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

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

@@ -17,7 +17,8 @@ The three single controls share their prop surface (`BbSwitch` re-exports
 | `color?: string`                                                             | removed                                                     | style via theme tokens / CSS                                                                                                   |
 | `indeterminate` loose type (checkbox)                                        | `boolean`                                                   | retype                                                                                                                         |
 | `name: string` required (**BbRadio** only; checkbox/switch already optional) | `name?: string` (auto-generated per button when omitted)    | relaxation — a hand-composed group still needs one shared explicit `name`, since generated ones differ per button              |
-| —                                                                            | `description`, `compact`                                    | additive                                                                                                                       |
+| —                                                                            | `description`                                               | additive (all three)                                                                                                           |
+| —                                                                            | `compact` — **group components only**                       | additive on `BbCheckboxGroup` / `BbRadioGroup` / `BbSwitchGroup`; the three single controls have no `compact` prop             |
 
 ## The `reverse` flip, precisely
 
@@ -42,5 +43,38 @@ So explicit values translate **by inversion**:
 + <BbCheckbox v-model="ok" reverse label="I agree" />
 ```
 
-`rg -n 'reverse' --type vue` and review each hit on these components — the
-compiler cannot catch a boolean that changed meaning.
+### Finding every site
+
+The compiler cannot catch a boolean that changed meaning — it is a declared
+prop, correctly typed, holding its own default value. **`bitboss-ui/eslint-plugin`
+can**, and does: `bitboss-ui/no-reverse-false` (in `recommended`) flags every
+literal `:reverse="false"` on these three components and offers both
+corrections as editor suggestions.
+
+For a codebase that used the v2 spelling **extensively**, do the sweep in one
+pass instead of clicking through them:
+
+```js
+// eslint.config.js — temporarily, for the migration run
+{
+	rules: {
+		// Rewrites `:reverse="false"` → `reverse` (the v2 layout) everywhere.
+		'bitboss-ui/no-reverse-false': ['error', { assumeV2: true }],
+	},
+}
+```
+
+```sh
+npx eslint --fix 'src/**/*.vue'
+```
+
+Then drop `assumeV2` again. It is **off by default on purpose**: the two
+readings of `:reverse="false"` produce opposite layouts, so an unrequested
+`--fix` would silently flip every row in a codebase that wrote the redundant
+prop meaning nothing by it. Turn it on only when you know the file you are
+sweeping came from v2.
+
+What the rule deliberately leaves alone: a dynamic `:reverse="isRtl"` that
+merely evaluates false is legitimate v3 code, and only the template AST can
+tell the two apart. It also flags `reverse="false"` — the unbound string form,
+which is truthy, so it reads as off and behaves as on.

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

@@ -1,16 +1,16 @@
 ---
 title: 'Migration v2→v3: BbCollapsible'
-summary: The tag prop is removed; the root is always a div.
+summary: The tag prop is removed; the root is always a span.
 ---
 
 # BbCollapsible — v2 → v3
 
 ## Changes
 
-| v2                                          | v3        | Kind                                                                           |
-| ------------------------------------------- | --------- | ------------------------------------------------------------------------------ |
-| `tag?: string` (default `'div'`)            | removed   | root is a `div`; wrap in a semantic element if you passed `tag="section"` etc. |
-| `modelValue`, `eager`, `transitionDuration` | unchanged | —                                                                              |
+| v2                                          | v3        | Kind                                                                                                                                                         |
+| ------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `tag?: string` (default `'div'`)            | removed   | the root is a **`span`** (`display: grid`) — an inline element, so it is valid inside a `<p>`; wrap in a semantic element if you passed `tag="section"` etc. |
+| `modelValue`, `eager`, `transitionDuration` | unchanged | —                                                                                                                                                            |
 
 ## Edits
 

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

@@ -1,6 +1,6 @@
 ---
 title: 'Migration v2→v3: BbDialog'
-summary: '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.'
+summary: '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.'
 ---
 
 # BbDialog — v2 → v3
@@ -13,8 +13,8 @@ v2's `BbDialog` was a re-export of `BaseDialog`; v3 makes it first-class
 | v2                                                  | v3                                                                                                                                  | Kind                                                                                                      |
 | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
 | `showClose?: boolean` (default `true`)              | `hideClose?: boolean` (default `false`)                                                                                             | rename, polarity inverted                                                                                 |
-| `description`                                       | removed                                                                                                                             | put it in the default slot / `header` slot                                                                |
-| `#description` slot                                 | removed                                                                                                                             | same — and the `aria-describedby` wiring goes with it                                                     |
+| `description`                                       | **kept** (restored in 3.0.0-beta.19)                                                                                                | carries over unchanged; see below                                                                         |
+| `#description` slot                                 | **kept** (restored in 3.0.0-beta.19)                                                                                                | carries over unchanged                                                                                    |
 | `#close` slot                                       | removed                                                                                                                             | a custom close control goes inside `#header`, which replaces the default ✕ — no `hide-close` alongside it |
 | `hideHeader`                                        | removed                                                                                                                             | omit `title` and the header collapses; or use the `header` slot                                           |
 | `compact`                                           | removed                                                                                                                             | spacing is token-driven now (`--bb-panel-p`)                                                              |
@@ -39,27 +39,49 @@ v2's `BbDialog` was a re-export of `BaseDialog`; v3 makes it first-class
 
 ```diff
 - <BbDialog v-model="open" :show-close="false" size="md" description="Review before sending">
-+ <BbDialog v-model="open" hide-close size="md">
-+   <template #header="{ titleId }">
-+     <h2 :id="titleId">Review before sending</h2>
-+   </template>
++ <BbDialog v-model="open" hide-close size="md" description="Review before sending">
     …
   </BbDialog>
 ```
 
+## `description` came back in 3.0.0-beta.19
+
+Early v3 (beta.18 and before) dropped `description` and `#description`, and
+told you to move the copy into `#header` or the body. That reversed in
+**3.0.0-beta.19**: both are back, unchanged from v2, and `aria-describedby` is
+wired again.
+
+If you already migrated away from it, nothing is broken — `#header` still
+works. You can move back for the shorter form:
+
+```diff
+  <BbDialog v-model="open" title="Review before sending">
+-   <template #header="{ titleId }">
+-     <h2 :id="titleId">Review before sending</h2>
+-     <p class="muted">This sends to all 412 subscribers.</p>
+-   </template>
++   <template #description>This sends to all 412 subscribers.</template>
+```
+
+It renders one muted line under the title, and it is the only thing
+`aria-describedby` points at — the body is deliberately not described, since
+arbitrary body markup would be read aloud in full. Keep it to a sentence.
+
 ## 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 +124,48 @@ 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 */
+/* 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 */
-}
-.my-dialog .bb-dialog__body .bb-dialog__body-content {
-	padding-block: 0 20px;
-}
-.my-dialog .bb-dialog__body:first-child .bb-dialog__body-content {
-	padding-top: 20px;
+	--py: 10px; /* top 10px, bottom py/2 = 5px; the × inset follows */
 }
