@zentauri-ui/zentauri-components 1.9.2 → 2.1.0

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";

package/src/hooks/useLongPress/useLongPress.test.ts

@@ -0,0 +1,180 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type {
+  MouseEvent as ReactMouseEvent,
+  PointerEvent as ReactPointerEvent,
+} from "react";
+
+import { useLongPress } from "./useLongPress";
+
+function pointerEvent(x = 0, y = 0, button = 0): ReactPointerEvent {
+  return { clientX: x, clientY: y, button } as ReactPointerEvent;
+}
+
+describe("useLongPress", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("should fire the callback after the threshold", () => {
+    const callback = vi.fn();
+    const { result } = renderHook(() =>
+      useLongPress(callback, { thresholdMs: 400 }),
+    );
+    act(() => {
+      result.current.onPointerDown(pointerEvent());
+    });
+    act(() => {
+      vi.advanceTimersByTime(399);
+    });
+    expect(callback).not.toHaveBeenCalled();
+    act(() => {
+      vi.advanceTimersByTime(1);
+    });
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it("should cancel when released early", () => {
+    const callback = vi.fn();
+    const onCancel = vi.fn();
+    const { result } = renderHook(() =>
+      useLongPress(callback, { thresholdMs: 400, onCancel }),
+    );
+    act(() => {
+      result.current.onPointerDown(pointerEvent());
+      vi.advanceTimersByTime(200);
+      result.current.onPointerUp(pointerEvent());
+      vi.advanceTimersByTime(400);
+    });
+    expect(callback).not.toHaveBeenCalled();
+    expect(onCancel).toHaveBeenCalledTimes(1);
+  });
+
+  it("should call onStart and onFinish around a completed press", () => {
+    const callback = vi.fn();
+    const onStart = vi.fn();
+    const onFinish = vi.fn();
+    const { result } = renderHook(() =>
+      useLongPress(callback, { thresholdMs: 300, onStart, onFinish }),
+    );
+    act(() => {
+      result.current.onPointerDown(pointerEvent());
+    });
+    expect(onStart).toHaveBeenCalledTimes(1);
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+    act(() => {
+      result.current.onPointerUp(pointerEvent());
+    });
+    expect(callback).toHaveBeenCalledTimes(1);
+    expect(onFinish).toHaveBeenCalledTimes(1);
+  });
+
+  it("should cancel when the pointer travels beyond the tolerance", () => {
+    const callback = vi.fn();
+    const onCancel = vi.fn();
+    const { result } = renderHook(() =>
+      useLongPress(callback, {
+        thresholdMs: 300,
+        moveTolerancePx: 10,
+        onCancel,
+      }),
+    );
+    act(() => {
+      result.current.onPointerDown(pointerEvent(0, 0));
+      result.current.onPointerMove(pointerEvent(4, 4));
+      vi.advanceTimersByTime(100);
+      result.current.onPointerMove(pointerEvent(30, 0));
+      vi.advanceTimersByTime(300);
+    });
+    expect(callback).not.toHaveBeenCalled();
+    expect(onCancel).toHaveBeenCalledTimes(1);
+  });
+
+  it("should cancel when the pointer leaves the target", () => {
+    const callback = vi.fn();
+    const onCancel = vi.fn();
+    const { result } = renderHook(() =>
+      useLongPress(callback, { thresholdMs: 300, onCancel }),
+    );
+    act(() => {
+      result.current.onPointerDown(pointerEvent());
+      vi.advanceTimersByTime(100);
+      result.current.onPointerLeave(pointerEvent());
+      vi.advanceTimersByTime(300);
+    });
+    expect(callback).not.toHaveBeenCalled();
+    expect(onCancel).toHaveBeenCalledTimes(1);
+  });
+
+  it("should cancel when onPointerCancel fires", () => {
+    const callback = vi.fn();
+    const onCancel = vi.fn();
+    const { result } = renderHook(() =>
+      useLongPress(callback, { thresholdMs: 300, onCancel }),
+    );
+    act(() => {
+      result.current.onPointerDown(pointerEvent());
+      vi.advanceTimersByTime(100);
+      result.current.onPointerCancel(pointerEvent());
+      vi.advanceTimersByTime(300);
+    });
+    expect(callback).not.toHaveBeenCalled();
+    expect(onCancel).toHaveBeenCalledTimes(1);
+  });
+
+  it("should ignore non-primary mouse buttons", () => {
+    const callback = vi.fn();
+    const { result } = renderHook(() =>
+      useLongPress(callback, { thresholdMs: 300 }),
+    );
+    act(() => {
+      result.current.onPointerDown(pointerEvent(0, 0, 2)); // right click
+      vi.advanceTimersByTime(400);
+    });
+    expect(callback).not.toHaveBeenCalled();
+  });
+
+  it("should suppress click after a successful long press", () => {
+    const callback = vi.fn();
+    const { result } = renderHook(() =>
+      useLongPress(callback, { thresholdMs: 300 }),
+    );
+    act(() => {
+      result.current.onPointerDown(pointerEvent());
+      vi.advanceTimersByTime(300);
+      result.current.onPointerUp(pointerEvent());
+    });
+    const mockEvent = {
+      preventDefault: vi.fn(),
+    } as unknown as ReactMouseEvent;
+    act(() => {
+      result.current.onClick(mockEvent);
+    });
+    expect(mockEvent.preventDefault).toHaveBeenCalledTimes(1);
+  });
+
+  it("should not suppress click after a short press", () => {
+    const callback = vi.fn();
+    const { result } = renderHook(() =>
+      useLongPress(callback, { thresholdMs: 300 }),
+    );
+    act(() => {
+      result.current.onPointerDown(pointerEvent());
+      vi.advanceTimersByTime(100);
+      result.current.onPointerUp(pointerEvent());
+    });
+    const mockEvent = {
+      preventDefault: vi.fn(),
+    } as unknown as ReactMouseEvent;
+    act(() => {
+      result.current.onClick(mockEvent);
+    });
+    expect(mockEvent.preventDefault).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useLongPress/useLongPress.ts

@@ -0,0 +1,177 @@
+"use client";
+
+import type {
+  MouseEvent as ReactMouseEvent,
+  PointerEvent as ReactPointerEvent,
+} from "react";
+import { useCallback, useEffect, useRef } from "react";
+
+export type UseLongPressOptions = {
+  /** Hold duration in milliseconds before the press counts as "long" (default `500`). */
+  thresholdMs?: number;
+  /** Pointer travel in pixels that cancels the press (default `10`). */
+  moveTolerancePx?: number;
+  /** Called when the pointer goes down (press attempt starts). */
+  onStart?: (event: ReactPointerEvent) => void;
+  /** Called on release after a long press fired. */
+  onFinish?: (event: ReactPointerEvent) => void;
+  /** Called when the press is released or cancelled before the threshold. */
+  onCancel?: (event: ReactPointerEvent) => void;
+};
+
+export type UseLongPressHandlers = {
+  onPointerDown: (event: ReactPointerEvent) => void;
+  onPointerMove: (event: ReactPointerEvent) => void;
+  onPointerUp: (event: ReactPointerEvent) => void;
+  onPointerLeave: (event: ReactPointerEvent) => void;
+  /** Handles browser-level pointer cancellation (e.g. system interruption, scroll takeover). */
+  onPointerCancel: (event: ReactPointerEvent) => void;
+  /**
+   * Suppresses the synthetic `click` event that fires after a successful long press.
+   * Spread alongside the other handlers to prevent unintended navigation or button actions.
+   */
+  onClick: (event: ReactMouseEvent) => void;
+};
+
+/**
+ * Long-press gesture detection built on pointer events, so it works for mouse, touch, and pen.
+ *
+ * Spread the returned handlers onto the target element. After the pointer is held
+ * `thresholdMs` without travelling more than `moveTolerancePx`, `callback` fires once;
+ * releasing afterwards calls `onFinish`, while early release / movement / leaving the
+ * element calls `onCancel`.
+ *
+ * Only the primary button (button 0 / left click / first touch contact) starts a long press;
+ * right and middle mouse buttons are ignored.
+ *
+ * Pair with `touch-action` / `select-none` CSS on touch targets to suppress native
+ * scrolling or text selection during the hold where needed.
+ *
+ * @param callback - Invoked once when the press crosses the threshold.
+ * @param options - {@link UseLongPressOptions}
+ * @returns Spreadable pointer handlers ({@link UseLongPressHandlers}).
+ */
+export function useLongPress(
+  callback: (event: ReactPointerEvent) => void,
+  options: UseLongPressOptions = {},
+): UseLongPressHandlers {
+  const {
+    thresholdMs = 500,
+    moveTolerancePx = 10,
+    onStart,
+    onFinish,
+    onCancel,
+  } = options;
+
+  const callbackRef = useRef(callback);
+  const onStartRef = useRef(onStart);
+  const onFinishRef = useRef(onFinish);
+  const onCancelRef = useRef(onCancel);
+
+  useEffect(() => {
+    callbackRef.current = callback;
+    onStartRef.current = onStart;
+    onFinishRef.current = onFinish;
+    onCancelRef.current = onCancel;
+  }, [callback, onCancel, onFinish, onStart]);
+
+  const timeoutRef = useRef<number | undefined>(undefined);
+  const triggeredRef = useRef(false);
+  const pressingRef = useRef(false);
+  const originRef = useRef({ x: 0, y: 0 });
+
+  const stopTimer = useCallback(() => {
+    if (timeoutRef.current !== undefined) {
+      window.clearTimeout(timeoutRef.current);
+      timeoutRef.current = undefined;
+    }
+  }, []);
+
+  useEffect(() => stopTimer, [stopTimer]);
+
+  const cancel = useCallback(
+    (event: ReactPointerEvent) => {
+      if (!pressingRef.current) {
+        return;
+      }
+      pressingRef.current = false;
+      stopTimer();
+      if (!triggeredRef.current) {
+        onCancelRef.current?.(event);
+      }
+    },
+    [stopTimer],
+  );
+
+  const onPointerDown = useCallback(
+    (event: ReactPointerEvent) => {
+      // Only respond to the primary button (left click / first touch contact).
+      // event.button > 0 catches right (2) and middle (1) mouse buttons.
+      if (event.button > 0) {
+        return;
+      }
+      pressingRef.current = true;
+      triggeredRef.current = false;
+      originRef.current = { x: event.clientX, y: event.clientY };
+      onStartRef.current?.(event);
+      stopTimer();
+      timeoutRef.current = window.setTimeout(() => {
+        timeoutRef.current = undefined;
+        if (pressingRef.current) {
+          triggeredRef.current = true;
+          callbackRef.current(event);
+        }
+      }, thresholdMs);
+    },
+    [stopTimer, thresholdMs],
+  );
+
+  const onPointerMove = useCallback(
+    (event: ReactPointerEvent) => {
+      if (!pressingRef.current || triggeredRef.current) {
+        return;
+      }
+      const dx = event.clientX - originRef.current.x;
+      const dy = event.clientY - originRef.current.y;
+      if (Math.hypot(dx, dy) > moveTolerancePx) {
+        cancel(event);
+      }
+    },
+    [cancel, moveTolerancePx],
+  );
+
+  const onPointerUp = useCallback(
+    (event: ReactPointerEvent) => {
+      if (!pressingRef.current) {
+        return;
+      }
+      const triggered = triggeredRef.current;
+      pressingRef.current = false;
+      stopTimer();
+      if (triggered) {
+        onFinishRef.current?.(event);
+      } else {
+        onCancelRef.current?.(event);
+      }
+    },
+    [stopTimer],
+  );
+
+  // After a successful long press the browser fires a synthetic `click` event on pointer up.
+  // This handler suppresses it so navigation and button actions aren't triggered unexpectedly.
+  const onClick = useCallback((event: ReactMouseEvent) => {
+    if (triggeredRef.current) {
+      event.preventDefault();
+      triggeredRef.current = false;
+    }
+  }, []);
+
+  return {
+    onPointerDown,
+    onPointerMove,
+    onPointerUp,
+    onPointerLeave: cancel,
+    onPointerCancel: cancel,
+    onClick,
+  };
+}

package/src/hooks/usePrevious/index.ts

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

package/src/hooks/usePrevious/usePrevious.test.ts

@@ -0,0 +1,33 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { usePrevious } from "./usePrevious";
+
+describe("usePrevious", () => {
+  it("should return undefined on first render", () => {
+    const { result } = renderHook(() => usePrevious(1));
+    expect(result.current).toBeUndefined();
+  });
+
+  it("should return the previous value after an update", () => {
+    const { result, rerender } = renderHook(
+      ({ value }: { value: number }) => usePrevious(value),
+      { initialProps: { value: 1 } },
+    );
+    rerender({ value: 2 });
+    expect(result.current).toBe(1);
+    rerender({ value: 3 });
+    expect(result.current).toBe(2);
+  });
+
+  it("should track non-primitive values", () => {
+    const a = { id: "a" };
+    const b = { id: "b" };
+    const { result, rerender } = renderHook(
+      ({ value }: { value: object }) => usePrevious(value),
+      { initialProps: { value: a } },
+    );
+    rerender({ value: b });
+    expect(result.current).toBe(a);
+  });
+});

package/src/hooks/usePrevious/usePrevious.ts

@@ -0,0 +1,24 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+
+/**
+ * Returns the value passed in on the previous render (`undefined` on first render).
+ *
+ * The ref is updated in an effect after each committed render, so during a render
+ * you always see the value from the previous one — handy for diffing props/state,
+ * animation direction, or "changed since last render" checks.
+ *
+ * @typeParam T - Tracked value type.
+ * @param value - The current value to track.
+ * @returns The value from the previous render, or `undefined` before the first update.
+ */
+export function usePrevious<T>(value: T): T | undefined {
+  const previousRef = useRef<T | undefined>(undefined);
+
+  useEffect(() => {
+    previousRef.current = value;
+  }, [value]);
+
+  return previousRef.current;
+}

package/src/hooks/useScrollPosition/index.ts

@@ -0,0 +1,5 @@
+export {
+  useScrollPosition,
+  type ScrollPosition,
+  type UseScrollPositionParams,
+} from "./useScrollPosition";

package/src/hooks/useScrollPosition/useScrollPosition.test.ts

@@ -0,0 +1,69 @@
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { useScrollPosition } from "./useScrollPosition";
+
+describe("useScrollPosition", () => {
+  it("should start at the current window offset", () => {
+    const { result } = renderHook(() => useScrollPosition());
+    expect(result.current).toMatchObject({ x: 0, y: 0 });
+  });
+
+  it("should update from window scroll events", () => {
+    const { result } = renderHook(() => useScrollPosition());
+    act(() => {
+      Object.defineProperty(window, "scrollY", {
+        configurable: true,
+        value: 120,
+      });
+      Object.defineProperty(window, "scrollX", {
+        configurable: true,
+        value: 40,
+      });
+      window.dispatchEvent(new Event("scroll"));
+    });
+    expect(result.current).toMatchObject({ x: 40, y: 120 });
+    Object.defineProperty(window, "scrollY", { configurable: true, value: 0 });
+    Object.defineProperty(window, "scrollX", { configurable: true, value: 0 });
+  });
+
+  it("should track an element target", () => {
+    const element = document.createElement("div");
+    const ref = { current: element };
+    const { result } = renderHook(() => useScrollPosition({ target: ref }));
+    act(() => {
+      element.scrollTop = 75;
+      element.scrollLeft = 5;
+      element.dispatchEvent(new Event("scroll"));
+    });
+    expect(result.current).toMatchObject({ x: 5, y: 75 });
+  });
+
+  it("should stop listening on unmount", () => {
+    const element = document.createElement("div");
+    const ref = { current: element };
+    const { result, unmount } = renderHook(() =>
+      useScrollPosition({ target: ref }),
+    );
+    unmount();
+    act(() => {
+      element.scrollTop = 300;
+      element.dispatchEvent(new Event("scroll"));
+    });
+    expect(result.current).toMatchObject({ x: 0, y: 0 });
+  });
+
+  it("should track an element attached via setRef callback ref", () => {
+    const { result } = renderHook(() => useScrollPosition());
+    const element = document.createElement("div");
+    act(() => {
+      result.current.setRef(element);
+    });
+    act(() => {
+      element.scrollTop = 50;
+      element.scrollLeft = 10;
+      element.dispatchEvent(new Event("scroll"));
+    });
+    expect(result.current).toMatchObject({ x: 10, y: 50 });
+  });
+});