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

package/src/hooks/use-boolean/use-boolean.ts

@@ -0,0 +1,50 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useLatestRef } from "../internal/use-latest-ref";
+
+export interface UseBooleanOptions {
+  /** Called after every value change. NOT called on initial mount. */
+  onChange?: (value: boolean) => void;
+}
+
+export interface UseBooleanActions {
+  /** Flip the current value. */
+  toggle(): void;
+  /** Force the value to true. */
+  setTrue(): void;
+  /** Force the value to false. */
+  setFalse(): void;
+  /** Set the value explicitly. */
+  set(value: boolean): void;
+}
+
+export function useBoolean(
+  initialValue?: boolean,
+  options?: UseBooleanOptions,
+): readonly [boolean, UseBooleanActions] {
+  const [state, setState] = useState<boolean>(initialValue ?? false);
+
+  // Always the latest handler — never a memo/effect dep.
+  const onChangeRef = useLatestRef(options?.onChange);
+
+  // Fire onChange on every change EXCEPT the initial mount.
+  const mountedRef = useRef(false);
+  useEffect(() => {
+    if (!mountedRef.current) {
+      mountedRef.current = true;
+      return;
+    }
+    onChangeRef.current?.(state);
+  }, [state]);
+
+  const actions = useMemo<UseBooleanActions>(
+    () => ({
+      toggle: () => setState((prev) => !prev),
+      setTrue: () => setState(true),
+      setFalse: () => setState(false),
+      set: (value) => setState(value),
+    }),
+    [setState],
+  );
+
+  return [state, actions] as const;
+}

package/src/hooks/use-click-outside/index.ts

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

package/src/hooks/use-click-outside/use-click-outside.stories.tsx

