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

package/dist/ai/BbDialog.md

@@ -42,11 +42,11 @@ for buttons inside the body. Footer buttons simply set the model back to
 ```vue
 <template>
 	<div
-		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
+		class="flex w-full max-w-sm flex-col gap-3 rounded-(--bb-radius) border p-4"
 	>
 		<div>
 			<p class="m-0 text-sm font-medium">Issue labels</p>
-			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+			<p class="m-0 text-xs text-(--bb-text-muted)">
 				12 labels · used across Northwind issues
 			</p>
 		</div>
@@ -68,7 +68,7 @@ for buttons inside the body. Footer buttons simply set the model back to
 				label="Label name"
 				placeholder="e.g. Priority"
 			/>
-			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+			<p class="m-0 text-xs text-(--bb-text-muted)">
 				Names are unique per workspace and show up in filters.
 			</p>
 		</div>
@@ -108,35 +108,56 @@ A `title` prop renders the standard header (title text + close button) and wires
 `aria-labelledby` for you. Put form fields in the `default` slot and actions in
 the `footer` slot — keep exactly one primary action there and align the group to
 the end. The body area scrolls internally when content overflows; header and
-footer stay pinned. This edit-record dialog re-seeds a typed draft from the
-record on `@show` — so a canceled edit never leaks into the next session — and
-copies it back on save.
+footer stay pinned. This edit-record dialog builds a fresh draft from the
+selected record on `@show`, drops it on `@hidden`, and copies it back on save —
+so a canceled edit never leaks into the next session, and neither does a field
+the next record happens not to have.
 
 **Edit-record dialog with a footer action**
 
 ```vue
 <template>
-	<div
-		class="flex w-full max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-4"
-	>
-		<div class="min-w-0">
-			<p class="m-0 truncate text-sm font-medium">{{ contact.name }}</p>
-			<p class="m-0 truncate text-xs text-[color:var(--bb-text-muted)]">
-				{{ contact.email }}
-			</p>
-		</div>
-		<BbButton
-			prepend:icon="lucide:pencil"
-			variant="outline"
-			@click="open = true"
+	<ul class="m-0 flex w-full max-w-sm list-none flex-col gap-2 p-0">
+		<li
+			v-for="contact in contacts"
+			:key="contact.id"
+			class="flex items-center justify-between gap-3 rounded-(--bb-radius) border p-3"
 		>
-			Edit contact
-		</BbButton>
-	</div>
-	<BbDialog v-model="open" size="md" title="Edit contact" @show="seedDraft">
-		<div class="grid gap-3">
+			<div class="min-w-0">
+				<p class="m-0 truncate text-sm font-medium">{{ contact.name }}</p>
+				<p class="m-0 truncate text-xs text-(--bb-text-muted)">
+					{{ contact.email
+					}}<template v-if="contact.phone"> · {{ contact.phone }}</template>
+				</p>
+			</div>
+			<BbButton
+				:aria-label="`Edit ${contact.name}`"
+				prepend:icon="lucide:pencil"
+				size="sm"
+				variant="outline"
+				@click="edit(contact)"
+			>
+				Edit
+			</BbButton>
+		</li>
+	</ul>
+	<BbDialog
+		v-model="open"
+		size="md"
+		title="Edit contact"
+		@hidden="clear"
+		@show="seed"
+	>
+		<div v-if="draft" class="grid gap-3">
 			<BbTextInput v-model="draft.name" compact label="Full name" />
 			<BbTextInput v-model="draft.email" compact label="Email" type="email" />
+			<BbTextInput
+				v-model="draft.phone"
+				compact
+				label="Phone"
+				placeholder="Optional"
+				type="tel"
+			/>
 			<BbSwitch v-model="draft.subscribed" label="Subscribed to updates" />
 		</div>
 		<template #footer>
@@ -149,33 +170,100 @@ copies it back on save.
 </template>
 
 <script setup lang="ts">
-import { reactive, ref } from 'vue';
+import { ref } from 'vue';
 import { BbButton, BbDialog, BbSwitch, BbTextInput } from 'bitboss-ui';
 
