@zentauri-ui/zentauri-components 1.3.0 → 1.4.0

package/src/hooks/useClipboard/useClipboard.test.ts

@@ -0,0 +1,101 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { useClipboard } from "./useClipboard";
+
+describe("useClipboard", () => {
+  const originalClipboard = navigator.clipboard;
+
+  beforeEach(() => {
+    Object.defineProperty(navigator, "clipboard", {
+      configurable: true,
+      writable: true,
+      value: { writeText: vi.fn().mockResolvedValue(undefined) },
+    });
+  });
+
+  afterEach(() => {
+    Object.defineProperty(navigator, "clipboard", {
+      configurable: true,
+      writable: true,
+      value: originalClipboard,
+    });
+    vi.useRealTimers();
+  });
+
+  it("should copy text and set copied true", async () => {
+    const { result } = renderHook(() => useClipboard(0));
+    await act(async () => {
+      const ok = await result.current.copy("hello");
+      expect(ok).toBe(true);
+    });
+    expect(result.current.copied).toBe(true);
+    expect(result.current.error).toBeUndefined();
+    expect(navigator.clipboard.writeText).toHaveBeenCalledWith("hello");
+  });
+
+  it("should clear copied after resetDelay with fake timers", async () => {
+    vi.useFakeTimers();
+    const { result } = renderHook(() => useClipboard(1000));
+    await act(async () => {
+      await result.current.copy("x");
+    });
+    expect(result.current.copied).toBe(true);
+    act(() => {
+      vi.advanceTimersByTime(1000);
+    });
+    expect(result.current.copied).toBe(false);
+  });
+
+  it("should keep copied true when resetDelay is 0", async () => {
+    const { result } = renderHook(() => useClipboard(0));
+    await act(async () => {
+      await result.current.copy("y");
+    });
+    expect(result.current.copied).toBe(true);
+  });
+
+  it("should set error when clipboard API is missing", async () => {
+    Object.defineProperty(navigator, "clipboard", {
+      configurable: true,
+      writable: true,
+      value: undefined,
+    });
+    const { result } = renderHook(() => useClipboard());
+    await act(async () => {
+      const ok = await result.current.copy("z");
+      expect(ok).toBe(false);
+    });
+    expect(result.current.error?.message).toBe("Clipboard API is not available");
+    expect(result.current.copied).toBe(false);
+  });
+
+  it("should set error when writeText rejects", async () => {
+    vi.mocked(navigator.clipboard.writeText).mockRejectedValueOnce(
+      new Error("denied"),
+    );
+    const { result } = renderHook(() => useClipboard());
+    await act(async () => {
+      const ok = await result.current.copy("a");
+      expect(ok).toBe(false);
+    });
+    expect(result.current.error?.message).toBe("denied");
+  });
+
+  it("should reset copied error and pending timeout", async () => {
+    vi.useFakeTimers();
+    const { result } = renderHook(() => useClipboard(5000));
+    await act(async () => {
+      await result.current.copy("b");
+    });
+    act(() => {
+      result.current.reset();
+    });
+    expect(result.current.copied).toBe(false);
+    expect(result.current.error).toBeUndefined();
+    act(() => {
+      vi.advanceTimersByTime(5000);
+    });
+    expect(result.current.copied).toBe(false);
+  });
+});

package/src/hooks/useClipboard/useClipboard.ts

@@ -0,0 +1,69 @@
+"use client";
+
+import { useCallback, useRef, useState } from "react";
+
+export type UseClipboardResult = {
+  /** `true` after a successful `copy` until the reset delay elapses or `reset` is called. */
+  copied: boolean;
+  /** Set when the Clipboard API is missing or `writeText` rejects (e.g. permission denied). */
+  error: Error | undefined;
+  /** Writes `text` via `navigator.clipboard.writeText`; returns whether the write succeeded. */
+  copy: (text: string) => Promise<boolean>;
+  /** Clears `copied`/`error` and cancels any pending auto-reset timeout. */
+  reset: () => void;
+};
+
+/**
+ * Wraps the async Clipboard API with React state for UX feedback (“Copied!”) and error surfacing.
+ *
+ * After a successful copy, `copied` flips to `true` for `resetDelay` ms (or stays true if `resetDelay` is 0).
+ * SSR-safe: `copy` resolves `false` with an error when `navigator.clipboard` is unavailable.
+ *
+ * @param resetDelay - Milliseconds before `copied` auto-clears after success; `0` disables auto-clear.
+ * @returns `{ copied, error, copy, reset }` for rendering and handlers.
+ */
+export function useClipboard(resetDelay = 2000): UseClipboardResult {
+  const [copied, setCopied] = useState(false);
+  const [error, setError] = useState<Error | undefined>(undefined);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | undefined>(
+    undefined,
+  );
+
+  const reset = useCallback(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = undefined;
+    }
+    setCopied(false);
+    setError(undefined);
+  }, []);
+
+  const copy = useCallback(
+    async (text: string) => {
+      reset();
+      if (typeof navigator === "undefined" || !navigator.clipboard?.writeText) {
+        const err = new Error("Clipboard API is not available");
+        setError(err);
+        return false;
+      }
+      try {
+        await navigator.clipboard.writeText(text);
+        setCopied(true);
+        if (resetDelay > 0) {
+          timeoutRef.current = setTimeout(() => {
+            setCopied(false);
+          }, resetDelay);
+        }
+        return true;
+      } catch (cause) {
+        const err =
+          cause instanceof Error ? cause : new Error(String(cause));
+        setError(err);
+        return false;
+      }
+    },
+    [reset, resetDelay],
+  );
+
+  return { copied, error, copy, reset };
+}

package/src/hooks/useControllableState/index.ts

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

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/{dist/hooks/useDebouncedValue.d.mts → src/hooks/useDebouncedValue/useDebouncedValue.ts}

@@ -1,3 +1,7 @@
+"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.
@@ -9,6 +13,17 @@
  * @param delayMs - Debounce interval in milliseconds.
  * @returns The last value that survived the full delay without a newer `value` arriving.
  */
-declare function useDebouncedValue<T>(value: T, delayMs: number): T;
+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]);
 
-export { useDebouncedValue };
+  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();
+  });
+});