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

package/CodeHighlighter/CodeHighlighter.mjs

@@ -1,304 +1,26 @@
 import * as React from 'react';
-import { loadIsomorphicCodeVariant } from "../pipeline/loadIsomorphicCodeVariant/loadIsomorphicCodeVariant.mjs";
-import { loadCodeFallback } from "../pipeline/loadIsomorphicCodeVariant/loadCodeFallback.mjs";
-import { CodeHighlighterClient } from "./CodeHighlighterClient.mjs";
 import { maybeCodeInitialData } from "../pipeline/loadIsomorphicCodeVariant/maybeCodeInitialData.mjs";
-import { hasAllVariants } from "../pipeline/loadIsomorphicCodeVariant/hasAllCodeVariants.mjs";
 import { getFileNameFromUrl, getLanguageFromExtension } from "../pipeline/loaderUtils/index.mjs";
-import { replaceUrlPrefix } from "../pipeline/loaderUtils/applyUrlPrefix.mjs";
-import { codeToFallbackProps } from "./codeToFallbackProps.mjs";
+import { buildCodeHighlighterChunkProps } from "./buildCodeHighlighterChunkProps.mjs";
+import { prepareInitialSource } from "./prepareInitialSource.mjs";
+import { CodeHighlighterChunk } from "./CodeHighlighterChunk.mjs";
 import * as Errors from "./errors.mjs";
 import { jsx as _jsx } from "react/jsx-runtime";
 const DEBUG = false; // Set to true for debugging purposes
 
