u2ui 1.5.4 → 1.5.8

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

@@ -18,16 +18,38 @@ document structure, or UI behavior.
   browser and document-lifecycle differences without duplicate activation.
 - The nearest explicit nested `contenteditable` is an isolation boundary.
 - `sync()` resolves the current selection to one registered surface and captures
-  it without scanning or mutating unrelated editor contents.
+  it without scanning or mutating unrelated editor contents. A selection is not
+  a session: once focus has left the editor, only focus starts one again.
+  Engines leave a selection inside an editable that nobody focused — clicking
+  beside one does that — and a toolbar over a caret the keyboard cannot reach is
+  worse than no toolbar. The surface still keeps what it captured.
 - At most one surface is active per core; active state may outlive DOM focus so
   a roaming UI can safely receive focus.
 - `retain(element)` marks editor-owned UI in the same document. Focus inside it
   keeps the active surface, `retains(node)` identifies its composed subtree,
   and `release(element)` removes the mark. This also distinguishes UI from
   content when a native top-layer boundary requires both to share one host.
+- A link, a button, or a label around an editing host is answered by the element,
+  not by the text: the link is dragged rather than giving the text a caret and
+  followed when the press ends, and the label hands the press to the control it
+  names. Both are suppressed for a press that belongs to
+  the text, and the link is left undraggable — nobody drags a link wrapped
+  around editable content on purpose.
+- The right button never moves the selection inside a surface: its menu is about
+  what is selected, and aiming the menu somewhere else is what would make it
+  useless.
+- A press decides which surface a focus belongs to. Engines hand the focus to
+  the nearest editable when a press lands beside one, which an inline host in
+  running text collects a whole line of; a focus whose press did not land in the
+  surface is refused and given back. A press answers for every focus until it is
+  released — one drag can hand the focus back more than once — and a key taking
+  over ends it too, so a keyboard reaching a surface is never mistaken for it.
 - Focus that lands anywhere else — not a surface, not retained UI — ends the
-  session, so everything drawn for it goes at once. Retaining is therefore how a
-  UI that takes focus stays alive; `Toolbar` retains its element itself.
+  session, so everything drawn for it goes at once. So does focus that lands
+  nowhere: clicking a plain paragraph focuses nothing, and no focus event
+  follows to say so, which is what `focusout` is listened to for. Retaining is
+  therefore how a UI that takes focus stays alive; `Toolbar` retains its element
+  itself.
 - `dispose()` removes listeners and disconnects every surface. It is
   idempotent; `[Symbol.dispose]()` exposes the same teardown to `using`.
 

package/js/rte/src/core/core.js

@@ -1,4 +1,5 @@
 import {enabled} from '../config/config.js';
+import {interactiveAround} from '../browser/interactive.js';
 import {editingHost, isEditableHost, isEditingBoundary} from '../selection/ownership/ownership.js';
 import {Surface} from '../surface/surface.js';
 
