@zentauri-ui/zentauri-components 1.3.1 → 1.4.0

package/src/hooks/useControllableState/useControllableState.test.ts

@@ -0,0 +1,59 @@
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { useControllableState } from "./useControllableState";
+
+describe("useControllableState", () => {
+  it("should use internal state when uncontrolled", () => {
+    const { result } = renderHook(() =>
+      useControllableState({ defaultValue: 1 }),
+    );
+    expect(result.current[0]).toBe(1);
+    act(() => {
+      result.current[1](2);
+    });
+    expect(result.current[0]).toBe(2);
+  });
+
+  it("should follow value prop when controlled", () => {
+    const onChange = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ value }: { value: number }) =>
+        useControllableState({ value, defaultValue: 0, onChange }),
+      { initialProps: { value: 5 } },
+    );
+    expect(result.current[0]).toBe(5);
+    act(() => {
+      result.current[1](9);
+    });
+    expect(result.current[0]).toBe(5);
+    expect(onChange).toHaveBeenCalledWith(9);
+    rerender({ value: 9 });
+    expect(result.current[0]).toBe(9);
+  });
+
+  it("should call onChange with functional updater using current controlled value", () => {
+    const onChange = vi.fn();
+    const { result } = renderHook(() =>
+      useControllableState({
+        value: 10,
+        defaultValue: 0,
+        onChange,
+      }),
+    );
+    act(() => {
+      result.current[1]((previous) => previous + 1);
+    });
+    expect(onChange).toHaveBeenCalledWith(11);
+  });
+
+  it("should apply functional updater in uncontrolled mode", () => {
+    const { result } = renderHook(() =>
+      useControllableState({ defaultValue: 3 }),
+    );
+    act(() => {
+      result.current[1]((previous) => previous * 2);
+    });
+    expect(result.current[0]).toBe(6);
+  });
+});

package/src/hooks/useControllableState/useControllableState.ts

@@ -0,0 +1,49 @@
+"use client";
+
+import { useCallback, useRef, useState } from "react";
+
+export type UseControllableStateParams<T> = {
+  /** When defined, the hook is controlled and this value is returned as state. */
+  value?: T;
+  /** Initial / fallback value when uncontrolled (`value` is `undefined`). */
+  defaultValue: T;
+  /** Notified on every `setValue` with the resolved next value (controlled and uncontrolled). */
+  onChange?: (next: T) => void;
+};
+
+/**
+ * Implements the React “controlled vs uncontrolled” pattern as a single state tuple.
+ *
+ * - If `value` is `undefined`, internal state mirrors `defaultValue` and updates on `setValue`.
+ * - If `value` is defined, returned state follows `value`; `setValue` still calls `onChange` so the parent can update.
+ * - `setValue` accepts either the next value or an updater `(prev) => next` (updater uses the current `value` in controlled mode).
+ *
+ * @typeParam T - State value type.
+ * @param params - `value`, `defaultValue`, and optional `onChange`.
+ * @returns `[value, setValue]` compatible with `useState`-style usage.
+ */
+export function useControllableState<T>({
+  value: valueProp,
+  defaultValue,
+  onChange,
+}: UseControllableStateParams<T>): [T, (next: T | ((prev: T) => T)) => void] {
+  const [uncontrolled, setUncontrolled] = useState(defaultValue);
+  const isControlled = valueProp !== undefined;
+  const value = isControlled ? valueProp : uncontrolled;
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+
+  const setValue = useCallback(
+    (next: T | ((prev: T) => T)) => {
+      const resolved =
+        typeof next === "function" ? (next as (prev: T) => T)(value) : next;
+      if (!isControlled) {
+        setUncontrolled(resolved);
+      }
+      onChangeRef.current?.(resolved);
+    },
+    [isControlled, value],
+  );
+
+  return [value, setValue];
+}

package/src/hooks/useDebouncedValue/index.ts

@@ -0,0 +1 @@
+export { useDebouncedValue } from "./useDebouncedValue";

package/src/hooks/useDebouncedValue/useDebouncedValue.test.ts

