@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/components/blocks/editable-surface.d.ts

@@ -1,53 +1,59 @@
 /**
- * Shared editable-surface plumbing for the core contenteditable blocks (TextEditableBlock,
- * CodeBlock, TableCellBlock) and the `editable-leaf` seam: cross-block wiring, the
- * SharedKeydownContext, the BlockComponent surface methods, the input/composition + clipboard
- * skeletons. Each consumer supplies a CursorBackend for its own coordinate system plus the input
- * commit; mutable block state crosses the seam as live thunks, never as snapshots.
+ * What every contenteditable block and the `editable-leaf` factory share: cross-block wiring,
+ * the shared keydown context, the BlockComponent caret methods, input, composition and clipboard
+ * handling. Each block supplies a CursorBackend for its own offsets plus its input commit; state
+ * that changes is passed as functions, never as captured values.
  */
 import type { BlockEditActions, FocusActions, HistoryActions } from '../../action-contracts';
+import type { CaretLanding } from '../../selection/caret-landing';
 import { type StickyColumnDirection } from '../../block-component';
 import type { UserScrollport } from '../../cursor/scroll-ancestors';
-import type { BlockElLookup, DocumentGetter, PasteImageHook, PluginEditorLookup, LinkReferenceResolverRef, PresentationModeGetter } from '../../editor-keys';
+import type { ScrollOwner } from '../../cursor/scroll-owner';
+import type { BlockElLookup, DocumentGetter, PasteImageHook } from '../../editor-keys';
 import { type EditorEvents } from '../../editor-events';
-import type { KeybindingOverrideMap } from '../../schema/keybinding-overrides';
-import type { CommandErrorSink, CrossBlockCommandRouter } from '../../schema/block-commands';
-import type { GrammarView } from '../../schema/block-openers';
+import type { InlineMenuCombobox } from '../../inline-menu/inline-menu-state.svelte';
+import type { NodeView } from '../../core/node-views';
+import type { CommandDispatchContext } from '../../schema/block-commands';
 import type { PluginActivation } from '../../schema/plugin-activation';
 import type { UndoController } from '../../editor-actions/deps';
 import type { PasteCommitCoordinator } from '../../tree-operations/paste/paste-deps';
-import type { StickyColumnState } from '../../cursor/sticky-column';
-import type { EdgeAffinityState } from '../../cursor/edge-affinity';
+import type { CaretMemory } from '../../cursor/caret-memory';
 import type { SelectionState } from '../../selection/selection-state.svelte';
+import type { SelectedWidgetHandle } from '../../selection/primitives';
 import { type RawOffset } from '../../cursor/coordinate-spaces';
+import type { CursorBackend } from '../../cursor/surface-backend';
 import { type CrossBlockHandlers } from '../../selection/cross-block/dispatch';
+import { type RawRange } from '../../cursor/widget-offset';
 import type { SharedKeydownContext } from '../../selection/shared-keydown';
-/**
- * Binds a surface's keydown handler so the interaction trace records ONE verdict per event,
- * after the handler's own await chain settles. That record is the e2e harness's only positive
- * signal that a gesture which must change nothing has finished. Disabled, one boolean read.
- */
+import type { Reading } from '../../schema/reading';
+/** Records one trace decision per keydown once the handler's awaits finish: the e2e harness's
+ *  only sign that a gesture which must change nothing is done. Disabled, one boolean read. */
 export declare function withKeydownVerdict(handle: (e: KeyboardEvent) => Promise<void>): (e: KeyboardEvent) => void;
