bitboss-ui 3.0.0-beta.43 → 3.0.0-beta.44

package/dist/ai/BbAlert.md

@@ -278,7 +278,13 @@ genuine brand art; everything semantic stays a provider icon.
 
 <script setup lang="ts">
 import { BbAlert, BbIcon } from 'bitboss-ui';
-import acmeMark from './acme-mark.svg?raw';
+
+// A partner's brand mark as a full `<svg>` string. In an app it usually comes
+// from a file: `import acmeMark from './acme-mark.svg?raw'`.
+const acmeMark = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+	<rect width="32" height="32" rx="8" fill="#4f46e5" />
+	<path d="M17.5 5 8 18h6.5L14.5 27 24 14h-6.5z" fill="#fff" />
+</svg>`;
 </script>
 ```
 
@@ -462,7 +468,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `closeLabel` | `string \| undefined` |  |  | Visually hidden string used to label 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. |
+| `iconSize` | `number \| CssSize \| keyof Sizes \| undefined` | `"16"` |  | Size of the icon to use. |
 | `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. |

package/dist/ai/BbAvatar.md

@@ -427,8 +427,13 @@ it for you.
 import { BbAvatar, BbIcon } from 'bitboss-ui';
 // A raw `<svg>` string is a valid `icon` for BbIcon — the escape hatch for
 // brand art that lives in no icon collection. It paints in `currentColor`,
-// so on the avatar's fallback surface it inherits `--bb-primary-fg`.
-import releaseBotMark from '@/assets/icons/sparkles.svg?raw';
+// so on the avatar's fallback surface it inherits `--bb-primary-fg`. In an app
+// it usually comes from a file: `import releaseBotMark from './bot.svg?raw'`.
+const releaseBotMark = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none">
+	<path d="M12 4L13.6 8.4L18 10L13.6 11.6L12 16L10.4 11.6L6 10L10.4 8.4L12 4Z" stroke="currentColor" stroke-width="1.8" stroke-linejoin="round" />
+	<path d="M19 3L19.7 4.8L21.5 5.5L19.7 6.2L19 8L18.3 6.2L16.5 5.5L18.3 4.8L19 3Z" fill="currentColor" />
+	<path d="M5 16L5.7 17.8L7.5 18.5L5.7 19.2L5 21L4.3 19.2L2.5 18.5L4.3 17.8L5 16Z" fill="currentColor" />
+</svg>`;
 
 // Self-contained demo data: each portrait is an inline SVG data URI, so the
 // example loads nothing over the network. Any image URL works here; swap in
@@ -603,7 +608,7 @@ available in visible text or an adjacent label.
 | --- | --- | --- | --- | --- |
 | `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`. 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 `BbAvatarProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `alt` | `string \| undefined` | `""` |  | Alternative text for the image, used for accessibility. |
-| `size` | `number \| ({ size?: any; } & string) \| keyof Sizes \| undefined` | `"md"` |  | Defines the component size. Accepted values: - A key from the provided size map (`keyof T`), e.g. `'sm' \| 'md' \| 'lg'` - A custom CSS size string (e.g. `'20px'`, `'1.5rem'`, `'2em'`) - A number, typically interpreted as pixels by size parsers |
+| `size` | `number \| CssSize \| keyof Sizes \| undefined` | `"md"` |  | Defines the component size. Accepted values: - A key from the provided size map (`keyof T`), e.g. `'sm' \| 'md' \| 'lg'` - A custom CSS size string (e.g. `'20px'`, `'1.5rem'`, `'2em'`) - A number, typically interpreted as pixels by size parsers |
 | `sizes` | `string \| undefined` |  |  | Sizes attribute for the image, used with `srcset`. |
 | `src` | `string \| undefined` |  |  | Source URL of the avatar image. |
 | `srcset` | `string \| undefined` |  |  | Responsive image source set. |

package/dist/ai/BbBadge.md

@@ -836,7 +836,10 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
   as a screen-reader-only label — never leave it empty. In button mode that
   label is also the **button's accessible name**, so it is doubly required.
   `bitboss-ui check` and the ESLint rule `bitboss-ui/require-accessible-name`
-  report an empty one as an error.
+  report an empty one as an error. The exception is a purely decorative tile
+  hidden from assistive tech with `aria-hidden="true"` (it lands on the root),
+  e.g. `<BbBadge aria-hidden="true" icon="lucide:star" />`: nothing to name,
+  so neither tool reports it.
 - The `clearable` button's accessible name is composed by default: the
   localized `badge.clearLabel` verb plus the badge body's text ("Remove
   Italy"). `clearable-label` replaces the whole name; with a `BbBadgeButton`

package/dist/ai/BbBreadcrumbs.md

@@ -747,7 +747,7 @@ States are listed in precedence order: when two are on at once and their entries
 - `BbBreadcrumbs` _(this component)_ — its own template binds: `item` → `li.bb-breadcrumbs__item`, `icon` → `BbIcon`, `text` → `span.bb-breadcrumbs__text`
   - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
   - `BbDropdown` _(public — [contract](./BbDropdown.md))_ — its own pt parts (`BbDropdown`): `panel` → `CommonPopover`, `root` → `CommonPopover`, `header` → `div.bb-dropdown__header`, `list` → `span.bb-dropdown__list`, `footer` → `div.bb-dropdown__footer`; documented CSS variables: `--menu-inset`; also mounts `CommonPopover`, `DropdownPipelineResolver`
-    - `BbDropdownList` _(internal — not importable, reach it through `BbDropdown`)_ — also mounts `BbBaseButton`, `BbIcon`, `CommonPopover`, `BbDropdownList`
+    - `BbDropdownList` _(internal — not importable, reach it through `BbDropdown`)_ — also mounts `BbBaseButton`, `BbIcon`, `ErrorIcon`, `CommonPopover`, `BbDropdownList`
       - `BbBadge` _(public — [contract](./BbBadge.md))_ — its own pt parts (`BbBadge`): `spinner` → `BbSpinner`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear`; documented CSS variables: `--bg`, `--fg`, `--bw`, `--ring-color`, `--ring-size`, `--min-size-md`, `--min-size`, `--elev`, `--r`, `--fs`, `--icon-size`, `--gap`, `--px`, `--clear-size`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--pad-left`; also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
     - `AdaptiveDropdown` _(internal — not importable, reach it through `BbDropdown`)_ — hands `BbOffCanvas` the pt map `{ header: 'header', footer: 'footer', panel: 'root', sheet: 'root' }` (ours → theirs); also mounts `BbSmoothHeight`, `BbDropdownList`
       - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__content`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--handle-w`, `--handle-h`, `--handle-bg`, `--safe-top`, `--close-size`

package/dist/ai/BbButton.md

@@ -234,6 +234,12 @@ not `:text="'Save'"`. The `text` prop renders identically (`<slot>{{ text }}</sl
 under the hood) and exists mainly for `:items`-style loops that spread a config
 object; when both are present the slot wins. Reach for `text` only when a string
 is all you have; otherwise the slot reads cleaner and lets you compose markup.
