bitboss-ui 3.0.0-beta.65 → 3.0.0-beta.67

package/dist/ai/BbDropzone.md

@@ -1179,8 +1179,7 @@ onBeforeUnmount(() => controller?.abort());
 </style>
 ```
 
-`useToast` needs `<BbHost />` mounted once in your app layout — without it,
-toasts are enqueued but never shown. This demo fakes the transfer with a timer;
+`useToast` renders in the plugin's `<BbHost />`; nothing to mount. This demo fakes the transfer with a timer;
 the wiring is identical against real `XHR`/`fetch` progress events. **Abort and
 retry live in your request layer, not in `BbDropzone`** — the component has no
 cancel/retry API. Use an `AbortController` for cancellation and re-issue the
@@ -1672,7 +1671,7 @@ button, grows with every file added, and changes mid-drag. So:
 | `maxFiles` | `number \| undefined` |  |  | Maximum number of acceptable files. |
 | `maxSize` | `number \| undefined` |  |  | Max size of the files in bytes. |
 | `modelValue` | `File \| File[] \| null \| undefined` |  |  | Used by v-model. |
-| `multiple` | `boolean \| undefined` | `false` |  | Allows the selection of multiple items. |
+| `multiple` | `boolean` | `false` |  | Allows the selection of multiple items. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
 | `readonly` | `boolean \| undefined` | `false` |  | Shows the files; the user cannot change them: drop, the file picker and the `open()` slot prop do nothing, yet the input stays focusable and a `name`d zone still submits its files (unlike `disabled`). Your slot renders the list: hide your remove buttons with the slot's `readonly`. |
 | `rules` | `RuleExpression<File \| File[] \| null>` |  |  | vee-validate rules for this field. Only inside a `BbForm`. |

package/dist/ai/BbForm.md

@@ -4,7 +4,7 @@
 
 - Safety level: **Consumer API**
 - Group: **Inputs**
-- Description: Form host for the form controls inside it: owns the vee-validate form (useForm), validates every field on submit, and emits `submit` with the collected values only when the form is valid. `schema` takes any Standard Schema (Zod, Valibot, ArkType, Yup) as it is; a failed submit focuses the first invalid field on screen and emits `invalid`. Server errors (a 422): `setErrors(errors)` from the slot or `useBbFormContext(id)` puts each on its field.
+- Description: Form host for the form controls inside it: owns the vee-validate form (useForm), validates every field on submit, and emits `submit` with the collected values only when the form is valid. `schema` takes any Standard Schema (Zod, Valibot, ArkType, Yup) as it is; a failed submit focuses the first invalid field on screen and emits `invalid`. Server errors (a 422): `setErrors(errors)` from the slot or `useBbForm(id)` puts each on its field.
 - Usage rule: Prefer this component for consumer-facing implementations.
 - Implementation source (only when the contract below is not enough): [source/BbForm.md](./source/BbForm.md)
 
@@ -83,7 +83,7 @@ submitted, counts toward `dirty`, is reset and is validated if it has rules.
 Describe the whole form once, in the schema library you already use, and hand
 it to the `schema` prop. There is no adapter to import and no extra package
 to install: any [Standard Schema](https://standardschema.dev) works, which
-covers Zod 3.24+ and 4, Valibot 1, ArkType 2 and Yup 1.7+.
+covers Zod 4, Valibot 1, ArkType 2 and Yup 1.7+.
 
 **Sign-up form with a Zod schema**
 
@@ -134,7 +134,7 @@ import {
 	BbCheckbox,
 	BbForm,
 	BbTextInput,
-	useBbFormContext,
+	useBbForm,
 } from 'bitboss-ui';
 
 const fields = z.object({
@@ -158,7 +158,7 @@ const signup = fields.refine((form) => form.password === form.confirm, {
 			.success,
 });
 
-const form = useBbFormContext('signup');
+const form = useBbForm('signup');
 const created = ref<z.output<typeof signup> | null>(null);
 
 // Typed from the schema: `values` is its OUTPUT, transforms applied.
@@ -179,7 +179,10 @@ What you get from the one prop:
 
 - **Each message lands on its field.** A field's `name` is its path in the
   schema: `name="email"`, `name="address.city"` or `name="address[city]"`,
-  `name="lines[0][qty]"` (brackets read as dots). A field with no `name` is
+  `name="lines[0][qty]"` (brackets read as dots; a dot always nests, so a data
+  key that contains one, a permission name like `users.create`, cannot be a
+  field name: hold such keys as values, one `BbCheckboxGroup` per group whose
+  item `value` is the name, `name="permissions.0"`). A field with no `name` is
   named after its label, `Full name` → `fullname`, so schema-driven forms set
   `name` on every field. A cross-field rule
   reaches the right field through its `path` (`path: ['confirm']` above);
@@ -399,14 +402,14 @@ value. Give it a `name` (its path) and read the value where you need it:
 
 - **`@submit`** gets every value (the schema's output, with a `schema`).
 - **The default slot's `values`**, for chrome inside the form.
-- **`useBbFormContext(id).values`**, from anywhere else on the page.
+- **`useBbForm(id).values`**, from anywhere else on the page.
 
 ```vue
 <script setup lang="ts">
 import { computed } from 'vue';