-function createClientProps(props) {
-  const highlightAfter = props.highlightAfter === 'stream' ? 'init' : props.highlightAfter;
-  const enhanceAfter = props.enhanceAfter === 'stream' ? 'init' : props.enhanceAfter;
-
-  // Rewrite the top-level URL before it leaves the server. The client never
-  // receives `urlPrefix` (and shouldn't deal with `file://` URLs), so any
-  // local URL must be translated to its hosted form here. Variant-level URLs
-  // inside `code`/`precompute` are already rewritten upstream (by
-  // `loadIsomorphicCodeVariant` on the server, or by the demo factory for precomputed
-  // input).
-  const url = props.urlPrefix && props.url ? replaceUrlPrefix(props.url, props.urlPrefix) : props.url;
-  const contentProps = {
-    code: props.code || props.precompute,
-    components: props.components,
-    name: props.name,
-    slug: props.slug,
-    url,
-    variantType: props.variantType,
-    ...props.contentProps
-  };
-  return {
-    url,
-    code: props.code,
-    precompute: props.precompute,
-    components: props.components,
-    variants: props.variants,
-    variant: props.variant,
-    fileName: props.fileName,
-    initialVariant: props.initialVariant,
-    defaultVariant: props.defaultVariant,
-    highlightAfter: highlightAfter || 'idle',
-    enhanceAfter: enhanceAfter || 'idle',
-    skipFallback: props.skipFallback,
-    controlled: props.controlled,
-    name: props.name,
-    slug: props.slug,
-    // Use processedGlobalsCode if available, otherwise fall back to raw globalsCode
-    globalsCode: props.processedGlobalsCode || props.globalsCode,
-    // Note: it is important that we render components before passing them to the client
-    // otherwise we will get an error because functions can't be serialized
-    // On the client, in order to send data to these components, we have to set context
-    fallback: props.fallback,
-    children: /*#__PURE__*/_jsx(props.Content, {
-      ...contentProps
-    })
-  };
-}
-async function CodeSourceLoader(props) {
-  // Start with the loaded code from precompute, or load it if needed
-  let loadedCode = props.code || props.precompute;
-  if (!loadedCode) {
-    if (!props.loadCodeMeta) {
-      throw new Errors.ErrorCodeHighlighterServerMissingLoadCodeMeta();
-    }
-    if (!props.url) {
-      throw new Errors.ErrorCodeHighlighterServerMissingUrlForLoadCodeMeta();
-    }
-    try {
-      loadedCode = await props.loadCodeMeta(props.url);
-    } catch (error) {
-      throw new Errors.ErrorCodeHighlighterServerLoadCodeFailure(props.url, error);
-    }
-  }
-
-  // TODO: if props.variant is provided, we should only load that variant
-
-  // Process globalsCode: use already processed version if available, otherwise convert string URLs to Code objects
-  let processedGlobalsCode = props.processedGlobalsCode;
-  if (!processedGlobalsCode && props.globalsCode && props.globalsCode.length > 0) {
-    const hasStringUrls = props.globalsCode.some(item => typeof item === 'string');
-    if (hasStringUrls && !props.loadCodeMeta) {
-      throw new Errors.ErrorCodeHighlighterServerMissingLoadCodeMetaForGlobals();
-    }
-
-    // Load all string URLs in parallel, keep Code objects as-is
-    const globalsPromises = props.globalsCode.map(async globalItem => {
-      if (typeof globalItem === 'string') {
-        // String URL - load Code object via loadCodeMeta
-        try {
-          return await props.loadCodeMeta(globalItem);
-        } catch (error) {
-          throw new Errors.ErrorCodeHighlighterServerLoadGlobalsFailure(globalItem, error);
-        }
-      } else {
-        // Code object - return as-is
-        return globalItem;
-      }
-    });
-    processedGlobalsCode = await Promise.all(globalsPromises);
-  }
-  const variantNames = Object.keys(props.components || loadedCode || {});
-  const variantCodes = await Promise.all(variantNames.map(variantName => {
-    const variantCode = loadedCode[variantName];
-    const variantUrl = typeof variantCode === 'object' && variantCode?.url ? variantCode.url : props.url;
-
-    // Convert processedGlobalsCode to VariantCode | string for this specific variant
-    let resolvedGlobalsCode;
-    if (processedGlobalsCode && processedGlobalsCode.length > 0) {
-      resolvedGlobalsCode = [];
-      for (const codeObj of processedGlobalsCode) {
-        // Only include if this variant exists in the globalsCode
-        const targetVariant = codeObj[variantName];
-        if (targetVariant) {
-          resolvedGlobalsCode.push(targetVariant);
-        }
-      }
-    }
-    let output = 'hastCompressed';
-    if (props.deferParsing === 'json') {
-      output = 'hastJson';
-    } else if (props.deferParsing === 'none') {
-      output = 'hast';
-    }
-    return loadIsomorphicCodeVariant(variantUrl, variantName, variantCode, {
-      sourceParser: props.sourceParser,
-      loadSource: props.loadSource,
-      loadVariantMeta: props.loadVariantMeta,
-      sourceTransformers: props.sourceTransformers,
-      sourceEnhancers: props.sourceEnhancers,
-      globalsCode: resolvedGlobalsCode,
-      output,
-      urlPrefix: props.urlPrefix
-    }).then(variant => ({
-      name: variantName,
-      variant
-    })).catch(error => ({
-      error
-    }));
-  }));
-  const processedCode = {};
-  const errors = [];
-  for (const item of variantCodes) {
-    if ('error' in item) {
-      console.error(new Errors.ErrorCodeHighlighterServerLoadVariantFailure(props.url, item.error));
-      errors.push(item.error);
-    } else {
-      processedCode[item.name] = item.variant.code;
-    }
-  }
-  if (errors.length > 0) {
-    throw new Errors.ErrorCodeHighlighterServerLoadVariantsFailure(props.url, errors);
-  }
-  const clientProps = createClientProps({
-    ...props,
-    code: processedCode,
-    processedGlobalsCode
-  });
-  return /*#__PURE__*/_jsx(CodeHighlighterClient, {
-    ...clientProps
-  });
-}
-function renderCodeHighlighter(props) {
-  const code = props.code || props.precompute;
-  const variants = props.variants || Object.keys(props.components || code || {});
-  const allCodeVariantsLoaded = code && hasAllVariants(variants, code, true);
-
-  // Check if any loader functions are available before trying async loading
-  const hasAnyLoaderFunction = !!(props.loadCodeMeta || props.loadVariantMeta || props.loadSource || props.sourceParser || props.sourceTransformers);
-  if (!allCodeVariantsLoaded && hasAnyLoaderFunction && !props.forceClient) {
-    return /*#__PURE__*/_jsx(CodeSourceLoader, {
-      ...props
-    });
-  }
-  const clientProps = createClientProps(props);
-  return /*#__PURE__*/_jsx(CodeHighlighterClient, {
-    ...clientProps
-  });
-}
-
 /**
- * Ensures that the suspense boundary is always rendered, even if none of the children have async operations.
+ * Isomorphic entry for a code block. Validates and normalizes props, then maps them
+ * onto the generic {@link CodeHighlighterChunk} (a `createCoordinatedLazy` chunk):
+ * the decision inputs (`controlled`/`isInitial`/`forceClient`) computed by
+ * {@link buildCodeHighlighterChunkProps} route between rendering the client directly
+ * (precomputed content), dynamically importing the server `Loader` (load all
+ * variants), or the server `InitialLoader` (load a quick initial first). When a
+ * `ContentLoading` and an initial paint are available, the loading fallback +
+ * compressed residual are prepared up front via {@link prepareInitialSource}.
+ *
+ * The heavy load/parse pipeline lives behind the dynamically-imported loaders, so it
+ * never reaches the path that renders precomputed content.
  */
