@mui/internal-docs-infra 0.11.1-canary.11 → 0.11.1-canary.12

package/CodeHighlighter/CodeHighlighter.mjs

@@ -23,13 +23,13 @@ function createClientProps(props) {
   // input).
   const url = props.urlPrefix && props.url ? replaceUrlPrefix(props.url, props.urlPrefix) : props.url;
   const contentProps = {
+    ...props.contentProps,
     code: props.code || props.precompute,
     components: props.components,
     name: props.name,
     slug: props.slug,
     url,
-    variantType: props.variantType,
-    ...props.contentProps
+    variantType: props.variantType
   };
   return {
     url,
@@ -213,14 +213,15 @@ function renderWithInitialSource(props) {
   // Only include components (plural) if we're also including extraVariants
   const components = fallbackProps.extraVariants ? props.components : undefined;
   const contentProps = {
+    ...props.contentProps,
+    ...fallbackProps,
     name,
     slug,
     url,
     initialFilename,
+    initialVariant,
     component,
-    components,
-    ...fallbackProps,
-    ...props.contentProps
+    components
   };
   const fallback = /*#__PURE__*/_jsx(ContentLoading, {
     ...contentProps

package/CodeHighlighter/CodeHighlighterClient.mjs

@@ -9,6 +9,7 @@ import { CodeHighlighterFallbackContext } from "./CodeHighlighterFallbackContext
 import { useControlledCode } from "../CodeControllerContext/index.mjs";
 import { codeToFallbackProps } from "./codeToFallbackProps.mjs";
 import { mergeCodeMetadata } from "../pipeline/loadIsomorphicCodeVariant/mergeCodeMetadata.mjs";
+import { getAvailableTransforms } from "../pipeline/loadIsomorphicCodeVariant/getAvailableTransforms.mjs";
 import * as Errors from "./errors.mjs";
 import { jsx as _jsx } from "react/jsx-runtime";
 const DEBUG = false; // Set to true for debugging purposes
@@ -82,7 +83,7 @@ function useInitialData({
         variants,
         globalsCode // Let loadCodeFallback handle processing
       }).catch(error => ({
-        error
+        error: error instanceof Error ? error : new Error(String(error))
       }));
       if ('error' in loaded) {
         console.error(new Errors.ErrorCodeHighlighterClientLoadFallbackFailure(loaded.error));
@@ -210,7 +211,7 @@ function useAllVariants({
             name,
             variant
           })).catch(error => ({
-            error
+            error: error instanceof Error ? error : new Error(String(error))
           }));
         }));
         const resultCode = {};
@@ -237,8 +238,9 @@ function useAllVariants({
   };
 }
 function yieldToMain() {
-  if (globalThis.scheduler?.yield) {
-    return globalThis.scheduler.yield();
+  const scheduler = globalThis.scheduler;
+  if (scheduler?.yield) {
+    return scheduler.yield();
   }
 
   // Fall back to yielding with setTimeout.
@@ -289,9 +291,16 @@ function useCodeParsing({
     return isHighlightAllowed;
   }, [readyForContent, isHighlightAllowed]);
 
+  // Memoize the "every variant is already in HAST form" check so it
+  // doesn't re-walk the variant + extraFiles trees on every render.
+  // Used both as the short-circuit inside the `parseCode` memo (fully-
+  // precomputed sites skip parsing entirely) and as the unmemoized
+  // `waitingForParsedCode` gate just below.
+  const allVariantsAlreadyHighlighted = React.useMemo(() => code ? hasAllVariants(Object.keys(code), code, true) : false, [code]);
+
   // Parse the internal code state when ready and timing conditions are met
   const parsedCode = React.useMemo(() => {
-    if (!code || !shouldHighlight || hasAllVariants(Object.keys(code), code, true)) {
+    if (!code || !shouldHighlight || allVariantsAlreadyHighlighted) {
       return undefined;
     }
     if (!parseSource) {
@@ -317,36 +326,80 @@ function useCodeParsing({
       return undefined;
     }
     return parseCode(code, parseSource);
-  }, [code, shouldHighlight, sourceParser, parseSource, parseCode, forceClient, url]);
-  const deferHighlight = !shouldHighlight;
+  }, [code, shouldHighlight, allVariantsAlreadyHighlighted, sourceParser, parseSource, parseCode, forceClient, url]);
+
+  // Keep highlighting deferred until parsed HAST is actually available for the
+  // variants that need it. `shouldHighlight` can flip true ~30ms after
+  // hydration, but `parseCode` only runs once the async `sourceParser` promise
+  // resolves. Without this wait, downstream consumers (e.g. the transform
+  // swap) would commit while the visible variant is still rendered from its
+  // raw string source, producing a structure swap on the DOM moments later.
+  const waitingForParsedCode = shouldHighlight && !!code && !allVariantsAlreadyHighlighted && !parsedCode;
+
+  // Only signal `deferHighlight` while a highlight pass is actively in
+  // flight. When `shouldHighlight` is `false` (e.g. `highlightAt: 'idle'`
+  // before the idle window fires, or `'view'` before the block scrolls
+  // into view) we render the un-highlighted source as-is — downstream
+  // consumers like `useTransformManagement`'s `awaitHighlight` gate must
+  // commit eagerly against that source instead of blocking the barrier
+  // indefinitely. Once the trigger fires, `shouldHighlight` flips true,
+  // `waitingForParsedCode` becomes true while `parseCode` runs, and
+  // `deferHighlight` engages for the brief window before the next
+  // commit paints the highlighted tree.
+  const deferHighlight = waitingForParsedCode;
+
+  // Render-side readiness gate. `<Pre>` (via `useCode.shouldHighlight`)
+  // needs to know whether the published `code` should be rendered as
+  // highlighted HAST *now*. That answer is false in two distinct
+  // windows that `deferHighlight` deliberately collapses out:
+  //   1. The trigger for `highlightAt: 'hydration' | 'idle' | 'visible'`
+  //      hasn't fired yet — `shouldHighlight` is still false. The
+  //      precomputed `codeWithGlobals` already contains HAST, so
+  //      without a render-side gate `<Pre>` would render highlighted
+  //      spans on the SSR pass and on first client paint, defeating
+  //      the whole point of deferred highlighting.
+  //   2. The trigger has fired (`shouldHighlight = true`) but
+  //      `parseCode` hasn't resolved yet (`waitingForParsedCode`).
+  //      Rendering would briefly flash un-highlighted text against
+  //      the same tree position before the highlighted HAST lands.
+  //
+  // `highlightReady` is the inverse of the pre-`e7cc08b7` wide
+  // `deferHighlight` semantic, exposed separately so the narrow
+  // `deferHighlight` (barrier consumers only block on real in-flight
+  // work) and the render gate can diverge without coupling.
+  const highlightReady = shouldHighlight && !waitingForParsedCode;
   return {
     parsedCode,
-    deferHighlight
+    deferHighlight,
+    highlightReady
   };
 }
 function useCodeTransforms({
   parsedCode,
+  loadedCode,
   variantName
 }) {
   const {
     sourceParser,
-    getAvailableTransforms,
     computeHastDeltas
   } = useCodeContext();
-  const [transformedCode, setTransformedCode] = React.useState(undefined);
+  // Track which `parsedCode` the cached `transformedCode` was computed from
+  // so a fresh `parsedCode` (e.g. a newly-loaded variant being added to the
+  // map) re-engages `waitingForTransformedCode` instead of returning the
+  // stale output for one render cycle. Storing input + output together lets
+  // callers detect staleness with reference equality.
+  const [transformedState, setTransformedState] = React.useState({});
 
   // Get available transforms from the current variant (separate memo for efficiency)
-  const availableTransforms = React.useMemo(() => {
-    if (!getAvailableTransforms) {
-      return [];
-    }
-    return getAvailableTransforms(parsedCode, variantName);
-  }, [parsedCode, variantName, getAvailableTransforms]);
+  const availableTransforms = React.useMemo(() => getAvailableTransforms(parsedCode ?? loadedCode, variantName), [parsedCode, loadedCode, variantName]);
 
   // Effect to compute transformations for all variants
   React.useEffect(() => {
     if (!parsedCode || !sourceParser || !computeHastDeltas) {
-      setTransformedCode(parsedCode);
+      setTransformedState({
+        input: parsedCode,
+        output: parsedCode
+      });
       return;
     }
 
@@ -355,16 +408,49 @@ function useCodeTransforms({
       try {
         const parseSource = await sourceParser;
         const enhanced = await computeHastDeltas(parsedCode, parseSource);
-        setTransformedCode(enhanced);
+        setTransformedState({
+          input: parsedCode,
+          output: enhanced
+        });
       } catch (error) {
         console.error(new Errors.ErrorCodeHighlighterClientTransformProcessingFailure(error));
-        setTransformedCode(parsedCode);
+        setTransformedState({
+          input: parsedCode,
+          output: parsedCode
+        });
       }
     })();
   }, [parsedCode, sourceParser, computeHastDeltas]);
+
+  // Expose the cached output regardless of whether `parsedCode` changed since
+  // the last computation — falling back to `undefined` here would yank the
+  // currently-displayed HAST for a frame while the async pipeline catches up.
+  // Staleness is signalled via `waitingForTransformedCode` so downstream
+  // gates (e.g. `useTransformManagement` / `useVariantSelection`) hold off
+  // committing a swap until fresh deltas land.
+  const transformedCode = transformedState.output;
+
+  // Async hast-deltas pipeline status. While true, consumers (notably
+  // `useTransformManagement`'s `deferHighlight` gate) should treat
+  // highlighting as not-yet-settled and hold off committing a transform
+  // swap. Without this, the swap can commit after `parsedCode` is ready
+  // but *before* `computeHastDeltas` resolves: the incoming tree first
+  // renders without the transform deltas, then re-renders a frame or
+  // two later when `transformedCode` arrives, producing a visible jump
+  // on top of the just-played collapse animation.
+  //
+  // Only relevant when both a worker (`sourceParser`) and a deltas
+  // computer (`computeHastDeltas`) are wired up — environments without
+  // them resolve `transformedCode` synchronously to `parsedCode` in the
+  // effect above, so the deltas phase is a no-op. We compare the cached
+  // `input` against the live `parsedCode` instead of just checking
+  // `!transformedCode` so a freshly-arriving variant re-engages the wait
+  // until its deltas land.
+  const waitingForTransformedCode = !!parsedCode && !!sourceParser && !!computeHastDeltas && transformedState.input !== parsedCode;
   return {
     transformedCode,
-    availableTransforms
+    availableTransforms,
+    waitingForTransformedCode
   };
 }
 function useControlledCodeParsing({
@@ -794,7 +880,8 @@ export function CodeHighlighterClient(props) {
   const codeWithGlobals = propsCodeWithGlobals || stateCodeWithGlobals;
   const {
     parsedCode,
-    deferHighlight
+    deferHighlight: deferHighlightForParsing,
+    highlightReady
   } = useCodeParsing({
     code: codeWithGlobals,
     readyForContent: readyForContent || Boolean(props.code),
@@ -805,12 +892,26 @@ export function CodeHighlighterClient(props) {
   });
   const {
     transformedCode,
-    availableTransforms
+    availableTransforms,
+    waitingForTransformedCode
   } = useCodeTransforms({
     parsedCode,
+    loadedCode: codeWithGlobals,
     variantName
   });
 
+  // Combined highlight-readiness gate consumed via context (notably by
+  // `useTransformManagement`). Stay deferred while either the sync
+  // `parseCode` pass or the async `computeHastDeltas` pass is still in
+  // flight — committing a transform swap with `transformedCode` still
+  // pending causes the incoming pre to first render without the
+  // transform deltas and then re-flow a frame or two later when the
+  // deltas land, producing a visible jump on top of the collapse
+  // animation. The wait only matters for highlighters with at least one
+  // applicable transform; plain (variant-only) highlighters skip it so
+  // their stored-preference resolution doesn't pay the deltas latency.
+  const deferHighlight = deferHighlightForParsing || availableTransforms.length > 0 && waitingForTransformedCode;
+
   // Per-highlighter pre-parsed HAST cache. Lives in a ref so the same Map
   // instance is shared across renders without becoming a React dep. The
   // editable populates it via `useSourceEditing` (which reads it from
@@ -839,16 +940,31 @@ export function CodeHighlighterClient(props) {
     selection: controlled?.selection || selection,
     setSelection: controlled?.setSelection || setSelection,
     components: controlled?.components || props.components,
-    availableTransforms: isControlled ? [] : availableTransforms,
+    // Only suppress when an external CodeController owns the code; static
+    // `props.code` still needs the locally-computed list.
+    availableTransforms: controlled?.code ? [] : availableTransforms,
     url: props.url,
     deferHighlight,
+    highlightReady,
+    highlightAfter,
     preParsedCache
-  }), [overlaidCode, controlled?.setCode, selection, controlled?.selection, controlled?.setSelection, controlled?.components, props.components, isControlled, availableTransforms, props.url, deferHighlight, preParsedCache]);
+  }), [overlaidCode, controlled?.setCode, selection, controlled?.selection, controlled?.setSelection, controlled?.components, props.components, controlled?.code, availableTransforms, props.url, deferHighlight, highlightReady, highlightAfter, preParsedCache]);
   if (!props.variants && !props.components && !activeCode) {
     throw new Errors.ErrorCodeHighlighterClientMissingData();
   }
+
+  // If this CodeHighlighter is nested inside another CodeHighlighter that is
+  // currently rendering its fallback, hold our own fallback->full transition
+  // until the outer one swaps. Otherwise, when the outer swaps from its
+  // fallback element to its children element, our subtree unmounts and a fresh
+  // inner instance mounts and re-runs its own fallback->full transition,
+  // producing a visible "fallback -> full -> fallback -> full" flicker. By
+  // staying in fallback while nested, we collapse this to a single transition
+  // that happens after the outer is fully rendered.
+  const outerFallbackContext = React.useContext(CodeHighlighterFallbackContext);
+  const isNestedInsideOuterFallback = outerFallbackContext !== undefined;
   const fallback = props.fallback;
-  if (fallback && !props.skipFallback && !activeCodeReady) {
+  if (fallback && !props.skipFallback && (!activeCodeReady || isNestedInsideOuterFallback)) {
     return /*#__PURE__*/_jsx(CodeHighlighterFallbackContext.Provider, {
       value: fallbackContext,
       children: fallback

package/CodeHighlighter/CodeHighlighterContext.d.mts

@@ -21,6 +21,33 @@ export interface CodeHighlighterContextType {
   availableTransforms?: string[];
   url?: string;
   deferHighlight?: boolean;
+  /**
+   * Render-side readiness gate. `true` once the highlight trigger
+   * (`init` / `hydration` / `idle` / `visible`) has fired *and* the
+   * sync `parseCode` pass has resolved, so consumers like `<Pre>`
+   * can render the published `code` as highlighted HAST. While
+   * `false` they should render the un-highlighted fallback (plain
+   * text) — the published `code` may still contain precomputed HAST
+   * left over from SSR, so without this gate non-`init` demos would
+   * render highlighted spans on the first paint and defeat the
+   * deferred-highlighting trigger.
+   *
+   * Distinct from `deferHighlight`, which is the narrower
+   * "highlight pass is actively in flight" signal consumed by
+   * barrier gates (e.g. `useTransformManagement.awaitHighlight`)
+   * that must not block when no work is queued.
+   */
+  highlightReady?: boolean;
+  /**
+   * Echo of the `highlightAfter` prop on the surrounding
+   * `CodeHighlighter` / `CodeHighlighterClient`. Consumers such as
+   * `useCode` use this to skip transient highlighting-suppression
+   * gates that only matter when highlighting is asynchronous — in
+   * `'init'` mode the precomputed HAST already carries the highlight
+   * spans, so those gates would just cause a visible flash of
+   * unhighlighted content during variant swaps.
+   */
+  highlightAfter?: 'init' | 'hydration' | 'idle';
   /**
    * Per-file pre-parsed HAST cache. Populated by `useSourceEditing` when the
    * editable supplies a worker-parsed result alongside a source change, and

package/CodeHighlighter/codeToFallbackProps.mjs

@@ -1,8 +1,22 @@
 import { stringOrHastToJsx } from "../pipeline/hastUtils/index.mjs";
+import { getLanguageFromExtension } from "../pipeline/loaderUtils/getLanguageFromExtension.mjs";
+function getLanguageFromFileName(fileName) {
+  if (!fileName) {
+    return undefined;
+  }
+  const dotIndex = fileName.lastIndexOf('.');
+  if (dotIndex === -1) {
+    return undefined;
+  }
+  return getLanguageFromExtension(fileName.slice(dotIndex));
+}
 function toExtraSource(variantCode, fileName) {
   return Object.entries(variantCode.extraFiles || {}).reduce((acc, [name, file]) => {
     if (name !== fileName && typeof file === 'object' && file?.source) {
-      acc[name] = stringOrHastToJsx(file.source);
+      acc[name] = {
+        source: stringOrHastToJsx(file.source),
+        language: file.language ?? getLanguageFromFileName(name)
+      };
     }
     return acc;
   }, {});
@@ -14,13 +28,16 @@ export function codeToFallbackProps(variant, code, fileName, needsAllFiles = fal
   }
   const fileNames = [variantCode.fileName, ...Object.keys(variantCode.extraFiles || {})].filter(name => Boolean(name));
   let source;
+  let language;
   if (fileName && fileName !== variantCode.fileName) {
     const fileData = variantCode.extraFiles?.[fileName];
     if (fileData && typeof fileData === 'object' && 'source' in fileData && fileData.source) {
       source = stringOrHastToJsx(fileData.source);
+      language = fileData.language ?? getLanguageFromFileName(fileName);
     }
   } else if (variantCode.source) {
     source = stringOrHastToJsx(variantCode.source);
+    language = variantCode.language ?? getLanguageFromFileName(variantCode.fileName);
   }
   if (needsAllVariants || needsAllFiles) {
     const extraSource = toExtraSource(variantCode, fileName);
@@ -32,6 +49,7 @@ export function codeToFallbackProps(variant, code, fileName, needsAllFiles = fal
             fileNames: [vCode.fileName, ...Object.keys(vCode.extraFiles || {})].filter(fn => Boolean(fn)),
             // TODO: use filesOrder if provided
             source: vCode.source && stringOrHastToJsx(vCode.source),
+            language: vCode.source ? vCode.language ?? getLanguageFromFileName(vCode.fileName) : undefined,
             extraSource: extraVariantExtraSource
           };
         }
@@ -40,6 +58,7 @@ export function codeToFallbackProps(variant, code, fileName, needsAllFiles = fal
       return {
         fileNames,
         source,
+        language,
         extraSource,
         extraVariants
       };
@@ -47,11 +66,13 @@ export function codeToFallbackProps(variant, code, fileName, needsAllFiles = fal
     return {
       fileNames,
       source,
+      language,
       extraSource
     };
   }
   return {
     fileNames,
-    source
+    source,
+    language
   };
 }

package/CodeHighlighter/index.d.mts

@@ -1 +1,2 @@
-export * from "./CodeHighlighter.mjs";
+export * from "./CodeHighlighter.mjs";
+export { mergeComments } from "./mergeComments.mjs";

package/CodeHighlighter/index.mjs

@@ -1 +1,2 @@
-export * from "./CodeHighlighter.mjs";
+export * from "./CodeHighlighter.mjs";
+export { mergeComments } from "./mergeComments.mjs";

package/CodeHighlighter/mergeComments.d.mts

@@ -0,0 +1,38 @@
+import type { SourceComments } from "./types.mjs";
+/**
+ * Merges two `SourceComments` maps by concatenating entries per line.
+ *
+ * Both maps are keyed by line number. The function does not interpret
+ * keys — it only matches them by value — so 0-indexed and 1-indexed
+ * conventions are both supported, but **both inputs must use the same
+ * convention**. The repository's `SourceTransformer` contract supplies
+ * 1-indexed line numbers; if you build `mine` by hand, match the
+ * upstream indexing of `input` or your markers will land on the wrong
+ * lines.
+ *
+ * In non-production builds a heuristic dev warning is emitted when the
+ * two inputs look like they disagree about indexing (one contains a
+ * `0` key and the other does not). The check has no runtime cost in
+ * production builds.
+ *
+ * For any line present in either map, the resulting entry is
+ * `[...input[line] ?? [], ...mine[line] ?? []]` — `input` markers come
+ * first, the transformer's own markers (`mine`) are appended.
+ *
+ * Returns `undefined` when the merge would produce no entries (both
+ * inputs absent, both empty, or every per-line array empty). Otherwise
+ * returns a fresh object whose per-line arrays are also fresh copies,
+ * so callers may safely mutate the result without affecting either
+ * input.
+ *
+ * Intended to be called by `SourceTransformer` implementations that
+ * receive an upstream `comments` map as their 3rd argument and want to
+ * preserve those entries alongside the markers they themselves emit.
+ *
+ * @param input - Comments map received by the transformer (may be
+ *   `undefined` when no upstream comments exist).
+ * @param mine - Comments map the transformer wants to emit (may be
+ *   `undefined` when the transformer has none of its own). Must use
+ *   the same line-indexing convention as `input`.
+ */
+export declare function mergeComments(input: SourceComments | undefined, mine: SourceComments | undefined): SourceComments | undefined;

package/CodeHighlighter/mergeComments.mjs

@@ -0,0 +1,80 @@
+/**
+ * Merges two `SourceComments` maps by concatenating entries per line.
+ *
+ * Both maps are keyed by line number. The function does not interpret
+ * keys — it only matches them by value — so 0-indexed and 1-indexed
+ * conventions are both supported, but **both inputs must use the same
+ * convention**. The repository's `SourceTransformer` contract supplies
+ * 1-indexed line numbers; if you build `mine` by hand, match the
+ * upstream indexing of `input` or your markers will land on the wrong
+ * lines.
+ *
+ * In non-production builds a heuristic dev warning is emitted when the
+ * two inputs look like they disagree about indexing (one contains a
+ * `0` key and the other does not). The check has no runtime cost in
+ * production builds.
+ *
+ * For any line present in either map, the resulting entry is
+ * `[...input[line] ?? [], ...mine[line] ?? []]` — `input` markers come
+ * first, the transformer's own markers (`mine`) are appended.
+ *
+ * Returns `undefined` when the merge would produce no entries (both
+ * inputs absent, both empty, or every per-line array empty). Otherwise
+ * returns a fresh object whose per-line arrays are also fresh copies,
+ * so callers may safely mutate the result without affecting either
+ * input.
+ *
+ * Intended to be called by `SourceTransformer` implementations that
+ * receive an upstream `comments` map as their 3rd argument and want to
+ * preserve those entries alongside the markers they themselves emit.
+ *
+ * @param input - Comments map received by the transformer (may be
+ *   `undefined` when no upstream comments exist).
+ * @param mine - Comments map the transformer wants to emit (may be
+ *   `undefined` when the transformer has none of its own). Must use
+ *   the same line-indexing convention as `input`.
+ */
+export function mergeComments(input, mine) {
+  if (!input && !mine) {
+    return undefined;
+  }
+  if (process.env.NODE_ENV !== 'production' && input && mine && Object.keys(input).length > 0 && Object.keys(mine).length > 0) {
+    warnOnIndexingMismatch(input, mine);
+  }
+  const result = {};
+  const lines = new Set();
+  if (input) {
+    for (const key of Object.keys(input)) {
+      lines.add(Number(key));
+    }
+  }
+  if (mine) {
+    for (const key of Object.keys(mine)) {
+      lines.add(Number(key));
+    }
+  }
+  let hasAny = false;
+  for (const line of lines) {
+    const merged = [...(input?.[line] ?? []), ...(mine?.[line] ?? [])];
+    if (merged.length > 0) {
+      result[line] = merged;
+      hasAny = true;
+    }
+  }
+  return hasAny ? result : undefined;
+}
+function warnOnIndexingMismatch(input, mine) {
+  const inputHasZero = Object.prototype.hasOwnProperty.call(input, 0);
+  const mineHasZero = Object.prototype.hasOwnProperty.call(mine, 0);
+  if (inputHasZero === mineHasZero) {
+    return;
+  }
+
+  // Only warn when the side without a `0` key has at least one entry
+  // — otherwise we can't tell whether it would have included one.
+  const other = inputHasZero ? mine : input;
+  if (Object.keys(other).length === 0) {
+    return;
+  }
+  console.warn('mergeComments: inputs appear to use different line-indexing conventions ' + '(one contains a `0` key, the other does not). Both inputs must use the ' + 'same convention or markers will land on the wrong lines. The repository ' + "convention is 1-indexed; convert with `convertCommentsToOneIndexed` if you're emitting 0-indexed comments.");
+}