bitboss-ui 3.0.0-beta.4 → 3.0.0-beta.8

package/dist/ai/changelog.json

@@ -1,12 +1,12 @@
 {
 	"schemaVersion": 1,
 	"library": "bitboss-ui",
-	"version": "3.0.0-beta.4",
+	"version": "3.0.0-beta.8",
 	"upgrade": "v2-to-v3",
 	"guide": "ai/guides/migration/v2-to-v3.md",
 	"summary": {
 		"renames": 9,
-		"behaviourBreaks": 29
+		"behaviourBreaks": 43
 	},
 	"breaking": [
 		{
@@ -279,6 +279,90 @@
 			"description": "BbTable #no-data fills the table's own full-width <td> (was: the slot replaced the empty-state <tr>)",
 			"ruling": "F#/no-data-shell",
 			"guide": "components/bb-table.md"
+		},
+		{
+			"kind": "behaviour",
+			"description": "BbTable row events click:row / contextmenu:row / dblclick:row emit (event, item) with item the RAW record (was the internal row wrapper with the record at row.item) and no trailing selected boolean",
+			"ruling": "owner 2026-08-25, plans/BBTABLE-GRID.md",
+			"guide": "components/bb-table.md § Row events"
+		},
+		{
+			"kind": "behaviour",
+			"description": "BbTable: hiding a column with thClass/tdClass + display: none (the v2/early-v3 narrow-screen recipe) no longer works — a hidden grid item keeps its track and shifts the following cells; remove the column from columns instead",
+			"ruling": "grid substrate, plans/BBTABLE-GRID.md",
+			"guide": "components/bb-table.md § Do not override; guide § Narrow screens"
+		},
+		{
+			"kind": "behaviour",
+			"description": "BbTable renders a CSS grid of divs with ARIA roles, not a <table>: every element selector under .bb-table (table/thead/tbody/tfoot/caption/tr/th/td/colgroup/col) matches nothing. Every .bb-table* class survives; .bb-table__table/__head/__body/__foot + [role=row]/[role=columnheader]/[role=cell] are the blessed translation (no data-* hooks, no shim classes)",
+			"ruling": "plans/BBTABLE-GRID.md § Migration & ecosystem",
+			"guide": "components/bb-table.md § Selector translation"
+		},
+		{
+			"kind": "behaviour",
+			"description": "BbTable #thead / #tbody / #tfoot inner markup: role-complete <div role=\"row\"> holding <div role=\"columnheader\\",
+			"ruling": "cell\"> — never <tr>/<th>/<td>; #tfoot's columnCount now feeds grid-column: span N / 1 / -1 (+ aria-colspan), not colspan. A custom #thead over an empty table publishes no tracks",
+			"guide": "plans/BBTABLE-GRID.md § Non-negotiables (exception 1)"
+		},
+		{
+			"kind": "behaviour",
+			"description": "BbTable --fill custom property removed (not republished) — it fed the fixed-layout self-correction loop the grid does not have",
+			"ruling": "plans/BBTABLE-GRID.md § Tracks (RULED 2026-08-26)",
+			"guide": "components/bb-table.md § --fill and --natural-width are removed"
+		},
+		{
+			"kind": "behaviour",
+			"description": "BbTable --natural-width custom property removed (not republished) — republishing the resolved-track sum would publish the container width under a \"natural\" name",
+			"ruling": "plans/BBTABLE-GRID.md § Tracks (RULED 2026-08-26)",
+			"guide": "components/bb-table.md § --fill and --natural-width are removed"
+		},
+		{
+			"kind": "behaviour",
+			"description": "BbTable track-distribution drift: surplus split equally among auto columns (748/52 → 544/256), constrained wrapping grows tracks by equal increments (~22% narrower long column, taller rows), frozen+auto ≤ ~19px/column, all-frozen tables no longer inflate the select/actions columns, scroll-container cells no longer floor the column (max-width: 0 ellipsis trick breaks), % widths in an overflowing table resolve against min-content (30%: 181 → 303px), expand-row content never widens parent columns, orphan snap → auto. Overflow threshold, wrap floor, frozen px and fixed equal split are exact",
+			"ruling": "plans/BBTABLE-GRID.md § Tracks + § v2.1",
+			"guide": "components/bb-table.md § Column widths: what holds and what drifts"
+		},
+		{
+			"kind": "behaviour",
+			"description": "BbTable copy-to-spreadsheet degrades: Chrome's selection serializer keys off computed display, so a selected grid pastes one value per line (was one cell per column). Accepted; sanctioned path = app-level \"copy as TSV from the items model\" recipe (queued, not shipped)",
+			"ruling": "plans/BBTABLE-GRID.md § Migration & ecosystem (7)",
+			"guide": "components/bb-table.md § Copy-to-spreadsheet degrades"
+		},
+		{
+			"kind": "behaviour",
+			"description": "BbTable print header repetition lost — <thead> page-repetition has no grid equivalent; data rows get break-inside: avoid",
+			"ruling": "plans/BBTABLE-GRID.md § Migration & ecosystem (8)",
+			"guide": "components/bb-table.md § Print: header repetition is gone"
+		},
+		{
+			"kind": "behaviour",
+			"description": "BbTable: global element CSS (table/td resets, .prose table, stray td { padding }) silently stops reaching the table — immunity benefit AND a silent look change on pages that leaned on it",
+			"ruling": "plans/BBTABLE-GRID.md § Migration & ecosystem (9)",
+			"guide": "components/bb-table.md § Global element CSS no longer reaches the table"
+		},
+		{
+			"kind": "behaviour",
+			"description": "BbTable browser floor raised to subgrid engines (Chrome/Edge 117, Firefox 71, Safari 16), block align-content centring from Chrome 123 / Safari 17.4 / Firefox 125; no @supports fallback",
+			"ruling": "plans/BBTABLE-GRID.md § Non-negotiables + § CSS port rules",
+			"guide": "components/bb-table.md § Browser floor"
+		},
+		{
+			"kind": "behaviour",
+			"description": "BbTable contain: inline-size (+ min-width: 0, grid-column: 1 / -1) on the expand / no-data / loading cells is load-bearing — overriding it lets full-span content resize the tracks (runaway loop with a nested inheriting table); joins gap: 0 on the root and nowrap on the actions cell in the do-not-override list",
+			"ruling": "plans/BBTABLE-GRID.md § Measurement & track publishing",
+			"guide": "components/bb-table.md § Do not override"
+		},
+		{
+			"kind": "behaviour",
+			"description": "BbTable caption reading-order micro-drift: .bb-table-caption is a div before the role=table root (named via aria-labelledby), no longer the table's first child",
+			"ruling": "plans/BBTABLE-GRID.md § Accessibility",
+			"guide": "components/bb-table.md § Small semantic and visual changes"
+		},
+		{
+			"kind": "behaviour",
+			"description": "BbTable busy bar now rides with the stuck header under fixed-headers (sticky moved to the .bb-table__head rowgroup; multi-row #thead heads stack instead of overlapping; aria-rowcount = totalItems + 1)",
+			"ruling": "plans/BBTABLE-GRID.md § Sticky + § v2.1",
+			"guide": "components/bb-table.md § Small semantic and visual changes"
 		}
 	]
 }

