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

MUI Infra - internal documentation creation tools.

import * as React from 'react';
import type { Code, VariantCode } from "../CodeHighlighter/types.mjs";
import { type TransitionPhase } from "./useTransitionPhase.mjs";
interface UseVariantSelectionProps {
  effectiveCode: Code;
  initialVariant?: string;
  variantType?: string;
  mainSlug?: string;
  saveHashVariantToLocalStorage?: 'on-load' | 'on-interaction' | 'never';
  /**
   * Mode passed to `variantHasLayoutShift` to classify variant swaps
   * as layout-affecting (phase 1, coordinated) versus non-layout
   * (phase 2). See `useCode`'s `variantLayoutShift` option for
   * details. Defaults to `'selected'`.
   */
  variantLayoutShift?: 'all' | 'selected' | 'focus';
  /**
   * Currently-selected file name. Required for the `'selected'` and
   * `'focus'` `variantLayoutShift` modes; ignored by `'all'`.
   */
  selectedFileName?: string | undefined;
  /**
   * Whether the surrounding code block is currently expanded.
   * Consulted only by `variantLayoutShift: 'focus'`.
   */
  expanded?: boolean;
  /**
   * When set to a positive number, the *swap* of the rendered tree to
   * the newly-selected variant is delayed by this many milliseconds so
   * consumers can run an exit animation on the outgoing tree before
   * the incoming tree replaces it. `selectedVariantKey` always
   * updates synchronously so UI controls (tabs, dropdowns) reflect
   * the change immediately; the lag is only visible on the rendered
   * `<Pre>` content, which stays on `committedVariantKey` until the
   * delay elapses. While the swap is pending or just-committed,
   * `variantSwappingPhase` is non-null and the rendered `<pre>` is
   * annotated with `data-transforming` so CSS can react.
   */
  variantSwapDelay?: number;
  /**
   * When `true`, holds the coordinator barrier open via the engine's
   * `preload` slot until the highlighter pipeline (sync `parseCode`
   * + async `computeHastDeltas`) has finished, so the incoming
   * variant tree always paints with highlighting applied instead of
   * snapping to it a frame later. Plumbed in from
   * `CodeHighlighterContext.deferHighlight`; see `useHighlightGate`.
   */
  deferHighlight?: boolean;
}
export interface UseVariantSelectionResult {
  variantKeys: string[];
  selectedVariantKey: string;
  selectedVariant: VariantCode | null;
  /**
   * Engine-committed variant key. Lags `selectedVariantKey` by
   * `variantSwapDelay` ms when a delay is configured and a swap is
   * in flight, otherwise equal to `selectedVariantKey`. Consumers
   * that render the variant's file tree should key off this value
   * so the outgoing tree stays put while the pre-swap animation
   * window plays out.
   */
  committedVariantKey: string;
  /**
   * Variant resolved from `committedVariantKey`. See
   * `committedVariantKey` for the lag semantics. `null` when the
   * committed key doesn't resolve to a fully-loaded variant entry.
   */
  committedVariant: VariantCode | null;
  /**
   * State of the in-flight variant-swap animation, or `null` when
   * settled. Always `null` when `variantSwapDelay` is not set or is
   * `0`. Mirrors `useTransformManagement`'s `transformingPhase`.
   *
   * Each swap progresses through up to four states, gated on
   * `notifyVariantTransitionReady` calls from the rendered `<Pre>`:
   *
   *   - `'collapsed'`  pre-swap paused. Outgoing tree is rendered;
   *                    the bridge `.collapse` placeholder is held at
   *                    0 height. Waiting for one paint cycle before
   *                    releasing into the expand animation.
   *   - `'expanding'`  pre-swap active. The bridge animates from 0
   *                    up to the incoming variant's extra line
   *                    count. Outgoing tree still rendered.
   *   - `'expanded'`   post-swap paused. Incoming tree is now
   *                    rendered; the bridge is held at the outgoing
   *                    variant's extra height. Waiting for the new
   *                    tree's HAST to paint before releasing.
   *   - `'collapsing'` post-swap active. The bridge animates from
   *                    the outgoing variant's extra height back
   *                    down to 0.
   */
  variantSwappingPhase: TransitionPhase;
  /**
   * The "other" variant key participating in the in-flight swap:
   *   - During `'collapsed'` / `'expanding'`: the incoming variant
   *     (the user's intent target, equal to `selectedVariantKey`).
   *   - During `'expanded'` / `'collapsing'`: the outgoing variant
   *     we just transitioned away from, captured at the commit
   *     boundary.
   *   - `null` when no swap is in flight.
   *
   * Consumers use this to look up the partner variant's per-file
   * line counts so `<Pre>` can append a bridge `.collapse`
   * placeholder when the partner has more visible lines than the
   * currently-rendered (committed) variant.
   */
  swapPartnerVariantKey: string | null;
  /**
   * Target of an in-flight variant swap that is still waiting on slow
   * peers past the coordinator's grace window. `undefined` when no
   * swap is pending. Only populated on the demo that originated the
   * change; always `undefined` on peers and when no coordinator is
   * configured.
   */
  pendingVariantKey: string | undefined;
  /**
   * `true` while a stored-preference bootstrap swap is known to be
   * in flight: a valid `storedValue` exists, differs from the
   * currently-committed variant, and the engine has not yet
   * committed past the initial mount value. Releases on the first
   * commit (whether the bootstrap landed or a racing user click
   * superseded it) so consumers can defer expensive work — most
   * notably suppressing the outgoing initial variant's highlight
   * render — without leaking suppression into normal interactive
   * swaps.
   */
  pendingBootstrap: boolean;
  /**
   * 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.
   */
  notifyVariantTransitionReady: () => void;
  selectVariant: React.Dispatch<React.SetStateAction<string | null>>;
  selectVariantProgrammatic: React.Dispatch<React.SetStateAction<string>>;
  saveVariantToLocalStorage: (variant: string) => void;
  hashVariant: string | null;
}
export declare function useVariantSelection({
  effectiveCode,
  initialVariant,
  variantType,
  mainSlug,
  saveHashVariantToLocalStorage,
  variantLayoutShift,
  selectedFileName,
  expanded,
  variantSwapDelay,
  deferHighlight
}: UseVariantSelectionProps): UseVariantSelectionResult;
export {};