staffa 0.14.0 → 0.16.0

package/skill/addTooltip.md

@@ -1,10 +1,9 @@
 ## addTooltip · function
 
-Attaches a tooltip to the current element: adds hover/focus handlers via
-`A` so the tip appears when the element is hovered or keyboard-focused.
-The tip panel is rendered into `document.body` via a portal, so it is never
-clipped by `overflow:hidden` ancestors. Position is computed from the
-element's bounding rect and automatically flips when near the viewport edge.
+Attaches a tooltip to the current element, shown on hover or keyboard focus.
+The tip panel is portalled into `document.body`, so `overflow:hidden` ancestors
+never clip it; it is placed from the element's bounding rect, flipping to the
+opposite side when near the viewport edge.
 
 **Signature:** `(opts: TooltipOptions) => void`
 

package/skill/bindKey.md

@@ -0,0 +1,51 @@
+## bindKey · function
+
+Bind a keyboard shortcut, for as long as the calling scope lives.
+
+**The spec** is a `KeyboardEvent.key` value — `"k"`, `"f2"`, `"escape"`
+(`"esc"`), `"space"`, `"arrowdown"`, a bare `"?"` — optionally prefixed by
+`mod+` (⌘ on a Mac, Ctrl elsewhere) and/or `shift+`, in that order:
+`"mod+k"`, `"shift+f2"`, `"mod+shift+b"`. Case doesn't matter. A character
+Shift itself types is written as that character — `"?"`, never `"shift+/"` —
+so a combination works on every keyboard layout. No other modifiers are
+offered: Alt and the ⊞ key belong to the browser and the OS, which also
+keep some `mod` combinations for themselves — T, N, W, Q and the digits
+among them, while K, B, E, `/` and `.` are safely yours. Everything Staffa
+takes a `key` option is spelled this way, and `formatKey` turns it
+back into `"⇧⌘K"`/`"Ctrl+Shift+K"`.
+
+`description` is what the shortcut overview (see `showKeyHelp`) lists
+the binding as — a rich-text string or draw function; without one the
+binding stays out of the overview. Omit `press` to merely *describe* a key
+your app handles by other means, so the overview can still tell the user
+about it.
+
+A handler of the app's own that ran `preventDefault()` first always wins,
+and keystrokes the focused element owns (typing into a field, Enter on a
+link) are left to it. Otherwise `mode` says who else can reach the binding:
+
+- `"normal"` (the default): works app-wide, but is silenced while a modal
+  dialog from outside it is up. Binding the same combination again shadows
+  the earlier binding until the new scope dies — so a state can take a key
+  over temporarily.
+- `"global"`: keeps working even over a modal.
+- `"local"`: only fires while the keyboard focus is inside the current
+  element — for a shortcut that belongs to one row or panel of many.
+- an `Element`: like `"local"`, but for that element rather than the
+  current one.
+
+**Signature:** `(spec: string, description?: Slot, press?: (e: KeyboardEvent) => void, mode?: "normal" | "global" | "local" | Element) => void`
+
+**Parameters:**
+
+- `spec: string`
+- `description?: Slot`
+- `press?: (e: KeyboardEvent) => void`
+- `mode: "normal" | "global" | "local" | Element` (optional)
+
+**Examples:**
+
+```ts
+S.bindKey("mod+k", "Search", openSearch);
+S.bindKey("mod+z", "Undo");   // describe only: handled by our own listener
+```

package/skill/box.md

@@ -9,7 +9,7 @@ out as a flex container.
 
 Shortcut: pass a function to use it directly as the body content.
 
-**Signature:** `(opts?: BoxOptions | Slot) => void`
+**Signature:** `(opts?: Slot | BoxOptions) => void`
 
 **Parameters:**
 

package/skill/form.md

@@ -1,12 +1,10 @@
 ## form · function
 
