@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/selection/range-delete.js

@@ -1,149 +1,109 @@
 /**
- * Core range mutation primitive, in place: truncate both endpoints, delete between, re-parse
- * the merged raw, cascade-clean empty ancestors, rebuild container raws. Caller pre-normalizes
- * the range. The "start wins" rule: `docs/design/editor.md` § Cross-block selection.
+ * Deletes a covered range from the tree in place, merging what survives at the start. The
+ * "start wins" rule is in `docs/design/editor.md` § Cross-block selection.
  */
-import { metadataOf } from '../core/nodes';
-import { walkBetween, charOffsetOf } from './primitives';
-import { comparePaths, lowestCommonAncestor, isPathSubtreeBetween } from './path-math';
-import { firstLeafAtOrAfter } from './path-lookup';
-import { blockNodeAt, nodeAt, normalizeBodyWrite, normalizeOwnRaw, writeOwnRaw } from '../tree-operations/node-primitives';
+import { charOffsetOf } from './primitives';
+import { comparePaths } from './path-math';
+import { caretPointFor } from './caret-target';
+import { docPathFrom } from '../cursor/coordinate-spaces';
+import { blockNodeAt, nodeAt, normalizeBodyWrite, normalizeOwnRaw } from '../tree-operations/node-primitives';
 import { settleSeparatorOnBlank } from '../tree-operations/settle';
