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

package/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.mjs

@@ -33,6 +33,16 @@ const RESERVED_DATA_PROPS = new Set(['dataFilename',
  * Filters out reserved properties and returns remaining data-* attributes.
  * Converts from camelCase (dataTitle) to kebab-case keys (title).
  */
+
+function parseDataBoolean(value) {
+  if (value === true || value === 'true' || value === '') {
+    return true;
+  }
+  if (value === false || value === 'false') {
+    return false;
+  }
+  return undefined;
+}
 function extractUserProps(codeElement) {
   const props = codeElement.properties;
   if (!props) {
@@ -44,6 +54,13 @@ function extractUserProps(codeElement) {
     if (key.startsWith('data') && key.length > 4 && !RESERVED_DATA_PROPS.has(key)) {
       // Convert dataTitle -> title, dataHighlight -> highlight
       const propName = key.charAt(4).toLowerCase() + key.slice(5);
+      if (propName === 'collapseToEmpty' || propName === 'initialExpanded') {
+        const parsed = parseDataBoolean(value);
+        if (parsed !== undefined) {
+          userProps[propName] = parsed;
+        }
+        continue;
+      }
       // Convert value to string
       userProps[propName] = String(value);
     }
@@ -112,8 +129,20 @@ function stripJsxExpressionSemicolon(source) {
 }
 
 /**
- * Extracts code elements and filenames from semantic HTML structure
- * Handles both section/figure/dl and standalone dl structures
+ * A single code element extracted from a dl pair (dt for the filename, dd for the code).
+ * Multiple files may belong to the same variant.
+ */
+
+/**
+ * A variant extracted from the semantic structure. A variant maps to one figure
+ * inside a section (multi-variant) or to a single standalone dl/pre (single variant).
+ * The first entry in `files` is treated as the variant's main source; any
+ * subsequent entries become `extraFiles`.
+ */
+
+/**
+ * Extracts variants and their files from semantic HTML structure.
+ * Handles both `<section>` (with one or more `<figure>` children) and standalone `<dl>`.
  */
 function extractCodeFromSemanticStructure(element) {
   const results = [];
@@ -121,7 +150,7 @@ function extractCodeFromSemanticStructure(element) {
     // Handle section with multiple figures
     const figures = element.children.filter(child => child.type === 'element' && child.tagName === 'figure');
     for (const figure of figures) {
-      // Extract variant name from figcaption
+      // Extract variant name from figcaption (the literal " variant" suffix is stripped)
       let variantName;
       const figcaption = figure.children.find(child => child.type === 'element' && child.tagName === 'figcaption');
       if (figcaption && figcaption.children[0] && figcaption.children[0].type === 'text') {
@@ -131,67 +160,74 @@ function extractCodeFromSemanticStructure(element) {
       // Find dl element in figure
       const dl = figure.children.find(child => child.type === 'element' && child.tagName === 'dl');
       if (dl) {
-        const extracted = extractFromDl(dl);
-        if (extracted) {
+        const files = extractFromDl(dl);
+        if (files.length > 0) {
+          // figcaption takes precedence; data-variant on the first code element is a fallback.
+          const firstDataVariant = files[0].codeElement.properties?.dataVariant;
           results.push({
-            codeElement: extracted.codeElement,
-            filename: extracted.filename,
-            language: extracted.language,
-            variantName: variantName || extracted.variantName
+            variantName: variantName || firstDataVariant,
+            files
           });
         }
       }
     }
   } else if (element.tagName === 'dl') {
     // Handle standalone dl
-    const extracted = extractFromDl(element);
-    if (extracted) {
-      results.push(extracted);
+    const files = extractFromDl(element);
+    if (files.length > 0) {
+      const firstDataVariant = files[0].codeElement.properties?.dataVariant;
+      results.push({
+        variantName: firstDataVariant,
+        files
+      });
     }
   }
   return results;
 }
 
 /**
- * Extracts code element and filename from a dl element
+ * Extracts every dt/dd pair from a `<dl>` element.
+ * Pairs are matched positionally: each `<dt>` is bound to the first subsequent
+ * `<dd>` containing a `<pre><code>` element. A `<dd>` without a preceding `<dt>`
+ * is treated as a file with no explicit filename.
  */
 function extractFromDl(dl) {
-  // Find dt for filename and dd for code
-  let filename;
-  let codeElement;
+  const files = [];
+  let pendingFilename;
+  let hasPendingFilename = false;
   for (const child of dl.children) {
-    if (child.type === 'element') {
-      if (child.tagName === 'dt') {
-        // Extract filename from dt > code
-        const codeInDt = child.children.find(dtChild => dtChild.type === 'element' && dtChild.tagName === 'code');
-        if (codeInDt && codeInDt.children[0] && codeInDt.children[0].type === 'text') {
-          filename = codeInDt.children[0].value;
-        }
-      } else if (child.tagName === 'dd') {
-        // Extract code from dd > pre > code
-        const pre = child.children.find(ddChild => ddChild.type === 'element' && ddChild.tagName === 'pre');
-        if (pre) {
-          const code = pre.children.find(preChild => preChild.type === 'element' && preChild.tagName === 'code');
-          if (code) {
-            codeElement = code;
-          }
-        }
+    if (child.type !== 'element') {
+      continue;
+    }
+    if (child.tagName === 'dt') {
+      // Extract filename from dt > code
+      const codeInDt = child.children.find(dtChild => dtChild.type === 'element' && dtChild.tagName === 'code');
+      if (codeInDt && codeInDt.children[0] && codeInDt.children[0].type === 'text') {
+        pendingFilename = codeInDt.children[0].value;
+      } else {
+        pendingFilename = undefined;
+      }
+      hasPendingFilename = true;
+    } else if (child.tagName === 'dd') {
+      // Extract code from dd > pre > code
+      const pre = child.children.find(ddChild => ddChild.type === 'element' && ddChild.tagName === 'pre');
+      if (!pre) {
+        continue;
+      }
+      const codeElement = pre.children.find(preChild => preChild.type === 'element' && preChild.tagName === 'code');
+      if (!codeElement) {
+        continue;
       }
+      files.push({
+        codeElement,
+        filename: hasPendingFilename ? pendingFilename : undefined,
+        language: getLanguage(codeElement)
+      });
+      pendingFilename = undefined;
+      hasPendingFilename = false;
     }
   }
-  if (codeElement) {
-    // Extract variant name from data-variant if available
-    const variantName = codeElement.properties?.dataVariant;
-    // Extract language from className
-    const language = getLanguage(codeElement);
-    return {
-      codeElement,
-      filename,
-      language,
-      variantName
-    };
-  }
-  return null;
+  return files;
 }
 
 /**
@@ -214,10 +250,11 @@ export const transformHtmlCodeBlock = (options = {}) => {
     const sourceTransformers = [TypescriptToJavascriptTransformer];
     const sourceEnhancers = [createEnhanceCodeEmphasis({
       paddingFrameMaxSize: options.paddingFrameMaxSize ?? DEFAULT_PADDING_FRAME_MAX_SIZE,
-      focusFramesMaxSize: options.focusFramesMaxSize ?? DEFAULT_FOCUS_FRAMES_MAX_SIZE
+      focusFramesMaxSize: options.focusFramesMaxSize ?? DEFAULT_FOCUS_FRAMES_MAX_SIZE,
+      oversizedFocus: options.oversizedFocus
     })];
     visit(tree, 'element', node => {
-      let extractedElements = [];
+      let extractedVariants = [];
 
       // Handle basic pre > code structure from standard markdown
       if (node.tagName === 'pre' && node.children && node.children.length > 0 && !node.properties?.dataPrecompute // Don't process if already processed
@@ -229,37 +266,38 @@ export const transformHtmlCodeBlock = (options = {}) => {
           const filename = getFileName(codeElement);
           // Extract language from className
           const language = getLanguage(codeElement);
-          extractedElements = [{
-            codeElement,
-            filename,
-            language,
-            variantName: undefined // Basic pre > code doesn't have variants
+          extractedVariants = [{
+            variantName: undefined,
+            // Basic pre > code doesn't have variants
+            files: [{
+              codeElement,
+              filename,
+              language
+            }]
           }];
         }
       }
       // Look for section elements (multi-variant) or dl elements (single variant)
       else if ((node.tagName === 'section' || node.tagName === 'dl') && node.children && node.children.length > 0) {
-        // Extract code elements from semantic structure
-        extractedElements = extractCodeFromSemanticStructure(node);
+        // Extract variants (each with one or more files) from semantic structure
+        extractedVariants = extractCodeFromSemanticStructure(node);
       }
-      if (extractedElements.length > 0) {
+      if (extractedVariants.length > 0) {
         const transformPromise = (async () => {
           try {
-            // Create variants from extracted elements
-            const variants = {};
-
-            // Process each extracted element to extract comments and prepare variants
-            const processElementForVariant = async (codeElement, filename, language, explicitVariantName, index) => {
-              let sourceCode = getHastTextContent(codeElement);
-              const derivedFilename = filename || getFileName(codeElement);
+            // Process a single file (dt/dd pair or bare pre>code) into the fields
+            // needed to populate a VariantCode `source` or `extraFiles` entry.
+            const processFile = async file => {
+              let sourceCode = getHastTextContent(file.codeElement);
+              const derivedFilename = file.filename || getFileName(file.codeElement);
 
               // Strip trailing semicolon from JSX expressions
-              if (language && JSX_LANGUAGES.has(language)) {
+              if (file.language && JSX_LANGUAGES.has(file.language)) {
                 sourceCode = stripJsxExpressionSemicolon(sourceCode);
               }
 
               // Check if displayComments is enabled - if so, don't strip comments
-              const displayComments = codeElement.properties?.dataDisplayComments === 'true';
+              const displayComments = file.codeElement.properties?.dataDisplayComments === 'true';
 
               // Parse the source to extract @highlight comments
               // When displayComments is true, we only collect comments but don't strip them
@@ -267,58 +305,68 @@ export const transformHtmlCodeBlock = (options = {}) => {
                 removeCommentsWithPrefix: displayComments ? undefined : [EMPHASIS_COMMENT_PREFIX, FOCUS_COMMENT_PREFIX, ...IGNORE_COMMENT_PREFIXES],
                 notableCommentsPrefix: [EMPHASIS_COMMENT_PREFIX, FOCUS_COMMENT_PREFIX]
               });
+              return {
+                fileName: derivedFilename,
+                language: file.language,
+                source: parseResult.code ?? sourceCode,
+                comments: parseResult.comments,
+                skipTransforms: !file.codeElement.properties?.dataTransform
+              };
+            };
 
-              // Use processed code (with comments stripped) or original
-              const processedSource = parseResult.code ?? sourceCode;
-              // Keep comments as 0-indexed - loadIsomorphicCodeVariant will convert to 1-indexed
-              const comments = parseResult.comments;
+            // Build a VariantCode for each extracted variant. The first file
+            // populates `source`/`fileName`/`language`/`comments`; any additional
+            // files become `extraFiles` entries on the same variant.
+            const buildVariant = async (extracted, index) => {
+              const processedFiles = await Promise.all(extracted.files.map(processFile));
+              const [mainFile, ...restFiles] = processedFiles;
               const variant = {
-                source: processedSource,
-                skipTransforms: !codeElement.properties?.dataTransform,
-                comments // Store comments for sourceEnhancers to use
+                source: mainFile.source,
+                skipTransforms: mainFile.skipTransforms,
+                comments: mainFile.comments
               };
-
-              // Add filename if available
-              if (derivedFilename) {
-                variant.fileName = derivedFilename;
+              if (mainFile.fileName) {
+                variant.fileName = mainFile.fileName;
               }
-
-              // Add language if available (from className)
-              if (language) {
-                variant.language = language;
+              if (mainFile.language) {
+                variant.language = mainFile.language;
               }
-              const variantName = explicitVariantName || (index === 0 ? 'Default' : `Variant ${index + 1}`);
+              if (restFiles.length > 0) {
+                const extraFiles = {};
+                for (const extra of restFiles) {
+                  // Files without an explicit filename can't be addressed as extra files; skip.
+                  if (!extra.fileName) {
+                    continue;
+                  }
+                  const entry = {
+                    source: extra.source,
+                    skipTransforms: extra.skipTransforms
+                  };
+                  if (extra.language) {
+                    entry.language = extra.language;
+                  }
+                  if (extra.comments) {
+                    entry.comments = extra.comments;
+                  }
+                  extraFiles[extra.fileName] = entry;
+                }
+                if (Object.keys(extraFiles).length > 0) {
+                  variant.extraFiles = extraFiles;
+                }
+              }
+              const variantName = extracted.variantName || (index === 0 ? 'Default' : `Variant ${index + 1}`);
               return {
                 variantName,
                 variant
               };
             };
-            if (extractedElements.length === 1) {
-              // Single element - use "Default" as variant name
-              const {
-                codeElement,
-                filename,
-                language
-              } = extractedElements[0];
-              const {
-                variantName,
-                variant
-              } = await processElementForVariant(codeElement, filename, language, undefined, 0);
+            const builtVariants = await Promise.all(extractedVariants.map(buildVariant));
+            const variants = {};
+            for (const {
+              variantName,
+              variant
+            } of builtVariants) {
               variants[variantName] = variant;
-            } else {
-              // Multiple elements - use variant names
-              const results = await Promise.all(extractedElements.map(({
-                codeElement,
-                filename,
-                language,
-                variantName
-              }, index) => processElementForVariant(codeElement, filename, language, variantName, index)));
-              for (const {
-                variantName,
-                variant
-              } of results) {
-                variants[variantName] = variant;
-              }
             }
 
             // Process each variant with loadIsomorphicCodeVariant
@@ -354,15 +402,35 @@ export const transformHtmlCodeBlock = (options = {}) => {
               }
             }
 
-            // Extract user props from the first code element (they should be the same for all variants)
-            const userProps = extractUserProps(extractedElements[0].codeElement);
+            // The first code element of the first variant carries the
+            // top-level metadata (user props, name, slug) for the demo.
+            const firstCodeElement = extractedVariants[0].files[0].codeElement;
 
-            // Clear all code element contents
-            extractedElements.forEach(({
-              codeElement
-            }) => {
-              codeElement.children = [];
-            });
+            // Extract user props from the first code element. Per-block render
+            // flags (e.g. ` ```ts collapseToEmpty ` / ` ```ts initialExpanded `)
+            // arrive as `data-*` attributes and flow through here as content
+            // props. When the block sets no flag, fall back to the transform's
+            // matching option so it can default every block.
+            let userProps = extractUserProps(firstCodeElement);
+            if (firstCodeElement.properties?.dataCollapseToEmpty === undefined && options.collapseToEmpty) {
+              userProps = {
+                ...(userProps ?? {}),
+                collapseToEmpty: true
+              };
+            }
+            if (firstCodeElement.properties?.dataInitialExpanded === undefined && options.initialExpanded) {
+              userProps = {
+                ...(userProps ?? {}),
+                initialExpanded: true
+              };
+            }
+
+            // Clear all code element contents (across every variant and every file)
+            for (const extracted of extractedVariants) {
+              for (const file of extracted.files) {
+                file.codeElement.children = [];
+              }
+            }
 
             // Replace the semantic structure with a <pre> element
             node.tagName = 'pre';
@@ -378,7 +446,6 @@ export const transformHtmlCodeBlock = (options = {}) => {
             node.properties.dataPrecompute = JSON.stringify(processedCode);
 
             // Pass through name and slug if provided on the code element
-            const firstCodeElement = extractedElements[0].codeElement;
             if (firstCodeElement.properties?.dataName) {
               node.properties.dataName = firstCodeElement.properties.dataName;
             }

package/pipeline/transformHtmlCodeInline/removeSuffixFromHighlightedNodes.d.mts

@@ -0,0 +1,12 @@
+import type { ElementContent } from 'hast';
+/**
+ * Removes a suffix from the end of highlighted HAST nodes.
+ *
+ * Mirror of `removePrefixFromHighlightedNodes`: used to strip temporary
+ * trailing characters that were appended to the source before highlighting
+ * (e.g., closing `)` for object-literal wrapping).
+ *
+ * @param children - The array of HAST nodes to modify
+ * @param suffixLength - The number of characters to remove from the end
+ */
+export declare function removeSuffixFromHighlightedNodes(children: ElementContent[], suffixLength: number): void;

package/pipeline/transformHtmlCodeInline/removeSuffixFromHighlightedNodes.mjs

@@ -0,0 +1,52 @@
+/**
+ * Removes a suffix from the end of highlighted HAST nodes.
+ *
+ * Mirror of `removePrefixFromHighlightedNodes`: used to strip temporary
+ * trailing characters that were appended to the source before highlighting
+ * (e.g., closing `)` for object-literal wrapping).
+ *
+ * @param children - The array of HAST nodes to modify
+ * @param suffixLength - The number of characters to remove from the end
+ */
+export function removeSuffixFromHighlightedNodes(children, suffixLength) {
+  let removedLength = 0;
+  while (removedLength < suffixLength && children.length > 0) {
+    const lastChild = children[children.length - 1];
+    if (lastChild.type === 'text') {
+      const textLength = lastChild.value.length;
+      if (removedLength + textLength <= suffixLength) {
+        children.pop();
+        removedLength += textLength;
+      } else {
+        const charsToRemove = suffixLength - removedLength;
+        lastChild.value = lastChild.value.slice(0, textLength - charsToRemove);
+        removedLength = suffixLength;
+      }
+    } else if (lastChild.type === 'element') {
+      const element = lastChild;
+      if (element.children && element.children.length > 0) {
+        const lastElementChild = element.children[element.children.length - 1];
+        if (lastElementChild.type === 'text') {
+          const textLength = lastElementChild.value.length;
+          if (removedLength + textLength <= suffixLength) {
+            element.children.pop();
+            removedLength += textLength;
+            if (element.children.length === 0) {
+              children.pop();
+            }
+          } else {
+            const charsToRemove = suffixLength - removedLength;
+            lastElementChild.value = lastElementChild.value.slice(0, textLength - charsToRemove);
+            removedLength = suffixLength;
+          }
+        } else {
+          break;
+        }
+      } else {
+        children.pop();
+      }
+    } else {
+      break;
+    }
+  }
+}

package/pipeline/transformHtmlCodeInline/transformHtmlCodeInline.mjs

@@ -3,8 +3,10 @@ import { visit } from 'unist-util-visit';
 import { grammars } from "../parseSource/grammars.mjs";
 import { extensionMap } from "../parseSource/grammarMaps.mjs";
 import { extendSyntaxTokens } from "../parseSource/extendSyntaxTokens.mjs";
+import { getLanguageCapabilitiesFromScope } from "../parseSource/languageCapabilities.mjs";
 import { getHastTextContent } from "../hastUtils/index.mjs";
 import { removePrefixFromHighlightedNodes } from "./removePrefixFromHighlightedNodes.mjs";
+import { removeSuffixFromHighlightedNodes } from "./removeSuffixFromHighlightedNodes.mjs";
 const STARRY_NIGHT_KEY = '__docs_infra_starry_night_instance__';
 
 /**
@@ -67,7 +69,14 @@ export default function transformHtmlCodeInline(options = {}) {
       const highlightingPrefix = typeof node.properties?.dataHighlightingPrefix === 'string' ? node.properties.dataHighlightingPrefix : undefined;
 
       // Temporarily prepend the prefix for proper syntax highlighting
-      const sourceToHighlight = highlightingPrefix ? `${highlightingPrefix}${source}` : source;
+      let sourceToHighlight = highlightingPrefix ? `${highlightingPrefix}${source}` : source;
+
+      // Inline JS-family snippets that look like a bare object literal (e.g. `{ height: 400 }`)
+      // are tokenized by starry-night as a block statement with labeled statements, which makes
+      // the keys appear as `pl-en` (entity name) tokens rather than property names. Wrap them
+      // in `(...)` so the snippet parses as an expression and `extendSyntaxTokens` can split
+      // out the keys via `splitObjectKeys`. The wrapping characters are stripped after highlighting.
+      let objectWrap = false;
 
       // Determine language from className (e.g., 'language-ts')
       const className = node.properties?.className;
@@ -103,6 +112,14 @@ export default function transformHtmlCodeInline(options = {}) {
       if (!fileType || !extensionMap[fileType]) {
         return;
       }
+      const grammarScope = extensionMap[fileType];
+      if (!highlightingPrefix && getLanguageCapabilitiesFromScope(grammarScope).semantics === 'js') {
+        const trimmed = sourceToHighlight.trim();
+        if (trimmed.length >= 2 && trimmed.startsWith('{') && trimmed.endsWith('}')) {
+          sourceToHighlight = `(${sourceToHighlight})`;
+          objectWrap = true;
+        }
+      }
 
       // Apply syntax highlighting
       const highlighted = starryNight.highlight(sourceToHighlight, extensionMap[fileType]);
@@ -116,6 +133,10 @@ export default function transformHtmlCodeInline(options = {}) {
         if (highlightingPrefix && node.children.length > 0) {
           removePrefixFromHighlightedNodes(node.children, highlightingPrefix.length);
         }
+        if (objectWrap && node.children.length > 0) {
+          removePrefixFromHighlightedNodes(node.children, 1);
+          removeSuffixFromHighlightedNodes(node.children, 1);
+        }
       }
 
       // Mark this code element as inline highlighted (only for inline code, not pre>code)

package/pipeline/transformTypescriptToJavascript/removeTypes.d.mts

@@ -1,13 +1,10 @@
-import type { Options as PrettierOptions } from 'prettier';
 /**
- * Strips TypeScript types and decorators from code (including React in TSX),
- * preserving blank lines and optionally formatting with Prettier.
+ * Strips TypeScript types and decorators from code (including JSX in TSX),
+ * preserving line numbers so source maps and diff tooling stay aligned.
  *
  * @param code - The source code string to transform.
  * @param filename - The name of the file (e.g. "foo.ts" or "Foo.tsx").
- *                   Determines whether TSX parsing is enabled.
- * @param prettierConfig - `true` for default formatting, `false` to skip,
- *                         or a Prettier options object to customize.
- * @returns The transformed (and optionally formatted) code.
+ *                   Determines whether TSX/JSX parsing is enabled.
+ * @returns The transformed code with TypeScript syntax removed.
  */
-export declare function removeTypes(code: string, filename?: string, prettierConfig?: PrettierOptions | boolean): Promise<string>;
+export declare function removeTypes(code: string, filename?: string): Promise<string>;