@mui/internal-docs-infra 0.11.1-canary.19 → 0.11.1-canary.20

package/CodeHighlighter/types.d.mts

@@ -204,6 +204,7 @@ export type Code = {
 export type CollapseMap = Record<number, Array<{
   offset: number;
   comments: string[];
+  boundary?: true;
 }>>;
 export type ControlledVariantExtraFiles = {
   [fileName: string]: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.11.1-canary.19",
+  "version": "0.11.1-canary.20",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",
@@ -768,5 +768,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "5c3a1cfc4629c88f92e1f1c2833ae30c2d53c4cf"
+  "gitSha": "b61bf7023e4336cc842f108768ebbdfd79e56fad"
 }

package/pipeline/hastUtils/hastDecompress.mjs

@@ -19,13 +19,19 @@ export function decompressHast(base64, textContent) {
   const dictionary = buildDictionary(textContent);
   if (textContent != null) {
     verifyChecksum(raw, dictionary);
-    return strFromU8(inflateSync(raw.subarray(CHECKSUM_BYTES), {
+  }
+  try {
+    const deflated = textContent != null ? raw.subarray(CHECKSUM_BYTES) : raw;
+    return strFromU8(inflateSync(deflated, {
       dictionary
     }));
+  } catch (error) {
+    // A raw inflate failure (e.g. fflate's "unexpected EOF") is almost always a
+    // payload that was compressed with a fallback dictionary being decoded
+    // without one — the checksum prefix is then read as deflate data. Surface
+    // that cause instead of the cryptic `{code:0}` the raw error stringifies to.
+    throw new Error(`Failed to decompress payload${textContent == null ? ' — if it was compressed with a fallback dictionary, that dictionary must be provided' : ''}: ${error instanceof Error ? error.message : String(error)}`);
   }
-  return strFromU8(inflateSync(raw, {
-    dictionary
-  }));
 }
 
 /**

package/pipeline/hastUtils/hastUtils.mjs

@@ -28,13 +28,13 @@ export function hastOrJsonToJsx(hastOrJson, components, fallback) {
     try {
       hast = JSON.parse(hastOrJson.hastJson);
     } catch (error) {
-      throw new Error(`Failed to parse hastJson: ${JSON.stringify(error)}`);
+      throw new Error(`Failed to parse hastJson: ${error instanceof Error ? error.message : String(error)}`);
     }
   } else if ('hastCompressed' in hastOrJson) {
     try {
       hast = JSON.parse(decompressHast(hastOrJson.hastCompressed, fallbackDictionary(fallback)));
     } catch (error) {
-      throw new Error(`Failed to parse hastCompressed: ${JSON.stringify(error)}`);
+      throw new Error(`Failed to parse hastCompressed: ${error instanceof Error ? error.message : String(error)}`);
     }
   } else {
     hast = hastOrJson;
@@ -55,13 +55,13 @@ export function stringOrHastToString(source, fallback) {
     try {
       hast = JSON.parse(source.hastJson);
     } catch (error) {
-      throw new Error(`Failed to parse hastJson: ${JSON.stringify(error)}`);
+      throw new Error(`Failed to parse hastJson: ${error instanceof Error ? error.message : String(error)}`);
     }
   } else if ('hastCompressed' in source) {
     try {
       hast = JSON.parse(decompressHast(source.hastCompressed, fallbackDictionary(fallback)));
     } catch (error) {
-      throw new Error(`Failed to parse hastCompressed: ${JSON.stringify(error)}`);
+      throw new Error(`Failed to parse hastCompressed: ${error instanceof Error ? error.message : String(error)}`);
     }
   } else {
     hast = source;
@@ -79,13 +79,13 @@ export function stringOrHastToJsx(source, highlighted, components, fallback) {
     try {
       hast = JSON.parse(source.hastJson);
     } catch (error) {
-      throw new Error(`Failed to parse hastJson: ${JSON.stringify(error)}`);
+      throw new Error(`Failed to parse hastJson: ${error instanceof Error ? error.message : String(error)}`);
     }
   } else if ('hastCompressed' in source) {
     try {
       hast = JSON.parse(decompressHast(source.hastCompressed, fallbackDictionary(fallback)));
     } catch (error) {
-      throw new Error(`Failed to parse hastCompressed: ${JSON.stringify(error)}`);
+      throw new Error(`Failed to parse hastCompressed: ${error instanceof Error ? error.message : String(error)}`);
     }
   } else {
     hast = source;

package/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.mjs

@@ -297,13 +297,16 @@ function reportPreview(context, sourceCode, {
       if (options.wrapReturn && returnStatement) {
         const hasParens = hasReturnParens(sourceCode, returnStatement);
         if (hasParens) {
-          // Already `return (...)` — just insert the comment inside
+          // Already `return (...)` — just insert the comment inside. The focus
+          // sits one level deeper than the function body, so `@padding 2` keeps
+          // the `return (` line and the function signature/closing brace visible
+          // as context when collapsed.
           const lineStartOffset = sourceCode.getIndexFromLoc({
             line: firstNode.loc.start.line,
             column: 0
           });
           if (isSingleLine) {
-            return fixer.insertTextBeforeRange([lineStartOffset, lineStartOffset], `${indentation}// @focus\n`);
+            return fixer.insertTextBeforeRange([lineStartOffset, lineStartOffset], `${indentation}// @focus @padding 2\n`);
           }
           const lastLineStartOffset = sourceCode.getIndexFromLoc({
             line: lastNode.loc.end.line,
@@ -311,7 +314,7 @@ function reportPreview(context, sourceCode, {
           });
           const lastLine = sourceCode.lines[lastNode.loc.end.line - 1];
           const lastIndentation = lastLine.match(/^\s*/)?.[0] ?? '';
-          return [fixer.insertTextBeforeRange([lineStartOffset, lineStartOffset], `${indentation}// @focus-start\n`), fixer.insertTextAfterRange([lastLineStartOffset, lastLineStartOffset + lastLine.length], `\n${lastIndentation}// @focus-end`)];
+          return [fixer.insertTextBeforeRange([lineStartOffset, lineStartOffset], `${indentation}// @focus-start @padding 2\n`), fixer.insertTextAfterRange([lastLineStartOffset, lastLineStartOffset + lastLine.length], `\n${lastIndentation}// @focus-end`)];
         }
 
         // No parens — wrap `return <X>` into `return (\n  // comment\n  <X>\n)`
@@ -319,9 +322,9 @@ function reportPreview(context, sourceCode, {
         const returnIndentation = sourceCode.lines[returnStatement.loc.start.line - 1].match(/^\s*/)?.[0] ?? '';
         const innerIndentation = `${returnIndentation}  `;
         if (isSingleLine) {
-          return [fixer.replaceTextRange([returnKeywordEnd, firstNode.range[0]], ` (\n${innerIndentation}// @focus\n${innerIndentation}`), fixer.insertTextAfterRange(lastNode.range, `\n${returnIndentation})`)];
+          return [fixer.replaceTextRange([returnKeywordEnd, firstNode.range[0]], ` (\n${innerIndentation}// @focus @padding 2\n${innerIndentation}`), fixer.insertTextAfterRange(lastNode.range, `\n${returnIndentation})`)];
         }
-        return [fixer.replaceTextRange([returnKeywordEnd, firstNode.range[0]], ` (\n${innerIndentation}// @focus-start\n${innerIndentation}`), fixer.insertTextAfterRange(lastNode.range, `\n${innerIndentation}// @focus-end\n${returnIndentation})`)];
+        return [fixer.replaceTextRange([returnKeywordEnd, firstNode.range[0]], ` (\n${innerIndentation}// @focus-start @padding 2\n${innerIndentation}`), fixer.insertTextAfterRange(lastNode.range, `\n${innerIndentation}// @focus-end\n${returnIndentation})`)];
       }
 
       // Non-wrapper: wrapReturn with implicit-return arrow — wrap expression in parens with comment.
@@ -332,9 +335,9 @@ function reportPreview(context, sourceCode, {
           const arrowIndentation = sourceCode.lines[arrowToken.loc.start.line - 1].match(/^\s*/)?.[0] ?? '';
           const innerIndentation = `${arrowIndentation}  `;
           if (isSingleLine) {
-            return [fixer.replaceTextRange([arrowToken.range[1], firstNode.range[0]], ` (\n${innerIndentation}// @focus\n${innerIndentation}`), fixer.insertTextAfterRange(lastNode.range, `\n${arrowIndentation})`)];
+            return [fixer.replaceTextRange([arrowToken.range[1], firstNode.range[0]], ` (\n${innerIndentation}// @focus @padding 2\n${innerIndentation}`), fixer.insertTextAfterRange(lastNode.range, `\n${arrowIndentation})`)];
           }
-          return [fixer.replaceTextRange([arrowToken.range[1], firstNode.range[0]], ` (\n${innerIndentation}// @focus-start\n${innerIndentation}`), fixer.insertTextAfterRange(lastNode.range, `\n${innerIndentation}// @focus-end\n${arrowIndentation})`)];
+          return [fixer.replaceTextRange([arrowToken.range[1], firstNode.range[0]], ` (\n${innerIndentation}// @focus-start @padding 2\n${innerIndentation}`), fixer.insertTextAfterRange(lastNode.range, `\n${innerIndentation}// @focus-end\n${arrowIndentation})`)];
         }
       }
 

package/pipeline/loadIsomorphicCodeVariant/decodeSource.d.mts

@@ -0,0 +1,19 @@
+import type { VariantSource } from "../../CodeHighlighter/types.mjs";
+import type { FallbackNode } from "../../CodeHighlighter/fallbackFormat.mjs";
+/**
+ * Decode a `VariantSource` into a form that carries no serialization: a plain
+ * string stays a string, while a serialized `hastCompressed` / `hastJson`
+ * payload (or a live `HastRoot`) resolves to a live `HastRoot`. The
+ * `{ hastJson }` / `{ hastCompressed }` shapes never leak out, so consumers can
+ * read the source as text (`stringOrHastToString`) or inspect / transform the
+ * HAST tree directly without handling a DEFLATE dictionary.
+ *
+ * Decoding reuses the shared `decodeHastSource` cache — so a source already
+ * decoded for rendering is not inflated again — then returns a
+ * `structuredClone` of the tree. The clone matters: `decodeHastSource` hands
+ * back a read-only tree shared with the live render, and the result here is
+ * handed to user code (the `transformVariant` hook), which must be able to
+ * mutate it without corrupting that shared tree. `fallback` is the DEFLATE
+ * dictionary for a `hastCompressed` source.
+ */
+export declare function decodeSource(source: VariantSource, fallback?: FallbackNode[]): VariantSource;

package/pipeline/loadIsomorphicCodeVariant/decodeSource.mjs

@@ -0,0 +1,25 @@
+import { decodeHastSource } from "./decodeHastSource.mjs";
+
+/**
+ * Decode a `VariantSource` into a form that carries no serialization: a plain
+ * string stays a string, while a serialized `hastCompressed` / `hastJson`
+ * payload (or a live `HastRoot`) resolves to a live `HastRoot`. The
+ * `{ hastJson }` / `{ hastCompressed }` shapes never leak out, so consumers can
+ * read the source as text (`stringOrHastToString`) or inspect / transform the
+ * HAST tree directly without handling a DEFLATE dictionary.
+ *
+ * Decoding reuses the shared `decodeHastSource` cache — so a source already
+ * decoded for rendering is not inflated again — then returns a
+ * `structuredClone` of the tree. The clone matters: `decodeHastSource` hands
+ * back a read-only tree shared with the live render, and the result here is
+ * handed to user code (the `transformVariant` hook), which must be able to
+ * mutate it without corrupting that shared tree. `fallback` is the DEFLATE
+ * dictionary for a `hastCompressed` source.
+ */
+export function decodeSource(source, fallback) {
+  if (typeof source === 'string') {
+    return source;
+  }
+  const root = decodeHastSource(source, fallback);
+  return root ? structuredClone(root) : source;
+}

package/pipeline/loadIsomorphicCodeVariant/decodeSourceToText.d.mts

@@ -0,0 +1,17 @@
+import type { VariantSource } from "../../CodeHighlighter/types.mjs";
+import type { FallbackNode } from "../../CodeHighlighter/fallbackFormat.mjs";
+/**
+ * Decode a `VariantSource` to its plain text, reusing the shared
+ * `decodeHastSource` cache so a `hastCompressed` / `hastJson` payload that was
+ * already decoded for rendering is not inflated and parsed a second time.
+ *
+ * String sources are returned unchanged and need no `fallback`. For an encoded
+ * source, `fallback` supplies the DEFLATE dictionary required to decode a
+ * `hastCompressed` payload (the file's compact fallback text); omitting it for
+ * such a payload surfaces a descriptive error from `decodeHastSource` rather
+ * than a cryptic inflate failure.
+ *
+ * `null` / `undefined` sources resolve to an empty string so callers can treat
+ * a missing source the same as an empty file.
+ */
+export declare function decodeSourceToText(source: VariantSource | null | undefined, fallback?: FallbackNode[]): string;

package/pipeline/loadIsomorphicCodeVariant/decodeSourceToText.mjs

@@ -0,0 +1,26 @@
+import { toText } from 'hast-util-to-text';
+import { decodeHastSource } from "./decodeHastSource.mjs";
+
+/**
+ * Decode a `VariantSource` to its plain text, reusing the shared
+ * `decodeHastSource` cache so a `hastCompressed` / `hastJson` payload that was
+ * already decoded for rendering is not inflated and parsed a second time.
+ *
+ * String sources are returned unchanged and need no `fallback`. For an encoded
+ * source, `fallback` supplies the DEFLATE dictionary required to decode a
+ * `hastCompressed` payload (the file's compact fallback text); omitting it for
+ * such a payload surfaces a descriptive error from `decodeHastSource` rather
+ * than a cryptic inflate failure.
+ *
+ * `null` / `undefined` sources resolve to an empty string so callers can treat
+ * a missing source the same as an empty file.
+ */
+export function decodeSourceToText(source, fallback) {
+  if (source == null || typeof source === 'string') {
+    return source ?? '';
+  }
+  const root = decodeHastSource(source, fallback);
+  return root ? toText(root, {
+    whitespace: 'pre'
+  }) : '';
+}

package/pipeline/loadIsomorphicCodeVariant/flattenCodeVariant.mjs

@@ -4,7 +4,7 @@
  * Uses addPathsToVariant for the core logic, then flattens the result
  */
 
-import { stringOrHastToString } from "../hastUtils/index.mjs";
+import { decodeSourceToText } from "./decodeSourceToText.mjs";
 import { addPathsToVariant } from "./addCodeVariantPaths.mjs";
 /**
  * Flatten a VariantCode into a flat files structure
@@ -21,8 +21,9 @@ export function flattenCodeVariant(variant) {
   if (variantWithPaths.path && variantWithPaths.source !== undefined) {
     result[variantWithPaths.path] = {
       // The source may be `hastCompressed`; its `fallback` is the DEFLATE
-      // dictionary needed to decode it back to text.
-      source: stringOrHastToString(variantWithPaths.source, variantWithPaths.fallback)
+      // dictionary needed to decode it back to text. `decodeSourceToText` reuses
+      // the shared decode cache rather than re-inflating on every export.
+      source: decodeSourceToText(variantWithPaths.source, variantWithPaths.fallback)
     };
   }
 
@@ -39,7 +40,7 @@ export function flattenCodeVariant(variant) {
         continue;
       }
       result[fileWithPath.path] = {
-        source: stringOrHastToString(fileWithPath.source || '', fileWithPath.fallback),
+        source: decodeSourceToText(fileWithPath.source, fileWithPath.fallback),
         ...(fileWithPath.metadata && {
           metadata: fileWithPath.metadata
         })

package/pipeline/parseSource/addLineGutters.mjs

@@ -159,7 +159,17 @@ export function starryNightGutter(tree, sourceLines, frameSize = 120) {
           const startLine = Number(lineChildren[0].properties.dataLn) - 1;
           const endLine = Number(lineChildren[lineChildren.length - 1].properties.dataLn);
           const joined = sourceLines.slice(startLine, endLine).join('\n');
-          const text = frameIndex < lastIndex ? `${joined}\n` : joined;
+          // Non-final frames are always followed by more content, so their text
+          // ends with the line separator. The final frame's text ends with a
+          // newline only when the source itself does — mirroring the highlighted
+          // render, whose last `.line` span is then followed by a trailing `\n`
+          // text node. `sourceLines` has one more entry than `lineNumber` exactly
+          // when the source ended with a newline (the empty segment after it
+          // never became a line). This keeps the plain-text fallback the same
+          // height as the highlighted render (no hydration jump) AND makes the
+          // root fallback dictionary an exact match for the raw source text.
+          const sourceEndsWithNewline = sourceLines.length > lineNumber;
+          const text = frameIndex < lastIndex || sourceEndsWithNewline ? `${joined}\n` : joined;
           // Cast to `ElementData` because `hast-util-from-parse5` augments
           // it with a required `position` field (upstream bug — should be
           // optional). We're not running through that parser here, so the