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

MUI Infra - internal documentation creation tools.

import type { ElementContent } from 'hast';
import type { HastRoot, VariantSource, Transforms, SourceComments } from "../../CodeHighlighter/types.mjs";
import type { FallbackNode } from "../../CodeHighlighter/fallbackFormat.mjs";
/**
 * Decodes a `VariantSource` to a live `HastRoot` (or `null` for string /
 * unrecognized shapes).
 */
export type DecodeHastSource = (source: VariantSource | null | undefined, fallback?: FallbackNode[]) => HastRoot | null;
/** Rebuilds a frame's lazy fallback from its post-transform spans. */
export type FrameFallbackFromSpans = (spans: ElementContent[]) => ElementContent[];
/**
 * Hast helpers the transform core needs but must NOT import statically, so the
 * client `useCode/TransformEngine` chunk doesn't pull `decodeHastSource` /
 * `frameFallbackFromSpans` (and their `hastDecompress` dependency). The
 * always-loaded `useCode` shell already has both and injects them; the
 * standalone `applyCodeTransform` wrapper binds the built-ins for server/build
 * callers.
 */
export interface TransformRuntimeDeps {
  decode: DecodeHastSource;
  frameFallbackFromSpans: FrameFallbackFromSpans;
}
/**
 * Applies a specific transform to a variant source and returns the transformed source
 * along with a remapped copy of the supplied `comments` map (when any) shifted to
 * line up with the renumbered `dataLn` values in the transformed tree.
 *
 * **Return shape, by input shape:**
 * - `string` input → `string` output.
 * - HAST-backed input (`HastRoot`, `{ hastJson }`, or `{ hastCompressed }`)
 *   that actually applies a delta → live `HastRoot` output, regardless of the
 *   input wire shape. The serialized wire shapes are *not* re-emitted: every
 *   downstream reader in this package funnels through `decodeHastSource`,
 *   which accepts a live root directly, so re-stringifying / re-compressing
 *   here would just be undone by the next consumer (and would defeat the
 *   shared decode cache, which is keyed on payload identity). Callers
 *   outside this package that need a serialized payload must re-encode
 *   the returned root themselves.
 * - Rename-only entries (`hasDelta: false`) and unknown-transform passthrough
 *   return the original `source` object untouched (same shape and identity).
 *
 * @param source - The original variant source (string, `HastRoot`,
 *   `{ hastJson }`, or `{ hastCompressed }`)
 * @param transforms - Object containing all available transforms
 * @param transformKey - The key of the specific transform to apply
 * @param deps - Hast helpers (`decode`, `frameFallbackFromSpans`) injected so
 *   this module never statically imports them; see {@link TransformRuntimeDeps}.
 * @param comments - Optional 1-indexed comment map keyed by the source's original
 *   line numbers. Returned shifted so each entry now sits on the line its
 *   original source line occupies in the transformed tree; entries whose
 *   source line was wiped by the transform are dropped.
 * @returns `{ source, comments }` where `source` is the transformed variant
 *   source (see "Return shape" above) and `comments` is the remapped map
 *   (or `undefined` when no comments were passed).
 * @throws Error if the transform key doesn't exist or patching fails
 */
export declare function applyCodeTransformWithComments(source: VariantSource, transforms: Transforms, transformKey: string, deps: TransformRuntimeDeps, comments?: SourceComments, fallback?: FallbackNode[]): {
  source: VariantSource;
  comments?: SourceComments;
};
/**
 * Applies multiple transforms to a variant source in sequence. Comments are
 * shifted by each transform in turn so the returned map lines up with the
 * fully-transformed source.
 *
 * @param source - The original variant source
 * @param transforms - Object containing all available transforms
 * @param transformKeys - Array of transform keys to apply in order
 * @param deps - Hast helpers (`decode`, `frameFallbackFromSpans`) injected so
 *   this module never statically imports them; see {@link TransformRuntimeDeps}.
 * @param comments - Optional 1-indexed comment map for the original source
 * @returns `{ source, comments }` after applying every transform in order
 * @throws Error if any transform key doesn't exist or patching fails
 */
export declare function applyCodeTransformsWithComments(source: VariantSource, transforms: Transforms, transformKeys: string[], deps: TransformRuntimeDeps, comments?: SourceComments, fallback?: FallbackNode[]): {
  source: VariantSource;
  comments?: SourceComments;
};