staffa 0.6.0 → 0.7.0

package/skill/TabsOptions.md

@@ -0,0 +1,28 @@
+## TabsOptions · interface
+
+Options for `tabs`.
+
+### tabsOptions.attrs · member
+
+Aberdeen attr/style string applied to the outermost element.
+
+**Type:** `string`
+
+### tabsOptions.tabs · member
+
+The tabs to display.
+
+**Type:** `Tab[]`
+
+### tabsOptions.bind · member
+
+Two-way binding for the selected tab's id. When omitted, the component keeps
+its own internal selection, starting at the first tab.
+
+**Type:** `Bindable<string>`
+
+### tabsOptions.contentAttrs · member
+
+Aberdeen attr/style string applied to the active panel.
+
+**Type:** `string`

package/skill/TextareaOptions.md

@@ -0,0 +1,51 @@
+## TextareaOptions · interface
+
+Options for `textarea`.
+
+### textareaOptions.placeholder · member
+
+Placeholder text.
+
+**Type:** `string`
+
+### textareaOptions.bind · member
+
+Two-way binding target.
+
+**Type:** `Bindable<string>`
+
+### textareaOptions.value · member
+
+Static initial value.
+
+**Type:** `string`
+
+### textareaOptions.rows · member
+
+Visible number of text rows. Defaults to `4`. Ignored when `autoGrow` is enabled.
+
+**Type:** `number`
+
+### textareaOptions.resize · member
+
+Whether the textarea may be resized by the user. Defaults to `"vertical"`. Ignored when `autoGrow` is enabled.
+
+**Type:** `"none" | "vertical" | "horizontal" | "both"`
+
+### textareaOptions.autoGrow · member
+
+Auto-grow the textarea to fit its content. Defaults to `true`.
+
+**Type:** `boolean`
+
+### textareaOptions.input · member
+
+Fired on every `input` event.
+
+**Type:** `(event: Event) => void`
+
+### textareaOptions.change · member
+
+Fired on `change` (commit).
+
+**Type:** `(event: Event) => void`

package/skill/TextlineOptions.md

@@ -0,0 +1,45 @@
+## TextlineOptions · interface
+
+Options for `textline`.
+
+### textlineOptions.type · member
+
+Input type. Defaults to `"text"`.
+
+**Type:** `TextlineType`
+
+### textlineOptions.placeholder · member
+
+Placeholder text.
+
+**Type:** `string`
+
+### textlineOptions.bind · member
+
+Two-way binding target (e.g. `A.ref($user, "name")`).
+
+**Type:** `Bindable<string | number>`
+
+### textlineOptions.value · member
+
+Static initial value (use | bind for reactivity).
+
+**Type:** `string | number`
+
+### textlineOptions.autocomplete · member
+
+Autocomplete hint passed to the native `autocomplete` attribute.
+
+**Type:** `string`
+
+### textlineOptions.input · member
+
+Fired on every `input` event with the native event.
+
+**Type:** `(event: Event) => void`
+
+### textlineOptions.change · member
+
+Fired on `change` (commit) with the native event.
+
+**Type:** `(event: Event) => void`

package/skill/TextlineType.md

@@ -0,0 +1,18 @@
+## TextlineType · type
+
+The `<input>` types `textline` supports. Deliberately excludes types
+that need their own widget (`checkbox`, `radio`, `color`, `range`, `file`,
+`button`, ...) — use the dedicated components for those.
+
+**Type:** `| "text"
+	| "password"
+	| "email"
+	| "number"
+	| "tel"
+	| "url"
+	| "search"
+	| "date"
+	| "time"
+	| "datetime-local"
+	| "month"
+	| "week"`

package/skill/ToastOptions.md

