Load Code Variant

import { loadCodeVariant } from '@mui/internal-docs-infra/pipeline/loadCodeVariant';

// Load and process a single variant
const result = await loadCodeVariant(
  'file:///app/components/button/Button.tsx',
  'default',
  {
    fileName: 'Button.tsx',
    url: 'file:///app/components/button/Button.tsx',
  },
  {
    sourceParser: createParseSource(),
    loadSource: myLoadSourceFunction,
    sourceTransformers: [typescriptToJavaScript],
  },
);

// Returns:
// {
//   code: { fileName: 'Button.tsx', source: /* HAST nodes */, transforms: { ... } },
//   dependencies: ['file:///app/components/button/Button.tsx'],
//   externals: {}
// }

// Option 1: Specify extraFiles in the variant
const result = await loadCodeVariant(
  'file:///app/components/button/Button.tsx',
  'default',
  {
    fileName: 'Button.tsx',
    source: buttonSource,
    extraFiles: {
      'Button.module.css': 'file:///app/components/button/Button.module.css',
      '../utils/helpers.ts': 'file:///app/components/utils/helpers.ts',
    },
  },
  options,
);

// Option 2: Return extraFiles from loadSource (automatically loaded)
const loadSource = async (url) => {
  const source = await readFile(url);
  const extraFiles = await findDependencies(url); // e.g., CSS imports, relative imports

  return {
    source,
    extraFiles: {
      'Button.module.css': 'file:///app/components/button/Button.module.css',
      '../utils/helpers.ts': 'file:///app/components/utils/helpers.ts',
    },
  };
};

// Both approaches result in all files loaded and highlighted recursively
// result.code.extraFiles contains processed CSS and helpers

const result = await loadCodeVariant(
  'file:///app/components/button/Button.tsx',
  'default',
  variant,
  {
    ...options,
    globalsCode: [
      { fileName: 'package.json', source: packageJsonContent },
      'file:///app/tsconfig.json',
    ],
  },
);

// Global files are merged with metadata flag for filtering

import { parseCode } from '@mui/internal-docs-infra/pipeline/loadCodeVariant';

const code = {
  default: {
    fileName: 'Example.tsx',
    source: 'const x = 1;', // String source
  },
};

const parsed = parseCode(code, parseSource);
// Converts string sources to HAST nodes for rendering

import type { SourceEnhancer, SourceComments } from '@mui/internal-docs-infra/CodeHighlighter';
import type { HastRoot } from 'hast';

// SourceComments is Record<number, string[]> - line numbers to comment arrays

// Example: Add line numbers based on comment sections
const addSectionMarkers: SourceEnhancer = (root, comments, fileName) => {
  // comments is Record<number, string[]> mapping line numbers to comment arrays
  // Use comments to enhance the HAST tree, e.g., add section markers
  if (comments) {
    for (const [lineNumber, lineComments] of Object.entries(comments)) {
      // Process comments to add markers, highlights, etc.
    }
  }
  return root;
};

// Example: Async enhancer that fetches additional data
const addTypeInfo: SourceEnhancer = async (root, comments, fileName) => {
  const typeData = await fetchTypeInfo(fileName);
  // Modify root with type information
  return root;
};

const result = await loadCodeVariant(
  'file:///app/components/button/Button.tsx',
  'default',
  variant,
  {
    sourceParser: createParseSource(),
    loadSource: myLoadSourceFunction,
    sourceEnhancers: [addSectionMarkers, addTypeInfo], // Run in order
  },
);

import { flattenCodeVariant } from '@mui/internal-docs-infra/pipeline/loadCodeVariant';

const variant = {
  url: 'file:///src/components/button/Button.tsx',
  fileName: 'Button.tsx',
  source: buttonSource,
  extraFiles: {
    '../shared/utils.ts': { source: utilsSource },
    '../../package.json': { source: pkgSource, metadata: true },
  },
};

