bitboss-ui 3.0.0-beta.28 → 3.0.0-beta.30

package/dist/ai/BbButton.md

@@ -10,7 +10,7 @@
 
 ## Reachable through `BbButton`
 
-`BbButton` mounts other components (all of them: _Component tree_, near the end). These are the parts of its API that land inside them. Use them — never `:deep()` on an inner class, never an import of an internal component.
+`BbButton` mounts other components (all of them: _Component tree_, near the end). These are the parts of its API that land inside them. Prefer these over `:deep()` on an inner class (allowed, unsupported: it can break on upgrade) — and never an import of an internal component.
 
 | pt part | Lands on | In |
 | --- | --- | --- |
@@ -113,6 +113,46 @@ restate a state:
 }
 ```
 
+Every state has the full trio. Hover and pressed also take `--fg-hover` /
+`--border-hover` and `--fg-pressed` / `--border-pressed` (both default to the
+resting `--fg` / `--border-color`, so only the fill moves unless you say
+otherwise), which is how a toggle chip can flip from a light label on a dark
+fill to a dark label on a coloured one without a rule on `[aria-pressed]`.
+Disabled paints `--bg-disabled` / `--fg-disabled` / `--border-disabled` plus
+`--opacity-disabled` — muted grey at full opacity by default, whatever the
+variant. The complete matrix is in the contract's token table.
+
+#### Disabled: fade instead of grey
+
+The shadcn-style alternative keeps the variant's colours and fades the whole
+button, so a disabled destructive button stays recognisably red. Point the
+disabled trio back at the resting tokens and lower the opacity — on every
+button, in your stylesheet:
+
+```css
+.bb-button {
+	--bg-disabled: var(--bg);
+	--fg-disabled: var(--fg);
+	--border-disabled: var(--border-color);
+	--opacity-disabled: 0.5;
+}
+```
+
+or on one button, through `pt:root` and Tailwind's arbitrary properties:
+
+```vue
+<BbButton
+	variant="destructive"
+	disabled
+	pt:root="[--bg-disabled:var(--bg)] [--fg-disabled:var(--fg)] [--border-disabled:var(--border-color)] [--opacity-disabled:.5]"
+>
+	Delete
+</BbButton>
+```
+
+(`loading` is not `disabled`: a loading button keeps its variant colours by
+design and never reads the disabled trio — see _Loading and async actions_.)
+
 Never use a variant name that is neither built-in nor registered in the
 project's `vite.config.*` / `nuxt.config.*`. Unsure what's currently legal in
 a given project (built-ins plus whatever it has registered)? Don't guess from
@@ -253,8 +293,19 @@ button its accessible name the same way as any other — through the default slo
 visible text but announces "Settings". `aria-label` is plan B — an override for
 when the accessible name must differ from (or you can't supply) slot content.
 Just don't ship an icon-only button with neither. When `icon` is set,
-`append:icon` is ignored. Icons scale with the button's `size`; names come from
-the `lucide:*` set (see the icons policy).
+`append:icon` is ignored. Icons scale with the button's `size`. Icon names come
+from an installed provider set (e.g. `lucide:*`) or from your own SVGs as
+`local:<file-name>` (see the icons policy) — a brand mark or a custom glyph is
+a `local:` file in your `iconDir`, not a hand-made icon component wrapped in a
+`BbBaseButton`. The `local:` name below is one of _this repository's_ fixture
+SVGs: in your project it resolves only if `<file-name>.svg` sits in your own
+`iconDir`.
+
+**A local: icon from your own SVGs**
+
+```vue
+<BbButton variant="outline" prepend:icon="local:sparkles">Generate</BbButton>
+```
 
 **Icons and icon-only**
 
@@ -542,8 +593,12 @@ Escape hatches, when the default isn't right:
   `BbDropdownButton` caret stays usable while the primary action runs).
 
 The visually-hidden loading announcement is localized via the plugin's `locale`
-option. `disabled` and `loading` are independent: `disabled` wins the muted
-styling and native blocking; don't set both.
+option. `disabled` and `loading` are independent props, and setting both is
+redundant but harmless: `loading` wins the look (the spinner shows and the
+variant colours stay — the disabled paint is skipped while loading), and
+`disabled` adds native blocking on top of loading's soft block. The
+Inertia-form habit `:loading="form.processing" :disabled="form.processing"`
+therefore renders as a loading button, not a grey one.
 
 **Externally-owned loading state**
 
@@ -973,7 +1028,7 @@ Anti-patterns:
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `icon`, `root`, `spinner`, `text`. States: `disabled`, `loading`. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `icon`, `root`, `spinner`, `text`. States: `disabled`, `loading`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `activeClass` | `string \| undefined` |  |  | Class to apply when the link is active. |
 | `append:icon` | `string \| undefined` |  |  | Icon to be added on the right of the text. |
 | `ariaCurrentValue` | `"page" \| "step" \| "location" \| "date" \| "time" \| "true" \| "false" \| undefined` | `'page'` |  | Value passed to the attribute `aria-current` when the link is exact active. |
@@ -984,7 +1039,7 @@ Anti-patterns:
 | `component` | `string \| undefined` |  |  | Inertia: the page component this visit resolves to. Rarely set by hand — the server normally decides it. |
 | `data` | `object \| undefined` |  |  |  |
 | `disableAutoLoading` | `boolean \| undefined` | `false` |  | Disables the automatic loading state that tracks async click handlers (enabled by default). |
-| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the component: native `disabled` (or `aria-disabled` on a link), muted paint. Beside `loading`, loading wins the look (spinner and variant colours) and this only adds the native blocking — redundant but harmless. |
 | `download` | `string \| boolean \| undefined` |  |  | Marks an `href` link as a download: renders a plain `<a download>` doing a native navigation (never an Inertia/router visit), so file downloads work. Pass a string for the suggested filename. A native-anchor signal alongside `target` and `e… |
 | `exactActiveClass` | `string \| undefined` |  |  | Class to apply when the link is exact active. |
 | `except` | `string[] \| undefined` |  |  | Inertia: the inverse of `only` — properties to EXCLUDE from a partial reload. Pass one or the other, not both. |
