@mui/internal-docs-infra

import * as React from 'react'; import type { SetSource } from "./useSourceEditing.mjs"; import type { VariantSource } from "../CodeHighlighter/types.mjs"; import type { FallbackNode } from "../CodeHighlighter/fallbackFormat.mjs"; import { type SourceLineCounts } from "./sourceLineCounts.mjs"; export declare function Pre({ children, className, fileName, bridgeLineMode, language, ref, setSource, shouldHighlight, hydrateMargin, fallback, fallbackLineCounts, expanded, collapseToEmpty, expand, transforming, onTransitionReady, swapTarget, editActivation, onActivate }: { children: VariantSource; className?: string; fileName?: string; bridgeLineMode?: 'focus' | 'total'; language?: string; ref?: React.Ref<HTMLPreElement>; setSource?: SetSource; shouldHighlight?: boolean; hydrateMargin?: string; fallback?: FallbackNode[]; /** * Authoritative line metadata for a string source's framed fallback. Deferred * string sources do not have decoded HAST yet, but their loader-built fallback * already knows whether the collapsed window hides lines. */ fallbackLineCounts?: SourceLineCounts | null; /** * Whether the host has expanded the (collapsible) code block. When `true`, * collapsed-state behaviors such as `minColumn` are disabled so the caret * can move into the indent gutter normally. */ expanded?: boolean; /** * Render-time "collapse to empty": collapse the block to an *empty* window so the * whole block is hidden until expanded. Demotes every collapsed-visible frame * type to its hidden equivalent (`focus`→`focus-unfocused`, * `highlighted`→`highlighted-unfocused`, `padding-*`→`normal`), forces the * block collapsible, and reports `0` focused lines. Orthogonal to `expanded` * — it only changes what the *collapsed* state shows, not whether the block * starts expanded. The precomputed HAST is never mutated. */ collapseToEmpty?: boolean; /** * Called when the user attempts to navigate the caret past the visible * region of a collapsed code block (e.g. `ArrowUp` on the first visible * row, `ArrowDown` on the last). Typically wired to the host's * `expand()` action. */ expand?: () => void; /** * State of an in-flight transform animation, or `null` when settled. * The rendered `<pre>` is annotated with `data-transforming={state}` * so consumer CSS can react. The state machine moves through four * values per swap so the host can hold the `.collapse` bridge at a * static height while the new tree mounts, then release into the * animation once it has painted: * * ``` * ┌──────────────┐ onTransitionReady ┌──────────────┐ * │ 'collapsed' │ ───────────────────▶ │ 'expanding' │ * │ (paused 0) │ │ (anim ↑) │ * └──────────────┘ └──────┬───────┘ * ▲ │ animationend * │ next swap ▼ * ┌──────┴───────┐ onTransitionReady ┌──────────────┐ * │ 'collapsing' │ ◀─────────────────── │ 'expanded' │ * │ (anim ↓) │ │ (paused max) │ * └──────────────┘ └──────────────┘ * ``` * * - `'collapsed'` bridge is paused at 0 height (its closed rest * state) waiting for the outgoing tree to be * ready before animating open. Bridge is rendered * so CSS can hold it closed. * - `'expanding'` bridge is animating from 0 up to the partner * variant's extra height. Outgoing tree's pre-swap * exit window. * - `'expanded'` bridge is paused at the partner-variant height * (its open rest state) waiting for the incoming * tree to be ready before animating closed. * - `'collapsing'` bridge is animating from the open height back to * 0. Incoming tree's post-swap entry window. * * Callers transition `'collapsed' → 'expanding'` and * `'expanded' → 'collapsing'` once `onTransitionReady` fires for the * paused state. The paused values are CSS-side animation gates: the * bridge `.collapse` placeholder is rendered identically for the * paused and active values so consumer styles only need to suppress * the keyframes / transition on the paused selectors. */ transforming?: 'collapsed' | 'expanding' | 'expanded' | 'collapsing' | null; /** * Fired one animation frame after `transforming` enters a paused * value (`'collapsed'` or `'expanded'`). Lets the host transition * to the matching active value (`'expanding'` / `'collapsing'`) * only after the browser has had a paint cycle to flush the new * tree and the `.collapse` bridge into the layout. Without this * gate the active animation can start before the incoming `<Pre>` * has swapped from raw text to highlighted spans, producing a * visible snap mid-animation. * * When `shouldHighlight` is true the callback is held until the * highlighted HAST has committed *and* the IntersectionObserver has * had a chance to fire — i.e. every visible frame has swapped from * fallback text to highlighted spans and the `visibleFrames` map * has stopped changing. One animation frame after that, the * callback runs. * * When `shouldHighlight` is false there is no `.collapse` bridge to * animate, so the callback fires on the next frame instead of * deadlocking the swap waiting for hast/visibility that will never * affect the result. */ onTransitionReady?: () => void; /** * Per-file line counts from the *other* variant participating in an * in-flight variant swap. When set alongside `transforming`, `<Pre>` * appends a bridge `<span class="collapse" data-lines={delta}>` to * the last visible frame (when collapsed) or the last frame overall * (when expanded) so consumer CSS can animate the height delta * between the two variants. The placeholder is only added when the * partner has *more* lines than the currently-rendered tree (i.e. * this `<Pre>` is the shorter side of the swap); otherwise the * rendered hast is returned untouched. * * `null` (or omitted) disables the bridge entirely — useful for * transform-only swaps where `transforming` is set but no variant * swap is in flight. */ swapTarget?: { focusedLines: number; totalLines: number; } | null; /** * Controls when the editing engine loads for an editable block: `'eager'` * (default) loads it as soon as the block is editable; `'interaction'` defers * the load until the user hovers/focuses/clicks the `<pre>`. Ignored when the * block is not editable. Forwarded to `useEditable` as its `activation` config. */ editActivation?: 'eager' | 'interaction'; /** * Fired once when the block first engages for editing. Forwarded to * `useEditable` as its `onActivate` config; `CodeHighlighter` uses it to warm * the live-editing engine, grammars, and worker at the activation moment. */ onActivate?: () => void; }): React.ReactNode;