@mui/internal-docs-infra 0.12.1-canary.2 → 0.12.1-canary.21

package/pipeline/loaderUtils/parseImportsAndComments.mjs

@@ -641,6 +641,32 @@ function skipWhitespace(text, start) {
   return pos;
 }
 
+/**
+ * Skips whitespace and line (`//`) or block comments, returning the next
+ * significant position. Used to read a dynamic import's specifier past a leading
+ * comment — e.g. a webpack magic comment before the module string.
+ */
+function skipWhitespaceAndComments(text, start) {
+  let pos = start;
+  for (;;) {
+    pos = skipWhitespace(text, pos);
+    if (text[pos] === '/' && text[pos + 1] === '/') {
+      pos += 2;
+      while (pos < text.length && text[pos] !== '\n') {
+        pos += 1;
+      }
+    } else if (text[pos] === '/' && text[pos + 1] === '*') {
+      pos += 2;
+      while (pos < text.length && !(text[pos] === '*' && text[pos + 1] === '/')) {
+        pos += 1;
+      }
+      pos += 2;
+    } else {
+      return pos;
+    }
+  }
+}
+
 /**
  * Reads a JavaScript identifier starting at the given position.
  * @param text - The text to read from
@@ -678,7 +704,9 @@ function readQuotedString(text, start) {
   while (pos < text.length) {
     const ch = text[pos];
     if (ch === '\\' && pos + 1 < text.length) {
-      // Skip escaped character
+      // Keep the escaped character (drop the backslash): `\"` denotes a literal quote
+      // in the specifier, so it must stay in the path rather than being dropped.
+      value += text[pos + 1];
       pos += 2;
       continue;
     }
@@ -901,6 +929,131 @@ function parseCssImportStatement(cssCode, start) {
   };
 }
 
+/**
+ * Records one CSS import path into the relative or external bucket, with its
+ * source position for rewriting. Shared by `@import`, `composes ... from`, and
+ * `@value ... from`. In CSS a path is relative unless it has a protocol,
+ * hostname, or scoped-package (`@scope/`) prefix.
+ */
+function recordCssImport(modulePath, pathStart, pathEnd, cssResult, cssExternals, cssFilePath, positionMapper) {
+  const hasProtocol = /^https?:\/\//.test(modulePath);
+  const hasHostname = /^\/\//.test(modulePath);
+  const isScopedPackage = /^@[^/]+\//.test(modulePath);
+  const isRelative = !hasProtocol && !hasHostname && !isScopedPackage;
+  const position = {
+    start: positionMapper(pathStart),
+    end: positionMapper(pathEnd)
+  };
+  if (isRelative) {
+    // Normalize bare filenames (e.g. "reset.css") to relative paths.
+    let normalizedPath = modulePath;
+    if (!normalizedPath.startsWith('./') && !normalizedPath.startsWith('../')) {
+      normalizedPath = `./${normalizedPath}`;
+    }
+    if (!cssResult[modulePath]) {
+      cssResult[modulePath] = {
+        url: resolveRelativeImport(cssFilePath, normalizedPath),
+        names: [],
+        positions: []
+      };
+    }
+    cssResult[modulePath].positions.push(position);
+  } else {
+    if (!cssExternals[modulePath]) {
+      cssExternals[modulePath] = {
+        names: [],
+        positions: []
+      };
+    }
+    cssExternals[modulePath].positions.push(position);
+  }
+}
+
+/** Index of the `;` or `}` ending a CSS statement at/after `start` (string-aware). */
+function findCssStatementEnd(text, start) {
+  let pos = start;
+  while (pos < text.length) {
+    const ch = text[pos];
+    if (ch === ';' || ch === '}') {
+      return pos;
+    }
+    if (ch === '"' || ch === "'") {
+      pos += 1;
+      while (pos < text.length && text[pos] !== ch) {
+        pos += text[pos] === '\\' ? 2 : 1;
+      }
+    }
+    pos += 1;
+  }
+  return text.length;
+}
+
+/**
+ * Scans a `composes`/`@value` statement body (`[start, end)`) for a
+ * `from "<path>"` clause, skipping any quoted string before it. Returns the
+ * quoted module path with its position (quotes included), or null for a same-file
+ * `composes`, a `from global`, or a plain `@value` definition.
+ */
+function parseCssFromClause(text, start, end) {
+  let pos = start;
+  while (pos < end) {
+    const ch = text[pos];
+    // Skip a quoted string (e.g. a `@value` definition's string value).
+    if (ch === '"' || ch === "'") {
+      pos += 1;
+      while (pos < end && text[pos] !== ch) {
+        pos += text[pos] === '\\' ? 2 : 1;
+      }
+      pos += 1;
+      continue;
+    }
+    // A standalone `from` keyword introduces the source module.
+    if (ch === 'f' && text.slice(pos, pos + 4) === 'from' && !isIdentifierChar(text[pos - 1] || '') && !isIdentifierChar(text[pos + 4] || '')) {
+      const quoteStart = skipWhitespace(text, pos + 4);
+      const quote = text[quoteStart];
+      if (quote !== '"' && quote !== "'") {
+        return null; // `from global` or other non-path source
+      }
+      let cursor = quoteStart + 1;
+      let modulePath = '';
+      while (cursor < end && text[cursor] !== quote) {
+        if (text[cursor] === '\\' && cursor + 1 < end) {
+          // Keep the escaped character (drop the backslash): `\"` denotes a literal
+          // quote in the specifier, so it must stay in the path, not be lost.
+          modulePath += text[cursor + 1];
+          cursor += 2;
+          continue;
+        }
+        modulePath += text[cursor];
+        cursor += 1;
+      }
+      if (text[cursor] !== quote) {
+        return null; // unterminated
+      }
+      return {
+        modulePath,
+        pathStart: quoteStart,
+        pathEnd: cursor + 1
+      };
+    }
+    pos += 1;
+  }
+  return null;
+}
+
+/** Whether `pos` begins a CSS declaration (a property), not a selector or value. */
+function atCssDeclarationStart(text, pos) {
+  let index = pos - 1;
+  while (index >= 0 && isWhitespace(text[index])) {
+    index -= 1;
+  }
+  if (index < 0) {
+    return true;
+  }
+  const ch = text[index];
+  return ch === '{' || ch === ';' || ch === '}';
+}
+
 // CSS import detector function
 function detectCssImport(sourceText, pos, cssResult, cssExternals, cssFilePath, positionMapper) {
   const ch = sourceText[pos];
@@ -910,46 +1063,52 @@ function detectCssImport(sourceText, pos, cssResult, cssExternals, cssFilePath,
     // Parse the @import statement
     const importResult = parseCssImportStatement(sourceText, pos);
     if (importResult.modulePath && importResult.pathStart !== undefined && importResult.pathEnd !== undefined) {
-      // In CSS, imports are relative unless they have a protocol, hostname,
-      // or are scoped npm packages (start with @scope/)
-      const hasProtocol = /^https?:\/\//.test(importResult.modulePath);
-      const hasHostname = /^\/\//.test(importResult.modulePath);
-      const isScopedPackage = /^@[^/]+\//.test(importResult.modulePath);
-      const isRelative = !hasProtocol && !hasHostname && !isScopedPackage;
-      const position = {
-        start: positionMapper(importResult.pathStart),
-        end: positionMapper(importResult.pathEnd)
-      };
-      if (isRelative) {
-        // Normalize bare filenames (e.g. "reset.css") to relative paths
-        let normalizedPath = importResult.modulePath;
-        if (!normalizedPath.startsWith('./') && !normalizedPath.startsWith('../')) {
-          normalizedPath = `./${normalizedPath}`;
-        }
-        const resolvedUrl = resolveRelativeImport(cssFilePath, normalizedPath);
-        if (!cssResult[importResult.modulePath]) {
-          cssResult[importResult.modulePath] = {
-            url: resolvedUrl,
-            names: [],
-            positions: []
-          };
-        }
-        cssResult[importResult.modulePath].positions.push(position);
-      } else {
-        if (!cssExternals[importResult.modulePath]) {
-          cssExternals[importResult.modulePath] = {
-            names: [],
-            positions: []
-          };
-        }
-        cssExternals[importResult.modulePath].positions.push(position);
-      }
+      recordCssImport(importResult.modulePath, importResult.pathStart, importResult.pathEnd, cssResult, cssExternals, cssFilePath, positionMapper);
     }
     return {
       found: true,
       nextPos: importResult.nextPos
     };
   }
+
+  // Look for `@value <names> from "<path>"` — a cross-file CSS-module value import
+  // (a plain `@value name: value;` definition has no `from` and is left alone).
+  if (ch === '@' && sourceText.slice(pos, pos + 6) === '@value' && isWhitespace(sourceText[pos + 6] || '')) {
+    const stop = findCssStatementEnd(sourceText, pos + 6);
+    const fromClause = parseCssFromClause(sourceText, pos + 6, stop);
+    if (fromClause) {
+      recordCssImport(fromClause.modulePath, fromClause.pathStart, fromClause.pathEnd, cssResult, cssExternals, cssFilePath, positionMapper);
+      return {
+        found: true,
+        nextPos: stop
+      };
+    }
+    return {
+      found: false,
+      nextPos: pos
+    };
+  }
+
+  // Look for `composes: <names> from "<path>"` — a cross-file CSS-module
+  // composition (a same-file `composes: a b;` or `from global` is left alone).
+  if (ch === 'c' && sourceText.slice(pos, pos + 8) === 'composes' && !isIdentifierChar(sourceText[pos + 8] || '') && atCssDeclarationStart(sourceText, pos)) {
+    const colon = skipWhitespace(sourceText, pos + 8);
+    if (sourceText[colon] === ':') {
+      const stop = findCssStatementEnd(sourceText, colon + 1);
+      const fromClause = parseCssFromClause(sourceText, colon + 1, stop);
+      if (fromClause) {
+        recordCssImport(fromClause.modulePath, fromClause.pathStart, fromClause.pathEnd, cssResult, cssExternals, cssFilePath, positionMapper);
+        return {
+          found: true,
+          nextPos: stop
+        };
+      }
+    }
+    return {
+      found: false,
+      nextPos: pos
+    };
+  }
   return {
     found: false,
     nextPos: pos
@@ -1019,6 +1178,16 @@ function parseJSImports(code, filePath, result, externals, isMdxFile, removeComm
       pos = skipWhitespace(text, pos);
     }
 
+    // Dynamic import: `import('...')`. Step into the parens so its string-literal
+    // specifier is read by the side-effect handling below (a dynamic import has no
+    // bound names, so it's recorded just like a side-effect import). A non-literal
+    // argument — an identifier or a template — is left untouched since it can't be
+    // resolved statically. Skip a leading comment too (e.g. a webpack magic comment)
+    // so the specifier after it is still read.
+    if (pos < textLen && text[pos] === '(') {
+      pos = skipWhitespaceAndComments(text, pos + 1);
+    }
+
     // Check if this is a side-effect import (starts with quote)
     if (pos < textLen && (text[pos] === '"' || text[pos] === "'")) {
       const {
@@ -1362,12 +1531,85 @@ function detectJavaScriptImport(sourceText, pos, _positionMapper) {
     };
   }
 
-  // Look for 'import' keyword (not part of an identifier, and not preceded by @)
-  if (ch === 'i' && sourceText.slice(pos, pos + 6) === 'import' && (pos === 0 || /[^a-zA-Z0-9_$@]/.test(sourceText[pos - 1])) && /[^a-zA-Z0-9_$]/.test(sourceText[pos + 6] || '')) {
+  // Look for 'import' keyword (not part of an identifier, and not preceded by `@`
+  // or `.` — the latter would be a member call like `obj.import('./x')`, not a
+  // dynamic import).
+  if (ch === 'i' && sourceText.slice(pos, pos + 6) === 'import' && (pos === 0 || /[^a-zA-Z0-9_$@.]/.test(sourceText[pos - 1])) && /[^a-zA-Z0-9_$]/.test(sourceText[pos + 6] || '')) {
     // Mark start of import statement
     const importStart = pos;
     const len = sourceText.length;
 
+    // Dynamic import `import(...)`: end the statement at the matching `)`. The
+    // generic statement scan below ends at the next `;` (a dynamic import has no
+    // `from`), which would swallow a LATER `import('./b')` in the same expression
+    // (e.g. a one-lined tab map) and leave it undetected. Closing at `)` lets the
+    // scanner resume and find each one. Parens, strings, templates AND comments are
+    // tracked so a nested paren, the quoted specifier, or a `)`/quote inside a
+    // `/* … */` (e.g. a webpack magic comment or `/* user's tab */`) doesn't end it
+    // early.
+    let parenPos = pos + 6;
+    while (parenPos < len && /\s/.test(sourceText[parenPos] || '')) {
+      parenPos += 1;
+    }
+    if (sourceText[parenPos] === '(') {
+      let depth = 0;
+      let dynState = 'code';
+      let dynQuote = '';
+      let k = parenPos;
+      while (k < len) {
+        const ck = sourceText[k];
+        if (dynState === 'code') {
+          if (ck === '/' && sourceText[k + 1] === '/') {
+            dynState = 'line-comment';
+            k += 2;
+            continue;
+          }
+          if (ck === '/' && sourceText[k + 1] === '*') {
+            dynState = 'block-comment';
+            k += 2;
+            continue;
+          }
+          if (ck === '(') {
+            depth += 1;
+          } else if (ck === ')') {
+            depth -= 1;
+            if (depth === 0) {
+              k += 1;
+              break;
+            }
+          } else if (ck === '"' || ck === "'" || ck === '`') {
+            dynState = ck === '`' ? 'template' : 'string';
+            dynQuote = ck;
+          }
+        } else if (dynState === 'line-comment') {
+          if (ck === '\n') {
+            dynState = 'code';
+          }
+        } else if (dynState === 'block-comment') {
+          if (ck === '*' && sourceText[k + 1] === '/') {
+            dynState = 'code';
+            k += 2;
+            continue;
+          }
+        } else if (ck === '\\') {
+          k += 2;
+          continue;
+        } else if (dynState === 'string' && ck === dynQuote || dynState === 'template' && ck === '`') {
+          dynState = 'code';
+        }
+        k += 1;
+      }
+      return {
+        found: true,
+        nextPos: k,
+        statement: {
+          start: importStart,
+          end: k,
+          text: sourceText.slice(importStart, k)
+        }
+      };
+    }
+
     // Now, scan forward to find the end of the statement (semicolon or proper end for side-effect imports)
     let j = pos + 6;
     let importState = 'code';
@@ -1493,16 +1735,18 @@ function detectJavaScriptImport(sourceText, pos, _positionMapper) {
  * parsed straight out of remote sources without first being mapped onto a
  * placeholder `file://` URL.
  *
+ * Parsing is fully synchronous — no I/O, no `await`.
+ *
  * @param code - The source code to parse
  * @param fileUrl - The file URL (`file://`, `http://`, `https://`) or path, used to determine file type and resolve relative imports
  * @param options - Optional configuration for comment processing
  * @param options.removeCommentsWithPrefix - Array of prefixes; comments starting with these will be stripped from output
  * @param options.notableCommentsPrefix - Array of prefixes; comments starting with these will be collected regardless of stripping
- * @returns Promise resolving to parsed import data, optionally including processed code and collected comments
+ * @returns Parsed import data, optionally including processed code and collected comments
  *
  * @example
  * ```typescript
- * const result = await parseImportsAndComments(
+ * const result = parseImportsAndComments(
  *   'import React from "react";\nimport { Button } from "./Button";\nexport { Icon } from "./Icon";',
  *   '/src/App.tsx'
  * );
@@ -1511,7 +1755,7 @@ function detectJavaScriptImport(sourceText, pos, _positionMapper) {
  * // result.relative['./Icon'] contains the Icon re-export
  * ```
  */
-export async function parseImportsAndComments(code, fileUrl, options) {
+export function parseImportsAndComments(code, fileUrl, options) {
   const result = {};
   const externals = {};
 

package/pipeline/parseCreateFactoryCall/parseCreateFactoryCall.d.mts

@@ -1,5 +1,5 @@
-import { type ImportsAndComments } from "../loaderUtils/index.mjs";
-import { type SplitArguments } from "./parseFunctionArguments.mjs";
+import type { ImportsAndComments } from "../loaderUtils/index.mjs";
+import type { SplitArguments } from "./parseFunctionArguments.mjs";
 import type { Externals } from "../../CodeHighlighter/types.mjs";
 /**
  * Parse options for create* factory call parsing

package/pipeline/parseCreateFactoryCall/parseCreateFactoryCall.mjs

@@ -527,7 +527,7 @@ export async function parseCreateFactoryCall(code, filePath, parseOptions = {},
     }
   }
   // Get import mappings from precomputed imports or parse them
-  importsAndComments = importsAndComments || (await parseImportsAndComments(code, filePath));
+  importsAndComments = importsAndComments || parseImportsAndComments(code, filePath);
 
   // Process the match using shared logic
   const parsed = await processCreateFactoryMatch(match, code, filePath, parseOptions, importsAndComments);
@@ -566,8 +566,7 @@ export async function parseAllCreateFactoryCalls(code, filePath, parseOptions =
     const exportName = exportMatch?.[1] || 'unknown';
 
     // Get import mappings from precomputed imports or parse them
-    // eslint-disable-next-line no-await-in-loop
-    importsAndComments = importsAndComments || (await parseImportsAndComments(code, filePath));
+    importsAndComments = importsAndComments || parseImportsAndComments(code, filePath);
 
     // Process the match using shared logic
     // eslint-disable-next-line no-await-in-loop

package/pipeline/parseSource/detectFileTypes.d.mts

@@ -0,0 +1,16 @@
+import type { Code } from "../../CodeHighlighter/types.mjs";
+/**
+ * Detects which live-editing engine chunks a code block will need, by file
+ * extension across every variant — so a host can PRELOAD them the moment editing
+ * activates (before the first keystroke): `js` when any file is JS/TS/JSX/TSX/MJS
+ * (it will be transpiled and built), `css` when any file is CSS (it will be
+ * compiled). Reads only file names/keys, never source — cheap and synchronous, so
+ * it can run on every render.
+ *
+ * Bare string variants (no file metadata) and `undefined` variants contribute
+ * nothing.
+ */
+export declare function detectFileTypes(code: Code): {
+  js: boolean;
+  css: boolean;
+};

package/pipeline/parseSource/detectFileTypes.mjs

@@ -0,0 +1,44 @@
+/** Extensions whose files need the transpile + build engine when edited live. */
+const JS_EXTENSIONS = ['.js', '.mjs', '.jsx', '.ts', '.tsx'];
+
+/**
+ * Detects which live-editing engine chunks a code block will need, by file
+ * extension across every variant — so a host can PRELOAD them the moment editing
+ * activates (before the first keystroke): `js` when any file is JS/TS/JSX/TSX/MJS
+ * (it will be transpiled and built), `css` when any file is CSS (it will be
+ * compiled). Reads only file names/keys, never source — cheap and synchronous, so
+ * it can run on every render.
+ *
+ * Bare string variants (no file metadata) and `undefined` variants contribute
+ * nothing.
+ */
+export function detectFileTypes(code) {
+  let js = false;
+  let css = false;
+  for (const variant of Object.values(code)) {
+    if (!variant || typeof variant === 'string') {
+      continue;
+    }
+    const fileNames = [variant.fileName, ...(variant.extraFiles ? Object.keys(variant.extraFiles) : [])];
+    for (const fileName of fileNames) {
+      if (!fileName) {
+        continue;
+      }
+      if (fileName.endsWith('.css')) {
+        css = true;
+      } else if (JS_EXTENSIONS.some(extension => fileName.endsWith(extension))) {
+        js = true;
+      }
+      if (js && css) {
+        return {
+          js,
+          css
+        };
+      }
+    }
+  }
+  return {
+    js,
+    css
+  };
+}

package/pipeline/syncPageIndex/mergeMetadataMarkdown.d.mts

@@ -1,4 +1,4 @@
-import { type MetadataToMarkdownOptions, type PagesMetadata } from "./metadataToMarkdown.mjs";
+import type { MetadataToMarkdownOptions, PagesMetadata } from "./metadataToMarkdown.mjs";
 /**
  * Options for mergeMetadataMarkdown
  */
@@ -25,6 +25,30 @@ export interface MergeMetadataMarkdownOptions extends Omit<MetadataToMarkdownOpt
    */
   preserveExistingTitleAndSlug?: boolean;
 }
+/**
+ * Result of merging new metadata into existing markdown: the normalized
+ * `PagesMetadata` that renders to the merged markdown, plus the rendering options
+ * needed to reproduce that markdown.
+ */
+export interface MergedMetadataResult {
+  /** The normalized pages metadata that renders to the merged markdown. */
+  metadata: PagesMetadata;
+  /** Effective wrapper component to render with (undefined = no wrapper). */
+  indexWrapperComponent?: string;
+  /** Editable marker to render with (e.g. the alphabetical-sort marker), if any. */
+  editableMarker?: string;
+}
+/**
+ * Merges new page metadata with existing markdown content and returns the
+ * normalized `PagesMetadata` (and rendering options) without serializing to markdown.
+ *
+ * This is the in-memory source of truth that {@link mergeMetadataMarkdown} renders.
+ * `syncPageIndex` reuses it to pre-populate the page-index cache, so the cached
+ * value matches a fresh read of the rendered markdown.
+ *
+ * See {@link mergeMetadataMarkdown} for the ordering and merge semantics.
+ */
+export declare function mergeMetadataPages(existingMarkdown: string | undefined, newMetadata: PagesMetadata, options?: MergeMetadataMarkdownOptions): Promise<MergedMetadataResult>;
 /**
  * Merges new page metadata with existing markdown content, preserving the order
  * of pages from the existing markdown when available, unless the file contains