@zentauri-ui/zentauri-components 2.1.1 → 2.1.2

package/README.md

@@ -30,7 +30,7 @@ Generated from the component package Vitest JSON report via `pnpm --filter @zent
 | Metric     | Result           |
 | ---------- | ---------------- |
 | Test files | 92 passed (92)   |
-| Tests      | 707 passed (707) |
+| Tests      | 713 passed (713) |
 
 | Area                        | Test files | Tests |
 | --------------------------- | ---------- | ----- |
@@ -38,7 +38,7 @@ Generated from the component package Vitest JSON report via `pnpm --filter @zent
 | Standalone animations       | 1          | 45    |
 | React hooks                 | 41         | 174   |
 | Design system facade        | 1          | 11    |
-| CLI and import rewriting    | 2          | 18    |
+| CLI and import rewriting    | 2          | 24    |
 | Axe core test cases         | 1          | 6     |
 
 ### Per-suite snapshot
@@ -50,9 +50,9 @@ Generated from the component package Vitest JSON report via `pnpm --filter @zent
 | `src/ui/inputs/input.test.tsx`                                          |    40 |
 | `src/ui/peer-isolation.test.ts`                                         |    29 |
 | `src/ui/combobox/combobox.test.tsx`                                     |    24 |
+| `cli/cli.integration.test.ts`                                           |    19 |
 | `src/ui/pagination/pagination.test.tsx`                                 |    15 |
 | `src/ui/timeline/timeline.test.tsx`                                     |    14 |
-| `cli/cli.integration.test.ts`                                           |    13 |
 | `src/lib/facade.test.ts`                                                |    11 |
 | `src/ui/alert/alert.test.tsx`                                           |    11 |
 | `src/ui/rating/rating.test.tsx`                                         |    11 |
@@ -846,7 +846,7 @@ From this package directory in the monorepo:
 
 - `pnpm build` (or `npm run build`) — production bundle via `tsup` (Rollup treeshake + `scripts/prepend-use-client.mjs` via `onSuccess` so each UI entry under `dist/ui/`, animation entry under `dist/animations/`, chart entry under `dist/charts/`, and `dist/ui/<name>/animated.*` starts with `"use client"` where needed)
 - `pnpm dev` — `tsup` watch mode (same `onSuccess` hook after each rebuild)
-- `pnpm test` / `pnpm test:watch` — **Vitest** and **Testing Library** unit tests // currently covered 707 test cases in total
+- `pnpm test` / `pnpm test:watch` — **Vitest** and **Testing Library** unit tests // currently covered 713 test cases in total
 - `pnpm test:a11y` — focused **axe-core** accessibility smoke coverage for package-level UI primitives and compound components
 - `pnpm check:tokens` — enforce the `--zui-*` token contract across design-system, variant, and local custom-property usage without generating a large checked-in token catalog
 - **`pnpm run generate:registry`** — runs `scripts/generate-registry.mjs`, which reads **`uiComponentNames`**, **`uiAnimatedComponentNames`**, **`animationEntryNames`**, **`chartEntryNames`**, and **`hooksEntryNames`** from `tsup.config.ts`, applies fixed **`nameAliases`**, scans each component/chart source to build **`peerHints`**, and writes **`cli/registry.json`** (`components` + `animations` + `hooks` + `peerHints`). Run this after adding or renaming UI, animation, chart, or hook entries so the CLI stays in sync (the script prints counts).

package/cli/cli.integration.test.ts

@@ -17,7 +17,122 @@ function runCli(cwd: string, args: string[]): string {
   });
 }
 
+function runCliError(cwd: string, args: string[]): string {
+  try {
+    runCli(cwd, args);
+    throw new Error("Expected CLI command to fail");
+  } catch (error) {
+    if (error && typeof error === "object" && "stderr" in error) {
+      return Buffer.isBuffer(error.stderr)
+        ? error.stderr.toString("utf8")
+        : String(error.stderr);
+    }
+    throw error;
+  }
+}
+
 describe("zentauri-ui CLI", () => {
+  it("should init with framework-aware Tailwind source guidance", () => {
+    const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-init-next-"));
+    try {
+      const packageJsonPath = join(dir, "package.json");
+      execFileSync(
+        process.execPath,
+        [
+          "-e",
+          `require("node:fs").writeFileSync(${JSON.stringify(
+            packageJsonPath,
+          )}, JSON.stringify({ dependencies: { next: "16.0.0" } }))`,
+        ],
+        { cwd: dir },
+      );
+      const out = runCli(dir, ["init"]);
+      expect(out).toContain("Detected framework: Next.js");
+      expect(out).toContain('@source "./src/components/ui";');
+      expect(out).toContain("pnpm add react react-dom");
+      expect(existsSync(join(dir, "components.json"))).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("should detect Remix over Vite when both dependencies are present", () => {
+    const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-init-remix-"));
+    try {
+      const packageJsonPath = join(dir, "package.json");
+      execFileSync(
+        process.execPath,
+        [
+          "-e",
+          `require("node:fs").writeFileSync(${JSON.stringify(
+            packageJsonPath,
+          )}, JSON.stringify({ dependencies: { "@remix-run/react": "2.0.0" }, devDependencies: { vite: "5.0.0" } }))`,
+        ],
+        { cwd: dir },
+      );
+      const out = runCli(dir, ["init"]);
+      expect(out).toContain("Detected framework: Remix");
+      expect(out).toContain('@source "./app/components/ui";');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("should list addable UI, chart, animation, and hook entries", () => {
+    const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-list-"));
+    try {
+      const out = runCli(dir, ["list"]);
+      expect(out).toContain("UI components");
+      expect(out).toContain("buttons");
+      expect(out).toContain("charts/line");
+      expect(out).toContain("animations/fade-in");
+      expect(out).toContain("Hooks");
+      expect(out).toContain("useWindowSize");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("should print component info with install and import commands", () => {
+    const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-info-"));
+    try {
+      const out = runCli(dir, ["info", "button"]);
+      expect(out).toContain("Name: buttons");
+      expect(out).toContain("npx zentauri-ui add button");
+      expect(out).toContain("@zentauri-ui/zentauri-components/ui/buttons");
+      expect(out).toContain("--animated");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("should add an animated component explicitly and report missing peers", () => {
+    const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-add-animated-"));
+    try {
+      runCli(dir, ["init"]);
+      const out = runCli(dir, ["add", "--animated", "button"]);
+      expect(
+        existsSync(join(dir, "src/components/ui/buttons/animated/index.ts")),
+      ).toBe(true);
+      expect(out).toContain("Including animated entry for buttons");
+      expect(out).toContain("Missing peer dependencies in this project");
+      expect(out).toContain("framer-motion");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("should reject --animated for components without an animated entry", () => {
+    const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-add-static-only-"));
+    try {
+      runCli(dir, ["init"]);
+      const stderr = runCliError(dir, ["add", "--animated", "pagination"]);
+      expect(stderr).toContain('Component "pagination" has no animated entry');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
   it("should init, add accordion, and rewrite internal imports", () => {
     const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-int-"));
     try {

package/cli/index.mjs

@@ -136,7 +136,7 @@ function loadRegistry() {
  */
 function printHelp() {
   const reg = loadRegistry();
-  const componentsList = (reg.components ?? []).join("\n");
+  const componentsList = (reg.uiComponents ?? reg.components ?? []).join("\n");
   const animationsList = (reg.animations ?? []).join("\n");
   const hooksList = (reg.hooks ?? []).join("\n");
 
@@ -145,7 +145,10 @@ function printHelp() {
 Usage:
   zentauri-components init [options]              Create components.json with defaults
   zentauri-components add <component> [...]       Copy UI components (and their hooks)
+  zentauri-components add --animated <component>  Copy and validate an animated UI entry
   zentauri-components add hook <hook> [...]       Copy hook source only (plus transitive hook deps)
+  zentauri-components list                        Show addable components, charts, animations, and hooks
+  zentauri-components info <name>                 Show install/import details for one entry
   zentauri-components theme <hex>                 Generate compact global --zui-* theme tokens
 
 List of components:
@@ -301,6 +304,136 @@ function defaultConfig() {
   };
 }
 
+const CORE_PEERS = [
+  "react",
+  "react-dom",
+  "class-variance-authority",
+  "clsx",
+  "tailwind-merge",
+];
+
+// Ordered by specificity: meta-frameworks first, generic Vite last. Vite-era
+// Remix (and other Vite-based setups) also depend on `vite`, so a first-match
+// scan with Vite earlier would misclassify them.
+const FRAMEWORKS = [
+  {
+    name: "Next.js",
+    deps: ["next"],
+    files: ["next.config.js", "next.config.mjs", "next.config.ts"],
+    source: '@source "./src/components/ui";',
+    note: "Place the @source line in your global CSS file, often app/globals.css.",
+  },
+  {
+    name: "Remix",
+    deps: ["@remix-run/react", "@remix-run/node"],
+    files: ["remix.config.js", "remix.config.mjs"],
+    source: '@source "./app/components/ui";',
+    note: "If components.json keeps the default src/ paths, use @source \"./src/components/ui\" instead.",
+  },
+  {
+    name: "Astro",
+    deps: ["astro"],
+    files: ["astro.config.js", "astro.config.mjs", "astro.config.ts"],
+    source: '@source "./src/components/ui";',
+    note: "Use this in the global stylesheet loaded by your Astro React integration.",
+  },
+  {
+    name: "Vite",
+    deps: ["vite"],
+    files: ["vite.config.js", "vite.config.mjs", "vite.config.ts"],
+    source: '@source "./src/components/ui";',
+    note: "Place the @source line in src/index.css or the CSS file imported by your app entry.",
+  },
+];
+
+function readProjectPackageJson(cwd) {
+  const packagePath = join(cwd, "package.json");
+  if (!existsSync(packagePath)) {
+    return undefined;
+  }
+  try {
+    return JSON.parse(readFileSync(packagePath, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function packageDependencyMap(pkg) {
+  return {
+    ...(pkg?.dependencies ?? {}),
+    ...(pkg?.devDependencies ?? {}),
+    ...(pkg?.peerDependencies ?? {}),
+    ...(pkg?.optionalDependencies ?? {}),
+  };
+}
+
+function detectFramework(cwd) {
+  const deps = packageDependencyMap(readProjectPackageJson(cwd));
+  return (
+    FRAMEWORKS.find((framework) =>
+      framework.deps.some((dep) => deps[dep]),
+    ) ??
+    FRAMEWORKS.find((framework) =>
+      framework.files.some((file) => existsSync(join(cwd, file))),
+    )
+  );
+}
+
+function printInitGuidance(cwd) {
+  const framework = detectFramework(cwd);
+  const missingCorePeers = getMissingDependencies(cwd, CORE_PEERS);
+  console.log(
+    `Detected framework: ${framework?.name ?? "React app (framework not detected)"}`,
+  );
+  console.log("\nInstall core peer dependencies:");
+  console.log(`  pnpm add ${CORE_PEERS.join(" ")}`);
+  console.log(`  npm install ${CORE_PEERS.join(" ")}`);
+  if (missingCorePeers.length > 0) {
+    console.log(
+      `  Missing now: ${missingCorePeers.join(", ")}`,
+    );
+  }
+  console.log("\nTailwind v4 source scanning:");
+  console.log(`  ${framework?.source ?? '@source "./src/components/ui";'}`);
+  console.log(
+    `  ${framework?.note ?? "Place the @source line in the global CSS file processed by Tailwind."}`,
+  );
+  console.log("\nOptional peers:");
+  console.log("  framer-motion  # animated UI and animation entries");
+  console.log("  react-icons     # icon-heavy components such as rating");
+  console.log("  recharts        # chart entries");
+}
+
+function findPackageJson(startDir) {
+  let d = startDir;
+  for (;;) {
+    const p = join(d, "package.json");
+    if (existsSync(p)) {
+      return p;
+    }
+    const parent = dirname(d);
+    if (parent === d) {
+      return undefined;
+    }
+    d = parent;
+  }
+}
+
+function getMissingDependencies(cwd, deps) {
+  const packagePath = findPackageJson(cwd);
+  if (!packagePath) {
+    return deps;
+  }
+  try {
+    const installed = packageDependencyMap(
+      JSON.parse(readFileSync(packagePath, "utf8")),
+    );
+    return deps.filter((dep) => !installed[dep]);
+  } catch {
+    return deps;
+  }
+}
+
 /**
  * Ensures `add` has everything it needs to compute destination paths and rewrite
  * imports. Throws a single clear error if the config is incomplete.
@@ -396,6 +529,87 @@ function resolveHookName(input, registry) {
   );
 }
 
+function resolveAnyRegistryName(input, registry) {
+  try {
+    return { kind: "component", name: resolveComponentName(input, registry) };
+  } catch {
+    try {
+      return { kind: "hook", name: resolveHookName(input, registry) };
+    } catch {
+      throw new Error(
+        `Unknown entry "${input}". Run: zentauri-ui list`,
+      );
+    }
+  }
+}
+
+function isAnimatedComponent(name, registry) {
+  return (registry.animatedComponents ?? []).includes(name);
+}
+
+function printList(registry) {
+  const ui = Array.from(
+    new Set([
+      ...(registry.uiComponents ?? registry.components ?? []),
+      ...(registry.animatedComponents ?? []).filter(
+        (name) => !(registry.uiComponents ?? []).includes(name),
+      ),
+    ]),
+  );
+  const charts = registry.charts ?? [];
+  const animations = registry.animations ?? [];
+  const hooks = registry.hooks ?? [];
+
+  console.log("UI components:");
+  console.log(ui.join("\n"));
+  console.log("\nCharts:");
+  console.log(charts.join("\n"));
+  console.log("\nAnimations:");
+  console.log(animations.join("\n"));
+  console.log("\nHooks:");
+  console.log(hooks.join("\n"));
+}
+
+function importPathFor(name, kind, registry) {
+  const uiComponents = registry.uiComponents ?? [];
+
+  if (kind === "hook") {
+    return `@zentauri-ui/zentauri-components/hooks/${name}`;
+  }
+  if (name.startsWith("charts/")) {
+    return `@zentauri-ui/zentauri-components/${name}`;
+  }
+  if (name.startsWith("animations/")) {
+    return `@zentauri-ui/zentauri-components/${name}`;
+  }
+  if (isAnimatedComponent(name, registry) && !uiComponents.includes(name)) {
+    return `@zentauri-ui/zentauri-components/ui/${name}/animated`;
+  }
+  return `@zentauri-ui/zentauri-components/ui/${name}`;
+}
+
+function printInfo(input, registry) {
+  const { kind, name } = resolveAnyRegistryName(input, registry);
+  const peers = kind === "component" ? (registry.peerHints?.[name] ?? []) : [];
+
+  console.log(`Name: ${name}`);
+  console.log(`Type: ${kind === "hook" ? "hook" : "addable entry"}`);
+  console.log(`Add command: npx zentauri-ui add ${input}`);
+  if (kind === "hook") {
+    console.log(`Hook-only command: npx zentauri-ui add hook ${name}`);
+  }
+  console.log(`Import: ${importPathFor(name, kind, registry)}`);
+  if (kind === "component" && isAnimatedComponent(name, registry)) {
+    console.log(
+      `Animated import: @zentauri-ui/zentauri-components/ui/${name}/animated`,
+    );
+    console.log(`Animated vendoring: npx zentauri-ui add --animated ${input}`);
+  }
+  if (peers.length > 0) {
+    console.log(`Peer hints: ${peers.join(", ")}`);
+  }
+}
+
 const THEME_COLOR_NAMES = [
   "blue",
   "cyan",
@@ -901,7 +1115,7 @@ const PEER_HINT_REASONS = {
  * @param {object} registry — from `loadRegistry()`
  * @param {object} config — validated `components.json` (for resolvedPaths.ui)
  */
-function printAdoptionHints(resolvedNames, registry, config) {
+function printAdoptionHints(resolvedNames, registry, config, configDir) {
   const peerHints = registry.peerHints ?? {};
   /** @type {Map<string, string[]>} peer -> component names that need it */
   const needed = new Map();
@@ -923,6 +1137,14 @@ function printAdoptionHints(resolvedNames, registry, config) {
       );
     }
     console.log(`  Install with: npm i ${[...needed.keys()].join(" ")}`);
+    const missing = getMissingDependencies(configDir, [...needed.keys()]);
+    if (missing.length > 0) {
+      console.log("\nMissing peer dependencies in this project:");
+      for (const peer of missing) {
+        console.log(`  - ${peer}`);
+      }
+      console.log(`  Install with: pnpm add ${missing.join(" ")}`);
+    }
   }
 
   const uiPath = config?.resolvedPaths?.ui ?? "your components directory";
@@ -962,6 +1184,7 @@ async function cmdInit(cwd) {
   const body = `${JSON.stringify(defaultConfig(), null, 2)}\n`;
   await writeFile(target, body, "utf8");
   console.log(`Wrote ${target}`);
+  printInitGuidance(cwd);
 }
 
 /**
@@ -983,7 +1206,7 @@ async function cmdInit(cwd) {
  * // No components.json in cwd or parents — stderr:
  * // No components.json found. Run: zentauri-components init  (or: zentauri-ui init)
  */
-async function cmdAdd(names, cwd) {
+async function cmdAdd(names, cwd, options = {}) {
   const configPath = await findComponentsJson(cwd);
   if (!configPath) {
     console.error(
@@ -997,6 +1220,7 @@ async function cmdAdd(names, cwd) {
   validateConfig(config);
 
   const registry = loadRegistry();
+  const animated = Boolean(options.animated);
   const hookMode = names.length > 0 && names[0].toLowerCase() === "hook";
   const payload = hookMode ? names.slice(1) : names;
 
@@ -1009,6 +1233,11 @@ async function cmdAdd(names, cwd) {
   }
 
   if (hookMode) {
+    if (animated) {
+      console.error("--animated can only be used with UI component entries.");
+      process.exitCode = 1;
+      return;
+    }
     await ensureUtilsFile(config, configDir, packageRoot);
     const resolvedHooks = payload.map((n) => resolveHookName(n, registry));
     const finalHooks = await collectHookTransitiveClosure(
@@ -1024,6 +1253,15 @@ async function cmdAdd(names, cwd) {
   }
 
   const resolvedNames = payload.map((n) => resolveComponentName(n, registry));
+  if (animated) {
+    for (const name of resolvedNames) {
+      if (!isAnimatedComponent(name, registry)) {
+        console.error(`Component "${name}" has no animated entry.`);
+        process.exitCode = 1;
+        return;
+      }
+    }
+  }
 
   await ensureUtilsFile(config, configDir, packageRoot);
   await copyDesignSystemFolder(config, configDir, packageRoot);
@@ -1031,6 +1269,9 @@ async function cmdAdd(names, cwd) {
   const allHooks = new Set();
   for (const name of resolvedNames) {
     console.log(`Adding ${name}…`);
+    if (animated) {
+      console.log(`Including animated entry for ${name}…`);
+    }
     const uh = await copyUiComponent(name, config, configDir, packageRoot);
     for (const h of uh) {
       allHooks.add(h);
@@ -1047,7 +1288,7 @@ async function cmdAdd(names, cwd) {
   }
 
   console.log("Done.");
-  printAdoptionHints(resolvedNames, registry, config);
+  printAdoptionHints(resolvedNames, registry, config, configDir);
 }
 
 async function cmdTheme(hex, options, cwd) {
@@ -1102,6 +1343,7 @@ async function main() {
       out: { type: "string" },
       selector: { type: "string" },
       dark: { type: "string" },
+      animated: { type: "boolean" },
     },
   });
 
@@ -1131,6 +1373,19 @@ async function main() {
     await cmdInit(cwd);
     return;
   }
+  if (cmd === "list") {
+    printList(loadRegistry());
+    return;
+  }
+  if (cmd === "info") {
+    if (rest.length === 0) {
+      console.error("Usage: zentauri-components info <component|hook>");
+      process.exitCode = 1;
+      return;
+    }
+    printInfo(rest[0], loadRegistry());
+    return;
+  }
   if (cmd === "add") {
     if (rest.length === 0) {
       console.error(
@@ -1139,7 +1394,7 @@ async function main() {
       process.exitCode = 1;
       return;
     }
-    await cmdAdd(rest, cwd);
+    await cmdAdd(rest, cwd, { animated: values.animated });
     return;
   }
   if (cmd === "theme") {

package/cli/registry.json

@@ -1,6 +1,90 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "description": "Addable UI components (src/ui), animation entries (src/animations/*), chart entries (src/charts/*), and hooks (src/hooks). Generated by scripts/generate-registry.mjs.",
+  "uiComponents": [
+    "accordion",
+    "alert",
+    "animated-number",
+    "avatar",
+    "badge",
+    "breadcrumb",
+    "buttons",
+    "card",
+    "checkbox",
+    "combobox",
+    "command",
+    "context-menu",
+    "copy-button",
+    "divider",
+    "drawer",
+    "dropdown",
+    "dynamic-stepper",
+    "empty-state",
+    "file-upload",
+    "inputs",
+    "kbd",
+    "marquee",
+    "modal",
+    "otp-input",
+    "pagination",
+    "popover",
+    "progress",
+    "radio-group",
+    "rating",
+    "scroll-area",
+    "search",
+    "select",
+    "skeleton",
+    "slider",
+    "table",
+    "tabs",
+    "timeline",
+    "toast",
+    "toggle",
+    "tooltip",
+    "tree-view",
+    "typography"
+  ],
+  "animatedComponents": [
+    "accordion",
+    "alert",
+    "avatar",
+    "badge",
+    "buttons",
+    "card",
+    "checkbox",
+    "command",
+    "copy-button",
+    "divider",
+    "drawer",
+    "empty-state",
+    "inputs",
+    "kbd",
+    "modal",
+    "popover",
+    "progress",
+    "radio-group",
+    "skeleton",
+    "spinner",
+    "table",
+    "tabs",
+    "timeline",
+    "toast",
+    "toggle",
+    "tooltip",
+    "tree-view"
+  ],
+  "charts": [
+    "charts/area",
+    "charts/bar",
+    "charts/bubble",
+    "charts/funnel",
+    "charts/line",
+    "charts/pie",
+    "charts/radar",
+    "charts/scatter",
+    "charts/stacked-bar"
+  ],
   "components": [
     "accordion",
     "alert",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zentauri-ui/zentauri-components",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "React + Tailwind UI kit with charts, ESM/CJS builds, per-entry exports, and a zentauri-components / zentauri-ui CLI to vendor UI or hook source into your app",
   "keywords": [
     "react",
@@ -103,7 +103,8 @@
     "prepack": "npm run build && node scripts/generate-registry.mjs && node scripts/check-design-tokens.mjs && node scripts/check-exports.mjs",
     "test": "vitest run",
     "test:a11y": "vitest run src/accessibility/axe-core.test.tsx",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "test:all": "pnpm test && pnpm test:a11y"
   },
   "peerDependencies": {
     "class-variance-authority": "*",