@zentauri-ui/zentauri-components 1.3.0 → 1.4.0

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";

package/src/hooks/useInView/useInView.test.ts

@@ -0,0 +1,43 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { useInView } from "./useInView";
+
+describe("useInView", () => {
+  const OriginalIO = globalThis.IntersectionObserver;
+  let lastCallback: IntersectionObserverCallback | undefined;
+
+  afterEach(() => {
+    globalThis.IntersectionObserver = OriginalIO;
+    lastCallback = undefined;
+  });
+
+  it("should derive inView from isIntersecting", () => {
+    class MockIntersectionObserver {
+      constructor(cb: IntersectionObserverCallback) {
+        lastCallback = cb;
+      }
+
+      observe = vi.fn();
+
+      disconnect = vi.fn();
+    }
+
+    globalThis.IntersectionObserver =
+      MockIntersectionObserver as unknown as typeof IntersectionObserver;
+
+    const { result } = renderHook(() => useInView());
+    const el = document.createElement("div");
+    act(() => {
+      result.current[0](el);
+    });
+    expect(result.current[1]).toBe(false);
+    act(() => {
+      lastCallback?.(
+        [{ isIntersecting: true, target: el } as unknown as IntersectionObserverEntry],
+        {} as IntersectionObserver,
+      );
+    });
+    expect(result.current[1]).toBe(true);
+  });
+});

package/src/hooks/useInView/useInView.ts

@@ -0,0 +1,28 @@
+"use client";
+
+import type { RefCallback } from "react";
+
+import { useIntersectionObserver } from "../useIntersectionObserver";
+
+export type UseInViewParams = IntersectionObserverInit & {
+  /** When `false`, no observer is attached (useful to pause work when off-screen lists are virtualized). */
+  enabled?: boolean;
+};
+
+/**
+ * Convenience wrapper around {@link useIntersectionObserver} that exposes only a boolean `inView` flag.
+ *
+ * `inView` is `true` when the latest `IntersectionObserverEntry.isIntersecting` is truthy; otherwise `false`.
+ * Accepts the same `root`, `rootMargin`, `threshold`, and `enabled` options as the underlying observer.
+ *
+ * @typeParam T - Observed element type.
+ * @param params - IntersectionObserver options plus optional `enabled` flag.
+ * @returns `[setRef, inView]` callback ref and intersection boolean.
+ */
+export function useInView<T extends Element>(
+  params: UseInViewParams = {},
+): [RefCallback<T>, boolean] {
+  const [setRef, entry] = useIntersectionObserver<T>(params);
+  const inView = Boolean(entry?.isIntersecting);
+  return [setRef, inView];
+}

package/src/hooks/useIntersectionObserver/index.ts

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

package/src/hooks/useIntersectionObserver/useIntersectionObserver.test.ts