@@ -0,0 +1,74 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { useDebouncedValue } from "./useDebouncedValue";
+
+describe("useDebouncedValue", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("should return initial value immediately", () => {
+    const { result } = renderHook(() => useDebouncedValue("a", 300));
+    expect(result.current).toBe("a");
+  });
+
+  it("should update after delay when value stabilizes", () => {
+    const { result, rerender } = renderHook(
+      ({ value, delay }: { value: string; delay: number }) =>
+        useDebouncedValue(value, delay),
+      { initialProps: { value: "x", delay: 100 } },
+    );
+    rerender({ value: "y", delay: 100 });
+    expect(result.current).toBe("x");
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+    expect(result.current).toBe("y");
+  });
+
+  it("should reset timer when value changes rapidly", () => {
+    const { result, rerender } = renderHook(
+      ({ value }: { value: number }) => useDebouncedValue(value, 50),
+      { initialProps: { value: 0 } },
+    );
+    rerender({ value: 1 });
+    act(() => {
+      vi.advanceTimersByTime(40);
+    });
+    rerender({ value: 2 });
+    act(() => {
+      vi.advanceTimersByTime(40);
+    });
+    expect(result.current).toBe(0);
+    act(() => {
+      vi.advanceTimersByTime(20);
+    });
+    expect(result.current).toBe(2);
+  });
+
+  it("should reset debounce when delayMs changes", () => {
+    const { result, rerender } = renderHook(
+      ({ value, delay }: { value: string; delay: number }) =>
+        useDebouncedValue(value, delay),
+      { initialProps: { value: "a", delay: 200 } },
+    );
+    rerender({ value: "b", delay: 200 });
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+    rerender({ value: "b", delay: 500 });
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+    expect(result.current).toBe("a");
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+    expect(result.current).toBe("b");
+  });
+});

package/src/hooks/useDebouncedValue/useDebouncedValue.ts

@@ -0,0 +1,29 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/**
+ * Returns a lagged copy of `value` that only updates after `value` has been stable for `delayMs`.
+ * Each change to `value` or `delayMs` resets the timer; rapid updates collapse into one committed update.
+ *
+ * Common uses: search inputs, resize-driven layout, or any expensive work that should not run on every keystroke.
+ *
+ * @typeParam T - Value type (any JSON-serializable or referential type).
+ * @param value - Live value from props or state.
+ * @param delayMs - Debounce interval in milliseconds.
+ * @returns The last value that survived the full delay without a newer `value` arriving.
+ */
+export function useDebouncedValue<T>(value: T, delayMs: number): T {
+  const [debounced, setDebounced] = useState(value);
+
+  useEffect(() => {
+    const id = setTimeout(() => {
+      setDebounced(value);
+    }, delayMs);
+    return () => {
+      clearTimeout(id);
+    };
+  }, [delayMs, value]);
+
+  return debounced;
+}

package/src/hooks/useDisclosure/index.ts

@@ -0,0 +1,5 @@
+export {
+  useDisclosure,
+  type UseDisclosureParams,
+  type UseDisclosureResult,
+} from "./useDisclosure";

package/src/hooks/useDisclosure/useDisclosure.test.ts

@@ -0,0 +1,64 @@
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { useDisclosure } from "./useDisclosure";
+
+describe("useDisclosure", () => {
+  it("should start closed by default", () => {
+    const { result } = renderHook(() => useDisclosure());
+    expect(result.current.isOpen).toBe(false);
+  });
+
+  it("should respect defaultOpen when uncontrolled", () => {
+    const { result } = renderHook(() => useDisclosure({ defaultOpen: true }));
+    expect(result.current.isOpen).toBe(true);
+  });
+
+  it("should open close and toggle", () => {
+    const { result } = renderHook(() => useDisclosure({ defaultOpen: false }));
+    act(() => {
+      result.current.open();
+    });
+    expect(result.current.isOpen).toBe(true);
+    act(() => {
+      result.current.close();
+    });
+    expect(result.current.isOpen).toBe(false);
+    act(() => {
+      result.current.toggle();
+    });
+    expect(result.current.isOpen).toBe(true);
+    act(() => {
+      result.current.toggle();
+    });
+    expect(result.current.isOpen).toBe(false);
+  });
+
+  it("should call onOpenChange when state changes", () => {
+    const onOpenChange = vi.fn();
+    const { result } = renderHook(() =>
+      useDisclosure({ defaultOpen: false, onOpenChange }),
+    );
+    act(() => {
+      result.current.setOpen(true);
+    });
+    expect(onOpenChange).toHaveBeenLastCalledWith(true);
+  });
+
+  it("should be controlled when open prop is defined", () => {
+    const onOpenChange = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ open }: { open: boolean }) =>
+        useDisclosure({ open, onOpenChange }),
+      { initialProps: { open: false } },
+    );
+    expect(result.current.isOpen).toBe(false);
+    act(() => {
+      result.current.open();
+    });
+    expect(result.current.isOpen).toBe(false);
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+    rerender({ open: true });
+    expect(result.current.isOpen).toBe(true);
+  });
+});

