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

package/pipeline/parseSource/frameVisibility.mjs

@@ -0,0 +1,114 @@
+import { isFrameSpan } from "./isFrameSpan.mjs";
+
+/**
+ * The `data-frame-type` values whose frames make up the window a collapsible
+ * code block shows while collapsed (the contiguous focused window:
+ * `padding-top`, `highlighted` / `focus`, `padding-bottom`).
+ *
+ * This is the single source of truth shared by the runtime visibility rule in
+ * `useCode/Pre.tsx`, the collapsed fallback reducer in
+ * `CodeHighlighter/fallbackFormat.ts`, and the collapsed line computation in
+ * `pipeline/loadIsomorphicCodeVariant/getInitialVisibleSourceLines.ts`. It is
+ * intentionally isomorphic (no client-only code) so the server and the client
+ * stay in sync.
+ */
+const COLLAPSED_VISIBLE_FRAME_TYPE_LIST = ['highlighted', 'focus', 'padding-top', 'padding-bottom'];
+
+/**
+ * Set form of {@link COLLAPSED_VISIBLE_FRAME_TYPE_LIST} for fast membership
+ * checks. Typed as `ReadonlySet<string>` so callers can pass a raw
+ * `data-frame-type` string to `.has()` without narrowing first.
+ */
+export const COLLAPSED_VISIBLE_FRAME_TYPES = new Set(COLLAPSED_VISIBLE_FRAME_TYPE_LIST);
+
+/**
+ * Runtime "collapse to empty" frame-type rewrite.
+ *
+ * `collapseToEmpty` is a render-time option (it never touches the precomputed
+ * HAST) that makes a collapsible code block render with an *empty* collapsed
+ * window — the whole block is hidden until the reader expands it. It works by
+ * demoting every collapsed-visible frame type to a hidden equivalent so the
+ * existing collapse CSS (which only shows {@link COLLAPSED_VISIBLE_FRAME_TYPES}
+ * while collapsed) hides everything:
+ *
+ * - `focus` → `focus-unfocused`
+ * - `highlighted` → `highlighted-unfocused`
+ * - `padding-top` / `padding-bottom` → `normal`
+ *
+ * The `-unfocused` variants are kept (rather than `normal`) for `focus` /
+ * `highlighted` so the highlight styling is still present once the block is
+ * expanded. Padding frames carry no styling, so they become `normal`.
+ *
+ * Frame types that are already hidden (or non-region, e.g. `comment`) are
+ * returned unchanged. Returns the input untouched when `collapseToEmpty` is false.
+ *
+ * @param frameType - The frame's `data-frame-type` (may be `undefined` for `normal`)
+ * @param collapseToEmpty - Whether the block is rendered collapse-to-empty
+ */
+export function resolveCollapsedFrameType(frameType, collapseToEmpty) {
+  if (!collapseToEmpty) {
+    return frameType;
+  }
+  switch (frameType) {
+    case 'focus':
+      return 'focus-unfocused';
+    case 'highlighted':
+      return 'highlighted-unfocused';
+    case 'padding-top':
+    case 'padding-bottom':
+      return 'normal';
+    default:
+      return frameType;
+  }
+}
+
+/**
+ * The set of frame indices that are visible on the initial (collapsed) render of
+ * a code block: the contiguous focused window
+ * ({@link COLLAPSED_VISIBLE_FRAME_TYPES}), falling back to the first frame when no
+ * frame carries an emphasis type. Returns an empty set for `collapseToEmpty` (an
+ * empty collapsed window) and for a `focusedLines === 0` carve-out
+ * (`oversizedFocus: 'hide'`).
+ *
+ * Shared by the runtime rule in `useCode/Pre.tsx` and the server-side
+ * highlighted-visible fallback builder, so the frames highlighted on the first
+ * paint match exactly. Isomorphic — reads only precomputed HAST attributes.
+ */
+export function getInitialVisibleFrames(hast, collapseToEmpty = false) {
+  if (!hast) {
+    return collapseToEmpty ? {} : {
+      0: true
+    };
+  }
+
+  // Collapse-to-empty renders an empty collapsed window — no frame is visible while
+  // collapsed, regardless of the precomputed frame types.
+  if (collapseToEmpty) {
+    return {};
+  }
+  const visibleFrames = {};
+  let frameIndex = 0;
+  let hasVisibleEmphasisFrame = false;
+  hast.children.forEach(child => {
+    if (child.type !== 'element' || !isFrameSpan(child)) {
+      return;
+    }
+    const frameType = child.properties.dataFrameType;
+    if (typeof frameType === 'string' && COLLAPSED_VISIBLE_FRAME_TYPES.has(frameType)) {
+      visibleFrames[frameIndex] = true;
+      hasVisibleEmphasisFrame = true;
+    }
+    frameIndex += 1;
+  });
+
+  // Collapse-to-nothing (oversizedFocus: 'hide'): `focusedLines === 0` means
+  // the collapsed window is intentionally empty, so skip the first-frame
+  // fallback and keep every frame hidden when collapsed.
+  if (hast.data?.focusedLines === 0) {
+    return visibleFrames;
+  }
+  if (!hasVisibleEmphasisFrame && frameIndex > 0) {
+    visibleFrames[0] = true;
+  }
+  return visibleFrames;
+}

