@mui/internal-docs-infra 0.11.1-canary.8 → 0.11.1

package/useCoordinated/coordinatePreference.testUtils.d.mts

@@ -0,0 +1,21 @@
+/**
+ * Reset all module state between test cases. Production callers never
+ * need this; channels self-dispose when their last peer unregisters.
+ */
+export declare function resetCoordinatorsForTests(): void;
+/**
+ * Snapshot of channel/peer/barrier counts across all channels.
+ * Useful for asserting cleanup in tests.
+ */
+export declare function getCoordinatorStatsForTests(): {
+  channelCount: number;
+  totalPeers: number;
+  totalPendingBarriers: number;
+};
+/**
+ * Override the target encoder. Returns a function that restores the
+ * previous encoder. Useful when the value type contains unstable
+ * references that the default `JSON.stringify`-based encoder cannot
+ * key deterministically.
+ */
+export declare function setTargetEncoderForTests(impl: (value: unknown) => string): () => void;

package/useCoordinated/coordinatePreference.testUtils.mjs

@@ -0,0 +1,69 @@
+/**
+ * Test-only affordances for `coordinatePreference`. Kept in a sibling
+ * file so the production module's public surface (`registerPeer`,
+ * `announceTarget`, `reportValue`, `hasEverAnnounced`,
+ * `getBarrierAnnounceTime`) stays free of helpers that should never
+ * be reachable from runtime code or re-exported from the package
+ * entry.
+ *
+ * The implementation here reaches into `__testInternals` from
+ * `coordinatePreference.ts`. That export is the only sanctioned
+ * channel into module-private state and is marked `__`-prefixed so
+ * accidental imports are obvious in code review.
+ */
+import { __testInternals } from "./coordinatePreference.mjs";
+const {
+  channels,
+  setTargetEncoder
+} = __testInternals;
+
+/**
+ * Reset all module state between test cases. Production callers never
+ * need this; channels self-dispose when their last peer unregisters.
+ */
+export function resetCoordinatorsForTests() {
+  for (const channel of channels.values()) {
+    for (const barrier of channel.pendingBarriers.values()) {
+      clearTimeout(barrier.minWaitTimer);
+      clearTimeout(barrier.waitingForPeersTimer);
+      clearTimeout(barrier.ultimateTimer);
+      for (const waiter of barrier.waiters.values()) {
+        waiter.abort.abort();
+      }
+    }
+    for (const peer of channel.peers.values()) {
+      for (const controller of peer.lazyInFlight.keys()) {
+        controller.abort();
+      }
+    }
+  }
+  channels.clear();
+}
+
+/**
+ * Snapshot of channel/peer/barrier counts across all channels.
+ * Useful for asserting cleanup in tests.
+ */
+export function getCoordinatorStatsForTests() {
+  let totalPeers = 0;
+  let totalPendingBarriers = 0;
+  for (const channel of channels.values()) {
+    totalPeers += channel.peers.size;
+    totalPendingBarriers += channel.pendingBarriers.size;
+  }
+  return {
+    channelCount: channels.size,
+    totalPeers,
+    totalPendingBarriers
+  };
+}
+
+/**
+ * Override the target encoder. Returns a function that restores the
+ * previous encoder. Useful when the value type contains unstable
+ * references that the default `JSON.stringify`-based encoder cannot
+ * key deterministically.
+ */
+export function setTargetEncoderForTests(impl) {
+  return setTargetEncoder(impl);
+}

package/useCoordinated/createSettleGate.d.mts

