bitboss-ui 3.0.0-beta.2 → 3.0.0-beta.21

package/dist/ai/BbSelect.md

@@ -128,9 +128,13 @@ markup needed:
   the field never shows amber while it has an error.
 - **Form participation**: `name` renders hidden inputs carrying the selection
   (one per value; non-string values are JSON-stringified), so the select posts
-  in a plain HTML form; `required` adds a visually-hidden sentinel input so
-  native constraint validation fires. `autocomplete` / `autofocus` forward to
-  the control.
+  in a plain HTML form. **`required` does NOT give you native constraint
+  validation**: the HTML spec bars `required` on `input[type=hidden]` from
+  constraint validation, so the browser will never block submission on an empty
+  select (`BbBaseSelect.vue:432` says so in its own comment). `required` is kept
+  for form introspection and for the asterisk. Gate submission with `errors` /
+  `has-errors`, or with the validated entrypoint. `autocomplete` / `autofocus`
+  forward to the control.
 - **Affixes**: `prepend:icon` / `append:icon` place icons in the control —
   `append:icon` replaces the default chevron (there is no `#chevron` slot).
 - **Value display**: `placeholder` shows when a _single-mode_ select is empty.
@@ -609,8 +613,10 @@ later responses don't include them — no need to merge them into every response
 `prefill` controls **when the first load happens**:
 
 - `'interaction'` (default) — on the first open.
-- `true` — immediately on mount, and during SSR (`onServerPrefetch`), so the
-  panel is warm on hydration.
+- `true` — immediately on mount, and during SSR **on hosts that can carry the
+  result to the client** (Nuxt does; see
+  [SSR prefill](./guides/ssr-prefill.md)), so the panel is warm on hydration.
+  Everywhere else the load happens on the client, right after mount.
 - `false` — **search-first**: nothing loads until the user types. Opening is not
   a search, so the panel opens empty and shows a _"search to begin"_ hint until
   the first query. Use it when the result set is too big or too costly to browse
@@ -1068,10 +1074,12 @@ const role = ref<string | null>(null);
 
 ### Custom option rows
 
-The `#option` slot replaces the default row rendering — use it for avatars,
-secondary text or metadata. It exposes the raw `item`, the resolved `text` and
-`value`, plus `selected` / `focused` / `disabled` / `loading` / `hasErrors`
-flags and the row `index`. Rows are fixed-height (the list is virtualized): if
+The `#option` slot replaces the row's **text** — use it for avatars, secondary
+text or metadata. It exposes the raw `item`, the resolved `text` and `value`,
+plus `selected` / `focused` / `disabled` / `loading` / `hasErrors` flags and the
+row `index`. The selection check is not yours to redraw: it renders outside the
+slot, so a custom row keeps it (`selected` is there for rows that want to show
+the state some _other_ way, not for drawing a second check). Rows are fixed-height (the list is virtualized): if
 your markup is taller than the default 28px (24px compact; 44px / 36px inside
 the adaptive sheet), set `item-height` to match — and `header-height` for
 grouped headers (defaults 32px / 24px compact; 36px / 32px in the sheet). The
