@zentauri-ui/zentauri-components 1.9.2 → 2.1.0

package/src/hooks/useCookie/useCookie.ts

@@ -0,0 +1,127 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+
+export type CookieOptions = {
+  /** Lifetime in seconds (sets `max-age`). Omit for a session cookie. */
+  maxAgeSeconds?: number;
+  /** Absolute expiry (sets `expires`). */
+  expires?: Date;
+  /** Cookie path (default `"/"`). */
+  path?: string;
+  /** Cookie domain. */
+  domain?: string;
+  /** Restrict to HTTPS. */
+  secure?: boolean;
+  /** SameSite attribute. `"none"` automatically forces `secure` per browser requirements. */
+  sameSite?: "strict" | "lax" | "none";
+};
+
+export type UseCookieResult = [
+  string | null,
+  (value: string, options?: CookieOptions) => void,
+  (options?: Pick<CookieOptions, "path" | "domain">) => void,
+];
+
+function readCookie(name: string): string | null {
+  if (typeof document === "undefined") {
+    return null;
+  }
+  const prefix = `${encodeURIComponent(name)}=`;
+  const match = document.cookie
+    .split("; ")
+    .find((row) => row.startsWith(prefix));
+  if (!match) {
+    return null;
+  }
+  try {
+    return decodeURIComponent(match.slice(prefix.length));
+  } catch {
+    // Malformed cookie value — return null rather than crashing.
+    return null;
+  }
+}
+
+function serializeCookie(
+  name: string,
+  value: string,
+  options: CookieOptions,
+): string {
+  const { maxAgeSeconds, expires, path = "/", domain, sameSite } = options;
+  // SameSite=None requires Secure; enforce it automatically.
+  const secure = options.secure || sameSite === "none";
+  let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}; path=${path}`;
+  if (maxAgeSeconds != null) {
+    cookie += `; max-age=${maxAgeSeconds}`;
+  }
+  if (expires) {
+    cookie += `; expires=${expires.toUTCString()}`;
+  }
+  if (domain) {
+    cookie += `; domain=${domain}`;
+  }
+  if (secure) {
+    cookie += "; secure";
+  }
+  if (sameSite) {
+    cookie += `; samesite=${sameSite}`;
+  }
+  return cookie;
+}
+
+/**
+ * Reads and writes a single cookie with React state that stays in sync with your updates.
+ *
+ * - Initial state is `initialValue` (or `null`) to avoid SSR hydration mismatches; the actual
+ *   cookie value is read on mount via a `useEffect`.
+ * - `setCookie` writes `document.cookie` (URI-encoded) and updates state in the same call.
+ * - `removeCookie` expires the cookie via `max-age=0`; pass the same `path` / `domain` used when setting.
+ * - Reactivity covers writes made through this hook instance; cookies changed elsewhere are
+ *   re-read only when `name` changes (the browser offers no cookie change event in wide support).
+ * - `SameSite="none"` automatically forces the `Secure` flag per browser requirements.
+ *
+ * @param name - Cookie name.
+ * @param initialValue - Fallback when the cookie is absent (and during SSR).
+ * @returns `[value, setCookie, removeCookie]`.
+ */
+export function useCookie(
+  name: string,
+  initialValue?: string,
+): UseCookieResult {
+  // Initialize to initialValue (not readCookie) to avoid SSR hydration mismatches.
+  // The effect below syncs the actual cookie value after mount.
+  const [value, setValueState] = useState<string | null>(initialValue ?? null);
+
+  const setCookie = useCallback(
+    (value: string, options: CookieOptions = {}) => {
+      if (typeof document === "undefined") {
+        return;
+      }
+      document.cookie = serializeCookie(name, value, options);
+      setValueState(value);
+    },
+    [name],
+  );
+
+  const removeCookie = useCallback(
+    (options: Pick<CookieOptions, "path" | "domain"> = {}) => {
+      if (typeof document === "undefined") {
+        return;
+      }
+      document.cookie = serializeCookie(name, "", {
+        ...options,
+        maxAgeSeconds: 0,
+      });
+      setValueState(null);
+    },
+    [name],
+  );
+
+  useEffect(() => {
+    setValueState(readCookie(name) ?? initialValue ?? null);
+    // Intentionally keyed by name only: initialValue is a fallback, not a data source.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [name]);
+
+  return [value, setCookie, removeCookie];
+}

package/src/hooks/useCountdown/index.ts

@@ -0,0 +1,5 @@
+export {
+  useCountdown,
+  type UseCountdownParams,
+  type UseCountdownResult,
+} from "./useCountdown";

package/src/hooks/useCountdown/useCountdown.test.ts

@@ -0,0 +1,113 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { useCountdown } from "./useCountdown";
+
+describe("useCountdown", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("should stay idle until started", () => {
+    const { result } = renderHook(() =>
+      useCountdown({ countStart: 5, intervalMs: 100 }),
+    );
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+    expect(result.current.count).toBe(5);
+    expect(result.current.isRunning).toBe(false);
+  });
+
+  it("should count down once started", () => {
+    const { result } = renderHook(() =>
+      useCountdown({ countStart: 5, intervalMs: 100 }),
+    );
+    act(() => {
+      result.current.start();
+    });
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+    expect(result.current.count).toBe(2);
+    expect(result.current.isRunning).toBe(true);
+  });
+
+  it("should auto start when configured", () => {
+    const { result } = renderHook(() =>
+      useCountdown({ countStart: 3, intervalMs: 100, autoStart: true }),
+    );
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+    expect(result.current.count).toBe(2);
+  });
+
+  it("should pause and resume", () => {
+    const { result } = renderHook(() =>
+      useCountdown({ countStart: 5, intervalMs: 100 }),
+    );
+    act(() => {
+      result.current.start();
+    });
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+    act(() => {
+      result.current.pause();
+    });
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+    expect(result.current.count).toBe(3);
+    act(() => {
+      result.current.resume();
+    });
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+    expect(result.current.count).toBe(2);
+  });
+
+  it("should stop at countStop and call onComplete once", () => {
+    const onComplete = vi.fn();
+    const { result } = renderHook(() =>
+      useCountdown({ countStart: 2, intervalMs: 100, onComplete }),
+    );
+    act(() => {
+      result.current.start();
+    });
+    act(() => {
+      vi.advanceTimersByTime(1000);
+    });
+    expect(result.current.count).toBe(0);
+    expect(result.current.isRunning).toBe(false);
+    expect(result.current.isComplete).toBe(true);
+    expect(onComplete).toHaveBeenCalledTimes(1);
+  });
+
+  it("should reset back to countStart without running", () => {
+    const { result } = renderHook(() =>
+      useCountdown({ countStart: 5, intervalMs: 100 }),
+    );
+    act(() => {
+      result.current.start();
+    });
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+    act(() => {
+      result.current.reset();
+    });
+    expect(result.current.count).toBe(5);
+    expect(result.current.isRunning).toBe(false);
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+    expect(result.current.count).toBe(5);
+  });
+});

package/src/hooks/useCountdown/useCountdown.ts

@@ -0,0 +1,106 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export type UseCountdownParams = {
+  /** Value the countdown starts from. */
+  countStart: number;
+  /** Value the countdown stops at (default `0`). */
+  countStop?: number;
+  /** Milliseconds between ticks (default `1000`). */
+  intervalMs?: number;
+  /** Start counting immediately on mount (default `false`). */
+  autoStart?: boolean;
+  /** Called once when the countdown reaches `countStop`. */
+  onComplete?: () => void;
+};
+
+export type UseCountdownResult = {
+  /** Current count value. */
+  count: number;
+  /** Whether the countdown is actively ticking. */
+  isRunning: boolean;
+  /** Whether the countdown has reached `countStop`. */
+  isComplete: boolean;
+  /** Reset to `countStart` and begin ticking. */
+  start: () => void;
+  /** Stop ticking, keeping the current count. */
+  pause: () => void;
+  /** Continue ticking from the current count. No-op if the countdown is complete. */
+  resume: () => void;
+  /** Stop ticking and reset the count to `countStart`. */
+  reset: () => void;
+};
+
+/**
+ * Countdown timer decrementing by one each tick, with start, pause, resume, and reset controls.
+ *
+ * - Counts from `countStart` down to `countStop` (default `0`) every `intervalMs` (default 1s).
+ * - `onComplete` fires once when the count reaches `countStop`; the timer stops automatically.
+ * - `resume` on a completed countdown is a no-op; call `start` or `reset` to run it again.
+ *
+ * @param params - {@link UseCountdownParams}
+ * @returns {@link UseCountdownResult}
+ */
+export function useCountdown({
+  countStart,
+  countStop = 0,
+  intervalMs = 1000,
+  autoStart = false,
+  onComplete,
+}: UseCountdownParams): UseCountdownResult {
+  const [count, setCount] = useState(countStart);
+  const [isRunning, setIsRunning] = useState(autoStart);
+  const onCompleteRef = useRef(onComplete);
+
+  useEffect(() => {
+    onCompleteRef.current = onComplete;
+  }, [onComplete]);
+
+  const isComplete = count <= countStop;
+
+  // Interval effect: does NOT include `count` in deps so the timer is not recreated on every tick.
+  // Completion is handled by the separate effect below.
+  useEffect(() => {
+    if (!isRunning) {
+      return;
+    }
+    const id = window.setInterval(() => {
+      setCount((previous) => Math.max(countStop, previous - 1));
+    }, intervalMs);
+    return () => {
+      window.clearInterval(id);
+    };
+  }, [countStop, intervalMs, isRunning]);
+
+  useEffect(() => {
+    if (isRunning && count <= countStop) {
+      setIsRunning(false);
+      onCompleteRef.current?.();
+    }
+  }, [count, countStop, isRunning]);
+
+  const start = useCallback(() => {
+    setCount(countStart);
+    setIsRunning(true);
+  }, [countStart]);
+
+  const pause = useCallback(() => {
+    setIsRunning(false);
+  }, []);
+
+  const resume = useCallback(() => {
+    // No-op when the countdown has already reached countStop to prevent retriggering onComplete.
+    if (isComplete) {
+      return;
+    }
+    setIsRunning(true);
+  }, [isComplete]);
+
+  const reset = useCallback(() => {
+    setIsRunning(false);
+    setCount(countStart);
+  }, [countStart]);
+
+  return { count, isRunning, isComplete, start, pause, resume, reset };
+}

package/src/hooks/useEventListener/index.ts

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

package/src/hooks/useEventListener/useEventListener.test.ts

@@ -0,0 +1,60 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { useEventListener } from "./useEventListener";
+
+describe("useEventListener", () => {
+  it("should listen on window by default", () => {
+    const handler = vi.fn();
+    renderHook(() => useEventListener("focus", handler));
+    window.dispatchEvent(new Event("focus"));
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it("should listen on an element target", () => {
+    const element = document.createElement("button");
+    const handler = vi.fn();
+    renderHook(() => useEventListener("click", handler, element));
+    element.dispatchEvent(new Event("click"));
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it("should listen on a ref target resolved after mount", () => {
+    const element = document.createElement("div");
+    const ref = { current: element };
+    const handler = vi.fn();
+    renderHook(() => useEventListener("click", handler, ref));
+    element.dispatchEvent(new Event("click"));
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it("should always invoke the latest handler without re-subscribing", () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const addSpy = vi.spyOn(window, "addEventListener");
+    const { rerender } = renderHook(
+      ({ handler }: { handler: () => void }) =>
+        useEventListener("focus", handler),
+      { initialProps: { handler: first } },
+    );
+    const subscriptions = addSpy.mock.calls.filter(
+      ([type]) => type === "focus",
+    ).length;
+    rerender({ handler: second });
+    window.dispatchEvent(new Event("focus"));
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+    expect(addSpy.mock.calls.filter(([type]) => type === "focus").length).toBe(
+      subscriptions,
+    );
+    addSpy.mockRestore();
+  });
+
+  it("should remove the listener on unmount", () => {
+    const handler = vi.fn();
+    const { unmount } = renderHook(() => useEventListener("focus", handler));
+    unmount();
+    window.dispatchEvent(new Event("focus"));
+    expect(handler).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useEventListener/useEventListener.ts

@@ -0,0 +1,99 @@
+"use client";
+
+import type { RefObject } from "react";
+import { useEffect, useRef } from "react";
+
+export type UseEventListenerTarget =
+  | EventTarget
+  | RefObject<EventTarget | null>
+  | null;
+
+function resolveTarget(
+  target: UseEventListenerTarget | undefined,
+): EventTarget | null {
+  if (target === undefined) {
+    // No target specified — default to window.
+    return typeof window === "undefined" ? null : window;
+  }
+  if (target === null) {
+    // Explicit null — caller opts out; do not attach any listener.
+    return null;
+  }
+  if (target instanceof EventTarget) {
+    return target;
+  }
+  return target.current;
+}
+
+/**
+ * Attaches a DOM event listener with automatic cleanup and a stable wrapper around the latest handler.
+ *
+ * - Defaults to `window`; pass an element, `document`, or a React ref object as `target`.
+ * - Pass explicit `null` as `target` to skip attaching (useful for conditional subscriptions).
+ * - The handler is kept in a ref, so passing a new inline function each render does not re-subscribe.
+ * - Ref targets are resolved when the effect runs (after mount); if the ref is retargeted later,
+ *   re-render with a state-backed node (or key the component) to re-subscribe.
+ * - Pass `options` as individual booleans or a stable object reference to avoid re-subscribing on
+ *   every render. Internally, `capture`, `passive`, and `once` are compared individually.
+ *
+ * @param eventName - DOM event name (typed against `WindowEventMap` / `DocumentEventMap` / `HTMLElementEventMap`).
+ * @param handler - Listener invoked with the native event.
+ * @param target - Event target, React ref to one, `undefined` for `window`, or `null` to skip.
+ * @param options - Standard `addEventListener` options.
+ */
+export function useEventListener<K extends keyof WindowEventMap>(
+  eventName: K,
+  handler: (event: WindowEventMap[K]) => void,
+  target?: Window | null,
+  options?: boolean | AddEventListenerOptions,
+): void;
+export function useEventListener<K extends keyof DocumentEventMap>(
+  eventName: K,
+  handler: (event: DocumentEventMap[K]) => void,
+  target: Document | RefObject<Document | null>,
+  options?: boolean | AddEventListenerOptions,
+): void;
+export function useEventListener<
+  K extends keyof HTMLElementEventMap,
+  T extends HTMLElement = HTMLElement,
+>(
+  eventName: K,
+  handler: (event: HTMLElementEventMap[K]) => void,
+  target: T | RefObject<T | null> | null,
+  options?: boolean | AddEventListenerOptions,
+): void;
+export function useEventListener(
+  eventName: string,
+  handler: (event: Event) => void,
+  target?: UseEventListenerTarget,
+  options?: boolean | AddEventListenerOptions,
+): void {
+  const handlerRef = useRef(handler);
+
+  useEffect(() => {
+    handlerRef.current = handler;
+  }, [handler]);
+
+  // Destructure options to stable primitives so an inline `{ passive: true }` object literal
+  // passed by callers does not cause the listener to be removed and re-added on every render.
+  const capture =
+    typeof options === "boolean" ? options : (options?.capture ?? false);
+  const passive =
+    typeof options === "object" ? (options?.passive ?? false) : false;
+  const once = typeof options === "object" ? (options?.once ?? false) : false;
+
+  useEffect(() => {
+    const node = resolveTarget(target);
+    if (node == null) {
+      return;
+    }
+    const listenerOptions = { capture, passive, once };
+    const listener = (event: Event) => {
+      handlerRef.current(event);
+    };
+    node.addEventListener(eventName, listener, listenerOptions);
+    return () => {
+      node.removeEventListener(eventName, listener, listenerOptions);
+    };
+  }, [eventName, target, capture, passive, once]);
+}

package/src/hooks/useGeolocation/index.ts

@@ -0,0 +1,6 @@
+export {
+  useGeolocation,
+  type GeolocationCoordinatesSnapshot,
+  type UseGeolocationParams,
+  type UseGeolocationResult,
+} from "./useGeolocation";

package/src/hooks/useGeolocation/useGeolocation.test.ts

@@ -0,0 +1,110 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { useGeolocation } from "./useGeolocation";
+
+type SuccessCallback = (position: GeolocationPosition) => void;
+type ErrorCallback = (error: GeolocationPositionError) => void;
+
+function stubGeolocation() {
+  const callbacks: { success?: SuccessCallback; error?: ErrorCallback } = {};
+  const geolocation = {
+    getCurrentPosition: vi.fn(
+      (success: SuccessCallback, error: ErrorCallback) => {
+        callbacks.success = success;
+        callbacks.error = error;
+      },
+    ),
+    watchPosition: vi.fn((success: SuccessCallback, error: ErrorCallback) => {
+      callbacks.success = success;
+      callbacks.error = error;
+      return 1;
+    }),
+    clearWatch: vi.fn(),
+  };
+  Object.defineProperty(navigator, "geolocation", {
+    configurable: true,
+    value: geolocation,
+  });
+  return { geolocation, callbacks };
+}
+
+function makePosition(latitude: number, longitude: number) {
+  return {
+    coords: {
+      latitude,
+      longitude,
+      accuracy: 10,
+      altitude: null,
+      altitudeAccuracy: null,
+      heading: null,
+      speed: null,
+    },
+    timestamp: 1700000000000,
+  } as GeolocationPosition;
+}
+
+describe("useGeolocation", () => {
+  afterEach(() => {
+    // @ts-expect-error cleanup of the test-defined property
+    delete navigator.geolocation;
+  });
+
+  it("should report unsupported environments", () => {
+    const { result } = renderHook(() => useGeolocation());
+    expect(result.current.isSupported).toBe(false);
+    expect(result.current.loading).toBe(false);
+    expect(result.current.position).toBeNull();
+  });
+
+  it("should not request position while disabled", () => {
+    const { geolocation } = stubGeolocation();
+    const { result } = renderHook(() => useGeolocation({ enabled: false }));
+    expect(geolocation.watchPosition).not.toHaveBeenCalled();
+    expect(result.current.loading).toBe(false);
+  });
+
+  it("should watch position and expose the snapshot", async () => {
+    const { geolocation, callbacks } = stubGeolocation();
+    const { result } = renderHook(() => useGeolocation());
+    expect(geolocation.watchPosition).toHaveBeenCalledTimes(1);
+    expect(result.current.loading).toBe(true);
+    act(() => {
+      callbacks.success?.(makePosition(48.85, 2.35));
+    });
+    await waitFor(() => {
+      expect(result.current.position?.latitude).toBe(48.85);
+    });
+    expect(result.current.position?.longitude).toBe(2.35);
+    expect(result.current.loading).toBe(false);
+    expect(result.current.error).toBeNull();
+  });
+
+  it("should use a one-shot read when watch is false", () => {
+    const { geolocation } = stubGeolocation();
+    renderHook(() => useGeolocation({ watch: false }));
+    expect(geolocation.getCurrentPosition).toHaveBeenCalledTimes(1);
+    expect(geolocation.watchPosition).not.toHaveBeenCalled();
+  });
+
+  it("should surface errors and clear loading", () => {
+    const { callbacks } = stubGeolocation();
+    const { result } = renderHook(() => useGeolocation());
+    const positionError = {
+      code: 1,
+      message: "denied",
+    } as GeolocationPositionError;
+    act(() => {
+      callbacks.error?.(positionError);
+    });
+    expect(result.current.error).toBe(positionError);
+    expect(result.current.loading).toBe(false);
+  });
+
+  it("should clear the watch on unmount", () => {
+    const { geolocation } = stubGeolocation();
+    const { unmount } = renderHook(() => useGeolocation());
+    unmount();
+    expect(geolocation.clearWatch).toHaveBeenCalledWith(1);
+  });
+});