@baseline-ui/core 0.62.0 → 0.63.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import React__default, { ReactNode, AriaAttributes, DOMAttributes as DOMAttributes$1, AriaRole, CSSProperties, HTMLAttributeAnchorTarget, HTMLAttributeReferrerPolicy, ClipboardEventHandler, CompositionEventHandler, ReactEventHandler, FormEventHandler, MouseEventHandler, TouchEventHandler, PointerEventHandler, UIEventHandler, WheelEventHandler, AnimationEventHandler, TransitionEventHandler, ReactElement, MouseEvent, FocusEvent, SyntheticEvent, KeyboardEvent as KeyboardEvent$2, JSX, HTMLAttributes, RefObject as RefObject$1, LabelHTMLAttributes, ElementType, JSXElementConstructor, ButtonHTMLAttributes, AnchorHTMLAttributes, InputHTMLAttributes, SVGProps, MutableRefObject, Key as Key$1, Dispatch, SetStateAction, Ref } from 'react';
+import React__default, { ReactNode, AriaAttributes, DOMAttributes as DOMAttributes$1, AriaRole, CSSProperties, HTMLAttributeAnchorTarget, HTMLAttributeReferrerPolicy, ClipboardEventHandler, CompositionEventHandler, ReactEventHandler, FormEventHandler, MouseEventHandler, TouchEventHandler, PointerEventHandler, UIEventHandler, WheelEventHandler, AnimationEventHandler, TransitionEventHandler, ReactElement, MouseEvent, FocusEvent, SyntheticEvent, KeyboardEvent as KeyboardEvent$2, JSX, HTMLAttributes, RefObject as RefObject$1, LabelHTMLAttributes, ElementType, JSXElementConstructor, ButtonHTMLAttributes, AnchorHTMLAttributes, InputHTMLAttributes, SVGProps, MutableRefObject, Key as Key$1, Ref, KeyboardEventHandler, Dispatch, SetStateAction } from 'react';
 import { Theme, Sprinkles } from '@baseline-ui/tokens';
 import { PanelImperativeHandle, PanelProps as PanelProps$1, SeparatorProps as SeparatorProps$2 } from 'react-resizable-panels';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -5755,10 +5755,6 @@ declare function classNames(...args: any[]): string;
 /**
  * Returns the HTMLElement from a string selector, HTMLElement, or React
  * RefObject.
- *
- * @param element - A string selector, HTMLElement, or React RefObject.
- * @param ownerDocument - The document to use for the querySelector call.
- * @returns The HTMLElement or null if not found.
  */
 declare function getHTMLElement(element: string | HTMLElement | React__default.RefObject<HTMLElement> | null | undefined, ownerDocument: Document): HTMLElement | null | undefined;
 interface FontProperties {
@@ -5781,17 +5777,13 @@ interface FontProperties {
  * });
  * ```
  *
- * @param options - The options for calculating the text dimensions.
- * @param options.text - The text to measure.
- * @param options.fontSize - The font size in pixels. Defaults to 16.
- * @param options.fontFamily - The font family. Defaults to 'Arial'.
- * @param options.fontWeight - The font weight. Defaults to 'normal'.
- * @param options.fontStyle - The font style. Defaults to 'normal'.
- * @param options.font - The full font string. Overrides fontSize, fontFamily,
- *   fontWeight, and fontStyle.
+ * @param options.element - A reference element whose owner document is used to
+ *   create the measuring canvas (required for correct results inside iframes).
+ *   Falls back to the global document when omitted.
  */
-declare function getTextDimensions({ text, fontSize, fontFamily, fontWeight, fontStyle, font, }: {
+declare function getTextDimensions({ text, fontSize, fontFamily, fontWeight, fontStyle, font, element, }: {
     text: string;
+    element?: Element | null;
 } & FontProperties): {
     width: number;
     height: number;
@@ -5811,51 +5803,32 @@ declare function getTextDimensions({ text, fontSize, fontFamily, fontWeight, fon
  *     fontStyle: "normal",
  *   });
  *
- * @param options - The options for calculating the font size.
- * @param options.text - The text to fit within the width.
- * @param options.maxWidth - The maximum width the text should fit within.
- * @param options.initialFontSize - The starting font size to use for
- *   calculations. Defaults to 50.
- * @param options.fontFamily - The font family to use. Defaults to 'Arial'.
- * @param options.fontWeight - The font weight to use. Defaults to 'normal'.
- * @param options.fontStyle - The font style to use. Defaults to 'normal'.
- * @returns The calculated font size that fits the text within the given width.
+ * @param options.element - A reference element whose owner document is used to
+ *   create the measuring canvas. Falls back to the global document when
+ *   omitted.
  */
-declare function calculateFontSizeToFitWidth({ text, maxWidth, initialFontSize, fontFamily, fontWeight, fontStyle, }: {
+declare function calculateFontSizeToFitWidth({ text, maxWidth, initialFontSize, fontFamily, fontWeight, fontStyle, element, }: {
     text: string;
     maxWidth: number;
     initialFontSize: number;
+    element?: Element | null;
 } & Omit<FontProperties, "fontSize">): number;
-/**
- * Returns true if the element is focusable.
- *
- * @param element - The element to check.
- */
 declare function isFocusableElement(element: HTMLElement): boolean;
 declare function findFocusableElements(element: HTMLElement): NodeListOf<Element>;
 /**
- * Returns the active element of the given node. If the node is within a shadow
- * root, the active element of the shadow root will be returned, otherwise the
- * active element of the document will be returned.
- *
- * @param node - The node to get the active element from.
- * @returns The active element of the given node.
+ * Returns the active element of the given node, resolving through a shadow root
+ * when the node lives in one.
  */
 declare function getActiveElement(node?: Node): Element | null;
 /**
  * Returns true if the target is an input that will cause the software keyboard
  * to appear.
- *
- * @param target Element - The element to check.
  */
 declare function isInputThatOpensKeyboard(target: Element): boolean;
 /**
  * Returns the absolute bounds of the element. If the element is within a shadow
  * root, the bounds will be relative to the host element. If the element is not
  * within a shadow root, the bounds will be relative to the document.
- *
- * @param element - The element to get the absolute bounds of.
- * @returns The absolute bounds of the element.
  */
 declare function getAbsoluteBounds(element: HTMLElement): {
     x: number;
@@ -5868,10 +5841,6 @@ declare function getAbsoluteBounds(element: HTMLElement): {
  * position: fixed. If the element is within a shadow root, the position will be
  * relative to the host element so that the element can be positioned correctly
  * within the shadow root.
- *
- * @param element - The element to get the absolute position of.
- * @param coordinates - The coordinates of the element.
- * @returns The absolute position of the element.
  */
 declare function getAbsolutePosition(element: HTMLElement, coordinates?: {
     x: number;
@@ -5926,11 +5895,19 @@ declare function booleanOrObjectToConfig<T extends Record<string, unknown>>(valu
  * ```ts
  * lightenColor("#000000", 10); // #1a1a1a
  * ```
- *
- * @param color
- * @param percent
  */
 declare function lightenColor(color: string, percent: number): string;
+/**
+ * Compare two (possibly undefined) CSS color strings by value rather than by
+ * serialized form. Browsers normalize colors when they round-trip through the
+ * DOM — `#ac0000` reads back as `rgb(172, 0, 0)`, `rgba(255, 0, 0, 1)` as
+ * `rgb(255, 0, 0)` — so a raw-string compare would treat the same color as
+ * different. Both sides are canonicalized via React Aria's {@link Color}; a
+ * value React Aria cannot parse (a CSS named color, or an invalid value) is
+ * compared by exact string instead — so it matches only an identical string
+ * and never a real, parseable color.
+ */
+declare function areColorsEqual(a: string | undefined, b: string | undefined): boolean;
 
 /**
  * Checks whether the given value is a valid URL.
@@ -8441,9 +8418,19 @@ interface EditorProps extends StylingProps, AriaLabelingProps {
      * the Cancel button will not be rendered.
      */
     onCancel?: () => void;
