@zentauri-ui/zentauri-components 1.9.2 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @zentauri-ui/zentauri-components Changelog
 
+## 2.0.0
+
+### Major Changes
+
+#### Extender hooks list
+
+- useEventListener Fundamental utility — safely attach/remove any DOM event
+- usePrevious Track previous value across renders — very common pattern
+- useInterval / useTimeout Safe, cleanup-aware timer hooks
+- useCountdown Countdown timer with pause/resume
+- useKeyPress / useHotkeys Keyboard shortcut management
+- useScrollPosition Track scroll X/Y (differs from useInView)
+- useCookie Cookie read/write with reactive updates
+- useGeolocation Browser geolocation with permission state
+- useLongPress Long-press gesture support
+- useVirtualList Virtual scrolling for large lists (critical for performance)
+- useIdleTimeout Detect user inactivity (session management)
+
 ## 1.9.0
 
 ### Minor Changes

package/README.md

@@ -29,16 +29,17 @@ Generated from the component package Vitest JSON report via `pnpm --filter @zent
 
 | Metric     | Result           |
 | ---------- | ---------------- |
-| Test files | 78 passed (78)   |
-| Tests      | 603 passed (603) |
+| Test files | 92 passed (92)   |
+| Tests      | 700 passed (700) |
 
 | Area                        | Test files | Tests |
 | --------------------------- | ---------- | ----- |
-| Components and UI utilities | 46         | 431   |
+| Components and UI utilities | 46         | 446   |
 | Standalone animations       | 1          | 45    |
-| React hooks                 | 28         | 101   |
+| React hooks                 | 41         | 174   |
 | Design system facade        | 1          | 11    |
-| CLI and import rewriting    | 2          | 15    |
+| CLI and import rewriting    | 2          | 18    |
+| Axe core test cases         | 1          | 6     |
 
 ### Per-suite snapshot
 
@@ -48,20 +49,22 @@ Generated from the component package Vitest JSON report via `pnpm --filter @zent
 | `src/ui/buttons/button.test.tsx`                                        |    44 |
 | `src/ui/inputs/input.test.tsx`                                          |    40 |
 | `src/ui/peer-isolation.test.ts`                                         |    29 |
+| `src/ui/combobox/combobox.test.tsx`                                     |    21 |
 | `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 |
 | `src/ui/select/select.test.tsx`                                         |    11 |
 | `src/ui/table/table.test.tsx`                                           |    11 |
-| `cli/cli.integration.test.ts`                                           |    10 |
 | `src/hooks/usePagination/usePagination.test.ts`                         |    10 |
 | `src/ui/context-menu/context-menu.test.tsx`                             |    10 |
 | `src/ui/marquee/marquee.test.tsx`                                       |    10 |
 | `src/ui/modal/modal.test.tsx`                                           |    10 |
 | `src/ui/otp-input/otp-input.test.tsx`                                   |    10 |
 | `src/ui/tree-view/tree-view.test.tsx`                                   |    10 |
+| `src/hooks/useLongPress/useLongPress.test.ts`                           |     9 |
 | `src/hooks/useTableFilter/useTableFilter.test.ts`                       |     9 |
 | `src/ui/animated-number/animated-number.test.tsx`                       |     9 |
 | `src/ui/slider/slider.test.tsx`                                         |     9 |
@@ -72,6 +75,7 @@ Generated from the component package Vitest JSON report via `pnpm --filter @zent
 | `src/ui/skeleton/skeleton.test.tsx`                                     |     8 |
 | `src/ui/spinner/animated/spinner.test.tsx`                              |     8 |
 | `src/hooks/useDynamicStepper/useDynamicStepper.test.ts`                 |     7 |
+| `src/hooks/useHotkeys/useHotkeys.test.ts`                               |     7 |
 | `src/hooks/useTableSort/useTableSort.test.ts`                           |     7 |
 | `src/ui/accordion/accordion.test.tsx`                                   |     7 |
 | `src/ui/card/card.test.tsx`                                             |     7 |
