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

package/esm/CodeHighlighter/maybeInitialData.d.ts

@@ -0,0 +1,108 @@
+import { Code, VariantExtraFiles, VariantSource } from "./types.js";
+/**
+ * Type guard function that determines if we have sufficient data to render a code highlighter
+ * component immediately, or if we need to start loading data first.
+ *
+ * This function acts as a validation layer to ensure we have the minimal required data
+ * to render either a fallback state or the actual code content, helping to prevent
+ * rendering errors and provide better user experience.
+ *
+ * ## Usage Contexts
+ *
+ * This function is used in two main scenarios:
+ *
+ * 1. **Server-side rendering (CodeHighlighter)**: Determines if we can render with initial
+ *    source content immediately, or if we need to load fallback data via `CodeInitialSourceLoader`
+ *
+ * 2. **Client-side hydration (CodeHighlighterClient)**: Within `useInitialData` hook to determine
+ *    if we should trigger loading effects or if we can render with available data
+ *
+ * ## Decision Flow
+ *
+ * The function checks data availability in this order:
+ * 1. Code object exists and contains the requested variant
+ * 2. All required variants are available (if `needsAllVariants` is true)
+ * 3. Requested file exists (main file or in extraFiles)
+ * 4. All extra files are loaded (if `needsAllFiles` is true)
+ * 5. Source content is properly highlighted (if `needsHighlight` is true)
+ *
+ * ## Synchronous vs Asynchronous Behavior
+ *
+ * This function operates **synchronously** and only validates existing data - it never triggers
+ * any loading operations. This design is crucial for performance and rendering strategies:
+ *
+ * - **Synchronous validation** allows immediate decisions about rendering paths without async overhead
+ * - **Enables build-time optimization**: When code is precomputed (e.g., via build-time processing),
+ *   this function can immediately return `initialData`, avoiding async components entirely
+ * - **Separates concerns**: Data validation is separate from data loading, making the codebase
+ *   more predictable and easier to reason about
+ *
+ * When `initialData: false` is returned, the calling component is responsible for initiating
+ * asynchronous loading operations (e.g., `loadFallbackCode`, `CodeInitialSourceLoader`).
+ *
+ * @param variants - Array of all available variant names for this code block (e.g., ['javascript', 'typescript'])
+ * @param variant - The specific variant we want to display (must exist in variants array)
+ * @param code - The code object containing all variant data (may be undefined if not loaded)
+ * @param fileName - Optional specific file to display. Resolution logic:
+ *   - When it matches `variantCode.fileName`, uses the main variant source
+ *   - When it doesn't match, looks for the file in `variantCode.extraFiles`
+ *   - When undefined, defaults to the main file of the variant
+ * @param needsHighlight - Whether the code needs to be syntax highlighted (source must be highlighted object, not string)
+ * @param needsAllFiles - Whether all extra files must be loaded before rendering (checks that all extraFiles have source content)
+ * @param needsAllVariants - Whether all variants must be available before rendering (validates using hasAllVariants)
+ *
+ * @returns Object with either:
+ * - `initialData: false` with a `reason` string explaining why data is insufficient for rendering
+ * - `initialData: object` containing the validated data ready for immediate rendering, including:
+ *   - `code`: The full code object
+ *   - `initialFilename`: The resolved filename (may be undefined if variant has no fileName)
+ *   - `initialSource`: The source content for the requested file
+ *   - `initialExtraFiles`: Extra files associated with the variant (if any)
+ *
+ * @example
+ * ```typescript
+ * // Server-side: Check if we can render with initial source or need to load fallback
+ * const { initialData, reason } = maybeInitialData(
+ *   variants,
+ *   initialKey,
+ *   code || props.precompute,
+ *   undefined,
+ *   highlightAt === 'init',
+ *   props.fallbackUsesExtraFiles,
+ *   props.fallbackUsesAllVariants,
+ * );
+ *
+ * if (!initialData) {
+ *   // Need to load fallback data
+ *   return <CodeInitialSourceLoader {...props} />;
+ * }
+ *
+ * // Client-side: Check if we need to trigger loading effects
+ * const { initialData, reason } = React.useMemo(() =>
+ *   maybeInitialData(
+ *     variants,
+ *     variantName,
+ *     code,
+ *     fileName,
+ *     highlightAt === 'init',
+ *     fallbackUsesExtraFiles,
+ *     fallbackUsesAllVariants,
+ *   ), [dependencies]);
+ *
+ * React.useEffect(() => {
+ *   if (initialData || isControlled) {
+ *     return; // No loading needed
+ *   }
+ *   // Trigger loadFallbackCode...
+ * }, [initialData, reason, ...]);
+ * ```
+ */
+export declare function maybeInitialData(variants: string[], variant: string, code?: Code, fileName?: string, needsHighlight?: boolean, needsAllFiles?: boolean, needsAllVariants?: boolean): {
+  initialData: false | {
+    code: Code;
+    initialFilename: string | undefined;
+    initialSource: VariantSource;
+    initialExtraFiles?: VariantExtraFiles;
+  };
+  reason?: string;
+};

