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

package/dist/ai/BbTable.md

@@ -77,7 +77,7 @@ needs is declared here, not in markup:
 ```vue
 <template>
 	<div
-		class="max-w-2xl overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		class="max-w-2xl overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 	>
 		<BbTable
 			caption="Recent invoices"
@@ -163,7 +163,7 @@ const invoices: Invoice[] = [
 // wash matches the design-language attention accent — public API, no internals.
 const rowClass = (invoice: Invoice) =>
 	invoice.status === 'overdue'
-		? 'bg-[color:color-mix(in_oklab,#d97706_8%,var(--bb-panel))]'
+		? 'bg-[color-mix(in_oklab,#d97706_8%,var(--bb-panel))]'
 		: '';
 </script>
 ```
@@ -256,7 +256,7 @@ CSS in a non-scoped style block.
 ```vue
 <template>
 	<div
-		class="max-w-2xl overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		class="max-w-2xl overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 	>
 		<BbTable
 			caption="Invoice status"
@@ -267,8 +267,8 @@ CSS in a non-scoped style block.
 		>
 			<!-- Cell slot: name = the column key (dots/non-word chars become `_`,
 			     dashes are kept).
-			     The glyphs are brand assets from the app's `iconDir`, referenced as
-			     `local:*` names — mapped to full literals, never template-composed. -->
+			     The glyphs are mapped to FULL icon literals, never template-composed
+			     (`lucide:${status}` would defeat the build-time icon scan). -->
 			<template #status="{ content }">
 				<BbBadge
 					:prepend:icon="glyphs[content as Status]"
@@ -282,9 +282,7 @@ CSS in a non-scoped style block.
 			<template #header:amount="{ label }">
 				<span class="inline-flex items-center gap-1">
 					{{ label }}
-					<span class="text-xs font-normal text-[color:var(--bb-text-muted)]"
-						>EUR</span
-					>
+					<span class="text-xs font-normal text-(--bb-text-muted)">EUR</span>
 				</span>
 			</template>
 		</BbTable>
@@ -316,11 +314,11 @@ const labels: Record<Status, string> = {
 	overdue: 'Overdue',
 };
 
-// Status → full-name literals (icons policy: no `local:${status}` templates).
+// Status → full-name literals (icons policy: no `lucide:${status}` templates).
 const glyphs: Record<Status, IconType> = {
-	paid: 'local:check_circle',
-	pending: 'local:clock',
-	overdue: 'local:alert_circle',
+	paid: 'lucide:circle-check',
+	pending: 'lucide:clock',
+	overdue: 'lucide:circle-alert',
 };
 
 const variants: Record<Status, BadgeVariantType> = {
@@ -458,7 +456,7 @@ for "there is nothing to show, here's why."
 		</div>
 
 		<div
-			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+			class="overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 		>
 			<BbTable
 				caption="Team members"
@@ -470,7 +468,7 @@ for "there is nothing to show, here's why."
 				loading-text="Loading members…"
 			>
 				<template #no-data>
-					<p class="p-3 text-center text-sm text-[color:var(--bb-text-muted)]">
+					<p class="p-3 text-center text-sm text-(--bb-text-muted)">
 						No members match your filters yet.
 					</p>
 				</template>
@@ -544,7 +542,7 @@ type ItemsProvider<T> = (
 		<!-- `items` is an async function; the table re-runs it (debounced) whenever
 		     an entry in `dependencies` changes, showing skeletons while it awaits. -->
 		<div
-			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+			class="overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 		>
 			<BbTable
 				caption="Invoices"
@@ -626,6 +624,55 @@ pagination, confirm-delete, toasts) is the records workspace recipe
 (`./recipes/vue/records-workspace.md`), which works unchanged under Inertia or
 Nuxt since the table itself never touches the router.
 
+### Filtering
+
+**There is no `filter` prop, and its absence is not a gap.** Libraries that ship
+one (Quasar's `filter` / `filter-method`, PrimeVue's per-column filters) are
+answering two different questions with one name, and this table answers both
+already — under names that do not contain the word "filter", which is the only
+reason the story looks missing.
+
+On a **server-driven** table, a filter is an input to the fetch. That is
+`dependencies`: list your filter state and the provider re-runs, debounced, with
+out-of-order responses discarded and the previous rows kept on failure. A
+`filter` prop would be a second, weaker spelling of the same thing — one value
+instead of many, and race handling left to you.
+
+On a **client-side** table holding every row, filtering is a computed:
+
+```vue
+<BbTable :items="filteredItems" :columns="columns" />
+```
+
+Always correct, no new prop, and it cannot desync from a `total-items` count the
+way a table that filtered its own rows behind your back would.
+
+Pick the shape by where the rows come from:
+
+| Your situation                         | The filter mechanism                                                                     |
+| -------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Server returns a page at a time        | `:dependencies="[search, status, sort]"` — see § Async items and filters                 |
+| A whole filtered listing, URL-mirrored | The records workspace recipe (chip rail, tabs, `useQueryObject`)                         |
+| Filter UI inside one column's header   | `#header:<key>:append` — keeps the built-in sort button (see § Custom cells and headers) |
+| All rows already in memory             | A computed feeding `items`                                                               |
+
+For the **per-column** case, use the affix slot rather than a full
+`#header:<key>` replacement, or you take over the sort button too:
+
+```vue
+<template #header:status:append>
+	<BbSelectPopover v-model="status" :items="statuses" />
+</template>
+```
+
+The filter control is yours; the table's only job is to refetch when the value
+lands in `dependencies`. That is the same division of labour as sorting, where
+`v-model:sort` reports intent and your provider acts on it.
+
+For a complete worked filter rail — one Filters menu, editable chips, URL
+mirroring, tab counts — read the records workspace recipe rather than assembling
+it here.
+
 ### Pagination
 
 `BbTable` never slices its own data — you do, or the server does. Feed it the