-async function CodeHighlighterSuspense(props) {
-  await new Promise(resolve => {
-    setTimeout(resolve, 0);
-  });
-  return props.children;
-}
-function renderWithInitialSource(props) {
-  const ContentLoading = props.ContentLoading;
-  const {
-    slug,
-    name,
-    initialVariant,
-    code,
-    initialFilename,
-    fallbackUsesExtraFiles,
-    fallbackUsesAllVariants
-  } = props;
-
-  // Rewrite the top-level URL before it reaches the loading fallback so the
-  // browser never sees `file://` URLs. See `createClientProps` for the same
-  // rewrite on the regular client path.
-  const url = props.urlPrefix && props.url ? replaceUrlPrefix(props.url, props.urlPrefix) : props.url;
-  const fallbackProps = codeToFallbackProps(initialVariant, code, initialFilename, fallbackUsesExtraFiles, fallbackUsesAllVariants);
-
-  // Get the component for the selected variant
-  const component = props.components?.[initialVariant];
-
-  // Only include components (plural) if we're also including extraVariants
-  const components = fallbackProps.extraVariants ? props.components : undefined;
-  const contentProps = {
-    name,
-    slug,
-    url,
-    initialFilename,
-    component,
-    components,
-    ...fallbackProps,
-    ...props.contentProps
-  };
-  const fallback = /*#__PURE__*/_jsx(ContentLoading, {
-    ...contentProps
-  });
-  if (props.highlightAfter === 'stream' && !props.forceClient) {
-    return /*#__PURE__*/_jsx(React.Suspense, {
-      fallback: fallback,
-      children: /*#__PURE__*/_jsx(CodeHighlighterSuspense, {
-        children: renderCodeHighlighter({
-          ...props,
-          fallback,
-          skipFallback: props.enhanceAfter === 'stream'
-        })
-      })
-    });
-  }
-  return renderCodeHighlighter({
-    ...props,
-    fallback
-  });
-}
-async function CodeInitialSourceLoader(props) {
-  const {
-    url,
-    initialVariant,
-    highlightAfter,
-    fallbackUsesExtraFiles,
-    fallbackUsesAllVariants,
-    sourceParser,
-    loadSource,
-    loadVariantMeta,
-    loadCodeMeta,
-    sourceEnhancers,
-    fileName,
-    variants,
-    globalsCode,
-    ContentLoading
-  } = props;
-  if (!url) {
-    throw new Errors.ErrorCodeHighlighterServerMissingUrl();
-  }
-  let output = 'hastCompressed';
-  if (props.deferParsing === 'json') {
-    output = 'hastJson';
-  } else if (props.deferParsing === 'none') {
-    output = 'hast';
-  }
-  const {
-    code,
-    initialFilename,
-    initialSource,
-    initialExtraFiles,
-    processedGlobalsCode
-  } = await loadCodeFallback(url, initialVariant, props.code, {
-    shouldHighlight: highlightAfter === 'init',
-    fallbackUsesExtraFiles,
-    fallbackUsesAllVariants,
-    sourceParser,
-    loadSource,
-    loadVariantMeta,
-    loadCodeMeta,
-    sourceEnhancers,
-    initialFilename: fileName,
-    variants,
-    globalsCode,
-    output,
-    urlPrefix: props.urlPrefix
-  });
-  return renderWithInitialSource({
-    ...props,
-    ContentLoading,
-    code,
-    initialFilename,
-    initialSource,
-    initialExtraFiles,
-    processedGlobalsCode
-  });
-}
 export function CodeHighlighter(props) {
   // Validate mutually exclusive props
   if (props.children && (props.code || props.precompute)) {
@@ -338,62 +60,118 @@ export function CodeHighlighter(props) {
     }
   }
   const ContentLoading = props.ContentLoading;
+  const initialKey = props.initialVariant || props.variant || props.defaultVariant || variants[0];
+
+  // Map the props onto the chunk decision inputs (replaces the bespoke
+  // renderCodeHighlighter/renderWithInitialSource branching).
+  const {
+    controlled,
+    isInitial,
+    forceClient
+  } = buildCodeHighlighterChunkProps({
+    ...props,
+    code
+  });
+
+  // Render the chunk. `controlled`/`isInitial`/`forceClient` drive the decision; a
+  // prepared `fallback`/`residualFallbacks` (and the wire `Code` as `preloaded`) are
+  // threaded through when an initial paint was available up front.
+  const renderChunk = options => {
+    const userProps = {
+      ...props,
+      code: options.preloaded,
+      ContentLoading,
+      initialVariant: initialKey,
+      fallback: options.fallback,
+      residualFallbacks: options.residualFallbacks
+      // The user's content generic is erased at the chunk boundary; the real props
+      // ride through `Content`/`contentProps` and are rebuilt by `createClientProps`.
+    };
+    return /*#__PURE__*/_jsx(CodeHighlighterChunk, {
+      preloaded: options.preloaded,
+      controlled: controlled,
+      isInitial: isInitial,
+      forceClient: forceClient
+      // No ContentLoading -> no fallback to paint an initial into, so skip the
+      // initial-loader stage and load the full content directly.
+      ,
+      skipInitialLoad: !ContentLoading
+      // Stream the fallback (Suspense) only when streaming the full load behind an
+      // already-in-hand initial; otherwise block on the loader so its content is in
+      // the initial HTML (the server-initial loader streams its own 2nd stage).
+      ,
+      awaitServerLoad: !(isInitial && props.highlightAfter === 'stream'),
+      userProps: userProps
+    });
+  };
+
+  // No ContentLoading: render the content/full-load directly, with no loading
+  // fallback (the client shows nothing until content is ready). For
+  // `highlightAt: 'init'`, `createClientProps` folds each variant's highlighted-visible
+  // `fallbackCritical` over its plain `fallback`, so `<Pre>` paints the visible frames
+  // highlighted on the first render (no decompression) and decodes the full tree after
+  // paint (the `decodeAllowed` latch).
+  if (process.env.NODE_ENV !== "production") renderChunk.displayName = "renderChunk";
   if (!ContentLoading) {
     if (props.highlightAfter === 'stream') {
-      // if the user explicitly sets highlightAfter to 'stream', we need a ContentLoading component
+      // `highlightAfter: 'stream'` needs a ContentLoading component to stream into.
       throw new Errors.ErrorCodeHighlighterServerMissingContentLoading();
     }
-    return renderCodeHighlighter({
-      ...props,
-      code
+    return renderChunk({
+      preloaded: code
     });
   }
-  const initialKey = props.initialVariant || props.variant || props.defaultVariant || variants[0];
   const initial = code?.[initialKey] || props.precompute?.[initialKey];
   if (!initial && !props.components?.[initialKey]) {
     throw new Errors.ErrorCodeHighlighterServerMissingVariant(initialKey);
   }
 
-  // TODO: use initial.filesOrder to determing which source to use
-
+  // TODO: use initial.filesOrder to determine which source to use
   const {
     initialData,
     reason
   } = maybeCodeInitialData(variants, initialKey, code || props.precompute, undefined,
   // TODO: use initial.filesOrder if provided?
   props.highlightAfter === 'init', props.fallbackUsesExtraFiles, props.fallbackUsesAllVariants);
+
+  // No initial paint in hand: either the client takes over (no loader fns / forced
+  // client), or the server initial loader fetches a quick initial first.
   if (!initialData) {
     if (DEBUG) {
       // eslint-disable-next-line no-console
       console.log('Initial data not found:', reason);
     }
-
-    // Check if any loader functions are available
-    const hasAnyLoaderFunction = !!(props.loadCodeMeta || props.loadVariantMeta || props.loadSource || props.sourceParser || props.sourceTransformers);
-
-    // If no loader functions are available, skip async loading and go directly to client
-    if (!hasAnyLoaderFunction || props.forceClient) {
-      if (props.highlightAfter === 'init') {
-        throw new Errors.ErrorCodeHighlighterServerInvalidClientMode();
-      }
-      return renderCodeHighlighter({
-        ...props,
-        code
-      });
+    if (forceClient && props.highlightAfter === 'init') {
+      throw new Errors.ErrorCodeHighlighterServerInvalidClientMode();
     }
-    return /*#__PURE__*/_jsx(CodeInitialSourceLoader, {
-      ...props,
-      ContentLoading: ContentLoading,
-      initialVariant: initialKey
+    return renderChunk({
+      preloaded: code
     });
   }
-  return renderWithInitialSource({
+
+  // Initial paint in hand: prepare the loading fallback + compressed residual, and
+  // send the wire `Code` as the preloaded value.
+  const {
+    fallback,
+    residualFallbacks,
+    codeForClient
+  } = prepareInitialSource({
     ...props,
     code: initialData.code,
-    ContentLoading,
     initialVariant: initialKey,
     initialFilename: initialData.initialFilename,
     initialSource: initialData.initialSource,
-    initialExtraFiles: initialData.initialExtraFiles
+    initialExtraFiles: initialData.initialExtraFiles,
+    ContentLoading,
+    // Compressing the residual fallbacks only shrinks the server→client payload. This
+    // entry is isomorphic, so when it runs on the client (e.g. a Pages-Router app that
+    // renders everything client-side) there is no wire — skip the compress and keep the
+    // fallbacks inline rather than compressing them only to decompress them right back.
+    compressResidual: typeof window === 'undefined'
+  });
+  return renderChunk({
+    preloaded: codeForClient,
+    fallback,
+    residualFallbacks
   });
 }

package/CodeHighlighter/CodeHighlighterChunk.d.mts

@@ -0,0 +1,42 @@
+import * as React from 'react';
+import type { ChunkContentProps as CoordinatedChunkContentProps } from "../CoordinatedLazy/types.mjs";
+import type { Code, CodeHighlighterBaseProps, ContentLoadingProps } from "./types.mjs";
+import type { CompressedFallback } from "./fallbackFormat.mjs";
+/**
+ * The user props the CodeHighlighter chunk threads to its content + loaders. It
+ * carries the isomorphic CodeHighlighter props plus the values prepared up front:
+ * the rendered loading `fallback`, the compressed `residualFallbacks`, and the
+ * resolved `initialVariant`. The content generic is erased here (`{}`); the user's
+ * real content props ride through `Content`/`contentProps` and are rebuilt by
+ * `createClientProps`.
+ */
+export interface CodeHighlighterChunkUserProps extends CodeHighlighterBaseProps<{}> {
+  ContentLoading?: React.ComponentType<ContentLoadingProps<{}>>;
+  /** The resolved initial variant key. */
+  initialVariant?: string;
+  /** Pre-rendered loading fallback, when an initial paint was prepared up front. */
+  fallback?: React.ReactNode;
+  /** Compressed residual fallbacks prepared alongside `fallback`. */
+  residualFallbacks?: CompressedFallback;
+  /** Globals code already resolved from string URLs to `Code`, when available. */
+  processedGlobalsCode?: Array<Code>;
+  /** Skip rendering the loading fallback on the client swap. */
+  skipFallback?: boolean;
+}
+/** Props the chunk content/loaders receive (user props + resolved `data`/`loading`). */
+export type CodeHighlighterChunkContentProps = CoordinatedChunkContentProps<CodeHighlighterChunkUserProps, Code>;
+/**
+ * The isomorphic chunk that drives `CodeHighlighter`. `CodeHighlighter` computes the
+ * decision inputs (`controlled`/`isInitial`/`forceClient`/`awaitServerLoad`/
+ * `skipInitialLoad`) and this routes via the generic chunk decision:
+ *
+ * - content / content-initial / attempt-initial-client -> render the client directly
+ *   (it self-manages its swap).
+ * - server-loader -> dynamically import `CodeSourceLoader` (load all variants).
+ * - server-initial -> dynamically import `CodeInitialSourceLoader` (load the initial,
+ *   then re-enter this chunk to load the full content).
+ *
+ * The `Loader`/`InitialLoader` are only imported when the decision routes to them, so
+ * the heavy load/parse pipeline stays off the path that renders precomputed content.
+ */
+export declare const CodeHighlighterChunk: React.ComponentType<import("../CoordinatedLazy/index.mjs").ChunkComponentProps<CodeHighlighterChunkUserProps, Code, never>>;

package/CodeHighlighter/CodeHighlighterChunk.mjs

@@ -0,0 +1,77 @@
+import * as React from 'react';
+import { createCoordinatedLazy } from "../CoordinatedLazy/createCoordinatedLazy.mjs";
+import { createClientProps } from "./createClientProps.mjs";
+import { CodeHighlighterClient } from "./CodeHighlighterClient.mjs";
+
+/**
+ * The user props the CodeHighlighter chunk threads to its content + loaders. It
+ * carries the isomorphic CodeHighlighter props plus the values prepared up front:
+ * the rendered loading `fallback`, the compressed `residualFallbacks`, and the
+ * resolved `initialVariant`. The content generic is erased here (`{}`); the user's
+ * real content props ride through `Content`/`contentProps` and are rebuilt by
+ * `createClientProps`.
+ */
+
+/** Props the chunk content/loaders receive (user props + resolved `data`/`loading`). */
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Render the `'use client'` `CodeHighlighterClient` from the resolved chunk props.
+ * `data` is the `Code` to send to the client; the prepared `fallback`/`residualFallbacks`
+ * ride through the user props. `CodeHighlighterClient` owns its own fallback->content
+ * swap (so the chunk is configured `contentManagesSwap`).
+ */
+function CodeHighlighterChunkContent(props) {
+  const {
+    data,
+    loading,
+    ...userProps
+  } = props;
+  const clientProps = createClientProps({
+    ...userProps,
+    code: data ?? userProps.code
+  });
+  return /*#__PURE__*/_jsx(CodeHighlighterClient, {
+    ...clientProps
+  });
+}
+
+/**
+ * The chunk's loading placeholder, used as the Suspense fallback while a server
+ * loader streams. It renders the pre-prepared `<ContentLoading />` element threaded
+ * through the user props (the actual loading UI is built up front by
+ * `prepareInitialSource`).
+ */
+function CodeHighlighterChunkLoading(props) {
+  return /*#__PURE__*/_jsx(React.Fragment, {
+    children: props.fallback ?? null
+  });
+}
+
+/**
+ * The isomorphic chunk that drives `CodeHighlighter`. `CodeHighlighter` computes the
+ * decision inputs (`controlled`/`isInitial`/`forceClient`/`awaitServerLoad`/
+ * `skipInitialLoad`) and this routes via the generic chunk decision:
+ *
+ * - content / content-initial / attempt-initial-client -> render the client directly
+ *   (it self-manages its swap).
+ * - server-loader -> dynamically import `CodeSourceLoader` (load all variants).
+ * - server-initial -> dynamically import `CodeInitialSourceLoader` (load the initial,
+ *   then re-enter this chunk to load the full content).
+ *
+ * The `Loader`/`InitialLoader` are only imported when the decision routes to them, so
+ * the heavy load/parse pipeline stays off the path that renders precomputed content.
+ */
+export const CodeHighlighterChunk = createCoordinatedLazy({
+  ChunkContent: CodeHighlighterChunkContent,
+  ChunkLoading: CodeHighlighterChunkLoading,
+  // `CodeHighlighter` computes the decision per-render (it depends on more than the
+  // preloaded value) and passes `controlled`/`isInitial` as overrides, so the config
+  // predicates always defer (returning `false` disables the default
+  // "preloaded !== undefined" rule, which would otherwise force content mode because
+  // CodeHighlighter always has a preloaded `Code`).
+  isLoaded: () => false,
+  isInitial: () => false,
+  Loader: () => import("./CodeSourceLoader.mjs"),
+  InitialLoader: () => import("./CodeInitialSourceLoader.mjs"),
+  contentManagesSwap: true
+});