@boxcustodia/library 2.0.0-alpha.2 → 2.0.0-alpha.20

package/src/hooks/use-hover/use-hover.stories.tsx

@@ -0,0 +1,268 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useHover } from "./use-hover";
+
+// ---------------------------------------------------------------------------
+// Story components
+// ---------------------------------------------------------------------------
+
+function HoverBox({
+  openDelay,
+  closeDelay,
+  onHoverStart,
+  onHoverEnd,
+  label,
+}: {
+  openDelay?: number;
+  closeDelay?: number;
+  onHoverStart?: (event: PointerEvent) => void;
+  onHoverEnd?: (event: PointerEvent) => void;
+  label?: string;
+}) {
+  const { ref, hovered } = useHover<HTMLDivElement>({
+    openDelay,
+    closeDelay,
+    onHoverStart,
+    onHoverEnd,
+  });
+
+  return (
+    <div
+      ref={ref}
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        justifyContent: "center",
+        width: 200,
+        height: 100,
+        borderRadius: 8,
+        border: "2px solid",
+        borderColor: hovered ? "#6366f1" : "#d1d5db",
+        backgroundColor: hovered ? "#eef2ff" : "#f9fafb",
+        color: hovered ? "#4338ca" : "#6b7280",
+        fontFamily: "sans-serif",
+        fontSize: 14,
+        fontWeight: 500,
+        cursor: "default",
+        transition: "all 150ms ease",
+        userSelect: "none",
+      }}
+    >
+      {label ?? (hovered ? "Hovered" : "Hover me")}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta: Meta<typeof HoverBox> = {
+  title: "Hooks/useHover",
+  component: HoverBox,
+  parameters: {
+    layout: "centered",
+    docs: {
+      description: {
+        component: `
+\`useHover\` tracks whether a pointer is over a DOM element. It returns a \`ref\`
+to attach to the target and a \`hovered\` boolean.
+
+\`\`\`ts
+const { ref, hovered } = useHover<HTMLDivElement>({
+  openDelay,   // ms before hovered becomes true  (default 0 — synchronous)
+  closeDelay,  // ms before hovered becomes false (default 0 — synchronous)
+  onHoverStart, // (event: PointerEvent) => void
+  onHoverEnd,   // (event: PointerEvent) => void
+});
+\`\`\`
+
+Uses \`pointerenter\`/\`pointerleave\` — touch-safe and no child-traversal flicker.
+        `.trim(),
+      },
+    },
+  },
+  argTypes: {
+    openDelay: {
+      control: { type: "number", min: 0, step: 50 },
+      description:
+        "Milliseconds before `hovered` becomes `true` after pointer entry. `0` = synchronous.",
+      defaultValue: 0,
+      table: { defaultValue: { summary: "0" } },
+    },
+    closeDelay: {
+      control: { type: "number", min: 0, step: 50 },
+      description:
+        "Milliseconds before `hovered` becomes `false` after pointer leave. `0` = synchronous.",
+      defaultValue: 0,
+      table: { defaultValue: { summary: "0" } },
+    },
+    onHoverStart: {
+      action: "onHoverStart",
+      description:
+        "Called with the originating `PointerEvent` when hover begins (after `openDelay`).",
+      table: { type: { summary: "(event: PointerEvent) => void" } },
+    },
+    onHoverEnd: {
+      action: "onHoverEnd",
+      description:
+        "Called with the originating `PointerEvent` when hover ends (after `closeDelay`).",
+      table: { type: { summary: "(event: PointerEvent) => void" } },
+    },
+    label: { table: { disable: true } },
+  },
+  args: {
+    openDelay: 0,
+    closeDelay: 0,
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof HoverBox>;
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Basic: Story = {
+  args: {
+    openDelay: 0,
+    closeDelay: 0,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Hover state updates synchronously — no delays. The controls panel lets you change `openDelay` and `closeDelay` live.",
+      },
+    },
+  },
+  render: (args) => <HoverBox {...args} />,
+};
+
+export const OpenDelay: Story = {
+  args: {
+    openDelay: 300,
+    closeDelay: 0,
+    label: "Open delay 300 ms",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "`openDelay={300}` — `hovered` only becomes `true` after 300 ms of continuous hover. Move the pointer in and out quickly to see that fast pass-throughs are ignored.",
+      },
+    },
+  },
+  render: (args) => <HoverBox {...args} />,
+};
+
+export const CloseDelay: Story = {
+  args: {
+    openDelay: 0,
+    closeDelay: 200,
+    label: "Close delay 200 ms",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "`closeDelay={200}` — `hovered` lingers 200 ms after the pointer leaves. Useful for tooltips and submenus where the pointer briefly exits before reaching the popup.",
+      },
+    },
+  },
+  render: (args) => <HoverBox {...args} />,
+};
+
+export const BothDelays: Story = {
+  args: {
+    openDelay: 300,
+    closeDelay: 200,
+    label: "Open 300 ms / Close 200 ms",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Both delays active: entry is debounced and exit lingers. Ideal for hover cards where accidental traversal should never trigger the reveal.",
+      },
+    },
+  },
+  render: (args) => <HoverBox {...args} />,
+};
+
+export const Callbacks: Story = {
+  args: {
+    openDelay: 0,
+    closeDelay: 0,
+    label: "Check Actions panel",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "`onHoverStart` and `onHoverEnd` receive the originating `PointerEvent`. Open the **Actions** panel (or browser console) to see the events fire. Useful for analytics, prefetch, or audio triggers.",
+      },
+    },
+  },
+  render: (args) => <HoverBox {...args} />,
+};
+
+export const NestedElements: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Moving the pointer into a child element does not re-trigger the parent — `pointerenter`/`pointerleave` do not bubble. The badge inside the box is a child element; hover over it and the parent state stays stable.",
+      },
+    },
+  },
+  render: () => {
+    function NestedDemo() {
+      const { ref, hovered } = useHover<HTMLDivElement>();
+
+      return (
+        <div
+          ref={ref}
+          style={{
+            display: "inline-flex",
+            flexDirection: "column",
+            alignItems: "center",
+            justifyContent: "center",
+            gap: 8,
+            width: 220,
+            height: 130,
+            borderRadius: 8,
+            border: "2px solid",
+            borderColor: hovered ? "#6366f1" : "#d1d5db",
+            backgroundColor: hovered ? "#eef2ff" : "#f9fafb",
+            color: hovered ? "#4338ca" : "#6b7280",
+            fontFamily: "sans-serif",
+            fontSize: 14,
+            cursor: "default",
+            transition: "all 150ms ease",
+            userSelect: "none",
+          }}
+        >
+          <span>{hovered ? "Hovered (no flicker)" : "Hover me"}</span>
+          {/* Nested child — traversal between the parent and this badge
+              does not re-trigger the parent's pointerleave/pointerenter */}
+          <span
+            style={{
+              padding: "2px 10px",
+              borderRadius: 999,
+              backgroundColor: hovered ? "#6366f1" : "#e5e7eb",
+              color: hovered ? "#fff" : "#374151",
+              fontSize: 12,
+              transition: "all 150ms ease",
+            }}
+          >
+            child element
+          </span>
+        </div>
+      );
+    }
+
+    return <NestedDemo />;
+  },
+};

