@mui/internal-docs-infra 0.10.1-canary.2 → 0.10.1-canary.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.10.1-canary.2",
+  "version": "0.10.1-canary.4",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",
@@ -643,5 +643,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "7c06e2fc2908c14730ae31975a4e6fa27955fdcf"
+  "gitSha": "a6c1a30f23657628b384ef27f0c3c4cb7f37869b"
 }

package/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.mjs

@@ -587,7 +587,11 @@ function calculateEmphasizedLines(directives, lineElements) {
         lineHighlight: directive.lineHighlight,
         focus: directive.focus,
         paddingFrameMaxSize: directive.paddingFrameMaxSize,
-        focusFramesMaxSize: directive.focusFramesMaxSize
+        focusFramesMaxSize: directive.focusFramesMaxSize,
+        // Treat a single `@highlight` as a containing highlight range of depth 1
+        // so that an outer multiline range wrapping this line is detected as
+        // nesting and promoted to `strong`.
+        containingRangeDepth: directive.lineHighlight ? 1 : undefined
       });
     } else if (directive.type === 'text') {
       // Text highlight - emphasize specific text(s) within the line.
@@ -640,7 +644,12 @@ function calculateEmphasizedLines(directives, lineElements) {
 
         // Determine position for this line in the current range
         let position;
-        if (line === startLine && line !== endLine) {
+        if (line === startLine && line === endLine) {
+          // A multiline range that resolves to a single content line (e.g.
+          // when comment-only lines are stripped) should be treated as a
+          // standalone single-line highlight.
+          position = 'single';
+        } else if (line === startLine && line !== endLine) {
           position = 'start';
         } else if (line === endLine && line !== startLine) {
           position = 'end';
@@ -651,13 +660,20 @@ function calculateEmphasizedLines(directives, lineElements) {
         // A focus range overlapping with a highlight is not nesting — it just
         // merges focus into the existing entry.
         const meta = existing ? {
-          // Nested highlight ranges are strong; focus+highlight overlap is not
-          strong: existing.lineHighlight && startDirective.lineHighlight && !existing.highlightTexts || existing.strong || strong,
+          // Nested highlight ranges are strong; focus+highlight overlap is not.
+          // Detect true nesting via `containingRangeDepth` rather than
+          // `existing.lineHighlight`. This works when the existing entry
+          // came from a `@highlight-text` directive on a line that's also
+          // wrapped in a highlight range — `existing.lineHighlight` is true
+          // after the first range merge, so a second wrapping range needs to
+          // see the depth to know nesting occurred.
+          strong: (existing.containingRangeDepth ?? 0) >= 1 && startDirective.lineHighlight || existing.strong || strong,
           description: existing.description ?? (line === startLine ? description : undefined),
           // Inner range position takes precedence, but 'single' from a standalone
           // @highlight-text should be replaced by the multiline range's position.
-          // Keep 'single' from regular @highlight (no highlightTexts).
-          position: existing.position && !(existing.position === 'single' && existing.highlightTexts) ? existing.position : position,
+          // Keep 'single' from a real @highlight (lineHighlight is set), even when
+          // the line also carries @highlight-text.
+          position: existing.position && !(existing.position === 'single' && existing.highlightTexts && !existing.lineHighlight) ? existing.position : position,
           highlightTexts: existing.highlightTexts,
           // Preserve text highlights from @highlight-text
           lineHighlight: existing.lineHighlight || startDirective.lineHighlight,
@@ -682,7 +698,10 @@ function calculateEmphasizedLines(directives, lineElements) {
           focus: startDirective.focus,
           paddingFrameMaxSize: startDirective.paddingFrameMaxSize,
           focusFramesMaxSize: startDirective.focusFramesMaxSize,
-          propagatedOverride: true
+          propagatedOverride: true,
+          // Track depth so a wrapping outer range can detect nesting
+          // (used by the `strong` calculation above).
+          containingRangeDepth: startDirective.lineHighlight ? 1 : undefined
         };
         emphasizedLines.set(line, meta);
       }

package/pipeline/hastUtils/getHastTextContent.d.mts

@@ -0,0 +1,9 @@
+import type { Root as HastRoot, Element, Text, RootContent } from 'hast';
+/**
+ * Extracts all text content from a HAST node recursively.
+ */
+export declare function getHastTextContent(node: HastRoot | Element | Text | RootContent): string;
+/**
+ * Gets the direct text content of a HAST element (non-recursive, first level only).
+ */
+export declare function getShallowTextContent(element: Element): string;

package/pipeline/hastUtils/getHastTextContent.mjs

@@ -0,0 +1,25 @@
+/**
+ * Extracts all text content from a HAST node recursively.
+ */
+export function getHastTextContent(node) {
+  if (node.type === 'text') {
+    return node.value || '';
+  }
+  if ('children' in node && Array.isArray(node.children)) {
+    return node.children.map(child => getHastTextContent(child)).join('');
+  }
+  return '';
+}
+
+/**
+ * Gets the direct text content of a HAST element (non-recursive, first level only).
+ */
+export function getShallowTextContent(element) {
+  let text = '';
+  for (const child of element.children) {
+    if (child.type === 'text') {
+      text += child.value;
+    }
+  }
+  return text;
+}

package/pipeline/hastUtils/index.d.mts

@@ -1,3 +1,4 @@
 export * from "./hastCompression.mjs";
 export * from "./hastUtils.mjs";
+export { getHastTextContent, getShallowTextContent } from "./getHastTextContent.mjs";
 export { stripHighlightingSpans } from "./stripHighlightingSpans.mjs";

package/pipeline/hastUtils/index.mjs

@@ -1,3 +1,4 @@
 export * from "./hastCompression.mjs";
 export * from "./hastUtils.mjs";
+export { getHastTextContent, getShallowTextContent } from "./getHastTextContent.mjs";
 export { stripHighlightingSpans } from "./stripHighlightingSpans.mjs";

package/pipeline/loadServerTypes/hastTypeUtils.d.mts

@@ -4,20 +4,14 @@
  * These utilities work on already-highlighted HAST nodes to detect type patterns
  * (unions, functions, objects) and derive shortType/detailedType variants.
  */
-import type { Root as HastRoot, Element, Text, RootContent } from 'hast';
-/**
- * Extracts all text content from a HAST node recursively.
- */
-export declare function getHastTextContent(node: HastRoot | Element | Text | RootContent): string;
+import type { Root as HastRoot, Element } from 'hast';
+import { getHastTextContent, getShallowTextContent } from "../hastUtils/index.mjs";
+export { getHastTextContent, getShallowTextContent };
 /**
  * Checks if a HAST element has a specific CSS class.
  * Handles both string and array class representations.
  */
 export declare function hasClass(element: Element, className: string): boolean;
-/**
- * Gets the direct text content of a HAST element (non-recursive, first level only).
- */
-export declare function getShallowTextContent(element: Element): string;
 /**
  * Checks if a HAST element is a span with class `line`.
  */

package/pipeline/loadServerTypes/hastTypeUtils.mjs

@@ -5,20 +5,8 @@
  * (unions, functions, objects) and derive shortType/detailedType variants.
  */
 
-import { compressHast } from "../hastUtils/index.mjs";
-
-/**
- * Extracts all text content from a HAST node recursively.
- */
-export function getHastTextContent(node) {
-  if (node.type === 'text') {
-    return node.value || '';
-  }
-  if ('children' in node && Array.isArray(node.children)) {
-    return node.children.map(child => getHastTextContent(child)).join('');
-  }
-  return '';
-}
+import { compressHast, getHastTextContent, getShallowTextContent } from "../hastUtils/index.mjs";
+export { getHastTextContent, getShallowTextContent };
 
 /**
  * Checks if a HAST element has a specific CSS class.
@@ -35,19 +23,6 @@ export function hasClass(element, className) {
   return false;
 }
 
-/**
- * Gets the direct text content of a HAST element (non-recursive, first level only).
- */
-export function getShallowTextContent(element) {
-  let text = '';
-  for (const child of element.children) {
-    if (child.type === 'text') {
-      text += child.value;
-    }
-  }
-  return text;
-}
-
 /**
  * Checks if a HAST element is a span with class `line`.
  */

package/pipeline/parseSource/addLineGutters.mjs

@@ -127,16 +127,26 @@ export function starryNightGutter(tree, sourceLines, frameSize = 120) {
     replacement.push(createFrame(frameLines));
   }
 
-  // If there are multiple frames and sourceLines provided, add dataAsString to each frame
+  // If there are multiple frames and sourceLines provided, add dataAsString to each frame.
+  // Every frame except the last covers `frameSize` source lines, each of which
+  // was followed by a newline separator in the original source, so its text
+  // ends with a trailing '\n'. The final frame only carries a trailing newline
+  // if the source itself ends with one. Without this trailing '\n', the
+  // plain-text fallback and the highlighted render disagree by exactly one
+  // newline per non-final frame, which causes a layout shift during lazy
+  // hydration when a frame toggles between the two.
   if (replacement.length > 1 && sourceLines) {
-    for (const frame of replacement) {
+    const lastIndex = replacement.length - 1;
+    for (let frameIndex = 0; frameIndex < replacement.length; frameIndex += 1) {
+      const frame = replacement[frameIndex];
       if (frame.type === 'element' && frame.tagName === 'span' && frame.properties?.className === 'frame') {
         // Extract line range from child .line elements
         const lineChildren = frame.children.filter(c => c.type === 'element' && c.properties?.className === 'line' && typeof c.properties.dataLn === 'number');
         if (lineChildren.length > 0) {
           const startLine = Number(lineChildren[0].properties.dataLn) - 1;
           const endLine = Number(lineChildren[lineChildren.length - 1].properties.dataLn);
-          frame.properties.dataAsString = sourceLines.slice(startLine, endLine).join('\n');
+          const joined = sourceLines.slice(startLine, endLine).join('\n');
+          frame.properties.dataAsString = frameIndex < lastIndex ? `${joined}\n` : joined;
         }
       }
     }

package/pipeline/transformHtmlCodeInline/transformHtmlCodeInline.mjs

@@ -2,6 +2,7 @@ import { createStarryNight } from '@wooorm/starry-night';
 import { visit } from 'unist-util-visit';
 import { grammars, extensionMap } from "../parseSource/grammars.mjs";
 import { extendSyntaxTokens } from "../parseSource/extendSyntaxTokens.mjs";
+import { getHastTextContent } from "../hastUtils/index.mjs";
 import { removePrefixFromHighlightedNodes } from "./removePrefixFromHighlightedNodes.mjs";
 const STARRY_NIGHT_KEY = '__docs_infra_starry_night_instance__';
 
@@ -56,18 +57,7 @@ export default function transformHtmlCodeInline(options = {}) {
       }
 
       // Extract all text content from children (handles multiple text nodes and newlines)
-      const getTextContent = children => {
-        return children.map(child => {
-          if (child.type === 'text') {
-            return child.value;
-          }
-          if (child.type === 'element' && 'children' in child) {
-            return getTextContent(child.children);
-          }
-          return '';
-        }).join('');
-      };
-      const source = getTextContent(node.children);
+      const source = node.children.map(child => getHastTextContent(child)).join('');
       if (!source) {
         return;
       }