@@ -0,0 +1,40 @@
+## ToastOptions · interface
+
+Options for `toast`.
+
+### toastOptions.message · member
+
+Primary message. A string is rendered as rich text.
+
+**Type:** `Slot`
+
+### toastOptions.title · member
+
+Optional bold title above the message.
+
+**Type:** `Slot`
+
+### toastOptions.type · member
+
+Colour role. Defaults to `"neutral"`.
+
+**Type:** `"success" | "danger" | "warning" | "neutral"`
+
+### toastOptions.duration · member
+
+Auto-dismiss delay in milliseconds. Defaults to `6000`.
+Pass `0` to make the toast persistent until dismissed manually.
+
+**Type:** `number`
+
+### toastOptions.dismissible · member
+
+Show a close button. Defaults to `true`.
+
+**Type:** `boolean`
+
+### toastOptions.attrs · member
+
+Aberdeen attr/style string applied to the toast element.
+
+**Type:** `string`

package/skill/TooltipOptions.md

@@ -0,0 +1,22 @@
+## TooltipOptions · interface
+
+Options for `addTooltip`.
+
+### tooltipOptions.tip · member
+
+The tooltip text or draw function. A string is rendered as rich text.
+
+**Type:** `Slot`
+
+### tooltipOptions.placement · member
+
+Which side the tooltip appears on. Defaults to `"top"`.
+Automatically flips to the opposite side when there isn't enough room.
+
+**Type:** `"left" | "right" | "top" | "bottom"`
+
+### tooltipOptions.attrs · member
+
+Aberdeen attr/style string applied to the tip panel.
+
+**Type:** `string`

package/skill/addContextMenu.md