package/dist/ai/components.json

@@ -1,8 +1,8 @@
 {
 	"schemaVersion": 1,
 	"library": "bitboss-ui",
-	"version": "3.0.0-beta.4",
-	"generatedAt": "2026-08-25T12:52:57.898Z",
+	"version": "3.0.0-beta.8",
+	"generatedAt": "2026-08-26T17:02:06.381Z",
 	"composables": [
 		{
 			"name": "useBbConfig",
@@ -12674,7 +12674,7 @@
 					"name": "fixed",
 					"type": "boolean | undefined",
 					"required": false,
-					"description": "Defines the table layout as fixed\nmaking each column take up the same amount of space."
+					"description": "Splits the width equally among the columns that declare no `width`\n(each undeclared column becomes a `minmax(0, 1fr)` track)\nmaking each column take up the same amount of space."
 				},
 				{
 					"name": "fixedColumns",
@@ -12693,7 +12693,7 @@
 					"name": "headerRowClass",
 					"type": "Classes | undefined",
 					"required": false,
-					"description": "Defines the classes to be passed to the header `<tr>`."
+					"description": "Defines the classes to be passed to the header row."
 				},
 				{
 					"name": "highlighted",
@@ -12712,7 +12712,7 @@
 					"name": "inheritColumnWidths",
 					"type": "string | boolean | undefined",
 					"required": false,
-					"description": "Opt a nested table into inheriting its column widths from an ancestor\ntable's matching tracks (accounting for `select`/`actions` columns). This\nalso forces `table-layout: fixed`, so it is **off by default** — a nested\ntable renders independently unless you ask for alignment.\n- `false` (the default): do not inherit; size independently.\n- `true`: inherit from the nearest ancestor table.\n- a table id (string): inherit from the specific ancestor in the chain with\n  that id rather than the immediate parent. Use this when an intermediate\n  table has a different column count, so the extra columns would otherwise\n  misalign against it."
+					"description": "Opt a nested table into inheriting its column widths from an ancestor\ntable's matching tracks (accounting for `select`/`actions` columns). This\nalso makes the parent's tracks authoritative, so it is **off by default** — a nested\ntable renders independently unless you ask for alignment.\n- `false` (the default): do not inherit; size independently.\n- `true`: inherit from the nearest ancestor table.\n- a table id (string): inherit from the specific ancestor in the chain with\n  that id rather than the immediate parent. Use this when an intermediate\n  table has a different column count, so the extra columns would otherwise\n  misalign against it."
 				},
 				{
 					"name": "interactiveWhileLoading",
@@ -12811,7 +12811,7 @@
 					"name": "rowClass",
 					"type": "RowClasses<Item> | undefined",
 					"required": false,
-					"description": "Defines the classes to be passed to each data `<tr>`. Can also be a\nfunction of the row's item for dynamic values."
+					"description": "Defines the classes to be passed to each data row. Can also be a\nfunction of the row's item for dynamic values."
 				},
 				{
 					"name": "selectable",
@@ -12849,13 +12849,13 @@
 					"name": "tdClass",
 					"type": "ColumnClasses<Item> | undefined",
 					"required": false,
-					"description": "Defines the classes to be passed to the `<td>` elements. Can also be a function for dynamic values."
+					"description": "Defines the classes to be passed to every data cell. Can also be a function for dynamic values."
 				},
 				{
 					"name": "thClass",
 					"type": "Classes | undefined",
 					"required": false,
-					"description": "Defines the classes to be passed to the `<th>`."
+					"description": "Defines the classes to be passed to every header cell."
 				},
 				{
 					"name": "totalItems",
@@ -12880,15 +12880,15 @@
 			"events": [
 				{
 					"name": "click:row",
-					"signature": "(e: \"click:row\", event: MouseEvent, item: any, selected: boolean): void"
+					"signature": "(e: \"click:row\", event: MouseEvent, item: any): void"
 				},
 				{
 					"name": "contextmenu:row",
-					"signature": "(e: \"contextmenu:row\", event: MouseEvent, item: any, selected: boolean): void"
+					"signature": "(e: \"contextmenu:row\", event: MouseEvent, item: any): void"
 				},
 				{
 					"name": "dblclick:row",
-					"signature": "(e: \"dblclick:row\", event: MouseEvent, item: any, selected: boolean): void"
+					"signature": "(e: \"dblclick:row\", event: MouseEvent, item: any): void"
 				},
 				{
 					"name": "item:selected",
@@ -12939,6 +12939,16 @@
 					"type": "{ text: string; }",
 					"description": "Replaces the default actions header cell content."
 				},
+				{
+					"name": "header:append",
+					"type": "BbTableHeaderAffixSlotProps<Item>",
+					"description": "Content rendered after every data column's header cell content — the\nlabel + sort control, or the column's own `header:<key>` replacement.\nA column's `header:<key>:append` slot wins over this one for that\ncolumn; they never stack. Branch on `columnKey` for per-column output."
+				},
+				{
+					"name": "header:prepend",
+					"type": "BbTableHeaderAffixSlotProps<Item>",
+					"description": "Content rendered before every data column's header cell content — the\nlabel + sort control, or the column's own `header:<key>` replacement.\nA column's `header:<key>:prepend` slot wins over this one for that\ncolumn; they never stack. Branch on `columnKey` for per-column output."
+				},
 				{
 					"name": "header:select",
 					"type": "{ multiple: boolean; selectAll: boolean; text: string; }",
@@ -12952,7 +12962,7 @@
 				{
 					"name": "no-data",
 					"type": "object",
-					"description": "Content shown when the items list is empty and not loading. It fills the\ntable's own full-width empty-state cell (the colspan already accounts for\nthe selection/actions columns), so provide the *content* — a message, an\nillustration, a \"clear filters\" button — never a `<tr>`/`<td>` of your own."
+					"description": "Content shown when the items list is empty and not loading. It fills the\ntable's own full-width empty-state cell (it already spans the\nselection/actions columns), so provide the *content* — a message, an\nillustration, a \"clear filters\" button — never a row/cell of your own."
 				},
 				{
 					"name": "select",
@@ -12962,17 +12972,17 @@
 				{
 					"name": "tbody",
 					"type": "object",
-					"description": "Replaces the entire `<tbody>` element. Use when you need full control over the body markup."
+					"description": "Replaces the content of the body row group (`.bb-table__body`). Use when\nyou need full control over the body markup. Provide role-complete rows —\n`<div role=\"row\">` holding one `<div role=\"cell\">` per column — never a\n`<tr>`/`<td>`. A full-width cell spans with `grid-column: 1 / -1`."
 				},
 				{
 					"name": "tfoot",
 					"type": "{ columnCount: number; }",
-					"description": "Replaces the entire `<tfoot>` element. Use when you need full control over the footer markup."
+					"description": "Fills the footer row group (`.bb-table__foot`). Use when you need a\nfooter. Provide role-complete rows — `<div role=\"row\">` holding\n`<div role=\"cell\">` elements — never a `<tr>`/`<td>`."
 				},
 				{
 					"name": "thead",
 					"type": "object",
-					"description": "Replaces the entire `<thead>` element. Use when you need full control over the header markup."
+					"description": "Replaces the content of the header row group (`.bb-table__head`). Use when\nyou need full control over the header markup. The table is a CSS grid,\nnot a `<table>`: provide role-complete rows — `<div role=\"row\">` holding\none `<div role=\"columnheader\">` per column — and never a `<tr>`/`<th>`.\nRows are subgrid rows, so each cell lands on the matching column track."
 				}
 			],
 			"exposed": [],

package/dist/ai/guides/design-language.md

@@ -53,20 +53,20 @@ naming rules, the emphasis ladder) lives in
 
 ### Surfaces & structure
 
-| Token                 | Meaning                                                           |
-| --------------------- | ----------------------------------------------------------------- |
-| `--bb-panel`          | Surface/background color of panels, popovers, dialogs             |
-| `--bb-muted`          | Subtle/disabled surface (derived, neutral)                        |
-| `--bb-hover`          | Hover fill for **affordances** (buttons, links, controls)         |
-| `--bb-surface-hover`  | Hover fill for **passive surfaces** (rows, cells, days) — fainter |
-| `--bb-pressed`        | Neutral pressed/active fill                                       |
-| `--bb-border`         | Border color; pair with `--bb-border-w` (1px)                     |
-| `--bb-radius`         | Corner radius of controls (8px)                                   |
-| `--bb-radius-surface` | Corner radius of large surfaces (derived, ×1.8)                   |
-| `--bb-radius-sm`      | Corner radius of small nested elements (derived)                  |
-| `--bb-shadow`         | Global elevation shadow                                           |
-| `--bb-panel-p`        | Content padding of large surfaces (dialog, off-canvas)            |
-| `--bb-z-overlay`      | Z-index for overlays (10)                                         |
+| Token                 | Meaning                                                                                                                           |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `--bb-panel`          | Surface/background color of panels, popovers, dialogs                                                                             |
+| `--bb-muted`          | Subtle/disabled surface (derived, neutral)                                                                                        |
+| `--bb-hover`          | Hover fill for **affordances** (buttons, links, controls)                                                                         |
+| `--bb-surface-hover`  | Hover fill for **passive surfaces** (rows, cells, days) — fainter                                                                 |
+| `--bb-pressed`        | Neutral pressed/active fill                                                                                                       |
+| `--bb-border`         | Border color; pair with `--bb-border-w` (1px)                                                                                     |
+| `--bb-radius`         | Corner radius of controls (8px)                                                                                                   |
+| `--bb-radius-surface` | Corner radius of large surfaces (derived, ×1.8)                                                                                   |
+| `--bb-radius-sm`      | Corner radius of small nested elements (derived)                                                                                  |
+| `--bb-shadow`         | Global elevation shadow                                                                                                           |
+| `--bb-panel-p`        | Content padding of large surfaces (dialog, off-canvas); axis split via the locals `--px`/`--py` on `.bb-dialog` / `.bb-offcanvas` |
+| `--bb-z-overlay`      | Z-index for overlays (10)                                                                                                         |
 
 ### Color semantics
 

package/dist/ai/guides/design-tokens.md

@@ -190,11 +190,11 @@ multipliers — never literals.
 
 ### Scale
 
-| Token            | Default | Notes                                                                                                             |
-| ---------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
-| `--bb-control-h` | `32px`  | Master control height. Inputs are exactly this; buttons/tabs derive their size scale from it via `calc()` offsets |
-| `--bb-fs`        | `14px`  | Master font size. Component font sizes derive via `calc()` offsets                                                |
-| `--bb-panel-p`   | `16px`  | Content padding of large surfaces (dialog, off-canvas; header/footer paddings derive from it)                     |
+| Token            | Default | Notes                                                                                                                                                                                                                                                                                         |
+| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--bb-control-h` | `32px`  | Master control height. Inputs are exactly this; buttons/tabs derive their size scale from it via `calc()` offsets                                                                                                                                                                             |
+| `--bb-fs`        | `14px`  | Master font size. Component font sizes derive via `calc()` offsets                                                                                                                                                                                                                            |
+| `--bb-panel-p`   | `16px`  | Content padding of large surfaces (dialog, off-canvas; header/footer paddings derive from it). Axis split via the component locals `--px`/`--py` on `.bb-dialog` / `.bb-offcanvas`, each branching off `var(--bb-panel-p)`; set the pair (on the component's class) only when the axes differ |
 
 ### Motion
 
@@ -272,10 +272,13 @@ Rules:
    component seals itself.
 3. **Short names are for self-consumption only.** `--h`, `--px`, `--gap`,
    `--fs`, `--r` are fine while the rules using them target the component's
-   own boxes. If a value must be read _inside a nested foreign component_
-   (e.g. dialog padding positioning the close button, which is itself a
-   button defining `--px`), the token gets a distinctive name (`--dialog-px`)
-   or — better — the formula moves to an element the component owns.
+   own boxes. If a value must be read _inside a nested foreign component_,
+   prefer moving the formula to an element the component owns, or a
+   distinctive name. One ruled exception (2026-08-25): the dialog/off-canvas
+   padding pair `--px`/`--py` is read by the nested close button's inset
+   formula — safe because `BbCloseButton` declares neither, a constraint that
+   component must keep (minting `--px`/`--py` there would silently mask the
+   surface's value and break the inset).
 4. **Mint only what varies.** A size variant that overrides four locals is
    four tokens, not four × six sizes. Per-size lookup tables
    (`--h-xs … --h-2xl`) are allowed only when a responsive matrix genuinely
@@ -443,19 +446,22 @@ every derivation that mixes it. It is also the trap. Write
 } /* wrong: not a <percentage> */
 ```
 
-and nothing errors — not the build, not the console. The computed value is
-just `25%`, and every ring paints 1.67× stronger than the `15%` you asked for
-(opacity is the ring's strength; its thickness is `--bb-ring-size`).
+and nothing errors — not the build, not the console. The declaration is
+discarded and the token lands on the registered `initial-value: 15%` — which
+happens to be the very value this override asked for, so a light page looks
+right by accident. Write `0.4` on a dark page instead and the ring quietly
+drops from the shipped `40%` to `15%` (opacity is the ring's strength; its
+thickness is `--bb-ring-size`).
 Percentages need the `%`; colors must be a `<color>` (`transparent` and
 `currentColor` qualify, `none` and a mistyped hex do not). Nothing in the
 toolchain catches it either: `bitboss-ui check` reads `.vue`/`.md`, never
 stylesheets.
 
 Fail-soft is only soft when the initial value is close to the real one. Every
-color knob is registered at its light default, so a rejected color override
-renders the library's own light theme. `--bb-ring-opacity` is registered at
-`25%`, which matches neither shipped scope (light `15%`, dark `40%`), so a
-rejected value there is the one that shows.
+registered knob — `--bb-ring-opacity` included — is registered at its light
+default, so a rejected override renders the library's own light theme. On a
+dark page that is still visible: a rejected `--bb-ring-opacity` lands on the
+light `15%` against the shipped dark `40%`.
 
 Typed knobs are also **animatable**. Add `.theme-animated`
 (main.css) to the element that carries the scheme class or theme overrides:
@@ -609,9 +615,10 @@ escape the host dialog's `overflow: hidden` and centering transform.
 | `--bb-overlay-color` + `--bb-overlay-opacity`                                                                                                                    | `--bb-overlay` (one color with alpha)                                        |
 | `--bb-overlay-z-index`                                                                                                                                           | `--bb-z-overlay`                                                             |
 | inline ring `color-mix()` formulas                                                                                                                               | `--bb-ring` / `--bb-ring-danger` (strength knob: `--bb-ring-opacity`)        |
-| `--bb-dialog-px/pt/pb/gap/…`                                                                                                                                     | `--bb-panel-p` (+ local derivations)                                         |
+| `--bb-dialog-px/pt/pb/gap/…`                                                                                                                                     | `--bb-panel-p` + the local axis pair `--px`/`--py` on the surface roots      |
 | `--bb-button-*`, `--bb-tabs-*`, `--bb-checkbox-*`, `--bb-radio-*`, `--bb-switch-*`, `--bb-rating-*`, `--bb-slider-*`, `--bb-table-cell-h`, `--bb-progress-track` | unprefixed locals in each component's CSS                                    |
-| `--bb-table-offset-*`, `--bb-table-fill`, `--bb-table-natural-width` (JS plumbing)                                                                               | unprefixed locals on `.bb-table` (`--offset-*`, `--fill`, `--natural-width`) |
+| `--bb-table-offset-*` (JS plumbing)                                                                                                                              | unprefixed locals on `.bb-table` (`--offset-*`)                              |
+| `--bb-table-fill`, `--bb-table-natural-width`                                                                                                                    | **removed** with the grid substrate — nothing publishes them any more (v3.0) |
 | `--bb-table-{id}-track-{key}` (parent→nested width bridge)                                                                                                       | `--table-{id}-track-{key}` (distinctive cross-component name, rule 3)        |
 | `--bb-select-option-*`, `--bb-primary-base`, all `--x-light`/`--x-dark` shadows                                                                                  | deleted (dead)                                                               |
 

package/dist/ai/guides/installation-and-plugin-setup.md

@@ -506,7 +506,7 @@ template emits are already styled by the public `bitboss-ui/styles.css`.
 
 Add `--mcp` to also register a live MCP server (`npx bitboss-ui@<installed version> mcp`, pinned so npx can never fetch a different version from the registry) the harness launches on demand — it merges the entry (never overwriting other servers) into `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), `.vscode/mcp.json` (VS Code / Copilot), and `~/.codeium/windsurf/mcp_config.json` (Windsurf). **Windsurf's config is global** — it has no per-project scope, so registering it affects every project on the machine; that is why only the explicit `ai-init --mcp` command writes it, while the plugin's `mcp: true` dev-server flag (§7) auto-registers the project-scoped harnesses only. Install the server's optional peers first — `npm i -D @modelcontextprotocol/sdk zod` — they are not dependencies of the library (~12 MB used only by the MCP server); the command warns if they are absent. **`--mcp` is optional and skipping it loses you nothing but the transport** — the server only reads the `dist/ai/` files listed above, so run plain `ai-init` and let the agent read that directory if you cannot add the peers (see `mcp?: boolean` in §7).
 
-For a human-in-the-loop (and agent) safety net, add the `bitboss-ui/eslint-plugin` flat-config plugin (`...bitbossUi.configs.recommended`) so unknown/removed `Bb*` props surface as ESLint errors in the editor and CI — the same manifest checks as `bitboss-ui check`, reusing your `eslint-plugin-vue` parser. Real HTML attributes fall through untouched; escape hatches are the standard `<!-- eslint-disable-next-line bitboss-ui/no-unknown-attributes -->` and the rule's `allowAttributes` / `allowComponents` options. **`eslint --fix` also auto-migrates deprecated v2 props** (renames, boolean-polarity inversions like `allowWriting`→`disableWriting`, value remaps like BbToast `placement`→`position`, and deletion of inert removed props); structural migrations that need a slot/directive/CSS are reported but left by hand. **This library is TS-first (recipes ship `<script setup lang="ts">`, some with `generic="T"`), so wire `@typescript-eslint/parser` for both `.ts` and `.vue` files** — without it `vue-eslint-parser` throws a `Parsing error` on those files, which means no rule (including `no-unknown-attributes`) runs on them at all. See the README "ESLint plugin" section for the full config snippet (both parser blocks + the `npm i -D @typescript-eslint/parser` line) and the fix table. `recommended` also enables `bitboss-ui/no-active-class-on-root-link`: `active-class` on a link-capable `Bb*` component (`BbButton`/`BbBaseButton`/`BbBadgeButton`) matches by path PREFIX, so a link whose target is the literal root (`href="/"` / `to="/"`) reads as "active" on every URL — the rule flags that combination and points you at `exact-active-class` instead.
+For a human-in-the-loop (and agent) safety net, add the `bitboss-ui/eslint-plugin` flat-config plugin (`...bitbossUi.configs.recommended`) so unknown/removed `Bb*` props surface as ESLint errors in the editor and CI — the same manifest checks as `bitboss-ui check`, reusing your `eslint-plugin-vue` parser. Real HTML attributes fall through untouched; escape hatches are the standard `<!-- eslint-disable-next-line bitboss-ui/no-unknown-attributes -->` and the rule's `allowAttributes` / `allowComponents` options. **`eslint --fix` also auto-migrates deprecated v2 props** (renames, boolean-polarity inversions like `allowWriting`→`disableWriting`, value remaps like BbToast `placement`→`position`, and deletion of inert removed props); structural migrations that need a slot/directive/CSS are reported but left by hand. One deliberate boundary: the rule's "did you mean `<prop>`?" hints for a mistyped/unknown attribute are advisory message text, not fixes — `eslint --fix` (including an unattended run in a pre-commit hook) never applies them; only the registered v2→v3 migrations above are auto-fixed. A guess applied blind across a codebase would be a silent behavior change, so acting on a hint is always a per-site decision. **This library is TS-first (recipes ship `<script setup lang="ts">`, some with `generic="T"`), so wire `@typescript-eslint/parser` for both `.ts` and `.vue` files** — without it `vue-eslint-parser` throws a `Parsing error` on those files, which means no rule (including `no-unknown-attributes`) runs on them at all. See the README "ESLint plugin" section for the full config snippet (both parser blocks + the `npm i -D @typescript-eslint/parser` line) and the fix table. `recommended` also enables `bitboss-ui/no-active-class-on-root-link`: `active-class` on a link-capable `Bb*` component (`BbButton`/`BbBaseButton`/`BbBadgeButton`) matches by path PREFIX, so a link whose target is the literal root (`href="/"` / `to="/"`) reads as "active" on every URL — the rule flags that combination and points you at `exact-active-class` instead.
 
 **The manifest ships with the package** — `dist/ai/components.json` is inside
 the tarball, and the rules resolve it relative to their own file, so a normal

package/dist/ai/guides/migration/components/bb-dialog.md

@@ -50,16 +50,18 @@ v2's `BbDialog` was a re-export of `BaseDialog`; v3 makes it first-class
 ## CSS and tokens
 
 The `--bb-dialog-*` family is gone. Padding comes from the shared
-`--bb-panel-p`; the rest are unprefixed locals on `.bb-dialog` or plain CSS
-rules. `BbOffCanvas` is identical throughout with `.bb-offcanvas__*` parts.
+`--bb-panel-p` and the local axis pair `--px` / `--py` on `.bb-dialog`; the
+rest are unprefixed locals on `.bb-dialog` or plain CSS rules. `BbOffCanvas`
+is identical throughout with `.bb-offcanvas__*` parts and the same `--px` /
+`--py` names.
 
 | v2 token                                     | v3                                                                                     |
 | -------------------------------------------- | -------------------------------------------------------------------------------------- |
-| `--bb-dialog-px` / `--bb-dialog-py` (`24px`) | `--bb-panel-p` (`16px`) — **one** value on both axes; asymmetry needs a CSS rule       |
+| `--bb-dialog-px` / `--bb-dialog-py` (`24px`) | local `--px` / `--py` on `.bb-dialog`, each branching off `--bb-panel-p` (`16px`)      |
 | `--bb-dialog-close` (`12px`)                 | **delete it** — v3's default already reproduces v2's control size                      |
 | `--bb-dialog-title-size` (`18px`)            | local `--dialog-title-fs` on `.bb-dialog`, default `calc(var(--bb-fs) + 2px)` = `16px` |
 | `--bb-dialog-title-weight` (`600`)           | no knob — `500` is hard-coded; override with a CSS rule                                |
-| —                                            | local `--dialog-gap`, default `--bb-panel-p` — the body↔footer vertical rhythm         |
+| —                                            | local `--dialog-gap`, default `--py` — the body↔footer vertical rhythm                 |
 
 ### `--bb-dialog-close` → delete it
 
@@ -102,43 +104,46 @@ specificity — a two-class `.my-dialog .bb-dialog__title` loses.
 
 ### Asymmetric padding
 
-`--bb-panel-p` is a single value used on both axes; there is no
-`--bb-panel-px`/`--bb-panel-py` pair. If your v2 theme set `--bb-dialog-px` ≠
-`--bb-dialog-py`, set `--bb-panel-p` to the **horizontal** value (it also
-positions the close button) and override the vertical with a `padding-block`
-rule on the part classes.
+The local pair `--px` / `--py` splits the axes; each branches off
+`var(--bb-panel-p)`, so setting `--bb-panel-p` alone still moves both. Like
+every unprefixed component token, set the pair on the component's class, never
+`:root` (other components also use `--px` as a sealed local of their own, so a
+dialog-scoped value never leaks into the buttons or alerts inside). v2's `--bb-dialog-px` / `--bb-dialog-py` map onto it directly:
 
-```css
-/* v2: --bb-dialog-px: 24px; header --bb-dialog-py: 10px; body --bb-dialog-py: 20px */
+````css
+/* v2: --bb-dialog-px: 24px; --bb-dialog-py: 10px */
 .my-dialog {
-	--bb-panel-p: 24px; /* horizontal + close-button inset */
+	--px: 24px; /* horizontal padding + close-button inline inset */
+	--py: 10px; /* vertical padding + close-button block inset */
 }
+``` Per-**part** vertical differences (header `py: 10px`,
+body `py: 20px`) work by scoping the token to the part class — the padding
+rules resolve it on the part elements and the token inherits:
+
+```css
 .my-dialog .bb-dialog__header {
-	padding-block: 10px 5px; /* the library halves the header's bottom padding */
+	--py: 10px; /* top 10px, bottom py/2 = 5px; the × inset follows */
 }
-.my-dialog .bb-dialog__body .bb-dialog__body-content {
-	padding-block: 0 20px;
+.my-dialog .bb-dialog__body-content {
+	--py: 20px; /* bottom padding, and top in the headerless case */
 }
-.my-dialog .bb-dialog__body:first-child .bb-dialog__body-content {
-	padding-top: 20px;
-}
-.my-dialog .bb-dialog__footer {
-	padding-block: 20px;
-}
-```
+````
 
-Use `padding-block`, not the `padding` shorthand, so the horizontal half keeps
-tracking `--bb-panel-p`. Library selectors are `.bb-dialog .bb-dialog__header`
+Derived spacings scale with it (header bottom is `py / 2`; the close button's
+block inset tracks the header's `py`). For exact literals instead of those
+ratios, use a `padding-block` rule on the part class — `padding-block`, not
+the `padding` shorthand, so the horizontal half keeps tracking
+`--px`. Library selectors are `.bb-dialog .bb-dialog__header`
 (0,2,0), `.bb-dialog__body-content` (0,1,0),
 `.bb-dialog__body:first-child .bb-dialog__body-content` (0,2,1) and
-`.bb-dialog .bb-dialog__footer` (0,2,0) — the three-class app rules above beat
-all four.
+`.bb-dialog .bb-dialog__footer` (0,2,0) — a three-class app rule beats all
+four.
 
 ### `--dialog-gap`
 
 If only the vertical rhythm _between parts_ differs, `--dialog-gap` does it
-without a padding rule — it replaces `--bb-panel-p` in the body's bottom padding
-and the footer's block padding:
+without a padding rule — it replaces `--py` in the body's bottom
+padding and the footer's block padding:
 
 ```css
 .my-dialog {
@@ -147,7 +152,8 @@ and the footer's block padding:
 ```
 
 It does **not** reach the header's top padding, any horizontal padding, or the
-body's top padding in the headerless case; those still read `--bb-panel-p`.
+body's top padding in the headerless case; those still read `--py` (and
+`--px` for the horizontal slots).
 
 ### `.bb-confirm`