@zentauri-ui/zentauri-components 1.9.2 → 2.1.0

package/src/hooks/useScrollPosition/useScrollPosition.ts

@@ -0,0 +1,88 @@
+"use client";
+
+import type { RefCallback, RefObject } from "react";
+import { useCallback, useEffect, useState } from "react";
+
+export type ScrollPosition = {
+  x: number;
+  y: number;
+};
+
+export type UseScrollPositionParams<T extends HTMLElement = HTMLElement> = {
+  /**
+   * Scroll container to observe via a pre-populated RefObject.
+   * For elements that mount asynchronously, use the returned `setRef` callback ref instead.
+   */
+  target?: RefObject<T | null>;
+};
+
+export type UseScrollPositionResult<T extends HTMLElement = HTMLElement> =
+  ScrollPosition & {
+    /**
+     * Callback ref to attach to a scroll container — works correctly with elements
+     * that are null on initial render (lazy / conditional mounts). Pass this as `ref`
+     * on the scrollable element when you cannot guarantee the ref is populated at mount.
+     */
+    setRef: RefCallback<T>;
+  };
+
+/**
+ * Tracks the scroll offset of the window (default) or a scrollable element.
+ *
+ * - Window mode reads `scrollX` / `scrollY`; element mode reads `scrollLeft` / `scrollTop`.
+ * - Subscribes with a passive `scroll` listener and reads the initial position on mount.
+ * - Pass a pre-populated `target` RefObject **or** use the returned `setRef` callback ref on
+ *   the scrollable element. Prefer `setRef` for elements that may be null on the first render
+ *   (conditional mounts, portals) — it stores the element in state so the effect re-attaches
+ *   correctly when the element becomes available.
+ * - For high-frequency consumers, derive throttled values downstream (e.g. with
+ *   `useThrottledCallback`) rather than throttling the source of truth.
+ *
+ * @param params - {@link UseScrollPositionParams}
+ * @returns Latest `{ x, y }` scroll offset in pixels plus a `setRef` callback ref.
+ */
+export function useScrollPosition<T extends HTMLElement = HTMLElement>(
+  params: UseScrollPositionParams<T> = {},
+): UseScrollPositionResult<T> {
+  const { target } = params;
+
+  // Track the element in state so the scroll listener effect reruns when the element
+  // is assigned (handles callback-ref / lazy-mount patterns).
+  const [element, setElement] = useState<T | null>(
+    () => target?.current ?? null,
+  );
+  const [position, setPosition] = useState<ScrollPosition>({ x: 0, y: 0 });
+
+  // Sync element state when the target RefObject changes (pre-populated refs).
+  useEffect(() => {
+    if (target?.current != null) {
+      setElement(target.current);
+    }
+  }, [target]);
+
+  const setRef = useCallback((node: T | null) => {
+    setElement(node);
+  }, []);
+
+  useEffect(() => {
+    const node: Window | T | null =
+      element ?? (typeof window === "undefined" ? null : window);
+    if (node == null) {
+      return;
+    }
+    const read = (): ScrollPosition =>
+      element == null
+        ? { x: window.scrollX, y: window.scrollY }
+        : { x: element.scrollLeft, y: element.scrollTop };
+    const onScroll = () => {
+      setPosition(read());
+    };
+    onScroll();
+    node.addEventListener("scroll", onScroll, { passive: true });
+    return () => {
+      node.removeEventListener("scroll", onScroll);
+    };
+  }, [element]);
+
+  return { x: position.x, y: position.y, setRef };
+}

package/src/hooks/useTimeout/index.ts

@@ -0,0 +1 @@
+export { useTimeout, type UseTimeoutResult } from "./useTimeout";

package/src/hooks/useTimeout/useTimeout.test.ts

