@zentauri-ui/zentauri-components 1.3.1 → 1.4.0

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

@@ -0,0 +1,36 @@
+"use client";
+
+import { useCallback, useEffect, useRef } from "react";
+
+/**
+ * Returns a stable, throttled version of `callback` that runs at most once per `intervalMs`.
+ *
+ * If invoked again inside the cooldown window, the extra calls are **dropped** (no trailing flush). The latest
+ * `callback` reference is always used via a ref, so changing the handler does not reset the throttle clock.
+ *
+ * @typeParam T - Void function type (`(...args) => void`).
+ * @param callback - Work to run when the throttle gate opens.
+ * @param intervalMs - Minimum milliseconds between invocations.
+ * @returns Throttled function with the same call signature as `callback`.
+ */
+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]);
+
+  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));
+}

package/src/ui/accordion/accordion-base.tsx

@@ -0,0 +1,223 @@
+"use client";
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useId,
+  useMemo,
+  useState,
+} from "react";
+
+import { cn } from "../../lib/utils";
+
+import type {
+  AccordionBaseProps,
+  AccordionContentProps,
+  AccordionCtx,
+  AccordionItemProps,
+  AccordionTriggerProps,
+} from "./types";
+import {
+  accordionContentVariants,
+  accordionItemVariants,
+  accordionTriggerVariants,
+  accordionVariants,
+} from "./variants";
+
+const AccordionContext = createContext<AccordionCtx | null>(null);
+
+const AccordionItemValueContext = createContext<string | null>(null);
+
+export function useAccordionContext(component: string): AccordionCtx {
+  const ctx = useContext(AccordionContext);
+  if (!ctx) {
+    throw new Error(`${component} must be used within <Accordion>`);
+  }
+  return ctx;
+}
+
+export function useAccordionItemValue(component: string): string {
+  const value = useContext(AccordionItemValueContext);
+  if (!value) {
+    throw new Error(`${component} must be used within <AccordionItem>`);
+  }
+  return value;
+}
+
+export function AccordionBase({
+  type = "single",
+  value,
+  values,
+  defaultValue,
+  defaultValues,
+  onValueChange,
+  onValuesChange,
+  appearance = "default",
+  size = "md",
+  className,
+  children,
+}: AccordionBaseProps) {
+  const isSingleControlled = value !== undefined;
+  const isMultipleControlled = values !== undefined;
+  const [singleUncontrolled, setSingleUncontrolled] = useState<
+    string | undefined
+  >(defaultValue);
+  const [multipleUncontrolled, setMultipleUncontrolled] = useState<string[]>(
+    defaultValues ?? [],
+  );
+
+  const singleValue = isSingleControlled ? value : singleUncontrolled;
+  const multipleValues = useMemo(
+    () => (isMultipleControlled ? (values ?? []) : multipleUncontrolled),
+    [isMultipleControlled, values, multipleUncontrolled],
+  );
+
+  const isOpen = useCallback(
+    (itemValue: string) => {
+      if (type === "single") {
+        return singleValue === itemValue;
+      }
+      return multipleValues.includes(itemValue);
+    },
+    [multipleValues, singleValue, type],
+  );
+
+  const toggle = useCallback(
+    (itemValue: string) => {
+      if (type === "single") {
+        const next = singleValue === itemValue ? undefined : itemValue;
+        if (!isSingleControlled) {
+          setSingleUncontrolled(next);
+        }
+        onValueChange?.(next);
+        return;
+      }
+      const exists = multipleValues.includes(itemValue);
+      const next = exists
+        ? multipleValues.filter((entry) => entry !== itemValue)
+        : [...multipleValues, itemValue];
+      if (!isMultipleControlled) {
+        setMultipleUncontrolled(next);
+      }
+      onValuesChange?.(next);
+    },
+    [
+      isMultipleControlled,
+      isSingleControlled,
+      multipleValues,
+      onValueChange,
+      onValuesChange,
+      singleValue,
+      type,
+    ],
+  );
+
+  const ctx = useMemo(
+    () => ({
+      type,
+      appearance: appearance ?? "default",
+      size: size ?? "md",
+      isOpen,
+      toggle,
+    }),
+    [appearance, isOpen, size, toggle, type],
+  );
+
+  return (
+    <AccordionContext.Provider value={ctx}>
+      <div
+        data-slot="accordion"
+        className={cn(accordionVariants({ appearance, size }), className)}
+      >
+        {children}
+      </div>
+    </AccordionContext.Provider>
+  );
+}
+
+AccordionBase.displayName = "Accordion";
+
+export function AccordionItem({
+  className,
+  value,
+  children,
+  ref,
+  ...rest
+}: AccordionItemProps) {
+  const { appearance } = useAccordionContext("AccordionItem");
+  return (
+    <AccordionItemValueContext.Provider value={value}>
+      <div
+        ref={ref}
+        data-slot="accordion-item"
+        data-value={value}
+        className={cn(accordionItemVariants({ appearance }), className)}
+        {...rest}
+      >
+        {children}
+      </div>
+    </AccordionItemValueContext.Provider>
+  );
+}
+
+AccordionItem.displayName = "AccordionItem";
+
+export function AccordionTrigger({
+  className,
+  children,
+  ref,
+  ...rest
+}: AccordionTriggerProps) {
+  const itemValue = useAccordionItemValue("AccordionTrigger");
+  const { isOpen, toggle, size } = useAccordionContext("AccordionTrigger");
+  const open = isOpen(itemValue);
+  const panelId = `${itemValue}-panel`;
+  const baseId = useId();
+
+  return (
+    <h3 className="m-0">
+      <button
+        ref={ref}
+        type="button"
+        data-slot="accordion-trigger"
+        id={`${baseId}-trigger-${itemValue}`}
+        aria-expanded={open}
+        aria-controls={panelId}
+        className={cn(accordionTriggerVariants({ size }), className)}
+        onClick={() => toggle(itemValue)}
+        {...rest}
+      >
+        {children}
+      </button>
+    </h3>
+  );
+}
+
+AccordionTrigger.displayName = "AccordionTrigger";
+
+export function AccordionContent({
+  className,
+  children,
+  ref,
+}: AccordionContentProps) {
+  const itemValue = useAccordionItemValue("AccordionContent");
+  const { isOpen, size } = useAccordionContext("AccordionContent");
+  const open = isOpen(itemValue);
+  const panelId = `${itemValue}-panel`;
+
+  return open ? (
+    <div
+      key={itemValue}
+      ref={ref}
+      id={panelId}
+      role="region"
+      data-slot="accordion-content"
+      className={cn(accordionContentVariants({ size }), className)}
+    >
+      {children}
+    </div>
+  ) : null;
+}
+
+AccordionContent.displayName = "AccordionContent";