u2ui 1.5.2 → 1.5.4

package/js/rte/src/model/html/html-model.js

@@ -0,0 +1,90 @@
+import {ContentModel} from '../content-model.js';
+
+const PHRASING = words(`
+    abbr b bdi bdo cite code data dfn em i kbd mark q ruby s samp small span
+    strong sub sup time u var
+`);
+const FLOW_BLOCKS = words(`
+    address article aside blockquote details dialog div fieldset figure footer
+    form header hgroup main nav search section
+`);
+const RULES = {};
+
+for (const name of PHRASING) RULES[name] = content(['flow', 'phrasing'], ['@phrasing']);
+for (const name of FLOW_BLOCKS) RULES[name] = content(['flow'], ['@flow'], {block: true});
+
+for (const name of words('h1 h2 h3 h4 h5 h6 p pre')) {
+    RULES[name] = content(['flow'], ['@phrasing'], {textBlock: true});
+}
+
+Object.assign(RULES, {
+    a: content(['flow', 'phrasing', 'interactive'], [], {transparent: true, exclude: ['a', '@interactive']}),
+    del: content(['flow', 'phrasing'], [], {transparent: true}),
+    ins: content(['flow', 'phrasing'], [], {transparent: true}),
+    map: content(['flow', 'phrasing'], [], {transparent: true}),
+    button: content(['flow', 'phrasing', 'interactive'], ['@phrasing'], {atomic: true, exclude: ['@interactive']}),
+    label: content(['flow', 'phrasing', 'interactive'], ['@phrasing'], {exclude: ['label']}),
+    textarea: content(['flow', 'phrasing', 'interactive'], [], {atomic: true}),
+    select: content(['flow', 'phrasing', 'interactive'], ['option', 'optgroup', 'hr'], {atomic: true}),
+    option: content([], ['#text']),
+    optgroup: content([], ['option']),
+    body: content([], ['@flow'], {block: true}),
+    form: content(['flow'], ['@flow'], {block: true, exclude: ['form']}),
+    details: content(['flow'], ['summary', '@flow'], {block: true}),
+    fieldset: content(['flow'], ['legend', '@flow'], {block: true}),
+    figure: content(['flow'], ['figcaption', '@flow'], {block: true}),
+    summary: content([], ['@phrasing'], {block: true}),
+    legend: content([], ['@phrasing'], {block: true}),
+    figcaption: content([], ['@phrasing'], {block: true}),
+    ul: content(['flow'], ['li'], {block: true, defaultChild: 'li'}),
+    ol: content(['flow'], ['li'], {block: true, defaultChild: 'li'}),
+    menu: content(['flow'], ['li'], {block: true, defaultChild: 'li'}),
+    li: content([], ['@flow'], {block: true, mergeable: true}),
+    dl: content(['flow'], ['dt', 'dd', 'div'], {block: true}),
+    dt: content([], ['@flow'], {block: true}),
+    dd: content([], ['@flow'], {block: true}),
+    table: content(['flow'], ['caption', 'colgroup', 'thead', 'tbody', 'tfoot', 'tr'], {block: true, defaultChild: 'tbody'}),
+    caption: content([], ['@flow'], {block: true}),
+    colgroup: content([], ['col']),
+    thead: content([], ['tr'], {block: true, defaultChild: 'tr'}),
+    tbody: content([], ['tr'], {block: true, defaultChild: 'tr'}),
+    tfoot: content([], ['tr'], {block: true, defaultChild: 'tr'}),
+    tr: content([], ['th', 'td'], {block: true, defaultChild: 'td'}),
+    th: content([], ['@flow'], {block: true}),
+    td: content([], ['@flow'], {block: true}),
+    picture: content(['flow', 'phrasing'], ['source', 'img']),
+    audio: content(['flow', 'phrasing', 'interactive'], ['source', 'track', '@flow'], {atomic: true}),
+    video: content(['flow', 'phrasing', 'interactive'], ['source', 'track', '@flow'], {atomic: true}),
+    object: content(['flow', 'phrasing', 'interactive'], ['@flow'], {atomic: true}),
+    iframe: content(['flow', 'phrasing', 'interactive'], [], {atomic: true}),
+    canvas: content(['flow', 'phrasing'], ['@phrasing'], {atomic: true}),
+    br: content(['flow', 'phrasing'], [], {atomic: true, void: true}),
+    wbr: content(['flow', 'phrasing'], [], {atomic: true, void: true}),
+    img: content(['flow', 'phrasing'], [], {atomic: true, void: true}),
+    input: content(['flow', 'phrasing', 'interactive'], [], {atomic: true, void: true}),
+    hr: content(['flow'], [], {block: true, atomic: true, void: true}),
+    source: content([], [], {atomic: true, void: true}),
+    track: content([], [], {atomic: true, void: true}),
+    col: content([], [], {atomic: true, void: true}),
+    script: content([], [], {atomic: true}),
+    style: content([], [], {atomic: true}),
+    template: content([], [], {atomic: true}),
+});
+
+export const htmlModel = new ContentModel({
+    rules: RULES,
+    fallback: {groups: ['flow', 'phrasing'], transparent: true},
+    text: {groups: ['flow', 'phrasing']},
+});
+
+export function createHtmlModel(overrides) {
+    return overrides ? htmlModel.extend(overrides) : htmlModel;
+}
+
+function content(groups, children, options = {}) {
+    return {groups, children, ...options};
+}
+
+function words(value) {
+    return value.trim().split(/\s+/);
+}

