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

package/esm/pipeline/loadServerPageIndex/loadServerPageIndex.d.ts

@@ -0,0 +1,51 @@
+import type { HeadingHierarchy } from "../transformMarkdownMetadata/types.js";
+import type { SitemapSection, SitemapSectionData } from "../../createSitemap/types.js";
+/**
+ * Options for creating a loadServerPageIndex function
+ */
+export interface CreateLoadServerPageIndexOptions {
+  /**
+   * The root context directory for resolving relative paths.
+   * Defaults to process.cwd().
+   */
+  rootContext?: string;
+}
+/**
+ * Function type for loading page index data from a markdown file
+ */
+export type LoadServerPageIndex = (filePath: string) => Promise<SitemapSectionData | null>;
+/**
+ * Converts a path segment to a title
+ * e.g., "docs-infra" -> "Docs Infra", "components" -> "Components"
+ */
+export declare function pathSegmentToTitle(segment: string): string;
+/**
+ * Recursively removes titleMarkdown fields from a heading hierarchy
+ */
+export declare function stripTitleMarkdown(hierarchy: HeadingHierarchy): Record<string, SitemapSection>;
+/**
+ * Extracts prefix and title from an import path
+ * e.g., "/path/to/app/docs-infra/components/page.mdx" -> { prefix: "/docs-infra/components/", title: "Docs Infra Components" }
+ */
+export declare function extractPrefixAndTitle(absolutePath: string, rootContext: string): {
+  prefix: string;
+  title: string;
+};
+/**
+ * Default loadServerPageIndex function that loads page index data from a markdown file.
+ * This function uses process.cwd() as the root context for resolving relative paths.
+ */
+export declare const loadServerPageIndex: LoadServerPageIndex;
+/**
+ * Creates a loadServerPageIndex function with custom options.
+ *
+ * This factory function creates a LoadServerPageIndex implementation that:
+ * 1. Reads the markdown file from the provided file path
+ * 2. Parses the markdown to extract metadata using markdownToMetadata
+ * 3. Enriches the metadata with prefix and title derived from the file path
+ * 4. Returns a SitemapSectionData object with page data
+ *
+ * @param options - Configuration options for the loader
+ * @returns LoadServerPageIndex function that takes a file path and returns Promise<SitemapSectionData | null>
+ */
+export declare function createLoadServerPageIndex(options?: CreateLoadServerPageIndexOptions): LoadServerPageIndex;

package/esm/pipeline/loadServerPageIndex/loadServerPageIndex.js