@@ -1148,11 +1156,91 @@ const assignee = ref<string | null>(null);
 </script>
 ```
 
+### Custom chips
+
+In `multiple` mode each selection renders as a badge. The `#chip` slot replaces
+that badge outright — a colored label, an avatar plus a name, anything — and
+receives `{ item, text, value, disabled, deselect }`. `item` is the raw entry
+from `items` (where a per-selection color or avatar lives), `disabled` is `true`
+while the control is `disabled` or `readonly` (render no remove affordance —
+`deselect` refuses anyway), and `deselect` drops just this value from the model.
+
+Custom chips need none of the library's class names: the chips row supplies the
+spacing and keeps them from shrinking. The slot is not called in `comma` mode
+(there are no chips to replace) nor for the collapsed "+N" summary that appears
+once the chips outgrow the field — keep chips compact, or raise
+`max-selected-labels`.
+
+**Labels as colored chips**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
+		<BbSelect
+			v-model="tags"
+			clearable
+			item-text="label"
+			item-value="value"
+			:items="tagItems"
+			label="Labels"
+			multiple
+			placeholder="Add labels"
+		>
+			<template #option="{ item, text }">
+				<span class="flex w-full items-center gap-2">
+					<span
+						class="size-2 shrink-0 rounded-full"
+						:style="{ background: item.color }"
+					></span>
+					<span class="min-w-0 flex-1 truncate">{{ text }}</span>
+				</span>
+			</template>
+			<!-- The chip slot replaces the default badge for each selection. It
+			hands over the raw `item` (here: the label's own color), the resolved
+			`text` / `value`, a `disabled` flag that is true while the control is
+			disabled or readonly, and `deselect` — which drops just this value. -->
+			<template #chip="{ item, text, disabled, deselect }">
+				<BbBadge
+					:clearable="!disabled"
+					size="lg"
+					:style="{
+						'--bg': `color-mix(in oklab, ${item.color} 15%, transparent)`,
+						'--color': 'var(--bb-text)',
+					}"
+					@click:clear="deselect"
+				>
+					<span
+						class="size-2 rounded-full"
+						:style="{ background: item.color }"
+					></span>
+					{{ text }}
+				</BbBadge>
+			</template>
+		</BbSelect>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbBadge, BbSelect } from 'bitboss-ui';
+
+type Label = { label: string; value: string; color: string };
+
+const tagItems: Label[] = [
+	{ label: 'Bug', value: 'bug', color: '#ef4444' },
+	{ label: 'Enhancement', value: 'enhancement', color: '#0ea5e9' },
+	{ label: 'Documentation', value: 'documentation', color: '#8b5cf6' },
+	{ label: 'Good first issue', value: 'good-first-issue', color: '#22c55e' },
+];
+
+const tags = ref<string[]>(['bug']);
+</script>
+```
+
 ### Slots around the input
 
 Beyond the panel slots, the field itself is extensible:
 
-- `#label` replaces the label text; receives `{ text, hasErrors }`.
+- `#label` replaces the label text; receives `{ text, hasErrors, hasWarning }`.
 - `#prefix` / `#suffix` render inline adornments inside the field (no scope) —
   currency symbols, units.
 - `#prepend` / `#append` render inside the field wrapper, before/after the
@@ -1212,6 +1300,14 @@ Shipped behavior — never reimplement it:
   library default) — `direction="horizontal"` gives a label-beside-field row.
   Only `floating`/`inside` label modes force the vertical layout, since they
   embed the label in the field itself.
+- **A long `placeholder` or a long selected label never widens the control's
+  track.** The trigger is a button, not an `<input>`, so the placeholder is
+  real text rather than a paint-only `::placeholder` — but the field's minimum
+  size is capped so that text cannot become the floor of a grid or flex track.
+  Put a select with a paragraph-length placeholder in
+  `grid-template-columns: repeat(3, 1fr)` and you still get three equal
+  columns, with the text ellipsised inside its field. You do **not** need
+  `min-w-0` on the item or `minmax(0, 1fr)` on the track to get this.
 
 ### Adaptive mobile sheet
 
@@ -1243,9 +1339,13 @@ From the vite/nuxt plugin options:
 
 Platform notes:
 
-- **SSR / Nuxt**: `prefill: true` providers also run in `onServerPrefetch`, so
-  server-rendered pages hydrate with options loaded. Keep providers isomorphic
-  (no `window` access).
+- **SSR / Nuxt**: under `bitboss-ui/nuxt`, `prefill: true` providers run in
+  `onServerPrefetch` AND their result travels in the Nuxt payload, so the client
+  hydrates with the options already in hand and never re-requests them. Under any
+  other SSR host the provider does **not** run on the server at all — the server
+  emits the placeholder and the client loads on mount, which keeps hydration
+  clean. Keep providers isomorphic (no `window` access) and have them return
+  plain, serializable rows. See [SSR prefill](./guides/ssr-prefill.md).
 - **Plain HTML forms / Inertia form posts**: give the select a `name` — hidden
   inputs carry the values (JSON-stringified when not strings), and `required`
   participates in native validation.
@@ -1346,58 +1446,58 @@ Platform notes:
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `adaptive` | `boolean \| undefined` | `undefined` |  | When `true`, the options panel opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover; on desktop it stays a popover. When unset, falls back to the global `config.adaptive`. |
+| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | When `true`, the options panel opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover; on desktop it stays a popover. When unset, falls back to the global `config.adaptive`. |
 | `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
 | `autocomplete` | `string \| undefined` |  |  | Guides to the browser as to the type of information expected in the field. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
-| `clearable` | `boolean \| undefined` |  |  | Displays a clear button when the input has a value and is being interacted with. |
-| `comma` | `boolean \| undefined` |  |  | Sets the display model for selected values to a list of comma separated string. In this mode the user cannot deselect an option by pressing the close button. |
-| `compact` | `boolean \| undefined` |  |  | Sets the component in a compact mode. |
+| `clearable` | `boolean \| undefined` | `false` |  | Displays a clear button when the input has a value and is being interacted with. |
+| `comma` | `boolean \| undefined` | `false` |  | Sets the display model for selected values to a list of comma separated string. In this mode the user cannot deselect an option by pressing the close button. |
+| `compact` | `boolean \| undefined` | `false` |  | Sets the component in a compact mode. |
 | `dependencies` | `unknown[] \| undefined` |  |  | Defines an array of dependencies that will trigger actions in the component upon change. |
-| `depsDebounceTime` | `number \| undefined` |  |  | Timeout used to debounce response to changes to dependencies. |
+| `depsDebounceTime` | `number \| undefined` | `0` |  | Timeout used to debounce response to changes to dependencies. |
 | `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`). |
 | `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