package/src/hooks/useDisclosure/useDisclosure.ts

@@ -0,0 +1,62 @@
+"use client";
+
+import { useCallback } from "react";
+
+import { useControllableState } from "../useControllableState";
+
+export type UseDisclosureParams = {
+  /** Controlled open flag; omit for uncontrolled usage with `defaultOpen`. */
+  open?: boolean;
+  /** Initial open state when uncontrolled. */
+  defaultOpen?: boolean;
+  /** Fired whenever open state changes from user-driven `setOpen` / `open` / `close` / `toggle`. */
+  onOpenChange?: (open: boolean) => void;
+};
+
+export type UseDisclosureResult = {
+  isOpen: boolean;
+  open: () => void;
+  close: () => void;
+  toggle: () => void;
+  setOpen: (open: boolean) => void;
+};
+
+/**
+ * Boolean open/close state for overlays (dialogs, menus, collapsible regions) with optional control from the parent.
+ * Built on {@link useControllableState}; semantics match common headless UI libraries.
+ *
+ * @param params - Optional `open`, `defaultOpen`, and `onOpenChange`.
+ * @returns Helpers `open`, `close`, `toggle`, `setOpen`, and the current `isOpen` flag.
+ */
+export function useDisclosure({
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+}: UseDisclosureParams = {}): UseDisclosureResult {
+  const [isOpen, setOpenState] = useControllableState({
+    value: openProp,
+    defaultValue: defaultOpen,
+    onChange: onOpenChange,
+  });
+
+  const setOpen = useCallback(
+    (open: boolean) => {
+      setOpenState(open);
+    },
+    [setOpenState],
+  );
+
+  const open = useCallback(() => {
+    setOpenState(true);
+  }, [setOpenState]);
+
+  const close = useCallback(() => {
+    setOpenState(false);
+  }, [setOpenState]);
+
+  const toggle = useCallback(() => {
+    setOpenState(!isOpen);
+  }, [isOpen, setOpenState]);
+
+  return { isOpen, open, close, toggle, setOpen };
+}

package/src/hooks/useDocumentTitle/index.ts

@@ -0,0 +1,4 @@
+export {
+  useDocumentTitle,
+  type UseDocumentTitleParams,
+} from "./useDocumentTitle";

package/src/hooks/useDocumentTitle/useDocumentTitle.test.ts

@@ -0,0 +1,40 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { useDocumentTitle } from "./useDocumentTitle";
+
+describe("useDocumentTitle", () => {
+  it("should set document title from title prop", () => {
+    document.title = "Original";
+    const { unmount } = renderHook(() =>
+      useDocumentTitle({ title: "Page A" }),
+    );
+    expect(document.title).toBe("Page A");
+    unmount();
+    expect(document.title).toBe("Original");
+  });
+
+  it("should update title when title prop changes", () => {
+    document.title = "Start";
+    const { rerender, unmount } = renderHook(
+      ({ title }: { title: string }) => useDocumentTitle({ title }),
+      { initialProps: { title: "One" } },
+    );
+    expect(document.title).toBe("One");
+    rerender({ title: "Two" });
+    expect(document.title).toBe("Two");
+    unmount();
+    expect(document.title).toBe("Start");
+  });
+
+  it("should not restore when restoreOnUnmount is false", () => {
+    document.title = "KeepMe";
+    const { unmount } = renderHook(() =>
+      useDocumentTitle({ title: "Temp", restoreOnUnmount: false }),
+    );
+    expect(document.title).toBe("Temp");
+    unmount();
+    expect(document.title).toBe("Temp");
+    document.title = "KeepMe";
+  });
+});

package/src/hooks/useDocumentTitle/useDocumentTitle.ts