package/pipeline/parseSource/grammarCache.d.mts

@@ -0,0 +1,33 @@
+/**
+ * Light, client-reachable facade over the grammar engine in `./parseSource`.
+ *
+ * Importing this module must NOT pull `createStarryNight` (the regex engine:
+ * vscode-textmate + oniguruma) or any grammar JSON into the bundle — the engine
+ * is reached only through the dynamic `import()` in {@link ensureGrammars}. That
+ * keeps `CodeHighlighter` (which drives lazy, per-language grammar loading from
+ * the client chunk) free of the engine until a block actually needs to
+ * highlight, mirroring the `./useCode/transformEngineCache` split.
+ */
+/**
+ * Synchronously reports whether every given scope's grammar is already
+ * registered. Reads the shared singleton without importing the engine, so it is
+ * safe on the render path (e.g. a `useState` initializer) to decide whether a
+ * block can highlight immediately or must wait — avoiding a cold flash.
+ */
+export declare function areGrammarsRegistered(scopes: string[]): boolean;
+/**
+ * Ensures the grammars for the given scopes (and their dependencies) are
+ * registered, loading the engine and the per-scope grammar chunks on demand. A
+ * synchronous no-op when the scopes are already registered (warm — e.g. a prior
+ * block, the speculative preload, or an eager `CodeProvider` primed them), so it
+ * is cheap to call on render or as a speculative preload. Fails open: a failed
+ * load leaves the affected scope as plain text.
+ */
+export declare function ensureGrammars(scopes: string[]): Promise<void>;
+/**
+ * Registers ALL grammars via the single barrel chunk (~146 KB gzip). Backs the
+ * `preloadGrammars: 'all'` provider opt-in — for layouts that will render code
+ * in many languages and prefer one upfront fetch over per-language chunks. Fails
+ * open.
+ */
+export declare function preloadAllGrammars(): Promise<void>;

package/pipeline/parseSource/grammarCache.mjs

