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

package/dist/ai/BbDropdown.md

@@ -4,7 +4,7 @@
 
 - Safety level: **Consumer API**
 - Group: **Overlay**
-- Description: Displays contextual action menus and menu content.
+- Description: Displays contextual action menus and menu content (includes the co-located BbDropdownGroup export, which is how a selectable group is bound).
 - Usage rule: Prefer this component for consumer-facing implementations.
 - Implementation source (only when the contract below is not enough): [source/BbDropdown.md](./source/BbDropdown.md)
 
@@ -85,7 +85,7 @@ yes (the `<BbConfirm>` host mounts once per app, e.g. in the root layout).
 				248 KB · <span data-last>{{ last }}</span>
 			</p>
 		</div>
-		<BbDropdown :items="items" placement="bottom-end" :width="240">
+		<BbDropdown :items="items" placement="bottom-end">
 			<template #activator="{ props }">
 				<BbButton
 					v-bind="props"
@@ -204,7 +204,7 @@ selectable group the menu stays open instead, and the row itself carries
 		</div>
 		<!-- `adaptive` is pinned off so the demo behaves identically on any
 		viewport; leave it at the project default in real apps. -->
-		<BbDropdown :adaptive="false" :items="items" :width="220">
+		<BbDropdown :adaptive="false" :items="items">
 			<template #activator="{ props, loading }">
 				<!-- The slot's `loading` flag is true while any item's async
 				`onClick` is in flight — even after the menu has closed. -->
@@ -271,7 +271,7 @@ nesting shallow (two levels is plenty).
 		class="flex max-w-xs items-center justify-between gap-2 rounded-[var(--bb-radius)] border p-2"
 	>
 		<span class="text-sm font-medium">Acme Studio</span>
-		<BbDropdown :items="items" placement="bottom-end" :width="240">
+		<BbDropdown :items="items" placement="bottom-end">
 			<template #activator="{ props }">
 				<BbButton
 					v-bind="props"
@@ -362,7 +362,7 @@ must point at a _group_ (not a plain item, not a missing key).
 		<span class="pr-1 text-xs font-medium text-[color:var(--bb-text-muted)]"
 			>Invoices</span
 		>
-		<BbDropdown :adaptive="false" :items="items" :width="220">
+		<BbDropdown :adaptive="false" :items="items" :width="200">
 			<template #activator="{ props }">
 				<BbButton
 					v-bind="props"
@@ -429,10 +429,11 @@ The full grammar:
 
 - `items: (prefill, modelValue) => raw[] | Promise<raw[]>` — called lazily on
   the menu's **first open**, never on mount, and again whenever `dependencies`
-  change. `modelValue` is the group's current selection; `prefill` is always
-  `true` here (it reads `false` only for a user-typed query, which a menu has
-  no field for) and exists so the same provider can serve a `BbSelect`. A plain
-  raw array also works when you just need the mapping.
+  change. `modelValue` is the group's current selection. A plain raw array also
+  works when you just need the mapping.
+  On a **`searchable`** group the signature gains a leading query argument —
+  `(query, prefill, modelValue)`, identical to `BbSelect`'s — which is why the
+  same provider drops into both.
 - `itemText` / `itemValue` — a path string or getter producing each raw item's
   label and value. `v-model` on the companion surfaces the selected value(s);
   internally the selection key is a hash of the value. BbBaseButton props on the
@@ -543,7 +544,7 @@ a valid selection.
 			:adaptive="false"
 			:items="menu"
 			loading-text="Loading members…"
-			:width="230"
+			:width="200"
 		>
 			<template #activator="{ props, loading }">
 				<BbButton