@@ -0,0 +1,58 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+
+export type UseDocumentTitleParams = {
+  title: string;
+  /** When true (default), restores the document title from before this hook mounted when the component unmounts */
+  restoreOnUnmount?: boolean;
+};
+
+/**
+ * Keeps `document.title` in sync with `title` for the lifetime of the component.
+ *
+ * On first mount in the browser, the current title is captured. When `title` changes, the document title updates.
+ * If `restoreOnUnmount` is true when the component unmounts, the captured title is restored so nested routes or
+ * modals do not leak titles. Changing `restoreOnUnmount` while mounted does not run restore; only unmount does.
+ *
+ * @param params.title - Desired `document.title` string.
+ * @param params.restoreOnUnmount - Whether to restore the pre-mount title on unmount (default `true`). The value
+ *   read at unmount time determines behavior, not mid-mount prop changes.
+ */
+export function useDocumentTitle({
+  title,
+  restoreOnUnmount = true,
+}: UseDocumentTitleParams): void {
+  const originalTitle = useRef<string | undefined>(undefined);
+  const restoreOnUnmountRef = useRef(restoreOnUnmount);
+  restoreOnUnmountRef.current = restoreOnUnmount;
+
+  useEffect(() => {
+    if (typeof document === "undefined") {
+      return;
+    }
+    if (originalTitle.current === undefined) {
+      originalTitle.current = document.title;
+    }
+  }, []);
+
+  useEffect(() => {
+    if (typeof document === "undefined") {
+      return;
+    }
+    document.title = title;
+  }, [title]);
+
+  useEffect(() => {
+    return () => {
+      if (
+        !restoreOnUnmountRef.current ||
+        typeof document === "undefined" ||
+        originalTitle.current === undefined
+      ) {
+        return;
+      }
+      document.title = originalTitle.current;
+    };
+  }, []);
+}

package/src/hooks/useFocusManagement/index.ts

@@ -0,0 +1 @@
+export { useFocusManagement } from "./useFocusManagement";

package/src/hooks/useFocusManagement/useFocusManagement.test.tsx

@@ -0,0 +1,45 @@
+import { createRef, useState } from "react";
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { useFocusManagement } from "./useFocusManagement";
+
+function Modal({ initialOpen }: { initialOpen: boolean }) {
+  const [open, setOpen] = useState(initialOpen);
+  const contentRef = createRef<HTMLDivElement>();
+  useFocusManagement({
+    open,
+    setOpen,
+    contentRef,
+  });
+  return (
+    <div>
+      <button type="button" data-testid="trigger">
+        trigger
+      </button>
+      {open ? (
+        <div ref={contentRef} tabIndex={-1} data-testid="dialog">
+          <button type="button">first</button>
+          <button type="button">second</button>
+        </div>
+      ) : null}
+      <button type="button" data-testid="after">
+        after
+      </button>
+    </div>
+  );
+}
+
+describe("useFocusManagement", () => {
+  it("should call setOpen false when Escape is pressed while open", () => {
+    render(<Modal initialOpen />);
+    fireEvent.keyDown(window, { key: "Escape" });
+    expect(screen.queryByTestId("dialog")).not.toBeInTheDocument();
+  });
+
+  it("should not react to Escape when closed", () => {
+    render(<Modal initialOpen={false} />);
+    fireEvent.keyDown(window, { key: "Escape" });
+    expect(screen.queryByTestId("dialog")).not.toBeInTheDocument();
+  });
+});

package/src/hooks/useFocusManagement/useFocusManagement.ts

@@ -0,0 +1,77 @@
+"use client";
+
+import type { RefObject } from "react";
+import { useEffect } from "react";
+import { useBodyScrollLock } from "../useBodyScrollLock";
+
+const FOCUSABLE_SELECTOR =
+  'a[href], button:not([disabled]), textarea, input, select, [tabindex]:not([tabindex="-1"])';
+
+/**
+ * Composes modal-like behavior for an open overlay: body scroll lock, Escape to close, and focus trapping.
+ *
+ * - Delegates scroll locking to {@link useBodyScrollLock} while `open` is true.
+ * - Listens for `Escape` on `window` and calls `setOpen(false)`.
+ * - When `open` becomes true, focuses the first visible focusable inside `contentRef`, or the container itself.
+ * - Traps focus within `contentRef` via a capturing `focusin` listener on `document` that redirects focus back inside.
+ * - On close/unmount of the open effect, restores focus to the element that was focused before the trap ran.
+ *
+ * @param params.open - Whether the overlay is visible.
+ * @param params.setOpen - Setter used for Escape and cleanup paths.
+ * @param params.contentRef - Root of the dialog/drawer content (must point at a focusable container or include focusables).
+ * @param params.focusableSelector - Query selector for tabbable elements; defaults to a common interactive set.
+ */
+export const useFocusManagement = ({
+  open,
+  setOpen,
+  contentRef,
+  focusableSelector = FOCUSABLE_SELECTOR,
+}: {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  contentRef: RefObject<HTMLDivElement | null>;
+  focusableSelector?: string;
+}) => {
+  useBodyScrollLock(open);
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        setOpen(false);
+      }
+    };
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [open, setOpen]);
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+    const node = contentRef.current;
+    if (!node) {
+      return;
+    }
+    const focusables = Array.from(
+      node.querySelectorAll<HTMLElement>(focusableSelector),
+    ).filter((element) => element.offsetParent !== null || element === node);
+    const target = focusables[0] ?? node;
+    const previouslyFocused = document.activeElement as HTMLElement | null;
+    target.focus();
+
+    const handleFocusIn = (event: FocusEvent) => {
+      if (!node.contains(event.target as Node)) {
+        event.stopPropagation();
+        target.focus();
+      }
+    };
+    document.addEventListener("focusin", handleFocusIn);
+    return () => {
+      document.removeEventListener("focusin", handleFocusIn);
+      previouslyFocused?.focus?.();
+    };
+  }, [contentRef, open]);
+};