-import { isBlankParagraph } from '../core/parser';
-import { displayLength } from '../core/lines';
-import { deleteAtPath } from '../tree-operations/path-mutate';
-import { cleanJoinedRaw } from '../tree-operations/node-ops';
-import { deleteSubtreesIdentityGated, installTruncatedEndpoint, reparseTruncatedEndpoint } from './range-delete-ceremony';
-import { ensureUnsharedNode, ensureUnsharedPath } from '../tree-operations/unshare';
-import { rebuildUnsharedAncestry, rebuildUnsharedChain } from '../tree-operations/chain-rebuild';
-import { involvesTable, tableAwareRangeDelete } from './range-delete-table';
-import { involvesReservedChrome, chromeAwareRangeDelete } from './range-delete-chrome';
-/** Whoever takes the slot gets the caret, at its start; the block above when nothing does. */
-function deleteWholeUnit(doc, path, sharing, grammar) {
-    const parentPath = path.slice(0, -1);
-    const index = path[path.length - 1];
-    // The path-addressed door, so the commit's id ledger sees the slot go.
-    const chain = ensureUnsharedPath(doc, parentPath, sharing);
-    deleteAtPath(doc, path, sharing);
-    if (chain.length > 0)
-        rebuildUnsharedChain(doc, chain, sharing, null, grammar);
-    const survivors = (chain.length > 0 ? chain[chain.length - 1] : doc).children ?? [];
-    const landing = Math.max(0, Math.min(index, survivors.length - 1));
-    return { newDoc: doc, collapsedCaret: { path: [...parentPath, landing], offset: 0 } };
+import { documentLineEnding } from '../core/lines';
+import { cleanJoinedRaw } from '../tree-operations/leaf-range';
+import { storedAsAt } from '../tree-operations/stored-as';
+import { joinKeepingSuffix } from '../tree-operations/structural-suffix';
+import { applyPlannedDeletion, installSurvivor, planCrossBlockDeletion, rebuildSharedAncestries } from './range-delete-ceremony';
+import { ensureUnsharedPath } from '../tree-operations/unshare';
+import { rebuildUnsharedAncestry } from '../tree-operations/chain-rebuild';
+import { clearGridCells, keepsTableEdge, tableAwareRangeDelete } from './range-delete-table';
+import { involvesReservedChrome, unjoinedRangeDelete } from './range-delete-chrome';
+/** Deletes what the coverage says the range covers, in place, merging at the start's position
+ *  inside its container; `gesture` lands the caret if a block goes. */
+export function rangeDelete(doc, coverage, sharing, reading, gesture) {
+    const { start, end } = coverage.range;
+    // A pair inside one table clears its cells, even all of them; only Backspace and Delete take
+    // the rows, columns or table away, through the table's own structural commits.
+    if (coverage.grid)
+        return clearGridCells(doc, coverage, coverage.grid, sharing, reading);
+    if (keepsTableEdge(coverage)) {
+        return tableAwareRangeDelete(doc, coverage, sharing, reading);
+    }
+    // Nothing merges across a title-line container's edge, and a range that holds an edge's block
+    // whole has nothing there to merge.
+    if (!coverage.startEdge || !coverage.endEdge || involvesReservedChrome(doc, start, end)) {
+        return unjoinedRangeDelete(doc, coverage, sharing, reading, gesture);
+    }
+    return joinedRangeDelete(doc, coverage, sharing, reading);
 }
-/**
- * Delete [start, end] in place, merge at start's position with its container context preserved,
- * cascade-clean empty ancestors, rebuild container raws. Copy-path-on-write: every spliced or
- * written spine is unshared BEFORE target identities are captured, so the identity gate compares
- * post-unshare references. Caller pre-normalizes and keeps endpoints on focusable blocks.
- */
-export function rangeDelete(doc, start, end, sharing, grammar, presentationMode, linkRef) {
+/** Deletes every subtree the range holds whole and truncates each edge it keeps, never merging:
+ *  Backspace or Delete over a table held whole removes it, where `rangeDelete` clears it. */
+export function removeHeldWhole(doc, coverage, sharing, reading, gesture) {
+    return unjoinedRangeDelete(doc, coverage, sharing, reading, gesture);
+}
+// ── Internal ────────────────────────────────────────────────────────────────
+/** Both edges kept and plain: the end's tail joins the start's head in the start's block. */
+function joinedRangeDelete(doc, coverage, sharing, reading) {
+    const { grammar } = reading;
+    const { start, end } = coverage.range;
     const startBlock = blockNodeAt(doc, start.path);
     const endBlock = blockNodeAt(doc, end.path);
     if (!startBlock || !endBlock) {
         throw new Error('rangeDelete: start or end path does not resolve to a block node');
     }
-    // The wall branches join nothing, but a truncation still strands the runs whose partner went
-    // with the cut, so their prose endpoints cross the cleaner's unpaired-run half; only the
-    // chrome child's own raw writes stay byte-literal.
-    if (involvesTable(startBlock, endBlock)) {
-        return tableAwareRangeDelete(doc, start, end, sharing, grammar, presentationMode, linkRef);
-    }
-    if (involvesReservedChrome(doc, start, end)) {
-        return chromeAwareRangeDelete(doc, start, end, sharing, grammar, presentationMode, linkRef);
-    }
     const sameBlock = comparePaths(start.path, end.path) === 0;
     const startRaw = startBlock.raw;
-    const endRaw = endBlock.raw;
-    const startOffset = charOffsetOf(start, 'rangeDelete:prose-merge-start');
+    const startCut = charOffsetOf(start, 'rangeDelete:prose-merge-start');
     const endOffset = charOffsetOf(end, 'rangeDelete:prose-merge-end');
-    // The range holds one block whole, so none of its own bytes survive: the byte arm below would
-    // keep a husk holding a bare line ending, which no reload reads as that kind. A paragraph is
-    // the one kind that survives empty, because a blank one IS the separating line below it.
-    if (sameBlock &&
-        startOffset === 0 &&
-        endOffset >= displayLength(startRaw) &&
-        !isBlankParagraph({ kind: startBlock.kind, raw: '' })) {
-        return deleteWholeUnit(doc, start.path, sharing, grammar);
-    }
-    // The end slice answers to the END block's rule before the join: start's rule below speaks
-    // only for start's bytes, so a truncation from the end block's head strands its closer. A
-    // same-block merge is one block's bytes and takes that rule once, whole, on the arm below.
-    const endTail = endRaw.slice(endOffset);
-    // A join can MINT a line neither side held: two lines each carrying a mid-line `</details>`
-    // become one that opens with it. The survivor lands in start's container, so it answers to
-    // that container's body rule, applied here so the kinds derive from the bytes that land.
-    const mergedRaw = normalizeBodyWrite(blockNodeAt(doc, start.path.slice(0, -1))?.kind, startRaw.slice(0, startOffset) + (sameBlock ? endTail : normalizeOwnRaw(endBlock, endTail)));
-    // After both normalizers and ahead of both consumers: in live the runs the truncation left
-    // unpaired, and the pair a join brings back to back, are bytes the reader never saw
-    // (live-mode.md § 4.5).
+    // A cross-block join runs the end slice through the end block's own write rule, or a cut from
+    // its head would leave its closer stranded; a same-block merge takes the rule once, below.
+    const join = sameBlock
+        ? {
+            raw: startRaw.slice(0, startCut) + startRaw.slice(endOffset),
+            start: startCut,
+            end: endOffset
+        }
+        : joinKeepingSuffix(startBlock, startCut, endBlock, endOffset, (tail) => normalizeOwnRaw(endBlock, tail, documentLineEnding(doc)));
+    const startOffset = join.start;
+    // A join can create a line neither side held (two mid-line `</details>` joined into one that
+    // opens with it), so the start container's body rule runs before kinds are derived.
+    const mergedRaw = normalizeBodyWrite(blockNodeAt(doc, start.path.slice(0, -1)) ?? undefined, join.raw, documentLineEnding(doc));
+    // Runs after both write rules and before either consumer, dropping live-mode bytes the user
+    // never saw: `docs/design/live-mode.md` § 4.5 Joins clean up where they meet.
     const joined = cleanJoinedRaw({
         mergedRaw,
         seam: startOffset,
         start: { node: startBlock, offset: startOffset },
-        end: { node: endBlock, offset: endOffset },
-        linkRef,
-        ambientPrefix: containerAmbientPrefix(doc, start.path)
-    }, presentationMode);
+        end: { node: endBlock, offset: join.end },
+        typed: '',
+        store: storedAsAt(doc, start.path, reading)
+    });
     if (sameBlock) {
         // May be nested in a blockquote/list/listItem whose raw depends on this leaf.
-        const chain = ensureUnsharedPath(doc, start.path, sharing);
-        // start.path resolved above, so the chain reaches the leaf; the fallback still routes
-        // through the unshare seam, never a raw capture.
-        const owned = chain[chain.length - 1] ?? ensureUnsharedNode(startBlock, sharing);
-        // No reparse on this arm, so the survivor's own grammar answers here: a join can mint
-        // a line the kind reads as its terminator (a fence run in a code body).
-        writeOwnRaw(owned, joined.raw, grammar);
-        // Ahead of the rebuild, which reads the body's trivia: a selection covering a block's whole
+        ensureUnsharedPath(doc, start.path, sharing);
+        const shift = installSurvivor(doc, start.path, startBlock, joined.raw, sharing, reading);
+        // Before the rebuild, which reads the blank lines: a selection covering a block's whole
         // text leaves it blank, and a blank block is the separating line of the one below it.
         const parent = nodeAt(doc, start.path.slice(0, -1));
         if (parent)
             settleSeparatorOnBlank(parent, start.path[start.path.length - 1], sharing);
-        rebuildUnsharedChain(doc, chain, sharing, null, grammar);
-        return {
-            newDoc: doc,
-            collapsedCaret: { path: start.path.slice(), offset: joined.seam }
-        };
+        rebuildUnsharedAncestry(doc, start.path, sharing, null, grammar);
+        const joinAt = { path: start.path.slice(), offset: Math.max(0, joined.seam + shift) };
+        return { newDoc: doc, caret: () => joinAt };
     }
-    // Start's slot, start's rule: the survivor answers to it BEFORE the reparse re-derives
-    // metadata, and inherits the slot's separator a fragment reparse would mint empty.
-    const replacement = reparseTruncatedEndpoint(startBlock, joined.raw);
-    // walkBetween includes ancestors of `end` whose subtrees extend past it, so filter to
-    // subtrees fully inside (start, end). Cascade-cleanup handles ancestors emptied afterwards.
-    const betweenPaths = walkBetween(doc, start.path, end.path).filter((p) => isPathSubtreeBetween(p, start.path, end.path));
-    const deletionPaths = [...betweenPaths, end.path];
-    const lcaPath = lowestCommonAncestor(start.path, end.path);
-    // Unshare every spliced spine before capturing target identities: a copy made after capture
-    // would fail the identity gate and skip the deletion.
+    // The end block goes once its tail has joined the start. Every chain is copied before the
+    // splices capture node identities, or a later copy would fail the check and skip a deletion.
     ensureUnsharedPath(doc, start.path, sharing);
-    for (const path of deletionPaths) {
-        ensureUnsharedPath(doc, path.slice(0, -1), sharing);
-    }
-    deleteSubtreesIdentityGated(doc, deletionPaths, lcaPath, sharing);
-    installTruncatedEndpoint(doc, start.path, replacement, sharing);
+    const plan = planCrossBlockDeletion(doc, coverage, [end.path], sharing);
+    applyPlannedDeletion(doc, plan, grammar);
+    const shift = installSurvivor(doc, start.path, startBlock, joined.raw, sharing, reading);
     rebuildUnsharedAncestry(doc, start.path, sharing, null, grammar);
-    for (const path of deletionPaths) {
-        rebuildUnsharedAncestry(doc, path, sharing, null, grammar);
-    }
-    // The re-parse may change kind, including leaf → CONTAINER (a list marker joined to its item
-    // text). Caret restore walks the block element at its path, and a container path drops focus
-    // on a non-editable wrapper, so descend to the leaf. The offset stays a byte coordinate (the
-    // paste and type-replace splice at it); the restore door's landable clamp owns the caret seat.
-    const leafPath = firstLeafAtOrAfter(doc, start.path);
-    const collapsedCaret = leafPath && leafPath.length > start.path.length
-        ? { path: leafPath, offset: 0 }
-        : { path: start.path.slice(), offset: joined.seam };
-    return { newDoc: doc, collapsedCaret };
-}
-/** The container prefix the survivor renders under, so the join seam can read its candidate back
- *  through it (live-mode.md § 4.5). An ambient marker rides the container's FIRST child only, the
- *  way `BlockList` forwards it, and a list item is the one built-in container that paints one. */
-function containerAmbientPrefix(doc, path) {
-    if (path.length < 2 || path[path.length - 1] !== 0)
-        return '';
-    const parent = blockNodeAt(doc, path.slice(0, -1));
-    const item = parent?.kind === 'listItem' ? metadataOf(parent, 'listItem') : null;
-    // A task item's ambient carries its checkbox too, which this derivation does not model: '' skips
-    // the read-back rather than checking it against the wrong prefix.
-    return item && !item.taskItem ? item.marker : '';
+    rebuildSharedAncestries(doc, plan, sharing, grammar);
+    // The reparse can turn the survivor into a container (a list marker joined to text), whose own
+    // element holds no caret, so the join point resolves to the leaf that holds it.
+    const joinAt = {
+        path: start.path.slice(),
+        offset: Math.max(0, joined.seam + shift)
+    };
+    const landing = caretPointFor(doc, { path: docPathFrom(joinAt.path), offset: joinAt.offset }) ?? joinAt;
+    return { newDoc: doc, caret: () => landing };
 }