@@ -637,6 +638,72 @@ const assigneeNames = computed(() =>
 </script>
 ```
 
+### Searchable groups
+
+A group can render **its own search field**, scoped to itself alone — the
+nested "category › searchable options" pattern. Set `searchable` on the group,
+not on the dropdown: there is no dropdown-level search, and each searchable
+group owns an independent query.
+
+```vue
+<BbDropdown
+	:items="[
+		{
+			id: 'assignee',
+			label: 'Assignee',
+			searchable: true,
+			searchPlaceholder: 'Find a teammate…',
+			selectable: true,
+			multiple: true,
+			stash: true,
+			prefill: false,
+			items: (query, prefill, modelValue) => api.users({ q: query }),
+			itemText: 'name',
+			itemValue: 'id',
+		},
+	]"
+/>
+```
+
+What each knob does:
+
+- **`searchable`** puts the field at the top of that group — inside its submenu
+  when the group is nested. Typing narrows the group's rows by case-insensitive
+  substring, and on an async group passes the query to the getter as the
+  **leading** argument: `(query, prefill, modelValue)`, the same shape
+  `BbSelect` uses, so one provider serves both.
+- **`filterBy`** picks which raw fields the local substring match reads. Empty
+  (the default) matches the resolved display text.
+- **`searchPlaceholder`** overrides the field's placeholder; it defaults to the
+  localized label.
+- **`prefill: false`** means _search-first_ — nothing loads until the user
+  types, and the group shows a hint row until then. It **requires**
+  `searchable`, which is the one place the three-state `prefill` differs from a
+  plain menu group (`'interaction'`, the default, fetches when the group is
+  first reached; `true` fetches on mount).
+- **`stash`** accumulates the items behind _selected_ keys so they stay
+  resolvable after the query changes. Without it, selecting in one search and
+  then searching for something else leaves the earlier selection unresolvable
+  and breaks the `v-model` round-trip. **Recommended for every `multiple`
+  searchable group.**
+- **`maxHeight`** defaults to `280` (≈ 10 rows) on a searchable group **in the
+  flyout**, because a searched list should scroll rather than grow. The
+  adaptive sheet ignores that default (and any explicit cap): the off-canvas
+  body is the only scrollport, so a downward swipe on a row can dismiss the
+  sheet the same way a swipe on the handle does. Non-searchable flyout groups
+  are uncapped unless you set it.
+
+Two knobs live on the **dropdown**, not the group, because they apply to every
+searchable group in the menu:
+
+- **`queryDebounceTime`** (default `300`) debounces the async re-fetch a
+  searchable group fires as the user types. Distinct from the per-group
+  `depsDebounceTime`, which debounces refetches caused by `dependencies`
+  changing.
+- **`compact`** tightens the rows, search field included.
+
+A searchable surface is a `role="dialog"`, not a `menu` — see Accessibility.
+
 ### Reading a dropdown from anywhere: `useBbDropdownContext`
 
 Give the dropdown an explicit `id` and any component — no shared parent needed —
@@ -711,7 +778,7 @@ the edge slots, to replace one row's content use its key.
 		>
 		<!-- `adaptive` is pinned off so the demo behaves identically on any
 		viewport; leave it at the project default in real apps. -->
-		<BbDropdown :adaptive="false" :items="items" :width="200">
+		<BbDropdown :adaptive="false" :items="items">
 			<template #activator="{ props }">
 				<BbButton
 					v-bind="props"
@@ -851,7 +918,6 @@ behaves exactly as with a click menu.
 			:items="items"
 			placement="cursor"
 			:trigger="['click', 'contextMenu']"
-			:width="200"
 		>
 			<template #activator="{ props }">
 				<BbButton
@@ -1008,6 +1074,46 @@ too, the same as it would to the slot's `props`; don't hand-write your own
 </BbButton>
 ```
 
+### Density: `compact`
+
+`compact` walks the same ladder `BbSelect` does, so a dense toolbar can hold a
+select and a menu that agree: flyout rows go 28px → 24px, sheet rows 44px →
+36px. The label does not shrink — density here is height, exactly as it is for a
+select.
+
+The sheet stops at 36px and never follows the flyout down to 24px. A menu row is
+a touch target whose mis-tap fires the neighbouring **command**, where a
+mis-tapped option merely picks the wrong value and can be picked again; 36px is
+the same floor the select's own sheet holds.
+
+**A compact menu beside a compact select**
+
+```vue
+<div class="flex items-center gap-2">
+	<BbSelect
+		v-model="state.owner"
+		compact
+		hide-label
+		label="Owner"
+		:items="['Ada', 'Grace', 'Alan']"
+		placeholder="Owner"
+	/>
+	<BbButton
+		v-bb-dropdown="{
+			compact: true,
+			items: [
+				{ key: 'rename', text: 'Rename' },
+				{ key: 'duplicate', text: 'Duplicate' },
+			],
+		}"
+		size="sm"
+		variant="outline"
+	>
+		Actions
+	</BbButton>
+</div>
+```
+
 ### Mobile: the adaptive sheet
 
 On viewports below the config's `mobileMaxWidth`, the menu renders as a
