staffa 0.1.0

package/src/components/autocomplete.ts

@@ -0,0 +1,272 @@
+import A from "aberdeen";
+import { type Bindable, uniqueId } from "../core.js";
+import { type FieldOptions, drawField } from "./field.js";
+
+/** A selectable option: a bare string, or a `{ value, label }` pair. */
+export type AutocompleteOptionInput = string | { value: string; label?: string };
+
+interface AcOption {
+	value: string;
+	label: string;
+}
+
+/** Options for {@link autocomplete}. */
+export interface AutocompleteOptions extends FieldOptions {
+	/**
+	 * The candidate options. May be a static array or a function returning one —
+	 * the function is called inside a reactive scope, so it can read proxied state
+	 * to provide dynamic/async suggestions.
+	 */
+	options: AutocompleteOptionInput[] | (() => AutocompleteOptionInput[]);
+	/**
+	 * Two-way binding for the selection. In single mode this is the selected
+	 * `value` string (`""` when empty). In {@link AutocompleteOptions.multi} mode
+	 * it is an array of value strings.
+	 */
+	bind?: Bindable<string | string[]>;
+	/** Allow selecting several values, shown as removable chips. */
+	multi?: boolean;
+	/** Allow committing free text that isn't in the options list. Defaults to `true`. */
+	allowCustom?: boolean;
+	/** Placeholder for the text input. */
+	placeholder?: string;
+}
+
+A.insertGlobalCss({
+	".S_ac": {
+		"&": "position:relative",
+		"> .S_control": "display:flex flex-wrap:wrap align-items:center gap:$1 bg:$sSurface fg:$sFg border: 1px solid $sBorder; r:$sRadius padding: 0.3em 0.4em; cursor:text; transition: border-color 0.15s, box-shadow 0.15s;",
+		"> .S_control:hover": "border-color:$sBorderStrong",
+		"> .S_control:focus-within": "border-color:$sPrimary box-shadow: 0 0 0 3px $sFocus;",
+		"&[aria-invalid=true] > .S_control": "border-color:$sDanger",
+		".S_chip": "display:inline-flex align-items:center gap:$1 font-size:0.85em bg:$sSurfaceHi border: 1px solid $sBorder; r:$sRadius padding: 0.1em 0.2em 0.1em 0.5em;",
+		".S_chip > button": "cursor:pointer border:0 background:transparent fg:$sFgMuted font-size:1.1em line-height:1 padding: 0 0.2em; r:4px",
+		".S_chip > button:hover": "fg:$sFg background:$sBorder",
+		"input": "flex:1 min-width:6ch border:0 background:transparent color:inherit outline:none padding:0.25em",
+		"> .S_menu": "position:absolute top:100% left:0 right:0 z-index:20 margin-top:4px max-height:15rem overflow-y:auto list-style:none p:$1 margin-bottom:0 bg:$sSurface border: 1px solid $sBorder; r:$sRadius box-shadow:$sShadow",
+		".S_option": "padding: 0.45em 0.6em; r:6px cursor:pointer",
+		".S_option[aria-selected=true]": "background:$sSurfaceHi",
+		".S_add": "fg:$sPrimary font-style:italic",
+		".S_empty": "padding: 0.45em 0.6em; fg:$sFgMuted",
+	},
+});
+
+function normOption(o: AutocompleteOptionInput): AcOption {
+	return typeof o === "string" ? { value: o, label: o } : { value: o.value, label: o.label ?? o.value };
+}
+
+/**
+ * A combobox with type-ahead filtering. Supports single or multi-select (chips),
+ * optional free-text entry, and full keyboard control (arrows, enter, escape,
+ * backspace-to-remove). Implements the ARIA combobox/listbox pattern.
+ *
+ * @example
+ * ```ts
+ * // Single select from a fixed list
+ * S.autocomplete({ label: "Country", options: ["Belgium", "Netherlands"], bind: $sel });
+ *
+ * // Multi-select, disallowing custom items
+ * S.autocomplete({ label: "Tags", multi: true, allowCustom: false,
+ *   options: knownTags, bind: A.ref($post, "tags") });
+ * ```
+ */
+export function autocomplete(opts: AutocompleteOptions): void {
+	const menuId = uniqueId("ac-menu");
+	const $st = A.proxy({ query: "", open: false, active: 0 });
+
+	const getOptions = (): AcOption[] => {
+		const raw = typeof opts.options === "function" ? opts.options() : opts.options;
+		return raw.map(normOption);
+	};
+	const selectedValues = (): string[] => {
+		const v = opts.bind?.value;
+		if (v == null || v === "") return [];
+		return Array.isArray(v) ? v : [v];
+	};
+	const labelFor = (value: string): string => getOptions().find((o) => o.value === value)?.label ?? value;
+
+	// Seed the input with the current single-selection's label.
+	if (!opts.multi) {
+		const v = opts.bind ? A.peek(opts.bind, 'value') : undefined;
+		if (typeof v === "string" && v) $st.query = A.peek(() => labelFor(v));
+	}
+
+	const filtered = (): AcOption[] => {
+		const sel = new Set(selectedValues());
+		let list = getOptions();
+		if (opts.multi) list = list.filter((o) => !sel.has(o.value));
+		const q = $st.query.trim().toLowerCase();
+		if (q) list = list.filter((o) => o.label.toLowerCase().includes(q));
+		return list;
+	};
+
+	const commit = (value: string, inputEl?: HTMLInputElement) => {
+		if (opts.multi) {
+			const arr = Array.isArray(opts.bind?.value) ? [...(opts.bind.value as string[])] : [];
+			if (!arr.includes(value)) arr.push(value);
+			if (opts.bind) opts.bind.value = arr;
+			$st.query = "";
+		} else {
+			if (opts.bind) opts.bind.value = value;
+			$st.query = labelFor(value);
+			$st.open = false;
+		}
+		$st.active = 0;
+		// Keep focus on the input so the user can Tab to the next field.
+		inputEl?.focus();
+	};
+
+	const remove = (value: string) => {
+		if (!opts.bind) return;
+		const arr = (opts.bind.value as string[]) ?? [];
+		opts.bind.value = arr.filter((v) => v !== value);
+	};
+
+	drawField(opts, (id, isInvalid) => {
+		A("div.S_ac", opts.control, () => {
+			A(() => A("aria-invalid=", isInvalid() ? "true" : "false"));
+
+			let inputEl: HTMLInputElement | undefined;
+
+			A("div.S_control", () => {
+				A("click=", () => inputEl?.focus());
+
+				// Chips for multi-select.
+				A(() => {
+					if (!opts.multi) return;
+					for (const value of selectedValues()) {
+						A("span.S_chip", () => {
+							A("span #", A.peek(() => labelFor(value)));
+							A("button type=button aria-label=", `Remove ${value}`, () => {
+								A("#×");
+								A("click=", (e: Event) => {
+									e.stopPropagation();
+									remove(value);
+									inputEl?.focus();
+								});
+							});
+						});
+					}
+				});
+
+				inputEl = A("input type=text role=combobox autocomplete=off", () => {
+					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");
+					A("bind=", A.ref($st, "query"));
+					A(() => A("aria-expanded=", $st.open ? "true" : "false"));
+					A(() => {
+						const list = filtered();
+						const act = list[$st.active];
+						A("aria-activedescendant=", $st.open && act ? `${menuId}-opt-${$st.active}` : "");
+					});
+					A("input=", () => {
+						$st.open = true;
+						$st.active = 0;
+					});
+					A("focus=", () => {
+						$st.open = true;
+					});
+					A("blur=", () => {
+						// Delay so option mousedown/click can run first.
+						setTimeout(() => onBlur(), 150);
+					});
+					A("keydown=", (e: KeyboardEvent) => onKey(e, inputEl));
+				}) as HTMLInputElement;
+			});
+
+			// The suggestions popup.
+			A(() => {
+				if (!$st.open) return;
+				const list = filtered();
+				const q = $st.query.trim();
+				const showAdd = opts.allowCustom !== false && q !== "" && !list.some((o) => o.label.toLowerCase() === q.toLowerCase());
+
+				A("ul.S_menu role=listbox", `id=${menuId}`, () => {
+					list.forEach((option, i) => {
+						A("li.S_option role=option", `id=${menuId}-opt-${i}`, () => {
+							A(() => A("aria-selected=", $st.active === i ? "true" : "false"));
+							A("#", option.label);
+							A("mousedown=", (e: Event) => e.preventDefault());
+							A("click=", () => commit(option.value, inputEl));
+							A("mousemove=", () => {
+								$st.active = i;
+							});
+						});
+					});
+					if (showAdd) {
+						A("li.S_option.S_add role=option", () => {
+							A("#", `Add "${q}"`);
+							A("mousedown=", (e: Event) => e.preventDefault());
+							A("click=", () => commit(q, inputEl));
+						});
+					}
+					if (list.length === 0 && !showAdd) {
+						A("li.S_empty #No matches");
+					}
+				});
+			});
+
+			// Hidden inputs so the selection participates in native FormData.
+			A(() => {
+				if (!opts.name) return;
+				if (opts.multi) {
+					for (const val of selectedValues()) {
+						A("input type=hidden", () => {
+							A("name=", opts.name!);
+							A("value=", val);
+						});
+					}
+				} else {
+					A("input type=hidden", () => {
+						A("name=", opts.name!);
+						A("value=", selectedValues()[0] ?? "");
+					});
+				}
+			});
+		});
+	});
+
+	function onKey(e: KeyboardEvent, inputEl?: HTMLInputElement) {
+		const list = filtered();
+		const max = list.length - 1;
+		if (e.key === "ArrowDown") {
+			e.preventDefault();
+			$st.open = true;
+			$st.active = Math.min(max, $st.active + 1);
+		} else if (e.key === "ArrowUp") {
+			e.preventDefault();
+			$st.active = Math.max(0, $st.active - 1);
+		} else if (e.key === "Enter") {
+			// Always prevent default to avoid accidental form submission.
+			e.preventDefault();
+			const chosen = list[$st.active];
+			if (chosen) {
+				commit(chosen.value, inputEl);
+			} else if (opts.allowCustom !== false && $st.query.trim()) {
+				commit($st.query.trim(), inputEl);
+			} else if ($st.open) {
+				$st.open = false;
+			}
+		} else if (e.key === "Escape") {
+			$st.open = false;
+			if (!opts.multi) $st.query = labelFor(selectedValues()[0] ?? "");
+		} else if (e.key === "Backspace" && opts.multi && $st.query === "") {
+			const sel = selectedValues();
+			if (sel.length) remove(sel[sel.length - 1]!);
+		}
+	}
+
+	function onBlur() {
+		$st.open = false;
+		if (opts.multi) {
+			$st.query = "";
+		} else if (opts.allowCustom !== false && $st.query.trim()) {
+			commit($st.query.trim());
+		} else {
+			// Revert to the committed selection's label.
+			$st.query = labelFor(selectedValues()[0] ?? "");
+		}
+	}
+}