package/dist/selection/round-trip-restore.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Puts back a selection saved before a detour (a presentation-mode switch, the find bar) through
+ * the caret landing's `restore`, unless a widget is still selected: then the widget stays selected
+ * and its block takes focus again, since the saved caret is only the widget's stand-in. Interim:
+ * it goes once the landing's `restore` puts a selected widget back itself.
+ */
+import type { BlockElLookup } from '../editor-keys';
+import type { CaretLanding, LandOptions } from './caret-landing';
+import type { EditorSelection } from './primitives';
+import type { SelectionRestoreOutcome } from './selection-restore';
+import type { SelectionState } from './selection-state.svelte';
+export interface RoundTripRestoreDeps {
+    selection: Pick<SelectionState, 'widget' | 'announceSelection'>;
+    landing: Pick<CaretLanding, 'restore' | 'mount'>;
+    getBlockElByPath: BlockElLookup;
+}
+export type RoundTripRestore = (selection: EditorSelection, opts?: LandOptions) => Promise<SelectionRestoreOutcome>;
+export declare function createRoundTripRestore(deps: RoundTripRestoreDeps): RoundTripRestore;

package/dist/selection/round-trip-restore.js

@@ -0,0 +1,19 @@
+/**
+ * Puts back a selection saved before a detour (a presentation-mode switch, the find bar) through
+ * the caret landing's `restore`, unless a widget is still selected: then the widget stays selected
+ * and its block takes focus again, since the saved caret is only the widget's stand-in. Interim:
+ * it goes once the landing's `restore` puts a selected widget back itself.
+ */
+export function createRoundTripRestore(deps) {
+    return async (selection, opts) => {
+        const widget = deps.selection.widget;
+        if (!widget)
+            return deps.landing.restore(selection, opts);
+        await deps.landing.mount(widget.paragraphPath);
+        const blockEl = deps.getBlockElByPath(widget.paragraphPath);
+        blockEl?.focus({ preventScroll: true });
+        // Once, as the caret restore it stands in for announces.
+        deps.selection.announceSelection();
+        return blockEl ? 'applied' : 'unplaced';
+    };
+}

