bitboss-ui 3.0.0-beta.10 → 3.0.0-beta.14

package/dist/ai/BbBaseSelect.md

@@ -76,6 +76,7 @@
 
 - `append` — scope: `BaseSelectActivatorSlotProps`
 - `append-outer` — scope: `BaseSelectOuterSlotProps`
+- `chip` — scope: `BaseSelectChipSlotProps<Item>` — Replaces the default badge rendered for each selection in `multiple` mode.
 - `footer` — scope: `BaseSelectPanelSlotProps` — Content pinned to the bottom of the panel, below the options list.
 - `group` — scope: `BaseSelectGroupSlotProps<Item>`
 - `header` — scope: `BaseSelectPanelSlotProps` — Content pinned to the top of the panel, above the search field.

package/dist/ai/BbSelect.md

@@ -1068,10 +1068,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,6 +1150,86 @@ 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:
@@ -1424,6 +1506,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 };
 

package/dist/ai/BbTable.md

@@ -31,12 +31,14 @@ that state to your data source (client-side or via `dependencies`-driven
 refetch). This keeps it equally at home in a client-only screen and a
 server-paginated one.
 
-**`BbTable` ships no client-side virtualization or windowing** — every row you
-hand it in `items` mounts to the DOM, always. A few hundred rows is fine for a
-client-only screen. Past roughly 1,000 rows, don't ship the whole dataset to
-the browser: page it — feed `BbTable` the current slice as `items` and pass
-`page` / `per-page` / `total-items` (see § Pagination) so the server, not the
-DOM, holds the rest.
+**Every row in `items` mounts to the DOM unless you say `virtual`.** A few
+hundred rows is fine for a client-only screen. Past roughly 1,000 rows,
+either page it — feed `BbTable` the current slice as `items` and pass `page`
+/ `per-page` / `total-items` (see § Pagination) so the server, not the DOM,
+holds the rest — or, when the whole dataset legitimately lives in the
+browser (local filtering, a spreadsheet-shaped tool), add `virtual` and let
+the table window its rows (see § Virtual rows). The two compose: a large
+page can be windowed.
 
 ### Columns: the full grammar
 
