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

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

@@ -0,0 +1,82 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useLatestRef } from "../internal/use-latest-ref";
+
+export interface DebouncedControls {
+  /** Cancel the pending invocation without calling the callback. No-op if nothing is pending. */
+  cancel: () => void;
+  /** Immediately invoke the callback with the last queued arguments, clearing the timer. No-op if nothing is pending. */
+  flush: () => void;
+  /** Reactive boolean: `true` while a debounced call is scheduled, `false` otherwise. */
+  isPending: boolean;
+}
+
+/**
+ * Returns a debounced version of `callback` together with a controls object.
+ *
+ * The returned `debounced` function has a **stable identity** — it is only
+ * recreated when `delay` changes, never when `callback` changes. This means
+ * passing an inline arrow function is safe: it will not reset a pending timer
+ * on re-render.
+ *
+ * @returns `[debounced, { cancel, flush, isPending }]`
+ */
+export function useDebouncedCallback<T extends (...args: any[]) => any>(
+  callback: T,
+  delay: number,
+): readonly [(...args: Parameters<T>) => void, DebouncedControls] {
+  const cbRef = useLatestRef(callback);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const lastArgsRef = useRef<Parameters<T> | null>(null);
+  const mountedRef = useRef(true);
+  const [isPending, setIsPending] = useState(false);
+
+  const clear = useCallback(() => {
+    if (timeoutRef.current !== null) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+  }, []);
+
+  const debounced = useCallback(
+    (...args: Parameters<T>) => {
+      clear();
+      lastArgsRef.current = args;
+      setIsPending(true);
+      timeoutRef.current = setTimeout(() => {
+        timeoutRef.current = null;
+        if (mountedRef.current) setIsPending(false);
+        cbRef.current(...args);
+      }, delay);
+    },
+    [delay, clear, cbRef],
+  );
+
+  const cancel = useCallback(() => {
+    clear();
+    if (mountedRef.current) setIsPending(false);
+  }, [clear]);
+
+  const flush = useCallback(() => {
+    if (timeoutRef.current === null) return;
+    clear();
+    if (mountedRef.current) setIsPending(false);
+    if (lastArgsRef.current !== null) {
+      cbRef.current(...lastArgsRef.current);
+    }
+  }, [clear, cbRef]);
+
+  useEffect(
+    () => () => {
+      mountedRef.current = false;
+      clear();
+    },
+    [clear],
+  );
+
+  const controls = useMemo(
+    () => ({ cancel, flush, isPending }),
+    [cancel, flush, isPending],
+  );
+
+  return [debounced, controls] as const;
+}

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

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

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

