@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.d.mts

MUI Infra - internal documentation creation tools.

import type { SourceEnhancer } from "../../CodeHighlighter/types.mjs";
import type { EnhanceCodeEmphasisOptions } from "../parseSource/calculateFrameRanges.mjs";
export type { EmphasisMeta, EnhanceCodeEmphasisOptions, FrameRange } from "../parseSource/calculateFrameRanges.mjs";
/**
 * The prefix used to identify emphasis comments in source code.
 * Comments starting with this prefix will be processed for emphasis.
 */
export declare const EMPHASIS_COMMENT_PREFIX = "@highlight";
/**
 * The prefix used to identify focus-only comments in source code.
 * Comments starting with this prefix will mark the region as focused without highlighting.
 */
export declare const FOCUS_COMMENT_PREFIX = "@focus";
/**
 * Modifier token used inside `@highlight` / `@focus` comments
 * to override padding for that directive.
 * Example: @highlight @padding 2.
 */
export declare const PADDING_COMMENT_PREFIX = "@padding";
/**
 * Modifier token used inside `@highlight` / `@focus` comments
 * to override focus max size for that directive.
 * Example: @highlight @min 6.
 */
export declare const MIN_COMMENT_PREFIX = "@min";
/**
 * Creates a source enhancer that adds emphasis to code lines based on `@highlight` comments
 * and restructures frames around highlighted regions.
 *
 * Supports five patterns:
 *
 * 1. **Single line emphasis** - emphasizes the line containing the comment:
 *    ```jsx
 *    <h1>Heading 1</h1> {/* @highlight *\/}
 *    ```
 *
 * 2. **Multiline emphasis** - emphasizes all lines between start and end:
 *    ```jsx
 *    // @highlight-start
 *    <div>
 *      <h1>Heading 1</h1>
 *    </div>
 *    // @highlight-end
 *    ```
 *
 * 3. **Multiline with description**:
 *    ```jsx
 *    // @highlight-start "we add a heading"
 *    <div>
 *      <h1>Heading 1</h1>
 *    </div>
 *    // @highlight-end
 *    ```
 *
 * 4. **Text highlight** - highlights specific text within a line:
 *    ```jsx
 *    <h1>Heading 1</h1> {/* @highlight-text "Heading 1" *\/}
 *    ```
 *
 * 5. **Focus override** - mark a region for padding focus:
 *    ```jsx
 *    <h1>Heading 1</h1> {/* @highlight @focus *\/}
 *    ```
 *
 * Emphasized lines receive a `data-hl` attribute on their `<span class="line">` element.
 * When highlights exist, frames are restructured with `data-frame-type` attributes
 * (`highlighted`, `padding-top`, `padding-bottom`, or omitted for normal).
 * Highlighted frames also receive `data-frame-indent` with the shared indent level.
 *
 * @param options - Optional configuration for padding frames
 * @returns A `SourceEnhancer` function
 *
 * @example
 * ```ts
 * import { createEnhanceCodeEmphasis } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
 *
 * const enhancers = [createEnhanceCodeEmphasis({ paddingFrameMaxSize: 5, focusFramesMaxSize: 8 })];
 * ```
 */
export declare function createEnhanceCodeEmphasis(options?: EnhanceCodeEmphasisOptions): SourceEnhancer;
/**
 * Default source enhancer that adds emphasis to code lines based on `@highlight` comments.
 * Uses no padding frames by default. Use `createEnhanceCodeEmphasis` for configurable padding.
 *
 * @example
 * ```ts
 * import { enhanceCodeEmphasis } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
 *
 * const enhancers = [enhanceCodeEmphasis];
 * ```
 */
export declare const enhanceCodeEmphasis: SourceEnhancer;