+// `phone` is optional on the record: some contacts simply do not have one.
 type Contact = {
+	id: number;
 	name: string;
 	email: string;
+	phone?: string;
 	subscribed: boolean;
 };
 
-// The record being edited — in a real app this comes from your store/API.
-const contact = reactive<Contact>({
-	name: 'Ada Lovelace',
-	email: 'ada@analytical.co',
-	subscribed: true,
+// The records being edited — in a real app these come from your store/API.
+// Two of them on purpose, one WITHOUT the optional field: that is the case a
+// single-record demo can never show going wrong.
+const contacts = ref<Contact[]>([
+	{
+		id: 1,
+		name: 'Ada Lovelace',
+		email: 'ada@analytical.co',
+		phone: '+44 20 7946 0958',
+		subscribed: true,
+	},
+	{
+		id: 2,
+		name: 'Grace Hopper',
+		email: 'grace@navy.mil',
+		subscribed: false,
+	},
+]);
+
+// The form binds every field, so the draft must always carry every field.
+// A blank factory guarantees that; the record only overrides what it has.
+type Draft = {
+	name: string;
+	email: string;
+	phone: string;
+	subscribed: boolean;
+};
+const blank = (): Draft => ({
+	name: '',
+	email: '',
+	phone: '',
+	subscribed: false,
 });
 
 const open = ref(false);
-const draft = reactive<Contact>({ ...contact });
+const editing = ref<Contact | null>(null);
+const draft = ref<Draft | null>(null);
 
-// Re-seed on every open: a canceled edit must not leak into the next session.
-const seedDraft = () => {
-	Object.assign(draft, contact);
+const edit = (contact: Contact) => {
+	editing.value = contact;
+	open.value = true;
+};
+
+// Seed on `@show`, and REPLACE the draft rather than merging into it.
+// `Object.assign(draft, record)` copies only the keys the record has: open Grace
+// (no phone) right after Ada (phone set) and Ada's phone is still in the input.
+const seed = () => {
+	const record = editing.value;
+	if (!record) return;
+	draft.value = {
+		...blank(),
+		name: record.name,
+		email: record.email,
+		phone: record.phone ?? '',
+		subscribed: record.subscribed,
+	};
+};
+
+// Drop the draft once the close transition ends, so nothing waits around for
+// the next record — `@hidden` is the teardown hook, not `@hide`.
+const clear = () => {
+	draft.value = null;
+	editing.value = null;
 };
 
 const save = () => {
-	// Persist here, then dismiss.
-	Object.assign(contact, draft);
+	const record = editing.value;
+	const next = draft.value;
+	if (!record || !next) return;
+	// Persist here, then dismiss. The optional field goes back to "absent"
+	// when it was cleared, so the record never grows an empty string.
+	contacts.value = contacts.value.map((contact) =>
+		contact.id === record.id
+			? {
+					...contact,
+					name: next.name,
+					email: next.email,
+					phone: next.phone.trim() || undefined,
+					subscribed: next.subscribed,
+				}
+			: contact
+	);
 	open.value = false;
 };
 </script>
@@ -194,11 +282,11 @@ and the only thing `aria-describedby` points at:
 ```vue
 <template>
 	<div
-		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
+		class="flex w-full max-w-sm flex-col gap-3 rounded-(--bb-radius) border p-4"
 	>
 		<div>
 			<p class="m-0 text-sm font-medium">INV-2044</p>
-			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+			<p class="m-0 text-xs text-(--bb-text-muted)">
 				Northwind Traders · €1,280.00 · paid
 			</p>
 		</div>
@@ -263,11 +351,11 @@ dismissed invite doesn't resurface half-typed:
 ```vue
 <template>
 	<div
-		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
+		class="flex w-full max-w-sm flex-col gap-3 rounded-(--bb-radius) border p-4"
 	>
 		<div>
 			<p class="m-0 text-sm font-medium">Team · Northwind Labs</p>
-			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+			<p class="m-0 text-xs text-(--bb-text-muted)">
 				4 members · 1 pending invite
 			</p>
 		</div>
@@ -298,7 +386,7 @@ dismissed invite doesn't resurface half-typed:
 				:items="roles"
 				label="Role"
 			/>
-			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+			<p class="m-0 text-xs text-(--bb-text-muted)">
 				They'll get an email with a link that expires in 7 days.
 			</p>
 		</div>
@@ -349,10 +437,18 @@ const send = () => {
 </script>
 ```
 
-Two rules keep dialog forms honest:
-
-- Reset or re-seed the draft when the dialog opens (`@show` is the hook), not
-  when it closes — a dismissed dialog may be reopened with stale state.
+Three rules keep dialog forms honest:
+
+- Seed the draft when the dialog opens (`@show` is the hook), and **replace
+  it, never merge into it**. `Object.assign(draft, record)` copies only the
+  keys the record has, so opening a record whose optional field is absent
+  right after one where it was set leaves the previous value in the input —
+  nothing warns. Build the draft from a blank factory so every field the form
+  binds is always present, then overlay the record
+  (`{ ...blank(), phone: record.phone ?? '' }`).
+- Clear the draft on `@hidden` as well. A close must leave nothing behind for
+  the next caller; `@hidden` fires after the close transition, so the form
+  does not blank mid-fade.
 - On success, do the work first, then set the model to `false`; the close
   transition runs while your toast/refresh happens.
 
@@ -361,7 +457,8 @@ Two rules keep dialog forms honest:
 Four events bracket the transitions — `show` fires as the model turns `true`,
 `shown` after the native `showModal()` call and initial focus, `hide` as the
 model turns `false`, and `hidden` after the close transition completes. Use
-`@show` to (re)seed form state, `@hidden` to tear down expensive content.
+`@show` to (re)seed form state, `@hidden` to drop a draft and tear down
+expensive content.
 
 Body content is **lazy**: nothing inside the dialog renders until the first
 open. Set `eager` to render it immediately (e.g. so a chart can pre-measure, or
@@ -435,11 +532,11 @@ element.
 ```vue
 <template>
 	<div
-		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
+		class="flex w-full max-w-sm flex-col gap-3 rounded-(--bb-radius) border p-4"
 	>
 		<div>
 			<p class="m-0 text-sm font-medium">Finish setting up</p>
-			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+			<p class="m-0 text-xs text-(--bb-text-muted)">
 				Add your company so invoices and invites look right.
 			</p>
 		</div>
@@ -513,13 +610,11 @@ automatically; close only once the work resolves:
 ```vue
 <template>
 	<div
-		class="flex w-full max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-4"
+		class="flex w-full max-w-sm items-center justify-between gap-3 rounded-(--bb-radius) border p-4"
 	>
 		<div class="min-w-0">
 			<p class="m-0 truncate text-sm font-medium">{{ projectName }}</p>
-			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
-				Project · private
-			</p>
+			<p class="m-0 text-xs text-(--bb-text-muted)">Project · private</p>
 		</div>
 		<BbButton
 			prepend:icon="lucide:pencil"
@@ -595,8 +690,10 @@ const save = async () => {
 
 Dialogs sharing a `stack` name **replace** one another: only the most recently
 opened member is visible, the ones beneath are hidden until it closes — the
-stack reads as a single surface whose content swaps as you drill in. Dialogs
-with different names (or none) are independent and simply layer by open order.
+stack reads as a single surface whose content swaps as you drill in. When a
+member closes, the one beneath crossfades in as it fades out, on the stack's
+single backdrop — the page behind never blinks between them. Dialogs with
+different names (or none) are independent and simply layer by open order.
 Use a stack for a two-step flow that should not read as two boxes piling up.
 
 **Drill into advanced options**
@@ -604,11 +701,11 @@ Use a stack for a two-step flow that should not read as two boxes piling up.
 ```vue
 <template>
 	<div
-		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
+		class="flex w-full max-w-sm flex-col gap-3 rounded-(--bb-radius) border p-4"
 	>
 		<div>
 			<p class="m-0 text-sm font-medium">Workspace settings</p>
-			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+			<p class="m-0 text-xs text-(--bb-text-muted)">
 				Storage, backups, retention
 			</p>
 		</div>
@@ -621,7 +718,7 @@ Use a stack for a two-step flow that should not read as two boxes piling up.
 	<BbDialog v-model="first" stack="settings" title="Storage">
 		<div class="grid gap-3">
 			<BbSwitch v-model="autoBackup" label="Automatic backups" />
-			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+			<p class="m-0 text-xs text-(--bb-text-muted)">
 				Nightly snapshots keep the last 30 days of changes.
 			</p>
 			<BbButton
@@ -636,7 +733,7 @@ Use a stack for a two-step flow that should not read as two boxes piling up.
 	<BbDialog v-model="second" stack="settings" title="Advanced retention">
 		<div class="grid gap-3">
 			<BbSwitch v-model="keepForever" label="Keep monthly snapshots" />
-			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+			<p class="m-0 text-xs text-(--bb-text-muted)">
 				Monthly snapshots stay available for 12 months after creation.
 			</p>
 		</div>
@@ -694,11 +791,11 @@ link.
 ```vue
 <template>
 	<div
-		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
+		class="flex w-full max-w-sm flex-col gap-3 rounded-(--bb-radius) border p-4"
 	>
 		<div>
 			<p class="m-0 text-sm font-medium">Projects</p>
-			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+			<p class="m-0 text-xs text-(--bb-text-muted)">
 				Free plan · {{ used }} of {{ limit }} used
 			</p>
 		</div>
@@ -719,7 +816,7 @@ link.
 				using all of them. Upgrade to <strong>Pro</strong> for unlimited
 				projects and priority support.
 			</p>
-			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+			<p class="m-0 text-xs text-(--bb-text-muted)">
 				Billing starts when you confirm — you can cancel anytime.
 			</p>
 		</div>
@@ -846,7 +943,7 @@ default falls back to `config.adaptive`.
 | `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to open / close the dialog. A dialog with no `v-model` starts closed. |
 | `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Overrides merged over the offcanvas (mobile) surface's props. The drawer defaults to a bottom, draggable, content-sized sheet (`side: 'bottom'`, `draggable: true`, `size: 'auto'`); use this to override those, set other drawer-only options (… |
 | `persistent` | `boolean \| undefined` | `false` |  | Prevent closing via outside clicks or Escape key. The header close (×) button STILL closes a persistent dialog — that is the documented escape hatch; combine with `hideClose` to remove it, or use `disabled` to block every dismissal. Program… |
-| `size` | `Responsive<NonNullable<number \| ({ size?: any; } & string) \| keyof Sizes \| undefined>> \| undefined` | `"sm"` |  | Controls the maximum width of the dialog. Accepts named presets from `'xs'` to `'2xl'`, a custom CSS width string, or a numeric pixel value — or a per-breakpoint map (e.g. `{ default: 'sm', lg: 'lg' }`) to switch width responsively. |
+| `size` | `Responsive<NonNullable<number \| ({ size?: any; } & string) \| keyof BbDialogSizes \| undefined>> \| undefined` | `"sm"` |  | Controls the maximum width of the dialog. Accepts named presets from `'xs'` to `'2xl'`, a custom CSS width string, or a numeric pixel value — or a per-breakpoint map (e.g. `{ default: 'sm', lg: 'lg' }`) to switch width responsively. |
 | `stack` | `string \| undefined` |  |  | Name of the stack this dialog belongs to. Dialogs sharing the same `stack` value replace one another: only the most recently opened stays visible while the others in the stack are hidden beneath it. Dialogs in different stacks — or with no … |
 | `title` | `string \| undefined` |  |  | Title text announced to assistive technologies. If omitted, no header is rendered (unless a `header` slot is supplied) and accessibility must be handled manually. |
 | `transitionDuration` | `number \| undefined` | `250` |  | Controls the duration of the open and close animations. |

package/dist/ai/BbDropdown.md

@@ -71,17 +71,17 @@ yes (the `<BbConfirm>` host mounts once per app, e.g. in the root layout).
 ```vue
 <template>
 	<div
-		class="flex max-w-sm items-center gap-2 rounded-[var(--bb-radius)] border p-2"
+		class="flex max-w-sm items-center gap-2 rounded-(--bb-radius) border p-2"
 	>
 		<div
 			aria-hidden="true"
-			class="flex size-8 shrink-0 items-center justify-center rounded-[var(--bb-radius-sm)] bg-[color:var(--bb-muted)] text-[color:var(--bb-text-muted)]"
+			class="flex size-8 shrink-0 items-center justify-center rounded-(--bb-radius-sm) bg-(--bb-muted) text-(--bb-text-muted)"
 		>
 			<span class="text-xs font-medium">PDF</span>
 		</div>
 		<div class="min-w-0 flex-1">
 			<p class="truncate text-sm font-medium">Q3-report.pdf</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				248 KB · <span data-last>{{ last }}</span>
 			</p>
 		</div>
@@ -194,11 +194,11 @@ selectable group the menu stays open instead, and the row itself carries
 ```vue
 <template>
 	<div
-		class="flex max-w-sm items-center gap-2 rounded-[var(--bb-radius)] border p-2"
+		class="flex max-w-sm items-center gap-2 rounded-(--bb-radius) border p-2"
 	>
 		<div class="min-w-0 flex-1">
 			<p class="truncate text-sm font-medium">bitboss/storefront</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]" data-sync>
+			<p class="text-xs text-(--bb-text-muted)" data-sync>
 				{{ status }}
 			</p>
 		</div>
@@ -268,7 +268,7 @@ nesting shallow (two levels is plenty).
 ```vue
 <template>
 	<div
-		class="flex max-w-xs items-center justify-between gap-2 rounded-[var(--bb-radius)] border p-2"
+		class="flex max-w-xs items-center justify-between gap-2 rounded-(--bb-radius) border p-2"
 	>
 		<span class="text-sm font-medium">Acme Studio</span>
 		<BbDropdown :items="items" placement="bottom-end">
@@ -357,9 +357,9 @@ must point at a _group_ (not a plain item, not a missing key).
 ```vue
 <template>
 	<div
-		class="flex max-w-md flex-wrap items-center gap-2 rounded-[var(--bb-radius)] border p-2"
+		class="flex max-w-md flex-wrap items-center gap-2 rounded-(--bb-radius) border p-2"
 	>
-		<span class="pr-1 text-xs font-medium text-[color:var(--bb-text-muted)]"
+		<span class="pr-1 text-xs font-medium text-(--bb-text-muted)"
 			>Invoices</span
 		>
 		<BbDropdown :adaptive="false" :items="items" :width="200">
@@ -378,7 +378,7 @@ must point at a _group_ (not a plain item, not a missing key).
 			<BbDropdownGroup id="sort" v-model="sortBy" />
 			<BbDropdownGroup id="tags" v-model="tags" />
 		</BbDropdown>
-		<span class="text-xs text-[color:var(--bb-text-muted)]">
+		<span class="text-xs text-(--bb-text-muted)">
 			Sort: <span data-sort>{{ sortBy }}</span> · Tags:
 			<span data-tags>{{ tags.join(', ') || 'none' }}</span>
 		</span>
@@ -456,11 +456,11 @@ The full grammar:
 ```vue
 <template>
 	<div
-		class="flex max-w-sm flex-wrap items-center gap-2 rounded-[var(--bb-radius)] border p-2"
+		class="flex max-w-sm flex-wrap items-center gap-2 rounded-(--bb-radius) border p-2"
 	>
 		<div class="min-w-0 flex-1">
 			<p class="truncate text-sm font-medium">INV-2048 · Northwind</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Assignees ·
 				<span data-count>{{ assignees.length }} selected</span>
 			</p>
@@ -535,11 +535,9 @@ a valid selection.
 ```vue
 <template>
 	<div
-		class="flex max-w-md flex-wrap items-center gap-2 rounded-[var(--bb-radius)] border p-2"
+		class="flex max-w-md flex-wrap items-center gap-2 rounded-(--bb-radius) border p-2"
 	>
-		<span class="pr-1 text-xs font-medium text-[color:var(--bb-text-muted)]"
-			>Board</span
-		>
+		<span class="pr-1 text-xs font-medium text-(--bb-text-muted)">Board</span>
 		<BbDropdown
 			:adaptive="false"
 			:items="menu"
@@ -560,7 +558,7 @@ a valid selection.
 			<BbDropdownGroup id="board" v-model="board" />
 			<BbDropdownGroup id="assignees" v-model="assignees" />
 		</BbDropdown>
-		<span class="text-xs text-[color:var(--bb-text-muted)]">
+		<span class="text-xs text-(--bb-text-muted)">
 			<span data-board>{{ board ?? 'all boards' }}</span> ·
 			<span data-assignees>{{ assigneeNames || 'anyone' }}</span>
 		</span>
@@ -771,11 +769,9 @@ the edge slots, to replace one row's content use its key.
 ```vue
 <template>
 	<div
-		class="flex max-w-xs items-center gap-2 rounded-[var(--bb-radius)] border p-2"
+		class="flex max-w-xs items-center gap-2 rounded-(--bb-radius) border p-2"
 	>
-		<span class="text-xs font-medium text-[color:var(--bb-text-muted)]"
-			>Workspace</span
-		>
+		<span class="text-xs font-medium text-(--bb-text-muted)">Workspace</span>
 		<!-- `adaptive` is pinned off so the demo behaves identically on any
 		viewport; leave it at the project default in real apps. -->
 		<BbDropdown :adaptive="false" :items="items">
@@ -794,7 +790,7 @@ the edge slots, to replace one row's content use its key.
 			(and inside group headers). Payload is read-only. -->
 			<template #item:prepend="{ item }">
 				<BbIcon
-					class="text-[color:var(--bb-text-muted)]"
+					class="text-(--bb-text-muted)"
 					data-env-dot
 					:icon="envIcon(item.key)"
 					size="xs"
@@ -874,7 +870,7 @@ the sheet's pinned header and footer.
 		</BbButton>
 	</template>
 	<template #header>
-		<div class="px-3 py-2 text-xs font-semibold text-[color:var(--bb-text-muted)]">
+		<div class="px-3 py-2 text-xs font-semibold text-(--bb-text-muted)">
 			Jump to month
 		</div>
 	</template>
@@ -903,11 +899,11 @@ behaves exactly as with a click menu.
 ```vue
 <template>
 	<div
-		class="flex max-w-sm items-center gap-2 rounded-[var(--bb-radius)] border p-2"
+		class="flex max-w-sm items-center gap-2 rounded-(--bb-radius) border p-2"
 	>
 		<div class="min-w-0 flex-1">
 			<p class="truncate text-sm font-medium">INV-2048</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Northwind · €1,240.00 ·
 				<span data-last>{{ last }}</span>
 			</p>
@@ -1221,7 +1217,7 @@ mid-session never swaps a live menu between flyout and sheet.
 | `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
 | `enforceCoherence` | `boolean \| undefined` | `false` |  | Default for pipeline groups: drop selections that are no longer present in a group's current items (e.g. after a `dependencies` re-fetch) from the selection and `v-model`. A group's own `enforceCoherence` overrides this. |
 | `id` | `string \| undefined` |  |  | The identifier of the component. |
-| `items` | `Item[]` | `[]` | yes | Array used to render each dropdown button. They can act as `button`, as `a`, or as `router-link` as they are based on the functionality provided by `BbBaseButton`. Pass a flat array for a single group, nest arrays for divider-separated grou… |
+| `items` | `BbDropdownItem[]` | `[]` | yes | Array used to render each dropdown button. They can act as `button`, as `a`, or as `router-link` as they are based on the functionality provided by `BbBaseButton`. Pass a flat array for a single group, nest arrays for divider-separated grou… |
 | `loadingText` | `string \| undefined` |  |  | Default placeholder text shown while a pipeline group's async items load. A group's own `loadingText` overrides this; both fall back to the localized `common.loadingText` (`'Loading...'`). |
 | `noDataText` | `string \| undefined` |  |  | Default placeholder text shown when a pipeline group resolves to no items. A group's own `noDataText` overrides this; both fall back to the localized `common.noDataText` (`'No data to display'`). |
 | `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Overrides forwarded to the underlying `BbOffCanvas` when `adaptive` renders the sheet on mobile. Merged over the adaptive defaults (`direction: 'bottom'`, `size: 'auto'`, `draggable: true`). Ignored when `adaptive` is `false`. |

package/dist/ai/BbDropdownButton.md

@@ -47,20 +47,16 @@ entry's remaining rows are dropped from the menu.
 
 ```vue
 <template>
-	<div
-		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
-	>
+	<div class="flex max-w-sm flex-col gap-3 rounded-(--bb-radius) border p-3">
 		<div class="flex flex-col gap-0.5">
 			<span class="text-sm font-medium">Invoice INV-2048</span>
-			<span class="text-xs text-[color:var(--bb-text-muted)]">
+			<span class="text-xs text-(--bb-text-muted)">
 				Acme Studio · due Jul 31, 2026
 			</span>
 		</div>
 		<div class="flex items-center gap-2">
 			<BbDropdownButton :items="items" prepend:icon="lucide:check" />
-			<span class="text-xs text-[color:var(--bb-text-muted)]" data-last>{{
-				last
-			}}</span>
+			<span class="text-xs text-(--bb-text-muted)" data-last>{{ last }}</span>
 		</div>
 	</div>
 </template>
@@ -100,12 +96,10 @@ so each export is a real navigation, not an `@click` that fakes a download.
 
 ```vue
 <template>
-	<div
-		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
-	>
+	<div class="flex max-w-sm flex-col gap-3 rounded-(--bb-radius) border p-3">
 		<div class="flex flex-col gap-0.5">
 			<span class="text-sm font-medium">Q2 revenue report</span>
-			<span class="text-xs text-[color:var(--bb-text-muted)]">
+			<span class="text-xs text-(--bb-text-muted)">
 				Acme Studio · Jul 1 – Sep 30, 2026
 			</span>
 		</div>
@@ -115,9 +109,7 @@ so each export is a real navigation, not an `@click` that fakes a download.
 				prepend:icon="lucide:download"
 				variant="outline"
 			/>
-			<span class="text-xs text-[color:var(--bb-text-muted)]" data-export>{{
-				last
-			}}</span>
+			<span class="text-xs text-(--bb-text-muted)" data-export>{{ last }}</span>
 		</div>
 	</div>
 </template>
@@ -205,18 +197,16 @@ manually.
 
 ```vue
 <template>
-	<div
-		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
-	>
+	<div class="flex max-w-sm flex-col gap-3 rounded-(--bb-radius) border p-3">
 		<div class="flex flex-col gap-0.5">
 			<span class="text-sm font-medium">July product changelog</span>
-			<span class="text-xs text-[color:var(--bb-text-muted)]">
+			<span class="text-xs text-(--bb-text-muted)">
 				bitboss-ui · ready to publish
 			</span>
 		</div>
 		<div class="flex items-center gap-2">
 			<BbDropdownButton :items="items" prepend:icon="lucide:rocket" />
-			<span class="text-xs text-[color:var(--bb-text-muted)]" data-status>{{
+			<span class="text-xs text-(--bb-text-muted)" data-status>{{
 				status
 			}}</span>
 		</div>
@@ -272,16 +262,11 @@ not the one that needs a second thought.
 
 ```vue
 <template>
-	<div
-		class="flex max-w-md flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
-	>
+	<div class="flex max-w-md flex-col gap-3 rounded-(--bb-radius) border p-3">
 		<div class="flex items-center justify-between gap-3">
 			<div class="flex min-w-0 flex-col gap-0.5">
 				<span class="text-sm font-medium">acme-web · production</span>
-				<span
-					class="text-xs text-[color:var(--bb-text-muted)]"
-					data-deploy-status
-				>
+				<span class="text-xs text-(--bb-text-muted)" data-deploy-status>
 					{{ status }}
 				</span>
 			</div>
@@ -376,12 +361,10 @@ main button itself — so the control always announces exactly what it will do.
 
 ```vue
 <template>
-	<div
-		class="flex max-w-md flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
-	>
+	<div class="flex max-w-md flex-col gap-3 rounded-(--bb-radius) border p-3">
 		<div class="flex flex-col gap-0.5">
 			<span class="text-sm font-medium">Add usage-based billing #482</span>
-			<span class="text-xs text-[color:var(--bb-text-muted)]" data-merge-status>
+			<span class="text-xs text-(--bb-text-muted)" data-merge-status>
 				{{ status }}
 			</span>
 		</div>