bitboss-ui 3.0.0-beta.4 → 3.0.0-beta.41

package/dist/ai/BbAlert.md

@@ -8,6 +8,21 @@
 - Usage rule: Prefer this component for consumer-facing implementations.
 - Implementation source (only when the contract below is not enough): [source/BbAlert.md](./source/BbAlert.md)
 
+## Reachable through `BbAlert`
+
+`BbAlert` 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 |
+| --- | --- | --- |
+| `pt:icon` | the root of `BbIcon` | `BbIcon` ([contract](./BbIcon.md)) |
+| `pt:close` | the root of `ClearableButton` | `ClearableButton` _(internal)_ |
+
+**CSS variables you can set through those parts** — declared deeper in the tree, so set one on the part that reads it (`pt:<part>="[--name:value]"`), never on `BbAlert`'s root:
+
+| Variable | Set through | Declared by | What it is |
+| --- | --- | --- | --- |
+| `--w` | `pt:icon` | `BbIcon` | `--w` is set inline by BbIcon from the size prop. The `initial` default seals it: without it an ancestor's `--w` (e.g. a dropdown's width bridge) would inherit in and size the icon. The `--size` indirection stays so higher-specificity rules (e.g. `.bb-badge .bb-icon`) can re-point it. |
+
 ## Usage & Guidelines
 
 ### When to use
@@ -38,6 +53,11 @@ the user should attend to; `destructive` reports a failure or dangerous state.
 An alert reads far better with a matching leading `icon`, so treat variant and
 icon as a pair.
 