package/src/components/box.ts

@@ -0,0 +1,62 @@
+import A from "aberdeen";
+import { type Content, type ContentOptions, type Slot, type Styling, drawSlot } from "../core.js";
+
+/** Options for {@link box}. */
+export interface BoxOptions extends ContentOptions {
+	/** Header content, drawn in a styled bar above the body. */
+	header?: Slot;
+	/** Footer content, drawn in a styled bar below the body. */
+	footer?: Slot;
+	/** Aberdeen attr/style string applied to the header bar. */
+	headerInner?: Styling;
+	/** Aberdeen attr/style string applied to the footer bar. */
+	footerInner?: Styling;
+}
+
+A.insertGlobalCss({
+	".S_box": {
+		"&": "display:flex flex-direction:column bg:$sSurface border: 1px solid $sBorder; r:$sRadius overflow:hidden",
+		"> header": "display:flex align-items:center gap:$2 padding: $2 $3; bg:$sSurfaceHi border-bottom: 1px solid $sBorder; font-weight:600",
+		"> footer": "display:flex align-items:center gap:$2 padding: $2 $3; bg:$sSurfaceHi border-top: 1px solid $sBorder;",
+		// The body is the only plain <div> child; give it the default padding+gap.
+		"> div": "p:$3 gap:$3",
+	},
+});
+
+/**
+ * A surface container — the workhorse layout primitive. Has an optional styled
+ * header and footer, and a padded body that holds {@link ContentOptions.content}.
+ *
+ * The body gets default `padding` and matching `gap`; add `display:flex` via
+ * {@link ContentOptions.inner | inner} if you want its children laid out as a
+ * flex container.
+ *
+ * Shortcut: pass a function to use it directly as the body content.
+ *
+ * @example
+ * ```ts
+ * S.box({ header: "Profile", inner: "display:flex flex-direction:column", content: () => {
+ *   S.textline({ label: "Name", bind: A.ref($user, "name") });
+ * }});
+ * S.box(() => A("p#Just some content"));   // shorthand
+ * ```
+ */
+export function box(opts: BoxOptions | Content = {}): void {
+	const o: BoxOptions = typeof opts === "function" ? { content: opts } : opts;
+
+	A("section.S_box", o.root, () => {
+		// Header and footer get their own scopes so toggling them doesn't recreate
+		// the body (which may hold focused inputs / lots of content).
+		A(() => {
+			if (o.header != null) A("header", o.headerInner, () => drawSlot(o.header));
+		});
+
+		A("div", o.inner, () => {
+			if (o.content) o.content();
+		});
+
+		A(() => {
+			if (o.footer != null) A("footer", o.footerInner, () => drawSlot(o.footer));
+		});
+	});
+}