package/src/hooks/useHover/index.ts

@@ -0,0 +1 @@
+export { useHover } from "./useHover";

package/src/hooks/useHover/useHover.test.ts

@@ -0,0 +1,45 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { useHover } from "./useHover";
+
+describe("useHover", () => {
+  afterEach(() => {
+    document.body.replaceChildren();
+  });
+
+  it("should report hovered true on pointerenter and false on pointerleave", () => {
+    const { result } = renderHook(() => useHover<HTMLDivElement>());
+    const node = document.createElement("div");
+    document.body.appendChild(node);
+    act(() => {
+      result.current[0](node);
+    });
+    expect(result.current[1]).toBe(false);
+    act(() => {
+      node.dispatchEvent(new Event("pointerenter", { bubbles: true }));
+    });
+    expect(result.current[1]).toBe(true);
+    act(() => {
+      node.dispatchEvent(new Event("pointerleave", { bubbles: true }));
+    });
+    expect(result.current[1]).toBe(false);
+  });
+
+  it("should clear hover when ref target is cleared", () => {
+    const { result } = renderHook(() => useHover<HTMLDivElement>());
+    const node = document.createElement("div");
+    document.body.appendChild(node);
+    act(() => {
+      result.current[0](node);
+    });
+    act(() => {
+      node.dispatchEvent(new Event("pointerenter", { bubbles: true }));
+    });
+    expect(result.current[1]).toBe(true);
+    act(() => {
+      result.current[0](null);
+    });
+    expect(result.current[1]).toBe(false);
+  });
+});

package/src/hooks/useHover/useHover.ts

@@ -0,0 +1,45 @@
+"use client";
+
+import type { RefCallback } from "react";
+import { useCallback, useEffect, useState } from "react";
+
+/**
+ * Tracks pointer hover state for a single DOM node using `pointerenter` / `pointerleave`.
+ *
+ * When the ref target changes (or unmounts), hover is cleared so state does not stay `true` after
+ * retargeting without a `pointerleave` on the previous node.
+ *
+ * @typeParam T - HTMLElement subtype for the ref callback (e.g. `HTMLDivElement`).
+ * @returns A tuple `[setRef, hovered]` where `setRef` is a callback ref to attach to the target element
+ *          and `hovered` is `true` while the pointer is over that element (primary button agnostic).
+ */
+export function useHover<T extends HTMLElement>(): [RefCallback<T>, boolean] {
+  const [element, setElement] = useState<T | null>(null);
+  const [hovered, setHovered] = useState(false);
+
+  const setRef = useCallback((node: T | null) => {
+    setElement(node);
+  }, []);
+
+  useEffect(() => {
+    if (element == null) {
+      setHovered(false);
+      return;
+    }
+    const onEnter = () => {
+      setHovered(true);
+    };
+    const onLeave = () => {
+      setHovered(false);
+    };
+    element.addEventListener("pointerenter", onEnter);
+    element.addEventListener("pointerleave", onLeave);
+    return () => {
+      setHovered(false);
+      element.removeEventListener("pointerenter", onEnter);
+      element.removeEventListener("pointerleave", onLeave);
+    };
+  }, [element]);
+
+  return [setRef, hovered];
+}

package/src/hooks/useInView/index.ts

@@ -0,0 +1 @@
+export { useInView, type UseInViewParams } from "./useInView";