@mui/internal-docs-infra

/** * Metadata for an emphasized line. */ export interface EmphasisMeta { /** Optional description for this emphasis */ description?: string; /** Position: 'single' for single-line, 'start'/'end' for multiline range bounds, undefined for middle */ position?: 'single' | 'start' | 'end'; /** Whether this is a strong emphasis (description ended with !) */ strong?: boolean; /** For text highlighting: the specific texts to highlight within the line */ highlightTexts?: string[]; /** Whether this line's region is the focused region (for padding) */ focus?: boolean; /** Whether the line itself should receive data-hl. True for highlight directives and false for focus-only directives. */ lineHighlight: boolean; /** How many containing highlight ranges wrap this line (used for mark data-hl propagation) */ containingRangeDepth?: number; /** Optional per-directive padding override for this region */ paddingFrameMaxSize?: number; /** Optional per-directive focus max size override for this region */ focusFramesMaxSize?: number; /** * True when the overrides were propagated from a multiline range * rather than set by an explicit per-line directive. * Explicit overrides take precedence over propagated ones in regions. */ propagatedOverride?: boolean; } /** * A range of lines that forms a frame in the output. */ export interface FrameRange { /** First line number (1-based, inclusive) */ startLine: number; /** Last line number (1-based, inclusive) */ endLine: number; /** The type of frame */ type: 'normal' | 'padding-top' | 'highlighted' | 'highlighted-unfocused' | 'focus' | 'focus-unfocused' | 'padding-bottom' | 'comment'; /** Index of the highlighted region this frame belongs to. Present on region-type frames. */ regionIndex?: number; /** * Present on frames created by splitting an oversized region via `focusFramesMaxSize`. * - `'visible'` — the focused window kept visible when collapsed. * - `'hidden'` — the overflow portion hidden when collapsed. */ truncated?: 'visible' | 'hidden'; } /** * Options for the enhance code emphasis factory. */ export interface EnhanceCodeEmphasisOptions { /** * Maximum number of padding lines above and below the focused highlight region. * Padding frames provide surrounding context for the highlighted code. * Set to 0 or omit to disable padding frames. */ paddingFrameMaxSize?: number; /** * Maximum total number of lines in the focus area (padding-top + focused region + padding-bottom). * When the region fits within this limit, padding sizes are reduced so the total focus area * fits. The remainder after subtracting the region size is split: floor(remainder/2) for * padding-top and ceil(remainder/2) for padding-bottom. * When the region exceeds this limit, a focused window is taken from the start of the * region, and the remaining overflow lines are marked as unfocused. * @default 12 */ focusFramesMaxSize?: number; /** * How to handle a focused region that exceeds `focusFramesMaxSize`. * * - `'truncate'` (default) — keep the first `focusFramesMaxSize` lines visible * as a window and hide the overflow. * - `'hide'` — produce no visible-window frame at all: the block collapses to * nothing (`focusedLines === 0`) while staying `collapsible`, so the collapsed * state is empty and expanding reveals the whole source. * * Applies to every focus trigger — an oversized `@highlight` region, an * oversized `@focus` / `@focus-start` region, and the auto-focus-from-line-1 * case (no emphasis comments) when the source exceeds `focusFramesMaxSize`. * Regions that fit within `focusFramesMaxSize` are unaffected. * * @default 'truncate' */ oversizedFocus?: 'truncate' | 'hide'; /** * When `true`, throws an error if a `@highlight-text` match has to be * fragmented across element boundaries (producing `data-hl-part` spans). * Wrapping multiple complete elements in a single `data-hl` span is still * allowed — only boundary-straddling matches are rejected. */ strictHighlightText?: boolean; /** * When `true`, emits a `data-frame-indent` attribute on highlighted/focus * region frames indicating the shared leading indent level. Consumers can * use this to visually shift collapsible regions horizontally when * surrounding context lines are hidden. Off by default since most demos * don't need it and it bloats the rendered HTML. * * Indent and padding are alternatives for conveying surrounding context. * Combining this with the `paddingFrameMaxSize` option throws (configure one * or the other); a per-region `@padding` directive in the source is allowed * and ignored while this is set. * @default false */ emitFrameIndent?: boolean; } /** Default max number of lines kept in focus when not explicitly configured. */ export declare const DEFAULT_FOCUS_FRAMES_MAX_SIZE = 12; /** * Calculates frame ranges for the code block based on emphasized lines. * * This is a pure function that operates on line numbers — no HAST traversal. * It groups consecutive highlighted lines into regions, determines the focused * region (first by default, or the one with `focus: true`), computes padding * for the focused region, and returns an ordered array of frame ranges covering * all lines 1 through totalLines. * * @param emphasizedLines - Map of line numbers to their emphasis metadata * @param totalLines - Total number of lines in the code block * @param options - Optional padding configuration * @param normalFrameMaxSize - Maximum lines per normal frame. Read from `hast.data.frameSize` * (set by `starryNightGutter` when it splits a tree into multiple frames) so that emphasis * reframing matches the original gutter split size. * @returns Ordered array of frame ranges covering all lines */ export declare function calculateFrameRanges(emphasizedLines: Map<number, EmphasisMeta>, totalLines: number, options?: EnhanceCodeEmphasisOptions, normalFrameMaxSize?: number): FrameRange[];