@rathkit/rte-headless 0.0.0 → 0.1.0-alpha.3

package/README.md

@@ -1,11 +1,45 @@
 # @rathkit/rte-headless
 
-This version is an empty placeholder. It holds no code.
+> **Alpha** (0.1.0-alpha.0). Not for production: the APIs will change between releases. Published to the `next` tag only.
 
-@rathkit/rte-headless is in alpha. Install the alpha with the `next` tag:
+How a toolbar, menu, dialog, tooltip and live announcement should behave for the keyboard and assistive technology, with no markup or CSS of its own. Draw the elements yourself and this makes them behave (roving focus, ARIA state, focus returned to the editor); also external stores for any framework.
+
+## Install
 
 ```sh
-npm install @rathkit/rte-headless@next
+npm install @rathkit/rte-headless@next @rathkit/rte-core@next
+```
+
+This package has no dependencies of its own. It works with `@rathkit/rte-core` (peer dependencies, all optional so that npm installs nothing you did not ask for), so install the ones you use alongside it.
+
+## Example
+
+```js
+import { createEditor } from "@rathkit/rte-core/standard";
+import { createToolbar } from "@rathkit/rte-headless";
+
+const surface = document.createElement("div");
+surface.setAttribute("aria-label", "Body");
+document.body.append(surface);
+const editor = createEditor({ element: surface, html: "<p>Hello</p>" });
+
+// Draw the controls yourself and mark each with data-rk-item="<id>"; the toolbar makes them behave.
+const bar = document.createElement("div");
+const toolbar = createToolbar(editor, { label: "Formatting" });
+for (const item of toolbar.items.filter((i) => i.kind === "button" || i.kind === "toggle")) {
+  const button = document.createElement("button");
+  button.setAttribute("data-rk-item", item.id);
+  button.textContent = toolbar.state(item.id).label;
+  bar.append(button);
+}
+document.body.prepend(bar);
+toolbar.bind(bar);                            // roving focus, aria-pressed, focus kept in the editor
 ```
 
-About the project: https://rathkit.com
+## More
+
+Documentation: <https://rathkit.com>. Source and issues: <https://github.com/rathkit/rte>. What is checked: [SUPPORT.md](https://github.com/rathkit/rte/blob/main/docs/SUPPORT.md). Changes: [CHANGELOG.md](https://github.com/rathkit/rte/blob/main/CHANGELOG.md). How a release is verified: [VERIFY.md](https://github.com/rathkit/rte/blob/main/docs/VERIFY.md).
+
+## License
+
+[Apache-2.0](LICENSE)

package/dist/announcer.d.ts

@@ -0,0 +1,9 @@
+import type { Unsubscribe } from "./types.ts";
+export interface Announcer {
+    /** Says a message to assistive technology. The same message twice in a row is said twice. */
+    announce(message: string): void;
+    /** The element, so a host can place it. It is visually hidden, but not removed from the accessibility tree. */
+    readonly element: HTMLElement;
+    destroy: Unsubscribe;
+}
+export declare function createAnnouncer(parent?: HTMLElement): Announcer;

package/dist/announcer.js

@@ -0,0 +1,23 @@
+export function createAnnouncer(parent = document.body) {
+    const element = document.createElement("div");
+    element.setAttribute("role", "status");
+    element.setAttribute("aria-live", "polite");
+    element.setAttribute("aria-atomic", "true");
+    element.style.cssText = "position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);clip-path:inset(50%);white-space:nowrap;border:0";
+    parent.appendChild(element);
+    let timer;
+    return {
+        element,
+        announce(message) {
+            element.textContent = "";
+            if (timer)
+                clearTimeout(timer);
+            timer = setTimeout(() => { element.textContent = message; }, 50);
+        },
+        destroy() {
+            if (timer)
+                clearTimeout(timer);
+            element.remove();
+        },
+    };
+}

package/dist/dialog.d.ts

@@ -0,0 +1,33 @@
+import type { Field } from "@rathkit/rte-core";
+import type { Unsubscribe } from "./types.ts";
+export interface DialogOptions {
+    readonly dialog: HTMLElement;
+    /** What opened it; focus returns here. If it is gone, focus goes to the editor. */
+    readonly opener?: HTMLElement | null;
+    readonly editor?: {
+        focus(): void;
+    };
+    readonly onClose?: (result: "submit" | "cancel") => void;
+    /** Called with a developer-facing warning, such as a dialog with no name. Default: the console. */
+    readonly warn?: (message: string) => void;
+}
+export interface Dialog {
+    readonly isOpen: boolean;
+    open(): void;
+    close(result?: "submit" | "cancel"): void;
+    destroy: Unsubscribe;
+}
+export declare function createDialog(options: DialogOptions): Dialog;
+export interface FormCheck {
+    readonly ok: boolean;
+    readonly values: Record<string, string | boolean>;
+}
+/**
+ * Checks a dialog's form against the fields an item asked for. Each field that is missing or wrong gets `aria-invalid` and is tied to
+ * its message by `aria-describedby`; put an element marked `data-rk-error="<field name>"` where the message should appear. The first
+ * bad field takes the focus, and the messages are announced when an announcer is given.
+ */
+export declare function checkFields(form: HTMLElement, fields: readonly Field[], messages?: {
+    readonly required?: string;
+    readonly url?: string;
+}, announce?: (message: string) => void): FormCheck;

