bitboss-ui 3.0.0-beta.1 → 3.0.0-beta.12

package/README.md

@@ -36,46 +36,53 @@ Full detail: `ai/guides/installation-and-plugin-setup.md`.
 
 ### Composables
 
-| Composable                    | Role                                                       |
-| ----------------------------- | ---------------------------------------------------------- |
-| `useBbConfig`                 | Global options for the kit (locale, defaults, etc.).       |
-| `useBroadcastChannelInstance` | Shared `BroadcastChannel` helper for cross-tab messaging.  |
-| `useConfirm`                  | Programmatic confirm / modal flows.                        |
-| `useCountdown`                | Countdown timer state.                                     |
-| `useMobile`                   | Mobile / viewport-oriented behaviour.                      |
-| `useQueue`                    | Simple async task queue.                                   |
-| `useSafeArea`                 | Claim a screen edge for a docked panel so toasts avoid it. |
-| `useToast`                    | Toast notifications API.                                   |
-
-### Base\* components (primitives) _(reference-only - prefer `Bb*` equivalents for consumer code)_
-
-Headless or low-level pieces used inside **Bb\*** wrappers or your own compositions:
-
-- **Actions:** `BbBaseButton`
-- **Text & numbers:** `BaseTextInput`, `BaseTextarea`, `BaseNumberInput`, `BaseTag`
-- **Choice:** `BaseCheckbox`, `BaseCheckboxGroup`, `BaseRadio`, `BaseRadioGroup`, `BaseSwitch`, `BaseSwitchGroup`, `BaseSlider`, `BaseRating`
-- **Choice glyphs (presentational SVGs):** `BbBaseCheckboxIcon`, `BbBaseRadioIcon`, `BbBaseSwitchIcon`
-- **Rich inputs:** `BaseSelect`, `BaseColorInput`, `BaseDatePicker`, `BaseDatePickerInput`
-- **Layout / chrome:** `BaseInputContainer`, `BaseDialog`
+| Composable             | Role                                                                  |
+| ---------------------- | --------------------------------------------------------------------- |
+| `useBbConfig`          | Global options for the kit (locale, defaults, etc.).                  |
+| `useBbDropdownContext` | Read a `BbDropdown`'s resolved groups/selections from anywhere by id. |
+| `useBbTableContext`    | Imperative handle onto a `BbTable` by id.                             |
+| `useBbTabsContext`     | Programmatic tab selection for a `BbTabs` by id.                      |
+| `useConfirm`           | Programmatic confirm / modal flows.                                   |
+| `useCountdown`         | Countdown timer state.                                                |
+| `useId`                | SSR-safe unique ids.                                                  |
+| `useMobile`            | Mobile / viewport-oriented behaviour.                                 |
+| `useSafeArea`          | Claim a screen edge for a docked panel so toasts avoid it.            |
+| `useToast`             | Toast notifications API.                                              |
+
+### Utilities
+
+- **`slotKey`** — the normalizer behind every dynamic per-item named slot (`BbDropdown`, `BbTable`, `BbTabs`, `BbTree`, `BbBreadcrumbs`). Import it when building slot names programmatically instead of restating the rule.
+
+### Directives
+
+`vBbTooltip`, `vBbDropdown`, `vBbColor`, `vBbDate`, `vBbTime` — plus a
+`Bb*DirectivePlugin` for each, for app-level registration. Prefer the directive
+over the component for simple no-slot cases.
+
+### Base\* primitives
+
+The styled `Base*` input controls and the input chrome (`BbBaseInputContainer`,
+`CommonInputWrapper` — label, prepend/append, prefix/suffix, clear button,
+spacing) are **internal composition layers and are not exported**. Use the full
+public inputs (`BbTextInput`, `BbSelect`, …); pass `hideLabel` for a
+bare/inline control. The exported primitives are **`BbBaseButton`** and the
+presentational glyphs **`BbBaseCheckboxIcon`**, **`BbBaseRadioIcon`**,
+**`BbBaseSwitchIcon`**.
 
 ### Bb\* components (composed)
 
 Product-ready components with labels, hints, errors, and consistent styling:
 
