@zentauri-ui/zentauri-components 1.3.1 → 1.4.0

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

package/src/hooks/usePrefersColorScheme/usePrefersColorScheme.test.ts

@@ -0,0 +1,53 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { usePrefersColorScheme } from "./usePrefersColorScheme";
+
+function createDarkPreferenceMatchMedia(initialDark: boolean) {
+  let dark = initialDark;
+  const listeners = new Set<() => void>();
+  return {
+    setDark(next: boolean) {
+      dark = next;
+      listeners.forEach((listener) => listener());
+    },
+    implementation: (query: string) => {
+      const mql = {
+        media: query,
+        get matches() {
+          return query === "(prefers-color-scheme: dark)" && dark;
+        },
+        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("usePrefersColorScheme", () => {
+  afterEach(() => {
+    vi.spyOn(window, "matchMedia").mockRestore();
+  });
+
+  it("should map dark media query to dark scheme", () => {
+    const { setDark, implementation } = createDarkPreferenceMatchMedia(false);
+    const matchMediaSpy = vi
+      .spyOn(window, "matchMedia")
+      .mockImplementation(implementation);
+    const { result } = renderHook(() => usePrefersColorScheme("light"));
+    expect(matchMediaSpy).toHaveBeenCalledWith("(prefers-color-scheme: dark)");
+    expect(result.current).toBe("light");
+    act(() => {
+      setDark(true);
+    });
+    expect(result.current).toBe("dark");
+  });
+});

package/src/hooks/usePrefersColorScheme/usePrefersColorScheme.ts

@@ -0,0 +1,21 @@
+"use client";
+
+import { useMediaQuery } from "../useMediaQuery";
+
+export type ColorSchemePreference = "light" | "dark";
+
+/**
+ * Resolves the user’s preferred color scheme from `prefers-color-scheme: dark` via {@link useMediaQuery}.
+ *
+ * @param defaultScheme - Hydration / SSR fallback when media queries are unavailable (`"light"` or `"dark"`).
+ * @returns `"dark"` when the dark media query matches, otherwise `"light"`.
+ */
+export function usePrefersColorScheme(
+  defaultScheme: ColorSchemePreference = "light",
+): ColorSchemePreference {
+  const prefersDark = useMediaQuery(
+    "(prefers-color-scheme: dark)",
+    defaultScheme === "dark",
+  );
+  return prefersDark ? "dark" : "light";
+}

package/src/hooks/usePrefersReducedMotion/index.ts

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

package/src/hooks/usePrefersReducedMotion/usePrefersReducedMotion.test.ts

@@ -0,0 +1,27 @@
+import { renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { usePrefersReducedMotion } from "./usePrefersReducedMotion";
+
+describe("usePrefersReducedMotion", () => {
+  afterEach(() => {
+    vi.spyOn(window, "matchMedia").mockRestore();
+  });
+
+  it("should subscribe to prefers-reduced-motion reduce query", () => {
+    const matchMediaSpy = vi.spyOn(window, "matchMedia").mockImplementation(
+      () =>
+        ({
+          matches: true,
+          addEventListener: vi.fn(),
+          removeEventListener: vi.fn(),
+          addListener: vi.fn(),
+          removeListener: vi.fn(),
+          dispatchEvent: vi.fn(),
+        }) as unknown as MediaQueryList,
+    );
+    const { result } = renderHook(() => usePrefersReducedMotion());
+    expect(matchMediaSpy).toHaveBeenCalledWith("(prefers-reduced-motion: reduce)");
+    expect(result.current).toBe(true);
+  });
+});

package/src/hooks/usePrefersReducedMotion/usePrefersReducedMotion.ts

@@ -0,0 +1,14 @@
+"use client";
+
+import { useMediaQuery } from "../useMediaQuery";
+
+/**
+ * Returns whether the user prefers reduced motion (`prefers-reduced-motion: reduce`).
+ *
+ * Use to disable non-essential animations or switch to instant transitions for accessibility.
+ *
+ * @returns `true` when reduced motion is requested.
+ */
+export function usePrefersReducedMotion(): boolean {
+  return useMediaQuery("(prefers-reduced-motion: reduce)");
+}

package/src/hooks/useResizeObserver/index.ts

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

package/src/hooks/useResizeObserver/useResizeObserver.test.ts

@@ -0,0 +1,68 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { useResizeObserver } from "./useResizeObserver";
+
+describe("useResizeObserver", () => {
+  const OriginalRO = globalThis.ResizeObserver;
+  let lastCallback: ResizeObserverCallback | undefined;
+
+  afterEach(() => {
+    globalThis.ResizeObserver = OriginalRO;
+    lastCallback = undefined;
+  });
+
+  it("should observe and set size from contentRect", () => {
+    const observeSpy = vi.fn();
+    class MockResizeObserver {
+      constructor(cb: ResizeObserverCallback) {
+        lastCallback = cb;
+      }
+
+      observe = observeSpy;
+
+      disconnect = vi.fn();
+    }
+
+    globalThis.ResizeObserver =
+      MockResizeObserver as unknown as typeof ResizeObserver;
+
+    const { result } = renderHook(() => useResizeObserver());
+    const node = document.createElement("div");
+    act(() => {
+      result.current[0](node);
+    });
+    expect(observeSpy).toHaveBeenCalledWith(node);
+    act(() => {
+      lastCallback?.(
+        [
+          {
+            contentRect: { width: 120, height: 80 },
+          } as ResizeObserverEntry,
+        ],
+        {} as ResizeObserver,
+      );
+    });
+    expect(result.current[1]).toEqual({ width: 120, height: 80 });
+  });
+
+  it("should not attach when enabled is false", () => {
+    const observeSpy = vi.fn();
+    class MockResizeObserver {
+      constructor(_cb: ResizeObserverCallback) {}
+
+      observe = observeSpy;
+
+      disconnect = vi.fn();
+    }
+
+    globalThis.ResizeObserver =
+      MockResizeObserver as unknown as typeof ResizeObserver;
+
+    const { result } = renderHook(() => useResizeObserver({ enabled: false }));
+    act(() => {
+      result.current[0](document.createElement("div"));
+    });
+    expect(observeSpy).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useResizeObserver/useResizeObserver.ts

@@ -0,0 +1,58 @@
+"use client";
+
+import type { RefCallback } from "react";
+import { useCallback, useEffect, useState } from "react";
+
+export type ElementSize = {
+  width: number;
+  height: number;
+};
+
+export type UseResizeObserverParams = {
+  /** When `false`, no `ResizeObserver` is attached. */
+  enabled?: boolean;
+};
+
+/**
+ * Observes an element’s `contentRect` size via `ResizeObserver` and exposes `{ width, height }`.
+ *
+ * When `ResizeObserver` is undefined or `enabled` is false, size may remain `undefined`. Uses the first
+ * entry from the observer callback (`entries[0]`) aligned with the single observed node.
+ *
+ * @typeParam T - Observed element type.
+ * @param params - Optional `{ enabled }` (default `true`).
+ * @returns `[setRef, size]` callback ref and latest measured size.
+ */
+export function useResizeObserver<T extends Element>(
+  params: UseResizeObserverParams = {},
+): [RefCallback<T>, ElementSize | undefined] {
+  const { enabled = true } = params;
+  const [element, setElement] = useState<T | null>(null);
+  const [size, setSize] = useState<ElementSize | undefined>(undefined);
+
+  const setRef = useCallback((node: T | null) => {
+    setElement(node);
+  }, []);
+
+  useEffect(() => {
+    if (!enabled || element == null) {
+      return;
+    }
+    if (typeof ResizeObserver === "undefined") {
+      return;
+    }
+    const observer = new ResizeObserver((entries) => {
+      const { width, height } = entries[0]?.contentRect ?? {
+        width: 0,
+        height: 0,
+      };
+      setSize({ width, height });
+    });
+    observer.observe(element);
+    return () => {
+      observer.disconnect();
+    };
+  }, [element, enabled]);
+
+  return [setRef, size];
+}

package/src/hooks/useSessionStorage/index.ts

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