package/src/components/button.ts

@@ -0,0 +1,137 @@
+import A from "aberdeen";
+import { type BaseOptions, type Content, type Slot, type Styling, drawSlot } from "../core.js";
+
+/**
+ * Visual weight of a button.
+ * - `filled`: solid background, highest emphasis.
+ * - `tonal`: soft tinted background, medium emphasis.
+ * - `outlined`: bordered, transparent background, lowest emphasis.
+ *
+ * Every variant carries at least a visible border, per Staffa's "everything is
+ * legible at a glance" principle.
+ */
+export type ButtonVariant = "filled" | "tonal" | "outlined";
+
+/**
+ * Color of a button.
+ *
+ * The four named **semantic roles** map to theme colours and are offered as
+ * autocomplete suggestions. You may also pass *any* CSS colour the browser
+ * understands and it becomes the button's accent directly: a literal like
+ * `"#ef6b00"` / `"rgb(255 107 0)"`, or a theme custom-property reference like
+ * `"$sWarning"` (Aberdeen's `$name` shorthand for `var(--name)`).
+ *
+ * The `(string & {})` member is what keeps the literal suggestions visible while
+ * still allowing arbitrary strings — TypeScript only widens to `string` lazily.
+ */
+export type ButtonColor = "primary" | "neutral" | "danger" | "success" | (string & {});
+
+/** Options for {@link button}. */
+export interface ButtonOptions extends BaseOptions {
+	/** Button label text. */
+	text?: string;
+	/** Custom content (overrides {@link ButtonOptions.text | text}). */
+	content?: Content;
+	/** Leading icon/adornment, drawn before the label. */
+	icon?: Slot;
+	/** Click handler. */
+	click?: (event: Event) => void;
+	/** Visual weight. Defaults to `"filled"`. */
+	variant?: ButtonVariant;
+	/** Color role. Defaults to `"primary"`. */
+	color?: ButtonColor;
+	/** Size. Defaults to `"md"`. */
+	size?: "sm" | "md" | "lg";
+	/** Disables the button. */
+	disabled?: boolean;
+	/** Native button behaviour. Defaults to `"button"`. */
+	type?: "button" | "submit" | "reset";
+	/** Render as a link (`<a role=button>`) pointing here instead of a `<button>`. */
+	href?: string;
+	/** Accessible label, when the button has only an icon. */
+	ariaLabel?: string;
+	/** Aberdeen attr/style string applied to the button element. */
+	inner?: Styling;
+}
+
+// The color role sets a local `--c` (and `--cfg` for text on filled); the
+// variant rules consume them, so we avoid writing colour×variant rules.
+A.insertGlobalCss({
+	".S_btn": {
+		"&":
+			"--c:$sPrimary --cfg:$sPrimaryFg " +
+			"display:inline-flex align-items:center justify-content:center gap:$2 " +
+			"font-weight:600 line-height:1.2 white-space:nowrap cursor:pointer text-decoration:none " +
+			"border: 1px solid transparent; r:$sRadius padding: 0.5em 1em; " +
+			"transition: background 0.15s, border-color 0.15s, filter 0.15s, box-shadow 0.15s;",
+		"&:focus-visible": "outline:none box-shadow: 0 0 0 3px $sFocus;",
+		"&:disabled, &[aria-disabled=true]": "opacity:0.45 cursor:not-allowed pointer-events:none filter:saturate(0.6)",
+		// Colour roles.
+		"&.S_neutral": "--c:$sBorderStrong --cfg:$sFg",
+		"&.S_danger": "--c:$sDanger --cfg:#fff",
+		"&.S_success": "--c:$sSuccess --cfg:#08110d",
+		// Variants.
+		"&.S_filled": "background:$c color:$cfg border-color:$c",
+		"&.S_filled:hover": "filter:brightness(1.1)",
+		"&.S_tonal": "color:$c background: color-mix(in srgb, $c 20%, transparent); border-color: color-mix(in srgb, $c 30%, transparent);",
+		"&.S_tonal:hover": "background: color-mix(in srgb, $c 30%, transparent);",
+		"&.S_outlined": "color:$c background:transparent border-color: color-mix(in srgb, $c 55%, $sBorder);",
+		"&.S_outlined:hover": "background: color-mix(in srgb, $c 12%, transparent);",
+		// Sizes.
+		"&.S_sm": "padding: 0.32em 0.7em; font-size:0.85em",
+		"&.S_lg": "padding: 0.66em 1.3em; font-size:1.1em",
+	},
+});
+
+/**
+ * A button. Always carries at least a visible border so its affordance is
+ * obvious at a glance, regardless of {@link ButtonVariant | variant}.
+ *
+ * Shortcut: pass a string to use it as the label, or a function for custom
+ * content.
+ *
+ * @example
+ * ```ts
+ * S.button({ text: "Save", click: save });
+ * S.button({ text: "Delete", color: "danger", variant: "outlined", click: del });
+ * S.button("Cancel");                        // shorthand for { text: "Cancel" }
+ * S.button({ href: "/docs", text: "Docs" }); // renders an <a role=button>
+ * ```
+ */
+export function button(opts: ButtonOptions | string | Content = {}): void {
+	const o: ButtonOptions = typeof opts === "string" ? { text: opts } : typeof opts === "function" ? { content: opts } : opts;
+
+	const tag = o.href != null ? "a" : "button";
+	const variant = o.variant ?? "filled";
+	const color = o.color ?? "primary";
+	const size = o.size === "sm" || o.size === "lg" ? `.S_${o.size}` : "";
+
+	// Semantic roles select a colour class (the CSS sets `--c`/`--cfg`); any other
+	// value is a raw CSS colour we assign to `--c`, which the variant rules consume
+	// via `var(--c)`. (`primary` is the base default — its class is a no-op.)
+	const semantic = color === "primary" || color === "neutral" || color === "danger" || color === "success";
+	const colorCls = semantic ? `.S_${color}` : "";
+
+	const el = A(`${tag}.S_btn.S_${variant}${colorCls}${size}`, o.root, o.inner, () => {
+		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");
+		}
+		if (o.ariaLabel) A("aria-label=", o.ariaLabel);
+		if (o.click) A("click=", o.click);
+
+		drawSlot(o.icon);
+		if (o.content) o.content();
+		else if (o.text != null) A("#", o.text);
+	});
+
+	// Aberdeen's inline styler doesn't set CSS custom properties, so assign the
+	// custom accent on the element directly. A leading `$` is Aberdeen's shorthand
+	// for a CSS variable reference, so expand it to `var(--name)`.
+	if (!semantic && el instanceof HTMLElement) {
+		el.style.setProperty("--c", color.startsWith("$") ? `var(--${color.slice(1)})` : color);
+	}
+}

