@zentauri-ui/zentauri-components 1.3.0 → 1.4.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);
+  });
+});

package/src/hooks/useNetworkStatus/useNetworkStatus.ts

@@ -0,0 +1,33 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/**
+ * Reflects browser online/offline connectivity using `navigator.onLine` and the `window` `"online"` / `"offline"` events.
+ *
+ * Defaults to `true` during SSR when `navigator` is undefined. Does not expose `connection` quality metrics—only reachability hints.
+ *
+ * @returns `true` when the browser believes the device is online, `false` when offline.
+ */
+export function useNetworkStatus(): boolean {
+  const [online, setOnline] = useState(() =>
+    typeof navigator === "undefined" ? true : navigator.onLine,
+  );
+
+  useEffect(() => {
+    const onOnline = () => {
+      setOnline(true);
+    };
+    const onOffline = () => {
+      setOnline(false);
+    };
+    window.addEventListener("online", onOnline);
+    window.addEventListener("offline", onOffline);
+    return () => {
+      window.removeEventListener("online", onOnline);
+      window.removeEventListener("offline", onOffline);
+    };
+  }, []);
+
+  return online;
+}

package/src/hooks/usePageVisibility/index.ts

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

package/src/hooks/usePageVisibility/usePageVisibility.test.ts

@@ -0,0 +1,21 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { usePageVisibility } from "./usePageVisibility";
+
+describe("usePageVisibility", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("should track document.visibilityState via visibilitychange", () => {
+    vi.spyOn(document, "visibilityState", "get").mockReturnValue("visible");
+    const { result } = renderHook(() => usePageVisibility());
+    expect(result.current).toBe("visible");
+    vi.spyOn(document, "visibilityState", "get").mockReturnValue("hidden");
+    act(() => {
+      document.dispatchEvent(new Event("visibilitychange"));
+    });
+    expect(result.current).toBe("hidden");
+  });
+});

package/src/hooks/usePageVisibility/usePageVisibility.ts

@@ -0,0 +1,31 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/**
+ * Tracks `document.visibilityState` (`"visible"`, `"hidden"`, or `"prerender"`) across tab visibility changes.
+ *
+ * Subscribes to `"visibilitychange"` so backgrounding a tab or switching windows updates state. SSR defaults to `"visible"`.
+ *
+ * @returns Current `DocumentVisibilityState` from the Page Visibility API.
+ */
+export function usePageVisibility(): DocumentVisibilityState {
+  const [state, setState] = useState<DocumentVisibilityState>(() =>
+    typeof document === "undefined" ? "visible" : document.visibilityState,
+  );
+
+  useEffect(() => {
+    if (typeof document === "undefined") {
+      return;
+    }
+    const onChange = () => {
+      setState(document.visibilityState);
+    };
+    document.addEventListener("visibilitychange", onChange);
+    return () => {
+      document.removeEventListener("visibilitychange", onChange);
+    };
+  }, []);
+
+  return state;
+}

package/src/hooks/usePagination/index.ts

@@ -0,0 +1,6 @@
+export {
+  buildPaginationItems,
+  usePagination,
+  type BuildPaginationItemsParams,
+  type PaginationPageItem,
+} from "./usePagination";

package/src/hooks/usePagination/usePagination.test.ts

