@zentauri-ui/zentauri-components 1.3.0 → 1.4.0

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/{dist/hooks/usePrefersReducedMotion.d.mts → 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,6 +9,6 @@
  *
  * @returns `true` when reduced motion is requested.
  */
-declare function usePrefersReducedMotion(): boolean;
-
-export { usePrefersReducedMotion };
+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";

package/src/hooks/useSessionStorage/useSessionStorage.test.ts

@@ -0,0 +1,54 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { useSessionStorage } from "./useSessionStorage";
+
+const keyPrefix = "zt-test-sessionstorage";
+
+async function flushEffects() {
+  await act(async () => {
+    await Promise.resolve();
+  });
+}
+
+describe("useSessionStorage", () => {
+  afterEach(() => {
+    sessionStorage.clear();
+  });
+
+  it("should apply stored value from sessionStorage after mount", async () => {
+    const key = `${keyPrefix}-hydrate`;
+    sessionStorage.setItem(key, JSON.stringify("stored"));
+    const { result } = renderHook(() =>
+      useSessionStorage(key, "initial"),
+    );
+    await flushEffects();
+    expect(result.current[0]).toBe("stored");
+  });
+
+  it("should persist setValue to sessionStorage", async () => {
+    const key = `${keyPrefix}-persist`;
+    const { result } = renderHook(() =>
+      useSessionStorage(key, { n: 0 }),
+    );
+    await flushEffects();
+    act(() => {
+      result.current[1]({ n: 3 });
+    });
+    expect(sessionStorage.getItem(key)).toBe(JSON.stringify({ n: 3 }));
+    expect(result.current[0]).toEqual({ n: 3 });
+  });
+
+  it("should remove and reset to initialValue", async () => {
+    const key = `${keyPrefix}-remove`;
+    sessionStorage.setItem(key, JSON.stringify(42));
+    const { result } = renderHook(() => useSessionStorage(key, 0));
+    await flushEffects();
+    expect(result.current[0]).toBe(42);
+    act(() => {
+      result.current[2]();
+    });
+    expect(sessionStorage.getItem(key)).toBeNull();
+    expect(result.current[0]).toBe(0);
+  });
+});

package/src/hooks/useSessionStorage/useSessionStorage.ts

@@ -0,0 +1,84 @@
+"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.sessionStorage.getItem(key);
+    if (raw == null) {
+      return fallback;
+    }
+    return JSON.parse(raw) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+export type UseSessionStorageResult<T> = [
+  T,
+  (value: T | ((previous: T) => T)) => void,
+  () => void,
+];
+
+/**
+ * Syncs JSON-serialized state with `window.sessionStorage` for the lifetime of the browser tab.
+ *
+ * Same persistence semantics as {@link useLocalStorage} but scoped to the session: data clears when the tab closes.
+ * Unlike `useLocalStorage`, this hook does **not** subscribe to `storage` events (session storage is not shared across tabs).
+ *
+ * State is initialized from `initialValue` only so the first client render can match SSR output; the stored value is
+ * applied after mount in an effect to avoid hydration mismatches.
+ *
+ * @typeParam T - Stored value type; must round-trip through `JSON.stringify` / `parse`.
+ * @param key - `sessionStorage` key.
+ * @param initialValue - Fallback when missing, invalid JSON, or during SSR; also used for the first render before hydrate.
+ * @returns `[stored, setValue, remove]` tuple.
+ */
+export function useSessionStorage<T>(
+  key: string,
+  initialValue: T,
+): UseSessionStorageResult<T> {
+  const [stored, setStored] = useState<T>(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.sessionStorage.setItem(key, JSON.stringify(next));
+          }
+        } catch {
+          /* quota or private mode */
+        }
+        return next;
+      });
+    },
+    [key],
+  );
+
+  const remove = useCallback(() => {
+    try {
+      if (typeof window !== "undefined") {
+        window.sessionStorage.removeItem(key);
+      }
+    } catch {
+      /* ignore */
+    }
+    setStored(initialValue);
+  }, [initialValue, key]);
+
+  useEffect(() => {
+    const next = readValue(key, initialValue);
+  
+    setStored((prev) => {
+      return JSON.stringify(prev) === JSON.stringify(next) ? prev : next;
+    });
+  }, [key]);
+
+  return [stored, setValue, remove];
+}

