staffa 0.19.0 → 0.22.0

package/skill/SKILL.md

@@ -249,10 +249,20 @@ Buttons, icon buttons and menu items carry a `tooltip` option of their own, so m
 
 ```ts
 S.button({ content: "Publish", tooltip: "Not until the draft validates", disabled: true });
-S.iconButton({ icon: trash2, ariaLabel: "Delete" });   // says "Delete" on hover
+S.iconButton({ icon: trash2, tooltip: "Delete" });   // says "Delete" on hover, and to screen readers
 ```
 
-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.
+A tooltip appears only where one is asked for; on an icon button, a string `tooltip` doubles as the `ariaLabel` when that is left out, so naming a glyph takes one option rather than two. A `key` is appended to whatever the tip says (`tooltip: false` keeps even that quiet), 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.
+
+`S.textline` and `S.textarea` take a `prefix` and a `suffix` slot that put content *inside* the control — a search glyph, a unit, a clear or send button. The control's text keeps clear of whatever they hold, and on a textarea they ride the bottom edge, which is where a send button belongs:
+
+```ts
+S.textline({ placeholder: "Search…", prefix: search, suffix: () => S.iconButton({ icon: x, tooltip: "Clear" }) });
+S.textarea({ placeholder: "Message…", bind: A.ref($chat, "text"),
+  suffix: () => S.iconButton({ icon: send, tooltip: "Send", click: post }) });
+```
+
+A plain glyph there lets the click through to the field it decorates; a button or a link takes it.
 
 `src/index.ts` is the authoritative list of exports.
 
@@ -408,6 +418,15 @@ A combobox with type-ahead filtering. Supports single or multi-select (chips),
 optional free-text entry, and full keyboard control (arrows, enter, escape,
 backspace-to-remove). Implements the ARIA combobox/listbox pattern.
 
+## [matchWords](matchWords.md) · function
+
+The default type-ahead test: every whitespace-separated term of the query has
+to match the label from a word start on, and no two terms may claim the same
+word. Order doesn't matter, so "se pal" finds "Palette search" just as
+"pal se" does — but "ette" finds nothing, as you type the beginnings of
+words. A term may run past its word's end ("typescript" finds "TypeScript",
+"c++" finds "C++"), so typing a label out in full always finds it.
+
 ## [AutocompleteOptions](AutocompleteOptions.md) · interface
 
 Options for `autocomplete`.
@@ -803,6 +822,13 @@ autocomplete, ...). Every field lays out the same way — optional label,
 control, optional help/error below — which is what lets `form` align
 groups of them.
 
+## [InsetOptions](InsetOptions.md) · interface
+
+Options for a field that can carry content *inside* its control box — an
+icon against the leading edge, a button against the trailing one. Added by
+("./textline").textline and
+("./textarea").textarea.
+
 ## [ContentOptions](ContentOptions.md) · interface
 
 Options for components that wrap a single block of caller-provided content,

package/skill/TextareaOptions.md

@@ -28,7 +28,10 @@ Visible number of text rows. Defaults to `4`. Ignored when `autoGrow` is enabled
 
 ### textareaOptions.resize · member
 
-Whether the textarea may be resized by the user. Defaults to `"vertical"`. Ignored when `autoGrow` is enabled.
+Whether the textarea may be resized by the user. Defaults to `"vertical"`,
+or to `"none"` when a | suffix is given — the
+resize grip and the inset both want the bottom-right corner. Ignored when
+`autoGrow` is enabled.
 
 **Type:** `"none" | "vertical" | "horizontal" | "both"`
 

package/skill/autocomplete.md

@@ -4,6 +4,10 @@ A combobox with type-ahead filtering. Supports single or multi-select (chips),
 optional free-text entry, and full keyboard control (arrows, enter, escape,
 backspace-to-remove). Implements the ARIA combobox/listbox pattern.
 
+What you type is matched against the start of the label's words, a term at a
+time and in any order — "pal se" finds "Palette search" — see
+`matchWords`, or `AutocompleteOptions.match` to filter your own way.
+
 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.

package/skill/dialog.md

@@ -5,8 +5,9 @@ that fades in and out. Returns a `Promise<void>` that resolves when the dialog
 closes. Lifecycle is also tied to the parent reactive scope — when that scope
 is cleaned up the dialog disappears and the promise resolves.
 