@@ -0,0 +1,139 @@
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { buildPaginationItems, usePagination } from "./usePagination";
+
+describe("buildPaginationItems", () => {
+  it("should return empty list when pageCount is zero", () => {
+    expect(
+      buildPaginationItems({
+        pageCount: 0,
+        currentPage: 1,
+        siblingCount: 1,
+        boundaryCount: 1,
+      }),
+    ).toEqual([]);
+  });
+
+  it("should return full page range when within totalNumbers window", () => {
+    const items = buildPaginationItems({
+      pageCount: 5,
+      currentPage: 3,
+      siblingCount: 1,
+      boundaryCount: 1,
+    });
+    expect(items).toEqual([
+      { type: "page", value: 1 },
+      { type: "page", value: 2 },
+      { type: "page", value: 3 },
+      { type: "page", value: 4 },
+      { type: "page", value: 5 },
+    ]);
+  });
+
+  it("should insert ellipsis when range is fragmented", () => {
+    const items = buildPaginationItems({
+      pageCount: 10,
+      currentPage: 5,
+      siblingCount: 1,
+      boundaryCount: 1,
+    });
+    const ellipsisKeys = items
+      .filter((item) => item.type === "ellipsis")
+      .map((item) => item.key);
+    expect(ellipsisKeys.length).toBeGreaterThan(0);
+    const pages = items
+      .filter((item) => item.type === "page")
+      .map((item) => item.value);
+    expect(pages).toContain(1);
+    expect(pages).toContain(10);
+    expect(pages).toContain(5);
+  });
+
+  it("should clamp current page into range", () => {
+    const items = buildPaginationItems({
+      pageCount: 3,
+      currentPage: 99,
+      siblingCount: 0,
+      boundaryCount: 1,
+    });
+    expect(items.every((i) => i.type === "page")).toBe(true);
+    expect(items.some((i) => i.type === "page" && i.value === 3)).toBe(true);
+  });
+});
+
+describe("usePagination", () => {
+  it("should use internal state when uncontrolled", () => {
+    const { result } = renderHook(() =>
+      usePagination({ pageCount: 5, defaultPage: 2 }),
+    );
+    expect(result.current.currentPage).toBe(2);
+    expect(result.current.canGoPrev).toBe(true);
+    expect(result.current.canGoNext).toBe(true);
+    act(() => {
+      result.current.setPage(4);
+    });
+    expect(result.current.currentPage).toBe(4);
+  });
+
+  it("should clamp setPage into 1 and pageCount", () => {
+    const { result } = renderHook(() =>
+      usePagination({ pageCount: 3, defaultPage: 2 }),
+    );
+    act(() => {
+      result.current.setPage(0);
+    });
+    expect(result.current.currentPage).toBe(1);
+    act(() => {
+      result.current.setPage(100);
+    });
+    expect(result.current.currentPage).toBe(3);
+  });
+
+  it("should follow controlled page prop", () => {
+    const onPageChange = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ page }: { page: number }) =>
+        usePagination({ pageCount: 4, page, onPageChange }),
+      { initialProps: { page: 1 } },
+    );
+    expect(result.current.currentPage).toBe(1);
+    act(() => {
+      result.current.setPage(3);
+    });
+    expect(result.current.currentPage).toBe(1);
+    expect(onPageChange).toHaveBeenCalledWith(3);
+    rerender({ page: 3 });
+    expect(result.current.currentPage).toBe(3);
+  });
+
+  it("should not change page on goPrev when already first", () => {
+    const { result } = renderHook(() =>
+      usePagination({ pageCount: 3, defaultPage: 1 }),
+    );
+    act(() => {
+      result.current.goPrev();
+    });
+    expect(result.current.currentPage).toBe(1);
+    expect(result.current.canGoPrev).toBe(false);
+  });
+
+  it("should not change page on goNext when already last", () => {
+    const { result } = renderHook(() =>
+      usePagination({ pageCount: 3, defaultPage: 3 }),
+    );
+    act(() => {
+      result.current.goNext();
+    });
+    expect(result.current.currentPage).toBe(3);
+    expect(result.current.canGoNext).toBe(false);
+  });
+
+  it("should set canGoPrev and canGoNext false when pageCount is zero", () => {
+    const { result } = renderHook(() =>
+      usePagination({ pageCount: 0, defaultPage: 1 }),
+    );
+    expect(result.current.canGoPrev).toBe(false);
+    expect(result.current.canGoNext).toBe(false);
+  });
+});

package/src/hooks/usePagination/usePagination.ts

