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

package/useCode/useEditable.d.mts

@@ -1,110 +1,31 @@
-import { type Position } from "./useEditableUtils.mjs";
+import type { Position } from "./useEditableUtils.mjs";
+import type { Edit, Options } from "./EditableEngine.mjs";
+import { preloadEditingEngine, resetEditingEngineCache } from "./editingEngineCache.mjs";
 export type { Position } from "./useEditableUtils.mjs";
-export interface Options<TPreParseResult = unknown> {
-  disabled?: boolean;
-  indentation?: number;
-  /**
-   * Minimum column the cursor is allowed to occupy on indented lines.
-   *
-   * When set, horizontal arrow navigation skips over the leading whitespace
-   * up to `minColumn` so the caret never lands inside a clipped/hidden
-   * indent region:
-   *
-   * - `ArrowLeft` at column `minColumn` (with that line's first `minColumn`
-   *   characters all whitespace) jumps to the end of the previous line
-   *   instead of stepping into the indent.
-   * - `ArrowRight` at the end of a line jumps to column `minColumn` of the
-   *   next line (when the next line is indented at least that far) instead
-   *   of landing at column 0.
-   *
-   * Useful when the editor is rendered in a horizontally-shifted view (for
-   * example a collapsed code block whose left padding is translated off
-   * screen) where columns below `minColumn` are not visible. Leave
-   * `undefined` for default arrow-key behavior.
-   */
-  minColumn?: number;
-  /**
-   * First row of the visible region. When set, `ArrowUp` on this row and
-   * `ArrowLeft` at the start of this row are blocked (no caret movement)
-   * and `onBoundary` is invoked. Useful when content above the visible
-   * region is hidden and the host wants a chance to reveal it.
-   */
-  minRow?: number;
-  /**
-   * Last row of the visible region. When set, `ArrowDown` on this row and
-   * `ArrowRight` at the end of this row are blocked (no caret movement)
-   * and `onBoundary` is invoked.
-   */
-  maxRow?: number;
-  /**
-   * Called when the user attempts to navigate past `minRow`/`maxRow` via
-   * arrow keys. When `onBoundary` is provided, the navigation is allowed
-   * to proceed natively so the host can react (e.g. expand a collapsed
-   * code block) and the caret continues moving in the now-visible
-   * content. When `onBoundary` is omitted, the navigation is blocked
-   * (caret stays put).
-   */
-  onBoundary?: () => void;
-  /**
-   * CSS selector identifying the elements that represent selectable
-   * "lines" inside the editable. When set, and only while the caret is
-   * actually inside an element matching the selector:
-   *
-   * - `ArrowLeft` at column 0 jumps synchronously to the end of the
-   *   previous line.
-   * - `ArrowRight` at the end of a line jumps synchronously to the start
-   *   of the next line.
-   *
-   * Useful when the editable contains intentionally-empty whitespace
-   * text nodes between block-level children (e.g. newline text nodes
-   * separating `.line` spans inside a `.frame`). Without this, the
-   * browser would place the caret in those gap nodes on horizontal
-   * navigation, making `ArrowLeft`/`ArrowRight` appear to no-op.
-   *
-   * Vertical navigation (`ArrowUp`/`ArrowDown`) is intentionally left to
-   * the browser so wrapped visual lines in `pre-wrap` layouts continue
-   * to behave natively. Gap nodes styled with `line-height: 0` are
-   * skipped by browsers vertically without intervention.
-   *
-   * The selector is matched against the caret's containing element via
-   * `Element.closest`, so non-`.line` render paths (e.g. plain-string
-   * editables) never trigger the wrap behavior.
-   */
-  caretSelector?: string;
-  /**
-   * Optional async pre-parse hook invoked before each `onChange` flush.
-   * When provided, the parser receives the post-edit `text` and caret
-   * `position` plus an `AbortSignal` that fires when a newer keystroke
-   * supersedes this flush. Its resolved value is forwarded as the third
-   * argument to `onChange`, allowing the host to cache an already-parsed
-   * HAST (or any other derived state) keyed off the same source string.
-   *
-   * If `preParse` is omitted, `onChange` runs synchronously inside the
-   * keyup / debounce handler as before. If it is provided, the React
-   * state sync is delayed until the returned promise settles. Structural
-   * edits that need a synchronous re-render (Enter, paste, cut, undo/redo,
-   * programmatic `edit.update`/`edit.insert`, `minColumn` blank-line
-   * collapse) bypass `preParse` and fire `onChange` immediately without
-   * a third argument.
-   */
-  preParse?: (text: string, position: Position, signal: AbortSignal) => Promise<TPreParseResult>;
-}
-export interface Edit {
-  /** Replaces the entire content of the editable while adjusting the caret position. */
-  update(content: string): void;
-  /** Inserts new text at the caret position while deleting text in range of the offset (which accepts negative offsets). */
-  insert(append: string, offset?: number): void;
-  /** Positions the caret where specified */
-  move(pos: number | {
-    row: number;
-    column: number;
-  }): void;
-  /** Returns the current editor state, as usually received in onChange */
-  getState(): {
-    text: string;
-    position: Position;
-  };
-}
+export type { Edit, Options } from "./EditableEngine.mjs";
+export type { EditingEngineLoader } from "./editingEngineCache.mjs";
+/**
+ * Eagerly loads the editing engine and primes the shared cache so the next
+ * editable block attaches synchronously instead of after a load round-trip.
+ * Optional — `useEditable` loads on demand anyway. Pass the provider's
+ * `editingEngineLoader` to share its deduplication.
+ */
+export declare const preloadEditableEngine: typeof preloadEditingEngine;
+/**
+ * Clears the shared editing-engine cache so the next editable block resolves its
+ * loader from scratch. Intended for tests that exercise the cold path.
+ */
+export declare const resetEditableEngineCache: typeof resetEditingEngineCache;
+/**
+ * The lightweight, always-mounted shell for live code editing. Owns the editing
+ * state/refs and a stable `edit` proxy; the heavy runtime is loaded on demand
+ * from `./EditableEngine` and `contentEditable` is applied only once it resolves.
+ *
+ * The host element (`elementRef.current`) is expected to be **stable for the
+ * lifetime of the hook** once the block is editable: the engine attaches once
+ * and its setup effect does not re-run on a node swap, so a caller that replaces
+ * the bound element in place would leave `contentEditable` on the stale node.
+ */
 export declare const useEditable: <TPreParseResult = unknown>(elementRef: {
   current: HTMLElement | undefined | null;
 }, onChange: (text: string, position: Position, preParseResult?: TPreParseResult) => void, opts?: Options<TPreParseResult>) => Edit;

package/useCode/useEditable.integration.browser.d.mts

@@ -0,0 +1 @@
+export {};