@mui/internal-docs-infra 0.2.3-canary.9 → 0.3.1-canary.0

package/esm/pipeline/loaderUtils/rewriteImports.js

@@ -3,6 +3,137 @@ import _createForOfIteratorHelper from "@babel/runtime/helpers/esm/createForOfIt
  * Interface for rewrite replacement operations.
  */
 
+/**
+ * Converts import statements to const declarations set to null.
+ * This preserves variable names while removing the actual imports.
+ * Useful when precomputing data that makes the imports unnecessary.
+ *
+ * @param source - The source code to process
+ * @param importPathsToRewrite - Set of import paths whose import statements should be rewritten
+ * @param importResult - Import result with position and name data
+ * @returns The source code with import statements rewritten to const declarations
+ */
+export function rewriteImportsToNull(source, importPathsToRewrite, importResult) {
+  var replacements = [];
+
+  // Find all import statements to rewrite
+  importPathsToRewrite.forEach(function (importPath) {
+    var importData = importResult[importPath];
+    if (importData && importData.positions.length > 0) {
+      // For each position (there should typically be one per import statement)
+      var _iterator = _createForOfIteratorHelper(importData.positions),
+        _step;
+      try {
+        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+          var position = _step.value;
+          // Parse backwards from the quote to find 'import' keyword
+          var importStart = position.start;
+          var targetWord = 'import';
+          while (importStart >= targetWord.length) {
+            var slice = source.slice(importStart - targetWord.length, importStart);
+            var prevChar = importStart > targetWord.length ? source[importStart - targetWord.length - 1] : '';
+            if (slice === targetWord && (!prevChar || /\s/.test(prevChar))) {
+              importStart -= targetWord.length;
+              break;
+            }
+            importStart -= 1;
+          }
+
+          // Parse forwards from after the closing quote to find semicolon/newline
+          // position.end points to the character AFTER the closing quote
+          var importEnd = position.end;
+
+          // Check for optional semicolon
+          if (importEnd < source.length && source[importEnd] === ';') {
+            importEnd += 1;
+          }
+
+          // Check for newline after the statement
+          var hasTrailingNewline = false;
+          if (importEnd < source.length && source[importEnd] === '\n') {
+            hasTrailingNewline = true;
+            importEnd += 1;
+          }
+
+          // Generate const declarations from import names
+          var constDeclarations = importData.names.map(function (nameInfo) {
+            var varName = nameInfo.alias || nameInfo.name;
+            return "const ".concat(varName, " = null;");
+          }).join('\n');
+
+          // Add newline if original import had one
+          var newText = constDeclarations + (hasTrailingNewline ? '\n' : '');
+          replacements.push({
+            start: importStart,
+            end: importEnd,
+            newText: newText
+          });
+        }
+      } catch (err) {
+        _iterator.e(err);
+      } finally {
+        _iterator.f();
+      }
+    }
+  });
+
+  // Sort replacements by position (descending) to avoid position shifts
+  replacements.sort(function (a, b) {
+    return b.start - a.start;
+  });
+
+  // Apply replacements from right to left (using same logic as rewriteImports)
+  var result = source;
+  for (var _i = 0, _replacements = replacements; _i < _replacements.length; _i++) {
+    var replacement = _replacements[_i];
+    result = result.slice(0, replacement.start) + replacement.newText + result.slice(replacement.end);
+  }
+  return result;
+}
+
+/**
+ * Removes entire import statements for the specified import paths.
+ * This removes the full import line, not just the path.
+ *
+ * @param source - The source code to process
+ * @param importPathsToRemove - Set of import paths whose entire import statements should be removed
+ * @param importResult - Import result with position data
+ * @returns The source code with import statements removed
+ */
+export function removeImports(source, importPathsToRemove, importResult) {
+  var linesToRemove = new Set();
+
+  // Find all line numbers that contain imports to remove
+  importPathsToRemove.forEach(function (importPath) {
+    var _importResult$importP;
+    var positions = (_importResult$importP = importResult[importPath]) == null ? void 0 : _importResult$importP.positions;
+    if (positions && positions.length > 0) {
+      var _iterator2 = _createForOfIteratorHelper(positions),
+        _step2;
+      try {
+        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+          var position = _step2.value;
+          // Find which line this position is on
+          var beforePosition = source.slice(0, position.start);
+          var lineNumber = (beforePosition.match(/\n/g) || []).length;
+          linesToRemove.add(lineNumber);
+        }
+      } catch (err) {
+        _iterator2.e(err);
+      } finally {
+        _iterator2.f();
+      }
+    }
+  });
+
+  // Split source into lines and filter out lines to remove
+  var lines = source.split('\n');
+  var filteredLines = lines.filter(function (_, index) {
+    return !linesToRemove.has(index);
+  });
+  return filteredLines.join('\n');
+}
+
 /**
  * Efficiently rewrites import paths using position data.
  * This avoids regex parsing and uses precise position information for replacement.
@@ -22,11 +153,11 @@ export function rewriteImports(source, importPathMapping, importResult) {
     var positions = (_importResult$origina = importResult[originalPath]) == null ? void 0 : _importResult$origina.positions;
     if (positions && positions.length > 0) {
       // Process all positions where this import path appears
-      var _iterator = _createForOfIteratorHelper(positions),
-        _step;
+      var _iterator3 = _createForOfIteratorHelper(positions),
+        _step3;
       try {
-        for (_iterator.s(); !(_step = _iterator.n()).done;) {
-          var position = _step.value;
+        for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+          var position = _step3.value;
           // Validate position bounds
           if (position.start >= 0 && position.end <= source.length && position.start < position.end) {
             // The positions include the quotes, so we need to preserve them
@@ -43,9 +174,9 @@ export function rewriteImports(source, importPathMapping, importResult) {
           }
         }
       } catch (err) {
-        _iterator.e(err);
+        _iterator3.e(err);
       } finally {
-        _iterator.f();
+        _iterator3.f();
       }
     }
   });
@@ -57,8 +188,8 @@ export function rewriteImports(source, importPathMapping, importResult) {
 
   // Apply replacements from right to left
   var result = source;
-  for (var _i = 0, _replacements = replacements; _i < _replacements.length; _i++) {
-    var replacement = _replacements[_i];
+  for (var _i2 = 0, _replacements2 = replacements; _i2 < _replacements2.length; _i2++) {
+    var replacement = _replacements2[_i2];
     result = result.slice(0, replacement.start) + replacement.newText + result.slice(replacement.end);
   }
   return result;

package/esm/pipeline/syncPageIndex/createMarkdownNodes.d.ts

@@ -0,0 +1,76 @@
+/**
+ * createMarkdownNodes.ts - Helper functions for creating MD AST nodes
+ *
+ * This module provides utility functions to create nodes for Markdown
+ * abstract syntax trees, making transformer code more readable and maintainable.
+ */
+import type { PhrasingContent, Text, Paragraph, Heading, Code, InlineCode, Table, Emphasis, Strong, Definition } from 'mdast';
+/**
+ * Create a text node
+ * @param value - The text content
+ * @returns A text node
+ */
+export declare function text(value: string): Text;
+type Child = PhrasingContent | string;
+/**
+ * Create a paragraph node
+ * @param children - Child node, string, or array of nodes/strings
+ * @returns A paragraph node
+ */
+export declare function paragraph(children: Child | Child[]): Paragraph;
+/**
+ * Create an emphasis (italic) node
+ * @param children - Child node, string, or array of nodes/strings
+ * @returns An emphasis node
+ */
+export declare function emphasis(children: Child | Child[]): Emphasis;
+/**
+ * Create a strong (bold) node
+ * @param children - Child node, string, or array of nodes/strings
+ * @returns A strong node
+ */
+export declare function strong(children: Child | Child[]): Strong;
+/**
+ * Create a heading node
+ * @param depth - Heading level (1-6)
+ * @param children - Child node, string, or array of nodes/strings
+ * @returns A heading node
+ */
+export declare function heading(depth: 1 | 2 | 3 | 4 | 5 | 6, children: Child | Child[]): Heading;
+/**
+ * Create a code block node
+ * @param {string} value - Code content
+ * @param {string} lang - Language for syntax highlighting
+ * @returns {Object} A code node
+ */
+export declare function code(value: string, lang?: string): Code;
+/**
+ * Create an inline code node
+ * @param {string} value - Code content
+ * @returns {Object} An inline code node
+ */
+export declare function inlineCode(value: string): InlineCode;
+/**
+ * Creates a markdown table node (GFM)
+ * @param {Array<string|Object>} headers - Array of header strings or nodes
+ * @param {Array<Array<string|Object>>} rows - Array of row data, each row is an array of cell content
+ * @param {Array<string>} [alignment] - Optional array of alignments ('left', 'center', 'right') for each column
+ * @param {number} [widthIncrements] - Optional value to control the increments that tables expand for cleaner
+ * @returns {Object} A table node
+ */
+export declare function table(headers: (Child | Child[])[], rows: (Child | Child[])[][], alignment?: string[] | null, widthIncrements?: number): Table;
+/**
+ * Create a comment node. Comment text will not be rendered in HTML output.
+ * @param value - Comment text
+ * @returns A comment node
+ */
+export declare function comment(value: string, ref?: string): Definition;
+/**
+ * Create a link node
+ * @param url - The URL to link to
+ * @param children - Child node, string, or array of nodes/strings
+ * @param title - Optional title attribute
+ * @returns A link node
+ */
+export declare function link(url: string, children: Child | Child[], title?: string): PhrasingContent;
+export {};

