staffa 0.14.0 → 0.16.0

package/src/keys.ts

@@ -0,0 +1,300 @@
+import A from "aberdeen";
+import type { Slot } from "./core.js";
+
+/**
+ * Keyboard shortcuts: a registry of live bindings served by one document-level
+ * `keydown` listener, and writing a combination back out the way this platform
+ * writes it. The spelling of a combination is documented on {@link bindKey}.
+ */
+
+/**
+ * Whether this is an Apple platform, where the modifier is ⌘ rather than Ctrl.
+ * `platform` is deprecated but frozen rather than removed, and the user agent
+ * behind it says Macintosh anyway — an iPad asking for the desktop site
+ * included, which is the right answer here.
+ */
+const IS_APPLE = typeof navigator !== "undefined" && /mac|iphone|ipad|ipod/i.test(navigator.platform || navigator.userAgent);
+
+/** Spellings people reach for that aren't `KeyboardEvent.key` values. */
+const ALIASES: Record<string, string> = { esc: "escape", space: " " };
+
+/** How a key is written in a hint, where its canonical name won't do. */
+const GLYPHS: Record<string, string> = { " ": "Space", escape: "Esc", arrowup: "↑", arrowdown: "↓", arrowleft: "←", arrowright: "→" };
+
+/** One registered shortcut, as {@link getActiveKeyBindings} hands them out. */
+export interface KeyBinding {
+	/**
+	 * What it does — a rich-text string or draw function, shown in the shortcut
+	 * overview. Without one, the binding stays out of the overview.
+	 */
+	description?: Slot;
+	/**
+	 * Runs on the keystroke, after `preventDefault()`. Without one, the binding
+	 * only *describes* the key (which is handled elsewhere) — it is listed and
+	 * shadows same-key bindings further out, but the keystroke passes untouched.
+	 */
+	press?: (e: KeyboardEvent) => void;
+	/** Keeps working while a modal owns the keyboard. */
+	global?: boolean;
+	/** The same-key binding this one shadows, restored when this one is removed. */
+	prev?: KeyBinding;
+}
+
+/**
+ * Live bindings, kept per element per canonical key string. The element a
+ * binding is stored at decides when it applies: the keydown handler walks up
+ * the tree from the focused element and takes the first match.
+ */
+const bindings = new WeakMap<Element, Map<string, KeyBinding>>();
+
+/** Elements that claimed the keyboard, in claiming order. The last one rules. */
+const modalStack: Element[] = [];
+
+/**
+ * Give the current element the keyboard, until the returned release function is
+ * called: normal bindings drawn inside it register at it, so they die with it
+ * and never fire once focus (and the walk up from it) has moved to a later
+ * claim — while bindings from outside any claim are silenced, the `global`
+ * ones excepted. What a modal dialog does while it is up.
+ */
+export function claimKeyboard(): () => void {
+	const el = A() as Element | undefined;
+	if (!el) throw new Error("Staffa: claimKeyboard needs a current element");
+	modalStack.push(el);
+	return () => {
+		const i = modalStack.indexOf(el);
+		if (i >= 0) modalStack.splice(i, 1);
+	};
+}
+
+/**
+ * A spec reduced to its canonical form, the registry's index — simply the spec
+ * lower-cased, aliases resolved: an optional `mod+`, an optional `shift+`,
+ * then the `KeyboardEvent.key` value. Throws on anything else, loudly: a
+ * shortcut is invisible until it fails to fire, so a typo must not wait for
+ * the keystroke that needed it.
+ */
+function canonKey(spec: string): string {
+	const [, mod, shift, name] = /^(mod\+)?(shift\+)?(.*)$/i.exec(spec)!;
+	let key = name.toLowerCase();
+	key = ALIASES[key] ?? key;
+	if (!key || (key.length > 1 && /[-+]/.test(key))) {
+		throw new Error(`Staffa: can't parse key "${spec}" — write "k", "f2", "mod+k" or "mod+shift+f2"`);
+	}
+	// The typed character is a combination's one name: `?` is what shift-/ types.
+	if (shift && key.toUpperCase() === key) {
+		throw new Error(`Staffa: "${spec}" — write the shifted character itself ("?", not "shift+/")`);
+	}
+	return (mod ? "mod+" : "") + (shift ? "shift+" : "") + key;
+}
+
+/** The canonical key string for a keystroke, or `null` for one that can't be a shortcut. */
+function canonEvent(e: KeyboardEvent): string | null {
+	// Alt is never bound, nor is Ctrl on a Mac: a keystroke holding one down
+	// belongs to the app, the browser or the OS — not to us.
+	if (e.altKey || (IS_APPLE ? e.ctrlKey : e.metaKey)) return null;
+	const key = e.key.toLowerCase();
+	// Shift counts only where it doesn't already shape the typed character: it
+	// turns k into K and holds during F2, but *is* the difference between / and
+	// ? — and Caps Lock's capitals don't register.
+	const shift = e.shiftKey && (key.length > 1 || e.key.toUpperCase() !== key);
+	return ((IS_APPLE ? e.metaKey : e.ctrlKey) ? "mod+" : "") + (shift ? "shift+" : "") + key;
+}
+
+/**
+ * Whether the focused element keeps this keystroke for itself: anything being
+ * typed into keeps the unmodified keys (Escape excepted — it never types), a
+ * button-like control keeps its activation keys, and a link keeps Enter even
+ * modified — that one is the keyboard's own open-in-a-new-tab, the counterpart
+ * of a ctrl-click. The one answer the matcher and the `?` overview share, so
+ * what is listed and what fires can never disagree.
+ */
+function keptByTarget(keyStr: string, target: Element | null): boolean {
+	if (!(target instanceof HTMLElement)) return false;
+	const mod = keyStr.startsWith("mod+");
+	// Modifiers stripped: a shifted Enter is still the link's new-window Enter.
+	const key = keyStr.replace(/^(mod\+)?(shift\+)?/, "");
+	if (key === "enter" && target.closest("a[href]") != null) return true;
+	if (!mod && (key === "enter" || key === " ") && target.closest("button, summary, [role=button]") != null) return true;
+	const tag = target.tagName;
+	return !mod && key !== "escape" &&
+		(tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT" || target.isContentEditable);
+}
+
+/** Whether a binding found at `el` applies, given the current keyboard claim. */
+function reachable(el: Element, b: KeyBinding): boolean {
+	const modal = modalStack[modalStack.length - 1];
+	return b.global === true || !modal || modal.contains(el);
+}
+
+/** The innermost claiming element containing `el`, if any. */
+function claimFor(el: Element): Element | undefined {
+	for (let i = modalStack.length - 1; i >= 0; i--) {
+		if (modalStack[i].contains(el)) return modalStack[i];
+	}
+}
+
+/** The element whose claim owns the keyboard right now: the top claim, or the body. */
+export function keyboardOwner(): Element {
+	return modalStack[modalStack.length - 1] ?? document.body;
+}
+
+/**
+ * Where the binding search starts: the focused element — or the claiming modal
+ * itself when focus has strayed outside it (a dialog holding nothing
+ * focusable, a click that blurred to the body), so a modal never loses its own
+ * keys.
+ */
+function walkStart(target: Element | null): Element {
+	const modal = modalStack[modalStack.length - 1];
+	return modal && !(target && modal.contains(target)) ? modal : target ?? document.body;
+}
+
+let listening = false;
+
+function onKeydown(e: KeyboardEvent): void {
+	// Something already answered for this keystroke — a handler of the app's own,
+	// a menu's or an autocomplete's; element listeners run before this one.
+	if (e.defaultPrevented || e.repeat || e.isComposing) return;
+	const keyStr = canonEvent(e);
+	const target = e.target instanceof Element ? e.target : null;
+	if (keyStr == null || keptByTarget(keyStr, target)) return;
+	for (let el: Element | null = walkStart(target); el; el = el.parentElement) {
+		const b = bindings.get(el)?.get(keyStr);
+		if (b && reachable(el, b)) {
+			// A describe-only binding still ends the search: the key is somebody
+			// else's, and the keystroke passes untouched.
+			if (b.press) {
+				e.preventDefault();
+				b.press(e);
+			}
+			return;
+		}
+	}
+}
+
+/**
+ * What a keypress aimed at `target` — the focused element, typically — could do
+ * right now: for each combination, the binding the walk up from `target` would
+ * find, minus the keystrokes `target` keeps for itself. Innermost first, as
+ * `[keyStr, binding]` pairs. A snapshot, not reactive.
+ */
+export function getActiveKeyBindings(target: Element | null): Array<[string, KeyBinding]> {
+	const found = new Map<string, KeyBinding>();
+	for (let el: Element | null = walkStart(target); el; el = el.parentElement) {
+		const map = bindings.get(el);
+		if (map) {
+			for (const [keyStr, b] of map) {
+				if (!found.has(keyStr) && reachable(el, b) && !keptByTarget(keyStr, target)) found.set(keyStr, b);
+			}
+		}
+	}
+	return [...found];
+}
+
+/**
+ * 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 {@link formatKey} turns it
+ * back into `"⇧⌘K"`/`"Ctrl+Shift+K"`.
+ *
+ * `description` is what the shortcut overview (see {@link 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.
+ *
+ * @example
+ * ```ts
+ * S.bindKey("mod+k", "Search", openSearch);
+ * S.bindKey("mod+z", "Undo");   // describe only: handled by our own listener
+ * ```
+ */
+export function bindKey(spec: string, description?: Slot, press?: (e: KeyboardEvent) => void, mode: "normal" | "global" | "local" | Element = "normal"): void {
+	const cur = A() as Element | undefined;
+	// A normal binding is anchored by containment, not by whatever claim is top
+	// at call time: a scope redrawn elsewhere while a dialog is up must not
+	// hitch its keys to that dialog and die with it.
+	const el = mode === "global" ? document.body
+		: mode === "local" ? cur
+		: mode === "normal" ? (cur && claimFor(cur)) ?? document.body
+		: mode;
+	if (!el) throw new Error("Staffa: a local key binding needs a current element");
+	const keyStr = canonKey(spec);
+	let map = bindings.get(el);
+	if (!map) bindings.set(el, map = new Map());
+	// Shadow (not replace) any same-key binding already at this element; the
+	// scope's cleanup below restores it.
+	const binding: KeyBinding = { description, press, global: mode === "global", prev: map.get(keyStr) };
+	map.set(keyStr, binding);
+	if (!listening) {
+		listening = true;
+		document.addEventListener("keydown", onKeydown);
+	}
+	A.clean(() => {
+		// Unlink, wherever in the shadow chain the binding sits by now.
+		let b = map.get(keyStr);
+		if (b === binding) {
+			if (binding.prev) map.set(keyStr, binding.prev);
+			else map.delete(keyStr);
+		} else {
+			for (; b; b = b.prev) {
+				if (b.prev === binding) { b.prev = binding.prev; break; }
+			}
+		}
+	});
+}
+
+/**
+ * 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"`.
+ *
+ * @example
+ * ```ts
+ * S.button({ content: `Search  ${S.formatKey("mod+k")}`, click: search });
+ * ```
+ */
+export function formatKey(spec: string, aria = false): string {
+	const keyStr = canonKey(spec);
+	const mod = keyStr.startsWith("mod+");
+	const rest = mod ? keyStr.slice(4) : keyStr;
+	const shift = rest.startsWith("shift+");
+	const key = shift ? rest.slice(6) : rest;
+	const cap = key.length === 1 ? key.toUpperCase() : key[0].toUpperCase() + key.slice(1);
+	if (aria) {
+		const name = key === " " ? "Space" : shift || key.length > 1 ? cap : key;
+		return (mod ? (IS_APPLE ? "Meta+" : "Control+") : "") + (shift ? "Shift+" : "") + name;
+	}
+	// Apple writes ⇧ before ⌘, and nothing between the glyphs.
+	const name = GLYPHS[key] ?? cap;
+	return IS_APPLE
+		? (shift ? "⇧" : "") + (mod ? "⌘" : "") + name
+		: (mod ? "Ctrl+" : "") + (shift ? "Shift+" : "") + name;
+}

package/src/theme.ts

@@ -3,54 +3,23 @@ import A from "aberdeen";
 /**
  * Theming and global base styles for Staffa.
  *
- * # The surface model
+ * A Staffa app is a tree of **surfaces** (`.s-s`), in two families:
  *
- * A Staffa app is a tree of **surfaces**. A surface is anything with its own
- * background and matching ink — the page, a card, a coloured button. Mark an
- * element with `.s-s` and (usually) one modifier class. There are two families:
+ * - **Neutral** — `.neutral`, and the implicit page at `:root`. Its shade steps
+ *   with nesting depth (capped). No `tonal`/`outlined` variants.
+ * - **Accent** — `.primary`, `.danger`, `.success`, `.warning`, `.link` (a bare
+ *   `.s-s` is primary): a bright fill with white ink, `.tonal`/`.outlined`
+ *   variants supported. A surface nested *inside* one is forced back to filled,
+ *   so it can't bleed into the vivid parent.
  *
- * - **Neutral surfaces** — `.s-s.neutral` (and the implicit page at `:root`). A calm
- *   neutral whose shade steps automatically with nesting depth (page → panel →
- *   raised, capped). No `tonal`/`outlined` variants. Use them for cards, bars,
- *   popovers — anything that just holds content.
- * - **Accent surfaces** — `.s-s.primary`, `.s-s.danger`, `.s-s.success`,
- *   `.s-s.warning`, `.s-s.link` (a bare `.s-s` defaults to primary). A bright
- *   fill with white ink, painted as a subtle single-colour gradient. They support
- *   `.tonal` and `.outlined` variants. A surface nested *inside* an accent surface
- *   is always rendered filled, so it can't bleed into the vivid parent.
- *
- * # Contextual tokens
- *
- * Inside any surface (including `:root`) these inherited custom properties are
- * defined, so widgets adapt to wherever they're nested:
- *
- * | token        | meaning                                                   |
- * | ------------ | --------------------------------------------------------- |
- * | `--s-bg`     | the surface background                                    |
- * | `--s-text`   | default ink (also applied as `color`)                     |
- * | `--s-muted`  | secondary text (subtitles, help)                          |
- * | `--s-accent` | the surface's "pop" — the brand primary on neutral surfaces, the ink on accent surfaces |
- * | `--s-faint` | hairline, derived from text/bg                            |
- *
- * The brand/semantic colours are mode-independent and settable: `--s-primary`
- * (the one brand colour — it tints the neutrals and defines `.s-s.primary`),
- * `--s-danger`, `--s-success`, `--s-warning`, and `--s-link` (the link colour,
- * also the fill of the `.s-s.link` surface). Links render in `--s-link` on
- * neutral surfaces and in the ink on accent surfaces.
- *
- * # Borders & shadows
- *
- * Neutral surfaces carry a subtle hairline border by default (so a card reads as a
- * card with no component help); it's applied through `:where()`, so a bar that
- * wants only a divider overrides it trivially. Any surface can opt into elevation
- * with `.shadow` or `.extra-shadow`, or drop a component's built-in shadow with
- * `.no-shadow` (e.g. `S.button({ attrs: ".no-shadow" })`).
- *
- * # Customising
- *
- * Re-skin by overriding the colour tokens (e.g. `--s-primary`). To add your own
- * accent surface, just set `--s-bg` (and, if needed, `--s-text`) — the gradient
- * and the rest of the tokens follow automatically:
+ * Every surface (and `:root`) defines the inherited tokens widgets style against,
+ * so they adapt to wherever they're nested: `--s-bg`, `--s-text` (also applied as
+ * `color`), `--s-muted` (secondary text), `--s-accent` (the surface's "pop" — the
+ * brand primary on neutral surfaces, the ink on accent ones) and `--s-faint`
+ * (hairline). The brand/semantic colours — `--s-primary`, `--s-danger`,
+ * `--s-success`, `--s-warning`, `--s-link` — are mode-independent and settable;
+ * overriding them re-skins the app. A custom accent surface needs only `--s-bg`
+ * (and, if needed, `--s-text`); gradient and tokens follow:
  *
  * ```ts
  * A.insertGlobalCss({ ".s-s.brand": "--s-bg:#ef6b00 --s-text:#fff" });
@@ -60,10 +29,9 @@ import A from "aberdeen";
 
 /**
  * The subtle single-colour wash a surface is painted with, as a `background:`
- * declaration, at the given angle. Shared constants rather than a CSS custom
- * property, deliberately: `var()`s inside a custom property resolve where the
- * property is *defined*, so a `--s-sheen` at `:root` would paint every surface
- * with the page's wash instead of its own `$s-bg`'s.
+ * declaration, at the given angle. A shared constant rather than a `--s-sheen`
+ * custom property: `var()`s inside a custom property resolve where it is
+ * *defined*, so every surface would get the page's wash instead of its own.
  */
 const sheen = (angle: string) =>
 	`background: linear-gradient(${angle}, color-mix(in oklab, $s-bg, white 9%), color-mix(in oklab, $s-bg, black 9%));`;
@@ -72,16 +40,10 @@ const sheen = (angle: string) =>
 export const SURFACE_SHEEN = sheen("170deg");
 
 /**
- * The same wash, straight down — for panels.ts, where the routed columns and
- * the ground beside them have to look like one continuous surface.
- *
- * A gradient at an angle takes its extent from the box's *width* as well as its
- * height, so a 430px column and the 1720px region behind it would paint
- * different slices of the same wash and meet at a visible step. Straight down,
- * the extent is the height alone — which every column shares exactly with the
- * region (a column is `top:0 bottom:0` in it) and so with every other column.
- * The 10° of tilt is worth losing there; it buys the one place in the app where
- * boxes of *different widths* must be seamless.
+ * The same wash, straight down — for panels.ts, where the routed columns and the
+ * ground beside them have to look like one continuous surface. An angled gradient
+ * takes its extent from the box's *width* as well as its height, so boxes of
+ * different widths would paint different slices of it and meet at a visible step.
  */
 export const PANEL_SHEEN = sheen("180deg");
 
@@ -129,13 +91,9 @@ export function getDarkMode(allowAuto = false): boolean | undefined {
 	return v === undefined && !allowAuto ? A.darkMode() : v;
 }
 
-// ---------------------------------------------------------------------------
-// The only mode-dependent thing: the neutral surface shades and their ink,
-// written straight onto the surfaces (no intermediate palette vars). `:root` is
-// the page (depth 0); each nested `.neutral` steps one shade up, capped at the
-// `.neutral .neutral` rule. The accent (coloured) surfaces and everything else are
-// mode-independent and live in the static block below.
-// ---------------------------------------------------------------------------
+// The only mode-dependent thing: the neutral shades and their ink, written
+// straight onto the surfaces (no intermediate palette vars). `:root` is the page
+// (depth 0); each nested `.neutral` steps a shade up, capped at the second level.
 A(() => {
 	if (getDarkMode()) {
 		A.insertGlobalCss({
@@ -152,37 +110,29 @@ A(() => {
 	}
 });
 
-// ---------------------------------------------------------------------------
-// Static structure — inserted once. The colour tokens are mode-independent
-// (saturated fills that carry white ink on either background); shape/effect
-// tokens are single values kept only because they're reused across components.
-// Rule order matters: role fills come after the `:not(.neutral)` default, so a
-// caller's `attrs` override wins at equal specificity.
-// ---------------------------------------------------------------------------
+// Static structure — inserted once, mode-independent. Rule order matters: role
+// fills come after the `:not(.neutral)` default, so a caller's `attrs` override
+// wins at equal specificity.
 
 A.setSpacingCssVars(1.1);
 
 A.insertGlobalCss({
-	// What follows is a lightweight CSS reset. Semantic HTML should keep working, but less ugly/with some reasonable defaults.
+	// A lightweight reset: bare semantic HTML, with less ugly defaults.
 	"*, *::before, *::after": "box-sizing:border-box",
 	html: "text-size-adjust:100%",
 	body: "m:0 p:$3 line-height:1.5 font-family: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif; -webkit-font-smoothing:antialiased background-color:$s-bg text:$s-text",
-	// Links resolve to the contextual link foreground: the link colour on nesting
-	// surfaces, the ink on accent surfaces.
+	// The contextual link colour: `--s-link` on neutral surfaces, the ink on accent ones.
 	a: "color: $s-link-fg; text-decoration:underline text-underline-offset:2px; transition: color 0.12s, filter 0.12s;",
 	"a:hover": "filter: brightness(1.15)",
 	"input, button, textarea, select, optgroup": "font:inherit color:inherit",
-	// Bare text-like fields get a calm bordered box derived from the surface. The
-	// styled controls (`.s-input`, autocomplete's `.s-control`) override this via
-	// higher specificity, so this only governs otherwise-unstyled HTML. `:where()`
-	// keeps it at element specificity, so a component class always wins.
+	// Bare text-like fields get a calm bordered box derived from the surface.
+	// `:where()` keeps it at element specificity, so a component class always wins.
 	"input:where(:not([type=checkbox],[type=radio],[type=range],[type=file],[type=color],[type=image],[type=submit],[type=button],[type=reset],[type=hidden])), textarea, select":
 		"background:$s-bg border: 1px solid $s-faint; r:$s-radius-sm padding: 0.45em 0.65em; max-width:100%",
-	// Checkboxes/radios: a touch larger with a pointer cursor. (The brand accent —
-	// `accent-color` — is inherited from the surface, see the `:root, .s-s` rule.)
+	// Checkboxes/radios: a touch larger, with a pointer cursor. (`accent-color` is
+	// inherited from the surface, see the `:root, .s-s` rule.)
 	"input:where([type=checkbox],[type=radio])": "width:1.15em height:1.15em cursor:pointer",
-	// Range: a thin pill track (faint, brand-filled on the lower side in Firefox)
-	// with a round brand thumb — no native groove/outline.
+	// Range: a thin faint pill track with a round brand thumb — no native groove.
 	"input[type=range]": "appearance:none background:transparent cursor:pointer vertical-align:middle",
 	"input[type=range]::-webkit-slider-runnable-track": "height:4px r:99px background:$s-faint",
 	"input[type=range]::-moz-range-track": "height:4px r:99px background:$s-faint",
@@ -223,12 +173,11 @@ A.insertGlobalCss({
 		// Brand sweep for the headline mark, the active nav pill, the selected tab.
 		"--s-gradient: linear-gradient(135deg, color-mix(in oklab, $s-primary, white 16%), color-mix(in oklab, $s-primary, black 14%));",
 
-	// Neutral surfaces (and the page): the pop colour is the brand primary, and
-	// links use the link colour. (The bg/ink come from the mode block above.)
+	// Neutral surfaces (and the page); their bg/ink come from the mode block above.
 	":root, .s-s.neutral": "--s-accent:$s-primary --s-link-fg:$s-link",
 
-	// Accent surfaces: bright fill, white ink. The bare `:not(.neutral)` carries the
-	// shared defaults (with a primary fallback fill); each role names its own fill.
+	// Accent surfaces: bright fill, white ink. The bare `:not(.neutral)` holds the
+	// shared defaults; each role below names its own fill.
 	".s-s:not(.neutral)":
 		"--s-bg:$s-primary " + // Default .s-s to .primary
 		"border:0 " +
@@ -241,8 +190,8 @@ A.insertGlobalCss({
 	".s-s.link": "--s-bg:$s-link",
 	".s-s.primary": "--s-bg:$s-primary",
 
-	// Shared derive: every surface (and the page) gets a muted ink + hairline from
-	// its resolved text/bg pair, plus `color` and themed scrollbars.
+	// Every surface (and the page) derives its muted ink + hairline from the
+	// text/bg pair it resolved to above.
 	":root, .s-s":
 		"--s-muted: color-mix(in oklab, $s-text, $s-bg 42%); " +
 		"--s-faint: color-mix(in oklab, $s-text, $s-bg 80%); " +
@@ -250,55 +199,44 @@ A.insertGlobalCss({
 	// Subtle single-colour gradient sheen, painted on every surface (and the page).
 	".s-s, body": SURFACE_SHEEN,
 	".s-s": "r:$s-radius",
-	// Neutral surfaces own a subtle hairline border (a card reads as a card without
-	// any component help). `:where()` keeps it zero-specificity, so a bar/panel that
-	// wants only a divider (a box header, the app top bar, the nav panel) overrides
-	// it with a single plain rule. Accent (filled) surfaces don't get it — their fill
-	// is the edge. Buttons keep their own `border:0`.
+	// A neutral surface owns a hairline border, so a card reads as a card without
+	// any component help. `:where()` keeps it zero-specificity, so a bar that wants
+	// only a divider overrides it with a single plain rule.
 	":where(.s-s.neutral)": "border: 1px solid $s-faint;",
 	".s-s::-webkit-scrollbar, .s-s ::-webkit-scrollbar": "width:10px height:10px",
 	".s-s::-webkit-scrollbar-track, .s-s ::-webkit-scrollbar-track": "background:transparent",
 	".s-s::-webkit-scrollbar-thumb, .s-s ::-webkit-scrollbar-thumb":
 		"background:$s-faint border-radius:99px border: 2px solid transparent; background-clip:padding-box",
 
-	// Elevation utilities — add `.shadow` or `.extra-shadow` to any surface:
-	//  • neutral surface       → a neutral drop shadow
-	//  • accent (filled) surface → a self-coloured glow, keyed on its own --s-bg (a
-	//    lit button is just this on a `.primary` surface)
-	//  • tonal/outlined surface → ignored (a translucent body has nothing to lift)
-	// A `.neutral` button stays flat (so segmented groups gain no stray
-	// shadows). `.no-shadow` is a hard override of any of the above — place it last
-	// and make it !important so it beats the higher-specificity glow rule.
+	// Elevation: `.shadow`/`.extra-shadow` give a neutral surface a drop shadow and
+	// an accent one a self-coloured glow; tonal/outlined have nothing to lift. A
+	// `.neutral` button stays flat, so segmented groups gain no stray shadows.
+	// `.no-shadow` comes last and needs `!important` to beat the glow rules.
 	".s-s.shadow.neutral:not(.s-btn)": "box-shadow: 0 4px 14px rgba(0,0,0,0.13);",
 	".s-s.extra-shadow.neutral:not(.s-btn)": "box-shadow: 0 18px 50px rgba(0,0,0,0.28);",
 	".s-s.shadow:not(.neutral):not(.tonal):not(.outlined)": "box-shadow: 0 4px 14px color-mix(in srgb, $s-bg 30%, transparent);",
 	".s-s.extra-shadow:not(.neutral):not(.tonal):not(.outlined)": "box-shadow: 0 14px 40px color-mix(in srgb, $s-bg 40%, transparent);",
 	".s-s.no-shadow": "box-shadow: none !important;",
 
-	// Accent variants. `tonal`: the fill colour becomes the ink over a soft
-	// self-tint. `outlined`: the fill colour is the ink over a transparent body
-	// with a colour edge. (Neutral surfaces ignore these.)
+	// Accent variants: the fill colour becomes the ink, over a soft self-tint
+	// (`tonal`) or a transparent body with a colour edge (`outlined`).
 	".s-s:not(.neutral).tonal, .s-s:not(.neutral).outlined":
 		"--s-text:$s-bg --s-accent:$s-bg --s-link-fg:$s-bg --s-faint: color-mix(in srgb, $s-bg 30%, transparent); --s-muted: color-mix(in srgb, $s-bg 70%, transparent);",
 	".s-s:not(.neutral).tonal":
 		"background: color-mix(in srgb, $s-bg 15%, transparent); border: 1px solid $s-faint;",
 	".s-s:not(.neutral).outlined":
 		"background: transparent; border: 1px solid color-mix(in srgb, $s-bg 45%, transparent);",
-	// A surface nested inside an accent surface is forced back to a filled look —
-	// a translucent tonal/outlined body would bleed into the vivid parent fill.
-	// Specificity (4 classes) beats the 2-class variant rules — no !important.
+	// A surface inside an accent surface is forced back to filled: a translucent
+	// body would bleed into the vivid parent. 4 classes beats the variant rules.
 	".s-s:not(.neutral) .s-s.tonal, .s-s:not(.neutral) .s-s.outlined":
 		"--s-text:#fff --s-accent:#fff --s-link-fg:#fff " +
 		SURFACE_SHEEN + " border-color: transparent;",
 });
 
 // ── Suppress transitions during the initial load ─────────────────────────────
-// Buttons (and links) transition their colours, so a light↔dark switch animates
-// smoothly. On a *cold* load that's a liability: elements mount and paint in the
-// active theme in one pass, but a transitioning element animates from its
-// default (unstyled) colours into the theme. Tag <html> until the first frame
-// has painted and hard-disable transitions under that tag, so the initial render
-// snaps straight to the right colours.
+// Colour transitions make a light↔dark switch smooth, but on a cold load they'd
+// animate from the unstyled colours into the theme. Tag <html> until the first
+// frame has painted, so the initial render snaps to the right colours.
 A.insertGlobalCss({
 	".s-preload, .s-preload *, .s-preload *::before, .s-preload *::after":
 		"transition: none !important; animation: none !important;",
@@ -310,19 +248,16 @@ if (typeof document !== "undefined" && typeof requestAnimationFrame === "functio
 }
 
 // ── Disabled region ───────────────────────────────────────────────────────────
-// aria-disabled="true" on any container dims it and blocks pointer events on
-// it and all descendants, matching the per-element disabled look. Keyboard
-// access to focusable descendants is unaffected — add the `inert` attribute too
-// if you need that.
+// aria-disabled="true" on any container dims it and blocks pointer events on it
+// and all descendants. Keyboard access is unaffected — add `inert` for that.
 A.insertGlobalCss({
 	":disabled, [aria-disabled=true]": "opacity:0.45 filter:saturate(0.6) user-select:none",
 	":disabled, [aria-disabled=true], :disabled *, [aria-disabled=true] *": "pointer-events:none cursor:not-allowed",
 });
 
 // ── Flow content: vertical rhythm & light typography ─────────────────────────
-// Sensible block defaults for *any* content — your own UI just as much as
-// markdown-rendered HTML. The rhythm: strip the browser's block margins, then
-// give every block a *top* margin only when it isn't its parent's first child.
+// Block defaults for *any* content, markdown-rendered or your own: no browser
+// block margins, but a *top* margin unless the block is its parent's first child.
 const BLOCK = "p, ul, ol, dl, blockquote, pre, table, figure, hr, h1, h2, h3, h4, h5, h6";
 
 A.insertGlobalCss({

package/skill/Attributes.md

@@ -1,10 +0,0 @@
-## Attributes · type
-
-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 `A` function. This module defines the option-type hierarchy
-that all components build on, plus a couple of tiny helpers.
-
-**Type:** `string`