@mui/internal-docs-infra 0.1.1-canary.8 → 0.2.0-alpha.1

package/esm/pipeline/loaderUtils/resolveModulePathWithFs.d.ts

@@ -0,0 +1,47 @@
+import { type DirectoryEntry, type DirectoryReader, type ResolveModulePathOptions, type TypeAwareResolveResult } from "./resolveModulePath.js";
+/**
+ * Resolves a module path using Node.js filesystem APIs.
+ * This is a convenience wrapper around the generic resolveModulePath function.
+ *
+ * @param modulePath - The module path to resolve (without file extension)
+ * @param options - Configuration options
+ * @param includeTypeDefs - If true, returns both import and typeImport paths with different extension priorities
+ * @returns Promise<string | TypeAwareResolveResult> - The resolved file path(s), or throws if not found
+ */
+export declare function resolveModulePathWithFs(modulePath: string, options?: ResolveModulePathOptions): Promise<string>;
+export declare function resolveModulePathWithFs(modulePath: string, options: ResolveModulePathOptions, includeTypeDefs: true): Promise<TypeAwareResolveResult>;
+/**
+ * Resolves multiple module paths using Node.js filesystem APIs.
+ * This is a convenience wrapper around the generic resolveModulePaths function.
+ *
+ * @param modulePaths - Array of module paths to resolve (without file extensions)
+ * @param options - Configuration options
+ * @returns Promise<Map<string, string>> - Map from input path to resolved file path
+ */
+export declare function resolveModulePathsWithFs(modulePaths: string[], options?: ResolveModulePathOptions): Promise<Map<string, string>>;
+/**
+ * Resolves import result by separating JavaScript modules from static assets,
+ * only resolving JavaScript modules and returning a combined map.
+ * This is a convenience wrapper around the generic resolveImportResult function
+ * that uses Node.js filesystem APIs.
+ *
+ * @param importResult - The result from parseImports containing all imports
+ * @param options - Configuration options for module resolution
+ * @returns Promise<Map<string, string>> - Map from import path to resolved file path
+ */
+export declare function resolveImportResultWithFs(importResult: Record<string, {
+  path: string;
+  names: string[];
+  includeTypeDefs?: true;
+}>, options?: ResolveModulePathOptions): Promise<Map<string, string>>;
+/**
+ * Resolves variant paths from a variants object mapping variant names to their file paths.
+ * This is a convenience wrapper around the generic resolveVariantPaths function
+ * that uses Node.js filesystem APIs.
+ *
+ * @param variants - Object mapping variant names to their file paths
+ * @param options - Configuration options for module resolution
+ * @returns Promise<Map<string, string>> - Map from variant name to resolved file URL
+ */
+export declare function resolveVariantPathsWithFs(variants: Record<string, string>, options?: ResolveModulePathOptions): Promise<Map<string, string>>;
+export type { DirectoryEntry, DirectoryReader, ResolveModulePathOptions };

package/esm/pipeline/loaderUtils/resolveModulePathWithFs.js