-Multiple dialogs stack correctly: each new pair (backdrop + dialog) has a
-higher z-index, while older dialogs are pushed behind their covering backdrop.
+Multiple dialogs stack: each new pair (backdrop + dialog) gets a higher
+z-index than the one it covers, while older dialogs are pushed behind their
+covering backdrop.
 
 **Signature:** `(opts: DialogOptions) => Promise<void>`
 

package/skill/iconButton.md

@@ -20,7 +20,9 @@ an icon alone is unambiguous only for a handful of universal actions.
 import { trash2, share2 } from "staffa/icons";
 
 $panel.actions = () => {
-  S.iconButton({ icon: share2, ariaLabel: "Share", click: share });
+  // A string `tooltip` names the button for screen readers too, so one option does.
+  S.iconButton({ icon: share2, tooltip: "Share", click: share });
+  // Named, but silent on hover: `ariaLabel` alone raises no tooltip.
   S.iconButton({ icon: trash2, ariaLabel: "Delete", click: del, attrs: "fg:$s-danger" });
 };
 ```

package/skill/matchWords.md

@@ -0,0 +1,17 @@
+## matchWords · function
+
+The default type-ahead test: every whitespace-separated term of the query has
+to match the label from a word start on, and no two terms may claim the same
+word. Order doesn't matter, so "se pal" finds "Palette search" just as
+"pal se" does — but "ette" finds nothing, as you type the beginnings of
+words. A term may run past its word's end ("typescript" finds "TypeScript",
+"c++" finds "C++"), so typing a label out in full always finds it.
+
+Pass it to `AutocompleteOptions.match` to compose with it.
+
+**Signature:** `(label: string, query: string) => boolean`
+
+**Parameters:**
+
+- `label: string`
+- `query: string`

package/skill/textarea.md

@@ -14,4 +14,12 @@ A multi-line text input. Shares the field chrome and styling of
 ```ts
 const $user = A.proxy({bio: ""});
 S.textarea({ label: "Bio", bind: A.ref($user, "bio") });
+
+// A chat box: the send button sits in the bottom-right corner, inside the field.
+const $chat = A.proxy({text: ""});
+S.textarea({
+  placeholder: "Message…",
+  bind: A.ref($chat, "text"),
+  suffix: () => S.iconButton({ icon: send, tooltip: "Send", click: () => post($chat.text) }),
+});
 ```

package/skill/textline.md

@@ -15,4 +15,7 @@ chrome (label, control, help/error), so it aligns cleanly inside a `form`.
 ```ts
 const $user = A.proxy({email: "test@example.com"});
 S.textline({ label: "Email", type: "email", required: true, bind: A.ref($user, "email") });
