@zentauri-ui/zentauri-components 1.9.2 → 2.0.0

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,98 @@
+"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,108 @@
+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);
+  });
+});

package/src/hooks/useGeolocation/useGeolocation.ts

@@ -0,0 +1,173 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+export type GeolocationCoordinatesSnapshot = {
+  latitude: number;
+  longitude: number;
+  accuracy: number;
+  altitude: number | null;
+  altitudeAccuracy: number | null;
+  heading: number | null;
+  speed: number | null;
+  timestamp: number;
+};
+
+export type UseGeolocationParams = {
+  /** Start requesting the position (default `true`). Set `false` to defer the permission prompt. */
+  enabled?: boolean;
+  /** Keep watching for position updates instead of a one-shot read (default `true`). */
+  watch?: boolean;
+  /** `PositionOptions.enableHighAccuracy`. */
+  enableHighAccuracy?: boolean;
+  /** `PositionOptions.maximumAge` in milliseconds. */
+  maximumAge?: number;
+  /** `PositionOptions.timeout` in milliseconds. */
+  timeout?: number;
+};
+
+export type UseGeolocationResult = {
+  /** Whether `navigator.geolocation` exists in this browser. */
+  isSupported: boolean;
+  /** True while enabled and no position or error has arrived yet. */
+  loading: boolean;
+  /** Permission state from the Permissions API (`"unknown"` where unsupported or before resolution). */
+  permission: PermissionState | "unknown";
+  /** Latest position snapshot, or `null` before the first fix. */
+  position: GeolocationCoordinatesSnapshot | null;
+  /** Latest geolocation error, cleared when a new fix succeeds. */
+  error: GeolocationPositionError | null;
+};
+
+function toSnapshot(position: GeolocationPosition): GeolocationCoordinatesSnapshot {
+  const { coords } = position;
+  return {
+    latitude: coords.latitude,
+    longitude: coords.longitude,
+    accuracy: coords.accuracy,
+    altitude: coords.altitude,
+    altitudeAccuracy: coords.altitudeAccuracy,
+    heading: coords.heading,
+    speed: coords.speed,
+    timestamp: position.timestamp,
+  };
+}
+
+/**
+ * Browser geolocation with loading, error, and Permissions API state.
+ *
+ * - Requesting the position triggers the browser permission prompt; pass `enabled: false`
+ *   and flip it from a user gesture to avoid prompting on mount.
+ * - `watch: true` (default) uses `watchPosition` for live updates; `false` reads once.
+ * - `permission` mirrors `navigator.permissions.query({ name: "geolocation" })` including
+ *   change events, independent of whether a request is active.
+ *
+ * @param params - {@link UseGeolocationParams}
+ * @returns {@link UseGeolocationResult}
+ */
+export function useGeolocation(
+  params: UseGeolocationParams = {},
+): UseGeolocationResult {
+  const {
+    enabled = true,
+    watch = true,
+    enableHighAccuracy,
+    maximumAge,
+    timeout,
+  } = params;
+
+  const isSupported =
+    typeof navigator !== "undefined" && "geolocation" in navigator;
+
+  const [permission, setPermission] = useState<PermissionState | "unknown">(
+    "unknown",
+  );
+  const [position, setPosition] =
+    useState<GeolocationCoordinatesSnapshot | null>(null);
+  const [error, setError] = useState<GeolocationPositionError | null>(null);
+  const [settled, setSettled] = useState(false);
+
+  useEffect(() => {
+    if (
+      typeof navigator === "undefined" ||
+      navigator.permissions?.query == null
+    ) {
+      return;
+    }
+    let active = true;
+    let status: PermissionStatus | undefined;
+    const onChange = () => {
+      if (active && status) {
+        setPermission(status.state);
+      }
+    };
+    navigator.permissions
+      .query({ name: "geolocation" })
+      .then((result) => {
+        // Guard against the component unmounting before this promise resolves,
+        // which would otherwise attach a listener that can never be cleaned up.
+        if (!active) {
+          return;
+        }
+        status = result;
+        setPermission(result.state);
+        result.addEventListener("change", onChange);
+      })
+      .catch(() => {
+        /* permissions API may reject for geolocation in some browsers */
+      });
+    return () => {
+      active = false;
+      status?.removeEventListener("change", onChange);
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!enabled || !isSupported) {
+      return;
+    }
+    const geolocation = navigator.geolocation;
+    let active = true;
+    setSettled(false);
+    const onSuccess = (next: GeolocationPosition) => {
+      if (!active) {
+        return;
+      }
+      setPosition(toSnapshot(next));
+      setError(null);
+      setSettled(true);
+    };
+    const onError = (nextError: GeolocationPositionError) => {
+      if (!active) {
+        return;
+      }
+      setError(nextError);
+      setSettled(true);
+    };
+    const options: PositionOptions = {
+      enableHighAccuracy,
+      maximumAge,
+      timeout,
+    };
+    let watchId: number | undefined;
+    if (watch) {
+      watchId = geolocation.watchPosition(onSuccess, onError, options);
+    } else {
+      geolocation.getCurrentPosition(onSuccess, onError, options);
+    }
+    return () => {
+      active = false;
+      if (watchId !== undefined) {
+        geolocation.clearWatch(watchId);
+      }
+    };
+  }, [enableHighAccuracy, enabled, isSupported, maximumAge, timeout, watch]);
+
+  return {
+    isSupported,
+    loading: enabled && isSupported && !settled,
+    permission,
+    position,
+    error,
+  };
+}