@@ -1022,8 +1128,11 @@ mid-session never swaps a live menu between flyout and sheet.
   stay a flyout everywhere — e.g. deterministic UI tests or dense desktop-only
   tooling.
 - `offCanvasProps` forwards overrides to the underlying `BbOffCanvas` (merged
-  over `direction: 'bottom'`, `size: 'auto'`, `draggable: true`); it is
-  ignored when `adaptive` resolves to `false`.
+  over `direction: 'bottom'`, `size: 'auto'`, `draggable: true`,
+  `hideClose: true`); it is ignored when `adaptive` resolves to `false`.
+  Pass `hideClose: false` to bring the close control back. The sheet search
+  field (on `searchable` groups) uses the same soft filled treatment as
+  `BbSelect`'s adaptive sheet.
 
 ### Works well with
 
@@ -1104,22 +1213,23 @@ mid-session never swaps a live menu between flyout and sheet.
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `activator` | `Record<string, any> \| HTMLElement \| null \| undefined` |  |  | External activator element or component ref. When provided, the activator slot is not rendered and event listeners are attached programmatically to the referenced element. ARIA (`aria-haspopup`/`aria-expanded`/`aria-controls`) is attached p… |
-| `adaptive` | `boolean \| undefined` | `undefined` |  | On mobile viewports (below `config.mobileMaxWidth`), render the dropdown as a bottom-anchored, auto-sized off-canvas sheet that **navigates** through nested submenus (drilling one level at a time with a back control) instead of showing hove… |
-| `anchor` | `Record<string, any> \| HTMLElement \| null \| undefined` |  |  | Element the panel positions itself against, when it should differ from the activator — e.g. a wrapper that the activator is only a part of, so the menu aligns to the whole control while a single button opens it. Accepts an HTMLElement or a … |
+| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile viewports (below `config.mobileMaxWidth`), render the dropdown as a bottom-anchored, auto-sized off-canvas sheet that **navigates** through nested submenus (drilling one level at a time with a back control) instead of showing hove… |
+| `anchor` | `Record<string, any> \| HTMLElement \| null \| undefined` | `the activator element` |  | Element the panel positions itself against, when it should differ from the activator — e.g. a wrapper that the activator is only a part of, so the menu aligns to the whole control while a single button opens it. Accepts an HTMLElement or a … |
 | `boundary` | `string \| Record<string, any> \| HTMLElement \| null \| undefined` |  |  | Constrains the dropdown within a bounding element. Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
-| `disabled` | `boolean \| undefined` |  |  | Disables the component |
-| `eager` | `boolean \| undefined` |  |  | Prevents rendering content before it's made visible. |
-| `enforceCoherence` | `boolean \| undefined` |  |  | Default for pipeline groups: drop selections that are no longer present in a group's current items (e.g. after a `dependencies` re-fetch) from the selection and `v-model`. A group's own `enforceCoherence` overrides this. |
+| `compact` | `boolean \| undefined` | `false` |  | Apply the compact density variant — the same ladder `BbSelect` uses, on both surfaces: flyout rows go 28px → 24px, sheet rows 44px → 36px. The label size does not change; density here is height, as it is for a select. A menu row is a touch … |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
+| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
+| `enforceCoherence` | `boolean \| undefined` | `false` |  | Default for pipeline groups: drop selections that are no longer present in a group's current items (e.g. after a `dependencies` re-fetch) from the selection and `v-model`. A group's own `enforceCoherence` overrides this. |
 | `id` | `string \| undefined` |  |  | The identifier of the component. |