@@ -0,0 +1,150 @@
+import _regenerator from "@babel/runtime/helpers/esm/regenerator";
+import _asyncToGenerator from "@babel/runtime/helpers/esm/asyncToGenerator";
+// webpack does not like node: imports
+// eslint-disable-next-line n/prefer-node-protocol
+import { readdir } from 'fs/promises';
+import { resolveModulePath, resolveModulePaths, resolveImportResult, resolveVariantPaths } from "./resolveModulePath.js";
+
+/**
+ * Node.js filesystem-based directory reader that converts Dirent objects
+ * to the DirectoryEntry interface expected by the resolver functions.
+ */
+var nodeDirectoryReader = /*#__PURE__*/function () {
+  var _ref = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee(path) {
+    var entries;
+    return _regenerator().w(function (_context) {
+      while (1) switch (_context.n) {
+        case 0:
+          _context.n = 1;
+          return readdir(path, {
+            withFileTypes: true
+          });
+        case 1:
+          entries = _context.v;
+          return _context.a(2, entries.map(function (entry) {
+            return {
+              name: entry.name,
+              isFile: entry.isFile(),
+              isDirectory: entry.isDirectory()
+            };
+          }));
+      }
+    }, _callee);
+  }));
+  return function nodeDirectoryReader(_x) {
+    return _ref.apply(this, arguments);
+  };
+}();
+
+/**
+ * Resolves a module path using Node.js filesystem APIs.
+ * This is a convenience wrapper around the generic resolveModulePath function.
+ *
+ * @param modulePath - The module path to resolve (without file extension)
+ * @param options - Configuration options
+ * @param includeTypeDefs - If true, returns both import and typeImport paths with different extension priorities
+ * @returns Promise<string | TypeAwareResolveResult> - The resolved file path(s), or throws if not found
+ */
+
+export function resolveModulePathWithFs(_x2) {
+  return _resolveModulePathWithFs.apply(this, arguments);
+}
+
+/**
+ * Resolves multiple module paths using Node.js filesystem APIs.
+ * This is a convenience wrapper around the generic resolveModulePaths function.
+ *
+ * @param modulePaths - Array of module paths to resolve (without file extensions)
+ * @param options - Configuration options
+ * @returns Promise<Map<string, string>> - Map from input path to resolved file path
+ */
+function _resolveModulePathWithFs() {
+  _resolveModulePathWithFs = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee2(modulePath) {
+    var options,
+      includeTypeDefs,
+      _args2 = arguments;
+    return _regenerator().w(function (_context2) {
+      while (1) switch (_context2.n) {
+        case 0:
+          options = _args2.length > 1 && _args2[1] !== undefined ? _args2[1] : {};
+          includeTypeDefs = _args2.length > 2 ? _args2[2] : undefined;
+          return _context2.a(2, resolveModulePath(modulePath, nodeDirectoryReader, options, includeTypeDefs));
+      }
+    }, _callee2);
+  }));
+  return _resolveModulePathWithFs.apply(this, arguments);
+}
+export function resolveModulePathsWithFs(_x3) {
+  return _resolveModulePathsWithFs.apply(this, arguments);
+}
+
+/**
+ * Resolves import result by separating JavaScript modules from static assets,
+ * only resolving JavaScript modules and returning a combined map.
+ * This is a convenience wrapper around the generic resolveImportResult function
+ * that uses Node.js filesystem APIs.
+ *
+ * @param importResult - The result from parseImports containing all imports
+ * @param options - Configuration options for module resolution
+ * @returns Promise<Map<string, string>> - Map from import path to resolved file path
+ */
+function _resolveModulePathsWithFs() {
+  _resolveModulePathsWithFs = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee3(modulePaths) {
+    var options,
+      _args3 = arguments;
+    return _regenerator().w(function (_context3) {
+      while (1) switch (_context3.n) {
+        case 0:
+          options = _args3.length > 1 && _args3[1] !== undefined ? _args3[1] : {};
+          return _context3.a(2, resolveModulePaths(modulePaths, nodeDirectoryReader, options));
+      }
+    }, _callee3);
+  }));
+  return _resolveModulePathsWithFs.apply(this, arguments);
+}
+export function resolveImportResultWithFs(_x4) {
+  return _resolveImportResultWithFs.apply(this, arguments);
+}
+
+/**
+ * Resolves variant paths from a variants object mapping variant names to their file paths.
+ * This is a convenience wrapper around the generic resolveVariantPaths function
+ * that uses Node.js filesystem APIs.
+ *
+ * @param variants - Object mapping variant names to their file paths
+ * @param options - Configuration options for module resolution
+ * @returns Promise<Map<string, string>> - Map from variant name to resolved file URL
+ */
+function _resolveImportResultWithFs() {
+  _resolveImportResultWithFs = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee4(importResult) {
+    var options,
+      _args4 = arguments;
+    return _regenerator().w(function (_context4) {
+      while (1) switch (_context4.n) {
+        case 0:
+          options = _args4.length > 1 && _args4[1] !== undefined ? _args4[1] : {};
+          return _context4.a(2, resolveImportResult(importResult, nodeDirectoryReader, options));
+      }
+    }, _callee4);
+  }));
+  return _resolveImportResultWithFs.apply(this, arguments);
+}
+export function resolveVariantPathsWithFs(_x5) {
+  return _resolveVariantPathsWithFs.apply(this, arguments);
+}
+
+// Re-export types for convenience
+function _resolveVariantPathsWithFs() {
+  _resolveVariantPathsWithFs = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee5(variants) {
+    var options,
+      _args5 = arguments;
+    return _regenerator().w(function (_context5) {
+      while (1) switch (_context5.n) {
+        case 0:
+          options = _args5.length > 1 && _args5[1] !== undefined ? _args5[1] : {};
+          return _context5.a(2, resolveVariantPaths(variants, nodeDirectoryReader, options));
+      }
+    }, _callee5);
+  }));
+  return _resolveVariantPathsWithFs.apply(this, arguments);
+}