-An opinionated `<form>` wrapper that lays its fields out consistently — a clean
-single column by default, or a responsive grid — and provides a standard
-action bar.
-
-Field components (("./textline").textline et al.) drop straight
-in as `ContentOptions.content`. Submission is wired so the browser's
-native validation runs, but the page never reloads.
+An opinionated `<form>` wrapper: fields in a single column by default, or a
+responsive grid, plus a standard action bar. Field components
+(("./textline").textline et al.) drop straight in as
+`ContentOptions.content`; the browser's native validation runs on submit,
+but the page never reloads.
 
 **Signature:** `(opts?: Slot | FormOptions) => void`
 

package/skill/formatKey.md

@@ -0,0 +1,21 @@
+## formatKey · function
+
+Write a key combination the way the platform writes it: `"⇧⌘K"` on a Mac,
+`"Ctrl+Shift+K"` everywhere else. What the components put in their key hints —
+use it for the same hint elsewhere in your app, so both spell the shortcut the
+way this machine's user expects. Pass `aria: true` for the `aria-keyshortcuts`
+spelling instead: full modifier names and real key names,
+`"Meta+Shift+K"`/`"Control+Shift+K"`.
+
+**Signature:** `(spec: string, aria?: boolean) => string`
+
+**Parameters:**
+
+- `spec: string`
+- `aria: any` (optional)
+
+**Examples:**
+
+```ts
+S.button({ content: `Search  ${S.formatKey("mod+k")}`, click: search });
+```

package/skill/iconButton.md

@@ -1,13 +1,12 @@
 ## iconButton · function
 
 A bare glyph in a square hit area — no fill, no border, just ink that lifts on
-hover. The quiet end of the button family, for chrome that has to sit beside
-something more important without competing with it: a ✕ on a box, the ☰ a
-routed `S.main()` puts in its top bar, the verbs in a
-| page's actions.
+hover. For chrome that has to sit beside something more important without
+competing with it: a ✕ on a box, the ☰ a routed `S.main()` puts in its top bar,
+the verbs in a | page's actions.
 
 Reach for `button` instead whenever the thing has a name worth reading;
-an icon alone is only unambiguous for a handful of universal actions.
+an icon alone is unambiguous only for a handful of universal actions.
 
 **Signature:** `(opts: IconButtonOptions) => void`
 

package/skill/scrollStrip.md

@@ -1,16 +1,14 @@
 ## scrollStrip · function
 
 A horizontal row that scrolls when its content outgrows it, with a ‹ / ›
-button appearing over whichever end still has something left to reach — a
-bare scroll area says nothing about itself to a mouse, and a scrollbar under
-a row of chrome reads as a mistake. The row's own scrollbar is hidden, and
-the buttons scroll it by most of a width at a time.
+button appearing over whichever end still has something left to reach — so it
+isn't just a swipe target. The row's own scrollbar is hidden, and the buttons
+scroll it by most of a width at a time.
 
-This is what `tabs` puts its tab strip in, and what the routed
-`main` shell puts its breadcrumb stack in. Reach for it for any row of
-chrome that can outgrow its space: a filter bar, a row of chips, a toolbar.
-To bring one of its children into view — after selecting it from elsewhere,
-say — call `revealInStrip` with that child.
+`tabs` puts its tab strip in one, and the routed `main` shell its
+breadcrumb stack. Reach for it for any row of chrome that can outgrow its
+space: a filter bar, a row of chips, a toolbar. `revealInStrip` brings
+one of its children into view.
 
 **Signature:** `(opts: ScrollStripOptions) => void`
 

package/skill/showFloatingMenu.md

@@ -2,8 +2,8 @@
 
 Open a floating dropdown menu anchored to an element. Portals to
 `document.body` (never clipped), positions itself (flipping up when there's
-no room below), and closes on Escape, Tab, item selection, or any click
-outside the panel and anchor. Returns a `close()` function.
+no room below), and closes on Escape, Tab, item selection, a navigation, or
+any click outside the panel and anchor. Returns a `close()` function.
 
 Menus are usually opened through `menuButton` or
 `addContextMenu`; reach for this primitive when you need to trigger a

package/skill/showKeyHelp.md

