staffa 0.14.0 → 0.16.0

package/dist/components/autocomplete.js

@@ -13,8 +13,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;",
@@ -235,9 +235,8 @@ export function autocomplete(opts) {
             }
         }
         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/dist/components/box.js

@@ -2,15 +2,10 @@ import A from "aberdeen";
 import { drawSlot } from "../core.js";
 import { x as closeIcon } from "../icons.js";
 import { iconButton } from "./button.js";
-// 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.
@@ -19,11 +14,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",
     },
 });
@@ -50,12 +42,11 @@ A.insertGlobalCss({
 export function box(opts = {}) {
     const o = 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);
@@ -77,9 +68,8 @@ export function box(opts = {}) {
     });
 }
 /**
- * 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) {
     iconButton({

package/dist/components/button.d.ts

@@ -7,6 +7,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. */
@@ -34,6 +40,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"`,
@@ -48,13 +64,12 @@ export interface ButtonOptions {
 }
 /**
  * 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

package/dist/components/button.js

@@ -1,59 +1,42 @@
 import A from "aberdeen";
 import { drawSlot } from "../core.js";
-// 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.
+import { bindKey, formatKey } from "../keys.js";
+import { addTooltip } from "./tooltip.js";
+// 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": {
         "&": "display:inline-flex align-items:center justify-content:center gap:$2 " +
             "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",
         // The glyph rides the font size, so it scales with the hit area.
@@ -63,13 +46,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
@@ -86,15 +68,16 @@ export function iconButton(opts) {
     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) {
     if (o.href != null) {
@@ -112,6 +95,29 @@ 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, 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) });
+    // 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.
@@ -139,14 +145,16 @@ function applyActionBehavior(o) {
 export function button(opts = {}) {
     const o = typeof opts === "string" || typeof opts === "function" ? { content: opts } : opts;
     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/dist/components/buttonChooser.js

@@ -23,8 +23,7 @@ export function buttonChooser(opts) {
             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: () => {
@@ -34,7 +33,6 @@ export function buttonChooser(opts) {
         });
     });
     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/dist/components/checkbox.js

@@ -5,8 +5,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",
     },
 });

package/dist/components/dialog.d.ts

@@ -20,10 +20,17 @@ export interface DialogOptions {
      */
     allowCancel?: boolean;
     /**
-     * When set to `true` (default) the model will be destroyed when the `dialog()`-calling
-     * scope is destroyed.
+     * When `true` (default), the dialog is destroyed when the scope that called
+     * `dialog()` is destroyed.
      */
     cancelWithScope?: boolean;
