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

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

@@ -11,22 +11,103 @@ describe("useDebouncedCallback", () => {
     vi.useRealTimers();
   });
 
-  it("returns a stable function reference", () => {
+  // --- 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;
+    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();
-    expect(result.current).toBe(first);
+
+    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(() => {
-      result.current("a");
+      const [debouncedFn] = result.current;
+      debouncedFn("a");
     });
 
     vi.advanceTimersByTime(299);
@@ -38,7 +119,8 @@ describe("useDebouncedCallback", () => {
     const { result } = renderHook(() => useDebouncedCallback(cb, 300));
 
     act(() => {
-      result.current("hello", 42);
+      const [debouncedFn] = result.current;
+      debouncedFn("hello", 42);
     });
 
     act(() => {
@@ -54,9 +136,10 @@ describe("useDebouncedCallback", () => {
     const { result } = renderHook(() => useDebouncedCallback(cb, 300));
 
     act(() => {
-      result.current("first");
+      const [debouncedFn] = result.current;
+      debouncedFn("first");
       vi.advanceTimersByTime(200);
-      result.current("second");
+      debouncedFn("second");
       vi.advanceTimersByTime(200);
     });
 
@@ -75,9 +158,10 @@ describe("useDebouncedCallback", () => {
     const { result } = renderHook(() => useDebouncedCallback(cb, 100));
 
     act(() => {
-      result.current("a");
+      const [debouncedFn] = result.current;
+      debouncedFn("a");
       vi.advanceTimersByTime(200);
-      result.current("b");
+      debouncedFn("b");
       vi.advanceTimersByTime(200);
     });
 
@@ -85,4 +169,128 @@ describe("useDebouncedCallback", () => {
     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();
+  });
 });

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

@@ -1,22 +1,82 @@
-import { useCallback, useRef } from "react";
+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,
-): (...args: Parameters<T>) => void {
-  const timeoutRef = useRef<NodeJS.Timeout | null>(null);
+): 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);
 
-  return useCallback(
-    (...args: Parameters<T>) => {
-      if (timeoutRef.current) {
-        clearTimeout(timeoutRef.current);
-      }
+  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(() => {
-        callback(...args);
+        timeoutRef.current = null;
+        if (mountedRef.current) setIsPending(false);
+        cbRef.current(...args);
       }, delay);
     },
-    [callback, 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/use-debounced-value.stories.tsx

@@ -1,74 +1,274 @@
 import { Meta, StoryObj } from "@storybook/react-vite";
-import { useState } from "react";
-import { Input } from "../../components";
+import { useEffect, useState } from "react";
+import { Input, Kbd, KbdGroup } from "../../components";
+import { getHotkeyHandler } from "../use-hotkey";
 import { useDebouncedValue } from "./use-debounced-value";
 
-const meta: Meta = {
+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;
 
-export const Basic = {
-  render: () => {
-    const [value, setValue] = useState<string>("");
-    const debouncedValue: string = useDebouncedValue(value, 400);
+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="space-y-2">
-        <pre className="rounded-md bg-slate-950 p-4 text-white">
-          <code className="block">
-            Valor actual: <span className="text-blue-300">{value}</span>
-          </code>
-          <code className="block">
-            Valor debounced:{" "}
-            <span className="text-blue-300">{debouncedValue}</span>
-          </code>
-        </pre>
+      <div className="flex max-w-sm flex-col gap-4">
         <Input
           value={value}
-          onChange={setValue}
-          placeholder="Escribe algo..."
+          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 = {
+export const MultipleDelays: StoryObj<Args> = {
+  parameters: {
+    controls: { exclude: ["delay"] },
+  },
   render: () => {
-    const [value, setValue] = useState<string>("");
-    const debouncedFast: string = useDebouncedValue(value, 200);
-    const debouncedMedium: string = useDebouncedValue(value, 500);
-    const debouncedSlow: string = useDebouncedValue(value, 1000);
+    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="space-y-4">
+      <div className="flex max-w-sm flex-col gap-4">
         <Input
           value={value}
-          onChange={setValue}
-          placeholder="Escribe para ver diferentes delays..."
+          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 className="space-y-2">
-          <pre className="rounded-md bg-slate-950 p-4 text-white">
-            <code className="block">
-              Valor actual: <span className="text-blue-300">{value}</span>
-            </code>
-            <code className="block">
-              Debounced (200ms):{" "}
-              <span className="text-blue-300">{debouncedFast}</span>
-            </code>
-            <code className="block">
-              Debounced (500ms):{" "}
-              <span className="text-blue-300">{debouncedMedium}</span>
-            </code>
-            <code className="block">
-              Debounced (1000ms):{" "}
-              <span className="text-blue-300">{debouncedSlow}</span>
-            </code>
-          </pre>
-        </div>
       </div>
     );
   },