package/src/components/buttonGroup.ts

@@ -0,0 +1,63 @@
+import A from "aberdeen";
+import type { ContentOptions } from "../core.js";
+import { type ButtonOptions, button } from "./button.js";
+
+/** Options for {@link buttonGroup}. */
+export interface ButtonGroupOptions extends ContentOptions {
+	/**
+	 * Declarative list of buttons. Rendered in order. Alternatively (or
+	 * additionally) draw buttons yourself via {@link ContentOptions.content}.
+	 */
+	buttons?: ButtonOptions[];
+	/**
+	 * `"attached"` (default) joins the buttons into a single segmented control
+	 * with shared borders; `"spaced"` lays them out with a normal gap.
+	 */
+	layout?: "attached" | "spaced";
+	/** Stack vertically instead of horizontally. */
+	vertical?: boolean;
+}
+
+A.insertGlobalCss({
+	".S_bgroup": {
+		"&": "display:inline-flex align-items:stretch",
+		"&.S_spaced": "gap:$2 flex-wrap:wrap",
+		"&.S_vertical": "flex-direction:column",
+		"&.S_attached": "gap:0",
+		// When attached, collapse the shared border and square off the touching
+		// corners, keeping only the outer ends of the group rounded.
+		"&.S_attached:not(.S_vertical) > .S_btn:not(:first-child)": "margin-left:-1px",
+		"&.S_attached:not(.S_vertical) > .S_btn:not(:first-child):not(:last-child)": "r:0",
+		"&.S_attached:not(.S_vertical) > .S_btn:first-child:not(:last-child)": "border-top-right-radius:0 border-bottom-right-radius:0",
+		"&.S_attached:not(.S_vertical) > .S_btn:last-child:not(:first-child)": "border-top-left-radius:0 border-bottom-left-radius:0",
+		"&.S_attached.S_vertical > .S_btn:not(:first-child)": "margin-top:-1px",
+		"&.S_attached.S_vertical > .S_btn:not(:first-child):not(:last-child)": "r:0",
+		"&.S_attached.S_vertical > .S_btn:first-child:not(:last-child)": "border-bottom-left-radius:0 border-bottom-right-radius:0",
+		"&.S_attached.S_vertical > .S_btn:last-child:not(:first-child)": "border-top-left-radius:0 border-top-right-radius:0",
+		// Keep the hovered/focused button's border above its neighbours.
+		"&.S_attached > .S_btn:hover, &.S_attached > .S_btn:focus-visible": "z-index:1",
+	},
+});
+
+/**
+ * Groups related buttons, either as a joined segmented control (`attached`) or
+ * spaced out. A `role=group` is applied for assistive tech.
+ *
+ * @example
+ * ```ts
+ * S.buttonGroup({ buttons: [
+ *   { text: "Day", variant: "outlined", color: "neutral" },
+ *   { text: "Week", variant: "outlined", color: "neutral" },
+ *   { text: "Month", variant: "outlined", color: "neutral" },
+ * ]});
+ * ```
+ */
+export function buttonGroup(opts: ButtonGroupOptions = {}): void {
+	const layout = opts.layout ?? "attached";
+	const cls = `.S_${layout}${opts.vertical ? ".S_vertical" : ""}`;
+
+	A(`div.S_bgroup${cls} role=group`, opts.root, opts.inner, () => {
+		if (opts.buttons) for (const b of opts.buttons) button(b);
+		if (opts.content) opts.content();
+	});
+}