@@ -10,6 +11,9 @@ export class Rte extends EventTarget {
     #elements = new WeakMap();
     #retained = new Set();
     #active = null;
+    #unfocused = false;
+    #pointer = null;
+    #handed = false;
     #controller;
 
     constructor(root = document, options = {}) {
@@ -24,6 +28,15 @@ export class Rte extends EventTarget {
         const listen = {capture: true, signal: this.#controller.signal};
         root.addEventListener('focus', this.#focus, listen);
         root.addEventListener('focusin', this.#focus, listen);
+        root.addEventListener('focusout', this.#focusOut, listen);
+        // A press answers for every focus until it is over: one drag can hand the
+        // focus back more than once. A key taking over ends it too, so what is
+        // left of a release that never arrived cannot answer for the keyboard.
+        root.addEventListener('pointerdown', this.#pointerDown, listen);
+        for (const type of ['pointerup', 'pointercancel', 'keydown']) {
+            root.addEventListener(type, this.#pointerDone, listen);
+        }
+        root.addEventListener('click', this.#click, listen);
         this.#document.addEventListener('selectionchange', this.#selectionChange, {signal: this.#controller.signal});
     }
 
@@ -108,6 +121,12 @@ export class Rte extends EventTarget {
             this.activate(null);
             return null;
         }
+        // A selection is not a session: once the focus has left the editor, only
+        // focus brings it back. Engines leave a selection inside an editable that
+        // nobody focused — clicking beside one does that — and a toolbar over a
+        // caret the keyboard cannot reach is worse than no toolbar. What the
+        // surface captured, it keeps either way.
+        if (this.#unfocused && this.#active !== surface) return null;
         this.activate(surface);
         return surface;
     }
@@ -125,26 +144,98 @@ export class Rte extends EventTarget {
     }
 
     #focus = event => {
-        if (event.composedPath().some(node => this.#retained.has(node))) return;
-        const editable = event.composedPath().find(node =>
+        const path = event.composedPath();
+        if (path.some(node => this.#retained.has(node))) {
+            this.#unfocused = false;
+            return;
+        }
+        const editable = path.find(node =>
             node?.nodeType === Node.ELEMENT_NODE && isEditingBoundary(node)
         );
         // Focus that went somewhere else entirely ends the session: retained UI
         // is already excluded above, so what is left is not the editor's, and
         // everything drawn for it has to go with it.
-        if (!editable) {
+        if (!editable || !isEditableHost(editable)) {
+            this.#unfocused = true;
             this.activate(null);
             return;
         }
-        if (!isEditableHost(editable)) {
+        let surface = this.#elements.get(editable);
+        if (!surface && this.#options.auto && enabled(editable)) surface = this.add(editable);
+        // An engine gives the focus to the nearest editable when a press lands
+        // beside one: an inline host collects its whole line. A press that did
+        // not land in this surface is nobody starting to edit it, and the caret
+        // it would leave behind is one no one asked for.
+        //
+        // Taking it back is the one thing here that reaches into the document:
+        // the element really is focused for a moment, so the page sees a
+        // focus/blur pair it did not ask for, and anything listening for either
+        // on that element — a host's own handler, a css `:focus` rule — sees it
+        // too. Leaving it focused instead is worse: a caret that types into a
+        // surface with no session behind it.
+        if (surface && this.#pointer && !this.#pointer.includes(surface.element)) {
+            this.#unfocused = true;
             this.activate(null);
+            // Handing the focus back once per press. An engine that answers a
+            // blur by focusing again — the selection is still in there, after
+            // all — would otherwise trade focus with the editor for as long as
+            // the button is down, and the session stays refused either way.
+            if (!this.#handed) {
+                this.#handed = true;
+                editable.blur();
+            }
             return;
         }
-        let surface = this.#elements.get(editable);
-        if (!surface && this.#options.auto && enabled(editable)) surface = this.add(editable);
+        this.#unfocused = !surface;
         this.activate(surface || null);
     };
 
+    // Focus falling back to the document is the one way a session ends without
+    // a focus event to end it: nothing is focused, so nothing announces it.
+    // A related target inside a surface or in retained UI is `#focus`'s to
+    // decide — deactivating here would end a session that is only moving.
+    #focusOut = event => {
+        if (this.#owns(event.relatedTarget)) return;
+        this.#unfocused = true;
+        this.activate(null);
+    };
+
+    // The editor's world: one of its surfaces, or UI it retains.
+    #owns(node) {
+        return !!node && (this.retains(node) || this.#elements.has(editingHost(node)));
+    }
+
+    #pointerDown = event => {
+        const path = event.composedPath();
+        this.#pointer = path;
+        this.#handed = false;
+        const editing = this.#editing(path[0]);
+        // The right button opens a menu about what is selected; moving the
+        // selection to what it was aimed at is what makes the menu useless.
+        if (event.button === 2 && editing) event.preventDefault();
+        // The drag has to be off before this very press is acted on, which is
+        // what a capturing listener is early enough for. It stays off: a link
+        // wrapping editable content is not one anybody drags on purpose.
+        const around = interactiveAround(editing);
+        if (around) around.draggable = false;
+    };
+
+    // The press belonged to the text, and so does its release.
+    #click = event => {
+        if (interactiveAround(this.#editing(event.composedPath()[0]))) event.preventDefault();
+    };
+
+    // The editing host a node sits in, if this core is the editor of it.
+    #editing(node) {
+        const host = editingHost(node);
+        if (!host) return null;
+        return this.#elements.has(host) || this.#options.auto && enabled(host) ? host : null;
+    }
+
+    #pointerDone = () => {
+        this.#pointer = null;
+    };
+
     #selectionChange = () => {
         this.sync();
     };

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

@@ -63,6 +63,24 @@ to `using`. Disconnecting the surface also disposes them automatically.
   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

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

@@ -1,5 +1,6 @@
 import {htmlModel} from '../model/html/html-model.js';
 import {narrow} from '../command/edit.js';
+import {activatingAround} from '../browser/interactive.js';
 import {Normalizer} from '../normalize/normalizer/normalizer.js';
 import {PointMap} from '../selection/map/point-map.js';
 import {EditRange} from '../selection/range/edit-range.js';
@@ -71,6 +72,7 @@ export class InputPipeline {
         root.addEventListener('compositionend', this.#compositionEnd, listen);
         root.addEventListener('paste', this.#paste, listen);
         root.addEventListener('drop', this.#drop, listen);
+        root.addEventListener('click', this.#click, listen);
         surface.addEventListener('u2-rte-command', this.#command, listen);
         surface.addEventListener('u2-rte-disconnect', this.#disconnect, listen);
     }
@@ -198,6 +200,7 @@ export class InputPipeline {
             if (this.#invoke(event, shortcut, {range: selectionRange(this.#surface)})) return;
         }
         if (event.altKey) return;
+        if ((event.key === 'Enter' || event.key === ' ') && this.#activation(event)) return;
         const inputType = keyInput(event);
         if (!inputType) return;
         this.#surface.capture();
@@ -208,6 +211,19 @@ export class InputPipeline {
         });
     };
 
+    // In a button, Enter and Space belong to the button: the text inside never
+    // sees them and no `beforeinput` arrives, so the editor puts in what the key
+    // meant. Everywhere else the browser's own input is left alone.
+    #activation(event) {
+        if (event.ctrlKey || event.metaKey || !activatingAround(this.#root)) return false;
+        this.#surface.capture();
+        const range = selectionRange(this.#surface);
+        if (event.key === 'Enter') return this.#route(event, {inputType: 'insertParagraph', data: null, range});
+        const fragment = this.#root.ownerDocument.createDocumentFragment();
+        fragment.append(space(range));
+        return this.#invoke(event, 'insert', {fragment, range});
+    }
+
     #input = event => {
         if (!this.#owns(event)) return;
         const pending = this.#pending;
@@ -245,6 +261,25 @@ export class InputPipeline {
         });
     };
 
+    // An atomic element is addressable only as the selection: engines disagree
+    // about whether pointing at one selects it, and a caret one leaves inside it
+    // reaches nothing at all. The host itself is left alone — a surface is not a
+    // thing inside itself.
+    #click = event => {
+        const target = event.composedPath()[0];
+        if (target === this.#root || !this.#owns(event) || target?.nodeType !== Node.ELEMENT_NODE) return;
+        // The base model, not the narrowed one: what an element is does not
+        // depend on which elements a host allows, and narrowing costs a computed
+        // style on a path every click in the text goes through.
+        if (!this.#model.atomic(target)) return;
+        const range = this.#root.ownerDocument.createRange();
+        range.selectNode(target);
+        const selection = this.#surface.core.selection;
+        selection.removeAllRanges();
+        selection.addRange(range);
+        this.#surface.capture();
+    };
+
     #paste = event => {
         if (this.#owns(event)) this.#rememberSource('paste');
     };
@@ -323,6 +358,16 @@ export class InputPipeline {
     }
 }
 
+// A plain space collapses away where there is nothing after it, or where another
+// space already is — so there the browser types a non-breaking one, and so does
+// this. Anywhere else a space is a space.
+function space(range) {
+    const node = range?.startContainer;
+    if (node?.nodeType !== Node.TEXT_NODE) return '\u00a0';
+    const before = range.startOffset ? node.data[range.startOffset - 1] : '';
+    return before.trim() && range.startOffset < node.length ? ' ' : '\u00a0';
+}
+
 function keyInput(event) {
     if (event.ctrlKey || event.metaKey || event.shiftKey) return null;
     return DELETE_KEYS.get(event.key) || null;

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

@@ -16,8 +16,11 @@ repairs editable document shape.
 - `comments` and `dataAttributes`: explicit booleans, both false by default.
 
 The supplied `sanitizePolicy` accepts the `document` element preset, ordinary
-editor metadata, and conservative web URLs. Inline styles, event attributes,
-`data:` URLs, comments, and data attributes are not enabled by default.
+editor metadata, and conservative web URLs. An image may carry a `data:` URL,
+because an image executes nothing — not even an SVG one, which browsers draw in
+a script-free context; in a navigating attribute the same protocol is a page, so
+links and citations keep it out. Inline styles, event attributes, comments, and
+data attributes are not enabled by default.
 Relative URLs use the explicit `relative` protocol token. Known URL attributes
 without a matching protocol rule are removed rather than accepted implicitly.
 

package/js/rte/src/sanitize/policy.js

@@ -19,7 +19,11 @@ const DEFAULT_ATTRIBUTES = Object.freeze({
 const DEFAULT_PROTOCOLS = Object.freeze({
     a: Object.freeze({href: Object.freeze(['http', 'https', 'mailto', 'relative', 'tel'])}),
     blockquote: Object.freeze({cite: Object.freeze(['http', 'https', 'relative'])}),
-    img: Object.freeze({src: Object.freeze(['http', 'https', 'relative'])}),
+    // `data:` belongs to an image and to nothing else here: an image executes
+    // nothing, not even an SVG one, which browsers draw in a script-free
+    // context. In a navigating attribute the same protocol is a page, so `a`
+    // and the citations keep it out.
+    img: Object.freeze({src: Object.freeze(['data', 'http', 'https', 'relative'])}),
     q: Object.freeze({cite: Object.freeze(['http', 'https', 'relative'])}),
 });
 

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

@@ -218,11 +218,22 @@ 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.
+Whether focus leaving the editor ends the session is the core's decision, not
+the toolbar's: it knows every surface and every retained element, so one rule
+covers the toolbar, the contextual UI in the chrome, and anything a host
+retains. The toolbar shows and hides with the active surface and does not watch
+focus itself.
+
+## The selection while a form has the focus
+
+A browser paints a selection only where the focus is, so a form of the editor's
+own makes the text it is about to change stop looking selected. `highlight.js`
+draws the surface's saved selection in its place, through the CSS custom
+highlight API, and stops the moment the text has the focus again — the browser's
+own selection is never painted over. The rule goes into the tree that holds the
+text, because a highlight is painted on the range's own nodes, and sits in the
+`u2-rte` layer, so `::highlight(u2-rte-selection)` in a page's own stylesheet
+replaces it. Engines without the API simply show nothing extra.
 
 ## Placement
 
@@ -232,12 +243,22 @@ 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.
 
+Two panels can answer for the same thing — an image that is also a link brings
+its frame, its name and its address — so a panel goes under whatever is already
+drawn where it wants to be, in the order the chrome holds them. `panelGap` is
+the one distance they all keep from what they hang off, and from each other.
+
+`caretAfter(surface, element)` is its counterpart at the end: the one way a
+contextual UI hands the caret back, after the element it was about to change
+rather than inside it. An element that is no longer there leaves the surface
+with the selection it had.
+
 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
+button would blur the surface and end the editing session. 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

package/js/rte/src/ui/caret.js

@@ -0,0 +1,17 @@
+// The other half of `place`: where a contextual UI hands the caret back when it
+// is done. After the element it was about to change, never inside it — whoever
+// just named an image or made a link wants to keep writing, without it. The
+// surface takes the focus first, so what it captures is a selection it owns.
+//
+// An element that is no longer there leaves the surface with what it had.
+export function caretAfter(surface, element) {
+    surface.element.focus();
+    if (!element?.isConnected) return surface.restore();
+    const range = surface.element.ownerDocument.createRange();
+    range.setStartAfter(element);
+    range.collapse(true);
+    const selection = surface.core.selection;
+    selection.removeAllRanges();
+    selection.addRange(range);
+    return !!surface.capture();
+}

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

@@ -196,7 +196,7 @@ export class Chrome {
 // 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) {
+function topLayer(target) {
     for (let element = target; element?.nodeType === Node.ELEMENT_NODE; element = composedParent(element)) {
         for (const selector of [':fullscreen', ':modal', ':popover-open']) {
             try {

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

@@ -1,4 +1,4 @@
-export const handleStyle = `
+const handleStyle = `
 .handles > .frame {
     border: 1px solid Highlight;
     box-sizing: border-box;

package/js/rte/src/ui/highlight.js

@@ -0,0 +1,86 @@
+const NAME = 'u2-rte-selection';
+// System colours, so what stands in for the selection looks like one. In a
+// layer, so a page that wants its own answer simply writes an ordinary rule.
+const STYLE = `@layer u2-rte {
+::highlight(${NAME}) { background-color: Highlight; color: HighlightText; }
+}`;
+
+// A browser paints a selection only where the focus is, so the moment a form of
+// the editor's own takes the caret, the text it is about to change stops looking
+// selected. The surface's saved selection is drawn in its place: the range the
+// commands act on is the range the eye follows.
+//
+// It is the editor's, not one form's: a link address, an image's name and
+// anything else that takes focus all leave the same gap behind them.
+export class SelectionHighlight {
+    #core;
+    #document;
+    #style = null;
+    #controller;
+    #connected = true;
+
+    constructor(core) {
+        if (!core?.root || typeof core?.addEventListener !== 'function') {
+            throw new TypeError('A selection highlight requires an editor core');
+        }
+        const root = core.root;
+        this.#core = core;
+        this.#document = root.nodeType === Node.DOCUMENT_NODE ? root : root.ownerDocument;
+        this.#controller = new this.#document.defaultView.AbortController();
+        const listen = {capture: true, signal: this.#controller.signal};
+        // Surface events bubble out composed, so one listener covers every
+        // surface the core owns, whichever of them is being edited.
+        for (const type of ['focusin', 'focusout', 'u2-rte-selectionchange', 'u2-rte-change']) {
+            root.addEventListener(type, this.#update, listen);
+        }
+        core.addEventListener('u2-rte-activechange', this.#update, {signal: this.#controller.signal});
+        this.#update();
+    }
+
+    get connected() { return this.#connected; }
+
+    refresh() {
+        const surface = this.#core.active;
+        const selection = surface?.selection;
+        const highlights = this.#document.defaultView.CSS?.highlights;
+        if (!highlights) return false;
+        // Not while the text itself has the focus: the browser is already
+        // painting that selection, and painting it twice can only disagree.
+        // `activeElement` of the core's own root: in a shadow tree the document
+        // reports the host, which says nothing about what is focused inside it.
+        if (!selection || selection.collapsed || surface.element.contains(this.#core.root.activeElement)) {
+            highlights.delete(NAME);
+            return false;
+        }
+        this.#ensure();
+        highlights.set(NAME, new this.#document.defaultView.Highlight(selection.range()));
+        return true;
+    }
+
+    dispose() {
+        if (!this.#connected) return;
+        this.#controller.abort();
+        this.#document.defaultView.CSS?.highlights?.delete(NAME);
+        this.#style?.remove();
+        this.#style = null;
+        this.#connected = false;
+    }
+
+    [Symbol.dispose]() {
+        this.dispose();
+    }
+
+    // The rule belongs to the tree that holds the text, not to the editor's own
+    // shadow root: a highlight is painted on the range's own nodes.
+    #ensure() {
+        if (this.#style) return;
+        const root = this.#core.root;
+        const style = this.#document.createElement('style');
+        style.dataset.u2RteHighlight = '';
+        style.textContent = STYLE;
+        (root.nodeType === Node.DOCUMENT_NODE ? this.#document.head || this.#document.documentElement : root).append(style);
+        this.#style = style;
+    }
+
+    #update = () => this.refresh();
+}

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

@@ -6,6 +6,11 @@ import {rangeRect} from '../browser/range-rect.js';
 //
 // 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.
+// One distance for every panel that hangs off an element rather than off the
+// selection: the handles on a frame's edge reach about this far, and two panels
+// answering for the same element must not sit at two different heights.
+export const panelGap = 16;
+
 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;
@@ -19,7 +24,24 @@ export function place(element, surface, {align = 'center', prefer = 'above', gap
     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`;
+    const left = Math.max(gap, Math.min(view.innerWidth - box.width - gap, start));
+    element.style.left = `${left}px`;
+    element.style.top = `${clear(element, {top, left, width: box.width, height: box.height}, gap)}px`;
     return true;
 }
+
+// Two panels can answer for the same thing — an image that is also a link — and
+// the second must not sit on the first. What is already drawn keeps its spot and
+// the newcomer goes under it, in the order the chrome holds them, so the same
+// two always stack the same way round.
+function clear(element, box, gap) {
+    let top = box.top;
+    for (const panel of element.getRootNode().querySelectorAll?.('.panel') ?? []) {
+        if (panel === element || panel.hidden) continue;
+        const other = panel.getBoundingClientRect();
+        const misses = other.bottom <= top || other.top >= top + box.height
+            || other.right <= box.left || other.left >= box.left + box.width;
+        if (!misses) top = other.bottom + gap;
+    }
+    return top;
+}