bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/BbBaseCheckboxGroup.md

@@ -0,0 +1,64 @@
+# BbBaseCheckboxGroup
+
+## Agent Contract
+
+- Safety level: **Reference Only - Internal**
+- Group: **Reference Only - Base Primitive**
+- Description: Internal low-level grouped checkbox primitive.
+- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
+- Implementation source (only when the contract below is not enough): [source/BbBaseCheckboxGroup.md](./source/BbBaseCheckboxGroup.md)
+
+## v-model
+
+- `v-model` — type: `any`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `ariaDescribedby` | `string \| undefined` |  |  | ID of the element that describes the entire checkbox group for assistive technologies. Forwarded to each generated input as `aria-describedby`. |
+| `autofocus` | `Booleanish \| undefined` |  |  | Automatically focuses the first checkbox on mount when true. Applied only to the first option. |
+| `dependencies` | `unknown[] \| undefined` |  |  | List of reactive values which, when changed, trigger items re-fetching. Useful to reload options based on external inputs. |
+| `depsDebounceTime` | `number \| undefined` | `0` |  | Debounce delay (ms) applied when reacting to `dependencies` changes. |
+| `direction` | `"horizontal" \| "vertical" \| undefined` | `"horizontal"` |  | Direction of the group layout. - `horizontal`: options flow in rows - `vertical`: options stack in a column |
+| `disabled` | `boolean \| undefined` |  |  | Disables interaction for the whole group. |
+| `enforceCoherence` | `boolean \| undefined` |  |  | Enforces that `modelValue` contains only values present in `items`. Incoherent values are removed and `update:modelValue` is emitted with a coherent array. Please check out {@link https://ui-components-docs.vercel.app/it/guides/coherence th… |
+| `hasErrors` | `boolean \| undefined` |  |  | Puts the component into an error state adds the error styling class. |
+| `hasWarning` | `boolean \| undefined` |  |  | Puts the component into a warning state. Errors take priority when both are set. |
+| `hideLabel` | `boolean \| undefined` |  |  | Visually hides each option's label text (the text rendered next to every input) while keeping it accessible to screen readers. |
+| `id` | `string \| undefined` |  |  | Identifier of the group. Used to derive per-option IDs for accessible labeling. |
+| `items` | `T[] \| ((prefill: boolean, modelValue?: any) => T[] \| Promise<T[]>)` | `[]` | yes | Items provider. Can be: - An array of items - A sync/async function `(prefill, modelValue) => items` When a function is provided, it is invoked on prefill and when dependencies change to load options dynamically. |
+| `itemText` | `(T extends object ? string \| ((item: T) => string) : (item: T) => string) \| undefined` |  |  | Defines how to derive the display text from an item. Accepts a nested key path into the item or a function `(item) => string`. |
+| `itemValue` | `(T extends object ? string \| ((item: T) => string) : (item: T) => any) \| undefined` |  |  | Defines how to derive the value from an item. Accepts a nested key path into the item or a function `(item) => any`. |
+| `loadingText` | `string \| undefined` |  |  | Text displayed while items are loading. |
+| `max` | `number \| undefined` | `Infinity` |  | Maximum number of selectable items. |
+| `modelValue` | `any` |  | yes | Selected values for the group. Used with `v-model`. Single value when `multiple` is false, array when `multiple` is true. |
+| `modelValueDebounceTime` | `number \| undefined` | `0` |  | Debounce delay (ms) applied when reacting to `modelValue` changes. |
+| `multiple` | `boolean \| undefined` | `true` |  | Enables multi-selection behavior. When `true`, `modelValue` must be an array and emitted updates are arrays. When `false`, `modelValue` must be a single value (or `null`) and emitted updates are single values. |
+| `name` | `string \| undefined` |  |  | Name attribute applied to each input for form submission. |
+| `noDataText` | `string \| undefined` |  |  | Text displayed when there are no items to show. |
+| `readonly` | `boolean \| undefined` |  |  | Makes all checkboxes read-only. Since checkboxes do not support native `readonly`, inputs are disabled while styled as read-only. |
+| `selectable` | `boolean \| ((item: T) => boolean) \| undefined` | `true` |  | Defines whether options are selectable. Can be a global boolean that affects all options or a function that accepts an item and returns a boolean that only affects that item. Non-selectable options are rendered disabled. |
+
+## Events
+
+- `active` — `(e: "active"): void` — Emitted when the group becomes active (focus/click enters it).
+- `blur` — `(e: "blur", event: FocusEvent): void` — Emitted when one of the generated checkbox inputs loses focus. Forwards the original DOM `FocusEvent`.
+- `change` — `(e: "change", event: Event): void` — Emitted when a checkbox option is toggled. Forwards the original DOM `Event` from the checkbox input.
+- `click` — `(e: "click", event: MouseEvent): void` — Emitted when one of the generated checkbox inputs is clicked. Forwards the original DOM `MouseEvent`.
+- `focus` — `(e: "focus", event: FocusEvent): void` — Emitted when one of the generated checkbox inputs receives focus. Forwards the original DOM `FocusEvent`.
+- `inactive` — `(e: "inactive"): void` — Emitted when focus/click moves outside the group after it was active. Useful for validation-on-blur flows at group level.
+- `input` — `(e: "input", event: Event): void` — Emitted on native input events from generated checkbox inputs. Forwards the original DOM `Event`.
+- `keydown` — `(e: "keydown", event: KeyboardEvent): void` — Emitted for keyboard interaction on generated checkbox inputs. Forwards the original DOM `KeyboardEvent`.
+- `mousedown` — `(e: "mousedown", event: MouseEvent): void` — Emitted when a pointing device button is pressed over a checkbox input. Forwards the original DOM `MouseEvent`.
+- `mouseup` — `(e: "mouseup", event: MouseEvent): void` — Emitted when a pointing device button is released over a checkbox input. Forwards the original DOM `MouseEvent`.
+- `update:modelValue` — `(e: "update:modelValue", value: any): void` — Emitted with the coherent next selection array whenever selection changes.
+
+## Slots
+
+- `append` — scope: `BaseCheckboxGroupEmptySlotProps` — Content rendered after the last option, inside the options container.
+- `icon` — scope: `BaseCheckboxGroupIconSlotProps<T>` — Replaces the default checkmark icon for each checkbox option. Receives all `BaseCheckbox` slot attributes plus the source item and its display text.
+- `label` — scope: `BaseCheckboxGroupLabelSlotProps<T>` — Replaces the default label text for each option.
+- `loading` — scope: `BaseCheckboxGroupEmptySlotProps` — Content shown while options are loading (replaces the default loading text).
+- `no-data` — scope: `BaseCheckboxGroupEmptySlotProps` — Content shown when no options are available (replaces the default "no data" text).
+- `prepend` — scope: `BaseCheckboxGroupEmptySlotProps` — Content rendered before the first option, inside the options container.

package/dist/ai/BbBaseCheckboxIcon.md

@@ -0,0 +1,174 @@
+# BbBaseCheckboxIcon
+
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Selection**
+- Description: Standalone checkbox glyph (box + checkmark SVG). Presentational only — no input, no events. Compose it into a fully custom checkbox design, or let BbCheckbox/BbBaseCheckbox render it.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbBaseCheckboxIcon.md](./source/BbBaseCheckboxIcon.md)
+
+## Usage & Guidelines
+
+### What this is (and when to reach for it)
+
+`BbBaseCheckboxIcon` is **only the visual** — the rounded box, the stroke-animated
+checkmark, and the indeterminate dash — extracted from `BbBaseCheckbox`. It has
+no native `<input>`, emits no events, and holds no state. You tell it how to
+look through boolean props; it draws that state.
+
+For virtually every form you should use [`BbCheckbox`](../BbCheckbox.md) (or
+[`BbCheckboxGroup`](../BbCheckboxGroup.md)) — they wire up the input, `v-model`,
+label, validation and accessibility for you. Reach for `BbBaseCheckboxIcon` only
+when the surrounding design is so different that a labelled checkbox row can't
+express it: a selectable card grid, a toolbar toggle, a bespoke list row. In
+those cases you own the real control (a native input or an ARIA widget) and drop
+the glyph in for the visuals.
+
+**Every visual state**
+
+```vue
+<div class="flex items-center gap-4">
+	<BbBaseCheckboxIcon :checked="false" />
+	<BbBaseCheckboxIcon :checked="true" />
+	<BbBaseCheckboxIcon :indeterminate="true" />
+	<BbBaseCheckboxIcon :checked="true" :disabled="true" />
+	<BbBaseCheckboxIcon :checked="true" :has-errors="true" />
+	<BbBaseCheckboxIcon :checked="true" :focus-visible="true" />
+</div>
+```
+
+### Compose it into a custom control
+
+The glyph is decorative (`aria-hidden`), so it **must** be paired with a real
+control. The reliable pattern: a `<label>` wrapping a visually-hidden native
+`<input type="checkbox">` (keep it in the a11y tree with `sr-only`, never
+`display:none`) plus the glyph reflecting `checked`. You get native keyboard
+support, focus, and form submission for free, and total freedom over the layout
+around it.
+
+**Invoice alert channel cards**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Invoice alerts</p>
+			<p class="text-xs text-gray-500">
+				Northwind · overdue notices for INV-1042 and later
+			</p>
+		</div>
+
+		<fieldset class="flex flex-col gap-1.5 border-0 p-0">
+			<legend class="sr-only">Notification channels</legend>
+			<label
+				v-for="channel in channels"
+				:key="channel.id"
+				class="flex cursor-pointer items-center gap-2.5 rounded-[var(--bb-radius)] border p-2.5 transition-colors"
+				:class="
+					selected.includes(channel.id)
+						? 'border-[color:var(--bb-primary)] bg-[color:var(--bb-muted)]'
+						: 'border-[color:var(--bb-border)] hover:bg-[color:var(--bb-surface-hover)]'
+				"
+			>
+				<!-- Glyph is decorative; the sr-only input owns focus, keyboard, and form state. -->
+				<input
+					v-model="selected"
+					class="sr-only"
+					type="checkbox"
+					:value="channel.id"
+				/>
+				<BbBaseCheckboxIcon :checked="selected.includes(channel.id)" />
+				<span class="flex min-w-0 flex-col">
+					<span class="text-sm font-medium">{{ channel.label }}</span>
+					<span class="text-xs text-gray-500">{{ channel.hint }}</span>
+				</span>
+			</label>
+		</fieldset>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbBaseCheckboxIcon } from 'bitboss-ui';
+
+type Channel = { id: string; label: string; hint: string };
+
+const channels: Channel[] = [
+	{ id: 'email', label: 'Email digest', hint: 'Morning summary · weekdays' },
+	{ id: 'sms', label: 'SMS', hint: 'Urgent overdue only' },
+	{ id: 'push', label: 'Slack #billing', hint: 'Posts to the shared channel' },
+];
+
+const selected = ref<string[]>(['email']);
+</script>
+```
+
+### Styling
+
+The glyph owns its own tokens, so restyle it by overriding CSS custom properties
+on the element (or an ancestor — they inherit):
+
+- `--size` — box edge length (default `16px`)
+- `--r` — corner radius (default `4px`)
+- `--color` — fill + border when checked/indeterminate (default `--bb-primary`)
+- `--check-color` — checkmark stroke (default `--bb-primary-fg`)
+- `--ring-color` — focus ring color
+
+**Bigger, rounder, recolored**
+
+```vue
+<BbBaseCheckboxIcon
+	:checked="true"
+	style="--size: 28px; --r: 999px; --color: #16a34a"
+/>
+```
+
+### Gotchas & anti-patterns
+
+- **Don't ship it as the whole control.** It is `aria-hidden` and non-focusable;
+  on its own it is invisible to keyboard and screen-reader users. Always back it
+  with a real `<input>` (or a proper ARIA checkbox widget).
+- **Don't reach for it when `BbCheckbox` fits.** If you need a labelled checkbox
+  in a form, `BbCheckbox` already does everything — the glyph is for designs the
+  wrapper genuinely can't express.
+- `indeterminate` wins over `checked` visually — a glyph that is both renders the
+  dash, matching native checkbox behavior.
+- It reflects state, it doesn't manage it: clicking the glyph does nothing by
+  itself. Toggle your own state (or the backing input) and pass it back in.
+
+### Works well with
+
+- [`BbCheckbox`](../BbCheckbox.md) — the batteries-included checkbox; prefer it
+  unless you truly need the bare glyph.
+- [`BbBaseRadioIcon`](../BbBaseRadioIcon.md) / [`BbBaseSwitchIcon`](../BbBaseSwitchIcon.md) — the
+  matching standalone glyphs for radios and switches.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `checked` | `boolean \| undefined` |  |  | Renders the checked state (fills the box and draws the checkmark). |
+| `disabled` | `boolean \| undefined` |  |  | Disables the glyph (muted fill, not-allowed cursor). Purely visual. |
+| `focusVisible` | `boolean \| undefined` |  |  | Whether keyboard focus is visible (`:focus-visible`). Draws the focus ring. |
+| `hasErrors` | `boolean \| undefined` |  |  | Puts the glyph into the error state (danger border and ring color). |
+| `hasWarning` | `boolean \| undefined` |  |  | Puts the glyph into the warning state (warn border and ring color). Errors take priority when both are set. |
+| `indeterminate` | `boolean \| undefined` |  |  | Renders the indeterminate state (filled box with a dash instead of the checkmark). Takes visual precedence over `checked`. |
+| `readonly` | `boolean \| undefined` |  |  | Renders the read-only affordance (default cursor instead of pointer). |
+
+## Events
+
+- None.
+
+## Slots
+
+- None.
+
+## See Also
+
+- [BbCheckbox](./BbCheckbox.md) — Toggles a single boolean option.
+- [BbBaseCheckbox](./BbBaseCheckbox.md) — Internal low-level checkbox primitive.
+- [BbBaseRadioIcon](./BbBaseRadioIcon.md) — Standalone radio glyph (ring + dot). Presentational only — no input, no events. Compose it into a fully custom radio design, or let BbRadio/BbBaseRadio render it.
+- [BbBaseSwitchIcon](./BbBaseSwitchIcon.md) — Standalone switch glyph (track + thumb). Presentational only — no input, no events. Compose it into a fully custom switch design, or let BbSwitch/BbBaseSwitch render it.

package/dist/ai/BbBaseColorInput.md

@@ -0,0 +1,64 @@
+# BbBaseColorInput
+
+## Agent Contract
+
+- Safety level: **Reference Only - Internal**
+- Group: **Reference Only - Base Primitive**
+- Description: Internal low-level color input primitive.
+- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
+- Implementation source (only when the contract below is not enough): [source/BbBaseColorInput.md](./source/BbBaseColorInput.md)
+
+## v-model
+
+- `v-model` — type: `string \| null`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `alpha` | `boolean \| undefined` | `false` |  | Enable the alpha channel. When true the picker shows an opacity slider and emits / accepts `#RRGGBBAA` hex8 values. |
+| `append:icon` | `string \| undefined` |  |  | Name of the icon to render at the right hand side of the input. |
+| `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of element(s) describing this input for assistive tech (space-separated). Typically includes the container hint id if used within a BaseInputContainer. |
+| `autocomplete` | `string \| undefined` | `"off"` |  | Autocomplete hint for the browser. |
+| `autofocus` | `Booleanish \| undefined` |  |  | Focus the input on mount. |
+| `clearable` | `boolean \| undefined` |  |  | Show a clear button when the input has a value. |
+| `compact` | `boolean \| undefined` |  |  | Display the component in a compact layout. |
+| `disabled` | `boolean \| undefined` |  |  | Disable all interactions. |
+| `eyeDropper` | `boolean \| undefined` |  |  | Show an eyedropper button to sample any color on screen. Uses the native EyeDropper API — hidden automatically on unsupported browsers. |
+| `hasErrors` | `boolean \| undefined` |  |  | Visually mark the component as invalid (also sets aria-invalid on the input). |
+| `hasWarning` | `boolean \| undefined` |  |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
+| `id` | `string \| undefined` |  |  | The id attribute for the input element. Defaults to a generated `bb_<unique>` id when omitted. |
+| `loading` | `boolean \| undefined` |  |  | Display the loading state. |
+| `modelValue` | `string \| null` |  | yes | v-model value: `#RRGGBB` hex string or `null` when empty. Example: `#1A2B3C` |
+| `name` | `string \| undefined` |  |  | Name attribute of the input. |
+| `placeholder` | `string \| undefined` |  |  | Placeholder text when there is no value. |
+| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to render at the start of the input. |
+| `readonly` | `boolean \| undefined` |  |  | Make the input read-only. |
+| `required` | `boolean \| undefined` |  |  | Mark the input as required. |
+| `swatches` | `boolean \| string[][] \| undefined` |  |  | Controls swatches display in the picker: - `true` — show the built-in Material-palette swatches - `string[][]` — show custom swatches (each inner array = a column of shades) - `false` / omitted — no swatches section |
+| `transitionDuration` | `number \| undefined` |  |  | Transition duration (ms) of the palette popover. |
+
+## Events
+
+- `blur` — `(event: "blur", event: FocusEvent): void`
+- `change` — `(event: "change", event: Event): void`
+- `click` — `(event: "click", event: MouseEvent): void`
+- `compositionend` — `(event: "compositionend", event: CompositionEvent): void`
+- `compositionstart` — `(event: "compositionstart", event: CompositionEvent): void`
+- `focus` — `(event: "focus", event: FocusEvent): void`
+- `input` — `(event: "input", event: Event): void`
+- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
+- `keyup` — `(event: "keyup", event: KeyboardEvent): void`
+- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
+- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
+- `paste` — `(event: "paste", event: ClipboardEvent): void`
+- `update:modelValue` — `(event: "update:modelValue", value: string \| null): void`
+
+## Slots
+
+- `append` — scope: `Record<string, never>` — Content rendered after the color picker indicator button, at the end of the inner container. Mutually exclusive with `suffix`: the `suffix` slot renders inside this slot's default content, so providing `append` replaces the suffix rendering…
+- `append-outer` — scope: `Record<string, never>` — Content rendered after the entire input control, outside the input chrome. This slot receives no scoped props.
+- `prefix` — scope: `Record<string, never>` — Inline content rendered at the start of the input field area, before the typed text. This slot receives no scoped props.
+- `prepend` — scope: `Record<string, never>` — Content rendered before the text input, at the start of the inner container. This slot receives no scoped props.
+- `prepend-outer` — scope: `Record<string, never>` — Content rendered before the entire input control, outside the input chrome. This slot receives no scoped props.
+- `suffix` — scope: `Record<string, never>` — Inline content rendered at the end of the input field area, after the typed text. Renders inside the default `append` area's suffix wrapper — mutually exclusive with `append`: if an `append` slot is provided it replaces this wrapper and the…

