u2ui 1.5.3 → 1.5.7

package/js/rte/src/selection/map/point-map.js

@@ -0,0 +1,307 @@
+import {Point, indexOf} from '../point/point.js';
+
+export class PointMap {
+    #points = new Map();
+
+    constructor(points = []) {
+        for (const point of points) this.add(point);
+    }
+
+    add(point) {
+        assertPoint(point);
+        if (!this.#points.has(point)) {
+            this.#points.set(point, {
+                node: point.node,
+                offset: point.offset,
+                affinity: point.affinity,
+            });
+        }
+        return this;
+    }
+
+    has(point) {
+        return this.#points.has(point);
+    }
+
+    get(point) {
+        const mapped = this.#points.get(point);
+        if (!mapped) throw new RangeError('Point is not tracked by this map');
+        return new Point(mapped.node, mapped.offset, mapped.affinity);
+    }
+
+    insert(parent, offset, node) {
+        assertBoundary(parent, offset);
+        assertDetached(node, parent);
+        const reference = parent.childNodes[offset] || null;
+        parent.insertBefore(node, reference);
+        for (const point of this.#points.values()) {
+            if (point.node !== parent) continue;
+            if (point.offset > offset || point.offset === offset && point.affinity === 'forward') point.offset++;
+        }
+        return node;
+    }
+
+    insertFragment(parent, offset, fragment) {
+        assertBoundary(parent, offset);
+        if (fragment?.nodeType !== Node.DOCUMENT_FRAGMENT_NODE) {
+            throw new TypeError('Fragment insertion requires a DocumentFragment');
+        }
+        const nodes = [...fragment.childNodes];
+        const reference = parent.childNodes[offset] || null;
+        parent.insertBefore(fragment, reference);
+        for (const point of this.#points.values()) {
+            if (point.node === fragment) {
+                relocate(point, parent, offset + point.offset);
+            } else if (point.node === parent
+                && (point.offset > offset || point.offset === offset && point.affinity === 'forward')) {
+                point.offset += nodes.length;
+            }
+        }
+        return nodes;
+    }
+
+    insertText(node, offset, data) {
+        if (node?.nodeType !== Node.TEXT_NODE) throw new TypeError('Text can only be inserted into a text node');
+        if (!Number.isInteger(offset) || offset < 0 || offset > node.length) throw new RangeError('Invalid text insertion offset');
+        if (typeof data !== 'string') throw new TypeError('Inserted text must be a string');
+        node.insertData(offset, data);
+        for (const point of this.#points.values()) {
+            if (point.node !== node) continue;
+            if (point.offset > offset || point.offset === offset && point.affinity === 'forward') point.offset += data.length;
+        }
+        return node;
+    }
+
+    splitText(node, offset) {
+        if (node?.nodeType !== Node.TEXT_NODE) throw new TypeError('Only a text node can be split');
+        if (!Number.isInteger(offset) || offset < 0 || offset > node.length) throw new RangeError('Invalid text split offset');
+        if (!node.parentNode) throw new RangeError('A detached text node cannot be split by the map');
+        const parent = node.parentNode;
+        const index = indexOf(node);
+        const right = node.splitText(offset);
+        for (const point of this.#points.values()) {
+            if (point.node === node) {
+                if (point.offset > offset || point.offset === offset && point.affinity === 'forward') {
+                    point.node = right;
+                    point.offset -= offset;
+                }
+            } else if (point.node === parent && point.offset > index) {
+                point.offset++;
+            }
+        }
+        return right;
+    }
+
+    split(container, node, offset) {
+        if (container?.nodeType !== Node.ELEMENT_NODE) throw new TypeError('A split container must be an element');
+        if (node !== container && !container.contains(node)) throw new RangeError('A split boundary must belong to its container');
+        let parent = node;
+        let index = offset;
+        if (node.nodeType === Node.TEXT_NODE) {
+            if (!Number.isInteger(offset) || offset < 0 || offset > node.length) throw new RangeError('Invalid text split offset');
+            if (offset > 0 && offset < node.length) this.splitText(node, offset);
+            parent = node.parentNode;
+            index = indexOf(node) + (offset > 0 ? 1 : 0);
+            if (offset === node.length) this.#follow(node, offset, parent, index);
+        } else {
+            assertBoundary(node, offset);
+        }
+        while (parent !== container) {
+            const tail = parent.cloneNode(false);
+            tail.removeAttribute('id');
+            const grand = parent.parentNode;
+            const at = indexOf(parent) + 1;
+            this.insert(grand, at, tail);
+            // Both halves replace one element. Nothing belongs between them, and
+            // everything from the boundary onward belongs to the trailing half.
+            const trailing = [];
+            for (const point of this.#points.values()) {
+                if (point.node === grand && point.offset === at) point.offset++;
+                else if (point.node === parent && follows(point, index)) trailing.push([point, point.offset - index]);
+            }
+            while (parent.childNodes[index]) this.move(parent.childNodes[index], tail, tail.childNodes.length);
+            for (const [point, offset] of trailing) relocate(point, tail, offset);
+            parent = grand;
+            index = at;
+        }
+        return index;
+    }
+
+    wrap(nodes, wrapper) {
+        nodes = [...nodes];
+        if (!nodes.length) throw new RangeError('At least one node is required to wrap');
+        const parent = nodes[0].parentNode;
+        if (!parent || nodes.some(node => node.parentNode !== parent)) throw new RangeError('Wrapped nodes must share a parent');
+        const start = indexOf(nodes[0]);
+        if (nodes.some((node, index) => parent.childNodes[start + index] !== node)) {
+            throw new RangeError('Wrapped nodes must be contiguous and ordered');
+        }
+        assertDetached(wrapper, parent);
+        if (wrapper.childNodes.length) throw new RangeError('A wrapper must be empty');
+        const end = start + nodes.length;
+        parent.insertBefore(wrapper, nodes[0]);
+        for (const node of nodes) wrapper.append(node);
+        for (const point of this.#points.values()) {
+            if (point.node !== parent) continue;
+            if (point.offset < start) continue;
+            if (point.offset > end) {
+                point.offset += 1 - nodes.length;
+            } else if (point.offset === start) {
+                if (point.affinity === 'forward') relocate(point, wrapper, 0);
+            } else if (point.offset === end) {
+                if (point.affinity === 'backward') relocate(point, wrapper, nodes.length);
+                else point.offset = start + 1;
+            } else {
+                relocate(point, wrapper, point.offset - start);
+            }
+        }
+        return wrapper;
+    }
+
+    unwrap(wrapper) {
+        if (!wrapper?.parentNode) throw new RangeError('A detached node cannot be unwrapped');
+        const parent = wrapper.parentNode;
+        const index = indexOf(wrapper);
+        const count = wrapper.childNodes.length;
+        const fragment = wrapper.ownerDocument.createDocumentFragment();
+        while (wrapper.firstChild) fragment.append(wrapper.firstChild);
+        wrapper.replaceWith(fragment);
+        for (const point of this.#points.values()) {
+            if (point.node === wrapper) {
+                relocate(point, parent, index + point.offset);
+            } else if (point.node === parent && point.offset > index) {
+                point.offset += count - 1;
+            }
+        }
+        return wrapper;
+    }
+
+    replace(node, replacement) {
+        if (!node?.parentNode) throw new RangeError('A detached node cannot be replaced');
+        const parent = node.parentNode;
+        const index = indexOf(node);
+        assertDetached(replacement, parent);
+        node.replaceWith(replacement);
+        for (const point of this.#points.values()) {
+            if (!inside(point, node)) continue;
+            relocate(point, parent, index + (point.affinity === 'forward' ? 1 : 0));
+        }
+        return replacement;
+    }
+
+    replaceWrapper(node, replacement) {
+        if (node?.nodeType !== Node.ELEMENT_NODE || replacement?.nodeType !== Node.ELEMENT_NODE) {
+            throw new TypeError('Wrapper replacement requires two elements');
+        }
+        if (!node.parentNode) throw new RangeError('A detached element cannot be replaced');
+        assertDetached(replacement, node.parentNode);
+        if (replacement.childNodes.length) throw new RangeError('A replacement wrapper must be empty');
+        while (node.firstChild) replacement.append(node.firstChild);
+        node.replaceWith(replacement);
+        for (const point of this.#points.values()) {
+            if (point.node === node) point.node = replacement;
+        }
+        return replacement;
+    }
+
+    move(node, parent, offset) {
+        if (!node?.parentNode) throw new RangeError('A detached node cannot be moved');
+        assertBoundary(parent, offset);
+        if (node === parent || node.contains(parent)) throw new RangeError('A node cannot move into itself');
+        const oldParent = node.parentNode;
+        const oldIndex = indexOf(node);
+        const reference = parent.childNodes[offset] || null;
+        if (reference === node || oldParent === parent && node.nextSibling === reference) return node;
+        const followers = new Map();
+        for (const point of this.#points.values()) {
+            if (point.node !== oldParent) continue;
+            if (point.offset === oldIndex && point.affinity === 'forward') followers.set(point, 'before');
+            else if (point.offset === oldIndex + 1 && point.affinity === 'backward') followers.set(point, 'after');
+        }
+        parent.insertBefore(node, reference);
+        const newIndex = indexOf(node);
+        for (const point of this.#points.values()) {
+            if (followers.has(point) || inside(point, node)) continue;
+            if (point.node === oldParent && point.offset > oldIndex) point.offset--;
+            if (point.node === parent && (point.offset > newIndex || point.offset === newIndex && point.affinity === 'forward')) {
+                point.offset++;
+            }
+        }
+        for (const [point, edge] of followers) relocate(point, parent, newIndex + (edge === 'after' ? 1 : 0));
+        return node;
+    }
+
+    // A boundary expressed against a text node is the same boundary as the one
+    // after it in its parent; forward affinity has to see it that way.
+    #follow(node, offset, target, index) {
+        for (const point of this.#points.values()) {
+            if (point.node === node && point.offset === offset && point.affinity === 'forward') relocate(point, target, index);
+        }
+    }
+
+    mergeText(left, right) {
+        if (left?.nodeType !== Node.TEXT_NODE || right?.nodeType !== Node.TEXT_NODE) {
+            throw new TypeError('Only text nodes can be merged');
+        }
+        if (!left.parentNode || left.nextSibling !== right) throw new RangeError('Merged text nodes must be adjacent siblings');
+        const parent = left.parentNode;
+        const index = indexOf(right);
+        const offset = left.length;
+        left.appendData(right.data);
+        right.remove();
+        for (const point of this.#points.values()) {
+            if (point.node === right) {
+                relocate(point, left, offset + point.offset);
+            } else if (point.node === parent && point.offset === index) {
+                relocate(point, left, offset);
+            } else if (point.node === parent && point.offset > index) {
+                point.offset--;
+            }
+        }
+        return left;
+    }
+
+    remove(node) {
+        if (!node?.parentNode) throw new RangeError('A detached node cannot be removed');
+        const parent = node.parentNode;
+        const index = indexOf(node);
+        node.remove();
+        for (const point of this.#points.values()) {
+            if (inside(point, node)) relocate(point, parent, index);
+            else if (point.node === parent && point.offset > index) point.offset--;
+        }
+        return node;
+    }
+}
+
+function assertPoint(point) {
+    if (!(point instanceof Point)) throw new TypeError('A point map only tracks points');
+}
+
+function assertBoundary(node, offset) {
+    if (!node?.childNodes) throw new TypeError('A child boundary requires a DOM node');
+    if (!Number.isInteger(offset) || offset < 0 || offset > node.childNodes.length) {
+        throw new RangeError('Invalid child boundary offset');
+    }
+}
+
+function assertDetached(node, parent) {
+    if (!node?.nodeType) throw new TypeError('A DOM node is required');
+    if (node.nodeType === Node.DOCUMENT_FRAGMENT_NODE) throw new TypeError('DocumentFragment insertion is not supported yet');
+    if (node.parentNode) throw new RangeError('Inserted nodes must be detached');
+    if (node === parent || node.contains(parent)) throw new RangeError('A node cannot contain itself');
+}
+
+function follows(point, index) {
+    return point.offset > index || point.offset === index && point.affinity === 'forward';
+}
+
+function inside(point, node) {
+    return point.node === node || node.contains(point.node);
+}
+
+function relocate(point, node, offset) {
+    point.node = node;
+    point.offset = offset;
+}
+

