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

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

@@ -1,90 +1,268 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { useHover } from "./use-hover";
 
-/**
- * Track whether the pointer is over a specific element.
- *
- * Returns a `ref` callback you attach to the target element and a
- * `hovered` boolean that flips while the pointer is inside its bounds.
- * Powered by `mouseenter` / `mouseleave` — children inside the target
- * do **not** flicker the state on and off.
- *
- * ```tsx
- * const { ref, hovered } = useHover<HTMLDivElement>();
- *
- * <div ref={ref} className={hovered ? "bg-accent" : ""}>
- *   Hover me
- * </div>
- * ```
- *
- * Optional callbacks for imperative side effects (analytics, prefetch,
- * audio) — they receive the native `MouseEvent` and don't force a render:
- *
- * ```tsx
- * useHover<HTMLAnchorElement>({
- *   onHoverStart: () => prefetch("/dashboard"),
- *   onHoverEnd: (event) => log("left", event.clientX, event.clientY),
- * });
- * ```
- *
- * Good to know:
- * - `ref` is a callback ref (not a `RefObject`). Pass it straight to a
- *   DOM element — you can't read `.current` from outside the hook.
- * - Listeners are attached when the ref binds and removed when it
- *   detaches (unmount, ref reassignment, conditional rendering). No
- *   memory leaks.
- * - The callback identity is read fresh on every event, so passing
- *   inline arrow functions is safe — no re-attaching, no stale closure.
- * - Generic param controls the element type:
- *   `useHover<HTMLButtonElement>()` types the ref for a `<button>`.
- */
-const meta: Meta<typeof useHover> = {
-  title: "hooks/useHover",
-  parameters: { layout: "centered" },
-  tags: ["beta"],
+// ---------------------------------------------------------------------------
+// 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 useHover>;
-
-/**
- * Move the pointer over the card. Background and label update in
- * real time. Notice the child elements (the icon and the caption) do
- * **not** flicker the state — `mouseenter` ignores child traversals.
- */
-export const Default: Story = {
+
+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: () => {
-    const { ref, hovered } = useHover<HTMLDivElement>();
-
-    return (
-      <div
-        ref={ref}
-        style={{
-          width: 280,
-          padding: 24,
-          borderRadius: 12,
-          cursor: "pointer",
-          transition: "background-color 150ms, transform 150ms",
-          transform: hovered ? "translateY(-2px)" : "translateY(0)",
-        }}
-        className={
-          hovered
-            ? "border border-primary bg-primary/10 text-primary"
-            : "border border-border bg-card"
-        }
-      >
-        <div className="flex items-center gap-3">
-          <span style={{ fontSize: 28 }}>{hovered ? "👋" : "🙂"}</span>
-          <div className="flex flex-col">
-            <span className="text-sm font-medium">
-              {hovered ? "Hovering" : "Hover me"}
-            </span>
-            <span className="text-xs text-muted-foreground">
-              hovered = {String(hovered)}
-            </span>
-          </div>
+    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>
-      </div>
-    );
+      );
+    }
+
+    return <NestedDemo />;
   },
 };