@@ -0,0 +1,73 @@
+/**
+ * Light, client-reachable facade over the grammar engine in `./parseSource`.
+ *
+ * Importing this module must NOT pull `createStarryNight` (the regex engine:
+ * vscode-textmate + oniguruma) or any grammar JSON into the bundle — the engine
+ * is reached only through the dynamic `import()` in {@link ensureGrammars}. That
+ * keeps `CodeHighlighter` (which drives lazy, per-language grammar loading from
+ * the client chunk) free of the engine until a block actually needs to
+ * highlight, mirroring the `./useCode/transformEngineCache` split.
+ */
+
+// Must match STARRY_NIGHT_KEY in ./parseSource. Duplicated intentionally to keep
+// this module free of a static `./parseSource` import (which would pull the
+// engine into every consumer's bundle).
+const STARRY_NIGHT_KEY = '__docs_infra_starry_night_instance__';
+
+// The narrow slice of the Starry Night instance this module reads synchronously.
+
+function getInstance() {
+  return globalThis[STARRY_NIGHT_KEY];
+}
+
+/**
+ * Synchronously reports whether every given scope's grammar is already
+ * registered. Reads the shared singleton without importing the engine, so it is
+ * safe on the render path (e.g. a `useState` initializer) to decide whether a
+ * block can highlight immediately or must wait — avoiding a cold flash.
+ */
+export function areGrammarsRegistered(scopes) {
+  if (scopes.length === 0) {
+    return true;
+  }
+  const instance = getInstance();
+  if (!instance) {
+    return false;
+  }
+  const registered = new Set(instance.scopes());
+  return scopes.every(scope => registered.has(scope));
+}
+
+/**
+ * Ensures the grammars for the given scopes (and their dependencies) are
+ * registered, loading the engine and the per-scope grammar chunks on demand. A
+ * synchronous no-op when the scopes are already registered (warm — e.g. a prior
+ * block, the speculative preload, or an eager `CodeProvider` primed them), so it
+ * is cheap to call on render or as a speculative preload. Fails open: a failed
+ * load leaves the affected scope as plain text.
+ */
+export async function ensureGrammars(scopes) {
+  if (scopes.length === 0 || areGrammarsRegistered(scopes)) {
+    return;
+  }
+  // Cold: pull the engine + registration impl now (this is when a block is about
+  // to highlight, so the engine load is expected and runs in parallel with the
+  // content via the speculative preload).
+  const {
+    registerGrammars
+  } = await import("./parseSource.mjs");
+  await registerGrammars(scopes);
+}
+
+/**
+ * Registers ALL grammars via the single barrel chunk (~146 KB gzip). Backs the
+ * `preloadGrammars: 'all'` provider opt-in — for layouts that will render code
+ * in many languages and prefer one upfront fetch over per-language chunks. Fails
+ * open.
+ */
+export async function preloadAllGrammars() {
+  const {
+    registerAllGrammars
+  } = await import("./parseSource.mjs");
+  await registerAllGrammars();
+}

package/pipeline/parseSource/grammarLoaders.d.mts

@@ -0,0 +1,14 @@
+/**
+ * Per-scope grammar loaders. Each entry dynamically imports a single
+ * `@wooorm/starry-night` grammar module, so the bundler emits one chunk per
+ * grammar instead of the all-in-one `./grammars` barrel. `ensureGrammars`
+ * (in `./parseSource`) resolves only the scopes a block needs, keeping the
+ * unused grammar payloads (~146 KB gzip for all 10) out of the download.
+ *
+ * Keys are starry-night scope names — the same values `./grammarMaps` resolves
+ * file extensions and language props to, so every detectable language has a
+ * loader (asserted in the tests).
+ */
+import type { Grammar } from '@wooorm/starry-night';
+export type GrammarLoader = () => Promise<Grammar>;
+export declare const grammarLoaders: Record<string, GrammarLoader>;

package/pipeline/parseSource/grammarLoaders.mjs

@@ -0,0 +1,24 @@
+/**
+ * Per-scope grammar loaders. Each entry dynamically imports a single
+ * `@wooorm/starry-night` grammar module, so the bundler emits one chunk per
+ * grammar instead of the all-in-one `./grammars` barrel. `ensureGrammars`
+ * (in `./parseSource`) resolves only the scopes a block needs, keeping the
+ * unused grammar payloads (~146 KB gzip for all 10) out of the download.
+ *
+ * Keys are starry-night scope names — the same values `./grammarMaps` resolves
+ * file extensions and language props to, so every detectable language has a
+ * loader (asserted in the tests).
+ */
+
+export const grammarLoaders = {
+  'source.js': () => import('@wooorm/starry-night/source.js').then(mod => mod.default),
+  'source.ts': () => import('@wooorm/starry-night/source.ts').then(mod => mod.default),
+  'source.tsx': () => import('@wooorm/starry-night/source.tsx').then(mod => mod.default),
+  'source.json': () => import('@wooorm/starry-night/source.json').then(mod => mod.default),
+  'text.md': () => import('@wooorm/starry-night/text.md').then(mod => mod.default),
+  'source.mdx': () => import('@wooorm/starry-night/source.mdx').then(mod => mod.default),
+  'text.html.basic': () => import('@wooorm/starry-night/text.html.basic').then(mod => mod.default),
+  'source.css': () => import('@wooorm/starry-night/source.css').then(mod => mod.default),
+  'source.shell': () => import('@wooorm/starry-night/source.shell').then(mod => mod.default),
+  'source.yaml': () => import('@wooorm/starry-night/source.yaml').then(mod => mod.default)
+};