@@ -0,0 +1,174 @@
+import _regenerator from "@babel/runtime/helpers/esm/regenerator";
+import _asyncToGenerator from "@babel/runtime/helpers/esm/asyncToGenerator";
+import _extends from "@babel/runtime/helpers/esm/extends";
+import _objectWithoutPropertiesLoose from "@babel/runtime/helpers/esm/objectWithoutPropertiesLoose";
+import _typeof from "@babel/runtime/helpers/esm/typeof";
+import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
+var _excluded = ["titleMarkdown", "children"],
+  _excluded2 = ["descriptionMarkdown", "sections"];
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { markdownToMetadata } from "../syncPageIndex/metadataToMarkdown.js";
+
+/**
+ * Options for creating a loadServerPageIndex function
+ */
+
+/**
+ * Function type for loading page index data from a markdown file
+ */
+
+/**
+ * Converts a path segment to a title
+ * e.g., "docs-infra" -> "Docs Infra", "components" -> "Components"
+ */
+export function pathSegmentToTitle(segment) {
+  return segment.split('-').map(function (word) {
+    return word.charAt(0).toUpperCase() + word.slice(1);
+  }).join(' ');
+}
+
+/**
+ * Recursively removes titleMarkdown fields from a heading hierarchy
+ */
+export function stripTitleMarkdown(hierarchy) {
+  var result = {};
+  for (var _i = 0, _Object$entries = Object.entries(hierarchy); _i < _Object$entries.length; _i++) {
+    var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+      key = _Object$entries$_i[0],
+      value = _Object$entries$_i[1];
+    if (_typeof(value) === 'object' && value !== null) {
+      var titleMarkdown = value.titleMarkdown,
+        children = value.children,
+        rest = _objectWithoutPropertiesLoose(value, _excluded);
+      var strippedChildren = children ? stripTitleMarkdown(children) : {};
+      result[key] = _extends(_extends({}, rest), {}, {
+        // Only include children if it has keys, otherwise set to undefined
+        children: Object.keys(strippedChildren).length > 0 ? strippedChildren : undefined
+      });
+    }
+  }
+  return result;
+}
+
+/**
+ * Extracts prefix and title from an import path
+ * e.g., "/path/to/app/docs-infra/components/page.mdx" -> { prefix: "/docs-infra/components/", title: "Docs Infra Components" }
+ */
+export function extractPrefixAndTitle(absolutePath, rootContext) {
+  // Get the relative path from the root context
+  var relativePath = path.relative(rootContext, absolutePath);
+
+  // Extract the directory path (remove filename)
+  var dirPath = path.dirname(relativePath);
+
+  // Split into segments
+  var allSegments = dirPath.split(path.sep);
+
+  // Filter out segments:
+  // - Remove leading 'src' and 'app' directory markers (only if they're at the start)
+  // - Remove Next.js route groups (segments in parentheses like '(public)')
+  // - Remove current directory markers ('.' and empty strings)
+  var segments = allSegments.filter(function (seg, index) {
+    // Remove 'src' only if it's the first segment
+    if (seg === 'src' && index === 0) {
+      return false;
+    }
+    // Remove 'app' only if it's the first or second segment (after 'src')
+    if (seg === 'app' && (index === 0 || index === 1 && allSegments[0] === 'src')) {
+      return false;
+    }
+    // Filter out Next.js route groups (e.g., '(public)', '(content)')
+    if (seg.startsWith('(') && seg.endsWith(')')) {
+      return false;
+    }
+    // Filter out current directory markers
+    if (seg === '.' || seg === '') {
+      return false;
+    }
+    return true;
+  });
+
+  // Generate prefix with leading and trailing slashes
+  var prefix = segments.length > 0 ? "/".concat(segments.join('/'), "/") : '/';
+
+  // Generate title from path segments
+  var title = segments.map(pathSegmentToTitle).join(' ');
+  return {
+    prefix: prefix,
+    title: title
+  };
+}
+
+/**
+ * Default loadServerPageIndex function that loads page index data from a markdown file.
+ * This function uses process.cwd() as the root context for resolving relative paths.
+ */
+export var loadServerPageIndex = createLoadServerPageIndex();
+
+/**
+ * Creates a loadServerPageIndex function with custom options.
+ *
+ * This factory function creates a LoadServerPageIndex implementation that:
+ * 1. Reads the markdown file from the provided file path
+ * 2. Parses the markdown to extract metadata using markdownToMetadata
+ * 3. Enriches the metadata with prefix and title derived from the file path
+ * 4. Returns a SitemapSectionData object with page data
+ *
+ * @param options - Configuration options for the loader
+ * @returns LoadServerPageIndex function that takes a file path and returns Promise<SitemapSectionData | null>
+ */
+export function createLoadServerPageIndex() {
+  var _options$rootContext;
+  var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  var rootContext = (_options$rootContext = options.rootContext) != null ? _options$rootContext : process.cwd();
+  return /*#__PURE__*/function () {
+    var _loadPageIndex = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee(filePath) {
+      var absolutePath, _extractPrefixAndTitl, prefix, generatedTitle, markdownContent, metadata, enrichedMetadata;
+      return _regenerator().w(function (_context) {
+        while (1) switch (_context.n) {
+          case 0:
+            // Resolve the absolute path to the markdown file
+            absolutePath = filePath.startsWith('file://') ? filePath.slice(7) : filePath; // Extract prefix and title from the import path
+            _extractPrefixAndTitl = extractPrefixAndTitle(absolutePath, rootContext), prefix = _extractPrefixAndTitl.prefix, generatedTitle = _extractPrefixAndTitl.title; // Read the markdown file
+            _context.n = 1;
+            return fs.readFile(absolutePath, 'utf-8');
+          case 1:
+            markdownContent = _context.v;
+            _context.n = 2;
+            return markdownToMetadata(markdownContent);
+          case 2:
+            metadata = _context.v;
+            if (metadata) {
+              _context.n = 3;
+              break;
+            }
+            return _context.a(2, null);
+          case 3:
+            // Add prefix and override title with the generated one from the path
+            // Strip descriptionMarkdown and titleMarkdown to reduce bundle size
+            enrichedMetadata = _extends(_extends({}, metadata), {}, {
+              prefix: prefix,
+              // Use the generated title from the path (override markdown's H1)
+              title: generatedTitle,
+              // Strip markdown AST fields from each page to reduce size
+              pages: metadata.pages.map(function (page) {
+                var descriptionMarkdown = page.descriptionMarkdown,
+                  sections = page.sections,
+                  pageWithoutMarkdown = _objectWithoutPropertiesLoose(page, _excluded2);
+                return _extends(_extends({}, pageWithoutMarkdown), {}, {
+                  // Strip titleMarkdown from sections hierarchy
+                  sections: sections ? stripTitleMarkdown(sections) : undefined
+                });
+              })
+            });
+            return _context.a(2, enrichedMetadata);
+        }
+      }, _callee);
+    }));
+    function loadPageIndex(_x) {
+      return _loadPageIndex.apply(this, arguments);
+    }
+    return loadPageIndex;
+  }();
+}

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