@@ -0,0 +1,75 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { useIntersectionObserver } from "./useIntersectionObserver";
+
+describe("useIntersectionObserver", () => {
+  const OriginalIO = globalThis.IntersectionObserver;
+  let lastCallback: IntersectionObserverCallback | undefined;
+
+  afterEach(() => {
+    globalThis.IntersectionObserver = OriginalIO;
+    lastCallback = undefined;
+    vi.restoreAllMocks();
+  });
+
+  it("should observe element and expose latest entry from callback", () => {
+    const observeSpy = vi.fn();
+    class MockIntersectionObserver {
+      constructor(cb: IntersectionObserverCallback) {
+        lastCallback = cb;
+      }
+
+      observe = observeSpy;
+
+      disconnect = vi.fn();
+    }
+
+    globalThis.IntersectionObserver =
+      MockIntersectionObserver as unknown as typeof IntersectionObserver;
+
+    const { result } = renderHook(() => useIntersectionObserver());
+    const node = document.createElement("div");
+    act(() => {
+      result.current[0](node);
+    });
+    expect(observeSpy).toHaveBeenCalledWith(node);
+    const rect = node.getBoundingClientRect();
+    const fakeEntry: IntersectionObserverEntry = {
+      boundingClientRect: rect,
+      intersectionRect: rect,
+      intersectionRatio: 1,
+      isIntersecting: true,
+      rootBounds: null,
+      target: node,
+      time: 0,
+    };
+    act(() => {
+      lastCallback?.([fakeEntry], {} as IntersectionObserver);
+    });
+    expect(result.current[1]?.isIntersecting).toBe(true);
+  });
+
+  it("should not observe when enabled is false", () => {
+    const observeSpy = vi.fn();
+    class MockIntersectionObserver {
+      constructor(_cb: IntersectionObserverCallback) {}
+
+      observe = observeSpy;
+
+      disconnect = vi.fn();
+    }
+
+    globalThis.IntersectionObserver =
+      MockIntersectionObserver as unknown as typeof IntersectionObserver;
+
+    const { result } = renderHook(() =>
+      useIntersectionObserver({ enabled: false }),
+    );
+    const node = document.createElement("div");
+    act(() => {
+      result.current[0](node);
+    });
+    expect(observeSpy).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useIntersectionObserver/useIntersectionObserver.ts

@@ -0,0 +1,54 @@
+"use client";
+
+import type { RefCallback } from "react";
+import { useCallback, useEffect, useState } from "react";
+
+export type UseIntersectionObserverParams = IntersectionObserverInit & {
+  /** When `false`, disconnects the observer until re-enabled (saves work for hidden or inactive content). */
+  enabled?: boolean;
+};
+
+/**
+ * Observes a single element with the browser `IntersectionObserver` API and exposes the latest entry.
+ *
+ * Returns a callback ref: assign it to the element to measure. When `enabled` is false or `IntersectionObserver`
+ * is undefined (unsupported environment), the effect is a no-op and `entry` may stay `undefined`.
+ *
+ * @typeParam T - Observed element type.
+ * @param params - Standard `IntersectionObserverInit` fields plus optional `enabled` (default `true`).
+ * @returns `[setRef, entry]` where `entry` is the most recent callback record for the observed target.
+ */
+export function useIntersectionObserver<T extends Element>(
+  params: UseIntersectionObserverParams = {},
+): [RefCallback<T>, IntersectionObserverEntry | undefined] {
+  const { enabled = true, root, rootMargin, threshold } = params;
+  const [element, setElement] = useState<T | null>(null);
+  const [entry, setEntry] = useState<IntersectionObserverEntry | undefined>(
+    undefined,
+  );
+
+  const setRef = useCallback((node: T | null) => {
+    setElement(node);
+  }, []);
+
+  useEffect(() => {
+    if (!enabled || element == null) {
+      return;
+    }
+    if (typeof IntersectionObserver === "undefined") {
+      return;
+    }
+    const observer = new IntersectionObserver(
+      (records) => {
+        setEntry(records[0]);
+      },
+      { root, rootMargin, threshold },
+    );
+    observer.observe(element);
+    return () => {
+      observer.disconnect();
+    };
+  }, [element, enabled, root, rootMargin, threshold]);
+
+  return [setRef, entry];
+}

package/src/hooks/useIsMounted/index.ts

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

package/src/hooks/useIsMounted/useIsMounted.test.ts

@@ -0,0 +1,25 @@
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { useIsMounted } from "./useIsMounted";
+
+describe("useIsMounted", () => {
+  it("should return true after mount", () => {
+    const { result } = renderHook(() => useIsMounted());
+    expect(result.current()).toBe(true);
+  });
+
+  it("should return false after unmount", () => {
+    const { result, unmount } = renderHook(() => useIsMounted());
+    expect(result.current()).toBe(true);
+    unmount();
+    expect(result.current()).toBe(false);
+  });
+
+  it("should keep stable function identity", () => {
+    const { result, rerender } = renderHook(() => useIsMounted());
+    const first = result.current;
+    rerender();
+    expect(result.current).toBe(first);
+  });
+});

package/{dist/hooks/useIsMounted.d.mts → src/hooks/useIsMounted/useIsMounted.ts}

@@ -1,3 +1,7 @@
+"use client";
+
+import { useCallback, useEffect, useRef } from "react";
+
 /**
  * Returns a stable function that reports whether the component is currently mounted.
  *
@@ -6,6 +10,13 @@
  *
  * @returns `() => boolean` — `true` after mount until unmount cleanup runs.
  */
-declare function useIsMounted(): () => boolean;
-
-export { useIsMounted };
+export function useIsMounted(): () => boolean {
+  const mounted = useRef(false);
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+  return useCallback(() => mounted.current, []);
+}

package/src/hooks/useIsomorphicLayoutEffect/index.ts

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

package/src/hooks/useIsomorphicLayoutEffect/useIsomorphicLayoutEffect.test.ts

@@ -0,0 +1,19 @@
+import { useRef } from "react";
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect";
+
+describe("useIsomorphicLayoutEffect", () => {
+  it("should run effect in jsdom without throwing", () => {
+    const order: string[] = [];
+    renderHook(() => {
+      const ref = useRef(false);
+      useIsomorphicLayoutEffect(() => {
+        order.push("effect");
+        ref.current = true;
+      }, []);
+    });
+    expect(order).toEqual(["effect"]);
+  });
+});

package/{dist/hooks/useIsomorphicLayoutEffect.d.mts → src/hooks/useIsomorphicLayoutEffect/useIsomorphicLayoutEffect.ts}

@@ -1,4 +1,6 @@
-import { useLayoutEffect } from 'react';
+"use client";
+
+import { useEffect, useLayoutEffect } from "react";
 
 /**
  * Runs `useLayoutEffect` in the browser and `useEffect` on the server to avoid SSR warnings.
@@ -6,6 +8,5 @@ import { useLayoutEffect } from 'react';
  * Use for DOM measurements or synchronous paint updates that must run before the browser paints,
  * but only when the code path is safe on the client; on the server the timing matches `useEffect`.
  */
-declare const useIsomorphicLayoutEffect: typeof useLayoutEffect;
-
-export { useIsomorphicLayoutEffect };
+export const useIsomorphicLayoutEffect =
+  typeof window !== "undefined" ? useLayoutEffect : useEffect;

package/src/hooks/useLocalStorage/index.ts

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

package/src/hooks/useLocalStorage/useLocalStorage.test.ts

@@ -0,0 +1,99 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { useLocalStorage } from "./useLocalStorage";
+
+const keyPrefix = "zt-test-localstorage";
+
+describe("useLocalStorage", () => {
+  afterEach(() => {
+    localStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("should read existing JSON value on mount", () => {
+    const key = `${keyPrefix}-read`;
+    localStorage.setItem(key, JSON.stringify({ count: 2 }));
+    const { result } = renderHook(() =>
+      useLocalStorage(key, { count: 0 }),
+    );
+    const value = result.current[0];
+    expect(value).toEqual({ count: 2 });
+  });
+
+  it("should fall back to initialValue when key missing", () => {
+    const key = `${keyPrefix}-missing`;
+    const { result } = renderHook(() =>
+      useLocalStorage(key, { count: 0 }),
+    );
+    const value = result.current[0];
+    expect(value).toEqual({ count: 0 });
+  });
+
+  it("should persist setValue and support functional updates", () => {
+    const key = `${keyPrefix}-set`;
+    const { result } = renderHook(() =>
+      useLocalStorage(key, { count: 0 }),
+    );
+    act(() => {
+      result.current[1]({ count: 5 });
+    });
+    expect(result.current[0]).toEqual({ count: 5 });
+    expect(localStorage.getItem(key)).toBe(JSON.stringify({ count: 5 }));
+    act(() => {
+      result.current[1]((previous) => ({ count: previous.count + 1 }));
+    });
+    expect(result.current[0]).toEqual({ count: 6 });
+  });
+
+  it("should remove key and reset to initialValue", () => {
+    const key = `${keyPrefix}-remove`;
+    localStorage.setItem(key, JSON.stringify({ ok: true }));
+    const { result } = renderHook(() =>
+      useLocalStorage(key, { ok: false }),
+    );
+    const remove = result.current[2];
+    act(() => {
+      remove();
+    });
+    expect(localStorage.getItem(key)).toBeNull();
+    expect(result.current[0]).toEqual({ ok: false });
+  });
+
+  it("should reconcile when storage event fires for same key", () => {
+    const key = `${keyPrefix}-storage`;
+    const { result } = renderHook(() =>
+      useLocalStorage(key, { v: 0 }),
+    );
+    act(() => {
+      window.dispatchEvent(
+        new StorageEvent("storage", {
+          key,
+          newValue: JSON.stringify({ v: 99 }),
+          storageArea: window.localStorage,
+        }),
+      );
+    });
+    const value= result.current[0];
+    expect(value).toEqual({ v: 99 });
+  });
+
+  it("should reset to initial when storage event clears key", () => {
+    const key = `${keyPrefix}-cleared`;
+    localStorage.setItem(key, JSON.stringify({ v: 1 }));
+    const { result } = renderHook(() =>
+      useLocalStorage(key, { v: 0 }),
+    );
+    act(() => {
+      window.dispatchEvent(
+        new StorageEvent("storage", {
+          key,
+          newValue: null,
+          storageArea: window.localStorage,
+        }),
+      );
+    });
+    const value= result.current[0];
+    expect(value).toEqual({ v: 0 });
+  });
+});