u2ui 1.5.2 → 1.5.4

package/js/rte/src/input/input-pipeline.js

@@ -0,0 +1,414 @@
+import {htmlModel} from '../model/html/html-model.js';
+import {narrow} from '../command/edit.js';
+import {Normalizer} from '../normalize/normalizer/normalizer.js';
+import {PointMap} from '../selection/map/point-map.js';
+import {EditRange} from '../selection/range/edit-range.js';
+import {editingHost, isPlainTextHost} from '../selection/ownership/ownership.js';
+import {Point} from '../selection/point/point.js';
+import {SelectionSnapshot} from '../selection/snapshot.js';
+import {defaultUnstyle} from '../unstyle/unstyle.js';
+import {sanitizePolicy} from '../sanitize/policy.js';
+
+const TRIGGERS = new Set(['input', 'paste', 'drop', 'command']);
+const PASTE = new Set(['insertFromPaste', 'insertFromPasteAsQuotation']);
+// An element a strict import list does not carry, but whose meaning a listed one
+// does. Dropping `<b>` would lose the emphasis; `<strong>` keeps it, and the
+// bold mark already treats the two as the same thing.
+export const importAliases = Object.freeze({b: 'strong', i: 'em', strike: 's'});
+
+const DELETE_KEYS = new Map([
+    ['Backspace', 'deleteContentBackward'],
+    ['Delete', 'deleteContentForward'],
+]);
+
+export class InputPipeline {
+    #surface;
+    #root;
+    #model;
+    #commands;
+    #unstyle;
+    #sanitize;
+    #aliases;
+    #controller;
+    #pending = null;
+    #source = null;
+    #deferred = null;
+    #composing = false;
+    #connected = true;
+
+    constructor(surface, {model = htmlModel, commands = null, unstyle = defaultUnstyle,
+        sanitize = sanitizePolicy, aliases = importAliases} = {}) {
+        const root = surface?.element;
+        if (root?.nodeType !== Node.ELEMENT_NODE || typeof surface?.transact !== 'function') {
+            throw new TypeError('An input pipeline requires an editor surface');
+        }
+        if (typeof model?.block !== 'function' || typeof model?.allows !== 'function'
+            || typeof model?.allowed !== 'function') {
+            throw new TypeError('An input pipeline requires a content model');
+        }
+        if (commands !== null && (typeof commands?.input !== 'function' || typeof commands?.run !== 'function')) {
+            throw new TypeError('An input pipeline requires a command registry');
+        }
+        if (unstyle !== null && typeof unstyle?.clean !== 'function') {
+            throw new TypeError('An input pipeline requires an Unstyle policy or null');
+        }
+        if (sanitize !== null && typeof sanitize?.clean !== 'function') {
+            throw new TypeError('An input pipeline requires a sanitize policy or null');
+        }
+        this.#surface = surface;
+        this.#root = root;
+        this.#model = model;
+        this.#commands = commands;
+        this.#unstyle = unstyle;
+        this.#sanitize = sanitize;
+        this.#aliases = aliases;
+        this.#controller = new root.ownerDocument.defaultView.AbortController();
+        const listen = {signal: this.#controller.signal};
+        root.addEventListener('beforeinput', this.#beforeInput, listen);
+        root.addEventListener('keydown', this.#keyDown, listen);
+        root.addEventListener('input', this.#input, listen);
+        root.addEventListener('compositionstart', this.#compositionStart, listen);
+        root.addEventListener('compositionend', this.#compositionEnd, listen);
+        root.addEventListener('paste', this.#paste, listen);
+        root.addEventListener('drop', this.#drop, listen);
+        surface.addEventListener('u2-rte-command', this.#command, listen);
+        surface.addEventListener('u2-rte-disconnect', this.#disconnect, listen);
+    }
+
+    get surface() { return this.#surface; }
+    get root() { return this.#root; }
+    get commands() { return this.#commands; }
+    get connected() { return this.#connected; }
+    get composing() { return this.#composing; }
+
+    normalize(trigger = 'command', {scope = null, range = null, inputType = '', imported = null} = {}) {
+        if (!this.#connected) throw new DOMException('The input pipeline is disconnected', 'InvalidStateError');
+        if (!TRIGGERS.has(trigger)) throw new TypeError('Unknown normalization trigger');
+        const settings = this.#surface.config;
+        if (!settings.cleanOn.includes(trigger)) return null;
+
+        const model = this.#commands?.model || narrow(this.#model, settings.elements);
+        const normalizer = new Normalizer(this.#root, {
+            model,
+            block: settings.block,
+            level: settings.cleanup,
+        });
+        const snapshot = this.#surface.capture();
+        const initial = snapshot ? rangePoints(snapshot.range()) : [];
+        const result = this.#surface.transact(transaction => {
+            let points = initial;
+            // Where to repair is decided before anything moves: narrowing
+            // dissolves the very nodes that say where the import landed.
+            const reach = () => points.length
+                ? EditRange.fromPoints(points[0], points.at(-1), this.#root).range()
+                : range || selectionRange(this.#surface);
+            let target = scope || normalizationScope(affected(reach(), imported, this.#root), this.#root, normalizer);
+            // What may exist at all is decided before what it should look like.
+            // A native paste is the one import the browser inserts itself, so
+            // this is where the policy reaches it: elements first, because
+            // unwrapping moves nodes, then attributes.
+            if (this.#sanitize && settings.importSanitize === 'policy' && imported?.roots.length) {
+                // Attributes first: removing them moves nothing, while narrowing
+                // dissolves wrappers and would leave nothing left to clean.
+                for (const root of imported.roots) {
+                    this.#sanitize.clean(root, {
+                        preserve: imported.preserve,
+                        base: this.#root.ownerDocument.baseURI,
+                        classes: settings.classes.length ? settings.classes : null,
+                    });
+                }
+                const map = new PointMap(points);
+                for (const root of imported.roots) {
+                    this.#sanitize.narrow(root, {
+                        map,
+                        preserve: imported.preserve,
+                        elements: importable(settings),
+                        alias: this.#aliases,
+                        // What the model already rejects is structural repair's
+                        // job: it dissolves a block without joining two lines.
+                        skip: element => !model.allows(element.parentNode, element),
+                    });
+                }
+                points = points.map(point => map.get(point));
+            }
+            const unstyled = [];
+            if (this.#unstyle && settings.importUnstyle !== 'none' && imported?.roots.length) {
+                const map = new PointMap(points);
+                for (const root of imported.roots) {
+                    unstyled.push(...this.#unstyle.clean(root, {
+                        through: settings.importUnstyle,
+                        map,
+                        transaction,
+                        preserve: imported.preserve,
+                        keep: settings.classes,
+                    }));
+                }
+                points = points.map(point => map.get(point));
+            }
+            if (target !== this.#root && !this.#root.contains(target)) target = this.#root;
+            const normalized = normalizer.normalize({scope: target, points, transaction});
+            if (snapshot) EditRange.fromPoints(normalized.map.get(points[0]), normalized.map.get(points.at(-1)), this.#root)
+                .select(this.#surface.core.selection, snapshot.backward);
+            return unstyled.length
+                ? Object.freeze({...normalized, unstyled: Object.freeze(unstyled)})
+                : normalized;
+        }, {trigger, inputType});
+        if (result) this.#surface.emit('u2-rte-normalize', {trigger, inputType, result});
+        return result || null;
+    }
+
+    dispose() {
+        if (!this.#connected) return;
+        this.#controller.abort();
+        this.#clearPending();
+        this.#source = null;
+        this.#deferred = null;
+        this.#composing = false;
+        this.#connected = false;
+    }
+
+    [Symbol.dispose]() {
+        this.dispose();
+    }
+
+    #beforeInput = event => {
+        if (!this.#owns(event)) return;
+        this.#surface.capture();
+        if (event.defaultPrevented) return;
+        if (this.#route(event)) return;
+        this.#clearPending();
+        const pending = {
+            inputType: event.inputType || '',
+            range: inputRange(event, this.#surface),
+            trigger: this.#source || inputTrigger(event.inputType),
+        };
+        this.#observe(pending);
+        this.#pending = pending;
+        this.#source = null;
+        queueMicrotask(() => {
+            if (this.#pending === pending) this.#clearPending();
+        });
+    };
+
+    #keyDown = event => {
+        if (!this.#owns(event)) return;
+        const shortcut = this.#commands?.shortcut(event);
+        if (shortcut) {
+            this.#surface.capture();
+            if (this.#invoke(event, shortcut, {range: selectionRange(this.#surface)})) return;
+        }
+        if (event.altKey) return;
+        const inputType = keyInput(event);
+        if (!inputType) return;
+        this.#surface.capture();
+        this.#route(event, {
+            inputType,
+            data: null,
+            range: selectionRange(this.#surface),
+        });
+    };
+
+    #input = event => {
+        if (!this.#owns(event)) return;
+        const pending = this.#pending;
+        const inputType = event.inputType || pending?.inputType || '';
+        const job = {
+            inputType,
+            range: pending?.range || inputRange(event, this.#surface),
+            trigger: pending?.trigger || this.#source || inputTrigger(inputType),
+            imported: takeImports(pending, this.#root),
+        };
+        this.#clearPending();
+        this.#source = null;
+        if (this.#composing || event.isComposing) {
+            this.#deferred = job;
+            return;
+        }
+        this.#deferred = null;
+        this.normalize(job.trigger, job);
+    };
+
+    #compositionStart = event => {
+        if (!this.#owns(event)) return;
+        this.#composing = true;
+        this.#deferred = null;
+    };
+
+    #compositionEnd = event => {
+        if (!this.#owns(event)) return;
+        this.#composing = false;
+        queueMicrotask(() => {
+            if (!this.#connected || this.#composing || !this.#deferred) return;
+            const job = this.#deferred;
+            this.#deferred = null;
+            this.normalize(job.trigger, job);
+        });
+    };
+
+    #paste = event => {
+        if (this.#owns(event)) this.#rememberSource('paste');
+    };
+
+    #drop = event => {
+        if (this.#owns(event)) this.#rememberSource('drop');
+    };
+
+    #command = event => {
+        if (!event.detail.transaction) return;
+        this.normalize('command', {inputType: event.detail.inputType || ''});
+    };
+
+    #disconnect = () => {
+        this.dispose();
+    };
+
+    // Native editing that cannot be interoperable is prevented and replaced by
+    // the registered command. Everything else keeps its native behavior and is
+    // repaired afterwards.
+    #route(event, detail = {
+        inputType: event.inputType,
+        data: event.data,
+        range: inputRange(event, this.#surface),
+    }) {
+        const name = this.#commands?.input(detail.inputType);
+        return !!name && this.#invoke(event, name, detail);
+    }
+
+    // A command replaces the native event only where it is actually available;
+    // otherwise the key keeps its own meaning, which is what lets Tab go on
+    // moving focus outside a list.
+    #invoke(event, name, detail) {
+        if (!event.cancelable || event.defaultPrevented || this.#composing
+            || event.isComposing || isPlainTextHost(this.#root)) return false;
+        if (!this.#commands.enabled(name, detail)) return false;
+        event.preventDefault();
+        this.#clearPending();
+        this.#source = null;
+        this.#commands.run(name, detail);
+        return true;
+    }
+
+    #rememberSource(trigger) {
+        this.#source = trigger;
+        queueMicrotask(() => {
+            if (this.#source === trigger) this.#source = null;
+        });
+    }
+
+    // What arrived is tracked for every cleaned paste or drop, not only when
+    // presentation cleanup is configured: structural repair needs to know where
+    // the content landed just as much.
+    #observe(pending) {
+        const settings = this.#surface.config;
+        if (!['paste', 'drop'].includes(pending.trigger) || !settings.cleanOn.includes(pending.trigger)) return;
+        const records = [];
+        const Observer = this.#root.ownerDocument.defaultView.MutationObserver;
+        const observer = new Observer(next => records.push(...next));
+        observer.observe(this.#root, {childList: true, subtree: true});
+        pending.import = {
+            observer,
+            records,
+            preserve: new Set(this.#root.querySelectorAll('*')),
+        };
+    }
+
+    #clearPending() {
+        this.#pending?.import?.observer.disconnect();
+        this.#pending = null;
+    }
+
+    #owns(event) {
+        const target = event.composedPath()[0];
+        return target === this.#root || editingHost(target) === this.#root;
+    }
+}
+
+function keyInput(event) {
+    if (event.ctrlKey || event.metaKey || event.shiftKey) return null;
+    return DELETE_KEYS.get(event.key) || null;
+}
+
+export function inputTrigger(inputType = '') {
+    if (PASTE.has(inputType)) return 'paste';
+    if (inputType === 'insertFromDrop') return 'drop';
+    return 'input';
+}
+
+// Pasted or dropped content is not where the caret ends up — the caret sits at
+// the end of it. Cleanup has to cover what actually arrived, or a pasted
+// document is only ever repaired in its last block.
+function affected(range, imported, root) {
+    let common = range?.commonAncestorContainer || null;
+    for (const node of imported?.roots || []) {
+        if (!root.contains(node)) continue;
+        common = common ? shared(common, node, root) : node;
+    }
+    return common;
+}
+
+function shared(node, other, root) {
+    let current = node;
+    while (current && current !== root && current !== other && !current.contains(other)) {
+        current = current.parentNode;
+    }
+    return current || root;
+}
+
+// What may arrive is the import policy bounded by what the host tolerates at
+// all; either alone may be open.
+function importable(settings) {
+    if (settings.importElements === null) return settings.elements;
+    if (settings.elements === null) return settings.importElements;
+    return settings.importElements.filter(name => settings.elements.includes(name));
+}
+
+function normalizationScope(node, root, normalizer) {
+    let element = node?.nodeType === Node.ELEMENT_NODE ? node : node?.parentElement;
+    if (!element || (element !== root && !root.contains(element))) return root;
+    while (element !== root && !normalizer.planner.model.block(element)) element = element.parentElement;
+    if (element === root) return root;
+    const parent = element.parentElement;
+    return normalizer.planner.plan(parent, element).type === 'keep' ? element : parent;
+}
+
+export function inputRange(event, surface) {
+    const target = event.getTargetRanges?.()[0];
+    if (!target) return selectionRange(surface);
+    try {
+        const range = surface.element.ownerDocument.createRange();
+        range.setStart(target.startContainer, target.startOffset);
+        range.setEnd(target.endContainer, target.endOffset);
+        return surface.element.contains(range.commonAncestorContainer) ? range : null;
+    } catch {
+        return null;
+    }
+}
+
+function selectionRange(surface) {
+    return SelectionSnapshot.capture(surface.core.selection, surface.element)?.range() || null;
+}
+
+function rangePoints(range) {
+    const start = Point.fromRange(range, 'start');
+    return range.collapsed ? [start] : [start, Point.fromRange(range, 'end')];
+}
+
+function takeImports(pending, root) {
+    if (!pending?.import) return null;
+    const {observer, records, preserve} = pending.import;
+    records.push(...observer.takeRecords());
+    const roots = importRoots(records.flatMap(record => [...record.addedNodes]), root, preserve);
+    return roots.length ? {roots, preserve} : null;
+}
+
+function importRoots(nodes, root, preserve) {
+    const elements = new Set();
+    for (const node of nodes) {
+        if (node.nodeType !== Node.ELEMENT_NODE || !root.contains(node)) continue;
+        if (!preserve.has(node)) elements.add(node);
+        for (const child of node.querySelectorAll('*')) if (!preserve.has(child)) elements.add(child);
+    }
+    const added = [...elements];
+    return added.filter(node => !added.some(parent => parent !== node && parent.contains(node)));
+}
+

package/js/rte/src/mark/README.md

@@ -0,0 +1,219 @@
+# Text formatting marks
+
+A mark is formatting attached to text. Bold is a mark. A link is a mark with a
+URL. A text color is a mark with a color value. Several marks can apply to the
+same text, for example bold plus a link.
+
+`mark.js` represents this formatting as immutable data. It answers the small,
+shared questions that every formatting command has:
+
+- Are two marks the same?
+- May they exist together?
+- Does a new mark replace an old one?
+- In which stable order are several marks kept?
+
+`dom-adapter.js` decides whether a mark is represented by `<strong>`, a class,
+an attribute, a style, or something custom. `standard.js` provides the compact
+default HTML policies for bold, italic, underline, strike, code, and links. The
+range commands apply or remove those representations on selected text.
+
+## Public contract
+
+`MarkType` describes one kind of formatting. `bold`, `link`, and `color` are
+different types. One type may have several concrete values: `color` can be
+`red` or `blue`, and `link` can contain different URLs.
+
+`new MarkType(name, options)` accepts:
+
+- `rank` controls the stable order when several marks apply. Lower ranks come
+  first. The default is `50`.
+- `excludes` names the types removed when this type is added. By default a type
+  replaces its own previous value, so blue replaces red. `[]` allows several
+  values of that type at once; `['*']` replaces every mark.
+- `create(value)` snapshots serializable value data and returns a `Mark`. The
+  default value is `true`, which suits boolean marks such as bold.
+- `remove(marks)` removes every mark of exactly that type.
+
+A `Mark` is one concrete piece of formatting, such as `bold: true`,
+`color: "red"`, or `link: {href: "/docs"}`. A mark array describes all
+formatting at one text position.
+
+- `equals(mark)` compares type identity and canonical value data.
+- `conflicts(mark)` reports exclusion in either direction.
+- `add(marks)` returns a new frozen array in stable order. Adding the same mark
+  changes nothing. A new mark removes types it excludes; an existing mark may
+  block it through a one-way exclusion.
+- `remove(marks)` removes only that exact type and value.
+
+`markSet(marks)` folds a complete array through those same rules and returns its
+frozen canonical set. Equivalent values collapse, one-way exclusions always
+favor the excluding type, and the later value wins when two marks exclude each
+other.
+
+Values may contain strings, finite numbers, booleans, `null`, arrays, and plain
+objects. Objects are copied with sorted keys and all copied containers are
+frozen. The same link therefore compares equal even when its object keys were
+written in a different order. Functions, DOM nodes, cyclic data, and other
+stateful objects are not mark values.
+
+```js
+const bold = new MarkType('bold', {rank: 10});
+const color = new MarkType('color');
+
+let marks = bold.create().add([]);
+marks = color.create('red').add(marks);
+marks = color.create('blue').add(marks); // replaces red
+
+// marks now means: bold text with the color blue
+```
+
+## DOM adapter
+
+A `MarkAdapter` translates between formatting data and HTML. Reading recognizes
+existing elements; rendering creates the empty canonical wrapper used for bare
+or partially selected text.
+
+```js
+const boldHtml = new MarkAdapter(bold, {
+    selector: 'strong, b', // both existing forms mean bold
+    tag: 'strong',         // new bold text uses <strong>
+});
+
+boldHtml.parse(document.querySelector('b')); // a bold Mark
+boldHtml.render(bold.create(), document);     // an empty <strong>
+```
+
+`selector` selects possible source elements. `read(element)` returns their mark
+value or `undefined` when a selected element does not represent the mark.
+`tag` plus `write(element, value)` creates the canonical wrapper. `write` can
+also decorate a reusable existing element. `clear(element, value)` removes only
+this mark and leaves its other classes or attributes alone. Returning `true`
+additionally asks the command to remove the representation wrapper. A bare
+wrapper is unwrapped; remaining attributes are retained on a neutral `span`. A
+custom `render(document, value)` may replace `tag` for custom elements or other
+application policies.
+
+The same contract handles semantic elements, classes, HTML attributes, and CSS
+declarations because their `read`, `write`, and `clear` functions differ while
+the mark value and command logic stay the same. Rendered wrappers must be empty,
+detached, and owned by the requested document.
+
+`reuse` is `false` by default. Set it to `true` to allow every suitable,
+fully-selected phrasing element, or provide a function to restrict reuse
+further. The range command still excludes blocks, atomic elements, the editing
+host, and nested editable boundaries.
+
+```js
+const x = new MarkType('x');
+const xHtml = new MarkAdapter(x, {
+    selector: '.x',
+    tag: 'span',
+    reuse: true,
+    write: element => element.classList.add('x'),
+    clear: element => element.classList.remove('x'),
+});
+```
+
+With that adapter, selecting `llo` in `hello` creates
+`he<span class="x">llo</span>`. Selecting a complete `<b>dear</b>` reuses it as
+`<b class="x">dear</b>`. Removal keeps the `<b>` and only unwraps a `span` when
+clearing the mark leaves it without attributes.
+
+## Standard HTML marks
+
+```js
+import {bold, boldHtml, italicHtml, link, linkHtml} from './rte.js';
+
+boldHtml.parse(document.querySelector('b')); // bold.create()
+boldHtml.render(bold.create(), document);     // <strong>
+italicHtml.render(italicHtml.type.create(), document); // <em>
+linkHtml.render(link.create({href: '/docs'}), document); // <a href="/docs">
+```
+
+Each exported type has one replaceable default adapter:
+
+| Type | Accepted HTML | Canonical HTML |
+| --- | --- | --- |
+| `bold` | `strong`, `b` | `strong` |
+| `italic` | `em`, `i` | `em` |
+| `underline` | `u` | `u` |
+| `strike` | `s`, `strike` | `s` |
+| `code` | `code` | `code` |
+| `link` | `a[href]` | `a` |
+
+Boolean marks use the default value `true`. A link uses
+`{href, target?, rel?, title?}` with string values; other keys are rejected so
+distinct mark values cannot silently render as the same HTML. The adapter does
+not impose a URL-scheme policy. Applications must validate command input, while
+external HTML remains the sanitizer's responsibility.
+
+Removing a bare semantic alias unwraps it. Unrelated attributes survive on a
+neutral `span`; replacing part of an attributed link therefore neither loses
+those attributes nor nests anchors.
+
+Applying a mark joins adjacent canonical wrappers produced by that adapter, so
+two neighboring `<span class="x">` elements become one. A wrapper carrying
+additional classes, attributes, or tag semantics is preserved: the adapter
+cannot assume that those mean the same thing as its mark.
+
+Canonical wrappers are also normalized across nested runs. Redundant nested
+copies are removed. A complete set orders single-child canonical wrappers by
+the set's stable rank, then repeatedly joins siblings exposed by that ordering.
+For example, opposite `bold/color` nesting on neighboring runs becomes one
+`bold` wrapper containing one `color` wrapper. Reordering happens only when the
+content model accepts both resulting relationships. A wrapper with additional
+attributes is meaningful and remains a boundary.
+
+Range commands expose `true`, `false`, or `'mixed'` state for selected editable
+text. At a caret they report whether its structural DOM position is inside the
+mark; a boundary outside a wrapper stays outside. Atomic elements and nested
+editable hosts are ignored because the same commands cannot format their
+contents. Toggle removes a fully active mark and applies it across inactive or
+mixed selections.
+
+`setMarks(adapters)` creates one value-bearing command for a closed adapter
+universe. Running it with `{value: marks}` replaces exactly those configured
+marks over the selection: absent values are removed, supplied values are
+canonicalized with `markSet()`, and the resulting set is applied in stable rank
+order within one mapped operation. Marks owned by unlisted adapters remain
+untouched. Every configured adapter needs a clear policy, and one adapter owns
+each type.
+
+Its state is the current canonical mark array, `'mixed'` when selected text has
+different sets, or `null` when no editable text contributes. At a caret it
+returns the structural array but, like the individual range commands, stays
+disabled.
+
+`PendingMarks` can extend those commands at a caret. It stores only an explicit
+override for one surface and replaces the next `insertText`; afterward the DOM
+it created carries the mark and native input resumes. IME input remains native
+throughout composition; the composed range receives the same override only
+after `compositionend`.
+
+## Invariants
+
+- Type identity decides equality and removal. Type names deliberately connect
+  exclusion rules.
+- Set operations never mutate their source and preserve its identity for a
+  no-op.
+- Equivalent non-conflicting inputs produce the same canonical set order.
+- Exclusion is directional policy; conflict reporting is symmetric.
+- Complete sets resolve policy conflicts before mutating the DOM.
+- Canonical DOM order follows canonical set order without crossing meaningful,
+  atomic, or nested-editable boundaries.
+- The algebra contains no editor, document, selection, or module-global mutable
+  state. DOM mutation belongs to the adapter and range commands.
+- Ready-made types and adapters are immutable shared defaults; applications may
+  replace them with their own policy.
+
+## Browser considerations
+
+The algebra uses standard JavaScript data. Adapters and range commands use the
+standard DOM, `Range`, and `Selection` APIs without an engine-specific branch.
+The shared real-browser suite covers boundary splitting, multi-block ranges,
+backward selections, atomic elements, nested editors, reuse, and cleanup.
+
+## TODO
+
+- Add a default link-control module only after URL entry, validation, and UI
+  ownership have an explicit application-facing contract.