@@ -0,0 +1,2 @@
+export { loadServerSitemap, createLoadServerSitemap, createSitemapSchema } from "./loadServerSitemap.js";
+export type { CreateLoadServerSitemapOptions, LoadServerSitemap } from "./loadServerSitemap.js";

package/esm/pipeline/loadServerSitemap/index.js

@@ -0,0 +1 @@
+export { loadServerSitemap, createLoadServerSitemap, createSitemapSchema } from "./loadServerSitemap.js";

package/esm/pipeline/loadServerSitemap/loadServerSitemap.d.ts

@@ -0,0 +1,39 @@
+import type { Sitemap } from "../../createSitemap/types.js";
+/**
+ * Options for creating a loadServerSitemap function
+ */
+export interface CreateLoadServerSitemapOptions {
+  /**
+   * The root context directory for resolving relative paths.
+   * Defaults to the directory containing the sitemap index file.
+   */
+  rootContext?: string;
+}
+/**
+ * Function type for loading sitemap data from a sitemap index file URL
+ */
+export type LoadServerSitemap = (url: string) => Promise<Sitemap>;
+/**
+ * Creates the default Orama schema for search indexing.
+ * See: https://docs.orama.com/docs/orama-js/usage/create#schema-properties-and-types
+ */
+export declare function createSitemapSchema(): Sitemap['schema'];
+/**
+ * Default loadServerSitemap function that loads sitemap data from a sitemap index file.
+ * This function parses the sitemap index file to find createSitemap calls and resolves
+ * the page index paths from the imports.
+ */
+export declare const loadServerSitemap: LoadServerSitemap;
+/**
+ * Creates a loadServerSitemap function with custom options.
+ *
+ * This factory function creates a LoadServerSitemap implementation that:
+ * 1. Parses the sitemap index file to find createSitemap calls with page imports
+ * 2. Resolves all page index paths from the imports
+ * 3. Loads each page index using loadServerPageIndex
+ * 4. Returns a Sitemap object with schema and page data
+ *
+ * @param options - Configuration options for the loader
+ * @returns LoadServerSitemap function that takes a file URL and returns Promise<Sitemap>
+ */
+export declare function createLoadServerSitemap(options?: CreateLoadServerSitemapOptions): LoadServerSitemap;

package/esm/pipeline/loadServerSitemap/loadServerSitemap.js

