bitboss-ui 3.0.0-beta.3 → 3.0.0-beta.31

package/README.md

@@ -6,12 +6,13 @@ Vue 3 component library used across BitBoss products. It ships typed building bl
 
 ## What’s in the package
 
-Published artifacts are **`dist/`** (ESM JavaScript, `.d.ts`, the two stylesheets **`styles.css`** and **`reset.css`**, and the `dist/ai/` knowledge base), plus the **`bin/`** CLI, **`scripts/lib/`** (ESLint plugin and markup validator), the root **`llms.txt`**, and this **README**. The sections below match how the library is organised in code and in the [documentation](https://ui-components-docs.vercel.app/).
+Published artifacts are **`dist/`** (ESM JavaScript, `.d.ts`, the two stylesheets **`styles.css`** and **`reset.css`**, and the `dist/ai/` knowledge base), plus the **`bin/`** CLI, **`scripts/lib/`** (ESLint plugin and markup validator), the root **`llms.txt`**, and this **README**. The sections below match how the library is organised in code and in the [documentation](https://ui-components.bitboss.it/).
 
 ### Styles
 
 - **Global stylesheet** — import `bitboss-ui/styles.css` once. It bundles design tokens, base rules, and styles for all exported components (built from the library’s PostCSS/Tailwind pipeline).
-- **Optional reset** — `bitboss-ui/reset.css`, only if your app has no reset of its own. Import it _before_ `styles.css` (or let the build plugin inject it with `resetCss: true`).
+- **Optional reset** — `bitboss-ui/reset.css`, only if your app has no reset of its own. Import it _before_ `styles.css` (or let the build plugin inject it with `resetCss: true`). A reset is a **prerequisite** of the components, not a nicety: their sizes are written for `border-box`, and native controls and fieldsets are expected to arrive without their browser chrome. Use this one, or your own — Tailwind's Preflight covers it, which is why `resetCss` defaults to off. The component test suite runs against this file.
+- **Cascade layers (opt-in)** — on Tailwind v4 the library must sit in your layer order or its unlayered rules outrank every utility you put on a component. `cssLayers: TAILWIND_V4_LAYERS` in the build plugin (both exported from `bitboss-ui/vite`) places it after Preflight and before the utilities. Details in `ai/guides/installation-and-plugin-setup.md` § Cascade layers.
 
 ### TypeScript: use `vue-tsc` 3
 
@@ -36,46 +37,73 @@ Full detail: `ai/guides/installation-and-plugin-setup.md`.
 
 ### Composables
 
-| Composable                    | Role                                                       |
-| ----------------------------- | ---------------------------------------------------------- |
-| `useBbConfig`                 | Global options for the kit (locale, defaults, etc.).       |
-| `useBroadcastChannelInstance` | Shared `BroadcastChannel` helper for cross-tab messaging.  |
-| `useConfirm`                  | Programmatic confirm / modal flows.                        |
-| `useCountdown`                | Countdown timer state.                                     |
-| `useMobile`                   | Mobile / viewport-oriented behaviour.                      |
-| `useQueue`                    | Simple async task queue.                                   |
-| `useSafeArea`                 | Claim a screen edge for a docked panel so toasts avoid it. |
-| `useToast`                    | Toast notifications API.                                   |
+| Composable             | Role                                                                  |
+| ---------------------- | --------------------------------------------------------------------- |
+| `useBbConfig`          | Global options for the kit (locale, defaults, etc.).                  |
+| `useBbDropdownContext` | Read a `BbDropdown`'s resolved groups/selections from anywhere by id. |
+| `useBbTableContext`    | Imperative handle onto a `BbTable` by id.                             |
+| `useBbTabsContext`     | Programmatic tab selection for a `BbTabs` by id.                      |
+| `useConfirm`           | Programmatic confirm / modal flows.                                   |
+| `useCountdown`         | Countdown timer state.                                                |
+| `useId`                | SSR-safe unique ids.                                                  |
+| `useMobile`            | Mobile / viewport-oriented behaviour.                                 |
+| `useSafeArea`          | Claim a screen edge for a docked panel so toasts avoid it.            |
+| `useToast`             | Toast notifications API.                                              |
 
-### Base\* components (primitives) _(reference-only - prefer `Bb*` equivalents for consumer code)_
+### Utilities
 
-Headless or low-level pieces used inside **Bb\*** wrappers or your own compositions:
+- **`slotKey`** — the normalizer behind every dynamic per-item named slot (`BbDropdown`, `BbTable`, `BbTabs`, `BbTree`, `BbBreadcrumbs`). Import it when building slot names programmatically instead of restating the rule.
 
-- **Actions:** `BbBaseButton`
-- **Text & numbers:** `BaseTextInput`, `BaseTextarea`, `BaseNumberInput`, `BaseTag`
-- **Choice:** `BaseCheckbox`, `BaseCheckboxGroup`, `BaseRadio`, `BaseRadioGroup`, `BaseSwitch`, `BaseSwitchGroup`, `BaseSlider`, `BaseRating`
-- **Choice glyphs (presentational SVGs):** `BbBaseCheckboxIcon`, `BbBaseRadioIcon`, `BbBaseSwitchIcon`
-- **Rich inputs:** `BaseSelect`, `BaseColorInput`, `BaseDatePicker`, `BaseDatePickerInput`
-- **Layout / chrome:** `BaseInputContainer`, `BaseDialog`
+### Directives
+
+`vBbTooltip`, `vBbDropdown`, `vBbColor`, `vBbDate`, `vBbTime` — plus a
+`Bb*DirectivePlugin` for each, for app-level registration. Prefer the directive
+over the component for simple no-slot cases.
+
+### Internal building blocks
+
+The shared field chrome (`CommonField`, `CommonFieldInput` — label,
+prepend/append, prefix/suffix, clear button, spacing) and the other `Common*`
+pieces are **internal and are not exported**; every form control renders them
+itself. Use the full
+public inputs (`BbTextInput`, `BbSelect`, …); pass `hideLabel` for a
+bare/inline control. The exported primitives are **`BbBaseButton`** and the
+presentational glyphs **`BbBaseCheckboxIcon`**, **`BbBaseRadioIcon`**,
+**`BbBaseSwitchIcon`**.
 
 ### Bb\* components (composed)
 
 Product-ready components with labels, hints, errors, and consistent styling:
 
-- **Forms & actions:** `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbSelect`, `BbCheckbox`, `BbCheckboxGroup`, `BbRadio`, `BbRadioGroup`, `BbSwitch`, `BbSwitchGroup`, `BbSlider`, `BbRating`, `BbColorInput`, `BbDatePickerInput`, `BbButton`, `BbBadge`, `BbIndicator`, `BbTag`, `BbDropdown`, `BbDropdownButton`
-- **Feedback:** `BbAlert`, `BbProgress`, `BbSpinner`, `BbToast`, `BbTooltip`
-- **Layout & navigation:** `BbAccordion`, `BbCollapsible`, `BbTab`, `BbBreadcrumbs`, `BbPagination`,`BbSmoothHeight`
+- **Forms & actions:** `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbSelect`, `BbSelectPopover`, `BbCheckbox`, `BbCheckboxGroup`, `BbRadio`, `BbRadioGroup`, `BbSwitch`, `BbSwitchGroup`, `BbSlider`, `BbRating`, `BbColorInput`, `BbColorPalette`, `BbDatePicker`, `BbDatePickerInput`, `BbTimePicker`, `BbTimePickerInput`, `BbButton`, `BbBadge`, `BbBadgeButton`, `BbIndicator`, `BbTag`, `BbDropdown`, `BbDropdownGroup`, `BbDropdownButton`, `BbAsterisk`
+- **Feedback:** `BbAlert`, `BbProgress`, `BbSpinner`, `BbToast`, `BbToastPortal`, `BbTooltip`
+- **Layout & navigation:** `BbAccordion`, `BbCollapsible`, `BbTabs` (+ `BbTabsRoot`, `BbTabsList`, `BbTabsPanes`), `BbBreadcrumbs`, `BbPagination`, `BbSmoothHeight`
 - **Overlays & panels:** `BbDialog`, `BbConfirm`, `BbConfirmPortal`, `BbOffCanvas`, `BbPopover`
 - **Data:** `BbTable`, `BbTree`
 - **Media & files:** `BbAvatar`, `BbDropzone`, `BbIcon`
 
-### Shared input shells _(internal layout primitives - not for direct consumer use)_
-
-- **`CommonInputWrapper`** — the internal input-chrome primitive (label, prepend/append, prefix/suffix, clear button, spacing) that every `Bb*` input composes. Not exported; use the full public inputs (`BbTextInput`, `BbSelect`, …).
+### Passthrough (`pt`)
+
+Every component names a short list of **parts** and **states**, and a
+`pt:<part>` / `pt:<part>:<state>` prop reaches that part with a class list —
+or, in the object form, a style and attributes — typed and linted in the
+attribute form, on top of any variant. Classes append to ours, attributes win, listeners run after the
+component's own handler. A build-time `pt` map in the Vite / Nuxt plugin seeds
+every instance. Grammar, merge rules and the per-component vocabulary:
+[`ai/guides/passthrough.md`](ai/guides/passthrough.md).
+
+```vue
+<BbButton
+	prepend:icon="lucide:save"
+	pt:icon="text-emerald-600"
+	pt:icon:loading="animate-pulse"
+>Save</BbButton>
+<BbTable :items="rows" pt:row:highlighted="bg-amber-50" />
+```
 
 ### Exported component types
 
-For most **Base\*** and **Bb\*** components, the package exports matching **props**, **events**, and (where relevant) **slots** types (for example `BbSelectProps`, `BaseSelectEvents`). Use them for typed wrappers and design-system layers; the docs list the full set per component.
+For the public **Bb\*** components, the package exports matching **props**, **events**, and (where relevant) **slots** types (for example `BbSelectProps`, `BbTableEvents`), plus supporting shapes like `BbDropdownItem` and `DropdownGroupItemsGetter`. Use them for typed wrappers and design-system layers; the docs list the full set per component.
 
 ---
 
@@ -83,7 +111,7 @@ For most **Base\*** and **Bb\*** components, the package exports matching **prop
 
 **Primary docs (components, props, guides):**
 
-- [BitBoss UI documentation](https://ui-components-docs.vercel.app/) — site with guides and API reference.
+- [BitBoss UI documentation](https://ui-components.bitboss.it/) — site with guides and API reference.
 
 **For AI coding agents:**
 
@@ -93,10 +121,10 @@ v3 prerelease; pin an exact version (`bitboss-ui@3.0.0-alpha.5`) for stable
 links. Sizes grow with the catalogue — treat them as the current order of
 magnitude, not a contract.
 
-- [Core knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-medium.txt) (~110 KB) — **start here if you can only fetch one file.** Hard rules, setup, component picker, design language, and the full component catalogue.
-- [Index](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/llms.txt) (~19 KB) — link index into every document.
-- [components.json](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/components.json) — machine-readable API surface, for programmatic validation.
-- [Complete knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-full.txt) (~3.2 MB) — everything concatenated. Bulk ingestion only; too large to prompt with.
+- [Core knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-medium.txt) (~110 KB) — **start here if you can only fetch one file.** Hard rules, setup, component picker, design language, and the full component catalogue.
+- [Index](https://llms-bitboss-ui.bitboss.it/llms.txt) (~19 KB) — link index into every document.
+- [components.json](https://llms-bitboss-ui.bitboss.it/dist/ai/components.json) — machine-readable API surface, for programmatic validation.
+- [Complete knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-full.txt) (~3.2 MB) — everything concatenated. Bulk ingestion only; too large to prompt with.
 
 Already installed? Prefer the local copy under `node_modules/bitboss-ui/dist/ai/`,
 run `npx bitboss-ui ai-init` to write agent pointers, and
@@ -174,6 +202,19 @@ export default defineConfig({
 });
 ```
 
+**Icons, in one paragraph.** `local:` ships every SVG in `iconDir`. Provider
+icons (`lucide:*`, `tabler:*`, any installed `@iconify-json/*` set) ship only
+what the plugin finds as a `prefix:name` literal anywhere in the project — it
+reads every file under the Vite root as bytes, PHP included, skipping only
+gitignored, hidden, binary, `node_modules`/`vendor`/`storage`/`outDir` and
+`iconsScanner.exclude` paths — plus whatever you list in `iconWhitelist`
+(exact names or globs, for names composed at runtime or stored in a database).
+This holds in dev exactly as in prod: dev registers the same set and re-scans a
+file on every save. A name that does not resolve renders a built-in placeholder
+(`data-bb-icon-missing="<name>"`) and logs one error with the fix; it never
+throws. Details: `ai/guides/icons-policy.md` and
+`ai/guides/installation-and-plugin-setup.md` § Icons.
+
 ### Nuxt module
 
 ```ts
@@ -203,7 +244,8 @@ npx bitboss-ui ai-init
 # same as: npx bitboss-ui ai-init --update
 ```
 
-Idempotently writes:
+Idempotently writes the pointer files below **and** sets up the MCP server
+(next section); `--no-mcp` skips the server:
 
 | File                                    | Harness                  |
 | --------------------------------------- | ------------------------ |
@@ -215,48 +257,48 @@ Idempotently writes:
 
 Re-run after upgrading `bitboss-ui` so versioned pointers stay fresh.
 
-### MCP server (optional)
+### MCP server
 
-The kickstart above writes static pointer files. Add `--mcp` to also register a
-live [Model Context Protocol](https://modelcontextprotocol.io) server so agents
-can **query** the knowledge base (search components, read a contract, validate
-markup) instead of reading files blind:
+Besides the static pointer files, `ai-init` registers a live
+[Model Context Protocol](https://modelcontextprotocol.io) server so agents can
+**query** the knowledge base (search components, read a contract, validate
+markup) instead of reading files blind. It is on by default; opt out with:
 
 ```bash
-npm i -D @modelcontextprotocol/sdk zod
-npx bitboss-ui ai-init --mcp
+npx bitboss-ui ai-init --no-mcp
 ```
 
-Those two are **optional peer dependencies**, not dependencies: together they
-weigh ~12 MB — more than every runtime dependency of the component library
-combined — and nothing but the MCP server loads them, so installing
-`bitboss-ui` never drags them in. `ai-init --mcp` warns if they are missing,
-and `bitboss-ui mcp` tells you what to install rather than dying on a module
-resolution error.
-
-The agent harness launches the server itself (`npx bitboss-ui@<installed version> mcp`,
-pinned so npx can never fall back to fetching a different version from the registry) on demand —
-you never run it by hand. `--mcp` merges the server entry into each harness's
+The server needs `@modelcontextprotocol/sdk` and `zod`. They are **optional
+peer dependencies**, not dependencies: together they weigh ~12 MB — more than
+every runtime dependency of the component library combined — and nothing but
+the MCP server loads them, so installing `bitboss-ui` never drags them in.
+`ai-init` installs them as dev dependencies with your package manager (npm,
+pnpm, yarn or bun, from your lockfile); if that fails it prints the command to
+run, and `bitboss-ui mcp` tells you what to install rather than dying on a
+module resolution error. `--no-mcp` skips the install too.
+
+The agent harness launches the server itself (`node node_modules/bitboss-ui/bin/bitboss-ui.mjs mcp`,
+the installed binary rather than `npx`, so it can never fetch from the registry, its optional
+peers resolve in your project, and it cannot drift behind an upgrade) on demand —
+you never run it by hand. `ai-init` merges the server entry into each harness's
 own config (never overwriting other servers you've registered), and each write
 is idempotent:
 
-| File                                  | Harness           | Scope                      |
-| ------------------------------------- | ----------------- | -------------------------- |
-| `.mcp.json`                           | Claude Code       | project                    |
-| `.cursor/mcp.json`                    | Cursor            | project                    |
-| `.vscode/mcp.json`                    | VS Code / Copilot | project                    |
-| `~/.codeium/windsurf/mcp_config.json` | Windsurf          | **global (whole machine)** |
+| File               | Harness           |
+| ------------------ | ----------------- |
+| `.mcp.json`        | Claude Code       |
+| `.cursor/mcp.json` | Cursor            |
+| `.vscode/mcp.json` | VS Code / Copilot |
 
-> **Windsurf is global.** Cascade only reads one config in your home directory —
-> it has no per-project scope — so registering it affects **every** project on
-> your machine, not just this one. That is why the dev-server auto-registration
-> below deliberately skips Windsurf; only the explicit `ai-init --mcp` command
-> writes it.
+Windsurf only reads a global config in your home directory, so the server is
+not registered for it — add the same entry to
+`~/.codeium/windsurf/mcp_config.json` yourself if you use it. Its
+`.windsurf/rules` pointer is written as above.
 
-**Zero-command option (dev server):** instead of running `ai-init --mcp`, pass
+**Zero-command option (dev server):** instead of running `ai-init`, pass
 `mcp: true` to the Vite/Nuxt plugin and the dev server registers the
-project-scoped harnesses (Claude Code, Cursor, VS Code) automatically on boot —
-idempotent, and it leaves Windsurf's global config alone:
+same harnesses automatically on boot — idempotent, and it never installs
+anything (run `ai-init` once for the peers):
 
 ```ts
 bitbossUi({ iconDir: './assets/icons', mcp: true });
@@ -321,6 +363,119 @@ migrations — a value that must move to a slot, directive, or CSS — are repor
 with a migration-guide link but left for you. Run `eslint --fix`, then the
 remaining reports are exactly the by-hand cases.
 
+#### The one v2 break a codemod cannot own: `reverse`
+
+`reverse` on `BbCheckbox` / `BbRadio` / `BbSwitch` kept its **name** and
+inverted its **meaning** in v3. Both versions render the same default layout,
+so only explicit values moved:
+
+| v2                            | v3        |
+| ----------------------------- | --------- |
+| `:reverse="false"`            | `reverse` |
+| `reverse` / `:reverse="true"` | delete it |
+
+That is invisible to every other check — `:reverse="false"` is a declared prop,
+correctly typed, holding its own default value — and it cannot go in the
+rename table above, because the table is keyed by prop _name_: an entry for
+`reverse` would rewrite the legitimate v3 spellings too.
+
+So it has its own rule, `bitboss-ui/no-reverse-false` (in `recommended`). It
+flags only a **literal** `:reverse="false"` and offers both corrections as
+editor suggestions — a dynamic `:reverse="isRtl"` that merely evaluates false
+is left alone. For a bulk sweep of a v2 codebase, opt into the fix:
+
+```js
+{
+	rules: {
+		'bitboss-ui/no-reverse-false': ['error', { assumeV2: true }],
+	},
+}
+```
+
+`assumeV2` is off by default because the two readings produce opposite
+layouts — turn it on only for files you know came from v2, then turn it off.
+
+#### Glyph state colours: `no-state-text-color`
+
+`bitboss-ui/no-state-text-color` flags a colour-shade text utility —
+`text-red-800`, not `text-xs` — in a toggle glyph's state entry:
+`pt:icon:errors` / `warnings` / `disabled` on `BbCheckbox`, `BbRadio`,
+`BbSwitch` and their groups, or `pt:root:<state>` on their standalone glyphs. Those states paint
+from the glyph's own `--accent`, never from `color`, so the class lands and
+paints nothing. CSS cannot let a state entry's colour win while a resting
+`pt:icon` colour loses — both are just a `color` utility by then — so the rule
+says so where the class is written, and for errors and warnings offers the
+spelling that works:
+
+```vue
+<!-- warns: paints nothing -->
+<BbCheckbox pt:icon="text-blue-500" pt:icon:errors="text-red-800" />
+<!-- blue at rest, red-800 while erroring -->
+<BbCheckbox
+	pt:icon="text-blue-500"
+	pt:icon:errors="[--accent:var(--color-red-800)]"
+/>
+```
+
+It reads literal classes only (the attribute, a bound string or `{ class }`,
+and a literal `:pt` object); a dynamic value is not checked.
+
+#### Field box borders: `no-box-border-color`
+
+`bitboss-ui/no-box-border-color` flags a colour-shade border utility —
+`border-green-500`, not `border-2` — in the **base** `pt:box` of a text-like
+control. The box paints its errors / warnings frame over the resting border,
+but a border utility sets `border-color` itself and wins, so the field keeps
+looking valid. The rule suggests the resting-border token instead; a state
+entry is the state itself and is never reported:
+
+```vue
+<!-- errors: hides the error frame -->
+<BbTextInput pt:box="border-green-500" />
+<!-- green at rest, the error frame while erroring, red-800 as the error style -->
+<BbTextInput
+	pt:box="[--border-color:var(--color-green-500)]"
+	pt:box:errors="border-red-800"
+/>
+```
+
+#### The one rule that reads CSS: `no-unknown-token`
+
+`bitboss-ui/no-unknown-token` flags a bare `var(--bb-…)` naming a token the
+installed package does not declare, in a `<style>` block or a static
+`style="…"` attribute. It is a `warn`, like `no-unknown-event`.
+
+An invented token is not a near miss that degrades — CSS treats an undefined
+custom property as invalid-at-computed-value-time and throws away the **whole
+declaration**, so the rule silently does nothing and the element keeps whatever
+it inherited. One pilot lost a calendar grid's separators that way and read it
+as a layout bug.
+
+**A fallback disarms it**, because that is defined behaviour rather than a
+silent drop:
+
+```css
+.panel {
+	background: var(--bb-canvas); /* warns: no such token */
+	background: var(--bb-canvas, #f8fafc); /* fine: yours to define */
+}
+```
+
+The token list is read from the `dist/styles.css` you installed, so the rule
+can never claim a token is invented when your version declares it; with no
+stylesheet to read it stays silent. `allowTokens: string[]` exempts names you
+define yourself, and `stylesPath` points it at a different sheet.
+
+Remember the two tiers before reaching for a `--bb-*` name at all: `--bb-*` is
+the small global theme set, while each component declares its own **unprefixed**
+tokens (`.bb-table { --cell-h: 32px }`). A missing `--bb-*` name usually means
+the knob you want is a component token, not a gap in the library.
+
+Two sibling checks stay in `bitboss-ui check` and are deliberately **not**
+ESLint rules: the hand-rolled avatar and spinner hints. Those are guesses (a
+round `<img>` is sometimes a logo), and a lint rule that fires on correct code
+spends the trust the rest of these depend on.
+
 Every real HTML attribute (plus `aria-*` / `data-*`) falls through untouched, so
 attribute inheritance is never flagged. Escape hatches when you do need one:
 
@@ -399,7 +554,7 @@ MIT — see [`LICENSE`](LICENSE).
 
 ## Support
 
-- **Usage and APIs:** see the [documentation](https://ui-components-docs.vercel.app/).
+- **Usage and APIs:** see the [documentation](https://ui-components.bitboss.it/).
 - **Company / licensing / commercial:** [BitBoss](https://www.bitboss.it/).
 
 ### Reporting a bug