const flattened = flattenCodeVariant(variant);
// Returns:
// {
//   'src/components/button/Button.tsx': { source: buttonSource },
//   'src/components/shared/utils.ts': { source: utilsSource },
//   'src/package.json': { source: pkgSource, metadata: true }
// }

import { maybeCodeInitialData } from '@mui/internal-docs-infra/pipeline/loadCodeVariant';

const { initialData, reason } = maybeCodeInitialData(
  ['typescript', 'javascript'],
  'typescript',
  code,
  undefined,
  true, // needsHighlight
  false, // needsAllFiles
  false, // needsAllVariants
);

if (initialData) {
  // Ready to render immediately
  return <CodeDisplay {...initialData} />;
} else {
  // Need to load more data
  console.log('Missing data:', reason);
}

import { loadCodeFallback } from '@mui/internal-docs-infra/pipeline/loadCodeVariant';

const fallback = await loadCodeFallback(
  'file:///app/demos/example/index.ts',
  'default', // initialVariant
  existingCode, // may be undefined
  {
    loadCodeMeta,
    loadVariantMeta,
    loadSource,
    sourceParser,
    variants: ['default', 'typescript'],
    fallbackUsesExtraFiles: true,
    fallbackUsesAllVariants: false,
  },
);

// Returns minimal data for initial render:
// {
//   code: { default: { ... } },
//   initialFilename: 'Example.tsx',
//   initialSource: /* HAST nodes */,
//   allFileNames: ['Example.tsx', 'Example.module.css'],
// }

import { applyCodeTransform } from '@mui/internal-docs-infra/pipeline/loadCodeVariant';

const jsSource = applyCodeTransform(
  tsSource, // Original TypeScript HAST
  transforms, // From variant.transforms
  'javascript', // Transform key
);

// Returns JavaScript version of the source as HAST

import { mergeCodeMetadata } from '@mui/internal-docs-infra/pipeline/loadCodeVariant';

const merged = mergeCodeMetadata(
  variant,
  {
    'package.json': { source: pkgJson },
    'tsconfig.json': { source: tsConfig },
  },
  { metadataPrefix: 'src/' },
);

// Positions metadata files at correct depth based on source structure

import { examineCodeVariant } from '@mui/internal-docs-infra/pipeline/loadCodeVariant';

const context = examineCodeVariant(variant);
// Returns:
// {
//   hasUrl: true,
//   hasMetadata: true,
//   maxSourceBackNavigation: 2,
//   urlDirectory: ['src', 'components', 'button'],
//   rootLevel: 'src',
//   pathInwardFromRoot: 'components/button',
//   actualUrl: 'file:///src/components/button/Button.tsx'
// }

// Enhancement flow
const enhancedRoot = await sourceEnhancers.reduce(async (rootPromise, enhancer) => {
  const root = await rootPromise;
  return enhancer(root, comments, fileName);
}, Promise.resolve(parsedRoot));

Button.tsx
├── Button.module.css (same directory)
├── ../utils/helpers.ts (parent directory)
└── ../../package.json (grandparent, metadata)

Without metadataPrefix:
├── Button.tsx (source)
├── utils.ts (source)
├── package.json (metadata)
└── tsconfig.json (metadata)

With metadataPrefix: 'src/':
├── src/
│   ├── Button.tsx (source)
│   └── utils.ts (source)
├── package.json (metadata - stays at root)
└── tsconfig.json (metadata - stays at root)

// Loads all files simultaneously
extraFiles: {
  'styles.css': 'url1',
  'utils.ts': 'url2',
  'types.ts': 'url3',
}
// All three load in parallel, not sequentially

// This would throw an error:
// A.tsx imports ../B.tsx
// B.tsx imports ../A.tsx

Error: Circular dependency detected: file:///path/to/file.ts

Error: Invalid extraFiles from loadSource: key "file:///..." appears to be an absolute path.

Error: "loadSource" function is required when source is not provided

Error: Transform "javascript" not found in transforms