-- **Forms & actions:** `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbSelect`, `BbCheckbox`, `BbCheckboxGroup`, `BbRadio`, `BbRadioGroup`, `BbSwitch`, `BbSwitchGroup`, `BbSlider`, `BbRating`, `BbColorInput`, `BbDatePickerInput`, `BbButton`, `BbBadge`, `BbIndicator`, `BbTag`, `BbDropdown`, `BbDropdownButton`
-- **Feedback:** `BbAlert`, `BbProgress`, `BbSpinner`, `BbToast`, `BbTooltip`
-- **Layout & navigation:** `BbAccordion`, `BbCollapsible`, `BbTab`, `BbBreadcrumbs`, `BbPagination`,`BbSmoothHeight`
+- **Forms & actions:** `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbSelect`, `BbSelectPopover`, `BbCheckbox`, `BbCheckboxGroup`, `BbRadio`, `BbRadioGroup`, `BbSwitch`, `BbSwitchGroup`, `BbSlider`, `BbRating`, `BbColorInput`, `BbColorPalette`, `BbDatePicker`, `BbDatePickerInput`, `BbTimePicker`, `BbTimePickerInput`, `BbButton`, `BbBadge`, `BbBadgeButton`, `BbIndicator`, `BbTag`, `BbDropdown`, `BbDropdownGroup`, `BbDropdownButton`, `BbAsterisk`
+- **Feedback:** `BbAlert`, `BbProgress`, `BbSpinner`, `BbToast`, `BbToastPortal`, `BbTooltip`
+- **Layout & navigation:** `BbAccordion`, `BbCollapsible`, `BbTabs` (+ `BbTabsRoot`, `BbTabsList`, `BbTabsPanes`), `BbBreadcrumbs`, `BbPagination`, `BbSmoothHeight`
 - **Overlays & panels:** `BbDialog`, `BbConfirm`, `BbConfirmPortal`, `BbOffCanvas`, `BbPopover`
 - **Data:** `BbTable`, `BbTree`
 - **Media & files:** `BbAvatar`, `BbDropzone`, `BbIcon`
 
-### Shared input shells _(internal layout primitives - not for direct consumer use)_
-
-- **`CommonInputWrapper`** — the internal input-chrome primitive (label, prepend/append, prefix/suffix, clear button, spacing) that every `Bb*` input composes. Not exported; use the full public inputs (`BbTextInput`, `BbSelect`, …).
-
 ### Exported component types
 
-For most **Base\*** and **Bb\*** components, the package exports matching **props**, **events**, and (where relevant) **slots** types (for example `BbSelectProps`, `BaseSelectEvents`). Use them for typed wrappers and design-system layers; the docs list the full set per component.
+For the public **Bb\*** components, the package exports matching **props**, **events**, and (where relevant) **slots** types (for example `BbSelectProps`, `BbTableEvents`), plus supporting shapes like `BbDropdownItem` and `DropdownGroupItemsGetter`. Use them for typed wrappers and design-system layers; the docs list the full set per component.
 
 ---
 

package/dist/ai/BbBadge.md

@@ -309,9 +309,12 @@ state in the handler. Prefer `secondary` / `outline` for filter chips; reserve
 ```
 
 The clear button inherits the variant's foreground, so it reads on every surface
-— light on a filled `primary`, dark on a `secondary`/`outline`. Set
-`clearable-label` for the button's accessible name (defaults to the localized
-`badge.clearLabel`).
+— light on a filled `primary`, dark on a `secondary`/`outline`. By default its
+accessible name composes the localized verb with the badge's own text — a chip
+reading "Italy" announces "Remove Italy", with no per-chip wiring. Set
+`clearable-label` only when that composition is wrong for the context (it
+replaces the whole name). With a `BbBadgeButton` body the composition is
+skipped and the button falls back to the bare localized `badge.clearLabel`.
 
 Icons combine with `clearable`: a **`prepend:icon`** stays (it leads the label);
 an **`append:icon`** shares the trailing slot with the clear button — the icon
@@ -695,8 +698,10 @@ selectors like `.bb-badge > .bb-badge__content`, which no longer match.
 - An icon-only badge (`icon`) has no visible text; the default slot is rendered
   as a screen-reader-only label — never leave it empty. In button mode that
   label is also the **button's accessible name**, so it is doubly required.
-- The `clearable` button has an accessible name from `clearable-label` (or the
-  localized `badge.clearLabel`).
+- The `clearable` button's accessible name is composed by default: the
+  localized `badge.clearLabel` verb plus the badge body's text ("Remove
+  Italy"). `clearable-label` replaces the whole name; with a `BbBadgeButton`
+  body the composition is skipped (bare verb only).
 - A clickable **and** clearable badge is two tab stops (body, then clear). That
   is intended: two actions, two controls.
 - Keyboard focus on either control rings the whole pill, so the focused target

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:
@@ -1212,6 +1294,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
 
@@ -1416,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 };