staffa 0.18.3 → 0.19.0

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/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);

package/dist/core.d.ts

@@ -62,6 +62,11 @@ export declare function uniqueId(prefix?: string): string;
  * `rich` markup (`*italic*`, `**bold**`, `` `code` ``, `[link](/path)`).
  */
 export declare function drawSlot<Args extends unknown[] = []>(slot: Slot<Args> | undefined, ...args: Args): void;
+/**
+ * The focusable elements inside `container`, in tab order — disabled,
+ * `aria-disabled`, `tabindex=-1` and hidden ones left out.
+ */
+export declare function focusables(container: HTMLElement): HTMLElement[];
 /**
  * Move keyboard focus to the first focusable element inside `container`, skipping
  * disabled, `aria-disabled`, `tabindex=-1` and hidden ones. A `prefer` selector,

package/dist/core.js

@@ -26,6 +26,19 @@ export function drawSlot(slot, ...args) {
 }
 /** Selector matching the natively focusable elements we care about. */
 const FOCUSABLE_SELECTOR = "a[href], button, input, select, textarea, [tabindex]";
+/** Whether this element can actually take focus right now. */
+const isFocusable = (el) => el instanceof HTMLElement &&
+    !el.hasAttribute("disabled") &&
+    el.getAttribute("aria-disabled") !== "true" &&
+    el.tabIndex >= 0 &&
+    el.getClientRects().length > 0;
+/**
+ * The focusable elements inside `container`, in tab order — disabled,
+ * `aria-disabled`, `tabindex=-1` and hidden ones left out.
+ */
+export function focusables(container) {
+    return [...container.querySelectorAll(FOCUSABLE_SELECTOR)].filter(isFocusable);
+}
 /**
  * Move keyboard focus to the first focusable element inside `container`, skipping
  * disabled, `aria-disabled`, `tabindex=-1` and hidden ones. A `prefer` selector,
@@ -36,13 +49,8 @@ const FOCUSABLE_SELECTOR = "a[href], button, input, select, textarea, [tabindex]
  * the DOM and laid out — typically inside a `requestAnimationFrame`.
  */
 export function focusFirst(container, prefer) {
-    const ok = (el) => el instanceof HTMLElement &&
-        !el.hasAttribute("disabled") &&
-        el.getAttribute("aria-disabled") !== "true" &&
-        el.tabIndex >= 0 &&
-        el.getClientRects().length > 0;
-    const target = (prefer ? [...container.querySelectorAll(prefer)].find(ok) : undefined) ??
-        [...container.querySelectorAll(FOCUSABLE_SELECTOR)].find(ok);
+    const target = (prefer ? [...container.querySelectorAll(prefer)].find(isFocusable) : undefined) ??
+        focusables(container)[0];
     target?.focus();
     return target != null;
 }