@@ -0,0 +1,153 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+
+import type {
+  PaginationPageItem,
+  UsePaginationParams,
+  UsePaginationResult,
+} from "../../ui/pagination/types";
+import { clampPage, range } from "../../lib/utils";
+
+export type { PaginationPageItem } from "../../ui/pagination/types";
+
+export type BuildPaginationItemsParams = {
+  pageCount: number;
+  currentPage: number;
+  siblingCount: number;
+  boundaryCount: number;
+};
+
+/**
+ * Headless pagination state: current page, derived page button items, and prev/next helpers.
+ *
+ * Supports controlled mode when `page` is passed from the parent, or internal state seeded by `defaultPage`.
+ * All page indices are **1-based** and clamped to `[1, pageCount]` via {@link clampPage}. `items` is memoized from
+ * {@link buildPaginationItems} for rendering numeric pages and ellipsis gaps.
+ *
+ * @param params - See `UsePaginationParams` in `../ui/pagination/types` for full fields (`pageCount`, `page`, `onPageChange`, etc.).
+ * @returns Current page, item list, `setPage`, navigation helpers, and `canGoPrev` / `canGoNext` flags.
+ */
+export function usePagination({
+  pageCount,
+  page,
+  defaultPage = 1,
+  siblingCount = 1,
+  boundaryCount = 1,
+  onPageChange,
+}: UsePaginationParams): UsePaginationResult {
+  const [internalPage, setInternalPage] = useState(() =>
+    clampPage(defaultPage, pageCount),
+  );
+
+  const isControlled = page !== undefined;
+  const currentPage = clampPage(isControlled ? page : internalPage, pageCount);
+
+  const setPage = useCallback(
+    (next: number) => {
+      const clamped = clampPage(next, pageCount);
+      if (!isControlled) {
+        setInternalPage(clamped);
+      }
+      onPageChange?.(clamped);
+    },
+    [isControlled, onPageChange, pageCount],
+  );
+
+  const items = useMemo(
+    () =>
+      buildPaginationItems({
+        pageCount,
+        currentPage,
+        siblingCount,
+        boundaryCount,
+      }),
+    [boundaryCount, currentPage, pageCount, siblingCount],
+  );
+
+  const canGoPrev = pageCount > 0 && currentPage > 1;
+  const canGoNext = pageCount > 0 && currentPage < pageCount;
+
+  const goPrev = useCallback(() => {
+    if (canGoPrev) {
+      setPage(currentPage - 1);
+    }
+  }, [canGoPrev, currentPage, setPage]);
+
+  const goNext = useCallback(() => {
+    if (canGoNext) {
+      setPage(currentPage + 1);
+    }
+  }, [canGoNext, currentPage, setPage]);
+
+  return {
+    currentPage,
+    pageCount,
+    items,
+    setPage,
+    goPrev,
+    goNext,
+    canGoPrev,
+    canGoNext,
+  };
+}
+
+/**
+ * Builds the ordered list of page numbers and ellipsis markers for a pagination control.
+ *
+ * @param params.pageCount - Total number of pages (must be >= 0; empty list when 0).
+ * @param params.currentPage - Active page index (1-based).
+ * @param params.siblingCount - How many page buttons to show on each side of the current page.
+ * @param params.boundaryCount - How many pages to pin at the start and end of the range.
+ * @returns Items suitable for rendering, e.g. page `1`, ellipsis gap, middle window, ellipsis, last page.
+ */
+export function buildPaginationItems({
+  pageCount,
+  currentPage,
+  siblingCount,
+  boundaryCount,
+}: BuildPaginationItemsParams): PaginationPageItem[] {
+  if (pageCount <= 0) {
+    return [];
+  }
+
+  const safeBoundary = Math.max(1, boundaryCount);
+  const safeSibling = Math.max(0, siblingCount);
+  const current = clampPage(currentPage, pageCount);
+
+  const totalNumbers = safeBoundary * 2 + safeSibling * 2 + 1;
+  if (pageCount <= totalNumbers) {
+    return range(1, pageCount).map((value) => ({ type: "page", value }));
+  }
+
+  const leftBoundaryEnd = safeBoundary;
+  const rightBoundaryStart = pageCount - safeBoundary + 1;
+
+  const siblingsStart = Math.max(current - safeSibling, leftBoundaryEnd + 1);
+  const siblingsEnd = Math.min(current + safeSibling, rightBoundaryStart - 1);
+
+  const pages = new Set<number>();
+  for (let p = 1; p <= leftBoundaryEnd; p += 1) {
+    pages.add(p);
+  }
+  for (let p = rightBoundaryStart; p <= pageCount; p += 1) {
+    pages.add(p);
+  }
+  for (let p = siblingsStart; p <= siblingsEnd; p += 1) {
+    pages.add(p);
+  }
+
+  const sorted = [...pages].sort((a, b) => a - b);
+  const items: PaginationPageItem[] = [];
+
+  for (let i = 0; i < sorted.length; i += 1) {
+    const value = sorted[i];
+    const prev = sorted[i - 1];
+    if (i > 0 && prev !== undefined && value && value - prev > 1) {
+      items.push({ type: "ellipsis", key: `gap-${prev}-${value}` });
+    }
+    items.push({ type: "page", value: value as number });
+  }
+
+  return items;
+}

package/src/hooks/usePrefersColorScheme/index.ts

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