@@ -0,0 +1,168 @@
+import _createForOfIteratorHelper from "@babel/runtime/helpers/esm/createForOfIteratorHelper";
+import _regenerator from "@babel/runtime/helpers/esm/regenerator";
+import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
+import _asyncToGenerator from "@babel/runtime/helpers/esm/asyncToGenerator";
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createLoadServerPageIndex } from "../loadServerPageIndex/loadServerPageIndex.js";
+import { parseCreateFactoryCall } from "../loadPrecomputedCodeHighlighter/parseCreateFactoryCall.js";
+
+/**
+ * Options for creating a loadServerSitemap function
+ */
+
+/**
+ * Function type for loading sitemap data from a sitemap index file URL
+ */
+
+/**
+ * Creates the default Orama schema for search indexing.
+ * See: https://docs.orama.com/docs/orama-js/usage/create#schema-properties-and-types
+ */
+export function createSitemapSchema() {
+  return {
+    slug: 'string',
+    path: 'string',
+    title: 'string',
+    description: 'string',
+    sections: 'string[]',
+    subsections: 'string[]',
+    keywords: 'string[]'
+  };
+}
+
+/**
+ * Default loadServerSitemap function that loads sitemap data from a sitemap index file.
+ * This function parses the sitemap index file to find createSitemap calls and resolves
+ * the page index paths from the imports.
+ */
+export var loadServerSitemap = createLoadServerSitemap();
+
+/**
+ * Creates a loadServerSitemap function with custom options.
+ *
+ * This factory function creates a LoadServerSitemap implementation that:
+ * 1. Parses the sitemap index file to find createSitemap calls with page imports
+ * 2. Resolves all page index paths from the imports
+ * 3. Loads each page index using loadServerPageIndex
+ * 4. Returns a Sitemap object with schema and page data
+ *
+ * @param options - Configuration options for the loader
+ * @returns LoadServerSitemap function that takes a file URL and returns Promise<Sitemap>
+ */
+export function createLoadServerSitemap() {
+  var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  return /*#__PURE__*/function () {
+    var _loadSitemap = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee2(url) {
+      var _options$rootContext;
+      var filePath, rootContext, loadPageIndex, source, sitemapCall, entries, results, sitemapData, errors, _iterator, _step, result, errorMessages;
+      return _regenerator().w(function (_context2) {
+        while (1) switch (_context2.n) {
+          case 0:
+            // Remove file:// prefix if present to get file path
+            filePath = url.startsWith('file://') ? url.slice(7) : url; // Determine root context from file path if not provided
+            rootContext = (_options$rootContext = options.rootContext) != null ? _options$rootContext : path.dirname(filePath); // Create page index loader with root context
+            loadPageIndex = createLoadServerPageIndex({
+              rootContext: rootContext
+            }); // Read the source file to find createSitemap calls
+            _context2.n = 1;
+            return readFile(filePath, 'utf-8');
+          case 1:
+            source = _context2.v;
+            _context2.n = 2;
+            return parseCreateFactoryCall(source, filePath);
+          case 2:
+            sitemapCall = _context2.v;
+            if (!(!sitemapCall || !sitemapCall.variants)) {
+              _context2.n = 3;
+              break;
+            }
+            return _context2.a(2, {
+              schema: createSitemapSchema(),
+              data: {}
+            });
+          case 3:
+            // Process all page index files in parallel
+            entries = Object.entries(sitemapCall.variants);
+            _context2.n = 4;
+            return Promise.all(entries.map(/*#__PURE__*/function () {
+              var _ref2 = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee(_ref) {
+                var _ref3, key, importPath, metadata, _t;
+                return _regenerator().w(function (_context) {
+                  while (1) switch (_context.p = _context.n) {
+                    case 0:
+                      _ref3 = _slicedToArray(_ref, 2), key = _ref3[0], importPath = _ref3[1];
+                      _context.p = 1;
+                      _context.n = 2;
+                      return loadPageIndex(importPath);
+                    case 2:
+                      metadata = _context.v;
+                      return _context.a(2, {
+                        key: key,
+                        metadata: metadata,
+                        error: null
+                      });
+                    case 3:
+                      _context.p = 3;
+                      _t = _context.v;
+                      return _context.a(2, {
+                        key: key,
+                        metadata: null,
+                        error: _t instanceof Error ? _t : new Error(String(_t))
+                      });
+                  }
+                }, _callee, null, [[1, 3]]);
+              }));
+              return function (_x2) {
+                return _ref2.apply(this, arguments);
+              };
+            }()));
+          case 4:
+            results = _context2.v;
+            // Collect results and errors
+            sitemapData = {};
+            errors = [];
+            _iterator = _createForOfIteratorHelper(results);
+            try {
+              for (_iterator.s(); !(_step = _iterator.n()).done;) {
+                result = _step.value;
+                if (result.error) {
+                  errors.push({
+                    key: result.key,
+                    error: result.error
+                  });
+                } else if (result.metadata) {
+                  sitemapData[result.key] = result.metadata;
+                }
+              }
+
+              // Throw if any pages failed to load
+            } catch (err) {
+              _iterator.e(err);
+            } finally {
+              _iterator.f();
+            }
+            if (!(errors.length > 0)) {
+              _context2.n = 5;
+              break;
+            }
+            errorMessages = errors.map(function (_ref4) {
+              var key = _ref4.key,
+                error = _ref4.error;
+              return "  ".concat(key, ": ").concat(error.message);
+            }).join('\n');
+            throw new Error("Failed to load ".concat(errors.length, " page index(es):\n").concat(errorMessages));
+          case 5:
+            return _context2.a(2, {
+              schema: createSitemapSchema(),
+              data: sitemapData
+            });
+        }
+      }, _callee2);
+    }));
+    function loadSitemap(_x) {
+      return _loadSitemap.apply(this, arguments);
+    }
+    return loadSitemap;
+  }();
+}

package/esm/pipeline/loadServerSource/loadServerSource.js

@@ -6,7 +6,7 @@ import _asyncToGenerator from "@babel/runtime/helpers/esm/asyncToGenerator";
 // eslint-disable-next-line n/prefer-node-protocol
 import { readFile } from 'fs/promises';
 import { parseImportsAndComments } from "../loaderUtils/index.js";
