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

package/esm/pipeline/loaderUtils/fileUrlToPortablePath.js

@@ -0,0 +1,80 @@
+/**
+ * Converts a file:// URL to a portable path format that can be used with path-module (POSIX-only).
+ *
+ * This function is designed to work with isomorphic code that uses path-module,
+ * which only supports POSIX paths. The key insight is that by stripping the `file://`
+ * prefix and normalizing backslashes to forward slashes, we get a path that:
+ * - On Unix: `/home/user/file.ts` - works directly with path-module
+ * - On Windows: `/C:/Users/file.ts` - also works with path-module because it starts with `/`
+ *
+ * The resulting path is NOT a valid filesystem path on Windows, but it's a valid
+ * POSIX-style path for path manipulation. Use `fileURLToPath` from the `url` module
+ * when you need to access the actual filesystem.
+ *
+ * @param fileUrl - A file:// URL or absolute path (with forward slashes)
+ * @returns A portable path starting with `/` that works with path-module
+ *
+ * @example
+ * // Unix file URL
+ * fileUrlToPortablePath('file:///home/user/file.ts') // => '/home/user/file.ts'
+ *
+ * // Windows file URL
+ * fileUrlToPortablePath('file:///C:/Users/file.ts') // => '/C:/Users/file.ts'
+ *
+ * // Already a portable path (passthrough)
+ * fileUrlToPortablePath('/home/user/file.ts') // => '/home/user/file.ts'
+ */
+export function fileUrlToPortablePath(fileUrl) {
+  // If it's not a file:// URL, check if it's already a portable path
+  if (!fileUrl.startsWith('file://')) {
+    // Normalize backslashes to forward slashes
+    var normalized = fileUrl.replace(/\\/g, '/');
+    // If it doesn't start with /, it's likely a Windows path - add leading slash
+    if (!normalized.startsWith('/') && /^[a-zA-Z]:\//.test(normalized)) {
+      return "/".concat(normalized);
+    }
+    return normalized;
+  }
+
+  // Strip the file:// prefix
+  // file:///home/user/file.ts => /home/user/file.ts (Unix)
+  // file:///C:/Users/file.ts => /C:/Users/file.ts (Windows - keep the leading slash)
+  var path = fileUrl.slice(7); // Remove 'file://'
+
+  // Normalize any backslashes that might have snuck in
+  path = path.replace(/\\/g, '/');
+
+  // If it doesn't start with /, add one (should already have one for valid file:// URLs)
+  if (!path.startsWith('/')) {
+    path = "/".concat(path);
+  }
+  return path;
+}
+
+/**
+ * Converts a portable path back to a file:// URL.
+ *
+ * This is the inverse of `fileUrlToPortablePath`. It takes a portable path
+ * (which always starts with `/`) and converts it back to a proper file:// URL.
+ *
+ * @param portablePath - A portable path starting with `/`
+ * @returns A file:// URL
+ *
+ * @example
+ * // Unix path
+ * portablePathToFileUrl('/home/user/file.ts') // => 'file:///home/user/file.ts'
+ *
+ * // Windows path (portable format)
+ * portablePathToFileUrl('/C:/Users/file.ts') // => 'file:///C:/Users/file.ts'
+ */
+export function portablePathToFileUrl(portablePath) {
+  // If it's already a URL (file://, http://, https://), return as-is
+  if (portablePath.startsWith('file://') || portablePath.startsWith('http://') || portablePath.startsWith('https://')) {
+    return portablePath;
+  }
+
+  // For Windows portable paths like /C:/Users/..., we need file:// + path
+  // For Unix paths like /home/user/..., we need file:// + path
+  // Both cases: file:// + /path = file:///path
+  return "file://".concat(portablePath);
+}

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

@@ -4,4 +4,5 @@ export * from "./rewriteImports.js";
 export * from "./processRelativeImports.js";
 export * from "./getFileNameFromUrl.js";
 export * from "./extractNameAndSlugFromUrl.js";
-export * from "./externalsToPackages.js";
+export * from "./externalsToPackages.js";
+export * from "./fileUrlToPortablePath.js";

package/esm/pipeline/loaderUtils/index.js

@@ -4,4 +4,5 @@ export * from "./rewriteImports.js";
 export * from "./processRelativeImports.js";
 export * from "./getFileNameFromUrl.js";
 export * from "./extractNameAndSlugFromUrl.js";
