bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/guides/component-picker.md

@@ -0,0 +1,236 @@
+---
+title: Component Picker
+summary: Decision guide for choosing the right component for common UI needs.
+---
+
+# Component Picker
+
+Use this guide to map a UI requirement to the correct `bitboss-ui` component before writing any code.
+
+## Rule
+
+Always pick from the **Consumer API** (`Bb*`) components first. Only fall back to base primitives when the user explicitly requests internal composition. Each linked doc leads with a "Usage & Guidelines" section — read it before the API tables.
+
+---
+
+## Text Input
+
+| Need                                    | Component                                    |
+| --------------------------------------- | -------------------------------------------- |
+| Single-line text                        | [BbTextInput](../BbTextInput.md)             |
+| Multi-line text                         | [BbTextarea](../BbTextarea.md)               |
+| Numeric value with clamping/stepping    | [BbNumberInput](../BbNumberInput.md)         |
+| Color value in a form                   | [BbColorInput](../BbColorInput.md)           |
+| Calendar date or date range             | [BbDatePickerInput](../BbDatePickerInput.md) |
+| Time or time range                      | [BbTimePickerInput](../BbTimePickerInput.md) |
+| Free-form tags / tokens typed by user   | [BbTag](../BbTag.md)                         |
+| File selection via drag-and-drop/picker | [BbDropzone](../BbDropzone.md)               |
+
+- `BbTag` is for **open vocabularies** (skills, keywords, recipients the user invents). If values come from a known set, use `BbSelect` in multiple mode instead.
+- `BbDropzone` captures and validates files; it does **not** upload — pair it with your request layer plus `BbProgress`/`useToast`.
+
+---
+
+## Selection from a List of Options
+
+| Need                                                | Component                                |
+| --------------------------------------------------- | ---------------------------------------- |
+| Dropdown search, single or multi-select             | [BbSelect](../BbSelect.md)               |
+| Picker on a custom trigger (no inline form input)   | [BbSelectPopover](../BbSelectPopover.md) |
+| Few exclusive options (radio semantics)             | [BbRadioGroup](../BbRadioGroup.md)       |
+| Multiple non-exclusive options (checkbox semantics) | [BbCheckboxGroup](../BbCheckboxGroup.md) |
+| Multiple options as live on/off settings            | [BbSwitchGroup](../BbSwitchGroup.md)     |
+| Approximate value or range from a bounded interval  | [BbSlider](../BbSlider.md)               |
+| Whole-number score out of N (stars, rating)         | [BbRating](../BbRating.md)               |
+
+**Choosing between BbSelect, BbRadioGroup, BbCheckboxGroup, BbSwitchGroup:**
+
+- Large, dynamic, or searchable option sets → `BbSelect` (search and async fetch baked in).
+- Small static exclusive choice (≤6 items, worth showing in full) → `BbRadioGroup`.
+- Small static multi-choice submitted with a form → `BbCheckboxGroup`.
+- Each option is a live setting that applies the moment it flips → `BbSwitchGroup`.
+- The trigger is a status pill, avatar stack, or table-cell chip rather than a form field → `BbSelectPopover` (same search/options engine as `BbSelect`, you own the trigger).
+
+Never hand-assemble a row of `BbCheckbox`/`BbRadio` — the groups give you fieldset semantics, item mapping, and validation for free.
+
+---
+
+## Single Toggle
+
+| Need                                              | Component                      |
+| ------------------------------------------------- | ------------------------------ |
+| An answer or an agreement (accept terms, opt in)  | [BbCheckbox](../BbCheckbox.md) |
+| The on/off state of a thing (notifications, sync) | [BbSwitch](../BbSwitch.md)     |
+| One option interleaved with other markup          | [BbRadio](../BbRadio.md)       |
+
+**BbCheckbox vs BbSwitch — choose on what the control _means_, not on when it commits.** A switch is the on/off **state of a thing**: "Email notifications", "Anyone with the link can view", "Auto-renew". A checkbox is an **answer or a selection**: "I accept the terms", "Also send me a copy", a selected row.
+
+**A switch inside a submit-gated form is correct** — it commits with the form, exactly like every other field. This library ships `BbSwitch` from `bitboss-ui/validated` for that case, its own fixtures put one inside `<BbForm>`, and its wizard recipes put one behind a Next button. Do not downgrade a state toggle to a checkbox just because a Save button exists.
+
+The one thing to avoid is **mixing commit models on one surface**: switches that already took effect the moment they were flipped, sitting under a Save button that implies they had not. Pick one — either the whole panel is live, or the whole form commits on submit.
+
+A lone `BbRadio` is an escape hatch only — for a plain stacked group use `BbRadioGroup`.
+
+---
+
+## Buttons and Actions
+
+| Need                                                                                      | Component                                                                 |
+| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| A single action (or link-shaped button)                                                   | [BbButton](../BbButton.md)                                                |
+| A clickable/navigable surface that is not a variant button (card, row, tile, custom link) | [BbBaseButton](../BbBaseButton.md)                                        |
+| One dominant action + close alternates                                                    | [BbDropdownButton](../BbDropdownButton.md)                                |
+| Menu of actions with no dominant one                                                      | [BbDropdown](../BbDropdown.md)                                            |
+| Dangerous action requiring confirmation                                                   | [BbConfirm](../BbConfirm.md) + [useConfirm](../composables/useConfirm.md) |
+
+**Choosing by intent:**
+
+- `BbButton` — a single action, nothing else. Also a navigation trigger via `href`/`to` (see Navigation below). It is variant-first: use it when you want something that looks like a button.
+- `BbBaseButton` — any clickable/navigable surface that is _not_ a variant button: a whole card or list row that links somewhere, or a control styled entirely by your own CSS. It carries the same navigation engine as `BbButton` (`href`/`to`/Inertia/active classes) with zero chrome. Prefer it over hand-rolling `@click="router.push(...)"` on a `<div>`/`<a>`.
+- `BbDropdownButton` — _Save / Save as draft / Save as template_: the primary action is one tap away, alternates behind a chevron. If the "alternates" are unrelated commands, it's a plain menu.
+- `BbDropdown` — overflow "…" menus, account menus, context menus. Declare rows through `items`; never rebuild rows, dividers, or keyboard handling in markup. When the menu is just an `items` array with no header/footer/per-item slots, attach the `v-bb-dropdown` directive to the trigger instead of importing the component (see the directive note under Overlays).
+- Every destructive action must pass through `useConfirm` first.
+
+---
+
+## Feedback and Status
+
+| Need                                | Component                                                         |
+| ----------------------------------- | ----------------------------------------------------------------- |
+| Inline persistent status message    | [BbAlert](../BbAlert.md)                                          |
+| Transient notification (toast)      | [BbToast](../BbToast.md) + [useToast](../composables/useToast.md) |
+| Passive status pill, count, or dot  | [BbBadge](../BbBadge.md)                                          |
+| Removable token (filter, selection) | [BbBadge](../BbBadge.md) (with `clearable`)                       |
+| Clickable pill / filter chip        | [BbBadge](../BbBadge.md) + `BbBadgeButton` in its default slot    |
+| Determinate progress bar            | [BbProgress](../BbProgress.md)                                    |
+| Indeterminate loading spinner       | [BbSpinner](../BbSpinner.md)                                      |
+
+**BbAlert vs BbToast:** `BbToast` for _what just happened_ (saved, copied, uploaded — transient, floating, self-dismissing, fired via `useToast`); `BbAlert` for _the current state of the page_ (form error summary, quota banner — in normal document flow, stays until read or dismissed).
+
+**BbAlert has no default slot.** The body is the `text` prop (or the `#text` slot); children passed directly (`<BbAlert>some text</BbAlert>`) render nothing, silently — Vue drops an unconsumed default slot with no warning. Use `title`/`text` (or `#title`/`#text`) instead.
+
+**BbBadge vs BbTag vs BbIndicator:** `BbTag` _creates_ tokens (an input); `BbBadge` _displays_ tokens — passive by default, removable with `clearable` (renders a clear button), and interactive when a `BbBadgeButton` is slotted into it (the body becomes a real button/link; combine with `clearable` for the press-to-edit / ×-to-remove filter chip); `BbIndicator` pins a count/dot _over_ another element.
+
+**BbBadgeButton vs BbButton:** both are real buttons — pick by the shape the user should see. `BbButton` looks like a button (variant chrome, button sizing); `BbBadgeButton` makes a **pill** clickable, and only exists inside a `BbBadge`.
+
+**BbProgress vs BbSpinner:** `BbProgress` is for measurable completion (`min`→`max`); passing `null` renders an empty bar, not an indeterminate animation — use `BbSpinner` for waits with no measurable end.
+
+---
+
+## Overlays
+
+| Need                                      | Component                              |
+| ----------------------------------------- | -------------------------------------- |
+| Modal dialog (one focused task)           | [BbDialog](../BbDialog.md)             |
+| Side panel / drawer                       | [BbOffCanvas](../BbOffCanvas.md)       |
+| Yes/No confirmation dialog                | [BbConfirm](../BbConfirm.md)           |
+| Anchored floating interactive content     | [BbPopover](../BbPopover.md)           |
+| Hover/focus label                         | [BbTooltip](../BbTooltip.md)           |
+| Color picker on a trigger you own         | [BbColorPalette](../BbColorPalette.md) |
+| Date/calendar picker on a trigger you own | [BbDatePicker](../BbDatePicker.md)     |
+| Time picker on a trigger you own          | [BbTimePicker](../BbTimePicker.md)     |
+
+**BbDialog vs BbOffCanvas:** `BbDialog` for one focused task the user must finish (a form, a blocking announcement) — centred, takes focus. `BbOffCanvas` for supplementary content beside the main task (filters, a record's detail panel, settings). They share the same API (v-model, `title`, `header`/`default`/`footer` slots, `size`, `persistent`), so moving between them is mostly a tag swap. A plain yes/no is `BbConfirm`, not a hand-built dialog.
+
+**BbPopover vs BbTooltip:** `BbTooltip` is a short, non-interactive label on hover/focus — never put links, buttons, or fields in it. `BbPopover` opens on click, stays open, and supports interactive content. A standard list of actions is `BbDropdown`, not a popover.
+
+**Prefer the directive over the component for tooltips and dropdowns.** For the common case — plain-text tooltips and menus declared from an `items` array — attach `v-bb-tooltip` / `v-bb-dropdown` directly to the element instead of importing `BbTooltip`/`BbDropdown` and wiring an `activator`. The directives are registered globally by the plugin (`injectDirectives`, on by default), so no import is needed, and they render no wrapper element. Reach for the **component** only when you need something the directive can't express: for tooltips, a markup label (default slot) or the `activator` slot's scope; for dropdowns, `header`/`footer` or per-item slots, or `<BbDropdownGroup>` companions. When you already hold an element/ref, `BbDropdown`'s `activator` **prop** gives the same no-wrapper wiring without a slot. See [BbTooltip](../BbTooltip.md) and [BbDropdown](../BbDropdown.md).
+
+There are also **`v-bb-color`**, **`v-bb-date`**, and **`v-bb-time`** directives for the narrower case of a value picker on a bare trigger in a table cell — a color dot, a date cell, or a schedule cell — attach the directive instead of wrapping each cell in `BbColorPalette` / `BbDatePicker` / `BbTimePicker`. Unlike tooltip/dropdown this is _not_ a blanket "prefer the directive": these components (and `BbColorInput` / `BbDatePickerInput` / `BbTimePickerInput`) have a real `v-model`, so use the component for form fields; the directive is only for bare per-row triggers. A directive can't two-way bind, so write-back rides an `onUpdate:modelValue` callback in the binding value (plus `onUpdate:time` for a datetime picker). See [BbColorPalette](../BbColorPalette.md), [BbDatePicker](../BbDatePicker.md), and [BbTimePicker](../BbTimePicker.md).
+
+---
+
+## Navigation
+
+| Need                                  | Component                            |
+| ------------------------------------- | ------------------------------------ |
+| Peer views of the same screen (tabs)  | [BbTabs](../BbTabs.md)               |
+| Collapsible section (accordion style) | [BbAccordion](../BbAccordion.md)     |
+| Togglable region, custom trigger      | [BbCollapsible](../BbCollapsible.md) |
+| Breadcrumb path (where am I)          | [BbBreadcrumbs](../BbBreadcrumbs.md) |
+| Pagination controls                   | [BbPagination](../BbPagination.md)   |
+| Hierarchical tree                     | [BbTree](../BbTree.md)               |
+
+**Offload navigation to the component.** `BbButton`, dropdown items, and breadcrumb items accept `href` (anchor, or Inertia visit with `method`/`data`/`preserveScroll`/…) and `to` (vue-router); tabs items accept `href`; `BbPagination` with `navigation` builds per-page links itself. Never wire `@click="router.push(...)"` for a plain destination.
+
+**Picking the pattern:** `BbTabs` switches peer sections of _one_ subject (Overview / Activity / Settings) — not steps in a flow, not hierarchy. `BbBreadcrumbs` answers "where am I and how do I get back up". `BbPagination` steps through a paged result set — prefer it over infinite scroll when users need to find their place again.
+
+**Disclosure ladder (BbAccordion vs BbCollapsible vs BbSmoothHeight):**
+
+- `BbAccordion` — composed header button + collapsible body, ARIA wired for you. The default for FAQ/settings sections.
+- `BbCollapsible` — v-model region with **no header**; you bring the trigger (inline "read more" link, toolbar toggle).
+- `BbSmoothHeight` — no hide/show at all; only animates height changes (wizard steps, growing lists).
+
+---
+
+## Data Display
+
+| Need                          | Component                  |
+| ----------------------------- | -------------------------- |
+| Rows of records with columns  | [BbTable](../BbTable.md)   |
+| Hierarchical expandable nodes | [BbTree](../BbTree.md)     |
+| User or entity avatar         | [BbAvatar](../BbAvatar.md) |
+| Standalone SVG icon           | [BbIcon](../BbIcon.md)     |
+
+**BbTable vs BbTree:** flat rows with one level of detail → `BbTable` with its `#expand` slot; genuinely recursive data of unbounded depth (file browser, nested categories) → `BbTree`. For a select-a-value list in a form, use the Selection components — not a selectable table.
+
+Prefer icon **props** (`icon`, `prepend:icon`, item `icon`) on components over standalone `BbIcon`; reach for `BbIcon` only for iconography the design owns (status glyphs, empty states).
+
+---
+
+## Layout and Utility
+
+| Need                       | Component                              |
+| -------------------------- | -------------------------------------- |
+| Animated height transition | [BbSmoothHeight](../BbSmoothHeight.md) |
+
+---
+
+## Not in this library
+
+The 58 public `Bb*` components are the whole surface. Everything below is a
+component agents routinely assume exists, invent a name for, and then work
+around — usually by hand-rolling something the library already covers under a
+different name. **If a component you want is not in the tables above, it is not
+here.** Check this list before inventing a name; if the need is genuinely
+absent, compose it or write it yourself.
+
+| Assumed component                                              | Reality                                                                                                                                                                                                                                                                                                                                   |
+| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BbColumnManager` — show/hide/reorder columns                  | Does not exist. Compose `BbPopover` + `BbCheckbox` and persist the ordered visible keys yourself.                                                                                                                                                                                                                                         |
+| `BbKanban` / drag-and-drop board                               | Does not exist. There is no DnD primitive in the library at all — compose the board from `BbTable` (a table/list view of the same data) or hand-roll the drag-and-drop interaction yourself.                                                                                                                                              |
+| `BbModal`                                                      | It is [BbDialog](../BbDialog.md).                                                                                                                                                                                                                                                                                                         |
+| `BbDrawer` / `BbSheet`                                         | It is [BbOffCanvas](../BbOffCanvas.md).                                                                                                                                                                                                                                                                                                   |
+| `BbCombobox` / `BbAutocomplete`                                | It is [BbSelect](../BbSelect.md) / [BbSelectPopover](../BbSelectPopover.md) — search is built in, see `disable-writing`.                                                                                                                                                                                                                  |
+| `BbToggle` / `BbToggleGroup`                                   | It is [BbButton](../BbButton.md) with `v-model` (+ `true-value` / `false-value`), which owns `aria-pressed` and the active class.                                                                                                                                                                                                         |
+| `TagChip` / colored, read-only tag chip                        | It is [BbBadge](../BbBadge.md) — [BbTag](../BbTag.md) is a tags-_input_ only, not a display component. Use `BbBadge` with a registered `soft-*` variant for a fixed palette, or a one-off `--bg`/`--color` override per row for arbitrary/data-driven colors (BbBadge.md § One-off colors) — not a registered variant per distinct color. |
+| `BbTab` (singular)                                             | The consumer API is [BbTabs](../BbTabs.md) / `BbTabsRoot`. `BbTab` appears only as the **v2 "before" side** of the migration diffs.                                                                                                                                                                                                       |
+| `BbCard`                                                       | Does not exist — a card is a `<div>` with tokens. See [design-language](./design-language.md).                                                                                                                                                                                                                                            |
+| `BbStepper` / `BbWizard`                                       | Does not exist as a component; the wizard-form recipe composes one.                                                                                                                                                                                                                                                                       |
+| `BbSkeleton` (standalone)                                      | Only `BbTable` ships skeletons, via the column `skeleton` field.                                                                                                                                                                                                                                                                          |
+| `BbCommand` / command palette                                  | Does not exist. Compose `BbDialog` + `BbSelectPopover`.                                                                                                                                                                                                                                                                                   |
+| `BbCalendar` (month / scheduling view)                         | Does not exist. [BbDatePicker](../BbDatePicker.md) is a picker, not a calendar surface.                                                                                                                                                                                                                                                   |
+| `BbChart` / `BbGraph`, `BbCarousel`, `BbTimeline`, `BbDivider` | Do not exist. No charting, carousel or timeline primitive ships here.                                                                                                                                                                                                                                                                     |
+
+App chrome — an app shell, sidebar, page header, selection dock — is
+deliberately **not** a component: it is yours to own. The per-platform
+[Layout Scaffold](../recipes/inertia/layout-scaffold.md) recipe ships the source
+to copy.
+
+---
+
+## Item-Driven Components
+
+The following components accept an `items` prop (array or async provider function) with `item-text`/`item-value` mapping. Consult the items playbooks before wiring them:
+
+- [BbSelect](../BbSelect.md), [BbSelectPopover](../BbSelectPopover.md)
+- [BbCheckboxGroup](../BbCheckboxGroup.md), [BbRadioGroup](../BbRadioGroup.md), [BbSwitchGroup](../BbSwitchGroup.md)
+- [BbTable](../BbTable.md)
+
+`BbDropdown`, `BbBreadcrumbs`, `BbTabs`, and `BbTree` are also declared through `items`, but with typed item objects (label/key/href/…) rather than arbitrary domain objects.
+
+See:
+
+- [Options and Items Playbook](./options-items-playbook.md)
+- [Fetch Data Items Playbook](./fetch-items-playbook.md)
+- [Coherence Playbook](./coherence-playbook.md)