@@ -0,0 +1,17 @@
+## showKeyHelp · function
+
+The shortcut overview: a dialog listing what a keypress could do *right now*
+— every described binding the keyboard focus and any open modal leave in
+effect: buttons under their label, menu items under theirs, `bindKey`
+bindings under the description they were given.
+
+It's a cheat-sheet, not a modal: the shortcuts it lists keep working, and any
+keypress closes it *and* still lands — so the key you just looked up can be
+pressed right there. That is also what keeps the listing honest: focus cannot
+move while it is up (a click lands on the backdrop, a key closes it), so what
+was true when it opened stays true. Bound to `?` (and `mod+?`, which also
+works while typing in a field) by default — see `setKeyHelp`. Calling
+this while the overview is already up closes it, which is what lets that `?`
+toggle.
+
+**Signature:** `() => void`

package/skill/tabs.md

@@ -3,10 +3,9 @@
 A tabbed view. Renders an ARIA `tablist` of buttons and a single live panel
 for the selected tab. Supports keyboard navigation (left/right/home/end).
 
-More tabs than fit make the strip scroll sideways, with a ‹ / › button
-appearing over whichever end still has something to reach — a bare scroll area
-says nothing about itself to a mouse. Selecting a tab that's out of view
-(arrow keys, or a `bind` written from elsewhere) scrolls it back in.
+More tabs than fit make the strip scroll sideways (see `scrollStrip`);
+selecting a tab that's out of view — with the arrow keys, or a `bind` written
+from elsewhere — scrolls it back in.
 
 **Signature:** `(opts: TabsOptions) => void`
 

package/skill/textline.md

@@ -1,10 +1,8 @@
 ## textline · function
 
-A single-line text input — covering text, passwords, numbers, email, dates and
-the other line-oriented `<input>` types.
-
-Renders inside the standard `drawField` chrome (label, control,
-help/error), so it aligns cleanly inside a `form`.
+A single-line text input — text, passwords, numbers, email, dates and the other
+line-oriented `<input>` types. Renders inside the standard `drawField`
+chrome (label, control, help/error), so it aligns cleanly inside a `form`.
 
 **Signature:** `(opts?: TextlineOptions) => void`
 

package/src/components/autocomplete.ts

@@ -44,8 +44,8 @@ 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",
-		// The popup is a `.s-s.neutral.shadow` surface (see below): background, border,
-		// radius and elevation all come from the surface.
+		// 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",
 		".s-option": "padding: 0.45em 0.6em; r:6px cursor:pointer transition: background 0.1s;",
