staffa 0.1.0

package/README.md

@@ -0,0 +1,186 @@
+# Staffa
+
+A small, opinionated component library for the
+[Aberdeen](https://aberdeenjs.org) reactive UI library.
+
+Staffa components are **plain functions** that draw DOM through Aberdeen — no JSX,
+no web components, no build step required. You import a single `S` object and
+call its methods:
+
+```ts
+import A from "aberdeen";
+import S from "staffa";
+
+const $user = A.proxy({ name: "", email: "", subscribe: false });
+
+A.mount(document.body, () => {
+  S.main({
+    title: "Sign up",
+    maxWidth: "40rem",
+    content: () => {
+      S.form({
+        submit: () => console.log("submit", A.unproxy($user)),
+        content: () => {
+          S.textline({ label: "Name", required: true, bind: A.ref($user, "name") });
+          S.textline({ label: "Email", type: "email", bind: A.ref($user, "email") });
+          S.checkbox({ label: "Email me updates", bind: A.ref($user, "subscribe") });
+        },
+        actions: () => S.button({ text: "Create account", type: "submit" }),
+      });
+    },
+  });
+});
+```
+
+Staffa ships a **dark theme** by default and looks reasonable out of the box.
+
+> **Pre-1.0 notice:** Staffa's API is likely to change fairly often before stabilising as 1.0. That shouldn't stop you from using it — the library is small enough that any breaking changes are easy to adapt to yourself.
+
+## Install
+
+```sh
+npm install staffa aberdeen
+```
+
+Aberdeen is a **peer dependency** — Staffa builds on your app's single copy of
+Aberdeen rather than bundling its own (two copies of Aberdeen would mean two
+independent reactivity systems). So install `aberdeen` alongside `staffa`.
+
+Staffa is published as ESM with TypeScript types.
+
+## Components
+
+Every component takes a single typed options object. Common options are shared
+across all components:
+
+| Option     | On                       | Meaning                                                              |
+| ---------- | ------------------------ | ------------------------------------------------------------------- |
+| `root`     | every component          | Aberdeen attr/style string for the outermost element                |
+| `content`  | container components     | a `() => void` draw function for the children                       |
+| `inner`    | container components     | attr/style string for the element holding the children             |
+| `control`  | form fields              | attr/style string for the actual input element                      |
+| `label` / `help` / `error` / `disabled` / `required` / `name` | form fields | standard field chrome |
+
+`root`/`inner`/`control` are [Aberdeen style strings](https://aberdeenjs.org),
+e.g. `"display:flex gap:$3 .my-class"`. (Write `display:flex`, not bare `flex`.)
+
+### Layout & containers
+
+- **`S.main(opts)`** — app shell: sticky top bar (`icon`, `title`, `subtitle`,
+  `menu`), a scrollable content area, and a `footer`. Set `maxWidth` to center
+  the content as a shadowed "sheet".
+- **`S.box(opts | content)`** — a surface with optional `header`/`footer` and a
+  padded body. Pass a function as a shorthand for `content`.
+- **`S.tabs(opts)`** — a `tablist` + live panel, with full keyboard navigation.
+- **`S.form(opts | content)`** — opinionated `<form>` that aligns fields in a
+  column (or a responsive `grid`) and provides an `actions` bar. Prevents the
+  default page reload.
+
+### Form fields
+
+- **`S.textline(opts)`** — single-line `<input>` (`text`, `password`, `email`,
+  `number`, `tel`, `url`, `search`, dates, ...).
+- **`S.textarea(opts)`** — multi-line input.
+- **`S.checkbox(opts)`** — labelled checkbox.
+- **`S.select(opts)`** — single-select dropdown backed by a native `<select>`.
+  The control is styled; the OS renders the drop-down list.
+- **`S.autocomplete(opts)`** — a type-ahead combobox; supports `multi` (chips),
+  `allowCustom` (free text), `required`, and dynamic `options`.
+
+### Dialogs
+
+- **`S.modal(opts)`** — dialog rendered into `document.body`, with a dimming
+  backdrop and fade transition. Lifecycle is tied to the calling reactive scope
+  (the modal disappears when that scope is cleaned up). The `content` callback
+  receives a `close()` function. Nested modals stack correctly.
+
+### Actions
+
+- **`S.button(opts | "text")`** — `variant` is `filled` | `tonal` | `outlined`;
+  `color` is `primary` | `neutral` | `danger` | `success`; plus `size`,
+  `disabled`, `icon`, and `href` (renders an `<a role=button>`).
+- **`S.buttonGroup(opts)`** — groups buttons, `attached` (segmented) or `spaced`.
+
+Two-way binding uses Aberdeen observables: pass `bind: A.ref($obj, "key")` (or
+any `{ value }` proxy) to fields.
+
+## Reactive options
+
+An options object — or any part of it — **may be an Aberdeen proxy**. Mutate it
+later and the affected part of the component re-renders in place:
+
+```ts
+const $opts = A.proxy({ text: "Save", disabled: false });
+S.button($opts);
+// ...later:
+$opts.disabled = true;   // the button updates, nothing else re-renders
+```
+
+## Theming
+
+Staffa is themed via CSS custom properties. `S.darkTheme` and `S.lightTheme` are
+live Aberdeen proxies — mutate them to restyle either scheme; changes flow into
+the CSS variables immediately:
+
+```ts
+S.darkTheme.sPrimary = "#28c4a0";
+S.darkTheme.sPrimaryFg = "#08110d";
+S.lightTheme.sRadius = "6px";
+```
+
+See the `Theme` type for all variables (`sBg`, `sSurface`, `sFg`, `sBorder`,
+`sPrimary`, `sDanger`, `sSuccess`, `sRadius`, `sShadow`, ...).
+
+### Dark / light mode
+
+Staffa follows the OS preference by default. Override it at runtime:
+
+```ts
+S.setDarkMode(true);      // force dark
+S.setDarkMode(false);     // force light
+S.setDarkMode(undefined); // follow OS again
+```
+
+The choice is persisted to `localStorage` and applied before the first paint
+(no flash). `S.getDarkMode()` returns the resolved boolean; pass `true` to get
+`undefined` when in "auto" mode (useful for a dark/light/auto control).
+
+All Staffa styles are **global** and use `S_`-prefixed class names, so you can
+also override anything from your own stylesheet.
+
+## Browser (no bundler)
+
+`staffa/all.js` is a pre-built ESM bundle that includes all of Staffa but keeps
+Aberdeen external. Use an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap)
+to tell the browser where to find both:
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "aberdeen": "https://cdn.jsdelivr.net/npm/aberdeen/dist/src/aberdeen.js",
+    "staffa/all.js": "https://cdn.jsdelivr.net/npm/staffa/dist/staffa.esm.js"
+  }
+}
+</script>
+<script type="module">
+  import A from "aberdeen";
+  import S from "staffa/all.js";
+  // ...
+</script>
+```
+
+Aberdeen stays external so if your app already loads it you won't get two
+independent copies.
+
+## Demo & development
+
+```sh
+npm run build      # compile TypeScript to dist/
+npx serve .        # then open /demo/ in a browser
+```
+
+`npm run smoke` builds and renders every component in jsdom as a quick check.
+
+Contributing or extending Staffa? See [`AGENTS.md`](./AGENTS.md) for the design
+philosophy and the add-a-component checklist.

package/dist/components/autocomplete.d.ts

@@ -0,0 +1,44 @@
+import { type Bindable } from "../core.js";
+import { type FieldOptions } from "./field.js";
+/** A selectable option: a bare string, or a `{ value, label }` pair. */
+export type AutocompleteOptionInput = string | {
+    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 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 declare function autocomplete(opts: AutocompleteOptions): void;

package/dist/components/autocomplete.js

@@ -0,0 +1,250 @@
+import A from "aberdeen";
+import { uniqueId } from "../core.js";
+import { drawField } from "./field.js";
+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) {
+    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) {
+    const menuId = uniqueId("ac-menu");
+    const $st = A.proxy({ query: "", open: false, active: 0 });
+    const getOptions = () => {
+        const raw = typeof opts.options === "function" ? opts.options() : opts.options;
+        return raw.map(normOption);
+    };
+    const selectedValues = () => {
+        const v = opts.bind?.value;
+        if (v == null || v === "")
+            return [];
+        return Array.isArray(v) ? v : [v];
+    };
+    const labelFor = (value) => 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 = () => {
+        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, inputEl) => {
+        if (opts.multi) {
+            const arr = Array.isArray(opts.bind?.value) ? [...opts.bind.value] : [];
+            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) => {
+        if (!opts.bind)
+            return;
+        const arr = opts.bind.value ?? [];
+        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;
+            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) => {
+                                    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) => onKey(e, inputEl));
+                });
+            });
+            // 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) => 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) => 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, inputEl) {
+        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/dist/components/box.d.ts

@@ -0,0 +1,31 @@
+import { type Content, type ContentOptions, type Slot, type Styling } 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 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 declare function box(opts?: BoxOptions | Content): void;

package/dist/components/box.js

@@ -0,0 +1,48 @@
+import A from "aberdeen";
+import { drawSlot } from "../core.js";
+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 = {}) {
+    const o = 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/dist/components/button.d.ts

@@ -0,0 +1,67 @@
+import { type BaseOptions, type Content, type Slot, type Styling } 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 Skye'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;
+}
+/**
+ * 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 declare function button(opts?: ButtonOptions | string | Content): void;