[WB-2281] Address feedback

Author: tony-dinh

__docs__/wonder-blocks-timing/use-animation-frame.mdx

@@ -34,28 +34,12 @@ Notes:
 
 - Because `clear` takes a param, it's important that you don't pass it directly to an event handler,
   e.g. `<Button onClick={clear} />` will not work as expected.
-- Unlike `useTimeout` and `useInterval`, each frame fires **once**. To create a continuous animation loop, call `set()` again inside the action.
+- Unlike `useInterval`, each frame fires **once**. Calling `set()` again schedules another single frame.
 - When the component using this hook is unmounted, the pending request will automatically be cleared.
 - Calling `set()` when a request is already pending cancels the existing request and makes a new one.
 
-## Immediately (default)
-
-With the default `SchedulePolicy.Immediately`, the frame fires automatically on
-mount — useful for deferring a one-time DOM read/write to just before the first
-paint:
-
 <Canvas sourceState="shown" of={UseAnimationFrameStories.Immediately} />
 
-## Animation loop (OnDemand + Resolve on clear)
-
-The most common pattern — a loop that starts on demand and fires one final
-callback on stop via `ClearPolicy.Resolve`, useful for settling animation state
-cleanly before halting:
-
 <Canvas sourceState="shown" of={UseAnimationFrameStories.OnDemandAndResolveOnClear} />
 
-## One-shot
-
-Use `SchedulePolicy.OnDemand` to defer a single unit of work to just before the next paint:
-
 <Canvas sourceState="shown" of={UseAnimationFrameStories.OneShot} />

__docs__/wonder-blocks-timing/use-animation-frame.stories.tsx

@@ -32,6 +32,12 @@ export const OnDemandAndResolveOnClear = () => {
     const [frameSet, setFrameSet] = React.useState(false);
     const runningRef = React.useRef(false);
 
+    // Clear the running flag before the animation frame cleanup fires so that
+    // ClearPolicy.Resolve's final callback doesn't re-schedule on unmount.
+    React.useEffect(() => () => {
+        runningRef.current = false;
+    }, []);
+
     const animationFrame = useAnimationFrame(
         () => {
             setFrameCount((n) => n + 1);

packages/wonder-blocks-timing/src/hooks/use-action-scheduler.ts

@@ -12,8 +12,10 @@ import ActionScheduler from "../util/action-scheduler";
  * All pending actions are automatically cleared when the component unmounts.
  *
  * @returns An `IScheduleActions` API for scheduling timeouts, intervals, and
- * animation frames. The returned API is stable across renders. All actions
- * scheduled via this API will be cleared when the component unmounts.
+ * animation frames. The returned API is stable across renders. This API is a
+ * no-op if called when not mounted — any calls prior to mounting or after
+ * unmounting will not have any effect. All actions scheduled via this API
+ * will be cleared when the component unmounts.
  *
  * @example
  * function MyComponent() {

packages/wonder-blocks-timing/src/hooks/use-animation-frame.ts

@@ -13,21 +13,7 @@ import AnimationFrame from "../util/animation-frame";
  * This makes it easier to use with inline lambda functions rather than
  * requiring consumers to wrap their action in a `useCallback`. To change
  * this behavior, see the `actionPolicy` option.
- * @param options Options for the hook.
- * @param options.actionPolicy Determines how the action is handled when it
- * changes. By default, the action is replaced but the request is not reset,
- * and the updated action will be invoked when the frame next fires.
- * If you want to reset the request when the action changes, use
- * `ActionPolicy.Reset`.
- * @param options.clearPolicy Determines how the request is cleared when the
- * component is unmounted or the request is recreated. By default, the
- * request is cancelled immediately. If you want to let the request run to
- * completion, use `ClearPolicy.Resolve`. This policy is also used as the
- * default when calling `clear()` manually with no argument. Pass an explicit
- * `ClearPolicy` to `clear(policy)` to override it for a specific call.
- * @param options.schedulePolicy Determines when the request is scheduled.
- * By default, the request is made immediately. If you want to delay
- * scheduling the request, use `SchedulePolicy.OnDemand`.
+ * @param options Options for the hook. See `HookOptions` for details.
  * @returns An `IAnimationFrame` API for interacting with the given request.
  * This API is a no-op if called when not mounted. This means that any calls
  * prior to mounting or after unmounting will not have any effect. This API is

packages/wonder-blocks-timing/src/util/types.ts

@@ -131,14 +131,35 @@ export interface IAnimationFrame {
  * Options for the scheduling APIs.
  */
 export type Options = {
+    /**
+     * Determines when the request is scheduled. By default, the request is
+     * made immediately on creation. Use `SchedulePolicy.OnDemand` to delay
+     * scheduling until `set()` is explicitly called.
+     */
     schedulePolicy?: Policies.SchedulePolicy;
+    /**
+     * Determines how the request is cleared when the component is unmounted
+     * or the request is recreated. By default, the request is cancelled
+     * immediately. Use `ClearPolicy.Resolve` to invoke the action one final
+     * time when the request is cleared. This policy is also used as the
+     * default when calling `clear()` manually with no argument — pass an
+     * explicit `ClearPolicy` to `clear(policy)` to override it for a
+     * specific call.
+     */
     clearPolicy?: Policies.ClearPolicy;
 };
 
 /**
  * Options for the hook variants of our scheduling APIs.
  */
 export type HookOptions = Options & {
+    /**
+     * Determines how the action is handled when it changes between renders.
+     * By default (`ActionPolicy.Passive`), the action is replaced but the
+     * request is not reset — the updated action will be invoked when the
+     * request next fires. Use `ActionPolicy.Reset` to cancel the current
+     * request and start a new one whenever the action changes.
+     */
     actionPolicy?: Policies.ActionPolicy;
 };