@mui/internal-docs-infra 0.11.1-canary.21 → 0.11.1-canary.22

package/useCoordinated/scheduleTasks.mjs

@@ -0,0 +1,45 @@
+// Internal task-scheduling primitives shared by the coordination/render-timing
+// code (and a few consumers that gate heavy work off the critical path). Kept
+// here rather than in a `*Utils` barrel so it stays an internal helper, not a
+// published API surface. Not re-exported from `index.ts`.
+
+/**
+ * Yield the current task back to the browser so it can paint and process input
+ * before the awaited continuation runs.
+ *
+ * Uses `scheduler.yield()` when available (modern Chromium) for better priority
+ * handling; falls back to `setTimeout(_, 0)`, which macrotask-defers in every
+ * browser, in Node/SSR, and in fake-timer test environments.
+ */
+export function yieldToMain() {
+  const {
+    scheduler
+  } = globalThis;
+  if (typeof scheduler?.yield === 'function') {
+    return scheduler.yield();
+  }
+  return new Promise(resolve => {
+    setTimeout(resolve, 0);
+  });
+}
+
+/**
+ * Run `task` during the browser's first idle period, falling back to
+ * `setTimeout(task, 0)` where `requestIdleCallback` is unavailable (Safari,
+ * Node/SSR, fake timers). Use this for genuinely deferrable background work
+ * (e.g. stale-while-revalidate refreshes, the `idle` highlight/enhance swap)
+ * that should wait for the main thread to be free.
+ *
+ * @param options.timeout forwarded to `requestIdleCallback` so the task still
+ *   runs even if the browser never goes idle.
+ * @returns a function that cancels the task if it has not run yet.
+ */
+export function requestIdle(task, options) {
+  const idleGlobals = globalThis;
+  if (idleGlobals.requestIdleCallback) {
+    const handle = idleGlobals.requestIdleCallback(task, options);
+    return () => idleGlobals.cancelIdleCallback?.(handle);
+  }
+  const handle = setTimeout(task, 0);
+  return () => clearTimeout(handle);
+}

package/useCoordinated/useCoordinated.mjs

@@ -59,7 +59,11 @@ export function useCoordinated(underlying, options) {
     lazyCommitPriority = 'idle'
   } = options;
 
-  // Stable peer id for the lifetime of the mounted component.
+  // Stable peer id for the lifetime of the mounted component. Held in a ref so an
+  // auto-generated fallback stays stable across renders, an explicit `peerId` prop
+  // wins and resyncs on change, and an explicit id later removed keeps the last
+  // explicit value. The registration effect keys off [channelKey, peerId].
+  /* eslint-disable react-hooks/refs -- deliberate stable-id ref: lazy init + explicit-prop resync during render; the ref is identity memory, never read for rendering output */
   const peerIdRef = React.useRef(null);
   if (peerIdRef.current === null) {
     peerIdRef.current = explicitPeerId ?? generatePeerId();
@@ -67,6 +71,7 @@ export function useCoordinated(underlying, options) {
     peerIdRef.current = explicitPeerId;
   }
   const peerId = peerIdRef.current;
+  /* eslint-enable react-hooks/refs */
 
   // The visible (committed) value. Lags `underlyingValue` while a
   // phase-1 barrier is open in the receiver flow.
@@ -84,10 +89,13 @@ export function useCoordinated(underlying, options) {
     onCommit,
     setUnderlyingValue
   });
+  /* eslint-disable react-hooks/refs -- latest-ref pattern: cache current callbacks for the once-registered peer and long-lived runCoordination closure; intentionally excluded from effect/useCallback deps to avoid re-registering on inline-function identity churn */
   callbacksRef.current.causesLayoutShift = causesLayoutShift;
   callbacksRef.current.preload = preload;
   callbacksRef.current.onCommit = onCommit;
   callbacksRef.current.setUnderlyingValue = setUnderlyingValue;