-import { resolveImportResultWithFs } from "../loaderUtils/resolveModulePathWithFs.js";
+import { resolveImportResultWithFs } from "../loadServerCodeMeta/resolveModulePathWithFs.js";
 import { processRelativeImports } from "../loaderUtils/processRelativeImports.js";
 import { isJavaScriptModule } from "../loaderUtils/resolveModulePath.js";
 /**

package/esm/pipeline/loaderUtils/externalsToPackages.js

@@ -21,7 +21,7 @@ export function externalsToPackages(externals) {
  * - 'react' -> 'react'
  * - 'react-dom' -> 'react-dom'
  * - '@mui/internal-docs-infra/CodeHighlighter' -> '@mui/internal-docs-infra'
- * - '@mui/internal-docs-infra/parseSource' -> '@mui/internal-docs-infra'
+ * - '@mui/internal-docs-infra/pipeline/parseSource' -> '@mui/internal-docs-infra'
  * - 'lodash/get' -> 'lodash'
  * - 'some-package/submodule/deep' -> 'some-package'
  */

package/esm/pipeline/loaderUtils/processRelativeImports.js

@@ -36,8 +36,13 @@ function processFlatMode(importResult, resolvedPathsMap) {
     var file = _fileMapping[_i];
     var fileName = file.segments[file.segments.length - 1];
     var isIndexFile = fileName.startsWith('index.');
+    var isUnderscoreIndexFile = fileName.startsWith('_index.');
     var candidateName = void 0;
-    if (isIndexFile) {
+    if (isUnderscoreIndexFile) {
+      // Files starting with "_index." should be treated as direct index imports
+      // e.g., "../../dir/_index.module.css" -> "index.module.css"
+      candidateName = "index".concat(file.extension);
+    } else if (isIndexFile) {
       // Check if the original import was a direct index file (e.g., "./index.ext")
       var originalImportParts = file.originalImportPath.split('/');
       var isDirectIndexImport = originalImportParts.length === 2 && originalImportParts[0] === '.' && originalImportParts[1].startsWith('index.');
@@ -131,9 +136,13 @@ function processFlatMode(importResult, resolvedPathsMap) {
                   var _file = _step.value;
                   var _fileName = _file.segments[_file.segments.length - 1];
                   var _isIndexFile = _fileName.startsWith('index.');
+                  var _isUnderscoreIndexFile = _fileName.startsWith('_index.');
                   var distinguishingSegment = _file.segments[_distinguishingIndex];
                   var finalName = void 0;
-                  if (_isIndexFile) {
+                  if (_isUnderscoreIndexFile) {
+                    // Files starting with "_index." should always use "index" as the base name
+                    finalName = "".concat(distinguishingSegment, "/index").concat(_file.extension);
+                  } else if (_isIndexFile) {
                     // Check if this was a direct index import
                     var _originalImportParts = _file.originalImportPath.split('/');
                     var _isDirectIndexImport = _originalImportParts.length === 2 && _originalImportParts[0] === '.' && _originalImportParts[1].startsWith('index.');
@@ -202,9 +211,13 @@ function processFlatMode(importResult, resolvedPathsMap) {
           var _file2 = _step3.value;
           var _fileName2 = _file2.segments[_file2.segments.length - 1];
           var _isIndexFile2 = _fileName2.startsWith('index.');
+          var _isUnderscoreIndexFile2 = _fileName2.startsWith('_index.');
           var _distinguishingSegment = _file2.segments[distinguishingIndex];
           var _finalName = void 0;
-          if (_isIndexFile2) {
+          if (_isUnderscoreIndexFile2) {
+            // Files starting with "_index." should always use "index" as the base name
+            _finalName = "".concat(_distinguishingSegment, "/index").concat(_file2.extension);
+          } else if (_isIndexFile2) {
             // Check if this was a direct index import
             var _originalImportParts2 = _file2.originalImportPath.split('/');
             var _isDirectIndexImport2 = _originalImportParts2.length === 2 && _originalImportParts2[0] === '.' && _originalImportParts2[1].startsWith('index.');

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

@@ -1,3 +1,39 @@
+/**
+ * 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 declare function rewriteImportsToNull(source: string, importPathsToRewrite: Set<string>, importResult: Record<string, {
+  positions: Array<{
+    start: number;
+    end: number;
+  }>;
+  names: Array<{
+    name: string;
+    alias?: string;
+    type: string;
+  }>;
+}>): string;
+/**
+ * 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 declare function removeImports(source: string, importPathsToRemove: Set<string>, importResult: Record<string, {
+  positions: Array<{
+    start: number;
+    end: number;
+  }>;
+}>): string;
 /**
  * Efficiently rewrites import paths using position data.
  * This avoids regex parsing and uses precise position information for replacement.