+
+// Content inside the field: a glyph against its left edge, a button against its right.
+S.textline({ placeholder: "Search…", prefix: search, suffix: () => S.iconButton({ icon: x, tooltip: "Clear" }) });
 ```

package/src/components/autocomplete.ts

@@ -26,8 +26,22 @@ export interface AutocompleteOptions extends FieldOptions {
 	bind?: Bindable<string | string[]>;
 	/** Allow selecting several values, shown as removable chips. */
 	multi?: boolean;
-	/** Allow committing free text that isn't in the options list. Defaults to `true`. */
+	/**
+	 * Allow committing free text that isn't in the options list. Defaults to
+	 * `true`, and includes no text at all: emptying a single-select field clears
+	 * its selection (`required` is what makes that an error). With
+	 * `allowCustom: false` only the options can be committed, so anything else
+	 * springs back to the current selection when the field loses focus.
+	 */
 	allowCustom?: boolean;
+	/**
+	 * The type-ahead test, run for each option against what has been typed.
+	 * Defaults to {@link matchWords}. Pass your own to filter differently — say
+	 * `(label, q) => label.toLowerCase().includes(q.toLowerCase())` for plain
+	 * substring matching, or something that also looks at an option's other
+	 * fields. Matching never reorders: options are shown as given.
+	 */
+	match?: (label: string, query: string) => boolean;
 	/** Placeholder for the text input. */
 	placeholder?: string;
 }
@@ -110,6 +124,41 @@ mountPortal(() => {
 	sizeChanged = followAnchor(p.anchor, (r) => place(el, r));
 });
 
+/**
+ * Where each word of a label begins: runs of letters or digits, split again at
+ * camelCase humps — "TypeScript" starts a word at `T` and at `S`.
+ */
+function wordStarts(label: string): number[] {
+	const starts: number[] = [];
+	for (const m of label.matchAll(/\p{N}+|\p{Lu}+(?=\p{Lu}\p{Ll})|\p{Lu}?\p{Ll}+|\p{Lu}+/gu)) starts.push(m.index);
+	return starts;
+}
+
+/**
+ * The default type-ahead test: every whitespace-separated term of the query has
+ * to match the label from a word start on, and no two terms may claim the same
+ * word. Order doesn't matter, so "se pal" finds "Palette search" just as
+ * "pal se" does — but "ette" finds nothing, as you type the beginnings of
+ * words. A term may run past its word's end ("typescript" finds "TypeScript",
+ * "c++" finds "C++"), so typing a label out in full always finds it.
+ *
+ * Pass it to {@link AutocompleteOptions.match} to compose with it.
+ */
+export function matchWords(label: string, query: string): boolean {
+	// Longest term first: it is the most constrained, so the greedy claim below
+	// doesn't let a short term take the word a long one needed.
+	const terms = query.toLowerCase().split(/\s+/).filter(Boolean).sort((a, b) => b.length - a.length);
+	if (!terms.length) return true;
+	const starts = wordStarts(label);
+	const used: boolean[] = [];
+	return terms.every((t) => {
+		const i = starts.findIndex((s, i) => !used[i] && label.slice(s, s + t.length).toLowerCase() === t);
+		if (i < 0) return false;
+		used[i] = true;
+		return true;
+	});
+}
+
 function normOption(o: AutocompleteOptionInput): AcOption {
 	return typeof o === "string" ? { value: o, label: o } : { value: o.value, label: o.label ?? o.value };
 }
@@ -119,6 +168,10 @@ function normOption(o: AutocompleteOptionInput): AcOption {
  * optional free-text entry, and full keyboard control (arrows, enter, escape,
  * backspace-to-remove). Implements the ARIA combobox/listbox pattern.
  *
+ * What you type is matched against the start of the label's words, a term at a
+ * time and in any order — "pal se" finds "Palette search" — see
+ * {@link matchWords}, or {@link AutocompleteOptions.match} to filter your own way.
+ *
  * 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.
@@ -154,6 +207,10 @@ export function autocomplete(opts: AutocompleteOptions): void {
 		return Array.isArray(v) ? v : [v];
 	};
 	const labelFor = (value: string): string => getOptions().find((o) => o.value === value)?.label ?? value;
+	// What committing free text means: the option the text names, or the text itself.
+	// Typing a label out in full is picking that option, not inventing a value.
+	const valueForText = (text: string): string =>
+		text ? getOptions().find((o) => o.label.toLowerCase() === text.toLowerCase())?.value ?? text : "";
 
 	// Seed the input with the current single-selection's label.
 	if (!opts.multi) {
@@ -165,8 +222,9 @@ export function autocomplete(opts: AutocompleteOptions): void {
 		const sel = new Set(selectedValues());
 		let list = getOptions();
 		if (opts.multi) list = list.filter((o) => !sel.has(o.value));
-		const q = $st.query.trim().toLowerCase();
-		if (q) list = list.filter((o) => o.label.toLowerCase().includes(q));
+		// Cased as typed: the matcher splits on camelCase humps, and lowercases itself.
+		const q = $st.query.trim();
+		if (q) list = list.filter((o) => (opts.match ?? matchWords)(o.label, q));
 		return list;
 	};
 
@@ -316,21 +374,27 @@ export function autocomplete(opts: AutocompleteOptions): void {
 		} else if (e.key === "Enter") {
 			// Always prevent default to avoid accidental form submission.
 			e.preventDefault();
-			const chosen = list[$st.active];
+			const q = $st.query.trim();
+			// Only a row of a list that is up: with it hidden there is no highlight to
+			// be seen, so Enter takes what has been typed instead.
+			const chosen = $st.open ? list[$st.active] : undefined;
 			if (chosen) {
 				commit(chosen.value, inputEl);
-			} else if (opts.allowCustom !== false && $st.query.trim()) {
-				commit($st.query.trim(), inputEl);
+			} else if (opts.allowCustom !== false && (q || !opts.multi)) {
+				// No text is a commit too, in single mode: it clears the selection.
+				// (In multi mode there is nothing to clear, and no chip to make.)
+				commit(valueForText(q), inputEl);
 			} else if ($st.open) {
+				// Nothing to commit (the options are all there is, and none match).
 				$st.open = false;
 			}
 		} else if (e.key === "Escape") {
-			// Only consume Escape while the list is showing: it dismisses the innermost
-			// layer, so a surrounding dialog closes on the next press, not this one.
+			// Escape hides the list and leaves what was typed standing — it dismisses
+			// a layer, it doesn't undo an edit. Only consumed while the list is up, so
+			// a surrounding dialog closes on the next press, not this one.
 			if ($st.open) {
 				e.preventDefault();
 				$st.open = false;
-				if (!opts.multi) $st.query = labelFor(selectedValues()[0] ?? "");
 			}
 		} else if (e.key === "Backspace" && opts.multi && $st.query === "") {
 			const sel = selectedValues();
@@ -342,10 +406,12 @@ export function autocomplete(opts: AutocompleteOptions): void {
 		$st.open = false;
 		if (opts.multi) {
 			$st.query = "";
-		} else if (opts.allowCustom !== false && $st.query.trim()) {
-			commit($st.query.trim());
+		} else if (opts.allowCustom !== false) {
+			// Free text stands as typed — nothing at all included, which is how a
+			// single selection is cleared. (`required` is what makes empty an error.)
+			commit(valueForText($st.query.trim()));
 		} else {
-			// Revert to the committed selection's label.
+			// Only the options exist, so anything else reverts to the selected one.
 			$st.query = labelFor(selectedValues()[0] ?? "");
 		}
 	}

package/src/components/button.ts

@@ -7,8 +7,12 @@ import { addTooltip } from "./tooltip.js";
 export interface IconButtonOptions {
 	/** The glyph, usually one of the `staffa/icons` draw functions. */
 	icon: Slot;
-	/** What it does, for screen readers. Required: there is no visible text to read. */
-	ariaLabel: string;
+	/**
+	 * What it does, for screen readers: there is no visible text to read. Required,
+	 * unless the `tooltip` is a string — that names the button just as well, and is
+	 * taken as the label when this is left out.
+	 */
+	ariaLabel?: string;
 	/**
 	 * Click handler. Return a promise and the glyph becomes a spinner until it
 	 * settles, with further clicks bouncing off — see {@link ButtonOptions.click}.
@@ -16,16 +20,17 @@ export interface IconButtonOptions {
 	click?: (event: Event) => unknown;
 	/**
 	 * A keyboard shortcut that presses this button — see {@link ButtonOptions.key}.
-	 * 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.
+	 * It is shown after the button's `tooltip`, or alone in a tooltip of its own
+	 * when there is none, and the `?` overview lists it under the button's label.
 	 */
 	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.
+	 * text. There is none unless you ask for one — but do consider it here, as
+	 * a glyph says nothing to whoever cannot guess it. A string doubles as the
+	 * `ariaLabel` when that is left out, so an icon button usually needs one
+	 * option, not two. A `key` is appended to the tip, behind a `·`; pass
+	 * `false` to suppress even that.
 	 *
 	 * Works on a disabled button too, which is where a tooltip earns its keep:
 	 * it is the only room there is to say why.
@@ -67,7 +72,10 @@ export interface ButtonOptions {
 	type?: "button" | "submit" | "reset";
 	/** Render as a link (`<a role=button>`) pointing here instead of a `<button>`. */
 	href?: string;
-	/** Accessible label, when the button has only an icon. */
+	/**
+	 * Accessible label, when the button has only an icon. A string `tooltip` is
+	 * taken as the label of such a button when this is left out.
+	 */
 	ariaLabel?: string;
 	/**
 	 * A keyboard shortcut that presses this button: `"mod+s"`, `"f2"` — see
@@ -81,9 +89,10 @@ export interface ButtonOptions {
 	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.
+	 * text, a function draws its own markup. There is none unless you ask for
+	 * one. A `key` is appended to it, behind a `·`; pass `false` to suppress
+	 * even that. On an icon-only button, a string tooltip doubles as the
+	 * `ariaLabel` when that is left out.
 	 *
 	 * Works on a disabled button too, which is where a tooltip earns its keep:
 	 * it is the only room there is to say why.
@@ -184,22 +193,25 @@ A.insertGlobalCss({
  * import { trash2, share2 } from "staffa/icons";
  *
  * $panel.actions = () => {
- *   S.iconButton({ icon: share2, ariaLabel: "Share", click: share });
+ *   // A string `tooltip` names the button for screen readers too, so one option does.
+ *   S.iconButton({ icon: share2, tooltip: "Share", click: share });
+ *   // Named, but silent on hover: `ariaLabel` alone raises no tooltip.
  *   S.iconButton({ icon: trash2, ariaLabel: "Delete", click: del, attrs: "fg:$s-danger" });
  * };
  * ```
  */
 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;