@@ -2490,6 +2492,107 @@ your wrapper actually sits on before sprinkling `min-width: 0` everywhere.)
 </div>
 ```
 
+### Virtual rows
+
+`virtual` windows the body: only the rows in the vertical scrollport (plus a
+few on each side) are mounted, and two spacer rows hold the scrollport at the
+full list height, so 5,000 or 50,000 rows scroll at the cost of a few dozen.
+Everything else is the same table — the rows stay in flow in the grid, so the
+stuck header, `fixed-columns`, nested tables, selection, highlight and the
+keyboard grammar work untouched. One prop, no knobs.
+
+- **Give it a scroller.** Bound the table's height (`max-height` / `height`
+  on the table, or a flex item with `min-height: 0`) and the table itself
+  scrolls its rows; left unbounded it grows with the page and the page (or
+  the nearest scrolling ancestor) is the scroller. `virtual` implies a stuck
+  header — a windowed body without column names is a scroller, not a table.
+- **Columns are sized once.** A windowed body only ever holds a few rows, so
+  `auto` tracks would move as rows come and go. The first rendered batch is
+  measured and its widths become floors (`minmax(px, 1fr)`): they still share
+  surplus, later rows never widen them — and the cells of those columns are
+  single-line and **clip with an ellipsis** (like a resized column) so a
+  longer value that shows up later never spills into its neighbour. Want a
+  column to wrap (prose, notes)? Declare a `width` on it: a declared width
+  wins as always and keeps wrapping. A resize overrides as always, and an
+  empty→non-empty transition (a refetch) re-measures from the new first
+  batch.
+- **A fast wheel never shows blank space.** A band of skeleton rows is kept
+  rendered beyond the window on both sides (cheap: empty cells at the
+  measured row height), so a wheel that the compositor scrolls ahead of the
+  main thread reveals skeletons, not blank spacer, and they turn into real
+  rows as the window reaches them. While the scroll is fast, rows never
+  mounted before stay skeletons and are swapped for real rows as soon as
+  it slows; rows you have already seen stay real. A moderate scroll never
+  sees a skeleton.
+- **Dynamic heights are fine.** Every mounted row is measured (wrapping
+  cells, a "show more", an expand row that opens a nested table three levels
+  deep), measurements are cached by row so a row seen once stays right, and a
+  height change _above_ the viewport moves the scroll offset with it so what
+  you are reading does not jump.
+- **Focus is never lost to an unmount.** The row (or expand row) that owns
+  focus stays mounted however far it scrolls — a control inside a nested
+  table included — and is released on blur. Arrow keys, Home/End and
+  PageUp/PageDown work across the whole list (the target row is scrolled in,
+  mounted, then focused).
+- **Nested tables are not windowed.** A nested table inside an expand row is
+  one tall row to the virtualizer; give a huge nested dataset its own page.
+  `virtual` is ignored on a table that inherits its widths, and under a
+  `#tbody` slot.
+- **Rows keep their absolute position for AT** (`aria-rowcount` /
+  `aria-rowindex`), page or no page — a virtual table is one page unless you
+  say otherwise.
+
+**5,000 rows in a 320px scroller**
+
+```vue
+<template>
+	<!-- Bounding the table's height is what makes it the scroller of its own
+	     rows; `virtual` windows them and implies the stuck header. -->
+	<div
+		class="max-w-2xl overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+	>
+		<BbTable
+			caption="Ledger"
+			class="max-h-80"
+			:columns="columns"
+			compact
+			:fixed-columns="[0]"
+			item-value="id"
+			:items="rows"
+			virtual
+		/>
+	</div>
+</template>
+<script setup lang="ts">
+import { BbTable } from 'bitboss-ui';
+import type { BbTableColumn } from 'bitboss-ui';
+
+type Entry = {
+	id: number;
+	number: string;
+	client: string;
+	issued: string;
+	amount: string;
+};
+
+const columns: Array<BbTableColumn<Entry>> = [
+	{ key: 'number', label: 'Invoice' },
+	{ key: 'client', label: 'Client' },
+	{ key: 'issued', label: 'Issued' },
+	{ key: 'amount', label: 'Amount', align: 'right' },
+];
+
+const clients = ['Northwind Traders', 'Globex', 'Initech', 'Umbrella', 'Hooli'];
+const rows: Entry[] = Array.from({ length: 5000 }, (_, i) => ({
+	id: i,
+	number: `INV-${10000 + i}`,
+	client: clients[i % clients.length],
+	issued: `2026-${String(1 + (i % 12)).padStart(2, '0')}-${String(1 + (i % 28)).padStart(2, '0')}`,
+	amount: `€${((i * 37) % 9000) + 100}`,
+}));
+</script>
+```
+
 ### Narrow screens: hide columns, don't scroll everything
 
 An ops table with ten columns is unusable on a phone as a horizontal scroller —
@@ -2551,6 +2654,9 @@ through element names, which match nothing:
 | focused header | `.bb-table-header[data-column-key]:focus-visible` (`reorderable` only; inset ring, the header row is one roving tab stop)  | `columnheader`                            |
 | dragged column | `.bb-table-header--dragging` on the header; `.bb-table__head--dragging` on the head group during a drag                    | —                                         |
 | clipped header | `.bb-table-header--clip` (the track is a length or an equal split, so the label ellipsizes instead of flooring the column) | `columnheader`                            |
