@mui/internal-docs-infra 0.11.1-canary.8 → 0.11.1

package/useCode/useTransformManagement.d.mts

@@ -1,18 +1,103 @@
 import type { Code, VariantCode } from "../CodeHighlighter/types.mjs";
-import { createTransformedFiles } from "./useCodeUtils.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<typeof createTransformedFiles>;
+  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
@@ -23,6 +108,9 @@ export declare function useTransformManagement({
   effectiveCode,
   selectedVariantKey,
   selectedVariant,
-  initialTransform
-}: UseTransformManagementProps): UseTransformManagementResult;
-export {};
+  initialTransform,
+  transformDelay,
+  transformLayoutShift,
+  selectedFileName,
+  expanded
+}: UseTransformManagementProps): UseTransformManagementResult;