@mui/internal-docs-infra 0.1.1-canary.9 → 0.2.0-alpha.2

package/esm/pipeline/loadServerSource/loadServerSource.js

@@ -0,0 +1,134 @@
+import _regenerator from "@babel/runtime/helpers/esm/regenerator";
+import _extends from "@babel/runtime/helpers/esm/extends";
+import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
+import _asyncToGenerator from "@babel/runtime/helpers/esm/asyncToGenerator";
+// webpack does not like node: imports
+// eslint-disable-next-line n/prefer-node-protocol
+import { readFile } from 'fs/promises';
+import { parseImports } from "../loaderUtils/index.js";
+import { resolveImportResultWithFs } from "../loaderUtils/resolveModulePathWithFs.js";
+import { processRelativeImports } from "../loaderUtils/processRelativeImports.js";
+import { isJavaScriptModule } from "../loaderUtils/resolveModulePath.js";
+/**
+ * Default loadServerSource function that reads a file and extracts its dependencies.
+ * This function is used to load source files for demos, resolving their imports and dependencies.
+ * It reads the source file, resolves its imports, and returns the processed source along with any
+ * additional files and dependencies that were found.
+ */
+export var loadServerSource = createLoadServerSource();
+
+/**
+ * Creates a loadSource function that reads a file and extracts its dependencies.
+ *
+ * @param options.storeAt - Controls how imports are stored in extraFiles:
+ *   - 'canonical': Full resolved path (e.g., '../Component/index.js')
+ *   - 'import': Import path with file extension (e.g., '../Component.js')
+ *   - 'flat': Flattened to current directory with rewritten imports (e.g., './Component.js')
+ */
+export function createLoadServerSource() {
+  var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  var _options$includeDepen = options.includeDependencies,
+    includeDependencies = _options$includeDepen === void 0 ? true : _options$includeDepen,
+    _options$storeAt = options.storeAt,
+    storeAt = _options$storeAt === void 0 ? 'flat' : _options$storeAt;
+  return /*#__PURE__*/function () {
+    var _loadSource = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee(url) {
+      var filePath, source, isJavascriptModuleFile, _yield$parseImports, importResult, externals, transformedExternals, _i, _Object$entries, _Object$entries$_i, modulePath, externalImport, relativeImportsCompatible, _i2, _Object$entries2, _Object$entries2$_i, importPath, _Object$entries2$_i$, path, names, includeTypeDefs, resolvedPathsMap, _processRelativeImpor, processedSource, extraFiles, extraDependencies;
+      return _regenerator().w(function (_context) {
+        while (1) switch (_context.n) {
+          case 0:
+            // Remove file:// prefix if present
+            filePath = url.replace('file://', ''); // Read the file
+            _context.n = 1;
+            return readFile(filePath, 'utf8');
+          case 1:
+            source = _context.v;
+            if (includeDependencies) {
+              _context.n = 2;
+              break;
+            }
+            return _context.a(2, {
+              source: source
+            });
+          case 2:
+            // Check if this is a static asset file (non-JS/TS modules)
+            isJavascriptModuleFile = isJavaScriptModule(filePath);
+            if (isJavascriptModuleFile) {
+              _context.n = 3;
+              break;
+            }
+            return _context.a(2, {
+              source: source
+            });
+          case 3:
+            _context.n = 4;
+            return parseImports(source, filePath);
+          case 4:
+            _yield$parseImports = _context.v;
+            importResult = _yield$parseImports.relative;
+            externals = _yield$parseImports.externals;
+            // Transform externals from parseImports format to simplified format
+            transformedExternals = {};
+            for (_i = 0, _Object$entries = Object.entries(externals); _i < _Object$entries.length; _i++) {
+              _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2), modulePath = _Object$entries$_i[0], externalImport = _Object$entries$_i[1];
+              transformedExternals[modulePath] = externalImport.names.map(function (importName) {
+                return {
+                  name: importName.name,
+                  type: importName.type,
+                  isType: importName.isType
+                };
+              });
+            }
+            if (!(Object.keys(importResult).length === 0)) {
+              _context.n = 5;
+              break;
+            }
+            return _context.a(2, {
+              source: source,
+              externals: Object.keys(transformedExternals).length > 0 ? transformedExternals : undefined
+            });
+          case 5:
+            // Convert to format expected by resolveImportResultWithFs and processImports
+            relativeImportsCompatible = {};
+            for (_i2 = 0, _Object$entries2 = Object.entries(importResult); _i2 < _Object$entries2.length; _i2++) {
+              _Object$entries2$_i = _slicedToArray(_Object$entries2[_i2], 2), importPath = _Object$entries2$_i[0], _Object$entries2$_i$ = _Object$entries2$_i[1], path = _Object$entries2$_i$.path, names = _Object$entries2$_i$.names, includeTypeDefs = _Object$entries2$_i$.includeTypeDefs;
+              relativeImportsCompatible[importPath] = _extends({
+                path: path,
+                names: names.map(function (_ref) {
+                  var name = _ref.name,
+                    alias = _ref.alias;
+                  return alias || name;
+                })
+              }, includeTypeDefs && {
+                includeTypeDefs: includeTypeDefs
+              });
+            }
+
+            // Resolve import paths, handling JS/TS modules and static assets appropriately
+            _context.n = 6;
+            return resolveImportResultWithFs(relativeImportsCompatible);
+          case 6:
+            resolvedPathsMap = _context.v;
+            // Process imports using the consolidated helper function
+            _processRelativeImpor = processRelativeImports(source, relativeImportsCompatible, resolvedPathsMap, storeAt), processedSource = _processRelativeImpor.processedSource, extraFiles = _processRelativeImpor.extraFiles; // Build dependencies list for recursive loading
+            extraDependencies = Object.values(importResult).map(function (_ref2) {
+              var path = _ref2.path;
+              return resolvedPathsMap.get(path);
+            }).filter(function (path) {
+              return path !== undefined;
+            });
+            return _context.a(2, {
+              source: processedSource,
+              extraFiles: Object.keys(extraFiles).length > 0 ? extraFiles : undefined,
+              extraDependencies: extraDependencies.length > 0 ? extraDependencies : undefined,
+              externals: Object.keys(transformedExternals).length > 0 ? transformedExternals : undefined
+            });
+        }
+      }, _callee);
+    }));
+    function loadSource(_x) {
+      return _loadSource.apply(this, arguments);
+    }
+    return loadSource;
+  }();
+}

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