package/esm/pipeline/loaderUtils/rewriteImports.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Rewrites relative imports in source code based on a provided mapping.
+ * Converts imports like '../utils/helper' or './components/Button' to their mapped equivalents
+ *
+ * @param source - The source code to process
+ * @param importPathMapping - Map from original import paths to new import paths (without extensions)
+ * @returns The source code with rewritten imports
+ */
+export declare function rewriteImportsToSameDirectory(source: string, importPathMapping: Map<string, string>): string;

package/esm/pipeline/loaderUtils/rewriteImports.js

@@ -0,0 +1,35 @@
+/**
+ * Rewrites relative imports in source code based on a provided mapping.
+ * Converts imports like '../utils/helper' or './components/Button' to their mapped equivalents
+ *
+ * @param source - The source code to process
+ * @param importPathMapping - Map from original import paths to new import paths (without extensions)
+ * @returns The source code with rewritten imports
+ */
+export function rewriteImportsToSameDirectory(source, importPathMapping) {
+  // Handle both types of imports:
+  // 1. import [something] from 'path' (including import type)
+  // 2. import 'path' (side-effect imports like CSS)
+
+  return source.replace(/import\s+((?:type\s+)?(?:\w+|\*\s+as\s+\w+|{[^}]+})\s+from\s+)['"]([^'"]+)['"]/g, function (match, importPart, modulePath) {
+    // Only process relative imports
+    if (modulePath.startsWith('.')) {
+      // Check if we have a mapping for this import path
+      if (importPathMapping.has(modulePath)) {
+        var newPath = importPathMapping.get(modulePath);
+        return "import ".concat(importPart, "'").concat(newPath, "'");
+      }
+    }
+    return match;
+  }).replace(/import\s+['"]([^'"]+)['"]/g, function (match, modulePath) {
+    // Only process relative imports
+    if (modulePath.startsWith('.')) {
+      // Check if we have a mapping for this import path
+      if (importPathMapping.has(modulePath)) {
+        var newPath = importPathMapping.get(modulePath);
+        return "import '".concat(newPath, "'");
+      }
+    }
+    return match;
+  });
+}

package/esm/pipeline/parseSource/addLineGutters.d.ts

@@ -0,0 +1,9 @@
+import type { Root } from 'hast';
+/**
+ * Counts the number of lines in a HAST tree without mutating it.
+ * Uses the same logic as starryNightGutter but only returns the count.
+ * @param tree - The HAST tree to count lines in
+ * @returns The number of lines in the tree
+ */
+export declare function countLines(tree: Root): number;
+export declare function starryNightGutter(tree: Root, sourceLines?: string[], frameSize?: number): void;

package/esm/pipeline/parseSource/addLineGutters.js

