@zentauri-ui/zentauri-components 1.9.2 → 2.0.0

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 });
+  });
+});

package/src/hooks/useScrollPosition/useScrollPosition.ts

@@ -0,0 +1,88 @@
+"use client";
+
+import type { RefCallback, RefObject } from "react";
+import { useCallback, useEffect, useState } from "react";
+
+export type ScrollPosition = {
+  x: number;
+  y: number;
+};
+
+export type UseScrollPositionParams<T extends HTMLElement = HTMLElement> = {
+  /**
+   * Scroll container to observe via a pre-populated RefObject.
+   * For elements that mount asynchronously, use the returned `setRef` callback ref instead.
+   */
+  target?: RefObject<T | null>;
+};
+
+export type UseScrollPositionResult<T extends HTMLElement = HTMLElement> =
+  ScrollPosition & {
+    /**
+     * Callback ref to attach to a scroll container — works correctly with elements
+     * that are null on initial render (lazy / conditional mounts). Pass this as `ref`
+     * on the scrollable element when you cannot guarantee the ref is populated at mount.
+     */
+    setRef: RefCallback<T>;
+  };
+
+/**
+ * Tracks the scroll offset of the window (default) or a scrollable element.
+ *
+ * - Window mode reads `scrollX` / `scrollY`; element mode reads `scrollLeft` / `scrollTop`.
+ * - Subscribes with a passive `scroll` listener and reads the initial position on mount.
+ * - Pass a pre-populated `target` RefObject **or** use the returned `setRef` callback ref on
+ *   the scrollable element. Prefer `setRef` for elements that may be null on the first render
+ *   (conditional mounts, portals) — it stores the element in state so the effect re-attaches
+ *   correctly when the element becomes available.
+ * - For high-frequency consumers, derive throttled values downstream (e.g. with
+ *   `useThrottledCallback`) rather than throttling the source of truth.
+ *
+ * @param params - {@link UseScrollPositionParams}
+ * @returns Latest `{ x, y }` scroll offset in pixels plus a `setRef` callback ref.
+ */
+export function useScrollPosition<T extends HTMLElement = HTMLElement>(
+  params: UseScrollPositionParams<T> = {},
+): UseScrollPositionResult<T> {
+  const { target } = params;
+
+  // Track the element in state so the scroll listener effect reruns when the element
+  // is assigned (handles callback-ref / lazy-mount patterns).
+  const [element, setElement] = useState<T | null>(
+    () => target?.current ?? null,
+  );
+  const [position, setPosition] = useState<ScrollPosition>({ x: 0, y: 0 });
+
+  // Sync element state when the target RefObject changes (pre-populated refs).
+  useEffect(() => {
+    if (target?.current != null) {
+      setElement(target.current);
+    }
+  }, [target]);
+
+  const setRef = useCallback((node: T | null) => {
+    setElement(node);
+  }, []);
+
+  useEffect(() => {
+    const node: Window | T | null =
+      element ?? (typeof window === "undefined" ? null : window);
+    if (node == null) {
+      return;
+    }
+    const read = (): ScrollPosition =>
+      element == null
+        ? { x: window.scrollX, y: window.scrollY }
+        : { x: element.scrollLeft, y: element.scrollTop };
+    const onScroll = () => {
+      setPosition(read());
+    };
+    onScroll();
+    node.addEventListener("scroll", onScroll, { passive: true });
+    return () => {
+      node.removeEventListener("scroll", onScroll);
+    };
+  }, [element]);
+
+  return { x: position.x, y: position.y, setRef };
+}

package/src/hooks/useTimeout/index.ts

@@ -0,0 +1 @@
+export { useTimeout, type UseTimeoutResult } from "./useTimeout";

package/src/hooks/useTimeout/useTimeout.test.ts

@@ -0,0 +1,63 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { useTimeout } from "./useTimeout";
+
+describe("useTimeout", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("should fire once after the delay", () => {
+    const callback = vi.fn();
+    renderHook(() => useTimeout(callback, 200));
+    vi.advanceTimersByTime(199);
+    expect(callback).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(1);
+    expect(callback).toHaveBeenCalledTimes(1);
+    vi.advanceTimersByTime(1000);
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it("should not schedule when delay is null", () => {
+    const callback = vi.fn();
+    renderHook(() => useTimeout(callback, null));
+    vi.advanceTimersByTime(1000);
+    expect(callback).not.toHaveBeenCalled();
+  });
+
+  it("should cancel via clear", () => {
+    const callback = vi.fn();
+    const { result } = renderHook(() => useTimeout(callback, 200));
+    act(() => {
+      result.current.clear();
+    });
+    vi.advanceTimersByTime(500);
+    expect(callback).not.toHaveBeenCalled();
+  });
+
+  it("should restart the delay via reset", () => {
+    const callback = vi.fn();
+    const { result } = renderHook(() => useTimeout(callback, 200));
+    vi.advanceTimersByTime(150);
+    act(() => {
+      result.current.reset();
+    });
+    vi.advanceTimersByTime(150);
+    expect(callback).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(50);
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it("should cancel the pending timeout on unmount", () => {
+    const callback = vi.fn();
+    const { unmount } = renderHook(() => useTimeout(callback, 200));
+    unmount();
+    vi.advanceTimersByTime(500);
+    expect(callback).not.toHaveBeenCalled();
+  });
+});