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

MUI Infra - internal documentation creation tools.

import type { VariantSource, VariantCode, Code, SourceComments } from "../CodeHighlighter/types.mjs";
export interface TransformedFile {
  name: string;
  originalName: string;
  source: VariantSource;
  /**
   * Comments map shifted onto the transformed source's line numbering.
   * Set only when the variant supplied a `comments` map for this file;
   * entries whose source line was wiped by the transform are dropped.
   */
  comments?: SourceComments;
}
export interface TransformedFiles {
  files: TransformedFile[];
  filenameMap: {
    [originalName: string]: string;
  };
}
/**
 * Pure function to get available transforms from effective code data.
 *
 * Variant-level `transforms` is a manifest produced by `splitTransformsForEmbed`
 * (or by the legacy `Transforms` shape with deltas, for back-compat). Only
 * entries that produced a real source delta are reported here — rename-only
 * entries (manifest entries with `hasDelta: false`, kept around so the
 * runtime can still apply the rename based on user preference) are filtered
 * out so the transform toggle stays hidden when nothing meaningful changes.
 *
 * @param effectiveCode - The effective code object containing all variants
 * @param selectedVariantKey - The currently selected variant key
 * @returns Array of available transform keys (toggle-visible only)
 */
export declare function getAvailableTransforms(effectiveCode: Code, selectedVariantKey: string): string[];
/**
 * Like `getAvailableTransforms` but also includes rename-only entries
 * (manifest entries with `hasDelta: false`). Used by the transform
 * resolution path so a stored preference can still apply a rename even
 * when its toggle is hidden because no actual delta exists.
 *
 * @param effectiveCode - The effective code object containing all variants
 * @param selectedVariantKey - The currently selected variant key
 * @returns Array of all applicable transform keys
 */
export declare function getApplicableTransforms(effectiveCode: Code, selectedVariantKey: string): string[];
/**
 * Determines whether applying `transformKey` to `variant` would introduce
 * `.collapse` placeholders into the rendered hast tree — i.e. whether the
 * swap is layout-affecting and must run through the coordinated barrier.
 *
 * Reads the precomputed `hasCollapse` / `hasCollapseInFocus` flags
 * stored on each transform entry by the pipeline (`diffHast` sets them
 * directly, `splitTransformsForEmbed` propagates them onto the
 * manifest). No tree walking or delta decompression happens at runtime.
 *
 * The `mode` option controls *which* file's transform entry is consulted:
 *
 *   - `'selected'` (default) — Consults only the transform map for the
 *     file identified by `selectedFileName` (or `variant.transforms`
 *     when `selectedFileName === variant.fileName`). When
 *     `selectedFileName` is omitted, treats the variant's main file
 *     (`variant.fileName`) as the selection.
 *   - `'all'` — Iterates every transform map on the variant
 *     (`variant.transforms` + each `extraFiles[*].transforms`) and
 *     returns `true` if any one has `hasCollapse: true`. Useful for
 *     callers that render multiple files simultaneously and need to
 *     coordinate a swap whenever *any* file would shift.
 *   - `'focus'` — Like `'selected'`, but consults
 *     `hasCollapseInFocus` instead of `hasCollapse` whenever
 *     `expanded === false`. Lets consumers skip the coordinated
 *     barrier for transforms whose `.collapse` insertion lands
 *     outside the initially-visible region of a collapsed code block.
 *
 * Falls back to a conservative phase 1 classification for legacy
 * payloads that carry `hasDelta: true` without the precomputed flag —
 * i.e. transforms produced by an older build that predates
 * `hasCollapse`, or constructed by a direct caller bypassing the
 * pipeline. For `hasCollapseInFocus`, entries that lack the field fall
 * back to the value of `hasCollapse` (matching the embed-side default).
 *
 * Returns `false` when every consulted entry has `hasCollapse: false`
 * (or `hasCollapseInFocus: false` in focus mode while collapsed), is
 * rename-only, is absent, or the variant is `null`.
 *
 * @param variant - The variant whose transforms to inspect.
 * @param transformKey - The transform key to classify, or `null`.
 * @param opts - Optional mode + selected-file + expanded context.
 */
export declare function transformHasCollapsePlaceholder(variant: VariantCode | null, transformKey: string | null, opts?: {
  mode?: 'all' | 'selected' | 'focus';
  selectedFileName?: string | undefined;
  expanded?: boolean;
}): boolean;
/**
 * Description of a single transform entry that carries
 * `hasCollapseInFocus: true`. Returned by
 * `findCollapseInFocusTransforms` so callers can produce actionable
 * error messages without re-walking the variant tree.
 */
export interface CollapseInFocusOffender {
  variantName: string;
  fileName: string;
  transformKey: string;
}
/**
 * Walk every variant on `effectiveCode` and collect transform entries
 * whose precomputed `hasCollapseInFocus` flag is `true` — i.e. the
 * collapse placeholder introduced by the transform lands inside the
 * focus region that is visible while the surrounding code block is
 * un-expanded.
 *
 * Used by `useCode`'s `strictCollapseInFocus` option to throw with a
 * pointer to the offending variant/file/transform so the demo author
 * can narrow the `@focus` region (or the transform's edit range) until
 * the placeholder lands outside the visible window.
 *
 * Walks main files (`variant.transforms`) and `extraFiles[*].transforms`.
 * Returns an empty array when no entry has the flag set.
 */
export declare function findCollapseInFocusTransforms(effectiveCode: Code): CollapseInFocusOffender[];
/**
 * Decide whether the rendered `<Pre>` should emit highlighted spans on
 * this render. Three gates compose:
 *
 * 1. `highlightReady` — the render-side readiness gate published by
 *    `CodeHighlighterClient`. `false` while the highlight trigger
 *    (`hydration` / `idle` / `visible`) hasn't fired yet *or* the
 *    sync `parseCode` pass hasn't resolved. The precomputed HAST on
 *    the published `code` would render highlighted spans on first
 *    paint otherwise — defeating the deferred trigger. Treated as
 *    `true` when undefined so legacy/test consumers without a
 *    surrounding context default to rendering highlighted.
 * 2. `deferHighlight` — the narrower pipeline-level signal published
 *    while the incoming variant's parse / transform deltas are still
 *    in flight. Always wins: if the tree isn't ready, highlighting
 *    can't happen.
 * 3. `pendingBootstrap` — set while a stored-preference variant swap
 *    is queued behind the initial mount. Suppresses the *outgoing*
 *    tree's highlighting so we don't burn cycles painting spans the
 *    user is about to swap away from.
 *
 * The bootstrap gate is skipped when `highlightAfter === 'init'`:
 * - the precomputed HAST already carries the spans (no "wasted work"),
 *   and
 * - leaving it on causes the *incoming* variant to render as plain
 *   text for the render between `pendingBootstrap` flipping and the
 *   bootstrap commit landing, producing a visible flash of unhighlighted
 *   code on first-paint variant swaps.
 */
export declare function shouldHighlightForRender(args: {
  deferHighlight: boolean | undefined;
  highlightReady?: boolean | undefined;
  pendingBootstrap: boolean;
  highlightAfter: 'init' | 'hydration' | 'idle' | undefined;
}): boolean;