@rathkit/rte-headless 0.0.0-stage → 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,4 @@
+Rathkit RTE
+Copyright 2026 Steven Rathbauer
+
+Licensed under the Apache License, Version 2.0. See LICENSE.

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+# @rathkit/rte-headless
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Alpha** (0.1.0-alpha.0). Not for production: the APIs will change between releases. Published to the `next` tag only.
+
+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 @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
+```
+
+## 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,6 +1,72 @@
 {
   "name": "@rathkit/rte-headless",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.0",
+  "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": {
+    "type": "git",
+    "url": "git+https://github.com/rathkit/rte.git",
+    "directory": "packages/rte-headless"
+  },
+  "bugs": {
+    "url": "https://github.com/rathkit/rte/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "publishConfig": {
+    "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.0 <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
+      }
+    ]
+  }
+}