u2ui 1.5.3 → 1.5.7

package/js/rte/src/history/history.js

@@ -0,0 +1,283 @@
+import {SelectionSnapshot} from '../selection/snapshot.js';
+import {contentChildren, replaceContent} from '../surface/content.js';
+
+// Snapshot history for one surface. RTE leaves ordinary typing and deletion to
+// the browser, so history cannot be an operation log: it observes every mutation
+// regardless of its origin and stores the resulting content as a cloned fragment
+// with a path-addressed selection that survives content replacement.
+//
+// Transactions provide the grouping boundaries. Ordinary input coalesces into
+// one entry per interval; commands, paste, and drop each become one entry.
+export class History {
+    #surface;
+    #entries = [];
+    #index = -1;
+    #limit;
+    #coalesce;
+    #observer;
+    #timer = null;
+    #dirty = false;
+    #applying = false;
+    #controller;
+    #commands;
+
+    constructor(surface, {limit = 100, coalesce = 400} = {}) {
+        if (surface?.element?.nodeType !== Node.ELEMENT_NODE || typeof surface?.transact !== 'function') {
+            throw new TypeError('History requires an editor surface');
+        }
+        if (!Number.isInteger(limit) || limit < 2) throw new RangeError('History limit must be an integer of at least 2');
+        if (!Number.isFinite(coalesce) || coalesce < 0) {
+            throw new RangeError('History coalescing must be a non-negative interval');
+        }
+        this.#surface = surface;
+        this.#limit = limit;
+        this.#coalesce = coalesce;
+        this.#commands = Object.freeze({
+            undo: step('historyUndo', 'ctrl+z', () => this.canUndo, () => this.undo()),
+            redo: step('historyRedo', 'ctrl+y ctrl+shift+z', () => this.canRedo, () => this.redo()),
+        });
+        const root = surface.element;
+        const view = root.ownerDocument.defaultView;
+        this.#observer = new view.MutationObserver(this.#mutate);
+        this.#observer.observe(root, {subtree: true, childList: true, attributes: true, characterData: true});
+        this.#controller = new view.AbortController();
+        const listen = {signal: this.#controller.signal};
+        surface.addEventListener('u2-rte-beforechange', this.#boundary, listen);
+        surface.addEventListener('u2-rte-change', this.#boundary, listen);
+        surface.addEventListener('u2-rte-selectionchange', this.#selectionChange, listen);
+        surface.addEventListener('u2-rte-deactivate', this.#deactivate, listen);
+        surface.addEventListener('u2-rte-disconnect', this.#disconnect, listen);
+        this.#push(this.#capture());
+    }
+
+    get surface() { return this.#surface; }
+    get commands() { return this.#commands; }
+    get length() { return this.#entries.length; }
+    get index() { return this.#index; }
+    get connected() { return !this.#controller.signal.aborted; }
+    get canUndo() { return this.#index > 0 || this.#pull(); }
+    get canRedo() { return this.#index < this.#entries.length - 1 && !this.#pull(); }
+
+    undo() {
+        return this.#go(-1);
+    }
+
+    redo() {
+        return this.#go(1);
+    }
+
+    // Commits the current content as one entry. Unchanged content adds nothing,
+    // so callers may flush at any boundary without producing duplicates.
+    record() {
+        if (this.#applying || !this.#surface.connected) return false;
+        const dirty = this.#pull();
+        this.#cancel();
+        if (!dirty) return false;
+        this.#dirty = false;
+        this.#push(this.#capture());
+        return true;
+    }
+
+    clear() {
+        this.#cancel();
+        this.#observer.takeRecords();
+        this.#dirty = false;
+        this.#entries = [];
+        this.#index = -1;
+        this.#push(this.#capture());
+        return this;
+    }
+
+    dispose() {
+        if (!this.connected) return;
+        this.#cancel();
+        this.#observer.disconnect();
+        this.#controller.abort();
+        this.#entries = [];
+        this.#index = -1;
+    }
+
+    [Symbol.dispose]() {
+        this.dispose();
+    }
+
+    #go(step) {
+        if (!this.#surface.connected) return false;
+        // Uncommitted input becomes its own entry first, so undo leaves the
+        // state the user actually sees instead of skipping past it.
+        this.record();
+        const next = this.#index + step;
+        const entry = this.#entries[next];
+        if (!entry) return false;
+        this.#apply(entry);
+        this.#index = next;
+        this.#emit();
+        return true;
+    }
+
+    #capture() {
+        const element = this.#surface.element;
+        const fragment = element.ownerDocument.createDocumentFragment();
+        for (const node of contentChildren(this.#surface)) fragment.append(node.cloneNode(true));
+        return {fragment, selection: this.#selection()};
+    }
+
+    #apply(entry) {
+        this.#applying = true;
+        try {
+            const clone = entry.fragment.cloneNode(true);
+            replaceContent(this.#surface, ...clone.childNodes);
+            this.#restore(entry.selection);
+        } finally {
+            // Restoring is not an edit: its own records never enter history.
+            this.#observer.takeRecords();
+            this.#dirty = false;
+            this.#applying = false;
+        }
+        this.#surface.capture();
+    }
+
+    #push(entry) {
+        this.#entries.splice(this.#index + 1);
+        this.#entries.push(entry);
+        if (this.#entries.length > this.#limit) this.#entries.shift();
+        this.#index = this.#entries.length - 1;
+        this.#emit();
+    }
+
+    #selection() {
+        const root = this.#surface.element;
+        const snapshot = SelectionSnapshot.capture(this.#surface.core.selection, root) || this.#surface.selection;
+        if (!snapshot?.valid()) return null;
+        const range = snapshot.range();
+        const start = address(this.#surface, root, range.startContainer, range.startOffset);
+        if (!start) return null;
+        const end = range.collapsed ? start : address(this.#surface, root, range.endContainer, range.endOffset);
+        return end ? {start, end, backward: snapshot.backward} : null;
+    }
+
+    #restore(saved) {
+        const root = this.#surface.element;
+        const start = saved && locate(this.#surface, root, saved.start);
+        const end = saved && locate(this.#surface, root, saved.end);
+        if (!start || !end) return false;
+        const range = root.ownerDocument.createRange();
+        range.setStart(start.node, start.offset);
+        range.setEnd(end.node, end.offset);
+        return new SelectionSnapshot(root, range, saved.backward).restore(this.#surface.core.selection);
+    }
+
+    #pull() {
+        if (this.#edited(this.#observer.takeRecords())) this.#mark();
+        return this.#dirty;
+    }
+
+    // The host element belongs to the application, not to the edited content:
+    // an entry restores children only, so its own attributes must not record.
+    #edited(records) {
+        const root = this.#surface.element;
+        const core = this.#surface.core;
+        return records.some(record => {
+            if (core.retains(record.target)) return false;
+            if (record.type === 'attributes') return record.target !== root;
+            if (record.type !== 'childList') return true;
+            const changed = [...record.addedNodes, ...record.removedNodes];
+            return !changed.length || changed.some(node => !core.retains(node));
+        });
+    }
+
+    // Continuous input keeps one open interval instead of restarting it, so a
+    // long paragraph still becomes several undo steps.
+    #mark() {
+        this.#dirty = true;
+        if (this.#timer === null) this.#timer = setTimeout(this.#flush, this.#coalesce);
+    }
+
+    #cancel() {
+        if (this.#timer === null) return;
+        clearTimeout(this.#timer);
+        this.#timer = null;
+    }
+
+    #emit() {
+        this.#surface.emit('u2-rte-history', {history: this});
+    }
+
+    #flush = () => {
+        this.#timer = null;
+        this.record();
+    };
+
+    #mutate = records => {
+        if (!this.#applying && this.#edited(records)) this.#mark();
+    };
+
+    // A transaction that is not ordinary input is its own undo step: the state
+    // before it and the state after it each become one entry.
+    #boundary = event => {
+        if (!this.#applying && !coalesced(event)) this.record();
+    };
+
+    // An entry captured before the surface had a selection adopts the first one
+    // it sees, so undoing back to it restores a caret too.
+    #selectionChange = () => {
+        if (this.#applying || this.#dirty) return;
+        const entry = this.#entries[this.#index];
+        if (entry && !entry.selection) entry.selection = this.#selection();
+    };
+
+    #deactivate = () => {
+        this.record();
+    };
+
+    #disconnect = () => {
+        this.dispose();
+    };
+}
+
+// Like every other command, a history step acts only where the surface owns the
+// selection. An editor the user has left must not change under a shortcut, and
+// a toolbar that still holds a saved selection passes it as the edit range.
+function step(inputType, shortcut, available, run) {
+    return {
+        inputTypes: [inputType],
+        shortcut,
+        transaction: false,
+        enabled: edit => !!edit.range && available(),
+        run,
+    };
+}
+
+function coalesced(event) {
+    return event.detail.transaction?.options.trigger === 'input';
+}
+
+// A selection address survives content replacement because it names positions
+// by child index instead of by node identity.
+function address(surface, root, node, offset) {
+    const path = [];
+    for (let current = node; current !== root; current = current.parentNode) {
+        const parent = current?.parentNode;
+        if (!parent) return null;
+        const index = contentChildren(surface, parent).indexOf(current);
+        if (index < 0) return null;
+        path.unshift(index);
+    }
+    return {path, offset: contentOffset(surface, node, offset)};
+}
+
+function locate(surface, root, {path, offset}) {
+    let node = root;
+    for (const index of path) {
+        node = contentChildren(surface, node)[index];
+        if (!node) return null;
+    }
+    const length = typeof node.length === 'number' ? node.length : contentChildren(surface, node).length;
+    return {node, offset: Math.min(offset, length)};
+}
+
+function contentOffset(surface, node, offset) {
+    if (typeof node.length === 'number') return offset;
+    const before = [...node.childNodes].slice(0, offset);
+    return before.filter(child => !surface.core.retains(child)).length;
+}

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

@@ -0,0 +1,173 @@
+# Input pipeline
+
+The input pipeline turns browser editing events—typing, Enter, paste, drop, and
+composition—into editor work. It decides whether the browser may perform an
+action itself or whether an RTE command replaces it, then repairs the small
+part of the document that changed.
+
+`input-pipeline.js` installs post-native behavior for one `Surface`.
+`external-input.js` is the optional pre-native boundary for rich HTML from
+paste and drop. Both are explicit and reversible: construct them for a surface
+and call `dispose()` during module cleanup. `[Symbol.dispose]()` exposes each
+to `using`. Disconnecting the surface also disposes them automatically.
+
+## Contract
+
+- `beforeinput` captures a live target range before the browser mutates DOM;
+  the matching `input` performs postcondition normalization afterward.
+- With a command registry, a cancelable `beforeinput` whose `inputType` has a
+  registered, available command is prevented and replaced by that command. The
+  registry decides availability; the pipeline only decides that native editing
+  is not used. The command receives the event's `inputType`, text `data`, and
+  target range unchanged. Uncancelable or already prevented events, plain-text
+  hosts, and active composition are never routed. This also prevents two
+  deliberately independent cores from executing the same bubbling event twice.
+- Plain unmodified Backspace and Delete are checked at `keydown` because
+  engines do not reliably expose a usable `beforeinput` at every filler
+  boundary. A key is prevented only when its registered structural command is
+  available; character deletion, selections, modified keys, and other
+  unavailable cases remain native.
+- A registered command shortcut is resolved at `keydown` before anything else,
+  and only replaces the key where that command is available. That is what lets
+  `Tab` reach the list-nesting command inside a list and go on moving focus
+  outside one. Undo and redo arrive this way too: an engine stops reporting
+  `historyUndo` and `historyRedo` once its own undo stack no longer matches
+  content the editor replaced, so their keys cannot come from `beforeinput`.
+- `u2-rte-command` with a transaction triggers the same cleanup as native
+  input, so an editing command executed from a toolbar is normalized like one
+  executed from the keyboard. View-only commands report a null transaction and
+  are ignored because they changed no editable DOM.
+- `insertFromPaste` and `insertFromDrop` are separate `paste` and `drop`
+  triggers. Other input types use `input`; explicit editor commands use
+  `command`.
+- Native paste/drop payloads remain browser-owned. Between their matching
+  `beforeinput` and `input`, the pipeline records only newly added element roots,
+  applies the configured `Unstyle` level to those roots with point mapping, and
+  then structurally normalizes the affected neighborhood. Elements present
+  before the input retain their presentation even when the browser moves them
+  below a newly inserted wrapper. The default level is `styles`; `none` disables
+  presentation cleanup.
+- `--u2-rte-clean-on` decides which triggers run. Cleanup level and semantic
+  default block are resolved from the surface CSS configuration for every run.
+- Scope starts at the affected block. If that block has an invalid relationship
+  to its parent, the parent becomes the scope so the relationship can be
+  repaired without cleaning unrelated sibling subtrees.
+- Native IME mutations are never interrupted. Input during composition is
+  deferred until the final input or the microtask after `compositionend`.
+- Nested editable hosts are ownership boundaries; their events are ignored.
+- Normalization runs in a surface transaction, maps the current forward or
+  backward selection, reports dirty nodes, and emits `u2-rte-normalize`.
+- A collapsed selection maps as one caret point. Two points would drift apart
+  when a repair inserts content exactly at the caret boundary.
+- The pipeline never reads clipboard or drag payloads. `inputRange(event,
+  surface)` is its public, shared conversion from a native `StaticRange` to an
+  owned live `Range`; missing target ranges fall back to the owned selection.
+
+## Keys a host answers itself
+
+A button answers Space and Enter by activating itself, whatever it holds: the
+text inside never sees them and no `beforeinput` arrives at all. In that host,
+and only there, the pipeline turns the key into the input it should have been —
+`insertParagraph` for Enter, and for Space the `insert` command with a space of
+its own — a non-breaking one where a plain space would collapse away, which is
+what the browser itself types there. Everywhere else ordinary typing stays the
+browser's own.
+
+## Pointing at an atomic element
+
+An atomic element is addressable only as the selection: engines disagree about
+whether pointing at one selects it, and a caret an engine leaves inside one —
+clicking a rule does that in some — reaches nothing at all. A click on one
+selects it, which is what makes a frame, a command, or a delete apply to it. The
+host itself is left alone: a surface is not a thing inside itself.
+
+## Rich external input
+
+The native path above needs no HTML parser or sanitizer adapter because RTE
+never reads the payload or reinserts its string. `ExternalInput` is a separate,
+optional pre-native path for applications that deliberately want to process a
+rich HTML string themselves.
+
+`ExternalInput` composes one selected sanitizer, an optional `Unstyle` policy,
+and a registered mapped insertion command:
+
+```js
+const commands = new Commands(surface, {commands: {insertFragment}});
+const external = new ExternalInput(surface, {
+    commands,
+    sanitizer: new NativeSanitizer(),
+    unstyle: defaultUnstyle,
+    through: 'styles',
+});
+```
+
+For `insertFromPaste` and `insertFromDrop`, the contenteditable Input Events
+contract supplies rich and plain data in `dataTransfer` plus the DOM range that
+would be replaced. The adapter takes over only when `text/html` is present. It
+prevents native insertion first, sanitizes into a detached `DocumentFragment`,
+optionally cleans presentation cumulatively through the selected level, and
+passes the result and exact target range to the registered command. Drop thus
+does not accidentally use a selection left elsewhere.
+
+`through` may be a level name, `null`, `none`, or a function receiving
+`{surface, inputType}`. This leaves serializable per-surface policy resolvers to
+the client layer without coupling security code to CSS. An empty sanitized
+fragment changes nothing and does not delete an existing selection.
+
+Plain text, quotation paste, uncancelable or already handled events, active
+composition, plain-text hosts, and nested editing hosts stay native. Quotation
+and plain-text line structure need their own contextual transformer rather than
+being guessed by this HTML adapter.
+
+`insert(html, {range, inputType})` exposes the same synchronous composition to
+an HTML source dialog or another trusted event adapter. It still always calls
+the configured sanitizer. A direct failure is thrown. A native event failure
+remains fail-closed—the browser insertion stays prevented—and emits
+`u2-rte-error` with `transaction: null` and `phase: 'external-input'`.
+
+## What an import goes through
+
+A native paste or drop is cleaned in three stages, in this order:
+
+1. **What may exist**: the sanitize policy narrows the arrived nodes to the
+   allowed attributes and protocols, and then to the importable elements.
+   Attributes go first — removing one moves nothing, while narrowing dissolves
+   wrappers and would leave nothing left to clean. What the content model
+   already rejects is skipped and left to stage 3, which knows that dissolving
+   a block into inline content needs a line break to survive.
+   `--u2-rte-import-sanitize: none` opts a host out of the whole stage.
+   An element the list does not carry but whose meaning a listed one does is
+   replaced rather than dropped: `importAliases` maps `b` to `strong`, `i` to
+   `em`, and `strike` to `s`, so a strict list costs no emphasis.
+2. **What it should look like**: `Unstyle` removes presentation up to
+   `--u2-rte-import-unstyle`, sparing the host's declared content classes.
+3. **How it is built**: the normalizer repairs structure.
+
+The order matters. An id removed in the first stage is exactly what lets the
+third dissolve the layout wrapper that carried it.
+
+Where to repair is decided before any of it runs: narrowing dissolves the very
+nodes that say where the import landed.
+
+## What cleanup covers
+
+The caret is not where pasted or dropped content is — it sits at the end of it.
+Deriving the cleanup scope from the caret therefore repaired only its last block
+and left the rest of a pasted document untouched, however broken. The pipeline
+already tracks the nodes that arrived, so the scope is the smallest element
+covering both them and the caret. That tracking is now set up for every cleaned
+paste or drop rather than only when presentation cleanup is configured:
+structural repair needs to know where content landed just as much.
+
+## TODO
+
+- Keep a native input transaction open from cancellable `beforeinput` through
+  the resulting `input` for exact history snapshots.
+- Derive multi-block neighborhoods from all `getTargetRanges()` entries.
+- Route selected-range deletion once its command can preserve structural
+  boundaries and selection direction.
+- Add contextual plain-text and quotation import without folding their line and
+  block semantics into HTML sanitizing.
+- Verify trusted clipboard and drag interactions in all target engines in
+  addition to the deterministic event-contract suite.
+- Group composition and consecutive typing transactions for history.

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

@@ -0,0 +1,130 @@
+import {inputRange} from './input-pipeline.js';
+import {editingHost, isPlainTextHost} from '../selection/ownership/ownership.js';
+
+const INPUTS = new Set(['insertFromPaste', 'insertFromDrop']);
+
+// Owns rich external HTML before the browser can insert it. The selected
+// sanitizer, optional presentation cleanup, and mapped insertion command stay
+// replaceable; this class only composes them for native input events.
+export class ExternalInput {
+    #surface;
+    #root;
+    #commands;
+    #sanitizer;
+    #unstyle;
+    #through;
+    #command;
+    #controller;
+    #connected = true;
+
+    constructor(surface, {
+        commands,
+        sanitizer,
+        unstyle = null,
+        through = null,
+        command = 'insertFragment',
+    } = {}) {
+        const root = surface?.element;
+        if (root?.nodeType !== Node.ELEMENT_NODE || typeof surface?.emit !== 'function') {
+            throw new TypeError('External input requires an editor surface');
+        }
+        if (typeof commands?.has !== 'function' || typeof commands?.run !== 'function') {
+            throw new TypeError('External input requires a command registry');
+        }
+        if (typeof command !== 'string' || !command.trim() || !commands.has(command)) {
+            throw new RangeError('External input requires a registered insertion command');
+        }
+        if (typeof sanitizer?.sanitize !== 'function') {
+            throw new TypeError('External input requires a sanitizer');
+        }
+        if (unstyle !== null && typeof unstyle?.clean !== 'function') {
+            throw new TypeError('External input cleanup requires an Unstyle policy');
+        }
+        if (through !== null && typeof through !== 'string' && typeof through !== 'function') {
+            throw new TypeError('External input cleanup level must be a string, function, or null');
+        }
+        if (through !== null && !unstyle) {
+            throw new TypeError('External input cleanup level requires an Unstyle policy');
+        }
+        this.#surface = surface;
+        this.#root = root;
+        this.#commands = commands;
+        this.#sanitizer = sanitizer;
+        this.#unstyle = unstyle;
+        this.#through = through;
+        this.#command = command.trim();
+        this.#controller = new root.ownerDocument.defaultView.AbortController();
+        const listen = {signal: this.#controller.signal};
+        root.addEventListener('beforeinput', this.#beforeInput, listen);
+        surface.addEventListener('u2-rte-disconnect', this.#disconnect, listen);
+    }
+
+    get surface() { return this.#surface; }
+    get connected() { return this.#connected; }
+
+    insert(html, {range = null, inputType = ''} = {}) {
+        if (!this.#connected) throw new DOMException('External input is disconnected', 'InvalidStateError');
+        if (typeof html !== 'string') throw new TypeError('External HTML must be a string');
+        const fragment = this.#sanitizer.sanitize(html, {
+            document: this.#root.ownerDocument,
+            base: this.#root.ownerDocument.baseURI,
+            elements: this.#surface.config.elements,
+            classes: this.#surface.config.classes.length ? this.#surface.config.classes : null,
+        });
+        if (fragment?.nodeType !== Node.DOCUMENT_FRAGMENT_NODE) {
+            throw new TypeError('A sanitizer must return a DocumentFragment');
+        }
+        const through = typeof this.#through === 'function'
+            ? this.#through(Object.freeze({surface: this.#surface, inputType}))
+            : this.#through;
+        if (through !== null && through !== 'none') {
+            this.#unstyle.clean(fragment, {through, keep: this.#surface.config.classes});
+        }
+        if (!fragment.childNodes.length) return [];
+        return this.#commands.run(this.#command, {fragment, range, inputType});
+    }
+
+    dispose() {
+        if (!this.#connected) return;
+        this.#controller.abort();
+        this.#connected = false;
+    }
+
+    [Symbol.dispose]() {
+        this.dispose();
+    }
+
+    #beforeInput = event => {
+        if (!this.#owns(event) || !INPUTS.has(event.inputType) || !event.cancelable
+            || event.defaultPrevented || event.isComposing || isPlainTextHost(this.#root)) return;
+        if (!hasHtml(event.dataTransfer)) return;
+        event.preventDefault();
+        try {
+            const html = event.dataTransfer.getData('text/html');
+            const range = inputRange(event, this.#surface);
+            this.insert(html, {range, inputType: event.inputType});
+        } catch (error) {
+            this.#surface.emit('u2-rte-error', {
+                transaction: null,
+                error,
+                phase: 'external-input',
+                inputType: event.inputType,
+            });
+        }
+    };
+
+    #disconnect = () => {
+        this.dispose();
+    };
+
+    #owns(event) {
+        const target = event.composedPath()[0];
+        return target === this.#root || editingHost(target) === this.#root;
+    }
+}
+
+function hasHtml(transfer) {
+    if (!transfer || typeof transfer.getData !== 'function') return false;
+    const types = [...(transfer.types || [])].map(type => String(type).toLowerCase());
+    return types.includes('text/html');
+}