package/src/hooks/useThrottledCallback/index.ts

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

package/src/hooks/useThrottledCallback/useThrottledCallback.test.ts

@@ -0,0 +1,75 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { useThrottledCallback } from "./useThrottledCallback";
+
+describe("useThrottledCallback", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(1_000_000);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("should invoke callback immediately when outside cooldown", () => {
+    const callback = vi.fn();
+    const { result } = renderHook(() => useThrottledCallback(callback, 100));
+    act(() => {
+      result.current("a");
+    });
+    expect(callback).toHaveBeenCalledTimes(1);
+    expect(callback).toHaveBeenCalledWith("a");
+  });
+
+  it("should drop calls inside cooldown window", () => {
+    const callback = vi.fn();
+    const { result } = renderHook(() => useThrottledCallback(callback, 1000));
+    act(() => {
+      result.current();
+      result.current();
+      result.current();
+    });
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it("should allow another call after interval elapses", () => {
+    const callback = vi.fn();
+    const { result } = renderHook(() => useThrottledCallback(callback, 500));
+    act(() => {
+      result.current(1);
+    });
+    act(() => {
+      vi.setSystemTime(1_000_400);
+      result.current(2);
+    });
+    expect(callback).toHaveBeenCalledTimes(1);
+    act(() => {
+      vi.setSystemTime(1_000_500);
+      result.current(3);
+    });
+    expect(callback).toHaveBeenCalledTimes(2);
+    expect(callback).toHaveBeenLastCalledWith(3);
+  });
+
+  it("should always use latest callback reference without resetting clock", () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ fn }: { fn: () => void }) => useThrottledCallback(fn, 200),
+      { initialProps: { fn: first } },
+    );
+    act(() => {
+      result.current();
+    });
+    expect(first).toHaveBeenCalledTimes(1);
+    rerender({ fn: second });
+    act(() => {
+      vi.setSystemTime(1_000_200);
+      result.current();
+    });
+    expect(second).toHaveBeenCalledTimes(1);
+    expect(first).toHaveBeenCalledTimes(1);
+  });
+});

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

@@ -1,3 +1,7 @@
+"use client";
+
+import { useCallback, useEffect, useRef } from "react";
+
 /**
  * Returns a stable, throttled version of `callback` that runs at most once per `intervalMs`.
  *
@@ -9,6 +13,24 @@
  * @param intervalMs - Minimum milliseconds between invocations.
  * @returns Throttled function with the same call signature as `callback`.
  */
-declare function useThrottledCallback<T extends (...args: any[]) => void>(callback: T, intervalMs: number): T;
+export function useThrottledCallback<
+  T extends (...args: any[]) => void,
+>(callback: T, intervalMs: number): T {
+  const callbackRef = useRef(callback);
+  const lastRunRef = useRef(0);
+
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
 
-export { useThrottledCallback };
+  return useCallback(
+    (...args: Parameters<T>) => {
+      const now = Date.now();
+      if (now - lastRunRef.current >= intervalMs) {
+        lastRunRef.current = now;
+        callbackRef.current(...args);
+      }
+    },
+    [intervalMs],
+  ) as T;
+}

package/src/hooks/useToggle/index.ts

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

package/src/hooks/useToggle/useToggle.test.ts

@@ -0,0 +1,40 @@
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { useToggle } from "./useToggle";
+
+describe("useToggle", () => {
+  it("should default to false", () => {
+    const { result } = renderHook(() => useToggle());
+    expect(result.current[0]).toBe(false);
+  });
+
+  it("should respect initial true", () => {
+    const { result } = renderHook(() => useToggle(true));
+    expect(result.current[0]).toBe(true);
+  });
+
+  it("should flip via toggle", () => {
+    const { result } = renderHook(() => useToggle(false));
+    act(() => {
+      result.current[1]();
+    });
+    expect(result.current[0]).toBe(true);
+    act(() => {
+      result.current[1]();
+    });
+    expect(result.current[0]).toBe(false);
+  });
+
+  it("should set absolute value via set", () => {
+    const { result } = renderHook(() => useToggle(false));
+    act(() => {
+      result.current[2](true);
+    });
+    expect(result.current[0]).toBe(true);
+    act(() => {
+      result.current[2](false);
+    });
+    expect(result.current[0]).toBe(false);
+  });
+});