package/src/hooks/useHotkeys/index.ts

@@ -0,0 +1,5 @@
+export {
+  useHotkeys,
+  type HotkeyHandler,
+  type UseHotkeysOptions,
+} from "./useHotkeys";

package/src/hooks/useHotkeys/useHotkeys.test.ts

@@ -0,0 +1,82 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { useHotkeys } from "./useHotkeys";
+
+function dispatchKeydown(
+  key: string,
+  init: KeyboardEventInit = {},
+  target: EventTarget = window,
+) {
+  const event = new KeyboardEvent("keydown", {
+    key,
+    bubbles: true,
+    cancelable: true,
+    ...init,
+  });
+  target.dispatchEvent(event);
+  return event;
+}
+
+describe("useHotkeys", () => {
+  it("should fire a plain key binding", () => {
+    const handler = vi.fn();
+    renderHook(() => useHotkeys({ escape: handler }));
+    dispatchKeydown("Escape");
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it("should require all listed modifiers", () => {
+    const handler = vi.fn();
+    renderHook(() => useHotkeys({ "ctrl+shift+k": handler }));
+    dispatchKeydown("k", { ctrlKey: true });
+    expect(handler).not.toHaveBeenCalled();
+    dispatchKeydown("k", { ctrlKey: true, shiftKey: true });
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it("should reject extra modifiers", () => {
+    const handler = vi.fn();
+    renderHook(() => useHotkeys({ k: handler }));
+    dispatchKeydown("k", { ctrlKey: true });
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("should match mod against ctrl or meta", () => {
+    const handler = vi.fn();
+    renderHook(() => useHotkeys({ "mod+k": handler }));
+    dispatchKeydown("k", { ctrlKey: true });
+    dispatchKeydown("k", { metaKey: true });
+    expect(handler).toHaveBeenCalledTimes(2);
+  });
+
+  it("should prevent default on match by default", () => {
+    renderHook(() => useHotkeys({ "mod+k": vi.fn() }));
+    const event = dispatchKeydown("k", { metaKey: true });
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("should skip events from editable targets unless allowed", () => {
+    const handler = vi.fn();
+    const input = document.createElement("input");
+    document.body.appendChild(input);
+    const { rerender } = renderHook(
+      ({ allowInInputs }: { allowInInputs: boolean }) =>
+        useHotkeys({ escape: handler }, { allowInInputs }),
+      { initialProps: { allowInInputs: false } },
+    );
+    dispatchKeydown("Escape", {}, input);
+    expect(handler).not.toHaveBeenCalled();
+    rerender({ allowInInputs: true });
+    dispatchKeydown("Escape", {}, input);
+    expect(handler).toHaveBeenCalledTimes(1);
+    input.remove();
+  });
+
+  it("should do nothing when disabled", () => {
+    const handler = vi.fn();
+    renderHook(() => useHotkeys({ escape: handler }, { enabled: false }));
+    dispatchKeydown("Escape");
+    expect(handler).not.toHaveBeenCalled();
+  });
+});