-| `disabled` | `boolean \| undefined` |  |  | Disables the component. |
-| `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` |  |  | Controls whether the search input is shown inside the dropdown panel. Use `'mobile'` / `'desktop'` to hide it on that platform only. |
-| `enforceCoherence` | `boolean \| undefined` |  |  | If coherence is enforced the input cannot have a modelValue that is incoherent with its current items. modelValue will be reset upon incoherence. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
+| `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` | `false` |  | Controls whether the search input is shown inside the dropdown panel. Use `'mobile'` / `'desktop'` to hide it on that platform only. |
+| `enforceCoherence` | `boolean \| undefined` | `false` |  | If coherence is enforced the input cannot have a modelValue that is incoherent with its current items. modelValue will be reset upon incoherence. |
 | `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… |
-| `filterBy` | `string[] \| undefined` |  |  | Property paths used to filter options when the user types in the search input. When empty (default) options are matched against their display text. When non-empty the provided paths are searched instead of the display text. To disable filte… |
+| `filterBy` | `string[] \| undefined` | `[]` |  | Property paths used to filter options when the user types in the search input. When empty (default) options are matched against their display text. When non-empty the provided paths are searched instead of the display text. To disable filte… |
 | `groupBy` | `string \| ((item: T) => string \| number \| symbol) \| undefined` |  |  | Path to item property for grouping options. |
-| `hasErrors` | `boolean \| undefined` |  |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
-| `hasWarning` | `boolean \| undefined` |  |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
+| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
+| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
 | `headerHeight` | `number \| undefined` |  |  | Height of group headers in the listbox (px). Defaults to 32px (24px compact; 36px / 32px on mobile viewports). Only applies when `groupBy` is set. An explicit value wins on every viewport. |
-| `hideLabel` | `boolean \| undefined` |  |  | Visually hides the label of the input while maintaining accessibility. |
+| `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 identifier of the component. |
-| `itemHeight` | `number \| undefined` |  |  | Height of the options in the listbox (px). Defaults to 28px (24px compact; 44px / 36px on mobile viewports). An explicit value wins on every viewport. |
+| `itemHeight` | `number \| undefined` | `28` |  | Height of the options in the listbox (px). Defaults to 28px (24px compact; 44px / 36px on mobile viewports). An explicit value wins on every viewport. |
 | `items` | `T[] \| ((query: string, prefill: boolean, modelValue: any) => Promise<T[]>) \| ((query: string, prefill: boolean, modelValue: any) => T[])` |  | yes | Used to retrieve items; can be an array or a function. |
 | `itemText` | `ItemAccessor<T, string> \| undefined` |  |  | 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` |  |  | Defines a path that returns a property of the object to use as value or a function that returns any value. |
 | `label` | `string` |  | yes | Text content of the label of the element. |
 | `labelMode` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Label rendering mode. |
 | `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
-| `loading` | `boolean \| undefined` |  |  | Sets the component in a loading state, usually triggering some visual styles. |
+| `loading` | `boolean \| undefined` | `false` |  | Sets the component in a loading state, usually triggering some visual styles. |
 | `loadingText` | `string \| undefined` |  |  | String displayed while items are being loaded. |
 | `max` | `number \| undefined` |  |  | Maximum number of selectable items when the multiple flag is set. |
 | `maxSelectedLabels` | `number \| undefined` |  |  | Maximum number of labels shown before collapsing to a count summary. |
 | `modelValue` | `any` |  | yes | Used by v-model. Can be any serializable type. |
-| `modelValueDebounceTime` | `number \| undefined` |  |  | Timeout used to debounce response to changes to modelValue. |
-| `multiple` | `boolean \| undefined` |  |  | Allows the selection of multiple items. |
+| `modelValueDebounceTime` | `number \| undefined` | `0` |  | Timeout used to debounce response to changes to modelValue. |
+| `multiple` | `boolean \| undefined` | `false` |  | Allows the selection of multiple items. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
 | `noDataText` | `string \| undefined` |  |  | String displayed when there are no items to display. |
 | `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile. |
-| `persistentHint` | `boolean \| undefined` |  |  | Keeps the hint displayed. |
+| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
 | `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