package/dist/selection/selection-announcer.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The one place a `selectionChange` event is sent, and the memory of what was last sent.
+ * The editor announces its own caret placements as they happen, so the browser's later
+ * `selectionchange` has to be able to tell a position subscribers already heard from one
+ * only it saw: that is what {@link SelectionAnnouncer.announceIfMoved} is for.
+ */
+import { type EditorSelection } from './primitives';
+export interface SelectionAnnouncer {
+    /** Send the current selection, whatever was sent last. */
+    announce(): void;
+    /** Send the current selection only when it differs from the one last sent. */
+    announceIfMoved(): void;
+}
+export declare function createSelectionAnnouncer(deps: {
+    read(): EditorSelection | null;
+    emit(selection: EditorSelection | null): void;
+}): SelectionAnnouncer;

package/dist/selection/selection-announcer.js

@@ -0,0 +1,25 @@
+/**
+ * The one place a `selectionChange` event is sent, and the memory of what was last sent.
+ * The editor announces its own caret placements as they happen, so the browser's later
+ * `selectionchange` has to be able to tell a position subscribers already heard from one
+ * only it saw: that is what {@link SelectionAnnouncer.announceIfMoved} is for.
+ */
+import { selectionsEqual } from './primitives';
+export function createSelectionAnnouncer(deps) {
+    // Wrapped rather than held bare, so "nothing announced yet" is distinct from "no selection
+    // announced", which a first read of null would otherwise be mistaken for.
+    let last = null;
+    function send(selection) {
+        last = { selection };
+        deps.emit(selection);
+    }
+    return {
+        announce: () => send(deps.read()),
+        announceIfMoved() {
+            const selection = deps.read();
+            if (last && selectionsEqual(selection, last.selection))
+                return;
+            send(selection);
+        }
+    };
+}

