staffa 0.6.0 → 0.7.0

package/skill/SKILL.md

@@ -0,0 +1,609 @@
+---
+name: staffa
+description: Documentation for the Staffa component library for Aberdeen. Covers *surfaces*, CSS variables for colors etc, how to the various `s-` prefixed css classes, customizing, overriding style, adding own components. Access this if you're doing front-end work on an Aberdeen project that already uses Staffa, or may benefit from it.
+---
+
+# Staffa
+
+A small, opinionated TypeScript component library for the [Aberdeen](https://aberdeenjs.org) reactive UI library.
+
+```ts
+import A from "aberdeen";
+import * as S from "staffa";
+
+const $user = A.proxy({ name: "", email: "" });
+
+S.main({
+  title: "Sign up",
+  maxWidth: "40rem",
+  content: () => {
+    S.form({
+      submit: () => S.dialog({
+        header: "Submitted",
+        content: () => A.dump($user)
+      }),
+      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: "Create account", type: "submit" }),
+    });
+  },
+});
+```
+
+Staffa is made to look decent out of the box, but easily customizable at runtime.
+
+## Screenshot
+
+![Screenshot](screenshot.png)
+
+## Install
+
+```sh
+npm install staffa aberdeen
+```
+
+Aberdeen is a peer dependency. Staffa is published as ESM with TypeScript types.
+
+## How it works
+
+### Components are functions
+
+Every component takes a single typed options object and draws DOM via Aberdeen. No classes, no web components. The `S` object collects all component functions:
+
+```ts
+S.button({ content: "Save", disabled: false });
+S.box({ header: "Settings", content: () => { ... } });
+```
+
+### Options objects are typed and can be reactive
+
+All components get their options in a typed object. The object may be an Aberdeen proxy, if you want to update the component in-place.
+
+```ts
+const $btn = A.proxy({ content: "Save", disabled: false });
+S.button($btn);
+setTimeout(() => // Later..
+  $btn.disabled = true;  // button updates instantly
+}, 3000);
+```
+
+### Rich text slots
+
+Anywhere a component takes content, a `label`, `header`, button `text`, dialog body, etc, you can pass either a string or a `() => void` draw function. Strings render as **rich text**: `*italic*`, `**bold**`, `` `code` ``, `[link](/path)`. All text is safely escaped.
+
+```ts
+S.button({ content: "Save **now**" });
+S.box({ header: "See the [docs](/docs)", content: () => { ... } });
+```
+
+### Surfaces
+
+Staffa builds on **surfaces**: elements marked with `.s-s` that have their own background and derived text/border tokens. There are two families:
+
+- **Nesting surfaces** — `.nest` (and the implicit page at `:root`). A calm neutral whose shade steps automatically with nesting depth (page → panel → raised, capped). Use them for cards, bars, popovers — anything that just holds content. No variants.
+- **Solid surfaces** — `.primary`, `.danger`, `.success`, `.warning`, `.link` (a bare `.s-s` defaults to primary). A bright fill with white ink, painted as a subtle single-colour gradient. They take a **variant**: `.filled` (default), `.tonal`, or `.outlined`. A surface nested *inside* a solid surface is always rendered filled, so it can't bleed into the vivid parent.
+
+Components are built from these (`S.button` is a `.s-s.primary`, `S.box` a `.s-s.nest`, etc.). Because component options include an optional `attrs` string, which has Aberdeen `A()` string semantics, you can easily override it:
+
+```ts
+S.button({ content: "Delete", attrs: ".danger" });
+S.button({ content: "Cancel", attrs: ".nest" });          // neutral button
+S.box({ attrs: ".primary", content: () => { ... } });
+```
+
+Inside any surface (including `:root`), CSS variables are defined for the background and a set of safe foreground colors: `$s-bg`, `$s-text` (also applied as `color`), `$s-muted`, `$s-accent` (the surface's "pop" — the brand primary on nesting surfaces, the ink on solid surfaces), and `$s-faint`. By using these, components adapt to wherever they're nested.
+
+The colour tokens are mode-independent and settable: `$s-primary` (the one brand colour — it tints the neutrals and defines `.s-s.primary`), `$s-danger`, `$s-success`, `$s-warning`, and `$s-link` (the link colour, which is also the fill of the `.s-s.link` surface). Links render in `$s-link` on nesting surfaces and in the ink on solid surfaces.
+
+**Borders & shadows.** Nesting surfaces carry a subtle hairline border on their own (so a card looks like a card without any component help). Any surface can be lifted with `.shadow` or `.extra-shadow`: on a nesting surface that's a neutral drop shadow, on a solid surface it's a self-coloured glow (a lit button is just a `.primary` surface with `.shadow`), and on `.tonal`/`.outlined` it's ignored. `.no-shadow` removes a component's built-in shadow:
+
+```ts
+S.box({ attrs: ".extra-shadow", content: () => { ... } });   // a more raised card
+S.button({ content: "Quiet", attrs: ".no-shadow" });          // drop the button glow
+```
+
+### Dark and light modes
+
+Dark/light mode is detected from OS preference by default. If you want to override this (based on user preferences), use:
+
+```ts
+S.setDarkMode(true);       // force dark
+S.setDarkMode(false);      // force light
+S.setDarkMode(undefined);  // follow OS
+```
+
+*Hint:* A `buttonChooser` is probably the right component for a color scheme selector.
+
+### CSS reset
+
+Staffa includes a lightweight CSS reset that makes bare semantic HTML look a bit better but unsurprising without additional styling. 
+
+### Theming
+
+The first step in theming is just setting some CSS variables. Everything derives from a single brand colour, `s-primary` (the neutral surface shades are tinted toward it too), so often that's all you need. This can be done through CSS directly, or using Aberdeen:
+
+```ts
+A.cssVars["s-primary"] = "#fdda58";
+A.cssVars["s-danger"] = "#ee4422";
+A.cssVars["s-radius"] = "4px";
+```
+
+See `src/theme.ts` for what other CSS variables are being used.
+
+If you need further customization, just add some CSS to override the default styling. For instance, to add your own solid surface, set its background (and, if needed, its ink) — the subtle gradient and the rest of the tokens follow automatically:
+
+```ts
+A.insertGlobalCss({".s-s.my-surface": "--s-bg:#ef6b00 --s-text:#fff"});
+
+S.button({
+  content: "You'll want to click me",
+  attrs: ".my-surface",
+  click: () => S.alert("Good work!", {attrs: ".my-surface"})
+});
+```
+
+Custom surface class names may be anything (other than the built-in modifiers `.tonal`, `.outlined`, `.small`, `.large`). The `.tonal` and `.outlined` variants work on your surface for free.
+
+Note that when changing CSS like this, things *may* break if you upgrade Staffa. The recommended update strategy is therefore: don't!
+
+If you want to make changes that are dependent upon the current light/dark mode setting, rely on Aberdeen reactivity:
+
+```ts
+A(() => {
+  if (S.getDarkMode()) {
+    A.cssVars["s-primary"] = "#aa9944";
+    A.insertGlobalCss({".s-s.my-surface": "--s-bg:#444444 --s-text:#fff"});
+  } else {
+    A.cssVars["s-primary"] = "#fdda58";
+    A.insertGlobalCss({".s-s.my-surface": "--s-bg:#cccccc --s-text:#000"});
+  }
+});
+```
+
+## Components
+
+Components share naming conventions for options: `attrs` (outermost element), `contentAttrs` (children-holding element), `inputAttrs` (form control element), and `<region>Attrs` (sub-regions like `headerAttrs`/`footerAttrs`). Form components consistently support `label`, `help`, `error`, `disabled`, `required`, `name` through the `drawField()` helper.
+
+### Layout & containers
+
+- **`S.main(opts)`**: app shell, a sticky header with `icon`, `title`, `subtitle`, `menu`; scrollable content area; footer. Set `maxWidth` to center the content.
+- **`S.box(opts | content)`**: surface with optional `header`/`footer` and padded body. Pass a function for shorthand `{ content }`.
+- **`S.tabs(opts)`**: tablist with live panels and keyboard navigation.
+- **`S.form(opts | content)`**: form aligning fields in a column or responsive grid, with 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 native `<select>` (styled control, OS dropdown).
+- **`S.autocomplete(opts)`**: type-ahead combobox with `multi` (chips), `allowCustom` (free text), `required`, and dynamic `options`.
+
+### Dialogs
+
+- **`S.dialog(opts)`**: modal dialog with backdrop and fade transition. The `content` slot receives a `close()` function. Lifecycle is tied to the calling scope (disappears when cleaned up). Nesting stacks correctly.
+- **`S.alert(msg)` / `S.confirm(msg)` / `S.prompt(msg, initial?)`**: promise-returning shortcuts.
+
+### Actions
+
+- **`S.button(opts | text)`**: button surface; restyle via `attrs` (e.g. `.danger`, `.outlined`), plus `size`, `disabled`, `icon`, `href` (renders `<a role=button>`). Defaults to filled `.primary`.
+- **`S.buttonGroup(opts)`**: groups buttons, `attached` (segmented) or `spaced`.
+- **`S.buttonChooser(opts)`**: single-select segmented control bound to a value.
+
+
+### Icons
+
+Staffa ships the full [Lucide icon set](https://lucide.dev/icons/) as named exports. Import only the ones you use, so a bundler tree-shakes the rest (the whole set is ~82 kB gzipped):
+
+Each icon is a draw function usable anywhere a slot is accepted (e.g. a button `icon`), or called directly. Customize per call, or globally via `setDefaults()`:
+
+```ts
+import * as S from "staffa";
+import { sparkles, bell } from "staffa/icons";
+S.button({ content: "Save", icon: bell });
+sparkles({ size: "1.5em", color: "var(--s-primary)", strokeWidth: 1.5 });
+```
+
+Options: `size`, `color` (defaults to `currentColor`), `strokeWidth`, `cap`, `join`, `attrs`.
+
+### Other
+
+- **`S.menuButton(opts)` / `S.addContextMenu(opts)` / `S.showFloatingMenu(opts)`**: dropdown menus from a button, right-click/long-press context menus, and the underlying floating menu primitive — with keyboard navigation.
+- **`S.toast(opts)`**: transient notification at the bottom of the viewport.
+- **`S.addTooltip(el, opts)`**: tooltip on hover, attached to an existing element.
+
+Two-way binding uses Aberdeen proxies: pass `bind: A.ref($obj, "key")` to form fields.
+
+## Browser (no bundler)
+
+`staffa/all.js` is a pre-built ESM bundle. Use an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap):
+
+```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 * as S from "staffa/all.js";
+  // ...
+</script>
+```
+
+It includes all components, but not the icons.
+
+## Extending Staffa
+
+Staffa is designed for extension. A component is simply a plain function taking a typed options object and drawing Aberdeen DOM. This section explains the philosophy so extensions follow the same patterns.
+
+### Design principles
+
+1. **Components are functions**. They take one typed options object, emit Aberdeen DOM, and *usually* return nothing.
+
+2. **Reuse option types.** Define options by extending `ContentOptions` (for layout components) or `FieldOptions` (for form controls) from `src/core.ts` and `src/components/field.ts`. Don't reinvent fields like `attrs`, `label`, `help`, etc.
+
+3. **Reach for reactivity deliberately.** Pass option strings straight to `A` as positional args (the caller's scope). Only wrap a dedicated `A(() => ...)` scope where it matters: input elements (recreation loses focus), or large subtrees you don't want to redraw. Use `A.peek(() => ...)` when you need a value but must not subscribe.
+
+4. **Build on surfaces.** Mark elements `.s-s` and add `.nest` (neutral) or a solid role (`.primary`, `.danger`, …) plus an optional variant. Inside them, use the contextual CSS variables (`$s-text`, `$s-bg`, `$s-muted`, `$s-accent`, `$s-faint`, ...) so components adapt to wherever they're nested. Hard-coding colors in components shouldn't be needed, but if you must, make sure you set *both* foreground and background.
+
+5. **No outer margins.** Components don't margin themselves; spacing is the parent's job. Content components set default `padding` on the content element; `contentAttrs` overrides it.
+
+6. **Make everything styleable.** Provide `attrs`, `contentAttrs`, `inputAttrs`, and `<region>Attrs` hooks so callers can customize. Apply `attrs` last so it can override component classes.
+
+7. **Use semantic HTML and ARIA.** Prefer native elements (`<button>`, `<label>`, `<form>`, `<section>`) and native behaviour. Add ARIA only where semantics fall short (e.g. tabs, combobox).
+
+8. **Use CSS.** Use `A.insertGlobalCss({...})` at module top level to provide (nested) CSS styling for your component. Give your top-level element the `s-<component-name>` class. Avoid inventing further classes; lean on nesting (`&` for the element, bare key for descendants) and element/structural selectors.  
+
+9. **Reuse form controls.** Use `drawField()` and call `applyControlAttrs()`.
+
+10. **Function over form.** Provide enough contrast. Stick to UI conventions to help users; buttons have a rounded border, links are underlined, text input background is white, etc.
+
+### Adding a component to Staffa
+
+The previous section is good advice for any project-specific custom, but should definitely be followed for any new components to be included in Staffa. In addition, you'd want to: 
+
+1. Create `src/components/<name>.ts`.
+2. Define `<Name>Options` extending `ContentOptions`, `FieldOptions`, or a plain interface. Add TSDoc on every option.
+3. Add a TSDoc `@example` on the function.
+4. Register in `src/index.ts` (the `S` object + type re-export).
+5. Extend `smoke.mjs` to render it. Run `npm run smoke` and `npm run build`.
+
+See `src/components/button.ts` and `src/components/dialog.ts` for examples.
+
+## Commands
+
+```sh
+npm run build      # compile TypeScript to dist/
+npm run typecheck  # check types
+npm run smoke      # render every component in jsdom
+npx http-server    # allows demo to be viewed at http://localhost:8080/demo
+npx shotest test   # visual tests: click through the demo, screenshotting every step
+npx shotest review # review/accept the visual changes against the baseline
+```
+
+The visual tests (`tests/*.spec.ts`) need a build first (`npm run build`); they serve the repo root themselves and click through every demo page. Accepted baselines live in `test-accepted/`.
+
+## AI skill
+
+If you use Claude Code, GitHub Copilot or another AI agents that supports Skills, Staffa includes a `skill/` directory that provides specialized knowledge to the AI about how to use the library effectively.
+
+To use this, it is recommended to symlink the skill into your project's `.claude/skills` directory:
+
+```sh
+mkdir -p .claude/skills
+ln -s ../../node_modules/staffa/skill .claude/skills/staffa
+```
+
+## Breaking changes
+
+- **0.7** — the surface model was simplified to two families: **nesting** (`.nest`) and **solid** (`.primary`/`.danger`/`.success`/`.warning`/`.link`).
+  - Surface levels `.base`/`.panel`/`.raised`/`.neutral` are replaced by a single `.nest` class whose shade steps with nesting depth. Replace them all with `.nest` (a neutral *button* is `.nest` too, in place of `.neutral .outlined`).
+  - `.secondary` and `.gradient` are gone: there is no more `s-secondary` colour, and the default button is `.primary` (which now carries a subtle auto-gradient). Drop `s-secondary` overrides.
+  - Solid surfaces now use **white** ink (was near-black), and the brand/semantic colours (`s-primary`/`s-danger`/`s-success`/`s-warning`) are now a single mode-independent value each.
+  - New: a `s-link` colour and a matching `.s-s.link` surface. Links use `s-link` on nesting surfaces, the ink on solid ones.
+  - Nesting surfaces now carry their own hairline border, and `.shadow`/`.extra-shadow`/`.no-shadow` utilities work on any surface. `S.box` no longer draws its own border/shadow (they come from the surface); pass `.no-shadow` to `S.box`/`S.button` to drop the default elevation.
+  - Contextual tokens were renamed/trimmed: `--s-fg`→`--s-text`, `--s-fg-muted`→`--s-muted`, `--s-border`→`--s-faint`; `--s-strong`, `--s-fg-faint`, `--s-border-strong`, `--s-on-accent`, `--s-ink`, `--s-page`/`--s-panel`/`--s-raised`, `--s-tint`, `--s-glow`, `--s-shadow`, `--s-gradient-surface`, and the `--s-a`/`--s-b` anchors were removed. Custom solid surfaces now set `--s-bg`/`--s-text`.
+
+- **0.6**: None.
+
+- **0.5**
+  - Surfaces (`.s-s`) now apply `border-radius` and — for `.tonal` and `.outlined` variants — `border` automatically. Custom surfaces or components that previously set these manually may see doubled or conflicting styles; remove the manual declarations.
+  - `border:0` is now applied to `.s-btn` by default (overriding the browser's 2px button border). Custom button-like components built on `.s-btn` that relied on the browser default border should add an explicit border.
+
+- **0.4**
+  - There is no default export anymore: replace `import S from "staffa"` with `import * as S from "staffa"`.
+  - `S.button` no longer has a `text` option: use `content` instead (it accepts a string or a draw function).
+  - The `Content` type is gone: use `Slot` instead. The `Styling` type alias is now exported as `Attributes`.
+  - `S.buttonChooser` uses `undefined` instead of `null` for "nothing selected" (in `bind` and with `allowDeselect`).
+  
+
+# API Reference
+
+## setDarkMode · function
+
+Force dark mode (`true`), light mode (`false`), or follow the OS preference
+(`undefined`). Takes effect immediately and is persisted to localStorage.
+
+**Signature:** `(value: boolean) => void`
+
+**Parameters:**
+
+- `value: boolean | undefined`
+
+## [getDarkMode](getDarkMode.md) · function
+
+Whether dark mode is currently active. Reactive — read it inside a scope to
+re-run on changes.
+
+## [autocomplete](autocomplete.md) · 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.
+
+## [AutocompleteOptions](AutocompleteOptions.md) · interface
+
+Options for `autocomplete`.
+
+## AutocompleteOptionInput · type
+
+A selectable option: a bare string, or a `{ value, label }` pair.
+
+**Type:** `string | { value: string; label?: string }`
+
+## [box](box.md) · function
+
+A surface container — the workhorse layout primitive. Has an optional styled
+header and footer, and a padded body that holds `ContentOptions.content`.
+
+## [BoxOptions](BoxOptions.md) · interface
+
+Options for `box`.
+
+## [button](button.md) · function
+
+A button. Tonal and outlined variants show a border; filled variants rely on
+their solid background for affordance.
+
+## [ButtonOptions](ButtonOptions.md) · interface
+
+Options for `button`.
+
+## [buttonChooser](buttonChooser.md) · 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`.
+
+## [ButtonChooserOptions](ButtonChooserOptions.md) · interface
+
+Options for `buttonChooser`.
+
+## [buttonGroup](buttonGroup.md) · function
+
+Groups related buttons, either as a joined segmented control (`attached`) or
+spaced out. A `role=group` is applied for assistive tech.
+
+## [ButtonGroupOptions](ButtonGroupOptions.md) · interface
+
+Options for `buttonGroup`.
+
+## [checkbox](checkbox.md) · 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.
+
+## [CheckboxOptions](CheckboxOptions.md) · interface
+
+Options for `checkbox`.
+
+## [form](form.md) · 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.
+
+## [FormOptions](FormOptions.md) · interface
+
+Options for `form`.
+
+## [main](main.md) · 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"`).
+
+## [MainOptions](MainOptions.md) · interface
+
+Options for `main`.
+
+## [menuButton](menuButton.md) · 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.
+
+## [showFloatingMenu](showFloatingMenu.md) · 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.
+
+## [addContextMenu](addContextMenu.md) · 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.
+
+## [MenuOptions](MenuOptions.md) · interface
+
+Options for `menuButton` and `MainOptions.nav`.
+
+## MenuEntry · type
+
+An entry in a menu or sidebar nav list. Three forms:
+- `MenuItem` — a clickable/linkable row with label and optional icon.
+- `MenuSeparator` — a visual divider (`{ separator: true }`).
+- A slot (string or draw function) — renders custom content (section header,
+  avatar, search box, …). Skipped by keyboard navigation.
+
+**Type:** `MenuItem | MenuSeparator | Slot`
+
+## [MenuItem](MenuItem.md) · interface
+
+A clickable item in a menu or sidebar nav.
+
+## MenuSeparator · interface
+
+A visual divider between groups of items.
+
+### menuSeparator.separator · member
+
+**Type:** `true`
+
+## [FloatingMenuOptions](FloatingMenuOptions.md) · interface
+
+Options for `showFloatingMenu`.
+
+## ContextMenuOptions · type
+
+Options for `addContextMenu` — like `FloatingMenuOptions`, but
+the anchor is the element the handler is attached to.
+
+**Type:** `Omit<FloatingMenuOptions, "anchor">`
+
+## [dialog](dialog.md) · 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.
+
+## [alert](alert.md) · function
+
+Shows a message dialog with a single OK button. Returns a `Promise<void>`
+that resolves when the user dismisses it.
+
+## [confirm](confirm.md) · function
+
+Shows a confirmation dialog with Cancel and OK buttons. Returns a
+`Promise<boolean>` — `true` if the user clicked OK, `false` otherwise.
+
+## [prompt](prompt.md) · 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.
+
+## [DialogOptions](DialogOptions.md) · interface
+
+Options for `dialog`.
+
+## [select](select.md) · 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.
+
+## [SelectOptions](SelectOptions.md) · interface
+
+Options for `select`.
+
+## SelectOptionInput · type
+
+A selectable option: a bare string, or a `{ value, label }` pair.
+
+**Type:** `string | { value: string; label?: string }`
+
+## [tabs](tabs.md) · 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).
+
+## [Tab](Tab.md) · interface
+
+A single tab definition.
+
+## [TabsOptions](TabsOptions.md) · interface
+
+Options for `tabs`.
+
+## [textarea](textarea.md) · function
+
+A multi-line text input. Shares the field chrome and styling of
+`textline`.
+
+## [TextareaOptions](TextareaOptions.md) · interface
+
+Options for `textarea`.
+
+## [textline](textline.md) · function
+
+A single-line text input — covering text, passwords, numbers, email, dates and
+the other line-oriented `<input>` types.
+
+## [TextlineOptions](TextlineOptions.md) · interface
+
+Options for `textline`.
+
+## [TextlineType](TextlineType.md) · 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.
+
+## [toast](toast.md) · function
+
+Show a toast notification. Returns a `dismiss()` function to remove it
+programmatically. Auto-dismisses after `duration` ms (default 6 000).
+
+## [ToastOptions](ToastOptions.md) · interface
+
+Options for `toast`.
+
+## [addTooltip](addTooltip.md) · 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.
+
+## [TooltipOptions](TooltipOptions.md) · interface
+
+Options for `addTooltip`.
+
+## [FieldOptions](FieldOptions.md) · interface
+
+Options shared by all *form field* components (textline, textarea, checkbox,
+autocomplete, ...).
+
+## [ContentOptions](ContentOptions.md) · interface
+
+Options for components that wrap a single block of caller-provided content,
+with an `attrs` escape hatch on the outermost element.
+
+## Bindable · type
+
+A reactive "value box", such as the result of `A.proxy(x)` or `A.ref(obj, key)`.
+
+**Type:** `{ value: T }`
+
+## [Slot](Slot.md) · type
+
+Something that renders a small piece of content: either a plain string or a
+draw function (for icons, badges, custom markup, ...).
+
+## [Attributes](Attributes.md) · type
+
+Shared building blocks for the Staffa component library.
+

package/skill/SelectOptions.md

@@ -0,0 +1,21 @@
+## SelectOptions · interface
+
+Options for `select`.
+
+### selectOptions.options · member
+
+The list of selectable options.
+
+**Type:** `SelectOptionInput[] | (() => SelectOptionInput[])`
+
+### selectOptions.bind · member
+
+Two-way binding for the selected value string (`""` when nothing is selected).
+
+**Type:** `Bindable<string>`
+
+### selectOptions.placeholder · member
+
+Placeholder option shown when nothing is selected yet.
+
+**Type:** `string`

package/skill/Slot.md

@@ -0,0 +1,13 @@
+## Slot · type
+
+Something that renders a small piece of content: either a plain string or a
+draw function (for icons, badges, custom markup, ...).
+
+A string is drawn as **rich text** (see `drawSlot`): Aberdeen's `rich`
+markup is applied, so `*italic*`, `**bold**`, `` `code` `` and
+`[links](/path)` render as inline elements (text is safely escaped).
+
+The optional `Args` type parameter lets a slot's draw-function receive
+arguments — e.g. a dialog body is a `Slot<[close: () => void]>`.
+
+**Type:** `string | ((...args: Args) => void)`

package/skill/Tab.md

@@ -0,0 +1,33 @@
+## Tab · interface
+
+A single tab definition.
+
+### tab.id · member
+
+Stable id used as the selection value. Falls back to the array index.
+
+**Type:** `string`
+
+### tab.label · member
+
+Tab label shown in the tab strip.
+
+**Type:** `Slot`
+
+### tab.icon · member
+
+Optional leading icon.
+
+**Type:** `Slot`
+
+### tab.content · member
+
+Content rendered in the panel when this tab is active. A string is rendered as rich text.
+
+**Type:** `Slot`
+
+### tab.disabled · member
+
+Disables selecting this tab.
+
+**Type:** `boolean`