@boxcustodia/library 2.0.0-alpha.16 → 2.0.0-alpha.18

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

@@ -0,0 +1,83 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useClipboard } from "./use-clipboard";
+
+describe("useClipboard", () => {
+  const writeText = vi.fn<(value: string) => Promise<void>>();
+
+  beforeEach(() => {
+    writeText.mockResolvedValue();
+    Object.defineProperty(navigator, "clipboard", {
+      value: { writeText },
+      configurable: true,
+    });
+  });
+
+  afterEach(() => {
+    writeText.mockReset();
+    vi.useRealTimers();
+  });
+
+  it("copies a value and flips copied to true", async () => {
+    const { result } = renderHook(() => useClipboard());
+
+    act(() => result.current.copy("test"));
+
+    await waitFor(() => expect(result.current.copied).toBe(true));
+    expect(writeText).toHaveBeenCalledWith("test");
+    expect(result.current.error).toBeNull();
+  });
+
+  it("auto-resets copied after the configured timeout", async () => {
+    vi.useFakeTimers();
+    const { result } = renderHook(() => useClipboard({ timeout: 500 }));
+
+    await act(async () => {
+      result.current.copy("test");
+      await Promise.resolve();
+    });
+
+    expect(result.current.copied).toBe(true);
+
+    act(() => vi.advanceTimersByTime(500));
+
+    expect(result.current.copied).toBe(false);
+  });
+
+  it("exposes the error when writeText rejects", async () => {
+    const failure = new Error("denied");
+    writeText.mockRejectedValueOnce(failure);
+    const { result } = renderHook(() => useClipboard());
+
+    act(() => result.current.copy("test"));
+
+    await waitFor(() => expect(result.current.error).toBe(failure));
+    expect(result.current.copied).toBe(false);
+  });
+
+  it("populates error when navigator.clipboard is unavailable", () => {
+    Object.defineProperty(navigator, "clipboard", {
+      value: undefined,
+      configurable: true,
+    });
+    const { result } = renderHook(() => useClipboard());
+
+    act(() => result.current.copy("test"));
+
+    expect(result.current.error).toBeInstanceOf(Error);
+    expect(result.current.error?.message).toMatch(/not supported/);
+    expect(result.current.copied).toBe(false);
+  });
+
+  it("clears copied and error on reset()", async () => {
+    const { result } = renderHook(() => useClipboard());
+
+    act(() => result.current.copy("test"));
+    await waitFor(() => expect(result.current.copied).toBe(true));
+
+    act(() => result.current.reset());
+
+    expect(result.current.copied).toBe(false);
+    expect(result.current.error).toBeNull();
+  });
+});

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

@@ -0,0 +1,64 @@
+import { useEffect, useRef, useState } from "react";
+
+export interface UseClipboardInput {
+  /** Time in ms after which the copied state will reset, `2000` by default */
+  timeout?: number;
+}
+
+export interface UseClipboardReturnValue {
+  /** Function to copy a string value to the clipboard */
+  copy: (value: string) => void;
+
+  /** Function to reset copied state and error */
+  reset: () => void;
+
+  /** Error if copying failed, `null` otherwise */
+  error: Error | null;
+
+  /** Boolean indicating if the value was copied successfully */
+  copied: boolean;
+}
+
+export function useClipboard(
+  options: UseClipboardInput = {},
+): UseClipboardReturnValue {
+  const timeout = options.timeout ?? 2000;
+  const [error, setError] = useState<Error | null>(null);
+  const [copied, setCopied] = useState(false);
+  const timeoutRef = useRef<number | null>(null);
+
+  useEffect(
+    () => () => {
+      if (timeoutRef.current) window.clearTimeout(timeoutRef.current);
+    },
+    [],
+  );
+
+  const handleCopyResult = (value: boolean) => {
+    if (timeoutRef.current) window.clearTimeout(timeoutRef.current);
+    timeoutRef.current = window.setTimeout(() => setCopied(false), timeout);
+    setCopied(value);
+  };
+
+  const copy = (value: string) => {
+    if (!navigator.clipboard?.writeText) {
+      setError(new Error("useClipboard: navigator.clipboard is not supported"));
+      return;
+    }
+    navigator.clipboard
+      .writeText(value)
+      .then(() => {
+        setError(null);
+        handleCopyResult(true);
+      })
+      .catch((err: Error) => setError(err));
+  };
+
+  const reset = () => {
+    setCopied(false);
+    setError(null);
+    if (timeoutRef.current) window.clearTimeout(timeoutRef.current);
+  };
+
+  return { copy, reset, error, copied };
+}