package/dist/selection/selection-description.d.ts

@@ -1,7 +1,8 @@
 /**
- * AT announcement text for a cross-block selection. The overlay paints rects but suppresses
- * native selection, so assistive tech sees nothing without this. Counts top-level blocks
- * spanned; a selection nested inside one top-level block gets a generic phrase.
+ * The screen-reader announcement for a cross-block selection. The overlay paints rectangles
+ * but suppresses the native selection, so assistive technology sees nothing without this.
+ * Counts the top-level blocks spanned; a selection inside one top-level block gets a generic
+ * phrase.
  */
 import type { EditorSelection } from './primitives';
 export declare function createSelectionDescription(selection: EditorSelection): string;

package/dist/selection/selection-description.js

@@ -1,7 +1,8 @@
 /**
- * AT announcement text for a cross-block selection. The overlay paints rects but suppresses
- * native selection, so assistive tech sees nothing without this. Counts top-level blocks
- * spanned; a selection nested inside one top-level block gets a generic phrase.
+ * The screen-reader announcement for a cross-block selection. The overlay paints rectangles
+ * but suppresses the native selection, so assistive technology sees nothing without this.
+ * Counts the top-level blocks spanned; a selection inside one top-level block gets a generic
+ * phrase.
  */
 import { normalize } from './primitives';
 import { pathsEqual } from './path-math';