@@ -0,0 +1,181 @@
+import _createForOfIteratorHelper from "@babel/runtime/helpers/esm/createForOfIteratorHelper";
+// Example copied from https://github.com/wooorm/starry-night#example-adding-line-numbers
+
+/**
+ * Counts the number of lines in a HAST tree without mutating it.
+ * Uses the same logic as starryNightGutter but only returns the count.
+ * @param tree - The HAST tree to count lines in
+ * @returns The number of lines in the tree
+ */
+export function countLines(tree) {
+  var search = /\r?\n|\r/g;
+  var index = -1;
+  var start = 0;
+  var startTextRemainder = '';
+  var lineNumber = 0;
+  while (index + 1 < tree.children.length) {
+    index += 1;
+    var child = tree.children[index];
+    if (child.type === 'text') {
+      var textStart = 0;
+      var match = search.exec(child.value);
+      while (match) {
+        lineNumber += 1;
+        start = index + 1;
+        textStart = match.index + match[0].length;
+        match = search.exec(child.value);
+      }
+
+      // If we matched, make sure to not drop the text after the last line ending.
+      if (start === index + 1) {
+        startTextRemainder = child.value.slice(textStart);
+      }
+    }
+  }
+
+  // Check if we have remaining content to process as a line
+  if (start < tree.children.length || startTextRemainder) {
+    lineNumber += 1;
+  }
+  return lineNumber;
+}
+export function starryNightGutter(tree, sourceLines) {
+  var frameSize = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 120;
+  /** @type {Array<RootContent>} */
+  var replacement = [];
+  var search = /\r?\n|\r/g;
+  var index = -1;
+  var start = 0;
+  var startTextRemainder = '';
+  var lineNumber = 0;
+  var frameLines = [];
+  var frameStartLine = 1; // Track the starting line number for the current frame
+
+  while (index + 1 < tree.children.length) {
+    index += 1;
+    var child = tree.children[index];
+    if (child.type === 'text') {
+      var textStart = 0;
+      var match = search.exec(child.value);
+      while (match) {
+        // Nodes in this line.
+        var _line = tree.children.slice(start, index);
+
+        // Prepend text from a partial matched earlier text.
+        if (startTextRemainder) {
+          _line.unshift({
+            type: 'text',
+            value: startTextRemainder
+          });
+          startTextRemainder = '';
+        }
+
+        // Append text from this text.
+        if (match.index > textStart) {
+          _line.push({
+            type: 'text',
+            value: child.value.slice(textStart, match.index)
+          });
+        }
+
+        // Add a line, and the eol.
+        lineNumber += 1;
+        frameLines.push(createLine(_line, lineNumber), {
+          type: 'text',
+          value: match[0]
+        });
+
+        // Check if we need to create a frame (only if sourceLines provided, otherwise keep everything in one frame)
+        if (sourceLines && lineNumber % frameSize === 0) {
+          replacement.push(createFrame(frameLines, sourceLines, frameStartLine, lineNumber));
+          frameLines = [];
+          frameStartLine = lineNumber + 1;
+        }
+        start = index + 1;
+        textStart = match.index + match[0].length;
+        match = search.exec(child.value);
+      }
+
+      // If we matched, make sure to not drop the text after the last line ending.
+      if (start === index + 1) {
+        startTextRemainder = child.value.slice(textStart);
+      }
+    }
+  }
+  var line = tree.children.slice(start);
+  // Prepend text from a partial matched earlier text.
+  if (startTextRemainder) {
+    line.unshift({
+      type: 'text',
+      value: startTextRemainder
+    });
+    startTextRemainder = '';
+  }
+  if (line.length > 0) {
+    lineNumber += 1;
+    frameLines.push(createLine(line, lineNumber));
+  }
+
+  // Add any remaining lines as the final frame
+  if (frameLines.length > 0) {
+    replacement.push(createFrame(frameLines, sourceLines, frameStartLine, lineNumber));
+  }
+
+  // If there are multiple frames and sourceLines provided, add dataAsString to each frame
+  if (replacement.length > 1 && sourceLines) {
+    var _iterator = _createForOfIteratorHelper(replacement),
+      _step;
+    try {
+      for (_iterator.s(); !(_step = _iterator.n()).done;) {
+        var _frame$properties;
+        var frame = _step.value;
+        if (frame.type === 'element' && frame.tagName === 'span' && ((_frame$properties = frame.properties) == null ? void 0 : _frame$properties.className) === 'frame' && typeof frame.properties.frameStartLine === 'number' && typeof frame.properties.frameEndLine === 'number') {
+          var startLine = frame.properties.frameStartLine - 1; // Convert to 0-based index
+          var endLine = frame.properties.frameEndLine; // This is already inclusive
+          frame.properties.dataAsString = sourceLines.slice(startLine, endLine).join('\n');
+        }
+      }
+    } catch (err) {
+      _iterator.e(err);
+    } finally {
+      _iterator.f();
+    }
+  }
+
+  // Replace children with new array.
+  tree.children = replacement;
+
+  // Add total line count to root data
+  if (!tree.data) {
+    tree.data = {};
+  }
+  tree.data.totalLines = lineNumber;
+}
+function createLine(children, line) {
+  return {
+    type: 'element',
+    tagName: 'span',
+    properties: {
+      className: 'line',
+      dataLn: line
+    },
+    children: children
+  };
+}
+function createFrame(frameChildren, sourceLines, startLine, endLine) {
+  var properties = {
+    className: 'frame'
+  };
+
+  // Store line range information if provided (for dataAsString generation)
+  if (sourceLines && startLine !== undefined && endLine !== undefined) {
+    properties.frameStartLine = startLine;
+    properties.frameEndLine = endLine;
+  }
+  return {
+    type: 'element',
+    tagName: 'span',
+    properties: properties,
+    children: frameChildren
+  };
+}

package/esm/pipeline/parseSource/grammars.d.ts

@@ -0,0 +1,2 @@
+export declare const grammars: import("@wooorm/starry-night").Grammar[];
+export declare const extensionMap: Record<string, string>;

package/esm/pipeline/parseSource/grammars.js

