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

MUI Infra - internal documentation creation tools.

import type { Code, VariantCode } from "../CodeHighlighter/types.mjs";
import type { CreateTransformedFiles } from "./TransformEngine.mjs";
import { preloadTransformEngine, resetTransformEngineCache } from "./transformEngineCache.mjs";
import { type CodeHighlighterContextType } from "../CodeHighlighter/CodeHighlighterContext.mjs";
import { type TransitionPhase } from "./useTransitionPhase.mjs";
export { preloadTransformEngine, resetTransformEngineCache };
interface UseTransformManagementProps {
  context?: CodeHighlighterContextType;
  effectiveCode: Code;
  selectedVariantKey: string;
  selectedVariant: VariantCode | null;
  initialTransform?: string;
  /**
   * When set to a positive number, the *swap* of `transformedFiles` to the
   * newly-selected transform is delayed by this many milliseconds so
   * consumers can run an exit animation on the currently-rendered tree
   * (notably the collapsed-lines placeholders) before the new tree is
   * committed.
   *
   * `selectedTransform` always updates synchronously to the chosen value
   * so the UI control (radio, toggle, …) reflects the change immediately,
   * whether it originated from a user click in *this* demo or from an
   * external broadcast (another demo on the page, another tab, or an
   * `availableTransforms` / `initialTransform` re-resolution). While the
   * swap is pending or just-committed, `transformingPhase` is non-null
   * and consumers should mark the rendered `<pre>` with
   * `data-transforming={phase}` so CSS can react.
   */
  transformDelay?: number;
  /**
   * Mode passed to `transformHasCollapsePlaceholder` to classify swaps
   * as layout-affecting (phase 1, coordinated) versus non-layout
   * (phase 2). See `useCode`'s `transformLayoutShift` option for
   * details. Defaults to `'all'` to preserve the historical behavior
   * when `selectedFileName` isn't supplied.
   */
  transformLayoutShift?: 'all' | 'selected' | 'focus';
  /**
   * Currently-selected file name. Required for the `'selected'` and
   * `'focus'` `transformLayoutShift` modes; ignored by `'all'`.
   */
  selectedFileName?: string | undefined;
  /**
   * Whether the surrounding code block is currently expanded. Consulted
   * only by `transformLayoutShift: 'focus'`.
   */
  expanded?: boolean;
}
export interface UseTransformManagementResult {
  availableTransforms: string[];
  selectedTransform: string | null;
  transformedFiles: ReturnType<CreateTransformedFiles>;
  selectTransform: (transformName: string | null) => void;
  /**
   * State of the in-flight transform animation, or `null` when
   * settled. Always `null` when `transformDelay` is not set or is `0`.
   *
   * Each swap progresses through up to four states, gated on
   * `notifyTransformTransitionReady` calls from the rendered `<Pre>`:
   *
   *   - `'collapsed'`  pre-swap paused. Outgoing transformed tree is
   *                    rendered; the bridge `.collapse` placeholder is
   *                    held at 0 height. Set briefly during the pre-
   *                    swap delay for `transform → null` and
   *                    `transform → transform` (first half).
   *   - `'expanding'`  pre-swap active. The bridge animates from 0
   *                    up to the incoming tree's extra line count.
   *   - `'expanded'`   post-swap paused. Incoming tree is rendered;
   *                    the bridge is held at the outgoing tree's
   *                    extra height. Set during the post-swap window
   *                    for `null → transform` and `transform →
   *                    transform` (second half).
   *   - `'collapsing'` post-swap active. The bridge animates from
   *                    the outgoing tree's extra height back to 0.
   */
  transformingPhase: TransitionPhase;
  /**
   * Callback the rendered `<Pre>` invokes (via its `onTransitionReady`
   * prop) once it has painted the new tree at a paused phase value.
   * Triggers the transition from `'collapsed' → 'expanding'` (pre-swap)
   * or `'expanded' → 'collapsing'` (post-swap). Holding the active
   * value off until the new tree has had a paint cycle prevents the
   * keyframe / transition from running against raw-text spans that
   * haven't yet been upgraded to highlighted HAST.
   */
  notifyTransformTransitionReady: () => void;
  /**
   * Target of an in-flight transform swap that is waiting on slow
   * peers past the coordinator's grace window (`gracePeriodMs`,
   * default 300ms beyond `transformDelay`). `undefined` when no swap
   * is pending. Otherwise mirrors the shape of `selectedTransform`:
   * `null` for a pending swap back to the un-transformed original,
   * or the transform name for a pending swap to that transform.
   * The commit is *not* force-resolved at this boundary — the barrier
   * keeps waiting up to `ultimateTimeoutMs` (10s) — so consumers can
   * use this value to render a transient loading indicator. Only
   * populated on the demo that originated the change; always
   * `undefined` on peers and when no coordinator is configured.
   */
  pendingTransform: string | null | undefined;
}
/**
 * Hook for managing code transforms and their application
 * Uses the useLocalStorage hook for local storage persistence of transform preferences
 */
export declare function useTransformManagement({
  context,
  effectiveCode,
  selectedVariantKey,
  selectedVariant,
  initialTransform,
  transformDelay,
  transformLayoutShift,
  selectedFileName,
  expanded
}: UseTransformManagementProps): UseTransformManagementResult;