@zentauri-ui/zentauri-components 1.9.2 → 2.1.0

package/src/hooks/useGeolocation/useGeolocation.ts

@@ -0,0 +1,175 @@
+"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();
+  });
+});

package/src/hooks/useHotkeys/useHotkeys.ts

@@ -0,0 +1,130 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+
+export type HotkeyHandler = (event: KeyboardEvent) => void;
+
+export type UseHotkeysOptions = {
+  /** Disable all bindings without unmounting (default `true`). */
+  enabled?: boolean;
+  /** Call `event.preventDefault()` on a match (default `true`). */
+  preventDefault?: boolean;
+  /** Fire even when typing in inputs, textareas, selects, or contentEditable (default `false`). */
+  allowInInputs?: boolean;
+};
+
+type ParsedHotkey = {
+  key: string;
+  ctrl: boolean;
+  meta: boolean;
+  alt: boolean;
+  shift: boolean;
+  mod: boolean;
+};
+
+function parseHotkey(combo: string): ParsedHotkey {
+  const parsed: ParsedHotkey = {
+    key: "",
+    ctrl: false,
+    meta: false,
+    alt: false,
+    shift: false,
+    mod: false,
+  };
+  for (const raw of combo.split("+")) {
+    const token = raw.trim().toLowerCase();
+    if (token === "ctrl" || token === "control") {
+      parsed.ctrl = true;
+    } else if (token === "meta" || token === "cmd" || token === "command") {
+      parsed.meta = true;
+    } else if (token === "alt" || token === "option") {
+      parsed.alt = true;
+    } else if (token === "shift") {
+      parsed.shift = true;
+    } else if (token === "mod") {
+      parsed.mod = true;
+    } else {
+      parsed.key = token === "space" ? " " : token;
+    }
+  }
+  return parsed;
+}
+
+function matchesHotkey(event: KeyboardEvent, hotkey: ParsedHotkey): boolean {
+  if (hotkey.key !== event.key.toLowerCase()) {
+    return false;
+  }
+  if (hotkey.mod) {
+    if (!event.ctrlKey && !event.metaKey) {
+      return false;
+    }
+  } else if (hotkey.ctrl !== event.ctrlKey || hotkey.meta !== event.metaKey) {
+    return false;
+  }
+  return hotkey.alt === event.altKey && hotkey.shift === event.shiftKey;
+}
+
+function isEditableTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) {
+    return false;
+  }
+  return (
+    target.tagName === "INPUT" ||
+    target.tagName === "TEXTAREA" ||
+    target.tagName === "SELECT" ||
+    target.isContentEditable
+  );
+}
+
+/**
+ * Binds keyboard shortcut combos (e.g. `"mod+k"`, `"ctrl+shift+p"`, `"escape"`) to handlers on `window`.
+ *
+ * - Combo syntax: modifier tokens (`ctrl`/`control`, `meta`/`cmd`/`command`, `alt`/`option`, `shift`,
+ *   `mod`) joined with `+` around a final key matched against `event.key` (use `space` for the spacebar).
+ * - `mod` matches Cmd on macOS *or* Ctrl elsewhere (it accepts either modifier).
+ * - Bindings are read from a ref on every keydown, so inline objects and closures stay fresh
+ *   without re-subscribing.
+ * - Shortcuts are suppressed while typing in form fields or contentEditable unless `allowInInputs`.
+ *
+ * @param bindings - Map of combo string → handler. The first matching combo wins per event.
+ * @param options - {@link UseHotkeysOptions}
+ */
+export function useHotkeys(
+  bindings: Record<string, HotkeyHandler>,
+  options: UseHotkeysOptions = {},
+): void {
+  const {
+    enabled = true,
+    preventDefault = true,
+    allowInInputs = false,
+  } = options;
+  const bindingsRef = useRef(bindings);
+
+  useEffect(() => {
+    bindingsRef.current = bindings;
+  }, [bindings]);
+
+  useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (!allowInInputs && isEditableTarget(event.target)) {
+        return;
+      }
+      for (const [combo, handler] of Object.entries(bindingsRef.current)) {
+        if (matchesHotkey(event, parseHotkey(combo))) {
+          if (preventDefault) {
+            event.preventDefault();
+          }
+          handler(event);
+          return;
+        }
+      }
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => {
+      window.removeEventListener("keydown", onKeyDown);
+    };
+  }, [allowInInputs, enabled, preventDefault]);
+}

package/src/hooks/useIdleTimeout/index.ts

@@ -0,0 +1,5 @@
+export {
+  useIdleTimeout,
+  type UseIdleTimeoutParams,
+  type UseIdleTimeoutResult,
+} from "./useIdleTimeout";