-| `items` | `Item[]` |  | yes | Array used to render each dropdown button. They can act as `button`, as `a`, or as `router-link` as they are based on the functionality provided by `BbBaseButton`. Pass a flat array for a single group, nest arrays for divider-separated grou… |
+| `items` | `Item[]` | `[]` | yes | Array used to render each dropdown button. They can act as `button`, as `a`, or as `router-link` as they are based on the functionality provided by `BbBaseButton`. Pass a flat array for a single group, nest arrays for divider-separated grou… |
 | `loadingText` | `string \| undefined` |  |  | Default placeholder text shown while a pipeline group's async items load. A group's own `loadingText` overrides this; both fall back to the localized `common.loadingText` (`'Loading...'`). |
 | `noDataText` | `string \| undefined` |  |  | Default placeholder text shown when a pipeline group resolves to no items. A group's own `noDataText` overrides this; both fall back to the localized `common.noDataText` (`'No data to display'`). |
 | `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Overrides forwarded to the underlying `BbOffCanvas` when `adaptive` renders the sheet on mobile. Merged over the adaptive defaults (`direction: 'bottom'`, `size: 'auto'`, `draggable: true`). Ignored when `adaptive` is `false`. |
 | `offset` | `number \| undefined` | `3` |  | Space the floating container will maintain from the activator. |
 | `padding` | `number \| undefined` | `10` |  | Minimum empty space to keep from the edge of the page |
-| `placement` | `Placement \| "cursor" \| undefined` | `"bottom"` |  | Position of the dropdown relative to the activator. Use `'cursor'` to anchor at the mouse/touch coordinates (hides arrow). |
+| `placement` | `Placement \| "cursor" \| undefined` | `"bottom"` |  | Position of the dropdown relative to the activator. Use `'cursor'` to anchor at the mouse/touch coordinates. (No arrow is drawn either way — arrows are tooltip-only in v3.) |
 | `queryDebounceTime` | `number \| undefined` | `300` |  | Debounce (ms) applied to the async re-fetch a `searchable` group fires as the user types. Applies to every searchable group in the menu. |
-| `transitionDuration` | `number \| undefined` | `transitions.fast` |  | How long the transition has to last in milliseconds. Menus use the fast transition rather than the medium one the other popovers default to. |
+| `transitionDuration` | `number \| undefined` | `150` |  | How long the transition has to last in milliseconds. Menus use the fast transition rather than the medium one the other popovers default to. |
 | `trigger` | `DropdownTrigger \| DropdownTrigger[] \| undefined` | `"click"` |  | Interaction(s) that open the dropdown. Accepts a single trigger or an array to combine them. - `'click'` — left-click / tap (default) - `'contextMenu'` — right-click on desktop, long-press on mobile |
 | `width` | `string \| number \| undefined` | `"auto"` |  | Width of the dropdown in pixels, percentage, or 'auto' to fit content. |
 

package/dist/ai/BbDropdownButton.md

@@ -516,22 +516,22 @@ the split control) and `boundary`.
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `append:icon` | `string \| undefined` |  |  | Icon to be added on the right of the text. |
-| `block` | `boolean \| undefined` |  |  | Displays the component as full width. |
-| `disableAutoLoading` | `boolean \| undefined` |  |  | Disables the automatic loading state that tracks async actions (enabled by default). Only affects the main action button: the split toggle half still mirrors the dropdown's internal async-action loading state. |
-| `disabled` | `boolean \| undefined` |  |  | Disables the component |
-| `eager` | `boolean \| undefined` |  |  | Prevents rendering content before it's made visible. |
+| `block` | `boolean \| undefined` | `false` |  | Displays the component as full width. |
+| `disableAutoLoading` | `boolean \| undefined` | `false` |  | Disables the automatic loading state that tracks async actions (enabled by default). Only affects the main action button: the split toggle half still mirrors the dropdown's internal async-action loading state. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
+| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
 | `id` | `string \| undefined` |  |  | The identifier of the component. |
-| `items` | `Item[]` |  | yes | Array used to render each dropdown button. They can act as `button`, as `a`, or as `router-link` as they are based on the functionality provided by `BbBaseButton`. Pass a flat array for a single group, nest arrays for divider-separated grou… |
-| `loading` | `boolean \| undefined` |  |  | Triggers a loading indicator. |
-| `offset` | `number \| undefined` |  |  | Space the floating container will maintain from the activator. |
-| `padding` | `number \| undefined` |  |  | Minimum empty space to keep from the edge of the page |
-| `placement` | `Placement \| "cursor" \| undefined` |  |  | Position of the dropdown relative to the activator. Use `'cursor'` to anchor at the mouse/touch coordinates (hides arrow). |
+| `items` | `Item[]` | `[]` | yes | Array used to render each dropdown button. They can act as `button`, as `a`, or as `router-link` as they are based on the functionality provided by `BbBaseButton`. Pass a flat array for a single group, nest arrays for divider-separated grou… |
+| `loading` | `boolean \| undefined` | `false` |  | Triggers a loading indicator. |
+| `offset` | `number \| undefined` | `3` |  | Space the floating container will maintain from the activator. |
+| `padding` | `number \| undefined` | `10` |  | Minimum empty space to keep from the edge of the page |
+| `placement` | `Placement \| "cursor" \| undefined` | `'bottom'` |  | Position of the dropdown relative to the activator. Use `'cursor'` to anchor at the mouse/touch coordinates. (No arrow is drawn either way — arrows are tooltip-only in v3.) |
 | `prepend:icon` | `string \| undefined` |  |  | Icon to be added on the left of the text. |
 | `right:icon` | `string \| undefined` |  |  | Replaces the chevron shown inside the right-side dropdown toggle button. A constrained alternative to a slot: only the toggle's icon changes, so the button keeps its semantics. Named for consistency with `prepend:icon` / `append:icon`. |
 | `size` | `Responsive<Sizes> \| undefined` | `"md"` |  | Sets the size of the button. When the value is a string, it will be applied to all screen sizes. Otherwise, it will be applied to the screen size specified by the object. |
-| `transitionDuration` | `number \| undefined` |  |  | How long the transition has to last in milliseconds. Menus use the fast transition rather than the medium one the other popovers default to. |
+| `transitionDuration` | `number \| undefined` | `150` |  | How long the transition has to last in milliseconds. Menus use the fast transition rather than the medium one the other popovers default to. |
 | `variant` | `ButtonVariantType \| undefined` | `"primary"` |  | Visual variant shared by both buttons of the split control. |
-| `width` | `string \| number \| undefined` |  |  | Width of the dropdown in pixels, percentage, or 'auto' to fit content. |
+| `width` | `string \| number \| undefined` | `'auto'` |  | Width of the dropdown in pixels, percentage, or 'auto' to fit content. |
 
 ## Events
 
@@ -550,5 +550,5 @@ the split control) and `boundary`.
 ## See Also
 
 - [BbButton](./BbButton.md) — Button with loading state, tooltip, and icon support.
-- [BbDropdown](./BbDropdown.md) — Displays contextual action menus and menu content.
+- [BbDropdown](./BbDropdown.md) — Displays contextual action menus and menu content (includes the co-located BbDropdownGroup export, which is how a selectable group is bound).
 - [BbBaseButton](./BbBaseButton.md) — Unstyled button/link primitive: element resolution (button/anchor/router link) and the full navigation engine, with no visual chrome. Use for any clickable or navigable surface that is not a variant-first BbButton — cards, list rows, custom links.

package/dist/ai/BbDropdownGroup.md

@@ -31,4 +31,4 @@
 
 ## See Also
 
-- [BbDropdown](./BbDropdown.md) — Displays contextual action menus and menu content.
+- [BbDropdown](./BbDropdown.md) — Displays contextual action menus and menu content (includes the co-located BbDropdownGroup export, which is how a selectable group is bound).

package/dist/ai/BbDropzone.md

@@ -1338,15 +1338,15 @@ button, grows with every file added, and changes mid-drag. So:
 | --- | --- | --- | --- | --- |
 | `accept` | `string[] \| undefined` |  |  | Array of MIME types (`'image/png'`), wildcards (`'image/*'`), extensions (`'.png'`) or bare tokens (`'png'`) to filter selectable files. A bare token upgrades to its extension instantly and is enriched with its MIME type from the lazily-imp… |
 | `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