package/dist/ai/BbBaseColorPalette.md

@@ -0,0 +1,39 @@
+# BbBaseColorPalette
+
+## Agent Contract
+
+- Safety level: **Reference Only - Internal**
+- Group: **Inputs**
+- Description: Internal low-level color palette panel used by BbColorPalette and BbColorInput.
+- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
+- Implementation source (only when the contract below is not enough): [source/BbBaseColorPalette.md](./source/BbBaseColorPalette.md)
+
+## v-model
+
+- `v-model` — type: `string \| null`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `alpha` | `boolean \| undefined` | `false` |  | Enable alpha channel support. When true, an alpha slider is shown and emitted values include alpha as hex8. |
+| `eyeDropper` | `boolean \| undefined` | `false` |  | Show an eyedropper button that lets the user sample any color on screen. Uses the native EyeDropper API — hidden automatically on unsupported browsers. |
+| `modelValue` | `string \| null` |  | yes | Current color value bound via `v-model`. Accepts `#RRGGBB` and `#RRGGBBAA` (alpha) formats, or `null` for no value. |
+| `swatches` | `boolean \| string[][] \| undefined` |  |  | Controls swatches display: - `true` — show the built-in Material-palette swatches - `string[][]` — show custom swatches (each inner array = a column of shades) - `false` / omitted — no swatches section |
+
+## Events
+
+- `update:modelValue` — `(event: "update:modelValue", value: string): void`
+
+## Slots
+
+- None.
+
+## Exposed (template ref)
+
+- `el`: `HTMLDivElement \| null`
+
+## See Also
+
+- [BbColorPalette](./BbColorPalette.md) — Opens an anchored popover color palette for color picking interactions.
+- [BbColorInput](./BbColorInput.md) — Captures color values through input controls.