package/js/rte/src/normalize/execute/README.md

@@ -0,0 +1,33 @@
+# Repair execution
+
+A repair action describes one concrete structural change, such as wrapping
+loose text in a paragraph, unwrapping an invalid element, or moving a child to
+a valid parent. The repair executor performs exactly that change while keeping
+tracked caret and selection positions meaningful.
+
+`repair-executor.js` contains only this mechanical DOM work. `RepairPlanner`
+decides which action is appropriate; `PointMap` keeps positions aligned.
+
+## Contract
+
+- Passive `keep`, `boundary`, and `reject` actions never mutate DOM.
+- `wrap` supports a contiguous node group, allowing the normalizer to create
+  one paragraph around an inline run rather than one paragraph per node.
+- `convert`, `unwrap`, `remove`, and `lift` use mapped operations so registered
+  points retain their logical positions.
+- Unwrapping a block into phrasing content inserts `<br>` only where adjacent
+  visible content would otherwise lose a block boundary.
+- Lifting splits each containing wrapper after the lifted node, preserving the
+  document order of content before and after it. Cloned wrappers retain
+  meaningful attributes except duplicate-prone `id`.
+- An optional transaction receives only connected changed nodes through
+  `touch()`.
+- Unknown actions and invalid roots, child relations, maps, or lift targets fail
+  explicitly before unrelated content is changed.
+
+## TODO
+
+- Preserve element-specific state that `cloneNode(false)` cannot copy.
+- Let content policy provide the line-separator node instead of assuming `<br>`.
+- Record reversible operation descriptions for history.
+- Add namespace-aware replacement and wrapper creation.

package/js/rte/src/normalize/execute/repair-executor.js