package/esm/CodeHighlighter/maybeInitialData.js

@@ -0,0 +1,192 @@
+import _typeof from "@babel/runtime/helpers/esm/typeof";
+import { hasAllVariants } from "./hasAllVariants.js";
+/**
+ * Type guard function that determines if we have sufficient data to render a code highlighter
+ * component immediately, or if we need to start loading data first.
+ *
+ * This function acts as a validation layer to ensure we have the minimal required data
+ * to render either a fallback state or the actual code content, helping to prevent
+ * rendering errors and provide better user experience.
+ *
+ * ## Usage Contexts
+ *
+ * This function is used in two main scenarios:
+ *
+ * 1. **Server-side rendering (CodeHighlighter)**: Determines if we can render with initial
+ *    source content immediately, or if we need to load fallback data via `CodeInitialSourceLoader`
+ *
+ * 2. **Client-side hydration (CodeHighlighterClient)**: Within `useInitialData` hook to determine
+ *    if we should trigger loading effects or if we can render with available data
+ *
+ * ## Decision Flow
+ *
+ * The function checks data availability in this order:
+ * 1. Code object exists and contains the requested variant
+ * 2. All required variants are available (if `needsAllVariants` is true)
+ * 3. Requested file exists (main file or in extraFiles)
+ * 4. All extra files are loaded (if `needsAllFiles` is true)
+ * 5. Source content is properly highlighted (if `needsHighlight` is true)
+ *
+ * ## Synchronous vs Asynchronous Behavior
+ *
+ * This function operates **synchronously** and only validates existing data - it never triggers
+ * any loading operations. This design is crucial for performance and rendering strategies:
+ *
+ * - **Synchronous validation** allows immediate decisions about rendering paths without async overhead
+ * - **Enables build-time optimization**: When code is precomputed (e.g., via build-time processing),
+ *   this function can immediately return `initialData`, avoiding async components entirely
+ * - **Separates concerns**: Data validation is separate from data loading, making the codebase
+ *   more predictable and easier to reason about
+ *
+ * When `initialData: false` is returned, the calling component is responsible for initiating
+ * asynchronous loading operations (e.g., `loadFallbackCode`, `CodeInitialSourceLoader`).
+ *
+ * @param variants - Array of all available variant names for this code block (e.g., ['javascript', 'typescript'])
+ * @param variant - The specific variant we want to display (must exist in variants array)
+ * @param code - The code object containing all variant data (may be undefined if not loaded)
+ * @param fileName - Optional specific file to display. Resolution logic:
+ *   - When it matches `variantCode.fileName`, uses the main variant source
+ *   - When it doesn't match, looks for the file in `variantCode.extraFiles`
+ *   - When undefined, defaults to the main file of the variant
+ * @param needsHighlight - Whether the code needs to be syntax highlighted (source must be highlighted object, not string)
+ * @param needsAllFiles - Whether all extra files must be loaded before rendering (checks that all extraFiles have source content)
+ * @param needsAllVariants - Whether all variants must be available before rendering (validates using hasAllVariants)
+ *
+ * @returns Object with either:
+ * - `initialData: false` with a `reason` string explaining why data is insufficient for rendering
+ * - `initialData: object` containing the validated data ready for immediate rendering, including:
+ *   - `code`: The full code object
+ *   - `initialFilename`: The resolved filename (may be undefined if variant has no fileName)
+ *   - `initialSource`: The source content for the requested file
+ *   - `initialExtraFiles`: Extra files associated with the variant (if any)
+ *
+ * @example
+ * ```typescript
+ * // Server-side: Check if we can render with initial source or need to load fallback
+ * const { initialData, reason } = maybeInitialData(
+ *   variants,
+ *   initialKey,
+ *   code || props.precompute,
+ *   undefined,
+ *   highlightAt === 'init',
+ *   props.fallbackUsesExtraFiles,
+ *   props.fallbackUsesAllVariants,
+ * );
+ *
+ * if (!initialData) {
+ *   // Need to load fallback data
+ *   return <CodeInitialSourceLoader {...props} />;
+ * }
+ *
+ * // Client-side: Check if we need to trigger loading effects
+ * const { initialData, reason } = React.useMemo(() =>
+ *   maybeInitialData(
+ *     variants,
+ *     variantName,
+ *     code,
+ *     fileName,
+ *     highlightAt === 'init',
+ *     fallbackUsesExtraFiles,
+ *     fallbackUsesAllVariants,
+ *   ), [dependencies]);
+ *
+ * React.useEffect(() => {
+ *   if (initialData || isControlled) {
+ *     return; // No loading needed
+ *   }
+ *   // Trigger loadFallbackCode...
+ * }, [initialData, reason, ...]);
+ * ```
+ */
+export function maybeInitialData(variants, variant, code, fileName) {
+  var needsHighlight = arguments.length > 4 && arguments[4] !== undefined ? arguments[4] : false;
+  var needsAllFiles = arguments.length > 5 && arguments[5] !== undefined ? arguments[5] : false;
+  var needsAllVariants = arguments.length > 6 && arguments[6] !== undefined ? arguments[6] : false;
+  if (!code) {
+    return {
+      initialData: false,
+      reason: 'No code provided'
+    };
+  }
+  if (needsAllVariants && !hasAllVariants(variants, code, needsHighlight)) {
+    return {
+      initialData: false,
+      reason: 'Not all variants are available'
+    };
+  }
+  var variantCode = code[variant];
+  if (!variantCode || typeof variantCode === 'string') {
+    return {
+      initialData: false,
+      reason: 'Variant code is not loaded yet'
+    };
+  }
+  if (needsAllFiles) {
+    if (!variantCode) {
+      return {
+        initialData: false,
+        reason: 'Variant code not found'
+      };
+    }
+    if (!variantCode.source) {
+      return {
+        initialData: false,
+        reason: 'Variant source not found'
+      };
+    }
+    if (variantCode.extraFiles && !Object.keys(variantCode.extraFiles).every(function (file) {
+      var _variantCode$extraFil;
+      var fileData = (_variantCode$extraFil = variantCode.extraFiles) == null ? void 0 : _variantCode$extraFil[file];
+      return _typeof(fileData) === 'object' && (fileData == null ? void 0 : fileData.source) !== undefined;
+    })) {
+      return {
+        initialData: false,
+        reason: 'Not all extra files are available'
+      };
+    }
+  }
+
+  // TODO, filename might need to be determined from filesOrder if provided?
+  var initialFilename = fileName || variantCode.fileName;
+  var fileSource;
+  if (fileName && fileName !== variantCode.fileName) {
+    var _variantCode$extraFil2;
+    var fileData = variantCode == null || (_variantCode$extraFil2 = variantCode.extraFiles) == null ? void 0 : _variantCode$extraFil2[fileName];
+    if (!fileData) {
+      return {
+        initialData: false,
+        reason: "File not found in code"
+      };
+    }
+    if (typeof fileData === 'string') {
+      // It's a URL, not actual source content
+      return {
+        initialData: false,
+        reason: "File is not loaded yet"
+      };
+    }
+    fileSource = fileData.source;
+  } else {
+    fileSource = variantCode.source;
+  }
+  if (!fileSource) {
+    return {
+      initialData: false,
+      reason: "File source not found"
+    };
+  }
+  if (needsHighlight && typeof fileSource === 'string') {
+    return {
+      initialData: false,
+      reason: 'File needs highlighting'
+    };
+  }
+  return {
+    initialData: {
+      code: code,
+      initialFilename: initialFilename,
+      initialSource: fileSource,
+      initialExtraFiles: variantCode == null ? void 0 : variantCode.extraFiles
+    }
+  };
+}