package/dist/dialog.js

@@ -0,0 +1,130 @@
+import { uniqueId } from "./disclosure.js";
+const FOCUSABLE = 'a[href],button:not([disabled]),input:not([disabled]):not([type=hidden]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])';
+export function createDialog(options) {
+    const { dialog } = options;
+    const warn = options.warn ?? ((m) => console.warn(`[rte] ${m}`));
+    const native = typeof HTMLDialogElement !== "undefined" && dialog instanceof HTMLDialogElement && typeof dialog.showModal === "function";
+    if (!dialog.hasAttribute("aria-labelledby") && !dialog.hasAttribute("aria-label"))
+        warn("A dialog needs a name: give it aria-labelledby or aria-label.");
+    dialog.setAttribute("role", "dialog");
+    dialog.setAttribute("aria-modal", "true");
+    let isOpen = false;
+    let result = "cancel";
+    const focusable = () => [...dialog.querySelectorAll(FOCUSABLE)].filter((e) => !e.hidden && e.getAttribute("aria-hidden") !== "true");
+    const returnFocus = () => {
+        const opener = options.opener;
+        if (opener && opener.isConnected)
+            opener.focus();
+        else
+            options.editor?.focus();
+    };
+    const finish = () => {
+        if (!isOpen)
+            return;
+        isOpen = false;
+        dialog.setAttribute("data-state", "closed");
+        returnFocus();
+        options.onClose?.(result);
+    };
+    const onKeyDown = (e) => {
+        if (e.key === "Escape") {
+            e.preventDefault();
+            close("cancel");
+        }
+        else if (e.key === "Tab" && !native) {
+            const list = focusable();
+            if (list.length === 0)
+                return;
+            const first = list[0];
+            const last = list[list.length - 1];
+            if (e.shiftKey && document.activeElement === first) {
+                e.preventDefault();
+                last.focus();
+            }
+            else if (!e.shiftKey && document.activeElement === last) {
+                e.preventDefault();
+                first.focus();
+            }
+        }
+    };
+    const onCancel = (e) => { e.preventDefault(); close("cancel"); };
+    dialog.addEventListener("keydown", onKeyDown);
+    if (native)
+        dialog.addEventListener("cancel", onCancel);
+    function close(how = "cancel") {
+        if (!isOpen)
+            return;
+        result = how;
+        if (native)
+            dialog.close();
+        else
+            dialog.hidden = true;
+        finish();
+    }
+    function open() {
+        if (isOpen)
+            return;
+        isOpen = true;
+        result = "cancel";
+        dialog.setAttribute("data-state", "open");
+        if (native)
+            dialog.showModal();
+        else
+            dialog.hidden = false;
+        const target = dialog.querySelector("[autofocus]") ?? focusable()[0] ?? dialog;
+        if (target === dialog && !dialog.hasAttribute("tabindex"))
+            dialog.tabIndex = -1;
+        target.focus();
+    }
+    return {
+        get isOpen() { return isOpen; },
+        open, close,
+        destroy() {
+            dialog.removeEventListener("keydown", onKeyDown);
+            dialog.removeEventListener("cancel", onCancel);
+        },
+    };
+}
+export function checkFields(form, fields, messages = {}, announce) {
+    const values = {};
+    const problems = [];
+    let firstBad;
+    for (const field of fields) {
+        const input = form.querySelector(`[name="${field.name}"]`);
+        if (!input)
+            continue;
+        if (field.type === "checkbox") {
+            values[field.name] = input.checked;
+            continue;
+        }
+        const value = input.value.trim();
+        values[field.name] = value;
+        let problem = "";
+        if (field.required && value === "")
+            problem = messages.required ?? `${field.label} is required.`;
+        else if (value !== "" && field.type === "url" && /^\s*(javascript|vbscript|data):/i.test(value))
+            problem = messages.url ?? `${field.label} must be a web, mail or phone address.`;
+        const slot = form.querySelector(`[data-rk-error="${field.name}"]`);
+        if (slot)
+            slot.textContent = problem;
+        if (problem) {
+            input.setAttribute("aria-invalid", "true");
+            if (slot) {
+                if (!slot.id)
+                    slot.id = uniqueId("rk-error");
+                input.setAttribute("aria-describedby", slot.id);
+            }
+            problems.push(problem);
+            firstBad ??= input;
+        }
+        else {
+            input.removeAttribute("aria-invalid");
+            input.removeAttribute("aria-describedby");
+        }
+    }
+    if (firstBad) {
+        firstBad.focus();
+        announce?.(problems.join(" "));
+    }
+    return { ok: problems.length === 0, values };
+}