@@ -9,7 +10,7 @@ import { SELECTED_ACROSS_BLOCKS, selectedBlocks } from '../a11y-strings';
 export function createSelectionDescription(selection) {
     const { start, end } = normalize(selection);
     if (pathsEqual(start.path, end.path))
-        return ''; // single-block — native
+        return ''; // one block: the browser announces it
     // Endpoints inside one top-level block (two items of the same list) span no top-level
     // blocks, and a count would read "1" and mislead.
     if (start.path[0] === end.path[0])

package/dist/selection/selection-drop.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Dragging a selection and dropping it, as one undo entry over two raw writes (the cut, then
+ * the insert). The browser's own drag is two separate edits, which undo would take in two steps.
+ */
+import type { Document } from '../core/nodes';
+import type { Reading } from '../schema/reading';
+import type { PluginActivation } from '../schema/plugin-activation';
+import type { CommitController } from '../action-contracts';
+import type { PasteCommitCoordinator } from '../tree-operations/paste/paste-deps';
+import { type EditorEvents } from '../editor-events';
+export interface SelectionDropDeps {
+    editorRoot: HTMLElement;
+    getDoc(): Document;
+    controller: CommitController;
+    coordinator: PasteCommitCoordinator;
+    /** How the editor reads its bytes: the cut is a join, and the reparse reads its grammar. */
+    reading: Reading;
+    activePlugins: PluginActivation;
+    /** The editor's event emitter: a move that throws halfway has nowhere else to report. */
+    events: EditorEvents;
+    /** Draws the caret saying where a release lands; null takes it away again. */
+    setDropCaret(rect: DropCaretRect | null): void;
+    isReadOnly(): boolean;
+}
+/** Where the drop caret stands, in viewport coordinates. */
+export interface DropCaretRect {
+    left: number;
+    top: number;
+    height: number;
+}
+/** Where the drag started, in raw offsets of the element it started in. */
+export interface DragSource {
+    /** The editable element the range sits in: a block, or a table cell. */
+    path: number[];
+    start: number;
+    end: number;
+    inCell: boolean;
+    /** The bytes the release writes, read once at `dragstart` so the caret shown while the drag
+     *  is held and the release itself cannot disagree about what moves. */
+    text: string;
+}
+export declare function installSelectionDrop(deps: SelectionDropDeps): () => void;
+/** Where `target` ends up after a splice of `delta` blocks at `at` inside `parent`: what the
+ *  drop's second write addresses once the first write's reparse changed the block count. */
+export declare function shiftPathAfterSplice(target: number[], parent: number[], at: number, delta: number): number[];
+/** Where a drop at `offset` lands once `[start, end)` has left the same block, which shrank by
+ *  `shrunkBy` bytes after the join cleanup. Null inside the range. */
+export declare function dropOffsetAfterCut(offset: number, start: number, end: number, shrunkBy: number): number | null;
+export declare function runDrop(deps: SelectionDropDeps, from: DragSource, to: {
+    path: number[];
+    offset: number;
+}, copy: boolean): Promise<void>;