package/src/hooks/useIdleTimeout/useIdleTimeout.test.ts

@@ -0,0 +1,95 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { useIdleTimeout } from "./useIdleTimeout";
+
+describe("useIdleTimeout", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("should start active and become idle after the timeout", () => {
+    const { result } = renderHook(() => useIdleTimeout({ timeoutMs: 1000 }));
+    expect(result.current.isIdle).toBe(false);
+    act(() => {
+      vi.advanceTimersByTime(1000);
+    });
+    expect(result.current.isIdle).toBe(true);
+  });
+
+  it("should stay active while activity events occur", () => {
+    const { result } = renderHook(() => useIdleTimeout({ timeoutMs: 1000 }));
+    act(() => {
+      vi.advanceTimersByTime(800);
+      window.dispatchEvent(new Event("keydown"));
+      vi.advanceTimersByTime(800);
+      window.dispatchEvent(new Event("pointermove"));
+      vi.advanceTimersByTime(800);
+    });
+    expect(result.current.isIdle).toBe(false);
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+    expect(result.current.isIdle).toBe(true);
+  });
+
+  it("should flip back to active on activity after idling", () => {
+    const onIdle = vi.fn();
+    const onActive = vi.fn();
+    const { result } = renderHook(() =>
+      useIdleTimeout({ timeoutMs: 500, onIdle, onActive }),
+    );
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+    expect(result.current.isIdle).toBe(true);
+    expect(onIdle).toHaveBeenCalledTimes(1);
+    act(() => {
+      window.dispatchEvent(new Event("pointerdown"));
+    });
+    expect(result.current.isIdle).toBe(false);
+    expect(onActive).toHaveBeenCalledTimes(1);
+  });
+
+  it("should not fire callbacks on mount", () => {
+    const onIdle = vi.fn();
+    const onActive = vi.fn();
+    renderHook(() => useIdleTimeout({ timeoutMs: 500, onIdle, onActive }));
+    expect(onIdle).not.toHaveBeenCalled();
+    expect(onActive).not.toHaveBeenCalled();
+  });
+
+  it("should respect a custom events list", () => {
+    const { result } = renderHook(() =>
+      useIdleTimeout({ timeoutMs: 500, events: ["click"] }),
+    );
+    act(() => {
+      vi.advanceTimersByTime(400);
+      window.dispatchEvent(new Event("keydown"));
+      vi.advanceTimersByTime(100);
+    });
+    expect(result.current.isIdle).toBe(true);
+    act(() => {
+      window.dispatchEvent(new Event("click"));
+    });
+    expect(result.current.isIdle).toBe(false);
+  });
+
+  it("should restart the timer via reset", () => {
+    const { result } = renderHook(() => useIdleTimeout({ timeoutMs: 500 }));
+    act(() => {
+      vi.advanceTimersByTime(400);
+      result.current.reset();
+      vi.advanceTimersByTime(400);
+    });
+    expect(result.current.isIdle).toBe(false);
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+    expect(result.current.isIdle).toBe(true);
+  });
+});

package/src/hooks/useIdleTimeout/useIdleTimeout.ts

