@mui/internal-docs-infra 0.12.1-canary.39 → 0.12.1-canary.40

package/CodeHighlighter/buildStringFallback.d.mts

@@ -15,8 +15,8 @@ export interface StringFallbackResult {
  * `sourceEnhancers` the live render uses over a cheap line-guttered HAST
  * (`parsePlainText` — gutters, no syntax highlighting). The inline-string
  * fallback path otherwise wraps the whole source in one un-windowed focus frame,
- * so an oversized / `@focus` / `@highlight` block paints its full text before
- * hydration then snaps to the collapsed window. Running the enhancers here makes
+ * so an oversized source (with or without `@focus` / `@highlight` directives)
+ * paints its full text before hydration then snaps to the collapsed window. Running the enhancers here makes
  * the loading frames match the live render, and the resulting `root.data` carries
  * the `totalLines` / `focusedLines` the compact fallback can't preserve.
  *

package/CodeHighlighter/buildStringFallback.mjs

@@ -9,8 +9,8 @@ function isPromiseLike(value) {
  * `sourceEnhancers` the live render uses over a cheap line-guttered HAST
  * (`parsePlainText` — gutters, no syntax highlighting). The inline-string
  * fallback path otherwise wraps the whole source in one un-windowed focus frame,
- * so an oversized / `@focus` / `@highlight` block paints its full text before
- * hydration then snaps to the collapsed window. Running the enhancers here makes
+ * so an oversized source (with or without `@focus` / `@highlight` directives)
+ * paints its full text before hydration then snaps to the collapsed window. Running the enhancers here makes
  * the loading frames match the live render, and the resulting `root.data` carries
  * the `totalLines` / `focusedLines` the compact fallback can't preserve.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.12.1-canary.39",
+  "version": "0.12.1-canary.40",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",
@@ -804,5 +804,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "3ce58e4dbb827caca255cf9b285beafd9f10967f"
+  "gitSha": "99c21315b55b03f58d832f7854e628da68343a10"
 }

package/pipeline/enhanceCodeEmphasis/calculateFrameIndentLevels.d.mts

@@ -0,0 +1,20 @@
+import type { Element } from 'hast';
+import type { FrameRange } from "../parseSource/calculateFrameRanges.mjs";
+/**
+ * Calculates the `data-frame-indent` level of each region frame, keyed by its
+ * index in `frameRanges`.
+ *
+ * Frames shown while collapsed form one contiguous window and share its indent,
+ * so shifting each of them by its own level keeps their left edges aligned.
+ * Hidden region frames use the indent of their whole region instead:
+ *
+ *   focus                 1–2 ─┐
+ *   highlighted           3    ├─ window: min indent of lines 1–4
+ *   focus                 4   ─┘
+ *   normal                5–6    (no indent)
+ *   highlighted-unfocused 7–8 ── region: min indent of lines 7–8
+ *
+ * @param frameRanges - Ordered frame ranges covering the source
+ * @param lineElements - Map of line numbers to their line elements
+ */
+export declare function calculateFrameIndentLevels(frameRanges: FrameRange[], lineElements: Map<number, Element>): Map<number, number>;

package/pipeline/enhanceCodeEmphasis/calculateFrameIndentLevels.mjs

@@ -0,0 +1,63 @@
+import { COLLAPSED_VISIBLE_FRAME_TYPES } from "../parseSource/frameVisibility.mjs";
+import { calculateFrameIndent } from "./calculateFrameIndent.mjs";
+
+/**
+ * Calculates the `data-frame-indent` level of each region frame, keyed by its
+ * index in `frameRanges`.
+ *
+ * Frames shown while collapsed form one contiguous window and share its indent,
+ * so shifting each of them by its own level keeps their left edges aligned.
+ * Hidden region frames use the indent of their whole region instead:
+ *
+ *   focus                 1–2 ─┐
+ *   highlighted           3    ├─ window: min indent of lines 1–4
+ *   focus                 4   ─┘
+ *   normal                5–6    (no indent)
+ *   highlighted-unfocused 7–8 ── region: min indent of lines 7–8
+ *
+ * @param frameRanges - Ordered frame ranges covering the source
+ * @param lineElements - Map of line numbers to their line elements
+ */
+export function calculateFrameIndentLevels(frameRanges, lineElements) {
+  const frameIndentLevels = new Map();
+  const windowFrames = [];
+  const windowLines = [];
+  const regionFrames = new Map();
+  const regionLines = new Map();
+  function collectLines(range) {
+    const lines = [];
+    for (let line = range.startLine; line <= range.endLine; line += 1) {
+      const element = lineElements.get(line);
+      if (element) {
+        lines.push(element);
+      }
+    }
+    return lines;
+  }
+  for (let frameIndex = 0; frameIndex < frameRanges.length; frameIndex += 1) {
+    const range = frameRanges[frameIndex];
+    if (COLLAPSED_VISIBLE_FRAME_TYPES.has(range.type)) {
+      windowFrames.push(frameIndex);
+      windowLines.push(...collectLines(range));
+      continue;
+    }
+    if (range.regionIndex === undefined) {
+      continue;
+    }
+    regionFrames.set(range.regionIndex, [...(regionFrames.get(range.regionIndex) ?? []), frameIndex]);
+    regionLines.set(range.regionIndex, [...(regionLines.get(range.regionIndex) ?? []), ...collectLines(range)]);
+  }
+  for (const [regionIndex, frames] of regionFrames) {
+    const indentLevel = calculateFrameIndent(regionLines.get(regionIndex) ?? []);
+    for (const frameIndex of frames) {
+      frameIndentLevels.set(frameIndex, indentLevel);
+    }
+  }
+  if (windowFrames.length > 0) {
+    const indentLevel = calculateFrameIndent(windowLines);
+    for (const frameIndex of windowFrames) {
+      frameIndentLevels.set(frameIndex, indentLevel);
+    }
+  }
+  return frameIndentLevels;
+}

package/pipeline/enhanceCodeEmphasis/emphasisCommentUtils.d.mts

@@ -0,0 +1,41 @@
+/**
+ * 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";
+/**
+ * The prefix used to identify focus-only comments in source code.
+ * Comments starting with this prefix will mark the region as focused without highlighting.
+ */
+export declare const FOCUS_COMMENT_PREFIX = "@focus";
+/**
+ * Modifier token used inside focused `@highlight` / `@focus` comments
+ * to override padding for that focus region.
+ * Example: combine `@highlight`, `@focus`, and `@padding 2`.
+ */
+export declare const PADDING_COMMENT_PREFIX = "@padding";
+/**
+ * Modifier token used inside focused `@highlight` / `@focus` comments
+ * to override the maximum size for that focus region.
+ * Example: combine `@highlight`, `@focus`, and `@min 6`.
+ */
+export declare const MIN_COMMENT_PREFIX = "@min";
+/**
+ * Replaces quoted content with underscores of the same length so directive
+ * matching only sees unquoted text. Backslash-escaped characters stay inside
+ * the current quoted section.
+ */
+export declare function maskQuotedContent(content: string): string;
+/**
+ * Extracts quoted strings while treating backslash-escaped quote characters
+ * as content. Returned strings preserve their original escape sequences.
+ */
+export declare function extractQuotedCommentStrings(content: string): string[];
+/**
+ * Collects whitespace-delimited comment tokens while ignoring quoted text.
+ */
+export declare function getUnquotedCommentTokens(comment: string): string[];
+/**
+ * Returns whether a parsed comment contains a real focus directive.
+ */
+export declare function hasFocusDirective(comment: string): boolean;

package/pipeline/enhanceCodeEmphasis/emphasisCommentUtils.mjs

@@ -0,0 +1,130 @@
+/**
+ * The prefix used to identify emphasis comments in source code.
+ * Comments starting with this prefix will be processed for emphasis.
+ */
+export const EMPHASIS_COMMENT_PREFIX = '@highlight';
+
+/**
+ * The prefix used to identify focus-only comments in source code.
+ * Comments starting with this prefix will mark the region as focused without highlighting.
+ */
+export const FOCUS_COMMENT_PREFIX = '@focus';
+
+/**
+ * Modifier token used inside focused `@highlight` / `@focus` comments
+ * to override padding for that focus region.
+ * Example: combine `@highlight`, `@focus`, and `@padding 2`.
+ */
+export const PADDING_COMMENT_PREFIX = '@padding';
+
+/**
+ * Modifier token used inside focused `@highlight` / `@focus` comments
+ * to override the maximum size for that focus region.
+ * Example: combine `@highlight`, `@focus`, and `@min 6`.
+ */
+export const MIN_COMMENT_PREFIX = '@min';
+
+/**
+ * Replaces quoted content with underscores of the same length so directive
+ * matching only sees unquoted text. Backslash-escaped characters stay inside
+ * the current quoted section.
+ */
+export function maskQuotedContent(content) {
+  let result = '';
+  let quote;
+  for (let index = 0; index < content.length; index += 1) {
+    const character = content[index];
+    if (quote) {
+      result += '_';
+      if (character === '\\' && index + 1 < content.length) {
+        index += 1;
+        result += '_';
+      } else if (character === quote) {
+        quote = undefined;
+      }
+    } else if (character === '"' || character === "'") {
+      quote = character;
+      result += '_';
+    } else {
+      result += character;
+    }
+  }
+  return result;
+}
+
+/**
+ * Extracts quoted strings while treating backslash-escaped quote characters
+ * as content. Returned strings preserve their original escape sequences.
+ */
+export function extractQuotedCommentStrings(content) {
+  const strings = [];
+  let quote;
+  let contentStart = -1;
+  for (let index = 0; index < content.length; index += 1) {
+    const character = content[index];
+    if (quote) {
+      if (character === '\\' && index + 1 < content.length) {
+        index += 1;
+      } else if (character === quote) {
+        if (index > contentStart) {
+          strings.push(content.slice(contentStart, index));
+        }
+        quote = undefined;
+        contentStart = -1;
+      }
+    } else if (character === '"' || character === "'") {
+      quote = character;
+      contentStart = index + 1;
+    }
+  }
+  return strings;
+}
+
+/**
+ * Collects whitespace-delimited comment tokens while ignoring quoted text.
+ */
+export function getUnquotedCommentTokens(comment) {
+  const tokens = [];
+  let currentToken = '';
+  let quote;
+  function pushCurrentToken() {
+    if (currentToken) {
+      tokens.push(currentToken);
+      currentToken = '';
+    }
+  }
+  for (let index = 0; index < comment.length; index += 1) {
+    const character = comment[index];
+    if (quote) {
+      if (character === '\\' && index + 1 < comment.length) {
+        index += 1;
+      } else if (character === quote) {
+        quote = undefined;
+      }
+      continue;
+    }
+    if (character === '"' || character === "'") {
+      pushCurrentToken();
+      quote = character;
+    } else if (character === ' ' || character === '\t' || character === '\n' || character === '\r') {
+      pushCurrentToken();
+    } else {
+      currentToken += character;
+    }
+  }
+  pushCurrentToken();
+  return tokens;
+}
+
+/**
+ * Returns whether a parsed comment contains a real focus directive.
+ */
+export function hasFocusDirective(comment) {
+  const tokens = getUnquotedCommentTokens(comment);
+  const firstToken = tokens[0];
+  if (firstToken === FOCUS_COMMENT_PREFIX || firstToken === `${FOCUS_COMMENT_PREFIX}-start` || firstToken === `${FOCUS_COMMENT_PREFIX}-end`) {
+    return true;
+  }
+  const acceptsFocusModifier = firstToken === EMPHASIS_COMMENT_PREFIX || firstToken === `${EMPHASIS_COMMENT_PREFIX}-start` || firstToken === `${EMPHASIS_COMMENT_PREFIX}-text`;
+  return acceptsFocusModifier && tokens.includes(FOCUS_COMMENT_PREFIX);
+}

package/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.d.mts

@@ -1,71 +1,27 @@
 import type { SourceEnhancer } from "../../CodeHighlighter/types.mjs";
 import type { EnhanceCodeEmphasisOptions } from "../parseSource/calculateFrameRanges.mjs";
 export type { EmphasisMeta, EnhanceCodeEmphasisOptions, FrameRange } from "../parseSource/calculateFrameRanges.mjs";
+export { EMPHASIS_COMMENT_PREFIX, FOCUS_COMMENT_PREFIX, MIN_COMMENT_PREFIX, PADDING_COMMENT_PREFIX } from "./emphasisCommentUtils.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";
-/**
- * The prefix used to identify focus-only comments in source code.
- * Comments starting with this prefix will mark the region as focused without highlighting.
- */
-export declare const FOCUS_COMMENT_PREFIX = "@focus";
-/**
- * Modifier token used inside `@highlight` / `@focus` comments
- * to override padding for that directive.
- * Example: @highlight @padding 2.
- */
-export declare const PADDING_COMMENT_PREFIX = "@padding";
-/**
- * Modifier token used inside `@highlight` / `@focus` comments
- * to override focus max size for that directive.
- * Example: @highlight @min 6.
- */
-export declare const MIN_COMMENT_PREFIX = "@min";
-/**
- * Creates a source enhancer that adds emphasis to code lines based on `@highlight` comments
- * and restructures frames around highlighted regions.
- *
- * Supports five patterns:
- *
- * 1. **Single line emphasis** - emphasizes the line containing the comment:
- *    ```jsx
- *    <h1>Heading 1</h1> {/* @highlight *\/}
- *    ```
- *
- * 2. **Multiline emphasis** - emphasizes all lines between start and end:
- *    ```jsx
- *    // @highlight-start
- *    <div>
- *      <h1>Heading 1</h1>
- *    </div>
- *    // @highlight-end
- *    ```
- *
- * 3. **Multiline with description**:
- *    ```jsx
- *    // @highlight-start "we add a heading"
- *    <div>
- *      <h1>Heading 1</h1>
- *    </div>
- *    // @highlight-end
- *    ```
- *
- * 4. **Text highlight** - highlights specific text within a line:
- *    ```jsx
- *    <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.
+ * Creates a source enhancer that renders `@highlight` as visual emphasis and
+ * uses `@focus` to select the collapsed preview.
+ *
+ * Supports six patterns:
+ *
+ * 1. **Single line emphasis** - `@highlight` emphasizes its line.
+ * 2. **Multiline emphasis** - `@highlight-start` and `@highlight-end`
+ *    emphasize the lines between them.
+ * 3. **Multiline with description** - add a quoted description after
+ *    `@highlight-start`.
+ * 4. **Text highlight** - `@highlight-text "Heading 1"` emphasizes matching text.
+ * 5. **Focused highlight** - combine `@highlight` with `@focus` to emphasize a line
+ *    and select it for the collapsed preview.
+ * 6. **Focus only** - `@focus-start` and `@focus-end` select preview lines
+ *    without emphasizing them.
+ *
+ * Frames are restructured with `data-frame-type` attributes for focused and highlighted
+ * regions. A highlight nested inside a focus frame receives line-level `data-hl` so both
+ * layers remain visible. Set `emitFrameIndent` to add the shared indent level to region frames.
  *
  * @param options - Optional configuration for padding frames
  * @returns A `SourceEnhancer` function
@@ -79,8 +35,9 @@ export declare const MIN_COMMENT_PREFIX = "@min";
  */
 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.
+ * Default source enhancer that renders `@highlight` emphasis and uses `@focus`
+ * to select the collapsed preview. Uses no padding frames by default. Use
+ * `createEnhanceCodeEmphasis` for configurable padding.
  *
  * @example
  * ```ts