@@ -0,0 +1,96 @@
+/**
+ * Fallback ceiling for {@link createSettleGate}: if a registered source never
+ * settles (its swap errored or hung), the gate opens anyway after this many
+ * milliseconds so coordination can never be blocked forever. Matches the
+ * coordinator's default `ultimateTimeoutMs` and the value the module-global
+ * `layoutShiftGate` shipped with.
+ */
+export declare const SETTLE_SAFETY_TIMEOUT_MS = 10000;
+/**
+ * A reusable "all sources settled" gate.
+ *
+ * The module-global page-wide layout-shift gate (`layoutShiftGate`) is one
+ * instance; each `StreamController` and `CoordinatedLazy` swap registers with
+ * one too. The behavior is the original layout-shift gate's, plus two opt-in
+ * completion signals (`expect` / `markLast`) for sources that arrive over time
+ * (chunks streaming in across ticks) rather than all within the initial
+ * hydration commit.
+ *
+ * Lifecycle: a source `register()`s and later calls the returned settle
+ * function when it reaches its stable state. The gate opens once every
+ * registered source has settled (and any completion constraint is met). It
+ * opens **once** and never re-closes - a source that registers after the gate
+ * has opened adopts the open state rather than re-closing it for everyone
+ * ("all sources" means "all present by the initial settle").
+ */
+export interface SettleGate {
+  /**
+   * Register a pending source. Returns an idempotent settle function; call it
+   * when the source reaches its stable state. Calling it more than once is a
+   * no-op. Registering after the gate has already opened returns a no-op settle
+   * and does not re-close the gate.
+   */
+  register(): () => void;
+  /**
+   * `true` before any source registers (nothing to wait for) and once every
+   * registered source has settled and any completion constraint is met.
+   */
+  isSettled(): boolean;
+  /**
+   * Resolves once {@link isSettled} is `true`. Returns `null` synchronously
+   * when already settled so callers can take a fast path (mirrors the original
+   * `whenLayoutShiftsSettled`). Rejects with an `AbortError` if `signal` aborts
+   * first, so a superseding wait can be abandoned.
+   */
+  whenSettled(signal?: AbortSignal): Promise<void> | null;
+  /**
+   * Declare how many sources will register in total. The gate then holds until
+   * at least `count` sources have registered (and all have settled), so it
+   * won't open during a momentary lull while later sources are still arriving -
+   * e.g. chunks streaming in across separate ticks. This is **known-count**
+   * completion.
+   *
+   * Pass a non-finite value (e.g. `Number.POSITIVE_INFINITY`) to hold the gate
+   * open-indefinitely for an unknown-count stream, then call {@link markLast}
+   * when the stream ends.
+   */
+  expect(count: number): void;
+  /**
+   * Terminal signal for **last-chunk** completion. Once called, the gate opens
+   * as soon as every outstanding source has settled, regardless of any `expect`
+   * count. Use it to end an unknown-count stream held open via
+   * `expect(Infinity)`, or to finish early before an `expect(n)` count is
+   * reached. Standalone - it does not require `expect` to have been called.
+   */
+  markLast(): void;
+  /** Reset all state to the initial unarmed gate. Test-only. */
+  reset(): void;
+}
+/**
+ * Options for {@link createSettleGate}.
+ */
+export interface CreateSettleGateOptions {
+  /**
+   * Fallback ceiling (ms): open the gate even if a registered source never
+   * settles.
+   * @default SETTLE_SAFETY_TIMEOUT_MS
+   */
+  safetyTimeoutMs?: number;
+  /**
+   * Schedule the deferred settle check. Defaults to `queueMicrotask`, which
+   * batches a burst of same-tick registrations before declaring the gate
+   * settled. Injectable so tests can drive the check synchronously.
+   */
+  scheduleCheck?: (callback: () => void) => void;
+}
+/**
+ * Create an independent "all sources settled" gate. See {@link SettleGate} for
+ * the contract.
+ *
+ * Isomorphic - it touches only `setTimeout` and the injectable `scheduleCheck`
+ * (default `queueMicrotask`), so it runs in tests and during SSR without the
+ * DOM. Client-only consumers are responsible for never registering during SSR
+ * (the page-wide layout-shift gate is only ever touched on the client for this
+ * reason).
+ */
+export declare function createSettleGate(options?: CreateSettleGateOptions): SettleGate;

package/useCoordinated/createSettleGate.mjs

