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

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

@@ -0,0 +1,126 @@
+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>
+    );
+  },
+};
+
+/**
+ * Pass a `template` with a `%s` placeholder to wrap every title in a
+ * suffix or prefix — e.g. append the app name to the page name.
+ *
+ * ```tsx
+ * useDocumentTitle(pageName, { template: "%s | Acme" });
+ * ```
+ */
+export const Template: Story = {
+  render: () => {
+    const [page, setPage] = useState("Inbox");
+    useDocumentTitle(page, { template: "%s | Acme" });
+
+    return (
+      <Stack direction="vertical" gap={12} style={{ minWidth: 360 }}>
+        <Input value={page} onValueChange={setPage} placeholder="Page name…" />
+        <code className="rounded-md bg-muted px-3 py-2 text-xs">
+          {`document.title = "${page.trim() || "…"} | Acme"`}
+        </code>
+      </Stack>
+    );
+  },
+};
+
+/**
+ * Set `enabled: false` to make the hook a no-op. The title is only
+ * written while `enabled` is `true`, so a component can own the tab
+ * title conditionally without unmounting.
+ */
+export const Enabled: Story = {
+  render: () => {
+    const [enabled, setEnabled] = useState(true);
+    useDocumentTitle("Live title", { enabled });
+
+    return (
+      <Stack direction="vertical" gap={12} style={{ minWidth: 360 }}>
+        <label className="flex items-center gap-2 text-sm">
+          <input
+            type="checkbox"
+            checked={enabled}
+            onChange={(e) => setEnabled(e.target.checked)}
+          />
+          enabled
+        </label>
+        <code className="rounded-md bg-muted px-3 py-2 text-xs">
+          {enabled
+            ? 'document.title = "Live title"'
+            : "(disabled — current title preserved)"}
+        </code>
+      </Stack>
+    );
+  },
+};

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

@@ -0,0 +1,101 @@
+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("applies a template with the %s placeholder", () => {
+    renderHook(() => useDocumentTitle("Inbox", { template: "%s | Acme" }));
+    expect(document.title).toBe("Inbox | Acme");
+  });
+
+  it("trims before applying the template", () => {
+    renderHook(() => useDocumentTitle("  Inbox  ", { template: "%s | Acme" }));
+    expect(document.title).toBe("Inbox | Acme");
+  });
+
+  it("does not touch the title when enabled is false", () => {
+    renderHook(() => useDocumentTitle("New", { enabled: false }));
+    expect(document.title).toBe("Original");
+  });
+
+  it("starts writing once enabled flips to true", () => {
+    const { rerender } = renderHook(
+      ({ enabled }) => useDocumentTitle("New", { enabled }),
+      { initialProps: { enabled: false } },
+    );
+    expect(document.title).toBe("Original");
+
+    rerender({ enabled: true });
+    expect(document.title).toBe("New");
+  });
+
+  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.ts

@@ -0,0 +1,46 @@
+import { useEffect, useRef } from "react";
+import { isBrowser } from "../internal";
+
+export interface UseDocumentTitleInput {
+  /** Restore the previous `document.title` when the component unmounts. Defaults to `false`. */
+  restoreOnUnmount?: boolean;
+  /**
+   * Template applied to the title. The `%s` placeholder is replaced with
+   * the (trimmed) title value. Example: `"%s | Acme"` turns `"Inbox"`
+   * into `"Inbox | Acme"`. When omitted, the title is written as-is.
+   */
+  template?: string;
+  /**
+   * When `false`, the hook does not touch `document.title`. Defaults to
+   * `true`. Useful to conditionally own the title.
+   */
+  enabled?: boolean;
+}
+
+export function useDocumentTitle(
+  title: string,
+  options: UseDocumentTitleInput = {},
+): void {
+  const { restoreOnUnmount = false, template, enabled = true } = options;
+  const restoreRef = useRef(restoreOnUnmount);
+  restoreRef.current = restoreOnUnmount;
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: mount/unmount only
+  useEffect(() => {
+    if (!isBrowser) return;
+    const previous = document.title;
+    return () => {
+      if (restoreRef.current) {
+        document.title = previous;
+      }
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!isBrowser || !enabled) return;
+    if (typeof title !== "string") return;
+    const trimmed = title.trim();
+    if (trimmed.length === 0) return;
+    document.title = template ? template.replace("%s", trimmed) : trimmed;
+  }, [title, template, enabled]);
+}

package/src/hooks/use-event-listener/index.ts

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

package/src/hooks/use-event-listener/use-event-listener.stories.tsx

