u2ui 1.5.3 → 1.5.4

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

@@ -0,0 +1,35 @@
+# Transactions
+
+A transaction groups one complete editor change, from the selection before it
+starts to the selection and affected nodes after it finishes. For example, an
+Enter command and the structural cleanup it triggers should be observed as one
+change rather than unrelated DOM mutations.
+
+`transaction.js` provides this synchronous boundary for commands, input
+handling, normalization, events, and history.
+
+## Contract
+
+- A transaction runs synchronously and at most once.
+- A live selection inside the surface is captured before change hooks execute;
+  only a selection the surface does not own is replaced by its saved snapshot.
+- `u2-rte-beforechange` is cancelable on both the surface object and DOM host.
+- `touch(node)` records affected nodes and rejects nodes outside the surface.
+- Nested operations share the surface's current transaction.
+- A successful transaction captures its resulting selection and emits
+  `u2-rte-change`; a thrown error emits `u2-rte-error` and is rethrown.
+- `selectionBefore` and `selectionAfter` expose read-only snapshots.
+- Transactions report state but do not pretend to roll back arbitrary DOM
+  mutations. Undo is provided by the state-based history layer, which uses the
+  `trigger` option to decide what belongs to one step.
+
+Synchronous execution is intentional: selection, `beforeinput`, browser undo,
+and DOM mutation order become ambiguous across an asynchronous gap.
+
+## TODO
+
+- Reduce touched nodes into minimal dirty scopes for normalization.
+- Record reversible DOM operations so history can store diffs instead of
+  whole content states.
+- Add transaction metadata compatible with Input Events `inputType` values.
+- Define composition transaction grouping without delaying DOM ownership.

package/js/rte/src/transaction/transaction.js