+Several children in the slot — a label and a status dot, a label and a count —
+are spaced like shadcn/ui's button: in a row, centred, the icon gap apart, with
+no wrapper of your own (`<BbButton>Synced <span class="dot" /></BbButton>`).
+A plain text label is untouched. Wrap rich text in one element
+(`<span>Save <b>all</b></span>`) to keep it one sentence; unwrapped, the `<b>`
+is a child of its own and sits the gap away.
 `type` defaults to `'button'`, so a `BbButton` inside a form never submits by
 accident; set `type="submit"` for the one that should, and let the form's
 `@submit` handler own the logic:
@@ -328,14 +334,12 @@ Just don't ship an icon-only button with neither. When `icon` is set,
 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**
+`BbBaseButton`. The name below stands for your own file: it resolves only if
+`brand-mark.svg` sits in your `iconDir` (BbIcon's guide renders a live
+`local:` demo).
 
 ```vue
-<BbButton variant="outline" prepend:icon="local:sparkles">Generate</BbButton>
+<BbButton variant="outline" prepend:icon="local:brand-mark">Generate</BbButton>
 ```
 
 **Icons and icon-only**

package/dist/ai/BbCalendar.md

@@ -397,14 +397,14 @@ object).
 | Slot                   | Renders                                     |
 | ---------------------- | ------------------------------------------- |
 | `#day`                 | every day's label, **replacing** the number |
-| `#append:day`          | under every day (dots, prices, badges)      |
+| `#day:append`          | under every day (dots, prices, badges)      |
 | `#<YYYY-MM-DD>`        | one date's label, e.g. `#2026-12-25`        |
-| `#append:<YYYY-MM-DD>` | under one date, e.g. `#append:2026-12-25`   |
+| `#<YYYY-MM-DD>:append` | under one date, e.g. `#2026-12-25:append`   |
 
 A date's slot name is its local `YYYY-MM-DD`, exactly as written, and it wins over
 the matching every-day slot for that date. Per-date slots suit a few fixed
 dates (holidays, a launch day); for data-driven marks — events from an API —
-use `#append:day` and look the day up from `item`. The per-date slots cover the
+use `#day:append` and look the day up from `item`. The per-date slots cover the
 day grid only, not the month and year panels.
 
 The rows grow to fit what you put under a day, with nothing to configure:
@@ -418,7 +418,7 @@ scheduler.
 ```vue
 <template>
 	<BbCalendar v-model="value" aria-label="Team calendar">
-		<template #append:day="{ item, outside }">
+		<template #day:append="{ item, outside }">
 			<span
 				v-if="!outside && busy.has(item.format('YYYY-MM-DD'))"
 				aria-hidden="true"
@@ -461,13 +461,13 @@ const busy = new Set(
 			:selectable="isOpen"
 		>
 			<!-- One slot per date: its `YYYY-MM-DD`, exactly as written. -->
-			<template #append:2026-12-24>
+			<template #2026-12-24:append>
 				<span class="holiday-note">Half day</span>
 			</template>
-			<template #append:2026-12-25>
+			<template #2026-12-25:append>
 				<span class="holiday-note">Closed</span>
 			</template>
-			<template #append:2026-12-26>
+			<template #2026-12-26:append>
 				<span class="holiday-note">Closed</span>
 			</template>
 		</BbCalendar>
@@ -637,10 +637,10 @@ States are listed in precedence order: when two are on at once and their entries
 
 ## Slots
 
-- `append:day` — scope: `BbCalendarDaySlotProps` `{ first: boolean; item: any; label: string; last: boolean; middle: boolean; outside: boolean; selected: boolean }` — Appends content below each calendar day.
 - `day` — scope: `BbCalendarDaySlotProps` `{ first: boolean; item: any; label: string; last: boolean; middle: boolean; outside: boolean; selected: boolean }` — Replaces the day button label inside each calendar day.
+- `day:append` — scope: `BbCalendarDaySlotProps` `{ first: boolean; item: any; label: string; last: boolean; middle: boolean; outside: boolean; selected: boolean }` — Appends content below each calendar day.
 - `#<YYYY-MM-DD>` (named from data) — scope: `BbCalendarDaySlotProps` — One date's button label (e.g. `#2024-03-15`: the local `YYYY-MM-DD`, which `slotKey` leaves as it is); beats `day`. Day grid only.
-- `#append:<YYYY-MM-DD>` (named from data) — scope: `BbCalendarDaySlotProps` — Content under one date's cell; beats `append:day`.
+- `#<YYYY-MM-DD>:append` (named from data) — scope: `BbCalendarDaySlotProps` — Content under one date's cell; beats `day:append`.
 
 ## CSS custom properties
 

package/dist/ai/BbCheckbox.md

@@ -19,6 +19,7 @@
 | `pt:label` | `component` | `CommonField` _(internal)_ |
 | `pt:description` | `span.bb-field__description` | `CommonField` _(internal)_ |
 | `pt:hint` | `span.bb-field__hint` | `CommonField` _(internal)_ |
