@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/selection/caret-landing.js

@@ -0,0 +1,157 @@
+/**
+ * The one way a caret is put down after an edit or a restore: resolve the position to a leaf, mount
+ * each level on the way, check the tree is still the one the caller aimed at, place, then bring
+ * the block into view. One per editor, built in `Editor.svelte`; nothing else scrolls for a landing.
+ */
+import { assertInvariant } from '../assert';
+import { CURSOR_END, CURSOR_START } from '../block-component';
+import { docPathFrom } from '../cursor/coordinate-spaces';
+import { isDevChecks } from '../env';
+import { checkLandingFocusScrollsNothing } from '../invariants/landing-focus-scroll';
+import { descendTo } from '../reactivity/child-list';
+import { caretTargetFor } from './caret-target';
+import { applySelectionToDom } from './native-bridge';
+import { firstUsefulRect } from '../cursor/visual-lines';
+import { findBlockPathForElement, findCellPathForElement } from './path-lookup';
+import { resolveSelectionPoint, restoreGapCaret } from './selection-restore';
+import { isGapSelection } from '../undo/types';
+/** What a caret in `el` needs on screen: its line, when the selection's focus sits in `el` and
+ *  measures, else `el`'s whole box (a divider, an empty line, a caret not placed yet). */
+function caretBox(el) {
+    const selection = typeof window === 'undefined' ? null : window.getSelection();
+    if (selection?.rangeCount && selection.focusNode && el.contains(selection.focusNode)) {
+        const range = document.createRange();
+        range.setStart(selection.focusNode, selection.focusOffset);
+        const line = firstUsefulRect(range, false);
+        if (line)
+            return line;
+    }
+    return el.getBoundingClientRect();
+}
+export function createCaretLanding(deps) {
+    let generation = 0;
+    /** Runs the landing's focus and DOM placement, which scroll nothing (G1.45). */
+    function placeWithoutScrolling(place) {
+        if (!isDevChecks())
+            return place();
+        const port = deps.scroll?.port();
+        const before = port?.scrollTop() ?? null;
+        const placed = place();
+        assertInvariant('landing-focus-scrolls-nothing', () => checkLandingFocusScrollsNothing(before, port?.scrollTop() ?? null));
+        return placed;
+    }
+    /** The only place a landing writes a scroll position. */
+    async function bringIntoView(leafPath, reveal) {
+        const scroll = deps.scroll;
+        if (reveal === 'mount' || !scroll)
+            return;
+        const el = deps.getBlockElByPath([...leafPath]);
+        if (!el)
+            return;
+        if (reveal === 'held') {
+            await scroll.place(leafPath, { block: 'nearest', hold: true }).scroll();
+            return;
+        }
+        scroll.showRect(() => {
+            const caret = caretBox(el);
+            if (scroll.shows(caret))
+                return null;
+            // A block that fits shows whole, as it always has; a taller one shows the caret's line.
+            const box = el.getBoundingClientRect();
+            return box.height <= (scroll.port()?.viewportHeight() ?? 0) ? box : caret;
+        });
+    }
+    async function landAt(pos, stamp, reveal, open) {
+        const target = caretTargetFor(deps.getDoc(), pos, open);
+        if (!target)
+            return 'unresolvable';
+        const component = await descendTo(deps.root, target.leafPath, open);
+        // The one check, after every await that mounts: the tree may have been swapped meanwhile.
+        if (generation !== stamp)
+            return 'stale';
+        if (!component)
+            return 'unresolvable';
+        deps.caretMemory.forget();
+        placeWithoutScrolling(() => component.focus(target.offset));
+        // Placed at an edge rather than stepped there, so the caret means the outside of a
+        // hidden closer (`docs/design/live-mode.md` § 4.2).
+        if (target.offset === CURSOR_END || target.offset === CURSOR_START) {
+            deps.caretMemory.noteExtreme();
+        }
+        await bringIntoView(target.leafPath, reveal);
+        return 'placed';
+    }
+    return {
+        land: (pos, opts = {}) => landAt(pos, opts.stamp ?? generation, opts.reveal ?? 'into-view', {}),
+        navigate: (pos) => landAt(pos, generation, 'held', { openCollapsed: true }),
+        async restore(selection, opts = {}) {
+            const reveal = opts.reveal ?? 'into-view';
+            if (isGapSelection(selection)) {
+                return restoreGapCaret(selection.gapCaret, {
+                    getDoc: deps.getDoc,
+                    selectionState: deps.selectionState,
+                    caretMemory: deps.caretMemory,
+                    mount: (path) => descendTo(deps.root, path),
+                    reveal: (path) => bringIntoView(path, reveal)
+                });
+            }
+            const stamp = opts.stamp ?? generation;
+            const doc = deps.getDoc();
+            const anchor = resolveSelectionPoint(doc, selection.anchor);
+            const focus = resolveSelectionPoint(doc, selection.focus);
+            if (!anchor || !focus)
+                return 'unresolvable';
+            // A stored caret places at its byte, not through the block's `focus`: the byte is where a
+            // caret once sat, and a kind's own landing rule would move it.
+            const caretAt = (point) => {
+                const cell = deps.selectionState.cellLandingFor(point);
+                const target = caretTargetFor(doc, { path: docPathFrom(cell.path), offset: cell.offset });
+                return target ? { path: [...target.leafPath], offset: target.offset } : cell;
+            };
+            const route = deps.selectionState.restoreRoute(anchor, focus);
+            const holdsCaret = route === 'collapsed' || route === 'custom';
+            const mountPath = holdsCaret ? caretAt(focus).path : focus.path;
+            const mounted = await descendTo(deps.root, mountPath);
+            if (generation !== stamp)
+                return 'unplaced';
+            deps.caretMemory.forget();
+            const placed = placeWithoutScrolling(() => applySelectionToDom({ anchor, focus }, {
+                selectionState: deps.selectionState,
+                getBlockElByPath: deps.getBlockElByPath,
+                caretAt,
+                getEditorRoot: deps.getEditorRoot
+            }));
+            await bringIntoView(mountPath, reveal);
+            return mounted && placed ? 'applied' : 'unplaced';
+        },
+        async park(pos) {
+            const stamp = generation;
+            const target = caretTargetFor(deps.getDoc(), pos);
+            if (!target)
+                return false;
+            const component = await descendTo(deps.root, target.leafPath);
+            if (generation !== stamp || !component?.parkCaret)
+                return false;
+            component.parkCaret(target.offset);
+            return true;
+        },
+        mount: (path, opts) => descendTo(deps.root, path, opts),
+        followArrival(path) {
+            const el = deps.scroll && deps.getBlockElByPath([...path]);
+            const active = el ? document.activeElement : null;
+            if (!el?.contains(active))
+                return;
+            // The cell that took the caret shows whole; in any other leaf only the caret's line, or a
+            // paragraph taller than the viewport would jump the page by a screen.
+            const cell = findCellPathForElement(active);
+            const cellEl = cell && deps.getBlockElByPath(cell);
+            const leaf = findBlockPathForElement(active);
+            const leafEl = (leaf && deps.getBlockElByPath(leaf)) ?? el;
+            deps.scroll?.showRect(() => (cellEl ? cellEl.getBoundingClientRect() : caretBox(leafEl)));
+        },
+        generation: () => generation,
+        noteTreeSwap: () => {
+            generation++;
+        }
+    };
+}

