@viliha/vui-ui 1.1.8 → 1.2.0

package/AGENT.md

@@ -67,6 +67,23 @@ Never duplicate functionality already provided by VUI.
 
 # Installation Requirements
 
+## Scaffold the shell + demo (`init`)
+
+The package ships the components; the **app shell** (layout, sidebar, open tabs,
+command palette, nav config, logo) and **demo pages** are scaffolded with:
+
+```bash
+npx @viliha/vui-ui init          # interactive: fresh vs existing, with/without demo
+```
+
+Files land in the consumer's repo (they own them). **Fresh project:** writes
+config too, runs out of the box. **Existing project:** `init --existing` never
+overwrites config — it adds the shell/pages and prints the merge steps
+(`transpilePackages`, the `theme.css` import, the `@/*` alias, `import
+"./globals.css"`). Flags: `--fresh` / `--existing` / `--demo` / `--no-demo` /
+`--yes` / `--force` / `--dry-run`. If you only need components, skip `init` and
+just do the setup below.
+
 VUI ships as TypeScript source.
 
 ## Next.js
@@ -207,16 +224,69 @@ One trail, **derived from the route — never hand-written per page.**
 
 To reorder or rename, edit the nav config; the trail follows automatically.
 
-## Open tabs
+## Sidebar: sections & collapsible groups
+
+The sidebar is driven by one `NAV` config (copy `nav-config.ts`). There are
+**two grouping shapes — use them, don't invent a third:**
+
+- **Section** (`NavSection`, `{ title?, items }`) — a top-level band with an
+  optional `title` heading. Items are **always visible** (no collapse). Use it to
+  cluster related pages under a label (e.g. *Records*, *System*). The first
+  section usually has no title.
+- **Collapsible group** (`NavGroup`, an entry with `children`) — a parent row with
+  a chevron that **hides/unhides** its nested links; it auto-opens when a child is
+  the active route. Use it for a set of sub-pages under one parent (e.g. *Auth*,
+  *CRM*, *System*) to keep the sidebar short. A group parent has no page of its
+  own — its breadcrumb points at its first child.
+
+```ts
+export const NAV: NavSection[] = [
+  { items: [                                   // untitled section
+    { label: "Home", href: "/dashboard", icon: Home },
+    { label: "Auth", icon: Lock, children: [   // collapsible group (hide/unhide)
+      { label: "Sign in", href: "/auth/signin", icon: LogIn },
+    ]},
+  ]},
+  { title: "Records", items: [                  // titled section (static band)
+    { label: "Organizations", href: "/organizations", icon: Building2 },
+  ]},
+];
+```
+
+When adding a page, always add it to `NAV` and mirror its color in
+`route-meta.ts` — the sidebar, breadcrumbs, and tabs all derive from these.
+
+## Open tabs (keep-alive)
+
+Enterprise apps keep several pages open at once. The reference app ships a
+browser-style **tab strip** under the top bar — a reference-app pattern (copy
+`open-tabs.tsx`), not a package export. **This is a first-class feature; wire it
+in — a fresh install won't have it.**
+
+It is **keep-alive**: every opened page stays mounted (inactive ones hidden), so
+switching is instant (no remount/flash) and each page keeps its live state
+(scroll, form input, filters). Mount the three pieces once in your app layout:
+
+```tsx
+<OpenTabsProvider>
+  <AppSidebar /> <TopBar />
+  <TabStrip />                          {/* the strip, under the top bar */}
+  <KeepAliveTabs>{children}</KeepAliveTabs>   {/* keeps open pages mounted */}
+</OpenTabsProvider>
+```
 
-Enterprise apps often keep several pages open at once. The reference app ships a
-browser-style **tab strip** under the top bar (a reference-app pattern — copy
-`open-tabs.tsx`): an `OpenTabsProvider` tracks opened routes, switching is a
-router push, and the list persists in `sessionStorage`. Tab labels/icons come
-from the same nav config as the sidebar. ⌘/Ctrl-click a nav item opens a
-background tab; expose an `openTab(href, { background })` for custom "open in new
-tab" buttons. Keep it a navigation-tab model (don't try to keep every page
-mounted) unless you specifically need live state preserved across tabs.
+- Labels/icons/colors derive from `nav-config.ts` + `route-meta.ts` — no per-tab wiring.
+- The list persists in `sessionStorage`, capped by `NEXT_PUBLIC_MAX_TABS`
+  (default 5; oldest FIFO-evicted with a warning).
+- Tabs are drag-reorderable and right-click-taggable with one of seven colors.
+- ⌘/Ctrl-click a nav item opens a **background tab**; call
+  `useOpenTabs().openTab(href, { background: true })` for custom "open in new tab"
+  buttons. `tabKey` normalizes trailing slashes so `/foo` and `/foo/` are one tab.
+
+Keep-alive relies on a static-export (all-client) shell. If your app renders
+server components per route, either adopt the demo's static-export shell or fall
+back to a plain navigation-tab model (router push per tab) — the strip,
+persistence, and nav-config wiring stay identical.
 
 ---
 