package/pipeline/parseSource/grammarMaps.d.mts

@@ -15,4 +15,24 @@ export declare const languageToGrammarMap: Record<string, string>;
  * @param language - The language name (e.g., 'tsx', 'css', 'typescript')
  * @returns The grammar scope or undefined if not recognized
  */
-export declare function getGrammarFromLanguage(language: string): string | undefined;
+export declare function getGrammarFromLanguage(language: string): string | undefined;
+/**
+ * Resolves a grammar scope from a file's name and/or explicit language,
+ * preferring `language` and falling back to the file extension. This is the
+ * single source of truth for how `parseSource` picks a grammar and how
+ * `detectGrammarScopes` enumerates the grammars a code block needs, so the two
+ * never disagree.
+ *
+ * @param fileName - File name used to detect language via its extension
+ * @param language - Optional explicit language override (e.g., 'tsx', 'css')
+ * @returns The grammar scope, or undefined for unsupported / unknown inputs
+ */
+export declare function resolveGrammarScope(fileName?: string, language?: string): string | undefined;
+/**
+ * Normalizes a user-supplied list (the `preloadGrammars` provider prop) to
+ * grammar scope names, accepting either language names (`'tsx'`, `'typescript'`)
+ * or scope names (`'source.tsx'`) and de-duplicating. Entries that match neither
+ * are passed through as-is, so an unrecognized scope is simply ignored
+ * downstream (it has no loader) rather than throwing.
+ */
+export declare function normalizeToScopes(entries: string[]): string[];

package/pipeline/parseSource/grammarMaps.mjs