package/esm/CodeHighlighter/mergeMetadata.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Metadata merging utility for positioning metadata files relative to source files
+ */
+import type { VariantCode, VariantExtraFiles } from "./types.js";
+/**
+ * Options for merging metadata files
+ */
+interface MergeMetadataOptions {
+  /**
+   * Optional prefix indicating where source files will be placed.
+   * When provided, metadata files will be positioned relative to this prefix
+   * PLUS the existing maxSourceBackNavigation from the variant structure.
+   *
+   * Examples (assuming maxSourceBackNavigation = 2):
+   * - 'src/' -> metadata goes to '../../../' (maxSourceBackNavigation + 1 for src/)
+   * - 'src/app/' -> metadata goes to '../../../../' (maxSourceBackNavigation + 2 for src/app/)
+   * - undefined -> uses only maxSourceBackNavigation (for client merging)
+   */
+  metadataPrefix?: string;
+}
+/**
+ * Merge metadata files into a variant with proper positioning
+ *
+ * @param variant - The variant containing source files and potentially mixed metadata/non-metadata files
+ * @param metadataFiles - Additional metadata files to merge in
+ * @param options - Options for metadata positioning
+ * @returns A variant with all metadata files properly positioned
+ */
+/**
+ * Extract metadata files from a variant, scoping them according to metadataPrefix
+ *
+ * @param variant - The variant containing mixed source and metadata files
+ * @returns An object with the cleaned variant and extracted metadata
+ */
+export declare function extractMetadata(variant: VariantCode): {
+  variant: VariantCode;
+  metadata: VariantExtraFiles;
+};
+export declare function mergeMetadata(variant: VariantCode, metadataFiles?: VariantExtraFiles, options?: MergeMetadataOptions): VariantCode;
+export {};