@@ -0,0 +1,111 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+const DEFAULT_ACTIVITY_EVENTS = [
+  "pointerdown",
+  "pointermove",
+  "keydown",
+  "wheel",
+  "touchstart",
+  "scroll",
+] as const;
+
+export type UseIdleTimeoutParams = {
+  /** Inactivity duration in milliseconds before the user counts as idle. */
+  timeoutMs: number;
+  /** Window events treated as activity (default: pointer, key, wheel, touch, scroll). */
+  events?: readonly string[];
+  /** Start in the idle state (default `false`). */
+  initiallyIdle?: boolean;
+  /** Called when the user becomes idle. */
+  onIdle?: () => void;
+  /** Called when activity resumes after being idle. */
+  onActive?: () => void;
+};
+
+export type UseIdleTimeoutResult = {
+  /** Whether the user is currently idle. */
+  isIdle: boolean;
+  /** Mark the user active and restart the inactivity timer (e.g. after programmatic activity). */
+  reset: () => void;
+};
+
+/**
+ * Detects user inactivity: `isIdle` flips to `true` after `timeoutMs` without any of the
+ * activity events on `window`, and back to `false` on the next activity.
+ *
+ * - `onIdle` / `onActive` fire on transitions only (not on mount), and are read from refs
+ *   so inline callbacks stay fresh.
+ * - Useful for session expiry warnings, pausing media or polling, and presence indicators.
+ *
+ * @param params - {@link UseIdleTimeoutParams}
+ * @returns {@link UseIdleTimeoutResult}
+ */
+export function useIdleTimeout({
+  timeoutMs,
+  events,
+  initiallyIdle = false,
+  onIdle,
+  onActive,
+}: UseIdleTimeoutParams): UseIdleTimeoutResult {
+  const [isIdle, setIsIdle] = useState(initiallyIdle);
+  const onIdleRef = useRef(onIdle);
+  const onActiveRef = useRef(onActive);
+  const restartRef = useRef<() => void>(() => {});
+  const firstRunRef = useRef(true);
+
+  useEffect(() => {
+    onIdleRef.current = onIdle;
+    onActiveRef.current = onActive;
+  }, [onActive, onIdle]);
+
+  useEffect(() => {
+    if (firstRunRef.current) {
+      firstRunRef.current = false;
+      return;
+    }
+    if (isIdle) {
+      onIdleRef.current?.();
+    } else {
+      onActiveRef.current?.();
+    }
+  }, [isIdle]);
+
+  const eventsKey = (events ?? DEFAULT_ACTIVITY_EVENTS).join(" ");
+
+  useEffect(() => {
+    const eventNames = eventsKey.split(" ").filter(Boolean);
+    let timeoutId: number | undefined;
+
+    const startTimer = () => {
+      window.clearTimeout(timeoutId);
+      timeoutId = window.setTimeout(() => {
+        setIsIdle(true);
+      }, timeoutMs);
+    };
+
+    const onActivity = () => {
+      setIsIdle(false);
+      startTimer();
+    };
+
+    restartRef.current = onActivity;
+    startTimer();
+    for (const name of eventNames) {
+      window.addEventListener(name, onActivity, { passive: true });
+    }
+    return () => {
+      window.clearTimeout(timeoutId);
+      for (const name of eventNames) {
+        window.removeEventListener(name, onActivity);
+      }
+    };
+  }, [eventsKey, timeoutMs]);
+
+  const reset = useCallback(() => {
+    restartRef.current();
+  }, []);
+
+  return { isIdle, reset };
+}

package/src/hooks/useInterval/index.ts

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

package/src/hooks/useInterval/useInterval.test.ts

@@ -0,0 +1,56 @@
+import { renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { useInterval } from "./useInterval";
+
+describe("useInterval", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("should invoke the callback on every tick", () => {
+    const callback = vi.fn();
+    renderHook(() => useInterval(callback, 100));
+    vi.advanceTimersByTime(350);
+    expect(callback).toHaveBeenCalledTimes(3);
+  });
+
+  it("should pause when delay is null", () => {
+    const callback = vi.fn();
+    const { rerender } = renderHook(
+      ({ delay }: { delay: number | null }) => useInterval(callback, delay),
+      { initialProps: { delay: 100 as number | null } },
+    );
+    vi.advanceTimersByTime(100);
+    expect(callback).toHaveBeenCalledTimes(1);
+    rerender({ delay: null });
+    vi.advanceTimersByTime(500);
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it("should use the latest callback without restarting the timer", () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const { rerender } = renderHook(
+      ({ callback }: { callback: () => void }) => useInterval(callback, 100),
+      { initialProps: { callback: first } },
+    );
+    vi.advanceTimersByTime(50);
+    rerender({ callback: second });
+    vi.advanceTimersByTime(50);
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+
+  it("should stop on unmount", () => {
+    const callback = vi.fn();
+    const { unmount } = renderHook(() => useInterval(callback, 100));
+    unmount();
+    vi.advanceTimersByTime(500);
+    expect(callback).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useInterval/useInterval.ts

@@ -0,0 +1,36 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+
+/**
+ * Declarative `setInterval`: runs `callback` every `delayMs` milliseconds with automatic cleanup.
+ *
+ * - The latest callback is kept in a ref, so a new inline function each render does not restart the timer.
+ * - Pass `null` as the delay to pause the interval; pass a number again to resume.
+ * - Changing `delayMs` clears the previous interval and starts a fresh one.
+ *
+ * @param callback - Function invoked on every tick.
+ * @param delayMs - Interval in milliseconds, or `null` to pause.
+ */
+export function useInterval(
+  callback: () => void,
+  delayMs: number | null,
+): void {
+  const callbackRef = useRef(callback);
+
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+
+  useEffect(() => {
+    if (delayMs == null) {
+      return;
+    }
+    const id = window.setInterval(() => {
+      callbackRef.current();
+    }, delayMs);
+    return () => {
+      window.clearInterval(id);
+    };
+  }, [delayMs]);
+}