-export * from "./externalsToPackages.js";
+export * from "./externalsToPackages.js";
+export * from "./fileUrlToPortablePath.js";

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

@@ -24,8 +24,8 @@ export interface ImportPathPosition {
  * Represents an import from a relative path (starts with ./ or ../).
  */
 export interface RelativeImport {
-  /** The resolved absolute path to the imported file */
-  path: string;
+  /** The resolved absolute URL to the imported file (file:// URL) */
+  url: string;
   /** Array of imported names from this module */
   names: ImportName[];
   /** Whether TypeScript type definitions should be included for this import */
@@ -68,8 +68,12 @@ export interface ImportsAndComments {
  * and template literals, it's most efficient to handle comment processing in this
  * same pass rather than requiring separate parsing steps.
  *
+ * The function accepts file:// URLs or file paths and converts them internally to a
+ * portable path format that works cross-platform. Resolved import paths are returned
+ * in the same portable format (forward slashes, starting with /).
+ *
  * @param code - The source code to parse
- * @param filePath - The file path, used to determine file type and resolve relative imports
+ * @param fileUrl - The file URL (file:// protocol) or path, used to determine file type and resolve relative imports
  * @param options - Optional configuration for comment processing
  * @param options.removeCommentsWithPrefix - Array of prefixes; comments starting with these will be stripped from output
  * @param options.notableCommentsPrefix - Array of prefixes; comments starting with these will be collected regardless of stripping
@@ -79,13 +83,13 @@ export interface ImportsAndComments {
  * ```typescript
  * const result = await parseImportsAndComments(
  *   'import React from "react";\nimport { Button } from "./Button";',
- *   '/src/App.tsx'
+ *   'file:///src/App.tsx'
  * );
  * // result.externals['react'] contains the React import
- * // result.relative['./Button'] contains the Button import
+ * // result.relative['./Button'] contains the Button import with url: 'file:///src/Button'
  * ```
  */
-export declare function parseImportsAndComments(code: string, filePath: string, options?: {
+export declare function parseImportsAndComments(code: string, fileUrl: string, options?: {
   removeCommentsWithPrefix?: string[];
   notableCommentsPrefix?: string[];
 }): Promise<ImportsAndComments>;

package/esm/pipeline/loaderUtils/parseImportsAndComments.js

@@ -3,9 +3,8 @@ import _asyncToGenerator from "@babel/runtime/helpers/esm/asyncToGenerator";
 import _createForOfIteratorHelper from "@babel/runtime/helpers/esm/createForOfIteratorHelper";
 import _extends from "@babel/runtime/helpers/esm/extends";
 import _toConsumableArray from "@babel/runtime/helpers/esm/toConsumableArray";
-// webpack does not like node: imports
-// eslint-disable-next-line n/prefer-node-protocol
-import path from 'path';
+import * as path from 'path-module';
+import { fileUrlToPortablePath, portablePathToFileUrl } from "./fileUrlToPortablePath.js";
 
 /**
  * Represents a single import name with its properties.
@@ -845,7 +844,7 @@ function detectCssImport(sourceText, pos, cssResult, cssExternals, cssFilePath,
         var resolvedPath = path.resolve(path.dirname(cssFilePath), normalizedPath);
         if (!cssResult[importResult.modulePath]) {
           cssResult[importResult.modulePath] = {
-            path: resolvedPath,
+            url: portablePathToFileUrl(resolvedPath),
             names: [],
             positions: []
           };
@@ -954,7 +953,7 @@ function parseJSImports(code, filePath, result, externals, isMdxFile, removeComm
               var resolvedPath = path.resolve(path.dirname(filePath), _modulePath);
               if (!result[_modulePath]) {
                 result[_modulePath] = {
-                  path: resolvedPath,
+                  url: portablePathToFileUrl(resolvedPath),
                   names: [],
                   positions: []
                 };
@@ -1083,7 +1082,7 @@ function parseJSImports(code, filePath, result, externals, isMdxFile, removeComm
           var _resolvedPath = path.resolve(path.dirname(filePath), modulePath);
           if (!result[modulePath]) {
             result[modulePath] = _extends({
-              path: _resolvedPath,
+              url: portablePathToFileUrl(_resolvedPath),
               names: [],
               positions: []
             }, isTypeImport && {
@@ -1285,8 +1284,12 @@ function detectJavaScriptImport(sourceText, pos, _positionMapper) {
  * and template literals, it's most efficient to handle comment processing in this
  * same pass rather than requiring separate parsing steps.
  *
+ * The function accepts file:// URLs or file paths and converts them internally to a
+ * portable path format that works cross-platform. Resolved import paths are returned
+ * in the same portable format (forward slashes, starting with /).
+ *
  * @param code - The source code to parse
- * @param filePath - The file path, used to determine file type and resolve relative imports
+ * @param fileUrl - The file URL (file:// protocol) or path, used to determine file type and resolve relative imports
  * @param options - Optional configuration for comment processing
  * @param options.removeCommentsWithPrefix - Array of prefixes; comments starting with these will be stripped from output
  * @param options.notableCommentsPrefix - Array of prefixes; comments starting with these will be collected regardless of stripping
@@ -1296,23 +1299,25 @@ function detectJavaScriptImport(sourceText, pos, _positionMapper) {
  * ```typescript
  * const result = await parseImportsAndComments(
  *   'import React from "react";\nimport { Button } from "./Button";',
- *   '/src/App.tsx'
+ *   'file:///src/App.tsx'
  * );
  * // result.externals['react'] contains the React import
- * // result.relative['./Button'] contains the Button import
+ * // result.relative['./Button'] contains the Button import with url: 'file:///src/Button'
  * ```
  */
 export function parseImportsAndComments(_x, _x2, _x3) {
   return _parseImportsAndComments.apply(this, arguments);
 }
 function _parseImportsAndComments() {
-  _parseImportsAndComments = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee(code, filePath, options) {
-    var result, externals, isCssFile, isMdxFile;
+  _parseImportsAndComments = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee(code, fileUrl, options) {
+    var result, externals, filePath, isCssFile, isMdxFile;
     return _regenerator().w(function (_context) {
       while (1) switch (_context.n) {
         case 0:
           result = {};
-          externals = {}; // Check if this is a CSS file
+          externals = {}; // Convert file:// URL or OS path to portable path format for cross-platform compatibility
+          // Portable paths always use forward slashes and start with / (even on Windows: /C:/...)
+          filePath = fileUrlToPortablePath(fileUrl); // Check if this is a CSS file
           isCssFile = filePath.toLowerCase().endsWith('.css'); // Check if this is an MDX file (which can contain code blocks with triple backticks)
           isMdxFile = filePath.toLowerCase().endsWith('.mdx'); // If this is a CSS file, parse CSS @import statements instead
           if (!isCssFile) {

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

@@ -15,7 +15,7 @@ export interface ProcessImportsResult {
  * @returns Object with processed source and extraFiles mapping
  */
 export declare function processRelativeImports(source: string, importResult: Record<string, {
-  path: string;
+  url: string;
   names: string[];
   positions?: Array<{
     start: number;

package/esm/pipeline/loaderUtils/processRelativeImports.js

@@ -4,6 +4,7 @@ import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
 import { rewriteImports } from "./rewriteImports.js";
 import { isJavaScriptModule } from "./resolveModulePath.js";
 import { getFileNameFromUrl } from "./getFileNameFromUrl.js";
+import { fileUrlToPortablePath, portablePathToFileUrl } from "./fileUrlToPortablePath.js";
 /**
  * Processes flat mode with intelligent conflict resolution
  */
@@ -16,9 +17,11 @@ function processFlatMode(importResult, resolvedPathsMap) {
     var _ref2 = _slicedToArray(_ref, 2),
       relativePath = _ref2[0],
       importInfo = _ref2[1];
-    var resolvedPath = resolvedPathsMap.get(importInfo.path);
-    if (resolvedPath) {
-      var fileExtension = getFileNameFromUrl(resolvedPath).extension;
+    var resolvedUrl = resolvedPathsMap.get(importInfo.url);
+    if (resolvedUrl) {
+      // Convert file URL to portable path for path manipulation
+      var resolvedPath = resolvedUrl.startsWith('file://') ? fileUrlToPortablePath(resolvedUrl) : resolvedUrl;
+      var fileExtension = getFileNameFromUrl(resolvedUrl).extension;
       var pathSegments = resolvedPath.split('/').filter(Boolean);
       fileMapping.push({
         resolvedPath: resolvedPath,
@@ -242,7 +245,7 @@ function processFlatMode(importResult, resolvedPathsMap) {
 
   // Fourth pass: build the extraFiles mapping
   finalNames.forEach(function (finalName, resolvedPath) {
-    extraFiles["./".concat(finalName)] = "file://".concat(resolvedPath);
+    extraFiles["./".concat(finalName)] = portablePathToFileUrl(resolvedPath);
   });
   return {
     processedSource: '',
@@ -266,8 +269,8 @@ function processBasicImports(source, importResult, storeAt) {
       var _ref4 = _slicedToArray(_ref3, 2),
         _relativePath = _ref4[0],
         importInfo = _ref4[1];
-      var resolvedPath = importInfo.path; // For CSS, this is already resolved by parseImports
-      var fileUrl = resolvedPath.startsWith('http') ? resolvedPath : "file://".concat(resolvedPath);
+      var resolvedPath = importInfo.url; // For CSS, this is already resolved by parseImports
+      var fileUrl = portablePathToFileUrl(resolvedPath);
       var _getFileNameFromUrl = getFileNameFromUrl(fileUrl),
         fileName = _getFileNameFromUrl.fileName,
         extension = _getFileNameFromUrl.extension;
@@ -290,7 +293,7 @@ function processBasicImports(source, importResult, storeAt) {
       var _ref6 = _slicedToArray(_ref5, 2),
         relativePath = _ref6[0],
         importInfo = _ref6[1];
-      var resolvedPath = importInfo.path;
+      var resolvedPath = importInfo.url;
       var finalName = finalNames.get(resolvedPath);
       if (finalName) {
         importPathMapping.set(relativePath, finalName);
@@ -299,8 +302,7 @@ function processBasicImports(source, importResult, storeAt) {
 
     // Create extraFiles entries
     finalNames.forEach(function (finalName, resolvedPath) {
-      var fileUrl = resolvedPath.startsWith('http') ? resolvedPath : "file://".concat(resolvedPath);
-      extraFiles["./".concat(finalName)] = fileUrl;
+      extraFiles["./".concat(finalName)] = portablePathToFileUrl(resolvedPath);
     });
 
     // Apply import path replacements using position-based rewriting
@@ -329,9 +331,8 @@ function processBasicImports(source, importResult, storeAt) {
       var _ref8 = _slicedToArray(_ref7, 2),
         relativePath = _ref8[0],
         importInfo = _ref8[1];
-      var resolvedPath = importInfo.path;
-      var fileUrl = resolvedPath.startsWith('http') ? resolvedPath : "file://".concat(resolvedPath);
-      extraFiles[relativePath] = fileUrl; // Always use original path for extraFiles
+      var resolvedPath = importInfo.url;
+      extraFiles[relativePath] = portablePathToFileUrl(resolvedPath); // Always use original path for extraFiles
     });
 
     // Apply import path replacements using position-based rewriting
@@ -351,9 +352,8 @@ function processBasicImports(source, importResult, storeAt) {
     var _ref0 = _slicedToArray(_ref9, 2),
       relativePath = _ref0[0],
       importInfo = _ref0[1];
-    var resolvedPath = importInfo.path;
-    var fileUrl = resolvedPath.startsWith('http') ? resolvedPath : "file://".concat(resolvedPath);
-    extraFiles[relativePath] = fileUrl; // Use original import path
+    var resolvedPath = importInfo.url;
+    extraFiles[relativePath] = portablePathToFileUrl(resolvedPath); // Use original import path
   });
   return {
     processedSource: source,
@@ -376,7 +376,8 @@ function processJsImports(source, importResult, storeAt, resolvedPathsMap) {
       var _ref10 = _slicedToArray(_ref1, 2),
         extraFileKey = _ref10[0],
         fileUrl = _ref10[1];
-      var resolvedPath = fileUrl.replace('file://', '');
+      // Convert file URL to portable path for lookup
+      var resolvedPath = fileUrl.startsWith('file://') ? fileUrlToPortablePath(fileUrl) : fileUrl;
       resolvedToExtraFile.set(resolvedPath, extraFileKey);
     });
 
@@ -386,8 +387,10 @@ function processJsImports(source, importResult, storeAt, resolvedPathsMap) {
       var _ref12 = _slicedToArray(_ref11, 2),
         relativePath = _ref12[0],
         importInfo = _ref12[1];
-      var resolvedPath = resolvedPathsMap.get(importInfo.path);
-      if (resolvedPath) {
+      var resolvedUrl = resolvedPathsMap.get(importInfo.url);
+      if (resolvedUrl) {
+        // Convert file URL to portable path for lookup
+        var resolvedPath = resolvedUrl.startsWith('file://') ? fileUrlToPortablePath(resolvedUrl) : resolvedUrl;
         var extraFileKey = resolvedToExtraFile.get(resolvedPath);
         if (extraFileKey) {
           // For JavaScript modules, remove the extension; for other files (CSS, JSON, etc.), keep it
@@ -421,12 +424,14 @@ function processJsImports(source, importResult, storeAt, resolvedPathsMap) {
     var _ref14 = _slicedToArray(_ref13, 2),
       relativePath = _ref14[0],
       importInfo = _ref14[1];
-    var resolved = resolvedPathsMap.get(importInfo.path);
-    if (!resolved) {
+    var resolvedUrl = resolvedPathsMap.get(importInfo.url);
+    if (!resolvedUrl) {
       return;
     }
-    var resolvedPath = resolved;
-    var fileExtension = getFileNameFromUrl(resolvedPath).extension;
+
+    // Convert file URL to portable path for path manipulation
+    var resolvedPath = resolvedUrl.startsWith('file://') ? fileUrlToPortablePath(resolvedUrl) : resolvedUrl;
+    var fileExtension = getFileNameFromUrl(resolvedUrl).extension;
     var isJavascriptModule = isJavaScriptModule(relativePath);
     var keyPath;
     if (!isJavascriptModule) {
@@ -447,8 +452,7 @@ function processJsImports(source, importResult, storeAt, resolvedPathsMap) {
           keyPath = "".concat(relativePath).concat(fileExtension);
       }
     }
-    var fileUrl = resolvedPath.startsWith('http') ? resolvedPath : "file://".concat(resolvedPath);
-    extraFiles[keyPath] = fileUrl;
+    extraFiles[keyPath] = portablePathToFileUrl(resolvedPath);
   });
   return {
     processedSource: source,

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

@@ -37,18 +37,18 @@ export interface TypeAwareResolveResult {
  * Resolves a module path by reading directory contents to find matching files.
  * This is more efficient than checking each file individually with stat calls.
  *
- * Given a path like `/Code/mui-public/packages/docs-infra/docs/app/components/code-highlighter/demos/code/BasicCode`,
+ * Given a path like `file:///Code/mui-public/packages/docs-infra/docs/app/components/code-highlighter/demos/code/BasicCode`,
  * this function will try to find the actual file by checking for:
  * - `BasicCode.ts`, `BasicCode.tsx`, `BasicCode.js`, `BasicCode.jsx`
  * - `BasicCode/index.ts`, `BasicCode/index.tsx`, `BasicCode/index.js`, `BasicCode/index.jsx`
  *
- * @param modulePath - The module path to resolve (without file extension)
+ * @param moduleUrl - The module URL to resolve (file:// URL or portable path, without file extension)
  * @param readDirectory - Function to read directory contents
  * @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)
+ * @returns Promise<string | TypeAwareResolveResult> - The resolved file:// URL(s)
  */
-export declare function resolveModulePath(modulePath: string, readDirectory: DirectoryReader, options?: ResolveModulePathOptions, includeTypeDefs?: boolean): Promise<string | TypeAwareResolveResult>;
+export declare function resolveModulePath(moduleUrl: string, readDirectory: DirectoryReader, options?: ResolveModulePathOptions, includeTypeDefs?: boolean): Promise<string | TypeAwareResolveResult>;
 /**
  * Resolves multiple module paths efficiently by grouping them by directory
  * and performing batch directory lookups.
@@ -70,7 +70,7 @@ export declare function resolveModulePaths(modulePaths: string[], readDirectory:
  * @returns Promise<Map<string, string>> - Map from import path to resolved file path
  */
 export declare function resolveImportResult(importResult: Record<string, {
-  path: string;
+  url: string;
   names: string[];
   includeTypeDefs?: true;
   positions?: Array<{