@@ -0,0 +1,275 @@
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { useEffect, useState } from "react";
+import { Input, Kbd, KbdGroup } from "../../components";
+import { getHotkeyHandler } from "../use-hotkey";
+import { useDebouncedValue } from "./use-debounced-value";
+
+type Args = { delay: number };
+
+const meta: Meta<Args> = {
+  title: "hooks/useDebouncedValue",
+  argTypes: {
+    delay: {
+      control: { type: "range", min: 100, max: 5000, step: 100 },
+      description: "Debounce delay in milliseconds.",
+    },
+  },
+  args: { delay: 400 },
+  parameters: {
+    docs: {
+      description: {
+        component: [
+          "Returns the debounced version of `value` paired with controls.",
+          "",
+          "**Signature**: `[debounced, { cancel, flush, isPending }] = useDebouncedValue(value, delay)`",
+          "",
+          "- `cancel()` — discard the pending update without applying it.",
+          "- `flush()` — apply the pending update immediately.",
+          "- `isPending` — reactive boolean, `true` while an update is scheduled.",
+          "",
+          "Delegates entirely to `useDebouncedCallback` — no duplicated timer logic.",
+        ].join("\n"),
+      },
+    },
+  },
+};
+
+export default meta;
+
+function StatePanel({
+  rows,
+}: {
+  rows: { label: string; value: string; highlight?: "pending" | "idle" }[];
+}) {
+  return (
+    <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="divide-y divide-slate-800/60">
+        {rows.map(({ label, value, highlight }) => (
+          <div key={label} className="flex items-center gap-4 px-4 py-2.5">
+            <span className="w-28 shrink-0 text-slate-500">{label}</span>
+            <span
+              className={
+                highlight === "pending"
+                  ? "text-yellow-300"
+                  : highlight === "idle"
+                    ? "text-slate-500"
+                    : "text-blue-300"
+              }
+            >
+              {value || "—"}
+            </span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export const Basic: StoryObj<Args> = {
+  render: ({ delay }) => {
+    const [value, setValue] = useState("");
+    const [debouncedValue, { isPending, cancel }] = useDebouncedValue(
+      value,
+      delay,
+    );
+
+    return (
+      <div className="flex max-w-sm flex-col gap-4">
+        <Input
+          value={value}
+          onValueChange={setValue}
+          placeholder="Type something..."
+        />
+        <StatePanel
+          rows={[
+            { label: "input", value: value },
+            { label: "debounced", value: debouncedValue },
+            {
+              label: "status",
+              value: isPending ? "pending" : "idle",
+              highlight: isPending ? "pending" : "idle",
+            },
+          ]}
+        />
+        <button
+          type="button"
+          onClick={cancel}
+          disabled={!isPending}
+          className="self-start 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>
+      </div>
+    );
+  },
+};
+
+type PokemonResult = { name: string; sprite: string | null };
+
+export const AsyncSearch: StoryObj<Args> = {
+  args: { delay: 2000 },
+  name: "Flush & Cancel",
+  render: ({ delay }) => {
+    const [query, setQuery] = useState("");
+    const [debouncedQuery, { isPending, cancel, flush }] = useDebouncedValue(
+      query,
+      delay,
+    );
+    const [result, setResult] = useState<PokemonResult | null>(null);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState<string | null>(null);
+
+    useEffect(() => {
+      const name = debouncedQuery.trim().toLowerCase();
+      if (!name) {
+        setResult(null);
+        setError(null);
+        return;
+      }
+
+      let cancelled = false;
+      setLoading(true);
+      setError(null);
+
+      fetch(`https://pokeapi.co/api/v2/pokemon/${name}`)
+        .then((res) => {
+          if (!res.ok) throw new Error("not found");
+          return res.json() as Promise<{
+            name: string;
+            sprites: { front_default: string | null };
+          }>;
+        })
+        .then((data) => {
+          if (cancelled) return;
+          setResult({ name: data.name, sprite: data.sprites.front_default });
+          setLoading(false);
+        })
+        .catch(() => {
+          if (cancelled) return;
+          setError(`No Pokémon found for "${debouncedQuery}"`);
+          setResult(null);
+          setLoading(false);
+        });
+
+      return () => {
+        cancelled = true;
+      };
+    }, [debouncedQuery]);
+
+    return (
+      <div className="flex max-w-sm flex-col gap-4">
+        <div className="rounded-md border border-slate-200 bg-slate-50 px-4 py-3 text-sm text-slate-600 space-y-1.5">
+          <p>
+            Delay is <strong>2 s</strong>.
+          </p>
+          <p>
+            <KbdGroup>
+              <Kbd>Enter</Kbd>
+            </KbdGroup>{" "}
+            — <strong>flush</strong>: skip the wait, search right now.
+          </p>
+          <p>
+            <KbdGroup>
+              <Kbd>Esc</Kbd>
+            </KbdGroup>{" "}
+            — <strong>cancel</strong>: discard the pending update, no request
+            fires.
+          </p>
+        </div>
+
+        <Input
+          value={query}
+          onValueChange={setQuery}
+          onKeyDown={getHotkeyHandler([
+            ["enter", flush],
+            ["escape", cancel],
+          ])}
+          placeholder="pikachu, bulbasaur, ditto..."
+        />
+
+        <StatePanel
+          rows={[
+            { label: "input", value: query },
+            { label: "debounced", value: debouncedQuery },
+            {
+              label: "status",
+              value: isPending ? "pending" : "idle",
+              highlight: isPending ? "pending" : "idle",
+            },
+          ]}
+        />
+
+        {loading && <p className="text-sm text-slate-400">Fetching...</p>}
+
+        {error && (
+          <p className="rounded-md bg-red-50 px-3 py-2 text-sm text-red-600">
+            {error}
+          </p>
+        )}
+
+        {result && (
+          <div className="flex items-center gap-3 rounded-lg border border-slate-200 bg-white px-4 py-3">
+            {result.sprite && (
+              <img
+                src={result.sprite}
+                alt={result.name}
+                className="h-16 w-16 [image-rendering:pixelated]"
+              />
+            )}
+            <span className="font-medium capitalize text-slate-800">
+              {result.name}
+            </span>
+          </div>
+        )}
+      </div>
+    );
+  },
+};
+
+export const MultipleDelays: StoryObj<Args> = {
+  parameters: {
+    controls: { exclude: ["delay"] },
+  },
+  render: () => {
+    const [value, setValue] = useState("");
+    const [fast, { isPending: fastPending }] = useDebouncedValue(value, 200);
+    const [medium, { isPending: mediumPending }] = useDebouncedValue(
+      value,
+      500,
+    );
+    const [slow, { isPending: slowPending }] = useDebouncedValue(value, 1000);
+
+    return (
+      <div className="flex max-w-sm flex-col gap-4">
+        <Input
+          value={value}
+          onValueChange={setValue}
+          placeholder="Type to see different delays..."
+        />
+        <StatePanel
+          rows={[
+            { label: "input", value: value },
+            {
+              label: "200ms",
+              value: fast,
+              highlight: fastPending ? "pending" : undefined,
+            },
+            {
+              label: "500ms",
+              value: medium,
+              highlight: mediumPending ? "pending" : undefined,
+            },
+            {
+              label: "1000ms",
+              value: slow,
+              highlight: slowPending ? "pending" : undefined,
+            },
+          ]}
+        />
+      </div>
+    );
+  },
+};

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

@@ -0,0 +1,196 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useDebouncedValue } from "./use-debounced-value";
+
+describe("useDebouncedValue", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  // --- Return shape (v2: tuple) ---
+
+  it("returns a tuple [debounced, controls]", () => {
+    const { result } = renderHook(() => useDebouncedValue("init", 300));
+    const [debounced, controls] = result.current;
+    expect(debounced).toBe("init");
+    expect(typeof controls.cancel).toBe("function");
+    expect(typeof controls.flush).toBe("function");
+    expect(typeof controls.isPending).toBe("boolean");
+  });
+
+  it("debounced is initial value at mount", () => {
+    const { result } = renderHook(() => useDebouncedValue("init", 300));
+    const [debounced] = result.current;
+    expect(debounced).toBe("init");
+  });
+
+  // --- Debounce behavior (using tuple destructure) ---
+
+  it("debounced does not update before delay elapses", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useDebouncedValue(value, 300),
+      { initialProps: { value: "a" } },
+    );
+
+    rerender({ value: "b" });
+    act(() => {
+      vi.advanceTimersByTime(299);
+    });
+
+    const [debounced] = result.current;
+    expect(debounced).toBe("a");
+  });
+
+  it("debounced updates after delay elapses", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useDebouncedValue(value, 300),
+      { initialProps: { value: "a" } },
+    );
+
+    rerender({ value: "b" });
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    const [debounced] = result.current;
+    expect(debounced).toBe("b");
+  });
+
+  it("cancels pending update when value changes again before delay", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useDebouncedValue(value, 300),
+      { initialProps: { value: "a" } },
+    );
+
+    rerender({ value: "b" });
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+
+    rerender({ value: "c" });
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+
+    expect(result.current[0]).toBe("a");
+
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+
+    expect(result.current[0]).toBe("c");
+  });
+
+  it("works with non-string values", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useDebouncedValue(value, 100),
+      { initialProps: { value: 0 } },
+    );
+
+    rerender({ value: 42 });
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+
+    expect(result.current[0]).toBe(42);
+  });
+
+  // --- isPending ---
+
+  it("isPending is true while pending, false after update", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useDebouncedValue(value, 300),
+      { initialProps: { value: "a" } },
+    );
+
+    rerender({ value: "b" });
+
+    expect(result.current[1].isPending).toBe(true);
+
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    expect(result.current[1].isPending).toBe(false);
+  });
+
+  // --- cancel ---
+
+  it("cancel() stops pending value update", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useDebouncedValue(value, 300),
+      { initialProps: { value: "a" } },
+    );
+
+    rerender({ value: "b" });
+
+    act(() => {
+      result.current[1].cancel();
+    });
+
+    expect(result.current[1].isPending).toBe(false);
+
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    // value should still be "a" — update was cancelled
+    expect(result.current[0]).toBe("a");
+  });
+
+  // --- flush ---
+
+  it("flush() forces immediate value update", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useDebouncedValue(value, 300),
+      { initialProps: { value: "a" } },
+    );
+
+    rerender({ value: "b" });
+
+    act(() => {
+      result.current[1].flush();
+    });
+
+    expect(result.current[0]).toBe("b");
+    expect(result.current[1].isPending).toBe(false);
+  });
+
+  // --- Stable references ---
+
+  it("cancel and flush forwarded from inner hook — stable references", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useDebouncedValue(value, 300),
+      { initialProps: { value: "a" } },
+    );
+
+    const { cancel: c1, flush: f1 } = result.current[1];
+    rerender({ value: "a" });
+    const { cancel: c2, flush: f2 } = result.current[1];
+
+    expect(c2).toBe(c1);
+    expect(f2).toBe(f1);
+  });
+
+  // --- Unmount cleanup ---
+
+  it("unmount cancels pending timer (no setState after unmount)", () => {
+    const { rerender, unmount } = renderHook(
+      ({ value }) => useDebouncedValue(value, 300),
+      { initialProps: { value: "a" } },
+    );
+
+    rerender({ value: "b" });
+    unmount();
+
+    expect(() => {
+      act(() => {
+        vi.advanceTimersByTime(300);
+      });
+    }).not.toThrow();
+  });
+});

package/src/hooks/use-debounce-value/use-debounced-value.ts

@@ -0,0 +1,25 @@
+import { useEffect, useState } from "react";
+import type { DebouncedControls } from "../use-debounce-callback/use-debounced-callback";
+import { useDebouncedCallback } from "../use-debounce-callback/use-debounced-callback";
+
+/**
+ * Returns the debounced version of `value` together with a controls object.
+ *
+ * Delegates entirely to `useDebouncedCallback` — there is no duplicated timer
+ * logic in this hook.
+ *
+ * @returns `[debouncedValue, { cancel, flush, isPending }]`
+ */
+export function useDebouncedValue<T>(
+  value: T,
+  delay: number,
+): readonly [T, DebouncedControls] {
+  const [debounced, setDebounced] = useState<T>(value);
+  const [schedule, controls] = useDebouncedCallback(setDebounced, delay);
+
+  useEffect(() => {
+    schedule(value);
+  }, [value, schedule]);
+
+  return [debounced, controls] as const;
+}

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

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