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

package/CodeHighlighter/fallbackFormat.mjs

@@ -0,0 +1,422 @@
+import { COLLAPSED_VISIBLE_FRAME_TYPES } from "../pipeline/parseSource/frameVisibility.mjs";
+import { isFrameSpan } from "../pipeline/parseSource/isFrameSpan.mjs";
+
+/**
+ * Compact serialization format for fallback HAST trees.
+ *
+ * A `FallbackNode` is either:
+ * - a plain string (text node), or
+ * - a variable-length tuple whose meaning is determined by length:
+ *   - `[tagName, children]`                                – no class, no props
+ *   - `[tagName, className, children]`                     – has class, no props
+ *   - `[tagName, className, properties, children]`         – has class and props
+ *   - `[tagName, className, properties, children, extra]`  – full
+ *
+ * Where:
+ *   - `tagName`    – HTML element name (e.g. `'span'`, `'a'`)
+ *   - `className`  – space-joined class string
+ *   - `properties` – remaining HTML properties (without `className`)
+ *   - `children`   – a single text string **or** an array of child `FallbackNode`s
+ *   - `extra`      – optional bag for anything else (data attributes, etc.)
+ *
+ * This eliminates the repeated `type`, `tagName`, `properties`, `children`,
+ * and `value` keys that make raw HAST costly in RSC payloads.
+ */
+
+/**
+ * A residual fallback that has been DEFLATE-compressed on its own. Mirrors the
+ * `{ hastCompressed }` shape of `VariantSource`.
+ *
+ * Used for the parts of a variant's fallback that the `ContentLoading`
+ * component never renders (extra files when the loading UI shows a single file,
+ * extra variants when it shows a single variant). Those residual fallbacks
+ * exist only as the DEFLATE dictionary for decompressing `hastCompressed`, so
+ * shipping them as plain `FallbackNode[]` text would be dead weight in the
+ * initial payload. They are compressed standalone — no preset text dictionary,
+ * so the blob is self-contained — and decompressed back to `FallbackNode[]`
+ * (via `decompressFallback`) only when the full content swaps in.
+ */
+
+/**
+ * Convert a HAST root into the compact `FallbackNode[]` format.
+ */
+export function hastToFallback(root) {
+  return convertChildren(root.children);
+}
+function convertChildren(children) {
+  return children.map(convertNode);
+}
+function convertNode(node) {
+  if (node.type === 'text') {
+    return node.value;
+  }
+  if (node.type === 'element') {
+    const el = node;
+    const {
+      className,
+      ...restProps
+    } = el.properties || {};
+    let classStr = '';
+    if (className != null) {
+      classStr = Array.isArray(className) ? className.join(' ') : String(className);
+    }
+    const props = Object.keys(restProps).length > 0 ? restProps : null;
+    const kids = el.children ?? [];
+
+    // Optimize single-text-child to inline string
+    let childValue;
+    if (kids.length === 1 && kids[0].type === 'text') {
+      childValue = kids[0].value;
+    } else {
+      childValue = convertChildren(kids);
+    }
+
+    // Variable-length tuple: omit trailing empty fields
+    if (props !== null) {
+      return [el.tagName, classStr, props, childValue];
+    }
+    if (classStr) {
+      return [el.tagName, classStr, childValue];
+    }
+    return [el.tagName, childValue];
+  }
+
+  // For any other node types (comment, doctype, etc.), skip
+  return '';
+}
+
+/**
+ * Convert the compact `FallbackNode[]` format back into a HAST root.
+ */
+export function fallbackToHast(nodes) {
+  // `ElementContent` (text/element) is a subset of `RootContent`, so the mapped
+  // children satisfy `Root.children` directly.
+  return {
+    type: 'root',
+    children: nodes.map(nodeToHast)
+  };
+}
+function nodeToHast(node) {
+  if (typeof node === 'string') {
+    return {
+      type: 'text',
+      value: node
+    };
+  }
+  let tagName;
+  let classStr;
+  let props;
+  let children;
+  let extra;
+  if (node.length === 2) {
+    [tagName, children] = node;
+  } else if (node.length === 3) {
+    [tagName, classStr, children] = node;
+  } else if (node.length === 5) {
+    [tagName, classStr, props, children, extra] = node;
+  } else {
+    [tagName, classStr, props, children] = node;
+  }
+  const properties = {
+    ...props,
+    ...extra
+  };
+  if (classStr) {
+    properties.className = classStr.split(' ');
+  }
+  const childNodes = typeof children === 'string' ? [{
+    type: 'text',
+    value: children
+  }] : children.map(nodeToHast);
+  return {
+    type: 'element',
+    tagName,
+    // The fallback tuple stores element props as `unknown`; assert they are
+    // valid HAST property values at this boundary (the one untyped seam).
+    properties: properties,
+    children: childNodes
+  };
+}
+
+/**
+ * Extract the text content from compact `FallbackNode[]` without
+ * converting back to HAST. Used to build DEFLATE dictionaries.
+ */
+export function fallbackToText(nodes) {
+  return nodes.map(nodeText).join('');
+}
+function nodeText(node) {
+  if (typeof node === 'string') {
+    return node;
+  }
+  // children is always the last element (or second-to-last when extra is present)
+  const children = node.length === 5 ? node[3] : node[node.length - 1];
+  if (typeof children === 'string') {
+    return children;
+  }
+  return children.map(nodeText).join('');
+}
+
+/**
+ * Collects the plain text of a frame from its `.line` spans and the newline
+ * text nodes between them. Used only as a fallback when a frame is missing a
+ * precomputed `data.fallback` (which `addLineGutters` normally provides);
+ * walks the frame's direct children once without recursing into highlighting
+ * spans beyond their text.
+ */
+function collectFrameText(frame) {
+  let out = '';
+  const visit = nodes => {
+    for (const node of nodes) {
+      if (node.type === 'text') {
+        out += node.value;
+      } else if (node.type === 'element') {
+        visit(node.children);
+      }
+    }
+  };
+  visit(frame.children);
+  return out;
+}
+
+/**
+ * The frame's precomputed plain-text fallback (`frame.data.fallback`, set by
+ * `addLineGutters`), falling back to walking the frame's text when absent. This
+ * is the exact text the highlighted children render, so it doubles as the
+ * DEFLATE dictionary contribution for the frame.
+ */
+function framePlainText(frame) {
+  const fallbackNodes = frame.data?.fallback;
+  return fallbackNodes && fallbackNodes.length > 0 ? fallbackNodes.map(node => node.type === 'text' ? node.value : '').join('') : collectFrameText(frame);
+}
+
+/**
+ * Builds the variant-level root fallback from a final (post-enhancer) HAST
+ * root. Each `span.frame` becomes a compact frame element whose single text
+ * child is the frame's precomputed plain text (`frame.data.fallback`), so the
+ * result is directly renderable as the pre-hydration code block **and** can be
+ * redistributed back onto the decoded HAST's frames (see
+ * `redistributeRootFallback`).
+ *
+ * The frame's `data-lined` attribute is dropped (line spans don't exist in the
+ * fallback) while other frame attributes (e.g. `data-frame-type`) are kept so
+ * the fallback's layout matches the highlighted render. Non-frame top-level
+ * nodes (e.g. whitespace text between frames) are preserved in place.
+ */
+export function buildRootFallback(root) {
+  const syntheticChildren = [];
+  for (const child of root.children) {
+    if (child.type === 'element' && isFrameSpan(child)) {
+      const frame = child;
+      const {
+        dataLined,
+        ...properties
+      } = frame.properties || {};
+      syntheticChildren.push({
+        type: 'element',
+        tagName: 'span',
+        properties,
+        children: [{
+          type: 'text',
+          value: framePlainText(frame)
+        }]
+      });
+    } else {
+      syntheticChildren.push(child);
+    }
+  }
+  return convertChildren(syntheticChildren);
+}
+
+/** A frame node in compact `FallbackNode` form — `['span', 'frame', …]`, in any of the
+ *  3/4/5-element shapes (`className` is always the second element). */
+function isFrameFallbackNode(node) {
+  return Array.isArray(node) && node.length >= 3 && node[0] === 'span' && typeof node[1] === 'string' && node[1].split(' ').includes('frame');
+}
+
+/**
+ * Whether a compact `fallback` already carries highlighting — i.e. at least one frame
+ * keeps nested token spans (array children) instead of flat plain text. True exactly for
+ * the promoted {@link promoteCriticalFallback} form; a plain {@link buildRootFallback} has
+ * a string child on every frame. `<Pre>` uses this to defer the decompressing decode ONLY
+ * when the first paint is already highlighted, so it never flashes plain → highlighted.
+ */
+export function fallbackIsHighlighted(fallback) {
+  return fallback.some(node => {
+    if (!isFrameFallbackNode(node)) {
+      return false;
+    }
+    // `children` is the last tuple slot, except the 5-element form keeps `extra` last
+    // (matches `nodeText`). An array means nested token spans, i.e. highlighted.
+    const children = node.length === 5 ? node[3] : node[node.length - 1];
+    return Array.isArray(children);
+  });
+}
+
+/**
+ * The **sparse** highlighted-visible fallback: a map from frame index to the
+ * highlighted `FallbackNode` for ONLY the frames visible on the initial collapsed
+ * render (`visibleFrames`). Off-screen frames are omitted — they flatten to exactly
+ * {@link buildRootFallback}'s plain output, so storing them would just duplicate
+ * `fallback` in the precompute. {@link promoteCriticalFallback} splices these back
+ * over the plain fallback for `highlightAt: 'init'` (paint highlighted on the first
+ * render, zero decompression). Frame indices count `span.frame` children only,
+ * matching `getInitialVisibleFrames`.
+ *
+ * The decoded `root` is shared/read-only; this only reads its frames (the synthetic
+ * visible frame reuses the frame's `children` array without mutating it, and
+ * `data-lined` is dropped via destructuring, not deletion).
+ */
+export function buildCriticalFallback(root, visibleFrames) {
+  const critical = {};
+  let frameIndex = 0;
+  for (const child of root.children) {
+    if (child.type === 'element' && isFrameSpan(child)) {
+      if (visibleFrames[frameIndex]) {
+        const frame = child;
+        const {
+          dataLined,
+          ...properties
+        } = frame.properties || {};
+        const [node] = convertChildren([{
+          type: 'element',
+          tagName: 'span',
+          properties,
+          children: frame.children
+        }]);
+        critical[frameIndex] = node;
+      }
+      frameIndex += 1;
+    }
+  }
+  return critical;
+}
+
+/**
+ * Splice a sparse {@link buildCriticalFallback} diff back onto a plain `fallback`,
+ * replacing each visible frame (matched by index in document order) with its
+ * highlighted node. The result is the full highlighted-visible fallback; its text is
+ * byte-identical to `fallback` (the highlight spans only wrap the same characters), so
+ * it stays a valid DEFLATE dictionary — asserted by tests. Returns a new array; the
+ * input is not mutated.
+ */
+export function promoteCriticalFallback(fallback, critical) {
+  let frameIndex = 0;
+  return fallback.map(node => {
+    if (!isFrameFallbackNode(node)) {
+      return node;
+    }
+    const replacement = critical[frameIndex];
+    frameIndex += 1;
+    return replacement ?? node;
+  });
+}
+
+/**
+ * Redistributes a root fallback (built by `buildRootFallback`) back onto the
+ * frames of a decoded HAST root, setting each frame's `data.fallback` to the
+ * corresponding fallback frame's text nodes (as HAST, not the compact form).
+ *
+ * Frames align 1:1 by position because the root fallback and the decoded HAST
+ * are both derived from the same final tree. Non-frame fallback entries (e.g.
+ * inter-frame whitespace) advance the cursor without being assigned. Mutates
+ * `root` in place and returns it.
+ */
+export function redistributeRootFallback(root, fallback) {
+  let fallbackIndex = 0;
+  for (const child of root.children) {
+    // Advance past any non-frame fallback entries so frames stay aligned.
+    while (fallbackIndex < fallback.length && !isFallbackFrame(fallback[fallbackIndex])) {
+      fallbackIndex += 1;
+    }
+    if (child.type !== 'element' || !isFrameSpan(child)) {
+      continue;
+    }
+    if (fallbackIndex >= fallback.length) {
+      break;
+    }
+    const frameFallback = fallback[fallbackIndex];
+    fallbackIndex += 1;
+    const frame = child;
+    // The fallback frame's children are the frame's plain text.
+    const childValue = frameFallback.length === 5 ? frameFallback[3] : frameFallback[frameFallback.length - 1];
+    const nodes = typeof childValue === 'string' ? [{
+      type: 'text',
+      value: childValue
+    }] : childValue.map(node => ({
+      type: 'text',
+      value: nodeText(node)
+    }));
+    if (!frame.data) {
+      frame.data = {};
+    }
+    frame.data.fallback = nodes;
+  }
+  return root;
+}
+function isFallbackFrame(node) {
+  if (!Array.isArray(node) || node[0] !== 'span' || node.length < 3) {
+    return false;
+  }
+  const classStr = node[1];
+  return typeof classStr === 'string' && (classStr === 'frame' || classStr.split(' ').includes('frame'));
+}
+function fallbackFrameType(frame) {
+  // Properties (carrying `dataFrameType`) live at index 2 of the 4- and
+  // 5-element tuple forms; the shorter forms have no properties.
+  if (frame.length >= 4) {
+    const frameType = frame[2]?.dataFrameType;
+    return typeof frameType === 'string' ? frameType : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Reduce a root fallback to the frames visible while the code block is
+ * collapsed — the contiguous focused window (`padding-top`, `highlighted` /
+ * `focus`, `padding-bottom`). Inter-frame nodes inside that window are kept so
+ * the slice renders with the same spacing as the full fallback.
+ *
+ * Matches the runtime rule in `Pre.tsx`: when a block has no emphasis frames
+ * (the whole source is the focused window) the first frame stands in. Returns
+ * the input unchanged when it has no frames at all.
+ *
+ * When `collapsesToEmpty` is `true` the source records `focusedLines === 0`
+ * (the `oversizedFocus: 'hide'` collapse-to-nothing case): the collapsed window
+ * is intentionally empty, so the first-frame fallback is skipped and an empty
+ * array is returned. Mirrors the runtime rule in `Pre.tsx` /
+ * `getInitialVisibleSourceLines`.
+ *
+ * Used by `fallbackCollapsed` to paint only the on-screen lines while the
+ * file's full fallback rides along compressed (see the prop-compression
+ * pattern's "Splitting the Fallback by Visibility").
+ */
+export function collapsedVisibleFallback(fallback, collapsesToEmpty = false) {
+  if (collapsesToEmpty) {
+    return [];
+  }
+  let firstFrame = -1;
+  let firstVisible = -1;
+  let lastVisible = -1;
+  for (let index = 0; index < fallback.length; index += 1) {
+    const node = fallback[index];
+    if (!isFallbackFrame(node)) {
+      continue;
+    }
+    if (firstFrame === -1) {
+      firstFrame = index;
+    }
+    const frameType = fallbackFrameType(node);
+    if (frameType && COLLAPSED_VISIBLE_FRAME_TYPES.has(frameType)) {
+      if (firstVisible === -1) {
+        firstVisible = index;
+      }
+      lastVisible = index;
+    }
+  }
+  if (firstVisible === -1) {
+    // No emphasis frames: the first frame is the collapsed window.
+    return firstFrame === -1 ? fallback : [fallback[firstFrame]];
+  }
+  return fallback.slice(firstVisible, lastVisible + 1);
+}

package/CodeHighlighter/index.d.mts

@@ -1 +1,4 @@
-export * from "./CodeHighlighter.mjs";
+export * from "./CodeHighlighter.mjs";
+export { useCodeFallback } from "./useCodeFallback.mjs";
+export type { UseCodeFallbackResult } from "./useCodeFallback.mjs";
+export { mergeComments } from "./mergeComments.mjs";

package/CodeHighlighter/index.mjs

@@ -1 +1,3 @@
-export * from "./CodeHighlighter.mjs";
+export * from "./CodeHighlighter.mjs";
+export { useCodeFallback } from "./useCodeFallback.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). Comments are 1-indexed everywhere ' + '(a `0` key means something emitted 0-indexed comments); both inputs must be ' + '1-indexed or markers will land on the wrong lines.');
+}

package/CodeHighlighter/prepareInitialSource.d.mts

@@ -0,0 +1,42 @@
+import * as React from 'react';
+import type { Code, CodeHighlighterBaseProps, ContentLoadingProps, VariantExtraFiles, VariantSource } from "./types.mjs";
+import type { CompressedFallback } from "./fallbackFormat.mjs";
+export interface PrepareInitialSourceOptions<T extends {}> extends CodeHighlighterBaseProps<T> {
+  code: Code;
+  initialVariant: string;
+  initialFilename: string | undefined;
+  initialSource: VariantSource;
+  initialExtraFiles?: VariantExtraFiles;
+  ContentLoading: React.ComponentType<ContentLoadingProps<T>>;
+  /**
+   * Whether to DEFLATE-compress the consolidated residual fallbacks. This only
+   * shrinks the server→client serialized payload, so it pays off only when the
+   * result actually crosses that wire (a server render). On the client there is no
+   * wire — compressing here just to have `CodeHighlighterClient` decompress it right
+   * back is a wasted round-trip — so the isomorphic `CodeHighlighter` entry passes
+   * `typeof window === 'undefined'`. Defaults to `true` for the server-only loaders
+   * (and tests) that always produce wire output; when `false`, the fallbacks stay
+   * inline on `codeForClient`.
+   */
+  compressResidual?: boolean;
+}
+export interface PreparedInitialSource {
+  /** The pre-rendered loading fallback (`<ContentLoading />`). */
+  fallback: React.ReactNode;
+  /**
+   * The variant/file fallbacks the loading UI won't render, consolidated into a
+   * single DEFLATE blob. Absent when there is nothing worth compressing.
+   */
+  residualFallbacks?: CompressedFallback;
+  /** The `Code` to send to the client (fallbacks stripped/wired out when compressed). */
+  codeForClient: Code;
+}
+/**
+ * Prepare the loading fallback and the wire `Code` from the initial source. Hoists
+ * the rendered subset onto `ContentLoading` props, strips those fallback HASTs off
+ * `Code`, and consolidates the rest into a compressed `residualFallbacks` blob the
+ * client decodes against the rendered text. The render *decision* (client vs server
+ * load, stream vs await) is the chunk's job; this is just the shared preparation
+ * used by the content path and the server loaders.
+ */
+export declare function prepareInitialSource<T extends {}>(props: PrepareInitialSourceOptions<T>): PreparedInitialSource;