-| `prefill` | `boolean \| "interaction" \| undefined` | `undefined` |  | Controls when items are pre-loaded. `'interaction'` loads on the first user interaction, `true` loads immediately on mount, `false` is *search-first*: with a provider, nothing is fetched until the user types — opening alone does not load, a… |
+| `prefill` | `boolean \| "interaction" \| undefined` | `'interaction'` |  | Controls when items are pre-loaded. `'interaction'` loads on the first user interaction, `true` loads immediately on mount, `false` is *search-first*: with a provider, nothing is fetched until the user types — opening alone does not load, a… |
 | `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
-| `queryDebounceTime` | `number \| undefined` |  |  | Time to wait when the user stops writing in the input before querying data. |
-| `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
-| `required` | `boolean \| undefined` |  |  | Sets the input as required. |
-| `reverse` | `boolean \| undefined` |  |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
+| `queryDebounceTime` | `number \| undefined` | `500` |  | Time to wait when the user stops writing in the input before querying data. |
+| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
+| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
+| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
 | `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. |
 | `selectedLabelsFn` | `((count: number) => string) \| undefined` |  |  | Function that returns a string to be displayed when the number of selected labels is greater than `maxSelectedLabels`. |
-| `stash` | `boolean \| undefined` |  |  | Adds a stash to accumulate selected values across searches. |
-| `transitionDuration` | `number \| undefined` |  |  | How long the transition has to last in milliseconds. |
+| `stash` | `boolean \| undefined` | `false` |  | Adds a stash to accumulate selected values across searches. |
+| `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds. |
 | `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |
 
 ## Events
@@ -1416,6 +1516,7 @@ Platform notes:
 
 - `append` — scope: `{ query: string; focus: () => void; close: () => Promise<void>; }` — Content appended inside the input field, after the value area.
 - `append-outer` — scope: `{ query: string; close: () => Promise<void>; }` — Content appended outside the input field wrapper.
+- `chip` — scope: `BbSelectChipSlotProps<T>` — Replaces the default badge rendered for each selection in `multiple` mode. Not called in `comma` mode, nor for the collapsed "+N" summary.
 - `footer` — scope: `BbSelectPanelSlotProps` — Content pinned to the bottom of the options panel, below the options list. Rendered in both the desktop popover and the adaptive sheet.
 - `group` — scope: `BbSelectGroupSlotProps<T>` — Replaces the default group header rendered above grouped options.
 - `header` — scope: `BbSelectPanelSlotProps` — Content pinned to the top of the options panel, above the search field. Rendered in both the desktop popover and the adaptive sheet.

package/dist/ai/BbSelectPopover.md

@@ -216,9 +216,11 @@ const reviewers = ref<string[]>(['ada', 'grace']);
 
 ### Custom option rows
 
-The `#option` slot replaces each row — exposing the raw `item`, resolved `text` /
-`value`, the row `index`, and `selected` / `focused` / `disabled` / `loading`
-flags — so options can carry avatars, badges or secondary metadata. Rows are
+The `#option` slot replaces each row's **text** — exposing the raw `item`,
+resolved `text` / `value`, the row `index`, and `selected` / `focused` /
+`disabled` / `loading` flags — so options can carry avatars, badges or secondary
+metadata. The selection check renders outside the slot and survives any custom
+markup, so there is no need to redraw it from `selected`. Rows are
 fixed-height and virtualized: if your markup is taller than the default 28px
 (24px compact; 44px / 36px inside the adaptive sheet), set `item-height` to
 match — and `header-height` for grouped headers (32px / 24px compact; 36px /
@@ -258,16 +260,12 @@ height wins everywhere.
 					}}</BbBadgeButton>
 				</BbBadge>
 			</template>
-			<template #option="{ item, text, selected }">
+			<!-- The slot replaces the row's TEXT only: the selection check keeps
+			rendering outside it, so custom rows never have to redraw it. -->
+			<template #option="{ item, text }">
 				<span class="flex w-full items-center gap-2">
 					<BbAvatar :alt="text" size="32">{{ item.initials }}</BbAvatar>
 					<span class="min-w-0 flex-1 truncate">{{ text }}</span>
-					<BbIcon
-						v-if="selected"
-						class="shrink-0 text-[color:var(--bb-text-muted)]"
-						icon="lucide:check"
-						:size="14"
-					/>
 				</span>
 			</template>
 		</BbSelectPopover>
@@ -275,13 +273,7 @@ height wins everywhere.
 </template>
 <script setup lang="ts">
 import { computed, ref } from 'vue';