@@ -0,0 +1,27 @@
+import sourceJs from '@wooorm/starry-night/source.js';
+import sourceTs from '@wooorm/starry-night/source.ts';
+import sourceTsx from '@wooorm/starry-night/source.tsx';
+import sourceJson from '@wooorm/starry-night/source.json';
+import textMd from '@wooorm/starry-night/text.md';
+import sourceMdx from '@wooorm/starry-night/source.mdx';
+import textHtmlBasic from '@wooorm/starry-night/text.html.basic';
+import sourceCss from '@wooorm/starry-night/source.css';
+import sourceShell from '@wooorm/starry-night/source.shell';
+import sourceYaml from '@wooorm/starry-night/source.yaml';
+export var grammars = [sourceJs, sourceTs, sourceTsx, sourceJson, textMd, sourceMdx,
+// needs sourceTsx
+textHtmlBasic, sourceCss, sourceShell, sourceYaml];
+export var extensionMap = {
+  '.js': 'source.js',
+  '.ts': 'source.ts',
+  '.jsx': 'source.tsx',
+  // TODO: is there a JSX grammar?
+  '.tsx': 'source.tsx',
+  '.json': 'source.json',
+  '.md': 'text.md',
+  '.mdx': 'source.mdx',
+  '.html': 'text.html.basic',
+  '.css': 'source.css',
+  '.sh': 'source.shell',
+  '.yaml': 'source.yaml'
+};

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

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

package/esm/pipeline/parseSource/index.js

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

package/esm/pipeline/parseSource/parseSource.d.ts

@@ -0,0 +1,3 @@
+import type { ParseSource } from "../../CodeHighlighter/types.js";
+export declare const parseSource: ParseSource;
+export declare const createParseSource: () => Promise<ParseSource>;

package/esm/pipeline/parseSource/parseSource.js

@@ -0,0 +1,51 @@
+import _regenerator from "@babel/runtime/helpers/esm/regenerator";
+import _asyncToGenerator from "@babel/runtime/helpers/esm/asyncToGenerator";
+import { createStarryNight } from '@wooorm/starry-night';
+import { grammars, extensionMap } from "./grammars.js";
+import { starryNightGutter } from "./addLineGutters.js";
+var STARRY_NIGHT_KEY = '__docs_infra_starry_night_instance__';
+export var parseSource = function parseSource(source, fileName) {
+  var starryNight = globalThis[STARRY_NIGHT_KEY];
+  if (!starryNight) {
+    throw new Error('Starry Night not initialized. Use createParseSource to create an initialized parseSource function.');
+  }
+  var fileType = fileName.slice(fileName.lastIndexOf('.'));
+  if (!extensionMap[fileType]) {
+    // Return a basic HAST root node with the source text for unsupported file types
+    // TODO: should we split and add line gutters?
+    return {
+      type: 'root',
+      children: [{
+        type: 'text',
+        value: source
+      }]
+    };
+  }
+  var highlighted = starryNight.highlight(source, extensionMap[fileType]);
+  var sourceLines = source.split(/\r?\n|\r/);
+  starryNightGutter(highlighted, sourceLines); // mutates the tree to add line gutters
+
+  return highlighted;
+};
+export var createParseSource = /*#__PURE__*/function () {
+  var _ref = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee() {
+    return _regenerator().w(function (_context) {
+      while (1) switch (_context.n) {
+        case 0:
+          if (globalThis[STARRY_NIGHT_KEY]) {
+            _context.n = 2;
+            break;
+          }
+          _context.n = 1;
+          return createStarryNight(grammars);
+        case 1:
+          globalThis[STARRY_NIGHT_KEY] = _context.v;
+        case 2:
+          return _context.a(2, parseSource);
+      }
+    }, _callee);
+  }));
+  return function createParseSource() {
+    return _ref.apply(this, arguments);
+  };
+}();

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

@@ -0,0 +1,2 @@
+import { transformHtmlCode } from "./transformHtmlCode.js";
+export default transformHtmlCode;

package/esm/pipeline/transformHtmlCode/index.js

@@ -0,0 +1,4 @@
+// This is the export format expected by a remark plugin.
+
+import { transformHtmlCode } from "./transformHtmlCode.js";
+export default transformHtmlCode;

package/esm/pipeline/transformHtmlCode/transformHtmlCode.d.ts

@@ -0,0 +1,13 @@
+import type { Plugin } from 'unified';
+/**
+ * Rehype plugin that transforms pre > code elements to use loadVariant
+ *
+ * This plugin:
+ * 1. Finds pre elements in the HTML AST
+ * 2. Collects all code children within each pre element
+ * 3. Creates variants from multiple code elements or single Default variant
+ * 4. Uses loadVariant to process each variant
+ * 5. Stores the combined precompute data on the pre element
+ * 6. Clears all code element contents
+ */
+export declare const transformHtmlCode: Plugin;