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

package/esm/CodeHighlighter/parseControlledCode.js

@@ -0,0 +1,87 @@
+import _typeof from "@babel/runtime/helpers/esm/typeof";
+import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
+/**
+ * Pure function to parse controlled code and convert it to regular Code format.
+ * Handles the conversion from ControlledCode (string|null sources) to Code (HAST nodes).
+ */
+export function parseControlledCode(controlledCode, parseSource) {
+  var parsed = {};
+  for (var _i = 0, _Object$entries = Object.entries(controlledCode); _i < _Object$entries.length; _i++) {
+    var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+      variant = _Object$entries$_i[0],
+      variantCode = _Object$entries$_i[1];
+    if (variantCode === null) {
+      // Explicitly deleted - skip this variant
+      continue;
+    }
+    if (variantCode && _typeof(variantCode) === 'object') {
+      var mainSource = void 0;
+
+      // Convert null to empty string, then parse
+      var sourceToProcess = variantCode.source === null ? '' : variantCode.source;
+      if (typeof sourceToProcess === 'string' && variantCode.fileName) {
+        try {
+          mainSource = parseSource(sourceToProcess, variantCode.fileName);
+        } catch (error) {
+          // Keep original string if parsing fails
+          mainSource = sourceToProcess;
+        }
+      } else if (typeof sourceToProcess === 'string' && !variantCode.fileName) {
+        // Return a basic HAST root node with the source text for unsupported file types
+        // This indicates that the source has at least passed through the parsing pipeline
+        var source = {
+          type: 'root',
+          children: [{
+            type: 'text',
+            value: sourceToProcess
+          }]
+        };
+        mainSource = source;
+      } else {
+        // Handle undefined or other non-string values
+        mainSource = sourceToProcess;
+      }
+
+      // Parse extraFiles if present
+      var extraFiles = void 0;
+      if (variantCode.extraFiles) {
+        var parsedExtraFiles = {};
+        for (var _i2 = 0, _Object$entries2 = Object.entries(variantCode.extraFiles); _i2 < _Object$entries2.length; _i2++) {
+          var _Object$entries2$_i = _slicedToArray(_Object$entries2[_i2], 2),
+            fileName = _Object$entries2$_i[0],
+            fileData = _Object$entries2$_i[1];
+          // Convert null to empty string, then parse
+          var fileSourceToProcess = fileData.source === null ? '' : fileData.source;
+          if (typeof fileSourceToProcess === 'string') {
+            // Parse string sources
+            try {
+              var parsedSource = parseSource(fileSourceToProcess, fileName);
+              parsedExtraFiles[fileName] = {
+                source: parsedSource
+              };
+            } catch (error) {
+              // Keep original if parsing fails
+              parsedExtraFiles[fileName] = {
+                source: fileSourceToProcess
+              };
+            }
+          } else {
+            // Keep other values as-is
+            parsedExtraFiles[fileName] = {
+              source: fileSourceToProcess
+            };
+          }
+        }
+        extraFiles = parsedExtraFiles;
+      }
+      parsed[variant] = {
+        fileName: variantCode.fileName,
+        url: variantCode.url,
+        source: mainSource,
+        extraFiles: extraFiles,
+        filesOrder: variantCode.filesOrder
+      };
+    }
+  }
+  return parsed;
+}