package/src/components/checkbox.ts

@@ -0,0 +1,70 @@
+import A from "aberdeen";
+import { type Bindable, type Slot, drawSlot, uniqueId } from "../core.js";
+import type { FieldOptions } from "./field.js";
+
+/** Options for {@link checkbox}. */
+export interface CheckboxOptions extends Omit<FieldOptions, "label"> {
+	/** The label shown next to the box. Required for a meaningful checkbox. */
+	label?: Slot;
+	/** Two-way binding target holding a boolean. */
+	bind?: Bindable<boolean>;
+	/** Static initial checked state. */
+	checked?: boolean;
+	/** Fired on `change` with the native event. */
+	change?: (event: Event) => void;
+}
+
+A.insertGlobalCss({
+	".S_check": {
+		"&": "display:flex flex-direction:column gap:$1",
+		"> label": "display:flex align-items:center gap:$2 cursor:pointer user-select:none",
+		"> label:has(input:disabled)": "cursor:not-allowed opacity:0.6",
+		// Native control styled with accent-color: accessible and zero-fuss.
+		"input": "width:1.15em height:1.15em accent-color:$sPrimary cursor:inherit m:0",
+	},
+});
+
+/**
+ * A checkbox with an associated, clickable label. Uses the native `<input
+ * type=checkbox>` (styled with `accent-color`) for full keyboard and screen
+ * reader support.
+ *
+ * @example
+ * ```ts
+ * S.checkbox({ label: "Subscribe to newsletter", bind: A.ref($prefs, "newsletter") });
+ * ```
+ */
+export function checkbox(opts: CheckboxOptions = {}): void {
+	const id = opts.id ?? uniqueId("check");
+
+	A("div.S_check", opts.root, () => {
+		A(`label for=${id}`, () => {
+			A("input type=checkbox", opts.control, () => {
+				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);
+				A(() => {
+					if (opts.disabled) A("disabled=true");
+				});
+				A(() => {
+					if (opts.required) A("aria-required=true");
+				});
+				if (opts.bind) A("bind=", opts.bind);
+			});
+			// Own scope so the label text/required marker don't recreate the input.
+			A(() => {
+				if (opts.label != null) drawSlot(opts.label);
+				if (opts.required) A("span.S_req aria-hidden=true #*");
+			});
+		});
+
+		A(() => {
+			if (opts.help != null && !opts.error) A("div.S_help", () => drawSlot(opts.help));
+		});
+		A(() => {
+			if (opts.error) A("div.S_error role=alert #", opts.error);
+		});
+	});
+}