+  /* eslint-enable react-hooks/refs */
+
   const timingRef = React.useRef({
     minWaitMs,
     multiPeerExtraMinWaitMs,
@@ -97,6 +105,7 @@ export function useCoordinated(underlying, options) {
     animateDuringPreload,
     lazyCommitPriority
   });
+  /* eslint-disable react-hooks/refs -- latest-ref pattern: cache current timing options for the once-registered peer and long-lived runCoordination closure; intentionally excluded from effect/useCallback deps to avoid re-registering on option identity churn */
   timingRef.current.minWaitMs = minWaitMs;
   timingRef.current.multiPeerExtraMinWaitMs = multiPeerExtraMinWaitMs;
   timingRef.current.lazyMinWaitMs = lazyMinWaitMs;
@@ -104,6 +113,7 @@ export function useCoordinated(underlying, options) {
   timingRef.current.ultimateTimeoutMs = ultimateTimeoutMs;
   timingRef.current.animateDuringPreload = animateDuringPreload;
   timingRef.current.lazyCommitPriority = lazyCommitPriority;
+  /* eslint-enable react-hooks/refs */
 
   // In-flight handle so we can cancel/supersede.
   const handleRef = React.useRef(null);
@@ -291,9 +301,10 @@ export function useCoordinated(underlying, options) {
     } else if (!layoutShiftsSettled() && callbacksRef.current.causesLayoutShift(target)) {
       // No user preload, but the target shifts layout and the gate is still
       // closed: synthesize a preload that only awaits the gate so the commit
-      // still holds until the page settles (previously the gate was consulted
-      // only inside the user-preload wrapper, so a layout-shifting peer with
-      // no preload skipped coordination entirely). Once the gate has opened
+      // still holds until the page settles (the gate is otherwise consulted
+      // only inside the user-preload wrapper, so without this branch a
+      // layout-shifting peer with no preload would skip coordination entirely).
+      // Once the gate has opened
       // this branch is skipped, so steady-state layout-shifting commits keep
       // the synchronous fast path. The gate wait rejects `AbortError` on
       // supersede, which propagates into the engine's `await preload(...)`
@@ -365,6 +376,7 @@ export function useCoordinated(underlying, options) {
   // Keep the ref pointed at the latest `runCoordination` so the
   // peer-registration callback (set once at mount) always invokes
   // the current closure.
+  // eslint-disable-next-line react-hooks/refs -- forward-declared latest-ref: the once-registered peer callback must invoke the current runCoordination closure without re-registering
   runCoordinationRef.current = runCoordination;
 
   // Receiver flow: external `underlyingValue` change that we did not
@@ -376,11 +388,13 @@ export function useCoordinated(underlying, options) {
   // the originator's barrier window.
   React.useLayoutEffect(() => {
     if (channelKey === null) {
+      // Coordination disabled: the hook is a transparent pass-through,
+      // so the visible value / pending value are derived directly from
+      // `underlyingValue` at the return rather than mirrored into state.
+      // Only reset the in-flight ref here.
       inFlightTargetRef.current = {
         has: false
       };
-      setCommittedValue(underlyingValue);
-      setPendingValue(underlyingValue);
       return;
     }
     if (lastWrittenRef.current.has) {
@@ -419,6 +433,7 @@ export function useCoordinated(underlying, options) {
       // setter, the originator flow drives every cycle.
       return;
     }
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- receiver flow: runCoordination drives the coordination state machine in response to an external underlyingValue change; this is the genuine effect side-effect, not derivable during render
     runCoordination(underlyingValue, false);
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [channelKey, underlyingValue, runCoordination]);
@@ -438,5 +453,17 @@ export function useCoordinated(underlying, options) {
     isCoordinating,
     isWaitingForPeers
   }), [pendingValue, isCoordinating, isWaitingForPeers]);
+
+  // When coordination is disabled the hook is a transparent
+  // pass-through: derive the visible value, pending value, and inert
+  // coordination flags straight from `underlyingValue` rather than
+  // mirroring it into `committedValue` / `pendingValue` state.
+  if (channelKey === null) {
+    return [underlyingValue, coordinatedSetValue, {
+      pendingValue: underlyingValue,
+      isCoordinating: false,
+      isWaitingForPeers: false
+    }];
+  }
   return [committedValue, coordinatedSetValue, extras];
 }

package/useStream/useStream.mjs

@@ -3,6 +3,7 @@
 import * as React from 'react';
 import { streamChunks } from "./streamChunks.mjs";
 import { useStreamController } from "./useStreamController.mjs";
+import { requestIdle } from "../useCoordinated/scheduleTasks.mjs";
 
 /** Options for {@link useStream}. */
 
@@ -99,10 +100,7 @@ export function useStream(options) {
     if (!revalidateOnIdle || !streamComplete || typeof window === 'undefined') {
       return undefined;
     }
-    const requestIdle = window.requestIdleCallback ?? (callback => setTimeout(callback, 1));
-    const cancelIdle = window.cancelIdleCallback ?? clearTimeout;
-    const handle = requestIdle(() => refresh());
-    return () => cancelIdle(handle);
+    return requestIdle(() => refresh());
   }, [revalidateOnIdle, streamComplete, refresh]);
 
   // Loading until the list has finished streaming AND every rendered chunk has

package/useStream/useStreamController.mjs

@@ -52,7 +52,11 @@ export function useStreamController(options = {}) {
   React.useEffect(() => {
     // Chunks register in their own (child) effects, which run before this
     // (parent) effect - so by now the gate reflects every chunk present in the
-    // initial commit.
+    // initial commit. These setState calls cannot move to render: at render
+    // time the gate is still unarmed, so `gate.isSettled()` returns `true` and a
+    // render-time derivation would wrongly report 'done' immediately. Only after
+    // the child effects register does the gate reflect the initial-commit chunks.
+    /* eslint-disable react-hooks/set-state-in-effect -- gate.isSettled() only reflects child chunks after their (child) effects register them; this parent effect runs after, so the value is unavailable during render */
     if (gate.isSettled()) {
       setLoading(false);
       return undefined;
@@ -69,6 +73,7 @@ export function useStreamController(options = {}) {
     } else {
       setLoading(false);
     }
+    /* eslint-enable react-hooks/set-state-in-effect */
     return () => {
       cancelled = true;
     };