@zentauri-ui/zentauri-components 1.3.1 → 1.4.0

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/src/hooks/useIsMounted/useIsMounted.ts

@@ -0,0 +1,22 @@
+"use client";
+
+import { useCallback, useEffect, useRef } from "react";
+
+/**
+ * Returns a stable function that reports whether the component is currently mounted.
+ *
+ * Useful to guard async completions (fetch, timers) so `setState` does not run after unmount.
+ * The returned function identity is stable across renders; it reads a ref updated in an effect.
+ *
+ * @returns `() => boolean` — `true` after mount until unmount cleanup runs.
+ */
+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/src/hooks/useIsomorphicLayoutEffect/useIsomorphicLayoutEffect.ts

@@ -0,0 +1,12 @@
+"use client";
+
+import { useEffect, useLayoutEffect } from "react";
+
+/**
+ * Runs `useLayoutEffect` in the browser and `useEffect` on the server to avoid SSR warnings.
+ *
+ * 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`.
+ */
+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 });
+  });
+});

package/src/hooks/useLocalStorage/useLocalStorage.ts

@@ -0,0 +1,109 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+
+function readValue<T>(key: string, fallback: T): T {
+  if (typeof window === "undefined") {
+    return fallback;
+  }
+  try {
+    const raw = window.localStorage.getItem(key);
+    if (raw == null) {
+      return fallback;
+    }
+    return JSON.parse(raw) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+export type UseLocalStorageResult<T> = [
+  T,
+  (value: T | ((previous: T) => T)) => void,
+  () => void,
+];
+
+/**
+ * Syncs JSON-serialized state with `window.localStorage` under a fixed key.
+ *
+ * - Initial read runs on the client; SSR uses `initialValue`.
+ * - `setValue` persists with `JSON.stringify` and updates React state; functional updates supported.
+ * - `remove` clears the key and resets state to `initialValue`.
+ * - Subscribes to the `storage` event so updates from other tabs (or same tab via `storage` dispatch quirks) reconcile.
+ * - Read/write failures (private mode, quota) fall back silently on read; write errors are swallowed except `remove` logs on failure.
+ *
+ * @typeParam T - Stored value type; must be compatible with `JSON.stringify` / `parse`.
+ * @param key - `localStorage` key.
+ * @param initialValue - Fallback when missing, invalid JSON, or during SSR.
+ * @returns `[stored, setValue, remove]` tuple mirroring `useState` plus explicit removal.
+ */
+export function useLocalStorage<T>(
+  key: string,
+  initialValue: T,
+): UseLocalStorageResult<T> {
+  const [stored, setStored] = useState<T>(() =>
+    readValue(key, initialValue),
+  );
+
+  const setValue = useCallback(
+    (value: T | ((previous: T) => T)) => {
+      setStored((previous) => {
+        const next =
+          typeof value === "function" ? (value as (p: T) => T)(previous) : value;
+        try {
+          if (typeof window !== "undefined") {
+            window.localStorage.setItem(key, JSON.stringify(next));
+          }
+        } catch {
+          /* quota or private mode */
+        }
+        return next;
+      });
+    },
+    [key],
+  );
+
+  const remove = useCallback(() => {
+    try {
+      if (typeof window !== "undefined") {
+        window.localStorage.removeItem(key);
+      }
+    } catch {
+      console.error(`Failed to remove item from localStorage: ${key}`);
+    }
+    setStored(initialValue);
+  }, [initialValue, key]);
+
+  useEffect(() => {
+    setStored((prev) => {
+      const next = readValue(key, initialValue);
+      return JSON.stringify(prev) === JSON.stringify(next) ? prev : next;
+    });
+  }, [key]);
+
+  useEffect(() => {
+    if (typeof window === "undefined") {
+      return;
+    }
+    const onStorage = (event: StorageEvent) => {
+      if (event.key !== key) {
+        return;
+      }
+      if (event.newValue == null) {
+        setStored(initialValue);
+        return;
+      }
+      try {
+        setStored(JSON.parse(event.newValue) as T);
+      } catch {
+        setStored(initialValue);
+      }
+    };
+    window.addEventListener("storage", onStorage);
+    return () => {
+      window.removeEventListener("storage", onStorage);
+    };
+  }, [initialValue, key]);
+
+  return [stored, setValue, remove];
+}

package/src/hooks/useMediaQuery/index.ts

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

package/src/hooks/useMediaQuery/useMediaQuery.test.ts

@@ -0,0 +1,63 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { useMediaQuery } from "./useMediaQuery";
+
+function createControllableMatchMedia(initialMatches: boolean) {
+  let matches = initialMatches;
+  const listeners = new Set<() => void>();
+  return {
+    setMatches(next: boolean) {
+      matches = next;
+      listeners.forEach((listener) => listener());
+    },
+    implementation: (query: string) => {
+      const mql = {
+        media: query,
+        get matches() {
+          return matches;
+        },
+        addEventListener: (_type: string, listener: () => void) => {
+          listeners.add(listener);
+        },
+        removeEventListener: (_type: string, listener: () => void) => {
+          listeners.delete(listener);
+        },
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+        dispatchEvent: vi.fn(),
+      };
+      return mql as unknown as MediaQueryList;
+    },
+  };
+}
+
+describe("useMediaQuery", () => {
+  afterEach(() => {
+    vi.spyOn(window, "matchMedia").mockRestore();
+  });
+
+  it("should reflect matchMedia matches and subscribe to change", () => {
+    const { setMatches, implementation } = createControllableMatchMedia(false);
+    const matchMediaSpy = vi
+      .spyOn(window, "matchMedia")
+      .mockImplementation(implementation);
+
+    const { result } = renderHook(() => useMediaQuery("(min-width: 1px)"));
+    expect(result.current).toBe(false);
+    act(() => {
+      setMatches(true);
+    });
+    expect(result.current).toBe(true);
+    expect(matchMediaSpy).toHaveBeenCalledWith("(min-width: 1px)");
+  });
+
+  it("should sync to media.matches after mount when defaultValue differs", () => {
+    const { implementation } = createControllableMatchMedia(false);
+    vi.spyOn(window, "matchMedia").mockImplementation(implementation);
+    const { result } = renderHook(() =>
+      useMediaQuery("(min-width: 99999px)", true),
+    );
+    expect(result.current).toBe(false);
+  });
+});

package/src/hooks/useMediaQuery/useMediaQuery.ts

@@ -0,0 +1,37 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/**
+ * Subscribes to `window.matchMedia(query)` and returns whether the query currently matches.
+ *
+ * On the server or when `matchMedia` is missing, `defaultValue` is used for the initial render and the effect no-ops.
+ * The `change` listener keeps `matches` updated when the viewport or user settings change.
+ *
+ * @param query - A valid media query string, e.g. `"(min-width: 768px)"`.
+ * @param defaultValue - Value to use before hydration or when `matchMedia` is unavailable (default `false`).
+ * @returns Current `matches` boolean for the query.
+ */
+export function useMediaQuery(
+  query: string,
+  defaultValue = false,
+): boolean {
+  const [matches, setMatches] = useState(defaultValue);
+
+  useEffect(() => {
+    if (typeof window === "undefined" || !window.matchMedia) {
+      return;
+    }
+    const media = window.matchMedia(query);
+    const onChange = () => {
+      setMatches(media.matches);
+    };
+    setMatches(media.matches);
+    media.addEventListener("change", onChange);
+    return () => {
+      media.removeEventListener("change", onChange);
+    };
+  }, [query]);
+
+  return matches;
+}

package/src/hooks/useNetworkStatus/index.ts

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

package/src/hooks/useNetworkStatus/useNetworkStatus.test.ts

@@ -0,0 +1,53 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { useNetworkStatus } from "./useNetworkStatus";
+
+describe("useNetworkStatus", () => {
+  const originalOnLine = navigator.onLine;
+
+  afterEach(() => {
+    Object.defineProperty(navigator, "onLine", {
+      configurable: true,
+      writable: true,
+      value: originalOnLine,
+    });
+  });
+
+  it("should reflect navigator.onLine initially", () => {
+    Object.defineProperty(navigator, "onLine", {
+      configurable: true,
+      writable: true,
+      value: true,
+    });
+    const { result } = renderHook(() => useNetworkStatus());
+    expect(result.current).toBe(true);
+  });
+
+  it("should update on offline and online window events", () => {
+    Object.defineProperty(navigator, "onLine", {
+      configurable: true,
+      writable: true,
+      value: true,
+    });
+    const { result } = renderHook(() => useNetworkStatus());
+    act(() => {
+      Object.defineProperty(navigator, "onLine", {
+        configurable: true,
+        writable: true,
+        value: false,
+      });
+      window.dispatchEvent(new Event("offline"));
+    });
+    expect(result.current).toBe(false);
+    act(() => {
+      Object.defineProperty(navigator, "onLine", {
+        configurable: true,
+        writable: true,
+        value: true,
+      });
+      window.dispatchEvent(new Event("online"));
+    });
+    expect(result.current).toBe(true);
+  });
+});