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

package/dist/ai/recipes/vue/records-workspace.md

@@ -461,7 +461,6 @@ export function useInvoicesWorkspace(): InvoicesWorkspaceContext {
 
 			<BbTable
 				id="invoices-table"
-				actions
 				caption="Invoices"
 				:columns="columns"
 				compact
@@ -735,7 +734,11 @@ const statusGroup: BbDropdownItem = {
 
 // Pipeline facet: `prefill: true` resolves a picked customer's name eagerly,
 // so a chip never sits on a bare id while this group's own submenu (inside
-// the Filters menu) has never been opened.
+// the Filters menu) has never been opened. The eager flag belongs HERE, on
+// the menu's copy only — the chip derives its own copy with
+// `prefill: 'interaction'` (see FilterChip.vue), because a second dropdown
+// redeclaring `prefill: true` would fetch every seeded facet twice on page
+// load for nothing.
 const customerGroup: BbDropdownItem = {
 	key: 'customer',
 	label: 'Customer',
@@ -787,10 +790,10 @@ const menu = computed<BbDropdownItem[]>(() => [
 	     component sitting between `BbBadge` and `BbBadgeButton` breaks the
 	     badge's direct-child vnode scan (the companion must be a literal
 	     child). This IS "the chip is itself a dropdown onto the same filter
-	     group": `group` is the exact descriptor FilterRail declared, reused
-	     rather than redeclared, so this scoped picker and the Filters menu's
-	     own submenu can never drift apart. -->
-	<BbDropdown :activator="chipRef" :items="[group]" :width="220">
+	     group": `chipGroup` is derived from the exact descriptor FilterRail
+	     declared (spread, one override — never redeclared), so this scoped
+	     picker and the Filters menu's own submenu can never drift apart. -->
+	<BbDropdown :activator="chipRef" :items="[chipGroup]" :width="220">
 		<BbDropdownGroup
 			:id="groupKey"
 			:model-value="modelValue"
@@ -824,9 +827,24 @@ const emit = defineEmits<{ 'update:modelValue': [value: unknown] }>();
 
 const chipRef = useTemplateRef('chipRef');
 
+// The chip's own copy of the shared descriptor, one override: `prefill:
+// 'interaction'`. BbDropdown mounts a pipeline resolver for every group it
+// declares at its own root, independent of the panel ever opening — so if
+// this second dropdown repeated the menu's `prefill: true` verbatim, each
+// seeded pipeline facet would be fetched TWICE on page load, and the chip's
+// copy of the result would feed nothing (the label below comes from the
+// menu's resolution via context). `'interaction'` defers this copy's fetch
+// to the moment the chip's dropdown is actually opened. For static array
+// facets the override is inert — arrays resolve synchronously either way.
+const chipGroup = computed<BbDropdownItem>(() => ({
+	...props.group,
+	prefill: 'interaction',
+}));
+
 // Reads the Filters menu's already-resolved selection — no twin fetch. A
-// pipeline group needs `prefill: true` (set on `group` by FilterRail) so this
-// never sits on a bare id/value while the menu's own submenu is unopened.
+// pipeline group needs `prefill: true` (set on the MENU's copy of `group` by
+// FilterRail) so this never sits on a bare id/value while the menu's own
+// submenu is unopened.
 const dropdownFilters = useBbDropdownContext('invoice-filters');
 const chipText = computed(() => {
 	const options =

package/dist/ai/recipes/vue/upload-center.md

@@ -603,7 +603,6 @@ export function useUploadCenter(): UploadCenterContext {
 
 			<BbTable
 				id="receipts-table"
-				actions
 				caption="Expense receipts"
 				:columns="columns"
 				compact

package/dist/ai/source/BbAlert.md

@@ -190,7 +190,16 @@ export type BbAlertEvents =
 
 /** Props exposed by the `title` slot. */
 export type BbAlertTitleSlotProps = {
-	/** The `title` prop value. */
+	/**
+	 * The `title` prop's value — despite the scope being named `text`.
+	 *
+	 * Both slots name their payload `text` (each meaning "the text of THIS
+	 * slot"), so `#title="{ text }"` gives you the title and
+	 * `#text="{ text }"` gives you the body. Worth stating because the v2 bug
+	 * this replaced was the opposite mix-up: v2's `#text` slot passed the
+	 * *title*. Renaming the scope now would be another break, so the rule is
+	 * simply: the payload belongs to the slot you are in.
+	 */
 	text: BbAlertProps['title'];
 };
 
@@ -290,9 +299,23 @@ export type BbAlertSlots = {
 		}
 	}
 
+	/*
+	 * Q17.1 — the body is the danger colour at FULL strength, not a mix.
+	 *
+	 * The 75%-of-main formula the quiet variants use holds for `outline` and
+	 * `primary`, whose `--main-color` is already a text colour. It does not hold
+	 * for a STATUS colour: 75% of `--bb-danger` measures 3.18:1 light / 3.17:1
+	 * dark against the panel, under the 4.5:1 budget real message text carries.
+	 *
+	 * Dropping the mix fixes that without changing what the variant IS: 4.55:1
+	 * in both schemes, and the body stays red — which is also what shadcn does,
+	 * colouring title and description alike. (A neutral grey body was tried and
+	 * reverted: it cleared contrast comfortably but read as a different
+	 * component.) Hierarchy comes from the title's font-weight, as before.
+	 */
 	&--destructive {
 		--main-color: var(--bb-danger);
-		--muted-color: color-mix(in oklab, var(--main-color) 75%, transparent);
+		--muted-color: var(--main-color);
 		background-color: transparent;
 		border-color: var(--bb-border);
 
@@ -316,6 +339,31 @@ export type BbAlertSlots = {
 		}
 	}
 
+	/*
+	 * Warning keeps the shadcn amber it has always had — the owner's call, and
+	 * the palette is deliberate. What changed is HOW the two schemes are
+	 * selected (Q4.1).
+	 *
+	 * The old rule paired a light block with `:where(.dark) &--warning`. Because
+	 * `:where()` contributes no specificity, that tied the light rule at (0,1,0)
+	 * and won on source order — so it matched through ANY `.dark` ancestor. A
+	 * `.light` island inside a dark page (the docs theme builder's light preview
+	 * pane is exactly this) flipped every other component back to light and left
+	 * the warning Alert dark on a white panel. No scope class could beat it at
+	 * any nesting depth.
+	 *
+	 * `light-dark()` keys off the element's computed `color-scheme`, which
+	 * variables.css already sets on `.light` / `.dark`. That makes the choice
+	 * INHERITED rather than selector-matched, so the nearest scheme scope wins
+	 * — a dark card inside a light island inside a dark page resolves correctly,
+	 * which is the case a second selector can never get right.
+	 *
+	 * The two rules below it are the pre-`light-dark()` fallback, kept exactly
+	 * as they shipped: on a browser without it (pre-Chrome 123 / Safari 17.5 /
+	 * Firefox 120) the `@supports` block simply does not apply and behaviour is
+	 * identical to before, island leak included. Nothing regresses; modern
+	 * browsers just stop leaking.
+	 */
 	&--warning {
 		--main-color: #7b3306;
 		--muted-color: #737373;
@@ -349,6 +397,16 @@ export type BbAlertSlots = {
 		border-color: #7c5f1f;
 	}
 
+	/* Wins over both of the above wherever it is understood. */
+	@supports (color: light-dark(red, blue)) {
+		&--warning {
+			--main-color: light-dark(#7b3306, #facc15);
+			--muted-color: light-dark(#737373, #d6d3d1);
+			background-color: light-dark(#fffbea, #2a2112);
+			border-color: light-dark(#fee685, #7c5f1f);
+		}
+	}
+
 	.bb-alert__inner-container {
 		align-items: start;
 		display: grid;

package/dist/ai/source/BbAvatar.md

@@ -36,22 +36,22 @@
 import { computed, onMounted, ref, watch } from 'vue';
 import { parseSize } from '@/utilities/functions/parseSize';
 import { wait } from '@/utilities/functions/wait';
-import { config } from 'virtual:bitboss-ui/config';
+import { useConfig } from '@/composables/useConfig';
 import { useLogger } from '@/composables/useLogger';
 import { removedPropsFor } from '@/deprecation/removedProps';
 import { warnRemovedAttrs } from '@/utilities/functions/warnRemovedAttrs';
 import BbIcon from '../BbIcon/BbIcon.vue';
 import defaultFallbackIcon from '@/assets/svgs/user.svg?raw';
 import type { BbAvatarProps, BbAvatarSlots } from './types';
-export type { BbAvatarProps, BbAvatarSlots };
 
 const props = withDefaults(defineProps<BbAvatarProps>(), {
 	alt: '',
 	timeout: 400,
 	size: 'md',
 });
-
 defineSlots<BbAvatarSlots>();
+const config = useConfig();
+export type { BbAvatarProps, BbAvatarSlots };
 
 if (process.env.NODE_ENV !== 'production')
 	warnRemovedAttrs('BbAvatar', removedPropsFor('BbAvatar'));

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(() => [
@@ -202,8 +241,14 @@ export type BbBadgeProps = {
 	 */
 	clearable?: boolean;
 	/**
-	 * Accessible label for the clear button. Falls back to the localized
-	 * `badge.clearLabel` key.
+	 * Accessible label for the clear button.
+	 *
+	 * Rarely needed: unset, the name is **composed** from the localized
+	 * `badge.clearLabel` verb and the badge's own text — "Remove Italy", not a
+	 * bare "Remove" — which is already the right name in almost every case.
+	 * Composition is skipped when a `BbBadgeButton` owns the body (the verb
+	 * then stands alone, so the two controls do not both announce the label).
+	 * Set this only to override that composed name outright.
 	 */
 	clearableLabel?: string;
 	/**

package/dist/ai/source/BbBadgeButton.md

@@ -105,8 +105,14 @@ export type BbBadgeProps = {
 	 */
 	clearable?: boolean;
 	/**
-	 * Accessible label for the clear button. Falls back to the localized
-	 * `badge.clearLabel` key.
+	 * Accessible label for the clear button.
+	 *
+	 * Rarely needed: unset, the name is **composed** from the localized
+	 * `badge.clearLabel` verb and the badge's own text — "Remove Italy", not a
+	 * bare "Remove" — which is already the right name in almost every case.
+	 * Composition is skipped when a `BbBadgeButton` owns the body (the verb
+	 * then stands alone, so the two controls do not both announce the label).
+	 * Set this only to override that composed name outright.
 	 */
 	clearableLabel?: string;
 	/**

package/dist/ai/source/BbBaseButton.md

@@ -47,7 +47,7 @@ import RouterComponent from './RouterComponent.vue';
 import { useFrameworkDetection } from '@/composables/useFrameworkDetection';
 import { useHydrated } from '@/composables/useHydrated';
 import { useInertiaPage } from '@/composables/useInertiaPage';
-import { config } from 'virtual:bitboss-ui/config';
+import { useConfig } from '@/composables/useConfig';
 import type { BbBaseButtonProps, BbBaseButtonSlots } from './types';
 
 const props = withDefaults(defineProps<BbBaseButtonProps>(), {
@@ -56,6 +56,8 @@ const props = withDefaults(defineProps<BbBaseButtonProps>(), {
 
 defineSlots<BbBaseButtonSlots>();
 
+const config = useConfig();
+
 const { isInertia, isNuxt } = useFrameworkDetection();
 const { isHydrated } = useHydrated();
 const { getPageUrl } = useInertiaPage();

package/dist/ai/source/BbBaseCheckboxGroup.md

@@ -109,6 +109,8 @@ useOnTruthy(active, () => emit('active'));
 
 const {
 	getter,
+	clientReproducible,
+	hydratedFromSsr,
 	items: internalItems,
 	loading,
 } = useItemsGetter({
@@ -122,6 +124,8 @@ const alignToCoherenceSettings = () => {
 };
 
 const { hasPrefilled } = usePrefill({
+	alreadyLoaded: hydratedFromSsr,
+	clientReproducible,
 	trigger: true,
 	currentValue: props.modelValue,
 	multiple: props.multiple,
@@ -287,7 +291,7 @@ export type BaseCheckboxGroupProps<T = any> = {
 	/**
 	 * 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 | the docs} for more information.
+	 * coherent array. Please check out {@link https://ui-components.bitboss.it/it/guides/coherence | the docs} for more information.
 	 * @defaultValue `false`
 	 */
 	enforceCoherence?: boolean;
@@ -402,7 +406,7 @@ export type BaseCheckboxGroupEvents = {
 	 */
 	(e: 'blur', event: FocusEvent): void;
 	/**
-	 * Emitted when a checkbox option is toggled.
+	 * Emitted when an option is toggled.
 	 * Forwards the original DOM `Event` from the checkbox input.
 	 */
 	(e: 'change', event: Event): void;

package/dist/ai/source/BbBaseDatePicker.md

@@ -176,7 +176,7 @@ import MonthSelector from './BbBaseDatePickerMonthSelector.vue';
 import ScaleFadeTransition from '@/components/Transitions/ScaleFade.vue';
 import YearSelector from './BbBaseDatePickerYearSelector.vue';
 import { useLocale } from '@/composables/useLocale';
-import { config } from 'virtual:bitboss-ui/config';
+import { useConfig } from '@/composables/useConfig';
 import { normalizeSearchToken, useTypeahead } from './typeahead';
 import {
 	provideDatePickerContext,
@@ -199,6 +199,8 @@ import type {
 	BaseDatePickerSlots,
 } from './types';
 
+const config = useConfig();
+
 const { t } = useLocale();
 
 const globalId = props.id || useId().id;

package/dist/ai/source/BbBaseDatePickerInput.md

@@ -175,7 +175,7 @@
 </template>
 
 <script setup lang="ts">
-import { config } from 'virtual:bitboss-ui/config';
+import { useConfig } from '@/composables/useConfig';
 import { computed, onBeforeUnmount, ref, watch, watchEffect } from 'vue';
 import type { Dayjs } from 'dayjs';
 import { default as dayjs } from 'dayjs';
@@ -230,7 +230,11 @@ const props = withDefaults(defineProps<BaseDatePickerInputProps>(), {
 });
 
 const emit = defineEmits<BaseDatePickerInputEvents>();
+
 defineSlots<BaseDatePickerInputSlots>();
+
+const config = useConfig();
+
 /**
  * Time affordances belong to one member of the union. Reading the type through
  * these keeps the old `props.datetime` branches intact while the union stays

package/dist/ai/source/BbBaseInputContainer.md

@@ -274,8 +274,11 @@ const widths = computed(() => {
 			initial.input = second;
 		}
 	} else {
+		// The ratio is CHARACTER COUNT, not numeric value: 'x xx' is 1:2. This
+		// message used to name '1 2', which is two one-character tokens — a
+		// 50/50 split, and precisely the mistake the warning exists to prevent.
 		logger.warn(
-			`Invalid direction: "${resolvedDirection.value}". Expected 'auto', 'vertical', 'horizontal', or a two-token ratio like '1 2'. Falling back to 'auto'.`
+			`Invalid direction: "${resolvedDirection.value}". Expected 'auto', 'vertical', 'horizontal', or a two-token pattern whose TOKEN LENGTHS are the ratio, like 'x xx' for 1:2. Falling back to 'auto'.`
 		);
 		// `initial` is already the auto shape (label/input: 'auto'), so falling
 		// through here leaves the layout at the safe default.
@@ -657,6 +660,22 @@ export type BaseInputContainerSlots = {
 	display: flex;
 	flex-direction: column;
 
+	/*
+	 * A field never sizes its own track from its content.
+	 * -----------------------------------------------------------------
+	 * As a grid or flex item this container's automatic minimum size is
+	 * `min-content`, and for a select that is the ENTIRE placeholder string:
+	 * the trigger paints its placeholder as real `nowrap` text, because a
+	 * native `::placeholder` only exists on a real `<input>`. So a long
+	 * placeholder used to widen the column it sat in, while a `BbTextInput`
+	 * next to it held its own (its `<input>` floors at `min-width: 50px` and
+	 * `::placeholder` is paint-only). In a `repeat(3, 1fr)` form row that
+	 * measured 188.9 / 226 / 68px instead of three equal tracks.
+	 *
+	 * The floor lives on the control, not here — see `__control` below.
+	 */
+	min-width: 0;
+
 	/*
 	 * Compact mode
 	 * -----------------------------------------------------------------
@@ -961,6 +980,16 @@ export type BaseInputContainerSlots = {
 		 */
 		display: grid;
 
+		/* Same reason as the container root: this is a flex item, so its
+		   automatic minimum would re-introduce the content floor the root just
+		   dropped. `min-width` has to be 0 on EVERY link between the sized
+		   ancestor and the element that ellipses, or the chain stops truncating
+		   at the first link that still says `auto`. The 50px keeps a squeezed
+		   field usable, mirroring the `min-width: 50px` the native input and
+		   textarea already carry so a select and a text input degrade
+		   identically. */
+		min-width: min(50px, 100%);
+
 		&--left {
 			justify-items: flex-start;
 		}
@@ -972,6 +1001,28 @@ export type BaseInputContainerSlots = {
 		}
 	}
 
+	/*
+	 * Control-first widgets opt OUT of that floor.
+	 * -----------------------------------------------------------------
+	 * The 50px above buys a squeezed text track a usable minimum. These four
+	 * have no track: their control is a fixed-size glyph (a 16px box, a 32px
+	 * switch) and `direction: 'auto'` leaves `widths.input` at `auto`, so the
+	 * floor was the only thing sizing the column — a 16px checkbox sat in a
+	 * 50px cell and its label started 42px away instead of the
+	 * `--bb-label-spacing-x` the layout intends. Pinned in BbCheckbox.test.ts.
+	 *
+	 * Groups are deliberately NOT here: a group's control column holds full
+	 * option rows with their own labels, so it still wants a floor.
+	 */
+	&.bb-checkbox,
+	&.bb-radio,
+	&.bb-switch,
+	&.bb-rating {
+		.bb-base-input-container__control {
+			min-width: 0;
+		}
+	}
+
 	&__description {
 		/*
 		 * Description channel

package/dist/ai/source/BbBaseRadioGroup.md

@@ -134,6 +134,8 @@ useOnTruthy(active, () => emit('active'));
 
 const {
 	getter,
+	clientReproducible,
+	hydratedFromSsr,
 	items: internalItems,
 	loading,
 } = useItemsGetter({
@@ -147,6 +149,8 @@ const alignToCoherenceSettings = () => {
 };
 
 const { hasPrefilled } = usePrefill({
+	alreadyLoaded: hydratedFromSsr,
+	clientReproducible,
 	trigger: true,
 	currentValue: props.modelValue,
 	multiple: false,

package/dist/ai/source/BbBaseRating.md

@@ -95,7 +95,7 @@ import { useOnFalsy } from '@/composables/useOnFalsy';
 import { useOnTruthy } from '@/composables/useOnTruthy';
 import { useId } from '@/composables/useId';
 import { useLogger } from '@/composables/useLogger';
-import { config } from 'virtual:bitboss-ui/config';
+import { useConfig } from '@/composables/useConfig';
 
 const props = withDefaults(defineProps<BaseRatingProps>(), {
 	clearable: false,
@@ -106,6 +106,8 @@ const emit = defineEmits<BaseRatingEvents>();
 
 defineSlots<BaseRatingSlots>();
 
+const config = useConfig();
+
 const { t } = useLocale();
 const logger = useLogger();
 

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
 			);