@@ -0,0 +1,56 @@
+export class Transaction {
+    #surface;
+    #options;
+    #dirty = new Set();
+    #state = 'new';
+    #selectionBefore = null;
+    #selectionAfter = null;
+
+    constructor(surface, options = {}) {
+        this.#surface = surface;
+        this.#options = Object.freeze({...options});
+    }
+
+    get surface() { return this.#surface; }
+    get options() { return this.#options; }
+    get state() { return this.#state; }
+    get dirty() { return [...this.#dirty]; }
+    get selectionBefore() { return this.#selectionBefore; }
+    get selectionAfter() { return this.#selectionAfter; }
+
+    touch(node) {
+        if (node !== this.#surface.element && !this.#surface.element.contains(node)) {
+            throw new RangeError('Dirty nodes must belong to the transaction surface');
+        }
+        this.#dirty.add(node);
+        return this;
+    }
+
+    run(change) {
+        if (this.#state !== 'new') throw new DOMException('A transaction can run only once', 'InvalidStateError');
+        // A live selection inside the surface is newer than the saved one; only
+        // a selection the surface does not own is replaced by its snapshot.
+        if (!this.#surface.capture()) this.#surface.restore();
+        this.#selectionBefore = this.#surface.selection;
+        if (!this.#surface.emit('u2-rte-beforechange', {transaction: this}, {cancelable: true})) {
+            this.#state = 'canceled';
+            return;
+        }
+        this.#state = 'running';
+        try {
+            const result = change(this);
+            if (result?.then) throw new TypeError('Editor transactions must be synchronous');
+            this.#selectionAfter = this.#surface.capture();
+            if (!this.#selectionAfter && this.#selectionBefore?.restore()) {
+                this.#selectionAfter = this.#surface.capture();
+            }
+            this.#state = 'committed';
+            this.#surface.emit('u2-rte-change', {transaction: this});
+            return result;
+        } catch (error) {
+            this.#state = 'failed';
+            this.#surface.emit('u2-rte-error', {transaction: this, error});
+            throw error;
+        }
+    }
+}

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

@@ -0,0 +1,255 @@
+# Toolbar UI
+
+`toolbar.js` binds an application's toolbar markup to the command registry of
+the currently active surface. It provides the roaming behavior; it does not
+create buttons, inject styles, choose icons, or define editor commands.
+
+The useful interaction model comes from the original `../rte0` toolbar: one
+shared toolbar follows the active editor, its items reflect the current
+selection, pointer interaction keeps the editor selection, and keyboard
+shortcuts invoke the same actions. RTE replaces the old global item registry,
+`execCommand()`, delayed focus repair, and automatic style injection with the
+existing core, surface, and command contracts.
+
+## Contract
+
+```js
+const toolbar = new Toolbar(core, element, {
+    commands: surface => commandsBySurface.get(surface),
+    place: (element, surface) => placeNearSelection(element, surface.selection),
+});
+```
+
+- `core` supplies the active surface and owns the single root-level lifecycle.
+- `element` is application-owned markup. Descendants with `data-command` are
+  action/toggle items; `select[data-command-value]` binds one value-bearing
+  command. No icon system or CSS is required. If the element has
+  `popover="manual"`, visibility also opens and closes it in the browser top
+  layer without changing focus.
+- `commands(surface)` resolves the registry belonging to that surface. Returning
+  `null` hides the toolbar, which permits lazy surface setup without coupling a
+  registry to `Surface`.
+- `place(element, surface)` is optional presentation policy called after every
+  visible refresh. Positioning remains replaceable and outside command logic.
+- `refresh()` reads command availability and state immediately and returns
+  whether the toolbar is visible.
+- `dispose()` removes all core, surface, DOM, and shortcut listeners. Core
+  disposal also disposes the toolbar.
+
+The toolbar listens only to active-surface changes, selection changes, committed
+changes, disconnect, and root focus transitions. Switching surfaces aborts the
+old surface listeners. It does not observe DOM or poll state.
+
+## Items
+
+```html
+<div class="toolbar" aria-label="Text formatting">
+    <button type="button" data-command="bold" data-state data-shortcut="b">Bold</button>
+    <button type="button" data-command="italic" data-state data-shortcut="i">Italic</button>
+</div>
+```
+
+An item is visible only when the active registry contains its command. Its
+`disabled`/`aria-disabled` state follows `commands.enabled()`. On a `data-state`
+item, boolean and `'mixed'` command states become `aria-pressed`, so toggle
+buttons need no separate adapter. Action buttons omit `data-state` and never
+pretend to be toggles merely because their command can report state.
+`data-control` may give a button a CSS-facing name different from its command,
+just as it does for a value control. This lets `--u2-rte-toolbar: breaks` expose
+a button whose command is `showBreaks`.
+
+`data-shortcut="b"` means Ctrl+B or Command+B while keyboard input belongs to
+the active surface. Shortcuts with Shift or Alt are deliberately not inferred;
+future keymap policy can generalize that syntax without changing commands.
+
+An editor may select the shared toolbar's available items with an inherited CSS
+property:
+
+```css
+.compact-editor { --u2-rte-toolbar: bold italic; }
+```
+
+An absent or empty property exposes every registered item represented in the
+markup. `--u2-rte-ui: none` hides this roaming toolbar. A future static binding
+can consume the same item contract without changing the core or registry.
+
+By default the toolbar is useful at both a caret and a selected range. An
+editor that wants contextual formatting controls only while text is visibly
+selected can opt in without constructing a different toolbar:
+
+```css
+.selection-toolbar { --u2-rte-toolbar-when: selection; }
+```
+
+`selection` means a valid, non-collapsed saved selection. A missing selection
+or caret hides the toolbar. `always`, an absent value, and unknown future values
+retain the default behavior.
+
+### Command values
+
+A select can represent a mutually exclusive group of commands:
+
+```html
+<select data-command-value="blockStyle" data-control="block" aria-label="Block style">
+    <option value="">Block style</option>
+    <option value="paragraph">Paragraph</option>
+    <option value="h1">Heading 1</option>
+</select>
+```
+
+`data-command-value` names one command, while `data-control` is the name exposed
+to `--u2-rte-toolbar`. Option values become `edit.value`. The command's string
+state selects the matching option; mixed, null, unknown, or conflicting state
+selects the empty placeholder. A change restores the saved editor selection and
+runs the command through the same transaction path as a button. Availability
+is queried with each option's value, so unsupported values are hidden and
+disabled; state is queried once per refresh. The adapter attaches no listener
+per option or surface.
+
+## Invariants
+
+- UI focus never deactivates the current surface or becomes editor selection.
+- Focus moving between the active surface and its toolbar keeps the toolbar
+  open. Leaving both hides it; later selection/change notifications do not
+  reopen it until focus returns.
+- Every action runs through `Commands`; UI code never mutates editable DOM.
+- One toolbar can serve arbitrarily many surfaces and resolve different command
+  sets for each one.
+- Markup, labels, localization, icons, layout, and placement are application
+  policy and add no engine-side resources when no toolbar is constructed.
+
+## Chrome
+
+`Chrome` is one shadow root per editor for everything the editor draws: its
+toolbar, its contextual handles, its forms and dialogs. It carries the top layer.
+
+`part(key, css, tag)` gives a piece of chrome its node and its stylesheet under
+one name: the key becomes the element's `id`, so the css is written `#link input`
+and nothing is named twice. Inside a root shared by nothing else an id is as
+unique as an attribute, and a second claim on the same key is an error rather
+than a silent second element. `style(key, css)` registers a stylesheet alone,
+once, for a piece that builds its own node.
+
+What every piece shares is one skin, `.panel` — blur, rounding, shadow, border —
+because to the eye the editor's chrome is one thing and not five. A piece brings
+only its own layout.
+
+Sizes inside are `em`, against a text size stated once on the host. Page-relative
+units would let a site's root font resize the editor's furniture by accident, and
+a variable plus `calc()` would only be `em` with arithmetic bolted on. The size
+is still meant to be changed, just not by accident: `--u2-rte-ui-size` (default
+`14px`) sets it, and reaches the chrome because `all: initial` does not touch
+custom properties and the host inherits them from the page.
+
+`follow(element)` keeps that one chrome inside the closest currently active
+native top-layer boundary: a modal dialog, open popover, or fullscreen element.
+This is a DOM relationship rather than a `z-index` trick, because modal
+inertness and fullscreen rendering admit only descendants. Dialog `open`
+mutations, popover `toggle`, and `fullscreenchange` update the mount; closing a
+boundary returns the chrome to its original `Document` or `ShadowRoot`.
+The host is an explicit `contenteditable=false` boundary. A convention client
+also retains it in the core so UI focus and temporary direct-host mounting do
+not become editor state or content.
+
+An editor is chrome inside someone else's document and has to survive their
+`button {}` rule. One encapsulated root means the page's CSS reaches none of it,
+none of its styles leak out, and the application sees a single element rather
+than one per piece of UI. Its host is `all: initial`, so the page's typography
+does not shift it either; custom properties are excluded from `all` and still
+inherit, so configuration is unaffected.
+
+There is deliberately no `::part` surface. Exposing parts would make the
+internal structure of the chrome a public contract, and it is not needed:
+an application that wants different chrome builds its own on the commands, which
+is the supported path and always was. `Toolbar` already binds application-owned
+markup for exactly that reason.
+
+## Handles
+
+`Handles` is 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, so anything with a rectangle can use it —
+inside this engine or outside it.
+
+```js
+const handles = new Handles(chrome.root, {
+    name: 'tables',
+    handles: [{name: 'rowAfter', label: 'Row below', text: '+'}],
+    action: name => …,
+    press: name => …,
+});
+handles.show().place('rowAfter', x, y).disable('rowAfter', false);
+```
+
+Given a shadow root it places itself inside it and registers its stylesheet
+there. Given a document it makes an encapsulated root of its own, so it works
+just as well outside an editor.
+
+Both its listeners are on the containing root rather than the host: an event
+that is not composed never leaves the shadow tree it happened in. Pressing a
+handle prevents its default, because pointing at editor chrome must never move
+the selection it acts on.
+
+The glyph inside a handle is centred with `text-box: trim-both cap alphabetic`,
+which trims the font's leading so a bare `+` or `×` sits on its optical centre
+rather than its metric one. Where that is unsupported the flex centring alone
+still applies.
+
+## Present or available
+
+Two different questions, answered two different ways:
+
+- **Presence** says what this editor offers at all. A control is absent when its
+  command is not registered on the surface, when `--u2-rte-toolbar` does not
+  list it, or when its choices are not configured — a style select with no
+  `--u2-rte-classes` has nothing to be.
+- **Availability** says what the current selection allows. A control that exists
+  but cannot act is disabled, never hidden.
+
+Keeping the two apart is what makes a toolbar usable: its shape follows the
+configuration and stays put while the caret moves, so a control is always found
+in the same place. A toolbar whose buttons appeared and vanished with every
+selection change would move its targets out from under the pointer.
+
+`--u2-rte-toolbar-unavailable: hide` trades that away deliberately, for a
+toolbar that only ever shows what it can do. It is the host's call, not the
+default: a compact toolbar of two or three controls loses little by moving,
+while a wide one loses a great deal.
+
+## Focus across the boundary
+
+A `focusout` listener outside the toolbar's shadow tree sees its related target
+retargeted to that tree's host. Focus moving from the surface into a control of
+the toolbar's own therefore looks like focus leaving the editor, and dismissing
+on it would take the toolbar away in the middle of the click that opened a
+select. Ownership is decided against the tree's host as well as its contents.
+
+## Placement
+
+`place(element, surface, {align, prefer, gap})` is the one placement policy for every
+contextual UI. It anchors on the surface's saved selection through `rangeRect`,
+keeps the element inside the viewport, and falls to the other side when the
+preferred one does not fit. The roaming toolbar centres above the selection; the
+link form aligns to its start and prefers below.
+
+A select with no usable choice hides like a button whose command is unavailable:
+a control that cannot be used is not shown.
+
+Pointing anywhere at the toolbar never moves the editor's selection, including
+at a control that currently has nothing to run — otherwise clicking a disabled
+button would blur the surface and dismiss the toolbar. Fields keep their own
+pointer behaviour so they can be opened and typed in.
+
+Keys are not the toolbar's concern: a command declares its own shortcut and the
+input pipeline resolves it, so a key works whether or not a control for it is on
+screen. `data-shortcut` remains as the hint shown in a control's title.
+
+## TODO
+
+- Add a static-surface binding using the same item state rules.
+- Define richer shortcut descriptors and conflict resolution with application
+  keymaps.
+- Bind menus and application-owned custom controls; command-valued selects are
+  implemented.
+- Verify top-layer Popover focus, caret, viewport, writing-mode, and ShadowRoot
+  behavior in all target browsers; use Dialog only for modal extension UI.

package/js/rte/src/ui/chrome.js

@@ -0,0 +1,214 @@
+// One shadow root per editor for everything the editor draws: its toolbar, its
+// contextual handles, its forms and dialogs.
+//
+// An editor is chrome inside someone else's document. Sharing one encapsulated
+// root means the page's own CSS cannot reach any of it, none of its styles can
+// leak out, and the application sees a single element rather than one per piece
+// of UI. Each piece owns its own layout; what they share is one skin, `.panel`,
+// because to the eye the editor's chrome is one thing and not five.
+export class Chrome {
+    #host;
+    #root;
+    #home;
+    #context;
+    #document;
+    #target = null;
+    #styles = new Set();
+    #controller;
+    #observer;
+    #drawing;
+    #connected = true;
+
+    constructor(root, {name = 'chrome'} = {}) {
+        const isDocument = root?.nodeType === Node.DOCUMENT_NODE;
+        const isShadow = root?.nodeType === Node.DOCUMENT_FRAGMENT_NODE;
+        if (!isDocument && !isShadow) throw new TypeError('Editor chrome requires a document or shadow root');
+        const document = isDocument ? root : root.ownerDocument;
+        this.#context = root;
+        this.#document = document;
+        this.#host = document.createElement('div');
+        this.#host.dataset.u2RteChrome = name;
+        this.#host.contentEditable = 'false';
+        this.#root = this.#host.attachShadow({mode: 'open'});
+        const style = document.createElement('style');
+        // The host is inert ground: only what a piece of UI places inside it
+        // takes the pointer.
+        //
+        // Important, because a normal declaration in a shadow tree loses to the
+        // outer document for the host element: a page rule as ordinary as
+        // `[popover] { border: solid }` would otherwise draw a frame around the
+        // whole editor. Important declarations reverse that order, so this is
+        // what makes the host unreachable rather than merely encapsulated.
+        style.textContent = `
+:host {
+    all: initial !important;
+    /* The chrome's own text size lives here, and everything inside measures
+       itself in em against it — one knob, no arithmetic. Page-relative units
+       would instead let a site's root font resize the editor's furniture by
+       accident. Important like the rest of the reset, because a rule in the
+       outer document outranks one from this shadow tree; the size stays settable
+       all the same, because "all" does not touch custom properties and the host
+       inherits them from the page. */
+    font: var(--u2-rte-ui-size, 14px)/1.2 system-ui, sans-serif !important;
+    inset: 0 !important;
+    pointer-events: none !important;
+    position: fixed !important;
+}
+/* A part states its own display, and an id beats any rule that would hide it —
+   so hiding says so outright, once, for everything drawn in here. */
+[hidden] { display: none !important; }
+.panel {
+    backdrop-filter: blur(.57em);
+    background: color-mix(in srgb, Canvas 92%, transparent);
+    border: 1px solid color-mix(in srgb, CanvasText 24%, transparent);
+    border-radius: .51em;
+    box-shadow: 0 .34em 1.14em #0006;
+    color: CanvasText;
+    inset: auto;
+    margin: 0;
+    padding: .23em;
+    pointer-events: auto;
+    position: fixed;
+    z-index: 2147483647;
+
+    button, input, select { color: inherit; font: inherit; }
+    button, select { background: transparent; border: 0; }
+    :disabled { opacity: .4; }
+}`;
+        this.#root.append(style);
+        this.#home = isDocument ? document.body || document.documentElement : root;
+        this.#home.append(this.#host);
+        if (typeof this.#host.showPopover === 'function') {
+            this.#host.popover = 'manual';
+            this.#host.showPopover();
+        }
+        this.#controller = new document.defaultView.AbortController();
+        const listen = {capture: true, signal: this.#controller.signal};
+        for (const type of ['toggle', 'fullscreenchange']) {
+            document.addEventListener(type, this.#topLayerChange, listen);
+            if (!isDocument) root.addEventListener(type, this.#topLayerChange, listen);
+        }
+        // Dialogs expose their open state synchronously as an attribute, but
+        // current engines do not all dispatch their newer toggle event yet.
+        this.#observer = new document.defaultView.MutationObserver(this.#topLayerChange);
+        // Whatever the editor draws is the most recent thing the user triggered,
+        // so it belongs in front of anything the page put in the top layer before.
+        this.#drawing = new document.defaultView.MutationObserver(records => {
+            if (records.some(record => !record.target.hidden)) this.raise();
+        });
+        this.#drawing.observe(this.#root, {subtree: true, attributes: true, attributeFilter: ['hidden']});
+    }
+
+    get element() { return this.#host; }
+    get root() { return this.#root; }
+    get target() { return this.#target; }
+    get connected() { return this.#connected; }
+
+    // Follows the target only across native top-layer boundaries. In ordinary
+    // content the chrome stays in its original document or shadow root.
+    follow(target = null) {
+        if (target !== null && target?.nodeType !== Node.ELEMENT_NODE) {
+            throw new TypeError('Editor chrome can follow only an element or null');
+        }
+        if (target && (target.ownerDocument !== this.#document || target.getRootNode() !== this.#context)) {
+            throw new RangeError('Editor chrome target must belong to its root');
+        }
+        this.#target = target;
+        this.#observer.disconnect();
+        for (let element = target; element?.nodeType === Node.ELEMENT_NODE; element = composedParent(element)) {
+            this.#observer.observe(element, {attributes: true, attributeFilter: ['open']});
+        }
+        this.#place();
+        return this;
+    }
+
+    // Registers one stylesheet under a key, once, however often it is offered.
+    style(key, css) {
+        if (!this.#connected || this.#styles.has(key)) return this;
+        this.#styles.add(key);
+        const style = this.#document.createElement('style');
+        style.id = `${key}-style`;
+        style.textContent = css;
+        this.#root.append(style);
+        return this;
+    }
+
+    // One node and one stylesheet under one name. The key is the element's id, so
+    // a piece of chrome writes `#link input` and is never named twice; inside an
+    // encapsulated root shared by nothing else, that is as unique as it gets.
+    part(key, css = '', tag = 'div') {
+        if (this.#root.getElementById(key)) throw new RangeError(`Editor chrome already draws: ${key}`);
+        const element = this.#document.createElement(tag);
+        element.id = key;
+        if (css) this.style(key, css);
+        this.#root.append(element);
+        return element;
+    }
+
+    dispose() {
+        if (!this.#connected) return;
+        this.#controller.abort();
+        this.#observer.disconnect();
+        this.#drawing.disconnect();
+        this.#host.remove();
+        // Emptying the root as well: a detached shadow tree still answers
+        // queries, and a disposed editor must have nothing left to find.
+        this.#root.replaceChildren();
+        this.#styles.clear();
+        this.#target = null;
+        this.#connected = false;
+    }
+
+    [Symbol.dispose]() {
+        this.dispose();
+    }
+
+    // Back to the front of the top layer, which is ordered by when each member
+    // was shown. Two manual popovers that never close — an editor's chrome and a
+    // host application's own menu — would otherwise keep the order they happened
+    // to be created in, whatever is being used right now.
+    raise() {
+        if (!this.#connected || typeof this.#host.showPopover !== 'function') return false;
+        if (!this.#host.matches(':popover-open')) return this.#place();
+        this.#host.hidePopover();
+        this.#host.showPopover();
+        return true;
+    }
+
+    #place() {
+        if (!this.#connected) return false;
+        const parent = topLayer(this.#target) || this.#home;
+        if (parent === this.#host.parentNode) {
+            if (typeof this.#host.showPopover === 'function' && !this.#host.matches(':popover-open')) {
+                this.#host.showPopover();
+            }
+            return false;
+        }
+        if (this.#host.matches(':popover-open')) this.#host.hidePopover();
+        parent.append(this.#host);
+        if (typeof this.#host.showPopover === 'function') this.#host.showPopover();
+        return true;
+    }
+
+    #topLayerChange = () => this.#place();
+}
+
+// The closest boundary is the one that owns the target's current top-layer
+// context. Walking through shadow hosts keeps the rule identical for document
+// and ShadowRoot editors.
+export function topLayer(target) {
+    for (let element = target; element?.nodeType === Node.ELEMENT_NODE; element = composedParent(element)) {
+        for (const selector of [':fullscreen', ':modal', ':popover-open']) {
+            try {
+                if (element.matches(selector)) return element;
+            } catch {
+                // Unsupported top-layer states simply cannot be active.
+            }
+        }
+    }
+    return null;
+}
+
+function composedParent(element) {
+    return element.parentElement || element.getRootNode()?.host || null;
+}