package/dist/selection/caret-restore.d.ts

@@ -1,15 +1,22 @@
 /**
- * Hold the document caret while editor-owned chrome borrows focus, and put it back on close.
- * Focusing an overlay's input collapses the native selection, so the range has to live somewhere
- * that outlives the borrow.
+ * Saves the document selection while a menu or overlay input borrows focus, and puts it back on
+ * close through the caret landing's `restore`, by document path, so it survives the block being
+ * windowed out or rebuilt meanwhile.
  */
+import type { EditorSelection } from './primitives';
+import type { SelectionRestoreOutcome } from './selection-restore';
 export interface CaretRestore {
-    /** Snapshot the live caret. Null clears the slot, which makes `restore` fall back to the root. */
-    save(range: Range | null): void;
-    /** Snapshot the live caret from the window selection — the usual door. */
+    /** Saves the editor's selection as it stands, or nothing when no block holds a caret. */
     saveCurrent(): void;
-    /** Re-seat the saved caret and focus its host leaf. A container the DOM no longer holds falls
-     *  back to the editor root, so cross-block keyboard routing survives a rebuild. */
-    restore(): void;
+    /** Puts the saved selection back and brings it into view; with nothing saved, or when it no
+     *  longer lands, focuses the editor root so the keyboard still reaches the editor. */
+    restore(): Promise<void>;
 }
-export declare function createCaretRestore(getEditorEl: () => HTMLElement | null): CaretRestore;
+export interface CaretRestoreDeps {
+    getEditorEl(): HTMLElement | null;
+    /** The editor's selection, as `getSelection()` reads it. */
+    read(): EditorSelection | null;
+    /** The caret landing's `restore`. */
+    restore(selection: EditorSelection): Promise<SelectionRestoreOutcome>;
+}
+export declare function createCaretRestore(deps: CaretRestoreDeps): CaretRestore;

