staffa 0.1.0 → 0.3.0

package/src/components/button.ts

@@ -1,33 +1,8 @@
 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 & {});
+import { type Content, type Slot, type Attributes, drawSlot } from "../core.js";
 
 /** Options for {@link button}. */
-export interface ButtonOptions extends BaseOptions {
+export interface ButtonOptions {
 	/** Button label text. */
 	text?: string;
 	/** Custom content (overrides {@link ButtonOptions.text | text}). */
@@ -36,12 +11,6 @@ export interface ButtonOptions extends BaseOptions {
 	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"`. */
@@ -50,50 +19,76 @@ export interface ButtonOptions extends BaseOptions {
 	href?: string;
 	/** Accessible label, when the button has only an icon. */
 	ariaLabel?: string;
-	/** Aberdeen attr/style string applied to the button element. */
-	inner?: Styling;
+	/**
+	 * Aberdeen attr/style string applied to the button. A button is a surface, so
+	 * pass surface modifier classes here to restyle it, e.g. `".danger"`,
+	 * `".neutral .outlined"`. Defaults to a filled `.primary` surface.
+	 *
+	 * Size is set here too, with `.small` or `.large` (medium is the default and
+	 * needs no class), e.g. `".danger .small"`. A `.small`/`.large` parent (such
+	 * as a {@link buttonGroup}) also sizes its buttons, so you can set it once.
+	 */
+	attrs?: Attributes;
 }
 
-// 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.
+// The button is a `.s-s` surface (defaulting to `.primary` in button() below), so
+// its colours come from the surface classes in theme.ts. This rule only handles
+// layout, border, focus, hover and sizing.
 A.insertGlobalCss({
-	".S_btn": {
+	".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;",
+			"border: 1px solid $s-border; r: $s-radius; padding: 0.5em 1em; " +
+			"transition: background 0.15s, border-color 0.15s, color 0.15s, filter 0.15s, box-shadow 0.15s, transform 0.08s;",
+		"&:focus-visible": "outline:none box-shadow: 0 0 0 3px $s-focus;",
 		"&: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",
+		// Every button lifts a little toward the cursor on hover (the transform is in
+		// the transition list above). The filled `.gradient` CTA below layers a deeper
+		// shadow on top of the same lift, so it still reads as the signature action.
+		"&:hover": "filter: brightness(1.08); transform: translateY(-1px)",
+		"&.tonal:hover, &.outlined:hover": "background: color-mix(in srgb, $s-b 26%, transparent);",
+		// A filled `.gradient` button (the default) is the app's signature call to
+		// action: a borderless gradient with a soft glow that lifts on hover. The
+		// gradient fill itself comes from the `.s-s.gradient` surface rule in theme.ts.
+		// No border: a filled gradient reads as one solid shape. Dropping the border
+		// (rather than making it transparent) also sidesteps a Chromium artifact where
+		// a gradient clipped to a transparent rounded border fringes the edge with the
+		// gradient's far colour.
+		"&.gradient:not(.tonal):not(.outlined)": "border:0 box-shadow: $s-glow;",
+		"&.gradient:not(.tonal):not(.outlined):hover":
+			"filter: brightness(1.06); box-shadow: 0 10px 28px color-mix(in srgb, $s-primary 42%, transparent); transform: translateY(-1px);",
+		// Subtle press feedback.
+		"&:active:not(:disabled):not([aria-disabled=true])": "transform: translateY(1px)",
+		// Size: set on the button itself, or inherited from a `.small`/`.large`
+		// parent (e.g. a buttonGroup), so a container can size all its buttons at once.
+		"&.small, .small > &": "padding: 0.32em 0.7em; font-size:0.85em",
+		"&.large, .large > &": "padding: 0.66em 1.3em; font-size:1.1em",
 	},
 });
 
+// Surface-role classes a caller may pass in `attrs`. When one is present we skip
+// the default `.gradient` base so the two roles don't stack on one element.
+const ROLE_CLASS = /\.(gradient|primary|secondary|neutral|danger|success|warning|base|panel|raised)(\.|\s|$)/;
+
 /**
  * A button. Always carries at least a visible border so its affordance is
- * obvious at a glance, regardless of {@link ButtonVariant | variant}.
+ * obvious at a glance.
  *
  * Shortcut: pass a string to use it as the label, or a function for custom
  * content.
  *
+ * **Tip:** pair `href` with Aberdeen's `interceptLinks()` (called once at app
+ * startup) for SPA-style navigation without manual click handlers:
+ * ```ts
+ * interceptLinks(); // once at root
+ * S.button({ href: "/dashboard", text: "Dashboard" }); // navigates via router
+ * ```
+ *
  * @example
  * ```ts
  * S.button({ text: "Save", click: save });
- * S.button({ text: "Delete", color: "danger", variant: "outlined", click: del });
+ * S.button({ text: "Delete", attrs: ".danger .outlined", click: del });
  * S.button("Cancel");                        // shorthand for { text: "Cancel" }
  * S.button({ href: "/docs", text: "Docs" }); // renders an <a role=button>
  * ```
@@ -102,17 +97,13 @@ 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, () => {
+	// A filled `.gradient` surface by default — the signature CTA. If the caller's
+	// `attrs` already names a surface role we omit the default, so `.danger`,
+	// `.neutral .outlined`, etc. fully take over (rather than stacking two roles).
+	// A bare variant/size (`.outlined`, `.small`) keeps the gradient base.
+	const role = o.attrs && ROLE_CLASS.test(o.attrs) ? "" : ".gradient";
+	A(`${tag}.s-btn.s-s${role}`, o.attrs, () => {
 		if (o.href != null) {
 			A(`href=${o.href} role=button`);
 			if (o.disabled) A("aria-disabled=true");
@@ -127,11 +118,4 @@ export function button(opts: ButtonOptions | string | Content = {}): void {
 		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/buttonChooser.ts

@@ -0,0 +1,65 @@
+import A from "aberdeen";
+import { type Bindable, type Attributes, type Slot } from "../core.js";
+import { buttonGroup } from "./buttonGroup.js";
+
+/** Options for {@link buttonChooser}. */
+export interface ButtonChooserOptions {
+	/** Aberdeen attr/style string applied to the button group. */
+	attrs?: Attributes;
+	/**
+	 * The options to display, as a plain object mapping id → display label.
+	 * Buttons appear in insertion order. A label may be a plain (rich-text)
+	 * string, or a draw-function for custom content such as an icon.
+	 */
+	options: Record<string, Slot>;
+	/**
+	 * Two-way binding for the selected id, or `null` when nothing is selected.
+	 * Use an `A.proxy` or `A.ref`.
+	 */
+	bind: Bindable<string | null>;
+	/**
+	 * When `true`, clicking the already-selected button deselects it, setting
+	 * `bind.value` to `null`. Useful for "none / auto" states.
+	 */
+	allowDeselect?: boolean;
+	/** Name attribute for the hidden `<input>`, enabling form submission. */
+	name?: string;
+}
+
+/**
+ * A single-selection segmented control: an attached button group where exactly
+ * one button is active at a time. Optionally allows deselecting back to `null`.
+ *
+ * Renders a hidden `<input>` alongside (when `name` is set) so the selected
+ * value is included in native form submission.
+ *
+ * @example
+ * ```ts
+ * const $view = A.proxy({ value: "day" as string | null });
+ * S.buttonChooser({
+ *   options: { day: "Day", week: "Week", month: "Month" },
+ *   bind: $view,
+ * });
+ * ```
+ */
+export function buttonChooser(opts: ButtonChooserOptions): void {
+	A(() => {
+		const selected = opts.bind.value;
+		buttonGroup({
+			attrs: opts.attrs,
+			buttons: Object.entries(opts.options).map(([id, label]) => ({
+				text: typeof label === "string" ? label : undefined,
+				content: typeof label === "function" ? label : undefined,
+				attrs: selected === id ? ".primary" : ".neutral .outlined",
+				click: () => {
+					opts.bind.value = (opts.allowDeselect && selected === id) ? null : id;
+				},
+			})),
+		});
+	});
+
+	if (opts.name) {
+		// Hidden input carries the value into native form submission.
+		A(() => A(`input type=hidden name=${opts.name} value=`, opts.bind.value ?? ""));
+	}
+}

package/src/components/buttonGroup.ts

@@ -19,23 +19,20 @@ export interface ButtonGroupOptions extends ContentOptions {
 }
 
 A.insertGlobalCss({
-	".S_bgroup": {
+	".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",
+		"&.s-spaced": "gap:$2 flex-wrap:wrap",
+		"&.s-vertical": "flex-direction:column",
+		"&.s-attached": "gap:0",
+		"&.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",
+		"&.s-attached > .s-btn:hover, &.s-attached > .s-btn:focus-visible": "z-index:1",
 	},
 });
 
@@ -46,17 +43,17 @@ A.insertGlobalCss({
  * @example
  * ```ts
  * S.buttonGroup({ buttons: [
- *   { text: "Day", variant: "outlined", color: "neutral" },
- *   { text: "Week", variant: "outlined", color: "neutral" },
- *   { text: "Month", variant: "outlined", color: "neutral" },
+ *   { text: "Day", attrs: ".neutral .outlined" },
+ *   { text: "Week", attrs: ".neutral .outlined" },
+ *   { text: "Month", attrs: ".neutral .outlined" },
  * ]});
  * ```
  */
 export function buttonGroup(opts: ButtonGroupOptions = {}): void {
 	const layout = opts.layout ?? "attached";
-	const cls = `.S_${layout}${opts.vertical ? ".S_vertical" : ""}`;
+	const cls = `.s-${layout}${opts.vertical ? ".s-vertical" : ""}`;
 
-	A(`div.S_bgroup${cls} role=group`, opts.root, opts.inner, () => {
+	A(`div.s-bgroup${cls} role=group`, opts.attrs, () => {
 		if (opts.buttons) for (const b of opts.buttons) button(b);
 		if (opts.content) opts.content();
 	});

package/src/components/checkbox.ts

@@ -15,12 +15,12 @@ export interface CheckboxOptions extends Omit<FieldOptions, "label"> {
 }
 
 A.insertGlobalCss({
-	".S_check": {
+	".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",
+		"input": "width:1.15em height:1.15em accent-color:$s-accent cursor:inherit m:0",
 	},
 });
 
@@ -37,9 +37,9 @@ A.insertGlobalCss({
 export function checkbox(opts: CheckboxOptions = {}): void {
 	const id = opts.id ?? uniqueId("check");
 
-	A("div.S_check", opts.root, () => {
+	A("div.s-check", opts.attrs, () => {
 		A(`label for=${id}`, () => {
-			A("input type=checkbox", opts.control, () => {
+			A("input type=checkbox", opts.inputAttrs, () => {
 				A(`id=${id}`);
 				if (opts.name) A(`name=${opts.name}`);
 				// `checked` is a boolean attribute: only set it when actually true.
@@ -56,15 +56,15 @@ export function checkbox(opts: CheckboxOptions = {}): void {
 			// 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 #*");
+				if (opts.required) A("span.s-req aria-hidden=true #*");
 			});
 		});
 
 		A(() => {
-			if (opts.help != null && !opts.error) A("div.S_help", () => drawSlot(opts.help));
+			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);
+			if (opts.error) A("div.s-error role=alert #", opts.error);
 		});
 	});
 }