-.my-dialog .bb-dialog__footer {
-	padding-block: 20px;
+.my-dialog .bb-dialog__body-content {
+	--py: 20px; /* bottom padding, and top in the headerless case */
 }
 ```
 
-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 +174,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`
 

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

@@ -1,6 +1,6 @@
 ---
 title: 'Migration v2→v3: BbOffCanvas'
-summary: 'direction→side; showClose→hideClose; description and the #close/#description slots removed; size defaults change; adaptive drawer configs unify on offCanvasProps.'
+summary: 'direction→side; showClose→hideClose; #close removed (description restored in beta.19); size defaults change; adaptive drawer configs unify on offCanvasProps.'
 ---
 
 # BbOffCanvas — v2 → v3
@@ -11,8 +11,8 @@ summary: 'direction→side; showClose→hideClose; description and the #close/#d
 | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `direction?: 'left' \| 'top' \| 'right' \| 'bottom'` (default `'left'`) | `side?: 'left' \| 'top' \| 'right' \| 'bottom'` (default `'left'`)                                         | **⚠ silent** — a leftover `direction` is ignored and the panel falls back to `'left'`                                                                                                                    |
 | `showClose?: boolean` (default `true`)                                  | `hideClose?: boolean` (default `false`)                                                                    | rename, polarity inverted                                                                                                                                                                                |
-| `description?: string`                                                  | removed                                                                                                    | put the copy in the default slot or own the header via `#header`; the `aria-describedby` wiring goes with it                                                                                             |
-| `#description` slot                                                     | removed                                                                                                    | same — nothing links body copy to the panel automatically now                                                                                                                                            |
+| `description?: string`                                                  | **kept** (restored in 3.0.0-beta.19)                                                                       | carries over unchanged; `aria-describedby` is wired again                                                                                                                                                |
+| `#description` slot                                                     | **kept** (restored in 3.0.0-beta.19)                                                                       | carries over unchanged                                                                                                                                                                                   |
 | `#close` slot                                                           | removed                                                                                                    | a custom close control goes inside `#header`, see below                                                                                                                                                  |
 | `size?: 'sm' \| 'md' \| 'lg'`                                           | `size?: Responsive<'xs'…'2xl' \| 'auto' \| CSS length>`                                                    | widened — **defaults changed**, same trap as BbDialog: v2 `{ sm: 384, md: 652, lg: 896 }` → v3 `{ xs: 320, sm: 384, md: 448, lg: 512, xl: 576, '2xl': 672 }`. Pin via `offCanvasDefaultSizes` if needed. |
 | —                                                                       | `draggable`, `stack` / `stackGap`, `persistent`, `disabled`, `fullscreen`, `eager`, `focusTarget`, `title` | additive                                                                                                                                                                                                 |
@@ -41,9 +41,24 @@ renames to `side` for the same reason:
 + <BbDialog :off-canvas-props="{ side: 'bottom' }" />
 ```
 
-The failure mode for leftover `direction` is silent (Vue does not warn on
-unknown props; it falls through `$attrs`). `vue-tsc` catches it in typed
-templates; `bitboss-ui/eslint-plugin` catches it everywhere and
+**The two leftovers fail differently — check both.** Measured with `vue-tsc`
+against this repo:
+
+- **Inside `offCanvasProps`** (`:off-canvas-props="{ direction: 'bottom' }"`) a
+  typed template **does** catch it: the value is a fresh object literal typed
+  `Partial<BbOffCanvasProps>`, so TypeScript's excess-property check fires —
+  `TS2353: 'direction' does not exist in type 'Partial<BbOffCanvasProps>'`.
+- **As an attribute on the component** (`<BbOffCanvas direction="right">`) it is
+  **silent**, and `vue-tsc` does **not** catch it by default: an unknown
+  attribute is legal Vue, lands on `$attrs`, and type-checks clean. Verified —
+  a made-up `totallyBogusProp` passes too. The panel just falls back to
+  `'left'`.
+
+For that second case `vueCompilerOptions.checkUnknownProps` would catch it, but
+it is blunt: it also rejects legitimate fallthrough like `aria-label` /
+`aria-describedby`, which these guides tell you to use. Prefer
+**`npx bitboss-ui check`**, which knows the difference, or
+`bitboss-ui/eslint-plugin`, which catches it everywhere and
 **`eslint --fix` auto-renames it**. Grep: `rg -i 'direction' --type vue` in
 offcanvas markup.
 
@@ -65,15 +80,16 @@ Pure rename — the `Partial<BbOffCanvasProps>` object is unchanged.
 
 Also silent on upgrade; `eslint --fix` auto-renames it.
 
-## `description` and `#close` are gone
+## `#close` is gone; `description` came back in beta.19
 
-v3's slot set is `header | title | default | footer` — no `#close`, no
-`#description`, and no `description` prop. Same removal as
-[BbDialog](./bb-dialog.md).
+v3's slot set is `header | title | description | default | footer` — no
+`#close`.
 
-`description` copy moves into the default slot. Nothing wires
-`aria-describedby` for you any more; add it yourself if a screen reader needs
-the panel described rather than just labelled.
+`description` and `#description` were dropped in early v3 and **restored in
+3.0.0-beta.19**, unchanged from v2 and with `aria-describedby` wired again —
+same reversal as [BbDialog](./bb-dialog.md). One muted line under the title;
+keep it to a sentence, and leave longer copy in the default slot (which is
+deliberately not described).
 
 **`#header` replaces the ✕, so `hide-close` is redundant beside it.** The
 default header renders `#title` + a `CloseButton`; providing `#header` replaces

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

@@ -38,7 +38,12 @@ The block name is unchanged; the star's state modifier is not.
 | —                                      | `.bb-base-rating--warnings`, `--forced-clear` (new)     |
 
 v2 styled unfilled stars with `:not(--highlighted)`; v3 gives them a positive
-name. Everything else survives unchanged: `.bb-base-rating`, `--disabled`,
+name. `--empty` is a **hook for your CSS**, not a painted default: the shipped
+sheet has no `&--empty` rule, because an empty star is just the base
+`__option` colour. So porting `:not(--highlighted)` to `--empty` works, and
+writing nothing also works.
+
+Everything else survives unchanged: `.bb-base-rating`, `--disabled`,
 `--errors`, `--readonly`, `--has-value`, `__inner-container`, `__option`,
 `__label-text`. Nothing warns — a `--highlighted` rule just stops matching.
 
@@ -61,7 +66,8 @@ rule now fights the library's. Delete the workaround and keep the prop.
 
 `--bb-rating-size` was a `:root` global in v2, read as
 `.bb-base-rating { --size: var(--bb-rating-size) }`. v3 drops the global and
-hard-defaults the local:
+hard-defaults the local to **`24px`** (`BbBaseRating/index.css:4`). Move your
+override off `:root` and onto the block — the value itself is yours to keep:
 
 ```diff
 - :root { --bb-rating-size: 32px; }

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

@@ -139,5 +139,8 @@ virtualizer's `estimateSize`; a CSS override desynchronises the paint from the
 scroll math and the list mispositions. Use `item-height` / `header-height` (or
 `compact`) instead — they move both halves together.
 
-The panel is teleported, so a wrapper class on your `<BbSelect>` does not reach
-it — scope on `.bb-select-popover` or on the surrounding page/theme class.
+The panel is **not** teleported — there is no `Teleport` anywhere in
+`BbSelect`, `BbBaseSelect` or `BbSelectPopover` — so it stays inside your
+`<BbSelect>` and a wrapper class does reach it. Scoping on `.bb-select-popover`
+is still the clearer target, and CSS custom properties inherit into the panel
+either way.