@@ -644,7 +691,7 @@ the same page ref.
 		     announcements (aria-rowcount / aria-rowindex); the actual slicing is
 		     yours (or the server's). -->
 		<div
-			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+			class="overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 		>
 			<BbTable
 				caption="Invoices"
@@ -658,7 +705,7 @@ the same page ref.
 			/>
 		</div>
 		<div class="flex items-center justify-between gap-2">
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				{{ rangeStart }}–{{ rangeEnd }} of {{ invoices.length }}
 			</p>
 			<BbPagination v-model="page" :total-pages="totalPages" />
@@ -738,7 +785,7 @@ third click.
 		     cycle asc → desc → off; the table only REPORTS the model — you sort
 		     the data. -->
 		<div
-			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+			class="overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 		>
 			<BbTable
 				v-model:sort="sort"
@@ -749,7 +796,7 @@ third click.
 				:items="sortedInvoices"
 			/>
 		</div>
-		<p class="text-xs text-[color:var(--bb-text-muted)]">
+		<p class="text-xs text-(--bb-text-muted)">
 			Sort model: <code>{{ JSON.stringify(sort) }}</code>
 		</p>
 	</div>
@@ -861,12 +908,12 @@ The model's contract is what makes a column panel trivial:
 		     where it was. -->
 		<ul
 			aria-label="Columns"
-			class="flex flex-wrap gap-2 text-xs text-[color:var(--bb-text-muted)]"
+			class="flex flex-wrap gap-2 text-xs text-(--bb-text-muted)"
 		>
 			<li
 				v-for="(column, index) in panelColumns"
 				:key="column.key"
-				class="flex items-center gap-1 rounded-[var(--bb-radius-sm)] border border-[color:var(--bb-border)] py-0.5 pl-2 pr-1"
+				class="flex items-center gap-1 rounded-(--bb-radius-sm) border border-(--bb-border) py-0.5 pr-1 pl-2"
 			>
 				<BbCheckbox
 					:label="column.label"
@@ -892,7 +939,7 @@ The model's contract is what makes a column panel trivial:
 			</li>
 		</ul>
 		<div
-			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+			class="overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 		>
 			<BbTable
 				v-model:order="order"
@@ -918,7 +965,7 @@ The model's contract is what makes a column panel trivial:
 				</template>
 			</BbTable>
 		</div>
-		<p class="text-xs text-[color:var(--bb-text-muted)]">
+		<p class="text-xs text-(--bb-text-muted)">
 			Order model: <code>{{ JSON.stringify(order) }}</code> · hidden:
 			<code>{{ JSON.stringify([...hidden]) }}</code>
 		</p>
@@ -1106,7 +1153,7 @@ everywhere in the library, the destructive bulk action is gated by
 		     gated by `useConfirm`. -->
 		<div
 			v-if="selectedCount"
-			class="flex items-center gap-2 rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] bg-[color:var(--bb-muted)] px-2.5 py-1.5"
+			class="flex items-center gap-2 rounded-(--bb-radius) border border-(--bb-border) bg-(--bb-muted) px-2.5 py-1.5"
 		>
 			<span class="text-sm">{{ selectedCount }} selected</span>
 			<BbButton
@@ -1121,7 +1168,7 @@ everywhere in the library, the destructive bulk action is gated by
 		</div>
 
 		<div
-			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+			class="overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 		>
 			<BbTable
 				id="member-selection"
@@ -1260,7 +1307,7 @@ with the current selection, which is exactly where the new rows are known.
 			>
 				{{ filter.label }}
 			</BbButton>
-			<span class="ml-auto text-xs text-[color:var(--bb-text-muted)]">
+			<span class="ml-auto text-xs text-(--bb-text-muted)">
 				{{ selected.length }} selected
 			</span>
 		</div>
@@ -1270,7 +1317,7 @@ with the current selection, which is exactly where the new rows are known.
 		     show the provider-side reconcile, the pattern paginated tables
 		     (where the prop must stay off) still need. -->
 		<div
-			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+			class="overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 		>
 			<BbTable
 				v-model="selected"
@@ -1365,7 +1412,7 @@ const fetchMembers = async (
 		     null) — not an array. `select-text` labels the radio column for
 		     screen readers. -->
 		<div
-			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+			class="overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 		>
 			<BbTable
 				v-model="planId"
@@ -1381,9 +1428,9 @@ const fetchMembers = async (
 				selectable
 			/>
 		</div>
-		<p class="text-sm text-[color:var(--bb-text-muted)]">
+		<p class="text-sm text-(--bb-text-muted)">
 			Chosen plan:
-			<span class="font-medium text-[color:var(--bb-text)]">{{
+			<span class="font-medium text-(--bb-text)">{{
 				chosen ? chosen.name : 'none yet'
 			}}</span>
 		</p>
@@ -1460,7 +1507,7 @@ the read-only `expanded` flag. Drive open/close through the callback; the
 	     you `toggleExpanded` (a callback) and `expanded` (read-only) — drive the
 	     toggle through the callback, never by mutating the slot prop. -->
 	<div
-		class="max-w-2xl overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		class="max-w-2xl overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 	>
 		<BbTable
 			v-model:expanded-items="expanded"
@@ -1478,9 +1525,9 @@ the read-only `expanded` flag. Drive open/close through the callback; the
 			</template>
 
 			<template #expand="{ item }">
-				<div class="bg-[color:var(--bb-muted)] px-3 py-2.5 text-sm">
+				<div class="bg-(--bb-muted) px-3 py-2.5 text-sm">
 					<p class="font-medium">{{ item.client }} · {{ item.number }}</p>
-					<p class="text-xs text-[color:var(--bb-text-muted)]">
+					<p class="text-xs text-(--bb-text-muted)">
 						Issued {{ item.issuedAt }} · net 30 · {{ item.lines }} line items
 					</p>
 				</div>
@@ -1627,7 +1674,7 @@ parent's.
 <template>
 	<div class="flex max-w-2xl flex-col gap-1.5">
 		<div
-			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+			class="overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 		>
 			<BbTable
 				caption="Invoices"
@@ -1639,7 +1686,7 @@ parent's.
 				@resize:column="onResize"
 			/>
 		</div>
-		<p class="text-xs text-[color:var(--bb-text-muted)]">
+		<p class="text-xs text-(--bb-text-muted)">
 			Widths: <code>{{ JSON.stringify(widths) }}</code>
 		</p>
 	</div>
@@ -1744,7 +1791,7 @@ above it. The mechanics:
 	     the parent's tracks, so line items line up under the invoice columns.
 	     The toggle binds the scope's `expandProps` for wired-up aria state. -->
 	<div
-		class="max-w-2xl overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		class="max-w-2xl overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 	>
 		<BbTable
 			v-model:expanded-items="expanded"
@@ -1767,7 +1814,7 @@ above it. The mechanics:
 			</template>
 
 			<template #expand="{ item }">
-				<div class="bg-[color:var(--bb-muted)] px-1 py-1">
+				<div class="bg-(--bb-muted) px-1 py-1">
 					<BbTable
 						:caption="`Line items of ${item.number}`"
 						:columns="lineColumns"
@@ -1961,7 +2008,7 @@ customize the look:
 ```ts
 const rowClass = (item: Invoice) =>
 	item.id === highlighted.value
-		? 'bg-[color:color-mix(in_oklab,var(--bb-danger)_10%,var(--bb-panel))]'
+		? 'bg-[color-mix(in_oklab,var(--bb-danger)_10%,var(--bb-panel))]'
 		: '';
 ```
 
@@ -1975,7 +2022,7 @@ const rowClass = (item: Invoice) =>
 		     box; this example repaints it explicitly via the public `row-class`
 		     API to show how to customize it (here, matching the same tint). -->
 		<div
-			class="min-w-0 flex-1 overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+			class="min-w-0 flex-1 overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 		>
 			<BbTable
 				v-model:highlighted="highlighted"
@@ -1989,15 +2036,15 @@ const rowClass = (item: Invoice) =>
 		</div>
 
 		<aside
-			class="w-full shrink-0 rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3 text-sm sm:w-52"
+			class="w-full shrink-0 rounded-(--bb-radius) border border-(--bb-border) p-3 text-sm sm:w-52"
 		>
 			<template v-if="active">
 				<p class="font-medium">{{ active.client }}</p>
-				<p class="mt-0.5 text-xs text-[color:var(--bb-text-muted)]">
+				<p class="mt-0.5 text-xs text-(--bb-text-muted)">
 					{{ active.number }} · {{ active.amount }}
 				</p>
 			</template>
-			<p v-else class="text-xs text-[color:var(--bb-text-muted)]">
+			<p v-else class="text-xs text-(--bb-text-muted)">
 				Select an invoice to preview it.
 			</p>
 		</aside>
@@ -2037,7 +2084,7 @@ const active = computed(() =>
 // Primary tint for the open row — selection chrome stays on content, not hover.
 const rowClass = (invoice: Invoice) =>
 	invoice.id === highlighted.value
-		? 'cursor-pointer bg-[color:color-mix(in_oklab,var(--bb-primary)_8%,var(--bb-panel))]'
+		? 'cursor-pointer bg-[color-mix(in_oklab,var(--bb-primary)_8%,var(--bb-panel))]'
 		: 'cursor-pointer';
 </script>
 ```
@@ -2068,7 +2115,7 @@ look with `row-class` if the default tint doesn't fit.
 		     focused row, Home/End jump, Enter/Space open it (same path as a
 		     click, so it toggles `highlighted` and emits `click:row`). -->
 		<div
-			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+			class="overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 		>
 			<BbTable
 				v-model:highlighted="openEventId"
@@ -2081,10 +2128,10 @@ look with `row-class` if the default tint doesn't fit.
 				:row-class="rowClass"
 			/>
 		</div>
-		<p class="text-xs text-[color:var(--bb-text-muted)]">
+		<p class="text-xs text-(--bb-text-muted)">
 			Tab into the table, move with the arrow keys, press Enter to open a row.
 			Open event:
-			<span class="font-medium text-[color:var(--bb-text)]">{{
+			<span class="font-medium text-(--bb-text)">{{
 				openEvent ? `${openEvent.actor} — ${openEvent.action}` : 'none'
 			}}</span>
 		</p>
@@ -2130,7 +2177,7 @@ const openEvent = computed(() =>
 // customize it (the public API for doing so).
 const rowClass = (event: AuditEvent) =>
 	event.id === openEventId.value
-		? 'bg-[color:color-mix(in_oklab,var(--bb-primary)_8%,var(--bb-panel))]'
+		? 'bg-[color-mix(in_oklab,var(--bb-primary)_8%,var(--bb-panel))]'
 		: '';
 </script>
 ```
@@ -2164,7 +2211,7 @@ open-in-new-tab for free.
 	<!-- Row-level navigation is offloaded to BbButton: `href` (or `to` in a
 	     router app) makes it a real link, not a JS click handler. -->
 	<div
-		class="max-w-2xl overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		class="max-w-2xl overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 	>
 		<BbTable
 			actions-text="Actions"
@@ -2258,7 +2305,7 @@ rollback on failure, and overlay retirement inside the items function.
 <template>
 	<div class="flex max-w-2xl flex-col gap-1.5">
 		<div
-			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+			class="overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 		>
 			<BbTable
 				caption="Sprint tasks — every cell saves itself"
@@ -2312,10 +2359,10 @@ rollback on failure, and overlay retirement inside the items function.
 			</BbTable>
 		</div>
 
-		<p v-if="lastFailure" class="text-xs text-[color:var(--bb-danger)]">
+		<p v-if="lastFailure" class="text-xs text-(--bb-danger)">
 			{{ lastFailure }}
 		</p>
-		<p class="text-xs text-[color:var(--bb-text-muted)]">
+		<p class="text-xs text-(--bb-text-muted)">
 			No Save button anywhere — edits persist per field, optimistically.
 			BB-121's save always fails and rolls back.
 		</p>
@@ -2530,7 +2577,7 @@ your wrapper actually sits on before sprinkling `min-width: 0` everywhere.)
 
 ```vue
 <div
-	class="max-h-52 max-w-2xl overflow-auto rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+	class="max-h-52 max-w-2xl overflow-auto rounded-(--bb-radius) border border-(--bb-border)"
 >
 	<BbTable
 		caption="Server fleet"
@@ -2649,7 +2696,7 @@ keyboard grammar work untouched. One prop, no knobs.
 	<!-- 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)]"
+		class="max-w-2xl overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 	>
 		<BbTable
 			caption="Ledger"
@@ -2987,7 +3034,7 @@ reader.
 | `actionsText` | `string \| undefined` |  |  | Label used in the header of the actions column. |
 | `align` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Text alignment of the columns. |
 | `caption` | `string \| undefined` |  |  | Caption that describes the content of the table. Used for accessibility purposes. |
-| `columns` | `InternalColumn<T>[] \| undefined` | `[]` |  | Array of definitions of how the columns should be rendered. |
+| `columns` | `BbTableColumn<T>[] \| undefined` | `[]` |  | Array of definitions of how the columns should be rendered. |
 | `compact` | `boolean \| undefined` | `false` |  | Adds a CSS class that applies a compact style to the component. |
 | `dependencies` | `unknown[] \| undefined` | `[]` |  | Defines an array of dependencies that will trigger actions in the component upon change. |
 | `depsDebounceTime` | `number \| undefined` | `0` |  | Timeout used to debounce response to changes to dependencies. |
@@ -3022,7 +3069,7 @@ reader.
 | `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
 | `reorderable` | `boolean \| undefined` | `false` |  | Lets the user reorder the data columns: drag a header cell (AG Grid style — the column moves live under the pointer and a chip with its label follows) or, from the keyboard, use each header's reorder handle (ArrowLeft / ArrowRight move the … |
 | `resizable` | `boolean \| undefined` | `false` |  | Lets the user resize the data columns of a root table: drag the handle on a header's trailing edge (the column follows live, the width commits on release), or press Alt + ArrowLeft / ArrowRight on the focused header; double-click the handle… |
-| `rowClass` | `RowClasses<Item> \| undefined` |  |  | Defines the classes to be passed to each data row. Can also be a function of the row's item for dynamic values. |
+| `rowClass` | `BbTableRowClasses<Item> \| undefined` |  |  | Defines the classes to be passed to each data row. Can also be a function of the row's item for dynamic values. |
 | `selectable` | `boolean \| ((item: Item) => boolean) \| undefined` |  |  | Defines whether the table is selectable. Can be a global boolean that affects all rows or a function that accepts an item and returns a boolean that only affects that item. |
 | `selectAll` | `boolean \| undefined` | `false` |  | Defines whether the "Select all" checkbox is checked. |
 | `selectAllLabel` | `string \| undefined` |  |  | Text of the label used by the "Select all" boolean. |