package/js/rte/src/selection/ownership/README.md

@@ -0,0 +1,32 @@
+# Selection ownership
+
+When editable elements are nested, every node, selection, and input event must
+belong to exactly one editor. The inner editor is independent; its work must not
+leak into the outer editor.
+
+`ownership.js` finds that owning editable element and recognizes the explicit
+`contenteditable` boundaries between editors.
+
+## Contract
+
+- `editingHost(node)` returns the nearest explicit `[contenteditable]` ancestor.
+- `isEditableHost(element)` accepts the standard editable values: an empty
+  value, `true`, and `plaintext-only`.
+- `isEditingBoundary(element)` additionally recognizes `false` as an explicit
+  isolation boundary.
+- `isPlainTextHost(element)` reports `plaintext-only`, where structural editing
+  commands must not replace the browser's plain-text behavior.
+- `belongsTo(node, host)` requires DOM containment and that exact nearest host.
+- A nested editable therefore never leaks selection or mutations to its parent.
+- `selectionOf(host)` uses the host's tree selection when available and falls
+  back to its owner document for current browser interoperability.
+
+The functions use valid explicit attribute values rather than
+`isContentEditable`; inherited or invalid values belong to the nearest real
+boundary and do not create a new surface.
+
+## TODO
+
+- Verify `ShadowRoot.getSelection()` behavior in every target browser.
+- Define ownership for future non-`contenteditable` editing hosts, if needed.
+- Add composed-range ownership once interoperable browser support exists.