package/dist/ai/BbBaseDatePicker.md

@@ -0,0 +1,42 @@
+# BbBaseDatePicker
+
+## Agent Contract
+
+- Safety level: **Reference Only - Internal**
+- Group: **Reference Only - Base Primitive**
+- Description: Internal low-level date picker primitive.
+- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
+- Implementation source (only when the contract below is not enough): [source/BbBaseDatePicker.md](./source/BbBaseDatePicker.md)
+
+## v-model
+
+- `v-model` — type: `string \| string[] \| null`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `disabled` | `boolean \| undefined` |  |  | Disables the component. |
+| `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` | `1` |  | Defines the first day of the week with `0` meaning Sunday and `6` meaning Saturday. |
+| `floating` | `boolean \| undefined` |  |  | If true the date will have a format YYYY-MM-DD instead of the default ISO string. |
+| `id` | `string \| undefined` |  |  | The identifier of the component. |
+| `max` | `string \| undefined` |  |  | Maximum selectable date. |
+| `min` | `string \| undefined` |  |  | Minimum selectable date. |
+| `modelValue` | `string \| string[] \| null` |  | yes | Used by v-model. Can be null, a single string, or an array of strings based on whether a range or single date is needed. |
+| `multiple` | `boolean \| undefined` |  |  | Allows the selection of multiple items. |
+| `range` | `boolean \| undefined` |  |  | Selects a range of dates between two dates. It selects all of the days between start and end. |
+| `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
+| `selectable` | `((date: string) => boolean) \| undefined` |  |  | Function that accepts a date string and returns a boolean. Returning `false` means the date cannot be selected. |
+| `utc` | `boolean \| undefined` |  |  | Emits values as UTC ISO strings (`...Z`) instead of ISO strings carrying the local offset (`...+01:00`). Emission-only: incoming values are parsed identically either way, so the prop can be added or removed without touching stored values. I… |
+
+## Events
+
+- `update:modelValue` — `(event: "update:modelValue", value: string \| string[] \| null): void`
+
+## Slots
+
+- None.
+
+## Exposed (template ref)
+
+- `resetStatus`: `() => void`

package/dist/ai/BbBaseDatePickerInput.md

@@ -0,0 +1,73 @@
+# BbBaseDatePickerInput
+
+## Agent Contract
+
+- Safety level: **Reference Only - Internal**
+- Group: **Reference Only - Base Primitive**
+- Description: Internal low-level date-picker input primitive.
+- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
+- Implementation source (only when the contract below is not enough): [source/BbBaseDatePickerInput.md](./source/BbBaseDatePickerInput.md)
+
+## v-model
+
+- `v-model` — type: `string \| string[] \| null`
+- `v-model:time` — type: `string \| string[] \| null \| undefined`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `adaptive` | `boolean \| undefined` | `undefined` |  | On mobile the calendar opens inside a bottom off-canvas sheet instead of a floating popover, mirroring the adaptive behaviour of `BbPopover`/`BbSelectPopover`. When unset, falls back to the global `config.adaptive`. |
+| `ampm` | `boolean \| undefined` |  |  | 12-hour display with an AM/PM segment (requires `datetime`). Purely a field-composition concern: `modelValue` and the `time` model stay 24-hour regardless. Type `A`/`P` (or ArrowUp/Down) to set the meridiem. |
+| `append:icon` | `string \| undefined` |  |  | Name of the icon to render at the right hand side of the input. |
+| `ariaDescribedby` | `string \| undefined` |  |  | Additional description id(s) announced by assistive technologies. Usually provided by an outer input container to link hint/error text. |
+| `autocomplete` | `string \| undefined` | `"off"` |  | Browser autocomplete hint for the input. |
+| `autofocus` | `Booleanish \| undefined` |  |  | Focus the first text field automatically when the component mounts. |
+| `clearable` | `boolean \| undefined` |  |  | Displays a clear button whenever a value is present and the control is interactive. |
+| `compact` | `boolean \| undefined` |  |  | Applies the compact density styles to the control. |
+| `datetime` | `boolean \| undefined` |  |  | Adds time selection beside date selection: `HH:mm` segments in the text field (24-hour) and time columns under the calendar. A picked or typed date with a blank time commits at `00:00`. Non-floating values carry the time inside `modelValue`… |
+| `disableCalendar` | `boolean \| "mobile" \| "desktop" \| undefined` | `false` |  | Disables the calendar: hides the trigger button and prevents the popover from opening. Use `'desktop'` to disable it on desktop only (keyboard-first there, calendar-first on mobile — complementing `disableWriting: 'mobile'`) or `'mobile'` t… |
+| `disabled` | `boolean \| undefined` |  |  | Disables the input, calendar trigger, and popover. |
+| `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` | `false` |  | Controls whether manual typing is disabled inside the text fields. Use `'mobile'` to disable typing only on mobile, `'desktop'` to disable typing only on desktop. Applies to both single and range modes. |
+| `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` |  |  | Sets the first day of the week for the calendar (0 = Sunday, 6 = Saturday). |
+| `floating` | `boolean \| undefined` |  |  | Emit dates formatted as `YYYY-MM-DD` instead of ISO strings. |
+| `hasErrors` | `boolean \| undefined` |  |  | Marks the control as invalid, applying error styles and setting `aria-invalid`. |
+| `hasWarning` | `boolean \| undefined` |  |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
+| `id` | `string \| undefined` |  |  | Explicit id for the input element. Falls back to an auto-generated `bdpi-<uid>` value. |
+| `loading` | `boolean \| undefined` |  |  | Shows loading visuals on the input. |
+| `max` | `string \| undefined` |  |  | Maximum selectable date in `YYYY-MM-DD` format — or, with `datetime`, `YYYY-MM-DDTHH:mm` to tighten the boundary day to a minute. Values outside both patterns throw during setup to surface configuration mistakes. |
+| `min` | `string \| undefined` |  |  | Minimum selectable date in `YYYY-MM-DD` format — or, with `datetime`, `YYYY-MM-DDTHH:mm` to tighten the boundary day to a minute. Values outside both patterns throw during setup to surface configuration mistakes. |
+| `modelValue` | `string \| string[] \| null` |  | yes | v-model value. Use `null` for empty, a single string for single selection, or a two-element string array (`[start, end]`) when `range` is true. |
+| `name` | `string \| undefined` |  |  | Name attribute forwarded to the native inputs. In single mode fields are named `${name}-day`, `${name}-month`, `${name}-year`; in range mode they are prefixed with the segment (`${name}-start-day`, `${name}-end-day`, …). |
+| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile (e.g. `title`, `size`, `persistent`). |
+| `placeholder` | `string \| undefined` |  |  | Placeholder text displayed when no value is present. Defaults to the localized format hint (`baseDatePickerInput.dateFormatSingle` / `dateFormatRange` — e.g. `MM/DD/YYYY` for `en`, `GG/MM/AAAA` for `it`). |
+| `prepend:icon` | `string \| undefined` |  |  | Icon name rendered before the input field. |
+| `range` | `boolean \| undefined` |  |  | Enables range selection. When active, v-model expects a two-element array `[start, end]`. Users can still type into the start and end segments unless `disableWriting` disables typing. |
+| `readonly` | `boolean \| undefined` |  |  | Makes the text fields read-only and prevents opening the calendar. |
+| `required` | `boolean \| undefined` |  |  | Marks the inputs as required to the browser. |
+| `seconds` | `boolean \| undefined` |  |  | Adds the seconds segment (requires `datetime`). Without it, an incoming value carrying seconds displays truncated and is left untouched until the user commits an edit, at which point seconds zero out. |
+| `selectable` | `((date: string) => boolean) \| undefined` |  |  | Predicate invoked for each candidate date. Return `false` to disable selection for that value. |
+| `step` | `number \| undefined` |  |  | Minute granularity for the calendar's minute column and arrow stepping (requires `datetime`). Constrains what the component produces, never what it accepts: a typed off-grid value (e.g. `10:07` with `step: 15`) is emitted verbatim, and no c… |
+| `time` | `string \| string[] \| null \| undefined` |  |  | Companion model for the time part (`v-model:time`), always 24-hour `HH:mm` / `HH:mm:ss` regardless of display. With `floating` it is the only carrier of the time; otherwise it mirrors the time inside `modelValue` (same digits) and writing i… |
+| `transitionDuration` | `number \| undefined` |  |  | Transition duration, in milliseconds, for the popover appearance. |
+| `utc` | `boolean \| undefined` |  |  | Emits values as UTC ISO strings (`...Z`) instead of ISO strings carrying the local offset (`...+01:00`). Emission-only: incoming values are parsed identically either way, so the prop can be added or removed without touching stored values. F… |
+
+## Events
+
+- `active` — `(event: "active"): void`
+- `error` — `(event: "error", error: DatePickerInputError): void`
+- `focus` — `(event: "focus", event: FocusEvent): void`
+- `inactive` — `(event: "inactive"): void`
+- `update:modelValue` — `(event: "update:modelValue", value: string \| string[] \| null): void`
+- `update:time` — `(event: "update:time", value: string \| string[] \| null): void`
+
+## Slots
+
+- `append` — scope: `object` — Content rendered after the date fields, at the end of the inner container (before the calendar toggle button).
+- `append-outer` — scope: `object` — Content rendered after the entire input control, outside the input chrome.
+- `append:day` — scope: `{ first: boolean; highlighted: boolean; item: any; label: string; last: boolean; middle: boolean; selected: boolean; }` — Appends content below each calendar day.
+- `day` — scope: `{ first: boolean; highlighted: boolean; item: any; label: string; last: boolean; middle: boolean; selected: boolean; }` — Replaces the day button label inside each calendar day.
+- `prefix` — scope: `object` — Inline content rendered at the start of the input field area, before the date fields.
+- `prepend` — scope: `object` — Content rendered before the date fields, at the start of the inner container.
+- `prepend-outer` — scope: `object` — Content rendered before the entire input control, outside the input chrome.
+- `suffix` — scope: `object` — Inline content rendered at the end of the input field area, after the date fields.

package/dist/ai/BbBaseInputContainer.md

@@ -0,0 +1,48 @@
+# BbBaseInputContainer
+
+## Agent Contract
+
+- Safety level: **Reference Only - Internal**
+- Group: **Reference Only - Base Primitive**
+- Description: Internal wrapper for labels, hints, validation, and shared input layout.
+- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
+- Implementation source (only when the contract below is not enough): [source/BbBaseInputContainer.md](./source/BbBaseInputContainer.md)
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `clearable` | `boolean \| undefined` |  |  | Whether the inner control exposes a clear action. |
+| `compact` | `boolean \| undefined` |  |  | Apply the compact density variant to the container. |
+| `description` | `string \| undefined` |  |  | Always-visible descriptive text rendered below the label and above the input, in muted foreground color. When present, its id is exposed to the input slot via `ariaDescribedby` (together with the hint id). In `floating` label mode it render… |
+| `direction` | `InputDirection \| undefined` | `"vertical"` |  | Controls label/input layout. Accepts `'vertical'`, `'horizontal'`, `'auto'`, or a two-token ratio pattern such as `"xx xxxxx"` that sizes the label/input columns by token length. An unrecognized value warns and falls back to `'auto'`. |
+| `disabled` | `boolean \| undefined` |  |  | Whether the inner control is disabled. |
+| `errors` | `string \| string[] \| undefined` |  |  | Messages displayed beneath the input. Accepts a string or array; values are rendered one per line. |
+| `hasErrors` | `boolean \| undefined` |  |  | Forces the error state independently of `errors`, useful to pre-style the container. |
+| `hasValue` | `boolean \| undefined` |  |  | Whether the inner control currently contains a value. |
+| `hasWarning` | `boolean \| undefined` |  |  | Forces the warning state independently of `warnings`. Same chrome as errors but with `--bb-warn`; errors take priority when both are set. |
+| `hideLabel` | `boolean \| undefined` |  |  | Hide the visual label while keeping it available to assistive technology. |
+| `hint` | `string \| undefined` |  |  | Hint text rendered below the input. When present, its id is exposed to the input slot via `ariaDescribedby`. |
+| `id` | `string \| undefined` |  |  | Explicit id for the container and associated input. Falls back to an auto-generated id when omitted. |
+| `inputPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Horizontal alignment of the input column when direction is horizontal or custom. |
+| `label` | `string` |  | yes | Visible label text for the field. Also used to derive a fallback name. |
+| `labelMode` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Label rendering mode. |
+| `labelPosition` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Horizontal alignment for the label column. |
+| `labelTag` | `LabelTag \| undefined` | `"label"` |  | Element used for the label: `label` (default), `legend` inside a `fieldset` container, or `span` when the text must not steal the click because the control already carries its own label. |
+| `loading` | `boolean \| undefined` |  |  | Whether the inner control is in a loading state. |
+| `mobile` | `boolean \| undefined` |  |  | Whether the inner control is in mobile viewport mode. |
+| `name` | `string \| undefined` |  |  | Explicit name attribute forwarded to the input. When omitted, a slug derived from `label` is used. |
+| `readonly` | `boolean \| undefined` |  |  | Whether the inner control is readonly. |
+| `reverse` | `boolean \| undefined` | `false` |  | Swap the label and input columns. |
+| `showHint` | `boolean \| undefined` |  |  | Keep the hint permanently visible, regardless of focus. |
+| `tag` | `ContainerTag \| undefined` | `"span"` |  | Element used for the inner wrapper: `span` (default) to remain inline, `div` for a block wrapper, `fieldset` for grouped controls (pair it with `labelTag="legend"`), or `label` to make the whole wrapper activate the control. |
+| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages displayed beneath the input, in their own `aria-live` region. Accepts a string or array; values are rendered one per line, in `--bb-warn` amber. A non-empty list implies the warning state (mirroring how `errors` implies the… |
+
+## Events
+
+- None.
+
+## Slots
+
+- `input` — scope: `BaseInputContainerInputSlotProps` — The form control to render, positioned in the input column. Receives pre-computed wiring attributes so the inner input can be correctly associated with the label and hint.
+- `label` — scope: `BaseInputContainerLabelSlotProps` — Replaces the default label text. The outer label element and its `for` association are always rendered.

package/dist/ai/BbBaseNumberInput.md

@@ -0,0 +1,71 @@
+# BbBaseNumberInput
+
+## Agent Contract
+
+- Safety level: **Reference Only - Internal**
+- Group: **Reference Only - Base Primitive**
+- Description: Internal low-level numeric input primitive.
+- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
+- Implementation source (only when the contract below is not enough): [source/BbBaseNumberInput.md](./source/BbBaseNumberInput.md)
+
+## v-model
+
+- `v-model` — type: `string \| number \| null`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `append:icon` | `string \| undefined` |  |  | Name of the icon to render at the right hand side of the input. |
+| `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of descriptive elements announced by screen readers. |
+| `autocomplete` | `string \| undefined` | `"off"` |  | Browser autocomplete hint for the field. |
+| `autofocus` | `Booleanish \| undefined` |  |  | Focus the input automatically after mount. |
+| `clearable` | `boolean \| undefined` |  |  | Show a clear button whenever a value is present and the control is interactive. |
+| `compact` | `boolean \| undefined` |  |  | Apply the compact density variant. |
+| `disabled` | `boolean \| undefined` |  |  | Disable manual input and the exposed increase/decrease helpers. |
+| `hasErrors` | `boolean \| undefined` |  |  | Force the error state; also toggles `aria-invalid`. |
+| `hasWarning` | `boolean \| undefined` |  |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
+| `id` | `string \| undefined` |  |  | Explicit id forwarded to the native input. |
+| `loading` | `boolean \| undefined` |  |  | Display the loading state styles. |
+| `max` | `number \| undefined` | `Number.MAX_SAFE_INTEGER` |  | Upper bound for clamping user input and helper increments. |
+| `maxPrecision` | `number \| undefined` | `8` |  | Maximum number of decimal digits retained after processing. |
+| `min` | `number \| undefined` | `Number.MIN_SAFE_INTEGER` |  | Lower bound for clamping user input and helper decrements. |
+| `modelValue` | `string \| number \| null` |  | yes | v-model value. Accepts numbers, numeric strings, or null when empty. |
+| `name` | `string \| undefined` |  |  | Name attribute forwarded to the native input. |
+| `placeholder` | `string \| undefined` |  |  | Placeholder text when no value is present. |
+| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to render at the left hand side of the input. |
+| `readonly` | `boolean \| undefined` |  |  | Make the input read-only while keeping its value visible. |
+| `required` | `boolean \| undefined` |  |  | Mark the input as required for form validation. |
+| `step` | `number \| undefined` | `1` |  | Increment used by the `increase`/`decrease` helpers. Manual typing is never forced to this step. |
+
+## Events
+
+- `blur` — `(event: "blur", event: FocusEvent): void`
+- `change` — `(event: "change", event: Event): void`
+- `click` — `(event: "click", event: MouseEvent): void`
+- `compositionend` — `(event: "compositionend", event: CompositionEvent): void`
+- `compositionstart` — `(event: "compositionstart", event: CompositionEvent): void`
+- `decrease` — `(event: "decrease", value: number): void`
+- `focus` — `(event: "focus", event: FocusEvent): void`
+- `increase` — `(event: "increase", value: number): void`
+- `input` — `(event: "input", event: Event): void`
+- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
+- `keyup` — `(event: "keyup", event: KeyboardEvent): void`
+- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
+- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
+- `paste` — `(event: "paste", event: ClipboardEvent): void`
+- `update:modelValue` — `(event: "update:modelValue", value: number \| null): void`
+
+## Slots
+
+- `append` — scope: `BaseNumberInputStepSlotProps` — Content rendered after the number input, at the end of the inner container. Typically used to place increment/decrement buttons next to the input.
+- `append-outer` — scope: `BaseNumberInputStepSlotProps` — Content rendered after the entire input control, outside the input chrome.
+- `prefix` — scope: `BaseNumberInputStepSlotProps` — Inline content rendered at the start of the input field area, before the typed number.
+- `prepend` — scope: `BaseNumberInputStepSlotProps` — Content rendered before the number input, at the start of the inner container.
+- `prepend-outer` — scope: `BaseNumberInputStepSlotProps` — Content rendered before the entire input control, outside the input chrome.
+- `suffix` — scope: `BaseNumberInputStepSlotProps` — Inline content rendered at the end of the input field area, after the typed number.
+
+## Exposed (template ref)
+
+- `decrease`: `() => void`
+- `increase`: `() => void`

package/dist/ai/BbBaseRadio.md

@@ -0,0 +1,46 @@
+# BbBaseRadio
+
+## Agent Contract
+
+- Safety level: **Reference Only - Internal**
+- Group: **Reference Only - Base Primitive**
+- Description: Internal low-level radio primitive.
+- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
+- Implementation source (only when the contract below is not enough): [source/BbBaseRadio.md](./source/BbBaseRadio.md)
+
+## v-model
+
+- `v-model` — type: `any`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of descriptive elements associated with the radio. |
+| `autofocus` | `Booleanish \| undefined` |  |  | Focus the control automatically after mount. |
+| `checked` | `boolean \| undefined` | `undefined` |  | Force the radio into a checked state regardless of `modelValue`. |
+| `disabled` | `boolean \| undefined` |  |  | Disable the radio. When combined with `readonly`, the control is also disabled to mimic native behaviour. |
+| `hasErrors` | `boolean \| undefined` |  |  | Apply the error styling class. |
+| `hasWarning` | `boolean \| undefined` |  |  | Apply the warning styling class. Errors take priority when both are set. |
+| `id` | `string \| undefined` |  |  | Explicit id for the underlying input element. |
+| `modelValue` | `any` |  |  | Current v-model value used to determine checked state. |
+| `name` | `string \| undefined` |  | yes | Shared group name for the radio input (required to join options). |
+| `readonly` | `boolean \| undefined` |  |  | Treat the radio as read-only. Implemented by disabling the input while preserving styling hooks. |
+| `required` | `boolean \| undefined` |  |  | Mark the radio as required within its group. |
+| `value` | `any` |  | yes | Value emitted when the radio becomes checked. Accepts any serializable value. |
+
+## Events
+
+- `blur` — `(event: "blur", event: FocusEvent): void`
+- `change` — `(event: "change", event: Event): void`
+- `click` — `(event: "click", event: MouseEvent): void`
+- `focus` — `(event: "focus", event: FocusEvent): void`
+- `input` — `(event: "input", event: Event): void`
+- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
+- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
+- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
+- `update:modelValue` — `(event: "update:modelValue", value: any): void`
+
+## Slots
+
+- `icon` — scope: `BaseRadioIconSlotProps` — Replaces the default radio dot visual rendered inside the radio container.