package/esm/CodeHighlighter/mergeMetadata.js

@@ -0,0 +1,165 @@
+import _objectWithoutPropertiesLoose from "@babel/runtime/helpers/esm/objectWithoutPropertiesLoose";
+import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
+import _extends from "@babel/runtime/helpers/esm/extends";
+var _excluded = ["metadata"];
+/**
+ * Metadata merging utility for positioning metadata files relative to source files
+ */
+
+import { calculateMaxSourceBackNavigation, removeBackNavigationPrefix, buildPath, calculateMetadataBackNavigation, splitPath } from "./pathUtils.js";
+
+/**
+ * Options for merging metadata files
+ */
+
+/**
+ * Merge metadata files into a variant with proper positioning
+ *
+ * @param variant - The variant containing source files and potentially mixed metadata/non-metadata files
+ * @param metadataFiles - Additional metadata files to merge in
+ * @param options - Options for metadata positioning
+ * @returns A variant with all metadata files properly positioned
+ */
+/**
+ * Extract metadata files from a variant, scoping them according to metadataPrefix
+ *
+ * @param variant - The variant containing mixed source and metadata files
+ * @returns An object with the cleaned variant and extracted metadata
+ */
+export function extractMetadata(variant) {
+  var metadataPrefix = variant.metadataPrefix;
+  var extractedMetadata = {};
+  var nonMetadataFiles = {};
+  if (!variant.extraFiles) {
+    return {
+      variant: _extends(_extends({}, variant), {}, {
+        extraFiles: {}
+      }),
+      metadata: {}
+    };
+  }
+
+  // Calculate how much back navigation to remove using pathUtils
+  var backLevelsToRemove = calculateMaxSourceBackNavigation(variant.extraFiles || {});
+  if (metadataPrefix) {
+    // Add metadataPrefix levels if present
+    backLevelsToRemove += splitPath(metadataPrefix).length;
+  }
+
+  // Process all extraFiles
+  for (var _i = 0, _Object$entries = Object.entries(variant.extraFiles); _i < _Object$entries.length; _i++) {
+    var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+      relativePath = _Object$entries$_i[0],
+      fileContent = _Object$entries$_i[1];
+    var file = typeof fileContent === 'string' ? {
+      source: fileContent
+    } : fileContent;
+    if (file.metadata) {
+      var scopedPath = removeBackNavigationPrefix(relativePath, backLevelsToRemove);
+
+      // Remove metadata flag when extracting
+      var metadataFlag = file.metadata,
+        cleanFile = _objectWithoutPropertiesLoose(file, _excluded);
+      extractedMetadata[scopedPath] = cleanFile;
+    } else {
+      nonMetadataFiles[relativePath] = file;
+    }
+  }
+  return {
+    variant: _extends(_extends({}, variant), {}, {
+      extraFiles: nonMetadataFiles
+    }),
+    metadata: extractedMetadata
+  };
+}
+export function mergeMetadata(variant) {
+  var _options$metadataPref;
+  var metadataFiles = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  var options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+  // Determine which metadataPrefix to use
+  var targetMetadataPrefix = (_options$metadataPref = options.metadataPrefix) != null ? _options$metadataPref : variant.metadataPrefix;
+
+  // Check if we need to re-extract metadata due to metadataPrefix change
+  var needsReextraction = options.metadataPrefix !== undefined && options.metadataPrefix !== variant.metadataPrefix;
+
+  // If metadataPrefix is changing, extract existing metadata and reposition everything
+  var workingVariant = variant;
+  var existingMetadata = {};
+  if (needsReextraction && variant.extraFiles) {
+    // Extract existing metadata using the old metadataPrefix
+    var extracted = extractMetadata(variant);
+    workingVariant = extracted.variant;
+    existingMetadata = extracted.metadata;
+  }
+
+  // Calculate the positioning level for metadata files
+  var metadataBackNavigation = calculateMetadataBackNavigation(workingVariant.extraFiles, targetMetadataPrefix);
+
+  // Collect all metadata files that need positioning
+  var allMetadataFiles = {};
+  var nonMetadataFiles = {};
+  var positionedMetadataFiles = {};
+
+  // Process existing extraFiles from working variant
+  if (workingVariant.extraFiles) {
+    for (var _i2 = 0, _Object$entries2 = Object.entries(workingVariant.extraFiles); _i2 < _Object$entries2.length; _i2++) {
+      var _Object$entries2$_i = _slicedToArray(_Object$entries2[_i2], 2),
+        relativePath = _Object$entries2$_i[0],
+        fileContent = _Object$entries2$_i[1];
+      var file = typeof fileContent === 'string' ? {
+        source: fileContent
+      } : fileContent;
+      if (file.metadata) {
+        // If we're not changing metadataPrefix, keep existing metadata files where they are
+        if (!needsReextraction) {
+          positionedMetadataFiles[relativePath] = file;
+        } else {
+          // Only collect for repositioning if metadataPrefix is changing
+          allMetadataFiles[relativePath] = file;
+        }
+      } else {
+        nonMetadataFiles[relativePath] = file;
+      }
+    }
+  }
+
+  // Add extracted metadata (if any) for repositioning
+  for (var _i3 = 0, _Object$entries3 = Object.entries(existingMetadata); _i3 < _Object$entries3.length; _i3++) {
+    var _Object$entries3$_i = _slicedToArray(_Object$entries3[_i3], 2),
+      filePath = _Object$entries3$_i[0],
+      _file = _Object$entries3$_i[1];
+    allMetadataFiles[filePath] = _extends(_extends({}, typeof _file === 'string' ? {
+      source: _file
+    } : _file), {}, {
+      metadata: true
+    });
+  }
+
+  // Add additional metadata files for positioning
+  for (var _i4 = 0, _Object$entries4 = Object.entries(metadataFiles); _i4 < _Object$entries4.length; _i4++) {
+    var _Object$entries4$_i = _slicedToArray(_Object$entries4[_i4], 2),
+      _filePath = _Object$entries4$_i[0],
+      _file2 = _Object$entries4$_i[1];
+    allMetadataFiles[_filePath] = _extends(_extends({}, typeof _file2 === 'string' ? {
+      source: _file2
+    } : _file2), {}, {
+      metadata: true
+    });
+  }
+
+  // Position new metadata files at the calculated level using buildPath
+  for (var _i5 = 0, _Object$entries5 = Object.entries(allMetadataFiles); _i5 < _Object$entries5.length; _i5++) {
+    var _Object$entries5$_i = _slicedToArray(_Object$entries5[_i5], 2),
+      originalPath = _Object$entries5$_i[0],
+      _file3 = _Object$entries5$_i[1];
+    var metadataPath = buildPath(metadataBackNavigation, originalPath);
+    positionedMetadataFiles[metadataPath] = _file3;
+  }
+
+  // Combine all files
+  var finalExtraFiles = _extends(_extends({}, nonMetadataFiles), positionedMetadataFiles);
+  return _extends(_extends({}, workingVariant), {}, {
+    extraFiles: finalExtraFiles,
+    metadataPrefix: targetMetadataPrefix
+  });
+}