-import { BbButton, BbForm, BbTextInput, useBbFormContext } from 'bitboss-ui';
+import { BbButton, BbForm, BbTextInput, useBbForm } from 'bitboss-ui';
 
-const form = useBbFormContext('invite');
+const form = useBbForm('invite');
 const who = computed(() => form.values.value.email ?? 'nobody yet');
 
 const send = async (values: Record<string, unknown>) => {
@@ -430,7 +433,7 @@ it on some fields and not others: each bound ref is a two-way window into that
 one value, and `resetForm()` puts it back too.
 
 Only `@submit` (with a `schema`) and a bound `v-model` ref are typed. The
-slot's `values` is untyped and `useBbFormContext(id).values` holds `unknown`
+slot's `values` is untyped and `useBbForm(id).values` holds `unknown`
 entries, so narrow what you read there
 (`form.values.value.role as Invite['role'] | undefined`).
 
@@ -487,10 +490,13 @@ async function save(submitted: Record<string, unknown>) {
   leaves for good takes its key with it; with it, the key stays.
 - **No event.** The form emits nothing when it writes: the object IS the
   state. Watch it with `{ deep: true }` (its contents change, not its
-  reference), or read `useBbFormContext(id).values`. A deep watch also runs
+  reference), or read `useBbForm(id).values`. A deep watch also runs
   when your own code sets a key, which the form cannot tell apart.
 - **Replace it to rebind.** Give the prop another object (`values.value =
 loaded` on a `ref`, a new object from the parent) and the fields follow it.
+  The values the form STARTED with stay its baseline: a record that arrives
+  after mount reads as unsaved until you call
+  [`snapshot(loaded)`](#loading-an-edit-form).
 - **A prop works too.** `<BbForm :model="props.user">` fills the parent's
   object in place, with no readonly warning; a writable `computed` does not
   (the form writes into what the getter returns and never calls the setter).
@@ -1051,10 +1057,10 @@ re-renders, so the watcher's timing does not matter:
 ```vue
 <script setup lang="ts">
 import { ref, watch } from 'vue';
-import { BbCheckbox, BbForm, BbTextInput, useBbFormContext } from 'bitboss-ui';
+import { BbCheckbox, BbForm, BbTextInput, useBbForm } from 'bitboss-ui';
 
 const signup = ref({ business: false });
-const form = useBbFormContext('signup');
+const form = useBbForm('signup');
 
 watch(
 	() => signup.value.business,
@@ -1139,7 +1145,7 @@ While it runs:
   A submit button outside the form that points at it (a dialog footer's
   `form="…"`) follows the same rule, with no `:loading` to bind
   (`disable-auto-loading` opts out). A submit from code
-  (`useBbFormContext(id).submit()`) spins no submit button: the button whose
+  (`useBbForm(id).submit()`) spins no submit button: the button whose
   click calls it spins on its own, since its click returns the promise.
 - **A `BbDialog` / `BbOffCanvas` around the form refuses every user close**
   (the ✕, Cancel's `close()`, `Escape`, the backdrop, a swipe) until the save
@@ -1155,7 +1161,7 @@ While it runs:
 button (the HTML rule: there is no other way to choose it). So the primary
 action is the form's only `type="submit"` button, and a secondary action
 ("Save & new") is a plain button whose click calls `submit()`.
-`useBbFormContext(id).submit()` resolves `true` once the save went through and
+`useBbForm(id).submit()` resolves `true` once the save went through and
 `false` when the form is invalid or the save failed, so the secondary action
 continues only after a save:
 
@@ -1181,11 +1187,11 @@ continues only after a save:
 <script setup lang="ts">
 import { ref } from 'vue';
 import { z } from 'zod';
-import { BbButton, BbForm, BbTextInput, useBbFormContext } from 'bitboss-ui';
+import { BbButton, BbForm, BbTextInput, useBbForm } from 'bitboss-ui';
 
 const schema = z.object({ title: z.string().min(1, 'Name the task') });
 const saved = ref<string[]>([]);
-const form = useBbFormContext('new-task');
+const form = useBbForm('new-task');
 
 // Your API call.
 const save = async (values: Record<string, unknown>) => {
@@ -1218,7 +1224,7 @@ element, so tell them apart by an attribute you put on it:
 A synchronous handler never locks. A handler that throws or rejects still ends
 the save (nothing spins forever), and the error goes to
 `app.config.errorHandler`, where Vue sends any other event-handler failure.
-`isSubmitting` (slot) and `submitting` (`useBbFormContext`) follow the same
+`isSubmitting` (slot) and `submitting` (`useBbForm`) follow the same
 save, for anything else you show meanwhile.
 
 To keep the fields editable during the save, set `disable-submit-lock` on the
@@ -1237,7 +1243,7 @@ those instead (`snapshot(saved)`: merged over the current ones, arrays
 replace). `reset()` then goes back to this new baseline.
 
 ```ts
-const form = useBbFormContext('profile');
+const form = useBbForm('profile');
 
 async function save(values: Record<string, unknown>) {
 	const saved = await api.updateProfile(values);
@@ -1245,6 +1251,30 @@ async function save(values: Record<string, unknown>) {
 }
 ```
 
+### Loading an edit form
+
+An edit page usually mounts the form before the record arrives. Filling
+`:model` then updates the fields, but `dirty` still compares against the
+empty values the form started with: the page warns "unsaved changes" before
+anyone typed, and `reset()` empties the form. Call `snapshot(loaded)` once the
+record is in, and the loaded record becomes the clean state:
+
+```ts
+const values = reactive<Partial<Course>>({});
+const form = useBbForm('course');
+
+onMounted(async () => {
+	const loaded = await api.getCourse(id);
+	Object.assign(values, loaded);
+	form.snapshot(loaded); // loaded = clean; reset() returns here
+});
+```
+
+The form never re-takes its baseline on its own when `:model` changes: a
+record loading and a field your code sets look the same from inside. Or skip
+the step by rendering the form only once the record is there
+(`<BbForm v-if="loaded" :model="loaded">`).
+
 ### Saving a draft
 
 A draft saves what the user has typed so far, valid or not, so it does not go
@@ -1255,9 +1285,9 @@ longer reads as unsaved:
 
 ```vue
 <script setup lang="ts">
-import { BbButton, BbForm, BbTextInput, useBbFormContext } from 'bitboss-ui';
+import { BbButton, BbForm, BbTextInput, useBbForm } from 'bitboss-ui';
 
-const form = useBbFormContext('article');
+const form = useBbForm('article');
 
 async function saveDraft() {
 	await fetch('/api/articles/draft', {
@@ -1302,13 +1332,13 @@ first (`JSON.parse(JSON.stringify(form.values.value))`).
 ### `resetForm()` clears the fields, and your model
 
 `resetForm()` is the slot's name; from outside the form the same reset is
-`useBbFormContext(id).reset()` (the handle has no `resetForm`). Resetting publishes the new value back through each field's
+`useBbForm(id).reset()` (the handle has no `resetForm`). Resetting publishes the new value back through each field's
 `update:modelValue` (and writes it into the object bound with `:model`), so
 the control, the form's own state and whatever ref you bound all agree
 afterwards.
 The same holds for vee-validate's `resetField` and `setFieldValue`.
 
-> Fixed in 3.0.0-beta.15 (Q18.4). Before that the value pipe only ran one way:
+> Fixed in 3.0.0-beta.15. Before that the value pipe only ran one way:
 > a reset moved the form's internal value but never told your model, so the
 > form reported itself pristine while the user's text was still on screen.
 
@@ -1338,7 +1368,7 @@ The form state is one answer to "what is wrong, and where":
 validationLabel, errors, dirty, touched }`. `fields[path].errors` is one
   field's full list, the same array as `errors[path]`.
 
-All of them are on `useBbFormContext(id)` and in the default slot, with
+All of them are on `useBbForm(id)` and in the default slot, with
 `setErrors(map)` and `removeField(path)`.
 
 #### The page's errors object (`field-errors`)
@@ -1476,15 +1506,9 @@ It returns nothing: read the state afterwards.
 
 ```vue
 <script setup lang="ts">
-import {
-	BbAlert,
-	BbButton,
-	BbForm,
-	BbTextInput,
-	useBbFormContext,
-} from 'bitboss-ui';
+import { BbAlert, BbButton, BbForm, BbTextInput, useBbForm } from 'bitboss-ui';
 
-const form = useBbFormContext('signup');
+const form = useBbForm('signup');
 
 const save = async (values: Record<string, unknown>) => {
 	const response = await fetch('/api/signup', {
@@ -1561,9 +1585,9 @@ a wizard can count errors per step:
 ```vue
 <script setup lang="ts">
 import { computed } from 'vue';
-import { BbBadge, useBbFormContext } from 'bitboss-ui';
+import { BbBadge, useBbForm } from 'bitboss-ui';
 
-const form = useBbFormContext('checkout');
+const form = useBbForm('checkout');
 const STEPS = [
 	{ title: 'Account', paths: ['email', 'password'] },
 	{ title: 'Shipping', paths: ['address.street', 'address.city'] },
@@ -1656,7 +1680,7 @@ the page, in their order.
 
 **Rows from an array the form is not bound to** (each field with its own
 `v-model="line.qty"`) work too, with one extra call in a form with
-`keep-values-on-unmount`: `useBbFormContext(id).removeField(`lines.${i}`)`
+`keep-values-on-unmount`: `useBbForm(id).removeField(`lines.${i}`)`
 beside the `splice`. Such a form keeps a field's value when it unmounts on
 purpose (a wizard step), so it cannot tell a deleted row from one on another
 step. Call it in the same tick as your `splice` or later; it removes each row
@@ -1704,8 +1728,8 @@ worse.
 
 When the submit action lives outside the form — a dialog footer, a page toolbar,
 a leave guard — give the form an **explicit `id`** and read it with
-`useBbFormContext(id)`. Same pattern as `useBbTableContext` /
-`useBbDropdownContext`: no template ref, no shared subtree, no props threaded
+`useBbForm(id)`. Same pattern as `useBbTable` /
+`useBbDropdown`: no template ref, no shared subtree, no props threaded
 through the layout.
 
 The `id` is also the `<form>`'s own (it follows a BbForm; a plain `<form>`
@@ -1722,13 +1746,13 @@ import {
 	BbDialog,
 	BbForm,
 	BbTextInput,
-	useBbDialogContext,
-	useBbFormContext,
+	useBbDialog,
+	useBbForm,
 } from 'bitboss-ui';
 
 // The dialog opens by id (`v-bb-dialog="'invite-dialog'"` on its button).
-const dialog = useBbDialogContext('invite-dialog');
-const invite = useBbFormContext('invite-teammate');
+const dialog = useBbDialog('invite-dialog');
+const invite = useBbForm('invite-teammate');
 
 const sendInvite = async (values: Record<string, unknown>) => {
 	await api.invites.create(values);
@@ -1796,8 +1820,8 @@ out.
 `BbForm` exposes exactly one thing — `$el`, the native `<form>` — and nothing
 else, so a template ref gives you no `form.value.submitForm()` / `.isValid` /
 `.validate()` / `.reset()`. That is deliberate, not an oversight: state and
-actions live on `useBbFormContext(id)`, so there is no second,
-instance-shaped API to keep in step with it. Use the context for all four.
+actions live on `useBbForm(id)`, so there is no second,
+instance-shaped API to keep in step with it. Use the handle for all four.
 
 The native form element is still right there, though — `$el` is public-instance
 API and unaffected:
@@ -1819,7 +1843,7 @@ still fires only when every field passes. (`form.submit()`, the other native
 method, bypasses event handlers entirely and would skip validation _and_ reload
 the page. Never use it here.)
 
-Prefer `useBbFormContext(id).submit()` anyway: it says what you mean, needs no
+Prefer `useBbForm(id).submit()` anyway: it says what you mean, needs no
 cast, and does not depend on the root element staying a `<form>`.
 
 ### Required markers
@@ -1832,8 +1856,8 @@ renders a red asterisk beside its label ([`BbAsterisk`](./BbAsterisk.md) does th
 With a `schema`, the schema decides, with every Standard Schema
 library above: a field gets the asterisk when its key is required in the
 schema (not optional, no default, not nullable, and its parent object required
-too). Zod 4, ArkType and Joi are read through their JSON Schema; Zod 3, Yup,
-Valibot and Effect through their own schema shape — nothing to wrap, no
+too). Zod 4, ArkType and Joi are read through their JSON Schema; Yup, Valibot
+and Effect through their own schema shape — nothing to wrap, no
 `required` to add. The
 marker follows a per-step schema as it changes, and a field the schema (or a
 `required` rule) requires gets `aria-required="true"`, so assistive tech hears
@@ -1858,7 +1882,7 @@ marker stays consistent with the rules.
 | --- | --- | --- | --- | --- |
 | `disableSubmitLock` | `boolean \| undefined` | `false` |  | Keeps the fields editable while a `@submit` promise is pending (by default every joined field is read-only until it settles; a `@submit` that returns nothing never locks). Submit buttons spin either way. |
 | `fieldErrors` | `Record<string, unknown> \| null \| undefined` |  |  | Server validation errors by field path (Inertia's `form.errors`, a Laravel 422 body), shown on their fields while they are in the object. They never block a submit; a key no field has is in `unmatchedErrors`. A one-off message: `setErrors`. |
-| `id` | `string \| undefined` |  |  | Lets anything outside the form read and drive it through `useBbFormContext(id)` (a dialog footer, a toolbar, a leave guard). It is also the `<form>`'s id, so `<button form="id" type="submit">` outside it submits it. |
+| `id` | `string \| undefined` |  |  | Lets anything outside the form read and drive it through `useBbForm(id)` (a dialog footer, a toolbar, a leave guard). It is also the `<form>`'s id, so `<button form="id" type="submit">` outside it submits it. |
 | `keepValuesOnUnmount` | `boolean \| Ref<boolean, boolean> \| undefined` |  |  | Keep a field's value (and its place in `@submit`) when it unmounts — the `v-if` wizard step you left, a collapsed section. Off, an unmounted field drops out of the values. |
 | `model` | `Record<string, any> \| undefined` |  |  | The object the fields edit in place (`reactive()`, a `ref`, Pinia state, Inertia `useForm()`): bind it one way, `:model`, never `v-model`. A field without its own `v-model` reads and writes the value at its `name` path. Nothing is written on mount. |
 | `schema` | `MaybeRef<S \| undefined>` |  |  | One Standard Schema for the form (Zod, Valibot, ArkType, Yup, Joi, Effect), passed as is. An issue lands on the field whose `name` is its path; `@submit` gets the typed output. Set it at mount (a `computed` may change it); per-field `rules` are then ignored. |

package/dist/ai/BbHost.md

@@ -4,7 +4,7 @@
 
 - Safety level: **Consumer API**
 - Group: **Overlay**
-- Description: Renders confirm() and toast(); one, at the app root.
+- Description: Renders confirm() and toast(); the plugin renders one, place one per scoped area.
 - Usage rule: Prefer this component for consumer-facing implementations.
 - Implementation source (only when the contract below is not enough): [source/BbHost.md](./source/BbHost.md)
 
@@ -15,38 +15,21 @@
 `<BbHost />` renders everything the library opens from code: every
 `confirm()` ([useConfirm](./composables/useConfirm.md)), every `toast()`
 ([useToast](./composables/useToast.md)) and every on-demand dialog
-(`useBbDialogContext(Component).show()`, `v-bb-dialog="{ component }"`; see
-[BbDialog § On-demand dialogs](./BbDialog.md#on-demand-dialogs-open-a-component)). Mount it **once, at the app root**,
-beside the router outlet. A page that calls `confirm()` or `toast()` mounts
-nothing.
-
-```vue
-<!-- App.vue -->
-<template>
-	<RouterView />
-	<BbHost />
-</template>
-
-<script setup lang="ts">
-import { RouterView } from 'vue-router';
-import { BbHost } from 'bitboss-ui';
-</script>
-```
+(`useBbDialog(Component).show()`, `v-bb-dialog="{ component }"`; see
+[BbDialog § On-demand dialogs](./BbDialog.md#on-demand-dialogs-open-a-component)).
 
-On Nuxt it goes in `app.vue`, beside `<NuxtPage />`. On Inertia it goes in the
-`createInertiaApp` render root, beside the page:
+**You don't mount it.** The plugin (`app.use(bitbossUiPlugin)`, the Nuxt
+module) renders one beside your app when the app mounts, under Vue, Nuxt and
+Inertia alike. A page that calls `confirm()` or `toast()` mounts nothing.
 
-```ts
-createInertiaApp({
-	// …
-	setup({ el, App, props, plugin }) {
-		createApp({ render: () => [h(App, props), h(BbHost)] })
-			.use(plugin)
-			.use(bitbossUiPlugin)
-			.mount(el);
-	},
-});
-```
+Place a `<BbHost />` yourself only when an area of the app needs its own
+look (§ Areas with their own look). A placed host takes over from the
+plugin's while it is mounted, and hands back when it unmounts.
+
+The plugin's host sits right after the app's mount element (a
+`<div data-bb-host>` with `display: contents`) and sees the app's
+`app.provide`s, as a host beside the router outlet would; it does not see
+what `App.vue` provides, nor a `<BbPtScope>` around the app's template.
 
 It replaces `<BbConfirm />` and `<BbToast />`, which are no longer exported.
 `<BbConfirmPortal>` and `<BbToastPortal>` are unchanged.
@@ -70,10 +53,15 @@ The same keys go in the build plugin (`bitbossUi({ confirm, toastPosition })`).
 
 ### One host
 
-- **A second `<BbHost />`** mounted at the same time renders nothing, and a
-  dev warning says so. It takes over when the first one unmounts, so a host in
-  a layout that swaps keeps working.
-- **No host**: a `confirm()` resolves `false` after one second, with a dev
+- **A placed `<BbHost />`** takes over from the plugin's while it is
+  mounted, without a warning, and hands back when it unmounts.
+- **A second placed `<BbHost />`** mounted at the same time renders nothing,
+  and a dev warning says so. It takes over when the first one unmounts, so a
+  host in a layout that swaps keeps working.
+- **Two Vue apps on one page** (islands) each get the plugin's host, and
+  `confirm()` / `toast()` messages render once, in the first app's host (a
+  placed host anywhere wins). On-demand dialogs render in their own app.
+- **No host** (the plugin isn't installed and none is placed): a `confirm()` resolves `false` after one second, with a dev
   warning, and never hangs; an on-demand dialog settles `'unmounted'` the
   same way. Toasts stay queued and show once a host mounts.
 - **The one-second grace** covers a host that unmounts and remounts across a
@@ -89,12 +77,12 @@ The same keys go in the build plugin (`bitbossUi({ confirm, toastPosition })`).
 
 A confirm takes the passthrough scope and tokens of the component that called
 `useConfirm()`, wherever the host sits: nothing to set up. Toasts take the
-scope and tokens of the place the HOST sits. When the app is split into areas
-that each wrap their pages in `<BbPtScope>`
-([passthrough guide](./guides/passthrough.md) § Named scopes) and toasts need
-each area's look, mount one `<BbHost />` inside each area's layout, within its
-scope, and none at the app root. That holds only if **every** page renders inside exactly one of those
-layouts, so there is still one host at a time. See
+scope and tokens of the place the HOST sits, which for the plugin's host is
+the app's own level. When the app is split into areas that each wrap their
+pages in `<BbPtScope>` ([passthrough guide](./guides/passthrough.md) § Named
+scopes) and toasts need each area's look, place one `<BbHost />` inside each
+area's layout, within its scope. While an area's host is mounted it renders;
+a page outside every area falls back to the plugin's host. See
 [Agent Contract § Global Host Rule](./guides/agent-contract.md).
 
 ### On-demand dialogs

package/dist/ai/BbIcon.md

@@ -437,6 +437,9 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
   before it runs.
 - Inventing icon names or assuming a provider set is installed without checking
   `package.json`.
+- Writing an SVG attribute camelCase (`strokeWidth`): it lands as a dead
+  `strokeWidth` attribute. Write SVG attributes dashed, `stroke-width="2"`;
+  `vue-tsc` accepts both spellings, the browser only the dashed one.
 
 ### Accessibility
 

package/dist/ai/BbNumberInput.md

@@ -41,7 +41,7 @@
 | `--border-focus` | `pt:box` | `CommonFieldInput` | frame while focused, or --active |
 | `--ring-size` | `pt:box` | `CommonFieldInput` | ring width; 0 is a variant declining the ring |
 | `--ring-color` | `pt:box` | `CommonFieldInput` | ring colour; state owns it, not variants |
-| `--elev` | `pt:box` | `CommonFieldInput` | Resting lift, composed UNDER the ring at every box-shadow site below. `0 0 0 0 transparent` and not `none`, so the shadow list keeps a constant length and stays interpolable whatever a variant assigns — the same reason `--bb-elev` itself ships that value. |
+| `--elev` | `pt:box` | `CommonFieldInput` | Resting lift, alone in `box-shadow`: the ring is the box's outline, so a theme's `--elev: none` never takes the ring with it. |
 | `--frost` | `pt:box` | `CommonFieldInput` | Plate frost — a full `backdrop-filter` value (see --bb-surface-filter). Routed through a local rather than read from the token directly, so a chrome-less variant can decline it: frosting a ghost field gives it the plate it is contractually not supposed to have. |
 | `--inside-label-clearance` | `pt:box`, `pt:prefix`, `pt:suffix` | `CommonFieldInput` | Height and top padding added above the text for a label rendered inside the box. Zero here; the `--inside-label` rules at the bottom of this file raise it to one label line, or two with a description. |
 | `--w` | `pt:icon` | `BbIcon` | `--w` is set inline by BbIcon from the size prop. The `initial` default seals it: without it an ancestor's `--w` (e.g. a dropdown's width bridge) would inherit in and size the icon. The `--size` indirection stays so higher-specificity rules (e.g. `.bb-badge .bb-icon`) can re-point it. |
@@ -302,8 +302,9 @@ const temperature = ref<number | null>(21);
 - the **`increase()` / `decrease()`** scope functions.
 
 Those functions are handed to the `prepend` / `append` / `prefix` / `suffix`
-slots as scope props, so you build a plus/minus stepper without wiring any state
-yourself. For a stepper rendered _outside_ the field, drive `v-model` directly
+slots as scope props, with **`increaseDisabled` / `decreaseDisabled`** (true at
+`max` / `min` and while `disabled` or `readonly`), so you build a plus/minus
+stepper without wiring any state yourself. For a stepper rendered _outside_ the field, drive `v-model` directly
 (`model += step`) rather than reaching for a template ref. Stepping respects
 `min`/`max`/`maxPrecision` and is a no-op while `disabled` or `readonly`.
 
@@ -329,18 +330,20 @@ stays free while the buttons move in fixed increments.
 			:min="1"
 			name="quantity"
 		>
-			<template #prepend="{ decrease }">
+			<template #prepend="{ decrease, decreaseDisabled }">
 				<BbButton
 					aria-label="Decrease quantity"
+					:disabled="decreaseDisabled"
 					icon="lucide:minus"
 					size="xs"
 					variant="ghost"
 					@click="decrease"
 				/>
 			</template>
-			<template #append="{ increase }">
+			<template #append="{ increase, increaseDisabled }">
 				<BbButton
 					aria-label="Increase quantity"
+					:disabled="increaseDisabled"
 					icon="lucide:plus"
 					size="xs"
 					variant="ghost"
@@ -444,7 +447,8 @@ icon (`hasWarnings`) shares the error icon's slot — shown when `hasWarnings` i
 and there is no error.
 
 Every content slot (`prefix`, `suffix`, `prepend`, `append`, `prepend:outer`,
-`append:outer`) receives `{ increase, decrease }` scope, so stepper buttons can
+`append:outer`) receives `{ increase, decrease, increaseDisabled, decreaseDisabled }`
+scope, so stepper buttons can
 live anywhere in the ring. Put interactive controls in the _outer_ slots or use
 the scoped callbacks; plain `prefix`/`suffix` text is decoration only.
 
@@ -872,7 +876,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `formless` | `boolean \| undefined` | `false` |  | Keep this control out of the enclosing `BbForm` entirely: not submitted, not dirty, not reset, not validated. For a control that is not form data (a filter, a "show advanced" switch). |
 | `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
 | `hasWarnings` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
-| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
+| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. Pair it with a `placeholder`: an empty field otherwise shows nothing saying what it is for. |
 | `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
 | `id` | `string \| undefined` |  |  | The `id` of the native control; the label's `for` and the description and message ids derive from it. Generated when omitted. |
 | `inputAlign` | `'top'` \| `'center'` \| `'bottom'` |  |  | Vertical position of the control in a side-by-side row; not `inputPosition`, the horizontal one. Omitted, the control's first line meets the label's. |
@@ -955,14 +959,14 @@ States are listed in precedence order: when two are on at once and their entries
 
 ## Slots
 
-- `append` — scope: `BbNumberInputStepSlotProps` `{ increase: () => void; decrease: () => void }` — Content rendered after the number input, at the end of the inner container. Typically used to place increment/decrement buttons next to the input.
-- `append:outer` — scope: `BbNumberInputStepSlotProps` `{ increase: () => void; decrease: () => void }` — Content rendered after the entire input control, outside the input chrome.
+- `append` — scope: `BbNumberInputStepSlotProps` `{ increase: () => void; decrease: () => void; increaseDisabled: boolean; decreaseDisabled: boolean }` — Content rendered after the number input, at the end of the inner container. Typically used to place increment/decrement buttons next to the input.
+- `append:outer` — scope: `BbNumberInputStepSlotProps` `{ increase: () => void; decrease: () => void; increaseDisabled: boolean; decreaseDisabled: boolean }` — Content rendered after the entire input control, outside the input chrome.
 - `description` — scope: `BbNumberInputDescriptionSlotProps` `{ text: string; hasErrors: boolean; hasWarnings: boolean }` — Replaces the description text. Provided alone (no `description` prop) it still renders the description region and wires it into `aria-describedby`.
 - `label` — scope: `BbNumberInputLabelSlotProps` `{ showAsterisk?: boolean; text: string; hasErrors: boolean; hasWarnings: boolean }` — Replaces the default label text rendered above the number input.
-- `prefix` — scope: `BbNumberInputStepSlotProps` `{ increase: () => void; decrease: () => void }` — Inline content rendered at the start of the input field area, before the typed number.
-- `prepend` — scope: `BbNumberInputStepSlotProps` `{ increase: () => void; decrease: () => void }` — Content rendered before the number input, at the start of the inner container.
-- `prepend:outer` — scope: `BbNumberInputStepSlotProps` `{ increase: () => void; decrease: () => void }` — Content rendered before the entire input control, outside the input chrome.
-- `suffix` — scope: `BbNumberInputStepSlotProps` `{ increase: () => void; decrease: () => void }` — Inline content rendered at the end of the input field area, after the typed number.
+- `prefix` — scope: `BbNumberInputStepSlotProps` `{ increase: () => void; decrease: () => void; increaseDisabled: boolean; decreaseDisabled: boolean }` — Inline content rendered at the start of the input field area, before the typed number.
+- `prepend` — scope: `BbNumberInputStepSlotProps` `{ increase: () => void; decrease: () => void; increaseDisabled: boolean; decreaseDisabled: boolean }` — Content rendered before the number input, at the start of the inner container.
+- `prepend:outer` — scope: `BbNumberInputStepSlotProps` `{ increase: () => void; decrease: () => void; increaseDisabled: boolean; decreaseDisabled: boolean }` — Content rendered before the entire input control, outside the input chrome.
+- `suffix` — scope: `BbNumberInputStepSlotProps` `{ increase: () => void; decrease: () => void; increaseDisabled: boolean; decreaseDisabled: boolean }` — Inline content rendered at the end of the input field area, after the typed number.
 
 ## CSS custom properties