bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/guides/validated-forms.md

@@ -0,0 +1,177 @@
+---
+title: Validated Forms (vee-validate)
+summary: The `bitboss-ui/validated` entrypoint — form controls pre-wired to vee-validate. Global rules give an effort-free `rules="required|email"` string syntax; BbForm hosts the form; requiredAsterisk marks required fields.
+---
+
+# Validated Forms
+
+`bitboss-ui/validated` ships the standard form controls wrapped with
+[vee-validate](https://vee-validate.logaretm.com/v4/) field binding. Import from
+`bitboss-ui/validated` **only** where you want validation — the core `bitboss-ui`
+entrypoint never pulls vee-validate into apps that don't use it.
+
+```bash
+npm i vee-validate                        # required peer for /validated
+npm i @vee-validate/rules @vee-validate/i18n   # recommended: standard rules + messages
+```
+
+## 1. Define rules once (global)
+
+The recommended, effort-free setup: `defineRule` your rules once as a
+side-effect module imported from your app entry, then reference them as plain
+strings on every field.
+
+```ts
+// app/validators.ts
+import { configure, defineRule } from 'vee-validate';
+import { localize, setLocale } from '@vee-validate/i18n';
+import en from '@vee-validate/i18n/dist/locale/en.json';
+import {
+	required,
+	email,
+	min_value,
+	max_value,
+	numeric,
+	min,
+	max,
+} from '@vee-validate/rules';
+
+defineRule('required', required);
+defineRule('email', email);
+defineRule('min_value', min_value);
+defineRule('max_value', max_value);
+defineRule('numeric', numeric);
+defineRule('min', min);
+defineRule('max', max);
+
+// Project-specific rules — same (value, params, ctx) signature:
+defineRule('password', (v: unknown) =>
+	typeof v === 'string' && v.length > 0 && v.length < 8
+		? 'Password must be at least 8 characters'
+		: true
+);
+
+configure({ generateMessage: localize({ en }) }); // swap `en` for your locale JSON
+setLocale('en');
+```
+
+vee-validate's i18n is a **separate registry** from bitboss-ui's locale — they
+don't share keys, so there is no automatic bridge. Register a message locale for
+each language you support and set the active one; if you switch language at
+runtime, call `setLocale` yourself in step with it.
+
+```ts
+// main.ts — import once for its side effects
+import './app/validators';
+```
+
+## 2. Build the form
+
+Wrap fields in `<BbForm>` (a thin `useForm` host). Give each field a `label`
+(or `legend`) and `rules`. The field name is auto-derived from the label, so
+you don't write `vid`:
+
+```vue
+<script setup lang="ts">
+import { reactive, ref } from 'vue';
+import { BbButton } from 'bitboss-ui';
+import {
+	BbForm,
+	BbTextInput,
+	BbNumberInput,
+	BbCheckbox,
+} from 'bitboss-ui/validated';
+
+const form = reactive({ email: null, quantity: null, terms: false });
+const submitted = ref(null);
+</script>
+
+<template>
+	<BbForm v-slot="{ isSubmitting }" @submit="(v) => (submitted = v)">
+		<BbTextInput v-model="form.email" label="Email" rules="required|email" />
+		<BbNumberInput
+			v-model="form.quantity"
+			label="Quantity"
+			rules="required|min_value:1"
+		/>
+		<BbCheckbox v-model="form.terms" label="Accept terms" rules="required" />
+		<BbButton type="submit" :loading="isSubmitting">Submit</BbButton>
+	</BbForm>
+</template>
+```
+
+`@submit` fires **only when every field passes**, with the collected values.
+`<BbForm>` also exposes `isSubmitting` / `submitCount` / `values` / `validate` /
+`resetForm` in its slot — enough for any chrome that lives _inside_ the form.
+
+For chrome that lives **outside** it (a dialog footer, a page toolbar, a leave
+guard), give the form an explicit `id` and read it with
+[`useBbFormContext(id)`](./composables/useBbFormContext.md) — the same id-context
+pattern as `useBbTableContext` / `useBbDropdownContext`. There is no template-ref
+handle: `useBbFormContext` is the only outside surface, by design.
+
+Prefer strings, but a one-off inline function still works:
+`:rules="(v) => !!v || 'Required'"`.
+
+**`vid` is an escape hatch.** The field name is derived from the label
+(`"Preferred time"` → `preferredtime`), so set `vid` only when that wouldn't be
+unique — v-for'd rows, or array `v-model`s sharing a label:
+
+```vue
+<BbTextInput
+	v-for="(_, i) in form.attendees"
+	:key="i"
+	v-model="form.attendees[i]"
+	label="Attendee"
+	:vid="`attendee_${i}`"
+/>
+```
+
+`BbDropzone` has no label, so it always needs `vid`.
+
+## The three added props
+
+| Prop         | Type                         | Notes                                                                     |
+| ------------ | ---------------------------- | ------------------------------------------------------------------------- |
+| `rules`      | `RuleExpression<modelValue>` | A rule string (`"required\|email"`), function, or object.                 |
+| `validateOn` | timing array                 | When to re-validate; per-control default below.                           |
+| `vid`        | `string`                     | Escape hatch — explicit field name; normally auto-derived from the label. |
+
+External errors compose: whatever you pass to the base `errors` prop is
+**merged** with the vee-validate messages, so server-side errors and rule
+messages show together.
+
+## `validateOn` defaults
+
+| Default                                 | Controls                                                                                                                |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `['blur']`                              | BbTextInput, BbNumberInput, BbTextarea, BbColorInput, BbDropzone                                                        |
+| `['inactive']`                          | BbSelect, BbTag, BbSlider, BbRating, BbDatePickerInput, BbTimePickerInput, BbCheckboxGroup, BbSwitchGroup, BbRadioGroup |
+| `['update:modelValue','change','blur']` | BbCheckbox, BbSwitch                                                                                                    |
+
+`BbDropzone` has no label, so it **requires** `vid`.
+
+## Required asterisk
+
+Turn on the plugin option to mark required fields with a red `*`:
+
+```ts
+// vite.config.ts
+bitbossUi({ requiredAsterisk: true });
+```
+
+It shows on any `/validated` control that is `required` or has `rules`, rendered
+in the control's `#label`/`#legend` slot. Core (non-validated) components ignore
+the option. The marker is the exported `BbAsterisk` component — drop it into your
+own label content when you build a bespoke field.
+
+## Controls
+
+BbTextInput · BbNumberInput · BbTextarea · BbSelect · BbTag · BbCheckbox ·
+BbCheckboxGroup · BbSwitch · BbSwitchGroup · BbRadioGroup · BbRating · BbSlider ·
+BbDatePickerInput · BbTimePickerInput · BbColorInput — plus `BbForm` and the
+`useValidatedField` composable for wrapping your own controls.
+
+A live, end-to-end demo lives in `fixtures/vue/pages/ValidatedForm` (with global
+rules in `fixtures/vue/app/validators.ts`), asserted by
+`fixtures/vue/e2e/validated-form.e2e.mjs`.

package/dist/ai/index.md

@@ -2,45 +2,81 @@
 
 This index helps agents quickly find component intent and authored guides before opening full files.
 
+## Start here
+
+- **[AI Router](./guides/ai-router.md)** — tiny hop map (contract → picker/recipe → one contract file). Read it before this catalogue.
+
+## Agent Rules
+
+- Default policy: recommend `Bb*` components first and treat low-level/internal primitives as reference-only.
+- Setup policy: verify installation + plugin setup before proposing usage code.
+- Icon policy: discover available icons first and use only existing icon names.
+- Contract-first policy: each component link below is a typed contract (props/events/slots/v-model). Read `source/<Name>.md` only when the contract is not enough.
+- Machine-readable manifest: [components.json](./components.json) lists every component API surface for programmatic validation.
+- Package path: use `dist/ai/guides/ai-router.md` (then `dist/ai/index.md`) inside the installed `bitboss-ui` package (`node_modules/bitboss-ui/dist/ai/`).
+
+## Recipes (Page-Level Assemblies)
+
+Start from a recipe when building a whole page or flow — they encode the idiomatic composition of multiple components. Fall back to individual contracts for the details.
+
+- [Approvals Inbox (Inertia)](./recipes/inertia/approvals-inbox.md) - Keyboard-first expense-approvals triage for Laravel + Inertia — `keyboard-navigation` with highlight-opens-peek, one-click approve, reject-with-reason and snooze dialogs via promise-wrapped visits, bulk approve/reject with select-all-across-pages, and an `A`/`R`/`S` shortcut bar, all through one page context that coopts the Inertia Helpers toolkit.
+- [Approvals Inbox (Nuxt)](./recipes/nuxt/approvals-inbox.md) - Keyboard-first expense-approvals triage for Nuxt — `keyboard-navigation` with highlight-opens-peek, one-click approve, reject-with-reason and snooze dialogs backed by `useAsyncData`/`$fetch`, bulk approve/reject, and an `A`/`R`/`S` shortcut bar, filters URL-synced, all through one coopting page context.
+- [Approvals Inbox (Vue)](./recipes/vue/approvals-inbox.md) - Keyboard-first expense-approvals triage for a vue-router SPA — `keyboard-navigation` with highlight-opens-peek, one-click approve, reject-with-reason and snooze dialogs, bulk approve/reject, and an `A`/`R`/`S` shortcut bar, all through one coopting page context.
+- [Inline-Edit Workspace (Inertia)](./recipes/inertia/inline-edit-workspace.md) - Linear-style sprint backlog for Laravel + Inertia where every cell autosaves — optimistic per-field overlay with rollback retired where the fresh page prop lands, commit-on-blur text cells, spinner-in-the-chevron badge pickers, URL-driven filters and tabs, bulk bar and peek workbench, all through one coopting page context.
+- [Inline-Edit Workspace (Nuxt)](./recipes/nuxt/inline-edit-workspace.md) - Linear-style sprint backlog for Nuxt where every cell autosaves — optimistic per-field overlay with rollback, commit-on-blur text cells, spinner-in-the-chevron badge pickers, an async assignee search, bulk bar and peek workbench, filters URL-synced and data fetched with useAsyncData (the overlay retires in its transform), all through one coopting page context.
+- [Inline-Edit Workspace (Vue)](./recipes/vue/inline-edit-workspace.md) - Linear-style sprint backlog for a vue-router SPA where every cell autosaves — optimistic per-field overlay with rollback, commit-on-blur text cells, spinner-in-the-chevron badge pickers, an async assignee search, bulk bar and peek workbench, all through one coopting page context.
+- [Ownership Atlas (Inertia)](./recipes/inertia/ownership-atlas.md) - Nested-table ownership atlas for Laravel + Inertia — expandable owner rows whose holdings render as a child BbTable snapped onto the parent's column tracks (inherit-column-widths + per-column snap), select-all-across-pages bulk transfer, region-visit tabs, URL-mirrored filters, expand/collapse-all, and a row-highlight owner peek, all through one page context that coopts the Inertia Helpers toolkit.
+- [Record Form (Inertia)](./recipes/inertia/record-form.md) - Full-anatomy invoice create/edit form for Laravel + Inertia — sectioned fields with tied selects, usePromiseForm + form.errors for 422 mapping, an inline-editing line-items table, a useConfirmOnRouteLeave dirty guard, a sticky action row, and a customer peek sidebar, all through one coopting page context.
+- [Record Form (Nuxt)](./recipes/nuxt/record-form.md) - Full-anatomy invoice create/edit form for Nuxt — sectioned fields with tied selects and FetchError 422 mapping, an inline-editing line-items table, a useAsyncData-backed dirty-snapshot route-leave guard, a sticky action row, and a customer peek sidebar, all through one coopting page context.
+- [Record Form (Vue)](./recipes/vue/record-form.md) - Full-anatomy invoice create/edit form for a vue-router SPA — sectioned fields with tied selects and 422 error mapping, inline-editing line-item rows, a dirty-snapshot route-leave guard, a sticky action row, and a customer peek sidebar, all through one coopting page context.
+- [Records Workspace (Inertia)](./recipes/inertia/records-workspace.md) - Full-anatomy invoices workspace for Laravel + Inertia — breadcrumbs + page search, chip filter rail (one Filters menu + editable filter chips), server-visit tabs with counts, one-click status cells via promise-wrapped visits, bulk bottom panel with select-all-across-pages, and a stacked peek sidebar, all through one page context that coopts the Inertia Helpers toolkit.
+- [Records Workspace (Nuxt)](./recipes/nuxt/records-workspace.md) - Full-anatomy invoices workspace for Nuxt — breadcrumbs + page search, pill filter rail, href tabs with counts, one-click status cells, bulk bottom panel, and a stacked peek sidebar, filters URL-synced and data fetched with useAsyncData, all through one coopting page context.
+- [Records Workspace (Vue)](./recipes/vue/records-workspace.md) - Full-anatomy invoices workspace for a vue-router SPA — breadcrumbs + page search, pill filter rail, href tabs with counts, one-click status cells, bulk bottom panel, and a stacked peek sidebar, all through one coopting page context.
+- [Upload Center (Inertia)](./recipes/inertia/upload-center.md) - Full-anatomy expense-receipts upload center for Laravel + Inertia — multi-file dropzone into an inline-editable table (text, category popover, amount, date cells), per-file progress with inline retry via a direct axios/fetch upload path, submit-all with count via promise-wrapped visits, bulk bottom panel, and a stacked receipt/merchant peek sidebar, all through one page context that coopts the Inertia Helpers toolkit.
+- [Upload Center (Nuxt)](./recipes/nuxt/upload-center.md) - Full-anatomy expense-receipts upload center for Nuxt — multi-file dropzone into an inline-editable table (text, category popover, amount, date cells), per-file progress with inline retry, submit-all with count, bulk bottom panel, and a stacked receipt/merchant peek sidebar, filters URL-synced and drafts fetched with useAsyncData while the upload queue stays client-only, all through one coopting page context.
+- [Upload Center (Vue)](./recipes/vue/upload-center.md) - Full-anatomy expense-receipts upload center for a vue-router SPA — multi-file dropzone into an inline-editable table (text, category popover, amount, date cells), per-file progress with inline retry, submit-all with count, bulk bottom panel, and a stacked receipt/merchant peek sidebar, all through one coopting page context.
+- [Wizard Form (Inertia)](./recipes/inertia/wizard-form.md) - Mailchimp-grade 4-step campaign wizard for Laravel + Inertia — BbBaseButton stepper with done/current/upcoming/locked states, per-step validation gating Next behind a BbAlert summary merging form.errors, BbSmoothHeight step swaps, the step mirrored into the URL with no extra visit, a usePromiseForm draft with save-draft everywhere, and useConfirmOnRouteLeave guarding unsaved changes, all through one coopting page context.
+- [Wizard Form (Nuxt)](./recipes/nuxt/wizard-form.md) - Mailchimp-grade 4-step campaign wizard for Nuxt — BbBaseButton stepper with done/current/upcoming/locked states, per-step validation gating Next behind a BbAlert summary, BbSmoothHeight step swaps, the step mirrored into the URL with navigateTo, useAsyncData + FetchError 422 handling merged into the same validation summary, save-draft everywhere and a dirty route-leave guard, all through one coopting page context.
+- [Wizard Form (Vue)](./recipes/vue/wizard-form.md) - Mailchimp-grade 4-step campaign wizard — BbBaseButton stepper with done/current/upcoming/locked states, per-step validation gating Next behind a BbAlert summary, BbSmoothHeight step swaps, the step in the URL, save-draft everywhere and a dirty route-leave guard, all through one coopting page context.
+- [Workspace Onboarding (Inertia)](./recipes/inertia/onboarding.md) - Full-anatomy workspace onboarding for Laravel + Inertia — a live BbProgress header, an accordion checklist whose steps do the real work inline (integration switches, tag-input invites, a mini project form, CSV import via useForm multipart), the checklist seeded from a page prop and mutations resolved through promise-wrapped visits, all through one page context that coopts the Inertia Helpers toolkit.
+- [Workspace Onboarding (Nuxt)](./recipes/nuxt/onboarding.md) - Full-anatomy workspace onboarding for Nuxt — a live BbProgress header, an accordion checklist whose steps do the real work inline (integration switches, tag-input invites, a mini project form, CSV import with real byte progress), data loaded with useAsyncData and mutations resolved through $fetch + refresh(), all through one coopting page context.
+- [Workspace Onboarding (Vue)](./recipes/vue/onboarding.md) - Full-anatomy workspace onboarding for a vue-router SPA — a live BbProgress header, an accordion checklist whose steps do the real work inline (integration switches, tag-input invites, a mini project form, CSV import), per-step done/skip, and step previews in the peek sidebar, all through one coopting page context.
+
 ## Components (Consumer API)
 
 ### Data Display
 
 - [BbAvatar](./BbAvatar.md) - Displays an avatar and has a fallback content slot.
-- [BbIcon](./BbIcon.md) - Renders an svg defined in the icon folder.
+- [BbIcon](./BbIcon.md) - Renders an icon either from the local icon folder or from a provider.
 - [BbTable](./BbTable.md) - Displays tabular data, configurable columns and data mapper.
 
 ### Feedback
 
 - [BbAlert](./BbAlert.md) - Shows contextual status messages.
 - [BbBadge](./BbBadge.md) - Displays compact status counters or labels, the floating mode acts as notification dot.
-- [BbChip](./BbChip.md) - Shows compact labeled tokens with optional clear action.
+- [BbBadgeButton](./BbBadgeButton.md) - Makes a badge's body interactive: slotted as a direct child of BbBadge it renders the badge body as a real button/link with full BbBaseButton parity, leaving `clearable` free to remain a separate control.
+- [BbIndicator](./BbIndicator.md) - Anchors a notification bubble (count/short text) or a dot over a wrapped element, with floating and corner-placement options.
 - [BbProgress](./BbProgress.md) - Visualizes task or operation progress state.
 - [BbSpinner](./BbSpinner.md) - Indicates ongoing loading or pending operations.
 - [BbToast](./BbToast.md) - Shows transient notification messages.
+- [BbToastPortal](./BbToastPortal.md) - Registers named slot content that toast() renders via `portal`.
 
 ### Inputs
 
-- [BaseButton](./BaseButton.md) - Foundational button primitive used by higher-level buttons, it can become a router button, an inertia link, or a button.
-- [BaseColorInput](./BaseColorInput.md) - Foundational color input primitive.
-- [BaseDatePicker](./BaseDatePicker.md) - Foundational calendar-based date picking primitive.
-- [BaseDatePickerInput](./BaseDatePickerInput.md) - Foundational date input and picker composition primitive.
-- [BaseNumberInput](./BaseNumberInput.md) - Foundational numeric input primitive.
-- [BaseTag](./BaseTag.md) - Foundational tag/token input primitive.
-- [BaseTextarea](./BaseTextarea.md) - Foundational multiline input primitive.
-- [BaseTextInput](./BaseTextInput.md) - Foundational text input primitive.
-- [BbButton](./BbButton.md) - Wrapper around BaseButton, with loading, tooltip, and icon support.
+- [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.
+- [BbButton](./BbButton.md) - Button with loading state, tooltip, and icon support.
 - [BbColorInput](./BbColorInput.md) - Captures color values through input controls.
 - [BbDatePickerInput](./BbDatePickerInput.md) - Combines date selection with text input behavior.
 - [BbDropzone](./BbDropzone.md) - Supports drag-and-drop file input flows.
-- [BbNumberInput](./BbNumberInput.md) - Captures and validates numeric form values.
+- [BbForm](./BbForm.md) - Form host for `bitboss-ui/validated`: owns the vee-validate form (useForm), validates every field on submit, and emits `submit` with the collected values only when the form is valid.
+- [BbNumberInput](./BbNumberInput.md) - Captures and validates numeric form values, emits a number value.
 - [BbTag](./BbTag.md) - Captures and displays tag-like token values.
 - [BbTextarea](./BbTextarea.md) - Captures multi-line text values.
 - [BbTextInput](./BbTextInput.md) - Captures single-line text values.
+- [BbTimePickerInput](./BbTimePickerInput.md) - Segmented time field with hour/minute columns; 24-hour string model.
 
 ### Layout & Utility
 
-- [BbRows](./BbRows.md) - Organizes content into row-based layout blocks.
 - [BbSmoothHeight](./BbSmoothHeight.md) - Animates height transitions for dynamic content.
 
 ### Navigation
@@ -49,22 +85,36 @@ This index helps agents quickly find component intent and authored guides before
 - [BbBreadcrumbs](./BbBreadcrumbs.md) - Renders hierarchical navigation paths.
 - [BbCollapsible](./BbCollapsible.md) - Toggles visibility of collapsible content blocks.
 - [BbPagination](./BbPagination.md) - Navigates paginated data sets by page index.
-- [BbTab](./BbTab.md) - Switches between tabbed content views.
+- [BbTabs](./BbTabs.md) - Switches between tabbed content views (shadcn-like strip; BbTabRoot enables split layouts).
+- [BbTabsList](./BbTabsList.md) - The trigger strip of a split BbTabsRoot layout (renders the tab buttons only).
+- [BbTabsPanes](./BbTabsPanes.md) - The pane host of a split BbTabsRoot layout (renders the tab content only).
+- [BbTabsRoot](./BbTabsRoot.md) - Provide/inject root that lets BbTabsList and BbTabsPanes live in separate layout slots.
 - [BbTree](./BbTree.md) - Renders hierarchical expandable tree structures.
 
+### Other
+
+- [BbAsterisk](./BbAsterisk.md) - Presentational required-field marker (red "*"). No props/slots/events; placed in custom label content.
+
 ### Overlay
 
 - [BbColorPalette](./BbColorPalette.md) - Opens an anchored popover color palette for color picking interactions.
-- [BbConfirm](./BbConfirm.md) - Prompts users to confirm or cancel critical actions.
+- [BbConfirm](./BbConfirm.md) - Prompts users to confirm or cancel critical actions (includes co-located BbConfirmPortal export).
+- [BbConfirmPortal](./BbConfirmPortal.md) - Registers named slot content that confirm() renders via `portal`.
+- [BbDatePicker](./BbDatePicker.md) - Opens an anchored calendar (and optional time rail) popover on a trigger you own — the date analog of BbColorPalette; also the v-bb-date directive.
 - [BbDialog](./BbDialog.md) - Presents modal dialogs for focused user interactions.
 - [BbDropdown](./BbDropdown.md) - Displays contextual action menus and menu content.
 - [BbDropdownButton](./BbDropdownButton.md) - A button with primary action and all other actions collected in a dropdown.
+- [BbDropdownGroup](./BbDropdownGroup.md) - Renderless v-model companion for a group declared in BbDropdown.items, bound by id.
 - [BbOffCanvas](./BbOffCanvas.md) - Shows side-panel overlay content outside normal layout flow.
 - [BbPopover](./BbPopover.md) - Anchors floating content to reference elements.
+- [BbTimePicker](./BbTimePicker.md) - Opens hour/minute(/second) columns in a popover on a trigger you own — the time analog of BbDatePicker; also the v-bb-time directive.
 - [BbTooltip](./BbTooltip.md) - Displays contextual helper text on interaction.
 
 ### Selection
 
+- [BbBaseCheckboxIcon](./BbBaseCheckboxIcon.md) - Standalone checkbox glyph (box + checkmark SVG). Presentational only — no input, no events. Compose it into a fully custom checkbox design, or let BbCheckbox/BbBaseCheckbox render it.
+- [BbBaseRadioIcon](./BbBaseRadioIcon.md) - Standalone radio glyph (ring + dot). Presentational only — no input, no events. Compose it into a fully custom radio design, or let BbRadio/BbBaseRadio render it.
+- [BbBaseSwitchIcon](./BbBaseSwitchIcon.md) - Standalone switch glyph (track + thumb). Presentational only — no input, no events. Compose it into a fully custom switch design, or let BbSwitch/BbBaseSwitch render it.
 - [BbCheckbox](./BbCheckbox.md) - Toggles a single boolean option.
 - [BbCheckboxGroup](./BbCheckboxGroup.md) - Manages multiple checkbox options as a group.
 - [BbRadio](./BbRadio.md) - Represents a single choice in exclusive options.
@@ -78,47 +128,121 @@ This index helps agents quickly find component intent and authored guides before
 
 ## Components (Reference Only - Internal)
 
-Do not under any circumstance use these components directly, they are documented for internal context and composition details. They are documented for styling and behavioral details.
+Do not use these components directly in consumer code unless the user explicitly asks for internal composition details.
 
 ### Feedback
 
 - [ErrorIcon](./ErrorIcon.md) - Renders the reusable error-state icon glyph used in validation UIs.
+- [WarningIcon](./WarningIcon.md) - Renders the reusable warning-state icon glyph used in validation UIs.
 
 ### Inputs
 
+- [BbBaseColorPalette](./BbBaseColorPalette.md) - Internal low-level color palette panel used by BbColorPalette and BbColorInput.
 - [ClearableButton](./ClearableButton.md) - Action button for clearing current input value.
 
 ### Layout & Utility
 
-- [BaseInputContainer](./BaseInputContainer.md) - Foundational wrapper for labels, hints, and error states in input controls.
-- [BbIntersection](./BbIntersection.md) - Observes element visibility via intersection events.
-- [BbRatio](./BbRatio.md) - Maintains constrained aspect-ratio containers.
 - [ChipsBox](./ChipsBox.md) - Layout helper for rendering chip collections.
 - [CommaBox](./CommaBox.md) - Utility for comma-separated content rendering.
-- [CommonInputInnerContainer](./CommonInputInnerContainer.md) - Shared inner wrapper for composed input controls.
-- [CommonInputOuterContainer](./CommonInputOuterContainer.md) - Shared outer wrapper for composed input controls.
+- [CommonInputWrapper](./CommonInputWrapper.md) - Shared wrapper utility for composed input controls.
+- [GuidesComponent](./GuidesComponent.md) - Dev-only showcase that auto-collects examples/*.vue files with live preview and extractable source. Not part of the consumer API.
 - [OptionsContainer](./OptionsContainer.md) - Container utility for option list composition.
 
 ### Overlay
 
-- [BaseDialog](./BaseDialog.md) - Foundational modal dialog primitive.
 - [CommonPopover](./CommonPopover.md) - Shared popover behavior and structure primitive.
 
+### Reference Only - Base Primitive
+
+- [BbBaseCheckbox](./BbBaseCheckbox.md) - Internal low-level checkbox primitive.
+- [BbBaseCheckboxGroup](./BbBaseCheckboxGroup.md) - Internal low-level grouped checkbox primitive.
+- [BbBaseColorInput](./BbBaseColorInput.md) - Internal low-level color input primitive.
+- [BbBaseDatePicker](./BbBaseDatePicker.md) - Internal low-level date picker primitive.
+- [BbBaseDatePickerInput](./BbBaseDatePickerInput.md) - Internal low-level date-picker input primitive.
+- [BbBaseInputContainer](./BbBaseInputContainer.md) - Internal wrapper for labels, hints, validation, and shared input layout.
+- [BbBaseNumberInput](./BbBaseNumberInput.md) - Internal low-level numeric input primitive.
+- [BbBaseRadio](./BbBaseRadio.md) - Internal low-level radio primitive.
+- [BbBaseRadioGroup](./BbBaseRadioGroup.md) - Internal low-level radio-group primitive.
+- [BbBaseRating](./BbBaseRating.md) - Internal low-level rating primitive.
+- [BbBaseSelect](./BbBaseSelect.md) - Internal low-level select/listbox primitive.
+- [BbBaseSlider](./BbBaseSlider.md) - Internal low-level slider primitive.
+- [BbBaseSwitch](./BbBaseSwitch.md) - Internal low-level switch primitive.
+- [BbBaseSwitchGroup](./BbBaseSwitchGroup.md) - Internal low-level grouped switch primitive.
+- [BbBaseTag](./BbBaseTag.md) - Internal low-level tag input primitive.
+- [BbBaseTextarea](./BbBaseTextarea.md) - Internal low-level textarea primitive.
+- [BbBaseTextInput](./BbBaseTextInput.md) - Internal low-level text input primitive.
+- [BbBaseTimePickerInput](./BbBaseTimePickerInput.md) - Internal low-level time-picker input primitive.
+
 ### Selection
 
-- [BaseCheckbox](./BaseCheckbox.md) - Foundational checkbox control primitive.
-- [BaseCheckboxGroup](./BaseCheckboxGroup.md) - Foundational grouped checkbox selection primitive.
-- [BaseRadio](./BaseRadio.md) - Foundational radio option primitive.
-- [BaseRadioGroup](./BaseRadioGroup.md) - Foundational radio group primitive.
-- [BaseRating](./BaseRating.md) - Foundational rating input primitive.
-- [BaseSelect](./BaseSelect.md) - Foundational option selection primitive.
-- [BaseSlider](./BaseSlider.md) - Foundational range slider primitive.
-- [BaseSwitch](./BaseSwitch.md) - Foundational switch/toggle primitive.
-- [BaseSwitchGroup](./BaseSwitchGroup.md) - Foundational grouped switch primitive.
 - [FlatListBox](./FlatListBox.md) - Flat listbox renderer for selectable option lists.
 - [GroupedListBox](./GroupedListBox.md) - Grouped listbox renderer for categorized options.
 - [ListBox](./ListBox.md) - Accessible listbox interaction primitive.
 
+## Composables
+
+- [useBbConfig](./composables/useBbConfig.md) - Patch the library's runtime-editable configuration — today that is exactly one key, locale.
+- [useBbFormContext](./composables/useBbFormContext.md) - Read and drive a BbForm from anywhere by id — validity, dirtiness, values, errors, plus submit/reset/validate — with no template ref and no shared subtree.
+- [useBbTableContext](./composables/useBbTableContext.md) - Drive and read a BbTable's state (selection, sort, highlight, pagination) from anywhere by id — no prop drilling, no template refs.
+- [useBbTabsContext](./composables/useBbTabsContext.md) - Read and drive a BbTabs/BbTabsRoot group from anywhere by id — writable current tab, goTo/select, no template refs.
+- [useBroadcastChannelInstance](./composables/useBroadcastChannelInstance.md) - Typed cross-tab messaging via the BroadcastChannel API with per-component subscriber lifecycle.
+- [useConfirm](./composables/useConfirm.md) - Promise-based confirm dialogs — await the user's yes/no, with yes/no button configs, async onClick busy states, and portal content.
+- [useCountdown](./composables/useCountdown.md) - Reactive countdown timer with start, pause, reset, and formatted time output.
+- [useId](./composables/useId.md) - Generate a unique, hydration-safe DOM id (prefixed bb-ui-) for aria wiring in custom markup.
+- [useMobile](./composables/useMobile.md) - Reactive isMobile flag using the same viewport breakpoint the library's adaptive components use.
+- [useToast](./composables/useToast.md) - Fire, update, and dismiss transient toast notifications from anywhere — returns { toast, dismiss, update }.
+
 ## Guides
 
-- No guides found yet. Add markdown files under `ai/guides` to populate this section.
+- [Agent Contract](./guides/agent-contract.md) - Mandatory rules for AI agents using bitboss-ui in consumer projects.
+- [AI Router](./guides/ai-router.md) - Tiny start-here map for any coding agent — which file to open next, in which order, without loading the full catalogue.
+- [App Layout](./guides/app-layout.md) - App-side chrome around every page — collapsible left nav sidebar and a fat footer, with the CSS hooks (layout--sidebar-expanded, --sidebar-max-w) that the floating bottom panel offsets against.
+- [Coherence Playbook](./guides/coherence-playbook.md) - Declarative coherence for tied inputs — enforce-coherence, dependencies and debounce props instead of manual watchers, with per-component availability.
+- [Component Picker](./guides/component-picker.md) - Decision guide for choosing the right component for common UI needs.
+- [Design Language](./guides/design-language.md) - Token vocabulary, variants, sizing, dark mode, and how to style around the components when building on-system UIs.
+- [Design Tokens](./guides/design-tokens.md) - The token architecture of bitboss-ui — tiers, naming rules, the emphasis ladder, and the theming contract.
+- [Fetch Data Items Playbook](./guides/fetch-items-playbook.md) - Item-provider signatures as actually invoked per component family, prefill semantics, dependencies-driven refetching, and canonical API request patterns.
+- [Floating Bottom Panel](./guides/floating-bottom-panel.md) - App-side selection action bar — a dark, token-swapped toolbar that slides up from the bottom when table rows are selected and dispatches bulk actions.
+- [Icons Policy](./guides/icons-policy.md) - Provider-first icon usage (`lucide:*` via `@iconify-json/*` packages), `local:*` for brand art, how the plugin resolves names, and a catalog of every surface that accepts an icon.
+- [Inertia Helpers](./guides/inertia-helpers.md) - App-side toolkit for Laravel + Inertia apps — typed page props, lazy props, URL-driven filters, paginated/selection page contexts, promise forms, and navigation guards that pair with bitboss-ui pages.
+- [Inline Edit Playbook](./guides/inline-edit-playbook.md) - Who owns the edit? Choosing between draft-map, autosave, and write-back persistence for inline-editing tables — commit rules per control kind, optimistic overlays with rollback, and the dirty-ring / chevron-to-spinner feedback grammar.
+- [Installation and Plugin Setup](./guides/installation-and-plugin-setup.md) - Canonical installation, style handling, and full plugin option reference for Vite, Nuxt, and Inertia consumers.
+- [Migration v2 → v3](./guides/migration/v2-to-v3.md) - Complete upgrade guide from bitboss-ui 2.x to 3.0 — plugin-based setup, token overhaul, variant registries, global behavioral changes, and the silent-failure audit playbook.
+- [Migration v2→v3: BbAlert](./guides/migration/components/bb-alert.md) - showClose inverted to hideClose, theme replaced by typed variant.
+- [Migration v2→v3: BbAvatar](./guides/migration/components/bb-avatar.md) - The color prop is removed — the initials fallback is always primary.
+- [Migration v2→v3: BbBadge (and where your v2 badges went)](./guides/migration/components/bb-badge.md) - The v2 BbBadge (floating count/dot) is now BbIndicator; the v3 BbBadge is a new inline pill that also replaces BbChip.
+- [Migration v2→v3: BbBreadcrumbs](./guides/migration/components/bb-breadcrumbs.md) - Item keys must be strings, the text divider prop is gone, per-item slot names are normalized.
+- [Migration v2→v3: BbButton](./guides/migration/components/bb-button.md) - Async click handlers now auto-track loading (behavior flip), built-in tooltip props removed, variant locked to the registry.
+- [Migration v2→v3: BbCheckbox / BbRadio / BbSwitch](./guides/migration/components/bb-checkbox.md) - reverse polarity inverted (explicit values flip, default layout unchanged), checked narrowed to boolean, color removed.
+- [Migration v2→v3: BbCheckboxGroup / BbRadioGroup / BbSwitchGroup](./guides/migration/components/bb-checkbox-group.md) - labelPosition renamed legendPosition, per-item disabled is now inert (use selectable), color and the option affix slots removed.
+- [Migration v2→v3: BbChip (removed)](./guides/migration/components/bb-chip.md) - BbChip is gone — BbBadge with clearable is the replacement; non-clearable chips were badges all along.
+- [Migration v2→v3: BbCollapsible](./guides/migration/components/bb-collapsible.md) - The tag prop is removed; the root is always a div.
+- [Migration v2→v3: BbColorInput](./guides/migration/components/bb-color-input.md) - picker renamed to eyeDropper.
+- [Migration v2→v3: BbColorPalette](./guides/migration/components/bb-color-palette.md) - flip inverted to disableFlip, showArrow removed, picker renamed eyeDropper, update:open dropped, model updates never emit null.
+- [Migration v2→v3: BbDatePickerInput](./guides/migration/components/bb-date-picker-input.md) - allowWriting inverted to disableWriting and hidePopover renamed to disableCalendar, both with a changed token set; the width prop is removed; adaptive mobile sheet by default; non-floating output carries the local offset instead of UTC `Z` (new `utc` prop restores v2 output).
+- [Migration v2→v3: BbDialog](./guides/migration/components/bb-dialog.md) - showClose inverted to hideClose, several presentation props removed, default widths changed, adaptive bottom sheet on mobile by default.
+- [Migration v2→v3: BbDropdown](./guides/migration/components/bb-dropdown.md) - Items now expect text as the label and can carry variants/submenus; arrowPadding removed; adaptive mobile sheet on by default.
+- [Migration v2→v3: BbDropdownButton](./guides/migration/components/bb-dropdown-button.md) - autoLoading renamed to disableAutoLoading, disabledWhileLoading and theme removed.
+- [Migration v2→v3: BbDropzone](./guides/migration/components/bb-dropzone.md) - modelValue is typed, accept no longer throws and takes bare tokens, and the hidden native-submit input only renders when name is set.
+- [Migration v2→v3: BbIcon](./guides/migration/components/bb-icon.md) - The required prop is renamed type→icon, color is removed, and the xxl size key becomes 2xl.
+- [Migration v2→v3: BbOffCanvas](./guides/migration/components/bb-off-canvas.md) - showClose inverted to hideClose; size becomes responsive with new (smaller) default widths.
+- [Migration v2→v3: BbOffCanvas](./guides/migration/components/bb-offcanvas.md) - direction renamed to side (same left/top/right/bottom values); adaptive drawer configs (offCanvasProps) rename direction→side too.
+- [Migration v2→v3: BbPagination](./guides/migration/components/bb-pagination.md) - querykey renamed to queryKey; the loading prop is removed.
+- [Migration v2→v3: BbPopover](./guides/migration/components/bb-popover.md) - Built-in close button, restoreFocus, theme, and the arrow are gone; close affordances move into your content.
+- [Migration v2→v3: BbRating](./guides/migration/components/bb-rating.md) - color removed; name no longer required.
+- [Migration v2→v3: BbSelect](./guides/migration/components/bb-select.md) - allowWriting inverted to disableWriting, filterBy narrowed to string[], prefill value renamed, chevron/options slots removed, and two behavior changes (second click, mount-time coherence).
+- [Migration v2→v3: BbSelectPopover](./guides/migration/components/bb-select-popover.md) - flip and allowWriting inverted, arrow props removed, filterBy narrowed, options slots replaced by header/footer; shares BbSelect's behavior changes.
+- [Migration v2→v3: BbSlider](./guides/migration/components/bb-slider.md) - thumbTranslate inverted to disableThumbTranslate; string model values and color removed.
+- [Migration v2→v3: BbSmoothHeight](./guides/migration/components/bb-smooth-height.md) - The `tag` prop is narrowed to `div | span`, and the inner measuring element now mirrors it instead of always being a `<div>`.
+- [Migration v2→v3: BbSpinner](./guides/migration/components/bb-spinner.md) - The color prop is removed; spinners follow currentColor.
+- [Migration v2→v3: BbTable](./guides/migration/components/bb-table.md) - allowSelectAll inverted to disableSelectAll; loading no longer blanks populated tables and now inerts rows; #loading is first-load-only; #no-data fills a full-width table cell instead of replacing the row.
+- [Migration v2→v3: BbTabs (was BbTab)](./guides/migration/components/bb-tabs.md) - Component renamed; querykey→queryKey; animations default on; label slots renamed and all dynamic names/URL slugs normalized.
+- [Migration v2→v3: BbTag](./guides/migration/components/bb-tag.md) - modelValue is strictly string[] now, multiple is removed, and duplicates are rejected case-insensitively by default.
+- [Migration v2→v3: BbTextInput](./guides/migration/components/bb-text-input.md) - The type prop narrows to the text-like input types — number/date values must move to their dedicated components.
+- [Migration v2→v3: BbToast and toast()](./guides/migration/components/bb-toast.md) - Host placement becomes position with a corner-based value set; toast() options rewritten (variant, duration, actions, portal).
+- [Migration v2→v3: BbTooltip](./guides/migration/components/bb-tooltip.md) - timeout renamed to delay; theme replaced by typed variant; hideArrow is now a declared prop.
+- [Migration v2→v3: BbTree](./guides/migration/components/bb-tree.md) - Item model rewritten — payload moves under meta, open becomes expanded, identifier becomes itemValue, expansion is a v-model.
+- [Migration v2→v3: confirm() / useConfirm](./guides/migration/components/use-confirm.md) - yesText/onYes/noText/onNo collapse into yes/no configs, actions becomes an array-or-false, labels are localized, footer buttons default md.
+- [Options and Items Playbook](./guides/options-items-playbook.md) - How item-driven components turn raw domain items into options — mapping, value identity, model seeding, and the supported ways to disable choices.
+- [Page Shell](./guides/page-shell.md) - App-side page layout — topbar, content, and a right details sidebar driven by a stack-based context (push a record to peek it, pop to go back), with a mobile drawer fallback.
+- [Validated Forms (vee-validate)](./guides/validated-forms.md) - The `bitboss-ui/validated` entrypoint — form controls pre-wired to vee-validate. Global rules give an effort-free `rules="required|email"` string syntax; BbForm hosts the form; requiredAsterisk marks required fields.