refactor(debounce): stabilize callback ref, add dispose, tidy tests

- useDebouncedCallback: hold latest callback in a ref so inline arrows
  no longer drop pending timers; normalize edges via booleans so array
  reference/order changes don't recreate the debounced instance
- debounce: add dispose() to detach the external signal abort listener
  via an internal AbortController, short-circuit schedule() when there
  is nothing to do, and switch Reflect.apply to func.apply
- tests: parameterize validation and "no-op from terminal state"
  matrices with it.for, add retention/dispose/edges-identity cases,
  and cover the maxWait forced-fire branch; 100% coverage on both files

Author: devmgn

src/hooks/useDebouncedCallback/useDebouncedCallback.test.ts

@@ -237,4 +237,89 @@ describe(useDebouncedCallback, () => {
     rerender({ wait: 500 });
     expect(result.current).toBe(prev);
   });
+
+  it("毎レンダリングで新しいアロー関数を渡しても保留中のタイマーと引数が失われず、最新のコールバックで発火すること", () => {
+    const spy = vi.fn();
+    let current = 0;
+    const { result, rerender } = renderHook(
+      ({ value }) =>
+        useDebouncedCallback((arg: string) => {
+          spy(value, arg);
+        }, 500),
+      { initialProps: { value: current } },
+    );
+
+    // 最初の呼び出しでタイマー開始
+    const first = result.current;
+    act(() => {
+      first("args");
+    });
+
+    // value を更新して再レンダリング。ここで debounced が再生成されると
+    // タイマーが失われてしまう。
+    current = 1;
+    rerender({ value: current });
+
+    // 同一の debounced 関数が返り続けること
+    expect(result.current).toBe(first);
+
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+
+    // 最新の callback (value=1) で、保持された引数 "args" で発火する
+    expect(spy).toHaveBeenCalledExactlyOnceWith(1, "args");
+  });
+
+  it("options.edges の配列参照が毎レンダリング変わっても、内容が同じなら同一 debounced 関数が返ること", () => {
+    const callback = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ edges }) =>
+        useDebouncedCallback(callback, 500, {
+          edges,
+        }),
+      { initialProps: { edges: ["leading"] as Array<"leading" | "trailing"> } },
+    );
+
+    const prev = result.current;
+    // 内容は同じで新しい配列参照を渡す
+    rerender({
+      edges: ["leading"] as Array<"leading" | "trailing">,
+    });
+
+    expect(result.current).toBe(prev);
+  });
+
+  it("edges が undefined と ['trailing'] (default 相当) で同一 debounced を返すこと", () => {
+    const callback = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ edges }: { edges: Array<"leading" | "trailing"> | undefined }) =>
+        useDebouncedCallback(callback, 500, { edges }),
+      {
+        initialProps: {
+          edges: undefined as Array<"leading" | "trailing"> | undefined,
+        },
+      },
+    );
+
+    const prev = result.current;
+    rerender({ edges: ["trailing"] });
+    expect(result.current).toBe(prev);
+  });
+
+  it("edges の順序が異なっても内容が同じなら同一 debounced を返すこと", () => {
+    const callback = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ edges }) => useDebouncedCallback(callback, 500, { edges }),
+      {
+        initialProps: {
+          edges: ["leading", "trailing"] as Array<"leading" | "trailing">,
+        },
+      },
+    );
+
+    const prev = result.current;
+    rerender({ edges: ["trailing", "leading"] });
+    expect(result.current).toBe(prev);
+  });
 });

src/hooks/useDebouncedCallback/useDebouncedCallback.ts

@@ -1,25 +1,50 @@
 import type { DebounceOptions } from "../../utils/debounce";
-import { useEffect, useMemo } from "react";
+import { useEffect, useMemo, useRef } from "react";
 import { debounce } from "../../utils/debounce";
 
 /**
- * `callback` と `options` は安定参照で渡すこと。毎レンダーで新しい参照を渡すと
- * `useMemo` が再計算され、保留中のタイマーと leading クールダウン状態が失われる。
- * `options` が静的な場合はコンポーネント外か `useMemo` で固定する。
+ * 最新の `callback` 参照を ref で保持することで、インラインのアロー関数を渡しても
+ * 保留中のタイマー・leading クールダウン状態が失われないようにする。
+ * debounced 関数は `wait`/`edges`/`signal`/`maxWait` が変化したときだけ再生成される。
+ * `edges` は boolean 正規化しているため `undefined` と `["trailing"]`、
+ * `["leading","trailing"]` と `["trailing","leading"]` はそれぞれ同じ扱いになる。
  */
 export function useDebouncedCallback<Args extends unknown[]>(
   callback: (...args: Args) => void,
   wait: number,
   options?: DebounceOptions,
 ) {
-  const debouncedFn = useMemo(
-    () => debounce(callback, wait, options),
-    [callback, options, wait],
-  );
+  const callbackRef = useRef(callback);
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+
+  const rawEdges = options?.edges;
+  // debounce 側 default (["trailing"]) と整合させる
+  const hasLeading = rawEdges?.includes("leading") ?? false;
+  const hasTrailing = rawEdges?.includes("trailing") ?? true;
+  const signal = options?.signal;
+  const maxWait = options?.maxWait;
+
+  const debouncedFn = useMemo(() => {
+    const invokeLatest = (...args: Args) => {
+      callbackRef.current(...args);
+    };
+    const edges: Array<"leading" | "trailing"> = [];
+    if (hasLeading) {
+      edges.push("leading");
+    }
+    if (hasTrailing) {
+      edges.push("trailing");
+    }
+    // ref は debounce のタイマーから非同期に読まれるだけで、レンダリング中には評価しない
+    // oxlint-disable-next-line react-compiler-rules/refs
+    return debounce(invokeLatest, wait, { edges, signal, maxWait });
+  }, [hasLeading, hasTrailing, maxWait, signal, wait]);
 
   useEffect(() => {
     return () => {
-      debouncedFn.cancel();
+      debouncedFn.dispose();
     };
   }, [debouncedFn]);