@@ -50,4 +50,40 @@ export const languageToGrammarMap = {
  */
 export function getGrammarFromLanguage(language) {
   return languageToGrammarMap[language.toLowerCase()];
+}
+
+/**
+ * Resolves a grammar scope from a file's name and/or explicit language,
+ * preferring `language` and falling back to the file extension. This is the
+ * single source of truth for how `parseSource` picks a grammar and how
+ * `detectGrammarScopes` enumerates the grammars a code block needs, so the two
+ * never disagree.
+ *
+ * @param fileName - File name used to detect language via its extension
+ * @param language - Optional explicit language override (e.g., 'tsx', 'css')
+ * @returns The grammar scope, or undefined for unsupported / unknown inputs
+ */
+export function resolveGrammarScope(fileName, language) {
+  if (language) {
+    const scope = getGrammarFromLanguage(language);
+    if (scope) {
+      return scope;
+    }
+  }
+  if (fileName) {
+    const fileType = fileName.slice(fileName.lastIndexOf('.'));
+    return extensionMap[fileType];
+  }
+  return undefined;
+}
+
+/**
+ * Normalizes a user-supplied list (the `preloadGrammars` provider prop) to
+ * grammar scope names, accepting either language names (`'tsx'`, `'typescript'`)
+ * or scope names (`'source.tsx'`) and de-duplicating. Entries that match neither
+ * are passed through as-is, so an unrecognized scope is simply ignored
+ * downstream (it has no loader) rather than throwing.
+ */
+export function normalizeToScopes(entries) {
+  return [...new Set(entries.map(entry => getGrammarFromLanguage(entry) ?? entry))];
 }

package/pipeline/parseSource/isFrameSpan.d.mts

@@ -0,0 +1,19 @@
+import type { Element as HastElement } from 'hast';
+/**
+ * Returns `true` when a HAST element carries the given class name, accepting
+ * both shapes `className` can take:
+ *
+ * - the string form (`className: 'frame'`), used by freshly parsed / live HAST
+ *   (e.g. `createFrame`), and
+ * - the array form (`className: ['frame']`), produced by `fallbackToHast` and by
+ *   any HAST that round-trips through serialization.
+ *
+ * Matching only the string silently skips real fallback frames, so class checks
+ * on HAST that may come from either path must go through this helper.
+ */
+export declare function hasClassName(element: HastElement, name: string): boolean;
+/**
+ * Returns `true` when a HAST element is a code frame span — its `className`
+ * includes `'frame'` in either the string or array shape (see {@link hasClassName}).
+ */
+export declare function isFrameSpan(element: HastElement): boolean;

package/pipeline/parseSource/isFrameSpan.mjs

@@ -0,0 +1,24 @@
+/**
+ * Returns `true` when a HAST element carries the given class name, accepting
+ * both shapes `className` can take:
+ *
+ * - the string form (`className: 'frame'`), used by freshly parsed / live HAST
+ *   (e.g. `createFrame`), and
+ * - the array form (`className: ['frame']`), produced by `fallbackToHast` and by
+ *   any HAST that round-trips through serialization.
+ *
+ * Matching only the string silently skips real fallback frames, so class checks
+ * on HAST that may come from either path must go through this helper.
+ */
+export function hasClassName(element, name) {
+  const className = element.properties?.className;
+  return className === name || Array.isArray(className) && className.includes(name);
+}
+
+/**
+ * Returns `true` when a HAST element is a code frame span — its `className`
+ * includes `'frame'` in either the string or array shape (see {@link hasClassName}).
+ */
+export function isFrameSpan(element) {
+  return hasClassName(element, 'frame');
+}

package/pipeline/parseSource/parseSource.d.mts

@@ -1,4 +1,20 @@
 import type { ParseSource } from "../../CodeHighlighter/types.mjs";
+/**
+ * Parses source into a line-guttered HAST **without** syntax highlighting — the
+ * raw text wrapped in the same `.line`/`.frame` structure `parseSource` produces,
+ * just no starry-night tokenization. It is a `ParseSource` so it can be dropped
+ * into the loader in place of the highlighting parser.
+ *
+ * Used for the deferred (un-highlighted) fallback: the enhancer pipeline needs the
+ * line/frame structure to compute focus windows and truncation, but the syntax
+ * colors are exactly the part being deferred — so we skip them. Cheap (no grammar,
+ * no `getInstance`); the frames it produces collapse back to text via `buildRootFallback`.
+ *
+ * Takes only `source` (it ignores file name / language since it never highlights) but
+ * stays structurally assignable to `ParseSource`, so it drops into the loader in place
+ * of the highlighting parser.
+ */
+export declare const parsePlainText: (source: string) => ReturnType<ParseSource>;
 /**
  * Parses source code into a HAST tree with syntax highlighting.
  *
@@ -9,15 +25,34 @@ import type { ParseSource } from "../../CodeHighlighter/types.mjs";
  * @throws Error if `createParseSource()` has not been called first
  */
 export declare const parseSource: ParseSource;
+/**
+ * Registers the grammars for the given scopes (and their dependencies) on the
+ * global Starry Night instance, loading the per-scope chunks on demand.
+ * Idempotent and deduped. Fails open: a chunk that fails to load leaves its
+ * scope as plain text rather than rejecting the batch.
+ *
+ * This is the heavy implementation (it can create the engine instance). Client
+ * code should call the light facade {@link ensureGrammars} from `./grammarCache`
+ * instead, so the engine stays out of the client bundle until a block needs it.
+ */
+export declare function registerGrammars(scopes: string[]): Promise<void>;
+export declare function registerAllGrammars(): Promise<void>;
 /**
  * Initializes Starry Night and returns a configured `parseSource` function.
- * This only needs to be called once per application. The Starry Night instance
- * is stored globally for reuse across calls.
+ * Only needs to be called once per application; the instance is stored globally
+ * for reuse across calls.
  *
- * The grammar definitions are loaded via dynamic `import('./grammars')` so the
- * (heavy) TextMate JSON payload is split into its own bundler chunk and only
- * fetched when syntax highlighting is actually needed.
+ * With no `initialScopes`, loads ALL grammars via the (lazy) `./grammars` barrel
+ * — the eager `CodeProvider` / Node / build-time behavior, so the heavy TextMate
+ * JSON is split into its own chunk but fully available. Pass `initialScopes`
+ * (possibly `[]`) to create a lean instance that registers grammars on demand
+ * via {@link registerGrammars} — the `CodeProviderLazy` per-language path.
  *
  * @returns A Promise that resolves to the initialized `parseSource` function
  */
-export declare const createParseSource: () => Promise<ParseSource>;
+export declare const createParseSource: (initialScopes?: string[]) => Promise<ParseSource>;
+/**
+ * Clears the global Starry Night singleton and registration state. Intended for
+ * tests exercising lazy registration from a known-empty registry.
+ */
+export declare function resetStarryNight(): void;