package/esm/CodeHighlighter/parseCode.d.ts

@@ -0,0 +1,6 @@
+import type { Code, ParseSource } from "./types.js";
+/**
+ * Pure function to parse code variants and their extraFiles.
+ * Converts string sources to HAST nodes and handles hastJson parsing.
+ */
+export declare function parseCode(code: Code, parseSource: ParseSource): Code;

package/esm/CodeHighlighter/parseCode.js

@@ -0,0 +1,134 @@
+import _extends from "@babel/runtime/helpers/esm/extends";
+import _typeof from "@babel/runtime/helpers/esm/typeof";
+import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
+/**
+ * Pure function to parse code variants and their extraFiles.
+ * Converts string sources to HAST nodes and handles hastJson parsing.
+ */
+export function parseCode(code, parseSource) {
+  var parsed = {};
+  for (var _i = 0, _Object$entries = Object.entries(code); _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 (typeof variantCode === 'string') {
+      // Already parsed/highlighted
+      parsed[variant] = variantCode;
+    } else if (variantCode && _typeof(variantCode) === 'object') {
+      // Parse if source is available and not already parsed, and we have a filename to determine the file type
+      if (variantCode.source && typeof variantCode.source === 'string' && variantCode.fileName) {
+        try {
+          var hastRoot = parseSource(variantCode.source, variantCode.fileName);
+
+          // Also parse extraFiles if they contain sources that need parsing
+          var parsedExtraFiles = variantCode.extraFiles ? Object.fromEntries(Object.entries(variantCode.extraFiles).map(function (_ref) {
+            var _ref2 = _slicedToArray(_ref, 2),
+              fileName = _ref2[0],
+              fileContent = _ref2[1];
+            if (typeof fileContent === 'string') {
+              return [fileName, fileContent]; // Keep string as-is
+            }
+            if (fileContent && _typeof(fileContent) === 'object' && fileContent.source) {
+              if (typeof fileContent.source === 'string') {
+                // Parse string source in extraFile
+                try {
+                  var parsedHastRoot = parseSource(fileContent.source, fileName);
+                  return [fileName, _extends(_extends({}, fileContent), {}, {
+                    source: parsedHastRoot
+                  })];
+                } catch (error) {
+                  return [fileName, fileContent]; // Keep original if parsing fails
+                }
+              }
+            }
+            return [fileName, fileContent]; // Keep as-is for other cases
+          })) : undefined;
+          parsed[variant] = _extends(_extends({}, variantCode), {}, {
+            source: hastRoot,
+            extraFiles: parsedExtraFiles
+          });
+        } catch (error) {
+          // Keep original if parsing fails
+          parsed[variant] = variantCode;
+        }
+      } else if (variantCode.source && typeof variantCode.source === '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
+        parsed[variant] = _extends(_extends({}, variantCode), {}, {
+          source: {
+            type: 'root',
+            children: [{
+              type: 'text',
+              value: variantCode.source
+            }]
+          }
+        });
+      } else if (variantCode.source && _typeof(variantCode.source) === 'object' && 'hastJson' in variantCode.source) {
+        try {
+          // Parse hastJson to HAST nodes
+          var _hastRoot = JSON.parse(variantCode.source.hastJson);
+
+          // Also parse extraFiles if they contain sources that need parsing
+          var _parsedExtraFiles = variantCode.extraFiles ? Object.fromEntries(Object.entries(variantCode.extraFiles).map(function (_ref3) {
+            var _ref4 = _slicedToArray(_ref3, 2),
+              fileName = _ref4[0],
+              fileContent = _ref4[1];
+            if (typeof fileContent === 'string') {
+              return [fileName, fileContent]; // Keep string as-is
+            }
+            if (fileContent && _typeof(fileContent) === 'object' && fileContent.source) {
+              if (typeof fileContent.source === 'string') {
+                // Parse string source in extraFile
+                try {
+                  var parsedHastRoot = parseSource(fileContent.source, fileName);
+                  return [fileName, _extends(_extends({}, fileContent), {}, {
+                    source: parsedHastRoot
+                  })];
+                } catch (error) {
+                  return [fileName, fileContent]; // Keep original if parsing fails
+                }
+              }
+            }
+            return [fileName, fileContent]; // Keep as-is for other cases
+          })) : undefined;
+          parsed[variant] = _extends(_extends({}, variantCode), {}, {
+            source: _hastRoot,
+            extraFiles: _parsedExtraFiles
+          });
+        } catch (error) {
+          // Keep original if parsing fails
+          console.error("Failed to parse hastJson for variant ".concat(variant, ":"), error);
+          parsed[variant] = variantCode;
+        }
+      } else {
+        // Already parsed or no source to parse - but still check extraFiles
+        var _parsedExtraFiles2 = variantCode.extraFiles ? Object.fromEntries(Object.entries(variantCode.extraFiles).map(function (_ref5) {
+          var _ref6 = _slicedToArray(_ref5, 2),
+            fileName = _ref6[0],
+            fileContent = _ref6[1];
+          if (typeof fileContent === 'string') {
+            return [fileName, fileContent]; // Keep string as-is
+          }
+          if (fileContent && _typeof(fileContent) === 'object' && fileContent.source) {
+            if (typeof fileContent.source === 'string') {
+              // Parse string source in extraFile
+              try {
+                var parsedHastRoot = parseSource(fileContent.source, fileName);
+                return [fileName, _extends(_extends({}, fileContent), {}, {
+                  source: parsedHastRoot
+                })];
+              } catch (error) {
+                return [fileName, fileContent]; // Keep original if parsing fails
+              }
+            }
+          }
+          return [fileName, fileContent]; // Keep as-is for other cases
+        })) : undefined;
+        parsed[variant] = _extends(_extends({}, variantCode), {}, {
+          extraFiles: _parsedExtraFiles2
+        });
+      }
+    }
+  }
+  return parsed;
+}

package/esm/CodeHighlighter/parseControlledCode.d.ts

@@ -0,0 +1,6 @@
+import type { Code, ControlledCode, ParseSource } from "./types.js";
+/**
+ * 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 declare function parseControlledCode(controlledCode: ControlledCode, parseSource: ParseSource): Code;