@@ -0,0 +1 @@
+export declare function externalsToPackages(externals: string[]): Record<string, true>;

package/esm/pipeline/loaderUtils/externalsToPackages.js

@@ -0,0 +1,46 @@
+export function externalsToPackages(externals) {
+  var packages = {};
+  externals.forEach(function (external) {
+    // Filter out path aliases that start with @/
+    if (external.startsWith('@/')) {
+      return;
+    }
+
+    // Extract package name from import path
+    var packageName = extractPackageName(external);
+    if (packageName) {
+      packages[packageName] = true;
+    }
+  });
+  return packages;
+}
+
+/**
+ * Extracts the package name from an import path.
+ * Examples:
+ * - 'react' -> 'react'
+ * - 'react-dom' -> 'react-dom'
+ * - '@mui/internal-docs-infra/CodeHighlighter' -> '@mui/internal-docs-infra'
+ * - '@mui/internal-docs-infra/parseSource' -> '@mui/internal-docs-infra'
+ * - 'lodash/get' -> 'lodash'
+ * - 'some-package/submodule/deep' -> 'some-package'
+ */
+function extractPackageName(importPath) {
+  if (!importPath) {
+    return null;
+  }
+
+  // Handle scoped packages (starting with @)
+  if (importPath.startsWith('@')) {
+    var _parts = importPath.split('/');
+    if (_parts.length >= 2) {
+      // Return @scope/package-name
+      return "".concat(_parts[0], "/").concat(_parts[1]);
+    }
+    return null;
+  }
+
+  // Handle regular packages
+  var parts = importPath.split('/');
+  return parts[0] || null;
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Extracts and formats a name and slug from a URL path.
+ * This utility takes the last meaningful segment of a URL path and formats it
+ * into both a human-readable title and a URL-friendly slug.
+ *
+ * - Strips common file extensions (index.js, index.ts, index.tsx, etc.)
+ * - Converts kebab-case to Title Case for names
+ * - Ensures slugs are in kebab-case format
+ */
+/**
+ * Extracts and formats a name and slug from a URL path
+ * @param url - The URL to extract from (can be file:// URL or regular path)
+ * @returns Object containing the formatted name and slug
+ *
+ * @example
+ * extractNameAndSlugFromUrl('file:///app/components/demos/advanced-keyboard/index.ts')
+ * // Returns: { name: 'Advanced Keyboard', slug: 'advanced-keyboard' }
+ *
+ * @example
+ * extractNameAndSlugFromUrl('/src/components/button-group.tsx')
+ * // Returns: { name: 'Button Group', slug: 'button-group' }
+ *
+ * @example
+ * extractNameAndSlugFromUrl('/src/components/customButton.tsx')
+ * // Returns: { name: 'Custom Button', slug: 'custom-button' }
+ *
+ * @example
+ * extractNameAndSlugFromUrl('https://example.com/docs/getting-started/')
+ * // Returns: { name: 'Getting Started', slug: 'getting-started' }
+ */
+export declare function extractNameAndSlugFromUrl(url: string): {
+  name: string;
+  slug: string;
+};

package/esm/pipeline/loaderUtils/extractNameAndSlugFromUrl.js

@@ -0,0 +1,161 @@
+/**
+ * Extracts and formats a name and slug from a URL path.
+ * This utility takes the last meaningful segment of a URL path and formats it
+ * into both a human-readable title and a URL-friendly slug.
+ *
+ * - Strips common file extensions (index.js, index.ts, index.tsx, etc.)
+ * - Converts kebab-case to Title Case for names
+ * - Ensures slugs are in kebab-case format
+ */
+
+/**
+ * Converts a camelCase string to kebab-case
+ * @param camelCase - The camelCase string to convert
+ * @returns kebab-case string
+ */
+function camelToKebabCase(camelCase) {
+  return camelCase
+  // Insert hyphens before uppercase letters that follow lowercase letters or numbers
+  .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+  // Insert hyphens before numbers that follow letters
+  .replace(/([a-zA-Z])([0-9])/g, '$1-$2')
+  // Insert hyphens before letters that follow numbers
+  .replace(/([0-9])([a-zA-Z])/g, '$1-$2').toLowerCase();
+}
+
+/**
+ * Converts a camelCase string to Title Case with spaces
+ * @param camelCase - The camelCase string to convert
+ * @returns Title case string with spaces
+ */
+function camelToTitleCase(camelCase) {
+  return camelCase
+  // Insert spaces before uppercase letters that follow lowercase letters or numbers
+  .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+  // Insert spaces before numbers that follow letters
+  .replace(/([a-zA-Z])([0-9])/g, '$1 $2')
+  // Insert spaces before letters that follow numbers
+  .replace(/([0-9])([a-zA-Z])/g, '$1 $2')
+  // Capitalize the first letter
+  .replace(/^./, function (str) {
+    return str.toUpperCase();
+  });
+}
+
+/**
+ * Converts a kebab-case string to Title Case
+ * @param kebabCase - The kebab-case string to convert
+ * @returns Title case string
+ */
+function kebabToTitleCase(kebabCase) {
+  return kebabCase.split(/[-_]/) // Split on both hyphens and underscores
+  .map(function (word) {
+    return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+  }).join(' ');
+}
+
+/**
+ * Detects if a string is camelCase or PascalCase
+ * @param str - The string to check
+ * @returns true if the string is camelCase or PascalCase
+ */
+function isCamelCase(str) {
+  // Check if it matches the camelCase/PascalCase pattern:
+  // - Only contains letters and numbers
+  // - Has at least one transition from lowercase letter or number to uppercase letter
+  // - Doesn't contain hyphens, underscores, or spaces
+  return /^[a-zA-Z][a-zA-Z0-9]*$/.test(str) && /[a-z0-9][A-Z]/.test(str);
+}
+
+/**
+ * Converts a string to kebab-case
+ * @param str - The string to convert
+ * @returns kebab-case string
+ */
+function toKebabCase(str) {
+  return str.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Extracts the last meaningful segment from a URL path
+ * @param url - The URL to extract from
+ * @returns The last meaningful path segment
+ */
+function extractLastSegment(url) {
+  // Handle file: URLs by removing the protocol
+  var path = url;
+  if (url.startsWith('file:')) {
+    path = url.replace(/^file:\/\//, '');
+  }
+
+  // Strip query parameters and hash fragments before processing
+  path = path.split('?')[0].split('#')[0];
+
+  // Split the path into segments and filter out empty ones
+  var segments = path.split('/').filter(Boolean);
+  if (segments.length === 0) {
+    throw new Error('Could not extract meaningful segment from URL');
+  }
+
+  // Get the last segment
+  var lastSegment = segments[segments.length - 1];
+
+  // Handle index files - any file that starts with 'index.'
+  if (lastSegment.startsWith('index.')) {
+    // If it's an index file, use the parent directory name
+    if (segments.length < 2) {
+      throw new Error('Cannot extract name from index file without parent directory');
+    }
+    lastSegment = segments[segments.length - 2];
+  } else {
+    // Strip everything after the first dot from non-index files
+    // This handles all extensions: .js, .d.ts, .module.css, .config.dev.js, etc.
+    var firstDotIndex = lastSegment.indexOf('.');
+    if (firstDotIndex !== -1) {
+      lastSegment = lastSegment.substring(0, firstDotIndex);
+    }
+  }
+  if (!lastSegment) {
+    throw new Error('Could not extract meaningful segment from URL');
+  }
+  return lastSegment;
+}
+
+/**
+ * Extracts and formats a name and slug from a URL path
+ * @param url - The URL to extract from (can be file:// URL or regular path)
+ * @returns Object containing the formatted name and slug
+ *
+ * @example
+ * extractNameAndSlugFromUrl('file:///app/components/demos/advanced-keyboard/index.ts')
+ * // Returns: { name: 'Advanced Keyboard', slug: 'advanced-keyboard' }
+ *
+ * @example
+ * extractNameAndSlugFromUrl('/src/components/button-group.tsx')
+ * // Returns: { name: 'Button Group', slug: 'button-group' }
+ *
+ * @example
+ * extractNameAndSlugFromUrl('/src/components/customButton.tsx')
+ * // Returns: { name: 'Custom Button', slug: 'custom-button' }
+ *
+ * @example
+ * extractNameAndSlugFromUrl('https://example.com/docs/getting-started/')
+ * // Returns: { name: 'Getting Started', slug: 'getting-started' }
+ */
+export function extractNameAndSlugFromUrl(url) {
+  var segment = extractLastSegment(url);
+
+  // Check if the segment is camelCase and handle it appropriately
+  if (isCamelCase(segment)) {
+    return {
+      name: camelToTitleCase(segment),
+      slug: camelToKebabCase(segment)
+    };
+  }
+
+  // For kebab-case, snake_case, or other formats, use the existing logic
+  return {
+    name: kebabToTitleCase(segment),
+    slug: toKebabCase(segment)
+  };
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Extracts the filename and extension from a URL or file path.
+ * This function is isomorphic and works in both Node.js and browser environments.
+ * It properly handles compound extensions like .module.css, .d.ts, .test.js, etc.
+ *
+ * @param url - The URL or file path to extract the filename from
+ * @returns An object containing the filename and extension
+ */
+export declare function getFileNameFromUrl(url: string): {
+  fileName: string;
+  extension: string;
+};

package/esm/pipeline/loaderUtils/getFileNameFromUrl.js

@@ -0,0 +1,66 @@
+import _createForOfIteratorHelper from "@babel/runtime/helpers/esm/createForOfIteratorHelper";
+/**
+ * Known compound extensions that should be treated as a single unit
+ */
+var COMPOUND_EXTENSIONS = ['.module.css', '.module.scss', '.module.sass', '.module.less', '.d.ts', '.test.js', '.test.jsx', '.test.ts', '.test.tsx', '.spec.js', '.spec.jsx', '.spec.ts', '.spec.tsx', '.config.js', '.config.ts', '.setup.js', '.setup.ts', '.stories.js', '.stories.jsx', '.stories.ts', '.stories.tsx'];
+
+/**
+ * Extracts the filename and extension from a URL or file path.
+ * This function is isomorphic and works in both Node.js and browser environments.
+ * It properly handles compound extensions like .module.css, .d.ts, .test.js, etc.
+ *
+ * @param url - The URL or file path to extract the filename from
+ * @returns An object containing the filename and extension
+ */
+export function getFileNameFromUrl(url) {
+  try {
+    // Use URL constructor to handle various URL formats
+    var urlObj = new URL(url);
+    var pathname = urlObj.pathname;
+    var fileName = pathname.split('/').pop() || '';
+    return extractFileNameAndExtension(fileName);
+  } catch (_unused) {
+    // If URL parsing fails, fall back to simple string manipulation
+    var _fileName = url.split('/').pop() || url;
+    return extractFileNameAndExtension(_fileName);
+  }
+}
+
+/**
+ * Helper function to extract filename and extension, handling compound extensions
+ */
+function extractFileNameAndExtension(fileName) {
+  if (!fileName) {
+    return {
+      fileName: '',
+      extension: ''
+    };
+  }
+
+  // Check for compound extensions first
+  var _iterator = _createForOfIteratorHelper(COMPOUND_EXTENSIONS),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var compoundExt = _step.value;
+      if (fileName.endsWith(compoundExt)) {
+        return {
+          fileName: fileName,
+          extension: compoundExt
+        };
+      }
+    }
+
+    // Fall back to simple extension detection
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  var lastDotIndex = fileName.lastIndexOf('.');
+  var extension = lastDotIndex > 0 ? fileName.substring(lastDotIndex) : '';
+  return {
+    fileName: fileName,
+    extension: extension
+  };
+}

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

@@ -0,0 +1,7 @@
+export * from "./parseImports.js";
+export * from "./resolveModulePath.js";
+export * from "./rewriteImports.js";
+export * from "./processRelativeImports.js";
+export * from "./getFileNameFromUrl.js";
+export * from "./extractNameAndSlugFromUrl.js";
+export * from "./externalsToPackages.js";

package/esm/pipeline/loaderUtils/index.js

@@ -0,0 +1,7 @@
+export * from "./parseImports.js";
+export * from "./resolveModulePath.js";
+export * from "./rewriteImports.js";
+export * from "./processRelativeImports.js";
+export * from "./getFileNameFromUrl.js";
+export * from "./extractNameAndSlugFromUrl.js";
+export * from "./externalsToPackages.js";

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

@@ -0,0 +1,32 @@
+import type { Externals } from "../../CodeHighlighter/types.js";
+/**
+ * Merges multiple externals objects into a single object, combining imports from the same module.
+ * Deduplicates imports by name and type within each module.
+ *
+ * @param externalsArray Array of externals objects to merge
+ * @returns Merged externals object
+ *
+ * @example
+ * ```typescript
+ * const externals1 = {
+ *   'react': [{ name: 'React', type: 'default' }],
+ *   'lodash': [{ name: 'map', type: 'named' }]
+ * };
+ *
+ * const externals2 = {
+ *   'react': [{ name: 'useState', type: 'named' }],
+ *   'lodash': [{ name: 'map', type: 'named' }] // duplicate - will be removed
+ * };
+ *
+ * const merged = mergeExternals([externals1, externals2]);
+ * // Result:
+ * // {
+ * //   'react': [
+ * //     { name: 'React', type: 'default' },
+ * //     { name: 'useState', type: 'named' }
+ * //   ],
+ * //   'lodash': [{ name: 'map', type: 'named' }]
+ * // }
+ * ```
+ */
+export declare function mergeExternals(externalsArray: Array<Externals>): Externals;

package/esm/pipeline/loaderUtils/mergeExternals.js

@@ -0,0 +1,72 @@
+import _toConsumableArray from "@babel/runtime/helpers/esm/toConsumableArray";
+import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
+import _createForOfIteratorHelper from "@babel/runtime/helpers/esm/createForOfIteratorHelper";
+/**
+ * Merges multiple externals objects into a single object, combining imports from the same module.
+ * Deduplicates imports by name and type within each module.
+ *
+ * @param externalsArray Array of externals objects to merge
+ * @returns Merged externals object
+ *
+ * @example
+ * ```typescript
+ * const externals1 = {
+ *   'react': [{ name: 'React', type: 'default' }],
+ *   'lodash': [{ name: 'map', type: 'named' }]
+ * };
+ *
+ * const externals2 = {
+ *   'react': [{ name: 'useState', type: 'named' }],
+ *   'lodash': [{ name: 'map', type: 'named' }] // duplicate - will be removed
+ * };
+ *
+ * const merged = mergeExternals([externals1, externals2]);
+ * // Result:
+ * // {
+ * //   'react': [
+ * //     { name: 'React', type: 'default' },
+ * //     { name: 'useState', type: 'named' }
+ * //   ],
+ * //   'lodash': [{ name: 'map', type: 'named' }]
+ * // }
+ * ```
+ */
+export function mergeExternals(externalsArray) {
+  var merged = {};
+  var _iterator = _createForOfIteratorHelper(externalsArray),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var externals = _step.value;
+      var _loop = function _loop() {
+        var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+          modulePath = _Object$entries$_i[0],
+          imports = _Object$entries$_i[1];
+        if (!merged[modulePath]) {
+          // First time seeing this module, copy all imports
+          merged[modulePath] = _toConsumableArray(imports);
+        } else {
+          // Module already exists, merge imports and deduplicate
+          var existingImports = merged[modulePath];
+          var newImports = imports.filter(function (newImport) {
+            // Check if this import already exists (same name, type, and isType)
+            return !existingImports.some(function (existingImport) {
+              return existingImport.name === newImport.name && existingImport.type === newImport.type && existingImport.isType === newImport.isType;
+            });
+          });
+
+          // Add only the new imports that don't already exist
+          merged[modulePath] = [].concat(_toConsumableArray(existingImports), _toConsumableArray(newImports));
+        }
+      };
+      for (var _i = 0, _Object$entries = Object.entries(externals); _i < _Object$entries.length; _i++) {
+        _loop();
+      }
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return merged;
+}

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

@@ -0,0 +1,19 @@
+export interface ImportName {
+  name: string;
+  alias?: string;
+  type: 'default' | 'named' | 'namespace';
+  isType?: boolean;
+}
+export interface RelativeImport {
+  path: string;
+  names: ImportName[];
+  includeTypeDefs?: true;
+}
+export interface ExternalImport {
+  names: ImportName[];
+}
+export interface ParseImportsResult {
+  relative: Record<string, RelativeImport>;
+  externals: Record<string, ExternalImport>;
+}
+export declare function parseImports(code: string, _filePath: string): Promise<ParseImportsResult>;