bitboss-ui 2.1.135 → 3.0.0-alpha.1

package/dist/ai/composables/useToast.md

@@ -0,0 +1,230 @@
+---
+title: useToast
+summary: Fire, update, and dismiss transient toast notifications from anywhere — returns { toast, dismiss, update }.
+type: composable
+---
+
+# useToast
+
+## Summary
+
+`useToast` is the imperative API behind `BbToast`: call `toast(...)` from any
+event handler to enqueue a transient, self-dismissing notification. Toasts stack
+per viewport corner and disappear on their own (default **4000 ms**).
+
+**Requires** a single `<BbToast />` host mounted once in the application layout —
+without it, messages are enqueued but never rendered.
+
+Rule of thumb: `useToast` for _what just happened_ ("Saved", "Upload complete"),
+`BbAlert` for the _current state of the page_ (a form error summary, a banner).
+
+## Import
+
+```ts
+import { useToast } from 'bitboss-ui';
+
+const { toast, dismiss, update } = useToast();
+```
+
+All three operate on one shared module-level stack — every `useToast()` call in
+the app talks to the same host.
+
+## API
+
+### `toast(input)`
+
+Enqueues a toast and returns its `id` (keep it to `update` or `dismiss` that
+specific toast later).
+
+```ts
+toast(input: string | BbToastOptions): string
+```
+
+The string shorthand shows a plain title: `toast('Changes saved.')`.
+
+### `BbToastOptions`
+
+| Option        | Type                      | Default                          | Description                                                                                                                                                                                         |
+| ------------- | ------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`       | `string`                  | —                                | Bold headline. At least one of `title`, `text`, `portal` should be set (dev warning otherwise).                                                                                                     |
+| `text`        | `string`                  | —                                | Body copy under the title.                                                                                                                                                                          |
+| `variant`     | `BbToastVariant`          | `'default'`                      | Visual tone. Registered variants (`success`, `info`, `warning`, `destructive` in the default setup) are typed; any string works for one-off variants (style `.bb-toast-message--<variant>`).        |
+| `icon`        | `IconType`                | —                                | Optional leading icon (`lucide:*` preferred, e.g. `'lucide:circle-check'`). No icon is implied by the variant.                                                                                      |
+| `loading`     | `boolean`                 | `false`                          | Shows a spinner and pins the toast open (implies `persistent`). Morph it later with `update(id, ...)`.                                                                                              |
+| `duration`    | `number`                  | `4000`                           | Milliseconds before auto-dismiss. Must be `> 0` — `toast()` throws otherwise. Ignored when persistent.                                                                                              |
+| `persistent`  | `boolean`                 | `loading`                        | Never auto-dismiss; user closes it, or your code calls `dismiss(id)`.                                                                                                                               |
+| `hideClose`   | `boolean`                 | `false`                          | Hides the close button. Only combine with `persistent` when code will dismiss the toast itself.                                                                                                     |
+| `position`    | `BbToastPosition`         | host → plugin → `'bottom-right'` | One of the six corners: `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`. Per-message override of the host's `position` prop and the plugin's `toastPosition`. |
+| `actions`     | `ActionButtonConfig[]`    | —                                | Buttons rendered in a row below the text (undo, retry…). See **Action buttons** below. Not rendered for portal toasts.                                                                              |
+| `portal`      | `Component \| string`     | —                                | Rich custom content: a `<BbToastPortal name="...">` name, or a component rendered in the toast body.                                                                                                |
+| `portalProps` | `Record<string, unknown>` | —                                | Data for the portal content (slot `props` for named portals, `v-bind` props for component portals).                                                                                                 |
+| `id`          | `string`                  | generated                        | Providing an existing id upserts that toast in place instead of stacking a new one.                                                                                                                 |
+
+### `dismiss(id?)`
+
+```ts
+dismiss(id?: string): string | undefined
+```
+
+With an `id`, removes that toast (after its exit transition). **With no
+argument, clears the entire stack.**
+
+### `update(id, options)`
+
+```ts
+update(id: string, options: Partial<BbToastOptions>): string
+```
+
+Patches a live toast in place — same `BbToastOptions` fields — and restarts its
+auto-dismiss countdown. Unknown ids are a safe no-op. This is the
+loading-then-resolve primitive: fire with `loading: true`, then `update` into a
+success or error when the work settles.
+
+## Required layout setup
+
+Mount the host once near the app root (the default layout on Nuxt/Inertia):
+
+```vue
+<template>
+	<RouterView />
+	<BbToast />
+</template>
+
+<script setup lang="ts">
+import { BbToast } from 'bitboss-ui';
+</script>
+```
+
+## Usage examples
+
+### Fire from an action
+
+```vue
+<template>
+	<BbButton prepend:icon="lucide:copy" variant="outline" @click="copyLink">
+		Copy invite link
+	</BbButton>
+</template>
+
+<script setup lang="ts">
+import { BbButton, useToast } from 'bitboss-ui';
+
+const { toast } = useToast();
+
+const copyLink = async () => {
+	await navigator.clipboard.writeText('https://app.example.com/invite/9f2c');
+	toast({
+		title: 'Link copied',
+		variant: 'success',
+		position: 'bottom-center',
+	});
+};
+</script>
+```
+
+### Loading, then resolve
+
+```vue
+<template>
+	<BbButton prepend:icon="lucide:upload" variant="primary" @click="upload">
+		Upload invoice
+	</BbButton>
+</template>
+
+<script setup lang="ts">
+import { BbButton, useToast } from 'bitboss-ui';
+
+const { toast, update } = useToast();
+
+const upload = async () => {
+	const id = toast({ title: 'Uploading invoice.pdf…', loading: true });
+	try {
+		await api.documents.upload(file);
+		update(id, {
+			title: 'invoice.pdf uploaded',
+			variant: 'success',
+			icon: 'lucide:circle-check',
+			loading: false,
+		});
+	} catch {
+		update(id, {
+			title: 'Upload failed',
+			text: 'Check your connection and retry.',
+			variant: 'destructive',
+			loading: false,
+		});
+	}
+};
+</script>
+```
+
+### Action buttons — the undo pattern
+
+`actions` takes an array of `ActionButtonConfig` (same shape as the confirm
+buttons: `text`, `variant` — default `'outline'` —, `size` — default `'md'` —,
+`prepend:icon`/`append:icon`/`icon`, `block`, `onClick`). While a button's
+`onClick` runs it shows a spinner, siblings are disabled, and the auto-dismiss
+countdown is held; the toast dismisses itself (reason `'action'`) when the
+callback resolves. A rejected callback keeps the toast open and the countdown
+resumes.
+
+```ts
+const removed = list.splice(index, 1)[0]; // commit immediately, no confirm
+toast({
+	title: `“${removed.name}” deleted`,
+	duration: 5000,
+	actions: [
+		{
+			text: 'Undo',
+			onClick: () => list.splice(index, 0, removed),
+		},
+	],
+});
+```
+
+Failure and re-purposing compose into the retry pattern: a **rejected**
+handler keeps the toast open (and the countdown resumes), while a handler
+that calls `update(id, ...)` **takes ownership** — instead of dismissing, the
+toast morphs in place with a fresh countdown:
+
+```ts
+const id = toast({
+	title: 'Sync failed',
+	variant: 'destructive',
+	duration: 10000,
+	actions: [
+		{
+			text: 'Retry',
+			variant: 'primary',
+			onClick: async () => {
+				await api.sync(); // a rejection keeps the toast open for another try
+				update(id, {
+					title: 'Workspace synced',
+					variant: 'success',
+					actions: [],
+					duration: 3000,
+				}); // …and an update morphs it instead of dismissing
+			},
+		},
+		{ text: 'Ignore' },
+	],
+});
+```
+
+## Anti-patterns
+
+- Don't put must-act information only in a toast — it self-dismisses. Mirror
+  critical state in the page (`BbAlert` or inline copy).
+- Don't mount `<BbToast />` per page or per component; one host serves the app.
+- Don't hand-roll notification markup — buttons under the message are the
+  `actions` option; for richer content use `<BbToastPortal>` (its slot receives
+  `{ toast, props, close }`), and even then sparingly. A toast needing more
+  than one or two actions is usually a `BbConfirm`.
+- `warning`/`destructive` toasts announce assertively (`role="alert"`); use the
+  calmer variants for routine confirmations.
+
+## Related
+
+- [BbToast](../BbToast.md) — the host component and portal mechanics.
+- [BbAlert](../BbAlert.md) — inline, persistent status messages.
+- [useConfirm](./useConfirm.md) — when the user must decide, not just be told.

package/dist/ai/guides/agent-contract.md

@@ -0,0 +1,108 @@
+---
+title: Agent Contract
+summary: Mandatory rules for AI agents using bitboss-ui in consumer projects.
+---
+
+# Agent Contract
+
+Use this contract before generating any UI code with `bitboss-ui`.
+
+## Default API Boundary
+
+1. Prefer `Bb*` components in consumer-facing code.
+2. Treat low-level primitives (`Base*`, `BbBase*`, `Common*`, listbox internals) as reference-only — **except `BbBaseButton`**, which is a first-class consumer component: the unstyled navigable primitive for any clickable surface (cards, rows, custom links) that isn't a variant-first `BbButton`.
+3. Use the other reference-only components only when the user explicitly asks for internal composition details.
+
+## Setup-First Rule
+
+Before writing component usage code, verify:
+
+- `bitboss-ui` is installed;
+- the build plugin is configured (`bitboss-ui/vite` in Vite/Inertia apps, `bitboss-ui/nuxt` in Nuxt apps) — it serves the `virtual:bitboss-ui/icons` and `virtual:bitboss-ui/config` modules;
+- the runtime plugin is installed (`app.use(bitbossUiPlugin)`; the Nuxt module does this for you), which injects `bitboss-ui/styles.css` unless `injectStyles: false`.
+
+If setup is missing, provide setup code first ([Installation and Plugin Setup](./installation-and-plugin-setup.md)), then component examples.
+
+## Knowledge Base: Router First, Then Curated Guides
+
+Read the installed package knowledge base before recommending components:
+
+1. **`dist/ai/guides/ai-router.md`** — tiny hop map (which file to open next).
+2. **`dist/ai/index.md`** — full catalogue only when the router is not enough.
+
+Every component doc (`dist/ai/<Name>.md`) **leads with a "Usage & Guidelines" section** — a curated, runtime-tested guide with live examples. Read it before the raw props/events/slots tables, and prefer its idioms over anything you would infer from the API surface alone. If a guide shows one way to do something, that is the idiomatic way.
+
+Consumer projects should run `npx bitboss-ui ai-init` once so AGENTS.md / Cursor / Copilot / Claude / Windsurf all point at this corpus.
+
+## Navigation Rule
+
+Offload navigation to the component. The navigation engine lives in `BbBaseButton`, the primitive every button wraps — so `BbButton`, `BbDropdownButton`, `BbBaseButton` itself, and every item-driven surface built on the same core (dropdown items, breadcrumb items, tabs items, pagination in `navigation` mode) all navigate by themselves. Push _as much navigation as possible_ onto this surface — any click whose result is a destination belongs here, not in an `@click` handler:
+
+- `href` — renders an anchor; in an Inertia app it becomes an Inertia visit and accepts `method`, `data`, `headers`, `preserveScroll`, `replace`, …;
+- `to` — vue-router `RouteLocationRaw`, rendered as a router link (tabs items use `href`; pagination `navigation` builds per-page `to`/`href` links itself).
+
+**NEVER** write `@click="router.push(...)"` (or `window.location = ...`) for something the component can navigate to itself. Click handlers are for actions; destinations go in `href`/`to`.
+
+## Item-Driven Components Rule
+
+For components accepting `items`:
+
+- prefer declarative mapping with `item-text` and `item-value`;
+- use `dependencies` and `deps-debounce-time` for tied fields;
+- use `enforce-coherence` instead of custom watchers for stale model cleanup.
+
+## Icons Rule
+
+External-provider-first: prefer iconify provider icons — default set `lucide:*` — sourced from `@iconify-json/*` packages the consumer installs separately (`npm i -D @iconify-json/lucide`). Use `local:*` SVGs only for brand-specific art placed in the configured `iconDir`. Only reference icons from installed providers or existing local files — **never invent icon names**. Full workflow: [Icons Policy](./icons-policy.md).
+
+## Variants Rule
+
+Unlike icons, variants are **not** a fixed vocabulary you must stay inside. The
+shipped names (`primary`, `secondary`, `destructive`, `outline`, …) are the
+**floor**; the registries are open on purpose so an app can add the tones its
+design needs. When a design calls for a colour the library does not ship — soft
+semantic status badges, a brand button tone — **add it, in both halves**:
+
+1. **Register the name** in the build plugin: `badgeVariants`, `buttonVariants`,
+   `alertVariants`, `confirmVariants`, `dropdownItemVariants`, `tooltipVariants`,
+   `toastVariants`, `indicatorVariants` (`bitboss-ui/vite` or `bitboss-ui/nuxt`).
+   The plugin regenerates the typed registry, so the name type-checks.
+2. **Style the class** — `.bb-badge.bb-badge--<name>`, `.bb-button--<name>`, … —
+   in a project stylesheet loaded **after** `bitboss-ui/styles.css`. The library
+   ships no CSS for names it does not own.
+
+Half the job is a bug in both directions: a registered name with no CSS renders
+an unstyled pill (the original "warning badge" hallucination), and CSS with no
+registration fails `vue-tsc`. Equally, **do not downgrade the design** — falling
+back to `secondary`/`outline` because a status palette "isn't available" is the
+wrong fix; registering it is a two-file change you are expected to make.
+
+Never write a variant name that is neither shipped nor registered. Canonical
+soft status palette (accents, the shared treatment, and why the selectors are
+doubled): [Design Language](./design-language.md) § Getting soft semantic badges.
+Where the option goes: [Installation and Plugin Setup](./installation-and-plugin-setup.md).
+
+## Overlay Open-State Rule
+
+Overlay visibility is controlled by the component's **primary `v-model`** — never a separate `v-model:open`. The standalone overlays (`BbDialog`, `BbOffCanvas`, `BbPopover`, `BbTooltip`) expose a boolean `v-model` for open state. The popover-embedded surfaces (`BbDropdown`, `BbSelectPopover`, `BbColorPalette`) keep open state **internal** — drive them through their trigger/activator, not a bound open flag. There is no `v-model:open` anywhere in the library, by design; do not reach for one.
+
+## Boolean Prop Defaults Rule
+
+Boolean props default to `false` so the bare `<Comp foo>` shorthand turns the feature **on**. A few props deliberately default to `true` for cross-library keyword clarity — pass `:prop="false"` to opt out:
+
+- `multiple` on `BbTable`, `BbCheckboxGroup`, `BbSwitchGroup` — multi-select is the expected default; `:multiple="false"` forces single-select.
+- `hideArrow` on `BbPopover`, `BbSelectPopover` — the arrow is hidden by default; `:hide-arrow="false"` shows it.
+- `selectable` on the item-driven components (`BbSelect`, `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`, `BbTable`) — items are selectable by default; pass a predicate or `false` to restrict.
+
+These are the only intentional default-`true` booleans; anywhere else, `true` default is a bug (`check-api` flags it).
+
+## Safety Checklist
+
+- [ ] Started from the AI Router (or already knows the next hop).
+- [ ] Recommends `Bb*` components by default.
+- [ ] Uses only existing props/events/slots from library types.
+- [ ] Read the component's "Usage & Guidelines" section before writing usage code.
+- [ ] Navigation goes through `href`/`to` on buttons and items — no `router.push` click handlers for plain destinations.
+- [ ] Uses only icons from installed `@iconify-json/*` providers or existing `local:*` files.
+- [ ] Avoids reference-only imports unless explicitly requested.
+- [ ] Uses declarative coherence/dependencies before manual watchers.

package/dist/ai/guides/ai-router.md

@@ -0,0 +1,111 @@
+---
+title: AI Router
+summary: Tiny start-here map for any coding agent — which file to open next, in which order, without loading the full catalogue.
+---
+
+# AI Router
+
+Read this file first. Open **at most one** deeper file per hop. Do not load
+every recipe or every component contract into context.
+
+Knowledge base root (installed package):
+`node_modules/bitboss-ui/dist/ai/`
+
+Package export entry: `bitboss-ui/ai` → `dist/ai/index.md`.
+Subpaths: `bitboss-ui/ai/components.json`, `bitboss-ui/ai/guides/…`, etc.
+
+**Not installed, or can only fetch URLs?** The same files are served from the
+published package at `https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/…`.
+If you can make only one request, fetch
+[`…@alpha/dist/llms-medium.txt`](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-medium.txt)
+— this router plus the agent contract, setup, component picker, design language
+and the full component catalogue, in ~74 KB.
+
+---
+
+## Mandatory order (every UI task)
+
+1. **[Agent contract](./agent-contract.md)** — hard rules (Bb\* boundary,
+   setup-first, `href`/`to` navigation, icons, coherence).
+2. **Setup?** If the project may not have the plugin yet →
+   [Installation & Plugin Setup](./installation-and-plugin-setup.md).
+3. **Choose intent:**
+   - Whole page / flow → hop to **Recipes** below (one platform file only).
+   - Single control → [Component picker](./component-picker.md), then open
+     **one** `../<ComponentName>.md` contract (Usage & Guidelines first).
+4. **Never invent props.** Confirm names in that contract or in
+   [`../components.json`](../components.json).
+
+---
+
+## Recipes (page-level — pick one platform)
+
+Folders: `../recipes/vue/`, `../recipes/nuxt/`, `../recipes/inertia/`.
+
+Same page shapes on each platform; only the data/mutation layer differs.
+
+| Intent                               | Recipe file (kebab)        |
+| ------------------------------------ | -------------------------- |
+| Filterable listing + bulk/peek       | `records-workspace.md`     |
+| Create/edit form                     | `record-form.md`           |
+| Inline-edit table / backlog          | `inline-edit-workspace.md` |
+| Hierarchy drill-down (nested tables) | `ownership-atlas.md`       |
+| Approvals / triage inbox             | `approvals-inbox.md`       |
+| Uploads + editable queue             | `upload-center.md`         |
+| Multi-step wizard                    | `wizard-form.md`           |
+| Onboarding checklist                 | `onboarding.md`            |
+
+No recipe for detail-with-tabs, settings, dashboards, or profile pages —
+compose those from the closest listing/form recipe plus the guides
+(page shell, tabs, inline-edit playbook) instead of inventing a new shape.
+
+---
+
+## Playbooks (only when the pattern applies)
+
+| Need                                   | Guide                                                 |
+| -------------------------------------- | ----------------------------------------------------- |
+| Tied selects / stale model cleanup     | [coherence-playbook](./coherence-playbook.md)         |
+| Async `items` providers / prefill      | [fetch-items-playbook](./fetch-items-playbook.md)     |
+| `item-text` / `item-value` / disabled  | [options-items-playbook](./options-items-playbook.md) |
+| Table cell edit ownership              | [inline-edit-playbook](./inline-edit-playbook.md)     |
+| Icons (`lucide:*`, never invent names) | [icons-policy](./icons-policy.md)                     |
+| Tokens / styling around components     | [design-language](./design-language.md)               |
+| Upgrading from bitboss-ui 2.x          | [migration/v2-to-v3](./migration/v2-to-v3.md)         |
+
+---
+
+## Full catalogue (last resort)
+
+- [Component index](../index.md) — every consumer + reference-only entry
+- [components.json](../components.json) — machine-readable API for validation
+- Composables: `../composables/` (`useToast`, `useConfirm`, table/tabs context, …)
+
+Reference-only (`BbBase*` form primitives, listbox internals, …) — **do not
+import in consumer apps** unless the user explicitly asks for internals.
+Exception documented in the agent contract: **`BbBaseButton` is consumer API**.
+
+---
+
+## Consumer kickstart
+
+In the app repo (once), after installing `bitboss-ui`:
+
+```bash
+npx bitboss-ui ai-init
+# optional: also register the MCP server
+npx bitboss-ui ai-init --mcp
+```
+
+Writes harness-agnostic pointers (`AGENTS.md`) plus Cursor / Copilot / Claude /
+Windsurf rules so agents find this router without being told.
+
+After writing Bb\* markup, validate against the installed contract:
+
+```bash
+npx bitboss-ui check
+# or: npx bitboss-ui check 'src/**/*.{vue,md}' --json
+```
+
+Optional MCP (`npx bitboss-ui mcp`): search/get components, list/get recipes,
+validate snippets — version-matched to the installed package.