+| virtual table  | `.bb-table--virtual` on the container (`overflow: auto`, the scroller once its height is bounded)                          | —                                         |
+| spacer row     | `.bb-table-spacer__row` (a `virtual` body's stand-in for unmounted rows, `aria-hidden`; never style its height)            | — (`aria-hidden`)                         |
+| skeleton row   | `.bb-table-placeholder__row` > `.bb-table-placeholder__cell` (a `virtual` body's skeleton band and fast-scroll stand-in)   | `row` > `cell` (`aria-hidden`)            |
 | drag chip      | `.bb-table-column-ghost` (a `popover="manual"` in the top layer; paints `--bb-panel`, not the table's `--bg`)              | — (`aria-hidden`)                         |
 | caption        | `.bb-table-caption` (before the root, `aria-labelledby`)                                                                   | —                                         |
 
@@ -2817,6 +2923,7 @@ reader.
 | `totalItems` | `string \| number \| undefined` |  |  | Total number of items there is. Also flows into the shared table context, where a `BbPagination` paired through `id` derives its page count from it. When omitted, an array `items` table infers it from `items.length`; an explicit value (or a… |
 | `totalPages` | `string \| number \| undefined` |  |  | Seeds the page count shown by a `BbPagination` paired through `id`. A shortcut for when the server reports a page count rather than a row count: the table renders nothing from it, it only flows into the shared table context. A known total a… |
 | `unselectedItems` | `any[] \| undefined` | `[]` |  | Items that are not selected. |
+| `virtual` | `boolean \| undefined` |  |  | Windows the body: only the rows in (and just around) the vertical scrollport are mounted, so a client-side dataset of any size scrolls at a constant cost. The table itself is the scroller as soon as you bound its height (`max-height` / `hei… |
 
 ## Events
 

package/dist/ai/changelog.json

@@ -1,7 +1,7 @@
 {
 	"schemaVersion": 1,
 	"library": "bitboss-ui",
-	"version": "3.0.0-beta.10",
+	"version": "3.0.0-beta.14",
 	"upgrade": "v2-to-v3",
 	"guide": "ai/guides/migration/v2-to-v3.md",
 	"summary": {

package/dist/ai/components.json

@@ -1,8 +1,8 @@
 {
 	"schemaVersion": 1,
 	"library": "bitboss-ui",
-	"version": "3.0.0-beta.10",
-	"generatedAt": "2026-08-27T13:52:59.543Z",
+	"version": "3.0.0-beta.14",
+	"generatedAt": "2026-08-28T14:01:44.030Z",
 	"composables": [
 		{
 			"name": "useBbConfig",
@@ -3506,6 +3506,11 @@
 					"name": "append-outer",
 					"type": "BaseSelectOuterSlotProps"
 				},
+				{
+					"name": "chip",
+					"type": "BaseSelectChipSlotProps<Item>",
+					"description": "Replaces the default badge rendered for each selection in `multiple` mode."
+				},
 				{
 					"name": "footer",
 					"type": "BaseSelectPanelSlotProps",
@@ -10923,6 +10928,11 @@
 					"type": "{ query: string; close: () => Promise<void>; }",
 					"description": "Content appended outside the input field wrapper."
 				},
+				{
+					"name": "chip",
+					"type": "BbSelectChipSlotProps<T>",
+					"description": "Replaces the default badge rendered for each selection in `multiple` mode.\nNot called in `comma` mode, nor for the collapsed \"+N\" summary."
+				},
 				{
 					"name": "footer",
 					"type": "BbSelectPanelSlotProps",
@@ -12894,6 +12904,12 @@
 					"required": false,
 					"default": "[]",
 					"description": "Items that are not selected."
+				},
+				{
+					"name": "virtual",
+					"type": "boolean | undefined",
+					"required": false,
+					"description": "Windows the body: only the rows in (and just around) the vertical\nscrollport are mounted, so a client-side dataset of any size scrolls at\na constant cost. The table itself is the scroller as soon as you bound\nits height (`max-height` / `height`, or a flex item with\n`min-height: 0`); left unbounded, the nearest scrolling ancestor or the\npage scrolls it. The header sticks to that scroller. Column widths are\nmeasured once from the first rendered batch and then hold — later rows\nnever widen them. Expand rows and nested tables stay fully rendered\ninside their row (a nested table is never windowed); the row that owns\nfocus stays mounted even when scrolled out of view. Ignored by a table\nthat inherits its widths from a parent, and under a `#tbody` slot."
 				}
 			],
 			"events": [

package/dist/ai/source/BbBadge.md

@@ -19,7 +19,17 @@
 		The append icon joins it here so the two can share the hover swap; on a
 		non-clearable badge it renders inside the body instead. -->
 		<span v-if="props.clearable" class="bb-badge__trailing">
-			<BadgeAppendIcon v-if="!props.icon" />
+			<template v-if="!props.icon">
+				<BbSpinner
+					v-if="props.loading && spinnerTrails()"
+					class="bb-badge__append-icon"
+				/>
+				<BbIcon
+					v-else-if="props['append:icon']"
+					class="bb-badge__append-icon"
+					:icon="props['append:icon']"
+				/>
+			</template>
 			<button
 				:id="`${badgeId}__clear`"
 				:aria-label="props.clearableLabel || t('badge.clearLabel').value"
@@ -45,7 +55,7 @@ import { useLogger } from '@/composables/useLogger';
 import { removedPropsFor } from '@/deprecation/removedProps';
 import { warnRemovedAttrs } from '@/utilities/functions/warnRemovedAttrs';
 import BbIcon from '../BbIcon/BbIcon.vue';
-import BadgeAppendIcon from './BadgeAppendIcon.vue';
+import BbSpinner from '../BbSpinner/BbSpinner.vue';
 import BadgeBodyContent from './BadgeBodyContent.vue';
 import BbBadgeButton from './BbBadgeButton.vue';
 import { provideBadgeHost } from './badgeButtonContext';
@@ -80,9 +90,7 @@ const normalizedSize = computed(() => {
 });
 
 /** The spinner overlays the append slot only when the append icon is the sole icon. */
-const spinnerTrails = computed(
-	() => !!props['append:icon'] && !props['prepend:icon']
-);
+const spinnerTrails = () => !!props['append:icon'] && !props['prepend:icon'];
 
 /* ── BbBadgeButton detection ─────────────────────────────── */
 
@@ -106,15 +114,46 @@ const scanForButton = (nodes: unknown): boolean =>
 const detectButton = () => scanForButton(slots.default?.({}));
 
 // Published to the subtree: BadgeBodyContent — ours or the one inside a
-// slotted BbBadgeButton — renders the leading side from this state.
+// slotted BbBadgeButton — renders the leading side from this state. Plain
+// getters, not `computed()`: see `HostValue`. Every entry is a bare prop read,
+// so there is nothing for a computed to memoize — and seven reactive effects
+// per badge is a real per-row tax in a table cell that carries three of them.
 provideBadgeHost({
-	icon: computed(() => props.icon),
-	prependIcon: computed(() => props['prepend:icon']),
-	appendIcon: computed(() => props['append:icon']),
-	loading: computed(() => !!props.loading),
-	spinnerLeads: computed(() => !!props.loading && !spinnerTrails.value),
-	spinnerTrails: computed(() => !!props.loading && spinnerTrails.value),
-	clearable: computed(() => !!props.clearable),
+	icon: {
+		get value() {
+			return props.icon;
+		},
+	},
+	prependIcon: {
+		get value() {
+			return props['prepend:icon'];
+		},
+	},
+	appendIcon: {
+		get value() {
+			return props['append:icon'];
+		},
+	},
+	loading: {
+		get value() {
+			return !!props.loading;
+		},
+	},
+	spinnerLeads: {
+		get value() {
+			return !!props.loading && !spinnerTrails();
+		},
+	},
+	spinnerTrails: {
+		get value() {
+			return !!props.loading && spinnerTrails();
+		},
+	},
+	clearable: {
+		get value() {
+			return !!props.clearable;
+		},
+	},
 });
 
 const badgeClasses = computed(() => [

package/dist/ai/source/BbBaseSelect.md

@@ -115,7 +115,11 @@
 							v-if="usesOverflowCollapse || !isCollapsed"
 							ref="chipsContainerRef"
 							class="bb-base-select__chips-row"
-							:class="{ 'bb-base-select__chips-row--hidden': isCollapsed }"
+							:class="{
+								'bb-base-select__chips-row--hidden': isCollapsed,
+								'bb-base-select__chips-row--chips':
+									!comma && !!selectedOptions.length,
+							}"
 						>
 							<template v-if="comma">
 								<span
@@ -127,19 +131,40 @@
 								</span>
 							</template>
 							<!-- One badge per selection: removable (clearable) when
-							deselection is allowed, non-removable otherwise. -->
+							deselection is allowed, non-removable otherwise. The `chip`
+							slot replaces the badge outright (the badge below is its
+							fallback), so a consumer can render their own chip — a colored
+							tag, an avatar row — without reaching for `prepend`. No wrapper
+							element around it: the row itself supplies the spacing (see
+							`--chips` in index.css), so custom content needs none of our
+							class names to sit correctly. -->
 							<template v-else>
-								<BbBadge
+								<!-- `v-for` on a `<template>`, not on the `<slot>` itself: a
+								`key` bound on a slot outlet is passed through as a slot
+								PROP. The template renders no element of its own. -->
+								<template
 									v-for="item in selectedOptions"
 									:key="hash(item.value)"
-									class="bb-base-select__chip"
-									:clearable="canDeselectChips"
-									size="lg"
-									variant="secondary"
-									@click:clear.stop="onChipUnselected(item)"
 								>
-									{{ item.text }}
-								</BbBadge>
+									<slot
+										:deselect="() => onChipUnselected(item)"
+										:disabled="!canDeselectChips"
+										:item="item.item"
+										name="chip"
+										:text="item.text"
+										:value="item.value"
+									>
+										<BbBadge
+											class="bb-base-select__chip"
+											:clearable="canDeselectChips"
+											size="lg"
+											variant="secondary"
+											@click:clear.stop="onChipUnselected(item)"
+										>
+											{{ item.text }}
+										</BbBadge>
+									</slot>
+								</template>
 							</template>
 						</span>
 						<span v-if="isCollapsed" class="bb-base-select__max-reached">
@@ -769,6 +794,27 @@ export type BaseSelectPanelSlotProps = {
 	selectedOptions: BbSelectResolvedOption[];
 };
 
+/**
+ * Props exposed by the `chip` slot — called once per selected value in
+ * `multiple` mode, in place of the default badge. Not called in `comma` mode
+ * (there are no chips there) nor for the collapsed "+N" summary.
+ */
+export type BaseSelectChipSlotProps<Item = any> = {
+	/** The selected item, exactly as it was supplied in `items`. */
+	item: Item;
+	/** The item's resolved display text (what the default badge prints). */
+	text: string;
+	/** The item's resolved value — what sits in the v-model. */
+	value: any;
+	/**
+	 * `true` while the control is disabled or readonly: the chip must not offer
+	 * a way to remove itself, and `deselect` is a no-op.
+	 */
+	disabled: boolean;
+	/** Drops this value from the selection. No-op while `disabled`. */
+	deselect: () => void;
+};
+
 export type BaseSelectSlots<Item = any> = {
 	/** Content pinned to the top of the panel, above the search field. */
 	header?: (props: BaseSelectPanelSlotProps) => any;
@@ -784,6 +830,8 @@ export type BaseSelectSlots<Item = any> = {
 	'no-data'?: (props: { query: string; focus: () => void }) => any;
 	option?: (props: BaseSelectOptionSlotProps<Item>) => any;
 	group?: (props: BaseSelectGroupSlotProps<Item>) => any;
+	/** Replaces the default badge rendered for each selection in `multiple` mode. */
+	chip?: (props: BaseSelectChipSlotProps<Item>) => any;
 };
 ```
 
@@ -885,12 +933,19 @@ export type BaseSelectSlots<Item = any> = {
 			pointer-events: none;
 			visibility: hidden;
 		}
-	}
 
-	&__chip {
-		flex-shrink: 0;
-		&:not(:last-child) {
-			margin-right: 0.25rem;
+		/* Chips mode with at least one selection — never comma mode, which
+		   separates with its own `,` and wants no gap. The `chip` slot lets a
+		   consumer render their own element in place of our badge, so the layout
+		   a chip needs (no shrinking, the gap between chips, and the negative
+		   inset coupling below) lives HERE, on the row, rather than on a
+		   `__chip` class custom content would have to know to apply. */
+		&--chips {
+			gap: 0.25rem;
+
+			> * {
+				flex-shrink: 0;
+			}
 		}
 	}
 
@@ -927,7 +982,7 @@ export type BaseSelectSlots<Item = any> = {
 	}
 	/* If there is no prepend icon, add a negative margin to the chips row so it smoothly couples with the border */
 	&:not(:has(.common-input-wrapper__prepend-icon)) {
-		.bb-base-select__chips-row:has(.bb-base-select__chip) {
+		.bb-base-select__chips-row--chips {
 			margin-left: calc(
 				var(--bb-input-px) * var(--compensation-multiplier) * -1
 			);