@@ -0,0 +1,124 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useRef, useState } from "react";
+import { action } from "storybook/actions";
+import { Button } from "../../components";
+import { useEventListener } from "../use-event-listener";
+
+/**
+ * Subscribe to a DOM event with automatic add/remove, without writing a
+ * manual `useEffect` + cleanup.
+ *
+ * The `listener` is held in an internal ref (handler-stable pattern): passing
+ * an inline function does **not** re-attach the underlying listener on every
+ * render, and the listener always sees fresh props/state when it fires.
+ *
+ * The target is **explicit** and chosen by overload — there is no returned
+ * ref to wire up:
+ *
+ * ```tsx
+ * // window — omit the target
+ * useEventListener("resize", onResize);
+ *
+ * // an element — create your own ref and pass it
+ * const ref = useRef<HTMLButtonElement>(null);
+ * useEventListener("click", onClick, ref);
+ *
+ * // document — pass it directly (global key handlers, etc.)
+ * useEventListener("keydown", onKeyDown, document);
+ *
+ * // a MediaQueryList — react to media query changes
+ * const mql = window.matchMedia("(min-width: 768px)");
+ * useEventListener("change", onChange, mql);
+ * ```
+ *
+ * The fourth argument forwards the native `addEventListener` options
+ * (`{ capture, once, passive, signal }` or a boolean). The listener is
+ * re-attached when the `capture` / `once` / `passive` flags change.
+ *
+ * SSR-safe: the effect no-ops when there is no DOM.
+ *
+ * Migrating from v1: the hook no longer returns a ref. Replace
+ * `const ref = useEventListener("click", cb)` with an explicit ref —
+ * `const ref = useRef(null); useEventListener("click", cb, ref)`.
+ */
+const meta: Meta = {
+  title: "hooks/useEventListener",
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Listen on an element by creating a ref yourself and passing it as the
+ * third argument. The hook attaches the listener once the element is mounted.
+ */
+export const ElementByRef: Story = {
+  render: () => {
+    const ref = useRef<HTMLButtonElement>(null);
+    useEventListener("click", action("click"), ref);
+    return <Button ref={ref}>click me</Button>;
+  },
+};
+
+/**
+ * Omitting the target listens on `window`. Resize the preview pane to watch
+ * the value update — no manual subscription or cleanup required.
+ */
+export const WindowResize: Story = {
+  render: () => {
+    const [width, setWidth] = useState(window.innerWidth);
+    useEventListener("resize", () => setWidth(window.innerWidth));
+    return (
+      <p>
+        window width: <strong>{width}px</strong>
+      </p>
+    );
+  },
+};
+
+/**
+ * Pass `document` directly for document-level events such as global keyboard
+ * shortcuts that should fire regardless of focus. The listener receives the
+ * native `KeyboardEvent`.
+ */
+export const DocumentKeydown: Story = {
+  render: () => {
+    const [key, setKey] = useState("—");
+    useEventListener("keydown", (event) => setKey(event.key), document);
+    return (
+      <p>
+        last key pressed: <kbd>{key}</kbd>
+      </p>
+    );
+  },
+};
+
+/**
+ * Pass a `MediaQueryList` (from `window.matchMedia`) to react to viewport
+ * changes. Create the `MediaQueryList` once so its identity stays stable and
+ * the listener is not re-attached on every render.
+ */
+export const MediaQueryChange: Story = {
+  render: () => {
+    const [mql] = useState(() => window.matchMedia("(min-width: 768px)"));
+    const [matches, setMatches] = useState(mql.matches);
+    useEventListener("change", (event) => setMatches(event.matches), mql);
+    return <p>{matches ? "≥ 768px (desktop)" : "< 768px (mobile)"}</p>;
+  },
+};
+
+/**
+ * The fourth argument is forwarded to `addEventListener`. Here `{ once: true }`
+ * makes the listener fire a single time and then detach itself — the counter
+ * never goes past one regardless of how many times you click.
+ */
+export const OnceOption: Story = {
+  render: () => {
+    const ref = useRef<HTMLButtonElement>(null);
+    const [count, setCount] = useState(0);
+    useEventListener("click", () => setCount((c) => c + 1), ref, {
+      once: true,
+    });
+    return <Button ref={ref}>clicked {count} time(s)</Button>;
+  },
+};

package/src/hooks/use-event-listener/use-event-listener.test.tsx

@@ -0,0 +1,96 @@
+import { screen } from "@testing-library/dom";
+import { fireEvent, render, renderHook } from "@testing-library/react";
+import { useRef } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { click } from "../../utils/tests";
+import { useEventListener } from "../use-event-listener";
+
+describe("useEventListener hook", () => {
+  it("should be defined", () => {
+    expect(useEventListener).toBeDefined();
+  });
+
+  it("listens on window by default when no target is passed", () => {
+    const handler = vi.fn();
+    renderHook(() => useEventListener("resize", handler));
+
+    fireEvent(window, new Event("resize"));
+
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it("listens on an element passed by ref", () => {
+    const handler = vi.fn();
+    const Component = () => {
+      const ref = useRef<HTMLDivElement>(null);
+      useEventListener("click", handler, ref);
+      return <div ref={ref} data-testid="target" />;
+    };
+    render(<Component />);
+
+    click(screen.getByTestId("target"));
+
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it("listens on document when passed directly", () => {
+    const handler = vi.fn();
+    renderHook(() => useEventListener("keydown", handler, document));
+
+    fireEvent.keyDown(document.body);
+
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it("always calls the latest listener without re-attaching", () => {
+    const addSpy = vi.spyOn(window, "addEventListener");
+    const first = vi.fn();
+    const second = vi.fn();
+
+    const { rerender } = renderHook(
+      ({ cb }) => useEventListener("resize", cb),
+      {
+        initialProps: { cb: first },
+      },
+    );
+    const attachCountAfterMount = addSpy.mock.calls.filter(
+      ([type]) => type === "resize",
+    ).length;
+
+    rerender({ cb: second });
+    fireEvent(window, new Event("resize"));
+
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+    // listener identity change must not re-attach
+    expect(addSpy.mock.calls.filter(([type]) => type === "resize").length).toBe(
+      attachCountAfterMount,
+    );
+
+    addSpy.mockRestore();
+  });
+
+  it("removes the listener on unmount", () => {
+    const removeSpy = vi.spyOn(window, "removeEventListener");
+    const { unmount } = renderHook(() => useEventListener("resize", () => {}));
+
+    unmount();
+
+    expect(removeSpy).toHaveBeenCalledWith(
+      "resize",
+      expect.any(Function),
+      undefined,
+    );
+    removeSpy.mockRestore();
+  });
+
+  it("does not call the listener after unmount", () => {
+    const handler = vi.fn();
+    const { unmount } = renderHook(() => useEventListener("resize", handler));
+
+    unmount();
+    fireEvent(window, new Event("resize"));
+
+    expect(handler).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/use-event-listener/use-event-listener.ts

@@ -0,0 +1,84 @@
+import { type RefObject, useEffect } from "react";
+import { isBrowser, useLatestRef } from "../internal";
+
+type ListenableTarget = Window | Document | HTMLElement | MediaQueryList;
+
+type TargetArg<T extends ListenableTarget> = T | RefObject<T | null> | null;
+
+const resolveTarget = (
+  target: TargetArg<ListenableTarget> | undefined,
+): EventTarget | null => {
+  if (target == null) return isBrowser ? window : null;
+  if ("current" in target) return target.current;
+  return target;
+};
+
+/**
+ * Subscribe to a DOM event with automatic cleanup. The `listener` is read
+ * through an internal ref (handler-stable pattern), so passing an inline
+ * function never re-attaches the underlying listener on every render.
+ *
+ * The target is explicit and selected by overload:
+ * - omit it to listen on `window` (the default);
+ * - pass a `RefObject` or the element itself for an `HTMLElement`;
+ * - pass `document` for document-level events;
+ * - pass a `MediaQueryList` for media query changes.
+ *
+ * SSR-safe: the effect no-ops when there is no DOM.
+ */
+export function useEventListener<K extends keyof WindowEventMap>(
+  type: K,
+  listener: (event: WindowEventMap[K]) => void,
+  target?: Window | RefObject<Window | null> | null,
+  options?: boolean | AddEventListenerOptions,
+): void;
+export function useEventListener<K extends keyof DocumentEventMap>(
+  type: K,
+  listener: (event: DocumentEventMap[K]) => void,
+  target: Document | RefObject<Document | null>,
+  options?: boolean | AddEventListenerOptions,
+): void;
+export function useEventListener<
+  K extends keyof HTMLElementEventMap,
+  T extends HTMLElement = HTMLElement,
+>(
+  type: K,
+  listener: (event: HTMLElementEventMap[K]) => void,
+  target: T | RefObject<T | null>,
+  options?: boolean | AddEventListenerOptions,
+): void;
+export function useEventListener<K extends keyof MediaQueryListEventMap>(
+  type: K,
+  listener: (event: MediaQueryListEventMap[K]) => void,
+  target: MediaQueryList | RefObject<MediaQueryList | null>,
+  options?: boolean | AddEventListenerOptions,
+): void;
+export function useEventListener(
+  type: string,
+  listener: (event: Event) => void,
+  target?: TargetArg<ListenableTarget>,
+  options?: boolean | AddEventListenerOptions,
+): void {
+  const listenerRef = useLatestRef(listener);
+  const optionsRef = useLatestRef(options);
+
+  const capture = typeof options === "boolean" ? options : options?.capture;
+  const once = typeof options === "object" ? options.once : undefined;
+  const passive = typeof options === "object" ? options.passive : undefined;
+
+  useEffect(() => {
+    if (!isBrowser) return;
+
+    const node = resolveTarget(target);
+    if (!node) return;
+
+    const handler = (event: Event) => {
+      listenerRef.current(event);
+    };
+
+    node.addEventListener(type, handler, optionsRef.current);
+    return () => {
+      node.removeEventListener(type, handler, optionsRef.current);
+    };
+  }, [type, target, capture, once, passive]);
+}

package/src/hooks/use-focus-trap/index.ts

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

package/src/hooks/use-focus-trap/scope-tab.ts

@@ -0,0 +1,38 @@
+import { findTabbableDescendants } from "./tabbable";
+
+export function scopeTab(node: HTMLElement, event: KeyboardEvent) {
+  const tabbable = findTabbableDescendants(node);
+  if (!tabbable.length) {
+    event.preventDefault();
+    return;
+  }
+  const finalTabbable = tabbable[event.shiftKey ? 0 : tabbable.length - 1];
+  const root = node.getRootNode() as unknown as DocumentOrShadowRoot;
+  let leavingFinalTabbable =
+    finalTabbable === root.activeElement || node === root.activeElement;
+
+  const activeElement = root.activeElement as Element;
+  const activeElementIsRadio =
+    activeElement.tagName === "INPUT" &&
+    activeElement.getAttribute("type") === "radio";
+  if (activeElementIsRadio) {
+    const activeRadioGroup = tabbable.filter(
+      (element) =>
+        element.getAttribute("type") === "radio" &&
+        element.getAttribute("name") === activeElement.getAttribute("name"),
+    );
+    leavingFinalTabbable = activeRadioGroup.includes(finalTabbable);
+  }
+
+  if (!leavingFinalTabbable) {
+    return;
+  }
+
+  event.preventDefault();
+
+  const target = tabbable[event.shiftKey ? tabbable.length - 1 : 0];
+
+  if (target) {
+    (target as HTMLElement).focus();
+  }
+}

package/src/hooks/use-focus-trap/tabbable.ts

@@ -0,0 +1,70 @@
+const TABBABLE_NODES = /input|select|textarea|button|object/;
+export const FOCUS_SELECTOR =
+  "a, input, select, textarea, button, object, [tabindex]";
+
+function hidden(element: HTMLElement) {
+  if (process.env.NODE_ENV === "test") {
+    return false;
+  }
+
+  return element.style.display === "none";
+}
+
+function visible(element: HTMLElement) {
+  const isHidden =
+    element.getAttribute("aria-hidden") ||
+    element.getAttribute("hidden") ||
+    element.getAttribute("type") === "hidden";
+
+  if (isHidden) {
+    return false;
+  }
+
+  let parentElement: HTMLElement = element;
+  while (parentElement) {
+    if (parentElement === document.body || parentElement.nodeType === 11) {
+      break;
+    }
+
+    if (hidden(parentElement)) {
+      return false;
+    }
+
+    parentElement = parentElement.parentNode as HTMLElement;
+  }
+
+  return true;
+}
+
+function getElementTabIndex(element: HTMLElement) {
+  let tabIndex: string | null | undefined = element.getAttribute("tabindex");
+  if (tabIndex === null) {
+    tabIndex = undefined;
+  }
+  return parseInt(tabIndex as string, 10);
+}
+
+export function focusable(element: HTMLElement) {
+  const nodeName = element.nodeName.toLowerCase();
+  const isTabIndexNotNaN = !Number.isNaN(getElementTabIndex(element));
+  const res =
+    // @ts-expect-error function accepts any html element but if it is a button, it should not be disabled to trigger the condition
+    (TABBABLE_NODES.test(nodeName) && !element.disabled) ||
+    (element instanceof HTMLAnchorElement
+      ? element.href || isTabIndexNotNaN
+      : isTabIndexNotNaN);
+
+  return res && visible(element);
+}
+
+export function tabbable(element: HTMLElement) {
+  const tabIndex = getElementTabIndex(element);
+  const isTabIndexNaN = Number.isNaN(tabIndex);
+  return (isTabIndexNaN || tabIndex >= 0) && focusable(element);
+}
+
+export function findTabbableDescendants(element: HTMLElement): HTMLElement[] {
+  return Array.from(
+    element.querySelectorAll<HTMLElement>(FOCUS_SELECTOR),
+  ).filter(tabbable);
+}