-import {
-	BbAvatar,
-	BbBadge,
-	BbBadgeButton,
-	BbIcon,
-	BbSelectPopover,
-} from 'bitboss-ui';
+import { BbAvatar, BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
 
 type Person = { label: string; value: string; initials: string };
 
@@ -406,8 +398,9 @@ const destinationLabel = computed(
 ### Laziness, prefill and the trigger label
 
 `prefill` controls **when the first load happens**: `'interaction'` (default) on
-first open, `true` immediately on mount (and during SSR via `onServerPrefetch`),
-`false` **search-first** — nothing is fetched until the user types a query.
+first open, `true` immediately on mount (and during SSR via `onServerPrefetch`,
+but only on a host that can transfer the result — see
+[SSR prefill](./guides/ssr-prefill.md)), `false` **search-first** — nothing is fetched until the user types a query.
 Opening the panel is not a search, so it loads nothing; until the first query the
 list shows a _"search to begin"_ hint instead of "no data".
 
@@ -1179,8 +1172,10 @@ const variantFor = (value: Status | null): BadgeVariantType =>
 With `adaptive` (default: global `config.adaptive`, which is `true`), the panel
 opens as a bottom off-canvas sheet on mobile viewports (below
 `config.mobileMaxWidth`) instead of a floating popover — same search, options and
-`#header`/`#footer` slots, plus a representation of the current selection between
-them. The surface is **latched per open cycle**: a mid-open resize never swaps
+`#header`/`#footer` slots. In **multiple** mode the current selection also shows
+as removable chips above the search (so picks stay clearable when filtered or
+scrolled away); single select relies on the listbox checkmark and closes on pick.
+The surface is **latched per open cycle**: a mid-open resize never swaps
 popover ↔ sheet. `off-canvas-props` forwards extra `BbOffCanvas` props to the
 sheet (`size`, `draggable`, `fullscreen`, `stack`); `:adaptive="false"` keeps a
 floating popover everywhere.
@@ -1207,9 +1202,13 @@ floating popover everywhere.
 - **Global config** — `config.adaptive` (default for `adaptive`),
   `config.mobileMaxWidth` (the mobile threshold), `config.locale` (the search
   field's default accessible name and panel string defaults).
-- **SSR / Nuxt** — `prefill: true` providers also run in `onServerPrefetch`, so
-  server-rendered pages hydrate with options loaded; keep providers isomorphic
-  (no `window` access).
+- **SSR / Nuxt** — under `bitboss-ui/nuxt`, `prefill: true` providers run in
+  `onServerPrefetch` and their result rides the Nuxt payload, so the client
+  hydrates with options already loaded and does not fetch again. On other SSR
+  hosts the provider stays client-side and the server renders the placeholder —
+  deliberately, since server markup the client cannot rebuild is a hydration
+  mismatch. Keep providers isomorphic (no `window` access) and returning plain
+  rows. See [SSR prefill](./guides/ssr-prefill.md).
 
 ### Works well with
 
@@ -1330,36 +1329,36 @@ floating popover everywhere.
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `activator` | `Record<string, any> \| HTMLElement \| null \| undefined` |  |  | External activator element or component ref. When provided, the activator slot is not rendered and event listeners are attached programmatically to the referenced element. |
-| `adaptive` | `boolean \| undefined` | `undefined` |  | When `true`, the panel opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover; on desktop it stays a popover. The sheet reuses the same search field and options list, adding a representation of the current sele… |
+| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | When `true`, the panel opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover; on desktop it stays a popover. The sheet reuses the same search field and options list, adding a representation of the current sele… |
 | `anchor` | `Record<string, any> \| HTMLElement \| null \| undefined` | `null` |  | Override the element used for popover positioning and width measurement. Useful when the focusable activator is narrower than its visual container (e.g. a button inside a wrapper). Falls back to `activatorEl` when omitted. |
 | `ariaDescribedby` | `string \| string[] \| undefined` |  |  | Space-separated IDREF(s) that describe this field for assistive technologies. Accepts either a string or array of ids. |
 | `ariaInvalid` | `boolean \| undefined` | `undefined` |  | Explicit invalid state for accessibility semantics. Falls back to `hasErrors` when not provided. |
 | `autocomplete` | `string \| undefined` | `"off"` |  | Browser autocomplete hint for the popover search input. |
 | `boundary` | `string \| Record<string, any> \| HTMLElement \| null \| undefined` |  |  | Constrains the popover to a specific boundary element. |
-| `clearable` | `boolean \| undefined` |  |  | Shows a clear button inside the search field's icon stack: it takes the lens' place on hover/focus while there is a query or selection to clear, and resets both. Off by default. Leave it off when the component is wrapped by a control that a… |
-| `compact` | `boolean \| undefined` |  |  | Apply the compact density variant. |
+| `clearable` | `boolean \| undefined` | `false` |  | Shows a clear button inside the search field's icon stack: it takes the lens' place on hover/focus while there is a query or selection to clear, and resets both. Off by default. Leave it off when the component is wrapped by a control that a… |
+| `compact` | `boolean \| undefined` | `false` |  | Apply the compact density variant. |
 | `dependencies` | `unknown[] \| undefined` | `[]` |  | Additional dependencies that trigger item reloading when changed. |
 | `depsDebounceTime` | `number \| undefined` | `0` |  | Debounce delay (ms) for dependency-triggered reloads. |
-| `disabled` | `boolean \| undefined` |  |  | Disables the component. |
-| `disableFlip` | `boolean \| undefined` |  |  | Disables the automatic flip to the opposite side when the popover would overflow (flipping is on by default). |
-| `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` |  |  | Controls whether the search input is shown inside the popover panel. Use `'mobile'` to hide the search input on mobile, `'desktop'` to hide it on desktop. |
-| `enforceCoherence` | `boolean \| undefined` |  |  | Reset modelValue to `null` or empty array if it no longer matches available items. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
+| `disableFlip` | `boolean \| undefined` | `false` |  | Disables the automatic flip to the opposite side when the popover would overflow (flipping is on by default). |
+| `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` | `false` |  | Controls whether the search input is shown inside the popover panel. Use `'mobile'` to hide the search input on mobile, `'desktop'` to hide it on desktop. |
+| `enforceCoherence` | `boolean \| undefined` | `false` |  | Reset modelValue to `null` or empty array if it no longer matches available items. |
 | `filterBy` | `string[] \| undefined` | `[]` |  | Property paths used to filter options when the user types in the search input. When empty (default) options are matched against their display text. When non-empty the provided paths are searched instead of the display text. To disable filte… |
 | `groupBy` | `string \| ((item: Item) => string \| number \| symbol) \| undefined` |  |  | Path to item property for grouping options. |
-| `hasErrors` | `boolean \| undefined` |  |  | Marks the component as being in error state. |
-| `hasWarning` | `boolean \| undefined` |  |  | Marks the component as being in a warning state. Visually mirrors `hasErrors` but uses `--bb-warn` chrome; errors take priority when both are set. |
+| `hasErrors` | `boolean \| undefined` | `false` |  | Marks the component as being in error state. |
+| `hasWarning` | `boolean \| undefined` | `false` |  | Marks the component as being in a warning state. Visually mirrors `hasErrors` but uses `--bb-warn` chrome; errors take priority when both are set. |
 | `headerHeight` | `number \| undefined` |  |  | Height of group headers in the listbox (px). Defaults to 32px (24px compact; 36px / 32px on mobile viewports). Only applies when `groupBy` is set. An explicit value wins on every viewport. |
 | `id` | `string \| undefined` |  |  | Explicit id for the component. Used to generate ids for listbox and options. |
-| `itemHeight` | `number \| undefined` |  |  | Height of the options in the listbox (px). Defaults to 28px (24px compact; 44px / 36px on mobile viewports). An explicit value wins on every viewport. |
-| `items` | `Item[] \| ((query: string, prefill: boolean, modelValue: any) => Promise<Item[]>) \| ((query: string, prefill: boolean, modelValue: any) => Item[])` |  | yes | Array of items or function to load them asynchronously. Functions receive `(query, prefill, modelValue)` and can return a promise. `modelValue` is the raw v-model: an array in `multiple` mode, the raw model value (possibly `null`) in single… |
+| `itemHeight` | `number \| undefined` | `28` |  | Height of the options in the listbox (px). Defaults to 28px (24px compact; 44px / 36px on mobile viewports). An explicit value wins on every viewport. |
+| `items` | `Item[] \| ((query: string, prefill: boolean, modelValue: any) => Promise<Item[]>) \| ((query: string, prefill: boolean, modelValue: any) => Item[])` | `[]` | yes | Array of items or function to load them asynchronously. Functions receive `(query, prefill, modelValue)` and can return a promise. `modelValue` is the raw v-model: an array in `multiple` mode, the raw model value (possibly `null`) in single… |
 | `itemText` | `ItemAccessor<Item, string> \| undefined` |  |  | Path to item property for display text or function to extract it. |
 | `itemValue` | `ItemAccessor<Item> \| undefined` |  |  | Path to item property for value or function to extract it. |
-| `loading` | `boolean \| undefined` |  |  | Display the loading state styles. |
+| `loading` | `boolean \| undefined` | `false` |  | Display the loading state styles. |
 | `loadingText` | `string \| undefined` |  |  | Message shown while items are being loaded. |
 | `max` | `number \| undefined` | `Infinity` |  | Maximum number of selectable items (limits selection when `multiple` is true). |
 | `modelValue` | `any` |  | yes | v-model value. Single value for single select, array for multiple select. |
 | `modelValueDebounceTime` | `number \| undefined` | `0` |  | Debounce delay (ms) for modelValue change handling. |
-| `multiple` | `boolean \| undefined` |  |  | Enable multiple item selection. When true, modelValue must be an array. |
+| `multiple` | `boolean \| undefined` | `false` |  | Enable multiple item selection. When true, modelValue must be an array. |
 | `noDataText` | `string \| undefined` |  |  | Message displayed when no items are available. |
 | `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile (e.g. `size`, `draggable`, `fullscreen`, `stack`). |
 | `offset` | `number \| undefined` | `4` |  | Distance (px) between the activator and the popover. |
@@ -1367,11 +1366,11 @@ floating popover everywhere.
 | `placement` | `Placement \| undefined` | `"bottom"` |  | Floating placement of the popover. |
 | `prefill` | `boolean \| "interaction" \| undefined` | `"interaction"` |  | Controls when items are pre-loaded. `'interaction'` loads on the first user interaction (opening the popover), `true` loads immediately on mount (and during SSR via `onServerPrefetch`), `false` is *search-first*: nothing is fetched until th… |
 | `queryDebounceTime` | `number \| undefined` | `500` |  | Debounce delay (ms) before triggering search queries after user input stops. |
-| `readonly` | `boolean \| undefined` |  |  | Prevents opening the popover while keeping the activator accessible. |
-| `searchInputAriaLabel` | `string \| undefined` |  |  | Accessible label used by the search input rendered inside the popover. Falls back to the localized `select.searchLabel` key when omitted. |
+| `readonly` | `boolean \| undefined` | `false` |  | Prevents opening the popover while keeping the activator accessible. |
+| `searchInputAriaLabel` | `string \| undefined` | ``t('select.searchLabel')` (`'Search options'`)` |  | Accessible label used by the search input rendered inside the popover. Falls back to the localized `select.searchLabel` key when omitted. |
 | `selectable` | `boolean \| ((item: Item) => 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. |
-| `stash` | `boolean \| undefined` |  |  | Accumulate selected items across searches instead of replacing them. |
-| `transitionDuration` | `number \| undefined` | `transitions.medium` |  | Transition duration (ms) for popover show/hide animations. |
+| `stash` | `boolean \| undefined` | `false` |  | Accumulate selected items across searches instead of replacing them. |
+| `transitionDuration` | `number \| undefined` | `250` |  | Transition duration (ms) for popover show/hide animations. |
 | `width` | `string \| number \| undefined` | `"200"` |  | Width of the popover in pixels, percentage, or `'auto'`. A bare number is read as pixels — the default is the string `'200'`, not the number `200`. |
 
 ## Events

package/dist/ai/BbSlider.md

@@ -183,10 +183,16 @@ const volume = ref(40);
 
 ### Discrete steps with ticks
 
-`ticks` marks every step. Add `disable-thumb-translate` so the thumb sits exactly
-over each tick instead of being nudged to stay centred — the two pair naturally
-when you want a stepped, notched slider. The `tick` slot (`{ value, percent,
-active }`) replaces each mark if you want custom notches or per-step labels.
+`ticks` lays out one evenly-spaced slot per step. **You draw the mark**: the
+library positions the tick elements but ships no default notch —
+`.bb-base-slider__tick` carries only `position: relative`, and the `tick` slot
+has no fallback content, so `ticks` on its own renders empty spans and looks
+like nothing happened. Fill the `tick` slot (`{ value, percent, active }`) with
+your notch or per-step label, or style `.bb-base-slider__tick` yourself.
+
+Add `disable-thumb-translate` so the thumb sits exactly over each tick instead
+of being nudged to stay centred — the two pair naturally when you want a
+stepped, notched slider.
 
 **Stepped slider with ticks**
 
@@ -309,8 +315,13 @@ const limit = ref<number | null>(200);
 - `label` is required and names the slider; `hide-label` keeps it for assistive
   tech only.
 - `label-mode` is `'outside'` (default) or `'inside'`. `'floating'` is **not
-  supported and throws at runtime** — a slider has no empty/filled state for the
-  label to float against.
+  supported** — a slider has no empty/filled state for the label to float
+  against — and it is no longer in the type, so a typed template cannot write
+  it. It does not throw: an explicit `'floating'` from untyped code warns in
+  dev and falls back to `'outside'` (`resolveEnumProp`, the library-wide policy
+  that a bad enum token is cosmetic, never fatal). A plugin-level
+  `defaultInputLabelMode: 'floating'` degrades to `'outside'` **silently** —
+  the consumer made no per-slider choice, so there is nothing to warn about.
 - `direction` (`'horizontal'`, `'vertical'`, `'auto'`, or a pattern like
   `'xx xxxxxx'`), `reverse`, and `label-position` arrange the label against the
   track, exactly as on the other inputs.
@@ -416,11 +427,15 @@ Works well with:
 
 ### Gotchas and anti-patterns
 
-- Don't bind a scalar with `range` (or an array without it) — the mode and the
-  `modelValue` shape must match, or it throws at mount.
+- Don't bind a scalar with `range` — that one throws at mount
+  (`BbBaseSlider.vue:249`). The mirror case is worse because it is **quiet**:
+  an array **without** `range` renders a single thumb and silently reads
+  `head()`, so the second value is dropped with no warning. Keep the mode and
+  the `modelValue` shape in step in both directions.
 - Don't expect `increase`/`decrease` to work in range mode; they are single-value
   only. Drive range thumbs with the keyboard or pointer.
-- Don't set `label-mode="floating"` — it throws. Use `'outside'` or `'inside'`.
+- Don't set `label-mode="floating"` — it is not in the type, and at runtime it
+  warns and falls back to `'outside'`. Use `'outside'` or `'inside'`.
 - Don't rely on a slider for exact numbers — steps finer than `0.01` round away
   unless you raise `max-precision` to match. Use `BbNumberInput` when the
   precise figure is the point.
@@ -455,32 +470,32 @@ Works well with:
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
-| `compact` | `boolean \| undefined` |  |  | Set the component in compact mode. |
+| `compact` | `boolean \| undefined` | `false` |  | Set the component in compact mode. |
 | `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`). |
 | `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
-| `disabled` | `boolean \| undefined` |  |  | Disables the component. |
-| `disableThumbTranslate` | `boolean \| undefined` |  |  | Disables the proportional thumb translation that keeps the thumb on track (enabled by default). Set it when displaying ticks so they align with less effort. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
+| `disableThumbTranslate` | `boolean \| undefined` | `false` |  | Disables the proportional thumb translation that keeps the thumb on track (enabled by default). Set it when displaying ticks so they align with less effort. |
 | `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… |
-| `hasErrors` | `boolean \| undefined` |  |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
-| `hasWarning` | `boolean \| undefined` |  |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
-| `hideLabel` | `boolean \| undefined` |  |  | Visually hides the label of the input while maintaining accessibility. |
+| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
+| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
+| `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 identifier of the component. |
 | `label` | `string` |  | yes | Text content of the label of the element. |
 | `labelMode` | `"outside" \| "inside" \| undefined` |  |  | Label rendering mode. Sliders do not support `floating` labels. |
 | `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
 | `max` | `number \| undefined` |  |  | Maximum value cap. |
-| `maxPrecision` | `number \| undefined` |  |  | Maximum decimal places to retain in emitted values. |
+| `maxPrecision` | `number \| undefined` | `2` |  | Maximum decimal places to retain in emitted values. |
 | `min` | `number \| undefined` |  |  | Minimum value cap. |
 | `modelValue` | `number \| number[] \| null` |  | yes | Used by v-model. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
-| `persistentHint` | `boolean \| undefined` |  |  | Keeps the hint displayed. |
-| `range` | `boolean \| undefined` |  |  | Set the input as range. modelValue must be an array. |
-| `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
-| `required` | `boolean \| undefined` |  |  | Sets the input as required. |
-| `reverse` | `boolean \| undefined` |  |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
+| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
+| `range` | `boolean \| undefined` | `false` |  | Set the input as range. modelValue must be an array. |
+| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
+| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
+| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
 | `step` | `number \| undefined` |  |  | The step attribute specifies the granularity that the value must adhere to. |
-| `ticks` | `boolean \| undefined` |  |  | Displays ticks on step. |
+| `ticks` | `boolean \| undefined` | `false` |  | Displays ticks on step. |
 | `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |
 
 ## Events

package/dist/ai/BbSmoothHeight.md

@@ -497,7 +497,7 @@ const expanded = ref(false);
 | `resizeOptions` | `ResizeObserverOptions \| undefined` |  |  | Options to pass to the ResizeObserver. |
 | `strategy` | `"resize" \| "mutation" \| undefined` | `"resize"` |  | Define which strategy to use. By default `'resize'` is used, which means the component will update on resizing. You can also define `'mutation'` to use a MutationObserver. |
 | `tag` | `LayoutTag \| undefined` | `"div"` |  | Element rendered as the component's wrapper. |
-| `transitionDuration` | `number \| undefined` | `transitions.medium` |  | How long the transition has to last in milliseconds |
+| `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds |
 
 ## Events