@@ -0,0 +1,129 @@
+import {indexOf} from '../../selection/point/point.js';
+import {PointMap} from '../../selection/map/point-map.js';
+
+const PASSIVE = new Set(['keep', 'boundary', 'reject']);
+
+export class RepairExecutor {
+    #root;
+    #map;
+    #transaction;
+
+    constructor(root, {map = new PointMap(), transaction = null} = {}) {
+        if (root?.nodeType !== Node.ELEMENT_NODE) throw new TypeError('A repair executor requires an element root');
+        if (!map?.wrap || !map?.get) throw new TypeError('A repair executor requires a point map');
+        if (transaction !== null && typeof transaction?.touch !== 'function') {
+            throw new TypeError('A repair transaction must support touch()');
+        }
+        this.#root = root;
+        this.#map = map;
+        this.#transaction = transaction;
+    }
+
+    get root() { return this.#root; }
+    get map() { return this.#map; }
+    get transaction() { return this.#transaction; }
+
+    apply(plan, parent, child) {
+        if (!plan?.type) throw new TypeError('A repair plan requires a type');
+        if (child?.parentNode !== parent || parent !== this.#root && !this.#root.contains(parent)) {
+            throw new RangeError('Repair execution requires a direct child inside the root');
+        }
+        if (PASSIVE.has(plan.type)) return false;
+        if (plan.type === 'wrap') {
+            this.wrap([child], plan.tag);
+        } else if (plan.type === 'convert') {
+            const replacement = this.#element(plan.tag);
+            this.#map.replaceWrapper(child, replacement);
+            this.#touch(parent, replacement);
+        } else if (plan.type === 'unwrap') {
+            this.#unwrap(child, !!plan.breaks);
+        } else if (plan.type === 'lift') {
+            this.#lift(child, plan.target);
+        } else if (plan.type === 'remove') {
+            this.#map.remove(child);
+            this.#touch(parent);
+        } else {
+            throw new TypeError(`Unknown repair action: ${plan.type}`);
+        }
+        return true;
+    }
+
+    wrap(nodes, tag) {
+        nodes = [...nodes];
+        if (!nodes.length) throw new RangeError('A repair wrapper requires content');
+        const parent = nodes[0].parentNode;
+        const wrapper = this.#element(tag);
+        this.#map.wrap(nodes, wrapper);
+        this.#touch(parent, wrapper);
+        return wrapper;
+    }
+
+    #unwrap(wrapper, breaks) {
+        const parent = wrapper.parentNode;
+        if (breaks) {
+            const previous = sibling(wrapper, 'previousSibling');
+            const next = sibling(wrapper, 'nextSibling');
+            const before = previous && !isBreak(previous) && !isBreak(first(wrapper));
+            const after = next && !isBreak(next) && !isBreak(last(wrapper));
+            if (before) this.#map.insert(parent, indexOf(wrapper), this.#element('br'));
+            if (after) this.#map.insert(parent, indexOf(wrapper) + 1, this.#element('br'));
+        }
+        this.#map.unwrap(wrapper);
+        this.#touch(parent);
+    }
+
+    #lift(node, target) {
+        if ((target !== this.#root && !this.#root.contains(target)) || !target?.contains(node)) {
+            throw new RangeError('Lift target must be an ancestor inside the repair root');
+        }
+        while (node.parentNode !== target) {
+            const parent = node.parentNode;
+            const grand = parent.parentNode;
+            const offset = indexOf(parent) + 1;
+            let after = null;
+            if (node.nextSibling) {
+                after = parent.cloneNode(false);
+                after.removeAttribute?.('id');
+                this.#map.insert(grand, offset, after);
+                while (node.nextSibling) this.#map.move(node.nextSibling, after, after.childNodes.length);
+            }
+            this.#map.move(node, grand, offset);
+            this.#touch(parent, grand, after);
+        }
+    }
+
+    #element(tag) {
+        if (typeof tag !== 'string' || !tag) throw new TypeError('A repair element requires a tag name');
+        return this.#root.ownerDocument.createElement(tag);
+    }
+
+    #touch(...nodes) {
+        if (!this.#transaction) return;
+        for (const node of nodes) if (node && (node === this.#root || this.#root.contains(node))) this.#transaction.touch(node);
+    }
+}
+
+function first(node) {
+    while (node?.firstChild) node = node.firstChild;
+    return node;
+}
+
+function last(node) {
+    while (node?.lastChild) node = node.lastChild;
+    return node;
+}
+
+function visible(node) {
+    return !!node && node.nodeType !== Node.COMMENT_NODE
+        && (node.nodeType !== Node.TEXT_NODE || !!node.data.trim());
+}
+
+function sibling(node, direction) {
+    do node = node[direction]; while (node && !visible(node));
+    return node;
+}
+
+function isBreak(node) {
+    return node?.nodeType === Node.ELEMENT_NODE && node.localName === 'br';
+}
+

package/js/rte/src/normalize/normalizer/README.md

@@ -0,0 +1,48 @@
+# Scoped normalization
+
+Normalization brings editable DOM into the valid, predictable shape required by
+the content model. For example, it can turn loose text in a block editor into a
+paragraph or place stray list content inside an `li`.
+
+`normalizer.js` asks the planner what is wrong and the executor to fix it. It
+works only in the requested part of one editor, preserves tracked positions,
+and repeats until that part needs no further repair.
+
+## Contract
+
+- `normalize()` accepts an element scope, logical points, and an optional
+  transaction. The default scope is the complete root.
+- `step()` executes at most the next single operation through the identical
+  traversal, grouping, mapping, and scope logic used by `normalize()`.
+- Descendant atomic elements and explicit nested editing boundaries are never
+  traversed. A nested editing host cannot itself be selected as a foreign scope.
+- Adjacent text and inline nodes with the same wrapper plan become one block.
+- Every executed action is returned in order. Unresolved `reject` plans are
+  reported separately and never hidden or treated as success.
+- `stable` states whether the requested scope has reached a fixed point; a
+  successful `step()` remains deliberately unstable until checked again.
+- The returned `PointMap` maps all supplied points after normalization; callers
+  decide whether and how to restore a browser selection.
+- Normalization repeats to a fixed point, making a second run a no-op. A hard
+  operation limit exposes non-converging custom policies instead of looping.
+- An optional transaction receives executor dirty nodes. The normalizer does
+  not create an implicit transaction because fragments and playgrounds also use
+  it independently.
+
+## Cost
+
+An unchanged document is the common case and must be close to free. Two guards
+used to make it linear in tree depth per node instead: the executor re-validated
+the parent against the root for every child, including the ones needing nothing,
+and the pass loop did the same for every element the walk had just collected.
+Both are now paid only where they can matter — a passive plan never reaches the
+executor, and a collected parent is re-checked only after a repair in that same
+pass could have detached it.
+
+## TODO
+
+- Reduce executor touches into minimal stable ancestor scopes.
+- Expand a local scope only when lift or split crosses its current boundary.
+- Add canonical sibling merging and empty metadata cleanup.
+- Restore mapped `EditRange` snapshots through a Surface integration module.
+- Add generated convergence and idempotence cases for custom policies.

package/js/rte/src/normalize/normalizer/normalizer.js

@@ -0,0 +1,141 @@
+import {RepairExecutor} from '../execute/repair-executor.js';
+import {RepairPlanner} from '../repair/repair-planner.js';
+import {PointMap} from '../../selection/map/point-map.js';
+import {isEditingBoundary} from '../../selection/ownership/ownership.js';
+
+const PASSIVE = new Set(['keep', 'boundary', 'reject']);
+
+export class Normalizer {
+    #root;
+    #planner;
+    #limit;
+
+    constructor(root, options = {}) {
+        const {planner = null, limit = 10000, ...policy} = options;
+        if (root?.nodeType !== Node.ELEMENT_NODE) throw new TypeError('A normalizer requires an element root');
+        if (planner !== null && (typeof planner?.plan !== 'function' || planner.root !== root)) {
+            throw new TypeError('A custom repair planner must belong to the normalizer root');
+        }
+        if (!Number.isInteger(limit) || limit < 1) throw new RangeError('Normalization limit must be a positive integer');
+        this.#root = root;
+        this.#planner = planner || new RepairPlanner(root, policy);
+        this.#limit = limit;
+    }
+
+    get root() { return this.#root; }
+    get planner() { return this.#planner; }
+    get limit() { return this.#limit; }
+
+    normalize(options) {
+        return this.#run(options, false);
+    }
+
+    step(options) {
+        return this.#run(options, true);
+    }
+
+    #run({scope = this.#root, points = [], transaction = null} = {}, single) {
+        if (scope?.nodeType !== Node.ELEMENT_NODE || scope !== this.#root && !this.#root.contains(scope)) {
+            throw new RangeError('Normalization scope must be an element inside the root');
+        }
+        if (scope !== this.#root && isEditingBoundary(scope)) {
+            throw new RangeError('Normalization scope cannot cross into a nested editing boundary');
+        }
+        const map = new PointMap(points);
+        const executor = new RepairExecutor(this.#root, {map, transaction});
+        const actions = [];
+        const issues = new Map();
+        let passes = 0;
+        let stable = false;
+        outer: while (true) {
+            let changed = false;
+            passes++;
+            // The walk just collected these, so only a repair in this same pass
+            // can have detached one. Until that happens the check is a tree walk
+            // per element for nothing.
+            const collected = actions.length;
+            for (const parent of parents(scope, this.#planner.model)) {
+                if (actions.length !== collected && parent !== this.#root && !this.#root.contains(parent)) continue;
+                const result = this.#normalizeParent(parent, executor, actions, issues, single);
+                if (result.changed) changed = true;
+                if (result.stopped) break outer;
+            }
+            if (!changed) {
+                stable = true;
+                break;
+            }
+        }
+        const unresolved = [...issues.values()].filter(issue => this.#root.contains(issue.node));
+        return Object.freeze({
+            changed: actions.length > 0,
+            stable,
+            passes,
+            actions: Object.freeze(actions),
+            issues: Object.freeze(unresolved),
+            map,
+        });
+    }
+
+    #normalizeParent(parent, executor, actions, issues, single) {
+        let changed = false;
+        for (let child = parent.firstChild; child;) {
+            const plan = this.#planner.plan(parent, child);
+            if (plan.type === 'reject') issues.set(child, Object.freeze({node: child, parent, plan}));
+            else if (issues.size) issues.delete(child);
+            // Most children need nothing. Asking the executor to confirm that
+            // would re-validate the parent against the root for every one of
+            // them, which is a tree walk per node in an unchanged document.
+            if (PASSIVE.has(plan.type)) {
+                child = child.nextSibling;
+                continue;
+            }
+            if (plan.type === 'wrap') {
+                const nodes = [child];
+                let next = child.nextSibling;
+                while (next && !this.#planner.model.block(child)) {
+                    const nextPlan = this.#planner.plan(parent, next);
+                    if (nextPlan.type !== 'wrap' || nextPlan.tag !== plan.tag || this.#planner.model.block(next)) break;
+                    nodes.push(next);
+                    next = next.nextSibling;
+                }
+                this.#assertLimit(actions);
+                const wrapper = executor.wrap(nodes, plan.tag);
+                actions.push(record(plan, parent, wrapper, {count: nodes.length}));
+                changed = true;
+                if (single) return {changed, stopped: true};
+                child = next;
+            } else {
+                const next = child.nextSibling;
+                this.#assertLimit(actions);
+                if (executor.apply(plan, parent, child)) {
+                    actions.push(record(plan, parent, child));
+                    changed = true;
+                    if (single) return {changed, stopped: true};
+                    child = next?.parentNode === parent ? next : null;
+                } else {
+                    child = next;
+                }
+            }
+        }
+        return {changed, stopped: false};
+    }
+
+    #assertLimit(actions) {
+        if (actions.length >= this.#limit) throw new RangeError('Normalization did not converge within its operation limit');
+    }
+}
+
+function parents(scope, model) {
+    const result = [];
+    const visit = element => {
+        if (element !== scope && (isEditingBoundary(element) || model.atomic(element))) return;
+        for (const child of element.children) visit(child);
+        result.push(element);
+    };
+    visit(scope);
+    return result;
+}
+
+function record(plan, parent, node, detail = {}) {
+    return Object.freeze({type: plan.type, parent, node, ...detail, ...plan});
+}

package/js/rte/src/normalize/repair/README.md

@@ -0,0 +1,70 @@
+# Repair planning
+
+The repair planner looks at one parent and one direct child and describes how an
+invalid relationship should be fixed. Text directly in a `ul`, for example,
+may need an `li` wrapper. A valid paragraph inside a `div` needs no action.
+
+`repair-planner.js` only makes this decision. It returns an immutable action
+without changing nodes, selections, or transaction state.
+
+## Actions
+
+- `keep`: the relationship is valid or cleanup is disabled.
+- `boundary`: the child is an explicit nested editable and must not be crossed.
+- `wrap`: place the child in the returned structural tag.
+- `convert`: replace a neutral generic block with the configured default block.
+- `unwrap`: remove a neutral wrapper while preserving its children;
+  `breaks` records whether adjacent phrasing content needs explicit line breaks.
+- `lift`: move the child to the nearest permitted ancestor inside the root.
+- `remove`: discard only ignorable whitespace/comments or an empty neutral,
+  non-atomic invalid wrapper.
+- `reject`: no lossless default repair is known; execution must leave the node
+  untouched or delegate to an application policy.
+
+## Contract
+
+- `none` never plans changes. `minimal` repairs invalid relationships only.
+  `structural` and `canonical` additionally shape direct root content.
+- A neutral generic block — one carrying no attributes — is redundant at any
+  depth, not only at the root. It becomes the block its context expects, or
+  dissolves into its parent. This is deliberately not a model decision: nested
+  `div`s are perfectly valid HTML, which is exactly why validity alone never
+  removes them, and why legacy documents arrive full of them. An attribute makes
+  a wrapper deliberate and it stays.
+- Loose inline content standing beside blocks in a generic container gets the
+  default block, for the same reason: the root already did this, and depth was
+  never the argument. Containers that carry their own meaning — list items,
+  cells, quotes — keep loose text as it is.
+- `canonical` goes one step beyond valid and also dissolves a generic *inline*
+  wrapper that carries nothing — a bare `<span>` — and removes an inline element
+  with neither attributes nor content, whatever its name. A semantic element
+  with content is never noise, however bare it is.
+- The configured root block wraps direct phrasing content, converts neutral
+  generic blocks containing phrasing content, and removes neutral generic
+  wrappers around root blocks mixed with content that can be shaped at the
+  root. A nested `<div>` followed by text can therefore become two sibling
+  paragraphs through repeated small repairs.
+- Root shaping requires a root block the root itself permits, and a generic
+  block that already is the root block is never converted into itself. Both
+  keep root repairs convergent instead of undoing each other.
+- Parent rules may provide `defaultChild` for structures such as lists, table
+  sections, and rows.
+- Attributes make a wrapper meaningful. Such an element is lifted when a safe
+  ancestor exists and is never silently unwrapped or converted.
+- Explicit nested `contenteditable` elements and atomic elements are never
+  removed by generic empty-node logic.
+- Cached detached elements make repeated category checks allocation-free after
+  the first use; they are inspection prototypes, never inserted into the DOM.
+
+The separate `RepairExecutor` applies these actions through `PointMap`. The
+scoped `Normalizer` groups compatible plans, repeats them to a fixed point,
+preserves registered points, and reports dirty scopes to an optional
+transaction.
+
+## TODO
+
+- Add policy hooks for application-specific generic and meaningful wrappers.
+- Make line-boundary planning configurable for non-HTML output policies.
+- Distinguish whitespace that is author content from formatting whitespace.
+- Add sibling-sequence repairs once the content model exposes ordered rules.
+- Define safe fallback policies for `reject` without hiding content loss.