Fix useDebouncedEvent pending calls surviving unmount and delay changes

[Copilot]

Problem

useDebouncedEvent wraps lodash/debounce but never cleans up the instance it creates, and it hides cancel() and flush(). As a result:

• A call pending at unmount fires delay ms later, after the component is gone.
• A delay change replaces the debounced instance but leaves the old one's pending call to fire later.
• Callers can't drop a pending call, for example a dialog that resets its state on close. They have to call the debounced function again with a neutral value instead.

Solution

• Cleanup: the layout effect that creates the debounced function now returns a cleanup that flushes the pending call. On unmount or delay change, the pending call runs immediately instead of delay ms later.
• cancel/flush: the returned callback is still referentially stable, and now carries cancel() and flush(). Both delegate to the current debounced instance.
• Types: the return type is a local DebouncedEvent<Args, Return> interface, so ra-core's public API does not depend on lodash typings.

const update = useDebouncedEvent(setValue, 300);
update(text);
// later, e.g. on dialog close
update.cancel();

This is backward compatible: the return value is still callable with the same signature, and only gains two properties.

How To Test

Run yarn jest packages/ra-core/src/util/useDebouncedEvent. The spec uses fake timers to check:

• the callback fires after the delay
• cancel() drops a pending call
• flush() runs a pending call immediately, and only once
• unmount flushes a pending call
• a delay change flushes a pending call

Additional Checks

• The PR targets master for a bugfix or a documentation fix, or next for a feature
• The PR includes unit tests (if not possible, describe why)
• The PR includes one or several stories (if not possible, describe why). N/A: this is a headless hook with no UI.
• The documentation is up to date. cancel/flush are not documented yet.

Also, please make sure to read the contributing guidelines.

• Fixes useDebouncedEvent: pending calls can't be cancelled, and survive unmount #11399

What & why: useDebouncedEvent now exposes cancel()/flush() and flushes a pending call on unmount or delay change, so callers can drop pending calls and no call fires late.
Risk: 🔴 High (public API of ra-core: hook return type and cleanup behavior change)
Start with: the useLayoutEffect cleanup in packages/ra-core/src/util/useDebouncedEvent.ts, which decides what happens to a pending call.

🎯 Intent

A debounced callback from useDebouncedEvent can be cancelled (or flushed),
and a pending call does not run after the component unmounts.

Source: #11399 (provided by dev)

🧭 Non-obvious decisions

• Flush instead of cancel on cleanup, which departs from the issue's proposed fix: FilterLiveForm's setFilters lives in the ListContext, which outlives the form. Cancelling dropped a filter typed less than debounce ms before the filter form unmounts. Flushing runs the call during unmount, never delay ms after.
• Callers who want to drop the pending call must call cancel() from an event handler: a cancel() in the caller's own cleanup runs after the hook's flush.
• Local DebouncedEvent interface instead of lodash's DebouncedFunc: keeps @types/lodash out of ra-core's public types and removes the as unknown as cast on the placeholder ref.

🧪 Tests

• Verified: yarn jest packages/ra-core/src/util/useDebouncedEvent: 1 suite, 5 tests passed
• Verified: yarn jest packages/ra-core/src/util/useDebouncedEvent packages/ra-core/src/form/FilterLiveForm: 2 suites passed (before the spec refactor)
• Verified: yarn jest packages/ra-core/src/util/useDebouncedEvent packages/ra-core/src/form/FilterLiveForm packages/ra-ui-materialui/src/list/filter (before the type refactor): 8 suites, 56 tests passed
• Verified: npx tsc --noEmit -p packages/ra-core and npx eslint on both files: no errors
• Not verified: full test suite, e2e

💥 Impact if wrong

• Who: FilterLiveForm (all list filter forms), and apps that import useDebouncedEvent
• Worst case: list filters typed just before closing the filter form are lost, or applied twice
• Rollback: revert the PR

📖 Docs to update

• useDebouncedEvent has no page in docs/ or docs_headless/; cancel/flush are undocumented.

🤖 AI

• Model: claude-opus-5-5. Wrote: code, tests, description (on top of the Copilot commits)
• Checkout: git fetch origin copilot/fix-usedebouncedevent-cancel-flush && git switch copilot/fix-usedebouncedevent-cancel-flush
• Test: yarn install && yarn jest packages/ra-core/src/util/useDebouncedEvent packages/ra-core/src/form/FilterLiveForm packages/ra-ui-materialui/src/list/filter && npx tsc --noEmit -p packages/ra-core
• Review: check the diff against 🎯 Intent and each 🧭 decision, then the cleanup order on unmount: the hook's layout-effect flush runs before FilterLiveForm's watch unsubscribe, so setFilters must still be safe to call at that point.

🤖 Generated with Claude Code

[fzaninotto]

@copilot fix the ci failures