staffa 0.18.3 → 0.18.4

package/src/components/button.ts

@@ -9,14 +9,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. */
@@ -35,8 +49,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"`. */
@@ -55,6 +79,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"`,
@@ -79,15 +113,19 @@ 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",
@@ -108,10 +146,28 @@ A.insertGlobalCss({
 		"&: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)" },
 });
 
 /**
@@ -135,10 +191,15 @@ A.insertGlobalCss({
  */
 export function iconButton(opts: IconButtonOptions): void {
 	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);
 	});
 }
@@ -152,41 +213,86 @@ export function iconButton(opts: IconButtonOptions): void {
 function applyActionBehavior(o: {
 	href?: string;
 	disabled?: boolean;
-	click?: (event: Event) => void;
+	click?: (event: Event) => unknown;
 	type?: string;
-}): void {
+}, hasTooltip = false): void {
 	if (o.href != null) {
 		A("role=button");
 		if (o.disabled) A("aria-disabled=true");
 		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) => { 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);
+	if (o.click && !o.disabled) applyClick(o.click);
 }
 
 /**
- * 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.
+ * 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: (event: Event) => unknown): void {
+	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: 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) as PromiseLike<unknown> | undefined;
+		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 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: string, label: string | undefined, content: Slot | undefined, disabled?: boolean): void {
-	const el = A() as HTMLElement;
-	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: Slot | undefined, key: string | undefined, label: string | undefined, disabled?: boolean): void {
+	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() as HTMLElement;
 		A("aria-keyshortcuts=", formatKey(key, true));
-		bindKey(key, typeof content === "string" ? content : label, () => el.click());
+		bindKey(key, label, () => el.click());
 	}
 }
 
@@ -198,16 +304,18 @@ function applyKey(key: string, label: string | undefined, content: Slot | undefi
  * 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" }
@@ -218,15 +326,18 @@ export function button(opts: ButtonOptions | Slot = {}): void {
 	const o: ButtonOptions = 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/src/components/dialog.ts

@@ -1,5 +1,5 @@
 import A from "aberdeen";
-import { type Slot, type Attributes, drawSlot, mountPortal, focusFirst } from "../core.js";
+import { type Slot, type Attributes, drawSlot, mountPortal, focusFirst, focusables } from "../core.js";
 import { button } from "./button.js";
 import { buttonGroup } from "./buttonGroup.js";
 import { textline } from "./textline.js";
@@ -113,11 +113,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) A.clean(claimKeyboard());
+			// (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() as HTMLElement;
+				A.clean(claimKeyboard());
+				A("aria-modal=true");
+				A("keydown=", (event: KeyboardEvent) => 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 —
@@ -131,7 +143,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));
 				}
 			});
 
@@ -152,6 +170,22 @@ mountPortal(() => {
 	});
 })
 
+/**
+ * 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: HTMLElement, event: KeyboardEvent): void {
+	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/src/components/form.ts

@@ -7,8 +7,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
@@ -53,22 +57,37 @@ A.insertGlobalCss({
 export function form(opts: FormOptions | Slot = {}): void {
 	const o: FormOptions = 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: SubmitEvent) => {
 			event.preventDefault();
-			if (o.submit) {
+			if (o.submit && !$busy.value) {
 				const fd = new FormData(event.target as HTMLFormElement);
 				const data: Record<string, string | string[]> = {};
 				for (const key of new Set(fd.keys())) {
 					const vals = fd.getAll(key) as string[];
 					data[key] = vals.length === 1 ? vals[0]! : vals;
 				}
-				o.submit(data, event);
+				const result = o.submit(data, event) as PromiseLike<unknown> | undefined;
+				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; });
+				}
 			}
 		});
 

package/src/core.ts

@@ -80,6 +80,22 @@ export function drawSlot<Args extends unknown[] = []>(slot: Slot<Args> | undefin
 /** 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: Element): el is HTMLElement =>
+	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: HTMLElement): HTMLElement[] {
+	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,
@@ -90,15 +106,9 @@ const FOCUSABLE_SELECTOR = "a[href], button, input, select, textarea, [tabindex]
  * the DOM and laid out — typically inside a `requestAnimationFrame`.
  */
 export function focusFirst(container: HTMLElement, prefer?: string): boolean {
-	const ok = (el: Element): el is HTMLElement =>
-		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);
+		(prefer ? [...container.querySelectorAll(prefer)].find(isFocusable) : undefined) ??
+		focusables(container)[0];
 	target?.focus();
 	return target != null;
 }