-/**
- * Per-surface cursor I/O in raw-content coordinates (ambient marker excluded).
- * `buildRange` maps a raw-offset span to a DOM Range for selection writes.
- */
-export interface CursorBackend {
-    getRaw(): RawOffset | null;
-    setRaw(offset: RawOffset): void;
-    buildRange(start: RawOffset, end: RawOffset): Range | null;
+/** What an editable block tells assistive tech: its name, and the inline menu's list while
+ *  one shows in it. */
+export interface EditableSurfaceAttributes {
+    role: 'textbox' | 'combobox';
+    'aria-label': string;
+    'aria-expanded'?: 'true';
+    'aria-controls'?: string;
+    'aria-activedescendant'?: string;
+    'aria-autocomplete'?: 'list';
 }
-/**
- * Guarded pending-caret restore. Applies only while `el` still holds focus, so a blur
- * between arming the restore and the render drops it instead of yanking the global
- * selection back. Callers clear their pending field unconditionally regardless.
- */
+/** The role is `combobox` only while inline menu rows show: `textbox` carries no
+ *  `aria-expanded`, so a screen reader would hear nothing about the list. */
+export declare function editableSurfaceAttributes(node: NodeView, combobox: InlineMenuCombobox | null): EditableSurfaceAttributes;
+/** Applies `pending` only while `el` still holds focus, so a blur before the render drops it
+ *  rather than pulling the selection back. The caller clears its pending field either way. */
 export declare function consumePendingRestore<T>(el: HTMLElement | null, pending: T | null, apply: (value: T) => void): boolean;
 export interface EditableSurfaceDeps {
     getEl: () => HTMLElement | null;
-    /** Ambient marker length in raw units — 0 for code/cell, prose marker width for text. */
-    getAmbientLength: () => number;
     backend: CursorBackend;
+    /** The raw range `focusAtColumn` searches, for a block whose first or last visual line takes
+     *  no caret (a code fence); the whole block when omitted. */
+    columnWindow?: () => RawRange;
+    /** What an offset handed to `focus` or `parkCaret` becomes before it lands. It receives the
+     *  `CURSOR_START`, `CURSOR_END` and `CURSOR_EXACT_START` values as they are. */
+    clampLanding?: (offset: number) => number;
     /** True while an ephemeral edit (inline-math source reveal) owns the DOM: the block
      *  commits on exit, so keyboard input and IME compositionend both skip the commit. */
     isInputSuppressed?: () => boolean;
@@ -55,81 +61,76 @@ export interface EditableSurfaceDeps {
     getIndex: () => number;
     getComposing: () => boolean;
     setComposing: (value: boolean) => void;
-    getPreEditOffset: () => number;
-    setPreEditOffset: (offset: number) => void;
     setPendingCursor: (offset: number | null) => void;
     selection: SelectionState;
     getDoc: DocumentGetter;
     getBlockElByPath: BlockElLookup;
     focusActions: FocusActions;
+    /** Where a cross-block key's caret goes: a collapse, an extend's parked caret, a command's block. */
+    caretLanding: Pick<CaretLanding, 'restore' | 'park' | 'mount'>;
     getEditorRoot: () => HTMLElement | null;
-    /** What scrolls this editor — the root in self mode, the host's scroller (or the
-     *  window) in host mode; threaded to the cross-block drag-select autoscroll. */
+    /** What scrolls this editor (the root in self mode; the host's scroller or the window in
+     *  host mode), for the cross-block drag-select autoscroll. */
     getScrollHost: () => UserScrollport | null;
+    /** Brings the block a Shift+Arrow extends into to the nearest edge. */
+    scrollOwner: Pick<ScrollOwner, 'place'>;
     getEditorLifetime: () => AbortSignal | null;
-    stickyColumn: StickyColumnState;
-    edgeAffinity: EdgeAffinityState;
+    caretMemory: CaretMemory;
     blockEdit: BlockEditActions;
     controller: UndoController;
     history: HistoryActions;
-    pluginEditor: PluginEditorLookup | undefined;
-    /** The effective presentation mode, threaded to the cross-block reading gate — a
-     *  sibling to `pluginEditor`, never smuggled through it. */
-    getPresentationMode: PresentationModeGetter | undefined;
-    /** The instance's link-reference resolver, forwarded to the cross-block join seam. */
-    linkRef: LinkReferenceResolverRef | undefined;
-    onCommandError: CommandErrorSink | undefined;
-    /** The arm a range command routes to; forwarded to the cross-block composer. */
-    crossBlockCommands: CrossBlockCommandRouter;
-    getKeybindingOverrides: () => KeybindingOverrideMap;
+    /** How this editor reads its bytes, for the cross-block join rules, the join-paste reparse and
+     *  the reading-mode check. */
+    reading: Reading;
+    /** The editor's command dispatch, which the keydown and cross-block handlers read. */
+    commands: CommandDispatchContext;
     pasteCoordinator: PasteCommitCoordinator;
-    /** The instance's block grammar, forwarded to the cross-block join-paste reparse.
-     *  Required-nullable: a surface must answer, and `undefined` means the global one. */
-    grammar: GrammarView | undefined;
     /** The plugins this instance activated, forwarded to the paste-transform pipeline. */
     activePlugins: PluginActivation;
-    /** The instance event surface, forwarded to the cross-block tier's clipboard
-     *  error channel — the same `EditorServices.events` the clipboard seam takes. */
+    /** This editor's events, for the cross-block clipboard's error reports. */
     events: EditorEvents;
-    /** Selection focus endpoint in raw space — surfaces convert or door-mint their DOM read. */
+    /** The image selected whole, passed to the shift-press that grows a range from it. */
+    selectedWidget: SelectedWidgetHandle;
+    /** The selection's focus endpoint as a raw offset; each block converts its own DOM read. */
     getFocusOffset: () => RawOffset | null;
     getTextLen: () => number;
     /** Read the current DOM content as raw text for the input commit. */
     readText: () => string;
-    /** Live mode's typing seat for a COMPOSITION: an IME inserts at the DOM caret and its
-     *  beforeinput is not cancelable, so the byte relocation a keystroke takes at keydown is
-     *  taken on this commit instead. Null keeps the read verbatim. */
+    /** Where live mode puts a composed run: an IME's beforeinput is not cancelable, so the byte
+     *  move a keystroke gets at keydown happens at this commit. Null keeps the text as read. */
     relocateComposedText?: (after: string, composedAt: number) => {
         raw: string;
         caret: number;
     } | null;
-    /**
-     * Commit the read text to the CST. Returns the caret offset to restore when the
-     * committed bytes differ from the DOM (a cell escaping a typed `|` to `\|`); void
-     * keeps the DOM caret.
-     */
-    commitInput: (text: string, preEditOffset: number, savedOffset: number) => number | void;
-    /** Extra input prelude before the shared body (text resets snap target + keystroke mark). */
+    /** Commits the read text; returns the caret to restore (a cell escapes a typed `|` to `\|`),
+     *  void to keep the DOM caret, or null for a refused write, which puts no caret back. */
+    commitInput: (text: string, preEditOffset: number, savedOffset: number) => number | null | void;
+    /** Runs before the shared input commit (the text block resets its snap target here). */
     inputPrelude?: () => void;
+    /** The block's own beforeinput handling, run after the surface records the pre-edit caret. */
+    handleBeforeInput?: (e: InputEvent) => unknown;
 }
 export interface EditableSurface {
     crossBlock: CrossBlockHandlers;
     sharedCtx: SharedKeydownContext;
     surface: EditableSurfaceMethods;
     caret: ClipboardCaretIO;
-    /**
-     * True while this surface's element is out of the document — a torn-down host, and equally a
-     * render-primary leaf whose source is folded. Svelte's delegated walk does not await a keydown
-     * handler, so a container above it (a list item's Tab) claims the press and unmounts the block
-     * while a step is suspended; every awaited step asks this before reading on.
-     */
+    /** True once this block's element has left the document. Svelte does not await a keydown
+     *  handler, so a container can unmount the block mid-await; each awaited step checks this. */
     isDetached(): boolean;
+    /** Bound to the element's `beforeinput`: every input route fires it, keydown or not, so the
+     *  caret the undo entry restores is read here. */
+    onBeforeInput: (e: InputEvent) => void;
     onInput: () => void;
     onCompositionStart: () => void;
     onCompositionEnd: () => void;
+    /** The caret before the edit in progress: what an edit a block commits itself anchors on. */
+    getPreEditOffset(): number;
+    /** Name the pre-edit caret for an edit the block splices itself rather than the browser. */
+    notePreEditOffset(offset: number): void;
 }
 /**
- * The caret door the clipboard seam borrows from its surface. `getEl` is a liveness
+ * The caret calls the shared clipboard code borrows from a block. `getEl` is a liveness
  * test: a host import hook can outlive the block that started the paste.
  */
 export interface ClipboardCaretIO {
@@ -141,7 +142,7 @@ export interface ClipboardCaretIO {
 export interface EditableSurfaceMethods {
     focus(offset: number): void;
     /** Required here, optional on `BlockComponent`: an editable surface is what the
-     *  cross-block extend paths park into, so every one of them owes the door. */
+     *  cross-block extend paths leave a caret in, so all of them go through here. */
     parkCaret(offset: number): void;
     focusAtColumn(x: number, from: StickyColumnDirection): void;
     getCursorOffset(): number | null;
@@ -151,48 +152,46 @@ export interface EditableSurfaceMethods {
 }
 export declare function createEditableSurface(deps: EditableSurfaceDeps): EditableSurface;
 /**
- * What folding a live source reveal hands the mutation that triggered it. A fold that
- * changes the block's KIND takes the structural path, whose completion is a promise —
- * so a mutation seam waits on `settled`, not on a tick that happens to outlast it.
+ * What hiding a shown source hands back to the edit that triggered it. A commit that changes
+ * the block's kind takes the structural path, whose completion is a promise, so an edit waits
+ * on `settled` rather than on a tick that happens to outlast it.
  */
 export interface RevealFold {
-    /** Committed caret offset — where the folded edit left the caret. */
+    /** The committed caret offset: where the edit left the caret. */
     caret: number;
-    /** Resolves once the fold's write has landed and its render has flushed. */
+    /** Resolves once that write has landed and its render has flushed. */
     settled: Promise<void>;
 }
 /**
- * The ordered copy / cut / paste skeleton shared by the four editable surfaces, owning the arms
- * that must stay in lockstep (reading gate, cross-block write, reveal fold, image arm) so no
- * surface can skip or resequence one. Paste prevents before its first await, or native paste fires
- * while the fold settles. Reads and writes go through the event's synchronous `clipboardData`;
- * `navigator.clipboard` is permission-gated and unreliable in Tauri's wry webview.
+ * The copy, cut and paste steps every editable block shares, in one order no block can
+ * skip or reshuffle. Paste prevents the default before its first await, or the native paste runs
+ * while a shown source hides. Everything goes through the event's synchronous `clipboardData`;
+ * `navigator.clipboard` is permission-gated and unreliable in Tauri's webview.
  */
 export interface ClipboardSurfaceDeps {
-    stickyColumn: StickyColumnState;
-    edgeAffinity: EdgeAffinityState;
+    caretMemory: CaretMemory;
     selection: SelectionState;
     getDoc: DocumentGetter;
     crossBlock: CrossBlockHandlers;
     /** Reading mode: copy/cut write the visible selection string, paste is inert. */
     isReadOnly: () => boolean;
-    /** The surface's caret door, borrowed by the image arm to anchor its insertion. */
+    /** The block's caret calls, borrowed by the image branch to anchor its insertion. */
     caret: ClipboardCaretIO;
-    /** The instance event surface — the image arm's only channel for a host hook that
-     *  rejects. Non-nullable so a surface cannot silently swallow a failed import. */
+    /** This editor's events: the image branch's only way to report a host hook that
+     *  rejects. Required so a block cannot silently swallow a failed import. */
     events: EditorEvents;
     /** Host image-import hook from the policies context. Undefined leaves an
-     *  image-bearing paste on the text/plain path, exactly as before the hook. */
+     *  image-bearing paste on the text/plain path. */
     onPasteImage: PasteImageHook | undefined;
-    /** Fold a live inline-source reveal before a cut/paste mutates, so the mutation runs
-     *  against a CST consistent with the swapped DOM. Omit on a surface with no reveal. */
+    /** Hides a shown inline source before a cut or paste mutates, so the mutation runs against a
+     *  CST that matches the DOM. Omit on a block that never shows source. */
     foldReveal?: () => RevealFold | null;
-    /** Pre-cross-block copy arm (selected-widget slice, intra-table rect). True when it
+    /** The copy step before cross-block handling (a selected widget, a table rectangle). True when it
      *  wrote the payload and the handler should stop; owns its own preventDefault. */
     copyPreHook?: (e: ClipboardEvent) => boolean;
-    /** Pre-cross-block cut arm (selected-widget splice, intra-table rect cut). */
+    /** The cut step before cross-block handling (a selected widget, a table rectangle). */
     cutPreHook?: (e: ClipboardEvent) => boolean | Promise<boolean>;
-    /** Pre-cross-block paste arm, handed the normalized text while a live rectangle is still
+    /** The paste step before cross-block handling, given the normalised text while a rectangle is
      *  readable (a grid into a table's cells). True when it consumed the paste. */
     pastePreHook?: (text: string) => boolean | Promise<boolean>;
     /** The intra-block copy payload; owns its preventDefault. Omit to write the
@@ -200,19 +199,16 @@ export interface ClipboardSurfaceDeps {
     copyTail?: (e: ClipboardEvent) => void;
     /** The intra-block cut: a synchronous clipboardData write, then the CST delete. */
     cutTail: (e: ClipboardEvent) => void | Promise<void>;
-    /** The intra-block paste after normalize: the surface's splice/dispatch, handed
-     *  the normalized text and the reveal-fold landing caret. */
+    /** The intra-block paste, handed the normalized text and the caret left by hiding a shown
+     *  source. */
     pasteTail: (pastedText: string, foldedCaret: number | null) => void | Promise<void>;
 }
 export interface ClipboardHandlers {
     onCopy(e: ClipboardEvent): void;
     onCut(e: ClipboardEvent): Promise<void>;
     onPaste(e: ClipboardEvent): Promise<void>;
-    /**
-     * Insert `md` exactly as pasting it here would, minus the clipboard — the surface half of
-     * `EditorInstance.insertMarkdown`. True means the pipeline took the text, not that its
-     * commit has flushed; the synchronous declines are reading mode and an empty payload.
-     */
-    insertMarkdown(md: string): boolean;
+    /** Insert `md` as pasting it here would, for `EditorInstance.insertMarkdown`. Resolves once
+     *  the paste lands; false in reading mode or for an empty payload. */
+    insertMarkdown(md: string): Promise<boolean>;
 }
 export declare function createClipboardHandlers(deps: ClipboardSurfaceDeps): ClipboardHandlers;