+	const tip = opts.tooltip === false ? undefined : opts.tooltip;
+	// A glyph says nothing on its own, so the button needs a name — and a tooltip
+	// written as a string already is one. Said once, it serves both.
+	const label = opts.ariaLabel ?? (typeof tip === "string" ? plainText(tip) : undefined);
 	A(`${tag}.s-icon-btn`, opts.attrs, () => {
 		applyActionBehavior(opts, tip != null);
-		A("aria-label=", opts.ariaLabel);
+		A("aria-label=", label);
 		// 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);
+		applyTooltipAndKey(opts.tooltip, opts.key, label, opts.disabled);
 		drawSlot(opts.icon);
 	});
 }
@@ -265,24 +277,41 @@ function applyClick(click: (event: Event) => unknown): void {
 	});
 }
 
+/**
+ * A rich-text string as a screen reader should hear it. Same pattern Aberdeen's
+ * `rich=` draws with, so a tooltip standing in as the accessible name says the
+ * words it shows, and not its own asterisks and brackets.
+ */
+function plainText(rich: string): string {
+	return rich.replace(/\*\*(.+?)\*\*|\*(.+?)\*|`(.+?)`|\[(.+?)\]\((.+?)\)/g,
+		(_m, bold, italic, code, link) => bold ?? italic ?? code ?? link);
+}
+
 /**
  * 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`.
+ * it as `aria-keyshortcuts`. A key with no tooltip to join gets a tip of its
+ * own, saying the combination and no more.
  *
- * Pressing it clicks the element rather than calling `click` directly, so a
+ * Pressing the key 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.
+ * the binding follows. `keyLabel` is how the `?` overview names the shortcut.
  */
