@mui/internal-docs-infra/pipeline/loadIsomorphicCodeVariant/findExpandingRanges.d.mts

MUI Infra - internal documentation creation tools.

import type { SourceComments } from "../../CodeHighlighter/types.mjs";
/**
 * Sentinel substrings a transformer puts into its returned `comments`
 * map to mark newly-added lines that should animate in (when the
 * transform is applied) or out (when it is reverted). The markers are
 * metadata only — they never appear in the rendered source text.
 * Detection is substring-based so callers can decorate them however
 * reads best alongside any neighbouring comments
 * (e.g. `'// @expanding-start (api key)'`).
 *
 * Two flavours:
 * - `@expanding-start` / `@expanding-end` delimit a contiguous,
 *   multi-line range (inclusive on both ends).
 * - `@expanding` on its own marks a single added line — equivalent
 *   to a same-line start+end pair, but easier to write when the
 *   addition is just one line.
 */
export declare const EXPANDING_START_MARKER = "@expanding-start";
export declare const EXPANDING_END_MARKER = "@expanding-end";
export declare const EXPANDING_SINGLE_MARKER = "@expanding";
/**
 * Scans a `SourceComments` map for `@expanding`, `@expanding-start`,
 * and `@expanding-end` markers and returns the inclusive 1-indexed
 * line ranges they delimit.
 *
 * Pairing rule: walk lines in ascending order. A standalone
 * `@expanding` immediately produces a single-line `[line, line]`
 * range. For ranges, the first `@expanding-start` opens a range and
 * the next `@expanding-end` closes it. Unpaired range markers (a
 * start with no matching end, or an end with no preceding start) are
 * silently dropped — the most likely cause is a transformer
 * mid-iteration and the safe behaviour is "no animation for that
 * fragment" rather than either crashing or animating an unbounded
 * region. Nested or overlapping ranges are not supported; a second
 * `@expanding-start` before the previous one is closed replaces the
 * open range's start.
 *
 * @param comments - The remapped 1-indexed comments map.
 * @returns Sorted `[startLine, endLine]` pairs (inclusive on both
 *   ends). Returns an empty array when `comments` is `undefined`,
 *   empty, or contains no markers.
 */
export declare function findExpandingRanges(comments: SourceComments | undefined): Array<[number, number]>;
/**
 * Fast yes/no check used by the pipeline's layout-shift classifier so
 * it can avoid materialising the full `findExpandingRanges` array when
 * all it needs is a boolean. Equivalent to
 * `findExpandingRanges(...).length > 0` but short-circuits on the first
 * matched marker.
 */
export declare function hasExpandingRanges(comments: SourceComments | undefined): boolean;