@mui/internal-docs-infra 0.4.1-canary.9 → 0.6.1-canary.0

package/cli/index.mjs

@@ -7,4 +7,4 @@ function getVersion() {
 }
 yargs().scriptName('docs-infra').usage('$0 <command> [args]').command(runValidate).demandCommand(1, 'You need at least one command before moving on').strict().help()
 // MUI_VERSION is set through the code-infra build command.
-.version("0.4.0" || getVersion()).parse(hideBin(process.argv));
+.version("0.6.0" || getVersion()).parse(hideBin(process.argv));

package/createSitemap/createSitemap.mjs

@@ -9,7 +9,7 @@ function isNextJsContext() {
   typeof process.env.__NEXT_PROCESSED_ENV === 'string' ||
   // Next.js build
   typeof process.env.NEXT_PHASE === 'string') // Next.js build phase
-  ;
+;
 }
 
 /**

package/createSitemap/types.d.mts

@@ -1,3 +1,4 @@
+import type { Metadata } from 'next';
 /**
  * Section data structure from sitemap
  */
@@ -35,6 +36,8 @@ export interface SitemapPage {
   exports?: Record<string, SitemapExport>;
   tags?: string[];
   skipDetailSection?: boolean;
+  audience?: Audience;
+  index?: boolean;
   image?: {
     url: string;
     alt?: string;
@@ -59,4 +62,36 @@ export type OramaSchemaType = 'string' | 'number' | 'boolean' | 'string[]' | 'nu
 export interface Sitemap {
   schema: Record<string, OramaSchemaType>;
   data: Record<string, SitemapSectionData>;
-}
+}
+export type Audience = 'private' | 'introductory' | 'intermediate' | 'advanced' | 'business';
+/**
+ * Page metadata type extending Next.js `Metadata`.
+ *
+ * Adds the `audience` field under `other` using the WHATWG MetaExtensions `audience` meta name.
+ * All standard Next.js metadata fields (title, description, openGraph, etc.) remain available.
+ *
+ * @see https://nextjs.org/docs/app/api-reference/functions/generate-metadata#metadata-fields
+ */
+export type NextMetadata = Metadata & {
+  other?: {
+    /**
+     * Categorize the principal intended audience for the page.
+     * Uses the WHATWG MetaExtensions `audience` meta name.
+     *
+     * When omitted, the page is public and intended for all audiences.
+     *
+     * - `'private'`: Internal page, not intended for public consumption.
+     *   Should be paired with `robots: { index: false }` to exclude from public indexing.
+     * - `'introductory'`: Content aimed at beginners.
+     * - `'intermediate'`: Content aimed at intermediate users.
+     * - `'advanced'`: Content aimed at advanced users.
+     * - `'business'`: Content aimed at prospective customers and decision-makers
+     *   (e.g. marketing pages, pricing, product overviews).
+     *
+     * @see https://wiki.whatwg.org/wiki/MetaExtensions
+     * @see https://brittlebit.org/specifications/html-meta-audience/specification-for-html-meta-element-with-name-value-audience.html
+     */
+    audience?: Audience;
+    [key: string]: unknown;
+  };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.4.1-canary.9",
+  "version": "0.6.1-canary.0",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "keywords": [
@@ -22,12 +22,12 @@
   "homepage": "https://github.com/mui/mui-public/tree/master/packages/docs-infra",
   "dependencies": {
     "@babel/runtime": "^7.28.6",
-    "@babel/standalone": "^7.28.6",
+    "@babel/standalone": "^7.29.1",
     "@orama/orama": "^3.1.18",
     "@orama/plugin-qps": "^3.1.18",
     "@orama/stemmers": "^3.1.18",
     "@orama/stopwords": "^3.1.18",
-    "@wooorm/starry-night": "^3.8.0",
+    "@wooorm/starry-night": "^3.9.0",
     "chalk": "^5.6.2",
     "clipboard-copy": "^4.0.1",
     "fflate": "^0.8.2",
@@ -452,6 +452,16 @@
         "default": "./pipeline/loadServerSource/index.mjs"
       }
     },
+    "./pipeline/enhanceCodeEmphasis": {
+      "import": {
+        "types": "./pipeline/enhanceCodeEmphasis/index.d.mts",
+        "default": "./pipeline/enhanceCodeEmphasis/index.mjs"
+      },
+      "default": {
+        "types": "./pipeline/enhanceCodeEmphasis/index.d.mts",
+        "default": "./pipeline/enhanceCodeEmphasis/index.mjs"
+      }
+    },
     "./pipeline/parseSource": {
       "import": {
         "types": "./pipeline/parseSource/index.d.mts",
@@ -506,5 +516,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "5a397056f9e93982f8e275c0214fc882d8af3b1c"
+  "gitSha": "cad146f1682e0cb63baeeab28454423d77ef7c89"
 }

package/pipeline/enhanceCodeEmphasis/calculateFrameIndent.d.mts

@@ -0,0 +1,12 @@
+import type { Element } from 'hast';
+/**
+ * Calculates the shared indent level for a set of line elements.
+ *
+ * Finds the minimum leading whitespace across all non-empty lines,
+ * then divides by the indent size (2 spaces) and floors to get
+ * the indent level.
+ *
+ * @param lineElements - Array of HAST line elements to analyze
+ * @returns The shared indent level (e.g., 2 for 4 leading spaces with 2-space indent)
+ */
+export declare function calculateFrameIndent(lineElements: Element[]): number;

package/pipeline/enhanceCodeEmphasis/calculateFrameIndent.mjs

@@ -0,0 +1,62 @@
+const INDENT_SIZE = 2;
+
+/**
+ * Counts leading spaces in an element by walking the HAST tree.
+ *
+ * Returns the number of leading space characters before the first
+ * non-space character, or -1 if the line is empty/whitespace-only.
+ * Only counts space characters. Tab indentation is not supported
+ * since the input is HAST output from starry-night which uses spaces.
+ */
+function countLeadingSpaces(element) {
+  let spaces = 0;
+  function walk(node) {
+    for (const child of node.children) {
+      if (child.type === 'text') {
+        for (const char of child.value) {
+          if (char === ' ') {
+            spaces += 1;
+          } else {
+            return true;
+          }
+        }
+      } else if (child.type === 'element') {
+        if (walk(child)) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+  const foundNonSpace = walk(element);
+  return foundNonSpace ? spaces : -1;
+}
+
+/**
+ * Calculates the shared indent level for a set of line elements.
+ *
+ * Finds the minimum leading whitespace across all non-empty lines,
+ * then divides by the indent size (2 spaces) and floors to get
+ * the indent level.
+ *
+ * @param lineElements - Array of HAST line elements to analyze
+ * @returns The shared indent level (e.g., 2 for 4 leading spaces with 2-space indent)
+ */
+export function calculateFrameIndent(lineElements) {
+  let minLeadingSpaces = Infinity;
+  for (const element of lineElements) {
+    const leadingSpaces = countLeadingSpaces(element);
+
+    // Skip empty/whitespace-only lines
+    if (leadingSpaces === -1) {
+      continue;
+    }
+    if (leadingSpaces < minLeadingSpaces) {
+      minLeadingSpaces = leadingSpaces;
+    }
+  }
+  if (minLeadingSpaces === Infinity) {
+    return 0;
+  }
+  return Math.floor(minLeadingSpaces / INDENT_SIZE);
+}

package/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.d.mts

@@ -1,13 +1,16 @@
 import type { SourceEnhancer } from "../../CodeHighlighter/types.mjs";
+import type { EnhanceCodeEmphasisOptions } from "../parseSource/calculateFrameRanges.mjs";
+export type { EmphasisMeta, EnhanceCodeEmphasisOptions, FrameRange } from "../parseSource/calculateFrameRanges.mjs";
 /**
  * The prefix used to identify emphasis comments in source code.
  * Comments starting with this prefix will be processed for emphasis.
  */
 export declare const EMPHASIS_COMMENT_PREFIX = "@highlight";
 /**
- * Source enhancer that adds emphasis to code lines based on `@highlight` comments.
+ * Creates a source enhancer that adds emphasis to code lines based on `@highlight` comments
+ * and restructures frames around highlighted regions.
  *
- * Supports four patterns:
+ * Supports five patterns:
  *
  * 1. **Single line emphasis** - emphasizes the line containing the comment:
  *    ```jsx
@@ -37,12 +40,30 @@ export declare const EMPHASIS_COMMENT_PREFIX = "@highlight";
  *    <h1>Heading 1</h1> {/* @highlight-text "Heading 1" *\/}
  *    ```
  *
+ * 5. **Focus override** - mark a region for padding focus:
+ *    ```jsx
+ *    <h1>Heading 1</h1> {/* @highlight @focus *\/}
+ *    ```
+ *
  * Emphasized lines receive a `data-hl` attribute on their `<span class="line">` element.
+ * When highlights exist, frames are restructured with `data-frame-type` attributes
+ * (`highlighted`, `padding-top`, `padding-bottom`, or omitted for normal).
+ * Highlighted frames also receive `data-frame-indent` with the shared indent level.
+ *
+ * @param options - Optional configuration for padding frames
+ * @returns A `SourceEnhancer` function
+ *
+ * @example
+ * ```ts
+ * import { createEnhanceCodeEmphasis } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
  *
- * @param root - The HAST root node to enhance
- * @param comments - Comments extracted from the source code, keyed by line number
- * @param _fileName - The name of the file being processed (unused)
- * @returns The enhanced HAST root node with emphasis attributes added
+ * const enhancers = [createEnhanceCodeEmphasis({ paddingFrameMaxSize: 5, focusFramesMaxSize: 8 })];
+ * ```
+ */
+export declare function createEnhanceCodeEmphasis(options?: EnhanceCodeEmphasisOptions): SourceEnhancer;
+/**
+ * Default source enhancer that adds emphasis to code lines based on `@highlight` comments.
+ * Uses no padding frames by default. Use `createEnhanceCodeEmphasis` for configurable padding.
  *
  * @example
  * ```ts

package/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.mjs

@@ -1,3 +1,6 @@
+import { calculateFrameRanges } from "../parseSource/calculateFrameRanges.mjs";
+import { calculateFrameIndent } from "./calculateFrameIndent.mjs";
+import { restructureFrames } from "../parseSource/restructureFrames.mjs";
 /**
  * The prefix used to identify emphasis comments in source code.
  * Comments starting with this prefix will be processed for emphasis.
@@ -8,19 +11,15 @@ export const EMPHASIS_COMMENT_PREFIX = '@highlight';
  * Parsed emphasis directive from a comment.
  */
 
-/**
- * Metadata for an emphasized line.
- */
-
 /**
  * Extracts a quoted string from content.
  * Supports both double quotes ("...") and single quotes ('...').
+ * Escaped quotes within the string are not supported.
  *
  * @param content - The content to extract the quoted string from
  * @returns The extracted string (without quotes) or undefined if no quoted string found
  */
 function extractQuotedString(content) {
-  // Match either double-quoted or single-quoted string
   const match = content.match(/^["'](.*)["']$/);
   if (match) {
     return match[1];
@@ -30,14 +29,40 @@ function extractQuotedString(content) {
   return anyMatch?.[1];
 }
 
+/**
+ * Extracts and removes the `@focus` keyword from content.
+ *
+ * @param content - The content to check for `@focus`
+ * @returns An object with `focus` boolean and the `remaining` content with `@focus` removed
+ */
+function extractFocus(content) {
+  // Match @focus only as a standalone token (not inside quotes)
+  const match = content.match(/(^|\s)@focus(\s|$)/);
+  if (!match) {
+    return {
+      focus: false,
+      remaining: content
+    };
+  }
+  const start = match.index + match[1].length;
+  const remaining = (content.slice(0, start) + content.slice(start + '@focus'.length)).trim();
+  return {
+    focus: true,
+    remaining
+  };
+}
+
 /**
  * Parses emphasis comments and returns structured directives.
  *
  * Supported formats:
  * - Single line: `@highlight` or `@highlight "description"`
+ * - Single line focused: `@highlight @focus` or `@highlight @focus "description"`
  * - Multiline start: `@highlight-start` or `@highlight-start "description"`
+ * - Multiline start focused: `@highlight-start @focus` or `@highlight-start @focus "description"`
  * - Multiline end: `@highlight-end`
  * - Text highlight: `@highlight-text "text to highlight"`
+ * - Text highlight focused: `@highlight-text @focus "text to highlight"`
  *
  * @param comments - Source comments keyed by line number
  * @returns Array of parsed emphasis directives
@@ -63,31 +88,46 @@ function parseEmphasisDirectives(comments) {
       } else if (content.startsWith('-start')) {
         // Start of multiline emphasis: @highlight-start or @highlight-start "description"
         const afterStart = content.slice('-start'.length).trim();
-        const description = extractQuotedString(afterStart);
+        const {
+          focus,
+          remaining: remainingStart
+        } = extractFocus(afterStart);
+        const description = extractQuotedString(remainingStart);
         directives.push({
           line,
           type: 'start',
-          description
+          description,
+          focus
         });
       } else if (content.startsWith('-text')) {
         // Text highlight: @highlight-text "text to highlight"
         const afterText = content.slice('-text'.length).trim();
-        const highlightText = extractQuotedString(afterText);
+        const {
+          focus,
+          remaining: remainingText
+        } = extractFocus(afterText);
+        const highlightText = extractQuotedString(remainingText);
         if (highlightText) {
           directives.push({
             line,
             type: 'text',
-            highlightText
+            highlightText,
+            focus
           });
         }
       } else {
         // Single line emphasis: @highlight or @highlight "description"
         const afterHighlight = content.trim();
-        const description = extractQuotedString(afterHighlight) || undefined;
+        const {
+          focus,
+          remaining: remainingSingle
+        } = extractFocus(afterHighlight);
+        const description = extractQuotedString(remainingSingle) || undefined;
         directives.push({
           line,
           type: 'single',
-          description
+          description,
+          focus
         });
       }
     }
@@ -231,13 +271,15 @@ function calculateEmphasizedLines(directives, lineElements) {
       emphasizedLines.set(directive.line, {
         description,
         strong,
-        position: 'single'
+        position: 'single',
+        focus: directive.focus
       });
     } else if (directive.type === 'text') {
       // Text highlight - emphasize specific text within the line
       emphasizedLines.set(directive.line, {
         position: 'single',
-        highlightText: directive.highlightText
+        highlightText: directive.highlightText,
+        focus: directive.focus
       });
     }
   }
@@ -286,11 +328,14 @@ function calculateEmphasizedLines(directives, lineElements) {
           strong: true,
           // Nested = always strong
           description: existing.description ?? (line === startLine ? description : undefined),
-          position: existing.position ?? position // Inner range position takes precedence
+          position: existing.position ?? position,
+          // Inner range position takes precedence
+          focus: existing.focus || startDirective.focus
         } : {
           strong,
           description: line === startLine ? description : undefined,
-          position
+          position,
+          focus: startDirective.focus
         };
         emphasizedLines.set(line, meta);
       }
@@ -362,52 +407,113 @@ function wrapTextInHighlightSpan(children, textToHighlight) {
 }
 
 /**
- * Recursively finds and modifies line elements in a HAST tree.
+ * Single-pass traversal that applies emphasis attributes to line elements
+ * AND collects leading whitespace for indent calculation on highlighted lines.
+ *
+ * This merges what would otherwise be two separate traversals into one.
  *
  * @param node - The node to process
  * @param emphasizedLines - Map of line numbers to their emphasis metadata
+ * @returns Array of line elements that are highlighted, grouped by region
  */
-function addEmphasisToLines(node, emphasizedLines) {
-  if (!('children' in node) || !node.children) {
-    return;
-  }
-  for (let i = 0; i < node.children.length; i += 1) {
-    const child = node.children[i];
-    if (child.type !== 'element') {
-      continue;
+function applyEmphasisAndCollectHighlightedElements(node, emphasizedLines) {
+  const highlightedLineElements = [];
+  function traverse(n) {
+    if (!('children' in n) || !n.children) {
+      return;
     }
+    for (let i = 0; i < n.children.length; i += 1) {
+      const child = n.children[i];
+      if (child.type !== 'element') {
+        continue;
+      }
 
-    // Check if this is a line element
-    if (child.tagName === 'span' && child.properties?.className === 'line' && typeof child.properties.dataLn === 'number') {
-      const lineNumber = child.properties.dataLn;
-      const meta = emphasizedLines.get(lineNumber);
-      if (meta !== undefined) {
-        if (meta.highlightText) {
-          // For text highlight, wrap the specific text in a span with data-hl
-          // Don't add data-hl to the line itself
-          child.children = wrapTextInHighlightSpan(child.children, meta.highlightText);
-        } else {
-          // Use data-hl with optional "strong" value on the line
-          child.properties.dataHl = meta.strong ? 'strong' : '';
-          if (meta.description) {
-            child.properties.dataHlDescription = meta.description;
-          }
-          if (meta.position) {
-            child.properties.dataHlPosition = meta.position;
+      // Check if this is a line element
+      if (child.tagName === 'span' && child.properties?.className === 'line' && typeof child.properties.dataLn === 'number') {
+        const lineNumber = child.properties.dataLn;
+        const meta = emphasizedLines.get(lineNumber);
+        if (meta !== undefined) {
+          if (meta.highlightText) {
+            // For text highlight, wrap the specific text in a span with data-hl
+            // Don't add data-hl to the line itself
+            child.children = wrapTextInHighlightSpan(child.children, meta.highlightText);
+          } else {
+            // Use data-hl with optional "strong" value on the line
+            child.properties.dataHl = meta.strong ? 'strong' : '';
+            if (meta.description) {
+              child.properties.dataHlDescription = meta.description;
+            }
+            if (meta.position) {
+              child.properties.dataHlPosition = meta.position;
+            }
           }
+
+          // Collect this line element for indent calculation
+          highlightedLineElements.push(child);
         }
       }
+
+      // Recurse into children (for frames containing lines)
+      traverse(child);
+    }
+  }
+  traverse(node);
+  return highlightedLineElements;
+}
+
+/**
+ * Groups highlighted line elements by their highlight regions and calculates
+ * the indent level for each region.
+ *
+ * @param highlightedElements - Line elements that are highlighted, in order
+ * @param emphasizedLines - The emphasis metadata map
+ * @returns Map from region index to indent level
+ */
+function calculateRegionIndentLevels(highlightedElements, emphasizedLines) {
+  const regionIndentLevels = new Map();
+  if (highlightedElements.length === 0) {
+    return regionIndentLevels;
+  }
+
+  // Group elements by consecutive regions
+  const sortedLines = Array.from(emphasizedLines.keys()).sort((a, b) => a - b);
+  let regionIndex = 0;
+  let regionElements = [];
+  let prevLine = -1;
+
+  // Build a quick lookup from lineNumber to element
+  const elementByLine = new Map();
+  for (const el of highlightedElements) {
+    const ln = el.properties?.dataLn;
+    elementByLine.set(ln, el);
+  }
+  for (const line of sortedLines) {
+    const el = elementByLine.get(line);
+    if (!el) {
+      continue;
+    }
+    if (prevLine >= 0 && line !== prevLine + 1) {
+      // Gap: close current region
+      regionIndentLevels.set(regionIndex, calculateFrameIndent(regionElements));
+      regionIndex += 1;
+      regionElements = [];
     }
+    regionElements.push(el);
+    prevLine = line;
+  }
 
-    // Recurse into children (for frames containing lines)
-    addEmphasisToLines(child, emphasizedLines);
+  // Close the last region
+  if (regionElements.length > 0) {
+    regionIndentLevels.set(regionIndex, calculateFrameIndent(regionElements));
   }
+  return regionIndentLevels;
 }
 
 /**
- * Source enhancer that adds emphasis to code lines based on `@highlight` comments.
+ * Creates a source enhancer that adds emphasis to code lines based on `@highlight` comments
+ * and restructures frames around highlighted regions.
  *
- * Supports four patterns:
+ * Supports five patterns:
  *
  * 1. **Single line emphasis** - emphasizes the line containing the comment:
  *    ```jsx
@@ -437,12 +543,66 @@ function addEmphasisToLines(node, emphasizedLines) {
  *    <h1>Heading 1</h1> {/* @highlight-text "Heading 1" *\/}
  *    ```
  *
+ * 5. **Focus override** - mark a region for padding focus:
+ *    ```jsx
+ *    <h1>Heading 1</h1> {/* @highlight @focus *\/}
+ *    ```
+ *
  * Emphasized lines receive a `data-hl` attribute on their `<span class="line">` element.
+ * When highlights exist, frames are restructured with `data-frame-type` attributes
+ * (`highlighted`, `padding-top`, `padding-bottom`, or omitted for normal).
+ * Highlighted frames also receive `data-frame-indent` with the shared indent level.
  *
- * @param root - The HAST root node to enhance
- * @param comments - Comments extracted from the source code, keyed by line number
- * @param _fileName - The name of the file being processed (unused)
- * @returns The enhanced HAST root node with emphasis attributes added
+ * @param options - Optional configuration for padding frames
+ * @returns A `SourceEnhancer` function
+ *
+ * @example
+ * ```ts
+ * import { createEnhanceCodeEmphasis } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
+ *
+ * const enhancers = [createEnhanceCodeEmphasis({ paddingFrameMaxSize: 5, focusFramesMaxSize: 8 })];
+ * ```
+ */
+export function createEnhanceCodeEmphasis(options = {}) {
+  return (root, comments) => {
+    if (!comments || Object.keys(comments).length === 0) {
+      return root;
+    }
+
+    // Step 1: Parse directives from comments (no tree traversal)
+    const directives = parseEmphasisDirectives(comments);
+    if (directives.length === 0) {
+      return root;
+    }
+
+    // Step 2 (Traversal 1): Build line element map
+    const lineElements = buildLineElementMap(root);
+
+    // Step 3: Calculate which lines are emphasized (no tree traversal)
+    const emphasizedLines = calculateEmphasizedLines(directives, lineElements);
+    if (emphasizedLines.size === 0) {
+      return root;
+    }
+
+    // Step 4 (Traversal 2): Apply emphasis attributes AND collect highlighted elements
+    const highlightedElements = applyEmphasisAndCollectHighlightedElements(root, emphasizedLines);
+
+    // Step 5: Calculate indent levels per region (uses collected elements, no tree traversal)
+    const regionIndentLevels = calculateRegionIndentLevels(highlightedElements, emphasizedLines);
+
+    // Step 6: Calculate frame ranges (pure math, no tree traversal)
+    const totalLines = root.data?.totalLines ?? lineElements.size;
+    const frameRanges = calculateFrameRanges(emphasizedLines, totalLines, options);
+
+    // Step 7: Restructure frames (flat iteration, not deep recursive traversal)
+    restructureFrames(root, frameRanges, regionIndentLevels);
+    return root;
+  };
+}
+
+/**
+ * Default source enhancer that adds emphasis to code lines based on `@highlight` comments.
+ * Uses no padding frames by default. Use `createEnhanceCodeEmphasis` for configurable padding.
  *
  * @example
  * ```ts
@@ -451,19 +611,4 @@ function addEmphasisToLines(node, emphasizedLines) {
  * const enhancers = [enhanceCodeEmphasis];
  * ```
  */
-export const enhanceCodeEmphasis = (root, comments) => {
-  if (!comments || Object.keys(comments).length === 0) {
-    return root;
-  }
-  const directives = parseEmphasisDirectives(comments);
-  if (directives.length === 0) {
-    return root;
-  }
-  const lineElements = buildLineElementMap(root);
-  const emphasizedLines = calculateEmphasizedLines(directives, lineElements);
-  if (emphasizedLines.size === 0) {
-    return root;
-  }
-  addEmphasisToLines(root, emphasizedLines);
-  return root;
-};
+export const enhanceCodeEmphasis = createEnhanceCodeEmphasis();