staffa 0.1.0 → 0.3.0

package/dist/components/button.js

@@ -1,43 +1,59 @@
 import A from "aberdeen";
 import { drawSlot } from "../core.js";
-// 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": {
-        "&": "--c:$sPrimary --cfg:$sPrimaryFg " +
-            "display:inline-flex align-items:center justify-content:center gap:$2 " +
+    ".s-btn": {
+        "&": "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>
  * ```
@@ -45,15 +61,12 @@ A.insertGlobalCss({
 export function button(opts = {}) {
     const o = 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)
@@ -74,10 +87,4 @@ export function button(opts = {}) {
         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/dist/components/buttonChooser.d.ts

@@ -0,0 +1,41 @@
+import { type Bindable, type Attributes, type Slot } from "../core.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 declare function buttonChooser(opts: ButtonChooserOptions): void;

package/dist/components/buttonChooser.js

@@ -0,0 +1,38 @@
+import A from "aberdeen";
+import { buttonGroup } from "./buttonGroup.js";
+/**
+ * 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) {
+    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/dist/components/buttonGroup.d.ts

@@ -22,9 +22,9 @@ export interface ButtonGroupOptions extends ContentOptions {
  * @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" },
  * ]});
  * ```
  */

package/dist/components/buttonGroup.js

@@ -1,23 +1,20 @@
 import A from "aberdeen";
 import { button } from "./button.js";
 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",
     },
 });
 /**
@@ -27,16 +24,16 @@ 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 = {}) {
     const layout = opts.layout ?? "attached";
-    const cls = `.S_${layout}${opts.vertical ? ".S_vertical" : ""}`;
-    A(`div.S_bgroup${cls} role=group`, opts.root, opts.inner, () => {
+    const cls = `.s-${layout}${opts.vertical ? ".s-vertical" : ""}`;
+    A(`div.s-bgroup${cls} role=group`, opts.attrs, () => {
         if (opts.buttons)
             for (const b of opts.buttons)
                 button(b);

package/dist/components/checkbox.js

@@ -1,12 +1,12 @@
 import A from "aberdeen";
 import { drawSlot, uniqueId } from "../core.js";
 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",
     },
 });
 /**
@@ -21,9 +21,9 @@ A.insertGlobalCss({
  */
 export function checkbox(opts = {}) {
     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}`);
@@ -48,16 +48,16 @@ export function checkbox(opts = {}) {
                 if (opts.label != null)
                     drawSlot(opts.label);
                 if (opts.required)
-                    A("span.S_req aria-hidden=true #*");
+                    A("span.s-req aria-hidden=true #*");
             });
         });
         A(() => {
             if (opts.help != null && !opts.error)
-                A("div.S_help", () => drawSlot(opts.help));
+                A("div.s-help", () => drawSlot(opts.help));
         });
         A(() => {
             if (opts.error)
-                A("div.S_error role=alert #", opts.error);
+                A("div.s-error role=alert #", opts.error);
         });
     });
 }

package/dist/components/dialog.d.ts

@@ -1,18 +1,18 @@
-import { type Slot, type Styling } from "../core.js";
+import { type Slot, type Attributes } from "../core.js";
 /** Options for {@link dialog}. */
 export interface DialogOptions {
     /** Slot rendered in the styled header bar. */
     header?: Slot;
     /** Slot rendered in the styled footer bar. */
     footer?: Slot;
+    /** Aberdeen attr/style string applied to the dialog panel. A surface — pass modifier classes (e.g. `".warning"`) to recolour it. */
+    attrs?: Attributes;
     /** Aberdeen attr/style string applied to the header bar. */
-    headerInner?: Styling;
+    headerAttrs?: Attributes;
     /** Aberdeen attr/style string applied to the footer bar. */
-    footerInner?: Styling;
+    footerAttrs?: Attributes;
     /** Aberdeen attr/style string applied to the scrollable content `<div>`. */
-    inner?: Styling;
-    /** Aberdeen attr/style string applied to the dialog panel itself. */
-    root?: Styling;
+    contentAttrs?: Attributes;
     /**
      * Allow closing via Esc or clicking the backdrop. Defaults to `true`.
      * May be changed on a proxied options object while the dialog is open
@@ -20,10 +20,16 @@ export interface DialogOptions {
      */
     allowCancel?: boolean;
     /**
-     * Dialog body. Receives a `close()` function — call it to dismiss the dialog
-     * programmatically.
+     * When set to `true` (default) the model will be destroyed when the `dialog()`-calling
+     * scope is destroyed.
      */
-    content?: (close: () => void) => void;
+    cancelWithScope?: boolean;
+    /**
+     * Dialog body. A {@link Slot} whose draw-function receives a `close()` function
+     * — call it to dismiss the dialog programmatically. (A plain string renders as
+     * rich text.)
+     */
+    content?: Slot<[close: () => void]>;
     /**
      * Called when the dialog closes for any reason (explicit `close()`, Esc, or
      * backdrop click). Useful when you want a side-effect on close but don't need
@@ -37,11 +43,8 @@ export interface DialogOptions {
  * closes. Lifecycle is also tied to the parent reactive scope — when that scope
  * is cleaned up the dialog disappears and the promise resolves.
  *
- * Only the **last** open dialog (and its backdrop) is visible; earlier pairs are
- * hidden via the CSS `+` selector, so nested dialogs stack correctly.
- *
- * The header and footer are pinned; only the body content scrolls when it is
- * taller than `88vh`.
+ * Multiple dialogs stack correctly: each new pair (backdrop + dialog) has a
+ * higher z-index, while older dialogs are pushed behind their covering backdrop.
  *
  * @example
  * ```ts
@@ -50,7 +53,7 @@ export interface DialogOptions {
  *   content: (close) => {
  *     A("p #Are you sure?");
  *     S.button({ text: "Yes", click: () => { doIt(); close(); } });
- *     S.button({ text: "Cancel", variant: "outlined", click: close });
+ *     S.button({ text: "Cancel", attrs: ".neutral .outlined", click: close });
  *   },
  * });
  * ```
@@ -60,8 +63,6 @@ export declare function dialog(opts: DialogOptions): Promise<void>;
  * Shows a message dialog with a single OK button. Returns a `Promise<void>`
  * that resolves when the user dismisses it.
  *
- * All properties of `opts` override the defaults, including `content`.
- *
  * @example
  * ```ts
  * await S.alert("File saved successfully.");
@@ -70,10 +71,7 @@ export declare function dialog(opts: DialogOptions): Promise<void>;
 export declare function alert(message: string, opts?: Partial<DialogOptions>): Promise<void>;
 /**
  * Shows a confirmation dialog with Cancel and OK buttons. Returns a
- * `Promise<boolean>` — `true` if the user clicked OK, `false` otherwise
- * (including Esc / backdrop click when `allowCancel` is not `false`).
- *
- * All properties of `opts` override the defaults, including `content`.
+ * `Promise<boolean>` — `true` if the user clicked OK, `false` otherwise.
  *
  * @example
  * ```ts
@@ -83,10 +81,7 @@ export declare function alert(message: string, opts?: Partial<DialogOptions>): P
 export declare function confirm(message: string, opts?: Partial<DialogOptions>): Promise<boolean>;
 /**
  * Shows a prompt dialog with a text input. Returns a `Promise<string | null>` —
- * the entered string if the user confirmed, or `null` if cancelled (Esc /
- * backdrop click / Cancel button).
- *
- * All properties of `opts` override the defaults, including `content`.
+ * the entered string if the user confirmed, or `null` if cancelled.
  *
  * @example
  * ```ts