package/esm/CodeHighlighter/pathUtils.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Shared path utilities for CodeHighlighter components
+ *
+ * Back navigation counting functions:
+ * - resolveRelativePath().backSteps: Net back navigation after path resolution (recommended for most cases)
+ * - countConsecutiveBackNavigation(): Raw consecutive '../' at start (for trimming leading patterns)
+ * - countBackNavigationOccurrences(): Total raw '../' count anywhere (for metadata analysis)
+ */
+/**
+ * Minimal file representation for path utilities
+ */
+type URL = string;
+type FileEntry = URL | {
+  metadata?: boolean;
+};
+/**
+ * Resolves a relative path by handling .. and . segments properly
+ * This mimics path.resolve() behavior for relative paths
+ * Returns the net back navigation steps after path resolution
+ */
+export declare function resolveRelativePath(relativePath: string): {
+  resolvedPath: string;
+  backSteps: number;
+};
+/**
+ * Split a path into components, filtering out empty strings
+ */
+export declare function splitPath(path: string): string[];
+/**
+ * Extract URL path components, filtering out empty strings
+ */
+export declare function getUrlParts(url: string): string[];
+/**
+ * Remove trailing slash from a path string
+ */
+export declare function removeTrailingSlash(path: string): string;
+/**
+ * Remove a specific number of back navigation prefixes from a path
+ */
+export declare function removeBackNavigationPrefix(path: string, count: number): string;
+/**
+ * Calculate the maximum back navigation levels from a collection of file paths
+ *
+ * This function analyzes all file paths in the collection and determines:
+ * 1. The maximum back navigation steps needed to reach any file (including metadata)
+ * 2. The maximum back navigation steps needed to reach any non-metadata file
+ *
+ * @param files - Record of relative file paths to file content (string) or file objects with optional metadata flag
+ * @returns Object containing:
+ *   - maxBackNavigation: Maximum '../' steps needed to reach any file in the collection
+ *   - maxSourceBackNavigation: Maximum '../' steps needed to reach any non-metadata file
+ *
+ * @example
+ * ```typescript
+ * const files = {
+ *   'component.tsx': 'url',
+ *   '../shared/utils.ts': 'url',
+ *   '../../docs/readme.md': { metadata: true }
+ * };
+ *
+ * const result = calculateMaxBackNavigation(files);
+ * // result: { maxBackNavigation: 2, maxSourceBackNavigation: 1 }
+ * ```
+ */
+export declare function calculateMaxBackNavigation(files: Record<string, FileEntry>): {
+  maxBackNavigation: number;
+  maxSourceBackNavigation: number;
+};
+/**
+ * Calculate the maximum back navigation level from a collection of file paths
+ *
+ * This function analyzes file paths and determines the maximum number of back navigation
+ * steps needed to reach any non-metadata file. It ignores metadata files completely,
+ * focusing only on source code and other content files.
+ *
+ * @param files - Record of relative file paths to file content (string) or file objects with optional metadata flag
+ * @returns The maximum number of `../` steps needed to reach any non-metadata file
+ *
+ * @example
+ * ```typescript
+ * const files = {
+ *   'component.tsx': 'url',
+ *   '../shared/utils.ts': 'url',
+ *   '../../docs/readme.md': { metadata: true }, // ignored
+ *   '../../../deep/source.js': 'url'
+ * };
+ *
+ * const maxSteps = calculateMaxSourceBackNavigation(files);
+ * // maxSteps: 3 (from '../../../deep/source.js')
+ * ```
+ */
+export declare function calculateMaxSourceBackNavigation(files: Record<string, FileEntry>): number;
+/**
+ * Build a path from multiple components, filtering out empty parts
+ */
+export declare function buildPath(...segments: (string | string[] | undefined)[]): string;
+/**
+ * Create synthetic directory names for path structure
+ * Generates alphabetic names: 'a', 'b', 'c', ..., 'z', 'aa', 'ab', 'ac', etc.
+ * @param count - Number of directory names to generate
+ * @returns Array of alphabetic directory names
+ */
+export declare function createSyntheticDirectories(count: number): string[];
+/**
+ * Calculate the required back navigation pattern for metadata files positioning.
+ * This combines maxSourceBackNavigation from files with additional levels from metadataPrefix.
+ *
+ * @param files - Record of extraFiles to analyze for source back navigation
+ * @param metadataPrefix - Optional prefix path (e.g., 'src/', 'src/app/') that adds additional back navigation levels
+ * @returns A string of '../' patterns representing the back navigation needed
+ *
+ * @example
+ * ```typescript
+ * const files = { '../utils.ts': 'url', '../../shared.ts': 'url' };
+ * const result = calculateMetadataBackNavigation(files, 'src/');
+ * // result: '../../../' (maxSourceBackNavigation=2 + metadataPrefix=1)
+ * ```
+ */
+export declare function calculateMetadataBackNavigation(files: Record<string, FileEntry> | undefined, metadataPrefix?: string): string;
+export {};

package/esm/CodeHighlighter/pathUtils.js

