staffa 0.5.0 → 0.6.1

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`