@voithos-labs/aragonite 0.10.3 → 0.10.7

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

@@ -1,24 +1,21 @@
 /**
- * The editable-leaf seam a plugin block component builds on: native caret/IME/undo/selection
- * parity in one factory, so a plugin never touches an editor context key. `plain` commits per
- * keystroke; `render-primary` reveals its source and commits on blur. A painted source
- * (`renderSource`) edits only its own DOM: every byte still enters the CST through
- * `commitReveal`'s one `updateBlockContent`. Call synchronously during init. Contract:
- * plugin-guide § The editable leaf.
+ * What a plugin's block component builds on: the caret, IME, undo and selection behaviour the
+ * built-in blocks have, in one factory, so a plugin never touches an editor context key. `plain`
+ * commits on every keystroke; `render-primary` shows its source and commits on blur. Call it
+ * synchronously during initialisation; the contract is plugin-guide § The editable leaf.
  */
 import type { BlockEditActions } from '../../action-contracts';
 import type { StickyColumnDirection } from '../../block-component';
 import type { NodeView } from '../../core/node-views';
-import { type PluginEditorLookup } from '../../editor-keys';
+import { type EditableSurfaceAttributes } from './editable-surface';
 import type { PresentationMode } from '../../presentation-mode';
-import { type CommandId } from '../../schema/commands';
-import { type BlockCommandContext } from '../../schema/block-commands';
+import { type BlockTargetContext } from '../../schema/block-commands';
+import type { EditorContext } from '../../schema/plugin-install';
 export type EditableLeafMode = 'plain' | 'render-primary';
 /**
- * The frozen inputs the host component feeds in. A function-valued field is a **live
- * read**, re-evaluated on every use, so a structural op or undo replacement is observed
- * rather than snapshotted; `mode` and `singleLine` are static configuration captured at the
- * factory call.
+ * What the host component passes in. A function-valued field is read on every use, so a
+ * structural edit or an undo is seen rather than snapshotted; `mode` and `singleLine` are read
+ * once, at the factory call.
  */
 export interface EditableLeafDeps {
     getNode(): NodeView;
@@ -32,30 +29,17 @@ export interface EditableLeafDeps {
     /** render-primary only: the component owns the swap flag and both views. */
     isRevealed?(): boolean;
     setRevealed?(revealed: boolean): void;
-    /**
-     * The mounted component's view-state hooks, handed to a minted block command as
-     * `ctx.hooks`. Read live at dispatch: return a getter, never a captured value. The
-     * platform treats it as `unknown`; the plugin casts it.
-     */
+    /** The component's view-state hooks, handed to a block command as `ctx.hooks` and read at
+     *  dispatch, so return live values. Typed `unknown`; the plugin casts it. */
     commandHooks?: () => unknown;
-    /**
-     * Paints the source as DOM instead of one text node — fence lines the mode CSS hides,
-     * highlight tokens. Must keep `fragment.textContent === text` (G1.28); the offset walk sees
-     * through spans, and hidden marker runs behave as they do in a code block.
-     */
+    /** Draws the source as DOM (hidden fence lines, highlight tokens) instead of one text node.
+     *  Must keep `fragment.textContent === text`, or caret offsets drift (G1.28). */
     renderSource?(text: string): DocumentFragment;
-    /**
-     * The surface's text after each edit the leaf applies itself (a painted source's typing,
-     * deleting, Enter). A render-primary host keeping a live preview reads this: the CST sees
-     * the edit only on blur, and a cancelled `beforeinput` fires no `input` event.
-     */
+    /** The source text after each edit the leaf applies itself, for a live preview: the CST sees
+     *  a render-primary edit only on blur, and a cancelled `beforeinput` fires no `input`. */
     onSourceEdit?(text: string): void;
-    /**
-     * A source that is only its own chrome (a `$$$$` with no body line), completed to the shape
-     * a caret can sit in, with where the caret goes. Applied as the source is revealed, so the
-     * block the user just entered is one they can type into and delete; null leaves the bytes
-     * alone. The edit is the reveal's own, committed on blur like any other.
-     */
+    /** Completes a markers-only source (a `$$$$` with no body line) to one a caret can sit in,
+     *  applied on show and after any edit that empties it; null leaves the bytes alone. */
     completeBareSource?(text: string): {
         text: string;
         caret: number;
@@ -64,14 +48,13 @@ export interface EditableLeafDeps {
 /**
  * The one-spread source surface: `<div {...leaf.surfaceProps}>` wires every handler and attribute
  * a source contenteditable needs, so a consumer cannot drop one (a forgotten `oncompositionend`
- * breaks IME silently). Symbol-keyed attachments carry the view-lifecycle contracts: a SINGLE text
- * node, so the ambient offset walk stays exact, and the focus-park on unmount.
+ * breaks IME silently). Attachments under symbol keys carry the view's lifecycle rules: one text
+ * node, so the offset traversal stays exact, and moving focus away on unmount.
  */
-export interface EditableLeafSurfaceProps {
+export interface EditableLeafSurfaceProps extends EditableSurfaceAttributes {
     tabindex: number;
     /** Reading mode makes a plain leaf's always-mounted source inert. */
     contenteditable: 'true' | 'false';
-    role: 'textbox';
     spellcheck: 'false';
     oninput: () => void;
     onbeforeinput: (e: InputEvent) => void;
@@ -83,52 +66,48 @@ export interface EditableLeafSurfaceProps {
     onfocusout: () => void;
     oncompositionstart: () => void;
     oncompositionend: () => void;
-    /** View-sync + focus-park ride Svelte attachments under symbol keys. */
+    /** Keeping the view in sync and moving focus away are Svelte attachments, symbol-keyed. */
     [attachment: symbol]: unknown;
 }
 /**
  * The one-spread rendered surface: `<div {...leaf.renderProps}>` on a render-primary block's
- * FOLDED view. One bundle rather than a handler apiece, because a rendered view wired for the
- * reveal click alone swallows every chord while it holds focus — undo included. Both entries
- * stand down while the source is up, so the spread may sit on a wrapper the fold keeps.
+ * rendered view. One bundle rather than a handler apiece, because a rendered view wired only for
+ * the click that shows the source consumes every chord while it holds focus, undo included. Both
+ * do nothing while the source is up, so the spread may sit on a wrapper that stays either way.
  */
 export interface EditableLeafRenderProps {
-    /** Notes the press; the reveal is the CLICK's (shift-click extends a selection instead). */
+    /** Records where the pointer went down; the click is what shows the source, and a
+     *  shift-click extends a selection instead. */
     onpointerdown: (e: PointerEvent) => void;
-    /** Reveal on a click that did not drag — a press that moved is a selection, not an entry. */
+    /** Show the source on a click that did not drag: one that moved is a selection. */
     onclick: (e: MouseEvent) => void;
-    /** Chord dispatch at this block's kind: the global tier, then its own commands. */
+    /** Chord dispatch at this block's kind: the global commands, then its own. */
     onkeydown: (e: KeyboardEvent) => void;
 }
 export interface EditableLeaf {
-    /** The block's source minus its trailing line ending — the editable text. */
+    /** The block's source minus its trailing line ending, which is the editable text. */
     readonly sourceText: string;
     /**
-     * Re-run `renderSource` over the surface's CURRENT text with the caret kept, for a host
+     * Run `renderSource` again over the element's current text, keeping the caret, for a host
      * that repaints as the user types (highlighting goes stale otherwise). No-op without it.
      */
     repaintSource(): void;
-    /** The one-spread source surface (attributes + handlers + view/park attachments). */
+    /** The source element in one spread: attributes, handlers and the two attachments. */
     surfaceProps: EditableLeafSurfaceProps;
     /** render-primary: the one-spread folded surface. */
     renderProps: EditableLeafRenderProps;
-    /**
-     * The live EFFECTIVE presentation mode. The factory already gates itself in
-     * 'reading' (no reveal, no commits); a plain-mode component additionally binds
-     * `contenteditable` off this so its always-mounted source goes structurally inert.
-     */
+    /** The presentation mode in effect. The factory already does nothing in reading mode; a
+     *  plain-mode component also binds `contenteditable` to it so its source goes inert. */
     getPresentationMode(): PresentationMode;
-    /**
-     * The live editor theme name (`data-editor-theme`), for a leaf whose rendered half
-     * comes from an engine emitting its own colors rather than from CSS.
-     */
+    /** The live editor theme name (`data-editor-theme`), for a rendered view drawn by something
+     *  that emits its own colours rather than by CSS. */
     getTheme(): string;
-    /**
-     * This editor instance's options for the plugin owning this block's kind — the
-     * `{ plugin, options }` entry's channel, so two editors in one process configure the
-     * same kind differently. `unknown`, like `commandHooks`: the plugin narrows it.
-     */
+    /** This editor's options for the plugin owning this kind, so two editors can configure one
+     *  kind differently. `unknown`, like `commandHooks`: the plugin narrows it. */
     getOptions(): unknown;
+    /** This editor's context for the plugin that owns this block's kind; undefined in a bare
+     *  harness. Its `computeInlineContent` reads the inline syntax this editor draws. */
+    getEditor(): EditorContext | undefined;
     focus(offset: number): void;
     parkCaret(offset: number): void;
     focusAtColumn(x: number, from: StickyColumnDirection): void;
@@ -136,22 +115,19 @@ export interface EditableLeaf {
     getSelectedText(): string;
     setSelection(start: number, end: number): void;
     measurePartialRects(startOffset: number, endOffset: number): DOMRect[];
-    runCommand(id: CommandId): boolean;
-    /** Insert markdown at the caret exactly as pasting it here would, minus the clipboard —
-     *  publish it as the component's `insertMarkdown` so `editor.insertMarkdown()` reaches
-     *  this leaf. True means the paste pipeline took the text, not that its commit flushed. */
-    insertMarkdown(md: string): boolean;
+    /** Insert Markdown at the caret as a paste would; export it as the component's
+     *  `insertMarkdown`. Resolves once the paste lands, false when it declined. */
+    insertMarkdown(md: string): Promise<boolean>;
     /** Mount/focus the source with the caret at `offset` (plain mode: focus only). */
     reveal(offset?: number): Promise<void>;
     /** Commit edited source as one undo entry, fire and forget; the parse decides update / kind
      *  change / structural split. */
     commitSource(edited: string): void;
+    /** Run `run` once a shown source is hidden and written, so a move from outside the block takes
+     *  the edit along: publish it as the component's `afterSourceCommit`. */
+    afterSourceCommit(run: () => void): void;
 }
-/**
- * The node → metadata bridge (plus `commandHooks`) a minted block command resolves
- * against on the leaf tier — the container factory's `buildContainerKindTarget` sibling.
- * Every field reads through `deps`' thunks at dispatch, so a node swap or hook rebind is
- * observed live; `pluginEditor` resolves by the kind's recorded owner.
- */
-export declare function buildLeafCommandContext(deps: Pick<EditableLeafDeps, 'getNode' | 'getIndex' | 'commandHooks'>, blockEdit: Pick<BlockEditActions, 'updateBlockMetadata'>, pluginEditor?: PluginEditorLookup): Omit<BlockCommandContext, 'arg'>;
+/** What a plugin block command runs against on a leaf, read through `deps` at dispatch so a
+ *  node swap is seen; the leaf's counterpart of `buildContainerKindTarget`. */
+export declare function buildLeafCommandContext(deps: Pick<EditableLeafDeps, 'getNode' | 'getIndex' | 'commandHooks'>, blockEdit: Pick<BlockEditActions, 'updateBlockMetadata'>): BlockTargetContext;
 export declare function createEditableLeaf(deps: EditableLeafDeps): EditableLeaf;