@zentauri-ui/zentauri-components 2.1.4 → 2.1.6

package/README.md

@@ -29,16 +29,16 @@ Generated from the component package Vitest JSON report via `pnpm --filter @zent
 
 | Metric     | Result           |
 | ---------- | ---------------- |
-| Test files | 93 passed (93)   |
-| Tests      | 752 passed (752) |
+| Test files | 96 passed (96)   |
+| Tests      | 792 passed (792) |
 
 | Area                           | Test files | Tests |
 | ------------------------------ | ---------- | ----- |
-| Components and UI utilities    | 46         | 456   |
+| Components and UI utilities    | 47         | 490   |
 | Standalone animations          | 1          | 45    |
 | React hooks                    | 41         | 174   |
 | Design system facade           | 1          | 11    |
-| CLI and import rewriting       | 2          | 24    |
+| CLI and import rewriting       | 4          | 30    |
 | Accessibility (axe + keyboard) | 2          | 42    |
 
 ### Per-suite snapshot
@@ -48,10 +48,11 @@ Generated from the component package Vitest JSON report via `pnpm --filter @zent
 | `src/animations/animations.test.tsx`                                    |    45 |
 | `src/ui/buttons/button.test.tsx`                                        |    44 |
 | `src/ui/inputs/input.test.tsx`                                          |    40 |
+| `src/ui/audio-player/audio-player.test.tsx`                             |    34 |
 | `src/ui/peer-isolation.test.ts`                                         |    29 |
 | `src/accessibility/axe-core.test.tsx`                                   |    24 |
 | `src/ui/combobox/combobox.test.tsx`                                     |    24 |
-| `cli/cli.integration.test.ts`                                           |    19 |
+| `cli/cli.integration.test.ts`                                           |    20 |
 | `src/accessibility/keyboard-interaction.test.tsx`                       |    18 |
 | `src/ui/pagination/pagination.test.tsx`                                 |    15 |
 | `src/ui/timeline/timeline.test.tsx`                                     |    14 |
@@ -109,6 +110,7 @@ Generated from the component package Vitest JSON report via `pnpm --filter @zent
 | `src/ui/popover/popover.test.tsx`                                       |     5 |
 | `src/ui/radio-group/radio-group.test.tsx`                               |     5 |
 | `src/ui/toggle/toggle.test.tsx`                                         |     5 |
+| `cli/index.test.ts`                                                     |     4 |
 | `src/hooks/useBodyScrollLock/useBodyScrollLock.test.ts`                 |     4 |
 | `src/hooks/useControllableState/useControllableState.test.ts`           |     4 |
 | `src/hooks/useDebouncedValue/useDebouncedValue.test.ts`                 |     4 |
@@ -131,6 +133,7 @@ Generated from the component package Vitest JSON report via `pnpm --filter @zent
 | `src/hooks/useMediaQuery/useMediaQuery.test.ts`                         |     2 |
 | `src/hooks/useNetworkStatus/useNetworkStatus.test.ts`                   |     2 |
 | `src/hooks/useResizeObserver/useResizeObserver.test.ts`                 |     2 |
+| `cli/props.test.ts`                                                     |     1 |
 | `src/hooks/useInView/useInView.test.ts`                                 |     1 |
 | `src/hooks/useIsomorphicLayoutEffect/useIsomorphicLayoutEffect.test.ts` |     1 |
 | `src/hooks/usePageVisibility/usePageVisibility.test.ts`                 |     1 |
@@ -847,7 +850,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 752 test cases in total
+- `pnpm test` / `pnpm test:watch` — **Vitest** and **Testing Library** unit tests // currently covered 792 test cases in total
 - `pnpm test:a11y` — focused accessibility coverage for package-level UI primitives and compound components: **axe-core** audits for every interactive component plus **keyboard-interaction** tests (focus order, arrow-key nav, Home/End, Escape/Enter) for the 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

