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

package/dist/ai/guides/ssr-prefill.md

@@ -0,0 +1,120 @@
+# SSR prefill
+
+Five components load their options from a function you give them — `BbSelect`,
+`BbSelectPopover`, `BbTable`, and the checkbox / radio / switch groups. This
+page is about one question: **does that function run on the server?**
+
+The short answer: **only when the host installed an SSR-state adapter.**
+`bitboss-ui/nuxt` installs one for you. Nothing else does, and that is a
+deliberate design, not a gap.
+
+## Why it is conditional
+
+Server-side resolution is only useful if the client starts from the same data.
+The server can resolve `loadCities()` and paint "Milan"; if the client boots
+with an empty list, its first render paints the placeholder instead — and the
+two disagree. Vue calls that a hydration mismatch: a console error in dev, and
+in production the stale server HTML is simply kept, because Vue does not
+re-patch text it did not expect to differ.
+
+So the rule the library follows is:
+
+> Resolve on the server only if the result can reach the client.
+> Otherwise do not resolve on the server at all.
+
+A cold panel for one tick is a much cheaper failure than markup nobody can
+reproduce.
+
+## What happens on each platform
+
+| Host                         | Provider runs on the server? | Client re-fetches on mount? |
+| ---------------------------- | ---------------------------- | --------------------------- |
+| **Nuxt** (`bitboss-ui/nuxt`) | yes                          | no — it reads the payload   |
+| Plain Vue SSR                | no                           | yes                         |
+| Inertia SSR                  | no                           | yes                         |
+| Any client-only app (SPA)    | n/a                          | yes, as always              |
+
+In every row hydration is clean. The difference is only whether the first paint
+already has the data.
+
+## Nuxt: nothing to do
+
+Install the module and you are done.
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({ modules: ['bitboss-ui/nuxt'] });
+```
+
+```vue
+<BbSelect v-model="city" :items="loadCities" item-text="name" item-value="id" />
+```
+
+On the server the provider runs inside `onServerPrefetch`, its rows are written
+into `nuxtApp.payload` under a `bb-items:` key, and the client picks them up
+during setup — before its first render. The provider is called **once, on the
+server**, and the seeded model resolves to its label in the server HTML.
+
+## Any other SSR host: opt in with an adapter
+
+The library cannot import from your framework, so it asks for two methods:
+
+```ts
+import { SSR_STATE_INJECTION_KEY, type SsrStateAdapter } from 'bitboss-ui';
+
+const adapter: SsrStateAdapter = {
+	get: (key) => myPayload[key],
+	set: (key, value) => {
+		myPayload[key] = value;
+	},
+};
+
+app.provide(SSR_STATE_INJECTION_KEY, adapter);
+```
+
+The contract:
+
+- `set` is called on the **server only**, during `onServerPrefetch`, before the
+  component renders.
+- `get` is called on the **client only**, during setup of the same component,
+  before its first render — so whatever the server wrote must already be
+  readable by then. (This is the hard part: your payload has to be rehydrated
+  before the Vue app mounts. Nuxt does this; a hand-rolled SSR setup must too.)
+- Keys are opaque strings namespaced with `bb-items:`, unique per component
+  instance, and identical on both sides.
+
+Provide it at the **app** level (`app.provide`), not inside a component.
+
+## Rules for your provider
+
+- **Return plain, serializable rows.** They go through the host's payload
+  serializer — under Nuxt that is devalue: objects, arrays, dates, maps, sets.
+  Not class instances, not ORM models, not anything carrying methods. If the
+  library spots a function or symbol on a row it warns in dev, drops the
+  server-rendered rows, and lets the client fetch instead — hydration stays
+  clean, you just lose the server-side head start.
+- **Keep it isomorphic.** No `window`, no `document`.
+- **Let it reject safely.** If the provider throws on the server the error is
+  logged, nothing is transferred, and the client loads normally.
+
+## What is NOT transferred
+
+Only the **first** load — the prefill. Everything after it is client-side by
+nature and stays that way:
+
+- a search query the user types,
+- a `dependencies` change re-running the fetch,
+- a page change in `BbTable`.
+
+That is the intent: the transfer exists to make the first paint correct, not to
+cache a session.
+
+## Payload size
+
+Every provider-backed control on an SSR page adds its resolved rows to the
+page payload. For a select that is a handful of options; for a `BbTable` it is
+a page of rows, which is the same data you would otherwise fetch immediately
+after hydration — traded from a second request into first-paint bytes. If a
+particular control's list is large and it is not worth server-rendering, set
+`prefill="interaction"` (or `false` for a search-first select) and it will not
+load on the server at all.

package/dist/ai/index.md

@@ -59,12 +59,12 @@ Start from a recipe when building a whole page or flow — they encode the idiom
 ### Feedback
 
 - [BbAlert](./BbAlert.md) - Shows contextual status messages.
-- [BbBadge](./BbBadge.md) - Displays compact status counters or labels, the floating mode acts as notification dot.
+- [BbBadge](./BbBadge.md) - Displays a compact inline status counter or label. It sits in the flow — for a bubble or dot anchored OVER another element, use BbIndicator (includes the co-located BbBadgeButton export).
 - [BbBadgeButton](./BbBadgeButton.md) - Makes a badge's body interactive: slotted as a direct child of BbBadge it renders the badge body as a real button/link with full BbBaseButton parity, leaving `clearable` free to remain a separate control.
-- [BbIndicator](./BbIndicator.md) - Anchors a notification bubble (count/short text) or a dot over a wrapped element, with floating and corner-placement options.
+- [BbIndicator](./BbIndicator.md) - Anchors a notification bubble (count/short text) or a dot over a wrapped element.
 - [BbProgress](./BbProgress.md) - Visualizes task or operation progress state.
 - [BbSpinner](./BbSpinner.md) - Indicates ongoing loading or pending operations.
-- [BbToast](./BbToast.md) - Shows transient notification messages.
+- [BbToast](./BbToast.md) - Shows transient notification messages (includes the co-located BbToastPortal export).
 - [BbToastPortal](./BbToastPortal.md) - Registers named slot content that toast() renders via `portal`.
 
 ### Inputs
@@ -91,7 +91,7 @@ Start from a recipe when building a whole page or flow — they encode the idiom
 - [BbBreadcrumbs](./BbBreadcrumbs.md) - Renders hierarchical navigation paths.
 - [BbCollapsible](./BbCollapsible.md) - Toggles visibility of collapsible content blocks.
 - [BbPagination](./BbPagination.md) - Navigates paginated data sets by page index.
-- [BbTabs](./BbTabs.md) - Switches between tabbed content views (shadcn-like strip; BbTabRoot enables split layouts).
+- [BbTabs](./BbTabs.md) - Switches between tabbed content views (shadcn-like strip; the co-located BbTabsRoot / BbTabsList / BbTabsPanes exports enable split layouts).
 - [BbTabsList](./BbTabsList.md) - The trigger strip of a split BbTabsRoot layout (renders the tab buttons only).
 - [BbTabsPanes](./BbTabsPanes.md) - The pane host of a split BbTabsRoot layout (renders the tab content only).
 - [BbTabsRoot](./BbTabsRoot.md) - Provide/inject root that lets BbTabsList and BbTabsPanes live in separate layout slots.
@@ -108,7 +108,7 @@ Start from a recipe when building a whole page or flow — they encode the idiom
 - [BbConfirmPortal](./BbConfirmPortal.md) - Registers named slot content that confirm() renders via `portal`.
 - [BbDatePicker](./BbDatePicker.md) - Opens an anchored calendar (and optional time rail) popover on a trigger you own — the date analog of BbColorPalette; also the v-bb-date directive.
 - [BbDialog](./BbDialog.md) - Presents modal dialogs for focused user interactions.
-- [BbDropdown](./BbDropdown.md) - Displays contextual action menus and menu content.
+- [BbDropdown](./BbDropdown.md) - Displays contextual action menus and menu content (includes the co-located BbDropdownGroup export, which is how a selectable group is bound).
 - [BbDropdownButton](./BbDropdownButton.md) - A button with primary action and all other actions collected in a dropdown.
 - [BbDropdownGroup](./BbDropdownGroup.md) - Renderless v-model companion for a group declared in BbDropdown.items, bound by id.
 - [BbOffCanvas](./BbOffCanvas.md) - Shows side-panel overlay content outside normal layout flow.
@@ -222,17 +222,17 @@ Do not use these components directly in consumer code unless the user explicitly
 - [Migration v2→v3: BbCheckbox / BbRadio / BbSwitch](./guides/migration/components/bb-checkbox.md) - reverse polarity inverted (explicit values flip, default layout unchanged), checked narrowed to boolean, color removed, BbRadio's name no longer required.
 - [Migration v2→v3: BbCheckboxGroup / BbRadioGroup / BbSwitchGroup](./guides/migration/components/bb-checkbox-group.md) - labelPosition renamed legendPosition, per-item disabled is now inert (use selectable), color and the option affix slots removed, BbRadioGroup's name no longer required, and the shared bb-cr-container CSS block split into one per group.
 - [Migration v2→v3: BbChip (removed)](./guides/migration/components/bb-chip.md) - BbChip is gone — BbBadge with clearable is the replacement; non-clearable chips were badges all along.
-- [Migration v2→v3: BbCollapsible](./guides/migration/components/bb-collapsible.md) - The tag prop is removed; the root is always a div.
+- [Migration v2→v3: BbCollapsible](./guides/migration/components/bb-collapsible.md) - The tag prop is removed; the root is always a span.
 - [Migration v2→v3: BbColorInput](./guides/migration/components/bb-color-input.md) - picker renamed to eyeDropper.
 - [Migration v2→v3: BbColorPalette](./guides/migration/components/bb-color-palette.md) - flip inverted to disableFlip, showArrow removed, picker renamed eyeDropper, update:open dropped, model updates never emit null.
 - [Migration v2→v3: BbDatePickerInput](./guides/migration/components/bb-date-picker-input.md) - allowWriting inverted to disableWriting and hidePopover renamed to disableCalendar, both with a changed token set; the width prop is removed; adaptive mobile sheet by default; non-floating output carries the local offset instead of UTC `Z` (new `utc` prop restores v2 output).
-- [Migration v2→v3: BbDialog](./guides/migration/components/bb-dialog.md) - showClose inverted to hideClose, several presentation props and the #close/#description slots removed, default widths changed, adaptive bottom sheet on mobile by default, --bb-dialog-* tokens replaced by --bb-panel-p plus locals.
+- [Migration v2→v3: BbDialog](./guides/migration/components/bb-dialog.md) - showClose inverted to hideClose, #close removed (description restored in beta.19), default widths changed, adaptive bottom sheet on mobile by default, --bb-dialog-* tokens replaced by --bb-panel-p plus locals.
 - [Migration v2→v3: BbDropdown](./guides/migration/components/bb-dropdown.md) - Items now expect text as the label and can carry variants/submenus; arrowPadding removed; adaptive mobile sheet on by default.
 - [Migration v2→v3: BbDropdownButton](./guides/migration/components/bb-dropdown-button.md) - autoLoading renamed to disableAutoLoading, disabledWhileLoading and theme removed.
 - [Migration v2→v3: BbDropzone](./guides/migration/components/bb-dropzone.md) - modelValue is typed, accept no longer throws and takes bare tokens, and the hidden native-submit input only renders when name is set.
 - [Migration v2→v3: BbIcon](./guides/migration/components/bb-icon.md) - The required prop is renamed type→icon, color is removed, and the xxl size key becomes 2xl.
 - [Migration v2→v3: BbIntersection](./guides/migration/components/bb-intersection.md) - Removed with no replacement — it wrapped IntersectionObserver and carried no styling; use @vueuse/core's useIntersectionObserver.
-- [Migration v2→v3: BbOffCanvas](./guides/migration/components/bb-offcanvas.md) - direction→side; showClose→hideClose; description and the #close/#description slots removed; size defaults change; adaptive drawer configs unify on offCanvasProps.
+- [Migration v2→v3: BbOffCanvas](./guides/migration/components/bb-offcanvas.md) - direction→side; showClose→hideClose; #close removed (description restored in beta.19); size defaults change; adaptive drawer configs unify on offCanvasProps.
 - [Migration v2→v3: BbPagination](./guides/migration/components/bb-pagination.md) - querykey renamed to queryKey; the loading prop is removed.
 - [Migration v2→v3: BbPopover](./guides/migration/components/bb-popover.md) - Built-in close button, restoreFocus, theme, and the arrow are gone; close affordances move into your content.
 - [Migration v2→v3: BbRating](./guides/migration/components/bb-rating.md) - color removed; name no longer required; the star state modifier renamed --highlighted to --filled/--empty; --bb-rating-size demoted to a local --size; input-position finally works.
@@ -241,7 +241,7 @@ Do not use these components directly in consumer code unless the user explicitly
 - [Migration v2→v3: BbSlider](./guides/migration/components/bb-slider.md) - thumbTranslate inverted to disableThumbTranslate; string model values and color removed.
 - [Migration v2→v3: BbSmoothHeight](./guides/migration/components/bb-smooth-height.md) - The `tag` prop is narrowed to `div | span`, and the inner measuring element now mirrors it instead of always being a `<div>`.
 - [Migration v2→v3: BbSpinner](./guides/migration/components/bb-spinner.md) - The color prop is removed; spinners follow currentColor.
-- [Migration v2→v3: BbTable](./guides/migration/components/bb-table.md) - allowSelectAll inverted to disableSelectAll; loading no longer blanks populated tables and now inerts rows; #loading is first-load-only; #no-data fills a full-width table cell instead of replacing the row; columns gained sortable + rowClass, which collide with same-named consumer fields.
+- [Migration v2→v3: BbTable](./guides/migration/components/bb-table.md) - The table renders as a CSS grid of divs with ARIA roles, not a <table> — every element selector (table/thead/tbody/tr/th/td) under .bb-table matches nothing, #thead/#tbody/#tfoot take role-complete div rows, --fill/--natural-width are gone, column widths drift within documented bounds, copy-to-spreadsheet and print header repetition degrade; allowSelectAll inverted to disableSelectAll; loading no longer blanks populated tables and now inerts rows; #loading is first-load-only; #no-data fills a full-width cell instead of replacing the row; row events drop the selected argument; columns gained sortable + rowClass, which collide with same-named consumer fields.
 - [Migration v2→v3: BbTabs (was BbTab)](./guides/migration/components/bb-tabs.md) - Component renamed; querykey→queryKey; animations default on; label slots renamed and all dynamic names/URL slugs normalized; the entire .bb-tab BEM tree renamed to .bb-tabs / .bb-tabs-list / .bb-tabs-panes.
 - [Migration v2→v3: BbTag](./guides/migration/components/bb-tag.md) - modelValue is strictly string[] now, multiple is removed, and duplicates are rejected case-insensitively by default.
 - [Migration v2→v3: BbTextInput](./guides/migration/components/bb-text-input.md) - The type prop narrows to the text-like input types — number/date values must move to their dedicated components; a bare `floating` attribute was never a prop, the spelling is label-mode="floating".
@@ -252,4 +252,5 @@ Do not use these components directly in consumer code unless the user explicitly
 - [Migration v2→v3: useBroadcastChannelInstance](./guides/migration/components/use-broadcast-channel-instance.md) - Removed — cross-tab messaging is not a UI concern; use useBroadcastChannel from @vueuse/core.
 - [Options and Items Playbook](./guides/options-items-playbook.md) - How item-driven components turn raw domain items into options — mapping, value identity, model seeding, and the supported ways to disable choices.
 - [Page Shell](./guides/page-shell.md) - App-side page layout — topbar, content, and a right details sidebar driven by a stack-based context (push a record to peek it, pop to go back). The implementation ships in the per-platform Layout Scaffold recipe; this guide covers when and how to use it.
+- [ssr-prefill](./guides/ssr-prefill.md) - Guide for ssr-prefill usage and decision-making context.
 - [Validated Forms (vee-validate)](./guides/validated-forms.md) - The `bitboss-ui/validated` entrypoint — form controls pre-wired to vee-validate. Global rules give an effort-free `rules="required|email"` string syntax; BbForm hosts the form; requiredAsterisk marks required fields.

package/dist/ai/recipes/inertia/approvals-inbox.md

@@ -596,7 +596,6 @@ export function useApprovalsInbox(): ApprovalsInboxContext {
 				v-model:highlighted="ctx.highlighted.value"
 				v-model:select-all="ctx.table.all.value"
 				v-model:unselected-items="ctx.table.unselected.value"
-				actions
 				caption="Expense approvals"
 				:columns="columns"
 				compact

package/dist/ai/recipes/inertia/inline-edit-workspace.md

@@ -826,7 +826,6 @@ export function useBacklogWorkspace(): BacklogWorkspaceContext {
 				v-model:highlighted="highlightedIssue"
 				v-model:select-all="ctx.table.all.value"
 				v-model:unselected-items="ctx.table.unselected.value"
-				actions
 				caption="Sprint 24 backlog"
 				:columns="columns"
 				compact

package/dist/ai/recipes/inertia/layout-scaffold.md

@@ -648,7 +648,11 @@ paints a selected row but opens nothing is a dead affordance.
 
 `.plain-link`, `.table-flush` and the row tints are project CSS by design (the
 library ships no such classes), but they are the _same_ project CSS on every
-workspace page. Author them **once**, next to the layout, and import that file
+workspace page. (`.table-flush`'s edge-inset rules address the table through
+its grid containers — `> .bb-table__table > .bb-table__body > [role='row'] >
+:first-child` — never through `table`/`tbody`/`tr`/`td`, which the table no
+longer renders; the canonical block is in the BbTable guide § Styling hooks.)
+Author them **once**, next to the layout, and import that file
 from the app entry — not per page, and never copy-pasted into a page's
 `<style scoped>`, which is how three pages end up with three underline colours.
 

package/dist/ai/recipes/inertia/ownership-atlas.md

@@ -63,19 +63,21 @@ OwnerPaginator::make(...), 'tabCounts' => [...], 'ownerOptions' => [...]])` —
   the page.
 - **The expand row is a real nested `BbTable` that inherits the parent's
   column tracks.** `inherit-column-widths` snaps the holdings table onto the
