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

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

@@ -0,0 +1,114 @@
+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("resets copied to false when a later copy fails", async () => {
+    const failure = new Error("denied");
+    const { result } = renderHook(() => useClipboard());
+
+    act(() => result.current.copy("first"));
+    await waitFor(() => expect(result.current.copied).toBe(true));
+
+    writeText.mockRejectedValueOnce(failure);
+    act(() => result.current.copy("second"));
+
+    await waitFor(() => expect(result.current.error).toBe(failure));
+    expect(result.current.copied).toBe(false);
+  });
+
+  it("resets copied to false when clipboard becomes unavailable", async () => {
+    const { result } = renderHook(() => useClipboard());
+
+    act(() => result.current.copy("first"));
+    await waitFor(() => expect(result.current.copied).toBe(true));
+
+    Object.defineProperty(navigator, "clipboard", {
+      value: undefined,
+      configurable: true,
+    });
+
+    act(() => result.current.copy("second"));
+
+    expect(result.current.copied).toBe(false);
+    expect(result.current.error?.message).toMatch(/not supported/);
+  });
+
+  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,70 @@
+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) {
+      if (timeoutRef.current) window.clearTimeout(timeoutRef.current);
+      setCopied(false);
+      setError(new Error("useClipboard: navigator.clipboard is not supported"));
+      return;
+    }
+    navigator.clipboard
+      .writeText(value)
+      .then(() => {
+        setError(null);
+        handleCopyResult(true);
+      })
+      .catch((err: Error) => {
+        if (timeoutRef.current) window.clearTimeout(timeoutRef.current);
+        setCopied(false);
+        setError(err);
+      });
+  };
+
+  const reset = () => {
+    setCopied(false);
+    setError(null);
+    if (timeoutRef.current) window.clearTimeout(timeoutRef.current);
+  };
+
+  return { copy, reset, error, copied };
+}

package/src/hooks/use-debounce-callback/index.ts

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

package/src/hooks/use-debounce-callback/use-debounced-callback.stories.tsx

