@twip/web 0.0.0-canary-092e560 → 0.0.0-canary-abcb2d5

package/dist/commands.d.ts

@@ -1,5 +1,5 @@
 import type { RichText } from './review.js';
-import type { ControlKind, ControlOptions, DataBinding } from './services/elements.js';
+import type { ControlKind, ControlOptions, DataBinding, ReferenceRule } from './services/elements.js';
 import type { TabAlignment, TabLeader, TabSelector } from './services/ruler.js';
 import type { ViewOptions } from './services/view.js';
 import type { AutoCorrectChange, HighlightColor, HorizontalPosition, LineSpacing, MarkupView, ObjectWrap, RowHeight, TablePosition, TableWidth, UnderlineStyle, VerticalPosition, WrapSide } from './state.js';
@@ -476,6 +476,40 @@ export interface Commands {
         labels: Record<string, string>;
         merge?: boolean;
     }): Promise<void>;
+    /** Which fields are sub-template references: replaces the rules; an empty list turns sub-templates off. View. */
+    setSubTemplateRules(options: {
+        rules: ReferenceRule[];
+    }): Promise<void>;
+    /** Shows references' sub-template bodies in their place, or their fields (default: every reference). View. */
+    setSubTemplateView(options: {
+        ids?: ElementId[];
+        expanded: boolean;
+    }): Promise<void>;
+    /** Edits a sub-template's body in this editor, on its own pages. View. */
+    editSubTemplate(options: {
+        name: string;
+        category?: string;
+    }): Promise<void>;
+    /** Back to the template from a sub-template, at the template's selection from before. View. */
+    closeSubTemplate(): Promise<void>;
+    /** A new sub-template, empty or with a DOCX's body (`category`: default the first rule's). */
+    createSubTemplate(options: {
+        name: string;
+        category?: string;
+        from?: Uint8Array;
+    }): Promise<void>;
+    /** Renames a sub-template, and with `updateReferences` every reference to it. */
+    renameSubTemplate(options: {
+        name: string;
+        to: string;
+        category?: string;
+        updateReferences?: boolean;
+    }): Promise<void>;
+    /** Removes a sub-template; its references no longer resolve. */
+    removeSubTemplate(options: {
+        name: string;
+        category?: string;
+    }): Promise<void>;
     /** Inserts a content control, optionally around the selection. */
     insertControl(options: {
         kind: ControlKind;
@@ -646,6 +680,8 @@ export interface Commands {
     showAutoCorrectOptions(): Promise<void>;
     /** Dismisses the popover asked for (`popoverClosed`), for an application that closes its own on Esc or a press elsewhere; with none open, nothing. View. */
     closePopover(): Promise<void>;
+    /** Says the formatting at the caret to screen readers (an `announcement` of kind `formatting`). Shift+F1. */
+    describeFormatting(): Promise<void>;
 }
 /** A command id: the method name, the batch op's `type`, the catalog id and the key in `state.commands`. */
 export type CommandId = keyof Commands;

package/dist/commands.js

@@ -143,6 +143,13 @@ const encodings = {
     unlinkFields: 'spread',
     showFieldCodes: 'spread',
     setFieldLabels: 'spread',
+    setSubTemplateRules: 'spread',
+    setSubTemplateView: 'spread',
+    editSubTemplate: 'spread',
+    closeSubTemplate: 'none',
+    createSubTemplate: 'spread',
+    renameSubTemplate: 'spread',
+    removeSubTemplate: 'spread',
     insertControl: 'spread',
     setControl: 'spread',
     removeControl: 'spread',
@@ -184,6 +191,7 @@ const encodings = {
     neverAutoCorrect: 'none',
     showAutoCorrectOptions: 'none',
     closePopover: 'none',
+    describeFormatting: 'none',
 };
 /** Builds a command's op from its method arguments. */
 export function toOp(id, arg) {

package/dist/editor.d.ts

@@ -4,7 +4,7 @@ import { FontLibrary } from './fonts/library.js';
 import { type MountedReview, type Review } from './review.js';
 import { type Accessibility, type Shortcuts } from './services/accessibility.js';
 import { type Dialogs } from './services/dialogs.js';
-import { type DataParts, type Elements, type MountedElements } from './services/elements.js';
+import { type DataParts, type Elements, type MountedElements, type SubTemplates } from './services/elements.js';
 import { type Find } from './services/find.js';
 import { type Menus } from './services/menus.js';
 import { type Navigation, type Styles } from './services/navigation.js';
@@ -74,6 +74,8 @@ export interface MountOptions extends SessionOptions {
      * `leaders` colour, so the application draws only the cards. Default false: the application draws them.
      */
     drawLeaders?: boolean;
+    /** The editor's accessible name, which screen readers say when it gets the focus. Default `'Document'`. */
+    label?: string;
     /** Aborts the mount; everything it created is released. */
     signal?: AbortSignal;
 }
@@ -151,6 +153,8 @@ export declare class HeadlessEditor {
     readonly elements: Elements;
     /** The custom XML data parts. */
     readonly data: DataParts;
+    /** The template's sub-templates, and editing one in this editor. */
+    readonly subTemplates: SubTemplates;
     /** The ruler model. */
     readonly ruler: RulerModelSource;
     /** The accessibility tree. */

package/dist/editor.js

@@ -6,7 +6,7 @@ import { mountHost } from './host/mount.js';
 import { createMountedReview, createReview } from './review.js';
 import { createAccessibility, createShortcuts } from './services/accessibility.js';
 import { createDialogs } from './services/dialogs.js';
-import { createDataParts, createElements } from './services/elements.js';
+import { createDataParts, createElements, createSubTemplates, } from './services/elements.js';
 import { createFind } from './services/find.js';
 import { createMenus } from './services/menus.js';
 import { createNavigation, createStyles } from './services/navigation.js';
@@ -270,6 +270,8 @@ export class HeadlessEditor {
     elements;
     /** The custom XML data parts. */
     data;
+    /** The template's sub-templates, and editing one in this editor. */
+    subTemplates;
     /** The ruler model. */
     ruler;
     /** The accessibility tree. */
@@ -295,6 +297,7 @@ export class HeadlessEditor {
         this.review = createReview(session);
         this.elements = createElements(session);
         this.data = createDataParts(session);
+        this.subTemplates = createSubTemplates(session);
         this.ruler = { model: () => session.state.ruler };
         this.accessibility = createAccessibility(session);
         this.shortcuts = createShortcuts(session);

package/dist/events.d.ts

@@ -1,11 +1,12 @@
 import type { EditorError } from './errors.js';
 import type { BalloonPlacement, CommentAnchor } from './review.js';
+import type { AnnouncementKind } from './services/accessibility.js';
 import type { DialogKind } from './services/dialogs.js';
 import type { ElementInfo } from './services/elements.js';
 import type { ContextMenuEvent } from './services/menus.js';
 import type { RulerView } from './services/ruler.js';
 import type { GestureEvent, Popover } from './services/view.js';
-import type { SelectionSummary } from './state.js';
+import type { EditingTarget, SelectionSummary } from './state.js';
 import type { Author, ClientPoint, ClientRect, CommentId, ElementId, RevisionId, Warning } from './types.js';
 /** Every event of `editor.on(type, listener)`, keyed by type. */
 export interface TwipEvents {
@@ -13,6 +14,8 @@ export interface TwipEvents {
     documentChanged: TransactionRecord;
     /** The selection changed; coalesced per frame. */
     selectionChanged: SelectionSummary;
+    /** The editor switched between the template and a sub-template, or between sub-templates: where it is now. */
+    editingTargetChanged: EditingTarget;
     /** A link was activated: a click when read only, Ctrl+click otherwise. */
     linkActivated: {
         address: string;
@@ -23,6 +26,19 @@ export interface TwipEvents {
         key: string;
         element: ElementId | null;
     };
+    /**
+     * Typing, pasting or dropping was refused: into a sub-template's body shown in place of its reference (edit the
+     * sub-template instead), or into a locked control.
+     */
+    editRefused: {
+        reason: {
+            kind: 'subTemplate';
+            name: string;
+        } | {
+            kind: 'locked';
+        };
+        element?: ElementId;
+    };
     /** The user asked for a context menu. */
     contextMenu: ContextMenuEvent;
     /**
@@ -86,9 +102,10 @@ export interface TwipEvents {
     rulerChanged: RulerView;
     /** Mounted only: hover over a link, element mark, revision or comment, or `null` when it ends. */
     tooltip: Tooltip | null;
-    /** What the editor said to screen readers. */
+    /** What the editor said to screen readers, and what it is about (when one change says several things, the first). */
     announcement: {
         text: string;
+        kind: AnnouncementKind;
     };
     /** A fidelity warning outside an operation. */
     warning: Warning;

package/dist/host/a11y.d.ts

@@ -1,3 +1,9 @@
 import type { Session } from '../editor.js';
 import type { Dom, Ledger } from './dom.js';
-export declare function startA11y(s: Session, dom: Dom, ledger: Ledger): void;
+/** The mirror's part in pointer input. */
+export interface A11y {
+    /** Whether a mirror node was just activated: a press now is the screen reader's click, and places no caret. */
+    activating(): boolean;
+}
+/** Mirrors the tree and speaks announcements. `label` is the editor's accessible name; `focus` focuses the editing element. */
+export declare function startA11y(s: Session, dom: Dom, ledger: Ledger, label: string, focus: () => void, report: (e: unknown) => void): A11y;

package/dist/host/a11y.js

@@ -1,42 +1,156 @@
-import { Kind } from '../transport/protocol.js';
-const roles = {
-    document: 'document',
-    page: 'region',
-    paragraph: 'paragraph',
-    heading: 'heading',
-    list: 'list',
-    listItem: 'listitem',
-    table: 'table',
-    row: 'row',
-    cell: 'cell',
-    image: 'img',
-    link: 'link',
-    textBox: 'group',
-    note: 'note',
-    header: 'region',
-    footer: 'region',
+import { Kind, Method } from '../transport/protocol.js';
+/** Each role's element and ARIA role. Inline nodes are spans; the rest are divs. */
+const elements = {
+    document: { tag: 'div', role: 'document' },
+    paragraph: { tag: 'div', role: 'paragraph' },
+    heading: { tag: 'div', role: 'heading' },
+    list: { tag: 'div', role: 'list' },
+    listItem: { tag: 'div', role: 'listitem' },
+    table: { tag: 'div', role: 'table' },
+    row: { tag: 'div', role: 'row' },
+    cell: { tag: 'div', role: 'cell' },
+    columnHeader: { tag: 'div', role: 'columnheader' },
+    rowHeader: { tag: 'div', role: 'rowheader' },
+    image: { tag: 'span', role: 'img' },
+    link: { tag: 'span', role: 'link' },
+    textBox: { tag: 'div', role: 'group' },
+    note: { tag: 'div', role: 'note' },
+    noteRef: { tag: 'span', role: 'link' },
+    comment: { tag: 'div', role: 'comment' },
+    // Named groups inside the headers and footers region: the landmark key goes from region to region, not into each.
+    header: { tag: 'div', role: 'group' },
+    footer: { tag: 'div', role: 'group' },
+    region: { tag: 'div', role: 'region' },
+    text: { tag: 'span' },
 };
-const hidden = 'position:absolute;left:0;top:0;width:1px;height:1px;overflow:hidden;clip-path:inset(50%);white-space:nowrap;';
-function build(node) {
-    const e = document.createElement('div');
-    e.setAttribute('role', roles[node.role] ?? 'group');
-    if (node.name)
-        e.setAttribute('aria-label', node.name);
-    if (node.level !== undefined)
-        e.setAttribute('aria-level', String(node.level));
-    const marks = node.marks ?? [];
-    if (marks.includes('misspelling'))
-        e.setAttribute('aria-invalid', 'spelling');
-    const review = marks.filter((m) => m !== 'misspelling');
-    if (review.length)
-        e.setAttribute('aria-description', review.join(' '));
-    if (node.text)
-        e.append(node.text);
-    for (const child of node.children)
-        e.append(build(child));
-    return e;
+/** Nodes that hold no caret position of their own: the rest take the focus, and focusing one starts editing there. */
+const unfocused = new Set(['document', 'region', 'header', 'footer', 'list', 'table', 'row', 'text']);
+// Out of sight, one line per block: wrapped at 1px, a screen reader using the screen's layout reads a word a line.
+const hidden = 'position:absolute;left:0;top:0;width:1px;height:1px;overflow:hidden;clip-path:inset(50%);white-space:pre;';
+/** Mounts on one page get distinct element ids: `aria-details` refers to them. */
+let mounts = 0;
+/** The mirror of one mount's tree. */
+class Mirror {
+    #byId = new Map();
+    #prefix = `twip-${++mounts}-`;
+    root;
+    label;
+    constructor(root, label) {
+        this.root = root;
+        this.label = label;
+    }
+    /** The element id of node `id`, for `aria-details`. */
+    #elementId(id) {
+        return this.#prefix + id;
+    }
+    #build(node) {
+        const { tag, role } = elements[node.role] ?? elements.paragraph;
+        // Insertions and deletions are ins and del, which screen readers report as such.
+        const marks = node.marks ?? [];
+        const e = document.createElement(marks.includes('insertion') ? 'ins' : marks.includes('deletion') ? 'del' : tag);
+        e.dataset.twipId = String(node.id);
+        e.id = this.#elementId(node.id);
+        if (role)
+            e.setAttribute('role', role);
+        const name = node.role === 'document' ? this.label : node.name;
+        // A note reference holds no text of its own: its name is its text (a name alone, Chrome's NVDA reads as a letter).
+        if (name && node.role === 'noteRef' && !node.text && !node.children.length)
+            e.append(name);
+        else if (name && node.role !== 'text')
+            e.setAttribute('aria-label', name);
+        if (node.level !== undefined && (node.role === 'heading' || node.role === 'listItem'))
+            e.setAttribute('aria-level', String(node.level));
+        if (node.position) {
+            e.setAttribute('aria-posinset', String(node.position.index));
+            e.setAttribute('aria-setsize', String(node.position.count));
+        }
+        if (node.cell) {
+            e.setAttribute('aria-colindex', String(node.cell.col));
+            if (node.cell.colSpan > 1)
+                e.setAttribute('aria-colspan', String(node.cell.colSpan));
+            if (node.cell.rowSpan > 1)
+                e.setAttribute('aria-rowspan', String(node.cell.rowSpan));
+        }
+        if (marks.includes('misspelling'))
+            e.setAttribute('aria-invalid', 'spelling');
+        if (node.author && (marks.includes('insertion') || marks.includes('deletion')))
+            e.setAttribute('aria-description', `by ${node.author}`);
+        if (node.lang)
+            e.lang = node.lang;
+        if (node.details !== undefined)
+            e.setAttribute('aria-details', this.#elementId(node.details));
+        // Focusable, as a screen reader's activation (browse mode Enter) focuses the element before it clicks.
+        if (!unfocused.has(node.role))
+            e.tabIndex = -1;
+        if (node.label)
+            e.append(Object.assign(document.createElement('span'), { textContent: `${node.label} ` }));
+        if (node.text)
+            e.append(node.text);
+        for (const child of node.children)
+            e.append(this.#build(child));
+        // A row's index: its cells'.
+        if (node.role === 'row') {
+            const row = node.children.find((c) => c.cell)?.cell?.row;
+            if (row !== undefined)
+                e.setAttribute('aria-rowindex', String(row));
+        }
+        this.#byId.set(node.id, e);
+        return e;
+    }
+    #forget(e) {
+        for (const x of [e, ...e.querySelectorAll('[data-twip-id]')]) {
+            const id = Number(x.dataset.twipId);
+            if (this.#byId.get(id) === x)
+                this.#byId.delete(id);
+        }
+    }
+    update(update) {
+        if ('full' in update) {
+            this.#byId.clear();
+            this.root.replaceChildren(this.#build(update.full));
+            return;
+        }
+        // Replaced nodes not in the tree yet wait for the `children` change that places them.
+        const detached = new Map();
+        for (const change of update.patch) {
+            if (change.type === 'replace') {
+                const old = this.#byId.get(change.node.id);
+                if (old)
+                    this.#forget(old);
+                const e = this.#build(change.node);
+                if (old)
+                    old.replaceWith(e);
+                else
+                    detached.set(change.node.id, e);
+                continue;
+            }
+            const parent = this.#byId.get(change.parent);
+            if (!parent)
+                continue;
+            const wanted = change.ids.map((id) => detached.get(id) ?? this.#byId.get(id)).filter((e) => !!e);
+            const keep = new Set(wanted);
+            for (const child of [...parent.children]) {
+                if (!keep.has(child)) {
+                    this.#forget(child);
+                    child.remove();
+                }
+            }
+            // Only elements out of place move: the others stay where the screen reader may be reading.
+            wanted.forEach((e, i) => {
+                if (parent.children[i] !== e)
+                    parent.insertBefore(e, parent.children[i] ?? null);
+            });
+        }
+    }
 }
-export function startA11y(s, dom, ledger) {
+/** How long an announcement waits after emptying the live region. */
+const LIVE_MS = 50;
+/** How long after the focus comes into the editing element an announcement waits: past the focus's own speech. */
+const AFTER_FOCUS_MS = 600;
+/** How long after a mirror node's activation a press on the editor is the activation's own mouse click. */
+const ACTIVATION_MS = 500;
+/** Mirrors the tree and speaks announcements. `label` is the editor's accessible name; `focus` focuses the editing element. */
+export function startA11y(s, dom, ledger, label, focus, report) {
     const tree = ledger.node(dom.layer, document.createElement('div'));
     tree.dataset.twip = 'a11y';
     tree.style.cssText = hidden;
@@ -45,18 +159,42 @@ export function startA11y(s, dom, ledger) {
     live.setAttribute('aria-live', 'polite');
     live.setAttribute('role', 'status');
     live.style.cssText = hidden;
+    const mirror = new Mirror(tree, label);
     const onMessage = (m) => {
         const r = m.payload;
         if (m.kind === Kind.HostRequest && r.type === 'a11y')
-            tree.replaceChildren(build(r.tree));
+            mirror.update(r.update);
     };
     s.hostListeners.add(onMessage);
     s.disposers.push(() => s.hostListeners.delete(onMessage));
-    // A repeated announcement is read again: the region empties first.
+    // Activating a node starts editing there. A screen reader's activation focuses the node, then clicks it, or clicks
+    // with the mouse where it is: that lands on the canvas, and is the activation's, not a click to place the caret.
+    let activated = -Infinity;
+    const activate = (e) => {
+        // Regions and the document hold no caret position: the nearest node inside one that does.
+        const at = e.target?.closest('[data-twip-id][tabindex]');
+        if (!at || s.destroyed)
+            return;
+        e.preventDefault();
+        activated = performance.now();
+        s.call(Method.AccessibleGo, Number(at.dataset.twipId)).then(focus, report);
+    };
+    ledger.listen(tree, 'click', activate);
+    ledger.listen(tree, 'focusin', activate);
+    // A repeated announcement is read again: the region empties first. One made as the focus comes into the editing
+    // element waits for the screen reader to start saying the focus (NVDA does about 150 ms later, and cancels what it
+    // was saying): it is then said after it, not cut off by it ("Editing sub-template Violation" from a button).
     let cancel;
+    let focusedAt = -Infinity;
+    ledger.listen(dom.layer, 'focusin', (e) => {
+        if (e.target.matches('[data-twip="input"]'))
+            focusedAt = performance.now();
+    });
     s.disposers.push(s.on('announcement', ({ text }) => {
         live.textContent = '';
         cancel?.();
-        cancel = ledger.timeout(() => (live.textContent = text), 50);
+        const wait = Math.max(LIVE_MS, focusedAt + AFTER_FOCUS_MS - performance.now());
+        cancel = ledger.timeout(() => (live.textContent = text), wait);
     }));
+    return { activating: () => performance.now() - activated < ACTIVATION_MS };
 }

package/dist/host/clipboard.d.ts

@@ -7,7 +7,7 @@ export interface Clipboard {
         as?: 'formatted' | 'text';
     }): Promise<void>;
 }
-export declare function startClipboard(s: Session, dom: Dom, input: HTMLTextAreaElement, ledger: Ledger, report: (e: unknown) => void, toViewport: (e: {
+export declare function startClipboard(s: Session, dom: Dom, input: HTMLElement, ledger: Ledger, report: (e: unknown) => void, toViewport: (e: {
     clientX: number;
     clientY: number;
 }) => {

package/dist/host/clipboard.js

@@ -1,5 +1,6 @@
 import { EditorError } from '../errors.js';
 import { Kind, Method } from '../transport/protocol.js';
+import { codeOf } from './keys.js';
 /** The last copy on the page: the system clipboard has no place for its token, so a paste brings it back (the engine
  * pastes the copy it names only while the text is still that copy's). */
 let lastCopy;
@@ -71,7 +72,7 @@ export function startClipboard(s, dom, input, ledger, report, toViewport) {
     // Ctrl+Shift+V pastes as text.
     let plain = false;
     ledger.listen(input, 'keydown', (e) => {
-        plain = (e.ctrlKey || e.metaKey) && e.shiftKey && e.code === 'KeyV';
+        plain = (e.ctrlKey || e.metaKey) && e.shiftKey && codeOf(e) === 'KeyV';
     });
     ledger.listen(input, 'paste', (e) => {
         e.preventDefault();

package/dist/host/dom.js

@@ -113,6 +113,8 @@ export function createDom(container, ledger) {
     // extent, in both directions.
     const scroller = element('div', 'editor', 'position:relative;width:100%;height:100%;overflow:auto;display:grid;outline:none;');
     const canvas = element('canvas', 'canvas', 'grid-area:1/1;position:sticky;left:0;top:0;align-self:start;justify-self:start;display:block;touch-action:none;');
+    // The pixels say nothing to assistive technology: the editing element and the accessibility DOM do.
+    canvas.setAttribute('aria-hidden', 'true');
     const content = element('div', 'content', 'grid-area:1/1;position:relative;pointer-events:none;');
     const layer = element('div', 'layer', 'position:absolute;inset:0;overflow:hidden;');
     content.append(layer);

package/dist/host/ime.d.ts

@@ -1,3 +1,3 @@
 import type { Session } from '../editor.js';
 import type { Ledger } from './dom.js';
-export declare function startIme(s: Session, input: HTMLTextAreaElement, ledger: Ledger, report: (e: unknown) => void): void;
+export declare function startIme(s: Session, input: HTMLElement, ledger: Ledger, report: (e: unknown) => void): void;

package/dist/host/ime.js

@@ -3,9 +3,6 @@ export function startIme(s, input, ledger, report) {
     const compose = (phase, text) => s.input({ type: 'composition', phase, text }).catch(report);
     ledger.listen(input, 'compositionstart', () => compose(Phase.start, ''));
     ledger.listen(input, 'compositionupdate', (e) => compose(Phase.update, e.data));
-    ledger.listen(input, 'compositionend', (e) => {
-        compose(Phase.end, e.data);
-        // The element only ever holds the composition.
-        input.value = '';
-    });
+    // The editing element puts its text back after the composition (host/input.ts).
+    ledger.listen(input, 'compositionend', (e) => compose(Phase.end, e.data));
 }

package/dist/host/input.d.ts

@@ -1,12 +1,15 @@
 import type { Session } from '../editor.js';
 import type { Dom, Ledger } from './dom.js';
+/** What the editing element tells screen readers about leaving it. */
+export declare const LEAVE_HINT = "Press F6, or Escape then Tab, to leave the editor";
 /** The input element of a mounted editor. */
 export interface Input {
-    readonly element: HTMLTextAreaElement;
+    readonly element: HTMLElement;
     focus(): void;
 }
 /**
  * Starts keyboard and text input. `claims` says whether a chord is a command's, an application shortcut or a host
  * key (`shortcuts.lookup`): those keys are the editor's, and their browser defaults (Save, Print, Find) don't run.
+ * `label` is the editor's accessible name.
  */
-export declare function startInput(s: Session, dom: Dom, ledger: Ledger, report: (e: unknown) => void, claims: (chord: string) => boolean): Input;
+export declare function startInput(s: Session, dom: Dom, ledger: Ledger, report: (e: unknown) => void, claims: (chord: string) => boolean, label: string): Input;