package/esm/pipeline/syncPageIndex/createMarkdownNodes.js

@@ -0,0 +1,305 @@
+import _toConsumableArray from "@babel/runtime/helpers/esm/toConsumableArray";
+import _extends from "@babel/runtime/helpers/esm/extends";
+/**
+ * createMarkdownNodes.ts - Helper functions for creating MD AST nodes
+ *
+ * This module provides utility functions to create nodes for Markdown
+ * abstract syntax trees, making transformer code more readable and maintainable.
+ */
+
+/**
+ * Create a text node
+ * @param value - The text content
+ * @returns A text node
+ */
+export function text(value) {
+  return {
+    type: 'text',
+    value: value || ''
+  };
+}
+/**
+ * Helper to normalize children (handles string, node, or array)
+ * @param children - Child content
+ * @returns Normalized array of nodes
+ */
+function normalizeChildren(children) {
+  // Handle empty or undefined
+  if (!children) {
+    return [];
+  }
+
+  // Convert to array if not already
+  var childArray = Array.isArray(children) ? children : [children];
+
+  // Convert strings to text nodes
+  return childArray.map(function (child) {
+    return typeof child === 'string' ? text(child) : child;
+  });
+}
+
+/**
+ * Create a paragraph node
+ * @param children - Child node, string, or array of nodes/strings
+ * @returns A paragraph node
+ */
+export function paragraph(children) {
+  return {
+    type: 'paragraph',
+    children: normalizeChildren(children)
+  };
+}
+
+/**
+ * Create an emphasis (italic) node
+ * @param children - Child node, string, or array of nodes/strings
+ * @returns An emphasis node
+ */
+export function emphasis(children) {
+  return {
+    type: 'emphasis',
+    children: normalizeChildren(children)
+  };
+}
+
+/**
+ * Create a strong (bold) node
+ * @param children - Child node, string, or array of nodes/strings
+ * @returns A strong node
+ */
+export function strong(children) {
+  return {
+    type: 'strong',
+    children: normalizeChildren(children)
+  };
+}
+
+/**
+ * Create a heading node
+ * @param depth - Heading level (1-6)
+ * @param children - Child node, string, or array of nodes/strings
+ * @returns A heading node
+ */
+export function heading(depth, children) {
+  return {
+    type: 'heading',
+    depth: depth || 1,
+    children: normalizeChildren(children)
+  };
+}
+
+/**
+ * Create a code block node
+ * @param {string} value - Code content
+ * @param {string} lang - Language for syntax highlighting
+ * @returns {Object} A code node
+ */
+export function code(value, lang) {
+  return {
+    type: 'code',
+    lang: lang || null,
+    value: value || ''
+  };
+}
+
+/**
+ * Create an inline code node
+ * @param {string} value - Code content
+ * @returns {Object} An inline code node
+ */
+export function inlineCode(value) {
+  return {
+    type: 'inlineCode',
+    value: value || ''
+  };
+}
+
+/**
+ * Calculate the visual length of phrasing content
+ * (e.g., "One `two` three" has visual length of ~13, or ~9 if excludeFormatting=true)
+ * @param node - The phrasing content node
+ * @param excludeFormatting - If true, don't count formatting characters like backticks, brackets, etc.
+ *                            This allows "`false`" and "false" to both be treated as length 5.
+ */
+function getPhrasingContentLength(node) {
+  var excludeFormatting = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
+  switch (node.type) {
+    case 'text':
+      return node.value.length;
+    case 'inlineCode':
+      // Backticks add 2 chars, but exclude them if normalizing
+      return node.value.length + (excludeFormatting ? 0 : 2);
+    case 'emphasis':
+      // Asterisks/underscores add chars, but exclude them if normalizing
+      return (node.children || []).reduce(function (sum, child) {
+        return sum + getPhrasingContentLength(child, excludeFormatting);
+      }, excludeFormatting ? 0 : 2 // *text* or _text_ adds 2 chars
+      );
+    case 'strong':
+      // Double asterisks/underscores add chars, but exclude them if normalizing
+      return (node.children || []).reduce(function (sum, child) {
+        return sum + getPhrasingContentLength(child, excludeFormatting);
+      }, excludeFormatting ? 0 : 4 // **text** or __text__ adds 4 chars
+      );
+    case 'delete':
+      // Tildes add chars, but exclude them if normalizing
+      return (node.children || []).reduce(function (sum, child) {
+        return sum + getPhrasingContentLength(child, excludeFormatting);
+      }, excludeFormatting ? 0 : 4 // ~~text~~ adds 4 chars
+      );
+    case 'link':
+      {
+        var _node$url;
+        // [text](url) format adds chars, but exclude them if normalizing
+        var childrenLength = (node.children || []).reduce(function (sum, child) {
+          return sum + getPhrasingContentLength(child, excludeFormatting);
+        }, 0);
+        return excludeFormatting ? childrenLength : childrenLength + 4 + (((_node$url = node.url) == null ? void 0 : _node$url.length) || 0); // [](url) adds 4 + url length
+      }
+    case 'image':
+      {
+        var _node$url2;
+        // ![alt](url) format
+        var altLength = (node.alt || '').length;
+        return excludeFormatting ? altLength : altLength + 5 + (((_node$url2 = node.url) == null ? void 0 : _node$url2.length) || 0); // ![](url) adds 5 + url length
+      }
+    case 'break':
+      return 0;
+    default:
+      return 0;
+  }
+}
+
+/**
+ * Creates a table cell node
+ * @param content - Cell content
+ * @param widthIncrements - Optional width increment for padding alignment
+ * @param excludeFormatting - If true, don't count formatting chars when calculating width
+ * @returns Table cell node
+ */
+function tableCell(content, widthIncrements) {
+  var excludeFormatting = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : true;
+  var children = normalizeChildren(content);
+  if (widthIncrements) {
+    // Calculate total visual length of all content
+    var totalLength = children.reduce(function (sum, child) {
+      return sum + getPhrasingContentLength(child, excludeFormatting);
+    }, 0);
+
+    // Calculate padding needed
+    var paddingNeeded = Math.ceil(totalLength / widthIncrements) * widthIncrements - totalLength;
+
+    // Add padding as trailing spaces to the last text node, or create a new text node
+    if (paddingNeeded > 0) {
+      var spaces = new Array(paddingNeeded).fill(' ').join('');
+
+      // Find the last text node and append spaces (reverse search)
+      var lastTextIndex = -1;
+      for (var i = children.length - 1; i >= 0; i -= 1) {
+        if (children[i].type === 'text') {
+          lastTextIndex = i;
+          break;
+        }
+      }
+      if (lastTextIndex >= 0) {
+        var lastText = children[lastTextIndex];
+        children[lastTextIndex] = _extends(_extends({}, lastText), {}, {
+          value: "".concat(lastText.value).concat(spaces)
+        });
+      } else {
+        // No text node found, add a new text node with just spaces
+        children.push(text(spaces));
+      }
+    }
+  }
+  return {
+    type: 'tableCell',
+    children: children
+  };
+}
+
+/**
+ * Creates a table row node
+ * @param cells - Array of cell contents
+ * @returns Table row node
+ */
+function tableRow(cells, widthIncrements) {
+  return {
+    type: 'tableRow',
+    children: cells.map(function (cell) {
+      return tableCell(cell, widthIncrements);
+    })
+  };
+}
+
+/**
+ * Creates a markdown table node (GFM)
+ * @param {Array<string|Object>} headers - Array of header strings or nodes
+ * @param {Array<Array<string|Object>>} rows - Array of row data, each row is an array of cell content
+ * @param {Array<string>} [alignment] - Optional array of alignments ('left', 'center', 'right') for each column
+ * @param {number} [widthIncrements] - Optional value to control the increments that tables expand for cleaner
+ * @returns {Object} A table node
+ */
+export function table(headers, rows) {
+  var alignment = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : null;
+  var widthIncrements = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : 7;
+  // Convert alignment strings to AST format
+  var align = headers.map(function (_, index) {
+    if (!alignment || !alignment[index]) {
+      return null;
+    }
+    switch (alignment[index]) {
+      case 'center':
+        return 'center';
+      case 'right':
+        return 'right';
+      default:
+        return 'left';
+    }
+  });
+
+  // Create header row
+  var headerRow = tableRow(headers);
+
+  // Create data rows - rows is actually an array of arrays
+  var dataRows = rows.map(function (row) {
+    return tableRow(row, widthIncrements);
+  });
+
+  // Return table node
+  return {
+    type: 'table',
+    align: align,
+    children: [headerRow].concat(_toConsumableArray(dataRows))
+  };
+}
+
+/**
+ * Create a comment node. Comment text will not be rendered in HTML output.
+ * @param value - Comment text
+ * @returns A comment node
+ */
+export function comment(value, ref) {
+  return {
+    type: 'definition',
+    identifier: '//',
+    url: ref || '#',
+    title: value
+  };
+}
+
+/**
+ * Create a link node
+ * @param url - The URL to link to
+ * @param children - Child node, string, or array of nodes/strings
+ * @param title - Optional title attribute
+ * @returns A link node
+ */
+export function link(url, children, title) {
+  return {
+    type: 'link',
+    url: url,
+    title: title,
+    children: normalizeChildren(children)
+  };
+}