+There is no `success` or `info` alert, on purpose (the built-in ramps stay
+closed): a confirmation is usually a toast, and a neutral note is `outline`
+with an icon. When an app needs one anyway, register it with the plugin's
+`alertVariants` option and colour it from `--bb-success` / `--bb-info`.
+
 **Semantic variants, each with a fitting icon**
 
 ```vue
@@ -101,13 +121,13 @@ bitbossUi({
 
 ```css
 .bb-alert--success {
-	--main-color: #15803d; /* title + icon */
-	--muted-color: color-mix(
+	--fg: #15803d; /* title + icon */
+	--fg-muted: color-mix(
 		in oklab,
-		var(--main-color) 75%,
+		var(--fg) 75%,
 		transparent
 	); /* body + close */
-	background-color: transparent;
+	--bg: transparent;
 	border-color: var(--bb-border);
 }
 ```
@@ -129,18 +149,20 @@ Bind `v-model` when the visibility matters to you:
 
 ```vue
 <template>
-	<div
-		class="flex max-w-md flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
-	>
+	<div class="flex max-w-md flex-col gap-3 rounded-(--bb-radius) border p-3">
 		<div class="flex flex-col gap-0.5">
 			<p class="text-sm font-medium">Account</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Confirm your email to invite teammates and manage billing.
 			</p>
 		</div>
 
+		<!--
+			`v-model` alone owns the dismissal, so the alert plays its own leave
+			transition. Pairing it with a `v-if` on the SAME element unmounts the
+			node the instant the model flips and the animation never runs.
+		-->
 		<BbAlert
-			v-if="showBanner"
 			v-model="showBanner"
 			close-label="Dismiss email verification reminder"
 			icon="lucide:mail"
@@ -149,7 +171,7 @@ Bind `v-model` when the visibility matters to you:
 			variant="primary"
 		/>
 		<BbButton
-			v-else
+			v-if="!showBanner"
 			prepend:icon="lucide:mail"
 			variant="ghost"
 			@click="showBanner = true"
@@ -229,12 +251,10 @@ genuine brand art; everything semantic stays a provider icon.
 
 ```vue
 <template>
-	<div
-		class="flex max-w-md flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
-	>
+	<div class="flex max-w-md flex-col gap-3 rounded-(--bb-radius) border p-3">
 		<div class="flex flex-col gap-0.5">
 			<p class="text-sm font-medium">Integrations</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Connected payment providers for Northwind Billing.
 			</p>
 		</div>
@@ -275,12 +295,10 @@ list of problems changes.
 
 ```vue
 <template>
-	<div
-		class="flex max-w-md flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
-	>
+	<div class="flex max-w-md flex-col gap-3 rounded-(--bb-radius) border p-3">
 		<div class="flex flex-col gap-0.5">
 			<p class="text-sm font-medium">Publish checklist</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Northwind Q3 release notes — blocked until both items are done.
 			</p>
 		</div>
@@ -346,6 +364,55 @@ const publish = () => {
 </script>
 ```
 
+### Restyling with passthrough
+
+`pt` reaches a named part with a class list — or, in the object form, a
+style and attributes. Parts: `root` (the box), `icon` (the leading glyph),
+`title` (the heading), `text` (the body copy), `close` (the ✕). The column
+that wraps title and text is layout, not a part. No states — an alert is
+either mounted or gone.
+
+An overdue invoice banner, restyled through those parts: a hair of top offset
+on `pt:icon` so the glyph sits with wrapped copy, `text-sm` on `pt:text`, a
+tighter tracking on `pt:title`.
+`hide-close` — this is page state until the invoice is paid, not a snooze.
+
+**pt:icon / pt:title / pt:text — invoice overdue**
+
+```vue
+<template>
+	<div class="max-w-2xl">
+		<BbAlert
+			hide-close
+			icon="lucide:triangle-alert"
+			pt:icon="mt-0.5"
+			pt:text="text-sm"
+			pt:title="tracking-tight"
+			text="Globex · €2,400 due 4 Sep. Record a payment or send a reminder — dunning is paused while this stays open."
+			title="INV-1043 is 7 days overdue"
+			variant="warning"
+		/>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbAlert } from 'bitboss-ui';
+
+// Invoice-record overdue banner, restyled through passthrough: a hair of
+// top offset on `pt:icon` so the glyph sits with wrapped copy, `text-sm` on
+// `pt:text` and a tighter tracking on `pt:title`. `hide-close` — this is page state,
+// not a snooze; the ✕ is a different part, taught with a listener.
+</script>
+```
+
+A listener on `pt:close` runs after the alert closes, never instead of it. The
+full grammar, the merge rules and the global map are in the
+[passthrough guide](./guides/passthrough.md).
+
+A `pt` value written in `<script>` (a constant, a preset, a wrapper's
+`pt` prop) is typed as `BbAlertProps['pt']`, never an imported `PtValue`: see
+[passthrough § Typing `pt` in `<script>`](./guides/passthrough.md#typing-pt-in-script).
+
 ### Works well with
 
 - `BbToast` — pair them: the toast confirms _the action_ ("Saved"), the alert
@@ -384,34 +451,79 @@ const publish = () => {
 
 ## v-model
 
-- `v-model` — type: `any`
+- `v-model` — type: `boolean \| undefined`
 
 ## Props
 
 | 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: `close`, `icon`, `root`, `text`, `title`. States: —. 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`. In `<script>` a `pt` value is typed `BbAlertProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `ariaLive` | `"off" \| "polite" \| "assertive" \| undefined` |  |  | ARIA live region politeness. Defaults to `'assertive'` for destructive/warning variants, otherwise `'polite'`. |
 | `closeLabel` | `string \| undefined` |  |  | Visually hidden string used to label the close button. |
-| `hideClose` | `boolean \| undefined` |  |  | Defines whether to hide the close button. |
+| `hideClose` | `boolean \| undefined` | `false` |  | Defines whether to hide the close button. |
 | `icon` | `string \| undefined` |  |  | Name of a registered icon to use, or a full raw `<svg>` string (e.g. an SVG file imported with `?raw`). |
 | `iconSize` | `number \| ({ size?: any; } & string) \| keyof Sizes \| undefined` | `"16"` |  | Size of the icon to use. |
-| `modelValue` | `any` | `true` |  | Used by v-model, set type to any to avoid Vue casting it as false. Alerts are visible on mount; the model dismisses them. |
+| `modelValue` | `boolean \| undefined` | `true` |  | Used by v-model. Alerts are visible on mount; the model dismisses them. |
 | `role` | `"alert" \| "status" \| undefined` |  |  | Accessibility role for the alert container. Defaults to `'alert'` for destructive/warning variants, otherwise `'status'`. |
 | `text` | `string \| undefined` |  |  | Text content of the alert body. |
 | `title` | `string \| undefined` |  |  | Text content of the alert title. |
-| `transitionDuration` | `number \| undefined` | `transitions.medium` |  | Transition duration in milliseconds for enter/leave. |
-| `variant` | `keyof AlertVariantRegistry \| undefined` | `"outline"` |  | Visual variant of the alert. |
+| `transitionDuration` | `number \| undefined` | `250` |  | Transition duration in milliseconds for enter/leave. |
+| `variant` | `'outline'` \| `'primary'` \| `'destructive'` \| `'warning'` | `"outline"` |  | Visual variant of the alert. |
+
+## 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`. In `<script>`, type a `pt` value as `<Component>Props['pt']` (`<Component>Props<Row>['pt']` on a generic component); `PtValue` is not exported: `guides/passthrough.md` § Typing `pt` in `<script>`.
+
+| Part | What it is |
+| --- | --- |
+| `root` | The alert box. |
+| `icon` | The leading glyph — rendered only when an `icon` is set. |
+| `title` | The heading line. |
+| `text` | The body copy. |
+| `close` | The ✕ that dismisses the alert. |
 
 ## Events
 
-- `update:modelValue` — `(event: "update:modelValue", value: boolean): void`
+- `update:modelValue` — `(value: boolean): void` — Emitted with the new value whenever `v-model` changes.
 
 ## Slots
 
-- `default` — scope: `any` — The alert body — the shortest form, and the one to reach for: `<BbAlert>Something went wrong</BbAlert>`. Same idiom as the rest of the `text`-prop family (BbButton, BbBaseButton, BbTooltip, BbIndicator). When more than one source is present…
-- `text` — scope: `BbAlertTextSlotProps` — Replaces the default alert body text. Wins over children and `text`.
-- `title` — scope: `BbAlertTitleSlotProps` — Replaces the default alert title text.
+- `default` — scope: `any` — The alert body — the shortest form, and the one to reach for: `<BbAlert>Something went wrong</BbAlert>`. Same idiom as the rest of the `text`-prop family (BbButton, BbBaseButton, BbTooltip, BbIndicator). When more than one source is present the most specific wins: `#text` > children > the `text` prop.
+- `text` — scope: `BbAlertTextSlotProps` `{ text: string }` — Replaces the default alert body text. Wins over children and `text`.
+- `title` — scope: `BbAlertTitleSlotProps` `{ text: string }` — Replaces the default alert title text.
+
+## CSS custom properties
+
+Set these on the element, or on a class you put on it, to retune this component alone — the sanctioned alternative to reaching past the API with `:deep()`. They are this component's own locals — a **Set on** of `pt:<part>` means the local lives on that part's element, so set it through that entry (`pt:box="[--border-color:var(--color-green-500)]"`); the global `--bb-*` theme tokens are a separate tier (see the [design-tokens guide](./guides/design-tokens.md), or the MCP `list_tokens` tool).
+
+| Property | Default | What it is |
+| --- | --- | --- |
+| `--px` | `10px` | side padding of the plate |
+| `--py` | `6px` | top/bottom padding of the plate, and the close button's inset from those edges |
+| `--gap` | `4px` | icon column → content gap, reused between title parts and in the close button's reserved width |
+| `--title-size` | `14px` | icon column → content gap, reused between title parts and in the close button's reserved width |
+| `--title-lh` | `18px` | title line box — the close button is centred on it |
+| `--text-size` | `14px` | title line box — the close button is centred on it |
+| `--text-lh` | `18px` |  |
+| `--close-size` | `16px` | close glyph; also the width reserved at the end of the title |
+| `--bg` | `transparent` | plate fill |
+| `--fg` | `var(--bb-text)` | title and icon |
+| `--fg-muted` | `color-mix(in oklab, var(--fg) 75%, transparent)` | Body text and the close glyph (the destructive variant points it back at --fg) |
+| `--border-color` | `color-mix(in oklab, var(--bb-text) 15%, transparent)` | Plate border |
+| `--elev` | `var(--bb-elev)` | Resting lift. A local, so a page that already sits on a card can flatten one alert (`<BbAlert style="--elev: none">`) without unsetting the theme's lift everywhere. |
+
+## Component tree
+
+`BbAlert` is not one component: rendering it mounts every component below, and each one is live inside it. **Read this before styling, theming or debugging `BbAlert`, and before concluding a part, a token or a behaviour does not exist** — it may live on a component further down. How to read it:
+
+- **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbAlert`. A pt part listed as landing there is set on `BbAlert` (`pt:<part>`).
+- **_public_** nodes are components with their own contract. `BbAlert` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbAlert`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
+- **CSS custom properties** listed on a node are declared on THAT node's root and read by elements inside it. Set one on that node's root or on the element inside it that reads it — the pt part that lands there is how you reach it (`pt:box="[--border-color:…]"` on a text input) — never on `BbAlert`'s root, where the node's own declaration masks it (design-tokens guide, _Overriding one from a consumer app_, rule 0).
+- Listed nodes are the ones `BbAlert`'s API reaches or that declare a documented CSS variable; the rest fold into "also mounts". The complete tree, repeats and undocumented locals included, is the `tree` field of this component in `components.json`.
+
+- `BbAlert` _(this component)_ — its own template binds: `icon` → `BbIcon`, `close` → `ClearableButton`, `title` → `div.bb-alert__title`, `text` → `div.bb-alert__text`
+  - Also mounts `BbIcon`, `ClearableButton`
 
 ## See Also
 
-- [BbToast](./BbToast.md) — Shows transient notification messages.
+- [BbToast](./BbToast.md) — Shows transient notification messages (includes the co-located BbToastPortal export).

package/dist/ai/BbAsterisk.md

@@ -4,7 +4,7 @@
 
 - Safety level: **Consumer API**
 - Group: **Other**
-- Description: Presentational required-field marker (red "*"). No props/slots/events; placed in custom label content.
+- Description: Presentational required-field marker (red "*"). No behaviour props/slots/events (only `pt`); placed in custom label content.
 - Usage rule: Prefer this component for consumer-facing implementations.
 - Implementation source (only when the contract below is not enough): [source/BbAsterisk.md](./source/BbAsterisk.md)
 
@@ -13,11 +13,12 @@
 ### When to use
 
 `BbAsterisk` is the small red `*` that marks a field as required. It is purely
-presentational — it has no props, slots, or events, and it does not read
+presentational — it has no behaviour props, slots, or events (only `pt` to
+restyle its root), and it does not read
 `required` or drive validation. You render it yourself wherever you build custom
 label content, so the marker matches the library's styling (`--bb-danger`).
 
-Most consumers never place it by hand: the `bitboss-ui/validated` form controls
+Most consumers never place it by hand: the form controls
 render it for you in their `#label` slot when a field is `required`/has rules and
 `config.requiredAsterisk` is enabled. Reach for `BbAsterisk` directly only when
 you compose a bespoke label outside those controls.
@@ -33,9 +34,65 @@ you compose a bespoke label outside those controls.
 Wrap it in an element with your own spacing if the default `margin-inline-start`
 doesn't suit the layout; the glyph inherits nothing else from its surroundings.
 
+### It is `aria-hidden` — the control carries the requirement
+
+The span renders `aria-hidden="true"`, so **screen readers never announce it**.
+That is deliberate: an asterisk read aloud as "star" is noise, and a marker
+placed in a label is not a reliable way to convey a requirement. What actually
+carries mandatoriness to assistive tech is the **`required` attribute on the
+control** — which the library sets from your `required` prop.
+
+The practical consequence: the marker is a _visual_ affordance only, and
+`required` is the real thing. Never ship a field that shows the asterisk
+without `required` (sighted users see a requirement that assistive tech cannot
+perceive), and never assume the asterisk is doing accessibility work.
+
+`showAsterisk` on the form controls is also gated on the plugin option, so
+with `requiredAsterisk: false` there is no way to render the marker through
+them at all — placing `BbAsterisk` by hand is then the only route.
+
+### Restyling with passthrough
+
+`pt` reaches the one part with a class list — or, in the object form, a
+style and attributes. Part: `root` (the marker span — its only props are the passthrough ones). No states — nothing it paints is a
+state.
+
+With one part, `pt:root` is plain `class` with extra letters: write `class`
+/ `style` on the tag, as on any element. `pt:root` stays for uniformity —
+the global map, the object form and a wrapper that spreads props address
+every component the same way.
+
+The default paint is `--bb-danger`; `class` is how you retint it. The
+control's `required` still carries the requirement.
+
+**class — a softened required marker**
+
+```vue
+<span
+	class="text-sm font-medium"
+>Workspace name<BbAsterisk class="text-(--bb-warn)" /></span>
+```
+
+The full grammar, the merge rules and the global map are in the
+[passthrough guide](./guides/passthrough.md).
+
+A `pt` value written in `<script>` (a constant, a preset, a wrapper's
+`pt` prop) is typed as `BbAsteriskProps['pt']`, never an imported `PtValue`: see
+[passthrough § Typing `pt` in `<script>`](./guides/passthrough.md#typing-pt-in-script).
+
 ## Props
 
-- None.
+| 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: `root`. States: —. 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`. In `<script>` a `pt` value is typed `BbAsteriskProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+
+## 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`. In `<script>`, type a `pt` value as `<Component>Props['pt']` (`<Component>Props<Row>['pt']` on a generic component); `PtValue` is not exported: `guides/passthrough.md` § Typing `pt` in `<script>`.
+
+| Part | What it is |
+| --- | --- |
+| `root` | The required-marker span. |
 
 ## Events