-| `disabled` | `boolean \| undefined` |  |  | Disables the component |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
 | `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
-| `hasErrors` | `boolean \| undefined` |  |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
-| `hasWarning` | `boolean \| undefined` |  |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
+| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
+| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
 | `id` | `string \| undefined` |  |  | The identifier of the component. |
 | `maxFiles` | `number \| undefined` |  |  | Maximum number of acceptable files. |
 | `maxSize` | `number \| undefined` |  |  | Max size of the files in bytes. |
 | `modelValue` | `File \| File[] \| null` |  | yes | Used by v-model. |
-| `multiple` | `boolean \| undefined` |  |  | Allows the selection of multiple items. |
+| `multiple` | `boolean \| undefined` | `false` |  | Allows the selection of multiple items. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
 | `tag` | `LayoutTag \| undefined` | `"div"` |  | Element rendered as the component's wrapper. |
 | `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the dropzone, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they … |

package/dist/ai/BbForm.md

@@ -42,27 +42,22 @@ and stays put.
 
 ```vue
 <script setup lang="ts">
-import { ref } from 'vue';
 import { BbButton } from 'bitboss-ui';
 import { BbForm, BbTextInput } from 'bitboss-ui/validated';
 
-const saving = ref(false);
-
+// Just await the work — no `saving` ref. The form tracks it (see below).
 const save = async (values: Record<string, unknown>) => {
-	saving.value = true;
-	try {
-		await api.contacts.create(values);
-	} finally {
-		saving.value = false;
-	}
+	await api.contacts.create(values);
 };
 </script>
 
 <template>
-	<BbForm @submit="save">
+	<BbForm v-slot="{ isSubmitting }" @submit="save">
 		<BbTextInput label="Full name" rules="required" />
 		<BbTextInput label="Email" rules="required|email" type="email" />
-		<BbButton :loading="saving" type="submit" variant="primary">Save</BbButton>
+		<BbButton :loading="isSubmitting" type="submit" variant="primary">
+			Save
+		</BbButton>
 	</BbForm>
 </template>
 ```