package/src/hooks/useToggle/useToggle.ts

@@ -0,0 +1,22 @@
+"use client";
+
+import { useCallback, useState } from "react";
+
+/**
+ * Simple boolean state with `toggle()` and an explicit `set(next)` setter.
+ *
+ * @param initialValue - Starting boolean (default `false`).
+ * @returns `[on, toggle, set]` where `on` is the flag, `toggle` flips it, and `set` assigns an absolute value.
+ */
+export function useToggle(
+  initialValue = false,
+): [boolean, () => void, (next: boolean) => void] {
+  const [on, setOn] = useState(initialValue);
+  const toggle = useCallback(() => {
+    setOn((previous) => !previous);
+  }, []);
+  const set = useCallback((next: boolean) => {
+    setOn(next);
+  }, []);
+  return [on, toggle, set];
+}

package/src/hooks/useWindowSize/index.ts

@@ -0,0 +1 @@
+export { useWindowSize, type WindowSize } from "./useWindowSize";

package/src/hooks/useWindowSize/useWindowSize.test.ts

@@ -0,0 +1,23 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { useWindowSize } from "./useWindowSize";
+
+describe("useWindowSize", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("should read inner dimensions and update on resize", () => {
+    vi.spyOn(window, "innerWidth", "get").mockReturnValue(800);
+    vi.spyOn(window, "innerHeight", "get").mockReturnValue(600);
+    const { result } = renderHook(() => useWindowSize());
+    expect(result.current).toEqual({ width: 800, height: 600 });
+    vi.spyOn(window, "innerWidth", "get").mockReturnValue(1024);
+    vi.spyOn(window, "innerHeight", "get").mockReturnValue(768);
+    act(() => {
+      window.dispatchEvent(new Event("resize"));
+    });
+    expect(result.current).toEqual({ width: 1024, height: 768 });
+  });
+});

package/src/hooks/useWindowSize/useWindowSize.ts

@@ -0,0 +1,39 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+export type WindowSize = {
+  width: number;
+  height: number;
+};
+
+const defaultSize: WindowSize = { width: 0, height: 0 };
+
+/**
+ * Tracks the viewport size using `window.innerWidth` / `innerHeight` and a `resize` listener.
+ *
+ * Initializes to `{ width: 0, height: 0 }` on the server; after mount, size updates to the real viewport and on every resize.
+ *
+ * @returns Latest `{ width, height }` in CSS pixels.
+ */
+export function useWindowSize(): WindowSize {
+  const [size, setSize] = useState<WindowSize>(() => {
+    if (typeof window === "undefined") {
+      return defaultSize;
+    }
+    return { width: window.innerWidth || 0, height: window.innerHeight || 0 };
+  });
+
+  useEffect(() => {
+    const onResize = () => {
+      setSize({ width: window.innerWidth || 0, height: window.innerHeight || 0 });
+    };
+    onResize();
+    window.addEventListener("resize", onResize);
+    return () => {
+      window.removeEventListener("resize", onResize);
+    };
+  }, []);
+
+  return size;
+}

package/src/lib/utils.ts

@@ -0,0 +1,25 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+export const clampPage = (page: number, pageCount: number): number => {
+  if (pageCount <= 0) {
+    return 1;
+  }
+  return Math.min(pageCount, Math.max(1, Math.floor(page)));
+}
+
+export const range = (from: number, to: number): number[] => {
+  const out: number[] = [];
+  for (let i = from; i <= to; i += 1) {
+    out.push(i);
+  }
+  return out;
+}
+
+export const clamp = (value: number, min: number, max: number) => {
+  return Math.min(max, Math.max(min, value));
+}