staffa 0.6.0 → 0.6.1

package/README.md

@@ -285,6 +285,8 @@ ln -s ../../node_modules/staffa/skill .claude/skills/staffa
 
 ## Breaking changes
 
+- **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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "staffa",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "An opinionated component library for the Aberdeen reactive UI library.",
   "license": "ISC",
   "author": "",
@@ -20,7 +20,8 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "skill"
   ],
   "scripts": {
     "build:icons": "node scripts/generate-icons.mjs",

package/skill/Attributes.md

@@ -0,0 +1,10 @@
+## Attributes · type
+
+Shared building blocks for the Staffa component library.
+
+Every component in Staffa is "just an Aberdeen draw function": a plain function
+that takes a single, strongly typed options object and emits DOM through
+Aberdeen's `A` function. This module defines the option-type hierarchy
+that all components build on, plus a couple of tiny helpers.
+
+**Type:** `string`

package/skill/AutocompleteOptions.md

@@ -0,0 +1,37 @@
+## AutocompleteOptions · interface
+
+Options for `autocomplete`.
+
+### autocompleteOptions.options · member
+
+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.
+
+**Type:** `AutocompleteOptionInput[] | (() => AutocompleteOptionInput[])`
+
+### autocompleteOptions.bind · member
+
+Two-way binding for the selection. In single mode this is the selected
+`value` string (`""` when empty). In `AutocompleteOptions.multi` mode
+it is an array of value strings.
+
+**Type:** `Bindable<string | string[]>`
+
+### autocompleteOptions.multi · member
+
+Allow selecting several values, shown as removable chips.
+
+**Type:** `boolean`
+
+### autocompleteOptions.allowCustom · member
+
+Allow committing free text that isn't in the options list. Defaults to `true`.
+
+**Type:** `boolean`
+
+### autocompleteOptions.placeholder · member
+
+Placeholder for the text input.
+
+**Type:** `string`

package/skill/BoxOptions.md

@@ -0,0 +1,33 @@
+## BoxOptions · interface
+
+Options for `box`.
+
+### boxOptions.header · member
+
+Header content, drawn in a styled bar above the body.
+
+**Type:** `Slot`
+
+### boxOptions.footer · member
+
+Footer content, drawn in a styled bar below the body.
+
+**Type:** `Slot`
+
+### boxOptions.contentAttrs · member
+
+Aberdeen attr/style string applied to the body (content-holding) element.
+
+**Type:** `string`
+
+### boxOptions.headerAttrs · member
+
+Aberdeen attr/style string applied to the header bar.
+
+**Type:** `string`
+
+### boxOptions.footerAttrs · member
+
+Aberdeen attr/style string applied to the footer bar.
+
+**Type:** `string`

package/skill/ButtonChooserOptions.md

@@ -0,0 +1,37 @@
+## ButtonChooserOptions · interface
+
+Options for `buttonChooser`.
+
+### buttonChooserOptions.attrs · member
+
+Aberdeen attr/style string applied to the button group.
+
+**Type:** `string`
+
+### buttonChooserOptions.options · member
+
+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.
+
+**Type:** `Record<string, Slot>`
+
+### buttonChooserOptions.bind · member
+
+Two-way binding for the selected id, or `undefined` when nothing is selected.
+Use an `A.proxy` or `A.ref`.
+
+**Type:** `Bindable<string>`
+
+### buttonChooserOptions.allowDeselect · member
+
+When `true`, clicking the already-selected button deselects it, setting
+`bind.value` to `undefined`. Useful for "none / auto" states.
+
+**Type:** `boolean`
+
+### buttonChooserOptions.name · member
+
+Name attribute for the hidden `<input>`, enabling form submission.
+
+**Type:** `string`

package/skill/ButtonGroupOptions.md

@@ -0,0 +1,23 @@
+## ButtonGroupOptions · interface
+
+Options for `buttonGroup`.
+
+### buttonGroupOptions.buttons · member
+
+Declarative list of buttons. Rendered in order. Alternatively (or
+additionally) draw buttons yourself via `ContentOptions.content`.
+
+**Type:** `ButtonOptions[]`
+
+### buttonGroupOptions.layout · member
+
+`"attached"` (default) joins the buttons into a single segmented control
+with shared borders; `"spaced"` lays them out with a normal gap.
+
+**Type:** `"attached" | "spaced"`
+
+### buttonGroupOptions.vertical · member
+
+Stack vertically instead of horizontally.
+
+**Type:** `boolean`

package/skill/ButtonOptions.md

@@ -0,0 +1,57 @@
+## ButtonOptions · interface
+
+Options for `button`.
+
+### buttonOptions.content · member
+
+Button content: a string for plain text, or a function for custom markup.
+
+**Type:** `Slot`
+
+### buttonOptions.icon · member
+
+Leading icon/adornment, drawn before the label.
+
+**Type:** `Slot`
+
+### buttonOptions.click · member
+
+Click handler.
+
+**Type:** `(event: Event) => void`
+
+### buttonOptions.disabled · member
+
+Disables the button.
+
+**Type:** `boolean`
+
+### buttonOptions.type · member
+
+Native button behaviour. Defaults to `"button"`.
+
+**Type:** `"button" | "submit" | "reset"`
+
+### buttonOptions.href · member
+
+Render as a link (`<a role=button>`) pointing here instead of a `<button>`.
+
+**Type:** `string`
+
+### buttonOptions.ariaLabel · member
+
+Accessible label, when the button has only an icon.
+
+**Type:** `string`
+
+### buttonOptions.attrs · member
+
+Aberdeen attr/style string applied to the button. A button is a surface, so
+pass surface modifier classes here to restyle it, e.g. `".danger"`,
+`".neutral .outlined"`. Defaults to a filled `.primary` surface.
+
+Size is set here too, with `.small` or `.large` (medium is the default and
+needs no class), e.g. `".danger .small"`. A `.small`/`.large` parent (such
+as a `buttonGroup`) also sizes its buttons, so you can set it once.
+
+**Type:** `string`

package/skill/CheckboxOptions.md

@@ -0,0 +1,27 @@
+## CheckboxOptions · interface
+
+Options for `checkbox`.
+
+### checkboxOptions.label · member
+
+The label shown next to the box. Required for a meaningful checkbox.
+
+**Type:** `Slot`
+
+### checkboxOptions.bind · member
+
+Two-way binding target holding a boolean.
+
+**Type:** `Bindable<boolean>`
+
+### checkboxOptions.checked · member
+
+Static initial checked state.
+
+**Type:** `boolean`
+
+### checkboxOptions.change · member
+
+Fired on `change` with the native event.
+
+**Type:** `(event: Event) => void`

package/skill/ContentOptions.md

@@ -0,0 +1,16 @@
+## ContentOptions · interface
+
+Options for components that wrap a single block of caller-provided content,
+with an `attrs` escape hatch on the outermost element.
+
+### contentOptions.attrs · member
+
+Aberdeen attr/style string applied to the widget's outermost element.
+
+**Type:** `string`
+
+### contentOptions.content · member
+
+Draws the children of this component. A string is rendered as rich text.
+
+**Type:** `Slot<[]>`

package/skill/DialogOptions.md

@@ -0,0 +1,70 @@
+## DialogOptions · interface
+
+Options for `dialog`.
+
+### dialogOptions.header · member
+
+Slot rendered in the styled header bar.
+
+**Type:** `Slot`
+
+### dialogOptions.footer · member
+
+Slot rendered in the styled footer bar.
+
+**Type:** `Slot`
+
+### dialogOptions.attrs · member
+
+Aberdeen attr/style string applied to the dialog panel. A surface — pass modifier classes (e.g. `".warning"`) to recolour it.
+
+**Type:** `string`
+
+### dialogOptions.headerAttrs · member
+
+Aberdeen attr/style string applied to the header bar.
+
+**Type:** `string`
+
+### dialogOptions.footerAttrs · member
+
+Aberdeen attr/style string applied to the footer bar.
+
+**Type:** `string`
+
+### dialogOptions.contentAttrs · member
+
+Aberdeen attr/style string applied to the scrollable content `<div>`.
+
+**Type:** `string`
+
+### dialogOptions.allowCancel · member
+
+Allow closing via Esc or clicking the backdrop. Defaults to `true`.
+May be changed on a proxied options object while the dialog is open
+(e.g. lock when form data is dirty).
+
+**Type:** `boolean`
+
+### dialogOptions.cancelWithScope · member
+
+When set to `true` (default) the model will be destroyed when the `dialog()`-calling
+scope is destroyed.
+
+**Type:** `boolean`
+
+### dialogOptions.content · member
+
+Dialog body. A `Slot` whose draw-function receives a `close()` function
+— call it to dismiss the dialog programmatically. (A plain string renders as
+rich text.)
+
+**Type:** `Slot<[close: () => void]>`
+
+### dialogOptions.onClose · member
+
+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
+the Promise returned by `dialog`.
+
+**Type:** `() => void`

package/skill/FieldOptions.md

@@ -0,0 +1,63 @@
+## FieldOptions · interface
+
+Options shared by all *form field* components (textline, textarea, checkbox,
+autocomplete, ...).
+
+Fields share a consistent vertical layout: an optional label, the control
+itself, and optional help/error text below it. `form` relies on this
+shared structure to align groups of fields.
+
+### fieldOptions.attrs · member
+
+Aberdeen attr/style string applied to the field's wrapper element.
+
+**Type:** `string`
+
+### fieldOptions.label · member
+
+Visible label, associated with the control via `for`/`id` for a11y.
+
+**Type:** `Slot`
+
+### fieldOptions.help · member
+
+Helper text shown beneath the control.
+
+**Type:** `Slot`
+
+### fieldOptions.error · member
+
+Error message shown beneath the control. When set, the control is marked
+`aria-invalid` and styled accordingly. May be reactive.
+
+**Type:** `string`
+
+### fieldOptions.disabled · member
+
+Disables the control.
+
+**Type:** `boolean`
+
+### fieldOptions.required · member
+
+Marks the field required (adds a `*` and the `aria-required` attribute).
+
+**Type:** `boolean`
+
+### fieldOptions.name · member
+
+The `name` attribute, for native form submission.
+
+**Type:** `string`
+
+### fieldOptions.id · member
+
+Explicit id for the control; auto-generated when omitted.
+
+**Type:** `string`
+
+### fieldOptions.inputAttrs · member
+
+Aberdeen attr/style string applied to the control (input) element itself.
+
+**Type:** `string`

package/skill/FloatingMenuOptions.md

@@ -0,0 +1,21 @@
+## FloatingMenuOptions · interface
+
+Options for `showFloatingMenu`.
+
+### floatingMenuOptions.items · member
+
+Items to show.
+
+**Type:** `MenuEntry[]`
+
+### floatingMenuOptions.anchor · member
+
+Element to anchor the menu to (positioned just below it, flips up if needed).
+
+**Type:** `HTMLElement`
+
+### floatingMenuOptions.dropdownAttrs · member
+
+Aberdeen attr/style string on the floating panel.
+
+**Type:** `string`

package/skill/FormOptions.md

@@ -0,0 +1,31 @@
+## FormOptions · interface
+
+Options for `form`.
+
+### formOptions.submit · member
+
+Submit handler. Called with collected form data (keyed by each field's
+`name`) and the original event. `preventDefault()` is already called.
+Multi-value fields (e.g. multi-select) produce a `string[]`.
+
+**Type:** `(data: Record<string, string | string[]>, event: SubmitEvent) => void`
+
+### formOptions.layout · member
+
+Layout of fields. `"stacked"` (default) is a single column; `"grid"` packs
+fields into a responsive multi-column grid. A field can span the full grid
+width by adding the `.s-wide` class (e.g. `attrs: ".s-wide"`).
+
+**Type:** `"stacked" | "grid"`
+
+### formOptions.actionsAttrs · member
+
+Aberdeen attr/style string for the action bar.
+
+**Type:** `string`
+
+### formOptions.actions · member
+
+Footer actions (typically a ("./buttonGroup").buttonGroup or buttons).
+
+**Type:** `Slot`

package/skill/MainOptions.md

@@ -0,0 +1,91 @@
+## MainOptions · interface
+
+Options for `main`.
+
+### mainOptions.attrs · member
+
+Aberdeen attr/style string applied to the outermost shell element.
+
+**Type:** `string`
+
+### mainOptions.title · member
+
+App/page title shown in the top bar.
+
+**Type:** `Slot`
+
+### mainOptions.subtitle · member
+
+Secondary line under the title.
+
+**Type:** `Slot`
+
+### mainOptions.icon · member
+
+Leading icon/logo in the top bar.
+
+**Type:** `Slot`
+
+### mainOptions.menu · member
+
+Action area on the right of the top bar (buttons, menu, ...).
+
+**Type:** `Slot`
+
+### mainOptions.content · member
+
+The scrollable page content. A string is rendered as rich text.
+
+**Type:** `Slot`
+
+### mainOptions.footer · member
+
+Footer content, pinned below the scroll area.
+
+**Type:** `Slot`
+
+### mainOptions.maxWidth · member
+
+Max width for the page's *content*, e.g. `"60rem"`. The header and footer
+backgrounds still span the full shell width, but their contents — and the
+sidebar + separator + content trio (or just the content when there's no
+sidebar) — cap to this width and centre horizontally. When unset, everything
+fills the available width. Either way the content shares the page surface —
+it is not boxed.
+
+**Type:** `string`
+
+### mainOptions.contentAttrs · member
+
+Aberdeen attr/style string applied to the content area.
+
+**Type:** `string`
+
+### mainOptions.topbarAttrs · member
+
+Aberdeen attr/style string applied to the top bar.
+
+**Type:** `string`
+
+### mainOptions.nav · member
+
+Navigation menu. When provided, renders a sidebar (in `"left"` / `"right"`
+mode) or a button+dropdown (in `"button"` mode). The sidebar automatically
+collapses to button mode when the shell is too narrow.
+
+**Type:** `MenuOptions`
+
+### mainOptions.navPosition · member
+
+Where to render the nav. Defaults to `"left"`.
+- `"left"` / `"right"`: sidebar next to the content area; collapses to a
+  button+dropdown in the top bar when the shell width drops below 640 px.
+- `"button"`: always a button+dropdown, never a sidebar.
+
+**Type:** `"button" | "left" | "right"`
+
+### mainOptions.navAttrs · member
+
+Aberdeen attr/style string applied to the sidebar nav panel.
+
+**Type:** `string`

package/skill/MenuItem.md

@@ -0,0 +1,52 @@
+## MenuItem · interface
+
+A clickable item in a menu or sidebar nav.
+
+**Tip:** set `href` and call Aberdeen's `interceptLinks()` once at app
+startup for SPA-style navigation. When `href` is set, the item is
+automatically highlighted as active whenever the current URL matches it
+(via `matchCurrent`).
+
+### menuItem.label · member
+
+Label text or draw function. Strings are rendered as rich text.
+
+**Type:** `Slot`
+
+### menuItem.icon · member
+
+Leading icon drawn before the label.
+
+**Type:** `Slot`
+
+### menuItem.click · member
+
+Click handler.
+
+**Type:** `(e: Event) => void`
+
+### menuItem.href · member
+
+Render as a link (`<a>`) pointing here. Pairs naturally with
+`interceptLinks()` — the item is highlighted automatically when the URL
+matches.
+
+**Type:** `string`
+
+### menuItem.target · member
+
+`target` for the link (`_blank`, etc.). Only meaningful with `href`.
+
+**Type:** `string`
+
+### menuItem.disabled · member
+
+Disables the item.
+
+**Type:** `boolean`
+
+### menuItem.attrs · member
+
+Aberdeen attr/style string on the item element.
+
+**Type:** `string`

package/skill/MenuOptions.md

@@ -0,0 +1,25 @@
+## MenuOptions · interface
+
+Options for `menuButton` and `MainOptions.nav`.
+
+### menuOptions.items · member
+
+Items shown in the dropdown or sidebar nav.
+
+**Type:** `MenuEntry[]`
+
+### menuOptions.button · member
+
+Customize the trigger button rendered by `menuButton`. Defaults to a
+`☰` icon button. The `click` handler is managed internally.
+
+When used as a `nav` in `S.main()`, this also customizes the hamburger
+button shown when the sidebar collapses.
+
+**Type:** `ButtonOptions`
+
+### menuOptions.dropdownAttrs · member
+
+Aberdeen attr/style string on the floating dropdown panel.
+
+**Type:** `string`