@@ -0,0 +1,184 @@
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { Input } from "../../components";
+import {
+  createToastManager,
+  ToastProvider,
+  toast,
+} from "../../components/toast";
+import { useDebouncedCallback } from "./use-debounced-callback";
+
+const toastManager = createToastManager();
+
+type Args = { delay: number };
+
+const meta: Meta<Args> = {
+  title: "hooks/useDebouncedCallback",
+  argTypes: {
+    delay: {
+      control: { type: "range", min: 100, max: 3000, step: 100 },
+      description: "Debounce delay in milliseconds.",
+    },
+  },
+  args: { delay: 600 },
+  parameters: {
+    docs: {
+      description: {
+        component: [
+          "Returns a stable debounced wrapper around `callback` with controls.",
+          "",
+          "**Signature**: `[debounced, { cancel, flush, isPending }] = useDebouncedCallback(callback, delay)`",
+          "",
+          "- `cancel()` — discard the pending call without invoking.",
+          "- `flush()` — invoke the pending call immediately.",
+          "- `isPending` — reactive boolean, `true` while a call is scheduled.",
+          "",
+          "The wrapper has a **stable identity** — it is only recreated when `delay` changes,",
+          "never when `callback` changes. Inline arrow functions are safe to pass.",
+        ].join("\n"),
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <ToastProvider>
+        <Story />
+      </ToastProvider>
+    ),
+  ],
+};
+
+export default meta;
+
+export const Basic: StoryObj<Args> = {
+  render: ({ delay }) => {
+    const [handleSearch, { isPending, cancel, flush }] = useDebouncedCallback(
+      (value: string) => {
+        toast({
+          description: `Fired with: "${value}"`,
+        });
+      },
+      delay,
+    );
+
+    return (
+      <div className="flex max-w-sm flex-col gap-4">
+        <Input
+          onValueChange={(value) => handleSearch(value)}
+          placeholder="Type to trigger the debounced callback..."
+        />
+        <div className="overflow-hidden rounded-lg border border-slate-800 bg-slate-900 font-mono text-sm">
+          <div className="border-b border-slate-800 bg-slate-800/60 px-4 py-2 font-sans text-xs font-semibold uppercase tracking-widest text-slate-400">
+            State
+          </div>
+          <div className="px-4 py-2.5">
+            <span className="text-slate-500">status</span>
+            <span className="ml-4">
+              <span
+                className={isPending ? "text-yellow-300" : "text-slate-500"}
+              >
+                {isPending ? "pending" : "idle"}
+              </span>
+            </span>
+          </div>
+        </div>
+        <div className="flex gap-2">
+          <button
+            type="button"
+            onClick={cancel}
+            disabled={!isPending}
+            className="rounded border border-slate-300 px-3 py-1.5 text-sm text-slate-600 hover:bg-slate-50 disabled:cursor-not-allowed disabled:opacity-40"
+          >
+            Cancel
+          </button>
+          <button
+            type="button"
+            onClick={flush}
+            disabled={!isPending}
+            className="rounded border border-slate-300 px-3 py-1.5 text-sm text-slate-600 hover:bg-slate-50 disabled:cursor-not-allowed disabled:opacity-40"
+          >
+            Flush
+          </button>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const DifferentDelays: StoryObj<Args> = {
+  parameters: {
+    controls: { exclude: ["delay"] },
+  },
+  render: () => {
+    const [
+      handleFast,
+      { isPending: fastPending, cancel: cancelFast, flush: flushFast },
+    ] = useDebouncedCallback((value: string) => {
+      toastManager.add({
+        variant: "success",
+        description: `Fast (200ms): "${value}"`,
+      });
+    }, 200);
+
+    const [
+      handleSlow,
+      { isPending: slowPending, cancel: cancelSlow, flush: flushSlow },
+    ] = useDebouncedCallback((value: string) => {
+      toastManager.add({
+        variant: "success",
+        description: `Slow (1000ms): "${value}"`,
+      });
+    }, 1000);
+
+    return (
+      <div className="flex max-w-sm flex-col gap-6">
+        {[
+          {
+            label: "Fast — 200ms",
+            handler: handleFast,
+            pending: fastPending,
+            cancel: cancelFast,
+            flush: flushFast,
+          },
+          {
+            label: "Slow — 1000ms",
+            handler: handleSlow,
+            pending: slowPending,
+            cancel: cancelSlow,
+            flush: flushSlow,
+          },
+        ].map(({ label, handler, pending, cancel, flush }) => (
+          <div key={label} className="flex flex-col gap-2">
+            <p className="text-sm font-medium text-slate-700">{label}</p>
+            <Input
+              onValueChange={(value) => handler(value)}
+              placeholder="Type..."
+            />
+            <div className="flex items-center gap-3">
+              <span
+                className={`text-xs font-mono ${pending ? "text-yellow-500" : "text-slate-400"}`}
+              >
+                {pending ? "pending" : "idle"}
+              </span>
+              <button
+                type="button"
+                onClick={cancel}
+                disabled={!pending}
+                className="rounded border border-slate-300 px-2.5 py-1 text-xs text-slate-600 hover:bg-slate-50 disabled:opacity-40"
+              >
+                Cancel
+              </button>
+              <button
+                type="button"
+                onClick={flush}
+                disabled={!pending}
+                className="rounded border border-slate-300 px-2.5 py-1 text-xs text-slate-600 hover:bg-slate-50 disabled:opacity-40"
+              >
+                Flush
+              </button>
+            </div>
+          </div>
+        ))}
+      </div>
+    );
+  },
+};

package/src/hooks/use-debounce-callback/use-debounced-callback.test.ts

@@ -0,0 +1,296 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useDebouncedCallback } from "./use-debounced-callback";
+
+describe("useDebouncedCallback", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  // --- Return shape ---
+
+  it("returns a tuple [debounced, controls]", () => {
+    const cb = vi.fn();
+    const { result } = renderHook(() => useDebouncedCallback(cb, 200));
+    const [debounced, controls] = result.current;
+    expect(typeof debounced).toBe("function");
+    expect(typeof controls.cancel).toBe("function");
+    expect(typeof controls.flush).toBe("function");
+    expect(typeof controls.isPending).toBe("boolean");
+  });
+
+  // --- Stability ---
+
+  it("returns a stable debounced function reference across re-renders", () => {
+    const cb = vi.fn();
+    const { result, rerender } = renderHook(() =>
+      useDebouncedCallback(cb, 200),
+    );
+    const [first] = result.current;
+    rerender();
+    const [second] = result.current;
+    expect(second).toBe(first);
+  });
+
+  it("inline callback does not reset debounced wrapper (stable reference with inline fn)", () => {
+    const { result, rerender } = renderHook(() =>
+      // inline arrow fn — identity changes every render
+      useDebouncedCallback(() => {}, 200),
+    );
+    const [first] = result.current;
+    rerender();
+    const [second] = result.current;
+    expect(second).toBe(first);
+  });
+
+  it("callback identity change does not reset a pending timer", () => {
+    const cbA = vi.fn();
+    const cbB = vi.fn();
+    let currentCb = cbA;
+
+    const { result, rerender } = renderHook(() =>
+      useDebouncedCallback(currentCb, 300),
+    );
+
+    act(() => {
+      const [debouncedFn] = result.current;
+      debouncedFn("arg");
+    });
+
+    // swap callback mid-flight
+    currentCb = cbB;
+    rerender();
+
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    // timer should have fired exactly once with the latest callback
+    expect(cbA).not.toHaveBeenCalled();
+    expect(cbB).toHaveBeenCalledOnce();
+    expect(cbB).toHaveBeenCalledWith("arg");
+  });
+
+  it("delay change recreates the debounced function", () => {
+    const cb = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ delay }) => useDebouncedCallback(cb, delay),
+      { initialProps: { delay: 200 } },
+    );
+    const [first] = result.current;
+    rerender({ delay: 400 });
+    const [second] = result.current;
+    expect(second).not.toBe(first);
+  });
+
+  it("cancel and flush have stable references across re-renders", () => {
+    const cb = vi.fn();
+    const { result, rerender } = renderHook(() =>
+      useDebouncedCallback(cb, 200),
+    );
+    const [, { cancel: cancel1, flush: flush1 }] = result.current;
+    rerender();
+    const [, { cancel: cancel2, flush: flush2 }] = result.current;
+    expect(cancel2).toBe(cancel1);
+    expect(flush2).toBe(flush1);
+  });
+
+  // --- Basic debounce behavior ---
+
+  it("does not call callback before delay elapses", () => {
+    const cb = vi.fn();
+    const { result } = renderHook(() => useDebouncedCallback(cb, 300));
+
+    act(() => {
+      const [debouncedFn] = result.current;
+      debouncedFn("a");
+    });
+
+    vi.advanceTimersByTime(299);
+    expect(cb).not.toHaveBeenCalled();
+  });
+
+  it("calls callback after delay with correct args", () => {
+    const cb = vi.fn();
+    const { result } = renderHook(() => useDebouncedCallback(cb, 300));
+
+    act(() => {
+      const [debouncedFn] = result.current;
+      debouncedFn("hello", 42);
+    });
+
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    expect(cb).toHaveBeenCalledOnce();
+    expect(cb).toHaveBeenCalledWith("hello", 42);
+  });
+
+  it("resets the timer on consecutive calls (debounce behavior)", () => {
+    const cb = vi.fn();
+    const { result } = renderHook(() => useDebouncedCallback(cb, 300));
+
+    act(() => {
+      const [debouncedFn] = result.current;
+      debouncedFn("first");
+      vi.advanceTimersByTime(200);
+      debouncedFn("second");
+      vi.advanceTimersByTime(200);
+    });
+
+    expect(cb).not.toHaveBeenCalled();
+
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+
+    expect(cb).toHaveBeenCalledOnce();
+    expect(cb).toHaveBeenCalledWith("second");
+  });
+
+  it("invokes callback multiple times when enough time passes between calls", () => {
+    const cb = vi.fn();
+    const { result } = renderHook(() => useDebouncedCallback(cb, 100));
+
+    act(() => {
+      const [debouncedFn] = result.current;
+      debouncedFn("a");
+      vi.advanceTimersByTime(200);
+      debouncedFn("b");
+      vi.advanceTimersByTime(200);
+    });
+
+    expect(cb).toHaveBeenCalledTimes(2);
+    expect(cb).toHaveBeenNthCalledWith(1, "a");
+    expect(cb).toHaveBeenNthCalledWith(2, "b");
+  });
+
+  // --- isPending ---
+
+  it("isPending is false initially", () => {
+    const { result } = renderHook(() => useDebouncedCallback(vi.fn(), 300));
+    const [, { isPending }] = result.current;
+    expect(isPending).toBe(false);
+  });
+
+  it("isPending becomes true after call, false after delay elapses", () => {
+    const cb = vi.fn();
+    const { result } = renderHook(() => useDebouncedCallback(cb, 300));
+
+    act(() => {
+      const [debouncedFn] = result.current;
+      debouncedFn("x");
+    });
+
+    expect(result.current[1].isPending).toBe(true);
+
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    expect(result.current[1].isPending).toBe(false);
+  });
+
+  // --- cancel ---
+
+  it("cancel() stops pending invocation and sets isPending to false", () => {
+    const cb = vi.fn();
+    const { result } = renderHook(() => useDebouncedCallback(cb, 300));
+
+    act(() => {
+      const [debouncedFn] = result.current;
+      debouncedFn("x");
+    });
+
+    expect(result.current[1].isPending).toBe(true);
+
+    act(() => {
+      result.current[1].cancel();
+    });
+
+    expect(result.current[1].isPending).toBe(false);
+
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    expect(cb).not.toHaveBeenCalled();
+  });
+
+  // --- flush ---
+
+  it("flush() invokes callback immediately with last args and sets isPending to false", () => {
+    const cb = vi.fn();
+    const { result } = renderHook(() => useDebouncedCallback(cb, 300));
+
+    act(() => {
+      const [debouncedFn] = result.current;
+      debouncedFn("flush-arg");
+    });
+
+    expect(result.current[1].isPending).toBe(true);
+
+    act(() => {
+      result.current[1].flush();
+    });
+
+    expect(cb).toHaveBeenCalledOnce();
+    expect(cb).toHaveBeenCalledWith("flush-arg");
+    expect(result.current[1].isPending).toBe(false);
+  });
+
+  it("flush() is a no-op when nothing is pending", () => {
+    const cb = vi.fn();
+    const { result } = renderHook(() => useDebouncedCallback(cb, 300));
+
+    act(() => {
+      result.current[1].flush();
+    });
+
+    expect(cb).not.toHaveBeenCalled();
+  });
+
+  // --- Unmount cleanup ---
+
+  it("unmount cancels pending timer — callback not called after unmount", () => {
+    const cb = vi.fn();
+    const { result, unmount } = renderHook(() => useDebouncedCallback(cb, 300));
+
+    act(() => {
+      const [debouncedFn] = result.current;
+      debouncedFn("will-be-cancelled");
+    });
+
+    unmount();
+
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    expect(cb).not.toHaveBeenCalled();
+  });
+
+  it("isPending is false after unmount (no setState after unmount)", () => {
+    const cb = vi.fn();
+    const { result, unmount } = renderHook(() => useDebouncedCallback(cb, 300));
+
+    act(() => {
+      const [debouncedFn] = result.current;
+      debouncedFn("x");
+    });
+
+    expect(result.current[1].isPending).toBe(true);
+
+    expect(() => {
+      unmount();
+      act(() => {
+        vi.advanceTimersByTime(300);
+      });
+    }).not.toThrow();
+  });
+});