staffa 0.18.2 → 0.18.4

package/README.md

@@ -220,6 +220,17 @@ Return the paths shallowest first, or nothing to fall back to the parent-path wa
 - Aberdeen's own `route.go()` works, but builds the whole stack from the path; prefer the stack's methods. A guard your app registered with `route.setGuard` keeps working — Staffa registers none of its own.
 - Deep links need your static server to serve the app for unknown paths (the usual SPA fallback; `-P` for `http-server`, as in the demo command below).
 
+### Waiting
+
+A `click` handler — or a form's `submit` — that returns a promise puts its button to work until that promise settles: a spinner rides after the label, and clicks (and Enter) bounce off, so a slow save can't be started twice. There is nothing to wire up:
+
+```ts
+S.button({ content: "Save", click: () => api.save($user) });
+S.form({ submit: (data) => api.save(data), content: drawFields, actions: () => S.button({ content: "Save", type: "submit" }) });
+```
+
+A form marks its own submit buttons, wherever they sit, and a handler that awaits a `confirm()` waits with it. For a wait that isn't a promise, put a control in the same state yourself with `attrs: ".s-busy"`.
+
 ## Components
 
 Every option of every component is documented in TSDoc on its `…Options` interface. Options share naming conventions: `attrs` (outermost element), `contentAttrs` (the children-holding element), `inputAttrs` (the form control) and `<region>Attrs` (`headerAttrs`, `footerAttrs`, …) — all Aberdeen attr/style strings, applied last so they can override. Form components consistently support `label`, `help`, `error`, `disabled`, `required` and `name`, and two-way binding through `bind: A.ref($obj, "key")`.
@@ -229,6 +240,15 @@ Every option of every component is documented in TSDoc on its `…Options` inter
 - **Actions**: `button`, `iconButton`, `buttonGroup`, `buttonChooser`.
 - **Overlays & feedback**: `dialog` (+ `alert`, `confirm`, `prompt`), `menu`, `menuButton`, `showFloatingMenu`, `addContextMenu`, `toast`, `addTooltip`.
 
+Buttons, icon buttons and menu items carry a `tooltip` option of their own, so most tips need no `addTooltip` call:
+
+```ts
+S.button({ content: "Publish", tooltip: "Not until the draft validates", disabled: true });
+S.iconButton({ icon: trash2, ariaLabel: "Delete" });   // says "Delete" on hover
+```
+
+An icon button tips its `ariaLabel` unless given a `tooltip` of its own (`tooltip: false` for neither), a `key` is appended to whatever the tip says, and — unlike a tooltip on a plain disabled `<button>`, which the browser gives no hover events — these show while disabled, which is where a tooltip earns its keep.
+
 `src/index.ts` is the authoritative list of exports.
 
 ### Keyboard shortcuts

package/dist/components/autocomplete.d.ts