@@ -72,6 +67,44 @@ from the control's `label` unless you set `vid`. `Full name` above arrives as
 `fullname`; when two fields in one form would collide (rows in a `v-for`), give
 those a `vid`.
 
+### `isSubmitting` covers your submit, not just validation
+
+Bind a button's `loading` to `isSubmitting` (or to `submitting` from
+`useBbFormContext`) and it stays on for as long as your handler is actually
+working — **return the promise** and the form waits for it:
+
+```vue
+<!-- the spinner runs until save() settles -->
+<BbForm
+	@submit="
+		async (values) => {
+			await api.save(values);
+		}
+	"
+/>
+```
+
+A synchronous handler resolves immediately, as you would expect. If your
+handler throws or rejects, the flag still clears (so the button never spins
+forever) and the error is routed to `app.config.errorHandler`, the same place
+Vue sends any other event-handler failure — so a global reporter keeps seeing
+it.
+
+> Fixed in 3.0.0-beta.15 (Q18.3). Before that, `isSubmitting` cleared as soon
+> as _validation_ resolved, so the spinner flashed for a frame and the user
+> could double-submit a save still in flight. If you worked around it with your
+> own `saving` ref, you can drop it.
+
+### `resetForm()` clears the fields, and your model
+
+Resetting publishes the new value back through `update:modelValue`, 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:
+> 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.
+
 ### Reading form state in the slot
 
 The default slot is scoped, so the chrome around the fields can react without
@@ -183,9 +216,11 @@ through `useValidatedField`.
 
 #### There is no template-ref handle
 
-`BbForm` calls no `defineExpose`, so a template ref yields the plain component
-instance and `form.value.submitForm()` / `.isValid` / `.validate()` / `.reset()`
-do not exist. Use `useBbFormContext(id)` for all four.
+`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.
 
 The native form element is still right there, though — `$el` is public-instance
 API and unaffected:

package/dist/ai/BbIcon.md

@@ -173,6 +173,12 @@ workflow and the heroicons `-20-`/`-16-` size-variant caveat.
 `local:*` is for brand art in `iconDir`. The deploy card below cycles stages
 with full `local:` literals from that folder — the canonical brand-mark demo.
 
+**Every `local:` name in this guide is one of _this repository's_ fixture SVGs**
+(`clock`, `loader`, `check_circle`, `alert_circle`, …). They are illustrative,
+not a shipped set: copy the pattern, not the names. In your project a
+`local:` name resolves only if `<name>.svg` exists in your own `iconDir`, and a
+missing one throws at mount.
+
 **Brand marks via local: — deploy stages**
 
 ```vue

package/dist/ai/BbIndicator.md

@@ -4,7 +4,7 @@
 
 - Safety level: **Consumer API**
 - Group: **Feedback**
-- Description: Anchors a notification bubble (count/short text) or a dot over a wrapped element, with floating and corner-placement options.
+- Description: Anchors a notification bubble (count/short text) or a dot over a wrapped element.
 - Usage rule: Prefer this component for consumer-facing implementations.
 - Implementation source (only when the contract below is not enough): [source/BbIndicator.md](./source/BbIndicator.md)
 
