bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/guides/floating-bottom-panel.md

@@ -0,0 +1,191 @@
+---
+title: Floating Bottom Panel
+summary: 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.
+---
+
+# Floating Bottom Panel
+
+The bulk-action surface of a modern listing page (Linear, Gmail): select
+rows and a **dark toolbar slides up from the bottom**, showing the count
+and the actions that apply to the selection; empty the selection and it
+slides away. It floats over the content, never pushes layout.
+
+App code, not a `bitboss-ui` export — copy it into your project
+(conventionally `src/components/layout/`). The listing recipes wire it to
+table selection per platform; this guide is the component itself.
+
+## The component
+
+Visibility is a plain `open` prop — the panel owns _how_ it appears, the
+page owns _when_. The signature move is the token swap: the panel re-binds
+`--bb-panel` / `--bb-text` locally, so the bitboss-ui buttons inside render
+on the dark surface without any special props.
+
+```vue
+<!-- src/components/layout/FloatingBottomPanel.vue -->
+<template>
+	<Teleport to="body">
+		<Transition name="floating-bottom-panel">
+			<div
+				v-if="open"
+				:aria-label="label"
+				class="floating-bottom-panel"
+				:class="`floating-bottom-panel--${size}`"
+				role="toolbar"
+			>
+				<slot />
+			</div>
+		</Transition>
+	</Teleport>
+</template>
+
+<script setup lang="ts">
+const {
+	open,
+	size = 'sm',
+	label = 'Bulk actions',
+} = defineProps<{
+	open: boolean;
+	/** Max width preset: sm 768px, md 1024px, lg 1280px. */
+	size?: 'sm' | 'md' | 'lg';
+	label?: string;
+}>();
+</script>
+
+<style scoped>
+.floating-bottom-panel {
+	/* Dark surface via local token swap: children keep reading bb tokens. */
+	--bb-panel: #26262a;
+	--bb-text: #ffffff;
+
+	align-items: center;
+	background: var(--bb-panel);
+	border-radius: var(--bb-radius);
+	bottom: 24px;
+	box-shadow: 0 8px 24px rgb(0 0 0 / 0.25);
+	color: var(--bb-text);
+	display: flex;
+	gap: 4px;
+	height: 40px;
+	left: 50%;
+	max-width: min(768px, calc(100vw - 48px));
+	min-width: max-content;
+	padding: 0 8px;
+	position: fixed;
+	transform: translateX(-50%);
+	z-index: 50;
+}
+
+.floating-bottom-panel--md {
+	max-width: min(1024px, calc(100vw - 48px));
+}
+
+.floating-bottom-panel--lg {
+	max-width: min(1280px, calc(100vw - 48px));
+}
+
+/* Anything slotted with this class is pushed to the right edge. */
+.floating-bottom-panel :deep(.floating-bottom-panel__right) {
+	margin-left: auto;
+}
+
+.floating-bottom-panel-enter-active,
+.floating-bottom-panel-leave-active {
+	transition:
+		transform 200ms ease,
+		opacity 200ms ease;
+}
+
+.floating-bottom-panel-enter-from,
+.floating-bottom-panel-leave-to {
+	opacity: 0;
+	transform: translateX(-50%) translateY(12px);
+}
+</style>
+```
+
+## Usage
+
+The panel appears whenever the bound selection is non-empty. Inside it,
+`sm` buttons are the right density — this is a compact toolbar, the
+documented exception to the `md`-first button rule (see the
+[Design Language guide](./design-language.md)).
+
+```vue
+<template>
+	<FloatingBottomPanel :open="selectedCount > 0">
+		<span class="floating-bottom-panel__count"
+			>{{ selectedCount }} selected</span
+		>
+		<BbButton
+			prepend:icon="lucide:check"
+			size="sm"
+			variant="ghost"
+			@click="markPaid"
+		>
+			Mark as paid
+		</BbButton>
+		<BbButton
+			prepend:icon="lucide:send"
+			size="sm"
+			variant="ghost"
+			@click="sendReminders"
+		>
+			Send reminder
+		</BbButton>
+		<div class="floating-bottom-panel__right">
+			<BbButton size="sm" variant="destructive" @click="deleteSelected"
+				>Delete</BbButton
+			>
+			<BbButton
+				aria-label="Clear selection"
+				icon="lucide:x"
+				size="sm"
+				variant="ghost"
+				@click="clear"
+			/>
+		</div>
+	</FloatingBottomPanel>
+</template>
+```
+
+Where `selectedCount` comes from depends on the platform:
+
+- **Vue / Nuxt** — the library's
+  [`useBbTableContext`](../composables/useBbTableContext.md) by table id:
+  the bar takes zero props from the table.
+- **Inertia** — the app-side selection context from the
+  [Inertia Helpers](./inertia-helpers.md) toolkit
+  (`useTableSelectionContext`), which also models select-all-across-pages.
+
+The listing recipes show the full wiring, including the confirm-guarded
+destructive path and clearing the selection after a bulk action.
+
+## Design notes and enhancements
+
+- **One concern.** The panel is presentation: position, elevation, dark
+  surface, enter/leave motion. Counting, action dispatch and confirmation
+  belong to the page (via its selection context) — don't grow props for
+  them here.
+- **Actions open surfaces, they don't inline them.** A bulk action needing
+  input opens a `BbDialog`/`BbOffCanvas`; destructive ones go through
+  `useConfirm` with the count in the message ("Delete 12 invoices?").
+- Worthwhile enhancements, left out of the baseline:
+  - **Top-layer rendering** via the Popover API (`popover="manual"` +
+    `showPopover()` on open) instead of `z-index`, so the bar can never be
+    stacked over by page chrome.
+  - **Sidebar-aware centering**: offset `left`/`right` by the app
+    sidebar's and the [Page Shell](./page-shell.md) panel's widths (CSS
+    variables + multipliers) so the bar stays centered over the _visible_
+    content, and compensate for scrollbar width.
+  - **Keyboard path**: pair with `useDeleteCmd` from the
+    [Inertia Helpers](./inertia-helpers.md) (works on any platform) so
+    Delete triggers the same guarded bulk delete.
+
+## Related
+
+- [Recipe: CRUD Listing Page (Vue)](../recipes/vue/crud-listing-page.md) /
+  [(Nuxt)](../recipes/nuxt/crud-listing-page.md) /
+  [(Inertia)](../recipes/inertia/crud-listing-page.md) — full wiring per
+  platform.
+- [BbToast](../BbToast.md) — feedback after a bulk action completes.

package/dist/ai/guides/icons-policy.md

@@ -0,0 +1,257 @@
+---
+title: Icons Policy
+summary: 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.
+---
+
+# Icons Policy
+
+Mandatory for AI-generated code.
+
+## Rules
+
+1. **Prefer provider icons.** The house UI set is `lucide:*`. Provider sets are
+   plain npm packages the consumer sources separately
+   (`npm install -D @iconify-json/lucide`); the plugin resolves them
+   automatically — no registration step.
+2. **`local:*` is for brand-specific art only** — logos, custom marks, one-off
+   illustrations. They are SVG files in the configured `iconDir`.
+3. **Never invent icon names.** Use only names that exist in an installed
+   `@iconify-json/*` set or as files in `iconDir`. A missing icon throws at
+   mount (dev shows a Vite error overlay with the exact fix).
+4. **Icon names must be static string literals.** Production builds scan source
+   for `provider:name` literals and bundle only those — a name assembled at
+   runtime (`` `lucide:${kind}` ``) will be missing in production. Map dynamic
+   state to literals instead (e.g. a lookup object of full names).
+5. **Never hand-place `BbIcon` where a component already accepts an icon** via
+   a prop, item field, or dedicated slot (catalog below).
+
+## How resolution works
+
+The `bitbossUi` Vite plugin (`iconDir` option) — or the Nuxt module (config key
+`bitboss`, default `iconDir: './assets/icons'`) — serves every icon through the
+`virtual:bitboss-ui/icons` module that `bitbossUiPlugin` provides to `BbIcon`:
+
+- **Provider sets**: every `@iconify-json/*` package found in `node_modules` is
+  auto-discovered. Installing `@iconify-json/lucide` makes every valid
+  `lucide:<name>` available; removing it makes them all errors. Nothing to
+  configure.
+- **Dev**: all icons of installed sets are registered. Referencing an
+  uninstalled prefix or a non-existent name fails loudly with an actionable
+  message (`"lucide:fo" requires "@iconify-json/lucide" — run: npm install -D …`
+  or `icon "x" does not exist in the lucide icon set`).
+- **Build**: source files (`.vue`/`.ts`/`.js`/`.tsx`/`.jsx`; tests and stories
+  excluded) are scanned for static `provider:name` literals; each referenced
+  icon is emitted as its own lazy chunk. This is why rule 4 exists — and why an
+  icon used only in a `.stories.ts`/`.test.ts` file must also appear as a
+  literal in a scanned source file.
+- **Local icons**: `iconDir` is scanned recursively; each `.svg` becomes
+  `local:<basename-without-extension>`. A bare, unprefixed name normalizes to
+  `local:`. Adding/removing files is picked up live in dev, and the plugin
+  maintains a collection JSON plus the VS Code `iconify.customCollectionJsonPaths`
+  setting so the Iconify editor extension previews local icons too.
+- **Raw SVG escape hatch**: `BbIcon`'s `icon` prop also accepts a full
+  `<svg>…</svg>` string (e.g. an asset imported with `?raw`) for a one-off mark
+  that lives in no collection.
+
+Gotcha: heroicons `-20-`/`-16-` size-variant names are hard-filtered (CSS
+controls size, so they are redundant). Use base names — `heroicons:check`, not
+`heroicons:check-16-solid`.
+
+### Discovery workflow
+
+1. List installed sets: look for `@iconify-json/*` in the consumer's
+   `package.json`. If none fits, propose installing one (default suggestion:
+   `@iconify-json/lucide`).
+2. Verify each name exists in that set's `icons.json` (or its `aliases`) before
+   using it.
+3. For `local:*`, list the `.svg` files in the configured `iconDir`.
+
+## Where the library accepts icons — full catalog
+
+### Standalone `BbIcon`
+
+Only for iconography the design owns — a status glyph in a table cell,
+empty-state art, a custom composition. Every surface below is preferred when it
+exists.
+
+```html
+<BbIcon icon="lucide:circle-check" size="sm" label="Paid" />
+```
+
+### Button icons
+
+- `BbButton` — `prepend:icon` / `append:icon` beside the label; `icon` renders
+  an icon-only button. The label content (default slot, preferred over `text`)
+  still supplies the accessible name — it is just rendered `sr-only`. Use
+  `aria-label` only to override that name, not as the default.
+
+```html
+<BbButton prepend:icon="lucide:plus">New invoice</BbButton>
+<BbButton variant="outline" append:icon="lucide:download">Export</BbButton>
+<!-- Accessible name from slot content, hidden visually — no aria-label needed. -->
+<BbButton variant="ghost" icon="lucide:settings">Settings</BbButton>
+```
+
+- `BbDropdownButton` — `prepend:icon` / `append:icon` on the main action;
+  `right:icon` replaces the chevron inside the split toggle.
+
+```html
+<BbDropdownButton
+	text="Export"
+	prepend:icon="lucide:download"
+	:items="exportFormats"
+/>
+```
+
+### Input affix icons
+
+Every batteries-included input takes `prepend:icon` / `append:icon`; the input
+wrapper places, sizes, and colors the glyph (the append side may already host
+clear/stepper/toggle controls — prefer `prepend:icon` when in doubt):
+
+```html
+<BbTextInput
+	v-model="query"
+	label="Search members"
+	prepend:icon="lucide:search"
+/>
+<BbNumberInput v-model="amount" label="Amount" prepend:icon="lucide:euro" />
+<BbSelect
+	v-model="plan"
+	label="Plan"
+	:items="plans"
+	prepend:icon="lucide:layers"
+/>
+<BbDatePickerInput
+	v-model="dueDate"
+	label="Due date"
+	prepend:icon="lucide:calendar"
+/>
+<BbColorInput
+	v-model="brandColor"
+	label="Brand color"
+	append:icon="lucide:pipette"
+/>
+<BbTextarea
+	v-model="notes"
+	label="Internal notes"
+	prepend:icon="lucide:sticky-note"
+/>
+```
+
+### Status and metadata surfaces
+
+- `BbAlert` — `icon` (plus `iconSize`):
+  `<BbAlert variant="warning" icon="lucide:triangle-alert" text="Subscription expires in 3 days." />`
+- `BbToast` — `icon` in the `useToast()` options (variants set tone only, no
+  default glyph):
+  `toast({ title: 'Invoice sent', variant: 'success', icon: 'lucide:send' })`
+- `BbBadge` — `prepend:icon` / `append:icon` beside the default-slot label;
+  `icon` makes an icon-only badge (the other two are then ignored):
+  `<BbBadge variant="primary" prepend:icon="lucide:credit-card">Paid</BbBadge>`
+- `BbTag` (tokens input) — `prepend:icon` / `append:icon` on the field, like
+  the other inputs: `<BbTag v-model="skills" label="Skills" prepend:icon="lucide:tag" />`
+
+### Item-config icons (declared in data, not markup)
+
+`BbDropdown` entries — items **and** group headers — carry `'prepend:icon'` /
+`'append:icon'` fields. `append:icon` is ignored when the item opens a submenu
+(chevron) or sits in a selectable group (check).
+
+```ts
+const memberActions = [
+	{ key: 'edit', text: 'Edit member', 'prepend:icon': 'lucide:pencil' },
+	{
+		key: 'delete',
+		text: 'Delete',
+		variant: 'destructive',
+		'prepend:icon': 'lucide:trash-2',
+	},
+];
+```
+
+`BbDropdownButton` reuses the same `items` shape, so its menu entries get icons
+the same way.
+
+### Slot-injected icons (components with no icon prop)
+
+These surfaces take arbitrary content, so you place a `BbIcon` (or richer
+markup) yourself:
+
+- `BbTabs` / `BbTabsList` — per-tab `label-{key}` slot (or the generic `label`
+  fallback):
+
+```html
+<BbTabs v-model="tab" :items="tabs">
+	<template #label-billing="{ text }">
+		<BbIcon icon="lucide:file-text" size="sm" /> {{ text }}
+	</template>
+</BbTabs>
+```
+
+- `BbBreadcrumbs` — `item:prepend` / `item:append` around every item, or a
+  named slot per `item.key` to replace one item's content:
+
+```html
+<BbBreadcrumbs :items="trail">
+	<template #item:prepend="{ index }">
+		<BbIcon v-if="index === 0" icon="lucide:home" size="sm" />
+	</template>
+</BbBreadcrumbs>
+```
+
+- `BbRating` — the `icon` slot replaces each star glyph (slot props include
+  `checked`, `value`, `size`):
+
+```html
+<BbRating v-model="score">
+	<template #icon="{ checked }">
+		<BbIcon
+			icon="lucide:heart"
+			:class="checked ? 'text-red-500' : 'text-gray-300'"
+		/>
+	</template>
+</BbRating>
+```
+
+- `BbSwitch` — the `icon` slot replaces the toggle track visual (rarely
+  needed; the default track is correct for almost every case).
+- `BbDropdown` — `item:prepend` / `item:append`, or per-entry
+  `${key}:prepend` / `${key}:append` slots, when an entry's leading/trailing
+  region needs more than a named icon (e.g. an avatar).
+
+## Sizing and color
+
+- Icons paint in `currentColor`: they inherit the parent's text color. Color
+  the **container** (token-driven utility class), never the icon markup itself.
+- `BbIcon` `size` accepts the scale `xs`–`2xl` (12/16/24/28/36/40 px by
+  default; consumers can override via the plugin's `iconDefaultSizes` option),
+  a number (px), or a CSS length (`"1.5rem"`).
+- Icons placed through props/item fields are sized and aligned by the host
+  component to match its own size — don't fight that with custom CSS.
+
+## Accessibility
+
+- Decorative icon next to visible text (affixes, button prepend/append,
+  dropdown items): no label — the text already announces it; a label would
+  duplicate.
+- Meaningful standalone icon: give `BbIcon` a `label` — it adds `role="img"`,
+  `aria-label`, and a `title`.
+- Icon-only `BbButton` (the `icon` prop): supply the accessible name through the
+  label (default slot, or `text`) — it renders `sr-only` but is still announced.
+  `aria-label` is only an override; the one hard rule is that the button must
+  have a name from _one_ of the two.
+
+## Anti-patterns
+
+- Hand-placing `BbIcon` in a slot when the component has an icon prop or item
+  field for that exact spot.
+- Wrapping `BbIcon` in a raw `<button>` — use `BbButton` with `icon` + a label
+  (slot content or `text`; `aria-label` only to override).
+- Inventing or guessing icon names; assuming a set is installed without
+  checking `package.json`.
+- Runtime-composed icon names (template strings / concatenation) — invisible to
+  the build scanner, broken in production.
+- Setting `color`/`fill` on the icon element instead of the parent.
+- Falling back to random provider sets when a needed `local:` asset is missing —
+  ask for the SVG (or approval to substitute) instead.