@zentauri-ui/zentauri-components 1.9.2 → 2.0.0

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,97 @@
+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]);
+}

package/src/hooks/useKeyPress/index.ts

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

package/src/hooks/useKeyPress/useKeyPress.test.ts

@@ -0,0 +1,67 @@
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { useKeyPress } from "./useKeyPress";
+
+function dispatchKey(type: "keydown" | "keyup", key: string) {
+  window.dispatchEvent(new KeyboardEvent(type, { key }));
+}
+
+describe("useKeyPress", () => {
+  it("should be false initially", () => {
+    const { result } = renderHook(() => useKeyPress("k"));
+    expect(result.current).toBe(false);
+  });
+
+  it("should track keydown and keyup for the target key", () => {
+    const { result } = renderHook(() => useKeyPress("k"));
+    act(() => {
+      dispatchKey("keydown", "k");
+    });
+    expect(result.current).toBe(true);
+    act(() => {
+      dispatchKey("keyup", "k");
+    });
+    expect(result.current).toBe(false);
+  });
+
+  it("should ignore other keys", () => {
+    const { result } = renderHook(() => useKeyPress("k"));
+    act(() => {
+      dispatchKey("keydown", "j");
+    });
+    expect(result.current).toBe(false);
+  });
+
+  it("should match case-insensitively", () => {
+    const { result } = renderHook(() => useKeyPress("escape"));
+    act(() => {
+      dispatchKey("keydown", "Escape");
+    });
+    expect(result.current).toBe(true);
+  });
+
+  it("should accept an array of keys", () => {
+    const { result } = renderHook(() => useKeyPress(["ArrowUp", "ArrowDown"]));
+    act(() => {
+      dispatchKey("keydown", "ArrowDown");
+    });
+    expect(result.current).toBe(true);
+    act(() => {
+      dispatchKey("keyup", "ArrowDown");
+    });
+    expect(result.current).toBe(false);
+  });
+
+  it("should clear on window blur", () => {
+    const { result } = renderHook(() => useKeyPress("k"));
+    act(() => {
+      dispatchKey("keydown", "k");
+    });
+    expect(result.current).toBe(true);
+    act(() => {
+      window.dispatchEvent(new Event("blur"));
+    });
+    expect(result.current).toBe(false);
+  });
+});

package/src/hooks/useKeyPress/useKeyPress.ts

@@ -0,0 +1,65 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/**
+ * Tracks whether a keyboard key (or any of several keys) is currently held down.
+ *
+ * - Matches against `event.key`, case-insensitively (`"k"`, `"Escape"`, `"ArrowUp"`, …).
+ * - Listens on `window` for `keydown` / `keyup`, and clears on window `blur` so the
+ *   state cannot get stuck when focus leaves the page mid-press.
+ * - When an array of keys is watched, `pressed` remains `true` as long as ANY of the
+ *   target keys are still held — releasing one watched key while another is held does
+ *   not reset the state.
+ *
+ * @param targetKey - A key name or array of key names to watch.
+ * @returns `true` while one of the target keys is pressed.
+ */
+export function useKeyPress(targetKey: string | string[]): boolean {
+  const [pressed, setPressed] = useState(false);
+
+  // Build a stable string key from the sorted target array.
+  // Use \x00 as separator (not "|") so the literal "|" key is handled correctly.
+  const normalizedKey = (Array.isArray(targetKey) ? targetKey : [targetKey])
+    .map((k) => k.toLowerCase())
+    .sort()
+    .join("\x00");
+
+  useEffect(() => {
+    const keys = normalizedKey.split("\x00");
+    // Local Set tracks which target keys are currently pressed so that releasing
+    // one key while another is still held does not incorrectly clear `pressed`.
+    const pressedKeys = new Set<string>();
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      const key = event.key.toLowerCase();
+      if (keys.includes(key)) {
+        pressedKeys.add(key);
+        setPressed(true);
+      }
+    };
+    const onKeyUp = (event: KeyboardEvent) => {
+      const key = event.key.toLowerCase();
+      if (keys.includes(key)) {
+        pressedKeys.delete(key);
+        setPressed(pressedKeys.size > 0);
+      }
+    };
+    const onBlur = () => {
+      pressedKeys.clear();
+      setPressed(false);
+    };
+    window.addEventListener("keydown", onKeyDown);
+    window.addEventListener("keyup", onKeyUp);
+    window.addEventListener("blur", onBlur);
+    return () => {
+      pressedKeys.clear();
+      setPressed(false);
+      window.removeEventListener("keydown", onKeyDown);
+      window.removeEventListener("keyup", onKeyUp);
+      window.removeEventListener("blur", onBlur);
+    };
+  }, [normalizedKey]);
+
+  return pressed;
+}

package/src/hooks/useLongPress/index.ts

@@ -0,0 +1,5 @@
+export {
+  useLongPress,
+  type UseLongPressHandlers,
+  type UseLongPressOptions,
+} from "./useLongPress";