package/src/hooks/use-document-title/index.ts

@@ -0,0 +1 @@
+export * from "./use-document-title";

package/src/hooks/use-document-title/use-document-title.stories.tsx

@@ -0,0 +1,72 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { Input } from "../../components/input";
+import { Stack } from "../../components/stack";
+import { useDocumentTitle } from "./use-document-title";
+
+/**
+ * Sync `document.title` with a piece of React state — the classic
+ * "mirror the page name in the browser tab" pattern.
+ *
+ * ```tsx
+ * useDocumentTitle("Dashboard");
+ * useDocumentTitle(`Inbox (${unreadCount})`);
+ * ```
+ *
+ * Good to know:
+ * - **Empty and whitespace-only values are ignored.** The current title
+ *   stays put. Avoids the foot-gun of a parent component passing a
+ *   not-yet-loaded value and blanking the tab.
+ * - **Leading and trailing whitespace is trimmed** before being written.
+ * - **Opt-in cleanup:** pass `{ restoreOnUnmount: true }` to restore the
+ *   title that existed at mount time when the component unmounts. Useful
+ *   for modal/route components that only own the title while they are
+ *   visible.
+ *
+ * ```tsx
+ * useDocumentTitle(`Editing: ${doc.name}`, { restoreOnUnmount: true });
+ * ```
+ *
+ * Heads up: inside Storybook the change happens on the **iframe's**
+ * `document.title`, not the parent browser tab. Open the story in
+ * isolated canvas view to see the tab update, or just read the value
+ * rendered inline below.
+ */
+const meta: Meta<typeof useDocumentTitle> = {
+  title: "hooks/useDocumentTitle",
+  parameters: { layout: "centered" },
+  tags: ["beta"],
+};
+
+export default meta;
+type Story = StoryObj<typeof useDocumentTitle>;
+
+/**
+ * Type into the input — the hook writes `document.title` in real time.
+ * The code block below mirrors what gets written, including the
+ * whitespace-trim behavior. Clear the input to see the "ignored" path:
+ * the title stays at its last non-empty value.
+ */
+export const Default: Story = {
+  render: () => {
+    const [title, setTitle] = useState("Dashboard");
+    useDocumentTitle(title);
+
+    const written = title.trim();
+
+    return (
+      <Stack direction="vertical" gap={12} style={{ minWidth: 360 }}>
+        <Input
+          value={title}
+          onValueChange={setTitle}
+          placeholder="Type a title…"
+        />
+        <code className="rounded-md bg-muted px-3 py-2 text-xs">
+          {written.length > 0
+            ? `document.title = "${written}"`
+            : "(empty — current title preserved)"}
+        </code>
+      </Stack>
+    );
+  },
+};

package/src/hooks/use-document-title/use-document-title.test.tsx