-    /** The default value of the editor. */
+    /**
+     * The initial value of the editor (uncontrolled). The editor manages its
+     * own state afterwards; later changes to this prop are ignored.
+     */
     defaultValue?: string;
-    /** The value of the editor. */
+    /**
+     * The value of the editor (controlled). Provide together with `onChange`;
+     * later changes to this prop update the editor content.
+     *
+     * Backwards compatibility: in rich text mode, `value` without `onChange`
+     * behaves like `defaultValue` (initial content only), matching the
+     * behavior of earlier versions.
+     */
     value?: string;
     /**
      * The function to be called when the value of the editor changes.
@@ -8574,6 +8561,444 @@ interface EditorProps extends StylingProps, AriaLabelingProps {
 
 declare const Editor: React__default.MemoExoticComponent<React__default.ForwardRefExoticComponent<EditorProps & React__default.RefAttributes<HTMLDivElement>>>;
 
+declare const PARAGRAPH: "p";
+declare const LINK: "a";
+declare const MENTION: "mention";
+declare const MENTION_INPUT: "mention_input";
+interface RichTextEditorText {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    color?: string;
+    backgroundColor?: string;
+}
+interface RichTextEditorLink {
+    type: typeof LINK;
+    url: string;
+    children: RichTextEditorText[];
+}
+interface RichTextEditorMention {
+    type: typeof MENTION;
+    value: string;
+    displayName: string;
+    children: [RichTextEditorText];
+}
+interface RichTextEditorMentionInput {
+    type: typeof MENTION_INPUT;
+    children: [RichTextEditorText];
+}
+type RichTextEditorInline = RichTextEditorText | RichTextEditorLink | RichTextEditorMention | RichTextEditorMentionInput;
+interface RichTextEditorParagraph {
+    type: typeof PARAGRAPH;
+    children: RichTextEditorInline[];
+}
+type RichTextEditorDoc = RichTextEditorParagraph[];
+
+interface ModelPoint {
+    /** [paragraphIndex, inlineIndex within paragraph.children] */
+    path: [number, number];
+    /** Character offset within that inline node's text. */
+    offset: number;
+}
+interface ModelRange {
+    anchor: ModelPoint;
+    focus: ModelPoint;
+}
+
+type MarkName = "bold" | "italic" | "underline";
+/** Marks shared by all text content covered by a range. */
+interface ActiveMarks {
+    bold?: true;
+    italic?: true;
+    underline?: true;
+    color?: string;
+    backgroundColor?: string;
+}
+
+/**
+ * EditorCore.ts — framework-free orchestrator for the rich-text editor.
+ *
+ * Wires DOM events on a contenteditable host element to the pure command/model
+ * modules. React is responsible for rendering the host element and toolbar;
+ * EditorCore owns the document state.
+ *
+ * Design notes
+ * ─────────────
+ * - setValue() does NOT record history — external controlled updates are not
+ *   user edits.
+ * - No global `document` or `window` access; everything goes through
+ *   `el.ownerDocument` / `el.getRootNode()`.
+ * - renderDoc() during edits/sync is guarded against running mid-IME-composition
+ *   (the one-time attach-time render predates any composition, so it is exempt).
+ * - Identity-diffing: commands that return the same `doc` reference are no-ops.
+ */
+
+interface SelectionState {
+    /** Active marks at the current selection (merged with pendingMarks). */
+    marks: ActiveMarks;
+    /** Link covering (or touching) the current selection range, if any. */
+    link: {
+        url: string;
+        range: ModelRange;
+    } | null;
+    /** Current model selection range. */
+    range: ModelRange | null;
+}
+interface EditorCoreOptions {
+    /** Called after each user-visible document change; receives serialized HTML. */
+    onChange?: (html: string) => void;
+    /** Called when the selection changes. */
+    onSelectionChange?: (state: SelectionState) => void;
+    /**
+     * Called when "@" at an appropriate position creates a mention_input.
+     * The React layer is expected to open its mention dropdown in response.
+     */
+    onMentionTrigger?: () => void;
+    /**
+     * Called when a doc replacement (a controlled `setValue`) removes an open
+     * mention_input without going through the normal cancel/confirm path. The
+     * React layer must close its dropdown — the orphaned anchor fires no blur.
+     */
+    onMentionInputRemoved?: () => void;
+    /**
+     * When this returns false, typing "@" does not start the mention flow and
+     * the character is inserted natively (e.g. no mentionable users configured).
+     */
+    canStartMention?: () => boolean;
+    /** When this returns true all mutation inputs are blocked (preventDefault'd). */
+    isReadOnly?: () => boolean;
+    /**
+     * Whether the built-in formatting (bold/italic/underline) and history
+     * (undo/redo) shortcuts are active. When this returns false, the matching
+     * native `beforeinput` intents (`formatBold`, `historyUndo`, …) are still
+     * blocked from mutating the DOM but no longer toggle marks or move history —
+     * leaving a consumer free to wire their own. Defaults to enabled.
+     */
+    areKeyboardShortcutsEnabled?: () => boolean;
+}
+/** Names of commands that EditorCore can dispatch via exec(). */
+type CommandName = "toggleMark" | "setMarkValue" | "wrapLink" | "updateLinkUrl" | "unwrapLink" | "deleteRange" | "insertText" | "insertFragment" | "insertSoftBreak" | "insertMentionInput" | "confirmMention" | "removeMentionInput";
+/** Argument tuple for each command (beyond doc + range which are implicit). */
+interface CommandArgs {
+    toggleMark: [mark: MarkName];
+    setMarkValue: [key: "color" | "backgroundColor", value?: string];
+    wrapLink: [url: string];
+    updateLinkUrl: [url: string];
+    unwrapLink: [];
+    deleteRange: [];
+    insertText: [text: string];
+    insertFragment: [fragment: RichTextEditorDoc];
+    insertSoftBreak: [];
+    insertMentionInput: [];
+    confirmMention: [user: {
+        id: string;
+        displayName: string;
+    }];
+    removeMentionInput: [restoreText: string];
+}
+declare class EditorCore {
+    private doc;
+    /** The last serialized HTML known to us (including setValue calls). */
+    private lastKnownHtml;
+    private cachedRange;
+    private composing;
+    private pending;
+    /**
+     * Number of upcoming selectionchange events that must NOT clear pending marks.
+     *
+     * handleSelectionChange normally clears pending the moment the caret leaves
+     * pending.caretOffset. But a single user keystroke (and insertSoftBreak)
+     * triggers our own writeSelection, which the browser reports back as one or
+     * more selectionchange events — and in shadow DOM (notably Chromium and
+     * Firefox) one of those can arrive with the post-keystroke caret offset before
+     * syncFromDom has updated pending.caretOffset to match. Without this guard,
+     * that transient mismatch clears pending mid-typing, the toolbar flips off,
+     * and the next character is no longer colored. We absorb a small burst of
+     * these self-inflicted events (a single boolean is not enough — shadow DOM can
+     * emit several per action) and re-sync caretOffset to the real caret as they
+     * arrive, so a genuine later caret move still clears pending correctly.
+     *
+     * Confirmed load-bearing: removing it makes the shadow-DOM "color buttons stay
+     * active while typing" CT flake/time out in Chromium.
+     */
+    private preservePendingSelectionChanges;
+    private history;
+    private opts;
+    private el;
+    private pendingExternalRender;
+    private keyboardShortcutsOverride;
+    constructor(opts?: EditorCoreOptions);
+    /**
+     * Sets a per-element keyboard-shortcut override. `undefined` clears it and
+     * restores the editor-level {@link EditorCoreOptions.areKeyboardShortcutsEnabled}.
+     */
+    setKeyboardShortcutsEnabled(enabled: boolean | undefined): void;
+    /**
+     * Renders the current doc into `el`, attaches event listeners and returns a
+     * cleanup function that removes them. Calling attach() a second time without
+     * first calling the returned cleanup is undefined behaviour.
+     */
+    attach(el: HTMLElement): () => void;
+    private readonly handleBeforeInputBound;
+    private readonly handleInputBound;
+    private readonly handlePointerDownBound;
+    private readonly handleCompositionStartBound;
+    private readonly handleCompositionEndBound;
+    private readonly handleSelectionChangeBound;
+    /**
+     * Synchronously refreshes cachedRange from the live DOM selection when that
+     * selection is inside the editor. Leaves cachedRange untouched when the
+     * selection is elsewhere (dialogs, toolbar popovers) or unreadable.
+     */
+    private refreshSelectionFromDom;
+    getDoc(): RichTextEditorDoc;
+    getValue(): string;
+    /**
+     * Sets the document from an HTML string (controlled entry point).
+     *
+     * SKIPS (no-op) when `html` matches the last known serialized value to
+     * break controlled-value loops. Never emits onChange unless `emit: true`.
+     *
+     * NOTE: Does not record history — see module-level design notes.
+     */
+    setValue(html: string, opts?: {
+        emit?: boolean;
+    }): void;
+    private static docHasMentionInput;
+    /**
+     * Dispatches a named command at the current selection.
+     *
+     * Identity-diff: if the command returns the same `doc` reference (no-op),
+     * nothing changes — except for `toggleMark` on a collapsed selection, which
+     * sets pendingMarks and emits onSelectionChange.
+     */
+    exec<K extends CommandName>(name: K, ...args: CommandArgs[K]): void;
+    undo(): void;
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    focus(): void;
+    setCaretPosition(absoluteOffset: number): void;
+    /**
+     * Restores a model selection: focuses the editor and writes the range to
+     * both the DOM and cachedRange. Used by toolbar popovers (e.g. the color
+     * picker) that captured the selection before taking focus — on Firefox,
+     * refocusing a contenteditable collapses its DOM selection, so the range
+     * must be re-applied explicitly before dispatching a command.
+     */
+    select(range: ModelRange): void;
+    selectStart(): void;
+    selectEnd(): void;
+    getSelectionState(): SelectionState;
+    private buildSelectionState;
+    private mergePendingMarks;
+    /**
+     * Toggle a pending boolean mark for the collapsed-caret case.
+     *
+     * We store the FULL effective marks snapshot (base + toggle) so that
+     * applyPendingMarks can apply them directly to the just-typed range.
+     * Toggling the same mark a second time returns to the base state.
+     */
+    private setPendingMark;
+    /**
+     * Set or clear a pending color/backgroundColor mark for the collapsed-caret case.
+     * `value === undefined` removes that key from the pending snapshot.
+     */
+    private setPendingColorMark;
+    private emitSelectionChange;
+    /**
+     * Applies a doc+range change, re-renders if attached, emits events.
+     */
+    private applyDocChange;
+    private handleBeforeInput;
+    /**
+     * Returns true when the current caret position is preceded by a word boundary
+     * (or is at the start of a paragraph), matching the pattern /^$|^[\s"']$/.
+     */
+    private shouldTriggerMention;
+    private lastCharOf;
+    private handlePasteInput;
+    /**
+     * Called after an `input` event (or compositionend). Reads the current DOM
+     * back into a model doc and reconciles with internal state.
+     */
+    private syncFromDom;
+    /**
+     * Apply pending marks to the text that was just typed.
+     *
+     * The just-typed range is determined by diffing the pre-input caret absolute
+     * offset against the post-input caret absolute offset.
+     */
+    private applyPendingMarks;
+    /**
+     * Applies the pending mark snapshot to the [preOffset, postOffset] range,
+     * re-deriving the range from absolute offsets before each command (commands
+     * may split nodes and stale a ModelRange). Returns the resulting doc by
+     * identity when no mark changed.
+     */
+    private applyPendingMarkSnapshot;
+    private handleSelectionChange;
+    private dispatchCommand;
+    private collapsedAtDocEnd;
+    private rangesEqual;
+}
+
+/**
+ * Public types for the headless editor binding layer.
+ *
+ * The `EditorState` handle is the entire API: all reading (selection, value)
+ * and acting (focus, commands, marks) happens on it. Hooks and the provider
+ * only create the handle or deliver it to a component — they never wrap what
+ * the handle can already do.
+ */
+
+/**
+ * A live handle to one editor instance. Reactive fields (`selectionState`,
+ * `value`, `isEmpty`, `canUndo`, `canRedo`, `isDisabled`) update across renders;
+ * the methods are stable passthroughs to the underlying {@link EditorCore}.
+ */
+interface EditorState {
+    /** The underlying framework-free engine (escape hatch). */
+    core: EditorCore;
+    /** Active marks, link, and range at the current selection. */
+    selectionState: SelectionState;
+    /**
+     * Current value as a string. In controlled mode this mirrors the consumer's
+     * (possibly unnormalized) `value` prop; for the engine's own normalized
+     * serialization use {@link getValue}.
+     */
+    value: string;
+    /** Whether the document is empty (drives placeholder visibility). */
+    isEmpty: boolean;
+    /** Whether the editor is read-only. */
+    isDisabled: boolean;
+    /** Whether built-in formatting/history keyboard shortcuts are enabled. */
+    keyboardShortcuts: boolean;
+    canUndo: boolean;
+    canRedo: boolean;
+    focus: EditorCore["focus"];
+    selectStart: EditorCore["selectStart"];
+    selectEnd: EditorCore["selectEnd"];
+    setCaretPosition: EditorCore["setCaretPosition"];
+    undo: EditorCore["undo"];
+    redo: EditorCore["redo"];
+    getValue: EditorCore["getValue"];
+    setValue: EditorCore["setValue"];
+    exec: EditorCore["exec"];
+    /** Whether `mark` is active at the current selection. */
+    isMarkActive: (mark: MarkName) => boolean;
+    /** Toggle a boolean mark (bold/italic/underline). */
+    toggleMark: (mark: MarkName) => void;
+    /** Set or clear a color mark; omit `value` to clear. */
+    setMark: (key: "color" | "backgroundColor", value?: string) => void;
+}
+/**
+ * Options for {@link useEditor}. Combines the engine callbacks with the
+ * React-managed props the hook owns the lifecycle for.
+ */
+interface UseEditorOptions extends Pick<EditorCoreOptions, "onChange" | "onSelectionChange" | "onMentionTrigger" | "onMentionInputRemoved" | "canStartMention" | "isReadOnly"> {
+    /** Controlled value (provide with `onChange`). */
+    value?: string;
+    /** Initial value for uncontrolled use (applied once on mount). */
+    defaultValue?: string;
+    /** When true, the editor is read-only and selection is cleared. */
+    isDisabled?: boolean;
+    /**
+     * Whether the built-in formatting (bold/italic/underline) and history
+     * (undo/redo) keyboard shortcuts are active. Disable to wire your own.
+     *
+     * @default true
+     */
+    keyboardShortcuts?: boolean;
+}
+
+/**
+ * Creates and owns a single editor engine, wiring its React lifecycle:
+ * controlled `value` sync, one-time `defaultValue` init, `isDisabled`
+ * read-only handling, and reactive selection/value state. Returns the stable
+ * {@link EditorState} handle — the entire editor API.
+ *
+ * The handle does not attach to the DOM; pass it to {@link useEditable} on the
+ * element you want to make editable.
+ */
+declare function useEditor(options?: UseEditorOptions): EditorState;
+
+interface UseEditableOptions {
+    /** A ref to merge with the internal element ref (e.g. for measuring/querying). */
+    ref?: Ref<HTMLDivElement>;
+    /**
+     * Focus the element on mount, optionally positioning the caret at the
+     * start/end. Runs after the engine attaches.
+     */
+    autoFocus?: boolean | "start" | "end";
+    /**
+     * App-specific key handling, invoked before the built-in shortcuts
+     * (bold/italic/underline, undo/redo). Return `true` if the event was handled
+     * to skip the built-ins.
+     */
+    onKeyDown?: (event: KeyboardEvent$1) => boolean | undefined;
+    /**
+     * Whether the built-in formatting/history shortcuts are active. Overrides the
+     * editor's `keyboardShortcuts` setting for this element. Defaults to the
+     * editor's setting (which itself defaults to enabled).
+     */
+    keyboardShortcuts?: boolean;
+}
+interface EditableProps {
+    id: string;
+    ref: Ref<HTMLDivElement>;
+    contentEditable: boolean;
+    suppressContentEditableWarning: true;
+    role: "textbox";
+    "aria-multiline": true;
+    onKeyDown?: KeyboardEventHandler;
+    onKeyUp?: KeyboardEventHandler;
+}
+/**
+ * Applies the built-in formatting (Ctrl/Cmd+B/I/U) and history (Ctrl/Cmd+Z,
+ * Shift+Z, Ctrl+Y) shortcuts to `editor`. Returns `true` (and calls
+ * `preventDefault`) when the event matched a shortcut, so the caller can stop
+ * further handling. Exported for direct use by custom keydown handlers.
+ */
+declare function handleEditorShortcut(event: KeyboardEvent$1, editor: EditorState): boolean;
+/**
+ * Returns `{ editableProps }` to spread on the HTML element you want to make
+ * editable. Owns the element ref, the engine `attach()` lifecycle, the generic
+ * formatting shortcuts (Ctrl/Cmd+B/I/U, undo/redo), and `autoFocus`.
+ *
+ * Pass the editor handle explicitly, or omit it to resolve the nearest
+ * {@link EditorProvider}.
+ */
+declare function useEditable(editor?: EditorState, options?: UseEditableOptions): {
+    editableProps: EditableProps;
+};
+
+interface EditorProviderProps {
+    /** The editor handle returned by `useEditor`. */
+    editor: EditorState;
+    children: React__default.ReactNode;
+}
+/**
+ * Shares one editor handle with its subtree. Wrap each editor's UI in its own
+ * `EditorProvider`; hooks inside (`useEditable`, `useEditorContext`) resolve to
+ * this editor via the nearest provider.
+ */
+declare const EditorProvider: React__default.FC<EditorProviderProps>;
+
+/**
+ * EditorContext — shares one {@link EditorState} handle with a subtree so a
+ * co-located toolbar can reach the editor without prop-drilling. One provider
+ * per editor; nearest-wins resolution keeps multiple editors isolated.
+ */
+
+/**
+ * Returns the {@link EditorState} from the nearest {@link EditorProvider}.
+ * Throws if called outside a provider.
+ */
+declare function useEditorContext(): EditorState;
+declare const EMPTY_SELECTION_STATE: SelectionState;
+
 interface ScrollControlButtonProps extends StylingProps, Pick<ActionButtonProps, "label"> {
     /**
      * The ref to the scrollable element.
@@ -10365,5 +10790,5 @@ declare namespace reactStately {
   export type { reactStately_Color as Color, reactStately_ListData as ListData, reactStately_TreeData as TreeData };
 }
 
-export { Accordion, AccordionItem, ActionButton, ActionGroup, ActionGroupItem, ActionIconButton, Actionable, AlertDialog, AudioPlayer, Autocomplete, Avatar, Box, ButtonSelect, Calendar, Cell, Checkbox, Code, ColorInput, ColorSwatch, ColorSwatchPicker, Column, ComboBox, DateField, DateFormat, DefaultListOption, DeviceProvider, DeviceProviderContext, Dialog, DialogTitle, Disclosure, DomNodeRenderer, Drawer, Editor, FileInput, FileList$1 as FileList, FileUpload, FocusScope, Focusable, FrameProvider, FreehandCanvas, GlobalToastRegion, GridLayout, GridList, Group, I18nProvider, Icon, IconColorInput, IconColorInputButton, IconSelect, IconSlider, ImageDropZone, ImageGallery, InlineAlert, Kbd, Link, ListBox, ListLayout, LocaleAwareGridLayout, Markdown, Menu, MessageFormat, Modal, ModalClose, ModalContent, ModalTrigger, NumberFormat, NumberInput, Pagination, Panel, PanelGroup, PanelResizeHandle, PointPicker, PointPickerContent, PointPickerDisplay, Popover, PopoverContent, PopoverTrigger, Portal, PortalContainerProvider, Pressable, Preview, ProgressBar, ProgressSpinner, REACT_ARIA_INCOMPATIBLE_KEYS, RadioGroup, RangeCalendar, Reaction, Row, ScrollControlButton, SearchInput, Select, Separator, Size, Skeleton, Slider, StatusCard, Stepper, Switch, TabItem, Table, TableBody, TableHeader, TableLayout, Tabs, Tag, TagGroup, TaggedPagination, Text, TextInput, ThemeProvider, TimeField, ToastQueue, ToggleButton, ToggleIconButton, Toolbar, Tooltip, TreeView, UNSAFE_ListBox, reactAria as UNSAFE_aria, reactStately as UNSAFE_stately, VIRTUALIZER_LAYOUT_DEFAULT_OPTIONS, Virtualizer, VisuallyHidden, WaterfallLayout, announce, booleanOrObjectToConfig, calculateFontSizeToFitWidth, capitalize, clamp, classNames, cleanKeyFromGlobImport, clearAnnouncer, defineMessages, destroyAnnouncer, devWarnOnce, directionVar, disableAnimations, enableAnimations, filterDOMProps, filterTruthyValues, findFocusableElements, getAbsoluteBounds, getAbsolutePosition, getActiveElement, getHTMLElement, getOsSpecificKeyboardShortcutLabel, getOwnerDocument, getPlainText, getSvgPathFromStroke, getTextDimensions, iconMap, invariant, isFocusableElement, isInIframe, isInShadowDOM, isInputThatOpensKeyboard, isInsideOverlayContent, isRect, isUrl, lightenColor, mergeProps, mergeRefs, parseColor, safeSpreadProps, useCollator, useDateFormatter, useDevice, useDragAndDrop, useFilter, useFocusRing, useFocusVisible, useFrameDimensions, useI18n, useId, useImage, useInteractionModality, useIntersectionObserver, useIsFirstRender, useKeyboard, useListData, useLiveInteractionModality, useLocalStorage, useLocale, useMutationObserver, useNumberFormatter, useObjectRef, usePointProximity, usePortalContainer, usePreventFocus, useResizeObserver, useTableDragAndDrop, useTextSelection, useUndoRedo, useUserPreferences };
-export type { AccordionItemProps, AccordionProps, ActionButtonProps, ActionGroupProps, ActionIconButtonProps, ActionableProps, AlertDialogProps, AudioPlayerProps, AutocompleteProps, AvatarProps, BlockProps, BoundaryAxis, BoxProps, ButtonSelectProps, CalendarHeaderVariant, CalendarProps, CalendarSize, CellProps, CheckboxProps, CodeProps, ColorInputProps, ColorPreset, ColorSwatchPickerProps, ColorSwatchProps, ColumnProps, ComboBoxProps, DateFieldPickerType, DateFieldProps, DateFormatProps, Device, DeviceProviderProps, DialogProps, DialogTitleProps, DisclosureProps, DomNodeRendererProps, DrawerProps, EditorHandle, EditorProps, FileInputProps, FileListItem, FileListProps, FileUploadProps, FocusableProps, FrameProviderProps, FreehandCanvasProps, GridListProps, GroupProps, HorizontalBoundaryBehavior, I18nProviderProps, I18nResult, IconColorInputProps, IconComponentProps$1 as IconComponentProps, IconProps, IconSelectProps, IconSliderProps, ImageDropZoneProps, ImageGalleryProps, ImperativePanelGroupHandle, ImperativePanelHandle, InlineAlertProps, IntersectionObserverOptions, KbdProps, Key, LinkProps, ListBoxProps, ListHandle$1 as ListHandle, ListOption, MarkdownProps, MenuItem, MenuProps, MessageDescriptor, MessageFormatProps, MessageFormatter, ModalContentProps, ModalProps, NumberFormatProps, NumberInputProps, PaginationProps, PanelGroupProps, PanelProps, PanelResizeHandleProps, PointPickerContentProps, PointPickerDisplayProps, PointPickerProps, PopoverContentHandle, PopoverContentProps, PopoverProps, PopoverTriggerProps, PortalProps, PressEvent, PreviewProps, ProgressBarProps, ProgressSpinnerProps, RadioGroupProps, RangeCalendarProps, ReactAriaIncompatibleKey, ReactionProps, Rect, ResizeObserverOptions, RowProps, SVGRProps, SafeDOMAttributes, ScrollControlButtonProps, SearchInputProps, SelectProps, SeparatorProps, SetValue, SkeletonProps, SliderProps, StatusCardProps, StepperItem, StepperProps, StylingProps, SwitchProps, TabItemProps, TableBodyProps, TableHeaderProps, TableProps, TabsProps, TagGroupProps, TagProps, TagVariant, TaggedPaginationProps, TextInputProps, TextProps, TextSelectionProps, ThemeProviderProps, TimeFieldProps, ToastProps, ToggleButtonProps, ToggleIconButtonProps, ToolbarProps, TooltipProps, TreeListItem, TreeViewProps, UNSAFE_ListBoxProps, UseTableDragAndDropOptions, VirtualizerProps };
+export { Accordion, AccordionItem, ActionButton, ActionGroup, ActionGroupItem, ActionIconButton, Actionable, AlertDialog, AudioPlayer, Autocomplete, Avatar, Box, ButtonSelect, Calendar, Cell, Checkbox, Code, ColorInput, ColorSwatch, ColorSwatchPicker, Column, ComboBox, DateField, DateFormat, DefaultListOption, DeviceProvider, DeviceProviderContext, Dialog, DialogTitle, Disclosure, DomNodeRenderer, Drawer, EMPTY_SELECTION_STATE, Editor, EditorCore, EditorProvider, FileInput, FileList$1 as FileList, FileUpload, FocusScope, Focusable, FrameProvider, FreehandCanvas, GlobalToastRegion, GridLayout, GridList, Group, I18nProvider, Icon, IconColorInput, IconColorInputButton, IconSelect, IconSlider, ImageDropZone, ImageGallery, InlineAlert, Kbd, Link, ListBox, ListLayout, LocaleAwareGridLayout, Markdown, Menu, MessageFormat, Modal, ModalClose, ModalContent, ModalTrigger, NumberFormat, NumberInput, Pagination, Panel, PanelGroup, PanelResizeHandle, PointPicker, PointPickerContent, PointPickerDisplay, Popover, PopoverContent, PopoverTrigger, Portal, PortalContainerProvider, Pressable, Preview, ProgressBar, ProgressSpinner, REACT_ARIA_INCOMPATIBLE_KEYS, RadioGroup, RangeCalendar, Reaction, Row, ScrollControlButton, SearchInput, Select, Separator, Size, Skeleton, Slider, StatusCard, Stepper, Switch, TabItem, Table, TableBody, TableHeader, TableLayout, Tabs, Tag, TagGroup, TaggedPagination, Text, TextInput, ThemeProvider, TimeField, ToastQueue, ToggleButton, ToggleIconButton, Toolbar, Tooltip, TreeView, UNSAFE_ListBox, reactAria as UNSAFE_aria, reactStately as UNSAFE_stately, VIRTUALIZER_LAYOUT_DEFAULT_OPTIONS, Virtualizer, VisuallyHidden, WaterfallLayout, announce, areColorsEqual, booleanOrObjectToConfig, calculateFontSizeToFitWidth, capitalize, clamp, classNames, cleanKeyFromGlobImport, clearAnnouncer, defineMessages, destroyAnnouncer, devWarnOnce, directionVar, disableAnimations, enableAnimations, filterDOMProps, filterTruthyValues, findFocusableElements, getAbsoluteBounds, getAbsolutePosition, getActiveElement, getHTMLElement, getOsSpecificKeyboardShortcutLabel, getOwnerDocument, getPlainText, getSvgPathFromStroke, getTextDimensions, handleEditorShortcut, iconMap, invariant, isFocusableElement, isInIframe, isInShadowDOM, isInputThatOpensKeyboard, isInsideOverlayContent, isRect, isUrl, lightenColor, mergeProps, mergeRefs, parseColor, safeSpreadProps, useCollator, useDateFormatter, useDevice, useDragAndDrop, useEditable, useEditor, useEditorContext, useFilter, useFocusRing, useFocusVisible, useFrameDimensions, useI18n, useId, useImage, useInteractionModality, useIntersectionObserver, useIsFirstRender, useKeyboard, useListData, useLiveInteractionModality, useLocalStorage, useLocale, useMutationObserver, useNumberFormatter, useObjectRef, usePointProximity, usePortalContainer, usePreventFocus, useResizeObserver, useTableDragAndDrop, useTextSelection, useUndoRedo, useUserPreferences };
+export type { AccordionItemProps, AccordionProps, ActionButtonProps, ActionGroupProps, ActionIconButtonProps, ActionableProps, ActiveMarks, AlertDialogProps, AudioPlayerProps, AutocompleteProps, AvatarProps, BlockProps, BoundaryAxis, BoxProps, ButtonSelectProps, CalendarHeaderVariant, CalendarProps, CalendarSize, CellProps, CheckboxProps, CodeProps, ColorInputProps, ColorPreset, ColorSwatchPickerProps, ColorSwatchProps, ColumnProps, ComboBoxProps, CommandArgs, CommandName, DateFieldPickerType, DateFieldProps, DateFormatProps, Device, DeviceProviderProps, DialogProps, DialogTitleProps, DisclosureProps, DomNodeRendererProps, DrawerProps, EditableProps, EditorCoreOptions, EditorHandle, EditorProps, EditorProviderProps, EditorState, FileInputProps, FileListItem, FileListProps, FileUploadProps, FocusableProps, FrameProviderProps, FreehandCanvasProps, GridListProps, GroupProps, HorizontalBoundaryBehavior, I18nProviderProps, I18nResult, IconColorInputProps, IconComponentProps$1 as IconComponentProps, IconProps, IconSelectProps, IconSliderProps, ImageDropZoneProps, ImageGalleryProps, ImperativePanelGroupHandle, ImperativePanelHandle, InlineAlertProps, IntersectionObserverOptions, KbdProps, Key, LinkProps, ListBoxProps, ListHandle$1 as ListHandle, ListOption, MarkName, MarkdownProps, MenuItem, MenuProps, MessageDescriptor, MessageFormatProps, MessageFormatter, ModalContentProps, ModalProps, ModelPoint, ModelRange, NumberFormatProps, NumberInputProps, PaginationProps, PanelGroupProps, PanelProps, PanelResizeHandleProps, PointPickerContentProps, PointPickerDisplayProps, PointPickerProps, PopoverContentHandle, PopoverContentProps, PopoverProps, PopoverTriggerProps, PortalProps, PressEvent, PreviewProps, ProgressBarProps, ProgressSpinnerProps, RadioGroupProps, RangeCalendarProps, ReactAriaIncompatibleKey, ReactionProps, Rect, ResizeObserverOptions, RichTextEditorDoc, RichTextEditorInline, RichTextEditorLink, RichTextEditorMention, RichTextEditorMentionInput, RichTextEditorParagraph, RichTextEditorText, RowProps, SVGRProps, SafeDOMAttributes, ScrollControlButtonProps, SearchInputProps, SelectProps, SelectionState, SeparatorProps, SetValue, SkeletonProps, SliderProps, StatusCardProps, StepperItem, StepperProps, StylingProps, SwitchProps, TabItemProps, TableBodyProps, TableHeaderProps, TableProps, TabsProps, TagGroupProps, TagProps, TagVariant, TaggedPaginationProps, TextInputProps, TextProps, TextSelectionProps, ThemeProviderProps, TimeFieldProps, ToastProps, ToggleButtonProps, ToggleIconButtonProps, ToolbarProps, TooltipProps, TreeListItem, TreeViewProps, UNSAFE_ListBoxProps, UseEditableOptions, UseEditorOptions, UseTableDragAndDropOptions, VirtualizerProps };