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

package/pipeline/parseSource/calculateFrameRanges.mjs

@@ -207,6 +207,36 @@ function calculateFocusWindow(region, focusFramesMaxSize) {
   return [focusStart, focusEnd];
 }
 
+/**
+ * Splits an inclusive line range into `normal` frames, chunked by
+ * `normalFrameMaxSize` when provided. Returns an empty array when the range
+ * is empty (`start > end`).
+ */
+function splitIntoNormalFrames(start, end, normalFrameMaxSize) {
+  if (start > end) {
+    return [];
+  }
+  if (normalFrameMaxSize === undefined || normalFrameMaxSize < 1) {
+    return [{
+      startLine: start,
+      endLine: end,
+      type: 'normal'
+    }];
+  }
+  const frames = [];
+  let cursor = start;
+  while (cursor <= end) {
+    const frameEnd = Math.min(cursor + normalFrameMaxSize - 1, end);
+    frames.push({
+      startLine: cursor,
+      endLine: frameEnd,
+      type: 'normal'
+    });
+    cursor = frameEnd + 1;
+  }
+  return frames;
+}
+
 /**
  * Calculates frame ranges for the code block based on emphasized lines.
  *
@@ -232,6 +262,16 @@ export function calculateFrameRanges(emphasizedLines, totalLines, options = {},
   if (options.paddingFrameMaxSize !== undefined && (!Number.isFinite(options.paddingFrameMaxSize) || options.paddingFrameMaxSize < 0)) {
     throw new Error(`paddingFrameMaxSize must be a finite number >= 0, got ${options.paddingFrameMaxSize}`);
   }
+  if (options.oversizedFocus !== undefined && options.oversizedFocus !== 'truncate' && options.oversizedFocus !== 'hide') {
+    throw new Error(`oversizedFocus must be 'truncate' or 'hide', got ${options.oversizedFocus}`);
+  }
+  // Indent shifting replaces padding as the way to convey surrounding context, so the
+  // two options can't be combined — fail fast on a contradictory config. A per-region
+  // `@padding` directive in the source is NOT an error (it rides in `emphasizedLines`,
+  // not `options`); it is simply ignored below while `emitFrameIndent` is set.
+  if (options.emitFrameIndent && (options.paddingFrameMaxSize ?? 0) > 0) {
+    throw new Error('emitFrameIndent cannot be combined with the paddingFrameMaxSize option: indent ' + 'shifting replaces padding. Configure one or the other. (A per-region `@padding` ' + 'directive in the source is still allowed — it is ignored while emitFrameIndent is set.)');
+  }
   if (normalFrameMaxSize !== undefined && (!Number.isFinite(normalFrameMaxSize) || normalFrameMaxSize < 1)) {
     throw new Error(`normalFrameMaxSize must be a finite number >= 1, got ${normalFrameMaxSize}`);
   }
@@ -244,6 +284,12 @@ export function calculateFrameRanges(emphasizedLines, totalLines, options = {},
     // If focusFramesMaxSize is set and the code exceeds it, truncate.
     const autoFocusMax = effectiveFocusFramesMaxSize;
     if (autoFocusMax !== undefined && totalLines > autoFocusMax) {
+      if (options.oversizedFocus === 'hide') {
+        // No focus window is produced for an oversized source: emit normal
+        // frames covering everything. The block collapses to nothing (the
+        // enhancer marks it collapsible with focusedLines === 0).
+        return splitIntoNormalFrames(1, totalLines, normalFrameMaxSize);
+      }
       const autoFrames = [{
         startLine: 1,
         endLine: autoFocusMax,
@@ -252,26 +298,7 @@ export function calculateFrameRanges(emphasizedLines, totalLines, options = {},
         truncated: 'visible'
       }];
       // Split the trailing normal frame if normalFrameMaxSize is set
-      const normalStart = autoFocusMax + 1;
-      if (normalFrameMaxSize !== undefined && normalFrameMaxSize >= 1) {
-        const maxSize = normalFrameMaxSize;
-        let start = normalStart;
-        while (start <= totalLines) {
-          const end = Math.min(start + maxSize - 1, totalLines);
-          autoFrames.push({
-            startLine: start,
-            endLine: end,
-            type: 'normal'
-          });
-          start = end + 1;
-        }
-      } else {
-        autoFrames.push({
-          startLine: normalStart,
-          endLine: totalLines,
-          type: 'normal'
-        });
-      }
+      autoFrames.push(...splitIntoNormalFrames(autoFocusMax + 1, totalLines, normalFrameMaxSize));
       return autoFrames;
     }
     return [{
@@ -286,12 +313,26 @@ export function calculateFrameRanges(emphasizedLines, totalLines, options = {},
   // Calculate focus window split (for oversized regions)
   const focusedRegion = regions[focusedIndex];
   const focusFramesMaxSize = focusedRegion.focusFramesMaxSize ?? effectiveFocusFramesMaxSize;
-  const focusWindow = calculateFocusWindow(focusedRegion, focusFramesMaxSize);
 
-  // Calculate padding for the focused region (0 when region is split)
+  // When `oversizedFocus: 'hide'` is set and the focused region is larger than
+  // the focus window, suppress focus entirely: no window split, no padding,
+  // and the region is rendered with its unfocused frame type. The enhancer
+  // then sees focusedLines === 0 and collapses the block to nothing.
+  const focusedRegionSize = focusedRegion.endLine - focusedRegion.startLine + 1;
+  const oversizedFocusHidden = options.oversizedFocus === 'hide' && focusedRegionSize > focusFramesMaxSize;
+  const focusWindow = oversizedFocusHidden ? null : calculateFocusWindow(focusedRegion, focusFramesMaxSize);
+
+  // Calculate padding for the focused region (0 when region is split or focus
+  // is suppressed)
   const prevRegionEnd = focusedIndex > 0 ? regions[focusedIndex - 1].endLine : 0;
   const nextRegionStart = focusedIndex < regions.length - 1 ? regions[focusedIndex + 1].startLine : totalLines + 1;
-  const [paddingTop, paddingBottom] = calculatePadding(focusedRegion, prevRegionEnd, nextRegionStart, focusedRegion.paddingFrameMaxSize ?? options.paddingFrameMaxSize, focusFramesMaxSize);
+
+  // `emitFrameIndent` replaces padding with a horizontal shift, so it produces no
+  // padding frames. The global `paddingFrameMaxSize` option can't be combined with it
+  // (validated above), so the only padding that can reach here under `emitFrameIndent`
+  // is a per-region `@padding` directive from the source — which is intentionally
+  // tolerated and suppressed rather than rejected.
+  const [paddingTop, paddingBottom] = oversizedFocusHidden || options.emitFrameIndent ? [0, 0] : calculatePadding(focusedRegion, prevRegionEnd, nextRegionStart, focusedRegion.paddingFrameMaxSize ?? options.paddingFrameMaxSize, focusFramesMaxSize);
   // Build frame ranges by iterating through all regions
   const frames = [];
   let currentLine = 1;
@@ -357,11 +398,14 @@ export function calculateFrameRanges(emphasizedLines, totalLines, options = {},
       // Frame type depends on whether the region's lines are highlighted.
       // When all lines have data-hl (e.g. @highlight-start @focus), use "highlighted".
       // When only some lines are highlighted (e.g. @focus with inner @highlight), use "focus".
+      // When focus is suppressed for this oversized region, render it with its
+      // unfocused type so it stays hidden when collapsed (collapse-to-nothing).
+      const renderFocused = isFocused && !oversizedFocusHidden;
       let frameType;
       if (region.hasLineHighlight && (!region.focused || region.allLinesHighlighted)) {
-        frameType = isFocused ? 'highlighted' : 'highlighted-unfocused';
+        frameType = renderFocused ? 'highlighted' : 'highlighted-unfocused';
       } else {
-        frameType = isFocused ? 'focus' : 'focus-unfocused';
+        frameType = renderFocused ? 'focus' : 'focus-unfocused';
       }
       frames.push({
         startLine: region.startLine,

package/pipeline/parseSource/detectGrammarScopes.d.mts

@@ -0,0 +1,13 @@
+import type { Code } from "../../CodeHighlighter/types.mjs";
+/**
+ * Enumerates the unique grammar scopes a code block needs to highlight every
+ * file across all of its variants — the main file plus each extra file, by
+ * extension or explicit `language`. Cheap and synchronous (it reads only the
+ * lightweight metadata, never the grammar JSON), so it can run on every render
+ * to drive a speculative grammar preload.
+ *
+ * Variants that are bare source strings (no file metadata) or `undefined`, and
+ * files whose extension/language maps to no supported grammar, contribute no
+ * scope.
+ */
+export declare function detectGrammarScopes(code: Code): string[];