@@ -31,6 +31,10 @@ export interface AutocompleteOptions extends FieldOptions {
  * optional free-text entry, and full keyboard control (arrows, enter, escape,
  * backspace-to-remove). Implements the ARIA combobox/listbox pattern.
  *
+ * The suggestion list is portalled to `document.body`, so a dialog or a
+ * scrolling column can neither clip it nor grow a scrollbar around it. It hangs
+ * off whichever side of the field has the room, and follows it as things move.
+ *
  * @example
  * ```ts
  * // Single select from a fixed list

package/dist/components/autocomplete.js

@@ -1,9 +1,8 @@
 import A from "aberdeen";
-import { uniqueId } from "../core.js";
+import { followAnchor, mountPortal, uniqueId } from "../core.js";
 import { drawField } from "./field.js";
 A.insertGlobalCss({
     ".s-ac": {
-        "&": "position:relative",
         // Same light inset field as `.s-input` (see field.ts), derived from the surface.
         "> .s-control": "display:flex flex-wrap:wrap align-items:center gap:$1 background: color-mix(in oklab, $s-bg, $s-text 4%); color:$s-text border: 1px solid $s-faint; r:$s-radius padding: 0.3em 0.4em; cursor:text; transition: border-color 0.15s, box-shadow 0.15s;",
         "> .s-control:hover": "border-color: color-mix(in oklab, $s-text, $s-bg 55%);",
@@ -13,16 +12,56 @@ A.insertGlobalCss({
         ".s-chip > button": "cursor:pointer border:0 background:transparent fg:$s-muted font-size:1.1em line-height:1 padding: 0 0.2em; r:4px",
         ".s-chip > button:hover": "fg:$s-text background:$s-faint",
         "input": "flex:1 min-width:6ch border:0 background:transparent color:inherit outline:none padding:0.25em",
-        // Background, border, radius and elevation come from the popup's
-        // `.s-s.neutral.shadow` surface (see below).
-        "> .s-menu": "position:absolute top:100% left:0 right:0 z-index:20 margin-top:4px max-height:15rem overflow-y:auto list-style:none p:$1 margin-bottom:0",
-        "> .s-menu li": "margin:0",
+    },
+    // Background, border, radius and elevation come from the `.s-s.neutral.shadow`
+    // surface it carries; `place()` below sizes and positions it. Both of its
+    // classes are named here: standing in `<body>` rather than inside the field,
+    // it would otherwise lose to theme.ts's flow margins on `ul` and `li`.
+    ".s-ac-menu.s-s": {
+        "&": "position:fixed max-height:15rem overflow-y:auto list-style:none p:$1 margin:0",
+        li: "margin:0",
         ".s-option": "padding: 0.45em 0.6em; r:6px cursor:pointer transition: background 0.1s;",
         ".s-option[aria-selected=true]": "background: color-mix(in srgb, $s-text 10%, transparent);",
         ".s-add": "fg:$s-accent font-style:italic",
         ".s-empty": "padding: 0.45em 0.6em; fg:$s-muted",
     },
 });
+// Only one list is up at a time — it belongs to whichever field has focus — so
+// one portal at the end of <body> serves them all. Drawn inside the field, the
+// list would be clipped by a dialog or a scrolling column, and would stretch
+// that scroller's bar to reach it.
+const $popup = A.proxy({ cur: null });
+/** Hang the list under the field — or over it, when that's where the room is. */
+function place(el, r) {
+    const gap = 4, edge = 8;
+    // Measured at the stylesheet's own cap, so the flip is decided on the height
+    // the list wants, not on whatever the last placement clamped it to.
+    el.style.maxHeight = "";
+    const want = el.offsetHeight;
+    const below = window.innerHeight - r.bottom - gap - edge;
+    const above = r.top - gap - edge;
+    const up = want > below && above > below;
+    el.style.left = `${r.left}px`;
+    el.style.width = `${r.width}px`;
+    el.style.maxHeight = `${Math.min(want, Math.max(up ? above : below, 60))}px`;
+    el.style.top = up ? "auto" : `${r.bottom + gap}px`;
+    el.style.bottom = up ? `${window.innerHeight - r.top + gap}px` : "auto";
+}
+mountPortal(() => {
+    const p = $popup.cur;
+    if (!p)
+        return;
+    let sizeChanged;
+    const el = A("ul.s-ac-menu.s-s.neutral.shadow role=listbox", `id=${p.id} z-index:${p.zIndex}`, () => {
+        // A press in the list must not blur the field: the click that follows is
+        // what commits, and dragging the scrollbar has to keep it open too.
+        A("mousedown=", (e) => e.preventDefault());
+        p.draw();
+        // Re-run as you type, with the rows; the list's height changes with them.
+        sizeChanged?.();
+    });
+    sizeChanged = followAnchor(p.anchor, (r) => place(el, r));
+});
 function normOption(o) {
     return typeof o === "string" ? { value: o, label: o } : { value: o.value, label: o.label ?? o.value };
 }
@@ -31,6 +70,10 @@ function normOption(o) {
  * optional free-text entry, and full keyboard control (arrows, enter, escape,
  * backspace-to-remove). Implements the ARIA combobox/listbox pattern.
  *
+ * The suggestion list is portalled to `document.body`, so a dialog or a
+ * scrolling column can neither clip it nor grow a scrollbar around it. It hangs
+ * off whichever side of the field has the room, and follows it as things move.
+ *
  * @example
  * ```ts
  * // Single select from a fixed list
@@ -103,11 +146,36 @@ export function autocomplete(opts) {
         const arr = opts.bind.value ?? [];
         opts.bind.value = arr.filter((v) => v !== value);
     };
+    let inputEl;
+    /** The list's rows. Runs in the body portal, on this field's state. */
+    const drawList = () => {
+        const list = filtered();
+        const q = $st.query.trim();
+        const showAdd = opts.allowCustom !== false && q !== "" && !list.some((o) => o.label.toLowerCase() === q.toLowerCase());
+        list.forEach((option, i) => {
+            A("li.s-option role=option", `id=${menuId}-opt-${i}`, () => {
+                A(() => A("aria-selected=", $st.active === i ? "true" : "false"));
+                A("#", option.label);
+                A("click=", () => commit(option.value, inputEl));
+                A("mousemove=", () => {
+                    $st.active = i;
+                });
+            });
+        });
+        if (showAdd) {
+            A("li.s-option.s-add role=option", () => {
+                A("#", `Add "${q}"`);
+                A("click=", () => commit(q, inputEl));
+            });
+        }
+        if (list.length === 0 && !showAdd) {
+            A("li.s-empty #No matches");
+        }
+    };
     drawField(opts, (id, isInvalid) => {
         A("div.s-ac", opts.inputAttrs, () => {
             A(() => A("aria-invalid=", isInvalid() ? "true" : "false"));
-            let inputEl;
-            A("div.s-control", () => {
+            const controlEl = A("div.s-control", () => {
                 A("click=", () => inputEl?.focus());
                 // Chips for multi-select.
                 A(() => {
@@ -156,36 +224,16 @@ export function autocomplete(opts) {
                     A("keydown=", (e) => onKey(e, inputEl));
                 });
             });
-            // The suggestions popup.
+            // Hand the list to the portal for as long as it is up. Its layer clears
+            // the dialog the field sits in, but stays under one that may open over
+            // it — a field on the page can't paint across a modal.
             A(() => {
                 if (!$st.open)
                     return;
-                const list = filtered();
-                const q = $st.query.trim();
-                const showAdd = opts.allowCustom !== false && q !== "" && !list.some((o) => o.label.toLowerCase() === q.toLowerCase());
-                A("ul.s-menu.s-s.neutral.shadow role=listbox", `id=${menuId}`, () => {
-                    list.forEach((option, i) => {
-                        A("li.s-option role=option", `id=${menuId}-opt-${i}`, () => {
-                            A(() => A("aria-selected=", $st.active === i ? "true" : "false"));
-                            A("#", option.label);
-                            A("mousedown=", (e) => e.preventDefault());
-                            A("click=", () => commit(option.value, inputEl));
-                            A("mousemove=", () => {
-                                $st.active = i;
-                            });
-                        });
-                    });
-                    if (showAdd) {
-                        A("li.s-option.s-add role=option", () => {
-                            A("#", `Add "${q}"`);
-                            A("mousedown=", (e) => e.preventDefault());
-                            A("click=", () => commit(q, inputEl));
-                        });
-                    }
-                    if (list.length === 0 && !showAdd) {
-                        A("li.s-empty #No matches");
-                    }
-                });
+                const zIndex = controlEl.closest(".s-dialog") ? 350 : 150;
+                $popup.cur = { id: menuId, anchor: controlEl, zIndex, draw: drawList };
+                A.clean(() => { if ($popup.cur?.id === menuId)
+                    $popup.cur = null; });
             });
             // Hidden inputs so the selection participates in native FormData.
             A(() => {

package/dist/components/button.d.ts

@@ -5,14 +5,28 @@ export interface IconButtonOptions {
     icon: Slot;
     /** What it does, for screen readers. Required: there is no visible text to read. */
     ariaLabel: string;
-    /** Click handler. */
-    click?: (event: Event) => void;
+    /**
+     * Click handler. Return a promise and the glyph becomes a spinner until it
+     * settles, with further clicks bouncing off — see {@link ButtonOptions.click}.
+     */
+    click?: (event: Event) => unknown;
     /**
      * A keyboard shortcut that presses this button — see {@link ButtonOptions.key}.
-     * The tooltip shows it after the `ariaLabel` (a glyph is worth naming there
-     * anyway), and the `?` overview lists it under that label too.
+     * The tooltip shows it after the button's `tooltip` (or, failing that, its
+     * `ariaLabel` — a glyph is worth naming there anyway), and the `?` overview
+     * lists it under that label too.
      */
     key?: string;
+    /**
+     * A tooltip, shown on hover and keyboard focus; a string renders as rich
+     * text. Defaults to the `ariaLabel`, so an icon button says what it does
+     * without being told twice — pass this only to say something longer or
+     * different, or `false` for no tooltip at all. A `key` is appended to it.
+     *
+     * Works on a disabled button too, which is where a tooltip earns its keep:
+     * it is the only room there is to say why.
+     */
+    tooltip?: Slot | false;
     /** Render as a link (`<a role=button>`) pointing here instead of a `<button>`. */
     href?: string;
     /** Disables it. */
@@ -30,8 +44,18 @@ export interface ButtonOptions {
     content?: Slot;
     /** Leading icon/adornment, drawn before the label. */
     icon?: Slot;
-    /** Click handler. */
-    click?: (event: Event) => void;
+    /**
+     * Click handler.
+     *
+     * **Return a promise and the button goes *busy* until it settles**: a spinner
+     * rides after the label, and clicks (and keypresses) bounce off, so a slow
+     * save can't be started twice. Nothing to wire up — `click: () => save()` on
+     * an async `save` is the whole thing, and a handler awaiting a
+     * {@link confirm} counts: the button waits for the answer with everything
+     * else. For a wait that isn't a promise, put the button in the same state
+     * yourself with `attrs: ".s-busy"`.
+     */
+    click?: (event: Event) => unknown;
     /** Disables the button. */
     disabled?: boolean;
     /** Native button behaviour. Defaults to `"button"`. */
@@ -50,6 +74,16 @@ export interface ButtonOptions {
      * its `ariaLabel`).
      */
     key?: string;
+    /**
+     * A tooltip, shown on hover and keyboard focus. A string renders as rich
+     * text, a function draws its own markup. A `key` is appended to it, behind
+     * a `·`. Defaults to the `ariaLabel` of a button that has one (an icon-only
+     * button, that is); pass `false` for no tooltip at all.
+     *
+     * Works on a disabled button too, which is where a tooltip earns its keep:
+     * it is the only room there is to say why.
+     */
+    tooltip?: Slot | false;
     /**
      * Aberdeen attr/style string applied to the button. A button is a surface, so
      * pass surface modifier classes here to restyle it, e.g. `".danger"`,
@@ -90,16 +124,18 @@ export declare function iconButton(opts: IconButtonOptions): void;
  * content.
  *
  * **Tip:** pair `href` with Aberdeen's `interceptLinks()` (called once at app
- * startup) for SPA-style navigation without manual click handlers:
+ * startup) for SPA-style navigation without manual click handlers — a routed
+ * {@link main} already handles link clicks itself, so don't call it there:
  * ```ts
- * import {interceptLinks} from from "aberdeen/route";
+ * import {interceptLinks} from "aberdeen/route";
  * interceptLinks(); // once at root
  * S.button({ href: "/dashboard", content: "Dashboard" }); // navigates via router
  * ```
  *
  * @example
  * ```ts
- * S.button({ content: "Save", click: S.alert("Saved.") });
+ * S.button({ content: "Save", click: () => save() });     // async: spins while it saves
+ * S.button({ content: "About", click: () => S.alert("Staffa.") });
  * S.button({ content: "Cancel", attrs: ".neutral", click: cancel }); // neutral button
  * S.button({ content: "Delete", attrs: ".danger .outlined", click: del });
  * S.button("Cancel");                        // shorthand for { content: "Cancel" }

package/dist/components/button.js

@@ -12,15 +12,18 @@ A.insertGlobalCss({
             "transition: background 0.15s, border-color 0.15s, color 0.15s, filter 0.15s, box-shadow 0.15s, transform 0.08s;",
         // Focus ring via `outline`, not box-shadow: `.no-shadow` hard-clears box-shadow.
         "&:focus-visible": "outline: 3px solid $s-focus; outline-offset: 1px;",
-        "&:hover": "filter: brightness(1.06)",
-        "&.tonal:hover, &.outlined:hover": "background: color-mix(in srgb, $s-bg 24%, transparent);",
+        "&:hover:not([aria-disabled=true])": "filter: brightness(1.06)",
+        "&.tonal:hover:not([aria-disabled=true]), &.outlined:hover:not([aria-disabled=true])": "background: color-mix(in srgb, $s-bg 24%, transparent);",
         // A `.neutral` button is already near-white, so it darkens toward its ink
         // instead of brightening.
-        "&.neutral:hover": "filter:none background: color-mix(in srgb, $s-text 8%, $s-bg);",
+        "&.neutral:hover:not([aria-disabled=true])": "filter:none background: color-mix(in srgb, $s-text 8%, $s-bg);",
         // The button sizes its glyph rather than trusting the caller: only a rule here
         // makes every icon in a row match. In `em`, so `.small`/`.large` scale it.
         "> svg": "width:1.25em height:1.25em",
-        "&:active:not(:disabled)": "transform: translateY(1px)",
+        "&:active:not(:disabled):not([aria-disabled=true])": "transform: translateY(1px)",
+        // A disabled button that has something to say still takes hover, so its
+        // tooltip can say it (see `applyActionBehavior`); theme.ts stops the rest.
+        "&[aria-disabled=true]": "pointer-events:auto cursor:not-allowed",
         // Also inherited from a `.small`/`.large` parent (e.g. a buttonGroup), so a
         // container can size all its buttons at once.
         "&.small, .small > &": "padding: $m1 $m2; font-size:0.85em border-radius:$s-radius-sm",
@@ -39,10 +42,26 @@ A.insertGlobalCss({
         "> svg": "width:1.25em height:1.25em",
         "&:hover:not(:disabled):not([aria-disabled=true])": "fg:$s-text background: color-mix(in srgb, $s-text 10%, transparent);",
         "&:focus-visible": "outline: 3px solid $s-focus; outline-offset:1px",
+        // A disabled button that has something to say still takes hover, so its
+        // tooltip can say it (see `applyActionBehavior`); theme.ts stops the rest.
+        "&[aria-disabled=true]": "pointer-events:auto cursor:not-allowed",
         // The glyph rides the font size, so it scales with the hit area.
         "&.small, .small > &": "width:1.6rem height:1.6rem font-size:0.8rem",
         "&.large, .large > &": "width:2.4rem height:2.4rem font-size:1.2rem",
     },
+    // ── Busy ──────────────────────────────────────────────────────────────────
+    // Raised by a promise-returning `click`, by a submitting `S.form` on its own
+    // submit buttons, or by a caller who has some other wait to show. The spinner
+    // is a pseudo-element, so nothing has to be redrawn to start or stop it, and
+    // the flex `gap` spaces it like any other child.
+    ".s-btn.s-busy, .s-icon-btn.s-busy, .s-busy .s-btn[type=submit]": "pointer-events:none cursor:progress",
+    ".s-btn.s-busy::after, .s-icon-btn.s-busy::after, .s-busy .s-btn[type=submit]::after": "content:'' flex-shrink:0 width:1em height:1em r:50% " +
+        "border: 2px solid currentColor; border-top-color: transparent; " +
+        "animation: s-spin 0.7s linear infinite;",
+    // The glyph *is* an icon button, so the spinner takes its place rather than
+    // crowding in beside it.
+    ".s-icon-btn.s-busy > svg": "display:none",
+    "@keyframes s-spin": { to: "transform: rotate(360deg)" },
 });
 /**
  * A bare glyph in a square hit area — no fill, no border, just ink that lifts on
@@ -65,11 +84,15 @@ A.insertGlobalCss({
  */
 export function iconButton(opts) {
     const tag = opts.href != null ? "a" : "button";
+    // A glyph says nothing on its own, so the name it carries for screen readers is
+    // the tip too, unless the caller has something better (or `false`) to say.
+    const tip = opts.tooltip === false ? undefined : opts.tooltip ?? opts.ariaLabel;
     A(`${tag}.s-icon-btn`, opts.attrs, () => {
-        applyActionBehavior(opts);
+        applyActionBehavior(opts, tip != null);
         A("aria-label=", opts.ariaLabel);
-        if (opts.key)
-            applyKey(opts.key, opts.ariaLabel, undefined, opts.disabled);
+        // Before the glyph, so a tooltip the caller adds in there is the later of
+        // the two and wins the hover.
+        applyTooltipAndKey(tip, opts.key, opts.ariaLabel, opts.disabled);
         drawSlot(opts.icon);
     });
 }
@@ -79,7 +102,7 @@ export function iconButton(opts) {
  * anchor without one is out of the tab order and follows nothing, which is what
  * makes it as disabled as a `<button>`'s real `disabled` attribute.
  */
-function applyActionBehavior(o) {
+function applyActionBehavior(o, hasTooltip = false) {
     if (o.href != null) {
         A("role=button");
         if (o.disabled)
@@ -87,35 +110,84 @@ function applyActionBehavior(o) {
         else
             A("href=", o.href);
     }
+    else if (o.disabled && hasTooltip) {
+        // A natively `disabled` button fires no mouse events at all, so a tooltip on
+        // one — usually the one saying *why* it is disabled — would never show. Say
+        // it the ARIA way instead: the same dimmed, unclickable, out-of-the-tab-order
+        // button (theme.ts dims it, the CSS above keeps only hover alive), but one
+        // the pointer can still reach. Nothing can activate it: the `click` handler
+        // is skipped below, and this one stops a `type=submit` from reaching its form
+        // through a stray click or Enter.
+        A("type=", o.type ?? "button");
+        A("aria-disabled=true tabindex=-1");
+        A("click=", (event) => { event.preventDefault(); event.stopPropagation(); });
+    }
     else {
         A("type=", o.type ?? "button");
         if (o.disabled)
             A("disabled=true");
     }
     if (o.click && !o.disabled)
-        A("click=", o.click);
+        applyClick(o.click);
+}
+/**
+ * Wire a click handler that may be asynchronous: while the promise it returned
+ * is pending, the element wears `.s-busy` (spinner, no pointer events) and
+ * further clicks are ignored — the double-submit guard every save button needs.
+ *
+ * The rejection is rethrown from a promise nobody handles, so an error in the
+ * handler still reaches the console exactly as it would without us.
+ */
+function applyClick(click) {
+    const $busy = A.proxy({ value: false });
+    // Own scope: raising and dropping the class must not recreate the element,
+    // which would drop keyboard focus mid-click.
+    A(() => {
+        if ($busy.value)
+            A(".s-busy aria-busy=true");
+    });
+    A("click=", (event) => {
+        // A keypress on a focused button still gets here while `pointer-events:none`
+        // holds the mouse off, so the guard is what actually stops the second call.
+        if ($busy.value)
+            return;
+        const result = click(event);
+        if (!result || typeof result.then !== "function")
+            return;
+        $busy.value = true;
+        const done = () => { $busy.value = false; };
+        Promise.resolve(result).then(done, (err) => { done(); throw err; });
+    });
 }
 /**
- * The shortcut plumbing {@link button} and {@link iconButton} share: bind it,
- * announce it as `aria-keyshortcuts`, and hint at it in a tooltip — the only
- * place a button can say what its key is without shouting it beside the label.
+ * The tooltip and shortcut plumbing {@link button} and {@link iconButton} share:
+ * show the tip, with the key appended — the only place a button can say what its
+ * key is without shouting it beside the label — then bind that key and announce
+ * it as `aria-keyshortcuts`.
  *
  * Pressing it clicks the element rather than calling `click` directly, so a
  * `type=submit` still submits its form and an `href` still navigates. Call this
  * inside the button's own element scope, whose element it takes and whose life
  * the binding follows.
  */
-function applyKey(key, label, content, disabled) {
-    const el = A();
-    const tip = label ? `${label} · ${formatKey(key)}` : formatKey(key);
-    // A draw function, not a string: a key like `*` is markup to rich text.
-    addTooltip({ tip: () => A("#", tip) });
+function applyTooltipAndKey(tip, key, label, disabled) {
+    if (tip != null || key) {
+        addTooltip({
+            tip: () => {
+                drawSlot(tip);
+                // A draw function, not a string: a key like `*` is markup to rich text.
+                if (key)
+                    A("#", tip == null ? formatKey(key) : ` · ${formatKey(key)}`);
+            },
+        });
+    }
     // Bound only while it can be pressed — a disabled button would otherwise
     // swallow the combination rather than leave it to whoever else wants it. The
     // overview names it by its visible text, or its aria label failing that.
-    if (!disabled) {
+    if (key && !disabled) {
+        const el = A();
         A("aria-keyshortcuts=", formatKey(key, true));
-        bindKey(key, typeof content === "string" ? content : label, () => el.click());
+        bindKey(key, label, () => el.click());
     }
 }
 /**
@@ -126,16 +198,18 @@ function applyKey(key, label, content, disabled) {
  * content.
  *
  * **Tip:** pair `href` with Aberdeen's `interceptLinks()` (called once at app
- * startup) for SPA-style navigation without manual click handlers:
+ * startup) for SPA-style navigation without manual click handlers — a routed
+ * {@link main} already handles link clicks itself, so don't call it there:
  * ```ts
- * import {interceptLinks} from from "aberdeen/route";
+ * import {interceptLinks} from "aberdeen/route";
  * interceptLinks(); // once at root
  * S.button({ href: "/dashboard", content: "Dashboard" }); // navigates via router
  * ```
  *
  * @example
  * ```ts
- * S.button({ content: "Save", click: S.alert("Saved.") });
+ * S.button({ content: "Save", click: () => save() });     // async: spins while it saves
+ * S.button({ content: "About", click: () => S.alert("Staffa.") });
  * S.button({ content: "Cancel", attrs: ".neutral", click: cancel }); // neutral button
  * S.button({ content: "Delete", attrs: ".danger .outlined", click: del });
  * S.button("Cancel");                        // shorthand for { content: "Cancel" }
@@ -145,16 +219,18 @@ function applyKey(key, label, content, disabled) {
 export function button(opts = {}) {
     const o = typeof opts === "string" || typeof opts === "function" ? { content: opts } : opts;
     const tag = o.href != null ? "a" : "button";
+    // An `ariaLabel` means an icon-only button, whose name is worth showing to the
+    // sighted too; anything else says nothing until asked.
+    const tip = o.tooltip === false ? undefined : o.tooltip ?? o.ariaLabel;
     // A bare `.s-s` is a filled `.primary` surface (see theme.ts), so no role
     // detection here: `attrs` just names another role or variant.
     A(`${tag}.s-btn.s-s.shadow`, o.attrs, () => {
-        applyActionBehavior(o);
+        applyActionBehavior(o, tip != null);
         if (o.ariaLabel)
             A("aria-label=", o.ariaLabel);
         // Before the content, so a tooltip the caller adds in there is the later of
         // the two and wins the hover.
-        if (o.key)
-            applyKey(o.key, o.ariaLabel, o.content, o.disabled);
+        applyTooltipAndKey(tip, o.key, typeof o.content === "string" ? o.content : o.ariaLabel, o.disabled);
         drawSlot(o.icon);
         drawSlot(o.content);
     });

package/dist/components/dialog.js

@@ -1,5 +1,5 @@
 import A from "aberdeen";
-import { drawSlot, mountPortal, focusFirst } from "../core.js";
+import { drawSlot, mountPortal, focusFirst, focusables } from "../core.js";
 import { button } from "./button.js";
 import { buttonGroup } from "./buttonGroup.js";
 import { textline } from "./textline.js";
@@ -58,12 +58,23 @@ mountPortal(() => {
             if (opts.allowCancel !== false)
                 close();
         });
-        const dialogEl = A("div.s-dialog.neutral.s-s.extra-shadow create=hidden destroy=hidden", opts.attrs, () => {
+        // Derived from the dialog's own key rather than a second counter: there is
+        // exactly one of these per dialog, for as long as the dialog exists.
+        const labelId = `s-dialog-title-${dialogId}`;
+        const dialogEl = A("div.s-dialog.neutral.s-s.extra-shadow role=dialog create=hidden destroy=hidden", opts.attrs, () => {
             // A modal owns the keyboard: claiming makes the shortcuts drawn inside
-            // (the content below included) register here and silences the rest. The
-            // `?` overview passes `keyboardTransparent` to leave them all working.
-            if (!opts.keyboardTransparent)
+            // (the content below included) register here and silences the rest;
+            // `aria-modal` takes the page behind out of the screen reader's reading
+            // order, the way the backdrop takes it out of the pointer's reach; and
+            // Tab is held inside, so it can't wander off into what it is covering.
+            // The `?` overview passes `keyboardTransparent`: an overlay that informs
+            // rather than interrupts claims none of this.
+            if (!opts.keyboardTransparent) {
+                const el = A();
                 A.clean(claimKeyboard());
+                A("aria-modal=true");
+                A("keydown=", (event) => trapTab(el, event));
+            }
             // Esc closes the dialog — or, while `allowCancel` forbids it, is
             // swallowed by the no-op press, so nothing below acts on it either.
             // Anchored at whoever owned the keyboard as this dialog opened —
@@ -76,7 +87,13 @@ mountPortal(() => {
             });
             A(() => {
                 if (opts.header != null) {
-                    A("header.s-s.neutral", opts.headerAttrs, () => drawSlot(opts.header));
+                    // The header names the dialog to assistive tech as well as visually:
+                    // it is what a screen reader reads out as focus enters, before the
+                    // control it lands on. Set from this scope (so on the dialog, and
+                    // withdrawn with the header), rather than pointing at an id that
+                    // isn't there.
+                    A("aria-labelledby=", labelId);
+                    A("header.s-s.neutral id=", labelId, opts.headerAttrs, () => drawSlot(opts.header));
                 }
             });
             A("div", opts.contentAttrs, () => {
@@ -94,6 +111,23 @@ mountPortal(() => {
             focusFirst(dialogEl); });
     });
 });
+/**
+ * Keep Tab inside a modal dialog: from its last focusable element Tab wraps
+ * around to the first, and Shift+Tab from the first to the last. Without this,
+ * a couple of Tabs walk out of the dialog and into the page it is covering —
+ * which the backdrop makes invisible but not unreachable, so a keyboard user
+ * ends up typing into something they can't see.
+ */
+function trapTab(dialogEl, event) {
+    if (event.key !== "Tab" || event.altKey || event.ctrlKey || event.metaKey)
+        return;
+    const items = focusables(dialogEl);
+    const edge = event.shiftKey ? items[0] : items[items.length - 1];
+    if (!edge || document.activeElement !== edge)
+        return;
+    event.preventDefault();
+    (event.shiftKey ? items[items.length - 1] : items[0]).focus();
+}
 /**
  * A dialog rendered into `document.body` via `A.mount`, with a dimming backdrop
  * that fades in and out. Returns a `Promise<void>` that resolves when the dialog

package/dist/components/form.d.ts

@@ -5,8 +5,12 @@ export interface FormOptions extends ContentOptions {
      * Submit handler. Called with collected form data (keyed by each field's
      * `name`) and the original event. `preventDefault()` is already called.
      * Multi-value fields (e.g. multi-select) produce a `string[]`.
+     *
+     * **Return a promise and the form goes *busy* until it settles**: its submit
+     * buttons show a spinner and stop responding, and a second submit (Enter
+     * included) is ignored — so a slow save runs once, however impatient the user.
      */
-    submit?: (data: Record<string, string | string[]>, event: SubmitEvent) => void;
+    submit?: (data: Record<string, string | string[]>, event: SubmitEvent) => unknown;
     /**
      * Layout of fields. `"stacked"` (default) is a single column; `"grid"` packs
      * fields into a responsive multi-column grid. A field can span the full grid

package/dist/components/form.js

@@ -30,21 +30,36 @@ A.insertGlobalCss({
  */
 export function form(opts = {}) {
     const o = typeof opts === "string" || typeof opts === "function" ? { content: opts } : opts;
+    // Raised while an asynchronous `submit` is still running; the CSS in button.ts
+    // turns the form's submit buttons into spinners off it.
+    const $busy = A.proxy({ value: false });
     A(`form.s-form`, o.attrs, () => {
         // Own scope, so a layout change doesn't recreate the fields (losing focus/input state).
         A(() => {
             A(".grid=", o.layout === 'grid');
         });
+        // Likewise: going busy must not redraw the fields being submitted.
+        A(() => {
+            if ($busy.value)
+                A(".s-busy aria-busy=true");
+        });
         A("submit=", (event) => {
             event.preventDefault();
-            if (o.submit) {
+            if (o.submit && !$busy.value) {
                 const fd = new FormData(event.target);
                 const data = {};
                 for (const key of new Set(fd.keys())) {
                     const vals = fd.getAll(key);
                     data[key] = vals.length === 1 ? vals[0] : vals;
                 }
-                o.submit(data, event);
+                const result = o.submit(data, event);
+                if (result && typeof result.then === "function") {
+                    $busy.value = true;
+                    const done = () => { $busy.value = false; };
+                    // Rethrown from a promise nobody handles, so the error still
+                    // reaches the console the way an unawaited one would.
+                    Promise.resolve(result).then(done, (err) => { done(); throw err; });
+                }
             }
         });
         drawSlot(o.content);