@zentauri-ui/zentauri-components 1.3.1 → 1.4.1

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

@@ -1,2 +1 @@
 export { useNetworkStatus } from "./useNetworkStatus";
-//# sourceMappingURL=index.d.ts.map

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

@@ -1,2 +1 @@
 export { usePageVisibility } from "./usePageVisibility";
-//# sourceMappingURL=index.d.ts.map

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

@@ -1,9 +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 declare function usePrefersColorScheme(defaultScheme?: ColorSchemePreference): ColorSchemePreference;
-//# sourceMappingURL=usePrefersColorScheme.d.ts.map
+export function usePrefersColorScheme(
+  defaultScheme: ColorSchemePreference = "light",
+): ColorSchemePreference {
+  const prefersDark = useMediaQuery(
+    "(prefers-color-scheme: dark)",
+    defaultScheme === "dark",
+  );
+  return prefersDark ? "dark" : "light";
+}

package/{dist/hooks/usePrefersReducedMotion/index.d.ts → src/hooks/usePrefersReducedMotion/index.ts}

@@ -1,2 +1 @@
 export { usePrefersReducedMotion } from "./usePrefersReducedMotion";
-//# sourceMappingURL=index.d.ts.map

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

@@ -1,3 +1,7 @@
+"use client";
+
+import { useMediaQuery } from "../useMediaQuery";
+
 /**
  * Returns whether the user prefers reduced motion (`prefers-reduced-motion: reduce`).
  *
@@ -5,5 +9,6 @@
  *
  * @returns `true` when reduced motion is requested.
  */
-export declare function usePrefersReducedMotion(): boolean;
-//# sourceMappingURL=usePrefersReducedMotion.d.ts.map
+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";