@zentauri-ui/zentauri-components 1.8.1 → 1.8.3

package/README.md

@@ -11,38 +11,51 @@ The library targets **React 18+** apps that use **Tailwind CSS v4** (or an equiv
 
 Published artifacts live under `dist/`. Imports use **per-entry subpaths**: `@zentauri-ui/zentauri-components/ui/<area>` for static UI, `@zentauri-ui/zentauri-components/ui/<area>/animated` where a motion bundle exists, `@zentauri-ui/zentauri-components/charts/<type>` for Recharts-powered chart primitives, and `@zentauri-ui/zentauri-components/hooks/<entry>` for React hooks (and shared helpers under `hooks/utils`). Base UI entries do **not** re-export animated components; motion lives on its own entry so optional `framer-motion` usage stays tree-shakeable and chunk-friendly. Each entry resolves to its own ESM (`.mjs`), CJS (`.js`), and types (`.d.ts`) so bundlers pull only what you import. Most apps rely on Tailwind scanning the package sources (see installation); a separate CSS import is not required for that setup.
 
+## Current package surface
+
+| Surface             | Count | Import shape                                          |
+| ------------------- | ----: | ----------------------------------------------------- |
+| Static UI entries   |    42 | `@zentauri-ui/zentauri-components/ui/<name>`          |
+| Animated UI entries |    27 | `@zentauri-ui/zentauri-components/ui/<name>/animated` |
+| Chart entries       |     9 | `@zentauri-ui/zentauri-components/charts/<type>`      |
+| Hook entries        |    28 | `@zentauri-ui/zentauri-components/hooks/<entry>`      |
+
+`spinner` is the only animated-only UI area. Import it from `@zentauri-ui/zentauri-components/ui/spinner/animated`; there is no `@zentauri-ui/zentauri-components/ui/spinner` static entry.
+
 ## Package status and test coverage
 
 | Metric     | Result           |
 | ---------- | ---------------- |
-| Test files | 68 passed (68)   |
-| Tests      | 453 passed (453) |
+| Test files | 76 passed (76)   |
+| Tests      | 548 passed (548) |
 
 | Area                        | Test files | Tests |
 | --------------------------- | ---------- | ----- |
-| Components and UI utilities | 40         | 359   |
-| React hooks                 | 26         | 85    |
-| CLI and import rewriting    | 2          | 9     |
+| Components and UI utilities | 46         | 433   |
+| React hooks                 | 28         | 101   |
+| CLI and import rewriting    | 2          | 14    |
 
 ### Per-suite snapshot
 
 | Suite                                                                   | Tests |
 | ----------------------------------------------------------------------- | ----: |
 | `src/ui/dynamic-stepper/dynamic-stepper.test.tsx`                       |     8 |
-| `src/ui/select/select.test.tsx`                                         |     6 |
-| `src/ui/modal/modal.test.tsx`                                           |     9 |
+| `src/ui/select/select.test.tsx`                                         |    10 |
+| `src/charts/charts.test.tsx`                                            |     6 |
+| `src/ui/modal/modal.test.tsx`                                           |    10 |
 | `src/ui/drawer/drawer.test.tsx`                                         |     7 |
-| `cli/cli.integration.test.ts`                                           |     4 |
+| `src/ui/peer-isolation.test.ts`                                         |    29 |
+| `cli/cli.integration.test.ts`                                           |     9 |
 | `src/ui/buttons/button.test.tsx`                                        |    41 |
 | `src/ui/inputs/input.test.tsx`                                          |    40 |
-| `src/ui/marquee/marquee.test.tsx`                                       |     9 |
+| `src/ui/marquee/marquee.test.tsx`                                       |    10 |
 | `src/ui/otp-input/otp-input.test.tsx`                                   |    10 |
 | `src/ui/tree-view/tree-view.test.tsx`                                   |    10 |
 | `src/ui/card/card.test.tsx`                                             |     7 |
 | `src/ui/checkbox/checkbox.test.tsx`                                     |     6 |
 | `src/ui/popover/popover.test.tsx`                                       |     4 |
 | `src/ui/command/command.test.tsx`                                       |     7 |
-| `src/ui/context-menu/context-menu.test.tsx`                             |     8 |
+| `src/ui/context-menu/context-menu.test.tsx`                             |    10 |
 | `src/ui/copy-button/copy-button.test.tsx`                               |     8 |
 | `src/ui/kbd/kbd.test.tsx`                                               |     7 |
 | `src/ui/tooltip/tooltip.test.tsx`                                       |     4 |
@@ -55,6 +68,7 @@ Published artifacts live under `dist/`. Imports use **per-entry subpaths**: `@ze
 | `src/ui/accordion/accordion.test.tsx`                                   |     7 |
 | `src/ui/toast/toast.test.tsx`                                           |     5 |
 | `src/ui/pagination/pagination.test.tsx`                                 |    15 |
+| `src/ui/table/table.test.tsx`                                           |    11 |
 | `src/ui/tabs/tabs.test.tsx`                                             |     3 |
 | `src/ui/stepper/stepper.test.tsx`                                       |    12 |
 | `src/ui/timeline/timeline.test.tsx`                                     |    14 |
@@ -62,6 +76,9 @@ Published artifacts live under `dist/`. Imports use **per-entry subpaths**: `@ze
 | `src/ui/toggle/toggle.test.tsx`                                         |     5 |
 | `src/ui/slider/slider.test.tsx`                                         |     9 |
 | `src/ui/typography/typography.test.tsx`                                 |     7 |
+| `src/ui/skeleton/skeleton.test.tsx`                                     |     8 |
+| `src/ui/divider/divider.test.tsx`                                       |     6 |
+| `src/ui/empty-state/empty-state.test.tsx`                               |     6 |
 | `src/ui/alert/alert.test.tsx`                                           |    11 |
 | `src/ui/badge/badge.test.tsx`                                           |     6 |
 | `src/hooks/useClipboard/useClipboard.test.ts`                           |     6 |
@@ -77,6 +94,8 @@ Published artifacts live under `dist/`. Imports use **per-entry subpaths**: `@ze
 | `src/hooks/useThrottledCallback/useThrottledCallback.test.ts`           |     4 |
 | `src/hooks/useToggle/useToggle.test.ts`                                 |     4 |
 | `src/hooks/usePagination/usePagination.test.ts`                         |    10 |
+| `src/hooks/useTableFilter/useTableFilter.test.ts`                       |     9 |
+| `src/hooks/useTableSort/useTableSort.test.ts`                           |     7 |
 | `src/hooks/useSessionStorage/useSessionStorage.test.ts`                 |     3 |
 | `src/hooks/usePrefersColorScheme/usePrefersColorScheme.test.ts`         |     1 |
 | `src/hooks/useIsMounted/useIsMounted.test.ts`                           |     3 |
@@ -99,12 +118,12 @@ Published artifacts live under `dist/`. Imports use **per-entry subpaths**: `@ze
 
 ## Package exports
 
-| Subpath                                               | Description                                                                                                                                    |
-| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@zentauri-ui/zentauri-components/ui/<name>`          | Single UI area: static primitives, compound parts, variants, and types. Does **not** include Framer Motion–based animated exports.             |
-| `@zentauri-ui/zentauri-components/ui/<name>/animated` | Motion entry for that area when published: animated components, motion presets, and related types (depends on **framer-motion**).              |
-| `@zentauri-ui/zentauri-components/charts/<type>`      | Responsive Recharts chart entry for `area`, `bar`, `bubble`, `line`, or `pie`, with shared variants, palettes, and exported chart prop types.  |
-| `@zentauri-ui/zentauri-components/hooks/<entry>`      | One hook module or `utils` (`cn`, `clampPage`, `range` from `src/lib/utils.ts`). Entries match files under `src/hooks/` (see **React hooks**). |
+| Subpath                                               | Description                                                                                                                                                                                |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `@zentauri-ui/zentauri-components/ui/<name>`          | Single UI area: static primitives, compound parts, variants, and types. Does **not** include Framer Motion–based animated exports.                                                         |
+| `@zentauri-ui/zentauri-components/ui/<name>/animated` | Motion entry for that area when published: animated components, motion presets, and related types (depends on **framer-motion**).                                                          |
+| `@zentauri-ui/zentauri-components/charts/<type>`      | Responsive Recharts chart entry for `area`, `bar`, `stacked-bar`, `radar`, `scatter`, `bubble`, `funnel`, `line`, or `pie`, with shared variants, palettes, and exported chart prop types. |
+| `@zentauri-ui/zentauri-components/hooks/<entry>`      | One hook module or `utils` (`cn`, `clampPage`, `range` from `src/lib/utils.ts`). Entries match files under `src/hooks/` (see **React hooks**).                                             |
 
 The UI `<name>` segment matches the folder under `src/ui/` (for example `accordion`, `select`, `empty-state`, `buttons` for `Button`, `inputs` for `Input`, `typography` for `Heading` / `Text` and related primitives). The hooks `<entry>` is the file stem (for example `useMediaQuery`, `usePagination`) or `utils`.
 
@@ -117,7 +136,7 @@ Only a subset of UI areas publish a `/animated` entry (see **Components**). Some
 
 Published motion entries (same `<name>` as the base UI folder):
 
-`accordion`, `alert`, `avatar`, `badge`, `buttons`, `card`, `checkbox`, `divider`, `drawer`, `empty-state`, `inputs`, `modal`, `popover`, `progress`, `radio-group`, `skeleton`, `spinner`, `table`, `tabs`, `toast`, `toggle`, `tooltip`, `tree-view`
+`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`
 
 **Spinner:** only the motion entry is built—import from `@zentauri-ui/zentauri-components/ui/spinner/animated` (there is no separate `ui/spinner` static bundle).
 
@@ -135,6 +154,7 @@ Import static primitives from `@zentauri-ui/zentauri-components/ui/<subpath>` wh
 | --------------- | ----------------- | ---------------------------------- |
 | Accordion       | `accordion`       | `accordion/animated`               |
 | Alert           | `alert`           | `alert/animated`                   |
+| Animated number | `animated-number` | —                                  |
 | Avatar          | `avatar`          | `avatar/animated`                  |
 | Badge           | `badge`           | `badge/animated`                   |
 | Breadcrumb      | `breadcrumb`      | —                                  |
@@ -162,7 +182,7 @@ Import static primitives from `@zentauri-ui/zentauri-components/ui/<subpath>` wh
 | Rating          | `rating`          | —                                  |
 | Radio group     | `radio-group`     | `radio-group/animated`             |
 | Scroll area     | `scroll-area`     | —                                  |
-| Search          | `search`          | -                                  |
+| Search          | `search`          | —                                  |
 | Select          | `select`          | —                                  |
 | Skeleton        | `skeleton`        | `skeleton/animated`                |
 | Slider          | `slider`          | —                                  |
@@ -170,6 +190,7 @@ Import static primitives from `@zentauri-ui/zentauri-components/ui/<subpath>` wh
 | Stepper         | `stepper`         | —                                  |
 | Table           | `table`           | `table/animated`                   |
 | Tabs            | `tabs`            | `tabs/animated`                    |
+| Timeline        | `timeline`        | `timeline/animated`                |
 | Toast           | `toast`           | `toast/animated`                   |
 | Toggle          | `toggle`          | `toggle/animated`                  |
 | Tooltip         | `tooltip`         | `tooltip/animated`                 |
@@ -240,11 +261,11 @@ export function ArticleIntro() {
 
 Import the chart you need from `@zentauri-ui/zentauri-components/charts/<type>`, or vendor it with `zentauri-components add charts/<type>`. It is built on **Recharts**, so install `recharts` when you use these entries.
 
-**Components:** `AreaChart`, `BarChart`, `BubbleChart`, `LineChart`, `PieChart`.
+**Components:** `AreaChart`, `BarChart`, `StackedBarChart`, `RadarChart`, `ScatterChart`, `BubbleChart`, `FunnelChart`, `LineChart`, `PieChart`.
 
-**Types:** `AreaChartProps`, `BarChartProps`, `BubbleChartProps`, `LineChartProps`, `PieChartProps`, plus shared `ChartSeries`, `ChartDatum`, `ChartColor`, `ChartMargin`, and `ChartSharedStatic`.
+**Types:** `AreaChartProps`, `BarChartProps`, `StackedBarChartProps`, `RadarChartProps`, `ScatterChartProps`, `BubbleChartProps`, `FunnelChartProps`, `LineChartProps`, `PieChartProps`, plus shared `ChartSeries`, `ChartDatum`, `ChartColor`, `ChartMargin`, and `ChartSharedStatic`.
 
-**Chart entries:** `charts/area`, `charts/bar`, `charts/bubble`, `charts/line`, `charts/pie`.
+**Chart entries:** `charts/area`, `charts/bar`, `charts/stacked-bar`, `charts/radar`, `charts/scatter`, `charts/bubble`, `charts/funnel`, `charts/line`, `charts/pie`.
 
 **Variants:** `appearance` (`default`, `muted`, `outline`, `glass`) and `density` (`compact`, `comfortable`, `spacious`). Color presets are exported via `chartPalette` and `chartColorValues`.
 
@@ -361,6 +382,8 @@ Hooks live in `src/hooks/`. Each hook is a separate published entry under `@zent
 | `usePrefersReducedMotion`   | `usePrefersReducedMotion`   | `prefers-reduced-motion`                                                                  |
 | `useResizeObserver`         | `useResizeObserver`         | `ElementSize`                                                                             |
 | `useSessionStorage`         | `useSessionStorage`         | `UseSessionStorageResult`                                                                 |
+| `useTableFilter`            | `useTableFilter`            | `TableFilterState`, `UseTableFilterResult`                                                |
+| `useTableSort`              | `useTableSort`              | `UseTableSortParams`, `UseTableSortResult`                                                |
 | `useThrottledCallback`      | `useThrottledCallback`      | Throttled callback ref                                                                    |
 | `useToggle`                 | `useToggle`                 | Boolean toggle state                                                                      |
 | `useWindowSize`             | `useWindowSize`             | `WindowSize`                                                                              |
@@ -376,6 +399,8 @@ import {
   buildPaginationItems,
   usePagination,
 } from "@zentauri-ui/zentauri-components/hooks/usePagination";
+import { useTableFilter } from "@zentauri-ui/zentauri-components/hooks/useTableFilter";
+import { useTableSort } from "@zentauri-ui/zentauri-components/hooks/useTableSort";
 import { cn } from "@zentauri-ui/zentauri-components/hooks/utils";
 ```
 
@@ -644,9 +669,10 @@ Defaults look like this; edit `resolvedPaths` and `aliases` so they match your a
 
 ### Registry (`cli/registry.json`)
 
-- **`components`**: sorted list of folder names under **`src/ui/`**, plus chart entries from **`src/charts/<type>`**, that `add` may copy. The file is **generated**; the canonical build list lives in **`tsup.config.ts`** as `uiComponentNames` and `chartEntryNames`, and the generator always ensures **`spinner`** is included so the CLI stays aligned with the animated-only spinner bundle.
+- **`components`**: sorted list of folder names under **`src/ui/`**, plus chart entries from **`src/charts/<type>`**, that `add` may copy. The file is **generated**; the canonical build lists live in **`tsup.config.ts`** as `uiComponentNames`, `uiAnimatedComponentNames`, and `chartEntryNames`, so animated-only entries such as **`spinner`** stay aligned with the CLI.
 - **`hooks`**: sorted list of folder names under **`src/hooks/`** that `add hook` may copy; generated from **`hooksEntryNames`** in **`tsup.config.ts`** (same entries as published `…/hooks/<name>` subpaths).
-- **`nameAliases`**: optional map from a CLI token to a real folder name. Today: `button` → `buttons`, `input` → `inputs` (matching common singular names while folders stay plural).
+- **`nameAliases`**: optional map from a CLI token to a real folder name: `button` → `buttons`, `input` → `inputs` (singular forms while folders stay plural), and `chart-<type>` → `charts/<type>` for every chart (so `add chart-line` and `add charts/line` are equivalent).
+- **`peerHints`**: generated map from a component/chart name to the **optional peer dependencies** its source imports (`framer-motion` for components that ship an `animated/` variant, `react-icons` where icons are used, `recharts` for every chart). After `add`, the CLI prints a deduplicated install hint built from this map, so you never have to guess which peers a vendored component needs.
 
 Example: these are equivalent when `nameAliases` is configured:
 
@@ -657,6 +683,45 @@ zentauri-components add buttons
 
 After `add`, imports inside copied `.ts`/`.tsx` files are rewritten using your `aliases`; test files (`*.test.*`, `*.spec.*`) from the package are not copied.
 
+### Worked examples
+
+```bash
+# A static UI primitive — copies src/ui/buttons plus the shared design-system tokens it imports.
+zentauri-ui add button
+
+# A chart — copies src/charts/line and the shared chart frame; CLI hints `recharts`.
+zentauri-ui add charts/line
+
+# A hook on its own — copies src/hooks/useClipboard (plus any sibling hooks it imports).
+zentauri-ui add hook useClipboard
+```
+
+### Vendored destination structure
+
+Given the default `components.json`, running `zentauri-ui add button charts/line` then `add hook useClipboard` produces:
+
+```
+your-app/
+├── components.json
+└── src/
+    ├── components/
+    │   ├── design-system/        # shared token + variant strings (copied once, never overwritten)
+    │   │   └── button.ts
+    │   └── ui/
+    │       ├── buttons/          # the component folder (index.ts, button.tsx, variants.ts, …)
+    │       └── charts/
+    │           ├── shared/       # chart frame + helpers shared by every chart
+    │           └── line/         # the requested chart entry only
+    ├── hooks/
+    │   └── useClipboard/         # hooks pulled in by components or `add hook`
+    └── lib/
+        └── utils.ts              # cn() helper, created from the package template if missing
+```
+
+- `design-system/` lands beside `ui/` (one level up from `resolvedPaths.ui`) so vendored components keep their `../../design-system/*` imports working without a new alias. Existing files there are left untouched on re-add.
+- Charts always land under `<ui>/charts/`, with a single shared `charts/shared/` folder regardless of how many chart types you add.
+- Re-adding a component overwrites that component's files but preserves your `design-system/` and `lib/utils.ts` edits.
+
 ### When to use the CLI vs npm imports
 
 | Approach                                         | Best when                                                                                                                   |
@@ -670,14 +735,47 @@ Tailwind still needs to see the classes your **copied** files use—point `@sour
 
 https://zentauri-ui.vercel.app/
 
+## Accessibility checklist for contributors
+
+Every new or changed component should clear this bar before it merges. The
+highest-risk primitives (overlays and keyboard-heavy controls) are expected to
+have explicit tests for the items below.
+
+**Semantics & ARIA**
+
+- [ ] Correct landmark/role for the pattern (`dialog`, `menu`/`menuitem`, `listbox`/`option`, `tab`/`tabpanel`, `slider`, `tree`/`treeitem`, …).
+- [ ] State is announced: `aria-expanded`, `aria-selected`, `aria-checked`, `aria-disabled`, `aria-current` as appropriate.
+- [ ] Overlays set `aria-modal` and wire `aria-labelledby` / `aria-describedby` to the rendered title/description.
+- [ ] Compound parts are linked by id (`aria-controls`, `aria-haspopup`) rather than relying on DOM proximity.
+
+**Keyboard**
+
+- [ ] All interactive parts are reachable and operable by keyboard (Enter/Space activate; Arrow keys navigate where the role implies it).
+- [ ] Roving tabindex for composite widgets (one tab stop; arrows move within).
+- [ ] Dismissible surfaces close on `Escape`.
+- [ ] Focus moves into an opened overlay and **returns to the trigger** on close.
+
+**Disabled & edge states**
+
+- [ ] Disabled items are skipped by keyboard navigation and ignore pointer activation, and expose `aria-disabled`.
+- [ ] SSR-safe: no access to `window`/`document` during render (guard effects; the package targets React 18+ server rendering).
+
+**Motion**
+
+- [ ] Animated entries respect `prefers-reduced-motion` (use `usePrefersReducedMotion` / Framer Motion's `useReducedMotion`).
+- [ ] `framer-motion` stays out of static entries — enforced by `src/ui/peer-isolation.test.ts`. Charts stay isolated to `src/charts/*`.
+
+Add or extend the component's `*.test.tsx` to cover the items that apply; see
+`modal`, `select`, and `context-menu` tests for worked examples.
+
 ## Development
 
 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/`, the 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 // covered 453 test cases in total
-- **`pnpm run generate:registry`** — runs `scripts/generate-registry.mjs`, which reads **`uiComponentNames`**, **`chartEntryNames`**, and **`hooksEntryNames`** from `tsup.config.ts`, merges in **`spinner`**, applies fixed **`nameAliases`**, and writes **`cli/registry.json`** (`components` + `hooks`). Run this after adding or renaming UI/chart areas or hook entries so the CLI stays in sync (the script prints counts).
+- `pnpm test` / `pnpm test:watch` — **Vitest** and **Testing Library** unit tests // covered 548 test cases in total
+- **`pnpm run generate:registry`** — runs `scripts/generate-registry.mjs`, which reads **`uiComponentNames`**, **`uiAnimatedComponentNames`**, **`chartEntryNames`**, and **`hooksEntryNames`** from `tsup.config.ts`, applies fixed **`nameAliases`**, scans each component/chart source to build **`peerHints`**, and writes **`cli/registry.json`** (`components` + `hooks` + `peerHints`). Run this after adding or renaming UI/chart areas or hook entries so the CLI stays in sync (the script prints counts).
 
 ## Github Release log
 

package/cli/cli.integration.test.ts

@@ -9,8 +9,8 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(__dirname, "..");
 const cliEntry = join(packageRoot, "cli", "index.mjs");
 
-function runCli(cwd: string, args: string[]) {
-  execFileSync(process.execPath, [cliEntry, ...args], {
+function runCli(cwd: string, args: string[]): string {
+  return execFileSync(process.execPath, [cliEntry, ...args], {
     cwd,
     encoding: "utf8",
     stdio: ["pipe", "pipe", "pipe"],
@@ -84,4 +84,79 @@ describe("zentauri-ui CLI", () => {
       rmSync(dir, { recursive: true, force: true });
     }
   });
+
+  it("should add a chart entry under charts/ and hint recharts", () => {
+    const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-chart-"));
+    try {
+      runCli(dir, ["init"]);
+      const out = runCli(dir, ["add", "charts/line"]);
+      expect(
+        existsSync(join(dir, "src/components/ui/charts/line/index.ts")),
+      ).toBe(true);
+      // chart-line alias resolves to charts/line as well
+      expect(out).toContain("recharts");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("should add multiple components in one run", () => {
+    const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-multi-"));
+    try {
+      runCli(dir, ["init"]);
+      const out = runCli(dir, ["add", "buttons", "card", "badge"]);
+      expect(existsSync(join(dir, "src/components/ui/buttons/button.tsx"))).toBe(
+        true,
+      );
+      expect(existsSync(join(dir, "src/components/ui/card/card.tsx"))).toBe(
+        true,
+      );
+      expect(existsSync(join(dir, "src/components/ui/badge/badge.tsx"))).toBe(
+        true,
+      );
+      expect(out).toContain("Adding buttons…");
+      expect(out).toContain("Adding badge…");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("should print react-icons peer hint for components that use icons", () => {
+    const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-peer-"));
+    try {
+      runCli(dir, ["init"]);
+      const out = runCli(dir, ["add", "rating"]);
+      expect(out).toContain("Optional peer dependencies");
+      expect(out).toContain("react-icons");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("should print Tailwind v4 source guidance after adding", () => {
+    const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-tw-"));
+    try {
+      runCli(dir, ["init"]);
+      const out = runCli(dir, ["add", "buttons"]);
+      expect(out).toContain("Tailwind v4");
+      expect(out).toContain("@source");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("should not error when re-adding a component (existing files)", () => {
+    const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-reAdd-"));
+    try {
+      runCli(dir, ["init"]);
+      runCli(dir, ["add", "buttons"]);
+      // Second add over existing files must succeed and keep the design-system.
+      expect(() => runCli(dir, ["add", "buttons"])).not.toThrow();
+      expect(
+        existsSync(join(dir, "src/components/design-system/button.ts")),
+      ).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
 });

package/cli/index.mjs

@@ -599,6 +599,58 @@ async function ensureUtilsFile(config, configDir, packageRoot) {
   console.log(`Created ${relative(configDir, dest)}`);
 }
 
+/**
+ * Human-readable note explaining why each optional peer dependency may be
+ * needed, so the install hint is self-explanatory.
+ */
+const PEER_HINT_REASONS = {
+  "framer-motion": "only if you use the animated variants",
+  "react-icons": "icons used by this component",
+  recharts: "required to render charts",
+};
+
+/**
+ * Prints optional peer-dependency install hints and Tailwind v4 scanning
+ * guidance after a successful `add`. Hints come from `registry.peerHints`
+ * (generated by scripts/generate-registry.mjs). Silent when nothing applies.
+ *
+ * @param {string[]} resolvedNames — canonical component/chart names that were added
+ * @param {object} registry — from `loadRegistry()`
+ * @param {object} config — validated `components.json` (for resolvedPaths.ui)
+ */
+function printAdoptionHints(resolvedNames, registry, config) {
+  const peerHints = registry.peerHints ?? {};
+  /** @type {Map<string, string[]>} peer -> component names that need it */
+  const needed = new Map();
+  for (const name of resolvedNames) {
+    for (const peer of peerHints[name] ?? []) {
+      if (!needed.has(peer)) {
+        needed.set(peer, []);
+      }
+      needed.get(peer).push(name);
+    }
+  }
+
+  if (needed.size > 0) {
+    console.log("\nOptional peer dependencies:");
+    for (const [peer, users] of needed) {
+      const reason = PEER_HINT_REASONS[peer] ?? "";
+      console.log(
+        `  - ${peer}${reason ? ` (${reason})` : ""} — used by ${users.join(", ")}`,
+      );
+    }
+    console.log(`  Install with: npm i ${[...needed.keys()].join(" ")}`);
+  }
+
+  const uiPath = config?.resolvedPaths?.ui ?? "your components directory";
+  console.log(
+    `\nTailwind v4: vendored files live in ${uiPath}, so they are scanned automatically when inside your app's content sources.`,
+  );
+  console.log(
+    `  If you placed them elsewhere, add: @source "${uiPath}";  (light + dark: classes are paired, so the whole tree must be scanned)`,
+  );
+}
+
 /**
  * `zentauri-components init` — writes default `components.json` next to `--cwd`.
  *
@@ -707,6 +759,7 @@ async function cmdAdd(names, cwd) {
   }
 
   console.log("Done.");
+  printAdoptionHints(resolvedNames, registry, config);
 }
 
 /**

package/cli/registry.json

@@ -13,8 +13,12 @@
     "charts/area",
     "charts/bar",
     "charts/bubble",
+    "charts/funnel",
     "charts/line",
     "charts/pie",
+    "charts/radar",
+    "charts/scatter",
+    "charts/stacked-bar",
     "checkbox",
     "command",
     "context-menu",
@@ -75,17 +79,149 @@
     "usePrefersReducedMotion",
     "useResizeObserver",
     "useSessionStorage",
+    "useTableFilter",
+    "useTableSort",
     "useThrottledCallback",
     "useToggle",
     "useWindowSize"
   ],
+  "peerHints": {
+    "accordion": [
+      "framer-motion"
+    ],
+    "alert": [
+      "react-icons",
+      "framer-motion"
+    ],
+    "animated-number": [
+      "framer-motion"
+    ],
+    "avatar": [
+      "framer-motion"
+    ],
+    "badge": [
+      "react-icons",
+      "framer-motion"
+    ],
+    "buttons": [
+      "framer-motion"
+    ],
+    "card": [
+      "framer-motion"
+    ],
+    "checkbox": [
+      "framer-motion"
+    ],
+    "command": [
+      "framer-motion"
+    ],
+    "context-menu": [
+      "react-icons"
+    ],
+    "copy-button": [
+      "react-icons",
+      "framer-motion"
+    ],
+    "divider": [
+      "framer-motion"
+    ],
+    "drawer": [
+      "framer-motion"
+    ],
+    "dropdown": [
+      "react-icons"
+    ],
+    "empty-state": [
+      "framer-motion"
+    ],
+    "inputs": [
+      "framer-motion"
+    ],
+    "kbd": [
+      "framer-motion"
+    ],
+    "modal": [
+      "framer-motion"
+    ],
+    "popover": [
+      "framer-motion"
+    ],
+    "progress": [
+      "framer-motion"
+    ],
+    "radio-group": [
+      "framer-motion"
+    ],
+    "rating": [
+      "react-icons"
+    ],
+    "skeleton": [
+      "framer-motion"
+    ],
+    "table": [
+      "framer-motion"
+    ],
+    "tabs": [
+      "framer-motion"
+    ],
+    "timeline": [
+      "framer-motion"
+    ],
+    "toast": [
+      "framer-motion"
+    ],
+    "toggle": [
+      "framer-motion"
+    ],
+    "tooltip": [
+      "framer-motion"
+    ],
+    "tree-view": [
+      "react-icons",
+      "framer-motion"
+    ],
+    "spinner": [
+      "framer-motion"
+    ],
+    "charts/area": [
+      "recharts"
+    ],
+    "charts/bar": [
+      "recharts"
+    ],
+    "charts/bubble": [
+      "recharts"
+    ],
+    "charts/funnel": [
+      "recharts"
+    ],
+    "charts/line": [
+      "recharts"
+    ],
+    "charts/pie": [
+      "recharts"
+    ],
+    "charts/radar": [
+      "recharts"
+    ],
+    "charts/scatter": [
+      "recharts"
+    ],
+    "charts/stacked-bar": [
+      "recharts"
+    ]
+  },
   "nameAliases": {
     "button": "buttons",
     "chart-area": "charts/area",
     "chart-bar": "charts/bar",
     "chart-bubble": "charts/bubble",
+    "chart-funnel": "charts/funnel",
     "chart-line": "charts/line",
     "chart-pie": "charts/pie",
+    "chart-radar": "charts/radar",
+    "chart-scatter": "charts/scatter",
+    "chart-stacked-bar": "charts/stacked-bar",
     "input": "inputs"
   }
 }

package/cli/rewrite-imports.mjs

@@ -13,7 +13,10 @@ export function rewriteImports(source, options) {
     const re = /from\s+(["'])((?:\.\.\/)+)hooks\/([^'"]+)\1/g;
     let m;
     while ((m = re.exec(text)) !== null) {
-      usedHooks.add(m[3]);
+      // Imports may target a file inside the hook folder
+      // (e.g. hooks/useResizeObserver/useResizeObserver); the copyable unit is
+      // the folder, so keep only the first path segment.
+      usedHooks.add(m[3].split("/")[0]);
     }
   };