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

package/useCode/EditingEngine.d.mts

@@ -0,0 +1,13 @@
+/**
+ * The single live-editing engine chunk. Co-locates the two pieces an editable
+ * block always needs together — the contentEditable runtime + keyboard/paste/
+ * caret handlers (`createEditableEngine`, which pulls `react-dom` and the DOM
+ * utilities) and the edit-time source manipulation (`analyzeSource`,
+ * `shiftComments`, `toControlledCode`) — so the bundler emits ONE chunk for both
+ * instead of two. Importing this module is heavy; it is only ever reached
+ * through the `editingEngineLoader` accessor (eager `CodeProvider` bundles it;
+ * `CodeProviderLazy` code-splits it) or the dynamic import in
+ * `./editingEngineCache`, so a read-only block never pulls it in.
+ */
+export { createEditableEngine } from "./EditableEngine.mjs";
+export { analyzeSource, shiftComments, toControlledCode } from "./SourceEditingEngine.mjs";

package/useCode/EditingEngine.mjs

@@ -0,0 +1,14 @@
+/**
+ * The single live-editing engine chunk. Co-locates the two pieces an editable
+ * block always needs together — the contentEditable runtime + keyboard/paste/
+ * caret handlers (`createEditableEngine`, which pulls `react-dom` and the DOM
+ * utilities) and the edit-time source manipulation (`analyzeSource`,
+ * `shiftComments`, `toControlledCode`) — so the bundler emits ONE chunk for both
+ * instead of two. Importing this module is heavy; it is only ever reached
+ * through the `editingEngineLoader` accessor (eager `CodeProvider` bundles it;
+ * `CodeProviderLazy` code-splits it) or the dynamic import in
+ * `./editingEngineCache`, so a read-only block never pulls it in.
+ */
+
+export { createEditableEngine } from "./EditableEngine.mjs";
+export { analyzeSource, shiftComments, toControlledCode } from "./SourceEditingEngine.mjs";

package/useCode/Pre.browser.mjs

@@ -6,6 +6,7 @@ import { afterEach, beforeAll, describe, expect, it } from 'vitest';
 import { createParseSource } from "../pipeline/parseSource/index.mjs";
 import { enhanceCodeEmphasis } from "../pipeline/enhanceCodeEmphasis/index.mjs";
 import { Pre } from "./Pre.mjs";
+import { preloadEditableEngine } from "./useEditable.mjs";
 import { jsx as _jsx } from "react/jsx-runtime";
 const FILE_NAME = 'CheckboxBasic.tsx';
 const INITIAL_SOURCE = ["import * as React from 'react';", "import { Checkbox } from '@/components/Checkbox';", '', 'export default function CheckboxBasic() {', '  return (', '    <div>', '      <Checkbox defaultChecked />', "      <p style={{ color: '#CA244D' }}>Type Whatever You Want Below</p>", '    </div>', '  );', '}'].join('\n');
@@ -16,6 +17,9 @@ const HIGHLIGHT_COMMENTS = {
 let parseSource;
 beforeAll(async () => {
   parseSource = await createParseSource();
+  // `<Pre>`'s editable path loads its editing engine on demand; warm it so
+  // editable renders below attach contentEditable synchronously (within `act`).
+  await preloadEditableEngine();
 });
 function createHighlightedSource(source) {
   const root = parseSource(source, FILE_NAME);
@@ -153,7 +157,7 @@ describe('Pre - browser', () => {
   it('edits correctly when surrounding frames are not hast-rendered (mixed visibility)', async () => {
     // Build a tall source with two well-separated highlight regions and a
     // long non-emphasised middle. The middle frame is `'normal'` (not in
-    // `INITIAL_VISIBLE_FRAME_TYPES`), so it starts as plain text and only
+    // `COLLAPSED_VISIBLE_FRAME_TYPES`), so it starts as plain text and only
     // hydrates if the `IntersectionObserver` reports it as visible. Most
     // viewports won't reach the bottom highlight either, leaving it
     // un-hydrated. We verify editing in a hydrated frame still produces a

package/useCode/Pre.d.mts

@@ -1,32 +1,61 @@
 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,
-  expand
+  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
@@ -34,4 +63,101 @@ export declare function Pre({
    * `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;