@mui/internal-docs-infra/esm/CodeHighlighter/pathUtils.d.ts

MUI Infra - internal documentation creation tools.

/**
 * 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 {};