@viliha/vui-ui 1.3.0 → 1.4.0

package/AGENT.md

@@ -73,16 +73,23 @@ 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
+npx @viliha/vui-ui init          # interactive decision tree
 ```
 
-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.
+Files land in the consumer's repo (they own them). Two questions:
+1. **Fresh project?** (`--fresh` / `--existing`)
+2. **Pre-built theme?** (`--prebuilt` = shell + demo pages / `--theme-only` = just
+   the theme wiring you configure)
+
+- **fresh + prebuilt** → full runnable app (config + shell + demo).
+- **fresh + theme-only** → just `globals.css` + `next.config` wiring; build your own.
+- **existing + prebuilt** → shell + demo added; config **never** overwritten —
+  prints the merge steps (`transpilePackages`, the `theme.css` import, the `@/*`
+  alias, `import "./globals.css"`).
+- **existing + theme-only** → nothing copied; prints the wiring steps.
+
+Other flags: `--yes` / `--force` / `--dry-run`. If you only need components, use
+`--theme-only` (or skip `init`) and do the setup below.
 
 VUI ships as TypeScript source.
 

package/README.md

@@ -48,32 +48,43 @@ pages** live in a one-shot scaffolder:
 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.
+It's **interactive** — a short decision tree:
+
+1. **Fresh project?** (fresh vs existing)
+2. **Pre-built theme?** — the full shell + demo pages, or just the theme wiring
+   that you configure yourself.
+
+Files are copied into *your* repo, so you own and edit them.
+
+| | **Pre-built** (shell + demo) | **Theme-only** (you configure) |
+| --- | --- | --- |
+| **Fresh** | full runnable app: config + shell + demo pages | just the theme wiring (`globals.css`, `next.config`) — build your own pages |
+| **Existing** | shell + demo added; your config is **never** overwritten (prints merge steps) | nothing copied; prints the wiring steps |
 
 ```
 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
+  --fresh | --existing        project type (Q1)
+  --prebuilt | --theme-only   pre-built shell + demo, or just the theme (Q2)
+  --yes, -y                   accept defaults (fresh, prebuilt)
+  --force                     overwrite existing files
+  --dry-run                   preview without writing
 ```
 
-After it runs, install the peer deps it prints, then `npm run dev` → `/dashboard`.
+After a **pre-built** run, install the peer deps it prints, then `npm run dev` →
+`/dashboard`.
 
-### Fresh project (recommended)
+### Fresh + pre-built (recommended for new apps)
 
-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.
+Start from a `create-next-app` base. This writes `next.config.mjs`,
+`app/globals.css`, the shell, and the demo pages (overwriting the create-next-app
+boilerplate), 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:
+overwrites your config.** Pick pre-built to add the shell + pages under
+`app/(app)/` and `app/_components/`, or theme-only to copy nothing — either way it
+prints the four things to wire up:
 
 1. **`next.config`** — add `transpilePackages: ["@viliha/vui-ui"]`.
    (Optional, for the open-tabs *keep-alive*: `output: "export"`,
@@ -88,9 +99,9 @@ overwrites your config** — it adds the shell + pages under `app/(app)/` and
 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
+Run **`npx @viliha/vui-ui init --existing --prebuilt --dry-run`** first to see
+exactly what it will add. If you only want the components, choose **theme-only**
+(or skip `init` and follow the [Setup](#setup) above), then import from
 `@viliha/vui-ui/*`.
 
 > **Note on the theme in an existing app:** VUI owns its design tokens in

package/bin/vui.mjs

@@ -1,11 +1,16 @@
 #!/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).
+// @viliha/vui-ui CLI — sets up the theme in a consumer's Next.js project.
 //
 //   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).
+// Interactive decision tree (skip with flags):
+//   1. Fresh project?              --fresh | --existing
+//   2. Pre-built theme + demo?     --prebuilt | --theme-only
+//
+//   fresh    + prebuilt    -> full runnable app: config + shell + demo pages
+//   fresh    + theme-only  -> just the theme wiring (globals/next.config), you build
+//   existing + prebuilt    -> shell + demo added (config untouched; merge steps printed)
+//   existing + theme-only  -> nothing copied; prints the wiring steps
 import { copyFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -16,6 +21,39 @@ 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);
+const dry = has("--dry-run");
+const forceFlag = has("--force");
+
+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(" ");
+
+const WIRING_STEPS = `  1. Install peer deps (those your components use):
+       npm i ${DEPS}
+  2. app/globals.css:
+       @import "tailwindcss";
+       @import "@viliha/vui-ui/theme.css";
+  3. next.config:  transpilePackages: ["@viliha/vui-ui"]
+  4. tsconfig.json (only if you copy the reference-app pieces):
+       "compilerOptions": { "paths": { "@/*": ["./*"] } }
+Then import components from @viliha/vui-ui/* and build your pages.`;
 
 function usage() {
   console.log(`@viliha/vui-ui
@@ -23,18 +61,14 @@ function usage() {
 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).
+  init            Set up the VUI theme in this project (interactive).
 
 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.
+  --fresh | --existing        project type (Q1)
+  --prebuilt | --theme-only   pre-built shell + demo, or just the theme (Q2)
+  --yes, -y                   accept defaults (fresh, prebuilt)
+  --force                     overwrite existing files
+  --dry-run                   preview without writing
 `);
 }
 
@@ -50,9 +84,6 @@ if (!existsSync(TEMPLATE)) {
   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 });
@@ -61,80 +92,97 @@ async function ask(question, def) {
   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([
+// Theme wiring config an existing project already has — never clobbered there.
+const WIRING = new Set([
   "next.config.mjs",
   "postcss.config.mjs",
+  ".env.example",
   "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.
+// Optional demo pages (vs the always-present shell). 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)/")) {
+  if (p.startsWith("app/(app)/"))
     return !(p === "app/(app)/layout.tsx" || p.startsWith("app/(app)/dashboard/"));
-  }
   return false;
 }
 
+function category(rel) {
+  const p = rel.split(sep).join("/");
+  if (WIRING.has(p)) return "wiring";
+  if (isDemo(rel)) return "demo";
+  return "shell";
+}
+
+function allFiles(dir, out = []) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const abs = join(dir, entry.name);
+    if (entry.isDirectory()) allFiles(abs, out);
+    else out.push(abs);
+  }
+  return out;
+}
+
 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";
+  // Q1 — fresh vs existing.
+  let fresh = has("--fresh") ? true : has("--existing") ? false : null;
+  if (fresh === null) {
+    const a = await ask("Are you installing VUI in a fresh project? [Y/n] ", "y");
+    fresh = !a.startsWith("n");
+  }
+
+  // Q2 — pre-built (shell + demo) vs theme-only.
+  let prebuilt = has("--prebuilt") ? true : has("--theme-only") ? false : null;
+  if (prebuilt === null) {
+    const q = fresh
+      ? "Install the pre-built theme with a Next.js project (shell + demo pages)? [Y/n] "
+      : "Install the pre-built theme (shell + demo pages) into this project? [Y/n] ";
+    const a = await ask(q, "y");
+    prebuilt = !a.startsWith("n");
   }
 
-  // 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",
+  // Existing + theme-only: nothing to copy — just print the wiring steps.
+  if (!fresh && !prebuilt) {
+    console.log(
+      `\nTheme-only setup for an existing project — no files copied.\n\n` +
+        `Wire the theme into your app:\n${WIRING_STEPS}\n`,
     );
-    demo = !a.startsWith("n");
+    return;
   }
 
   const cwd = process.cwd();
+  const files = allFiles(TEMPLATE);
   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`,
-  );
+  const label = `${fresh ? "fresh" : "existing"}, ${prebuilt ? "prebuilt" : "theme-only"}`;
+  console.log(`\nScaffolding VUI (${label}) 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);
+    const cat = category(rel);
+
+    // Which files this leaf installs.
+    const include =
+      fresh && prebuilt
+        ? true // everything: config + shell + demo
+        : fresh && !prebuilt
+          ? cat === "wiring" // just the theme wiring
+          : /* existing && prebuilt */ cat !== "wiring"; // shell + demo, not config
+    if (!include) {
+      if (!fresh && cat === "wiring") configSkipped.push(rel.split(sep).join("/"));
       continue;
     }
 