package/dist/selection/caret-restore.js

@@ -1,32 +1,20 @@
 /**
- * Hold the document caret while editor-owned chrome borrows focus, and put it back on close.
- * Focusing an overlay's input collapses the native selection, so the range has to live somewhere
- * that outlives the borrow.
+ * Saves the document selection while a menu or overlay input borrows focus, and puts it back on
+ * close through the caret landing's `restore`, by document path, so it survives the block being
+ * windowed out or rebuilt meanwhile.
  */
-export function createCaretRestore(getEditorEl) {
+export function createCaretRestore(deps) {
     let saved = null;
     return {
-        save(range) {
-            saved = range;
-        },
         saveCurrent() {
-            const selection = window.getSelection();
-            saved = selection && selection.rangeCount ? selection.getRangeAt(0).cloneRange() : null;
+            saved = deps.read();
         },
-        restore() {
-            const editorEl = getEditorEl();
-            if (saved && editorEl?.contains(saved.startContainer)) {
-                const node = saved.startContainer;
-                const host = node instanceof Element ? node : node.parentElement;
-                host?.closest('[contenteditable]')?.focus();
-                const selection = window.getSelection();
-                selection?.removeAllRanges();
-                selection?.addRange(saved);
-            }
-            else {
-                editorEl?.focus();
-            }
+        async restore() {
+            const selection = saved;
             saved = null;
+            if (selection && (await deps.restore(selection)) === 'applied')
+                return;
+            deps.getEditorEl()?.focus({ preventScroll: true });
         }
     };
 }

package/dist/selection/caret-target.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Where a caret lands for a position that may name a container, a collapsed container's hidden
+ * body, or the position a removed block left, decided on the tree alone before anything mounts. A
+ * collapsed container counts as its title row throughout, so no answer here opens one.
+ */
+import type { DocumentView } from '../core/node-views';
+import type { DocPath } from './path-math';
+import type { CaretPosition, SelectionPoint } from './primitives';
+/** A leaf a caret can sit in, and the offset it takes there. */
+export interface CaretTarget {
+    readonly leafPath: DocPath;
+    readonly offset: number;
+}
+/** The leaf and offset a caret at `pos` takes, or null for a path that addresses nothing. A
+ *  path into a collapsed body lands at its title row's end unless `openCollapsed` is set. */
+export declare function caretTargetFor(doc: DocumentView, pos: CaretPosition, opts?: {
+    openCollapsed?: boolean;
+}): CaretTarget | null;
+/** {@link caretTargetFor} as a byte a range edit can splice at: a start edge is the leaf's first
+ *  byte and an end edge its last, for the range edits that still type or paste at the caret. */
+export declare function caretPointFor(doc: DocumentView, pos: CaretPosition): SelectionPoint | null;
+/** What removed a block: the key pressed (by its `KeyboardEvent.key`), a cut, or a delete no key
+ *  asked for (the block menu, or typing and pasting over a range). */
+export type RemovalGesture = 'Backspace' | 'Delete' | 'cut' | 'keyless';
+/** Where the caret goes once the block at `removedPath` is gone, read after the removal: Backspace
+ *  and a keyless delete prefer the previous block's end, Delete and cut the next block's start. */
+export declare function survivorAfterRemoval(doc: DocumentView, removedPath: readonly number[], gesture: RemovalGesture): CaretPosition | null;
+/** Where a range picks up once it took the block at `removedPath` whole and ran on past it: the
+ *  start of what's left of its end, whatever removed it. */
+export declare function survivorWhereRangeResumes(doc: DocumentView, removedPath: readonly number[]): CaretPosition | null;

package/dist/selection/caret-target.js

@@ -0,0 +1,84 @@
+/**
+ * Where a caret lands for a position that may name a container, a collapsed container's hidden
+ * body, or the position a removed block left, decided on the tree alone before anything mounts. A
+ * collapsed container counts as its title row throughout, so no answer here opens one.
+ */
+import { CURSOR_END, CURSOR_START, entryEdge } from '../block-component';
+import { docPathFrom } from '../cursor/coordinate-spaces';
+import { blockNodeAt, isBlockNode, nodeAt } from '../tree-operations/node-primitives';
+import { displayLength } from '../core/lines';
+import { leafAtRawOffset } from '../tree-operations/container-offsets';
+import { caretChildCount } from '../schema/reserved-chrome';
+import { collapsedContainerHiding, firstCaretLeafFrom, previousCaretPath } from './path-lookup';
+// ── Public API ──────────────────────────────────────────────────────────────
+/** The leaf and offset a caret at `pos` takes, or null for a path that addresses nothing. A
+ *  path into a collapsed body lands at its title row's end unless `openCollapsed` is set. */
+export function caretTargetFor(doc, pos, opts = {}) {
+    let path = [...pos.path];
+    let offset = pos.offset;
+    if (!nodeAt(doc, path))
+        return null;
+    for (;;) {
+        const hiding = opts.openCollapsed ? null : collapsedContainerHiding(doc, path);
+        if (hiding) {
+            path = [...hiding, 0];
+            offset = CURSOR_END;
+        }
+        const node = nodeAt(doc, path);
+        if (!node.children?.length) {
+            return path.length > 0 ? { leafPath: docPathFrom(path), offset } : null;
+        }
+        const edge = entryEdge(offset);
+        const byteLeaf = edge.inside && isBlockNode(node) ? leafAtRawOffset(node, offset) : null;
+        if (byteLeaf) {
+            path = [...path, ...byteLeaf.path];
+            offset = byteLeaf.offset;
+            continue;
+        }
+        const reachable = isBlockNode(node) ? caretChildCount(node) : node.children.length;
+        path = [...path, edge.child === 'first' ? 0 : reachable - 1];
+        offset = edge.offset;
+    }
+}
+/** {@link caretTargetFor} as a byte a range edit can splice at: a start edge is the leaf's first
+ *  byte and an end edge its last, for the range edits that still type or paste at the caret. */
+export function caretPointFor(doc, pos) {
+    const target = caretTargetFor(doc, pos);
+    if (!target)
+        return null;
+    const leaf = blockNodeAt(doc, target.leafPath);
+    // The start sentinels are the negative ones.
+    const offset = target.offset === CURSOR_END ? displayLength(leaf?.raw ?? '') : Math.max(0, target.offset);
+    return { path: [...target.leafPath], offset };
+}
+/** Where the caret goes once the block at `removedPath` is gone, read after the removal: Backspace
+ *  and a keyless delete prefer the previous block's end, Delete and cut the next block's start. */
+export function survivorAfterRemoval(doc, removedPath, gesture) {
+    const pointsForward = gesture === 'Delete' || gesture === 'cut';
+    return survivorBeside(doc, removedPath, pointsForward);
+}
+/** Where a range picks up once it took the block at `removedPath` whole and ran on past it: the
+ *  start of what's left of its end, whatever removed it. */
+export function survivorWhereRangeResumes(doc, removedPath) {
+    return survivorBeside(doc, removedPath, true);
+}
+// ── Internal ────────────────────────────────────────────────────────────────
+function survivorBeside(doc, removedPath, forward) {
+    const slot = liveSlot(doc, removedPath);
+    if (!slot)
+        return null;
+    const previous = previousCaretPath(doc, slot);
+    const next = firstCaretLeafFrom(doc, slot);
+    const atEnd = previous && { path: docPathFrom(previous), offset: CURSOR_END };
+    const atStart = next && { path: docPathFrom(next), offset: CURSOR_START };
+    return forward ? (atStart ?? atEnd) : (atEnd ?? atStart);
+}
+/** `removedPath`, or its nearest ancestor's position when the removal emptied the parent and took
+ *  it too (the path then resolves to nothing, or to a childless neighbour or the new empty block). */
+function liveSlot(doc, removedPath) {
+    let slot = [...removedPath];
+    while (slot.length > 1 && !nodeAt(doc, slot.slice(0, -1))?.children?.length) {
+        slot = slot.slice(0, -1);
+    }
+    return slot.length > 0 ? slot : null;
+}

package/dist/selection/char-endpoint-snap.d.ts

@@ -1,15 +1,11 @@
 /**
- * The char-space funnel, sibling of `table-endpoint-snap.ts`'s cell-space one: a cross-block
- * endpoint's offset lands inside its own block's raw, and inside a kind with no character
- * positions it lands on one of the two ends — a hit-test over such a block's rendered body walks
- * chrome text and mints neither. Whole-unit inclusion is the rule: the side comes from document
- * order against the other endpoint, never the anchor/focus role, which `normalize` reorders later.
+ * Clamps a cross-block endpoint's character offset into its own block's raw, the counterpart of
+ * `table-endpoint-snap.ts` for cells. Inside a kind with no character positions the endpoint
+ * snaps to whichever end faces the other endpoint in document order, never by anchor/focus
+ * role, since `normalize` reorders those later.
  */
 import type { DocumentView } from '../core/node-views';
 import { type SelectionEndpoint, type SelectionPoint } from './primitives';
-/**
- * `endpoint` in its block's legal char space. Equal paths carry no document order — and no
- * cross-block range — so they resolve to the block start. Tables are the cell funnel's subject
- * and pass through untouched.
- */
+/** `endpoint` clamped into its block's character range; equal paths resolve to the block start.
+ *  A table endpoint never arrives here, since the cell snap turned it into a cell index. */
 export declare function normalizeCharEndpoint(doc: DocumentView, endpoint: SelectionEndpoint, otherPath: readonly number[]): SelectionPoint;

package/dist/selection/char-endpoint-snap.js

@@ -1,20 +1,16 @@
 /**
- * The char-space funnel, sibling of `table-endpoint-snap.ts`'s cell-space one: a cross-block
- * endpoint's offset lands inside its own block's raw, and inside a kind with no character
- * positions it lands on one of the two ends — a hit-test over such a block's rendered body walks
- * chrome text and mints neither. Whole-unit inclusion is the rule: the side comes from document
- * order against the other endpoint, never the anchor/focus role, which `normalize` reorders later.
+ * Clamps a cross-block endpoint's character offset into its own block's raw, the counterpart of
+ * `table-endpoint-snap.ts` for cells. Inside a kind with no character positions the endpoint
+ * snaps to whichever end faces the other endpoint in document order, never by anchor/focus
+ * role, since `normalize` reorders those later.
  */
 import { displayLength, snapToScalarBoundary } from '../core/lines';
 import { isBlockNode, nodeAt } from '../tree-operations/node-primitives';
 import { isWholeBlockUnit } from '../schema/whole-block-unit';
 import { comparePaths } from './path-math';
 import { isWholeBlockEndpoint } from './primitives';
-/**
- * `endpoint` in its block's legal char space. Equal paths carry no document order — and no
- * cross-block range — so they resolve to the block start. Tables are the cell funnel's subject
- * and pass through untouched.
- */
+/** `endpoint` clamped into its block's character range; equal paths resolve to the block start.
+ *  A table endpoint never arrives here, since the cell snap turned it into a cell index. */
 export function normalizeCharEndpoint(doc, endpoint, otherPath) {
     const node = nodeAt(doc, endpoint.path);
     if (!node || !isBlockNode(node)) {
@@ -27,13 +23,11 @@ export function normalizeCharEndpoint(doc, endpoint, otherPath) {
     };
     if (isWholeBlockEndpoint(endpoint))
         return wholeUnit;
-    if (node.kind === 'table')
-        return endpoint;
     if (isWholeBlockUnit(node)) {
         return endpoint.offset === 0 || endpoint.offset === end ? endpoint : wholeUnit;
     }
-    // Range AND scalar: `setSelection` takes plain numbers, so this is the only gate between a
-    // caller's arithmetic and a delete that would halve an astral scalar.
+    // `setSelection` takes plain numbers, so the snap here is the only check between a caller's
+    // arithmetic and a delete that splits a surrogate pair.
     const clamped = snapToScalarBoundary(node.raw, Math.min(Math.max(endpoint.offset, 0), end));
     return clamped === endpoint.offset ? endpoint : { path: endpoint.path.slice(), offset: clamped };
 }

package/dist/selection/clipboard-text.d.ts

@@ -1,13 +1,6 @@
-/**
- * Cross-block clipboard text collection.
- */
-import type { SelectionPoint } from './primitives';
+/** Builds the plain text a cross-block selection puts on the clipboard. */
 import type { DocumentView } from '../core/node-views';
-/**
- * Plain text spanning a cross-block selection: the start block's tail, every middle block's
- * leadingTrivia + raw, the end block's head. Descendants of an already-collected container
- * are skipped, since a container's raw already holds its children's text. Full-boundary leaf
- * endpoints promote to their deepest non-shared container ancestor so list markers and
- * blockquote prefixes survive; a start inside reserved chrome re-emits its container once.
- */
-export declare function collectCrossBlockText(doc: DocumentView, anchor: SelectionPoint, focus: SelectionPoint): string;
+import type { RangeCoverage } from './range-coverage';
+/** The plain text of a covered range: whatever the coverage says is covered end to end is copied
+ *  whole, markers included, and a selection inside one table copies its rectangle. */
+export declare function collectCrossBlockText(doc: DocumentView, coverage: RangeCoverage): string;