package/src/hooks/use-hover/use-hover.test.tsx

@@ -0,0 +1,333 @@
+import {
+  act,
+  fireEvent,
+  render,
+  renderHook,
+  screen,
+} from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useHover } from "./use-hover";
+
+// ---------------------------------------------------------------------------
+// Test component helpers
+// ---------------------------------------------------------------------------
+
+function HoverTarget({
+  onHoverStart,
+  onHoverEnd,
+  openDelay,
+  closeDelay,
+}: {
+  onHoverStart?: (event: PointerEvent) => void;
+  onHoverEnd?: (event: PointerEvent) => void;
+  openDelay?: number;
+  closeDelay?: number;
+}) {
+  const { ref, hovered } = useHover<HTMLDivElement>({
+    onHoverStart,
+    onHoverEnd,
+    openDelay,
+    closeDelay,
+  });
+  return (
+    <div ref={ref} data-testid="target">
+      {hovered ? "hovered" : "idle"}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Pointer Event Subscription (R-PointerEvent)
+// ---------------------------------------------------------------------------
+
+describe("useHover — pointer event subscription", () => {
+  it("1: initial state — hovered is false and ref is a callable RefCallback", () => {
+    const { result } = renderHook(() => useHover());
+    expect(result.current.hovered).toBe(false);
+    expect(typeof result.current.ref).toBe("function");
+  });
+
+  it("2: pointerenter sets hovered to true", () => {
+    render(<HoverTarget />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.pointerEnter(target);
+
+    expect(target).toHaveTextContent("hovered");
+  });
+
+  it("3: pointerleave sets hovered to false", () => {
+    render(<HoverTarget />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.pointerEnter(target);
+    expect(target).toHaveTextContent("hovered");
+
+    fireEvent.pointerLeave(target);
+    expect(target).toHaveTextContent("idle");
+  });
+
+  it("4: mouseenter does NOT change state (regression guard)", () => {
+    render(<HoverTarget />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.mouseEnter(target);
+
+    expect(target).toHaveTextContent("idle");
+  });
+
+  it("5: mouseleave does NOT change state (regression guard)", () => {
+    render(<HoverTarget />);
+    const target = screen.getByTestId("target");
+
+    // Manually set hovered via pointer first
+    fireEvent.pointerEnter(target);
+    expect(target).toHaveTextContent("hovered");
+
+    fireEvent.mouseLeave(target);
+
+    expect(target).toHaveTextContent("hovered");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Open Delay (R-OpenDelay)
+// ---------------------------------------------------------------------------
+
+describe("useHover — openDelay", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("6: openDelay=0 — hovered flips immediately on pointerenter (no timer)", () => {
+    render(<HoverTarget openDelay={0} />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.pointerEnter(target);
+
+    expect(target).toHaveTextContent("hovered");
+  });
+
+  it("7: openDelay=300 — hovered stays false until timer fires", () => {
+    render(<HoverTarget openDelay={300} />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.pointerEnter(target);
+    expect(target).toHaveTextContent("idle");
+
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    expect(target).toHaveTextContent("hovered");
+  });
+
+  it("8: openDelay=300 — leave before timer fires cancels open, hovered never becomes true", () => {
+    render(<HoverTarget openDelay={300} />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.pointerEnter(target);
+    expect(target).toHaveTextContent("idle");
+
+    fireEvent.pointerLeave(target);
+
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    expect(target).toHaveTextContent("idle");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Close Delay (R-CloseDelay)
+// ---------------------------------------------------------------------------
+
+describe("useHover — closeDelay", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("9: closeDelay=0 — hovered flips immediately on pointerleave (no timer)", () => {
+    render(<HoverTarget closeDelay={0} />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.pointerEnter(target);
+    expect(target).toHaveTextContent("hovered");
+
+    fireEvent.pointerLeave(target);
+
+    expect(target).toHaveTextContent("idle");
+  });
+
+  it("10: closeDelay=200 — hovered stays true until timer fires", () => {
+    render(<HoverTarget closeDelay={200} />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.pointerEnter(target);
+    expect(target).toHaveTextContent("hovered");
+
+    fireEvent.pointerLeave(target);
+    expect(target).toHaveTextContent("hovered");
+
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+
+    expect(target).toHaveTextContent("idle");
+  });
+
+  it("11: closeDelay=200 — re-enter before close timer fires cancels close, hovered remains true", () => {
+    render(<HoverTarget closeDelay={200} />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.pointerEnter(target);
+    fireEvent.pointerLeave(target);
+    expect(target).toHaveTextContent("hovered");
+
+    // Re-enter before close timer fires
+    fireEvent.pointerEnter(target);
+
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+
+    expect(target).toHaveTextContent("hovered");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Callback Invocation (R-Callbacks)
+// ---------------------------------------------------------------------------
+
+describe("useHover — callbacks", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("12: onHoverStart is called on pointer enter (after open delay)", () => {
+    const onHoverStart = vi.fn();
+    render(<HoverTarget onHoverStart={onHoverStart} openDelay={100} />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.pointerEnter(target);
+    expect(onHoverStart).not.toHaveBeenCalled();
+
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+
+    expect(onHoverStart).toHaveBeenCalledTimes(1);
+  });
+
+  it("13: onHoverEnd is called on pointer leave (after close delay)", () => {
+    const onHoverEnd = vi.fn();
+    render(<HoverTarget onHoverEnd={onHoverEnd} closeDelay={100} />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.pointerEnter(target);
+    fireEvent.pointerLeave(target);
+    expect(onHoverEnd).not.toHaveBeenCalled();
+
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+
+    expect(onHoverEnd).toHaveBeenCalledTimes(1);
+  });
+
+  it("14: callbacks receive the originating PointerEvent (behavioral assertion + guarded instanceof)", () => {
+    const onHoverStart = vi.fn();
+    const onHoverEnd = vi.fn();
+    render(<HoverTarget onHoverStart={onHoverStart} onHoverEnd={onHoverEnd} />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.pointerEnter(target);
+    fireEvent.pointerLeave(target);
+
+    expect(onHoverStart).toHaveBeenCalledTimes(1);
+    expect(onHoverStart.mock.calls[0][0]).toMatchObject({
+      type: "pointerenter",
+    });
+
+    expect(onHoverEnd).toHaveBeenCalledTimes(1);
+    expect(onHoverEnd.mock.calls[0][0]).toMatchObject({ type: "pointerleave" });
+
+    // Guard: jsdom may not expose PointerEvent as a constructor
+    if (typeof window.PointerEvent === "function") {
+      expect(onHoverStart.mock.calls[0][0]).toBeInstanceOf(PointerEvent);
+      expect(onHoverEnd.mock.calls[0][0]).toBeInstanceOf(PointerEvent);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Latest-Ref Callback Pattern (R-LatestRef)
+// ---------------------------------------------------------------------------
+
+describe("useHover — latest-ref callback stability", () => {
+  it("15: callback identity stable — re-render with new function identity calls latest fn without re-attaching", () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const { rerender } = render(<HoverTarget onHoverStart={first} />);
+    const target = screen.getByTestId("target");
+
+    rerender(<HoverTarget onHoverStart={second} />);
+    fireEvent.pointerEnter(target);
+
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Timer Cleanup (R-TimerCleanup)
+// ---------------------------------------------------------------------------
+
+describe("useHover — timer cleanup on unmount", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("16: unmount cancels pending open timer — no state update after unmount", () => {
+    const onHoverStart = vi.fn();
+    const { unmount } = render(
+      <HoverTarget openDelay={300} onHoverStart={onHoverStart} />,
+    );
+    const target = screen.getByTestId("target");
+
+    fireEvent.pointerEnter(target);
+    expect(target).toHaveTextContent("idle");
+
+    unmount();
+
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    // onHoverStart must not have been called after unmount
+    expect(onHoverStart).not.toHaveBeenCalled();
+  });
+
+  it("17: unmount with no pending timers — no throw", () => {
+    const { unmount } = render(<HoverTarget />);
+
+    expect(() => unmount()).not.toThrow();
+  });
+});

package/src/hooks/use-hover/use-hover.tsx

@@ -0,0 +1,110 @@
+import {
+  type RefCallback,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import { useLatestRef } from "../internal";
+
+export interface UseHoverInput {
+  /** Delay in ms before `hovered` becomes true after pointer enters. Default 0 (synchronous). */
+  openDelay?: number;
+  /** Delay in ms before `hovered` becomes false after pointer leaves. Default 0 (synchronous). */
+  closeDelay?: number;
+  /** Fired when the pointer enters the target element. Receives the native PointerEvent. */
+  onHoverStart?: (event: PointerEvent) => void;
+  /** Fired when the pointer leaves the target element. Receives the native PointerEvent. */
+  onHoverEnd?: (event: PointerEvent) => void;
+}
+
+export interface UseHoverReturnValue<T extends HTMLElement = HTMLElement> {
+  hovered: boolean;
+  ref: RefCallback<T>;
+}
+
+export function useHover<T extends HTMLElement = HTMLElement>(
+  options: UseHoverInput = {},
+): UseHoverReturnValue<T> {
+  const { openDelay = 0, closeDelay = 0, onHoverStart, onHoverEnd } = options;
+
+  const [hovered, setHovered] = useState(false);
+
+  const onStartRef = useLatestRef(onHoverStart);
+  const onEndRef = useLatestRef(onHoverEnd);
+
+  const openTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const closeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const clearOpenTimer = useCallback(() => {
+    if (openTimerRef.current !== null) {
+      clearTimeout(openTimerRef.current);
+      openTimerRef.current = null;
+    }
+  }, []);
+
+  const clearCloseTimer = useCallback(() => {
+    if (closeTimerRef.current !== null) {
+      clearTimeout(closeTimerRef.current);
+      closeTimerRef.current = null;
+    }
+  }, []);
+
+  const ref: RefCallback<T> = useCallback(
+    (node) => {
+      if (!node) return;
+
+      const handleEnter = (event: PointerEvent) => {
+        clearCloseTimer();
+        if (openDelay > 0) {
+          openTimerRef.current = setTimeout(() => {
+            openTimerRef.current = null;
+            setHovered(true);
+            onStartRef.current?.(event);
+          }, openDelay);
+        } else {
+          setHovered(true);
+          onStartRef.current?.(event);
+        }
+      };
+
+      const handleLeave = (event: PointerEvent) => {
+        clearOpenTimer();
+        if (closeDelay > 0) {
+          closeTimerRef.current = setTimeout(() => {
+            closeTimerRef.current = null;
+            setHovered(false);
+            onEndRef.current?.(event);
+          }, closeDelay);
+        } else {
+          setHovered(false);
+          onEndRef.current?.(event);
+        }
+      };
+
+      node.addEventListener("pointerenter", handleEnter);
+      node.addEventListener("pointerleave", handleLeave);
+
+      return () => {
+        node.removeEventListener("pointerenter", handleEnter);
+        node.removeEventListener("pointerleave", handleLeave);
+        clearOpenTimer();
+        clearCloseTimer();
+        setHovered(false);
+      };
+    },
+    [openDelay, closeDelay, clearOpenTimer, clearCloseTimer],
+  );
+
+  // Unmount safety net: covers Suspense/concurrent remount races where a
+  // delayed timer could fire after the hook lifecycle ends.
+  useEffect(
+    () => () => {
+      clearOpenTimer();
+      clearCloseTimer();
+    },
+    [clearOpenTimer, clearCloseTimer],
+  );
+
+  return { hovered, ref };
+}

package/src/hooks/use-is-visible/index.ts

@@ -0,0 +1 @@
+export * from "./use-is-visible";