u2ui 1.5.2 → 1.5.4

package/js/rte/src/ui/handles.js

@@ -0,0 +1,179 @@
+export const handleStyle = `
+.handles > .frame {
+    border: 1px solid Highlight;
+    box-sizing: border-box;
+    display: none;
+    pointer-events: none;
+    position: fixed;
+}
+.handles[framed] > .frame { display: block; }
+.handles > button {
+    align-items: center;
+    background: Canvas;
+    border: 1px solid color-mix(in srgb, CanvasText 45%, transparent);
+    border-radius: 50%;
+    block-size: var(--u2-handle-size, 1.43em);
+    color: CanvasText;
+    display: flex;
+    font-size: .7em;
+    inline-size: var(--u2-handle-size, 1.43em);
+    justify-content: center;
+    padding: 0;
+    pointer-events: auto;
+    position: fixed;
+    /* Trimming the font's leading centres the glyph itself rather than its
+       metric box, which is what makes a bare + or × sit straight. */
+    text-box: trim-both cap alphabetic;
+}
+.handles > button:hover:not(:disabled) { background: color-mix(in srgb, Highlight 20%, Canvas); }
+.handles > button:disabled { opacity: .45; }
+`;
+
+// A set of buttons placed around something, with an optional frame drawn behind
+// them. It owns no editor concept: a caller says where each handle goes and what
+// pressing one means, which is what lets anything with a rectangle use it.
+//
+// Given a shadow root it places itself inside it and registers its stylesheet
+// there. Given a document it makes a shadow root of its own, so it works just as
+// well outside an editor.
+export class Handles {
+    #host;
+    #root;
+    #frame;
+    #buttons = new Map();
+    #action;
+    #owned = null;
+    #connected = true;
+
+    constructor(root, {handles, action = null, press = null, name = 'handles'} = {}) {
+        const isDocument = root?.nodeType === Node.DOCUMENT_NODE;
+        const isShadow = root?.nodeType === Node.DOCUMENT_FRAGMENT_NODE;
+        if (!isDocument && !isShadow) throw new TypeError('Handles require a document or shadow root');
+        if (!Array.isArray(handles) || !handles.length) throw new TypeError('Handles require descriptors');
+        for (const [label, value] of [['action', action], ['press', press]]) {
+            if (value !== null && typeof value !== 'function') throw new TypeError(`A handle ${label} must be a function`);
+        }
+        const document = isDocument ? root : root.ownerDocument;
+        this.#action = action;
+        this.#host = document.createElement('div');
+        this.#host.id = name;
+        this.#host.className = 'handles';
+        this.#host.hidden = true;
+        this.#host.setAttribute('aria-hidden', 'true');
+        this.#frame = document.createElement('div');
+        this.#frame.className = 'frame';
+        this.#host.append(this.#frame);
+        for (const handle of handles) {
+            if (typeof handle?.name !== 'string' || !handle.name.trim()) throw new TypeError('A handle requires a name');
+            const button = document.createElement('button');
+            button.type = 'button';
+            button.dataset.handle = handle.name;
+            button.tabIndex = -1;
+            button.title = handle.label || handle.name;
+            button.setAttribute('aria-label', handle.label || handle.name);
+            button.textContent = handle.text ?? '';
+            if (handle.cursor) button.style.cursor = handle.cursor;
+            this.#buttons.set(handle.name, button);
+            this.#host.append(button);
+        }
+        // Listening on the containing root rather than the host: an event that
+        // is not composed never leaves the shadow tree it happened in.
+        this.#root = isShadow ? root : ownRoot(this.#host, document);
+        this.#root.addEventListener('pointerdown', event => {
+            const button = named(event, this.#host);
+            if (!button || button.disabled) return;
+            // Pointing at editor chrome must never move the selection it acts on.
+            event.preventDefault();
+            press?.(button.dataset.handle, event);
+        });
+        this.#root.addEventListener('click', event => {
+            const button = named(event, this.#host);
+            if (button && !button.disabled) this.#action?.(button.dataset.handle, event);
+        });
+        if (isShadow) {
+            if (!root.getElementById('handles-style')) {
+                const style = document.createElement('style');
+                style.id = 'handles-style';
+                style.textContent = handleStyle;
+                root.append(style);
+            }
+            root.append(this.#host);
+        } else {
+            this.#owned = this.#host.parentNode;
+        }
+    }
+
+    get element() { return this.#host; }
+
+    button(name) {
+        return this.#buttons.get(name) || null;
+    }
+    get names() { return [...this.#buttons.keys()]; }
+    get visible() { return !this.#host.hidden; }
+    get connected() { return this.#connected; }
+
+    show(visible = true) {
+        this.#host.hidden = !visible;
+        return this;
+    }
+
+    // A handle is placed by its centre, in viewport coordinates.
+    place(name, x, y) {
+        const button = this.#buttons.get(name);
+        if (!button) throw new RangeError(`Unknown handle: ${name}`);
+        const size = button.offsetWidth || 20;
+        button.style.left = `${x - size / 2}px`;
+        button.style.top = `${y - size / 2}px`;
+        return this;
+    }
+
+    disable(name, disabled = true) {
+        const button = this.#buttons.get(name);
+        if (!button) throw new RangeError(`Unknown handle: ${name}`);
+        button.disabled = !!disabled;
+        return this;
+    }
+
+    // `null` hides the frame; a rectangle draws it in viewport coordinates.
+    frame(rect) {
+        this.#host.toggleAttribute('framed', !!rect);
+        if (!rect) return this;
+        this.#frame.style.left = `${rect.left}px`;
+        this.#frame.style.top = `${rect.top}px`;
+        this.#frame.style.width = `${rect.width}px`;
+        this.#frame.style.height = `${rect.height}px`;
+        return this;
+    }
+
+    dispose() {
+        if (!this.#connected) return;
+        (this.#owned?.host || this.#host).remove();
+        this.#buttons.clear();
+        this.#connected = false;
+    }
+
+    [Symbol.dispose]() {
+        this.dispose();
+    }
+}
+
+function named(event, host) {
+    const button = event.composedPath()[0]?.closest?.('button[data-handle]');
+    return button && host.contains(button) ? button : null;
+}
+
+// Standalone use: the handles bring their own encapsulated root.
+function ownRoot(host, document) {
+    const outer = document.createElement('div');
+    outer.dataset.u2RteChrome = 'handles';
+    const root = outer.attachShadow({mode: 'open'});
+    const style = document.createElement('style');
+    style.textContent = ':host { all: initial; pointer-events: none; position: fixed; inset: 0; }\n' + handleStyle;
+    root.append(style, host);
+    (document.body || document.documentElement).append(outer);
+    if (typeof outer.showPopover === 'function') {
+        outer.popover = 'manual';
+        outer.showPopover();
+    }
+    return root;
+}

package/js/rte/src/ui/place.js

@@ -0,0 +1,25 @@
+import {rangeRect} from '../browser/range-rect.js';
+
+// One placement policy for every contextual UI: anchor on the surface's saved
+// selection, keep the element inside the viewport, and fall to the other side
+// when the preferred one does not fit.
+//
+// A UI that belongs to one element rather than to the selection passes that
+// element's rect as `on`: what it points at should not shift with the caret.
+export function place(element, surface, {align = 'center', prefer = 'above', gap = 28, on = null} = {}) {
+    const range = on ? null : surface.selection?.range();
+    if (!on && !range) return false;
+    const anchor = on || rangeRect(range, {root: surface.element});
+    const view = element.ownerDocument.defaultView;
+    const box = element.getBoundingClientRect();
+    const start = align === 'center' ? anchor.left + anchor.width / 2 - box.width / 2 : anchor.left;
+    const above = anchor.top - box.height - gap;
+    const below = anchor.bottom + gap;
+    const fits = prefer === 'above' ? above >= gap : below + box.height + gap <= view.innerHeight;
+    const top = prefer === 'above'
+        ? (fits ? above : Math.min(view.innerHeight - box.height - gap, below))
+        : (fits ? below : Math.max(gap, above));
+    element.style.left = `${Math.max(gap, Math.min(view.innerWidth - box.width - gap, start))}px`;
+    element.style.top = `${top}px`;
+    return true;
+}

package/js/rte/src/ui/toolbar.js

@@ -0,0 +1,283 @@
+export class Toolbar {
+    #core;
+    #element;
+    #resolve;
+    #place;
+    #hovered = false;
+    #controller;
+    #surfaceController = null;
+    #surface = null;
+    #commands = null;
+    #dismissed = false;
+    #connected = true;
+
+    constructor(core, element, {commands, place = null} = {}) {
+        if (!core?.root || typeof core?.addEventListener !== 'function') {
+            throw new TypeError('A toolbar requires an editor core');
+        }
+        if (element?.nodeType !== Node.ELEMENT_NODE) throw new TypeError('A toolbar requires an element');
+        if (typeof commands !== 'function') throw new TypeError('A toolbar requires a command resolver');
+        if (place !== null && typeof place !== 'function') throw new TypeError('Toolbar placement must be a function');
+        const document = core.root.nodeType === Node.DOCUMENT_NODE ? core.root : core.root.ownerDocument;
+        if (element.ownerDocument !== document) throw new RangeError('A toolbar must share its core document');
+        this.#core = core;
+        this.#element = element;
+        this.#resolve = commands;
+        this.#place = place;
+        this.#controller = new document.defaultView.AbortController();
+        const listen = {signal: this.#controller.signal};
+        core.addEventListener('u2-rte-activechange', this.#activeChange, listen);
+        core.addEventListener('u2-rte-dispose', this.#coreDispose, listen);
+        element.addEventListener('pointerdown', this.#pointerDown, listen);
+        // A toolbar that moves out from under the pointer is a toolbar you
+        // cannot click. While it is being aimed at, it stays where it is and
+        // catches up when the pointer goes.
+        element.addEventListener('pointerenter', () => { this.#hovered = true; }, listen);
+        element.addEventListener('pointerleave', () => {
+            this.#hovered = false;
+            if (!this.#element.hidden && this.#surface) this.#place?.(this.#element, this.#surface);
+        }, listen);
+        element.addEventListener('click', this.#click, listen);
+        element.addEventListener('change', this.#change, listen);
+        core.root.addEventListener('focusin', this.#focusIn, {...listen, capture: true});
+        core.root.addEventListener('focusout', this.#focusOut, {...listen, capture: true});
+        if (!element.hasAttribute('role')) element.setAttribute('role', 'toolbar');
+        element.hidden = true;
+        // Focus landing in a control is still the editor's: without this the core
+        // would end the session the moment a button took the focus.
+        core.retain(element);
+        try {
+            this.#activate(core.active);
+        } catch (error) {
+            this.dispose();
+            throw error;
+        }
+    }
+
+    get core() { return this.#core; }
+    get element() { return this.#element; }
+    get surface() { return this.#surface; }
+    get commands() { return this.#commands; }
+    get connected() { return this.#connected; }
+
+    refresh() {
+        if (!this.#connected) return false;
+        const surface = this.#surface;
+        const commands = surface?.connected ? this.#resolve(surface) : null;
+        if (commands != null && !registry(commands)) throw new TypeError('Toolbar commands must resolve to a command registry');
+        this.#commands = commands || null;
+        const active = !!commands && !this.#dismissed && surface.config.ui === 'roaming'
+            && visibleForSelection(surface);
+        const names = active ? configured(surface.element) : null;
+        // A host may prefer a toolbar that only ever shows what it can do, at
+        // the cost of a shape that moves with the caret.
+        const hiding = active && unavailable(surface.element) === 'hide';
+        const detail = surface?.selection ? {range: surface.selection.range()} : undefined;
+        let visible = 0;
+        for (const item of this.#items()) {
+            const name = item.dataset.command.trim();
+            const control = item.dataset.control?.trim() || name;
+            const offered = active && commands.has(name) && (!names || names.has(control));
+            const disabled = !offered || !commands.enabled(name, detail);
+            item.hidden = !offered || hiding && disabled;
+            if (item.hidden) {
+                state(item, null, true);
+                continue;
+            }
+            visible++;
+            state(item, item.hasAttribute('data-state') ? commands.state(name, detail) : null, disabled);
+        }
+        for (const select of this.#values()) {
+            const command = select.dataset.commandValue.trim();
+            const control = select.dataset.control?.trim() || command;
+            const show = active && commands.has(command) && (!names || names.has(control));
+            let choices = 0;
+            for (const option of select.options) {
+                if (!option.value) continue;
+                const enabled = show && commands.enabled(command, {...detail, value: option.value});
+                option.hidden = !enabled;
+                option.disabled = !enabled;
+                if (enabled) choices++;
+            }
+            // Presence answers what this editor offers, availability what the
+            // selection allows. A select with no configured choice at all is
+            // absent; one whose choices simply do not apply here stays and is
+            // disabled, so the toolbar keeps its shape as the caret moves.
+            const offered = show && [...select.options].some(option => option.value);
+            const usable = offered && choices > 0;
+            const value = usable ? commands.state(command, detail) : null;
+            select.hidden = !offered || hiding && !usable;
+            select.disabled = !usable;
+            select.setAttribute('aria-disabled', String(!usable));
+            const selected = [...select.options].find(option => option.value === value && !option.disabled);
+            select.value = selected && value !== 'mixed' ? value : '';
+            if (!select.hidden) visible++;
+        }
+        const show = active && !!visible;
+        // Appearing is not moving: a toolbar that becomes visible must not slide
+        // in from wherever it last stood, so the first placement is made with
+        // any transition suppressed.
+        const appearing = show && this.#element.hidden;
+        display(this.#element, show);
+        if (show && !(this.#hovered && !appearing)) {
+            if (appearing) this.#element.dataset.placing = '';
+            this.#place?.(this.#element, surface);
+            if (appearing) {
+                const view = this.#element.ownerDocument.defaultView;
+                view.requestAnimationFrame(() => delete this.#element.dataset.placing);
+            }
+        }
+        return show;
+    }
+
+    dispose() {
+        if (!this.#connected) return;
+        this.#core.release(this.#element);
+        this.#surfaceController?.abort();
+        this.#controller.abort();
+        this.#surfaceController = null;
+        this.#surface = null;
+        this.#commands = null;
+        this.#dismissed = false;
+        display(this.#element, false);
+        this.#connected = false;
+    }
+
+    [Symbol.dispose]() {
+        this.dispose();
+    }
+
+    #activate(surface) {
+        if (surface === this.#surface) {
+            this.refresh();
+            return;
+        }
+        this.#surfaceController?.abort();
+        this.#surface = surface || null;
+        this.#dismissed = false;
+        this.#surfaceController = null;
+        if (surface) {
+            const Controller = this.#element.ownerDocument.defaultView.AbortController;
+            this.#surfaceController = new Controller();
+            const listen = {signal: this.#surfaceController.signal};
+            surface.addEventListener('u2-rte-selectionchange', this.#refresh, listen);
+            surface.addEventListener('u2-rte-change', this.#refresh, listen);
+            surface.addEventListener('u2-rte-history', this.#refresh, listen);
+            surface.addEventListener('u2-rte-disconnect', this.#disconnect, listen);
+        }
+        this.refresh();
+    }
+
+    #items() {
+        return this.#element.querySelectorAll('[data-command]');
+    }
+
+    #values() {
+        return this.#element.querySelectorAll('select[data-command-value]');
+    }
+
+    #item(target) {
+        const item = target?.closest?.('[data-command]');
+        if (!item || !this.#element.contains(item) || item.hidden || item.getAttribute('aria-disabled') === 'true') return null;
+        const name = item.dataset.command.trim();
+        return this.#commands?.has(name) ? item : null;
+    }
+
+    #run(name, detail) {
+        if (!this.#surface.capture()) this.#surface.restore();
+        this.#commands.run(name, detail);
+        this.refresh();
+    }
+
+    #activeChange = event => this.#activate(event.detail.surface);
+    #coreDispose = () => this.dispose();
+    #disconnect = () => this.#activate(null);
+    #refresh = () => this.refresh();
+
+    #focusIn = event => {
+        if (!this.#dismissed || !this.#ownsFocus(event.composedPath()[0])) return;
+        this.#dismissed = false;
+        this.refresh();
+    };
+
+    #focusOut = event => {
+        if (!this.#ownsFocus(event.composedPath()[0]) || this.#ownsFocus(event.relatedTarget)) return;
+        this.#dismissed = true;
+        display(this.#element, false);
+    };
+
+    // The toolbar is chrome: pointing at it must never move the editor's
+    // selection, not even at a control that currently has nothing to run.
+    // Fields keep their own pointer behaviour so they can be opened and typed in.
+    #pointerDown = event => {
+        const target = event.composedPath()[0];
+        if (target?.closest?.('select, input, textarea')) return;
+        event.preventDefault();
+    };
+
+    #click = event => {
+        const item = this.#item(event.target);
+        if (!item) return;
+        event.preventDefault();
+        this.#run(item.dataset.command.trim());
+    };
+
+    #change = event => {
+        const select = event.target?.closest?.('select[data-command-value]');
+        if (!select || !this.#element.contains(select) || select.hidden || select.disabled) return;
+        const name = select.value.trim();
+        const command = select.dataset.commandValue.trim();
+        if (!name || select.selectedOptions[0]?.disabled || !this.#commands?.has(command)) {
+            this.refresh();
+            return;
+        }
+        this.#run(command, {value: name});
+    };
+
+
+    #ownsFocus(node) {
+        if (!node || !this.#surface) return false;
+        // A `focusout` listener outside the toolbar's shadow tree sees its
+        // related target retargeted to that tree's host, so focus moving into a
+        // control of its own would otherwise read as focus leaving.
+        const root = this.#element.getRootNode();
+        if (root.host && node === root.host) return true;
+        return node === this.#element || this.#element.contains(node)
+            || node === this.#surface.element || this.#surface.element.contains(node);
+    }
+}
+
+function registry(value) {
+    return typeof value?.has === 'function'
+        && typeof value?.enabled === 'function'
+        && typeof value?.state === 'function'
+        && typeof value?.run === 'function';
+}
+
+function configured(element) {
+    const value = getComputedStyle(element).getPropertyValue('--u2-rte-toolbar').trim();
+    return value ? new Set(value.split(/[\s,]+/).filter(Boolean)) : null;
+}
+
+function unavailable(element) {
+    return getComputedStyle(element).getPropertyValue('--u2-rte-toolbar-unavailable').trim();
+}
+
+function visibleForSelection(surface) {
+    const value = getComputedStyle(surface.element).getPropertyValue('--u2-rte-toolbar-when').trim();
+    return value !== 'selection' || !!surface.selection && !surface.selection.collapsed;
+}
+
+function state(item, value, disabled) {
+    if ('disabled' in item) item.disabled = disabled;
+    item.setAttribute('aria-disabled', String(disabled));
+    if (value === true || value === false || value === 'mixed') item.setAttribute('aria-pressed', String(value));
+    else item.removeAttribute('aria-pressed');
+}
+
+function display(element, visible) {
+    const popover = element.hasAttribute('popover') && typeof element.showPopover === 'function';
+    if (!visible && popover && element.matches(':popover-open')) element.hidePopover();
+    element.hidden = !visible;
+    if (visible && popover && !element.matches(':popover-open')) element.showPopover();
+}

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

@@ -0,0 +1,103 @@
+# Unstyle policy
+
+`unstyle.js` describes presentation cleanup independently of where the HTML
+came from. The same immutable policy can power the selected-content command,
+clean a detached fragment after security sanitizing, or clean only the element
+roots added by native paste/drop.
+
+## Contract
+
+An `Unstyle` policy contains ordered named levels. A level lists exact
+attributes to remove and/or inline elements to unwrap:
+
+```js
+const policy = new Unstyle([
+    {name: 'classes', attributes: ['class']},
+    {name: 'styles', attributes: ['style']},
+    {name: 'formatting', elements: ['b', 'strong', 'span']},
+]);
+```
+
+The default levels are `classes`, `styles`, legacy presentation `attributes`,
+and `formatting`. Removing the last attribute from a `span` also unwraps that
+neutral wrapper. Links, code, revision elements, lists, and tables are not
+dismantled by the default formatting level.
+
+`clean(root, {through, map, transaction, preserve})` applies every level up to and
+including `through` to a DOM `Element` or `DocumentFragment`. `map` and
+`transaction` are optional for detached fragments and preserve points plus
+dirty ownership when cleanup runs on live editor content. `preserve` may be a
+set of elements whose own presentation must remain unchanged even when a new
+ancestor is cleaned. Their newly added descendants remain eligible. The
+strength is mandatory: external input must not become more destructive merely
+because an earlier level found nothing.
+
+```js
+const fragment = sanitizer.sanitize(externalHtml);
+defaultUnstyle.clean(fragment, {through: 'styles'});
+// Insert the detached fragment through an editor transaction afterwards.
+```
+
+`InputPipeline` uses the mapped live form only on element roots observed during
+one native paste/drop. `ExternalInput` uses the detached form after explicitly
+sanitizing rich data. Its `through` option may resolve a different named level
+per surface or input type.
+
+This order is deliberate:
+
+1. the browser inserts natively, or a security sanitizer safely parses external HTML;
+2. Unstyle removes unwanted presentation according to application policy;
+3. structural normalization repairs the fragment in its editing context.
+
+Unstyle is not a sanitizer and must never parse untrusted strings or precede
+the security boundary.
+
+## Invariants
+
+- Policies and their levels are immutable and application-replaceable.
+- Levels are cumulative for foreign fragments but individually addressable by
+  the selection command.
+- Cleanup preserves text and child order while unwrapping elements.
+- Security, presentation cleanup, and structural validity remain separate.
+
+## The ladder
+
+The levels are ordered from least to most destructive and do not stop at the
+application's own presentation. Someone who keeps pressing wants more removed,
+so the ladder runs out of rungs only when the selection is plain:
+
+| # | level | removes |
+|---|---|---|
+| 1 | `styles` | the `style` attribute |
+| 2 | `attributes` | `align`, `bgcolor`, `width` and the other presentational attributes |
+| 3 | `classes` | classes the host has **not** declared as content |
+| 4 | `formatting` | `b`, `font`, `i`, `s`, `span`, `strike`, `u` — unwrapped |
+| 5 | `contentClasses` | the declared classes too, and the wrappers carrying them |
+| 6 | `inline` | the remaining semantic inline elements, links included |
+
+Rungs 1–4 are scoped `foreign`: they spare the declared classes. Rung 5 is where
+the application's own presentation goes, so rung 6 no longer needs to protect
+anything.
+
+With nothing selected the whole content is the target, so the ladder is a way to
+clean a document as much as a way to clean a passage.
+
+A seventh rung, `blocks`, reduces structure to the host's default block. It
+needs the content model and mapped mutation and therefore lives in
+[`../command/`](../command/README.md), not here: this policy also runs on
+detached paste fragments, where there is no surface and no structure to reduce.
+
+## Declared content classes
+
+`clean(root, {keep})` names the classes the host treats as content. The class
+level then narrows the attribute to those names instead of removing it, and the
+formatting level leaves a wrapper that carries one, because the class applies to
+that wrapper. `removable()`, `strip()`, and `declared()` are exported so the
+selection command applies the identical rule from `--u2-rte-classes`.
+
+## TODO
+
+- Add separately configured structural levels for converting headings, lists,
+  and tables while preserving visible text and boundaries.
+- Add optional class-token and style-property rules before applications need
+  finer cleanup than whole attributes.