staffa 0.9.0 → 0.10.0

package/skill/scrollStrip.md

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

package/src/components/autocomplete.ts

@@ -161,7 +161,7 @@ export function autocomplete(opts: AutocompleteOptions): void {
 				});
 
 				inputEl = A("input type=text role=combobox autocomplete=off", () => {
-					A(`id=${id} aria-controls=${menuId} aria-autocomplete=list`);
+					A("id=", id, `aria-controls=${menuId} aria-autocomplete=list`);
 					if (opts.placeholder != null) A("placeholder=", opts.placeholder);
 					if (opts.disabled) A("disabled=true");
 					if (opts.required) A("aria-required=true");

package/src/components/box.ts

@@ -1,6 +1,7 @@
 import A from "aberdeen";
 import { type ContentOptions, type Slot, type Attributes, drawSlot } from "../core.js";
-import { closeContainingPanel } from "./panels.js";
+import { x as closeIcon } from "../icons.js";
+import { iconButton } from "./button.js";
 
 /** Options for {@link box}. */
 export interface BoxOptions extends ContentOptions {
@@ -9,21 +10,16 @@ export interface BoxOptions extends ContentOptions {
 	/** Footer content, drawn in a styled bar below the body. */
 	footer?: Slot;
 	/**
-	 * Draws a small ✕ button in the box's top-right corner: in the header row when
+	 * Draws a small ✕ button in the box's top-right corner — in the header row when
 	 * there is a {@link BoxOptions.header | header}, floating over the body when
-	 * there isn't.
+	 * there isn't — and runs this when it's clicked.
 	 *
-	 * `true` closes the panel the box is drawn in, which is how a screen of a
-	 * routed `S.main()` gives the user a way back (the shell draws no back
-	 * arrows or ✕ of its own). Which panel that is gets worked out from the DOM
-	 * when it's clicked, so the box needs no `$page` handed to it and works from
-	 * any column, top of the stack or not. A box in a column further left closes
-	 * just that column and leaves the others alone. Outside a routed shell it
-	 * does nothing but warn.
-	 *
-	 * Pass a function to run that instead, for a dismissal of your own.
+	 * It is plain furniture: a box that happens to sit in a page of a routed
+	 * `S.main()` does **not** close that page — the shell's breadcrumbs are the
+	 * way out of those. Wire it to `$panel.close()` yourself if a box really is
+	 * the whole page and wants its own ✕.
 	 */
-	close?: boolean | (() => void);
+	close?: () => void;
 	/** Aberdeen attr/style string applied to the body (content-holding) element. */
 	contentAttrs?: Attributes;
 	/** Aberdeen attr/style string applied to the header bar. */
@@ -49,16 +45,11 @@ 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 ✕: quiet until you're near it, and drawn in the surface's own tokens
-		// so it works on whatever the box was recoloured to. `margin-left:auto`
-		// parks it at the far end of the header's flex row.
-		".s-box-close":
-			"flex-shrink:0 margin-left:auto display:flex align-items:center justify-content:center " +
-			"width:1.6rem height:1.6rem p:0 border:0 background:transparent cursor:pointer " +
-			"fg:$s-muted font-size:0.95rem line-height:1 r:$s-radius-sm " +
-			"transition: color 0.12s, background 0.12s;",
-		".s-box-close:hover": "fg:$s-text background: color-mix(in srgb, $s-text 8%, transparent);",
-		// Without a header there is no row to sit in, so it floats over the body.
+		// The ✕ is an `S.iconButton` (see `drawCloseButton`); this only places it.
+		// In a header row it parks at the far end...
+		"> 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",
 	},
 });
@@ -73,9 +64,6 @@ A.insertGlobalCss({
  *
  * Shortcut: pass a function to use it directly as the body content.
  *
- * {@link BoxOptions.close | `close: true`} adds a ✕ that closes the panel the box
- * is drawn in: the usual way back out of a screen in a routed `S.main()`.
- *
  * @example
  * ```ts
  * const $user = A.proxy({name: "Kvothe"});
@@ -83,7 +71,7 @@ A.insertGlobalCss({
  *   S.textline({ label: "Name", bind: A.ref($user, "name") });
  * }});
  * S.box(() => A("p#Just some content"));   // shorthand
- * S.box({ header: "Task 42", close: true, content: drawTask });  // ✕ closes this panel
+ * S.box({ header: "Draft", close: () => discard(), content: drawDraft });  // ✕ runs discard()
  * ```
  */
 export function box(opts: BoxOptions | Slot = {}): void {
@@ -93,12 +81,15 @@ export function box(opts: BoxOptions | Slot = {}): void {
 		// Header and footer get their own scopes so toggling them doesn't recreate
 		// the body (which may hold focused inputs / lots of content).
 		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.
 			if (o.header != null) {
 				A("header.s-s.neutral", o.headerAttrs, () => {
 					drawSlot(o.header);
-					if (o.close) drawCloseButton(o.close);
+					if (typeof o.close === "function") drawCloseButton(o.close);
 				});
-			} else if (o.close) {
+			} else if (typeof o.close === "function") {
 				drawCloseButton(o.close);
 			}
 		});
@@ -114,16 +105,15 @@ export function box(opts: BoxOptions | Slot = {}): void {
 }
 
 /**
- * The box's ✕. With `close: true` the panel to close is resolved from the DOM at
- * click time — so one box can close whichever column it happens to be drawn in,
- * and a box outside a routed shell simply warns.
+ * 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.
  */
-function drawCloseButton(close: boolean | (() => void)): void {
-	A("button.s-box-close type=button aria-label=Close", () => {
-		A("click=", (e: Event) => {
-			if (typeof close === "function") close();
-			else void closeContainingPanel(e.currentTarget as HTMLElement);
-		});
-		A("span aria-hidden=true #✕");
+function drawCloseButton(close: () => void): void {
+	iconButton({
+		icon: closeIcon,
+		ariaLabel: "Close",
+		click: close,
+		attrs: ".s-box-close",
 	});
 }

package/src/components/button.ts

@@ -1,6 +1,26 @@
 import A from "aberdeen";
 import { type Slot, type Attributes, drawSlot } from "../core.js";
 
+/** Options for {@link iconButton}. */
+export interface IconButtonOptions {
+	/** The glyph, usually one of the `staffa/icons` draw functions. */
+	icon: Slot;
+	/** What it does, for screen readers. Required: there is no visible text to read. */
+	ariaLabel: string;
+	/** Click handler. */
+	click?: (event: Event) => void;
+	/** Render as a link (`<a role=button>`) pointing here instead of a `<button>`. */
+	href?: string;
+	/** Disables it. */
+	disabled?: boolean;
+	/**
+	 * Aberdeen attr/style string applied to the button. `.small` and `.large`
+	 * size the hit area (medium is the default and needs no class); a `.small`
+	 * or `.large` parent sizes the ones inside it, as with {@link button}.
+	 */
+	attrs?: Attributes;
+}
+
 /** Options for {@link button}. */
 export interface ButtonOptions {
 	/** Button content: a string for plain text, or a function for custom markup. */
@@ -51,6 +71,11 @@ A.insertGlobalCss({
 		// button (which is already near-white) darkens toward its ink instead.
 		"&.tonal:hover, &.outlined:hover": "background: color-mix(in srgb, $s-bg 24%, transparent);",
 		"&.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.
+		"> 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`
@@ -58,8 +83,91 @@ A.insertGlobalCss({
 		"&.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.
+	".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.)
+		"> 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.
+		"&.small, .small > &": "width:1.6rem height:1.6rem font-size:0.8rem",
+		"&.large, .large > &": "width:2.4rem height:2.4rem font-size:1.2rem",
+	},
 });
 
+/**
+ * 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}.
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { trash2, share2 } from "staffa/icons";
+ *
+ * $panel.actions = () => {
+ *   S.iconButton({ icon: share2, ariaLabel: "Share", click: share });
+ *   S.iconButton({ icon: trash2, ariaLabel: "Delete", click: del, attrs: "fg:$s-danger" });
+ * };
+ * ```
+ */
+export function iconButton(opts: IconButtonOptions): void {
+	const tag = opts.href != null ? "a" : "button";
+	A(`${tag}.s-icon-btn`, opts.attrs, () => {
+		applyActionBehavior(opts);
+		A("aria-label=", opts.ariaLabel);
+		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.
+ */
+function applyActionBehavior(o: {
+	href?: string;
+	disabled?: boolean;
+	click?: (event: Event) => void;
+	type?: string;
+}): void {
+	if (o.href != null) {
+		A("role=button");
+		if (o.disabled) A("aria-disabled=true");
+		else A("href=", o.href);
+	} else {
+		A("type=", o.type ?? "button");
+		if (o.disabled) A("disabled=true");
+	}
+	if (o.click && !o.disabled) A("click=", o.click);
+}
+
 /**
  * A button. Tonal and outlined variants show a border; filled variants rely on
  * their solid background for affordance.
@@ -94,15 +202,8 @@ export function button(opts: ButtonOptions | Slot = {}): void {
 	// role (`.danger`, `.neutral`, a custom `.brand`) or variant (`.outlined`); no
 	// role detection needed, since the default lives in CSS, not here.
 	A(`${tag}.s-btn.s-s.shadow`, o.attrs, () => {
-		if (o.href != null) {
-			A(`href=${o.href} role=button`);
-			if (o.disabled) A("aria-disabled=true");
-		} else {
-			A("type=", o.type ?? "button");
-			if (o.disabled) A("disabled=true");
-		}
+		applyActionBehavior(o);
 		if (o.ariaLabel) A("aria-label=", o.ariaLabel);
-		if (o.click) A("click=", o.click);
 
 		drawSlot(o.icon);
 		drawSlot(o.content);

package/src/components/buttonChooser.ts

@@ -62,6 +62,6 @@ export function buttonChooser(opts: ButtonChooserOptions): void {
 
 	if (opts.name) {
 		// Hidden input carries the value into native form submission.
-		A(() => A(`input type=hidden name=${opts.name} value=`, opts.bind.value ?? ""));
+		A(() => A("input type=hidden name=", opts.name, "value=", opts.bind.value ?? ""));
 	}
 }

package/src/components/checkbox.ts

@@ -40,10 +40,10 @@ export function checkbox(opts: CheckboxOptions = {}): void {
 	const id = opts.id ?? uniqueId("check");
 
 	A("div.s-check", opts.attrs, () => {
-		A(`label for=${id}`, () => {
+		A("label for=", id, () => {
 			A("input type=checkbox", opts.inputAttrs, () => {
-				A(`id=${id}`);
-				if (opts.name) A(`name=${opts.name}`);
+				A("id=", id);
+				if (opts.name) A("name=", opts.name);
 				// `checked` is a boolean attribute: only set it when actually true.
 				if (opts.checked && !opts.bind) A("checked=true");
 				if (opts.change) A("change=", opts.change);

package/src/components/field.ts

@@ -75,7 +75,7 @@ export function drawField(
 	A("div.s-field", opts.attrs, () => {
 		A(() => {
 			if (opts.label != null) {
-				A(`label for=${id}`, () => {
+				A("label for=", id, () => {
 					drawSlot(opts.label);
 					if (opts.required) A("span.s-req aria-hidden=true #*");
 				});
@@ -104,8 +104,8 @@ export function applyControlAttrs(
 	isInvalid: () => boolean,
 	bind?: Bindable<unknown>,
 ): void {
-	A(`id=${id}`);
-	if (opts.name) A(`name=${opts.name}`);
+	A("id=", id);
+	if (opts.name) A("name=", opts.name);
 	A(() => {
 		if (opts.disabled) A("disabled=true");
 	});