package/js/rte/src/selection/ownership/ownership.js

@@ -0,0 +1,42 @@
+const EDITABLE_VALUES = new Set(['', 'true', 'false', 'plaintext-only']);
+
+export function isEditableHost(element) {
+    const value = editableValue(element);
+    return value === '' || value === 'true' || value === 'plaintext-only';
+}
+
+export function isPlainTextHost(element) {
+    return editableValue(element) === 'plaintext-only';
+}
+
+export function isEditingBoundary(element) {
+    return editableValue(element) !== null;
+}
+
+// The element context of a node: itself when it is one, otherwise its parent.
+// Traversals start here so text and element boundaries behave identically.
+export function elementOf(node) {
+    return node?.nodeType === Node.ELEMENT_NODE ? node : node?.parentElement || null;
+}
+
+export function editingHost(node) {
+    for (let element = elementOf(node); element; element = element.parentElement) {
+        if (editableValue(element) !== null) return element;
+    }
+    return null;
+}
+
+export function belongsTo(node, host) {
+    return !!node && (node === host || host.contains(node)) && editingHost(node) === host;
+}
+
+export function selectionOf(host) {
+    const root = host.getRootNode();
+    return root.getSelection?.() || host.ownerDocument.getSelection();
+}
+
+function editableValue(element) {
+    if (!element?.hasAttribute?.('contenteditable')) return null;
+    const value = element.getAttribute('contenteditable').toLowerCase();
+    return EDITABLE_VALUES.has(value) ? value : null;
+}

