staffa 0.15.0 → 0.16.0

package/src/components/select.ts

@@ -38,8 +38,7 @@ A.insertGlobalCss({
 export function select(opts: SelectOptions): void {
 	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);
 
@@ -47,7 +46,6 @@ export function select(opts: SelectOptions): void {
 					if (opts.bind) opts.bind.value = (e.target as HTMLSelectElement).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 ?? "") as string;

package/src/components/tabs.ts

@@ -41,18 +41,12 @@ export interface TabsOptions {
 	contentAttrs?: Attributes;
 }
 
-// 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",
@@ -64,8 +58,7 @@ 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 " +
@@ -73,20 +66,19 @@ A.insertGlobalCss({
 		"> .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 " +
@@ -94,8 +86,8 @@ A.insertGlobalCss({
 			"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",
@@ -104,16 +96,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
@@ -140,8 +130,8 @@ export function scrollStrip(opts: ScrollStripOptions): void {
 export function revealInStrip(el: HTMLElement): void {
 	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;
@@ -153,10 +143,9 @@ export 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
@@ -169,13 +158,11 @@ export function revealInStrip(el: HTMLElement): void {
 export function tabs(opts: TabsOptions): void {
 	const groupId = uniqueId("tabs");
 
-	// Resolve a tab's selection key (its id, or its index as a string).
 	const keyOf = (tab: Tab, index: number) => tab.id ?? String(index);
 
-	// Selection state: caller-provided binding, or internal.
 	const $sel: Bindable<string> = 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);
 	}
@@ -198,9 +185,7 @@ export function tabs(opts: TabsOptions): void {
 							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 as HTMLElement));
 						});
 						if (tab.disabled) A("disabled=true");
@@ -227,16 +212,14 @@ export function tabs(opts: TabsOptions): void {
 }
 
 /**
- * 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: HTMLElement, dir: -1 | 1): void {
 	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" });
@@ -244,17 +227,16 @@ function drawScrollButton(row: HTMLElement, dir: -1 | 1): void {
 }
 
 /**
- * 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: HTMLElement): void {
 	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);
@@ -263,11 +245,9 @@ function watchScroll(row: HTMLElement): void {
 	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) if (el instanceof Element) ro.observe(el);

package/src/components/textline.ts

@@ -40,11 +40,9 @@ export interface TextlineOptions extends FieldOptions {
 }
 
 /**
- * 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/src/components/toast.ts

@@ -8,9 +8,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`.
@@ -54,14 +52,13 @@ let toastCount = 0;
 const toasts = A.proxy({} as Record<number, ToastEntry>);
 
 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;
 

package/src/components/tooltip.ts

@@ -14,9 +14,8 @@ export interface TooltipOptions {
 	attrs?: Attributes;
 }
 
-// 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": {
 		"&":
@@ -29,8 +28,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<{ opts: TooltipOptions; anchor: HTMLElement } | undefined>(undefined);
 let hideTimer: ReturnType<typeof setTimeout> | null = null;
 
@@ -107,11 +105,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/src/core.ts

@@ -1,12 +1,10 @@
 import A from "aberdeen";
 
 /**
- * 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}.
  */
 
 /**
@@ -56,9 +54,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 const NARROW_PX = 640;
 
@@ -84,13 +82,12 @@ 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: HTMLElement, prefer?: string): boolean {
 	const ok = (el: Element): el is HTMLElement =>
@@ -108,15 +105,11 @@ export 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 function mountPortal(draw: () => void): void {
 	queueMicrotask(() => A(draw));

package/src/icons-helpers.ts

@@ -55,12 +55,8 @@ export function setDefaults(opts: Partial<IconDefaults>): void {
 }
 
 /**
- * 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: string, opts: IconOptions): void {
 	const size = opts.size ?? defaults.size;
@@ -74,16 +70,15 @@ function drawIcon(inner: string, opts: IconOptions): void {
 		"stroke-linejoin=", opts.join ?? defaults.join,
 		opts.attrs,
 	) as SVGSVGElement;
-	// 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: string): (opts?: IconOptions) => void {
 	return (opts: IconOptions = {}) => drawIcon(inner, opts);

package/src/index.ts

@@ -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, 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";