@@ -0,0 +1,210 @@
+import type { Meta } from "@storybook/react-vite";
+import { useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { Button } from "../../components/button";
+import { useClickOutside } from "./use-click-outside";
+
+/**
+ * Fires a callback when a `pointerdown` (or any configured event) happens
+ * outside the returned ref. Listener lives on `document`, so the wrapped
+ * element does not need to receive focus or capture events itself.
+ *
+ * ```tsx
+ * const ref = useClickOutside<HTMLDivElement>(() => setOpen(false));
+ * ```
+ *
+ * Good to know:
+ * - **Default event is `pointerdown`** (handles mouse + touch + pen in one
+ *   listener). Override via `events` if you need legacy `mousedown` or want
+ *   to combine `mousedown` + `touchstart`.
+ * - **Callback identity does not matter.** The hook reads the callback
+ *   through an internal ref, so an inline arrow function will not re-attach
+ *   the listener every render.
+ * - **`enabled` controls subscription.** When `false` no listener is
+ *   attached at all — cheaper than checking inside the callback, and the
+ *   typical way to "pause" the hook while a popover is closed.
+ * - **Portals:** elements rendered into another part of the tree (modals,
+ *   popovers, tooltips) are NOT inside the ref's subtree. Use
+ *   `additionalRefs` to whitelist them, or `ignore(event)` for finer
+ *   control (e.g. ignore clicks on a specific class).
+ * - **SSR-safe:** the effect early-returns on the server.
+ *
+ * Breaking change from v1: the second argument is now an options object
+ * (`enabled`, `events`, `ignore`, `additionalRefs`) instead of the boolean
+ * `watch`. Default event changed from `mousedown` to `pointerdown`.
+ */
+const meta: Meta = {
+  title: "hooks/useClickOutside",
+  parameters: { layout: "centered" },
+  tags: ["beta"],
+};
+
+export default meta;
+
+/**
+ * Open the popover with the button, then click anywhere outside the
+ * yellow card to close it. Clicking inside the card (including the
+ * "Close from inside" button) does not trigger the callback.
+ */
+export const Default = {
+  render: () => {
+    const [open, setOpen] = useState(true);
+    const ref = useClickOutside<HTMLDivElement>(() => setOpen(false));
+
+    return (
+      <div className="flex flex-col items-start gap-3">
+        <Button onClick={() => setOpen(true)} disabled={open}>
+          Open
+        </Button>
+        {open ? (
+          <div
+            ref={ref}
+            className="rounded-md border border-warning bg-warning/10 p-4 text-sm shadow-md"
+          >
+            <p className="mb-2">Click outside this card to dismiss it.</p>
+            <Button size="sm" onClick={() => setOpen(false)}>
+              Close from inside
+            </Button>
+          </div>
+        ) : (
+          <p className="text-sm text-muted-foreground">
+            Popover closed. Re-open with the button.
+          </p>
+        )}
+      </div>
+    );
+  },
+};
+
+/**
+ * `enabled: false` removes the listener entirely. Useful when the consumer
+ * already has a separate "is open" flag — the hook does not need to be
+ * conditionally rendered, just toggled.
+ *
+ * ```tsx
+ * useClickOutside(close, { enabled: isOpen });
+ * ```
+ */
+export const Enabled = {
+  render: () => {
+    const [enabled, setEnabled] = useState(true);
+    const [hits, setHits] = useState(0);
+    const ref = useClickOutside<HTMLDivElement>(() => setHits((n) => n + 1), {
+      enabled,
+    });
+
+    return (
+      <div className="flex flex-col items-start gap-3">
+        <label className="flex items-center gap-2 text-sm">
+          <input
+            type="checkbox"
+            checked={enabled}
+            onChange={(e) => setEnabled(e.target.checked)}
+          />
+          listener enabled
+        </label>
+        <div
+          ref={ref}
+          className="rounded-md border border-input bg-card p-4 text-sm"
+        >
+          Click outside this box.
+        </div>
+        <code className="text-xs">outside clicks counted: {hits}</code>
+      </div>
+    );
+  },
+};
+
+/**
+ * Use `additionalRefs` when the popover has a separate trigger element
+ * that should NOT count as "outside". Without this, clicking the trigger
+ * to toggle the popover would immediately close it again because the
+ * button lives outside the popover's DOM subtree.
+ *
+ * ```tsx
+ * const triggerRef = useRef<HTMLButtonElement>(null);
+ * const popoverRef = useClickOutside<HTMLDivElement>(close, {
+ *   additionalRefs: [triggerRef],
+ * });
+ * ```
+ */
+export const AdditionalRefs = {
+  render: () => {
+    const [open, setOpen] = useState(false);
+    const triggerRef = useRef<HTMLButtonElement>(null);
+    const popoverRef = useClickOutside<HTMLDivElement>(() => setOpen(false), {
+      additionalRefs: [triggerRef],
+    });
+
+    return (
+      <div className="flex flex-col items-start gap-3">
+        <Button ref={triggerRef} onClick={() => setOpen((v) => !v)}>
+          Toggle
+        </Button>
+        {open ? (
+          <div
+            ref={popoverRef}
+            className="rounded-md border border-input bg-card p-4 text-sm shadow-md"
+          >
+            Toggling the trigger does NOT close me, but clicking elsewhere does.
+          </div>
+        ) : null}
+      </div>
+    );
+  },
+};
+
+/**
+ * `ignore(event)` is the escape hatch for content rendered into a React
+ * portal — by definition that DOM is not under the ref's subtree, so a
+ * raw click on a tooltip / overlay / dropdown would close the parent.
+ * Returning `true` from `ignore` skips the callback for that event.
+ *
+ * Here, the green portal is anchored to `document.body` but tagged with
+ * `data-inside-portal`. The `ignore` predicate checks that attribute and
+ * treats clicks on the portal as "inside".
+ *
+ * ```tsx
+ * useClickOutside(close, {
+ *   ignore: (event) =>
+ *     (event.target as HTMLElement | null)?.closest("[data-tooltip]") != null,
+ * });
+ * ```
+ */
+export const IgnorePortals = {
+  render: () => {
+    const [closed, setClosed] = useState(false);
+    const ref = useClickOutside<HTMLDivElement>(() => setClosed(true), {
+      ignore: (event) =>
+        (event.target as HTMLElement | null)?.closest("[data-inside-portal]") !=
+        null,
+    });
+
+    return (
+      <div className="flex flex-col items-start gap-3">
+        <div
+          ref={ref}
+          className="rounded-md border border-input bg-card p-4 text-sm"
+        >
+          {closed
+            ? "Closed — click Reset."
+            : "Click the green portal: NOT counted as outside. Click anywhere else: counted."}
+        </div>
+        {closed ? (
+          <Button size="sm" onClick={() => setClosed(false)}>
+            Reset
+          </Button>
+        ) : null}
+        {createPortal(
+          <div
+            data-inside-portal
+            className="fixed right-4 bottom-4 rounded-md border border-success bg-success/15 p-3 text-xs shadow-md"
+          >
+            Portal content (anchored to body, but ignored).
+          </div>,
+          document.body,
+        )}
+      </div>
+    );
+  },
+};

package/src/hooks/use-click-outside/use-click-outside.test.tsx

@@ -0,0 +1,118 @@
+import { act, render, screen } from "@testing-library/react";
+import { useRef } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { useClickOutside } from "../use-click-outside";
+
+type ComponentProps = {
+  onOutside: (event: Event) => void;
+  enabled?: boolean;
+  events?: Array<"mousedown" | "pointerdown" | "touchstart">;
+  ignore?: (event: Event) => boolean;
+  withExtra?: boolean;
+};
+
+function Component({
+  onOutside,
+  enabled,
+  events,
+  ignore,
+  withExtra,
+}: ComponentProps) {
+  const extraRef = useRef<HTMLDivElement>(null);
+  const ref = useClickOutside<HTMLDivElement>(onOutside, {
+    enabled,
+    events,
+    ignore,
+    additionalRefs: withExtra ? [extraRef] : undefined,
+  });
+  return (
+    <div data-testid="wrapper">
+      <div ref={ref} data-testid="target" />
+      {withExtra ? <div ref={extraRef} data-testid="extra" /> : null}
+    </div>
+  );
+}
+
+function fireEvent(
+  el: Element,
+  type: "mousedown" | "pointerdown" | "touchstart",
+) {
+  el.dispatchEvent(new Event(type, { bubbles: true }));
+}
+
+describe("useClickOutside", () => {
+  it("calls callback on pointerdown outside the ref element (default event)", () => {
+    const fn = vi.fn();
+    render(<Component onOutside={fn} />);
+    act(() => fireEvent(screen.getByTestId("wrapper"), "pointerdown"));
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it("passes the event to the callback", () => {
+    const fn = vi.fn();
+    render(<Component onOutside={fn} />);
+    act(() => fireEvent(screen.getByTestId("wrapper"), "pointerdown"));
+    expect(fn.mock.calls[0][0]).toBeInstanceOf(Event);
+  });
+
+  it("does not call callback when clicking inside the ref element", () => {
+    const fn = vi.fn();
+    render(<Component onOutside={fn} />);
+    act(() => fireEvent(screen.getByTestId("target"), "pointerdown"));
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it("does not attach listener when enabled=false", () => {
+    const fn = vi.fn();
+    render(<Component onOutside={fn} enabled={false} />);
+    act(() => fireEvent(screen.getByTestId("wrapper"), "pointerdown"));
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it("attaches listeners for each event in the events option", () => {
+    const fn = vi.fn();
+    render(<Component onOutside={fn} events={["mousedown", "touchstart"]} />);
+    act(() => fireEvent(screen.getByTestId("wrapper"), "mousedown"));
+    act(() => fireEvent(screen.getByTestId("wrapper"), "touchstart"));
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not call callback for events not in the events option", () => {
+    const fn = vi.fn();
+    render(<Component onOutside={fn} events={["mousedown"]} />);
+    act(() => fireEvent(screen.getByTestId("wrapper"), "pointerdown"));
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it("skips the callback when ignore returns true", () => {
+    const fn = vi.fn();
+    render(<Component onOutside={fn} ignore={() => true} />);
+    act(() => fireEvent(screen.getByTestId("wrapper"), "pointerdown"));
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it("treats additional refs as inside", () => {
+    const fn = vi.fn();
+    render(<Component onOutside={fn} withExtra />);
+    act(() => fireEvent(screen.getByTestId("extra"), "pointerdown"));
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it("uses the latest callback without re-attaching listeners", () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const { rerender } = render(<Component onOutside={first} />);
+    rerender(<Component onOutside={second} />);
+    act(() => fireEvent(screen.getByTestId("wrapper"), "pointerdown"));
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledOnce();
+  });
+
+  it("removes listeners on unmount", () => {
+    const fn = vi.fn();
+    const { unmount } = render(<Component onOutside={fn} />);
+    unmount();
+    act(() => fireEvent(document.body, "pointerdown"));
+    expect(fn).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/use-click-outside/use-click-outside.ts

@@ -0,0 +1,71 @@
+import { type RefObject, useEffect, useRef } from "react";
+import { isBrowser, useLatestRef } from "../internal";
+
+type UseClickOutsideOptions = {
+  /** Disable the listener without unmounting the hook. Defaults to `true`. */
+  enabled?: boolean;
+  /**
+   * Which DOM events trigger the outside check. Any DOM event names work;
+   * pass `null` to fall back to the default. Defaults to `["pointerdown"]`.
+   */
+  events?: string[] | null;
+  /**
+   * Return `true` to skip the callback for a given event. Useful for portals
+   * or popovers whose DOM lives outside the wrapped ref but should still count
+   * as "inside".
+   */
+  ignore?: (event: Event) => boolean;
+  /**
+   * Extra refs that also count as "inside". An event whose target lives in
+   * any of these elements will not fire the callback.
+   */
+  additionalRefs?: RefObject<HTMLElement | null>[];
+};
+
+const DEFAULT_EVENTS = ["pointerdown"];
+
+export const useClickOutside = <T extends HTMLElement = HTMLElement>(
+  callback: (event: Event) => void,
+  options: UseClickOutsideOptions = {},
+): RefObject<T | null> => {
+  const { enabled = true, events, ignore, additionalRefs } = options;
+  const resolvedEvents = events ?? DEFAULT_EVENTS;
+
+  const ref = useRef<T | null>(null);
+  const callbackRef = useLatestRef(callback);
+  const ignoreRef = useLatestRef(ignore);
+  const additionalRefsRef = useLatestRef(additionalRefs);
+
+  useEffect(() => {
+    if (!enabled || !isBrowser) return;
+
+    const handler = (event: Event) => {
+      if (ignoreRef.current?.(event)) return;
+
+      const target = event.target as Node | null;
+      if (!target) return;
+
+      if (ref.current?.contains(target)) return;
+
+      const extras = additionalRefsRef.current;
+      if (extras) {
+        for (const extra of extras) {
+          if (extra.current?.contains(target)) return;
+        }
+      }
+
+      callbackRef.current(event);
+    };
+
+    for (const event of resolvedEvents) {
+      document.addEventListener(event, handler);
+    }
+    return () => {
+      for (const event of resolvedEvents) {
+        document.removeEventListener(event, handler);
+      }
+    };
+  }, [enabled, resolvedEvents.join("|")]);
+
+  return ref;
+};

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

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

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

@@ -0,0 +1,168 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { Button } from "../../components/button";
+import { Input } from "../../components/input";
+import { Stack } from "../../components/stack";
+import { useClipboard } from "./use-clipboard";
+
+/**
+ * Copy text to the clipboard without writing the same boilerplate every time.
+ *
+ * The hook gives you a `copied` flag that flips to `true` for a moment after a
+ * successful copy and then flips back on its own — perfect for the classic
+ * "Copy → Copied!" button. It also surfaces `error` so you can react when the
+ * browser blocks the operation.
+ *
+ * ```tsx
+ * const { copy, copied } = useClipboard();
+ *
+ * <Button onClick={() => copy("hello")}>
+ *   {copied ? "Copied!" : "Copy"}
+ * </Button>
+ * ```
+ *
+ * Good to know:
+ * - `copy(value)` is fire-and-forget. It will never throw — check `error` if
+ *   you need to handle failures (denied permissions, insecure context, etc.).
+ * - `copied` flips back to `false` automatically after `timeout` ms (default
+ *   `2000`). Pass `useClipboard({ timeout })` to change the duration.
+ * - Need to reset early? `reset()` clears both `copied` and `error` right away.
+ * - Unmount-safe: the internal timeout is cleared on cleanup, so you can use
+ *   it inside dialogs or conditionally rendered components without worrying.
+ */
+const meta: Meta<typeof useClipboard> = {
+  title: "hooks/useClipboard",
+  parameters: { layout: "centered" },
+  tags: ["beta"],
+};
+
+export default meta;
+type Story = StoryObj<typeof useClipboard>;
+
+/**
+ * The happy path: click the button and the label flips for two seconds before
+ * going back. That's the whole point of the hook in one story.
+ */
+export const Default: Story = {
+  render: () => {
+    const { copy, copied } = useClipboard();
+
+    return (
+      <Button onClick={() => copy("Hello from useClipboard")}>
+        {copied ? "Copied!" : "Copy greeting"}
+      </Button>
+    );
+  },
+};
+
+/**
+ * Real-world usage: copying whatever the user typed in. The button label
+ * reflects the latest copy — every click re-arms the timeout, so the "copied"
+ * feedback always lines up with the most recent action.
+ */
+export const CopyFromInput: Story = {
+  render: () => {
+    const [value, setValue] = useState("npm i @boxcustodia/library@next");
+    const { copy, copied } = useClipboard();
+
+    return (
+      <Stack direction="vertical" gap={12} style={{ minWidth: 320 }}>
+        <Input
+          value={value}
+          onValueChange={(next) => setValue(next)}
+          placeholder="Type something to copy"
+        />
+        <Button onClick={() => copy(value)} disabled={!value}>
+          {copied ? "Copied to clipboard" : "Copy value"}
+        </Button>
+      </Stack>
+    );
+  },
+};
+
+/**
+ * Two seconds is great for short labels, but for long snippets you may want
+ * the confirmation to stick around. Pass `timeout` in milliseconds to extend
+ * (or shorten) the window.
+ */
+export const CustomTimeout: Story = {
+  render: () => {
+    const { copy, copied } = useClipboard({ timeout: 5000 });
+
+    return (
+      <Stack direction="vertical" gap={8} align="center">
+        <Button onClick={() => copy("Stays copied for 5 seconds")}>
+          {copied ? "Copied (5s)" : "Copy with 5s timeout"}
+        </Button>
+        <span className="text-xs text-muted-foreground">
+          The label sticks for 5000 ms instead of the default 2000 ms.
+        </span>
+      </Stack>
+    );
+  },
+};
+
+/**
+ * Sometimes you don't want to wait for the timeout — for example, when the
+ * user takes a follow-up action. Call `reset()` and the state goes back to
+ * idle right away.
+ */
+export const ManualReset: Story = {
+  render: () => {
+    const { copy, copied, reset } = useClipboard({ timeout: 60_000 });
+
+    return (
+      <Stack gap={8}>
+        <Button onClick={() => copy("Persistent until reset")}>
+          {copied ? "Copied" : "Copy"}
+        </Button>
+        <Button variant="outline" onClick={reset} disabled={!copied}>
+          Reset
+        </Button>
+      </Stack>
+    );
+  },
+};
+
+/**
+ * Browsers can refuse to copy — denied permissions, an insecure origin, an
+ * older browser without the Clipboard API. When that happens `error` carries
+ * the reason and `copied` stays `false`, so you can branch your UI safely.
+ *
+ * ```tsx
+ * const { copy, copied, error } = useClipboard();
+ *
+ * <Button onClick={() => copy(value)}>Copy</Button>
+ * {error && <span className="text-error">{error.message}</span>}
+ * {copied && <span className="text-success">Copied!</span>}
+ * ```
+ */
+export const ErrorHandling: Story = {
+  render: () => {
+    const { copy, copied, error, reset } = useClipboard();
+
+    return (
+      <Stack direction="vertical" gap={8} style={{ minWidth: 320 }}>
+        <Stack gap={8}>
+          <Button onClick={() => copy("Try copying me")}>Copy</Button>
+          <Button
+            variant="outline"
+            onClick={reset}
+            disabled={!copied && !error}
+          >
+            Reset
+          </Button>
+        </Stack>
+        {copied && (
+          <span className="text-xs text-success">Copied to clipboard.</span>
+        )}
+        {error && <span className="text-xs text-error">{error.message}</span>}
+        {!copied && !error && (
+          <span className="text-xs text-muted-foreground">
+            Click Copy. If the browser blocks it, you'll see the error here.
+          </span>
+        )}
+      </Stack>
+    );
+  },
+};