bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/BbBadgeButton.md

@@ -0,0 +1,54 @@
+# BbBadgeButton
+
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Feedback**
+- Description: 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.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbBadgeButton.md](./source/BbBadgeButton.md)
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `activeClass` | `string \| undefined` |  |  | CSS class applied when the component renders as a link and the target of the link is the current route or the url matches partially. Ported for Inertia compatibility. |
+| `ariaCurrentValue` | `"page" \| "step" \| "location" \| "date" \| "time" \| "true" \| "false" \| undefined` |  |  | Value forwarded to the `aria-current` attribute when the component renders as a router link and the target route is an exact match. Use to communicate the current location to assistive technologies. |
+| `data` | `object \| undefined` |  |  | Request payload forwarded to Inertia when navigating via `href` in an Inertia-enabled app. Ignored when not using Inertia. |
+| `disabled` | `boolean \| undefined` |  |  | Disables user interaction. - When rendering as a native button, sets the `disabled` attribute. - When rendering as a link (anchor/Inertia), removes `href`, adds `aria-disabled="true"`, and prevents navigation while keeping focusable semanti… |
+| `download` | `string \| boolean \| undefined` |  |  | Marks an `href` link as a download. Renders a plain `<a download>` doing a native navigation — never an Inertia/router visit — so file downloads (including same-origin, `blob:` and `data:` URLs) work. Pass a string to set the suggested file… |
+| `exactActiveClass` | `string \| undefined` |  |  | CSS class applied when the component renders as a link and the target of the link and the url matches exactly. Ported for Inertia compatibility. |
+| `external` | `boolean \| undefined` |  |  | Forces an `href` link to render as a plain `<a>` (native navigation), bypassing Inertia/router interception — the same intent as Nuxt's `NuxtLink` `external`. Use for links outside the SPA. One of the native-anchor signals alongside `target… |
+| `headers` | `object \| undefined` |  |  | Additional HTTP headers forwarded to Inertia when navigating via `href` in an Inertia-enabled app. |
+| `href` | `string \| undefined` |  |  | Hyperlink reference used when rendering as an anchor (or as an Inertia link in Inertia-enabled apps). If provided and not disabled, the component renders as an anchor/Inertia link. |
+| `method` | `"get" \| "post" \| "put" \| "patch" \| "delete" \| undefined` |  |  | HTTP method used for Inertia navigation when `href` is provided in an Inertia-enabled app. Ignored otherwise. |
+| `onBefore` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia right before the request is sent. |
+| `onCancel` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request is cancelled. |
+| `onCancelToken` | `((cancelToken: unknown) => void) \| undefined` |  |  | Receives the Inertia cancel token source when a request is initiated. Can be used to cancel the request. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be installed. |
+| `onFinish` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia after the request has finished (regardless of success or error). |
+| `only` | `string[] \| undefined` |  |  | Limits the properties that are preserved in Inertia partial reloads. |
+| `onProgress` | `((progress: { percentage: number \| undefined; }) => void) \| undefined` |  |  | Progress callback invoked by Inertia with the upload/download percentage when available. |
+| `onStart` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request starts. |
+| `onSuccess` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request succeeds. |
+| `preserveScroll` | `boolean \| ((props: Record<string, unknown>) => boolean) \| undefined` |  |  | Controls whether Inertia should preserve the current scroll position after navigation. Can be a boolean or a predicate receiving the visit props. |
+| `preserveState` | `boolean \| ((props: Record<string, unknown>) => boolean) \| null \| undefined` |  |  | Controls whether Inertia should preserve the current state after navigation. Can be a boolean or a predicate receiving the visit props. |
+| `queryStringArrayFormat` | `"brackets" \| "indices" \| undefined` |  |  | Format to use when serializing array values into the query string for Inertia requests. |
+| `rel` | `string \| undefined` |  |  | Relationship between the current document and the linked resource. Useful for security when opening new tabs (e.g. `noopener noreferrer`). |
+| `replace` | `boolean \| undefined` |  |  | Uses history replacement instead of push navigation. - With Vue Router (`to`), calls `router.replace`. - With Inertia (`href`), performs a replace visit. |
+| `tag` | `ButtonTag \| undefined` |  |  | Element to render for the plain (non-link, non-router) button: - `'button'` (default) — real button semantics and keyboard behavior - `'div'` / `'span'` — a clickable box nested inside another button or link, where a nested `<button>` would… |
+| `target` | `string \| undefined` |  |  | Target browsing context for anchor/Inertia links (e.g. `_self`, `_blank`). Ignored when rendering as a native button. |
+| `to` | `string \| wt \| bt \| undefined` |  |  | Route location to navigate to. When provided (and not disabled), the component renders as a Vue Router link. |
+| `type` | `"button" \| "submit" \| "reset" \| undefined` |  |  | Native `type` attribute used when rendering as a button (e.g. `button`, `submit`, `reset`). |
+
+## Events
+
+- None.
+
+## Slots
+
+- `default` — scope: `object` — The action's label — what the badge displays as its body.
+
+## See Also
+
+- [BbBadge](./BbBadge.md) — Displays compact status counters or labels, the floating mode acts as notification dot.
+- [BbBaseButton](./BbBaseButton.md) — Unstyled button/link primitive: element resolution (button/anchor/router link) and the full navigation engine, with no visual chrome. Use for any clickable or navigable surface that is not a variant-first BbButton — cards, list rows, custom links.