@@ -0,0 +1,63 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { useTimeout } from "./useTimeout";
+
+describe("useTimeout", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("should fire once after the delay", () => {
+    const callback = vi.fn();
+    renderHook(() => useTimeout(callback, 200));
+    vi.advanceTimersByTime(199);
+    expect(callback).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(1);
+    expect(callback).toHaveBeenCalledTimes(1);
+    vi.advanceTimersByTime(1000);
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it("should not schedule when delay is null", () => {
+    const callback = vi.fn();
+    renderHook(() => useTimeout(callback, null));
+    vi.advanceTimersByTime(1000);
+    expect(callback).not.toHaveBeenCalled();
+  });
+
+  it("should cancel via clear", () => {
+    const callback = vi.fn();
+    const { result } = renderHook(() => useTimeout(callback, 200));
+    act(() => {
+      result.current.clear();
+    });
+    vi.advanceTimersByTime(500);
+    expect(callback).not.toHaveBeenCalled();
+  });
+
+  it("should restart the delay via reset", () => {
+    const callback = vi.fn();
+    const { result } = renderHook(() => useTimeout(callback, 200));
+    vi.advanceTimersByTime(150);
+    act(() => {
+      result.current.reset();
+    });
+    vi.advanceTimersByTime(150);
+    expect(callback).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(50);
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it("should cancel the pending timeout on unmount", () => {
+    const callback = vi.fn();
+    const { unmount } = renderHook(() => useTimeout(callback, 200));
+    unmount();
+    vi.advanceTimersByTime(500);
+    expect(callback).not.toHaveBeenCalled();
+  });
+});

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,141 @@
+"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

@@ -1,6 +1,12 @@
 import { describe, expect, it } from "vitest";
 
 import { DesignSystem } from "../lib/facade";
+import { zuiGlobalThemeTokens } from "../design-system/tokens";
+
+const globalTokenNames = new Set([
+  ...Object.values(zuiGlobalThemeTokens),
+  ...Object.values(zuiGlobalThemeTokens).map((name) => `${name}-dark`),
+]);
 
 describe("DesignSystem facade", () => {
   it("lists known components", () => {
@@ -65,13 +71,23 @@ describe("DesignSystem facade", () => {
   it("scopes variables to the component token prefix", () => {
     const buttonVars = DesignSystem.getComponent("buttons")?.variables() ?? [];
     expect(buttonVars.length).toBeGreaterThan(0);
+    const componentSpecificButtonVars = buttonVars.filter(
+      (token) => !globalTokenNames.has(token.name),
+    );
     expect(
-      buttonVars.every((token) => token.name.startsWith("--zui-button")),
+      componentSpecificButtonVars.every((token) =>
+        token.name.startsWith("--zui-button"),
+      ),
     ).toBe(true);
 
     const inputVars = DesignSystem.getComponent("inputs")?.variables() ?? [];
+    const componentSpecificInputVars = inputVars.filter(
+      (token) => !globalTokenNames.has(token.name),
+    );
     expect(
-      inputVars.every((token) => token.name.startsWith("--zui-input")),
+      componentSpecificInputVars.every((token) =>
+        token.name.startsWith("--zui-input"),
+      ),
     ).toBe(true);
   });
 
@@ -84,9 +100,14 @@ describe("DesignSystem facade", () => {
     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,
+    const componentSpecificSearchVars = searchVars.filter(
+      (token) => !globalTokenNames.has(token.name),
     );
+    expect(
+      componentSpecificSearchVars.every((token) =>
+        token.name.startsWith("--zui-input"),
+      ),
+    ).toBe(true);
     expect(searchVars.length).toBe(input?.variables().length);
   });
 
@@ -100,7 +121,9 @@ describe("DesignSystem facade", () => {
     const contextMenuNames = (contextMenu?.variables() ?? []).map(
       (token) => token.name,
     );
-    const dropdownNames = (dropdown?.variables() ?? []).map((token) => token.name);
+    const dropdownNames = (dropdown?.variables() ?? []).map(
+      (token) => token.name,
+    );
 
     expect(contextMenuNames.length).toBeGreaterThan(0);
     expect(
@@ -153,9 +176,7 @@ describe("DesignSystem facade", () => {
   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)]",
-    );
+    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();

package/src/lib/facade.ts

@@ -439,8 +439,12 @@ function classifyVariables(raw: RawVariable[]): ZuiVariable[] {
       fallback,
       theme: isDark ? "dark" : hasDarkPair ? "light" : "shared",
       pairName: isDark
-        ? (names.has(baseName) ? baseName : undefined)
-        : (hasDarkPair ? darkName : undefined),
+        ? names.has(baseName)
+          ? baseName
+          : undefined
+        : hasDarkPair
+          ? darkName
+          : undefined,
     } satisfies ZuiVariable;
   });
 }