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

package/useCode/useUIState.mjs

@@ -6,20 +6,20 @@ import { isHashRelevantToDemo } from "./useFileNavigation.mjs";
  * Auto-expands if there's a relevant hash for this demo
  */
 export function useUIState({
-  defaultOpen = false,
+  initialExpanded = false,
   mainSlug
 }) {
   const [hash] = useUrlHashState();
   const hasRelevantHash = isHashRelevantToDemo(hash, mainSlug);
-  const [expanded, setExpanded] = React.useState(defaultOpen || hasRelevantHash);
+  const [expanded, setExpanded] = React.useState(initialExpanded || hasRelevantHash);
   const expand = React.useCallback(() => setExpanded(true), []);
 
-  // Auto-expand if hash becomes relevant
-  React.useEffect(() => {
-    if (hasRelevantHash && !expanded) {
-      setExpanded(true);
-    }
-  }, [hasRelevantHash, expanded]);
+  // Auto-expand if hash becomes relevant. This is a one-way OR-latch: it ratchets
+  // `expanded` to true but never collapses, so adjusting state during render is safe
+  // (the branch is skipped once `expanded` is true, avoiding an extra render).
+  if (hasRelevantHash && !expanded) {
+    setExpanded(true);
+  }
   return {
     expanded,
     expand,

package/useCode/useVariantSelection.d.mts

@@ -1,31 +1,155 @@
 import * as React from 'react';
 import type { Code, VariantCode } from "../CodeHighlighter/types.mjs";
+import { type TransitionPhase } from "./useTransitionPhase.mjs";
 interface UseVariantSelectionProps {
   effectiveCode: Code;
   initialVariant?: string;
   variantType?: string;
   mainSlug?: string;
   saveHashVariantToLocalStorage?: 'on-load' | 'on-interaction' | 'never';
+  /**
+   * Mode passed to `variantHasLayoutShift` to classify variant swaps
+   * as layout-affecting (phase 1, coordinated) versus non-layout
+   * (phase 2). See `useCode`'s `variantLayoutShift` option for
+   * details. Defaults to `'selected'`.
+   */
+  variantLayoutShift?: 'all' | 'selected' | 'focus';
+  /**
+   * Currently-selected file name. Required for the `'selected'` and
+   * `'focus'` `variantLayoutShift` modes; ignored by `'all'`.
+   */
+  selectedFileName?: string | undefined;
+  /**
+   * Whether the surrounding code block is currently expanded.
+   * Consulted only by `variantLayoutShift: 'focus'`.
+   */
+  expanded?: boolean;
+  /**
+   * When set to a positive number, the *swap* of the rendered tree to
+   * the newly-selected variant is delayed by this many milliseconds so
+   * consumers can run an exit animation on the outgoing tree before
+   * the incoming tree replaces it. `selectedVariantKey` always
+   * updates synchronously so UI controls (tabs, dropdowns) reflect
+   * the change immediately; the lag is only visible on the rendered
+   * `<Pre>` content, which stays on `committedVariantKey` until the
+   * delay elapses. While the swap is pending or just-committed,
+   * `variantSwappingPhase` is non-null and the rendered `<pre>` is
+   * annotated with `data-transforming` so CSS can react.
+   */
+  variantSwapDelay?: number;
+  /**
+   * When `true`, holds the coordinator barrier open via the engine's
+   * `preload` slot until the highlighter pipeline (sync `parseCode`
+   * + async `computeHastDeltas`) has finished, so the incoming
+   * variant tree always paints with highlighting applied instead of
+   * snapping to it a frame later. Plumbed in from
+   * `CodeHighlighterContext.deferHighlight`; see `useHighlightGate`.
+   */
+  deferHighlight?: boolean;
 }
 export interface UseVariantSelectionResult {
   variantKeys: string[];
   selectedVariantKey: string;
   selectedVariant: VariantCode | null;
+  /**
+   * Engine-committed variant key. Lags `selectedVariantKey` by
+   * `variantSwapDelay` ms when a delay is configured and a swap is
+   * in flight, otherwise equal to `selectedVariantKey`. Consumers
+   * that render the variant's file tree should key off this value
+   * so the outgoing tree stays put while the pre-swap animation
+   * window plays out.
+   */
+  committedVariantKey: string;
+  /**
+   * Variant resolved from `committedVariantKey`. See
+   * `committedVariantKey` for the lag semantics. `null` when the
+   * committed key doesn't resolve to a fully-loaded variant entry.
+   */
+  committedVariant: VariantCode | null;
+  /**
+   * State of the in-flight variant-swap animation, or `null` when
+   * settled. Always `null` when `variantSwapDelay` is not set or is
+   * `0`. Mirrors `useTransformManagement`'s `transformingPhase`.
+   *
+   * Each swap progresses through up to four states, gated on
+   * `notifyVariantTransitionReady` calls from the rendered `<Pre>`:
+   *
+   *   - `'collapsed'`  pre-swap paused. Outgoing tree is rendered;
+   *                    the bridge `.collapse` placeholder is held at
+   *                    0 height. Waiting for one paint cycle before
+   *                    releasing into the expand animation.
+   *   - `'expanding'`  pre-swap active. The bridge animates from 0
+   *                    up to the incoming variant's extra line
+   *                    count. Outgoing tree still rendered.
+   *   - `'expanded'`   post-swap paused. Incoming tree is now
+   *                    rendered; the bridge is held at the outgoing
+   *                    variant's extra height. Waiting for the new
+   *                    tree's HAST to paint before releasing.
+   *   - `'collapsing'` post-swap active. The bridge animates from
+   *                    the outgoing variant's extra height back
+   *                    down to 0.
+   */
+  variantSwappingPhase: TransitionPhase;
+  /**
+   * The "other" variant key participating in the in-flight swap:
+   *   - During `'collapsed'` / `'expanding'`: the incoming variant
+   *     (the user's intent target, equal to `selectedVariantKey`).
+   *   - During `'expanded'` / `'collapsing'`: the outgoing variant
+   *     we just transitioned away from, captured at the commit
+   *     boundary.
+   *   - `null` when no swap is in flight.
+   *
+   * Consumers use this to look up the partner variant's per-file
+   * line counts so `<Pre>` can append a bridge `.collapse`
+   * placeholder when the partner has more visible lines than the
+   * currently-rendered (committed) variant.
+   */
+  swapPartnerVariantKey: string | null;
+  /**
+   * Target of an in-flight variant swap that is still waiting on slow
+   * peers past the coordinator's grace window. `undefined` when no
+   * swap is pending. Only populated on the demo that originated the
+   * change; always `undefined` on peers and when no coordinator is
+   * configured.
+   */
+  pendingVariantKey: string | undefined;
+  /**
+   * `true` while a stored-preference bootstrap swap is known to be
+   * in flight: a valid `storedValue` exists, differs from the
+   * currently-committed variant, and the engine has not yet
+   * committed past the initial mount value. Releases on the first
+   * commit (whether the bootstrap landed or a racing user click
+   * superseded it) so consumers can defer expensive work — most
+   * notably suppressing the outgoing initial variant's highlight
+   * render — without leaking suppression into normal interactive
+   * swaps.
+   */
+  pendingBootstrap: boolean;
+  /**
+   * Callback the rendered `<Pre>` invokes (via its `onTransitionReady`
+   * prop) once it has painted the new tree at a paused phase value.
+   * Triggers the transition from `'collapsed' → 'expanding'` (pre-swap)
+   * or `'expanded' → 'collapsing'` (post-swap). Holding the active
+   * value off until the new tree has had a paint cycle prevents the
+   * keyframe / transition from running against raw-text spans that
+   * haven't yet been upgraded to highlighted HAST.
+   */
+  notifyVariantTransitionReady: () => void;
   selectVariant: React.Dispatch<React.SetStateAction<string | null>>;
   selectVariantProgrammatic: React.Dispatch<React.SetStateAction<string>>;
   saveVariantToLocalStorage: (variant: string) => void;
   hashVariant: string | null;
 }
-/**
- * Hook for managing variant selection and providing variant-related data
- * Priority: URL hash > localStorage > initialVariant > first variant
- * When hash has a variant, it overrides localStorage and is saved to localStorage
- */
 export declare function useVariantSelection({
   effectiveCode,
   initialVariant,
   variantType,
   mainSlug,
-  saveHashVariantToLocalStorage
+  saveHashVariantToLocalStorage,
+  variantLayoutShift,
+  selectedFileName,
+  expanded,
+  variantSwapDelay,
+  deferHighlight
 }: UseVariantSelectionProps): UseVariantSelectionResult;
 export {};