package/js/rte/src/selection/point/README.md

@@ -0,0 +1,34 @@
+# Logical DOM points
+
+A point names one exact place in the DOM: either a character offset inside text
+or a gap between child nodes. It can represent a caret or one edge of a
+selection. Its affinity says which side it belongs to when content is inserted
+at that exact place.
+
+`point.js` stores the place as a collapsed native `Range`, allowing the browser
+to follow text splits, removals, and many other DOM mutations without marker
+elements.
+
+## Contract
+
+- A point is always a valid node/offset boundary when constructed.
+- `start`, `end`, `before`, `after`, and `fromRange` make boundary intent clear.
+- `node` and `offset` are live: they reflect native range relocation after DOM
+  mutations.
+- `backward` affinity associates an ambiguous boundary with preceding content;
+  `forward` affinity associates it with following content. DOM operation
+  mappings will honor this when the native mutation rule is ambiguous.
+- `compare()` orders points in the same DOM tree and rejects unrelated trees.
+- `range()` and `clone()` never expose mutable internal state.
+- `within(root)` checks the current relocated boundary against an editing root.
+
+The class deliberately does not serialize a child-index path. Paths become
+stale under unrelated sibling changes; live ranges plus explicit operation
+mapping provide stronger local semantics.
+
+## TODO
+
+- Extend affinity rules to content-model-defined atomic boundaries.
+- Add stable logical offsets for fully replaced subtrees.
+- Define atomic-node inside/before/after coercion through content policy.
+- Test browser differences in live-range relocation with generated mutations.

package/js/rte/src/selection/point/point.js

