@mui/internal-docs-infra/useCode/sourceLineCounts.d.mts

MUI Infra - internal documentation creation tools.

import type { VariantSource, VariantCode, Code } from "../CodeHighlighter/types.mjs";
import type { FallbackNode } from "../CodeHighlighter/fallbackFormat.mjs";
export interface SourceLineCounts {
  totalLines: number;
  focusedLines: number;
  collapsible: boolean;
}
/**
 * Extract `{ totalLines, focusedLines }` from any `VariantSource`
 * shape. Reads precomputed metadata when available (`HastRoot.data`)
 * and falls back to counting lines for plain string sources. For
 * string sources, `focusedLines === totalLines` because the
 * `@focus` enhancer never ran. Results are cached by source identity
 * for object payloads so subsequent calls are O(1).
 *
 * Returns zeroes when the source is missing or malformed.
 */
export declare function getSourceLineCounts(source: VariantSource | undefined, fallback?: FallbackNode[]): SourceLineCounts;
export declare function getVariantFileLineCounts(variant: VariantCode, fileName: string): SourceLineCounts | null;
/**
 * Determines whether switching from `fromVariantKey` to `toVariantKey`
 * would visibly shift layout. The `mode` mirrors the transform
 * classifier and is configured via `useCode`'s `variantLayoutShift`
 * option:
 *
 *   - `'all'` — sums `totalLines` across every file (main +
 *     `extraFiles`) in both variants. Layout shift when the totals
 *     differ. Useful when the rendering surface displays the full
 *     variant simultaneously.
 *   - `'selected'` (default) — compares `totalLines` for the
 *     currently-selected file (`selectedFileName`, falling back to
 *     the source variant's main file) between the two variants.
 *     Layout shift when the line counts differ.
 *   - `'focus'` — like `'selected'` but consults `focusedLines`
 *     (the size of the visible window when the surrounding code
 *     block is collapsed) while `expanded === false`. Reverts to
 *     `'selected'`-style behavior when expanded. Recommended for
 *     demos that use `@focus`/`@padding` to collapse to a region.
 *
 * Returns `true` (layout shift) when:
 *   - either variant is missing,
 *   - the selected file is missing from either variant (the file
 *     list itself changes),
 *   - the relevant line count differs between the two variants.
 *
 * Returns `false` for same-variant swaps and when the line counts
 * match.
 */
export declare function variantHasLayoutShift(effectiveCode: Code, fromVariantKey: string | null, toVariantKey: string | null, opts?: {
  mode?: 'all' | 'selected' | 'focus';
  selectedFileName?: string | undefined;
  expanded?: boolean;
}): boolean;
/**
 * Description of a pair of variants whose same-named file has a
 * different `focusedLines` count. Returned by
 * `findVariantFocusedLinesMismatches` so callers can produce
 * actionable error messages without re-walking the variant tree.
 */
export interface VariantFocusedLinesMismatch {
  fileName: string;
  variantA: string;
  variantB: string;
  focusedLinesA: number;
  focusedLinesB: number;
}
/**
 * Walk every variant on `effectiveCode` and collect files that share
 * a name across variants but disagree on `focusedLines`. Used by
 * `useCode`'s `strictMatchingVariantFocusedLines` option to throw
 * with a pointer to the offending variants/file so the demo author
 * can align the `@focus` / `@padding` markers across language
 * variants and avoid coordinated barriers while collapsed.
 *
 * The first variant to declare a given file name is treated as the
 * baseline; every subsequent variant that disagrees produces a
 * mismatch entry paired with the baseline. Returns an empty array
 * when every shared file agrees.
 */
export declare function findVariantFocusedLinesMismatches(effectiveCode: Code): VariantFocusedLinesMismatch[];