@@ -0,0 +1,75 @@
+import { renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { useDocumentTitle } from "./use-document-title";
+
+describe("useDocumentTitle", () => {
+  beforeEach(() => {
+    document.title = "Original";
+  });
+
+  afterEach(() => {
+    document.title = "";
+  });
+
+  it("sets document.title to the provided value", () => {
+    renderHook(() => useDocumentTitle("Dashboard"));
+    expect(document.title).toBe("Dashboard");
+  });
+
+  it("updates the title when the value changes", () => {
+    const { rerender } = renderHook(({ title }) => useDocumentTitle(title), {
+      initialProps: { title: "First" },
+    });
+    expect(document.title).toBe("First");
+
+    rerender({ title: "Second" });
+    expect(document.title).toBe("Second");
+  });
+
+  it("ignores empty strings — the existing title stays put", () => {
+    renderHook(() => useDocumentTitle(""));
+    expect(document.title).toBe("Original");
+  });
+
+  it("ignores whitespace-only strings", () => {
+    renderHook(() => useDocumentTitle("   \t\n  "));
+    expect(document.title).toBe("Original");
+  });
+
+  it("trims surrounding whitespace before writing", () => {
+    renderHook(() => useDocumentTitle("  Hello  "));
+    expect(document.title).toBe("Hello");
+  });
+
+  it("does not restore the previous title on unmount by default", () => {
+    const { unmount } = renderHook(() => useDocumentTitle("New"));
+    expect(document.title).toBe("New");
+
+    unmount();
+    expect(document.title).toBe("New");
+  });
+
+  it("restores the previous title on unmount when restoreOnUnmount=true", () => {
+    const { unmount } = renderHook(() =>
+      useDocumentTitle("New", { restoreOnUnmount: true }),
+    );
+    expect(document.title).toBe("New");
+
+    unmount();
+    expect(document.title).toBe("Original");
+  });
+
+  it("captures the original title at mount, not the latest one", () => {
+    document.title = "First";
+    const { unmount, rerender } = renderHook(
+      ({ title }) => useDocumentTitle(title, { restoreOnUnmount: true }),
+      { initialProps: { title: "Step 1" } },
+    );
+
+    rerender({ title: "Step 2" });
+    expect(document.title).toBe("Step 2");
+
+    unmount();
+    expect(document.title).toBe("First");
+  });
+});

package/src/hooks/use-document-title/use-document-title.tsx

@@ -0,0 +1,32 @@
+import { useEffect, useRef } from "react";
+
+export interface UseDocumentTitleInput {
+  /** Restore the previous `document.title` when the component unmounts. Defaults to `false`. */
+  restoreOnUnmount?: boolean;
+}
+
+export function useDocumentTitle(
+  title: string,
+  options: UseDocumentTitleInput = {},
+): void {
+  const { restoreOnUnmount = false } = options;
+  const restoreRef = useRef(restoreOnUnmount);
+  restoreRef.current = restoreOnUnmount;
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: mount/unmount only
+  useEffect(() => {
+    const previous = document.title;
+    return () => {
+      if (restoreRef.current) {
+        document.title = previous;
+      }
+    };
+  }, []);
+
+  useEffect(() => {
+    if (typeof title !== "string") return;
+    const trimmed = title.trim();
+    if (trimmed.length === 0) return;
+    document.title = trimmed;
+  }, [title]);
+}

package/src/hooks/use-hover/index.ts

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

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

@@ -0,0 +1,90 @@
+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"],
+};
+
+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 = {
+  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>
+        </div>
+      </div>
+    );
+  },
+};

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