@@ -79,10 +83,15 @@ Generated from the component package Vitest JSON report via `pnpm --filter @zent
 | `src/ui/drawer/drawer.test.tsx`                                         |     7 |
 | `src/ui/kbd/kbd.test.tsx`                                               |     7 |
 | `src/ui/typography/typography.test.tsx`                                 |     7 |
+| `src/accessibility/axe-core.test.tsx`                                   |     6 |
 | `src/charts/charts.test.tsx`                                            |     6 |
 | `src/hooks/useClipboard/useClipboard.test.ts`                           |     6 |
+| `src/hooks/useCountdown/useCountdown.test.ts`                           |     6 |
+| `src/hooks/useGeolocation/useGeolocation.test.ts`                       |     6 |
+| `src/hooks/useIdleTimeout/useIdleTimeout.test.ts`                       |     6 |
+| `src/hooks/useKeyPress/useKeyPress.test.ts`                             |     6 |
 | `src/hooks/useLocalStorage/useLocalStorage.test.ts`                     |     6 |
-| `src/ui/accessibility/axe-core.test.tsx`                                |     6 |
+| `src/hooks/useVirtualList/useVirtualList.test.ts`                       |     6 |
 | `src/ui/badge/badge.test.tsx`                                           |     6 |
 | `src/ui/checkbox/checkbox.test.tsx`                                     |     6 |
 | `src/ui/divider/divider.test.tsx`                                       |     6 |
@@ -90,13 +99,18 @@ Generated from the component package Vitest JSON report via `pnpm --filter @zent
 | `src/ui/empty-state/empty-state.test.tsx`                               |     6 |
 | `src/ui/search/filter-search-suggestions.test.ts`                       |     6 |
 | `cli/rewrite-imports.test.ts`                                           |     5 |
+| `src/hooks/useCookie/useCookie.test.ts`                                 |     5 |
 | `src/hooks/useDisclosure/useDisclosure.test.ts`                         |     5 |
+| `src/hooks/useEventListener/useEventListener.test.ts`                   |     5 |
+| `src/hooks/useScrollPosition/useScrollPosition.test.ts`                 |     5 |
+| `src/hooks/useTimeout/useTimeout.test.ts`                               |     5 |
 | `src/ui/radio-group/radio-group.test.tsx`                               |     5 |
 | `src/ui/toast/toast.test.tsx`                                           |     5 |
 | `src/ui/toggle/toggle.test.tsx`                                         |     5 |
 | `src/hooks/useBodyScrollLock/useBodyScrollLock.test.ts`                 |     4 |
 | `src/hooks/useControllableState/useControllableState.test.ts`           |     4 |
 | `src/hooks/useDebouncedValue/useDebouncedValue.test.ts`                 |     4 |
+| `src/hooks/useInterval/useInterval.test.ts`                             |     4 |
 | `src/hooks/useThrottledCallback/useThrottledCallback.test.ts`           |     4 |
 | `src/hooks/useToggle/useToggle.test.ts`                                 |     4 |
 | `src/ui/avatar/avatar.test.tsx`                                         |     4 |
@@ -108,6 +122,7 @@ Generated from the component package Vitest JSON report via `pnpm --filter @zent
 | `src/hooks/useDocumentTitle/useDocumentTitle.test.ts`                   |     3 |
 | `src/hooks/useFocusManagement/useFocusManagement.test.tsx`              |     3 |
 | `src/hooks/useIsMounted/useIsMounted.test.ts`                           |     3 |
+| `src/hooks/usePrevious/usePrevious.test.ts`                             |     3 |
 | `src/hooks/useSessionStorage/useSessionStorage.test.ts`                 |     3 |
 | `src/ui/tabs/tabs.test.tsx`                                             |     3 |
 | `src/hooks/useHover/useHover.test.ts`                                   |     2 |
@@ -399,29 +414,42 @@ Hooks live in `src/hooks/`. Each hook is a separate published entry under `@zent
 | `useClickOutside`           | `useClickOutside`           | `ClickOutsideEventType`, `UseClickOutsideParams`                                          |
 | `useClipboard`              | `useClipboard`              | `UseClipboardResult`                                                                      |
 | `useControllableState`      | `useControllableState`      | `UseControllableStateParams`                                                              |
+| `useCookie`                 | `useCookie`                 | `CookieOptions`, `UseCookieResult`                                                        |
+| `useCountdown`              | `useCountdown`              | `UseCountdownParams`, `UseCountdownResult`                                                |
 | `useDebouncedValue`         | `useDebouncedValue`         | Debounced state from a value                                                              |
 | `useDisclosure`             | `useDisclosure`             | `UseDisclosureParams`, `UseDisclosureResult`                                              |
 | `useDocumentTitle`          | `useDocumentTitle`          | `UseDocumentTitleParams`                                                                  |
 | `useDynamicStepper`         | `useDynamicStepper`         | `UseDynamicStepperParams`, `UseDynamicStepperResult` (types also on `ui/dynamic-stepper`) |
+| `useEventListener`          | `useEventListener`          | `UseEventListenerTarget` — window / document / element / ref targets                      |
 | `useFocusManagement`        | `useFocusManagement`        | Focus trap / focus moves for overlays                                                     |
+| `useGeolocation`            | `useGeolocation`            | `UseGeolocationParams`, `UseGeolocationResult`, permission state                          |
+| `useHotkeys`                | `useHotkeys`                | `HotkeyHandler`, `UseHotkeysOptions` — `mod+k` style combos                               |
 | `useHover`                  | `useHover`                  | Pointer hover state                                                                       |
+| `useIdleTimeout`            | `useIdleTimeout`            | `UseIdleTimeoutParams`, `UseIdleTimeoutResult`                                            |
+| `useInterval`               | `useInterval`               | Declarative `setInterval`; `null` pauses                                                  |
 | `useInView`                 | `useInView`                 | `UseInViewParams`                                                                         |
 | `useIntersectionObserver`   | `useIntersectionObserver`   | `UseIntersectionObserverParams`                                                           |
 | `useIsomorphicLayoutEffect` | `useIsomorphicLayoutEffect` | `useLayoutEffect` safe for SSR                                                            |
 | `useIsMounted`              | `useIsMounted`              | Ref / flag after mount                                                                    |
+| `useKeyPress`               | `useKeyPress`               | Held-key boolean for a key or key list                                                    |
 | `useLocalStorage`           | `useLocalStorage`           | `UseLocalStorageResult`                                                                   |
+| `useLongPress`              | `useLongPress`              | `UseLongPressHandlers`, `UseLongPressOptions`                                             |
 | `useMediaQuery`             | `useMediaQuery`             | Match CSS media queries                                                                   |
 | `useNetworkStatus`          | `useNetworkStatus`          | Online / offline                                                                          |
 | `usePageVisibility`         | `usePageVisibility`         | Document visibility API                                                                   |
 | `usePagination`             | `usePagination`             | `buildPaginationItems`, `BuildPaginationItemsParams`, `PaginationPageItem`                |
 | `usePrefersColorScheme`     | `usePrefersColorScheme`     | `ColorSchemePreference`                                                                   |
 | `usePrefersReducedMotion`   | `usePrefersReducedMotion`   | `prefers-reduced-motion`                                                                  |
+| `usePrevious`               | `usePrevious`               | Value from the previous render                                                            |
 | `useResizeObserver`         | `useResizeObserver`         | `ElementSize`                                                                             |
+| `useScrollPosition`         | `useScrollPosition`         | `ScrollPosition`, `UseScrollPositionParams`                                               |
 | `useSessionStorage`         | `useSessionStorage`         | `UseSessionStorageResult`                                                                 |
 | `useTableFilter`            | `useTableFilter`            | `TableFilterState`, `UseTableFilterResult`                                                |
 | `useTableSort`              | `useTableSort`              | `UseTableSortParams`, `UseTableSortResult`                                                |
 | `useThrottledCallback`      | `useThrottledCallback`      | Throttled callback ref                                                                    |
+| `useTimeout`                | `useTimeout`                | `UseTimeoutResult` — `clear` / `reset` controls                                           |
 | `useToggle`                 | `useToggle`                 | Boolean toggle state                                                                      |
+| `useVirtualList`            | `useVirtualList`            | `UseVirtualListParams`, `UseVirtualListResult`, `VirtualItem`                             |
 | `useWindowSize`             | `useWindowSize`             | `WindowSize`                                                                              |
 | `cn`, `clampPage`, `range`  | `utils`                     | Shared helpers from `src/lib/utils.ts`                                                    |
 
@@ -818,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 603 test cases in total
+- `pnpm test` / `pnpm test:watch` — **Vitest** and **Testing Library** unit tests // currently covered 700 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

@@ -162,6 +162,58 @@ describe("zentauri-ui CLI", () => {
     }
   });
 
+  it("should generate compact global theme CSS", () => {
+    const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-theme-"));
+    try {
+      const out = runCli(dir, ["theme", "#2563eb", "--dark", "#60a5fa"]);
+      const tokenCount = (out.match(/^\s*--zui-/gm) ?? []).length;
+      expect(out).toContain("Generated by zentauri-ui theme #2563eb");
+      expect(out).toContain("--zui-brand: #2563eb;");
+      expect(out).toContain("--zui-brand-dark: #60a5fa;");
+      expect(out).toContain("--zui-color-blue: var(--zui-brand);");
+      expect(out).toContain("--zui-color-blue-dark: var(--zui-brand-dark);");
+      expect(out).not.toContain("--zui-button-default-bg:");
+      expect(tokenCount).toBeLessThan(100);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("should keep readable dark foreground when default dark brand stays dark", () => {
+    const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-theme-dark-"));
+    try {
+      const out = runCli(dir, ["theme", "#020617"]);
+      expect(out).toContain(
+        "--zui-brand-dark: color-mix(in oklch, #020617 72%, #ffffff);",
+      );
+      expect(out).toContain("--zui-brand-fg-dark: #ffffff;");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("should write compact theme CSS with a custom selector", () => {
+    const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-theme-out-"));
+    try {
+      const out = runCli(dir, [
+        "theme",
+        "38bdf8",
+        "--selector",
+        "[data-theme='zentauri']",
+        "--out",
+        "src/styles/zentauri-theme.css",
+      ]);
+      const themePath = join(dir, "src/styles/zentauri-theme.css");
+      expect(out).toContain("Wrote ");
+      expect(out).toContain("zentauri-theme.css");
+      const css = readFileSync(themePath, "utf8");
+      expect(css).toContain("[data-theme='zentauri'] {");
+      expect(css).toContain("--zui-brand: #38bdf8;");
+    } 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 {

package/cli/index.mjs

@@ -146,6 +146,7 @@ Usage:
   zentauri-components init [options]              Create components.json with defaults
   zentauri-components add <component> [...]       Copy UI components (and their hooks)
   zentauri-components add hook <hook> [...]       Copy hook source only (plus transitive hook deps)
+  zentauri-components theme <hex>                 Generate compact global --zui-* theme tokens
 
 List of components:
 ${componentsList}
@@ -160,6 +161,9 @@ ${hooksList}
 
 Options:
   --cwd <dir>    Working directory (default: process.cwd())
+  --out <file>   Write theme CSS to a file instead of stdout
+  --selector <s> CSS selector for light tokens (default: :root)
+  --dark <hex>   Explicit dark-mode brand color (default: derived from <hex>)
   -h, --help     Show help
   -v, --version  Show package version
 
@@ -175,6 +179,7 @@ Use hooks from the package without copying (after npm install):
 Published package:
   npx @zentauri-ui/zentauri-components init
   npx @zentauri-ui/zentauri-components add accordion buttons inputs
+  npx @zentauri-ui/zentauri-components theme "#2563eb" --dark "#60a5fa" --out zentauri-theme.css
 
 If npx does not pick the right binary:
   npx --yes --package=@zentauri-ui/zentauri-components zentauri-components init
@@ -391,6 +396,259 @@ function resolveHookName(input, registry) {
   );
 }
 
+const THEME_COLOR_NAMES = [
+  "blue",
+  "cyan",
+  "green",
+  "lime",
+  "mint",
+  "ocean",
+  "sapphire",
+  "lavender",
+  "ruby",
+  "red",
+  "slate",
+  "zinc",
+  "stone",
+  "royal",
+  "electric",
+  "forest",
+  "sunset",
+  "magenta",
+  "crimson",
+  "aqua",
+  "plum",
+  "emerald",
+  "indigo",
+  "purple",
+  "pink",
+  "rose",
+  "sky",
+  "teal",
+  "yellow",
+  "orange",
+  "gray",
+  "amber",
+  "violet",
+];
+
+function normalizeHexColor(input) {
+  const raw = input.trim().replace(/^#/, "");
+  if (/^[0-9a-fA-F]{3}$/.test(raw)) {
+    return `#${raw
+      .split("")
+      .map((ch) => `${ch}${ch}`)
+      .join("")
+      .toLowerCase()}`;
+  }
+  if (/^[0-9a-fA-F]{6}$/.test(raw)) {
+    return `#${raw.toLowerCase()}`;
+  }
+  throw new Error(
+    `Invalid brand color "${input}". Use a 3- or 6-digit hex color, for example "#2563eb".`,
+  );
+}
+
+function hexToRgb(hex) {
+  const normalized = normalizeHexColor(hex).slice(1);
+  return {
+    r: Number.parseInt(normalized.slice(0, 2), 16),
+    g: Number.parseInt(normalized.slice(2, 4), 16),
+    b: Number.parseInt(normalized.slice(4, 6), 16),
+  };
+}
+
+function srgbChannelToLinear(value) {
+  const channel = value / 255;
+  return channel <= 0.04045
+    ? channel / 12.92
+    : ((channel + 0.055) / 1.055) ** 2.4;
+}
+
+function linearChannelToSrgb(value) {
+  const channel =
+    value <= 0.0031308 ? 12.92 * value : 1.055 * value ** (1 / 2.4) - 0.055;
+  return Math.min(255, Math.max(0, Math.round(channel * 255)));
+}
+
+function rgbToOklab({ r, g, b }) {
+  const linearR = srgbChannelToLinear(r);
+  const linearG = srgbChannelToLinear(g);
+  const linearB = srgbChannelToLinear(b);
+
+  const l = Math.cbrt(
+    0.4122214708 * linearR + 0.5363325363 * linearG + 0.0514459929 * linearB,
+  );
+  const m = Math.cbrt(
+    0.2119034982 * linearR + 0.6806995451 * linearG + 0.1073969566 * linearB,
+  );
+  const s = Math.cbrt(
+    0.0883024619 * linearR + 0.2817188376 * linearG + 0.6299787005 * linearB,
+  );
+
+  return {
+    l: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+  };
+}
+
+function oklabToRgb({ l, a, b }) {
+  const lPrime = l + 0.3963377774 * a + 0.2158037573 * b;
+  const mPrime = l - 0.1055613458 * a - 0.0638541728 * b;
+  const sPrime = l - 0.0894841775 * a - 1.291485548 * b;
+
+  const lCubed = lPrime ** 3;
+  const mCubed = mPrime ** 3;
+  const sCubed = sPrime ** 3;
+
+  return {
+    r: linearChannelToSrgb(
+      4.0767416621 * lCubed - 3.3077115913 * mCubed + 0.2309699292 * sCubed,
+    ),
+    g: linearChannelToSrgb(
+      -1.2684380046 * lCubed + 2.6097574011 * mCubed - 0.3413193965 * sCubed,
+    ),
+    b: linearChannelToSrgb(
+      -0.0041960863 * lCubed - 0.7034186147 * mCubed + 1.707614701 * sCubed,
+    ),
+  };
+}
+
+function rgbToOklch(rgb) {
+  const lab = rgbToOklab(rgb);
+  return {
+    l: lab.l,
+    c: Math.sqrt(lab.a ** 2 + lab.b ** 2),
+    h: Math.atan2(lab.b, lab.a),
+  };
+}
+
+function oklchToRgb({ l, c, h }) {
+  return oklabToRgb({
+    l,
+    a: c * Math.cos(h),
+    b: c * Math.sin(h),
+  });
+}
+
+function mixHexWithWhiteInOklch(hex, weight) {
+  const brand = rgbToOklch(hexToRgb(hex));
+  const white = rgbToOklch({ r: 255, g: 255, b: 255 });
+
+  return oklchToRgb({
+    l: brand.l * weight + white.l * (1 - weight),
+    c: brand.c * weight,
+    h: brand.h,
+  });
+}
+
+function readableTextColorFromRgb({ r, g, b }) {
+  const linear = [r, g, b].map((value) => {
+    const channel = value / 255;
+    return channel <= 0.03928
+      ? channel / 12.92
+      : ((channel + 0.055) / 1.055) ** 2.4;
+  });
+  const luminance =
+    0.2126 * linear[0] + 0.7152 * linear[1] + 0.0722 * linear[2];
+  return luminance > 0.56 ? "#0f172a" : "#ffffff";
+}
+
+function readableTextColor(hex) {
+  return readableTextColorFromRgb(hexToRgb(hex));
+}
+
+function buildCompactThemeCss(hex, options = {}) {
+  const brand = normalizeHexColor(hex);
+  const darkBrand = options.dark
+    ? normalizeHexColor(options.dark)
+    : `color-mix(in oklch, ${brand} 72%, #ffffff)`;
+  const brandFg = readableTextColor(brand);
+  const darkBrandFg = options.dark
+    ? readableTextColor(darkBrand)
+    : readableTextColorFromRgb(mixHexWithWhiteInOklch(brand, 0.72));
+  const selector = options.selector || ":root";
+  const lightTokens = [
+    ["--zui-ring-offset", "#f8fafc"],
+    ["--zui-focus-ring", "color-mix(in oklch, var(--zui-brand) 72%, #475569)"],
+    ["--zui-surface-muted", "#e2e8f0"],
+    [
+      "--zui-surface-soft",
+      "color-mix(in oklch, var(--zui-brand) 8%, transparent)",
+    ],
+    [
+      "--zui-surface-hover",
+      "color-mix(in oklch, var(--zui-brand) 14%, transparent)",
+    ],
+    ["--zui-border", "color-mix(in oklch, var(--zui-brand) 24%, transparent)"],
+    ["--zui-fg", "#0f172a"],
+    ["--zui-fg-muted", "#475569"],
+    ["--zui-brand", brand],
+    ["--zui-brand-hover", "color-mix(in oklch, var(--zui-brand) 88%, #000000)"],
+    ["--zui-brand-fg", brandFg],
+    ["--zui-status-success", "#16a34a"],
+    ["--zui-status-warning", "#d97706"],
+    ["--zui-status-error", "#e11d48"],
+    ["--zui-status-info", "#0284c7"],
+    ...THEME_COLOR_NAMES.map((name) => [
+      `--zui-color-${name}`,
+      "var(--zui-brand)",
+    ]),
+  ];
+  const darkTokens = [
+    ["--zui-ring-offset-dark", "#020617"],
+    [
+      "--zui-focus-ring-dark",
+      "color-mix(in oklch, var(--zui-brand-dark) 72%, #cbd5e1)",
+    ],
+    ["--zui-surface-muted-dark", "#1e293b"],
+    [
+      "--zui-surface-soft-dark",
+      "color-mix(in oklch, var(--zui-brand-dark) 12%, transparent)",
+    ],
+    [
+      "--zui-surface-hover-dark",
+      "color-mix(in oklch, var(--zui-brand-dark) 18%, transparent)",
+    ],
+    [
+      "--zui-border-dark",
+      "color-mix(in oklch, var(--zui-brand-dark) 28%, transparent)",
+    ],
+    ["--zui-fg-dark", "#f8fafc"],
+    ["--zui-fg-muted-dark", "#cbd5e1"],
+    ["--zui-brand-dark", darkBrand],
+    [
+      "--zui-brand-hover-dark",
+      "color-mix(in oklch, var(--zui-brand-dark) 88%, #ffffff)",
+    ],
+    ["--zui-brand-fg-dark", darkBrandFg],
+    ["--zui-status-success-dark", "#22c55e"],
+    ["--zui-status-warning-dark", "#f59e0b"],
+    ["--zui-status-error-dark", "#fb7185"],
+    ["--zui-status-info-dark", "#38bdf8"],
+    ...THEME_COLOR_NAMES.map((name) => [
+      `--zui-color-${name}-dark`,
+      "var(--zui-brand-dark)",
+    ]),
+  ];
+
+  const render = (scope, tokens) =>
+    `${scope} {\n${tokens.map(([name, value]) => `  ${name}: ${value};`).join("\n")}\n}`;
+
+  return [
+    "/*",
+    ` * Generated by zentauri-ui theme ${brand}`,
+    ` * Compact global token mode: ${lightTokens.length + darkTokens.length} variables`,
+    " */",
+    "",
+    render(selector, lightTokens),
+    "",
+    render(".dark", darkTokens),
+    "",
+  ].join("\n");
+}
+
 /**
  * Starting from hook folder names discovered in UI code, expands the set to
  * include every hook that those hooks import from **sibling** hook packages
@@ -792,6 +1050,29 @@ async function cmdAdd(names, cwd) {
   printAdoptionHints(resolvedNames, registry, config);
 }
 
+async function cmdTheme(hex, options, cwd) {
+  if (!hex) {
+    console.error(
+      'Usage: zentauri-components theme <hex>  (e.g. theme "#2563eb" --dark "#60a5fa" --out zentauri-theme.css)',
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const css = buildCompactThemeCss(hex, {
+    dark: options.dark,
+    selector: options.selector,
+  });
+  if (options.out) {
+    const outPath = resolve(cwd, options.out);
+    await mkdir(dirname(outPath), { recursive: true });
+    await writeFile(outPath, css, "utf8");
+    console.log(`Wrote ${outPath}`);
+    return;
+  }
+  console.log(css);
+}
+
 /**
  * Parses `process.argv` with `node:util.parseArgs`, dispatches `init` / `add`,
  * or prints help / version. Sets `process.exitCode` for recoverable CLI errors
@@ -818,6 +1099,9 @@ async function main() {
       help: { type: "boolean", short: "h" },
       version: { type: "boolean", short: "v" },
       cwd: { type: "string" },
+      out: { type: "string" },
+      selector: { type: "string" },
+      dark: { type: "string" },
     },
   });
 
@@ -858,6 +1142,10 @@ async function main() {
     await cmdAdd(rest, cwd);
     return;
   }
+  if (cmd === "theme") {
+    await cmdTheme(rest[0], values, cwd);
+    return;
+  }
 
   console.error(`Unknown command: ${cmd}`);
   printHelp();

package/cli/registry.json

@@ -61,6 +61,7 @@
     "charts/scatter",
     "charts/stacked-bar",
     "checkbox",
+    "combobox",
     "command",
     "context-menu",
     "copy-button",
@@ -143,29 +144,42 @@
     "useClickOutside",
     "useClipboard",
     "useControllableState",
+    "useCookie",
+    "useCountdown",
     "useDebouncedValue",
     "useDisclosure",
     "useDocumentTitle",
     "useDynamicStepper",
+    "useEventListener",
     "useFocusManagement",
+    "useGeolocation",
+    "useHotkeys",
     "useHover",
+    "useIdleTimeout",
     "useInView",
     "useIntersectionObserver",
+    "useInterval",
     "useIsMounted",
     "useIsomorphicLayoutEffect",
+    "useKeyPress",
     "useLocalStorage",
+    "useLongPress",
     "useMediaQuery",
     "useNetworkStatus",
     "usePageVisibility",
     "usePagination",
     "usePrefersColorScheme",
     "usePrefersReducedMotion",
+    "usePrevious",
     "useResizeObserver",
+    "useScrollPosition",
     "useSessionStorage",
     "useTableFilter",
     "useTableSort",
     "useThrottledCallback",
+    "useTimeout",
     "useToggle",
+    "useVirtualList",
     "useWindowSize"
   ],
   "peerHints": {