+    /**
+     * Leave the keyboard shortcuts behind this dialog working, instead of owning
+     * the keyboard the way a modal does. For overlays that inform rather than
+     * interrupt — the `?` shortcut overview is one. Esc still closes it first,
+     * whatever it meant before.
+     */
+    keyboardTransparent?: boolean;
     /**
      * Dialog body. A {@link Slot} whose draw-function receives a `close()` function
      * — call it to dismiss the dialog programmatically. (A plain string renders as

package/dist/components/dialog.js

@@ -3,20 +3,19 @@ import { drawSlot, mountPortal, focusFirst } from "../core.js";
 import { button } from "./button.js";
 import { buttonGroup } from "./buttonGroup.js";
 import { textline } from "./textline.js";
+import { bindKey, claimKeyboard, keyboardOwner } from "../keys.js";
 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;",
         "&.hidden": "opacity:0 pointer-events:none",
     },
-    // The dialog panel is a `.s-s.neutral.extra-shadow` surface: border, radius (lg)
-    // and the deep floating shadow come from the surface itself (see theme.ts).
+    // Border, radius and the deep floating shadow come from the panel's
+    // `.s-s.neutral.extra-shadow` surface (see theme.ts).
     ".s-dialog": {
         "&": "position:fixed z-index:200 top:50% left:50% " +
             "display:flex flex-direction:column " +
             "transform:translate(-50%,-50%) " +
-            // vw/vh divided by --s-zoom: viewport units shrink with the page-fitting
-            // zoom (see `watchScale` in main.ts), and these caps mean the window.
-            "min-width:20rem max-width:min(calc(90vw/var(--s-zoom,1)),44rem) max-height:min(calc(88vh/var(--s-zoom,1)),800px) " +
+            "min-width:min(20rem,90vw) max-width:min(90vw,44rem) max-height:min(88vh,800px) " +
             "r: $s-radius-lg; overflow:hidden " +
             "transition: opacity 0.2s ease-out, transform 0.2s ease-out;",
         "> header": "display:flex align-items:center gap:$2 padding: $2 $3; " +
@@ -42,19 +41,39 @@ mountPortal(() => {
     A.onEach(dialogs, ({ resolve, opts }, dialogId) => {
         const close = () => { delete dialogs[dialogId]; };
         A.clean(() => {
-            // Fires when this render is torn down — either because $closed became
-            // true (normal close) or because the parent reactive scope was cleaned up.
+            // Fires on a normal close and on parent-scope teardown alike.
             opts.onClose?.();
             resolve();
         });
+        // Return focus to where it was when this dialog opened, so a keyboard
+        // user doesn't lose their place.
+        const prevFocus = document.activeElement;
+        A.clean(() => {
+            if (prevFocus instanceof HTMLElement && document.contains(prevFocus))
+                prevFocus.focus();
+        });
         // 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=", () => {
             if (opts.allowCancel !== false)
                 close();
         });
-        // Dialog itself
         const dialogEl = A("div.s-dialog.neutral.s-s.extra-shadow 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());
+            // 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 —
+            // itself, or with `keyboardTransparent` the modal beneath (or the page)
+            // — so it shadows whatever Esc meant so far, restored on close.
+            const escAt = keyboardOwner();
+            A(() => {
+                const can = opts.allowCancel !== false;
+                bindKey("esc", can ? "Close this dialog" : undefined, can ? close : () => { }, escAt);
+            });
             A(() => {
                 if (opts.header != null) {
                     A("header.s-s.neutral", opts.headerAttrs, () => drawSlot(opts.header));
@@ -69,8 +88,8 @@ mountPortal(() => {
                 }
             });
         });
-        // Once laid out, move focus into the dialog (first focusable element) so it's
-        // keyboard-ready and focus doesn't linger on whatever opened it.
+        // 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); });
     });
@@ -97,31 +116,6 @@ mountPortal(() => {
  * ```
  */
 export function dialog(opts) {
-    if (!dialogCount) {
-        // Install Esc handler the first time we create a dialog
-        document.addEventListener("keydown", (e) => {
-            // A layer above us that consumed Escape (an open floating menu's capture
-            // handler, or a widget inside the dialog like an open autocomplete list)
-            // marks it with preventDefault — the dialog must not also act on it.
-            if (e.key !== "Escape" || e.defaultPrevented)
-                return;
-            const ds = A.unproxy(dialogs);
-            // Search for top-most dialog
-            for (let i = dialogCount; i > 0; i--) {
-                if (ds[i]) {
-                    // A dialog owns Escape, closable or not — handlers beneath it
-                    // must not also act (main()'s nav jump and cooperative page
-                    // handlers check defaultPrevented, or S.isDialogOpen()).
-                    e.preventDefault();
-                    if (ds[i].opts.allowCancel !== false) {
-                        // The clean handler should call resolve and onClose
-                        delete dialogs[i];
-                    }
-                    break;
-                }
-            }
-        });
-    }
     const dialogId = ++dialogCount;
     if (opts.cancelWithScope !== false)
         A.clean(() => { delete dialogs[dialogId]; });

package/dist/components/field.d.ts

@@ -1,11 +1,9 @@
 import { type Bindable, type Slot, type Attributes } from "../core.js";
 /**
  * Options shared by all *form field* components (textline, textarea, checkbox,
- * autocomplete, ...).
- *
- * Fields share a consistent vertical layout: an optional label, the control
- * itself, and optional help/error text below it. {@link form} relies on this
- * shared structure to align groups of fields.
+ * autocomplete, ...). Every field lays out the same way — optional label,
+ * control, optional help/error below — which is what lets {@link form} align
+ * groups of them.
  */
 export interface FieldOptions {
     /** Aberdeen attr/style string applied to the field's wrapper element. */
@@ -34,9 +32,8 @@ export interface FieldOptions {
  * Render the standard field chrome (label + control + help/error) around a
  * caller-supplied control.
  *
- * Each piece is read inside its own small reactive scope, so e.g. flipping
- * `error` on a proxied options object only re-renders the error line — not the
- * control.
+ * Each piece gets its own reactive scope, so flipping `error` on a proxied
+ * options object re-renders just the error line, not the control.
  *
  * @param opts The field options.
  * @param drawControl Receives the resolved `id` and the live "invalid" getter,

package/dist/components/field.js

@@ -9,9 +9,8 @@ A.insertGlobalCss({
     ".s-help": "font-size:0.82em fg:$s-muted",
     ".s-error": "font-size:0.82em fg:$s-danger",
     ".s-input": {
-        // A light inset field, derived from the surrounding surface: the surface
-        // background nudged slightly toward its ink, with the ink as text. Adapts to
-        // whatever surface (and mode) holds the field, no fixed input colour needed.
+        // Derived from the surrounding surface — its background nudged toward its ink —
+        // so the field adapts to any surface and mode, with no fixed input colour.
         "&": "w:100% background: color-mix(in oklab, $s-bg, $s-text 4%); color:$s-text border: 1px solid $s-faint; r:$s-radius padding: 0.55em 0.7em; transition: border-color 0.15s, box-shadow 0.15s;",
         "&:hover:not(:disabled)": "border-color: color-mix(in oklab, $s-text, $s-bg 55%);",
         "&:focus-visible": "border-color:$s-accent box-shadow: 0 0 0 3px $s-focus; outline:none",
@@ -22,9 +21,8 @@ A.insertGlobalCss({
  * Render the standard field chrome (label + control + help/error) around a
  * caller-supplied control.
  *
- * Each piece is read inside its own small reactive scope, so e.g. flipping
- * `error` on a proxied options object only re-renders the error line — not the
- * control.
+ * Each piece gets its own reactive scope, so flipping `error` on a proxied
+ * options object re-renders just the error line, not the control.
  *
  * @param opts The field options.
  * @param drawControl Receives the resolved `id` and the live "invalid" getter,

package/dist/components/form.d.ts

@@ -19,13 +19,11 @@ export interface FormOptions extends ContentOptions {
     actions?: Slot;
 }
 /**
- * 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 ({@link import("./textline").textline} et al.) drop straight
- * in as {@link 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
+ * ({@link import("./textline").textline} et al.) drop straight in as
+ * {@link ContentOptions.content}; the browser's native validation runs on submit,
+ * but the page never reloads.
  *
  * @example
  * ```ts

package/dist/components/form.js

@@ -9,13 +9,11 @@ A.insertGlobalCss({
     },
 });
 /**
- * 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 ({@link import("./textline").textline} et al.) drop straight
- * in as {@link 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
+ * ({@link import("./textline").textline} et al.) drop straight in as
+ * {@link ContentOptions.content}; the browser's native validation runs on submit,
+ * but the page never reloads.
  *
  * @example
  * ```ts
@@ -33,8 +31,7 @@ A.insertGlobalCss({
 export function form(opts = {}) {
     const o = typeof opts === "string" || typeof opts === "function" ? { content: opts } : opts;
     A(`form.s-form`, o.attrs, () => {
-        // Toggle grid class in its own scope so changing layout doesn't recreate
-        // the fields (which would lose focus / input state).
+        // Own scope, so a layout change doesn't recreate the fields (losing focus/input state).
         A(() => {
             A(".grid=", o.layout === 'grid');
         });

package/dist/components/keyhelp.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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, {@link 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 {@link setKeyHelp}. Calling
+ * this while the overview is already up closes it, which is what lets that `?`
+ * toggle.
+ */
+export declare function showKeyHelp(): void;
+/**
+ * Turn the default overview shortcuts off (or back on): `?` — free, like any
+ * unmodified key, whenever nothing is being typed into — and `mod+?`, which
+ * reaches the overview even from inside a text field. On by default.
+ */
+export declare function setKeyHelp(enabled: boolean): void;