package/dist/ai/BbBaseButton.md

@@ -0,0 +1,491 @@
+# BbBaseButton
+
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Inputs**
+- Description: 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.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbBaseButton.md](./source/BbBaseButton.md)
+
+## Usage & Guidelines
+
+### When to use
+
+`BbBaseButton` is a first-class component, not an internal detail. It does two
+things and nothing else: it **resolves the right element** (native `<button>`,
+`<a>`, or a router link) and it runs the **navigation engine** (`href`/`to`,
+Inertia visits, active classes) — with **no visual styling** of its own.
+
+Split the two button components by nature:
+
+- **`BbButton`** — the self-contained, **variant-first** button: a discrete,
+  recognizable button/link with `primary`/`outline`/`ghost`/… chrome, sizes,
+  loading and icons baked in. Use it when you want _a button that looks like a
+  button_.
+- **`BbBaseButton`** — **any other clickable or navigable surface**, especially
+  when it must navigate. Reach for it whenever the thing you're making is _not_ a
+  variant button:
+  - a rich clickable region — a card, a list row, a tile, a media thumbnail —
+    that should be one real navigable element;
+  - a bespoke link or button whose look comes entirely from your own CSS /
+    design system, not from a `BbButton` variant;
+  - any "random" clickable that needs correct navigation (`href`/`to`, Inertia,
+    active state) but no button styling.
+
+Rule of thumb: **if it navigates and it isn't a `BbButton` variant, it's a
+`BbBaseButton`** — don't wrap your own `@click`/`router.push` around a plain
+`<div>` or `<a>`. `BbButton` itself is built on this primitive, and the
+dropdown, breadcrumb and tab items reuse the very same navigation prop surface.
+
+### What it renders — element resolution
+
+The one feature to understand. `BbBaseButton` picks its element from the props,
+in this priority order:
+
+1. **Router link** — when `to` is set, or an internal (same-origin) `href` is set
+   in an Inertia app without a `target`. Renders `RouterLink` (Vue Router),
+   `NuxtLink` (Nuxt), or the Inertia `Link` — resolved for you from the active
+   framework.
+2. **Anchor `<a>`** — when `href` is set but the above doesn't apply: external or
+   cross-origin URLs, any `href` with a `target`, or a disabled `to` link (kept
+   as an anchor for correct link semantics).
+3. **Native `<button>`** — the default when there is no `href`/`to`. Polymorphic
+   via `tag` (below), but a real `<button>` unless you say otherwise.
+
+You never toggle this by hand — pass the navigation intent and the element
+follows. The example below renders a `<button>`, an `<a href>`, and an
+`<a href target="_blank">` from three prop shapes (all Tailwind-styled, since the
+primitive brings no look of its own):
+
+**Same component, three elements**
+
+```vue
+<template>
+	<div class="flex flex-wrap items-center gap-2 text-sm">
+		<!-- No href/to → a native <button>. -->
+		<BbBaseButton
+			class="rounded-[var(--bb-radius)] bg-[var(--bb-primary)] px-3 py-1.5 text-[var(--bb-primary-fg)]"
+			@click="pinged = true"
+		>
+			Native button
+		</BbBaseButton>
+		<!-- Same-origin href → an <a>. -->
+		<BbBaseButton
+			class="rounded-[var(--bb-radius)] px-3 py-1.5 text-[color:var(--bb-primary)] underline"
+			href="#docs"
+		>
+			Anchor link
+		</BbBaseButton>
+		<!-- href + target → a plain <a target="_blank"> with rel secured. -->
+		<BbBaseButton
+			class="rounded-[var(--bb-radius)] px-3 py-1.5 underline"
+			href="https://example.com"
+			target="_blank"
+		>
+			External ↗
+		</BbBaseButton>
+		<span class="text-xs text-[color:var(--bb-text-muted)]">{{
+			pinged ? 'button clicked' : ''
+		}}</span>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbBaseButton } from 'bitboss-ui';
+
+const pinged = ref(false);
+</script>
+```
+
+### It ships no chrome — you style it
+
+The only classes it applies are structural: `bb-base-button` (a focus-ring
+scaffold, `cursor`, inherited text color and transitions), `bb-base-button--block`
+and `bb-base-button--disabled`. There is **no padding, background, border, or
+variant appearance** — that is the whole point. Give it a class (your own, or
+Tailwind utilities) and it looks like whatever you draw. This is what makes it
+the right base for a clickable card or a bespoke nav item:
+
+**From bare to branded**
+
+```vue
+<div class="flex items-center gap-2 text-sm">
+	<!-- Untouched: just text with the reset + focus scaffold. -->
+	<BbBaseButton href="#a">Bare</BbBaseButton>
+	<!-- Styled entirely by utility classes — neutral hover chrome. -->
+	<BbBaseButton
+		href="#b"
+		class="rounded-[var(--bb-radius)] border border-[var(--bb-border)] px-3 py-1 font-medium hover:bg-[color:var(--bb-hover)]"
+	>
+		Branded pill
+	</BbBaseButton>
+</div>
+```
+
+A whole card as a single navigable element — the primitive's signature use:
+
+**A clickable card built on the primitive**
+
+```vue
+<template>
+	<div class="grid max-w-md gap-2 sm:grid-cols-2">
+		<!-- The whole card is ONE navigable element — a BbBaseButton rendered as an
+		     anchor, styled entirely by these utility classes. No wrapper <a>, no
+		     @click; navigation rides on `href` (a `to`/Inertia target works the same). -->
+		<BbBaseButton
+			v-for="project in projects"
+			:key="project.name"
+			class="project-card flex flex-col items-start gap-1.5 rounded-[var(--bb-radius)] border border-[var(--bb-border)] bg-[var(--bb-panel)] p-3 text-left hover:bg-[color:var(--bb-surface-hover)]"
+			:href="project.href"
+		>
+			<span class="flex w-full items-center justify-between gap-2">
+				<span
+					class="flex size-7 shrink-0 items-center justify-center rounded-[var(--bb-radius-sm)] bg-[color:var(--bb-muted)] text-[color:var(--bb-text-muted)]"
+				>
+					<BbIcon :icon="project.icon" size="sm" />
+				</span>
+				<BbBadge variant="secondary">{{ project.status }}</BbBadge>
+			</span>
+			<span class="text-sm font-medium">{{ project.name }}</span>
+			<span class="text-xs text-[color:var(--bb-text-muted)]">{{
+				project.meta
+			}}</span>
+		</BbBaseButton>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbBaseButton, BbBadge, BbIcon } from 'bitboss-ui';
+
+type Project = {
+	name: string;
+	meta: string;
+	status: string;
+	icon: 'lucide:receipt' | 'lucide:folder-kanban';
+	href: string;
+};
+
+const projects: Project[] = [
+	{
+		name: 'Northwind Billing',
+		meta: '12 open invoices · updated Jul 18',
+		status: 'Active',
+		icon: 'lucide:receipt',
+		href: '#northwind-billing',
+	},
+	{
+		name: 'Acme Studio',
+		meta: '3 members · updated Jul 12',
+		status: 'Paused',
+		icon: 'lucide:folder-kanban',
+		href: '#acme-studio',
+	},
+];
+</script>
+
+<style scoped>
+/* Visible focus uses the base ring scaffold (box-shadow / --bb-ring). */
+.project-card:focus-visible {
+	box-shadow: 0 0 0 var(--bb-ring-size) var(--bb-ring);
+}
+</style>
+```
+
+### Label
+
+Same as `BbButton`: **prefer the default slot** (`<BbBaseButton>Label</BbBaseButton>`);
+the `text` prop is a string-only fallback for `:items`-style loops that spread a
+config object. Slot content wins when both are present.
+
+### Navigation
+
+This is where the library's navigation surface actually lives — `BbButton` and
+the item-driven components just forward to it. Push any click whose result is a
+destination onto these props instead of an `@click` handler:
+
+- **`href`** — renders an `<a>`; in an Inertia app a same-origin `href` (no
+  `target`) upgrades to an Inertia visit. `target` forces a plain anchor, and
+  `target="_blank"` automatically merges `noopener noreferrer` into `rel`.
+- **`to`** — a Vue Router `RouteLocationRaw`, rendered as a router/Nuxt link.
+- **`replace`** — history replacement (`router.replace` under Vue Router, a
+  replace visit under Inertia).
+- **Inertia visit options** ride along with `href`: request shape (`method`,
+  `data`, `headers`, `only`, `query-string-array-format`), history & scroll
+  (`preserve-scroll`, `preserve-state`), and lifecycle hooks (`on-before`,
+  `on-start`, `on-progress`, `on-success`, `on-cancel`, `on-finish`,
+  `on-cancel-token`) — bound as props, not `@` listeners.
+
+For the full navigation catalog with per-option detail, see the
+[`BbButton`](./BbButton.md) guide — the surface is identical because it is this
+component's. `to` and Inertia links can't run without their framework, so they
+live in static snippets here:
+
+```vue
+<!-- Vue Router / Nuxt -->
+<BbBaseButton
+	:to="{ name: 'invoices.show', params: { id } }"
+>Open</BbBaseButton>
+
+<!-- Inertia: href becomes a visit; options ride along as props -->
+<BbBaseButton
+	href="/invoices"
+	method="post"
+	:data="{ customerId }"
+	preserve-scroll
+	:on-success="() => drawer.close()"
+>
+	Create invoice
+</BbBaseButton>
+```
+
+#### Active state
+
+When a link points at the current location the component adds a **class name** to
+the element — a hook you style; it applies no styling itself. `active-class` is
+added on a path-prefix match, `exact-active-class` on an exact match (defaults
+`router-link-active` / `router-link-exact-active`, or the plugin's
+`linkActiveClass` / `linkExactActiveClass`). Matching is native under Vue Router
+(`to`), and ported by the library for `href` links — against the Inertia page
+under Inertia, or `window.location` in a plain app. On every platform the
+exact-active link also gets `aria-current` (default `page`, tune
+with `aria-current-value`). The [`BbButton` active-state
+section](./BbButton.md) covers the matching rules in depth.
+
+Because the primitive attaches only the class name, an unstyled nav item is a
+two-line affair: name the hook with `exact-active-class` (or `active-class` for
+a section link that should stay lit on child pages) and write the CSS yourself.
+The classic home for this is a settings sidebar — every item is a bare
+`BbBaseButton`, and the one pointing at the current page lights up:
+
+**Settings sidebar with an active nav item**
+
+```vue
+<template>
+	<nav
+		aria-label="Settings"
+		class="grid w-full max-w-xs gap-0.5 rounded-[var(--bb-radius)] border border-[var(--bb-border)] bg-[var(--bb-panel)] p-1.5"
+	>
+		<!-- Each nav item is a bare BbBaseButton: element resolution and active
+		     matching come from the primitive, the entire look comes from these
+		     classes. `exact-active-class` names the hook; the scoped style below
+		     decides what "active" looks like. -->
+		<BbBaseButton
+			v-for="item in items"
+			:key="item.label"
+			block
+			class="settings-nav-item flex items-center gap-2 rounded-[var(--bb-radius-sm)] px-2 py-1.5 text-left text-sm text-[color:var(--bb-text-muted)] hover:bg-[color:var(--bb-hover)] hover:text-[color:var(--bb-text)]"
+			exact-active-class="settings-nav-active"
+			:href="item.href"
+		>
+			<BbIcon :icon="item.icon" size="sm" />
+			{{ item.label }}
+		</BbBaseButton>
+	</nav>
+</template>
+
+<script setup lang="ts">
+import { BbBaseButton, BbIcon } from 'bitboss-ui';
+
+type NavItem = {
+	label: string;
+	icon:
+		| 'lucide:settings'
+		| 'lucide:users'
+		| 'lucide:credit-card'
+		| 'lucide:key-round';
+	href: string;
+};
+
+// This demo runs router-free, so the matcher compares each href against
+// `window.location` — exactly what the library does in a plain app. "General"
+// points at the page you are viewing right now, so it is the exact-active
+// link; in your app the items would be real sibling paths
+// ('/settings', '/settings/members', …). The hash hrefs keep the preview from
+// navigating — fragment-only links are same-page by definition, so the
+// matcher deliberately never marks them active.
+const here =
+	typeof window !== 'undefined' ? window.location.pathname : '/settings';
+
+const items: NavItem[] = [
+	{ label: 'General', icon: 'lucide:settings', href: here },
+	{ label: 'Members', icon: 'lucide:users', href: '#members' },
+	{ label: 'Billing', icon: 'lucide:credit-card', href: '#billing' },
+	{ label: 'API keys', icon: 'lucide:key-round', href: '#api-keys' },
+];
+</script>
+
+<style scoped>
+/* Nothing highlights until you style the class the component attached. */
+.settings-nav-active {
+	background: var(--bb-muted);
+	color: var(--bb-text);
+	font-weight: 500;
+}
+
+.settings-nav-item:focus-visible {
+	box-shadow: 0 0 0 var(--bb-ring-size) var(--bb-ring);
+}
+</style>
+```
+
+#### Disabled links
+
+`disabled` adapts to the element. On a native button it sets the `disabled`
+attribute. On a link it keeps the element in place but strips navigation: the
+`href` is dropped and it renders `role="link"`, `aria-disabled="true"`,
+`tabindex="-1"` — focus-inert and unfollowable, without collapsing the layout.
+
+**Disabled adapts to button vs link**
+
+```vue
+<div class="flex items-center gap-2 text-sm">
+	<BbBaseButton
+		disabled
+		class="rounded-[var(--bb-radius)] bg-[var(--bb-primary)] px-3 py-1.5 text-[var(--bb-primary-fg)] opacity-50"
+	>
+		Disabled button
+	</BbBaseButton>
+	<BbBaseButton disabled href="#nope" class="px-3 py-1.5 underline opacity-50">
+		Disabled link
+	</BbBaseButton>
+</div>
+```
+
+### The plain element: tag, type and block
+
+When it renders as a native button you can retune the element:
+
+- **`tag`** — render the plain (non-link) case as `button` (default), `div`,
+  `span` or `label`, for contexts where a `<button>` is invalid (e.g. nested
+  inside another interactive element, or a clickable `<label>` wrapping a hidden
+  file input). A non-`button` tag **drops the native `type`/`disabled`
+  attributes** (invalid there) — disabled state is then conveyed only by the
+  `bb-base-button--disabled` class, and you lose native keyboard/focus semantics,
+  so keep the default `<button>` unless you truly can't.
+- **`type`** — the native button type (`button` default, `submit`, `reset`).
+  Because it defaults to `button`, a `BbBaseButton` in a form never submits by
+  accident; set `type="submit"` for the one that should.
+- **`block`** — full-width layout (`bb-base-button--block`), for stacked nav
+  items, mobile CTAs, or list rows.
+
+**Submit type and block width**
+
+```vue
+<template>
+	<form
+		class="grid max-w-xs gap-2 rounded-[var(--bb-radius)] border border-[var(--bb-border)] bg-[var(--bb-panel)] p-3"
+		@submit.prevent="sent = true"
+	>
+		<p class="text-sm font-medium">New workspace</p>
+		<p class="text-xs text-[color:var(--bb-text-muted)]">
+			{{
+				sent
+					? 'Submitted via the native form event.'
+					: 'Submits the form — the default type="button" never would.'
+			}}
+		</p>
+		<BbBaseButton
+			block
+			class="rounded-[var(--bb-radius)] bg-[var(--bb-primary)] px-3 py-1.5 text-sm text-[var(--bb-primary-fg)]"
+			type="submit"
+		>
+			Create workspace
+		</BbBaseButton>
+	</form>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbBaseButton } from 'bitboss-ui';
+
+const sent = ref(false);
+</script>
+```
+
+### Works well with
+
+- [`BbButton`](./BbButton.md) — the variant-first sibling built on this
+  primitive (variants, sizes, loading, toggle, icons). Use it when you want a
+  discrete button; use `BbBaseButton` for every other clickable surface.
+- [`BbDropdown`](./BbDropdown.md) / [`BbBreadcrumbs`](./BbBreadcrumbs.md) /
+  [`BbTabs`](./BbTabs.md) — their items expose this same navigation prop surface,
+  so links there behave exactly like a `BbBaseButton`.
+- Your design system — when a control must look nothing like `BbButton`, build it
+  on `BbBaseButton` to inherit correct element resolution, link semantics and
+  active state for free.
+
+### Gotchas & anti-patterns
+
+- Don't use it just to get a plain-looking button — that's `variant="ghost"` /
+  `variant="link"` on `BbButton`. Reach for the base only to escape button
+  chrome entirely.
+- `to` and Inertia links need their framework present; without a router a `to`
+  link can't resolve. Use `href` for router-free contexts.
+- `tag="div"`/`tag="span"` throws away native button semantics — only do it when a
+  `<button>` is genuinely invalid, and restore keyboard/focus behavior yourself.
+- Style the focus state: the base provides only a ring _scaffold_
+  (`box-shadow`/`outline` transitions). Add a visible `:focus-visible` style in
+  your class so keyboard users can see focus.
+
+### Accessibility
+
+- **Element choice carries the semantics** — a real `<button>` and a real `<a>`
+  come with the correct role, keyboard behavior and focus for free. Preserve them
+  by keeping `href`/`to` for navigation and the default tag for actions.
+- **Disabled links** render `role="link"`, `aria-disabled="true"`, no `href`, and
+  leave the tab order — communicated to assistive tech without vanishing.
+- **Exact-active** links expose `aria-current` (default `page`) on every
+  platform — Vue Router, Inertia, and plain apps.
+- **`target="_blank"`** is secured with `rel="noopener noreferrer"` automatically.
+- **Provide a visible focus style** and, if you use a non-`button` `tag`, restore
+  the keyboard interaction the native element would have given you.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `activeClass` | `string \| undefined` |  |  | CSS class applied when the component renders as a link and the target of the link is the current route or the url matches partially. Ported for Inertia compatibility. |
+| `ariaCurrentValue` | `"page" \| "step" \| "location" \| "date" \| "time" \| "true" \| "false" \| undefined` |  |  | Value forwarded to the `aria-current` attribute when the component renders as a router link and the target route is an exact match. Use to communicate the current location to assistive technologies. |
+| `block` | `boolean \| undefined` |  |  | Makes the component take the full available width (block-level layout). Adds the `bb-base-button--block` modifier class. |
+| `data` | `object \| undefined` |  |  | Request payload forwarded to Inertia when navigating via `href` in an Inertia-enabled app. Ignored when not using Inertia. |
+| `disabled` | `boolean \| undefined` |  |  | Disables user interaction. - When rendering as a native button, sets the `disabled` attribute. - When rendering as a link (anchor/Inertia), removes `href`, adds `aria-disabled="true"`, and prevents navigation while keeping focusable semanti… |
+| `download` | `string \| boolean \| undefined` |  |  | Marks an `href` link as a download. Renders a plain `<a download>` doing a native navigation — never an Inertia/router visit — so file downloads (including same-origin, `blob:` and `data:` URLs) work. Pass a string to set the suggested file… |
+| `exactActiveClass` | `string \| undefined` |  |  | CSS class applied when the component renders as a link and the target of the link and the url matches exactly. Ported for Inertia compatibility. |
+| `external` | `boolean \| undefined` |  |  | Forces an `href` link to render as a plain `<a>` (native navigation), bypassing Inertia/router interception — the same intent as Nuxt's `NuxtLink` `external`. Use for links outside the SPA. One of the native-anchor signals alongside `target… |
+| `headers` | `object \| undefined` |  |  | Additional HTTP headers forwarded to Inertia when navigating via `href` in an Inertia-enabled app. |
+| `href` | `string \| undefined` |  |  | Hyperlink reference used when rendering as an anchor (or as an Inertia link in Inertia-enabled apps). If provided and not disabled, the component renders as an anchor/Inertia link. |
+| `method` | `"get" \| "post" \| "put" \| "patch" \| "delete" \| undefined` |  |  | HTTP method used for Inertia navigation when `href` is provided in an Inertia-enabled app. Ignored otherwise. |
+| `onBefore` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia right before the request is sent. |
+| `onCancel` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request is cancelled. |
+| `onCancelToken` | `((cancelToken: unknown) => void) \| undefined` |  |  | Receives the Inertia cancel token source when a request is initiated. Can be used to cancel the request. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be installed. |
+| `onFinish` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia after the request has finished (regardless of success or error). |
+| `only` | `string[] \| undefined` |  |  | Limits the properties that are preserved in Inertia partial reloads. |
+| `onProgress` | `((progress: { percentage: number \| undefined; }) => void) \| undefined` |  |  | Progress callback invoked by Inertia with the upload/download percentage when available. |
+| `onStart` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request starts. |
+| `onSuccess` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request succeeds. |
+| `preserveScroll` | `boolean \| ((props: Record<string, unknown>) => boolean) \| undefined` |  |  | Controls whether Inertia should preserve the current scroll position after navigation. Can be a boolean or a predicate receiving the visit props. |
+| `preserveState` | `boolean \| ((props: Record<string, unknown>) => boolean) \| null \| undefined` |  |  | Controls whether Inertia should preserve the current state after navigation. Can be a boolean or a predicate receiving the visit props. |
+| `queryStringArrayFormat` | `"brackets" \| "indices" \| undefined` |  |  | Format to use when serializing array values into the query string for Inertia requests. |
+| `rel` | `string \| undefined` |  |  | Relationship between the current document and the linked resource. Useful for security when opening new tabs (e.g. `noopener noreferrer`). |
+| `replace` | `boolean \| undefined` |  |  | Uses history replacement instead of push navigation. - With Vue Router (`to`), calls `router.replace`. - With Inertia (`href`), performs a replace visit. |
+| `tag` | `ButtonTag \| undefined` |  |  | Element to render for the plain (non-link, non-router) button: - `'button'` (default) — real button semantics and keyboard behavior - `'div'` / `'span'` — a clickable box nested inside another button or link, where a nested `<button>` would… |
+| `target` | `string \| undefined` |  |  | Target browsing context for anchor/Inertia links (e.g. `_self`, `_blank`). Ignored when rendering as a native button. |
+| `text` | `string \| undefined` |  |  | Fallback text content rendered when no default slot is provided. |
+| `to` | `string \| wt \| bt \| undefined` |  |  | Route location to navigate to. When provided (and not disabled), the component renders as a Vue Router link. |
+| `type` | `"button" \| "submit" \| "reset" \| undefined` | `"button"` |  | Native `type` attribute used when rendering as a button (e.g. `button`, `submit`, `reset`). |
+
+## Events
+
+- None.
+
+## Slots
+
+- `default` — scope: `object` — Primary content rendered inside the button element. Falls back to the `text` prop when empty.
+
+## See Also
+
+- [BbButton](./BbButton.md) — Button with loading state, tooltip, and icon support.
+- [BbDropdownButton](./BbDropdownButton.md) — A button with primary action and all other actions collected in a dropdown.
+- [BbDropdown](./BbDropdown.md) — Displays contextual action menus and menu content.