@@ -0,0 +1,258 @@
+import _toConsumableArray from "@babel/runtime/helpers/esm/toConsumableArray";
+import _typeof from "@babel/runtime/helpers/esm/typeof";
+import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
+import _createForOfIteratorHelper from "@babel/runtime/helpers/esm/createForOfIteratorHelper";
+/**
+ * Shared path utilities for CodeHighlighter components
+ *
+ * Back navigation counting functions:
+ * - resolveRelativePath().backSteps: Net back navigation after path resolution (recommended for most cases)
+ * - countConsecutiveBackNavigation(): Raw consecutive '../' at start (for trimming leading patterns)
+ * - countBackNavigationOccurrences(): Total raw '../' count anywhere (for metadata analysis)
+ */
+
+/**
+ * Minimal file representation for path utilities
+ */
+
+/**
+ * Resolves a relative path by handling .. and . segments properly
+ * This mimics path.resolve() behavior for relative paths
+ * Returns the net back navigation steps after path resolution
+ */
+export function resolveRelativePath(relativePath) {
+  // Split the path into segments
+  var segments = relativePath.split('/');
+  var resolved = [];
+  var backSteps = 0;
+  var _iterator = _createForOfIteratorHelper(segments),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var segment = _step.value;
+      if (segment === '' || segment === '.') {
+        // Skip empty and current directory segments
+        continue;
+      } else if (segment === '..') {
+        if (resolved.length > 0) {
+          // Remove the last segment (go back one directory)
+          resolved.pop();
+        } else {
+          // Count back steps that go beyond the current directory
+          backSteps += 1;
+        }
+      } else {
+        // Regular directory or file segment
+        resolved.push(segment);
+      }
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return {
+    resolvedPath: resolved.join('/'),
+    backSteps: backSteps
+  };
+}
+
+/**
+ * Split a path into components, filtering out empty strings
+ */
+export function splitPath(path) {
+  return path.split('/').filter(Boolean);
+}
+
+/**
+ * Extract URL path components, filtering out empty strings
+ */
+export function getUrlParts(url) {
+  return splitPath(new URL(url).pathname);
+}
+
+/**
+ * Remove trailing slash from a path string
+ */
+export function removeTrailingSlash(path) {
+  return path.endsWith('/') ? path.slice(0, -1) : path;
+}
+
+/**
+ * Remove a specific number of back navigation prefixes from a path
+ */
+export function removeBackNavigationPrefix(path, count) {
+  var result = path;
+  for (var i = 0; i < count; i += 1) {
+    if (result.startsWith('../')) {
+      result = result.slice(3);
+    } else {
+      break;
+    }
+  }
+  return result;
+}
+
+/**
+ * Calculate the maximum back navigation levels from a collection of file paths
+ *
+ * This function analyzes all file paths in the collection and determines:
+ * 1. The maximum back navigation steps needed to reach any file (including metadata)
+ * 2. The maximum back navigation steps needed to reach any non-metadata file
+ *
+ * @param files - Record of relative file paths to file content (string) or file objects with optional metadata flag
+ * @returns Object containing:
+ *   - maxBackNavigation: Maximum '../' steps needed to reach any file in the collection
+ *   - maxSourceBackNavigation: Maximum '../' steps needed to reach any non-metadata file
+ *
+ * @example
+ * ```typescript
+ * const files = {
+ *   'component.tsx': 'url',
+ *   '../shared/utils.ts': 'url',
+ *   '../../docs/readme.md': { metadata: true }
+ * };
+ *
+ * const result = calculateMaxBackNavigation(files);
+ * // result: { maxBackNavigation: 2, maxSourceBackNavigation: 1 }
+ * ```
+ */
+export function calculateMaxBackNavigation(files) {
+  var maxBackNavigation = 0;
+  var maxSourceBackNavigation = 0;
+  for (var _i = 0, _Object$entries = Object.entries(files); _i < _Object$entries.length; _i++) {
+    var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+      relativePath = _Object$entries$_i[0],
+      fileContent = _Object$entries$_i[1];
+    // Check if this is a metadata file
+    var isMetadata = _typeof(fileContent) === 'object' && fileContent.metadata;
+    var _resolveRelativePath = resolveRelativePath(relativePath),
+      backSteps = _resolveRelativePath.backSteps;
+    if (!isMetadata) {
+      maxSourceBackNavigation = Math.max(maxSourceBackNavigation, backSteps);
+    }
+    maxBackNavigation = Math.max(maxBackNavigation, backSteps);
+  }
+  return {
+    maxBackNavigation: maxBackNavigation,
+    maxSourceBackNavigation: maxSourceBackNavigation
+  };
+}
+
+/**
+ * Calculate the maximum back navigation level from a collection of file paths
+ *
+ * This function analyzes file paths and determines the maximum number of back navigation
+ * steps needed to reach any non-metadata file. It ignores metadata files completely,
+ * focusing only on source code and other content files.
+ *
+ * @param files - Record of relative file paths to file content (string) or file objects with optional metadata flag
+ * @returns The maximum number of `../` steps needed to reach any non-metadata file
+ *
+ * @example
+ * ```typescript
+ * const files = {
+ *   'component.tsx': 'url',
+ *   '../shared/utils.ts': 'url',
+ *   '../../docs/readme.md': { metadata: true }, // ignored
+ *   '../../../deep/source.js': 'url'
+ * };
+ *
+ * const maxSteps = calculateMaxSourceBackNavigation(files);
+ * // maxSteps: 3 (from '../../../deep/source.js')
+ * ```
+ */
+export function calculateMaxSourceBackNavigation(files) {
+  var maxSourceBackNavigation = 0;
+  for (var _i2 = 0, _Object$entries2 = Object.entries(files); _i2 < _Object$entries2.length; _i2++) {
+    var _Object$entries2$_i = _slicedToArray(_Object$entries2[_i2], 2),
+      relativePath = _Object$entries2$_i[0],
+      fileContent = _Object$entries2$_i[1];
+    // Check if this is a metadata file
+    var isMetadata = _typeof(fileContent) === 'object' && fileContent.metadata;
+
+    // Skip metadata files - only consider non-metadata files for maxSourceBackNavigation
+    if (isMetadata) {
+      continue;
+    }
+
+    // Use path resolution to get the net back steps (most accurate)
+    var _resolveRelativePath2 = resolveRelativePath(relativePath),
+      backSteps = _resolveRelativePath2.backSteps;
+    maxSourceBackNavigation = Math.max(maxSourceBackNavigation, backSteps);
+  }
+  return maxSourceBackNavigation;
+}
+
+/**
+ * Build a path from multiple components, filtering out empty parts
+ */
+export function buildPath() {
+  var parts = [];
+  for (var _len = arguments.length, segments = new Array(_len), _key = 0; _key < _len; _key++) {
+    segments[_key] = arguments[_key];
+  }
+  for (var _i3 = 0, _segments = segments; _i3 < _segments.length; _i3++) {
+    var segment = _segments[_i3];
+    if (segment === undefined) {
+      continue;
+    }
+    if (Array.isArray(segment)) {
+      parts.push.apply(parts, _toConsumableArray(segment));
+    } else {
+      parts.push(segment);
+    }
+  }
+  return parts.filter(Boolean).map(removeTrailingSlash).join('/');
+}
+
+/**
+ * Create synthetic directory names for path structure
+ * Generates alphabetic names: 'a', 'b', 'c', ..., 'z', 'aa', 'ab', 'ac', etc.
+ * @param count - Number of directory names to generate
+ * @returns Array of alphabetic directory names
+ */
+export function createSyntheticDirectories(count) {
+  return Array.from({
+    length: count
+  }, function (_, i) {
+    var result = '';
+    var num = i + 1; // 1-based for Excel-style naming
+
+    while (num > 0) {
+      num -= 1; // Adjust for 0-based indexing
+      result = String.fromCharCode(97 + num % 26) + result;
+      num = Math.floor(num / 26);
+    }
+    return result;
+  });
+}
+
+/**
+ * Calculate the required back navigation pattern for metadata files positioning.
+ * This combines maxSourceBackNavigation from files with additional levels from metadataPrefix.
+ *
+ * @param files - Record of extraFiles to analyze for source back navigation
+ * @param metadataPrefix - Optional prefix path (e.g., 'src/', 'src/app/') that adds additional back navigation levels
+ * @returns A string of '../' patterns representing the back navigation needed
+ *
+ * @example
+ * ```typescript
+ * const files = { '../utils.ts': 'url', '../../shared.ts': 'url' };
+ * const result = calculateMetadataBackNavigation(files, 'src/');
+ * // result: '../../../' (maxSourceBackNavigation=2 + metadataPrefix=1)
+ * ```
+ */
+export function calculateMetadataBackNavigation(files, metadataPrefix) {
+  // Get the maxSourceBackNavigation from the file structure
+  var backLevels = 0;
+  if (files) {
+    backLevels = calculateMaxSourceBackNavigation(files);
+  }
+  if (metadataPrefix) {
+    // When a prefix is provided, add additional back navigation based on prefix depth
+    var prefixSegments = metadataPrefix.split('/').filter(Boolean);
+    backLevels += prefixSegments.length;
+  }
+  return '../'.repeat(backLevels);
+}

package/esm/CodeHighlighter/transformCode.d.ts

@@ -0,0 +1,21 @@
+import type { Code, ParseSource } from "./types.js";
+/**
+ * Pure function to identify which variants need transformation.
+ * Returns entries of variants that have transforms requiring processing.
+ */
+export declare function getVariantsToTransform(parsedCode: Code): Array<[string, any]>;
+/**
+ * Pure function to get available transforms from a specific variant.
+ * Only includes transforms that have actual deltas (file changes), not just filename changes.
+ */
+export declare function getAvailableTransforms(parsedCode: Code | undefined, variantName: string): string[];
+/**
+ * Pure async function to transform a single variant's code and extraFiles.
+ * Returns the transformed variant or the original if transformation fails.
+ */
+export declare function transformVariant(variant: string, variantCode: any, parseSource: ParseSource): Promise<any>;
+/**
+ * Pure async function to apply transformations to all variants that need them.
+ * Returns the enhanced code with computed transforms.
+ */
+export declare function applyTransforms(parsedCode: Code, parseSource: ParseSource): Promise<Code>;