package/dist/disclosure.d.ts

@@ -0,0 +1,18 @@
+import type { Unsubscribe } from "./types.ts";
+export interface DisclosureOptions {
+    readonly trigger: HTMLElement;
+    readonly popup: HTMLElement;
+    /** What the trigger opens, for `aria-haspopup`. Default `true` (a generic popup). */
+    readonly kind?: "menu" | "dialog" | "listbox" | "true";
+    readonly onToggle?: (open: boolean) => void;
+}
+export interface Disclosure {
+    readonly isOpen: boolean;
+    open(): void;
+    /** Closes it. By default the focus goes back to the trigger; pass false when the person has already moved on (a click elsewhere). */
+    close(returnFocus?: boolean): void;
+    toggle(): void;
+    destroy: Unsubscribe;
+}
+export declare const uniqueId: (prefix: string) => string;
+export declare function createDisclosure(options: DisclosureOptions): Disclosure;

package/dist/disclosure.js

@@ -0,0 +1,64 @@
+let counter = 0;
+export const uniqueId = (prefix) => `${prefix}-${++counter}`;
+export function createDisclosure(options) {
+    const { trigger, popup } = options;
+    if (!popup.id)
+        popup.id = uniqueId("rk-popup");
+    trigger.setAttribute("aria-haspopup", options.kind ?? "true");
+    trigger.setAttribute("aria-controls", popup.id);
+    let isOpen = false;
+    const apply = (open) => {
+        isOpen = open;
+        trigger.setAttribute("aria-expanded", String(open));
+        trigger.setAttribute("data-state", open ? "open" : "closed");
+        popup.setAttribute("data-state", open ? "open" : "closed");
+        popup.hidden = !open;
+        options.onToggle?.(open);
+    };
+    apply(false);
+    const close = (returnFocus = true) => {
+        if (!isOpen)
+            return;
+        apply(false);
+        if (returnFocus)
+            trigger.focus();
+    };
+    const open = () => {
+        if (!isOpen)
+            apply(true);
+    };
+    const onPointerDown = (e) => {
+        const target = e.target;
+        if (isOpen && target && !popup.contains(target) && !trigger.contains(target))
+            close(false);
+    };
+    const onFocusOut = (e) => {
+        const next = e.relatedTarget;
+        if (isOpen && next && !popup.contains(next) && !trigger.contains(next))
+            close(false);
+    };
+    const onKeyDown = (e) => {
+        if (isOpen && e.key === "Escape") {
+            e.preventDefault();
+            e.stopPropagation();
+            close(true);
+        }
+    };
+    const onClick = () => (isOpen ? close(true) : open());
+    document.addEventListener("pointerdown", onPointerDown, true);
+    popup.addEventListener("focusout", onFocusOut);
+    trigger.addEventListener("keydown", onKeyDown);
+    popup.addEventListener("keydown", onKeyDown);
+    trigger.addEventListener("click", onClick);
+    return {
+        get isOpen() { return isOpen; },
+        open, close, toggle: () => (isOpen ? close(true) : open()),
+        destroy() {
+            document.removeEventListener("pointerdown", onPointerDown, true);
+            popup.removeEventListener("focusout", onFocusOut);
+            trigger.removeEventListener("keydown", onKeyDown);
+            popup.removeEventListener("keydown", onKeyDown);
+            trigger.removeEventListener("click", onClick);
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { createToolbar, type BindOptions, type ItemState, type Toolbar, type ToolbarOptions } from "./toolbar.ts";
+export { createAnnouncer, type Announcer } from "./announcer.ts";
+export { createDisclosure, type Disclosure, type DisclosureOptions } from "./disclosure.ts";
+export { createMenu, type Menu, type MenuOptions } from "./menu.ts";
+export { checkFields, createDialog, type Dialog, type DialogOptions, type FormCheck } from "./dialog.ts";
+export { commandStore, selectStore, snapshotStore, toReadable, type ExternalStore, type Readable } from "./stores.ts";
+export type { HeadlessEditor, Unsubscribe } from "./types.ts";
+export { createTooltip, type Tooltip, type TooltipOptions } from "./tooltip.ts";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { createToolbar } from "./toolbar.js";
+export { createAnnouncer } from "./announcer.js";
+export { createDisclosure } from "./disclosure.js";
+export { createMenu } from "./menu.js";
+export { checkFields, createDialog } from "./dialog.js";
+export { commandStore, selectStore, snapshotStore, toReadable } from "./stores.js";
+export { createTooltip } from "./tooltip.js";

package/dist/menu.d.ts

@@ -0,0 +1,14 @@
+import { type Disclosure } from "./disclosure.ts";
+import type { Unsubscribe } from "./types.ts";
+export interface MenuOptions {
+    readonly trigger: HTMLElement;
+    readonly menu: HTMLElement;
+    /** Called with the item that was chosen. The menu closes and the focus returns to the trigger afterwards. */
+    readonly onSelect: (item: HTMLElement) => void;
+    /** Called when the menu has just opened and is showing, so it can be put where it fits on the screen. */
+    readonly onOpen?: () => void;
+}
+export interface Menu extends Pick<Disclosure, "isOpen" | "open" | "close" | "toggle"> {
+    destroy: Unsubscribe;
+}
+export declare function createMenu(options: MenuOptions): Menu;

package/dist/menu.js

@@ -0,0 +1,104 @@
+import { createDisclosure, uniqueId } from "./disclosure.js";
+export function createMenu(options) {
+    const { trigger, menu } = options;
+    if (!trigger.id)
+        trigger.id = uniqueId("rk-menu-button");
+    menu.setAttribute("role", "menu");
+    menu.setAttribute("aria-labelledby", trigger.id);
+    const items = () => [...menu.querySelectorAll("[data-rk-menuitem]")];
+    let typed = "";
+    let typedTimer;
+    const disclosure = createDisclosure({
+        trigger, popup: menu, kind: "menu",
+        onToggle: (open) => { if (open) {
+            options.onOpen?.();
+            queueMicrotask(() => focusAt(0));
+        } },
+    });
+    const sync = () => items().forEach((item) => { item.setAttribute("role", "menuitem"); item.tabIndex = -1; });
+    sync();
+    function focusAt(index) {
+        const list = items();
+        if (list.length === 0)
+            return;
+        const i = (index + list.length) % list.length;
+        list.forEach((item, at) => { item.tabIndex = at === i ? 0 : -1; });
+        list[i]?.focus();
+    }
+    const current = () => items().indexOf(document.activeElement);
+    const choose = (item) => {
+        if (item.getAttribute("aria-disabled") === "true")
+            return;
+        disclosure.close(true);
+        options.onSelect(item);
+    };
+    const onMenuKey = (e) => {
+        const list = items();
+        const at = current();
+        switch (e.key) {
+            case "ArrowDown":
+                focusAt(at + 1);
+                break;
+            case "ArrowUp":
+                focusAt(at <= 0 ? list.length - 1 : at - 1);
+                break;
+            case "Home":
+                focusAt(0);
+                break;
+            case "End":
+                focusAt(list.length - 1);
+                break;
+            case "Enter":
+            case " ": {
+                const item = list[at];
+                if (item)
+                    choose(item);
+                break;
+            }
+            case "Tab":
+                disclosure.close(false);
+                return;
+            default: {
+                if (e.key.length !== 1 || e.ctrlKey || e.metaKey || e.altKey)
+                    return;
+                typed += e.key.toLowerCase();
+                if (typedTimer)
+                    clearTimeout(typedTimer);
+                typedTimer = setTimeout(() => { typed = ""; }, 500);
+                const names = list.map((item) => (item.textContent ?? item.getAttribute("aria-label") ?? "").trim().toLowerCase());
+                const start = typed.length === 1 ? at + 1 : at;
+                const hit = [...names.keys()].map((k) => (k + start + names.length) % names.length).find((k) => names[k]?.startsWith(typed));
+                if (hit !== undefined)
+                    focusAt(hit);
+            }
+        }
+        e.preventDefault();
+    };
+    const onTriggerKey = (e) => {
+        if (e.key === "ArrowDown" || e.key === "ArrowUp") {
+            e.preventDefault();
+            disclosure.open();
+            queueMicrotask(() => focusAt(e.key === "ArrowDown" ? 0 : items().length - 1));
+        }
+    };
+    const onClick = (e) => {
+        const item = e.target?.closest("[data-rk-menuitem]");
+        if (item && menu.contains(item))
+            choose(item);
+    };
+    menu.addEventListener("keydown", onMenuKey);
+    menu.addEventListener("click", onClick);
+    trigger.addEventListener("keydown", onTriggerKey);
+    return {
+        get isOpen() { return disclosure.isOpen; },
+        open: disclosure.open, close: disclosure.close, toggle: disclosure.toggle,
+        destroy() {
+            if (typedTimer)
+                clearTimeout(typedTimer);
+            menu.removeEventListener("keydown", onMenuKey);
+            menu.removeEventListener("click", onClick);
+            trigger.removeEventListener("keydown", onTriggerKey);
+            disclosure.destroy();
+        },
+    };
+}

package/dist/stores.d.ts

@@ -0,0 +1,20 @@
+import type { CommandState, EditorSnapshot } from "@rathkit/rte-core";
+import type { HeadlessEditor, Unsubscribe } from "./types.ts";
+export interface ExternalStore<T> {
+    subscribe(onChange: () => void): Unsubscribe;
+    getSnapshot(): T;
+}
+/** A command's state: enabled, active, value. The same object until it changes. */
+export declare function commandStore(editor: HeadlessEditor, command: string): ExternalStore<CommandState>;
+/** The whole editor state. A new object after every change to the document, selection, focus or read-only state. */
+export declare function snapshotStore(editor: HeadlessEditor): ExternalStore<EditorSnapshot>;
+/**
+ * One value worked out from the state, such as the document's word count. Only changes in that value wake the subscriber. The snapshot is
+ * remembered per editor state, so asking twice between changes costs nothing and returns the same value.
+ */
+export declare function selectStore<T>(editor: HeadlessEditor, selector: (snapshot: EditorSnapshot) => T, equals?: (a: T, b: T) => boolean): ExternalStore<T>;
+/** The Svelte store contract: `subscribe(run)` calls `run` at once with the value, again on each change, and returns how to stop. */
+export interface Readable<T> {
+    subscribe(run: (value: T) => void): Unsubscribe;
+}
+export declare function toReadable<T>(store: ExternalStore<T>): Readable<T>;

package/dist/stores.js

@@ -0,0 +1,44 @@
+export function commandStore(editor, command) {
+    return {
+        subscribe: (onChange) => editor.commands.subscribe(command, onChange),
+        getSnapshot: () => editor.commands.state(command),
+    };
+}
+export function snapshotStore(editor) {
+    return {
+        subscribe: (onChange) => editor.subscribe(() => onChange()),
+        getSnapshot: () => editor.snapshot,
+    };
+}
+export function selectStore(editor, selector, equals = Object.is) {
+    let version = -1;
+    let value;
+    return {
+        subscribe: (onChange) => editor.select(selector, () => onChange(), equals),
+        getSnapshot() {
+            const snap = editor.snapshot;
+            if (snap.version === version)
+                return value;
+            const next = selector(snap);
+            if (version === -1 || !equals(value, next))
+                value = next;
+            version = snap.version;
+            return value;
+        },
+    };
+}
+export function toReadable(store) {
+    return {
+        subscribe(run) {
+            run(store.getSnapshot());
+            let last = store.getSnapshot();
+            return store.subscribe(() => {
+                const next = store.getSnapshot();
+                if (!Object.is(next, last)) {
+                    last = next;
+                    run(next);
+                }
+            });
+        },
+    };
+}

package/dist/toolbar.d.ts

@@ -0,0 +1,44 @@
+import type { UiItem } from "@rathkit/rte-core";
+import type { HeadlessEditor, Unsubscribe } from "./types.ts";
+export interface ItemState {
+    readonly id: string;
+    readonly kind: UiItem["kind"];
+    /** Always set: the item's own label, else the command's, else the item's id. A control without a name is a bug. */
+    readonly label: string;
+    readonly icon: string | undefined;
+    /** Not available right now. The control stays focusable (`aria-disabled`), so people can find it. */
+    readonly disabled: boolean;
+    /** For toggles: on or off. Undefined for other kinds. */
+    readonly pressed: boolean | undefined;
+    /** For selects: the current value. */
+    readonly value: unknown;
+    /** The key that runs it, written for `aria-keyshortcuts`, if it has one. */
+    readonly shortcut: string | undefined;
+    /** The same key written for people ("Ctrl+B"), for a tooltip. */
+    readonly shortcutLabel: string | undefined;
+}
+export interface ToolbarOptions {
+    /** The place to read items from. Default: the main toolbar. */
+    readonly slot?: string;
+    /** Names the toolbar for assistive technology. Required in practice: a toolbar without a name is announced as just "toolbar". */
+    readonly label?: string;
+    readonly orientation?: "horizontal" | "vertical";
+}
+export interface BindOptions {
+    /** Called for items that open something rather than run a command (a dialog, a menu, a panel), with the control that was pressed. */
+    readonly onOpen?: (item: UiItem, control: HTMLElement) => void;
+}
+export interface Toolbar {
+    /** The items now, in display order: the top level, with the items of a menu inside it. The same array until the items change. */
+    readonly items: readonly UiItem[];
+    /** The state of one item. The same object until that item's state changes, so a framework can compare by identity. */
+    state(id: string): ItemState | undefined;
+    /** Runs the item's command: a button or toggle with its own argument; a select with the chosen value. False if it did nothing. */
+    activate(id: string, value?: unknown): boolean;
+    /** Called, once per turn, when the items or the state of any of them change. */
+    subscribe(callback: () => void): Unsubscribe;
+    /** Makes the elements a person's own interface drew behave. Mark each with `data-rk-item="<id>"`. */
+    bind(root: HTMLElement, options?: BindOptions): Unsubscribe;
+    destroy(): void;
+}
+export declare function createToolbar(editor: HeadlessEditor, options?: ToolbarOptions): Toolbar;

package/dist/toolbar.js

@@ -0,0 +1,208 @@
+const commandOf = (item) => ("command" in item ? item.command : undefined);
+export function createToolbar(editor, options = {}) {
+    const slot = options.slot ?? "toolbar.main";
+    const labels = new Map(editor.commands.list().map((c) => [c.name, c.label]));
+    const listeners = new Set();
+    const cache = new Map();
+    let items = editor.ui.items(slot);
+    const flatten = (list) => list.flatMap((i) => (i.kind === "menu" ? [i, ...flatten(i.items)] : [i]));
+    let everything = flatten(items);
+    let watching = [];
+    let scheduled = false;
+    let destroyed = false;
+    const notify = () => {
+        if (scheduled || destroyed)
+            return;
+        scheduled = true;
+        queueMicrotask(() => {
+            scheduled = false;
+            if (!destroyed)
+                for (const callback of [...listeners])
+                    callback();
+        });
+    };
+    const watch = () => {
+        for (const stop of watching)
+            stop();
+        watching = [];
+        const seen = new Set();
+        for (const item of everything) {
+            const command = commandOf(item);
+            if (command && !seen.has(command)) {
+                seen.add(command);
+                watching.push(editor.commands.subscribe(command, notify));
+            }
+        }
+    };
+    watch();
+    const stopItems = editor.ui.subscribe(slot, () => {
+        items = editor.ui.items(slot);
+        everything = flatten(items);
+        watch();
+        notify();
+    });
+    const find = (id) => everything.find((i) => i.id === id);
+    function state(id) {
+        const item = find(id);
+        if (!item)
+            return undefined;
+        const command = commandOf(item);
+        const source = command ? editor.commands.state(command) : undefined;
+        const label = ("label" in item && item.label) || (command && labels.get(command)) || item.id;
+        const shortcut = command ? editor.keymap.ariaShortcut(command) : undefined;
+        const hit = cache.get(id);
+        if (hit && hit.source === source && hit.label === label && hit.shortcut === shortcut)
+            return hit.state;
+        const arg = "arg" in item ? item.arg : undefined;
+        const pressed = item.kind === "toggle" && source ? (arg !== undefined && source.value !== undefined ? Object.is(source.value, arg) : source.active) : undefined;
+        const next = {
+            id, kind: item.kind, label, icon: "icon" in item ? item.icon : undefined,
+            disabled: source ? !source.enabled : false,
+            pressed, value: item.kind === "select" ? source?.value : undefined,
+            shortcut, shortcutLabel: command ? editor.keymap.shortcutFor(command) : undefined,
+        };
+        cache.set(id, { state: next, source, label, shortcut });
+        return next;
+    }
+    function activate(id, value) {
+        const item = find(id);
+        const command = item ? commandOf(item) : undefined;
+        if (!item || !command)
+            return false;
+        const arg = item.kind === "select" ? value : item.kind === "button" || item.kind === "toggle" ? item.arg : value;
+        const ran = editor.commands.run(command, arg);
+        return ran;
+    }
+    function bind(root, bindOptions = {}) {
+        root.setAttribute("role", "toolbar");
+        root.setAttribute("aria-orientation", options.orientation ?? "horizontal");
+        if (options.label)
+            root.setAttribute("aria-label", options.label);
+        const controls = () => [...root.querySelectorAll("[data-rk-item]")];
+        let current = 0;
+        const sync = () => {
+            const all = controls();
+            all.forEach((control, index) => {
+                const s = state(control.getAttribute("data-rk-item") ?? "");
+                if (!s)
+                    return;
+                control.setAttribute("aria-disabled", String(s.disabled));
+                if (s.pressed !== undefined)
+                    control.setAttribute("aria-pressed", String(s.pressed));
+                if (s.shortcut)
+                    control.setAttribute("aria-keyshortcuts", s.shortcut);
+                else
+                    control.removeAttribute("aria-keyshortcuts");
+                if (!control.hasAttribute("aria-label") && !(control.textContent ?? "").trim())
+                    control.setAttribute("aria-label", s.label);
+                if (control.tagName === "SELECT" && s.value !== undefined)
+                    control.value = String(s.value);
+                control.tabIndex = index === current ? 0 : -1;
+            });
+        };
+        sync();
+        const stop = (() => { listeners.add(sync); return () => listeners.delete(sync); })();
+        const focusAt = (index) => {
+            const all = controls();
+            if (all.length === 0)
+                return;
+            current = (index + all.length) % all.length;
+            all.forEach((c, i) => { c.tabIndex = i === current ? 0 : -1; });
+            all[current]?.focus();
+        };
+        const control = (target) => (target instanceof Element ? target.closest("[data-rk-item]") : null);
+        const press = (el) => {
+            const id = el.getAttribute("data-rk-item") ?? "";
+            const item = find(id);
+            if (!item || el.getAttribute("aria-disabled") === "true")
+                return;
+            if (item.kind === "dialog" || item.kind === "menu" || item.kind === "panel") {
+                bindOptions.onOpen?.(item, el);
+                return;
+            }
+            if (activate(id))
+                editor.focus();
+        };
+        const onMouseDown = (e) => {
+            const el = control(e.target);
+            if (el && el.tagName !== "SELECT" && el.tagName !== "INPUT")
+                e.preventDefault();
+        };
+        const onClick = (e) => {
+            const el = control(e.target);
+            if (el && el.tagName !== "SELECT")
+                press(el);
+        };
+        const onChange = (e) => {
+            const el = control(e.target);
+            if (!el || el.tagName !== "SELECT")
+                return;
+            const item = find(el.getAttribute("data-rk-item") ?? "");
+            if (item?.kind !== "select")
+                return;
+            const chosen = item.options.find((o) => String(o.value) === el.value);
+            if (chosen && activate(item.id, chosen.value))
+                editor.focus();
+        };
+        const onFocusIn = (e) => {
+            const el = control(e.target);
+            if (el)
+                current = controls().indexOf(el);
+            sync();
+        };
+        const onKeyDown = (e) => {
+            const el = control(e.target);
+            if (!el)
+                return;
+            const vertical = (options.orientation ?? "horizontal") === "vertical";
+            const index = controls().indexOf(el);
+            const next = vertical ? "ArrowDown" : "ArrowRight";
+            const prev = vertical ? "ArrowUp" : "ArrowLeft";
+            if (e.key === next)
+                focusAt(index + 1);
+            else if (e.key === prev)
+                focusAt(index - 1);
+            else if (e.key === "Home")
+                focusAt(0);
+            else if (e.key === "End")
+                focusAt(controls().length - 1);
+            else if (e.key === "Escape")
+                editor.focus();
+            else if ((e.key === "Enter" || e.key === " ") && el.tagName !== "BUTTON" && el.tagName !== "SELECT")
+                press(el);
+            else
+                return;
+            e.preventDefault();
+        };
+        root.addEventListener("mousedown", onMouseDown);
+        root.addEventListener("click", onClick);
+        root.addEventListener("change", onChange);
+        root.addEventListener("focusin", onFocusIn);
+        root.addEventListener("keydown", onKeyDown);
+        return () => {
+            stop();
+            root.removeEventListener("mousedown", onMouseDown);
+            root.removeEventListener("click", onClick);
+            root.removeEventListener("change", onChange);
+            root.removeEventListener("focusin", onFocusIn);
+            root.removeEventListener("keydown", onKeyDown);
+        };
+    }
+    return {
+        get items() { return items; },
+        state, activate,
+        subscribe(callback) {
+            listeners.add(callback);
+            return () => listeners.delete(callback);
+        },
+        bind,
+        destroy() {
+            destroyed = true;
+            stopItems();
+            for (const stop of watching)
+                stop();
+            watching = [];
+            listeners.clear();
+        },
+    };
+}

package/dist/tooltip.d.ts

@@ -0,0 +1,20 @@
+import type { Unsubscribe } from "./types.ts";
+export interface TooltipOptions {
+    /** Events are listened for here, so controls added later work without more setup. */
+    readonly container: HTMLElement;
+    /** The tooltip's element. It is hidden and shown, and its text is set; the caller puts it in the page. */
+    readonly popup: HTMLElement;
+    /** Milliseconds the pointer must rest on a control before the tip shows. Default 500. Keyboard focus shows it at once. */
+    readonly delay?: number;
+    /** Milliseconds the tip stays when the pointer leaves, so it can be moved onto the tip. Default 150. */
+    readonly grace?: number;
+    /** Called with the control and the shown popup, to position it. */
+    readonly onShow?: (target: HTMLElement, popup: HTMLElement) => void;
+}
+export interface Tooltip {
+    /** The control whose tip is showing. */
+    readonly shown: HTMLElement | undefined;
+    hide(): void;
+    destroy: Unsubscribe;
+}
+export declare function createTooltip(options: TooltipOptions): Tooltip;

package/dist/tooltip.js

@@ -0,0 +1,125 @@
+import { uniqueId } from "./disclosure.js";
+const TIP = "[data-rk-tip]";
+export function createTooltip(options) {
+    const { container, popup } = options;
+    const delay = options.delay ?? 500;
+    const grace = options.grace ?? 150;
+    if (!popup.id)
+        popup.id = uniqueId("rk-tooltip");
+    popup.setAttribute("role", "tooltip");
+    popup.hidden = true;
+    let shown;
+    let showTimer;
+    let hideTimer;
+    const clear = () => {
+        if (showTimer)
+            clearTimeout(showTimer);
+        if (hideTimer)
+            clearTimeout(hideTimer);
+        showTimer = hideTimer = undefined;
+    };
+    const hide = () => {
+        clear();
+        shown = undefined;
+        popup.hidden = true;
+    };
+    const show = (target) => {
+        clear();
+        const text = target.getAttribute("data-rk-tip");
+        if (!text)
+            return;
+        shown = target;
+        popup.textContent = text;
+        popup.hidden = false;
+        options.onShow?.(target, popup);
+    };
+    const tipOf = (node) => (node instanceof Element ? node.closest(TIP) : null);
+    const later = () => {
+        if (hideTimer)
+            clearTimeout(hideTimer);
+        hideTimer = setTimeout(hide, grace);
+    };
+    const onOver = (e) => {
+        if (typeof matchMedia === "function" && matchMedia("(hover: none)").matches)
+            return;
+        const target = tipOf(e.target);
+        if (!target || target === shown) {
+            if (target && hideTimer) {
+                clearTimeout(hideTimer);
+                hideTimer = undefined;
+            }
+            return;
+        }
+        clear();
+        showTimer = setTimeout(() => show(target), shown ? 0 : delay);
+    };
+    const onOut = (e) => {
+        const from = tipOf(e.target);
+        if (!from)
+            return;
+        const to = e.relatedTarget;
+        if (to && (from.contains(to) || popup.contains(to)))
+            return;
+        if (showTimer) {
+            clearTimeout(showTimer);
+            showTimer = undefined;
+        }
+        if (shown)
+            later();
+    };
+    const onFocusIn = (e) => {
+        const target = tipOf(e.target);
+        if (!target)
+            return;
+        let visible = true;
+        try {
+            visible = target.matches(":focus-visible");
+        }
+        catch { }
+        if (visible)
+            show(target);
+    };
+    const onFocusOut = (e) => {
+        if (tipOf(e.target) && e.relatedTarget !== popup)
+            hide();
+    };
+    const onPress = () => hide();
+    const onKey = (e) => {
+        if (shown && e.key === "Escape") {
+            e.stopPropagation();
+            e.preventDefault();
+            hide();
+        }
+    };
+    const onPopupEnter = () => { if (hideTimer) {
+        clearTimeout(hideTimer);
+        hideTimer = undefined;
+    } };
+    const onPopupLeave = (e) => { if (!(e.relatedTarget instanceof Node && shown?.contains(e.relatedTarget)))
+        later(); };
+    container.addEventListener("mouseover", onOver);
+    container.addEventListener("mouseout", onOut);
+    container.addEventListener("focusin", onFocusIn);
+    container.addEventListener("focusout", onFocusOut);
+    container.addEventListener("pointerdown", onPress);
+    const page = container.ownerDocument;
+    page.addEventListener("keydown", onKey, true);
+    popup.addEventListener("mouseenter", onPopupEnter);
+    popup.addEventListener("mouseleave", onPopupLeave);
+    return {
+        get shown() { return shown; },
+        hide,
+        destroy() {
+            clear();
+            popup.hidden = true;
+            container.removeEventListener("mouseover", onOver);
+            container.removeEventListener("mouseout", onOut);
+            container.removeEventListener("focusin", onFocusIn);
+            container.removeEventListener("focusout", onFocusOut);
+            container.removeEventListener("pointerdown", onPress);
+            page.removeEventListener("keydown", onKey, true);
+            popup.removeEventListener("mouseenter", onPopupEnter);
+            popup.removeEventListener("mouseleave", onPopupLeave);
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,16 @@
+import type { Engine } from "@rathkit/rte-core";
+/**
+ * What the interaction rules need of an editor. The browser `Editor` fits as it is. A bare engine fits too, once it is given
+ * somewhere to send the keyboard focus.
+ */
+export interface HeadlessEditor {
+    readonly commands: Engine["commands"];
+    readonly keymap: Engine["keymap"];
+    readonly ui: Engine["ui"];
+    readonly snapshot: Engine["snapshot"];
+    readonly subscribe: Engine["subscribe"];
+    readonly select: Engine["select"];
+    /** Puts the keyboard focus back in the editing surface. */
+    focus(): void;
+}
+export type Unsubscribe = () => void;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,18 @@
 {
   "name": "@rathkit/rte-headless",
-  "version": "0.0.0",
-  "description": "Placeholder. @rathkit/rte-headless is in alpha: install it with the next tag.",
+  "version": "0.1.0-alpha.3",
+  "description": "How a toolbar, menu, dialog or announcement should behave for keyboard and assistive technology, with no markup or CSS of its own.",
+  "keywords": [
+    "rich-text",
+    "editor",
+    "wysiwyg",
+    "contenteditable",
+    "zero-dependencies",
+    "typescript",
+    "accessibility",
+    "headless",
+    "aria"
+  ],
   "license": "Apache-2.0",
   "homepage": "https://rathkit.com",
   "repository": {
@@ -12,7 +23,50 @@
   "bugs": {
     "url": "https://github.com/rathkit/rte/issues"
   },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.14.0"
+  },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true,
+    "tag": "next"
+  },
+  "files": [
+    "dist",
+    "NOTICE",
+    "!dist/**/*.map"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@rathkit/rte-core": ">=0.1.0-alpha.3 <0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@rathkit/rte-core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@rathkit/rte-core": "workspace:*"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && tsc -p tsconfig.build.js.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test \"src/**/*.test.ts\""
+  },
+  "rathkit": {
+    "budgets": [
+      {
+        "name": "headless",
+        "entry": "dist/index.js",
+        "gzipKB": 12
+      }
+    ]
   }
 }