@@ -261,9 +261,9 @@ const onClear = () => {
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `bottom` | `boolean \| undefined` |  |  | Anchors the indicator to the bottom edge of the wrapped element instead of the top. |
-| `dot` | `boolean \| undefined` |  |  | Renders a small contentless dot instead of a labelled bubble. Takes precedence over `text`. |
-| `left` | `boolean \| undefined` |  |  | Anchors the indicator to the left edge of the wrapped element instead of the right. |
+| `bottom` | `boolean \| undefined` | `false` |  | Anchors the indicator to the bottom edge of the wrapped element instead of the top. |
+| `dot` | `boolean \| undefined` | `false` |  | Renders a small contentless dot instead of a labelled bubble. Takes precedence over `text`. |
+| `left` | `boolean \| undefined` | `false` |  | Anchors the indicator to the left edge of the wrapped element instead of the right. |
 | `max` | `number \| undefined` |  |  | Caps a numeric `text` count: values above `max` render as `${max}+` (e.g. `max: 99` shows `99+`). Ignored for string `text`. |
 | `size` | `keyof Sizes \| undefined` | `"md"` |  | Preset size of the indicator. |
 | `text` | `string \| number \| undefined` |  |  | Content shown inside the indicator bubble. A `number` is accepted for count ergonomics (e.g. `:text="unread"`). When omitted the indicator renders only if `dot` is set. |
@@ -279,5 +279,5 @@ const onClear = () => {
 
 ## See Also
 
-- [BbBadge](./BbBadge.md) — Displays compact status counters or labels, the floating mode acts as notification dot.
+- [BbBadge](./BbBadge.md) — Displays a compact inline status counter or label. It sits in the flow — for a bubble or dot anchored OVER another element, use BbIndicator (includes the co-located BbBadgeButton export).
 - [BbAvatar](./BbAvatar.md) — Displays an avatar and has a fallback content slot.

package/dist/ai/BbNumberInput.md

@@ -662,32 +662,32 @@ const timeoutSeconds = ref<number | null>(30);
 | `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
 | `autocomplete` | `string \| undefined` |  |  | Guides the browser as to the type of information expected in the field. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
-| `clearable` | `boolean \| undefined` |  |  | Displays a clear button when the input has a value and is being interacted with. |
-| `compact` | `boolean \| undefined` |  |  | Sets the component in a compact state. |
+| `clearable` | `boolean \| undefined` | `false` |  | Displays a clear button when the input has a value and is being interacted with. |
+| `compact` | `boolean \| undefined` | `false` |  | Sets the component in a compact state. |
 | `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
 | `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
-| `disabled` | `boolean \| undefined` |  |  | Disables the component. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
 | `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
-| `hasErrors` | `boolean \| undefined` |  |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
-| `hasWarning` | `boolean \| undefined` |  |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
-| `hideLabel` | `boolean \| undefined` |  |  | Visually hides the label of the input while maintaining accessibility. |
+| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
+| `hasWarning` | `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. |
 | `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
 | `id` | `string \| undefined` |  |  | The identifier of the component. |
 | `label` | `string` |  | yes | Text content of the label of the element. |
 | `labelMode` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Label rendering mode. |
 | `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
-| `loading` | `boolean \| undefined` |  |  | Sets the component in a loading state, usually triggering some visual styles. |
+| `loading` | `boolean \| undefined` | `false` |  | Sets the component in a loading state, usually triggering some visual styles. |
 | `max` | `number \| undefined` |  |  | Maximum value cap. |
 | `maxPrecision` | `number \| undefined` |  |  | Maximum precision of the number. |
 | `min` | `number \| undefined` |  |  | Minimum value cap. |
 | `modelValue` | `string \| number \| null` | `null` | yes | Used by v-model. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
-| `persistentHint` | `boolean \| undefined` |  |  | Keeps the hint displayed. |
+| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
 | `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
 | `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
-| `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
-| `required` | `boolean \| undefined` |  |  | Sets the input as required. |
-| `reverse` | `boolean \| undefined` |  |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
+| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
+| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
+| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
 | `step` | `number \| undefined` |  |  | Incremental unit used in the exposed `increase` and `decrease` functions. It is NOT applied to manual input as a step of 5 would prevent the user from inserting a value like `115` because of rounding down. |
 | `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |