@zentauri-ui/zentauri-components 1.9.1 → 2.0.0

package/src/hooks/useTimeout/useTimeout.ts

@@ -0,0 +1,58 @@
+"use client";
+
+import { useCallback, useEffect, useRef } from "react";
+
+export type UseTimeoutResult = {
+  /** Cancel the pending timeout (no-op if already fired or cleared). */
+  clear: () => void;
+  /** Cancel any pending timeout and schedule a fresh one with the current delay. */
+  reset: () => void;
+};
+
+/**
+ * Declarative `setTimeout`: runs `callback` once after `delayMs` milliseconds with automatic cleanup.
+ *
+ * - The latest callback is kept in a ref, so a new inline function each render does not reschedule.
+ * - Pass `null` as the delay to cancel scheduling entirely.
+ * - Changing `delayMs` cancels the pending timeout and schedules a new one.
+ *
+ * @param callback - Function invoked when the timeout fires.
+ * @param delayMs - Delay in milliseconds, or `null` to disable.
+ * @returns `{ clear, reset }` to cancel or restart the timeout imperatively.
+ */
+export function useTimeout(
+  callback: () => void,
+  delayMs: number | null,
+): UseTimeoutResult {
+  const callbackRef = useRef(callback);
+  const timeoutRef = useRef<number | undefined>(undefined);
+
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+
+  const clear = useCallback(() => {
+    if (timeoutRef.current !== undefined) {
+      window.clearTimeout(timeoutRef.current);
+      timeoutRef.current = undefined;
+    }
+  }, []);
+
+  const reset = useCallback(() => {
+    clear();
+    if (delayMs == null) {
+      return;
+    }
+    timeoutRef.current = window.setTimeout(() => {
+      timeoutRef.current = undefined;
+      callbackRef.current();
+    }, delayMs);
+  }, [clear, delayMs]);
+
+  useEffect(() => {
+    reset();
+    return clear;
+  }, [clear, reset]);
+
+  return { clear, reset };
+}

package/src/hooks/useVirtualList/index.ts

@@ -0,0 +1,6 @@
+export {
+  useVirtualList,
+  type UseVirtualListParams,
+  type UseVirtualListResult,
+  type VirtualItem,
+} from "./useVirtualList";

package/src/hooks/useVirtualList/useVirtualList.test.ts

@@ -0,0 +1,102 @@
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { useVirtualList } from "./useVirtualList";
+
+function createContainer(clientHeight: number): HTMLDivElement {
+  const element = document.createElement("div");
+  Object.defineProperty(element, "clientHeight", {
+    configurable: true,
+    value: clientHeight,
+  });
+  return element;
+}
+
+describe("useVirtualList", () => {
+  it("should expose the full content height", () => {
+    const { result } = renderHook(() =>
+      useVirtualList({ itemCount: 1000, itemHeight: 40 }),
+    );
+    expect(result.current.totalHeight).toBe(40000);
+  });
+
+  it("should render only the visible window plus overscan", () => {
+    const container = createContainer(200);
+    const { result } = renderHook(() =>
+      useVirtualList({ itemCount: 1000, itemHeight: 40, overscan: 2 }),
+    );
+    act(() => {
+      result.current.setContainerRef(container);
+    });
+    // viewport 200px / 40px rows = 5 visible + 2 overscan below (none above at top)
+    expect(result.current.startIndex).toBe(0);
+    expect(result.current.endIndex).toBe(6);
+    expect(result.current.virtualItems).toHaveLength(7);
+    expect(result.current.virtualItems[0]).toEqual({
+      index: 0,
+      start: 0,
+      size: 40,
+    });
+  });
+
+  it("should shift the window on scroll", () => {
+    const container = createContainer(200);
+    const { result } = renderHook(() =>
+      useVirtualList({ itemCount: 1000, itemHeight: 40, overscan: 2 }),
+    );
+    act(() => {
+      result.current.setContainerRef(container);
+    });
+    act(() => {
+      container.scrollTop = 400;
+      container.dispatchEvent(new Event("scroll"));
+    });
+    // rows 10..14 visible, ±2 overscan
+    expect(result.current.startIndex).toBe(8);
+    expect(result.current.endIndex).toBe(16);
+    expect(result.current.virtualItems[0]?.start).toBe(8 * 40);
+  });
+
+  it("should clamp the window at the end of the list", () => {
+    const container = createContainer(200);
+    const { result } = renderHook(() =>
+      useVirtualList({ itemCount: 12, itemHeight: 40, overscan: 3 }),
+    );
+    act(() => {
+      result.current.setContainerRef(container);
+    });
+    act(() => {
+      container.scrollTop = 280;
+      container.dispatchEvent(new Event("scroll"));
+    });
+    expect(result.current.endIndex).toBe(11);
+  });
+
+  it("should handle an empty list", () => {
+    const { result } = renderHook(() =>
+      useVirtualList({ itemCount: 0, itemHeight: 40 }),
+    );
+    expect(result.current.virtualItems).toHaveLength(0);
+    expect(result.current.totalHeight).toBe(0);
+    expect(result.current.endIndex).toBe(-1);
+  });
+
+  it("should scroll to an index, clamped to bounds", () => {
+    const container = createContainer(200);
+    const { result } = renderHook(() =>
+      useVirtualList({ itemCount: 100, itemHeight: 40, overscan: 0 }),
+    );
+    act(() => {
+      result.current.setContainerRef(container);
+    });
+    act(() => {
+      result.current.scrollToIndex(50);
+    });
+    expect(container.scrollTop).toBe(2000);
+    expect(result.current.startIndex).toBe(50);
+    act(() => {
+      result.current.scrollToIndex(500);
+    });
+    expect(container.scrollTop).toBe(99 * 40);
+  });
+});

package/src/hooks/useVirtualList/useVirtualList.ts

@@ -0,0 +1,144 @@
+"use client";
+
+import type { RefCallback } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
+
+export type VirtualItem = {
+  /** Index into your data array. */
+  index: number;
+  /** Offset from the top of the scroll content in pixels (use for `translateY` / `top`). */
+  start: number;
+  /** Row height in pixels. */
+  size: number;
+};
+
+export type UseVirtualListParams = {
+  /** Total number of rows in the list. */
+  itemCount: number;
+  /** Fixed height of every row in pixels (must be > 0). */
+  itemHeight: number;
+  /** Extra rows rendered above and below the viewport (default `3`). */
+  overscan?: number;
+};
+
+export type UseVirtualListResult = {
+  /** Callback ref for the scrollable container (needs `overflow-y: auto` and a bounded height). */
+  setContainerRef: RefCallback<HTMLElement>;
+  /** The rows to render, each with its absolute `start` offset. */
+  virtualItems: VirtualItem[];
+  /** Height of the full list content; set it on an inner spacer element. */
+  totalHeight: number;
+  /** First rendered index (after overscan). */
+  startIndex: number;
+  /** Last rendered index (after overscan), `-1` when empty. */
+  endIndex: number;
+  /** Scroll the container so the given row is at the top. */
+  scrollToIndex: (index: number) => void;
+};
+
+/**
+ * Headless fixed-height list virtualization: renders only the rows visible in the
+ * scroll container (plus `overscan`), so lists of tens of thousands of rows stay cheap.
+ *
+ * Markup recipe: outer container gets `setContainerRef` + `overflow-y: auto` and a height;
+ * inside it, one relative spacer div with `height: totalHeight`; each virtual item is
+ * absolutely positioned at `translateY(item.start)` with `height: item.size`.
+ *
+ * Viewport size tracks `ResizeObserver` (when available) and scroll position tracks a
+ * passive `scroll` listener. For variable-height rows, reach for a dedicated virtualizer.
+ *
+ * @param params - {@link UseVirtualListParams}
+ * @returns {@link UseVirtualListResult}
+ */
+export function useVirtualList({
+  itemCount,
+  itemHeight,
+  overscan = 3,
+}: UseVirtualListParams): UseVirtualListResult {
+  const [container, setContainer] = useState<HTMLElement | null>(null);
+  const [scrollTop, setScrollTop] = useState(0);
+  const [viewportHeight, setViewportHeight] = useState(0);
+
+  const setContainerRef = useCallback((node: HTMLElement | null) => {
+    setContainer(node);
+  }, []);
+
+  useEffect(() => {
+    if (container == null) {
+      return;
+    }
+    const onScroll = () => {
+      setScrollTop(container.scrollTop);
+    };
+    const measure = () => {
+      setViewportHeight(container.clientHeight);
+    };
+    measure();
+    onScroll();
+    container.addEventListener("scroll", onScroll, { passive: true });
+    let observer: ResizeObserver | undefined;
+    if (typeof ResizeObserver !== "undefined") {
+      observer = new ResizeObserver(measure);
+      observer.observe(container);
+    }
+    return () => {
+      container.removeEventListener("scroll", onScroll);
+      observer?.disconnect();
+    };
+  }, [container]);
+
+  const safeItemCount = Math.max(0, Math.floor(itemCount));
+  const safeItemHeight = Math.max(1, itemHeight);
+  const safeOverscan = Math.max(0, Math.floor(overscan));
+
+  const totalHeight = safeItemCount * safeItemHeight;
+  const startIndex =
+    safeItemCount === 0
+      ? 0
+      : Math.max(
+          0,
+          Math.floor(scrollTop / safeItemHeight) - safeOverscan,
+        );
+  const endIndex =
+    safeItemCount === 0
+      ? -1
+      : Math.min(
+          safeItemCount - 1,
+          Math.ceil((scrollTop + viewportHeight) / safeItemHeight) -
+            1 +
+            safeOverscan,
+        );
+
+  const virtualItems = useMemo(() => {
+    const items: VirtualItem[] = [];
+    for (let index = startIndex; index <= endIndex; index += 1) {
+      items.push({
+        index,
+        start: index * safeItemHeight,
+        size: safeItemHeight,
+      });
+    }
+    return items;
+  }, [endIndex, safeItemHeight, startIndex]);
+
+  const scrollToIndex = useCallback(
+    (index: number) => {
+      if (container == null || safeItemCount === 0) {
+        return;
+      }
+      const clamped = Math.min(Math.max(index, 0), safeItemCount - 1);
+      container.scrollTop = clamped * safeItemHeight;
+      setScrollTop(container.scrollTop);
+    },
+    [container, safeItemCount, safeItemHeight],
+  );
+
+  return {
+    setContainerRef,
+    virtualItems,
+    totalHeight,
+    startIndex,
+    endIndex,
+    scrollToIndex,
+  };
+}

package/src/lib/facade.test.ts

@@ -0,0 +1,182 @@
+import { describe, expect, it } from "vitest";
+
+import { DesignSystem } from "../lib/facade";
+
+describe("DesignSystem facade", () => {
+  it("lists known components", () => {
+    const slugs = DesignSystem.components();
+    expect(slugs).toContain("accordion");
+    expect(slugs).toContain("buttons");
+    expect(slugs).toContain("inputs");
+    expect(slugs.length).toBe(DesignSystem.listComponents().length);
+  });
+
+  it("resolves a component handle", () => {
+    const accordion = DesignSystem.getComponent("accordion");
+    expect(accordion?.title).toBe("Accordion");
+    expect(accordion?.appearances()).toEqual(
+      expect.arrayContaining(["default", "blue", "outline"]),
+    );
+    expect(accordion?.sizes()).toEqual(
+      expect.arrayContaining(["sm", "md", "lg"]),
+    );
+    expect(accordion?.slots()).toEqual(
+      expect.arrayContaining(["root", "item", "trigger", "content"]),
+    );
+    expect(accordion?.groups()).toEqual(
+      expect.arrayContaining(["appearance", "size"]),
+    );
+  });
+
+  it("resolves a variant and its variables with light/dark pairing", () => {
+    const variant = DesignSystem.getComponent("accordion")?.getVariant(
+      "appearance",
+      "blue",
+    );
+
+    expect(variant?.slot).toBe("root");
+    expect(variant?.className).toContain("--zui-accordion-blue-divider");
+
+    const variables = variant?.variables() ?? [];
+    const light = variables.find(
+      (token) => token.name === "--zui-accordion-blue-divider",
+    );
+    const dark = variables.find(
+      (token) => token.name === "--zui-accordion-blue-divider-dark",
+    );
+
+    expect(light?.theme).toBe("light");
+    expect(light?.pairName).toBe("--zui-accordion-blue-divider-dark");
+    expect(dark?.theme).toBe("dark");
+    expect(dark?.pairName).toBe("--zui-accordion-blue-divider");
+  });
+
+  it("resolves slot-scoped variants", () => {
+    const itemBlue = DesignSystem.getComponent("accordion")?.getVariant(
+      "appearance",
+      "blue",
+      { slot: "item" },
+    );
+
+    expect(itemBlue?.slot).toBe("item");
+    expect(itemBlue?.className).toContain("--zui-accordion-item-blue-border");
+  });
+
+  it("scopes variables to the component token prefix", () => {
+    const buttonVars = DesignSystem.getComponent("buttons")?.variables() ?? [];
+    expect(buttonVars.length).toBeGreaterThan(0);
+    expect(
+      buttonVars.every((token) => token.name.startsWith("--zui-button")),
+    ).toBe(true);
+
+    const inputVars = DesignSystem.getComponent("inputs")?.variables() ?? [];
+    expect(
+      inputVars.every((token) => token.name.startsWith("--zui-input")),
+    ).toBe(true);
+  });
+
+  it("borrows the Input recipe for SearchBar", () => {
+    const search = DesignSystem.getComponent("search");
+    const input = DesignSystem.getComponent("inputs");
+
+    expect(search?.title).toBe("Search");
+
+    const searchVars = search?.variables() ?? [];
+    expect(searchVars.length).toBeGreaterThan(0);
+    // SearchBar has no tokens of its own — every variable is an Input variable.
+    expect(
+      searchVars.every((token) => token.name.startsWith("--zui-input")),
+    ).toBe(true);
+    expect(searchVars.length).toBe(input?.variables().length);
+  });
+
+  it("does not absorb another component's exports via a shared namespace", () => {
+    // ContextMenu reuses Dropdown's `--zui-dropdown-*` namespace, but scoping by
+    // export stem means it only collects its own exports — never Dropdown's
+    // trigger tokens, which ContextMenu has no export for.
+    const contextMenu = DesignSystem.getComponent("context-menu");
+    const dropdown = DesignSystem.getComponent("dropdown");
+
+    const contextMenuNames = (contextMenu?.variables() ?? []).map(
+      (token) => token.name,
+    );
+    const dropdownNames = (dropdown?.variables() ?? []).map(
+      (token) => token.name,
+    );
+
+    expect(contextMenuNames.length).toBeGreaterThan(0);
+    expect(
+      dropdownNames.some((name) => name.includes("dropdown-trigger")),
+    ).toBe(true);
+    expect(
+      contextMenuNames.some((name) => name.includes("dropdown-trigger")),
+    ).toBe(false);
+  });
+
+  it("ignores shared recipe exports so badge tokens never leak into buttons", () => {
+    // `zuiButtonLikeSolidAppearances` is spread into `zuiBadgeAppearances` and
+    // references `--zui-badge-*`. Its `Button` prefix must not pull it into the
+    // Buttons model, and it must not add a phantom appearance group.
+    const buttons = DesignSystem.getComponent("buttons");
+
+    expect(
+      (buttons?.variables() ?? []).some((token) =>
+        token.name.startsWith("--zui-badge"),
+      ),
+    ).toBe(false);
+    expect(buttons?.appearances()).not.toContain("like-solid");
+    expect(buttons?.slots()).not.toContain("like-solid");
+  });
+
+  it("recognizes the full set of variant-group suffixes", () => {
+    const toastPositions = DesignSystem.getComponent("toast")
+      ?.variants("position", { slot: "viewport" })
+      .map((variant) => variant.key);
+    expect(toastPositions).toEqual(
+      expect.arrayContaining(["top-left", "bottom-right"]),
+    );
+
+    const popoverWidths = DesignSystem.getComponent("popover")
+      ?.variants("width", { slot: "content" })
+      .map((variant) => variant.key);
+    expect(popoverWidths).toEqual(expect.arrayContaining(["sm", "2xl"]));
+
+    const badgeShapes = DesignSystem.getComponent("badge")
+      ?.variants("shape")
+      .map((variant) => variant.key);
+    expect(badgeShapes).toEqual(expect.arrayContaining(["pill", "square"]));
+
+    const drawerSides = DesignSystem.getComponent("drawer")
+      ?.variants("side", { slot: "content" })
+      .map((variant) => variant.key);
+    expect(drawerSides).toEqual(expect.arrayContaining(["left", "right"]));
+  });
+
+  it("leaves dark-only variables unpaired", () => {
+    // A `-dark` reference with no light base must stay unpaired rather than
+    // pointing at a variable that was never parsed.
+    const darkOnly = DesignSystem.parse("bg-[var(--zui-probe-only-dark,#000)]");
+    expect(darkOnly).toHaveLength(1);
+    expect(darkOnly[0]?.theme).toBe("dark");
+    expect(darkOnly[0]?.pairName).toBeUndefined();
+
+    const paired = DesignSystem.parse(
+      "a-[var(--zui-probe-bg,#fff)] b-[var(--zui-probe-bg-dark,#000)]",
+    );
+    const light = paired.find((token) => token.name === "--zui-probe-bg");
+    const dark = paired.find((token) => token.name === "--zui-probe-bg-dark");
+    expect(light?.theme).toBe("light");
+    expect(light?.pairName).toBe("--zui-probe-bg-dark");
+    expect(dark?.pairName).toBe("--zui-probe-bg");
+  });
+
+  it("returns undefined for unknown slugs and variants", () => {
+    expect(DesignSystem.getComponent("not-a-component")).toBeUndefined();
+    expect(
+      DesignSystem.getComponent("accordion")?.getVariant(
+        "appearance",
+        "not-a-variant",
+      ),
+    ).toBeUndefined();
+  });
+});