package/README.md

@@ -38,6 +38,66 @@ export default nextConfig;
 
 (Vite and most bundlers need no extra config.)
 
+## Scaffold the full app + demo (`init`)
+
+The package ships the **components**; the **app shell** (layout, sidebar,
+browser-style **open tabs**, command palette, nav config, logo) and the **demo
+pages** live in a one-shot scaffolder:
+
+```bash
+npx @viliha/vui-ui init
+```
+
+It's **interactive** — it asks whether this is a **fresh** or **existing**
+project and whether to include the **demo pages** (dashboard, CRM, calendar,
+chat, support, settings, auth). Files are copied into *your* repo, so you own and
+edit them. It's **non-destructive**: existing files are skipped.
+
+```
+Flags (for CI / agents, skip the prompts):
+  --fresh | --existing    project type
+  --demo  | --no-demo     include demo pages (default: with demo)
+  --yes, -y               accept defaults (fresh, with demo)
+  --force                 overwrite existing files
+  --dry-run               preview without writing
+```
+
+After it runs, install the peer deps it prints, then `npm run dev` → `/dashboard`.
+
+### Fresh project (recommended)
+
+Start from a `create-next-app` base. `init --fresh` also writes `next.config.mjs`,
+`app/globals.css`, and the root layout, so the demo runs out of the box.
+
+### ⚠️ Existing project — read this first
+
+Adding VUI to an app you already have needs care. **`init --existing` never
+overwrites your config** — it adds the shell + pages under `app/(app)/` and
+`app/_components/`, then prints the four things to merge yourself:
+
+1. **`next.config`** — add `transpilePackages: ["@viliha/vui-ui"]`.
+   (Optional, for the open-tabs *keep-alive*: `output: "export"`,
+   `images: { unoptimized: true }`, `trailingSlash: true`.)
+2. **`app/globals.css`** — add:
+   ```css
+   @import "tailwindcss";
+   @import "@viliha/vui-ui/theme.css";
+   ```
+3. **`tsconfig.json`** — the scaffold imports via `@/*`; map it to your root:
+   `"compilerOptions": { "paths": { "@/*": ["./*"] } }`.
+4. **Root `app/layout.tsx`** — `import "./globals.css"` (and mount fonts to match
+   the demo's look).
+
+Run **`npx @viliha/vui-ui init --existing --dry-run`** first to see exactly what
+it will add. If you only want the components (not the shell/pages), **skip `init`
+entirely** — the [Setup](#setup) above is all you need, then import from
+`@viliha/vui-ui/*`.
+
+> **Note on the theme in an existing app:** VUI owns its design tokens in
+> `theme.css`. If your app already defines shadcn/ui or other CSS variables with
+> the same names, import `theme.css` **last** and remove the duplicates, or the
+> two token sets will fight. On a fresh project this never comes up.
+
 ## Usage
 
 Each component is its own entry point, so you only ship what you use:

package/bin/vui.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+// @viliha/vui-ui CLI — scaffolds the app shell + demo pages into a consumer's
+// Next.js project (shadcn-style: the files land in YOUR repo, you own them).
+//
+//   npx @viliha/vui-ui init [options]
+//
+// Interactive by default: asks whether this is a fresh or existing project and
+// whether to include the demo pages. Non-interactive with flags (for CI/agents).
+import { copyFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+
+const TEMPLATE = fileURLToPath(new URL("../template/", import.meta.url));
+const args = process.argv.slice(2);
+const cmd = args[0];
+const has = (f) => args.includes(f);
+
+function usage() {
+  console.log(`@viliha/vui-ui
+
+Usage:
+  npx @viliha/vui-ui init [options]
+
+  init            Scaffold the VUI app shell (+ optional demo pages) into this
+                  project. Interactive unless flags are given. Non-destructive:
+                  existing files are skipped (use --force to overwrite).
+
+Options:
+  --fresh         Treat as a brand-new project (copies config too).
+  --existing      Treat as an existing project (skips config; prints merge steps).
+  --demo          Include the demo pages (dashboard, CRM, calendar, chat, …).
+  --no-demo       Shell + dashboard only, no other demo pages.
+  --yes, -y       Accept defaults without prompting (fresh, with demo).
+  --force         Overwrite files that already exist.
+  --dry-run       Show what would be written without touching the disk.
+`);
+}
+
+if (cmd !== "init") {
+  usage();
+  process.exit(cmd ? 1 : 0);
+}
+if (!existsSync(TEMPLATE)) {
+  console.error(
+    "vui: bundled template not found. Reinstall @viliha/vui-ui (the template " +
+      "ships with the published package).",
+  );
+  process.exit(1);
+}
+
+const dry = has("--dry-run");
+const force = has("--force");
+
+async function ask(question, def) {
+  if (has("--yes") || has("-y") || !stdin.isTTY) return def;
+  const rl = createInterface({ input: stdin, output: stdout });
+  const a = (await rl.question(question)).trim().toLowerCase();
+  rl.close();
+  return a || def;
+}
+
+// Config/root files that an existing project almost certainly already has —
+// copying them would collide, so in "existing" mode we skip + print merge steps.
+const CONFIG_FILES = new Set([
+  "next.config.mjs",
+  "postcss.config.mjs",
+  "app/globals.css",
+  "app/layout.tsx",
+  "app/page.tsx",
+]);
+
+// A file is a "demo page" (optional) vs the shell (always). The dashboard stays
+// in the shell so `/` has a landing page.
+function isDemo(rel) {
+  const p = rel.split(sep).join("/");
+  if (p.startsWith("app/auth/")) return true;
+  if (p.startsWith("app/onboarding/")) return true;
+  if (p.startsWith("app/register-business/")) return true;
+  if (p.startsWith("app/(app)/")) {
+    return !(p === "app/(app)/layout.tsx" || p.startsWith("app/(app)/dashboard/"));
+  }
+  return false;
+}
+
+async function main() {
+  // 1. Fresh vs existing.
+  let mode = has("--existing") ? "existing" : has("--fresh") ? "fresh" : null;
+  if (!mode) {
+    const a = await ask(
+      "Is this a fresh project or an existing one? [F(resh)/e(xisting)] ",
+      "f",
+    );
+    mode = a.startsWith("e") ? "existing" : "fresh";
+  }
+
+  // 2. Include the demo pages?
+  let demo = has("--demo") ? true : has("--no-demo") ? false : null;
+  if (demo === null) {
+    const a = await ask(
+      "Install the demo pages (dashboard, CRM, calendar, chat, support…)? [Y/n] ",
+      "y",
+    );
+    demo = !a.startsWith("n");
+  }
+
+  const cwd = process.cwd();
+  let created = 0;
+  let skipped = 0;
+  const configSkipped = [];
+
+  const files = [];
+  (function walk(dir) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const abs = join(dir, entry.name);
+      if (entry.isDirectory()) walk(abs);
+      else files.push(abs);
+    }
+  })(TEMPLATE);
+
+  console.log(
+    `\nScaffolding VUI (${mode}${demo ? ", with demo" : ", no demo"}) into ${cwd}${
+      dry ? "  [dry run]" : ""
+    }\n`,
+  );
+
+  for (const abs of files) {
+    const rel = relative(TEMPLATE, abs);
+    const norm = rel.split(sep).join("/");
+
+    if (isDemo(rel) && !demo) continue; // demo not selected
+    if (mode === "existing" && CONFIG_FILES.has(norm)) {
+      configSkipped.push(norm);
+      continue;
+    }
+
+    const dest = join(cwd, rel);
+    if (existsSync(dest) && !force) {
+      skipped++;
+      console.log(`  skip      ${rel}`);
+      continue;
+    }
+    if (!dry) {
+      mkdirSync(dirname(dest), { recursive: true });
+      copyFileSync(abs, dest);
+    }
+    created++;
+    console.log(`  ${dry ? "would add" : "added   "}  ${rel}`);
+  }
+
+  console.log(
+    `\nDone — ${created} file(s) ${dry ? "would be added" : "added"}, ${skipped} skipped.`,
+  );
+
+  const DEPS = [
+    "@radix-ui/react-icons",
+    "@radix-ui/react-slot",
+    "@tanstack/react-table",
+    "class-variance-authority",
+    "clsx",
+    "cmdk",
+    "date-fns",
+    "input-otp",
+    "lucide-react",
+    "next-themes",
+    "radix-ui",
+    "react-day-picker",
+    "react-hook-form",
+    "@hookform/resolvers",
+    "recharts",
+    "sonner",
+    "tailwind-merge",
+    "zod",
+  ].join(" ");
+
+  if (mode === "existing") {
+    console.log(`
+⚠  Existing project — config files were NOT written to avoid clobbering yours.
+   Merge these into your project manually:
+
+   • next.config: add
+       transpilePackages: ["@viliha/vui-ui"]
+     (for the demo's tab keep-alive: output:"export", images:{unoptimized:true},
+      trailingSlash:true — optional, only if you want static-export keep-alive)
+   • app/globals.css: add
+       @import "tailwindcss";
+       @import "@viliha/vui-ui/theme.css";
+   • tsconfig.json: map the alias the scaffold uses
+       "compilerOptions": { "paths": { "@/*": ["./*"] } }
+   • Root app/layout.tsx: import "./globals.css" and mount fonts if you want the
+     demo's exact look (see the scaffolded app/(app)/layout.tsx for the shell).
+
+   The shell + pages were added under app/(app)/ and app/_components/ — review
+   them (re-run with --dry-run first if unsure) before committing.
+`);
+  }
+
+  console.log(`Next steps:
+  1. Install peer dependencies:
+       npm i ${DEPS}
+  2. Start the app:
+       npm run dev   ->   http://localhost:3000  (redirects to /dashboard)
+
+Everything landed in YOUR repo — edit app/_components/nav-config.ts, set your
+logo (NEXT_PUBLIC_LOGO_URL in .env), and delete demo pages you don't need.
+Docs: /docs/navigation (sidebar, tabs) and /docs/configuration (logo, env).
+`);
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viliha/vui-ui",
-  "version": "1.1.8",
+  "version": "1.2.0",
   "description": "Vui UI — a clean, token-driven React admin/CRM component library built on Tailwind CSS v4, shadcn-style patterns, and Radix Icons. Ships as TypeScript source (Just-in-Time), compiled by the consuming app.",
   "license": "MIT",
   "author": "Suman Bonakurthi",
@@ -33,9 +33,15 @@
     "src",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
+    "bin",
+    "template",
     "AGENT.md",
     "CLAUDE.template.md"
   ],
+  "bin": {
+    "vui-ui": "bin/vui.mjs",
+    "vui": "bin/vui.mjs"
+  },
   "exports": {
     "./theme.css": "./src/theme.css",
     "./utils": "./src/utils.ts",
@@ -48,7 +54,9 @@
     "lint": "eslint . --max-warnings 0",
     "generate:component": "turbo gen react-component",
     "check-types": "tsgo --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "sync-template": "node scripts/sync-template.mjs",
+    "prepublishOnly": "node scripts/sync-template.mjs"
   },
   "peerDependencies": {
     "react": "^18 || ^19",

package/template/.env.example

@@ -0,0 +1,20 @@
+# Footer & brand identity — copy to .env.local and edit per deployment.
+# All are optional; defaults are used when unset. NEXT_PUBLIC_ vars are read at
+# build time and inlined into the exported site.
+
+NEXT_PUBLIC_COMPANY_NAME="VILIHA PTE. LTD."
+# Optional — links the company name in the footer:
+NEXT_PUBLIC_COMPANY_URL="https://viliha.com"
+NEXT_PUBLIC_LICENSE="MIT Licensed"
+# The copyright year is automatic (always the current/build year) — no env needed.
+
+# Optional — your logo image, served from /public; falls back to the built-in
+# mark. e.g. drop public/logo.svg and set:
+# NEXT_PUBLIC_LOGO_URL="/logo.svg"
+
+# Override the entire footer line at once (takes precedence over the vars above):
+# NEXT_PUBLIC_FOOTER_NOTICE="© 2026 Acme Inc. · All rights reserved"
+
+# Max pages kept open in the tab strip (client-side). Default 5, min 1. Opening
+# more evicts the oldest tab with a warning.
+NEXT_PUBLIC_MAX_TABS="5"

package/template/app/(app)/branches/branches-table.tsx

@@ -0,0 +1,69 @@
+"use client";
+
+import {
+  CodeIcon as Hash,
+  CubeIcon as Building,
+  DotFilledIcon as CircleDot,
+  EnvelopeClosedIcon as Mail,
+  MobileIcon as Phone,
+  SewingPinFilledIcon as MapPin,
+  Share2Icon as Network,
+} from "@radix-ui/react-icons";
+
+import { usePathname } from "next/navigation";
+
+import { Badge } from "@viliha/vui-ui/badge";
+import { RecordView, type RecordField } from "@viliha/vui-ui/record-view";
+import { branches, type Branch } from "@/lib/mock-data";
+
+const fields: RecordField<Branch>[] = [
+  { key: "name", label: "Name", editable: true, required: true, group: "General", hideInTable: true },
+  { key: "organization", label: "Organization", icon: Building, editable: true, width: 180, group: "General" },
+  { key: "code", label: "Code", icon: Hash, editable: true, group: "General" },
+  { key: "email", label: "Email", icon: Mail, editable: true, copyable: true, width: 220, group: "General" },
+  { key: "phone", label: "Phone", icon: Phone, editable: true, copyable: true, width: 160, group: "General" },
+  { key: "city", label: "City", icon: MapPin, editable: true, group: "General" },
+  {
+    key: "isHeadquarters",
+    label: "HQ",
+    icon: CircleDot,
+    // Wide enough for the "Headquarters" badge so it never spills into Actions.
+    width: 150,
+    group: "System",
+    render: (row) =>
+      row.isHeadquarters ? (
+        <Badge variant="secondary">Headquarters</Badge>
+      ) : (
+        <Badge variant="muted">Branch</Badge>
+      ),
+  },
+];
+
+export function BranchesTable() {
+  const pathname = usePathname();
+  return (
+    <RecordView
+      persistKey={pathname}
+      title="Branches"
+      singular="Branch"
+      icon={Network}
+      fields={fields}
+      initialData={branches}
+      getPrimary={(row) => ({
+        title: row.name,
+        subtitle: row.organization,
+        initials: (row.code || row.name).slice(0, 2).toUpperCase(),
+      })}
+      makeEmptyRow={() => ({
+        id: Date.now(),
+        organization: "",
+        name: "",
+        code: "",
+        email: "",
+        phone: "",
+        city: "",
+        isHeadquarters: false,
+      })}
+    />
+  );
+}

package/template/app/(app)/branches/page.tsx

@@ -0,0 +1,13 @@
+import { pageMeta } from "@/lib/seo";
+
+import { BranchesTable } from "./branches-table";
+
+export const metadata = pageMeta("/branches");
+
+export default function BranchesPage() {
+  return (
+    <main className="h-full">
+      <BranchesTable />
+    </main>
+  );
+}

package/template/app/(app)/businesses/businesses-table.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import {
+  BackpackIcon as Briefcase,
+  CodeIcon as Hash,
+  TextAlignLeftIcon as AlignLeft,
+} from "@radix-ui/react-icons";
+
+import { RecordView, type RecordField } from "@viliha/vui-ui/record-view";
+import { businesses, type Business } from "@/lib/mock-data";
+
+const fields: RecordField<Business>[] = [
+  { key: "title", label: "Title", editable: true, required: true, group: "General", hideInTable: true },
+  { key: "code", label: "Code", icon: Hash, editable: true, group: "General" },
+  { key: "description", label: "Description", icon: AlignLeft, editable: true, width: 360, group: "General" },
+];
+
+export function BusinessesTable() {
+  return (
+    <RecordView
+      title="Businesses"
+      singular="Business"
+      icon={Briefcase}
+      fields={fields}
+      initialData={businesses}
+      getPrimary={(row) => ({
+        title: row.title,
+        subtitle: row.code,
+        initials: row.code.slice(0, 2).toUpperCase(),
+      })}
+      makeEmptyRow={() => ({
+        id: Date.now(),
+        title: "",
+        code: "",
+        description: "",
+      })}
+    />
+  );
+}

package/template/app/(app)/businesses/page.tsx

@@ -0,0 +1,13 @@
+import { pageMeta } from "@/lib/seo";
+
+import { BusinessesTable } from "./businesses-table";
+
+export const metadata = pageMeta("/businesses");
+
+export default function BusinessesPage() {
+  return (
+    <main className="h-full">
+      <BusinessesTable />
+    </main>
+  );
+}