@@ -0,0 +1,93 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { useHover } from "./use-hover";
+
+function HoverTarget({
+  onHoverStart,
+  onHoverEnd,
+}: {
+  onHoverStart?: (event: MouseEvent) => void;
+  onHoverEnd?: (event: MouseEvent) => void;
+}) {
+  const { ref, hovered } = useHover<HTMLDivElement>({
+    onHoverStart,
+    onHoverEnd,
+  });
+  return (
+    <div ref={ref} data-testid="target">
+      {hovered ? "hovered" : "idle"}
+    </div>
+  );
+}
+
+describe("useHover", () => {
+  it("starts in the idle state", () => {
+    render(<HoverTarget />);
+    expect(screen.getByTestId("target")).toHaveTextContent("idle");
+  });
+
+  it("flips hovered to true on mouseenter and back on mouseleave", () => {
+    render(<HoverTarget />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.mouseEnter(target);
+    expect(target).toHaveTextContent("hovered");
+
+    fireEvent.mouseLeave(target);
+    expect(target).toHaveTextContent("idle");
+  });
+
+  it("ignores mouseover/mouseout (which bubble from children)", () => {
+    render(<HoverTarget />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.mouseOver(target);
+    expect(target).toHaveTextContent("idle");
+  });
+
+  it("invokes onHoverStart with the MouseEvent on enter", () => {
+    const onHoverStart = vi.fn();
+    render(<HoverTarget onHoverStart={onHoverStart} />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.mouseEnter(target);
+
+    expect(onHoverStart).toHaveBeenCalledTimes(1);
+    expect(onHoverStart.mock.calls[0][0]).toBeInstanceOf(MouseEvent);
+  });
+
+  it("invokes onHoverEnd with the MouseEvent on leave", () => {
+    const onHoverEnd = vi.fn();
+    render(<HoverTarget onHoverEnd={onHoverEnd} />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.mouseEnter(target);
+    fireEvent.mouseLeave(target);
+
+    expect(onHoverEnd).toHaveBeenCalledTimes(1);
+    expect(onHoverEnd.mock.calls[0][0]).toBeInstanceOf(MouseEvent);
+  });
+
+  it("uses the latest callback identity without re-attaching listeners", () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const { rerender } = render(<HoverTarget onHoverStart={first} />);
+    const target = screen.getByTestId("target");
+
+    rerender(<HoverTarget onHoverStart={second} />);
+    fireEvent.mouseEnter(target);
+
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+
+  it("removes listeners on unmount", () => {
+    const { unmount } = render(<HoverTarget />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.mouseEnter(target);
+    expect(target).toHaveTextContent("hovered");
+
+    expect(() => unmount()).not.toThrow();
+  });
+});

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

@@ -0,0 +1,45 @@
+import { type RefCallback, useCallback, useRef, useState } from "react";
+
+export interface UseHoverInput {
+  /** Fired when the pointer enters the target element. Receives the native MouseEvent. */
+  onHoverStart?: (event: MouseEvent) => void;
+  /** Fired when the pointer leaves the target element. Receives the native MouseEvent. */
+  onHoverEnd?: (event: MouseEvent) => 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 [hovered, setHovered] = useState(false);
+  const callbacksRef = useRef(options);
+  callbacksRef.current = options;
+
+  const ref: RefCallback<T> = useCallback((node) => {
+    if (!node) return;
+
+    const handleEnter = (event: MouseEvent) => {
+      setHovered(true);
+      callbacksRef.current.onHoverStart?.(event);
+    };
+    const handleLeave = (event: MouseEvent) => {
+      setHovered(false);
+      callbacksRef.current.onHoverEnd?.(event);
+    };
+
+    node.addEventListener("mouseenter", handleEnter);
+    node.addEventListener("mouseleave", handleLeave);
+
+    return () => {
+      node.removeEventListener("mouseenter", handleEnter);
+      node.removeEventListener("mouseleave", handleLeave);
+      setHovered(false);
+    };
+  }, []);
+
+  return { hovered, ref };
+}

package/src/hooks/use-on-mount/index.ts

@@ -0,0 +1 @@
+export * from "./use-on-mount";

package/src/hooks/use-on-mount/use-on-mount.stories.tsx

@@ -0,0 +1,85 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { Button } from "../../components/button";
+import { Stack } from "../../components/stack";
+import { useOnMount } from "./use-on-mount";
+
+/**
+ * Run a callback exactly once, when the component mounts.
+ *
+ * It's basically `useEffect(fn, [])` with two improvements: the callback
+ * never re-runs even if React's StrictMode replays effects in dev, and
+ * the intent ("on mount") is right there in the name — no `// biome-ignore`
+ * for an empty deps array.
+ *
+ * ```tsx
+ * useOnMount(() => {
+ *   trackPageView("/dashboard");
+ * });
+ * ```
+ *
+ * Good to know:
+ * - Returning a function from the callback registers a cleanup that runs
+ *   on unmount — same contract as `useEffect`.
+ * - The callback identity is captured on first run. Passing a new function
+ *   on later renders does **not** re-fire the hook, so you don't need to
+ *   memoize it.
+ * - For "do something on every update except the first one" use a different
+ *   pattern (a ref-guarded `useEffect` with deps) — this hook is mount-only.
+ */
+const meta: Meta<typeof useOnMount> = {
+  title: "hooks/useOnMount",
+  parameters: { layout: "centered" },
+  tags: ["new"],
+};
+
+export default meta;
+type Story = StoryObj<typeof useOnMount>;
+
+/**
+ * The hook stamps a timestamp on the first render and never touches it
+ * again. Click "Force re-render" as many times as you want — the
+ * "Mounted at" value stays frozen while the render counter ticks up.
+ * That's the proof that `useOnMount` fires exactly once.
+ */
+export const Default: Story = {
+  render: () => {
+    const [mountedAt, setMountedAt] = useState("");
+    const [renderCount, setRenderCount] = useState(0);
+
+    useOnMount(() => {
+      setMountedAt(
+        new Date().toLocaleTimeString(undefined, {
+          hour12: false,
+          hour: "2-digit",
+          minute: "2-digit",
+          second: "2-digit",
+        }),
+      );
+    });
+
+    return (
+      <Stack
+        direction="vertical"
+        gap={16}
+        style={{ minWidth: 360, padding: 20, borderRadius: 12 }}
+        className="border border-border bg-card"
+      >
+        <Stack direction="vertical" gap={4}>
+          <span className="text-sm">
+            <strong>Mounted at:</strong>{" "}
+            <code className="text-success">{mountedAt || "..."}</code>
+          </span>
+          <span className="text-xs text-muted-foreground">
+            Re-rendered {renderCount} time{renderCount === 1 ? "" : "s"} —
+            timestamp stays the same.
+          </span>
+        </Stack>
+
+        <Button onClick={() => setRenderCount((n) => n + 1)}>
+          Force re-render
+        </Button>
+      </Stack>
+    );
+  },
+};