-  owners table's grid; because the parent is `selectable`, every child
-  column carries an explicit `snap` starting at `1` (`snap: 1…4`), so
-  Resource sits exactly under Owner and the right-aligned $/mo columns share
-  one edge. This is the recipe's signature move — the full defense is in
+  owners table's grid; every child column carries an explicit `snap` naming
+  the parent column it sits under (`snap: 'name'` … `'monthly'` — the
+  parent's `select` column is accounted for by name), so Resource sits
+  exactly under Owner and the right-aligned $/mo columns share one edge. This is the recipe's signature move — the full defense is in
   "Why it is built this way" and in the
   [BbTable guide](../../BbTable.md) ("Nested tables that align with the
   parent").
 - **Page-level cell-padding overrides are scoped with direct-child
   combinators.** The full-bleed treatment (`.table-flush`) pads the outer
-  table's first/last cells via `:deep(> table > thead > tr > th:first-child)`
-  — a bare descendant selector would also hit the nested table and clobber
-  the structural offset padding it computes to stay flush with the parent
-  grid.
+  table's first/last cells via
+  `:deep(> .bb-table__table > .bb-table__head > [role='row'] > :first-child)`
+  — the table is a CSS grid of roled `div`s, not a `<table>`, so the chain
+  runs through its container classes, and a bare descendant selector would
+  also hit the nested table (inside `.bb-table-expand__cell`) and clobber the
+  structural offset padding it computes to stay flush with the parent grid.
 - **Expansion is page state, not table-internal state.** `expanded` (owner
   ids) lives in the context and binds through `v-model:expanded-items`, so
   the toolbar (expand-all/collapse-all), the bulk bar (expand selected) and
@@ -190,7 +192,8 @@ one-off pixel inset per page:
 
 `--table-identity-lead` is the width of the identity cell's toggle track, so
 the two can never drift. Set the knob on the nest container — never pad the
-child's `tbody` alone, which reintroduces the edge mismatch the snap removed.
+child's body (`.bb-table__body`) alone, which reintroduces the edge mismatch
+the snap removed.
 
 ## The code
 
@@ -568,7 +571,6 @@ export function useOwnershipAtlas(): OwnershipAtlasContext {
 				v-model:highlighted="highlightedOwner"
 				v-model:select-all="ctx.table.all.value"
 				v-model:unselected-items="ctx.table.unselected.value"
-				actions
 				actions-text="Holdings"
 				caption="Resource owners"
 				class="table-flush"
@@ -780,25 +782,42 @@ const rowClass = (item: Owner) => {
 }
 
 /* Direct-child combinators keep these overrides on the OWNER table's own
-   cells. A bare `:deep(tbody td:first-child)` would also match the nested
-   holdings table and clobber the structural offset padding it computes to
-   stay flush with the parent grid — the one selector mistake that silently
-   breaks nested-table alignment. */
-.table-flush :deep(> table > thead > tr > th:first-child),
+   cells. The table is a CSS grid of roled divs (no <table>/<tr>/<td>), so the
+   chain runs through its container classes. A bare
+   `:deep([role='cell']:first-child)` would also match the nested holdings
+   table and clobber the structural offset padding it computes to stay flush
+   with the parent grid — the one selector mistake that silently breaks
+   nested-table alignment. */
 .table-flush
-	:deep(> table > tbody > tr > td:first-child:not(.bb-table-expand__cell)) {
+	:deep(> .bb-table__table > .bb-table__head > [role='row'] > :first-child),
+.table-flush
+	:deep(
+		> .bb-table__table
+			> .bb-table__body
+			> [role='row']
+			> :first-child:not(.bb-table-expand__cell)
+	) {
 	padding-inline-start: var(--page-inset);
 }
 
-.table-flush :deep(> table > thead > tr > th:last-child),
 .table-flush
-	:deep(> table > tbody > tr > td:last-child:not(.bb-table-expand__cell)) {
+	:deep(> .bb-table__table > .bb-table__head > [role='row'] > :last-child),
+.table-flush
+	:deep(
+		> .bb-table__table
+			> .bb-table__body
+			> [role='row']
+			> :last-child:not(.bb-table-expand__cell)
+	) {
 	padding-inline-end: var(--page-inset);
 }
 
 /* Expand rows stay edge-to-edge so the nested table can inherit the parent
    tracks without an extra inset shifting everything sideways. */
-.table-flush :deep(> table > tbody > tr > td.bb-table-expand__cell) {
+.table-flush
+	:deep(
+		> .bb-table__table > .bb-table__body > [role='row'] > .bb-table-expand__cell
+	) {
 	padding-inline: 0;
 }
 
@@ -882,10 +901,10 @@ defineProps<{ owner: Owner }>();
  * the parent's first data column, and that inset is what reads as hierarchy.
  */
 const columns: Array<BbTableColumn<Holding>> = [
-	{ key: 'name', label: 'Resource', snap: 1 },
-	{ key: 'kind', label: 'Type', snap: 2 },
-	{ key: 'status', label: 'Status', snap: 3 },
-	{ key: 'monthlyCost', label: '$ / mo', align: 'right', snap: 4 },
+	{ key: 'name', label: 'Resource', snap: 'name' },
+	{ key: 'kind', label: 'Type', snap: 'team' },
+	{ key: 'status', label: 'Status', snap: 'region' },
+	{ key: 'monthlyCost', label: '$ / mo', align: 'right', snap: 'monthly' },
 ];
 
 const money = (value: number) =>
@@ -1304,7 +1323,7 @@ export interface OwnerDetail extends Owner {
   widths.** `inherit-column-widths` is the whole alignment mechanism: the
   holdings table reads the owners table's measured tracks, so Resource sits
   under Owner and both $/mo columns share one right edge at every viewport
-  width. Two hand-maintained `<colgroup>`s (or two tables that merely look
+  width. Two hand-maintained width lists (or two tables that merely look
   similar) drift apart the first time a label changes; the inheritance
   cannot.
 - **Every child column snaps, and the base is 1.** The parent is
@@ -1321,11 +1340,12 @@ export interface OwnerDetail extends Owner {
 - **Cell-padding overrides use direct-child combinators.** `.table-flush`
   bleeds the owner table past the page padding and re-adds the inset on the
   outermost cells — but only via
-  `:deep(> table > tbody > tr > td:first-child)`. A bare descendant
-  selector would also hit the nested table's cells and clobber the offset
-  padding it computes to stay on the parent grid. The expand cell itself is
-  excluded from the inset and zero-padded, so the nested table gets the full
-  row width to snap within.
+  `:deep(> .bb-table__table > .bb-table__body > [role='row'] > :first-child)`
+  (the table is a CSS grid of roled `div`s; `table`/`tbody`/`tr`/`td`
+  selectors match nothing). A bare descendant selector would also hit the
+  nested table's cells and clobber the offset padding it computes to stay on
+  the parent grid. The expand cell itself is excluded from the inset and
+  zero-padded, so the nested table gets the full row width to snap within.
 - **Expansion is rung-3 page state.** `expanded` lives in the context
   because four surfaces touch it: the per-row control, the toolbar's
   expand-all/collapse-all, the bulk bar's Expand, and the peek's "Expand in

package/dist/ai/recipes/inertia/record-form.md

@@ -817,7 +817,6 @@ const ctx = useInvoiceForm();
 		<!-- Inline-editing table (§6.3): every editable cell type is its own
 		     leaf. The amount column is virtual — computed from the row. -->
 		<BbTable
-			actions
 			caption="Invoice line items"
 			:columns="columns"
 			compact

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

@@ -531,7 +531,6 @@ export function useInvoicesWorkspace(): InvoicesWorkspaceContext {
 				v-model="ctx.table.selected.value"
 				v-model:select-all="ctx.table.all.value"
 				v-model:unselected-items="ctx.table.unselected.value"
-				actions
 				caption="Invoices"
 				:columns="columns"
 				compact
@@ -814,7 +813,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',
@@ -866,10 +869,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"
@@ -903,9 +906,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/inertia/upload-center.md

@@ -687,7 +687,6 @@ export function useUploadCenter(): UploadCenterContext {
 				v-model="ctx.table.selected.value"
 				v-model:select-all="ctx.table.all.value"
 				v-model:unselected-items="ctx.table.unselected.value"
-				actions
 				caption="Expense receipts"
 				:columns="columns"
 				compact

package/dist/ai/recipes/nuxt/approvals-inbox.md

@@ -567,7 +567,6 @@ export function useApprovalsInbox(): ApprovalsInboxContext {
 
 			<BbTable
 				id="approvals-table"
-				actions
 				caption="Expense approvals"
 				:columns="columns"
 				compact

package/dist/ai/recipes/nuxt/inline-edit-workspace.md

@@ -804,7 +804,6 @@ export function useBacklogWorkspace(): BacklogWorkspaceContext {
 			<BbTable
 				id="backlog-table"
 				v-model:highlighted="highlightedIssue"
-				actions
 				caption="Sprint 24 backlog"
 				:columns="columns"
 				compact

package/dist/ai/recipes/nuxt/layout-scaffold.md

@@ -648,7 +648,11 @@ paints a selected row but opens nothing is a dead affordance.
 
 `.plain-link`, `.table-flush` and the row tints are project CSS by design (the
 library ships no such classes), but they are the _same_ project CSS on every
-workspace page. Author them **once**, next to the layout, and import that file
+workspace page. (`.table-flush`'s edge-inset rules address the table through
+its grid containers — `> .bb-table__table > .bb-table__body > [role='row'] >
+:first-child` — never through `table`/`tbody`/`tr`/`td`, which the table no
+longer renders; the canonical block is in the BbTable guide § Styling hooks.)
+Author them **once**, next to the layout, and import that file
 from the app entry — not per page, and never copy-pasted into a page's
 `<style scoped>`, which is how three pages end up with three underline colours.
 

package/dist/ai/recipes/nuxt/record-form.md

@@ -846,7 +846,6 @@ const ctx = useInvoiceForm();
 		<!-- Inline-editing table (§6.3): every editable cell type is its own
 		     leaf. The amount column is virtual — computed from the row. -->
 		<BbTable
-			actions
 			caption="Invoice line items"
 			:columns="columns"
 			compact

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

@@ -534,7 +534,6 @@ export function useInvoicesWorkspace(): InvoicesWorkspaceContext {
 
 			<BbTable
 				id="invoices-table"
-				actions
 				caption="Invoices"
 				:columns="columns"
 				compact
@@ -802,7 +801,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',
@@ -854,10 +857,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"
@@ -891,9 +894,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/nuxt/upload-center.md

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

package/dist/ai/recipes/vue/approvals-inbox.md

@@ -502,7 +502,6 @@ export function useApprovalsInbox(): ApprovalsInboxContext {
 
 			<BbTable
 				id="approvals-table"
-				actions
 				caption="Expense approvals"
 				:columns="columns"
 				compact

package/dist/ai/recipes/vue/inline-edit-workspace.md

@@ -706,7 +706,6 @@ export function useBacklogWorkspace(): BacklogWorkspaceContext {
 			<BbTable
 				id="backlog-table"
 				v-model:highlighted="highlightedIssue"
-				actions
 				caption="Sprint 24 backlog"
 				:columns="columns"
 				compact

package/dist/ai/recipes/vue/layout-scaffold.md

@@ -648,7 +648,11 @@ paints a selected row but opens nothing is a dead affordance.
 
 `.plain-link`, `.table-flush` and the row tints are project CSS by design (the
 library ships no such classes), but they are the _same_ project CSS on every
-workspace page. Author them **once**, next to the layout, and import that file
+workspace page. (`.table-flush`'s edge-inset rules address the table through
+its grid containers — `> .bb-table__table > .bb-table__body > [role='row'] >
+:first-child` — never through `table`/`tbody`/`tr`/`td`, which the table no
+longer renders; the canonical block is in the BbTable guide § Styling hooks.)
+Author them **once**, next to the layout, and import that file
 from the app entry — not per page, and never copy-pasted into a page's
 `<style scoped>`, which is how three pages end up with three underline colours.