@zentauri-ui/zentauri-components 1.9.2 → 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

@@ -84,9 +84,9 @@ 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,
-    );
+    expect(
+      searchVars.every((token) => token.name.startsWith("--zui-input")),
+    ).toBe(true);
     expect(searchVars.length).toBe(input?.variables().length);
   });
 
@@ -100,7 +100,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 +155,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;
   });
 }