package/pipeline/parseSource/detectGrammarScopes.mjs

@@ -0,0 +1,35 @@
+import { resolveGrammarScope } from "./grammarMaps.mjs";
+
+/**
+ * Enumerates the unique grammar scopes a code block needs to highlight every
+ * file across all of its variants — the main file plus each extra file, by
+ * extension or explicit `language`. Cheap and synchronous (it reads only the
+ * lightweight metadata, never the grammar JSON), so it can run on every render
+ * to drive a speculative grammar preload.
+ *
+ * Variants that are bare source strings (no file metadata) or `undefined`, and
+ * files whose extension/language maps to no supported grammar, contribute no
+ * scope.
+ */
+export function detectGrammarScopes(code) {
+  const scopes = new Set();
+  for (const variant of Object.values(code)) {
+    if (!variant || typeof variant === 'string') {
+      continue;
+    }
+    const mainScope = resolveGrammarScope(variant.fileName, variant.language);
+    if (mainScope) {
+      scopes.add(mainScope);
+    }
+    if (variant.extraFiles) {
+      for (const [fileName, extra] of Object.entries(variant.extraFiles)) {
+        const language = typeof extra === 'object' ? extra.language : undefined;
+        const scope = resolveGrammarScope(fileName, language);
+        if (scope) {
+          scopes.add(scope);
+        }
+      }
+    }
+  }
+  return [...scopes];
+}