+| `pt:counter` | `span.bb-field__counter` | `CommonField` _(internal)_ |
 | `pt:message` | `div.bb-field__message` | `CommonField` _(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 `BbCheckbox`'s root:
@@ -502,6 +503,10 @@ const toggleAll = (checked: boolean) => {
   negation as a consumer-facing quirk — it is not.)
 - `input-position` / `label-position` (`'left' | 'center' | 'right'`) align box
   and label text inside their columns — useful with ratio layouts.
+- `input-align` / `label-align` (`'top' | 'center' | 'bottom'`) are the
+  vertical axis of a side-by-side row. Omitted, the box sits on the label's
+  first line; `input-align="center"` puts it on the middle of a described
+  label.
 - `hide-label` keeps the label for screen readers but hides it visually — only
   for dense composites where visible text lives elsewhere.
 - `compact` tightens the field's label spacing (`--bb-label-spacing-y-compact` instead of `--bb-label-spacing-y`), the same as on the groups — for dense forms and settings panels.
@@ -701,8 +706,10 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
 | `id` | `string \| undefined` |  |  | The `id` of the native control; the label's `for` and the description and message ids derive from it. Generated when omitted. |
 | `indeterminate` | `boolean \| undefined` | `false` |  | Sets the input in an indeterminate state. |
+| `inputAlign` | `FieldCrossAlign \| undefined` |  |  | Vertical position of the control in a side-by-side row; not `inputPosition`, the horizontal one. Omitted, the control's first line meets the label's. |
 | `inputPosition` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can. |
 | `label` | `string` |  | yes | Text content of the label of the element. |
+| `labelAlign` | `FieldCrossAlign \| undefined` |  |  | Vertical position of the label block in a side-by-side row; not `labelPosition`, the horizontal one. Omitted, the label's first line meets the control's. |
 | `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
 | `layout` | `FieldLayout \| undefined` | `"auto"` |  | How the label and the input sit together: `'vertical'`, `'horizontal'` (50/50), `'auto'`, `'label-fill'` (the label takes the free space, the input keeps its size), `'input-fill'` (the other way round), or a two-word ratio pattern like `'xx xxxxx'`. |
 | `modelValue` | `any` |  |  | Used by v-model. Can be any serializable type. |
@@ -772,7 +779,7 @@ States are listed in precedence order: when two are on at once and their entries
 - Listed nodes are the ones `BbCheckbox`'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 `manifest/components/BbCheckbox.tree.json`.
 
 - `BbCheckbox` _(this component)_ — its own template binds: `icon` → `BbBaseCheckboxIcon`
-  - `CommonField` _(internal — not importable, reach it through `BbCheckbox`)_ — `BbCheckbox`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint`, `message` → `div.bb-field__message`; documented CSS variables: `--ctrl-line`; also mounts `BbAsterisk`
+  - `CommonField` _(internal — not importable, reach it through `BbCheckbox`)_ — `BbCheckbox`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint`, `counter` → `span.bb-field__counter`, `message` → `div.bb-field__message`; documented CSS variables: `--ctrl-line`; also mounts `BbAsterisk`
   - Also mounts `BbBaseCheckboxIcon`
 
 ## See Also

package/dist/ai/BbCheckboxGroup.md

@@ -19,6 +19,7 @@
 | `pt:label` | `component` | `CommonField` _(internal)_ |
 | `pt:description` | `span.bb-field__description` | `CommonField` _(internal)_ |
 | `pt:hint` | `span.bb-field__hint` | `CommonField` _(internal)_ |
+| `pt:counter` | `span.bb-field__counter` | `CommonField` _(internal)_ |
 | `pt:message` | `div.bb-field__message` | `CommonField` _(internal)_ |
 | `pt:list` | `span` | `OptionsContainer` _(internal)_ |
 | `pt:item` | `label` | `OptionsContainer` _(internal)_ |
@@ -377,6 +378,9 @@ disabling it.
   same keywords as `layout`; `item-reverse` swaps the two. A settings list is
   `list-layout="vertical-stretch" item-layout="label-fill" item-reverse`: the
   label takes the row, the input sits at the trailing edge.
+  `item-input-align` / `item-label-align` (`top | center | bottom`) aim each
+  row's cells vertically, as in the switch group's settings list; the field's
+  `input-align` / `label-align` move the options against the legend.
 - `layout` arranges the **legend against the options block** (the outer
   split): `'auto'`, `'horizontal'`, `'vertical'`, `'label-fill'`,
   `'input-fill'`, or a proportional pattern like `'xx xxxxxx'`.
@@ -695,11 +699,14 @@ above.
 
 ### Async items, loading and coherence
 
-`items` also accepts a provider function (`(prefill, modelValue) => T[] |
-Promise<T[]>`) for options fetched from an API. The group calls it on mount with
-`prefill = true`; every dependency-driven refetch passes `prefill = false`.
+`items` also accepts a provider function for options fetched from an API. It is
+called with one context object — `BbCheckboxGroupItemsContext`: `reason`
+(`'initial'` on mount, `'dependencies'` on a dependency-driven refetch,
+`'model'` when the model changed from outside and the options cannot resolve
+it), `modelValue` and `signal`; a group has no search field, so no `query`.
 While it resolves, `loading-text` (or the `#loading` slot) shows; `empty-text`
-(or `#empty`) covers the empty result. Loading and race protection are
+(or `#empty`) covers the empty result, and `failed-text` (or `#empty` with its
+`error` prop) a load that threw. Loading, cancellation and race protection are
 built in — don't wrap the provider in your own `loading` ref or debounce.
 
 Tie the option set to external state with `dependencies` (debounced by
@@ -791,12 +798,11 @@ const allScopes: Scope[] = [
 const role = ref<Role>('developer');
 const scopes = ref<string[]>(['repo:read', 'repo:write']);
 
-// Non-query group provider: (prefill, modelValue). Groups always pass
-// `prefill = true` — mount load and dependency refetches alike.
-const loadScopes = (
-	_prefill: boolean,
-	_modelValue?: string[]
-): Promise<Scope[]> =>
+// The group calls the provider with one context object (`reason`,
+// `modelValue`, `signal`); this one needs none of it — the role it filters by
+// is read from the ref — so it takes no parameter. `reason` would read
+// `'initial'` on the mount load and `'dependencies'` on a role change.
+const loadScopes = (): Promise<Scope[]> =>
 	new Promise((resolve) => {
 		setTimeout(
 			() =>
@@ -980,8 +986,9 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
 | `emptyText` | `string \| undefined` |  |  | String displayed when there are no items to display. |
-| `enforceCoherence` | `boolean \| undefined` | `false` |  | If coherence is enforced the input cannot have a modelValue that is incoherent with its current items. e.g. You cannot set v-model to a user that is not present in the items passed. modelValue will be reset upon incoherence. |
+| `enforceCoherence` | `boolean \| undefined` | `false` |  | If coherence is enforced the input cannot have a modelValue that is incoherent with its current items. e.g. You cannot set v-model to a user that is not present in the items passed. modelValue will be reset upon incoherence. Checked after every applied, successful load (an empty one included); a failed load never prunes. |
 | `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby`, so the reason the field is invalid is re-read whenever the control regains focus. |
+| `failedText` | `string \| undefined` | `the localized `common.failedText` ("Couldn't load items")` |  | String displayed in the empty state while the latest load FAILED (the `items` provider threw): the twin of `emptyText` for that case. |
 | `formless` | `boolean \| undefined` | `false` |  | Keep this control out of the enclosing `BbForm` entirely: not submitted, not dirty, not reset, not validated. For a control that is not form data (a filter, a "show advanced" switch). |
 | `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
 | `hasWarnings` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
@@ -989,13 +996,17 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `hideLegend` | `boolean \| undefined` | `false` |  | Visually hides the legend of the fieldset while maintaining accessibility. |
 | `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
 | `id` | `string \| undefined` |  |  | Prefix for the ids of each option's input and of the label, description and message. Generated when omitted. |
+| `inputAlign` | `'top'` \| `'center'` \| `'bottom'` |  |  | Vertical position of the control in a side-by-side row; not `inputPosition`, the horizontal one. Omitted, the control's first line meets the label's. |
 | `inputPosition` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can. |
+| `itemInputAlign` | `'top'` \| `'center'` \| `'bottom'` |  |  | Vertical position of each option's control in its row; `'center'` is the middle of the label plus its description. Omitted, it sits on the label's first line. |
+| `itemLabelAlign` | `'top'` \| `'center'` \| `'bottom'` |  |  | Vertical position of each option's label in its row. Omitted, it stays as it is. |
 | `itemLayout` | `FieldLayout \| undefined` | `'auto'` |  | How each row's input and label sit together — the keywords of `layout`: `'auto'`, `'vertical'` (the input above the label), `'horizontal'` (50/50), `'label-fill'` (the label takes the row's free space — pair it with `list-layout="vertical-stretch"` and `item-reverse` for a settings list), `'input-fill'`, or a two-word ratio pattern like `'xx xxxxx'`, read in on-screen order. |
 | `itemProps` | `BbOptionGroupItemProps<T> \| undefined` |  |  | ADDITIONAL row fields resolved from each item — never its text or value (those stay on `itemText` / `itemValue`). Option groups accept one field: - `description` — a muted line under the option label, beside the control; it may wrap. Either an object with a path or getter per field (`{ description: 'email' }`) or a function returning the fields (`(item) => ({ description: item.email })`). Without it no field renders — an item's own `description` is never read implicitly — and an empty value renders nothing for that item. The description is announced as the option's description, never part of its name. To disable individual options use `selectable`. |
 | `itemReverse` | `boolean \| undefined` | `false` |  | Swaps each row's input and label from their natural order (input first), in every `item-layout`. `reverse` swaps the legend and the options instead. |
-| `items` | `T[] \| ((prefill: boolean, modelValue?: any) => T[] \| Promise<T[]>)` |  | yes | Used to retrieve items; can be an array or a function. |
+| `items` | `T[] \| ((context: BbCheckboxGroupItemsContext) => T[] \| Promise<T[]>)` |  | yes | The options: an array, or a provider function called with ONE context object and returning the rows, sync or async. The context carries: - `reason` — why this call happened: `'initial'` (the first load, on mount), `'dependencies'` (a `dependencies` entry or the `items` function changed; a retry arrives this way) or `'model'` (the model changed from outside and the options cannot resolve it). The group has no search field, so it never passes `query`; - `modelValue` — the `v-model` as-is; - `signal` — an `AbortSignal`, aborted when a newer call starts or the group is disposed; pass it to every request. A provider signals a failure by THROWING, never by returning `[]`: the rows are cleared, nothing is pruned, and `#empty` receives the `error` (`failed-text` is shown). Zero-argument providers keep working. Annotate the parameter `BbCheckboxGroupItemsContext` (`BbSwitchGroupItemsContext` on a switch group, the same shape). |
 | `itemText` | `ItemAccessor<T, string> \| undefined` | `JSON.stringify(item)` |  | Defines a path that returns a property of the object to use as text or a function that returns a string. |
 | `itemValue` | `ItemAccessor<T> \| undefined` | `the whole item` |  | Defines a path that returns a property of the object to use as value or a function that returns any value. |
+| `labelAlign` | `'top'` \| `'center'` \| `'bottom'` |  |  | Vertical position of the label block in a side-by-side row; not `labelPosition`, the horizontal one. Omitted, the label's first line meets the control's. |
 | `layout` | `FieldLayout \| undefined` |  |  | How the label and the input sit together: `'vertical'`, `'horizontal'` (50/50), `'auto'`, `'label-fill'` (the label takes the free space, the input keeps its size), `'input-fill'` (the other way round), or a two-word ratio pattern like `'xx xxxxx'`. |
 | `legend` | `string` |  | yes | Text content of the legend. |
 | `legendMode` | `"outside" \| "inside" \| undefined` |  |  | Legend rendering mode. `'outside'` renders the legend above the fieldset in the normal flow; `'inside'` overlays the legend inside the fieldset border. Floating mode is not supported for option groups (checkbox, radio or switch) — there is no single field for the legend to float against. |
@@ -1065,7 +1076,7 @@ States are listed in precedence order: when two are on at once and their entries
 
 - `append` — scope: `object` — Content rendered after the last option, inside the options container.
 - `description` — scope: `BbCheckboxGroupDescriptionSlotProps` `{ text: string; hasErrors: boolean; hasWarnings: boolean }` — Replaces the description text. Provided alone (no `description` prop) it still renders the description region and wires it into `aria-describedby`.
-- `empty` — scope: `object` — Content shown when no options are available (replaces the default "no data" text).
+- `empty` — scope: `{ error: unknown; }` — Content shown when no options are available (replaces the default "no data" text). `error` is what the latest failed load rejected with, untouched, and `null` when nothing failed — a failed load clears the rows, so this slot is where it shows.
 - `icon` — scope: `BbCheckboxGroupIconSlotProps<T>` `{ disabled: boolean; readonly: boolean; checked: boolean; indeterminate?: boolean; focused: boolean; focusVisible: boolean; id: string; name: string; falseValue: any; hasErrors: boolean; hasWarnings: boolean; parsedValue: string; trueValue: any; value: any; item: T; text: string }` — Replaces the default checkmark icon for each checkbox option.
 - `label` — scope: `BbCheckboxGroupLabelSlotProps<T>` `{ item: T; text: string; checked: boolean; description: string }` — Replaces the default label text for each option.
 - `legend` — scope: `BbCheckboxGroupLegendSlotProps` `{ text: string; hasErrors: boolean; hasWarnings: boolean }` — Replaces the default fieldset legend text for the group.
@@ -1092,7 +1103,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - Listed nodes are the ones `BbCheckboxGroup`'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 `manifest/components/BbCheckboxGroup.tree.json`.
 
 - `BbCheckboxGroup` _(this component)_ — its own template binds: `icon` → `BbBaseCheckboxIcon`
-  - `CommonField` _(internal — not importable, reach it through `BbCheckboxGroup`)_ — `BbCheckboxGroup`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint`, `message` → `div.bb-field__message`; documented CSS variables: `--ctrl-line`; also mounts `BbAsterisk`
+  - `CommonField` _(internal — not importable, reach it through `BbCheckboxGroup`)_ — `BbCheckboxGroup`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint`, `counter` → `span.bb-field__counter`, `message` → `div.bb-field__message`; documented CSS variables: `--ctrl-line`; also mounts `BbAsterisk`
   - `OptionsContainer` _(internal — not importable, reach it through `BbCheckboxGroup`)_ — `BbCheckboxGroup`'s pt parts land here: `list` → `span`, `item` → `label`, `label` → `span`, `itemDescription` → `span`
   - Also mounts `BbBaseCheckboxIcon`
 

package/dist/ai/BbColorInput.md

@@ -21,6 +21,7 @@
 | `pt:label` | `component` | `CommonField` _(internal)_ |
 | `pt:description` | `span.bb-field__description` | `CommonField` _(internal)_ |
 | `pt:hint` | `span.bb-field__hint` | `CommonField` _(internal)_ |
+| `pt:counter` | `span.bb-field__counter` | `CommonField` _(internal)_ |
 | `pt:message` | `div.bb-field__message` | `CommonField` _(internal)_ |
 | `pt:box` | `span.bb-field-input__box` | `CommonFieldInput` _(internal)_ |
 | `pt:prefix` | `span.bb-field-input__prefix` | `CommonFieldInput` _(internal)_ |
@@ -694,7 +695,9 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
 | `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
 | `id` | `string \| undefined` |  |  | The `id` of the native control; the label's `for` and the description and message ids derive from it. Generated when omitted. |
+| `inputAlign` | `FieldCrossAlign \| undefined` |  |  | Vertical position of the control in a side-by-side row; not `inputPosition`, the horizontal one. Omitted, the control's first line meets the label's. |
 | `label` | `string` |  | yes | Text content of the label of the element. |
+| `labelAlign` | `FieldCrossAlign \| undefined` |  |  | Vertical position of the label block in a side-by-side row; not `labelPosition`, the horizontal one. Omitted, the label's first line meets the control's. |
 | `labelMode` | `"outside" \| "floating" \| "inside" \| undefined` |  |  | Label rendering mode: `outside` places the label above the input, `floating` overlays it on the field and shrinks it when a value is set, `inside` keeps it inside the field. |
 | `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
 | `layout` | `FieldLayout \| undefined` |  |  | How the label and the input sit together: `'vertical'`, `'horizontal'` (50/50), `'auto'`, `'label-fill'` (the label takes the free space, the input keeps its size), `'input-fill'` (the other way round), or a two-word ratio pattern like `'xx xxxxx'`. |
@@ -800,7 +803,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - Listed nodes are the ones `BbColorInput`'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 `manifest/components/BbColorInput.tree.json`.
 
 - `BbColorInput` _(this component)_ — its own template binds: `controlAttrs` → `input.bb-color-input__input`, `input` → `input.bb-color-input__input`, `indicator` → `button.bb-color-input__indicator`, `suffix` → `span.bb-field-input__suffix`; hands `BbColorPalette` the pt map `{ panel: 'panel', sheet: 'sheet', swatch: 'swatch' }` (ours → theirs)
-  - `CommonField` _(internal — not importable, reach it through `BbColorInput`)_ — `BbColorInput`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint`, `message` → `div.bb-field__message`; documented CSS variables: `--ctrl-line`; also mounts `BbAsterisk`
+  - `CommonField` _(internal — not importable, reach it through `BbColorInput`)_ — `BbColorInput`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint`, `counter` → `span.bb-field__counter`, `message` → `div.bb-field__message`; documented CSS variables: `--ctrl-line`; also mounts `BbAsterisk`
   - `CommonFieldInput` _(internal — not importable, reach it through `BbColorInput`)_ — `BbColorInput`'s pt parts land here: `box` → `span.bb-field-input__box`, `prefix` → `span.bb-field-input__prefix`, `icon` → `BbIcon`, `clear` → `ClearableButton`, `spinner` → `BbSpinner`, `suffix` → `span.bb-field-input__suffix`; documented CSS variables: `--bg`, `--bg-hover`, `--bg-focus`, `--bg-disabled`, `--fg-disabled`, `--border-color`, `--border-focus`, `--ring-size`, `--ring-color`, `--elev`, `--frost`, `--inside-label-clearance`; also mounts `ErrorIcon`, `WarningIcon`, `ClearableButton`, `BbIcon`, `BbSpinner`
   - `BbColorPalette` _(public — [contract](./BbColorPalette.md))_ — its own pt parts (`BbColorPalette`): `swatch` → `button.bb-color-palette__swatch`, `panel` → `div`, `panel` → `CommonPopover`; hands `BbOffCanvas` the pt map `{ panel: 'root', sheet: 'root' }` (ours → theirs); documented CSS variables: `--edge`; also mounts `CommonPopover`
     - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__content`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--handle-w`, `--handle-h`, `--handle-bg`, `--safe-top`, `--close-size`

package/dist/ai/BbDatePicker.md

@@ -209,11 +209,11 @@ const time = ref<string | null>(null);
 The picker passes its day slots straight to the calendar inside it, so the four
 day-grid slots work here unchanged:
 
-- `#day` replaces every day's number and `#append:day` adds under every day
+- `#day` replaces every day's number and `#day:append` adds under every day
   (event dots, prices). Both receive `label`, `selected`, `outside`,
   `first` / `middle` / `last` and `item` (the day as a dayjs object).
-- `#<YYYY-MM-DD>` and `#append:<YYYY-MM-DD>` do the same for one date, e.g.
-  `#append:2026-12-25`: its local `YYYY-MM-DD`, exactly as written. A date's
+- `#<YYYY-MM-DD>` and `#<YYYY-MM-DD>:append` do the same for one date, e.g.
+  `#2026-12-25:append`: its local `YYYY-MM-DD`, exactly as written. A date's
   slot wins over the every-day one.
 
 ```vue
@@ -221,12 +221,12 @@ day-grid slots work here unchanged:
 	<template #activator="{ props, value }">
 		<BbButton v-bind="props" variant="outline">{{ value ?? 'Pickup day' }}</BbButton>
 	</template>
-	<template #append:2026-12-25><span class="text-[10px]">Closed</span></template>
+	<template #2026-12-25:append><span class="text-[10px]">Closed</span></template>
 </BbDatePicker>
 ```
 
 Use per-date slots for a few fixed dates; mark data-driven days through
-`#append:day` and a lookup on `item`. The [BbCalendar](./BbCalendar.md) guide
+`#day:append` and a lookup on `item`. The [BbCalendar](./BbCalendar.md) guide
 has a worked example.
 
 ### Adaptive and positioning
@@ -430,7 +430,7 @@ and digit typeahead; the time rail exposes labelled columns. Always pass a
 | `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Props for the phone sheet. A `pt` inside it, object or colon keys, styles only that sheet. Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile (e.g. `title`, `size`, `persistent`). Spread over the defaults: the sheet is `draggable` (the time wheels and the year list never drag it) and hides its ✕ (picking, backdrop, Escape and drag close it); pass `{ hideClose: false }` to bring the ✕ back. A `pt` inside it styles ONLY the sheet, in `BbOffCanvas`'s part words (`root`, `header`, `title`, `description`, `content`, `footer`, `close`; state `open`), object (`{ pt: { header: '…' } }`) or colon keys (`{ 'pt:header': '…' }`) alike. It merges after what this component forwards to its sheet, so it wins a conflict and drops nothing — see the passthrough guide § Inside the sheet. For this component it is the only way to style the sheet's header, title and ✕: its own `pt:header` is the calendar's navigation bar. |
 | `offset` | `number \| undefined` | `4` |  | Space the popover keeps from the activator. |
 | `padding` | `number \| undefined` |  |  | Minimum empty space to keep from the edge of the page. |
-| `placement` | `'left'` \| `'right'` \| `'top'` \| `'top-start'` \| `'top-end'` \| `'right-start'` \| `'right-end'` \| `'bottom'` \| `'bottom-start'` \| `'bottom-end'` \| `'left-start'` \| `'left-end'` |  |  | Position of the popover relative to the activator/anchor. |
+| `placement` | `'top'` \| `'bottom'` \| `'left'` \| `'right'` \| `'top-start'` \| `'top-end'` \| `'right-start'` \| `'right-end'` \| `'bottom-start'` \| `'bottom-end'` \| `'left-start'` \| `'left-end'` |  |  | Position of the popover relative to the activator/anchor. |
 | `range` | `boolean \| undefined` | `false` |  | Enables range selection (`[start, end]`). |
 | `readonly` | `boolean \| undefined` | `false` |  | Prevents opening while keeping the activator visible. |
 | `seconds` | `boolean \| undefined` | `false` |  | Adds the seconds column (requires `type="datetime"`). |
@@ -491,10 +491,10 @@ States are listed in precedence order: when two are on at once and their entries
 ## Slots
 
 - `activator` — scope: `BbDatePickerActivatorSlotProps` `{ props: { ref: (el: unknown) => void; 'aria-haspopup': "dialog"; 'aria-expanded': "true" \| "false"; 'aria-labelledby': string; }; anchorProps: { ref: (el: unknown) => void; }; open: boolean; value: string \| string[] \| null; disabled: boolean }` — Custom activator element. Apply `v-bind="props"` to your trigger.
-- `append:day` — scope: `BbCalendarDaySlotProps` `{ first: boolean; item: any; label: string; last: boolean; middle: boolean; outside: boolean; selected: boolean }` — Appends content below each calendar day.
 - `day` — scope: `BbCalendarDaySlotProps` `{ first: boolean; item: any; label: string; last: boolean; middle: boolean; outside: boolean; selected: boolean }` — Replaces the day button label inside each calendar day.
+- `day:append` — scope: `BbCalendarDaySlotProps` `{ first: boolean; item: any; label: string; last: boolean; middle: boolean; outside: boolean; selected: boolean }` — Appends content below each calendar day.
 - `#<YYYY-MM-DD>` (named from data) — scope: `BbCalendarDaySlotProps` — One date's button label (e.g. `#2024-03-15`: the local `YYYY-MM-DD`, which `slotKey` leaves as it is); beats `day`. Day grid only.
-- `#append:<YYYY-MM-DD>` (named from data) — scope: `BbCalendarDaySlotProps` — Content under one date's cell; beats `append:day`.
+- `#<YYYY-MM-DD>:append` (named from data) — scope: `BbCalendarDaySlotProps` — Content under one date's cell; beats `day:append`.
 
 ## CSS custom properties
 

package/dist/ai/BbDatePickerInput.md

@@ -18,6 +18,7 @@
 | `pt:label` | `component` | `CommonField` _(internal)_ |
 | `pt:description` | `span.bb-field__description` | `CommonField` _(internal)_ |
 | `pt:hint` | `span.bb-field__hint` | `CommonField` _(internal)_ |
+| `pt:counter` | `span.bb-field__counter` | `CommonField` _(internal)_ |
 | `pt:message` | `div.bb-field__message` | `CommonField` _(internal)_ |
 | `pt:box` | `span.bb-field-input__box` | `CommonFieldInput` _(internal)_ |
 | `pt:prefix` | `span.bb-field-input__prefix` | `CommonFieldInput` _(internal)_ |
@@ -176,12 +177,13 @@ entirely, reach for `disableWriting` (below), not `range`.
 ### The segmented field & typing
 
 The value is edited as three separate inputs — day, month, year — not one free
-string. Their **order follows `config.locale`**: `en` renders `MM / DD / YYYY`,
-every other locale (e.g. `it`) renders `DD / MM / YYYY`. Typing is forgiving:
+string. Their **order and separator follow `config.locale`**, read from the
+locale's own format hint: `en` renders `MM/DD/YYYY`, `it` `DD/MM/YYYY`, `de`
+`TT.MM.JJJJ`, `ja` `YYYY/MM/DD`. Typing is forgiving:
 
 - digits **auto-advance** to the next segment when a segment fills (or can't
   take another digit — e.g. `4` in a day segment becomes `04` and moves on);
-- `/`, `-` or space also advances; **Backspace** at the start of a segment (and
+- `/`, `-`, `.` or space also advances; **Backspace** at the start of a segment (and
   **←** / **→** at the edges) moves between segments;
 - **↑** / **↓** step the focused segment by one, wrapping at its bounds (day
   `31` → `01`, month `12` → `01`, a 24-hour `23` → `00` — and back the other
@@ -215,7 +217,7 @@ disable that day. `firstDayOfWeek` shifts the calendar grid (`0` = Sunday …
 `6` = Saturday).
 
 The example below combines a rolling `min`/`max` window, a weekdays-only
-predicate, `floating` output, and the `append:day` slot to dot specific days.
+predicate, `floating` output, and the `day:append` slot to dot specific days.
 
 **Bounded, weekdays-only, with event dots**
 
@@ -241,7 +243,7 @@ predicate, `floating` output, and the `append:day` slot to dot specific days.
 			prepend:icon="lucide:calendar-check"
 			:selectable="isWeekday"
 		>
-			<template #append:day="{ item }">
+			<template #day:append="{ item }">
 				<span
 					v-if="hasOpenSlots(item)"
 					class="mx-auto mt-0.5 block h-1 w-1 rounded-full bg-current opacity-70"
@@ -263,7 +265,7 @@ const appointment = ref<string | null>(null);
 const min = dayjs().format('YYYY-MM-DD');
 const max = dayjs().add(30, 'day').format('YYYY-MM-DD');
 
-// Days that still have open demo slots — dotted via the `append:day` slot.
+// Days that still have open demo slots — dotted via the `day:append` slot.
 const openSlots = [3, 5, 8, 12].map((offset) =>
 	dayjs().add(offset, 'day').format('YYYY-MM-DD')
 );
@@ -383,7 +385,7 @@ const setPreset = (days: number) => {
 ```
 
 There is no day segment to tab through under `month`, no month segment under
-`year`, and the placeholder/format hint follows suit (`MM/YYYY`, localized) —
+`year`, and the placeholder/format hint follows suit (`MM/YYYY`, `MM.JJJJ` in `de`: the locale's words and separator) —
 promising `DD/MM/YYYY` to a two-segment field would be worse than no hint at
 all. The calendar button opens the matching terminal grid, so typing and
 picking always produce the same shape.
@@ -427,8 +429,9 @@ Tuning knobs, all inert without `type="datetime"` (DEV warning):
   renders 00/15/30/45 — and constrains what the panel _produces_, never what
   the field _accepts_: a typed `10:07` is emitted verbatim, and no column row
   highlights for it.
-- **`ampm`** switches the display to 12-hour with an AM/PM segment (type `A` /
-  `P`, or cycle with ArrowUp/Down). Purely visual: the model stays 24-hour.
+- **`ampm`** switches the display to 12-hour with an AM/PM segment in the
+  locale's words (`午前` / `午後` in `ja`; type `A` / `P` or the word, or cycle
+  with ArrowUp/Down). Purely visual: the model stays 24-hour.
 - **`min` / `max`** additionally accept `YYYY-MM-DDTHH:mm` to tighten the
   boundary day to a minute; date-only bounds keep working day-granular, so any
   time inside the boundary day is fine.
@@ -573,18 +576,18 @@ during setup** — every platform must keep at least one interaction method.
 
 ### Decorating days
 
-The `day` slot **replaces** a day's contents; the `append:day` slot **adds**
+The `day` slot **replaces** a day's contents; the `day:append` slot **adds**
 below it (badges, event dots, price tags). Both receive the day's state — `label`
 (the day number), `selected`, `outside` (a day of the previous or next month),
 `first` / `middle` / `last` (range edges) and `item` (the underlying dayjs object, for formatting or lookups). Keep
 decorations lightweight; they render for every visible cell. The appointment
-example above uses `append:day` for event dots.
+example above uses `day:append` for event dots.
 
 One date can have its own slot: `#<YYYY-MM-DD>` replaces that date's number and
-`#append:<YYYY-MM-DD>` adds under it, e.g. `#append:2026-12-25` — the local
-`YYYY-MM-DD`, exactly as written. A date's slot wins over `day` / `append:day` for
+`#<YYYY-MM-DD>:append` adds under it, e.g. `#2026-12-25:append` — the local
+`YYYY-MM-DD`, exactly as written. A date's slot wins over `day` / `day:append` for
 that date. Use them for a few fixed dates (holidays); mark data-driven days with
-`append:day` and a lookup on `item`.
+`day:append` and a lookup on `item`.
 
 ### Calendar keyboard navigation
 
@@ -675,7 +678,8 @@ sheet), its events differ from a plain input:
   `config.defaultInputLabelMode`) the label is embedded in the field, so the
   layout is forced vertical and `layout` is ignored — same rule as
   `BbTextInput`/`BbSelect`/`BbNumberInput`.
-- **`config.locale`** drives both the segment order (`en` → month-first) and the
+- **`config.locale`** drives both the segment order and separator (from the
+  locale's `datePickerInput.dateFormatSingle` hint) and the
   calendar's month/weekday names via dayjs (a dayjs pack is bundled for each of
   your `enabledLocales` — see
   [Installation and Plugin Setup](./guides/installation-and-plugin-setup.md) §
@@ -876,7 +880,9 @@ label>')` matches nothing; query each segment by its own label instead. See
 | `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
 | `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
 | `id` | `string \| undefined` |  |  | The `id` of the native control; the label's `for` and the description and message ids derive from it. Generated when omitted. |
+| `inputAlign` | `'top'` \| `'center'` \| `'bottom'` |  |  | Vertical position of the control in a side-by-side row; not `inputPosition`, the horizontal one. Omitted, the control's first line meets the label's. |
 | `label` | `string` |  | yes | Text content of the label of the element. |
+| `labelAlign` | `'top'` \| `'center'` \| `'bottom'` |  |  | Vertical position of the label block in a side-by-side row; not `labelPosition`, the horizontal one. Omitted, the label's first line meets the control's. |
 | `labelMode` | `"outside" \| "floating" \| "inside" \| undefined` |  |  | Label rendering mode. |
 | `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
 | `layout` | `FieldLayout \| undefined` |  |  | How the label and the input sit together: `'vertical'`, `'horizontal'` (50/50), `'auto'`, `'label-fill'` (the label takes the free space, the input keeps its size), `'input-fill'` (the other way round), or a two-word ratio pattern like `'xx xxxxx'`. |
@@ -974,9 +980,9 @@ States are listed in precedence order: when two are on at once and their entries
 ## Slots
 
 - `append` — scope: `object` — Content rendered after the date fields, at the end of the field box (before the calendar toggle button).
-- `append:day` — scope: `{ first: boolean; item: Dayjs; label: string; last: boolean; middle: boolean; outside: boolean; selected: boolean; }` — Appends content below each calendar day.
 - `append:outer` — scope: `object` — Content rendered after the entire date picker control, outside the input chrome.
 - `day` — scope: `{ first: boolean; item: Dayjs; label: string; last: boolean; middle: boolean; outside: boolean; selected: boolean; }` — Replaces the day button label inside each calendar day.
+- `day:append` — scope: `{ first: boolean; item: Dayjs; label: string; last: boolean; middle: boolean; outside: boolean; selected: boolean; }` — Appends content below each calendar day.
 - `description` — scope: `BbDatePickerInputDescriptionSlotProps` `{ text: string; hasErrors: boolean; hasWarnings: boolean }` — Replaces the description text. Provided alone (no `description` prop) it still renders the description region and wires it into `aria-describedby`.
 - `label` — scope: `BbDatePickerInputLabelSlotProps` `{ text: string; hasErrors: boolean; hasWarnings: boolean }` — Replaces the default label text rendered above the date picker.
 - `prefix` — scope: `object` — Inline content rendered at the start of the input field area, before the date fields.
@@ -984,7 +990,7 @@ States are listed in precedence order: when two are on at once and their entries
 - `prepend:outer` — scope: `object` — Content rendered before the entire date picker control, outside the input chrome.
 - `suffix` — scope: `object` — Inline content rendered at the end of the input field area, after the date fields.
 - `#<YYYY-MM-DD>` (named from data) — scope: `BbCalendarDaySlotProps` — One date's button label (e.g. `#2024-03-15`: the local `YYYY-MM-DD`, which `slotKey` leaves as it is); beats `day`. Day grid only.
-- `#append:<YYYY-MM-DD>` (named from data) — scope: `BbCalendarDaySlotProps` — Content under one date's cell; beats `append:day`.
+- `#<YYYY-MM-DD>:append` (named from data) — scope: `BbCalendarDaySlotProps` — Content under one date's cell; beats `day:append`.
 
 ## CSS custom properties
 
@@ -1010,7 +1016,7 @@ Set these on the element, or on a class you put on it, to retune this component
       - `CommonTimeSelector` _(internal — not importable, reach it through `BbCalendar`)_ — its own pt parts (`BbCalendar`): `header` → `div.bb-time-selector__header`, `cellColumnHeader` → `div.bb-time-selector__cell-column-header`, `item` → `BbBaseButton`; documented CSS variables: `--time-mark`; also mounts `BbBaseButton`
     - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__content`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--handle-w`, `--handle-h`, `--handle-bg`, `--safe-top`, `--close-size`
       - `CloseButton` _(internal — not importable, reach it through `BbOffCanvas`)_ — documented CSS variables: `--size`, `--p`
-  - `CommonField` _(internal — not importable, reach it through `BbDatePickerInput`)_ — `BbDatePickerInput`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint`, `message` → `div.bb-field__message`; documented CSS variables: `--ctrl-line`; also mounts `BbAsterisk`
+  - `CommonField` _(internal — not importable, reach it through `BbDatePickerInput`)_ — `BbDatePickerInput`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint`, `counter` → `span.bb-field__counter`, `message` → `div.bb-field__message`; documented CSS variables: `--ctrl-line`; also mounts `BbAsterisk`
   - `CommonFieldInput` _(internal — not importable, reach it through `BbDatePickerInput`)_ — `BbDatePickerInput`'s pt parts land here: `box` → `span.bb-field-input__box`, `prefix` → `span.bb-field-input__prefix`, `icon` → `BbIcon`, `clear` → `ClearableButton`, `spinner` → `BbSpinner`, `suffix` → `span.bb-field-input__suffix`; documented CSS variables: `--bg`, `--bg-hover`, `--bg-focus`, `--bg-disabled`, `--fg-disabled`, `--border-color`, `--border-focus`, `--ring-size`, `--ring-color`, `--elev`, `--frost`, `--inside-label-clearance`; also mounts `ErrorIcon`, `WarningIcon`, `ClearableButton`, `BbIcon`, `BbSpinner`
   - Also mounts `BbIcon`
 

package/dist/ai/BbDialog.md

@@ -479,8 +479,10 @@ Three rules keep dialog forms honest:
 ### Lifecycle events and lazy content
 
 Four events bracket the transitions — `show` fires as the model turns `true`,
-`shown` after the native `showModal()` call and initial focus, `hide` as the
-model turns `false`, and `hidden` after the close transition completes. Use
+`shown` after the open transition completes (focus has already moved in at
+`showModal()`), `hide` as the model turns `false`, and `hidden` after the close
+transition completes. A surface closed before it finished opening fires no
+`shown`. Use
 `@show` to (re)seed form state, `@hidden` to drop a draft and tear down
 expensive content.
 
@@ -1136,7 +1138,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to open / close the dialog. A dialog with no `v-model` starts closed. |
 | `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Props for the phone sheet. A `pt` inside it, object or colon keys, styles only that sheet. Overrides merged over the offcanvas (mobile) surface's props. The drawer defaults to a bottom, draggable, content-sized sheet (`side: 'bottom'`, `draggable: true`, `size: 'auto'`); use this to override those, set other drawer-only options (`stackGap`), or override shared props whose meaning differs on the drawer (`stack`). Ignored on the desktop dialog surface. A `pt` inside it styles ONLY the sheet, in `BbOffCanvas`'s part words (`root`, `header`, `title`, `description`, `content`, `footer`, `close`; state `open`), object (`{ pt: { header: '…' } }`) or colon keys (`{ 'pt:header': '…' }`) alike. It merges after what this component forwards to its sheet, so it wins a conflict and drops nothing — see the passthrough guide § Inside the sheet. |
 | `persistent` | `boolean \| undefined` | `false` |  | Prevent closing via outside clicks or Escape key. The header close (×) button STILL closes a persistent dialog — that is the documented escape hatch; combine with `hideClose` to remove it, or use `disabled` to block every dismissal. Programmatic close is still allowed. |
-| `size` | `Responsive<NonNullable<number \| ({ size?: any; } & string) \| keyof BbDialogSizes \| undefined>> \| undefined` | `"sm"` |  | Controls the maximum width of the dialog. Accepts named presets from `'xs'` to `'2xl'`, a custom CSS width string, or a numeric pixel value — or a per-breakpoint map (e.g. `{ default: 'sm', lg: 'lg' }`) to switch width responsively. |
+| `size` | `Responsive<NonNullable<number \| CssSize \| keyof BbDialogSizes \| undefined>> \| undefined` | `"sm"` |  | Controls the maximum width of the dialog. Accepts named presets from `'xs'` to `'2xl'`, a custom CSS width string, or a numeric pixel value — or a per-breakpoint map (e.g. `{ default: 'sm', lg: 'lg' }`) to switch width responsively. |
 | `stack` | `string \| undefined` |  |  | Name of the stack this dialog belongs to. Dialogs sharing the same `stack` value replace one another: only the most recently opened stays visible while the others in the stack are hidden beneath it. Dialogs in different stacks — or with no `stack` — never affect each other and remain fully visible. |
 | `title` | `string \| undefined` |  |  | Title text announced to assistive technologies. If omitted, no header is rendered (unless a `header` slot is supplied) and accessibility must be handled manually. |
 | `transitionDuration` | `number \| undefined` | `250` |  | Controls the duration of the open and close animations. |
@@ -1168,7 +1170,7 @@ States are listed in precedence order: when two are on at once and their entries
 - `hidden` — `(): void` — Emitted after the close transition completes and the dialog is fully dismissed.
 - `hide` — `(): void` — Emitted as soon as the dialog starts to close (model becomes false).
 - `show` — `(): void` — Emitted as soon as the dialog starts to open (model becomes true).
-- `shown` — `(): void` — Emitted after the dialog is fully opened via `showModal()`.
+- `shown` — `(): void` — Emitted once the open transition has run (symmetric with `hidden`): the dialog is settled, so code that measures or anchors to its content sees the final layout. Not emitted for a dialog closed before it finished opening.
 - `update:modelValue` — `(value: boolean): void` — Emitted with the new value whenever `v-model` changes.
 
 ## Slots