@@ -0,0 +1,83 @@
+export class Point {
+    #range;
+    #affinity;
+
+    constructor(node, offset, affinity = 'forward') {
+        if (!node?.nodeType) throw new TypeError('A point requires a DOM node');
+        if (affinity !== 'backward' && affinity !== 'forward') {
+            throw new TypeError('Point affinity must be backward or forward');
+        }
+        const length = boundaryLength(node);
+        if (!Number.isInteger(offset) || offset < 0 || offset > length) {
+            throw new RangeError(`Point offset must be between 0 and ${length}`);
+        }
+        const document = node.nodeType === 9 ? node : node.ownerDocument;
+        this.#range = document.createRange();
+        this.#range.setStart(node, offset);
+        this.#range.collapse(true);
+        this.#affinity = affinity;
+    }
+
+    static start(node, affinity = 'forward') {
+        return new this(node, 0, affinity);
+    }
+
+    static end(node, affinity = 'backward') {
+        return new this(node, boundaryLength(node), affinity);
+    }
+
+    static before(node, affinity = 'backward') {
+        if (!node.parentNode) throw new RangeError('A detached node has no position before it');
+        return new this(node.parentNode, indexOf(node), affinity);
+    }
+
+    static after(node, affinity = 'forward') {
+        if (!node.parentNode) throw new RangeError('A detached node has no position after it');
+        return new this(node.parentNode, indexOf(node) + 1, affinity);
+    }
+
+    static fromRange(range, edge, affinity = edge === 'end' ? 'backward' : 'forward') {
+        if (edge === 'start') return new this(range.startContainer, range.startOffset, affinity);
+        if (edge === 'end') return new this(range.endContainer, range.endOffset, affinity);
+        throw new TypeError('Range edge must be start or end');
+    }
+
+    get node() { return this.#range.startContainer; }
+    get offset() { return this.#range.startOffset; }
+    get affinity() { return this.#affinity; }
+
+    clone() {
+        return new this.constructor(this.node, this.offset, this.#affinity);
+    }
+
+    withAffinity(affinity) {
+        return new this.constructor(this.node, this.offset, affinity);
+    }
+
+    range() {
+        return this.#range.cloneRange();
+    }
+
+    compare(other) {
+        if (!(other instanceof Point)) throw new TypeError('Points can only be compared with points');
+        try {
+            return Math.sign(this.#range.compareBoundaryPoints(0, other.#range));
+        } catch {
+            throw new RangeError('Points belong to different DOM trees');
+        }
+    }
+
+    within(root) {
+        return this.node === root || root.contains(this.node);
+    }
+}
+
+function boundaryLength(node) {
+    return typeof node.length === 'number' ? node.length : node.childNodes.length;
+}
+
+// A node's child index in its parent. Child boundaries are expressed with it
+// throughout the engine, so it lives beside the point that names them.
+export function indexOf(node) {
+    return Array.prototype.indexOf.call(node.parentNode.childNodes, node);
+}

package/js/rte/src/selection/range/README.md

@@ -0,0 +1,38 @@
+# Edit ranges
+
+An edit range is the part of one editor that a command will read or change. It
+may be a caret, part of a text node, or a selection spanning several blocks.
+
+`edit-range.js` wraps an ordered native `Range` with operations needed by editor
+commands, such as finding selected text nodes, blocks, or fully covered roots.
+Native range behavior remains visible instead of being hidden behind a generic
+Proxy.
+
+## Contract
+
+- Both boundaries must belong to one explicit editable root.
+- Nested editable hosts are hard boundaries for construction and traversal.
+- `fromSelection()` returns `null` for absent or foreign selections.
+- `fromPoints()` rejects reversed points instead of silently collapsing.
+- Returned native ranges and cloned edit ranges cannot mutate the original.
+- `select()` restores forward or backward browser selections.
+- `splitTextBoundaries()` exposes exactly selected text without changing its
+  content or expanding the selection.
+- `textNodes()` returns intersecting non-empty text nodes in document order.
+- `blocks(predicate)` returns the nearest policy-defined block for each
+  selected leaf, including empty blocks, in document order. A collapsed range
+  resolves only its nearest block.
+- `roots()` returns maximal fully covered live nodes; partially selected
+  ancestors are traversed, never guessed as selected.
+- `intersects()` and `contains()` respect editable ownership.
+
+The class does not yet perform formatting. Commands will compose these
+primitives inside transactions and explicitly mark resulting dirty scopes.
+
+## TODO
+
+- Connect block predicates to the surface content model.
+- Add atomic-node coercion from content policy.
+- Add contextual fragment insertion without unsafe HTML sinks.
+- Extend the isolated browser `rangeRect()` policy with writing-mode and Shadow
+  DOM verification before adding geometry to command-level ranges.