@@ -0,0 +1,171 @@
+/**
+ * Fallback ceiling for {@link createSettleGate}: if a registered source never
+ * settles (its swap errored or hung), the gate opens anyway after this many
+ * milliseconds so coordination can never be blocked forever. Matches the
+ * coordinator's default `ultimateTimeoutMs` and the value the module-global
+ * `layoutShiftGate` shipped with.
+ */
+export const SETTLE_SAFETY_TIMEOUT_MS = 10_000;
+
+/**
+ * A reusable "all sources settled" gate.
+ *
+ * The module-global page-wide layout-shift gate (`layoutShiftGate`) is one
+ * instance; each `StreamController` and `CoordinatedLazy` swap registers with
+ * one too. The behavior is the original layout-shift gate's, plus two opt-in
+ * completion signals (`expect` / `markLast`) for sources that arrive over time
+ * (chunks streaming in across ticks) rather than all within the initial
+ * hydration commit.
+ *
+ * Lifecycle: a source `register()`s and later calls the returned settle
+ * function when it reaches its stable state. The gate opens once every
+ * registered source has settled (and any completion constraint is met). It
+ * opens **once** and never re-closes - a source that registers after the gate
+ * has opened adopts the open state rather than re-closing it for everyone
+ * ("all sources" means "all present by the initial settle").
+ */
+
+/**
+ * Options for {@link createSettleGate}.
+ */
+
+/**
+ * Create an independent "all sources settled" gate. See {@link SettleGate} for
+ * the contract.
+ *
+ * Isomorphic - it touches only `setTimeout` and the injectable `scheduleCheck`
+ * (default `queueMicrotask`), so it runs in tests and during SSR without the
+ * DOM. Client-only consumers are responsible for never registering during SSR
+ * (the page-wide layout-shift gate is only ever touched on the client for this
+ * reason).
+ */
+export function createSettleGate(options = {}) {
+  const safetyTimeoutMs = options.safetyTimeoutMs ?? SETTLE_SAFETY_TIMEOUT_MS;
+  const scheduleCheck = options.scheduleCheck ?? (typeof queueMicrotask === 'function' ? queueMicrotask : callback => {
+    Promise.resolve().then(callback);
+  });
+  let pendingCount = 0;
+  let registeredCount = 0;
+  // `true` once at least one source has registered - until then there is
+  // nothing to wait for and the gate reports settled.
+  let armed = false;
+  let settled = false;
+  let checkScheduled = false;
+  // Completion constraints layered on top of "every source settled":
+  // `expectedCount` holds the gate until that many sources have registered
+  // (known-count); `sawLast` is the standalone terminal that opens on the next
+  // pending-zero regardless of the count (last-chunk).
+  let expectedCount = null;
+  let sawLast = false;
+  let safetyTimer = null;
+  const settleListeners = new Set();
+  function isComplete() {
+    if (sawLast) {
+      return true;
+    }
+    if (expectedCount !== null) {
+      return registeredCount >= expectedCount;
+    }
+    return true;
+  }
+  function openGate() {
+    if (settled) {
+      return;
+    }
+    settled = true;
+    if (safetyTimer !== null) {
+      clearTimeout(safetyTimer);
+      safetyTimer = null;
+    }
+    const listeners = Array.from(settleListeners);
+    settleListeners.clear();
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+  function scheduleSettleCheck() {
+    if (settled || checkScheduled) {
+      return;
+    }
+    checkScheduled = true;
+    // Defer past the current tick so a burst of same-tick registrations - or an
+    // early settle that precedes a sibling's registration - all land before we
+    // declare the gate settled.
+    scheduleCheck(() => {
+      checkScheduled = false;
+      if (!settled && armed && pendingCount === 0 && isComplete()) {
+        openGate();
+      }
+    });
+  }
+  return {
+    register() {
+      if (settled) {
+        return () => {};
+      }
+      armed = true;
+      pendingCount += 1;
+      registeredCount += 1;
+      if (safetyTimer === null && typeof setTimeout === 'function') {
+        safetyTimer = setTimeout(openGate, safetyTimeoutMs);
+      }
+      let done = false;
+      return () => {
+        if (done) {
+          return;
+        }
+        done = true;
+        pendingCount -= 1;
+        scheduleSettleCheck();
+      };
+    },
+    isSettled() {
+      return settled || !armed;
+    },
+    whenSettled(signal) {
+      if (settled || !armed) {
+        return null;
+      }
+      return new Promise((resolve, reject) => {
+        const onSettle = () => {
+          signal?.removeEventListener('abort', onAbort);
+          resolve();
+        };
+        function onAbort() {
+          settleListeners.delete(onSettle);
+          reject(new DOMException('Settle gate wait aborted', 'AbortError'));
+        }
+        if (signal) {
+          if (signal.aborted) {
+            reject(new DOMException('Settle gate wait aborted', 'AbortError'));
+            return;
+          }
+          signal.addEventListener('abort', onAbort);
+        }
+        settleListeners.add(onSettle);
+      });
+    },
+    expect(count) {
+      expectedCount = count;
+      scheduleSettleCheck();
+    },
+    markLast() {
+      sawLast = true;
+      scheduleSettleCheck();
+    },
+    reset() {
+      pendingCount = 0;
+      registeredCount = 0;
+      armed = false;
+      settled = false;
+      checkScheduled = false;
+      expectedCount = null;
+      sawLast = false;
+      if (safetyTimer !== null) {
+        clearTimeout(safetyTimer);
+        safetyTimer = null;
+      }
+      settleListeners.clear();
+    }
+  };
+}

package/useCoordinated/index.d.mts

@@ -0,0 +1,8 @@
+export { useCoordinated, type UseCoordinatedOptions, type UseCoordinatedExtras } from "./useCoordinated.mjs";
+export { useCoordinatedLocalStorage } from "./useCoordinatedLocalStorage.mjs";
+export { useCoordinatedPreference } from "./useCoordinatedPreference.mjs";
+export { registerLayoutShiftSource, whenLayoutShiftsSettled, layoutShiftsSettled } from "./layoutShiftGate.mjs";
+export { useCoordinatedLazy } from "./useCoordinatedLazy.mjs";
+export { createSettleGate, SETTLE_SAFETY_TIMEOUT_MS, type SettleGate, type CreateSettleGateOptions } from "./createSettleGate.mjs";
+export { pageSettleGate } from "./pageSettleGate.mjs";
+export { useSettleGate } from "./useSettleGate.mjs";

package/useCoordinated/index.mjs

@@ -0,0 +1,8 @@
+export { useCoordinated } from "./useCoordinated.mjs";
+export { useCoordinatedLocalStorage } from "./useCoordinatedLocalStorage.mjs";
+export { useCoordinatedPreference } from "./useCoordinatedPreference.mjs";
+export { registerLayoutShiftSource, whenLayoutShiftsSettled, layoutShiftsSettled } from "./layoutShiftGate.mjs";
+export { useCoordinatedLazy } from "./useCoordinatedLazy.mjs";
+export { createSettleGate, SETTLE_SAFETY_TIMEOUT_MS } from "./createSettleGate.mjs";
+export { pageSettleGate } from "./pageSettleGate.mjs";
+export { useSettleGate } from "./useSettleGate.mjs";

package/useCoordinated/layoutShiftGate.d.mts

@@ -0,0 +1,24 @@
+/**
+ * Register a source that may cause a layout shift once it settles. Call the
+ * returned function when the source has reached its stable post-hydration
+ * layout. Idempotent — calling it more than once is a no-op.
+ */
+export declare function registerLayoutShiftSource(): () => void;
+/**
+ * Whether the page's initial layout-shifting swaps have settled. `true` before
+ * any source registers (nothing to wait for) and once every registered source
+ * has settled.
+ */
+export declare function layoutShiftsSettled(): boolean;
+/**
+ * Resolves once {@link layoutShiftsSettled} is `true`. Returns `null`
+ * synchronously when already settled so callers can take a fast path (mirrors
+ * `useHighlightGate`). Rejects with an `AbortError` if `signal` aborts first,
+ * so a superseding coordination announce can abandon the wait.
+ */
+export declare function whenLayoutShiftsSettled(signal?: AbortSignal): Promise<void> | null;
+/**
+ * Reset all gate state. Test-only — there is no production reason to reopen a
+ * settled gate.
+ */
+export declare function resetLayoutShiftGate(): void;

package/useCoordinated/layoutShiftGate.mjs

@@ -0,0 +1,79 @@
+'use client';
+
+/**
+ * Process-global, client-only gate that holds coordinated **layout-shifting**
+ * changes until the page has finished its initial hydration swaps.
+ *
+ * On hydration, anything that may shift layout once it settles — a code block
+ * swapping from its plain fallback to highlighted (and focus-collapsed) output,
+ * say — calls {@link registerLayoutShiftSource} and invokes the returned
+ * `settle` when it reaches its stable layout. `useCoordinated` consumers
+ * `await` {@link whenLayoutShiftsSettled} inside their existing `preload` slot,
+ * so the coordination barrier defers a layout-shifting commit until the gate
+ * opens. The upshot: the first transform/variant change lands as a single
+ * unified update across every block, instead of a cascade as blocks swap in at
+ * staggered idle times.
+ *
+ * Deliberately **not** a React context: registration happens in
+ * `CodeHighlighterClient` and is read deep inside `useCoordinated`, with no
+ * natural shared ancestor to thread a provider through. This mirrors the
+ * module-global design of `coordinatePreference`. It is client-only and never
+ * touched during SSR, so the shared module state cannot leak across server
+ * requests.
+ *
+ * The gate opens **once**, and it coordinates only the *initial hydration
+ * cohort* — every source present by the first settle. A source that registers
+ * after the page has already settled (e.g. a block streamed in and hydrated
+ * late, or a block mounted later on a client-side SPA navigation) registers
+ * into the already-settled gate: {@link whenLayoutShiftsSettled} resolves
+ * immediately, so it adopts the current coordinated value rather than
+ * re-closing the gate for everyone — "all sources" means "all present by the
+ * initial settle". This is by design: a client-side navigation does **not**
+ * re-coordinate a fresh cohort, and there is no production path that reopens a
+ * settled gate.
+ *
+ * The mechanism is the generic {@link createSettleGate}; this module wraps the
+ * shared {@link pageSettleGate} (the same instance generic `CoordinatedLazy`
+ * swaps register with by default) with the named functions preserved for
+ * existing callers. The layout-shift use case never needs the `expect` /
+ * `markLast` completion signals (sources are a fixed set present by the initial
+ * commit), so they are intentionally not re-exported here.
+ */
+import { pageSettleGate } from "./pageSettleGate.mjs";
+const gate = pageSettleGate;
+
+/**
+ * Register a source that may cause a layout shift once it settles. Call the
+ * returned function when the source has reached its stable post-hydration
+ * layout. Idempotent — calling it more than once is a no-op.
+ */
+export function registerLayoutShiftSource() {
+  return gate.register();
+}
+
+/**
+ * Whether the page's initial layout-shifting swaps have settled. `true` before
+ * any source registers (nothing to wait for) and once every registered source
+ * has settled.
+ */
+export function layoutShiftsSettled() {
+  return gate.isSettled();
+}
+
+/**
+ * Resolves once {@link layoutShiftsSettled} is `true`. Returns `null`
+ * synchronously when already settled so callers can take a fast path (mirrors
+ * `useHighlightGate`). Rejects with an `AbortError` if `signal` aborts first,
+ * so a superseding coordination announce can abandon the wait.
+ */
+export function whenLayoutShiftsSettled(signal) {
+  return gate.whenSettled(signal);
+}
+
+/**
+ * Reset all gate state. Test-only — there is no production reason to reopen a
+ * settled gate.
+ */
+export function resetLayoutShiftGate() {
+  gate.reset();
+}

package/useCoordinated/pageSettleGate.d.mts

@@ -0,0 +1,11 @@
+/**
+ * The process-global default settle gate that page-level `CoordinatedLazy`
+ * swaps register with when no explicit gate is supplied. The page-wide
+ * layout-shift coordination (`layoutShiftGate`) aliases this same instance, so
+ * a demo's fallback->content swap and a code block's highlight swap both feed
+ * one "page initial swaps settled" signal that `useCoordinated` can await.
+ *
+ * Inert until a client hook registers with it; nothing registers during SSR, so
+ * the shared module state cannot leak across server requests.
+ */
+export declare const pageSettleGate: import("./createSettleGate.mjs").SettleGate;

package/useCoordinated/pageSettleGate.mjs

@@ -0,0 +1,13 @@
+import { createSettleGate } from "./createSettleGate.mjs";
+
+/**
+ * The process-global default settle gate that page-level `CoordinatedLazy`
+ * swaps register with when no explicit gate is supplied. The page-wide
+ * layout-shift coordination (`layoutShiftGate`) aliases this same instance, so
+ * a demo's fallback->content swap and a code block's highlight swap both feed
+ * one "page initial swaps settled" signal that `useCoordinated` can await.
+ *
+ * Inert until a client hook registers with it; nothing registers during SSR, so
+ * the shared module state cannot leak across server requests.
+ */
+export const pageSettleGate = createSettleGate();

package/useCoordinated/scheduleTasks.d.mts

@@ -0,0 +1,23 @@
+/**
+ * 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 declare function yieldToMain(): Promise<void>;
+/**
+ * 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 declare function requestIdle(task: () => void, options?: {
+  timeout?: number;
+}): () => void;

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);
+}