+    // Fresh overwrites boilerplate (create-next-app defaults); existing is
+    // non-destructive so we never clobber the user's own files.
+    const force = forceFlag || fresh;
     const dest = join(cwd, rel);
     if (existsSync(dest) && !force) {
       skipped++;
@@ -153,59 +201,38 @@ async function main() {
     `\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") {
+  // Per-leaf next steps.
+  if (fresh && prebuilt) {
     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).
+Next steps:
+  1. npm i ${DEPS}
+  2. npm run dev   ->   http://localhost:3000  (redirects to /dashboard)
 
-   The shell + pages were added under app/(app)/ and app/_components/ — review
-   them (re-run with --dry-run first if unsure) before committing.
+Everything is 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.
 `);
-  }
-
-  console.log(`Next steps:
-  1. Install peer dependencies:
-       npm i ${DEPS}
-  2. Start the app:
-       npm run dev   ->   http://localhost:3000  (redirects to /dashboard)
+  } else if (fresh && !prebuilt) {
+    console.log(`
+Theme wired (globals.css + next.config). No shell or demo pages — build your own.
 
-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).
+Next steps:
+  1. npm i ${DEPS}
+  2. Import components from @viliha/vui-ui/* in your pages, then: npm run dev
 `);
+  } else {
+    // existing + prebuilt
+    console.log(`
+⚠  Existing project — config files were NOT written. Merge these yourself:
+${WIRING_STEPS}
+
+The shell + demo were added under app/(app)/ and app/_components/ — review them
+(re-run with --dry-run first if unsure) before committing.${
+      configSkipped.length
+        ? `\nSkipped config: ${configSkipped.join(", ")}`
+        : ""
+    }
+`);
+  }
 }
 
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viliha/vui-ui",
-  "version": "1.3.0",
+  "version": "1.4.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",