package/dist/ai/BbBaseCheckbox.md

@@ -0,0 +1,49 @@
+# BbBaseCheckbox
+
+## Agent Contract
+
+- Safety level: **Reference Only - Internal**
+- Group: **Reference Only - Base Primitive**
+- Description: Internal low-level checkbox primitive.
+- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
+- Implementation source (only when the contract below is not enough): [source/BbBaseCheckbox.md](./source/BbBaseCheckbox.md)
+
+## v-model
+
+- `v-model` — type: `any`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `ariaDescribedby` | `string \| undefined` |  |  | ID of the element that describes this checkbox for assistive technologies. Forwarded to the input as `aria-describedby`. |
+| `autofocus` | `Booleanish \| undefined` |  |  | Automatically focuses the checkbox when the page/component loads. Use sparingly to avoid usability issues. |
+| `checked` | `boolean \| undefined` | `undefined` |  | Forces the checkbox checked state (controlled prop). When omitted, the checked state is derived from `modelValue === trueValue`. Deliberately `undefined` rather than `false`, so "unset" stays distinguishable from an explicit `:checked="fals… |
+| `disabled` | `boolean \| undefined` |  |  | Disables user interaction. Also applied when `readonly` is set, since native checkboxes do not support `readonly`. |
+| `falseValue` | `any` | `false` |  | Value submitted/emitted when the checkbox is unchecked. Accepts any serializable value. Serialized to a string for form submission. |
+| `hasErrors` | `boolean \| undefined` |  |  | Puts the component into an error state (adds error styling class `bb-base-checkbox--errors`). |
+| `hasWarning` | `boolean \| undefined` |  |  | Puts the component into a warning state (adds `bb-base-checkbox--warnings`). Errors take priority when both are set. |
+| `id` | `string \| undefined` |  |  | Identifier forwarded to the input. |
+| `indeterminate` | `boolean \| undefined` |  |  | Renders the checkbox in the indeterminate state (neither checked nor unchecked). Note: the native `indeterminate` state resets on user click; this component re-applies it to keep UI and prop aligned. |
+| `modelValue` | `any` |  |  | Bound value for `v-model`. When it equals `trueValue` the checkbox is considered checked, otherwise unchecked. |
+| `name` | `string \| undefined` |  |  | Name attribute of the input, used during form submission. |
+| `readonly` | `boolean \| undefined` |  |  | Puts the input in a read-only state. Since checkboxes do not support native `readonly`, the input is disabled while styled as read-only. |
+| `required` | `boolean \| undefined` |  |  | Marks the input as required for form validation. |
+| `submitWhenFalse` | `boolean \| undefined` |  |  | When unchecked, submits a hidden input with `falseValue` so that a value is still posted with the form. When checked, the visible input submits `trueValue` as usual. |
+| `trueValue` | `any` | `true` |  | Value submitted/emitted when the checkbox is checked. Accepts any serializable value. Serialized to a string for form submission. |
+
+## Events
+
+- `blur` — `(event: "blur", event: FocusEvent): void`
+- `change` — `(event: "change", event: Event): void`
+- `click` — `(event: "click", event: MouseEvent): void`
+- `focus` — `(event: "focus", event: FocusEvent): void`
+- `input` — `(event: "input", event: Event): void`
+- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
+- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
+- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
+- `update:modelValue` — `(event: "update:modelValue", value: any): void`
+
+## Slots
+
+- `icon` — scope: `BaseCheckboxIconSlotProps` — Replaces the default checkmark SVG rendered inside the checkbox box.