@@ -996,7 +1051,7 @@ Anti-patterns:
 | `icon` | `string \| undefined` |  |  | Used when only an icon with no text should be displayed. |
 | `instant` | `boolean \| undefined` | `false` |  | Inertia: navigate optimistically on click and reconcile when the response lands, instead of waiting for the round trip. |
 | `interactiveWhileLoading` | `boolean \| undefined` | `false` |  | Keeps the button clickable while it is loading. Buttons are disabled while loading by default; this escape hatch exists for toggles that must stay interactive (e.g. the dropdown-button caret). |
-| `loading` | `boolean \| undefined` | `false` |  | Triggers a loading indicator. |
+| `loading` | `boolean \| undefined` | `false` |  | Triggers a loading indicator. A loading button is soft-disabled on its own (`aria-disabled`, out of the tab order, clicks and navigation blocked) and keeps its variant colours; with `disabled` set too, loading still wins the look. |
 | `method` | `"get" \| "post" \| "put" \| "patch" \| "delete" \| undefined` |  |  |  |
 | `modelValue` | `any` |  |  |  |
 | `onBefore` | `(() => void) \| undefined` |  |  |  |
@@ -1028,6 +1083,24 @@ Anti-patterns:
 | `variant` | `ButtonVariantType \| undefined` | `"primary"` |  | Visual variant of the button. Controls colors and surface style while keeping spacing and sizing unchanged. |
 | `viewTransition` | `boolean \| undefined` | `false` |  | Inertia: run the page swap inside a View Transition, where the browser supports one. |
 
+## Passthrough parts and states
+
+`pt:<part>="…"` restyles a part; `pt:<part>:<state>="…"` applies only while the state is on. A component-wide state is on for every part at once; a _per node_ state resolves on each node of a broadcast part (one row, one option, one day). Grammar and merge rules: `guides/passthrough.md`.
+
+| Part | What it is |
+| --- | --- |
+| `root` | The button element. The glyph size lives here: `--icon-size` on `pt:root` resizes the icon, the spinner and the gap between them together. |
+| `icon` | Every content icon the button renders (`icon`, `prepend:icon`, `append:icon`) — a broadcast; at most two render together. For colour, opacity and attributes — size it through `--icon-size` on `root`, never a size utility here (it breaks the icon / spinner pair). |
+| `spinner` | The loading spinner, parked exactly over the icon. Like `icon`: colour and opacity here, size through `--icon-size` on `root`. |
+| `text` | The label span. Typography inherits from `root`, so reach for `text` only when a class must apply to the label alone — `truncate` on a long label that must not clip the icons. It carries the margin the label slides by while the spinner is in, so a margin of your own fights the slide. |
+
+States are listed in precedence order: when two are on at once and their entries conflict, the later one wins.
+
+| State | When it is on |
+| --- | --- |
+| `disabled` | Component-wide: the button is `disabled`. |
+| `loading` | Component-wide: `loading` is on — the spinner shows and the button ignores the pointer. |
+
 ## Events
 
 - `update:modelValue` — `(event: "update:modelValue", value: any): void`
@@ -1091,6 +1164,14 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--border-color` | `transparent` | the frame; its width is --bw |
 | `--ring` | `transparent` | focus ring, drawn --bb-ring-size outside the border |
 | `--bw` | `var(--bb-border-w)` | border width |
+| `--fg-hover` | `var(--fg)` | label and icons on hover (and focus-visible) |
+| `--border-hover` | `var(--border-color)` | the frame on hover (and focus-visible) |
+| `--fg-pressed` | `var(--fg)` | label and icons while [aria-pressed='true'] |
+| `--border-pressed` | `var(--border-color)` | the frame while [aria-pressed='true'] |
+| `--bg-disabled` | `var(--bb-muted)` | the plate while disabled (not loading) |
+| `--fg-disabled` | `color-mix(in oklab, var(--bb-text) 45%, var(--bb-panel))` | label and icons while disabled |
+| `--border-disabled` | `var(--bb-muted)` | the frame while disabled |
+| `--opacity-disabled` | `1` | whole-button opacity while disabled — `.5` with the three above set to the resting tokens gives "fade instead of grey" |
 | `--elev-tier` | `var(--bb-elev)` | the shadow a plate variant may take |
 | `--elev` | `0 0 0 0 transparent` | the shadow painted; flat variants keep this |