@@ -261,9 +261,8 @@ export function autocomplete(opts: AutocompleteOptions): void {
 				$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 must not also close. With the
-			// list already closed, let it pass through to the dialog/nav handlers.
+			// 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.
 			if ($st.open) {
 				e.preventDefault();
 				$st.open = false;

package/src/components/box.ts

@@ -28,15 +28,10 @@ export interface BoxOptions extends ContentOptions {
 	footerAttrs?: Attributes;
 }
 
-// The box itself is a `.neutral` surface; its header/footer are `.neutral` surfaces
-// too — nested one level deeper, so they pick up the next elevation shade
-// automatically. Colours and borders come from the contextual tokens, so a box
-// stays legible on whatever surface it's nested in.
-// The box is just a `.s-s.neutral.shadow` surface: its border and shadow come from
-// the surface itself (see theme.ts), not from here. `.s-box` only does layout and
-// the header/footer dividers. Header/footer are `.neutral` surfaces too (one level
-// deeper, for the raised shade), so we cancel their full surface border down to a
-// single divider.
+// Colours, border and shadow come from the `.s-s.neutral.shadow` surface itself
+// (see theme.ts); `.s-box` only does layout. Header/footer are `.neutral` surfaces
+// one level deeper (for the raised shade), with their surface border cancelled
+// down to a single divider.
 A.insertGlobalCss({
 	".s-box": {
 		// position:relative so a headerless box can hang its ✕ in the corner.
@@ -45,11 +40,8 @@ A.insertGlobalCss({
 		"> header": "display:flex align-items:center gap:$2 padding: $2 $3; border:0 border-bottom: 1px solid $s-faint; r:0 font-weight:600",
 		"> footer": "display:flex align-items:center justify-content:flex-end gap:$2 padding: $2 $3; border:0 border-top: 1px solid $s-faint; r:0",
 		"> div": "p:$3 gap:$3",
-		// The ✕ is an `S.iconButton` (see `drawCloseButton`); this only places it.
-		// In a header row it parks at the far end...
+		// The ✕ parks at the end of a header row, or floats over the body when there is none.
 		"> header > .s-box-close": "margin-left:auto",
-		// ...and without a header there is no row to sit in, so it floats over the
-		// body's top-right corner instead.
 		"> .s-box-close": "position:absolute top:$2 right:$2 z-index:1",
 	},
 });
@@ -78,12 +70,11 @@ export function box(opts: BoxOptions | Slot = {}): void {
 	const o: BoxOptions = typeof opts === "string" || typeof opts === "function" ? { content: opts } : opts;
 
 	A("section.s-box.s-s.neutral.shadow", o.attrs, () => {
-		// Header and footer get their own scopes so toggling them doesn't recreate
-		// the body (which may hold focused inputs / lots of content).
+		// Header and footer get their own scopes, so toggling them doesn't recreate
+		// the body (which may hold focused inputs).
 		A(() => {
-			// The typeof guards against v0.9's `close: true` (removed API) reaching
-			// us from unchecked JS: a ✕ whose handler isn't a function would render
-			// but do nothing, which is worse than not rendering at all.
+			// typeof-guarded: v0.9's removed `close: true`, reaching us from unchecked
+			// JS, would otherwise render a ✕ that does nothing.
 			if (o.header != null) {
 				A("header.s-s.neutral", o.headerAttrs, () => {
 					drawSlot(o.header);
@@ -105,9 +96,8 @@ export function box(opts: BoxOptions | Slot = {}): void {
 }
 
 /**
- * The box's ✕: one definition, so the glyph, the label and the hit area are
- * identical whether it sits in the header row or floats over a headerless body.
- * The `.s-box-close` class is only a hook for the placement rules above.
+ * The box's ✕: one definition, so it is identical in a header row and floating
+ * over a headerless body. `.s-box-close` is only a hook for the placement rules.
  */
 function drawCloseButton(close: () => void): void {
 	iconButton({

package/src/components/button.ts

@@ -1,5 +1,7 @@
 import A from "aberdeen";
 import { type Slot, type Attributes, drawSlot } from "../core.js";
+import { bindKey, formatKey } from "../keys.js";
+import { addTooltip } from "./tooltip.js";
 
 /** Options for {@link iconButton}. */
 export interface IconButtonOptions {
@@ -9,6 +11,12 @@ export interface IconButtonOptions {
 	ariaLabel: string;
 	/** Click handler. */
 	click?: (event: Event) => void;
+	/**
+	 * 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.
+	 */
+	key?: string;
 	/** Render as a link (`<a role=button>`) pointing here instead of a `<button>`. */
 	href?: string;
 	/** Disables it. */
@@ -37,6 +45,16 @@ export interface ButtonOptions {
 	href?: string;
 	/** Accessible label, when the button has only an icon. */
 	ariaLabel?: string;
+	/**
+	 * A keyboard shortcut that presses this button: `"mod+s"`, `"f2"` — see
+	 * {@link bindKey} for the spelling and which keystrokes are yours to take.
+	 * It works from anywhere while the button is drawn, shows in a tooltip,
+	 * reaches screen readers as `aria-keyshortcuts`, and does exactly what a
+	 * click does: a `type: "submit"` submits its form, an `href` navigates. The
+	 * `?` overview ({@link showKeyHelp}) lists it under the button's text (or
+	 * its `ariaLabel`).
+	 */
+	key?: string;
 	/**
 	 * 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"`,
@@ -50,9 +68,8 @@ export interface ButtonOptions {
 	attrs?: Attributes;
 }
 
-// The button is a `.s-s` surface (defaulting to `.primary` in button() below), so
-// its colours, border, and border-radius come from the surface classes in theme.ts.
-// This rule only handles layout, focus, hover and sizing.
+// Colours, border and radius come from the `.s-s` surface classes in theme.ts;
+// this rule only does layout, focus, hover and sizing.
 A.insertGlobalCss({
 	".s-btn": {
 		"&":
@@ -60,52 +77,34 @@ A.insertGlobalCss({
 			"font-weight:450 line-height:1.1 white-space:nowrap cursor:pointer text-decoration:none " +
 			"padding: $m2 $m3; " +
 			"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) so it survives a `.no-shadow`
-		// (which hard-clears box-shadow). Modern browsers round it to the border-radius.
+		// Focus ring via `outline`, not box-shadow: `.no-shadow` hard-clears box-shadow.
 		"&:focus-visible": "outline: 3px solid $s-focus; outline-offset: 1px;",
-		// The button carries `.shadow` (added in button() below); on a filled accent
-		// surface that resolves to the signature self-coloured glow, on a neutral
-		// `.neutral` button to nothing, on tonal/outlined to nothing — all via theme.ts.
 		"&:hover": "filter: brightness(1.06)",
-		// Tonal/outlined hover deepen their translucent fill; a neutral `.neutral`
-		// button (which is already near-white) darkens toward its ink instead.
 		"&.tonal:hover, &.outlined:hover": "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);",
-		// The button sizes its glyph, for the same reason `.s-icon-btn` does below:
-		// a caller can't know what the button beside it passed, and only a rule
-		// here makes every icon in a row come out alike. It rides the font size,
-		// so a `.small`/`.large` button scales its icon with its text.
+		// 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",
-		// Subtle press feedback.
 		"&:active:not(:disabled)": "transform: translateY(1px)",
-		// Size: set on the button itself, or inherited from a `.small`/`.large`
-		// parent (e.g. a buttonGroup), so a container can size all its buttons at once.
+		// 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",
 		"&.large, .large > &": "font-size:1.4em border-radius:$s-radius-lg",
 	},
-	// A bare glyph in a square hit area: no fill and no edge, just ink that lifts
-	// on hover. Deliberately *not* a `.s-s` surface — chrome that sits beside a
-	// title (a ✕, a ☰) should read as an affordance on the bar, not as
-	// another button competing with it, and a filled or outlined box around a
-	// 16px glyph is exactly what makes a top bar look busy.
+	// Deliberately *not* a `.s-s` surface: chrome sitting beside a title (a ✕, a ☰)
+	// should read as an affordance on the bar, not as another button competing with it.
 	".s-icon-btn": {
 		"&":
 			"display:inline-flex align-items:center justify-content:center flex-shrink:0 " +
 			"width:2rem height:2rem p:0 border:0 background:transparent cursor:pointer " +
 			"fg:$s-muted r:$s-radius-sm line-height:1 font-size:1rem text-decoration:none " +
 			"transition: color 0.12s, background 0.12s;",
-		// The container sizes the glyph, rather than trusting whatever the caller
-		// passed: a row of icon buttons only reads as a row when every glyph in it
-		// is the same size, and the caller of one of them can't know about the
-		// others. CSS beats the `width`/`height` attributes the icon set writes, so
-		// `iconButton({ icon: trash2 })` and a hand-sized glyph come out alike; an
-		// `attrs` override still wins over this, being an inline style. The same
-		// rule is on `.s-btn` above and on a floating menu's rows in menu.ts, so
-		// one `1.25em` governs the lot. (`S.main`'s nav rows are deliberately out
-		// of it — see the note there.)
+		// As on `.s-btn`: the container sizes the glyph so a row of icon buttons reads
+		// as a row. CSS beats the `width`/`height` attributes the icon set writes; an
+		// `attrs` override still wins over this, being an inline style.
 		"> svg": "width:1.25em height:1.25em",
-		// The ink resolves against whatever surface it sits on, so one treatment
-		// works on the page, in a box header, and on a coloured bar alike.
 		"&: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",
@@ -117,13 +116,12 @@ A.insertGlobalCss({
 
 /**
  * A bare glyph in a square hit area — no fill, no border, just ink that lifts on
- * hover. The quiet end of the button family, for chrome that has to sit beside
- * something more important without competing with it: a ✕ on a box, the ☰ a
- * routed `S.main()` puts in its top bar, the verbs in a
- * {@link Panel.actions | page's actions}.
+ * hover. For chrome that has to sit beside something more important without
+ * competing with it: a ✕ on a box, the ☰ a routed `S.main()` puts in its top bar,
+ * the verbs in a {@link Panel.actions | page's actions}.
  *
  * Reach for {@link button} instead whenever the thing has a name worth reading;
- * an icon alone is only unambiguous for a handful of universal actions.
+ * an icon alone is unambiguous only for a handful of universal actions.
  *
  * @example
  * ```ts
@@ -140,16 +138,16 @@ export function iconButton(opts: IconButtonOptions): void {
 	A(`${tag}.s-icon-btn`, opts.attrs, () => {
 		applyActionBehavior(opts);
 		A("aria-label=", opts.ariaLabel);
+		if (opts.key) applyKey(opts.key, opts.ariaLabel, undefined, opts.disabled);
 		drawSlot(opts.icon);
 	});
 }
 
 /**
- * The link-or-button plumbing {@link button} and {@link iconButton} share:
- * href/type, disabling, label and click. A disabled link keeps `role=button`
- * and `aria-disabled` but loses its `href` — an anchor without one is out of
- * the tab order and follows nothing, which is what makes it as disabled as
- * the `<button>` form's real `disabled` attribute.
+ * The link-or-button plumbing {@link button} and {@link iconButton} share. A
+ * disabled link keeps `role=button` and `aria-disabled` but loses its `href`: an
+ * 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: {
 	href?: string;
@@ -168,6 +166,30 @@ function applyActionBehavior(o: {
 	if (o.click && !o.disabled) A("click=", 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.
+ *
+ * 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) });
+	// 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) {
+		A("aria-keyshortcuts=", formatKey(key, true));
+		bindKey(key, typeof content === "string" ? content : label, () => el.click());
+	}
+}
+
 /**
  * A button. Tonal and outlined variants show a border; filled variants rely on
  * their solid background for affordance.
@@ -197,13 +219,14 @@ export function button(opts: ButtonOptions | Slot = {}): void {
 
 	const tag = o.href != null ? "a" : "button";
 
-	// A bare `.s-s` is a filled accent surface defaulting to `.primary` (see
-	// theme.ts) — the signature CTA. The caller's `attrs` simply names another
-	// role (`.danger`, `.neutral`, a custom `.brand`) or variant (`.outlined`); no
-	// role detection needed, since the default lives in CSS, not here.
+	// 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);
 		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);
 
 		drawSlot(o.icon);
 		drawSlot(o.content);

package/src/components/buttonChooser.ts

@@ -49,8 +49,7 @@ export function buttonChooser(opts: ButtonChooserOptions): void {
 			attrs: opts.attrs,
 			buttons: Object.entries(opts.options).map(([id, label]) => ({
 				content: label,
-				// Icon-only options (draw-function labels) get the id as their
-				// accessible name; plain-text labels speak for themselves.
+				// Icon-only (draw-function) labels get the id as their accessible name.
 				ariaLabel: typeof label === "function" ? id : undefined,
 				attrs: selected === id ? ".primary" : ".neutral",
 				click: () => {
@@ -61,7 +60,6 @@ export function buttonChooser(opts: ButtonChooserOptions): void {
 	});
 
 	if (opts.name) {
-		// Hidden input carries the value into native form submission.
 		A(() => A("input type=hidden name=", opts.name, "value=", opts.bind.value ?? ""));
 	}
 }

package/src/components/checkbox.ts

@@ -19,8 +19,7 @@ A.insertGlobalCss({
 		"&": "display:flex flex-direction:column gap:$1",
 		"> label": "display:flex align-items:center gap:$2 cursor:pointer user-select:none",
 		"> label:has(input:disabled)": "cursor:not-allowed opacity:0.45 filter:saturate(0.6)",
-		// Native control: size and brand accent-color come from the CSS reset; here we
-		// just strip the margin and let it inherit the label's cursor (pointer / not-allowed).
+		// Size and accent-color come from the CSS reset; here, the margin and the label's cursor.
 		"input": "cursor:inherit m:0",
 	},
 });