@@ -1,5 +1,12 @@
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import {
+  existsSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -106,6 +113,35 @@ describe("zentauri-ui CLI", () => {
     }
   });
 
+  it("should not use a monorepo root config when add runs inside a package", () => {
+    const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-monorepo-"));
+    try {
+      const appDir = join(dir, "apps/web");
+      execFileSync(process.execPath, [
+        "-e",
+        `require("node:fs").mkdirSync(${JSON.stringify(appDir)}, { recursive: true })`,
+      ]);
+      writeFileSync(
+        join(dir, "package.json"),
+        JSON.stringify({ private: true, workspaces: ["apps/*"] }),
+      );
+      writeFileSync(join(appDir, "package.json"), JSON.stringify({}));
+
+      runCli(dir, ["init"]);
+      const stderr = runCliError(appDir, ["add", "button"]);
+
+      expect(stderr).toContain("No components.json found");
+      expect(
+        existsSync(join(dir, "src/components/ui/buttons/button.tsx")),
+      ).toBe(false);
+      expect(
+        existsSync(join(appDir, "src/components/ui/buttons/button.tsx")),
+      ).toBe(false);
+    } 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 {
@@ -162,11 +198,17 @@ describe("zentauri-ui CLI", () => {
       expect(
         existsSync(join(dir, "src/components/design-system/button.ts")),
       ).toBe(true);
+      expect(
+        existsSync(join(dir, "src/components/design-system/tokens.ts")),
+      ).toBe(true);
+      expect(
+        readdirSync(join(dir, "src/components/design-system")).sort(),
+      ).toEqual(["button.ts", "tokens.ts"]);
       const variants = readFileSync(
         join(dir, "src/components/ui/buttons/variants.ts"),
         "utf8",
       );
-      expect(variants).toContain("../../design-system");
+      expect(variants).toContain("../../design-system/button");
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }

package/cli/index.mjs

@@ -84,7 +84,7 @@
  *   command, or refused `init` overwrite. Successful runs leave default exit 0.
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import {
   readFile,
   writeFile,
@@ -238,8 +238,9 @@ async function walkFiles(dir) {
 }
 
 /**
- * Walks upward from `startDir` toward the filesystem root until `components.json`
- * exists, or returns `undefined` if none found (e.g. user forgot `init`).
+ * Walks upward from `startDir` until `components.json` exists. If the command
+ * starts inside a package, discovery stops at that package's `package.json`
+ * boundary so monorepo root config cannot capture nested package installs.
  *
  * @param {string} startDir — typically `process.cwd()` or `--cwd` resolved path
  * @returns {string | undefined} — absolute path to `components.json` if found
@@ -253,11 +254,17 @@ async function walkFiles(dir) {
  */
 async function findComponentsJson(startDir) {
   let d = startDir;
+  const packagePath = findPackageJson(startDir);
+  const packageBoundary = packagePath ? dirname(packagePath) : undefined;
+
   for (;;) {
     const p = join(d, "components.json");
     if (existsSync(p)) {
       return p;
     }
+    if (packageBoundary && d === packageBoundary) {
+      return undefined;
+    }
     const parent = dirname(d);
     if (parent === d) {
       return undefined;
@@ -957,6 +964,7 @@ async function copyUiComponent(componentName, config, configDir, packageRoot) {
     return true;
   });
   const usedHooks = new Set();
+  const designSystemImportTarget = getDesignSystemEntryName(componentName);
 
   for (const absSrc of files) {
     const rel = relative(srcRoot, absSrc);
@@ -972,10 +980,13 @@ async function copyUiComponent(componentName, config, configDir, packageRoot) {
         hooksAlias: config.aliases.hooks,
         uiAlias: config.aliases.ui,
       });
+      const rewrittenCode = designSystemImportTarget
+        ? rewriteDesignSystemBarrelImports(code, designSystemImportTarget)
+        : code;
       for (const h of uh) {
         usedHooks.add(h);
       }
-      await writeFile(absDest, code, "utf8");
+      await writeFile(absDest, rewrittenCode, "utf8");
     } else {
       await copyFile(absSrc, absDest);
     }
@@ -1022,11 +1033,57 @@ async function copyHookFolder(hookName, config, configDir, packageRoot) {
 }
 
 /**
- * Copies shared component design tokens/variant maps beside the consumer's UI
- * folder so vendored components can keep relative `../../design-system/*`
- * imports without adding a new public alias to `components.json`.
+ * Maps registry component names to their matching design-system token file.
+ */
+function getDesignSystemEntryName(componentName) {
+  if (
+    componentName.startsWith("charts/") ||
+    componentName.startsWith("animations/")
+  ) {
+    return undefined;
+  }
+  if (componentName === "buttons") {
+    return "button";
+  }
+  return componentName;
+}
+
+/**
+ * Narrows vendored imports from the design-system barrel to the selected token
+ * file. This lets a component like `buttons` vendor `design-system/button.ts`
+ * without also requiring `design-system/index.ts`.
+ */
+function rewriteDesignSystemBarrelImports(source, designSystemEntryName) {
+  return source.replace(
+    /from\s+(["'])((?:\.\.\/)+)design-system\1/g,
+    (_, quote, rel) =>
+      `from ${quote}${rel}design-system/${designSystemEntryName}${quote}`,
+  );
+}
+
+/**
+ * Extracts local design-system dependencies from a design token file.
+ */
+function extractDesignSystemDependencies(source) {
+  const deps = new Set();
+  const re = /from\s+["']\.\/([^"']+)["']/g;
+  let match;
+  while ((match = re.exec(source)) !== null) {
+    deps.add(match[1].replace(/\.(tsx?|jsx?)$/, ""));
+  }
+  return [...deps];
+}
+
+/**
+ * Copies only the design-system token files required by selected components,
+ * plus local token dependencies such as `tokens.ts`.
  */
-async function copyDesignSystemFolder(config, configDir, packageRoot) {
+async function copyDesignSystemFiles(
+  componentNames,
+  config,
+  configDir,
+  packageRoot,
+) {
   const srcRoot = join(packageRoot, "src", "design-system");
   if (!existsSync(srcRoot)) {
     return;
@@ -1039,28 +1096,34 @@ async function copyDesignSystemFolder(config, configDir, packageRoot) {
     dirname(config.resolvedPaths.ui),
     "design-system",
   );
-  const files = await walkFiles(srcRoot);
-  for (const absSrc of files) {
-    const rel = relative(srcRoot, absSrc);
-    if (isTestFile(rel)) {
+  const pending = componentNames
+    .map((name) => getDesignSystemEntryName(name))
+    .filter(Boolean);
+  const copied = new Set();
+
+  while (pending.length > 0) {
+    const entryName = pending.shift();
+    if (copied.has(entryName)) {
+      continue;
+    }
+    const absSrc = join(srcRoot, `${entryName}.ts`);
+    if (!existsSync(absSrc)) {
       continue;
     }
+    copied.add(entryName);
+    const rel = relative(srcRoot, absSrc);
     const absDest = join(destRoot, rel);
+    const raw = await readFile(absSrc, "utf8");
+    for (const dep of extractDesignSystemDependencies(raw)) {
+      if (!copied.has(dep)) {
+        pending.push(dep);
+      }
+    }
     if (existsSync(absDest)) {
       continue;
     }
     await mkdir(dirname(absDest), { recursive: true });
-    if (/\.(tsx?|jsx?)$/.test(absSrc)) {
-      const raw = await readFile(absSrc, "utf8");
-      const { code } = rewriteImports(raw, {
-        utilsAlias: config.aliases.utils,
-        hooksAlias: config.aliases.hooks,
-        uiAlias: config.aliases.ui,
-      });
-      await writeFile(absDest, code, "utf8");
-    } else {
-      await copyFile(absSrc, absDest);
-    }
+    await writeFile(absDest, raw, "utf8");
   }
 }
 
@@ -1258,7 +1321,7 @@ async function cmdAdd(names, cwd, options = {}) {
   }
 
   await ensureUtilsFile(config, configDir, packageRoot);
-  await copyDesignSystemFolder(config, configDir, packageRoot);
+  await copyDesignSystemFiles(resolvedNames, config, configDir, packageRoot);
 
   const allHooks = new Set();
   for (const name of resolvedNames) {
@@ -1401,7 +1464,50 @@ async function main() {
   process.exitCode = 1;
 }
 
-main().catch((err) => {
-  console.error(err instanceof Error ? err.message : err);
-  process.exitCode = 1;
-});
+export {
+  buildCompactThemeCss,
+  cmdAdd,
+  cmdInit,
+  cmdTheme,
+  collectHookTransitiveClosure,
+  copyDesignSystemFiles,
+  copyHookFolder,
+  copyUiComponent,
+  defaultConfig,
+  detectFramework,
+  findComponentsJson,
+  getMissingDependencies,
+  importPathFor,
+  isTestFile,
+  loadRegistry,
+  main,
+  normalizeHexColor,
+  printAdoptionHints,
+  printInfo,
+  printList,
+  resolveComponentName,
+  resolveHookName,
+  validateConfig,
+  walkFiles,
+};
+
+function isDirectCliRun() {
+  if (!process.argv[1]) {
+    return false;
+  }
+  try {
+    return (
+      realpathSync(process.argv[1]) ===
+      realpathSync(fileURLToPath(import.meta.url))
+    );
+  } catch {
+    return resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+  }
+}
+
+if (isDirectCliRun()) {
+  main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exitCode = 1;
+  });
+}

package/cli/index.test.ts

@@ -0,0 +1,180 @@
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  cmdAdd,
+  cmdInit,
+  cmdTheme,
+  defaultConfig,
+  importPathFor,
+  normalizeHexColor,
+  resolveComponentName,
+  resolveHookName,
+  validateConfig,
+} from "./index.mjs";
+
+type TestRegistry = Parameters<typeof resolveComponentName>[1] &
+  Parameters<typeof resolveHookName>[1];
+
+function makeTempDir(prefix: string) {
+  return mkdtempSync(join(tmpdir(), prefix));
+}
+
+function silenceConsole() {
+  const logs: string[] = [];
+  const errors: string[] = [];
+
+  vi.spyOn(console, "log").mockImplementation((...args) => {
+    logs.push(args.join(" "));
+  });
+  vi.spyOn(console, "error").mockImplementation((...args) => {
+    errors.push(args.join(" "));
+  });
+
+  return { errors, logs };
+}
+
+describe("CLI module commands", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    process.exitCode = undefined;
+  });
+
+  it("resolves aliases, hooks, imports, hex colors, and config validation", () => {
+    const registry: TestRegistry = {
+      components: ["buttons", "card", "charts/line"],
+      hooks: ["useWindowSize"],
+      nameAliases: { button: "buttons" },
+      animatedComponents: ["buttons", "spinner"],
+      uiComponents: ["buttons", "card"],
+    };
+
+    expect(resolveComponentName("button", registry)).toBe("buttons");
+    expect(resolveComponentName("CARD", registry)).toBe("card");
+    expect(resolveHookName("usewindowsize", registry)).toBe("useWindowSize");
+    expect(importPathFor("useWindowSize", "hook", registry)).toBe(
+      "@zentauri-ui/zentauri-components/hooks/useWindowSize",
+    );
+    expect(importPathFor("charts/line", "component", registry)).toBe(
+      "@zentauri-ui/zentauri-components/charts/line",
+    );
+    expect(importPathFor("spinner", "component", registry)).toBe(
+      "@zentauri-ui/zentauri-components/ui/spinner/animated",
+    );
+    expect(normalizeHexColor("38b")).toBe("#3388bb");
+    expect(() => validateConfig(defaultConfig())).not.toThrow();
+    expect(() => resolveComponentName("missing", registry)).toThrow(
+      /Unknown component/,
+    );
+    expect(() => normalizeHexColor("not-a-color")).toThrow(
+      /Invalid brand color/,
+    );
+  });
+
+  it("initializes components.json with framework-aware guidance", async () => {
+    const dir = makeTempDir("zentauri-cli-module-init-");
+    const { errors, logs } = silenceConsole();
+
+    try {
+      writeFileSync(
+        join(dir, "package.json"),
+        JSON.stringify({ dependencies: { next: "16.0.0" } }),
+      );
+
+      await cmdInit(dir);
+
+      expect(existsSync(join(dir, "components.json"))).toBe(true);
+      expect(
+        JSON.parse(readFileSync(join(dir, "components.json"), "utf8")),
+      ).toEqual(defaultConfig());
+      expect(logs.join("\n")).toContain("Detected framework: Next.js");
+      expect(logs.join("\n")).toContain('@source "./src/components/ui";');
+
+      await cmdInit(dir);
+
+      expect(process.exitCode).toBe(1);
+      expect(errors.join("\n")).toContain("Refusing to overwrite existing");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("vendors components, animated entries, design tokens, and transitive hooks", async () => {
+    const dir = makeTempDir("zentauri-cli-module-add-");
+    const { logs } = silenceConsole();
+
+    try {
+      await cmdInit(dir);
+      await cmdAdd(["button"], dir);
+      await cmdAdd(["hook", "usePrefersReducedMotion"], dir);
+      await cmdAdd(["button"], dir, { animated: true });
+
+      expect(
+        existsSync(join(dir, "src/components/ui/buttons/button.tsx")),
+      ).toBe(true);
+      expect(
+        existsSync(join(dir, "src/components/ui/buttons/animated/index.ts")),
+      ).toBe(true);
+      expect(
+        existsSync(join(dir, "src/components/design-system/button.ts")),
+      ).toBe(true);
+      expect(
+        existsSync(join(dir, "src/components/design-system/tokens.ts")),
+      ).toBe(true);
+      expect(
+        existsSync(
+          join(
+            dir,
+            "src/hooks/usePrefersReducedMotion/usePrefersReducedMotion.ts",
+          ),
+        ),
+      ).toBe(true);
+      expect(
+        existsSync(join(dir, "src/hooks/useMediaQuery/useMediaQuery.ts")),
+      ).toBe(true);
+      expect(
+        readFileSync(
+          join(dir, "src/components/ui/buttons/button-base.tsx"),
+          "utf8",
+        ),
+      ).toContain('from "@/lib/utils"');
+      expect(logs.join("\n")).toContain("Including animated entry for buttons");
+      expect(logs.join("\n")).toContain("Missing peer dependencies");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("generates theme CSS to stdout or a requested file", async () => {
+    const dir = makeTempDir("zentauri-cli-module-theme-");
+    const { errors, logs } = silenceConsole();
+
+    try {
+      await cmdTheme("#2563eb", { dark: "#60a5fa" }, dir);
+      expect(logs.join("\n")).toContain("--zui-brand: #2563eb;");
+      expect(logs.join("\n")).toContain("--zui-brand-dark: #60a5fa;");
+
+      await cmdTheme("38bdf8", { out: "src/styles/zentauri-theme.css" }, dir);
+      const themePath = join(dir, "src/styles/zentauri-theme.css");
+      expect(existsSync(themePath)).toBe(true);
+      expect(readFileSync(themePath, "utf8")).toContain(
+        "--zui-brand: #38bdf8;",
+      );
+
+      await cmdTheme("", {}, dir);
+      expect(process.exitCode).toBe(1);
+      expect(errors.join("\n")).toContain("Usage: zentauri-components theme");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});