@@ -0,0 +1,28 @@
+## addContextMenu · function
+
+Attaches a context menu to the current element: adds a `contextmenu` handler
+via `A` so a | floating menu opens (instead of
+the browser's own menu) on right-click or long-press. The menu is anchored to
+the element and closes on Escape, Tab, item selection, or any click outside.
+
+**Signature:** `(opts: ContextMenuOptions) => void`
+
+**Parameters:**
+
+- `opts: ContextMenuOptions`
+
+**Examples:**
+
+```ts
+import * as icons from "staffa/icons";
+
+S.box(() => {
+  A("#Right-click / long-tap me!");
+  S.addContextMenu({
+    items: [
+      { label: "AI something", icon: icons.sparkles, click: () => ai() },
+      { label: "Launch missiles", icon: icons.rocket, click: () => launch() },
+    ],
+  });
+});
+```

package/skill/addTooltip.md

@@ -0,0 +1,29 @@
+## addTooltip · function
+
+Attaches a tooltip to the current element: adds hover/focus handlers via
+`A` so the tip appears when the element is hovered or keyboard-focused.
+The tip panel is rendered into `document.body` via a portal, so it is never
+clipped by `overflow:hidden` ancestors. Position is computed from the
+element's bounding rect and automatically flips when near the viewport edge.
+
+**Signature:** `(opts: TooltipOptions) => void`
+
+**Parameters:**
+
+- `opts: TooltipOptions`
+
+**Examples:**
+
+```ts
+S.button(() => {
+  A("#Save");
+  S.addTooltip({ tip: "Saves your work to the cloud" });
+});
+
+A(" ");
+
+S.button(() => {
+  A(".danger #Delete");
+  S.addTooltip({ tip: "Dangerous — cannot be undone", placement: "bottom" });
+});
+```

package/skill/alert.md

@@ -0,0 +1,17 @@
+## alert · function
+
+Shows a message dialog with a single OK button. Returns a `Promise<void>`
+that resolves when the user dismisses it.
+
+**Signature:** `(message: string, opts?: Partial<DialogOptions>) => Promise<void>`
+
+**Parameters:**
+
+- `message: string`
+- `opts: Partial<DialogOptions>` (optional)
+
+**Examples:**
+
+```ts
+await S.alert("File saved successfully.");
+```

package/skill/autocomplete.md

@@ -0,0 +1,29 @@
+## autocomplete · function
+
+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.
+
+**Signature:** `(opts: AutocompleteOptions) => void`
+
+**Parameters:**
+
+- `opts: AutocompleteOptions`
+
+**Examples:**
+
+```ts
+// Single select from a fixed list
+const $sel = A.proxy("Netherlands");
+S.autocomplete({ label: "Country", options: ["Belgium", "Netherlands"], bind: $sel });
+
+// Multi-select, disallowing custom items
+const $tags = A.proxy({value: [] as string[]});
+S.autocomplete({
+  label: "Tags",
+  multi: true,
+  allowCustom: false,
+  options: ["Rust", "JS", "C++", "Klingon", "Go"],
+  bind: A.ref($tags)
+});
+```

package/skill/box.md

@@ -0,0 +1,26 @@
+## box · function
+
+A surface container — the workhorse layout primitive. Has an optional styled
+header and footer, and a padded body that holds `ContentOptions.content`.
+
+The body gets default `padding` and matching `gap`; add `display:flex` via
+| contentAttrs if you want its children laid
+out as a flex container.
+
+Shortcut: pass a function to use it directly as the body content.
+
+**Signature:** `(opts?: BoxOptions | Slot) => void`
+
+**Parameters:**
+
+- `opts: BoxOptions | Slot` (optional)
+
+**Examples:**
+
+```ts
+const $user = A.proxy({name: "Kvothe"});
+S.box({ header: "Profile", contentAttrs: "display:flex flex-direction:column", content: () => {
+  S.textline({ label: "Name", bind: A.ref($user, "name") });
+}});
+S.box(() => A("p#Just some content"));   // shorthand
+```

package/skill/button.md

@@ -0,0 +1,31 @@
+## button · function
+
+A button. Tonal and outlined variants show a border; filled variants rely on
+their solid background for affordance.
+
+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
+import {interceptLinks} from from "aberdeen/route";
+interceptLinks(); // once at root
+S.button({ href: "/dashboard", content: "Dashboard" }); // navigates via router
+```
+
+**Signature:** `(opts?: Slot | ButtonOptions) => void`
+
+**Parameters:**
+
+- `opts: ButtonOptions | Slot` (optional)
+
+**Examples:**
+
+```ts
+S.button({ content: "Save", click: S.alert("Saved.") });
+S.button({ content: "Cancel", attrs: ".nest", click: cancel }); // neutral button
+S.button({ content: "Delete", attrs: ".danger .outlined", click: del });
+S.button("Cancel");                        // shorthand for { content: "Cancel" }
+S.button({ href: "/docs", content: "Docs" }); // renders an <a role=button>
+```

package/skill/buttonChooser.md

@@ -0,0 +1,23 @@
+## buttonChooser · function
+
+A single-selection segmented control: an attached button group where exactly
+one button is active at a time. Optionally allows deselecting back to `undefined`.
+
+Renders a hidden `<input>` alongside (when `name` is set) so the selected
+value is included in native form submission.
+
+**Signature:** `(opts: ButtonChooserOptions) => void`
+
+**Parameters:**
+
+- `opts: ButtonChooserOptions`
+
+**Examples:**
+
+```ts
+const $view = A.proxy({ value: "day" as string | undefined });
+S.buttonChooser({
+  options: { day: "Day", week: "Week", month: "Month" },
+  bind: $view,
+});
+```

package/skill/buttonGroup.md

@@ -0,0 +1,22 @@
+## buttonGroup · function
+
+Groups related buttons, either as a joined segmented control (`attached`) or
+spaced out. A `role=group` is applied for assistive tech.
+
+If you want a single button to be *selected*, use `buttonChooser`.
+
+**Signature:** `(opts?: ButtonGroupOptions) => void`
+
+**Parameters:**
+
+- `opts: ButtonGroupOptions` (optional)
+
+**Examples:**
+
+```ts
+S.buttonGroup({ buttons: [
+  { content: "Day", attrs: ".nest" },
+  { content: "Week", attrs: ".nest" },
+  { content: "Month", attrs: ".nest" },
+]});
+```

package/skill/checkbox.md

@@ -0,0 +1,18 @@
+## checkbox · function
+
+A checkbox with an associated, clickable label. Uses the native `<input
+type=checkbox>` (styled with `accent-color`) for full keyboard and screen
+reader support.
+
+**Signature:** `(opts?: CheckboxOptions) => void`
+
+**Parameters:**
+
+- `opts: CheckboxOptions` (optional)
+
+**Examples:**
+
+```ts
+const $prefs = A.proxy({newsletter: true});
+S.checkbox({ label: "Subscribe to newsletter", bind: A.ref($prefs, "newsletter") });
+```

package/skill/confirm.md

@@ -0,0 +1,17 @@
+## confirm · function
+
+Shows a confirmation dialog with Cancel and OK buttons. Returns a
+`Promise<boolean>` — `true` if the user clicked OK, `false` otherwise.
+
+**Signature:** `(message: string, opts?: Partial<DialogOptions>) => Promise<boolean>`
+
+**Parameters:**
+
+- `message: string`
+- `opts: Partial<DialogOptions>` (optional)
+
+**Examples:**
+
+```ts
+if (await S.confirm("Delete this item?")) S.alert("Gone!");
+```

package/skill/dialog.md

@@ -0,0 +1,28 @@
+## dialog · function
+
+A dialog rendered into `document.body` via `A.mount`, with a dimming backdrop
+that fades in and out. Returns a `Promise<void>` that resolves when the dialog
+closes. Lifecycle is also tied to the parent reactive scope — when that scope
+is cleaned up the dialog disappears and the promise resolves.
+
+Multiple dialogs stack correctly: each new pair (backdrop + dialog) has a
+higher z-index, while older dialogs are pushed behind their covering backdrop.
+
+**Signature:** `(opts: DialogOptions) => Promise<void>`
+
+**Parameters:**
+
+- `opts: DialogOptions`
+
+**Examples:**
+
+```ts
+S.dialog({
+  header: "Confirm",
+  content: (close) => {
+    A("p #Are you sure?");
+    S.button({ content: "Yes", click: () => { S.alert("Nice!"); close(); } });
+    S.button({ content: "Cancel", attrs: ".nest", click: close });
+  },
+});
+```

package/skill/form.md

@@ -0,0 +1,29 @@
+## form · function
+
+An opinionated `<form>` wrapper that lays its fields out consistently — a clean
+single column by default, or a responsive grid — and provides a standard
+action bar.
+
+Field components (("./textline").textline et al.) drop straight
+in as `ContentOptions.content`. Submission is wired so the browser's
+native validation runs, but the page never reloads.
+
+**Signature:** `(opts?: Slot | FormOptions) => void`
+
+**Parameters:**
+
+- `opts: FormOptions | Slot` (optional)
+
+**Examples:**
+
+```ts
+const $user = A.proxy({name: "Darth", email: "d.vader@example.com"});
+S.form({
+  submit: () => save(),
+  content: () => {
+    S.textline({ label: "Name", required: true, bind: A.ref($user, "name") });
+    S.textline({ label: "Email", type: "email", bind: A.ref($user, "email") });
+  },
+  actions: () => S.button({ content: "Save", type: "submit" }),
+});
+```

package/skill/getDarkMode.md

@@ -0,0 +1,12 @@
+## getDarkMode · function
+
+Whether dark mode is currently active. Reactive — read it inside a scope to
+re-run on changes.
+
+**Signature:** `(allowAuto?: boolean) => boolean`
+
+**Parameters:**
+
+- `allowAuto: any` (optional) - - When `true`, returns `undefined` (rather than a boolean) if
+the user is following the OS preference, so a dark/light/auto control can
+tell the three states apart.

package/skill/main.md

@@ -0,0 +1,37 @@
+## main · function
+
+An application shell that wires up the things almost every app needs: a sticky
+top bar (icon, title, subtitle, action menu), a scrollable content area, and a
+footer. With `MainOptions.maxWidth` the content area is centred and its
+width capped. Add a `nav` to get a responsive sidebar (auto-collapses to a
+menu button below 640 px, or always a button with `navPosition: "button"`).
+
+**Signature:** `(opts?: MainOptions) => void`
+
+**Parameters:**
+
+- `opts: MainOptions` (optional)
+
+**Examples:**
+
+```ts
+S.main({
+  icon: "✦",
+  title: "Staffa Demo",
+  maxWidth: "56rem",
+  nav: {
+    items: [
+      { label: "Home", icon: () => A("#🏠"), href: "/" },
+      { label: "Settings", href: "/settings" },
+    ],
+  },
+  navPosition: "left",
+  menu: () => S.button({ content: "New", attrs: ".small" }),
+  content: drawPage,
+  footer: "© 2026",
+});
+
+function drawPage() {
+  S.box({title: "Hello world", content: "Here's you app.."});
+}
+```

package/skill/menuButton.md

@@ -0,0 +1,27 @@
+## menuButton · function
+
+A button that opens a | floating dropdown menu on
+click. Keyboard navigation: Arrow Up/Down, Home, End; Escape/Tab to close;
+Enter/Space activate the focused item natively.
+
+**Tip:** set `href` on items and call `interceptLinks()` once at app startup
+for SPA navigation — active items are highlighted automatically.
+
+**Signature:** `(opts: MenuOptions) => void`
+
+**Parameters:**
+
+- `opts: MenuOptions`
+
+**Examples:**
+
+```ts
+S.menuButton({
+  button: { content: "Actions", attrs: ".nest" },
+  items: [
+    { label: "Edit", icon: () => A("#✎"), click: () => edit() },
+    { separator: true },
+    { label: "Delete", attrs: "fg:$s-danger", click: () => del() },
+  ],
+});
+```

package/skill/prompt.md

@@ -0,0 +1,19 @@
+## prompt · function
+
+Shows a prompt dialog with a text input. Returns a `Promise<string | null>` —
+the entered string if the user confirmed, or `null` if cancelled.
+
+**Signature:** `(message: string, defaultValue?: string, opts?: Partial<DialogOptions>) => Promise<string>`
+
+**Parameters:**
+
+- `message: string`
+- `defaultValue: any` (optional)
+- `opts: Partial<DialogOptions>` (optional)
+
+**Examples:**
+
+```ts
+const name = await S.prompt("Enter your name:", "Alice");
+if (name !== null) S.alert(`Hi ${name}!`);
+```

package/skill/select.md

@@ -0,0 +1,18 @@
+## select · function
+
+A single-select dropdown backed by a native `<select>` element. Looks like the
+other Staffa inputs but delegates all focus management, keyboard navigation, and
+mobile-native picker behaviour to the browser.
+
+**Signature:** `(opts: SelectOptions) => void`
+
+**Parameters:**
+
+- `opts: SelectOptions`
+
+**Examples:**
+
+```ts
+const $sel = A.proxy("Netherlands"); 
+S.select({ label: "Country", options: ["Belgium", "Netherlands"], bind: $sel });
+```

package/skill/showFloatingMenu.md

@@ -0,0 +1,21 @@
+## showFloatingMenu · function
+
+Open a floating dropdown menu anchored to an element. Portals to
+`document.body` (never clipped), positions itself (flipping up when there's
+no room below), and closes on Escape, Tab, item selection, or any click
+outside the panel and anchor. Returns a `close()` function.
+
+Menus are usually opened through `menuButton` or
+`addContextMenu`; reach for this primitive when you need to trigger a
+menu from some other event, anchored to an arbitrary element.
+
+**Signature:** `(opts: FloatingMenuOptions) => () => void`
+
+**Parameters:**
+
+- `opts: FloatingMenuOptions`
+
+**Examples:**
+
+```ts
+// An

package/skill/tabs.md

@@ -0,0 +1,19 @@
+## tabs · function
+
+A tabbed view. Renders an ARIA `tablist` of buttons and a single live panel
+for the selected tab. Supports keyboard navigation (left/right/home/end).
+
+**Signature:** `(opts: TabsOptions) => void`
+
+**Parameters:**
+
+- `opts: TabsOptions`
+
+**Examples:**
+
+```ts
+S.tabs({ tabs: [
+  { label: "Overview", content: () => A("p#Let me give you an overview..") },
+  { label: "Settings", content: () => S.checkbox({label: "I agree to anything", checked: true}) },
+]});
+```