-function applyTooltipAndKey(tip: Slot | undefined, key: string | undefined, label: string | undefined, disabled?: boolean): void {
-	if (tip != null || key) {
+function applyTooltipAndKey(
+	tooltip: Slot | false | undefined,
+	key: string | undefined,
+	keyLabel: string | undefined,
+	disabled?: boolean,
+): void {
+	// `false` is a vow of silence: not even a key raises a tip on this one.
+	if (tooltip !== false && (tooltip != null || key)) {
 		addTooltip({
 			tip: () => {
-				drawSlot(tip);
+				drawSlot(tooltip);
 				// A draw function, not a string: a key like `*` is markup to rich text.
-				if (key) A("#", tip == null ? formatKey(key) : ` · ${formatKey(key)}`);
+				if (key) A("#", tooltip == null ? formatKey(key) : ` · ${formatKey(key)}`);
 			},
 		});
 	}
@@ -292,7 +321,7 @@ function applyTooltipAndKey(tip: Slot | undefined, key: string | undefined, labe
 	if (key && !disabled) {
 		const el = A() as HTMLElement;
 		A("aria-keyshortcuts=", formatKey(key, true));
-		bindKey(key, label, () => el.click());
+		bindKey(key, keyLabel, () => el.click());
 	}
 }
 
@@ -326,18 +355,19 @@ 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;
+	const tip = o.tooltip === false ? undefined : o.tooltip;
+	// Only a button without visible text needs naming, and a string tooltip is a
+	// name: on one that has text, an aria-label would *hide* that text from AT.
+	const label = o.ariaLabel ?? (o.content == null && typeof tip === "string" ? plainText(tip) : undefined);
 
 	// 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, tip != null);
-		if (o.ariaLabel) A("aria-label=", o.ariaLabel);
+		if (label) A("aria-label=", label);
 		// Before the content, so a tooltip the caller adds in there is the later of
 		// the two and wins the hover.
-		applyTooltipAndKey(tip, o.key, typeof o.content === "string" ? o.content : o.ariaLabel, o.disabled);
+		applyTooltipAndKey(o.tooltip, o.key, typeof o.content === "string" ? o.content : label, o.disabled);
 
 		drawSlot(o.icon);
 		drawSlot(o.content);

package/src/components/dialog.ts

@@ -51,6 +51,9 @@ export interface DialogOptions {
 	onClose?: () => void;
 }
 
+/** The layer the bottom dialog's backdrop is painted on; each dialog adds two. */
+const BASE_Z = 200;
+
 A.insertGlobalCss({
 	".s-backdrop": {
 		"&": "position:fixed inset:0 z-index:200 display:block background: rgba(0,0,0,0.55); transition: opacity 0.4s ease-in-out;",
@@ -80,6 +83,8 @@ A.insertGlobalCss({
 const dialogs = A.proxy({} as Record<string,{resolve: (value: void | PromiseLike<void>) => void, opts: DialogOptions}>);
 let dialogCount = 0;
 
+// `Object.keys` orders integer-like keys numerically, so the last one is the
+// newest dialog — the one on top.
 const topDialogId = A.derive(() => {
 	const keys = Object.keys(dialogs);
 	if (keys.length) return keys[keys.length-1];
@@ -91,6 +96,9 @@ export function isDialogOpen(): boolean {
 }
 
 mountPortal(() => {
+	// Sorted numerically: the keys are numbers, and left to `onEach`'s default
+	// string ordering "10" would sort before "2", putting the tenth dialog
+	// before (hence behind) a still-open second one.
 	A.onEach(dialogs, ({resolve, opts}, dialogId) => {
 		const close = () => { delete dialogs[dialogId]; };
 
@@ -109,9 +117,9 @@ mountPortal(() => {
 
 		// Backdrop - hide when not the top dialog
 		const overlaid = A.derive(() => topDialogId.value != dialogId);
-		A("div.s-backdrop create=hidden destroy=hidden .hidden=", overlaid, "click=", () => {
+		const backdropEl = A("div.s-backdrop create=hidden destroy=hidden .hidden=", overlaid, "click=", () => {
 			if (opts.allowCancel !== false) close();
-		});
+		}) as HTMLElement;
 
 		// 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.
@@ -164,10 +172,28 @@ mountPortal(() => {
 			});
 		}) as HTMLElement;
 
+		// Stacking is stated, not left to the order the elements happen to sit in
+		// the DOM: a dialog sits a layer above its own backdrop, and that pair a
+		// layer above the dialog it covers. (A closing dialog has left the stack
+		// already; it keeps the layer it had while it fades out.)
+		let depth = 0;
+		A(() => {
+			const index = Object.keys(dialogs).indexOf(dialogId);
+			if (index >= 0) depth = index;
+			backdropEl.style.zIndex = `${BASE_Z + 2*depth}`;
+			dialogEl.style.zIndex = `${BASE_Z + 2*depth + 1}`;
+		});
+
 		// Once laid out, move focus into the dialog so it's keyboard-ready and focus
 		// doesn't linger on whatever opened it.
-		requestAnimationFrame(() => { if (document.body.contains(dialogEl)) focusFirst(dialogEl); });
-	});
+		requestAnimationFrame(() => {
+			// Only the top dialog claims focus: one opened *under* another (the
+			// covering dialog opened straight after it) must not pull focus into
+			// fields the user can't see.
+			if (A.peek(() => topDialogId.value) !== dialogId) return;
+			if (document.body.contains(dialogEl)) focusFirst(dialogEl);
+		});
+	}, (_value, dialogId) => +dialogId);
 })
 
 /**
@@ -192,8 +218,9 @@ function trapTab(dialogEl: HTMLElement, event: KeyboardEvent): void {
  * closes. Lifecycle is also tied to the parent reactive scope — when that scope
  * is cleaned up the dialog disappears and the promise resolves.
  *
- * Multiple dialogs stack correctly: each new pair (backdrop + dialog) has a
- * higher z-index, while older dialogs are pushed behind their covering backdrop.
+ * Multiple dialogs stack: each new pair (backdrop + dialog) gets a higher
+ * z-index than the one it covers, while older dialogs are pushed behind their
+ * covering backdrop.
  *
  * @example
  * ```ts