staffa 0.15.0 → 0.16.0

package/dist/components/select.js

@@ -22,15 +22,13 @@ A.insertGlobalCss({
 export function select(opts) {
     drawField(opts, (id, isInvalid) => {
         A("div.s-select_wrap", () => {
-            // On the <select> itself, like every other field control — an
-            // aria-label on the wrapper div would label nothing.
+            // Control attrs go on the <select>: on the wrapper div they'd label nothing.
             A("select.s-input", opts.inputAttrs, () => {
                 applyControlAttrs(opts, id, isInvalid);
                 A("change=", (e) => {
                     if (opts.bind)
                         opts.bind.value = e.target.value;
                 });
-                // Render options reactively; re-runs when options list or selected value changes.
                 A(() => {
                     const raw = typeof opts.options === "function" ? opts.options() : opts.options;
                     const current = (opts.bind?.value ?? "");

package/dist/components/tabs.d.ts

@@ -37,16 +37,14 @@ export interface TabsOptions {
 }
 /**
  * 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 {@link tabs} puts its tab strip in, and what the routed
- * {@link 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 {@link revealInStrip} with that child.
+ * {@link tabs} puts its tab strip in one, and the routed {@link 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. {@link revealInStrip} brings
+ * one of its children into view.
  *
  * @example
  * ```ts
@@ -67,10 +65,9 @@ export declare function revealInStrip(el: HTMLElement): void;
  * 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 {@link scrollStrip});
+ * selecting a tab that's out of view — with the arrow keys, or a `bind` written
+ * from elsewhere — scrolls it back in.
  *
  * @example
  * ```ts

package/dist/components/tabs.js

@@ -1,17 +1,11 @@
 import A from "aberdeen";
 import { drawSlot, uniqueId } from "../core.js";
 import { mk } from "../icons-helpers.js";
-// Chevrons for the scroll buttons, as inline SVG (the icon set's own helper, so
-// no icon data comes along) rather than `‹`/`›` characters — matching Lucide's
-// `chevron-left`/`chevron-right`.
+// Lucide's chevrons, inlined via the icon set's helper so no icon data tags along.
 const chevronLeft = mk('<path d="m15 18-6-6 6-6"/>');
 const chevronRight = mk('<path d="m9 18 6-6-6-6"/>');
 A.insertGlobalCss({
-    // A row that scrolls sideways once its content outgrows it, with a ‹ / ›
-    // button appearing over whichever end still has something to reach. Its own
-    // scrollbar is hidden — a raw scrollbar under a row of chrome reads as a
-    // mistake — so those buttons, and the fade they sit in, are the affordance.
-    // Shared by `tabs()` and the shell's breadcrumb stack; see `scrollStrip()`.
+    // See `scrollStrip()`. Shared by `tabs()` and the shell's breadcrumb stack.
     ".s-strip": {
         // The positioning context the buttons overlay from.
         "&": "position:relative display:flex min-width:0",
@@ -22,35 +16,33 @@ A.insertGlobalCss({
             "overflow-x:auto overflow-y:hidden scrollbar-width:none scroll-behavior:smooth",
         "> .s-strip-row::-webkit-scrollbar": "display:none",
         // The buttons overlay the row's ends rather than sitting beside it, so no
-        // width is reserved when there's nothing to scroll — and the content slides
-        // out from under a fade instead of stopping at a hard edge.
+        // width is reserved when there's nothing to scroll.
         "> .s-strip-btn": "position:absolute top:0 bottom:0 z-index:1 display:none align-items:center justify-content:center " +
             "width:2.4em border:0 padding:0 cursor:pointer fg:$s-muted " +
             "transition: color 0.15s;",
         "> .s-strip-btn:hover": "fg:$s-text",
         "> .s-strip-btn-left": "left:0 justify-content:flex-start background: linear-gradient(to right, $s-bg 45%, transparent)",
         "> .s-strip-btn-right": "right:0 justify-content:flex-end background: linear-gradient(to left, $s-bg 45%, transparent)",
-        // Shown only for the direction there is actually something to scroll towards,
-        // so the pair doubles as a position indicator.
+        // Shown only where there is something to scroll towards, so the pair doubles
+        // as a position indicator.
         "&.s-can-left > .s-strip-btn-left, &.s-can-right > .s-strip-btn-right": "display:flex",
     },
     ".s-tabs": {
         "&": "display:flex flex-direction:column gap:$3",
-        // The bar owns the hairline, so it runs the full width — under the scroll
-        // buttons too.
+        // The bar, not the strip, owns the hairline, so it runs the full width.
         ".s-tabbar": "border-bottom: 1px solid $s-faint;",
         ".s-tablist": "gap:$1 align-items:stretch " +
-            // Pulls the strip 1px down over the bar's hairline, so the active tab's
-            // underline lands *on* it rather than stacking above it. On the strip, not
-            // the tabs: a negative margin inside a scroll container is overflow.
+            // Pulls the strip down over the bar's hairline, so the active tab's underline
+            // lands *on* it. On the strip, not the tabs: a negative margin inside a
+            // scroll container is overflow.
             "margin-bottom:-1px",
         ".s-tab": "display:inline-flex align-items:center gap:$2 cursor:pointer background:transparent " +
             "border:0 color: $s-muted; font-weight:600 padding: 0.6em 0.9em; white-space:nowrap " +
             "border-bottom: 3px solid transparent; " +
             "transition: color 0.15s, background 0.15s, border-color 0.15s;",
         ".s-tab:hover:not(:disabled), .s-tab[aria-selected=true]": "color: $s-text;",
-        // An inset ring: the strip is a scroll container, so it clips its own
-        // painting, and an outset ring on the first/last tab would be shaved off.
+        // An inset ring: the strip clips its own painting, so an outset ring on the
+        // first/last tab would be shaved off.
         ".s-tab:focus-visible": "outline:none box-shadow: inset 0 0 0 2px $s-focus; r: $s-radius;",
         ".s-tab[aria-selected=true]": "border-image: $s-gradient 1;",
         ".s-tabpanel": "display:block",
@@ -58,16 +50,14 @@ A.insertGlobalCss({
 });
 /**
  * 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 {@link tabs} puts its tab strip in, and what the routed
- * {@link 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 {@link revealInStrip} with that child.
+ * {@link tabs} puts its tab strip in one, and the routed {@link 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. {@link revealInStrip} brings
+ * one of its children into view.
  *
  * @example
  * ```ts
@@ -94,8 +84,8 @@ export function revealInStrip(el) {
     const row = el.parentElement;
     if (!row || !el.isConnected)
         return;
-    // The overlays are 2.4em wide; clearing a little more than that keeps the
-    // revealed item from sitting right against one.
+    // The overlays are 2.4em wide; clear a little more, so the revealed item
+    // doesn't sit right against one.
     const pad = parseFloat(getComputedStyle(row).fontSize) * 2.6;
     const box = el.getBoundingClientRect(), strip = row.getBoundingClientRect();
     const left = box.left - strip.left, right = box.right - strip.right;
@@ -108,10 +98,9 @@ export function revealInStrip(el) {
  * 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 {@link scrollStrip});
+ * selecting a tab that's out of view — with the arrow keys, or a `bind` written
+ * from elsewhere — scrolls it back in.
  *
  * @example
  * ```ts
@@ -123,11 +112,9 @@ export function revealInStrip(el) {
  */
 export function tabs(opts) {
     const groupId = uniqueId("tabs");
-    // Resolve a tab's selection key (its id, or its index as a string).
     const keyOf = (tab, index) => tab.id ?? String(index);
-    // Selection state: caller-provided binding, or internal.
     const $sel = opts.bind ?? A.proxy(keyOf(opts.tabs[0] ?? { label: "" }, 0));
-    // If the current value isn't a valid tab key, reset to the first tab.
+    // A bound value that names no tab falls back to the first one.
     if (opts.tabs.length > 0 && !opts.tabs.some((t, i) => keyOf(t, i) === A.peek(() => $sel.value))) {
         $sel.value = keyOf(opts.tabs[0], 0);
     }
@@ -149,9 +136,7 @@ export function tabs(opts) {
                             const selected = $sel.value === key;
                             A("aria-selected=", selected ? "true" : "false");
                             A("tabindex=", selected ? "0" : "-1");
-                            // Selecting a tab that's (partly) scrolled out brings it into
-                            // view, so the strip follows the selection however it was made:
-                            // a click, the arrow keys, or a `bind` written from elsewhere.
+                            // So the strip follows the selection however it was made.
                             if (selected)
                                 requestAnimationFrame(() => revealInStrip(tabEl));
                         });
@@ -179,34 +164,31 @@ export function tabs(opts) {
     });
 }
 /**
- * One of the two scroll buttons overlaying the ends of the row. `dir` is -1 for
- * the left one and 1 for the right. Most of a width at a time (not one item at a
- * time): the row scrolls smoothly, so a nudge that moved a single tab or crumb
- * would read as a twitch.
+ * One of the two scroll buttons overlaying the ends of the row (`dir` is -1 for
+ * left, 1 for right). It scrolls most of a width at a time: a nudge of a single
+ * tab or crumb would read as a twitch.
  */
 function drawScrollButton(row, dir) {
     A(`button.s-strip-btn.s-strip-btn-${dir < 0 ? "left" : "right"} type=button`, () => {
-        // The row's own items are the real control; this is a convenience it offers
-        // a mouse. Keeping it out of the tab order means Tab still steps from the
-        // row straight into whatever follows.
+        // A mouse convenience only — out of the tab order, so Tab still steps from
+        // the row straight into whatever follows.
         A("tabindex=-1 aria-hidden=true");
         A("click=", () => row.scrollBy({ left: dir * row.clientWidth * 0.8, behavior: "smooth" }));
         (dir < 0 ? chevronLeft : chevronRight)({ size: "1.1em" });
     });
 }
 /**
- * Keep the `.s-can-left` / `.s-can-right` classes on the strip in step with what
- * there is left to scroll towards, so each button appears exactly when it has
- * somewhere to go. Watches the row's own scrolling *and* its size — and its
- * children's, since items arriving or leaving (a pushed page's crumb, a tab)
- * changes the answer without any scrolling at all.
+ * Keep the strip's `.s-can-left` / `.s-can-right` classes in step with what there
+ * is left to scroll towards. Watches the row's scrolling and its size — and its
+ * children's, since items arriving or leaving change the answer without any
+ * scrolling at all.
  */
 function watchScroll(row) {
     const strip = row.parentElement;
     if (!strip || typeof ResizeObserver === "undefined")
         return; // No-op outside the browser.
     const update = () => {
-        // A sub-pixel slack: fractional layout widths otherwise leave a permanent
+        // Sub-pixel slack: fractional layout widths otherwise leave a permanent
         // half-pixel of "scrollable" at an end that is plainly already reached.
         const max = row.scrollWidth - row.clientWidth;
         strip.classList.toggle("s-can-left", row.scrollLeft > 1);
@@ -215,11 +197,9 @@ function watchScroll(row) {
     row.addEventListener("scroll", update, { passive: true });
     const ro = new ResizeObserver(update);
     ro.observe(row);
-    // The children are watched through one observer that follows the row's live
-    // contents, so a strip whose items come and go keeps answering correctly.
-    // Removed children are unobserved: a strip whose items churn (the breadcrumb
-    // row redraws on navigation) would otherwise grow the observation list — and
-    // retain the detached elements — without bound.
+    // One observer follows the row's live children. Removed ones must be
+    // unobserved: a strip whose items churn (the breadcrumbs, on navigation) would
+    // otherwise retain every detached element for as long as it lives.
     const mo = typeof MutationObserver === "undefined" ? undefined : new MutationObserver((records) => {
         for (const record of records) {
             for (const el of record.addedNodes)

package/dist/components/textline.d.ts

@@ -24,11 +24,9 @@ export interface TextlineOptions extends FieldOptions {
     change?: (event: Event) => void;
 }
 /**
- * A single-line text input — covering text, passwords, numbers, email, dates and
- * the other line-oriented `<input>` types.
- *
- * Renders inside the standard {@link drawField} chrome (label, control,
- * help/error), so it aligns cleanly inside a {@link form}.
+ * A single-line text input — text, passwords, numbers, email, dates and the other
+ * line-oriented `<input>` types. Renders inside the standard {@link drawField}
+ * chrome (label, control, help/error), so it aligns cleanly inside a {@link form}.
  *
  * @example
  * ```ts

package/dist/components/textline.js

@@ -1,11 +1,9 @@
 import A from "aberdeen";
 import { applyControlAttrs, drawField } from "./field.js";
 /**
- * A single-line text input — covering text, passwords, numbers, email, dates and
- * the other line-oriented `<input>` types.
- *
- * Renders inside the standard {@link drawField} chrome (label, control,
- * help/error), so it aligns cleanly inside a {@link form}.
+ * A single-line text input — text, passwords, numbers, email, dates and the other
+ * line-oriented `<input>` types. Renders inside the standard {@link drawField}
+ * chrome (label, control, help/error), so it aligns cleanly inside a {@link form}.
  *
  * @example
  * ```ts

package/dist/components/toast.d.ts

@@ -5,9 +5,7 @@ export interface ToastOptions {
     message: Slot;
     /** Optional bold title above the message. */
     title?: Slot;
-    /**
-     * Colour role. Defaults to `"neutral"`.
-     */
+    /** Colour role. Defaults to `"neutral"`. */
     type?: "success" | "danger" | "warning" | "neutral";
     /**
      * Auto-dismiss delay in milliseconds. Defaults to `6000`.

package/dist/components/toast.js

@@ -22,15 +22,14 @@ let toastCount = 0;
 // Keyed by stable ID so A.onEach scopes are per-toast — removing one never re-renders others.
 const toasts = A.proxy({});
 mountPortal(() => {
-    // In initial peek is here to NOT subscribe to changes once `toasts` first becomes non empty,
-    // leaving the container in the DOM forever after. (So as not to cut of hide animations.)
+    // The peek keeps this scope from resubscribing once `toasts` is non-empty, so the
+    // container stays in the DOM afterwards and exit animations aren't cut off.
     if (A.peek(() => A.isEmpty(toasts)) && A.isEmpty(toasts))
         return;
     A("div.s-toasts", () => {
         A.onEach(toasts, (entry) => {
             const { opts, id } = entry;
             const role = opts.type === "danger" || opts.type === "warning" ? "alert" : "status";
-            // "neutral" (the default) is a neutral surface; the rest are accent surfaces.
             const surface = opts.type == null || opts.type === "neutral" ? "neutral" : opts.type;
             const duration = opts.duration ?? 6000;
             let timer;

package/dist/components/tooltip.d.ts

@@ -12,11 +12,10 @@ export interface TooltipOptions {
     attrs?: Attributes;
 }
 /**
- * Attaches a tooltip to the current element: adds hover/focus handlers via
- * {@link 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.
  *
  * @example
  * ```ts

package/dist/components/tooltip.js

@@ -1,8 +1,7 @@
 import A from "aberdeen";
 import { drawSlot, mountPortal } from "../core.js";
-// The tip is a `.s-s.neutral.shadow` surface (it portals to <body>, so it renders at
-// the page's next neutral shade), which provides its background, ink, border,
-// radius and elevation.
+// Background, ink, border, radius and elevation come from the `.s-s.neutral.shadow`
+// surface; portalled to <body>, it renders at the page's next neutral shade.
 A.insertGlobalCss({
     ".s-tt-tip": {
         "&": "position:fixed z-index:500 " +
@@ -12,8 +11,7 @@ A.insertGlobalCss({
     },
 });
 // ─── Global portal state ────────────────────────────────────────────────────
-// At most one tooltip is visible at a time. The anchor is the element the
-// handlers were attached to (its bounding rect drives positioning).
+// At most one tooltip at a time; the anchor is the element whose rect positions it.
 const $ttActive = A.proxy(undefined);
 let hideTimer = null;
 // Hide tooltip when the page scrolls (anchor has moved).
@@ -96,11 +94,10 @@ mountPortal(() => {
 });
 // ─── Public component ────────────────────────────────────────────────────────
 /**
- * Attaches a tooltip to the current element: adds hover/focus handlers via
- * {@link 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.
  *
  * @example
  * ```ts

package/dist/core.d.ts

@@ -1,10 +1,8 @@
 /**
- * Shared building blocks for the Staffa component library.
- *
- * Every component in Staffa is "just an Aberdeen draw function": a plain function
- * that takes a single, strongly typed options object and emits DOM through
- * Aberdeen's {@link A} function. This module defines the option-type hierarchy
- * that all components build on, plus a couple of tiny helpers.
+ * Shared building blocks for the Staffa component library: the option-type
+ * hierarchy every component builds on, plus a couple of tiny helpers. A
+ * component is just an Aberdeen draw function — one typed options object in,
+ * DOM out through {@link A}.
  */
 /**
  * An Aberdeen attribute/style/class string, e.g. `"display:flex gap:$3 .my-class"`.
@@ -51,9 +49,9 @@ export interface ContentOptions {
 }
 /**
  * Shell width — not viewport width — at or below which the app shell goes
- * "narrow": the nav sidebar collapses to a hamburger, and a routed shell
- * has room for exactly one full-bleed column. Shared by the `@container` queries
- * that do the switching and by the JS that has to agree with them.
+ * "narrow": the nav sidebar collapses to a hamburger, and a routed shell has room
+ * for exactly one full-bleed column. Shared by the `@container` queries that do
+ * the switching and by the JS that has to agree with them.
  */
 export declare const NARROW_PX = 640;
 /** Generates a process-unique id, used to wire `<label for>` to its control. */
@@ -66,25 +64,20 @@ export declare function uniqueId(prefix?: string): string;
 export declare function drawSlot<Args extends unknown[] = []>(slot: Slot<Args> | undefined, ...args: Args): void;
 /**
  * Move keyboard focus to the first focusable element inside `container`, skipping
- * disabled, `aria-disabled`, `tabindex=-1` and hidden ones. When `prefer` (a
- * selector) matches a focusable element it wins — e.g. a menu's current item — so
- * opening lands where the user already is. Returns whether anything was focused.
+ * disabled, `aria-disabled`, `tabindex=-1` and hidden ones. A `prefer` selector,
+ * where it matches a focusable element, wins — e.g. a menu's current item.
+ * Returns whether anything was focused.
  *
- * Shared by overlays (the floating menu, dialogs) so "open → focus the right
- * thing" behaves identically everywhere. Call it after the element is in the DOM
- * and laid out (typically inside a `requestAnimationFrame`).
+ * Shared by the overlays (floating menu, dialogs). Call it once the element is in
+ * the DOM and laid out — typically inside a `requestAnimationFrame`.
  */
 export declare function focusFirst(container: HTMLElement, prefer?: string): boolean;
 /**
  * Mount a portal (tooltip, toast, menu, dialog, …) directly into `<body>`.
- * Must be called at module top level, where Aberdeen's root scope (whose
- * element is `document.body`) is current. Separate `A.mount`s sharing a parent
- * can't tell their nodes apart, but sibling scopes within the root scope track
- * their positions, so portals coexist without wrapper elements and add nothing
- * to the DOM while they draw nothing.
- *
- * Scope creation is deferred a microtask so that an app drawing into `<body>`
- * at module top level gets its content *before* the portals, keeping overlays
- * at the end of the document.
+ * Must be called at module top level, where Aberdeen's root scope (whose element
+ * is `document.body`) is current: sibling scopes there track their positions, so
+ * portals coexist without wrapper elements — separate `A.mount`s sharing a parent
+ * could not. Scope creation is deferred a microtask, so an app drawing into
+ * `<body>` gets its content first and the overlays stay at the end.
  */
 export declare function mountPortal(draw: () => void): void;

package/dist/core.js

@@ -1,9 +1,9 @@
 import A from "aberdeen";
 /**
  * Shell width — not viewport width — at or below which the app shell goes
- * "narrow": the nav sidebar collapses to a hamburger, and a routed shell
- * has room for exactly one full-bleed column. Shared by the `@container` queries
- * that do the switching and by the JS that has to agree with them.
+ * "narrow": the nav sidebar collapses to a hamburger, and a routed shell has room
+ * for exactly one full-bleed column. Shared by the `@container` queries that do
+ * the switching and by the JS that has to agree with them.
  */
 export const NARROW_PX = 640;
 let idCounter = 0;
@@ -28,13 +28,12 @@ export function drawSlot(slot, ...args) {
 const FOCUSABLE_SELECTOR = "a[href], button, input, select, textarea, [tabindex]";
 /**
  * Move keyboard focus to the first focusable element inside `container`, skipping
- * disabled, `aria-disabled`, `tabindex=-1` and hidden ones. When `prefer` (a
- * selector) matches a focusable element it wins — e.g. a menu's current item — so
- * opening lands where the user already is. Returns whether anything was focused.
+ * disabled, `aria-disabled`, `tabindex=-1` and hidden ones. A `prefer` selector,
+ * where it matches a focusable element, wins — e.g. a menu's current item.
+ * Returns whether anything was focused.
  *
- * Shared by overlays (the floating menu, dialogs) so "open → focus the right
- * thing" behaves identically everywhere. Call it after the element is in the DOM
- * and laid out (typically inside a `requestAnimationFrame`).
+ * Shared by the overlays (floating menu, dialogs). Call it once the element is in
+ * the DOM and laid out — typically inside a `requestAnimationFrame`.
  */
 export function focusFirst(container, prefer) {
     const ok = (el) => el instanceof HTMLElement &&
@@ -49,15 +48,11 @@ export function focusFirst(container, prefer) {
 }
 /**
  * Mount a portal (tooltip, toast, menu, dialog, …) directly into `<body>`.
- * Must be called at module top level, where Aberdeen's root scope (whose
- * element is `document.body`) is current. Separate `A.mount`s sharing a parent
- * can't tell their nodes apart, but sibling scopes within the root scope track
- * their positions, so portals coexist without wrapper elements and add nothing
- * to the DOM while they draw nothing.
- *
- * Scope creation is deferred a microtask so that an app drawing into `<body>`
- * at module top level gets its content *before* the portals, keeping overlays
- * at the end of the document.
+ * Must be called at module top level, where Aberdeen's root scope (whose element
+ * is `document.body`) is current: sibling scopes there track their positions, so
+ * portals coexist without wrapper elements — separate `A.mount`s sharing a parent
+ * could not. Scope creation is deferred a microtask, so an app drawing into
+ * `<body>` gets its content first and the overlays stay at the end.
  */
 export function mountPortal(draw) {
     queueMicrotask(() => A(draw));

package/dist/icons-helpers.d.ts

@@ -39,8 +39,8 @@ export interface IconDefaults {
  */
 export declare function setDefaults(opts: Partial<IconDefaults>): void;
 /**
- * Turn a piece of inner-SVG markup into an icon draw-function. The returned
- * function emits a freshly-built `<svg>` into the current Aberdeen scope,
- * applying the {@link IconOptions} (or the module defaults).
+ * Turn a piece of inner-SVG markup into an icon draw-function: it emits a freshly
+ * built `<svg>` into the current Aberdeen scope, applying the {@link IconOptions}
+ * (or the module defaults).
  */
 export declare function mk(inner: string): (opts?: IconOptions) => void;

package/dist/icons-helpers.js

@@ -19,25 +19,20 @@ export function setDefaults(opts) {
     Object.assign(defaults, opts);
 }
 /**
- * Draw a single icon: build one `<svg>` through Aberdeen (applying the
+ * The shared body behind every icon: build one `<svg>` through Aberdeen (from the
  * {@link IconOptions} or the module defaults) and fill in its inner markup.
- *
- * This is the shared body behind every icon. {@link mk} hands it the icon's
- * `inner` markup, so the per-icon closures stay tiny instead of each carrying
- * a copy of this logic.
  */
 function drawIcon(inner, opts) {
     const size = opts.size ?? defaults.size;
     const el = A('svg.s-icon aria-hidden=true viewBox="0 0 24 24" fill=none', "width=", size, "height=", size, "stroke=", opts.color ?? defaults.color, "stroke-width=", opts.strokeWidth ?? defaults.strokeWidth, "stroke-linecap=", opts.cap ?? defaults.cap, "stroke-linejoin=", opts.join ?? defaults.join, opts.attrs);
-    // Drop the primitives in via innerHTML: setting it on the `<svg>` itself
-    // makes the parser put the children in the SVG namespace. (Aberdeen's
-    // `html=` builds them in the HTML namespace, leaving them non-rendering.)
+    // innerHTML on the `<svg>` itself puts the children in the SVG namespace;
+    // Aberdeen's `html=` would build them in the HTML namespace, non-rendering.
     el.innerHTML = inner;
 }
 /**
- * Turn a piece of inner-SVG markup into an icon draw-function. The returned
- * function emits a freshly-built `<svg>` into the current Aberdeen scope,
- * applying the {@link IconOptions} (or the module defaults).
+ * Turn a piece of inner-SVG markup into an icon draw-function: it emits a freshly
+ * built `<svg>` into the current Aberdeen scope, applying the {@link IconOptions}
+ * (or the module defaults).
  */
 export function mk(inner) {
     return (opts = {}) => drawIcon(inner, opts);

package/dist/index.d.ts

@@ -27,9 +27,11 @@
  * Every component takes a single typed options object (see each function's
  * docs). The options object — or parts of it — may be an Aberdeen proxy, in
  * which case the component re-renders the affected parts in place when you
- * mutate it. See `AGENTS.md` for the design philosophy.
+ * mutate it. See `README.md` for the design philosophy.
  */
 export { setDarkMode, getDarkMode } from "./theme.js";
+export { formatKey, bindKey } from "./keys.js";
+export { showKeyHelp, setKeyHelp } from "./components/keyhelp.js";
 export { autocomplete, type AutocompleteOptions, type AutocompleteOptionInput } from "./components/autocomplete.js";
 export { box, type BoxOptions } from "./components/box.js";
 export { button, iconButton, type ButtonOptions, type IconButtonOptions } from "./components/button.js";

package/dist/index.js

@@ -27,12 +27,13 @@
  * Every component takes a single typed options object (see each function's
  * docs). The options object — or parts of it — may be an Aberdeen proxy, in
  * which case the component re-renders the affected parts in place when you
- * mutate it. See `AGENTS.md` for the design philosophy.
+ * mutate it. See `README.md` for the design philosophy.
  */
-// Importing the theme module installs spacing vars, the reactive theme and the
-// base stylesheet. Customise it from your app with A.insertGlobalCss (see
-// theme.ts); toggle modes with setDarkMode / getDarkMode.
+// Importing theme.js installs the spacing vars, the reactive theme and the base
+// stylesheet.
 export { setDarkMode, getDarkMode } from "./theme.js";
+export { formatKey, bindKey } from "./keys.js";
+export { showKeyHelp, setKeyHelp } from "./components/keyhelp.js";
 export { autocomplete } from "./components/autocomplete.js";
 export { box } from "./components/box.js";
 export { button, iconButton } from "./components/button.js";