package/esm/pipeline/syncPageIndex/index.d.ts

@@ -0,0 +1 @@
+export * from "./syncPageIndex.js";

package/esm/pipeline/syncPageIndex/index.js

@@ -0,0 +1 @@
+export * from "./syncPageIndex.js";

package/esm/pipeline/syncPageIndex/mergeMetadataMarkdown.d.ts

@@ -0,0 +1,58 @@
+import { type MetadataToMarkdownOptions, type PagesMetadata } from "./metadataToMarkdown.js";
+/**
+ * Options for mergeMetadataMarkdown
+ */
+export interface MergeMetadataMarkdownOptions extends Omit<MetadataToMarkdownOptions, 'editableMarker' | 'indexWrapperComponent'> {
+  /** If true, pages in existing markdown that aren't in newMetadata will be preserved. If false (default), they are removed. */
+  preserveUnlisted?: boolean;
+  /**
+   * Component name to wrap the autogenerated content.
+   * - `undefined`: preserve existing wrapper (if any)
+   * - `null`: explicitly remove the wrapper
+   * - `string`: use this component name
+   */
+  indexWrapperComponent?: string | null;
+  /**
+   * The path to the file being generated. Used in autogenerated comments to help
+   * users validate the file.
+   */
+  path?: string;
+}
+/**
+ * Merges new page metadata with existing markdown content, preserving the order
+ * of pages from the existing markdown when available, unless the file contains
+ * only the autogeneration marker (no editable section), in which case pages are
+ * sorted alphabetically by title.
+ *
+ * Pages are matched by their `path` property (e.g., './button/page.mdx'), not by slug.
+ * This allows multiple pages to have the same slug (anchor) while still being treated
+ * as distinct pages.
+ *
+ * @param existingMarkdown - The existing markdown content (or undefined if none exists)
+ * @param newMetadata - The new metadata to merge in
+ * @param options - Optional configuration
+ * @param options.preserveUnlisted - If true, pages in existing markdown that aren't in newMetadata will be preserved. If false (default), they are removed.
+ * @param options.indexWrapperComponent - Optional component name to wrap the autogenerated content (e.g., 'PagesIndex')
+ * @returns The updated markdown content with merged metadata
+ *
+ * @example
+ * ```ts
+ * const existingMarkdown = `# Components
+ * - [Button](#button) - [Full Docs](./button/page.mdx) - A button
+ * - [Checkbox](#checkbox) - [Full Docs](./checkbox/page.mdx) - A checkbox
+ * `;
+ *
+ * const newMetadata = {
+ *   title: 'Components',
+ *   pages: [
+ *     { slug: 'checkbox', path: './checkbox/page.mdx', title: 'Checkbox', description: 'Updated checkbox' },
+ *     { slug: 'button', path: './button/page.mdx', title: 'Button', description: 'Updated button' },
+ *     { slug: 'input', path: './input/page.mdx', title: 'Input', description: 'New input' },
+ *   ],
+ * };
+ *
+ * const result = await mergeMetadataMarkdown(existingMarkdown, newMetadata);
+ * // Result preserves Button, Checkbox order from existing markdown, adds Input at the end
+ * ```
+ */
+export declare function mergeMetadataMarkdown(existingMarkdown: string | undefined, newMetadata: PagesMetadata, options?: MergeMetadataMarkdownOptions): Promise<string>;