bitboss-ui 3.0.0-alpha.4 → 3.0.0-alpha.5

package/README.md

@@ -18,15 +18,16 @@ Published artifacts are **`dist/`** (ESM JavaScript, `.d.ts`, and **`index.css`*
 
 ### Composables
 
-| Composable                    | Role                                                      |
-| ----------------------------- | --------------------------------------------------------- |
-| `useBbConfig`                 | Global options for the kit (locale, defaults, etc.).      |
-| `useBroadcastChannelInstance` | Shared `BroadcastChannel` helper for cross-tab messaging. |
-| `useConfirm`                  | Programmatic confirm / modal flows.                       |
-| `useCountdown`                | Countdown timer state.                                    |
-| `useMobile`                   | Mobile / viewport-oriented behaviour.                     |
-| `useQueue`                    | Simple async task queue.                                  |
-| `useToast`                    | Toast notifications API.                                  |
+| Composable                    | Role                                                       |
+| ----------------------------- | ---------------------------------------------------------- |
+| `useBbConfig`                 | Global options for the kit (locale, defaults, etc.).       |
+| `useBroadcastChannelInstance` | Shared `BroadcastChannel` helper for cross-tab messaging.  |
+| `useConfirm`                  | Programmatic confirm / modal flows.                        |
+| `useCountdown`                | Countdown timer state.                                     |
+| `useMobile`                   | Mobile / viewport-oriented behaviour.                      |
+| `useQueue`                    | Simple async task queue.                                   |
+| `useSafeArea`                 | Claim a screen edge for a docked panel so toasts avoid it. |
+| `useToast`                    | Toast notifications API.                                   |
 
 ### Base\* components (primitives) _(reference-only - prefer `Bb*` equivalents for consumer code)_
 
@@ -206,7 +207,8 @@ markup) instead of reading files blind:
 npx bitboss-ui ai-init --mcp
 ```
 
-The agent harness launches the server itself (`npx bitboss-ui mcp`) on demand —
+The agent harness launches the server itself (`npx bitboss-ui@<installed version> mcp`,
+pinned so npx can never fall back to fetching a different version from the registry) on demand —
 you never run it by hand. `--mcp` merges the server entry into each harness's
 own config (never overwriting other servers you've registered), and each write
 is idempotent:

package/bin/bitboss-ui-mcp.mjs

@@ -17,7 +17,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import {
@@ -257,7 +257,7 @@ function* eachTokenDeclaration(css) {
 
 /**
  * `list_tokens({ filter })` — the `--bb-*` design tokens with their values,
- * read from the shipped stylesheet (the same 89 `check:tokens` counts).
+ * read from the shipped stylesheet (the same 90 `check:tokens` counts).
  *
  * WHY ONLY `--bb-*` — and why there is no opt-in for the unprefixed ones, even
  * though `search_components` has `includeReferenceOnly`. The two tiers are not
@@ -405,12 +405,28 @@ function getRecipe({ platform, name, maxChars } = {}) {
 			error: `Unknown platform '${platform}' — expected one of ${RECIPE_PLATFORMS.join(', ')}`,
 		};
 	}
-	const fileName = String(name ?? '').endsWith('.md')
-		? String(name)
-		: `${name}.md`;
-	const filePath = join(AI_ROOT, 'recipes', platform, fileName);
-	if (!existsSync(filePath)) {
-		return { found: false, error: `Recipe not found: ${platform}/${fileName}` };
+	// Contain reads to the platform's recipe dir — no traversal out of the
+	// knowledge base. `platform` is already allow-listed above, but `name` is
+	// free text, so it gets the same treatment as `get_guide`'s: leading
+	// separators stripped, `..` rejected outright, and the joined path checked
+	// to still sit under the recipe dir.
+	const rel = String(name ?? '').replace(/^\/+/, '');
+	if (!rel || rel.includes('..')) {
+		return {
+			found: false,
+			error: `Invalid recipe name '${name}'.`,
+			hint: 'Call list_recipes for the available names.',
+		};
+	}
+	const fileName = rel.endsWith('.md') ? rel : `${rel}.md`;
+	const recipesDir = join(AI_ROOT, 'recipes', platform);
+	const filePath = join(recipesDir, fileName);
+	if (!filePath.startsWith(`${recipesDir}${sep}`) || !existsSync(filePath)) {
+		return {
+			found: false,
+			error: `Recipe not found: ${platform}/${fileName}`,
+			hint: 'Call list_recipes for the available names.',
+		};
 	}
 	const { content, ...meta } = truncateMarkdown(
 		readFileSync(filePath, 'utf-8'),

package/bin/bitboss-ui.mjs

@@ -16,7 +16,9 @@
  *   locale    Generate a custom locale blueprint (.locale.ts)
  *   check     Validate Bb* markup in .vue/.md files against the installed
  *             components.json manifest (unknown props, removed props, bad
- *             v-models). Exits 1 on findings; supports --json output.
+ *             v-models, unknown `<template #slot>` names, `href`/`to`/
+ *             `method` on a component that doesn't declare them). Exits 1
+ *             on findings; supports --json output.
  *   mcp       Start a stdio MCP server exposing the dist/ai knowledge base
  *             (search_components, get_component, list_recipes, get_recipe,
  *             validate) to MCP-capable agent harnesses.
@@ -533,10 +535,11 @@ function summarizeFileCounts(files) {
 }
 
 /**
- * `npx bitboss-ui check [glob…] [--json]` — validate `Bb*` markup in `.vue`
- * and `.md` files against the installed components.json manifest.
+ * `npx bitboss-ui check [glob…] [--json]` — validate `Bb*` markup (props,
+ * v-models, and `<template #slot>` names) in `.vue` and `.md` files against
+ * the installed components.json manifest.
  */
-function checkCommand(globs, jsonMode) {
+function checkCommand(globs, jsonMode, allowEmpty = false) {
 	const projectRoot = process.cwd();
 
 	const manifestPath = join(PACKAGE_ROOT, 'dist', 'ai', 'components.json');
@@ -562,12 +565,26 @@ function checkCommand(globs, jsonMode) {
 	}
 
 	if (jsonMode) {
-		console.log(JSON.stringify({ findings }, null, 2));
+		console.log(JSON.stringify({ findings, files: files.length }, null, 2));
 		if (findings.length > 0) process.exit(1);
+		if (files.length === 0 && globs.length > 0 && !allowEmpty) process.exit(1);
 		return;
 	}
 
 	if (files.length === 0) {
+		// An EXPLICIT pattern that matched nothing is almost always a typo'd or
+		// stale CI path, and answering it with exit 0 means the step goes green
+		// having validated nothing — the check that was meant to catch bad
+		// markup is itself the thing that broke, silently (SWP-016). A bare
+		// sweep finding nothing is a different, legitimate case (a package with
+		// no .vue files yet), so it still passes.
+		if (globs.length > 0 && !allowEmpty) {
+			console.error(
+				`[bitboss-ui] check: no .vue/.md files matched ${globs.map((g) => `\`${g}\``).join(', ')} — nothing was validated. ` +
+					'Fix the path, or pass `--allow-empty` if an empty match is expected.'
+			);
+			process.exit(1);
+		}
 		console.log(
 			'[bitboss-ui] check: no .vue/.md files matched — nothing to do.'
 		);
@@ -576,7 +593,7 @@ function checkCommand(globs, jsonMode) {
 
 	if (findings.length === 0) {
 		console.log(
-			`[bitboss-ui] check OK — ${summarizeFileCounts(files)} file(s), zero unknown Bb* props/v-models.`
+			`[bitboss-ui] check OK — ${summarizeFileCounts(files)} file(s), zero unknown Bb* props/v-models/slots/nav-attrs.`
 		);
 		return;
 	}
@@ -621,14 +638,19 @@ Commands:
                       server for Claude Code (.mcp.json), Cursor (.cursor/mcp.json),
                       VS Code/Copilot (.vscode/mcp.json), and Windsurf (~/.codeium
                       global) — merges, never overwrites other servers.
-  check [glob…] [--json]
+  check [glob…] [--json] [--allow-empty]
                       Validate \`Bb*\` markup in .vue/.md files against the
                       installed components.json manifest (unknown/removed props,
-                      bad v-models). Defaults to every .vue/.md file under the
-                      current directory (node_modules, dist, .git, vendor,
+                      bad v-models, unknown \`<template #slot>\` names,
+                      \`href\`/\`to\`/\`method\` on a component that doesn't declare
+                      them). Defaults to every .vue/.md file under the current directory
+                      (node_modules, dist, .git, vendor,
                       storage, public, .output, .nuxt, bootstrap/cache
                       excluded — pass an explicit glob/path to widen the scan).
-                      Exits 1 on findings; \`--json\` prints \`{ findings: [...] }\`.
+                      Exits 1 on findings, and on an explicit glob that matched
+                      nothing (a typo'd CI path validates zero files silently) —
+                      pass \`--allow-empty\` when an empty match is expected.
+                      \`--json\` prints \`{ findings: [...], files }\`.
   mcp                 Start a stdio MCP server exposing the dist/ai knowledge
                       base (search_components, get_component, list_recipes,
                       get_recipe, validate) to MCP-capable agent harnesses.
@@ -674,10 +696,17 @@ switch (command) {
 		const { values, positionals } = parseCommandArgs(
 			command,
 			commandArgs,
-			{ json: { type: 'boolean' } },
+			{
+				json: { type: 'boolean' },
+				'allow-empty': { type: 'boolean' },
+			},
 			{ allowPositionals: true }
 		);
-		checkCommand(positionals, values.json ?? false);
+		checkCommand(
+			positionals,
+			values.json ?? false,
+			values['allow-empty'] ?? false
+		);
 		break;
 	}
 	case 'mcp': {

package/dist/ai/BbAlert.md

@@ -76,6 +76,13 @@ icon as a pair.
 The default variant is `outline`. `warning` and `destructive` are treated as
 high-priority for accessibility (see below).
 
+There is no `success` (or `positive`) variant, and it will not be added — the
+shared status vocabulary is closed to `danger`/`warn` by ruling, see
+[Design Tokens § Brand knobs](./guides/design-tokens.md#brand-knobs-what-a-theme-builder-sets)
+("state colors are project-owned"). Reach for `primary` for a positive
+confirmation, or register your own variant (below) if the project needs a
+distinct success tone.
+
 #### Registering project variants
 
 Variants are an open registry, not a closed enum. The vite/nuxt plugin's

package/dist/ai/BbAvatar.md

@@ -39,9 +39,14 @@ accessible name.
 
 ```vue
 <div class="flex items-center gap-3">
-	<BbAvatar size="xl" src="https://i.pravatar.cc/128?img=47" alt="Ada Lovelace" />
-	<BbAvatar size="xl" alt="Grace Hopper">GH</BbAvatar>
-	<BbAvatar size="xl" alt="Unknown user" />
+	<BbAvatar
+		size="56"
+		src="https://images.unsplash.com/photo-1494790108377-be9c29b29330?w=256&h=256&fit=crop&crop=faces&auto=format"
+		:timeout="4000"
+		alt="Ada Lovelace"
+	/>
+	<BbAvatar size="56" alt="Grace Hopper">GH</BbAvatar>
+	<BbAvatar size="56" alt="Unknown user" />
 </div>
 ```
 
@@ -56,9 +61,10 @@ sources don't need to be pre-cropped square.
 
 ```vue
 <BbAvatar
-	size="xl"
-	srcset="https://i.pravatar.cc/64?img=32 64w, https://i.pravatar.cc/128?img=32 128w"
-	sizes="36px"
+	size="56"
+	srcset="https://images.unsplash.com/photo-1580489944761-15a19d654956?w=128&h=128&fit=crop&crop=faces&auto=format 128w, https://images.unsplash.com/photo-1580489944761-15a19d654956?w=256&h=256&fit=crop&crop=faces&auto=format 256w"
+	sizes="56px"
+	:timeout="4000"
 	alt="Margaret Hamilton"
 />
 ```
@@ -70,6 +76,10 @@ library-wide by the `iconDefaultSizes` plugin option), a number (px), a CSS
 dimension string (`"3rem"`), or a percentage (`"100%"` fills a square parent).
 The built-in fallback icon scales with the avatar automatically.
 
+Composed demos below use the larger end of that range (and a few explicit px
+sizes) so faces stay readable in Storybook — `xs`/`sm` are for dense chrome,
+not hero examples.
+
 The fallback surface is **always painted with the primary design token** —
 `--bb-primary` behind, `--bb-primary-fg` for the initials/icon, the same
 pairing as a primary button — so initials stay legible in light and dark and
@@ -80,11 +90,11 @@ API: theming happens through the tokens, not a prop.
 
 ```vue
 <div class="flex items-end gap-3">
-	<BbAvatar size="sm" src="https://i.pravatar.cc/128?img=5" alt="Joan Clarke" />
-	<BbAvatar size="md" src="https://i.pravatar.cc/128?img=5" alt="Joan Clarke" />
-	<BbAvatar size="lg" src="https://i.pravatar.cc/128?img=5" alt="Joan Clarke" />
-	<BbAvatar size="xl" src="https://i.pravatar.cc/128?img=5" alt="Joan Clarke" />
-	<BbAvatar size="2xl" src="https://i.pravatar.cc/128?img=5" alt="Joan Clarke" />
+	<BbAvatar size="md" src="https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=256&h=256&fit=crop&crop=faces&auto=format" :timeout="4000" alt="Joan Clarke" />
+	<BbAvatar size="lg" src="https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=256&h=256&fit=crop&crop=faces&auto=format" :timeout="4000" alt="Joan Clarke" />
+	<BbAvatar size="xl" src="https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=256&h=256&fit=crop&crop=faces&auto=format" :timeout="4000" alt="Joan Clarke" />
+	<BbAvatar size="2xl" src="https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=256&h=256&fit=crop&crop=faces&auto=format" :timeout="4000" alt="Joan Clarke" />
+	<BbAvatar size="56" src="https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=256&h=256&fit=crop&crop=faces&auto=format" :timeout="4000" alt="Joan Clarke" />
 </div>
 ```
 
@@ -101,10 +111,15 @@ too, since the dot alone is not announced.
 ```vue
 <div class="flex items-center gap-3">
 	<BbIndicator bottom dot variant="success">
-		<BbAvatar size="md" src="https://i.pravatar.cc/128?img=12" alt="Ada Lovelace — online" />
+		<BbAvatar
+			size="40"
+			src="https://images.unsplash.com/photo-1494790108377-be9c29b29330?w=256&h=256&fit=crop&crop=faces&auto=format"
+			:timeout="4000"
+			alt="Ada Lovelace — online"
+		/>
 	</BbIndicator>
 	<BbIndicator bottom dot :style="{ '--bg': 'var(--bb-text-muted)' }">
-		<BbAvatar size="md" alt="Grace Hopper — away">GH</BbAvatar>
+		<BbAvatar size="40" alt="Grace Hopper — away">GH</BbAvatar>
 	</BbIndicator>
 </div>
 ```
@@ -142,15 +157,16 @@ separates them with a panel-colored ring (an explicit override of the
 				v-for="reviewer in visible"
 				:key="reviewer.name"
 				:alt="reviewer.name"
-				size="sm"
+				size="40"
 				:src="reviewer.src"
+				:timeout="demoAvatarTimeout"
 			>
 				{{ reviewer.initials }}
 			</BbAvatar>
 			<BbAvatar
 				v-if="!expanded && hiddenCount > 0"
 				:alt="`${hiddenCount} more reviewers`"
-				size="sm"
+				size="40"
 			>
 				+{{ hiddenCount }}
 			</BbAvatar>
@@ -161,6 +177,7 @@ separates them with a panel-colored ring (an explicit override of the
 <script setup lang="ts">
 import { computed, ref } from 'vue';
 import { BbAvatar, BbButton } from 'bitboss-ui';
+import { demoAvatarTimeout, demoFaces } from './demoAvatars';
 
 type Reviewer = {
 	name: string;
@@ -171,11 +188,11 @@ type Reviewer = {
 // The overflow indicator is just another avatar with the count in its slot —
 // same size, same ring, no special markup.
 const reviewers: Reviewer[] = [
-	{ name: 'Ada Lovelace', src: 'https://i.pravatar.cc/96?img=47' },
+	{ name: 'Ada Lovelace', src: demoFaces.ada },
 	{ name: 'Grace Hopper', initials: 'GH' },
-	{ name: 'Alan Turing', src: 'https://i.pravatar.cc/96?img=13' },
+	{ name: 'Alan Turing', src: demoFaces.alan },
 	{ name: 'Katherine Johnson', initials: 'KJ' },
-	{ name: 'Margaret Hamilton', src: 'https://i.pravatar.cc/96?img=32' },
+	{ name: 'Margaret Hamilton', src: demoFaces.margaret },
 ];
 const maxVisible = 3;
 
@@ -201,7 +218,7 @@ const hiddenCount = computed(() => reviewers.length - maxVisible);
 }
 
 .stack :deep(.bb-avatar + .bb-avatar) {
-	margin-left: -6px;
+	margin-left: -12px;
 }
 </style>
 ```
@@ -244,7 +261,12 @@ list — the row markup stays identical whether a member has a photo or not.
 					"
 					:variant="member.online ? 'success' : 'default'"
 				>
-					<BbAvatar :alt="member.name" size="sm" :src="member.src">
+					<BbAvatar
+						:alt="member.name"
+						size="40"
+						:src="member.src"
+						:timeout="demoAvatarTimeout"
+					>
 						{{ member.initials }}
 					</BbAvatar>
 				</BbIndicator>
@@ -262,6 +284,7 @@ list — the row markup stays identical whether a member has a photo or not.
 <script setup lang="ts">
 import { computed, ref } from 'vue';
 import { BbAvatar, BbIndicator, BbButton } from 'bitboss-ui';
+import { demoAvatarTimeout, demoFaces } from './demoAvatars';
 
 type Member = {
 	name: string;
@@ -278,7 +301,7 @@ const members: Member[] = [
 		name: 'Ada Lovelace',
 		role: 'Engineering',
 		online: true,
-		src: 'https://i.pravatar.cc/96?img=47',
+		src: demoFaces.ada,
 	},
 	{
 		name: 'Grace Hopper',
@@ -290,7 +313,7 @@ const members: Member[] = [
 		name: 'Alan Turing',
 		role: 'Research',
 		online: false,
-		src: 'https://i.pravatar.cc/96?img=13',
+		src: demoFaces.alan,
 	},
 	{
 		name: 'Katherine Johnson',
@@ -341,8 +364,13 @@ it for you.
 
 		<ul class="flex flex-col gap-2">
 			<li v-for="entry in feed" :key="entry.id" class="flex items-center gap-2">
-				<BbAvatar :alt="entry.actor" size="sm" :src="entry.src">
-					<BbIcon v-if="entry.bot" :icon="releaseBotMark" size="xs" />
+				<BbAvatar
+					:alt="entry.actor"
+					size="40"
+					:src="entry.src"
+					:timeout="demoAvatarTimeout"
+				>
+					<BbIcon v-if="entry.bot" :icon="releaseBotMark" size="sm" />
 					<template v-else>{{ entry.initials }}</template>
 				</BbAvatar>
 				<span class="flex min-w-0 flex-1 flex-col">
@@ -365,6 +393,7 @@ import { BbAvatar, BbIcon } from 'bitboss-ui';
 // brand art that lives in no icon collection. It paints in `currentColor`,
 // so on the avatar's fallback surface it inherits `--bb-primary-fg`.
 import releaseBotMark from '@/assets/icons/sparkles.svg?raw';
+import { demoAvatarTimeout, demoFaces } from './demoAvatars';
 
 type FeedEntry = {
 	id: number;
@@ -391,7 +420,7 @@ const feed: FeedEntry[] = [
 		actor: 'Ada Lovelace',
 		action: 'approved the release',
 		time: '14 minutes ago',
-		src: 'https://i.pravatar.cc/96?img=47',
+		src: demoFaces.ada,
 		initials: 'AL',
 	},
 	{

package/dist/ai/BbBadge.md

@@ -331,6 +331,23 @@ swap the inputs use); and **`icon`** (icon-only) becomes a removable glyph.
 Active filters are the classic product shape: a chip row, each badge owned by
 your state, cleared one-by-one or all at once.
 
+**Size rule — match the pair, don't memorise a constant.** Badge scale is not
+button scale, so the number that looks right depends on the button standing
+next to it. A rail picks **one matched pair** and uses it for every chip:
+
+| Badge size     | Height | Pairs with button               |
+| -------------- | ------ | ------------------------------- |
+| `md` (default) | ≈16px  | — (inline token, opens nothing) |
+| `lg`           | ≈20px  | `xs`                            |
+| `xl`           | ≈24px  | `sm`                            |
+| `2xl`          | ≈28px  | `md`                            |
+
+So a rail whose Filters trigger is a `sm` button wants `xl` chips; drop the
+trigger to `xs` and the chips go to `lg`. Copying `sm`/`md` from an inline
+example into a rail is what makes chips look toy-sized next to their own
+button. Reserve `sm` for dense in-table status pills, and omit `size`
+(default `md`) only for a plain inline token that opens nothing.
+
 **A removable filter bar**
 
 ```vue
@@ -351,7 +368,7 @@ your state, cleared one-by-one or all at once.
 				clearable
 				:clearable-label="`Remove ${filter.label}`"
 				:prepend:icon="filter.icon"
-				size="sm"
+				size="lg"
 				variant="secondary"
 				@click:clear="onClear(filter.id)"
 				>{{ filter.label }}</BbBadge
@@ -484,10 +501,10 @@ press the × to remove. The two actions are two tab stops, which is correct.
 
 ```vue
 <div class="flex flex-wrap items-center gap-2">
-	<BbBadge clearable prepend:icon="lucide:tag" variant="secondary">
+	<BbBadge clearable prepend:icon="lucide:tag" size="xl" variant="secondary">
 		<BbBadgeButton @click="() => {}">Label: frontend</BbBadgeButton>
 	</BbBadge>
-	<BbBadge clearable append:icon="lucide:chevron-down" variant="secondary">
+	<BbBadge clearable append:icon="lucide:chevron-down" size="xl" variant="secondary">
 		<BbBadgeButton @click="() => {}">Priority: high</BbBadgeButton>
 	</BbBadge>
 </div>
@@ -528,7 +545,7 @@ anchor an overlay directly — no wrapper element, no `defineExpose`:
 			clearable
 			clearable-label="Remove status filter"
 			prepend:icon="lucide:circle-dot"
-			size="sm"
+			size="lg"
 			variant="secondary"
 			@click:clear="status = 'Open'"
 		>

package/dist/ai/BbBaseButton.md

@@ -207,7 +207,8 @@ 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`.
+  any target other than `_self` (`_blank`, named windows, …) 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).
@@ -418,9 +419,13 @@ const sent = ref(false);
 
 ### 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.
+- Don't use it just to get a plain-looking **standalone** button among other
+  buttons — that's `variant="ghost"` / `variant="link"` on `BbButton`. But **do**
+  use it for an **inline** link — a record-identity cell, an in-text link, a
+  property-grid value: `variant="link"` keeps the button box (height + padding)
+  and breaks the line, whereas `BbBaseButton` + your own link class (e.g.
+  `.plain-link`) flows inline. Reach for the base to escape button chrome
+  entirely — including whenever the link must sit inline in text.
 - `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
@@ -438,7 +443,8 @@ const sent = ref(false);
   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.
+- **Any `target` other than `_self`** (`_blank`, named windows, …) 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.
 

package/dist/ai/BbBaseColorInput.md

@@ -16,6 +16,7 @@
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
+| `adaptive` | `boolean \| undefined` | `undefined` |  | When `true`, the palette opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover. Forwarded to `BbColorPalette`, which resolves the fallback. When unset, falls back to the global `config.adaptive`. |
 | `alpha` | `boolean \| undefined` | `false` |  | Enable the alpha channel. When true the picker shows an opacity slider and emits / accepts `#RRGGBBAA` hex8 values. |
 | `append:icon` | `string \| undefined` |  |  | Name of the icon to render at the right hand side of the input. |
 | `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of element(s) describing this input for assistive tech (space-separated). Typically includes the container hint id if used within a BaseInputContainer. |

package/dist/ai/BbBaseDatePicker.md

@@ -18,7 +18,7 @@
 | --- | --- | --- | --- | --- |
 | `disabled` | `boolean \| undefined` |  |  | Disables the component. |
 | `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` | `1` |  | Defines the first day of the week with `0` meaning Sunday and `6` meaning Saturday. |
-| `floating` | `boolean \| undefined` |  |  | If true the date will have a format YYYY-MM-DD instead of the default ISO string. |
+| `floating` | `boolean \| undefined` |  |  | If true the value is a plain calendar string (`YYYY-MM-DD`, or the shape `type` dictates) instead of the default ISO instant. |
 | `id` | `string \| undefined` |  |  | The identifier of the component. |
 | `max` | `string \| undefined` |  |  | Maximum selectable date. |
 | `min` | `string \| undefined` |  |  | Minimum selectable date. |
@@ -26,7 +26,8 @@
 | `multiple` | `boolean \| undefined` |  |  | Allows the selection of multiple items. |
 | `range` | `boolean \| undefined` |  |  | Selects a range of dates between two dates. It selects all of the days between start and end. |
 | `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
-| `selectable` | `((date: string) => boolean) \| undefined` |  |  | Function that accepts a date string and returns a boolean. Returning `false` means the date cannot be selected. |
+| `selectable` | `((date: string) => boolean) \| undefined` |  |  | Function that accepts a date string and returns a boolean. Returning `false` means the date cannot be selected. The string is shaped by `type`: `YYYY-MM` under `month`, `YYYY` under `year`. |
+| `type` | `DatePickerType \| undefined` | `"date"` |  | What the grid selects: a day (`date`/`datetime`), a month, or a year. The coarse types make the month/year panel terminal instead of a navigation step, and emit `YYYY-MM` / `YYYY`. |
 | `utc` | `boolean \| undefined` |  |  | Emits values as UTC ISO strings (`...Z`) instead of ISO strings carrying the local offset (`...+01:00`). Emission-only: incoming values are parsed identically either way, so the prop can be added or removed without touching stored values. I… |
 
 ## Events

package/dist/ai/BbBaseDatePickerInput.md

@@ -18,14 +18,13 @@
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `adaptive` | `boolean \| undefined` | `undefined` |  | On mobile the calendar opens inside a bottom off-canvas sheet instead of a floating popover, mirroring the adaptive behaviour of `BbPopover`/`BbSelectPopover`. When unset, falls back to the global `config.adaptive`. |
-| `ampm` | `boolean \| undefined` |  |  | 12-hour display with an AM/PM segment (requires `datetime`). Purely a field-composition concern: `modelValue` and the `time` model stay 24-hour regardless. Type `A`/`P` (or ArrowUp/Down) to set the meridiem. |
+| `ampm` | `boolean \| undefined` |  |  | 12-hour display with an AM/PM segment (requires `type="datetime"`). Purely a field-composition concern: `modelValue` and the `time` model stay 24-hour regardless. Type `A`/`P` (or ArrowUp/Down) to set the meridiem. |
 | `append:icon` | `string \| undefined` |  |  | Name of the icon to render at the right hand side of the input. |
 | `ariaDescribedby` | `string \| undefined` |  |  | Additional description id(s) announced by assistive technologies. Usually provided by an outer input container to link hint/error text. |
 | `autocomplete` | `string \| undefined` | `"off"` |  | Browser autocomplete hint for the input. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Focus the first text field automatically when the component mounts. |
 | `clearable` | `boolean \| undefined` |  |  | Displays a clear button whenever a value is present and the control is interactive. |
 | `compact` | `boolean \| undefined` |  |  | Applies the compact density styles to the control. |
-| `datetime` | `boolean \| undefined` |  |  | Adds time selection beside date selection: `HH:mm` segments in the text field (24-hour) and time columns under the calendar. A picked or typed date with a blank time commits at `00:00`. Non-floating values carry the time inside `modelValue`… |
 | `disableCalendar` | `boolean \| "mobile" \| "desktop" \| undefined` | `false` |  | Disables the calendar: hides the trigger button and prevents the popover from opening. Use `'desktop'` to disable it on desktop only (keyboard-first there, calendar-first on mobile — complementing `disableWriting: 'mobile'`) or `'mobile'` t… |
 | `disabled` | `boolean \| undefined` |  |  | Disables the input, calendar trigger, and popover. |
 | `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` | `false` |  | Controls whether manual typing is disabled inside the text fields. Use `'mobile'` to disable typing only on mobile, `'desktop'` to disable typing only on desktop. Applies to both single and range modes. |
@@ -35,8 +34,8 @@
 | `hasWarning` | `boolean \| undefined` |  |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
 | `id` | `string \| undefined` |  |  | Explicit id for the input element. Falls back to an auto-generated `bdpi-<uid>` value. |
 | `loading` | `boolean \| undefined` |  |  | Shows loading visuals on the input. |
-| `max` | `string \| undefined` |  |  | Maximum selectable date in `YYYY-MM-DD` format — or, with `datetime`, `YYYY-MM-DDTHH:mm` to tighten the boundary day to a minute. Values outside both patterns throw during setup to surface configuration mistakes. |
-| `min` | `string \| undefined` |  |  | Minimum selectable date in `YYYY-MM-DD` format — or, with `datetime`, `YYYY-MM-DDTHH:mm` to tighten the boundary day to a minute. Values outside both patterns throw during setup to surface configuration mistakes. |
+| `max` | `string \| undefined` |  |  | Maximum selectable date in `YYYY-MM-DD` format — or, with `type="datetime"`, `YYYY-MM-DDTHH:mm` to tighten the boundary day to a minute. Values outside both patterns throw during setup to surface configuration mistakes. |
+| `min` | `string \| undefined` |  |  | Minimum selectable date in `YYYY-MM-DD` format — or, with `type="datetime"`, `YYYY-MM-DDTHH:mm` to tighten the boundary day to a minute. Values outside both patterns throw during setup to surface configuration mistakes. |
 | `modelValue` | `string \| string[] \| null` |  | yes | v-model value. Use `null` for empty, a single string for single selection, or a two-element string array (`[start, end]`) when `range` is true. |
 | `name` | `string \| undefined` |  |  | Name attribute forwarded to the native inputs. In single mode fields are named `${name}-day`, `${name}-month`, `${name}-year`; in range mode they are prefixed with the segment (`${name}-start-day`, `${name}-end-day`, …). |
 | `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile (e.g. `title`, `size`, `persistent`). |
@@ -45,11 +44,12 @@
 | `range` | `boolean \| undefined` |  |  | Enables range selection. When active, v-model expects a two-element array `[start, end]`. Users can still type into the start and end segments unless `disableWriting` disables typing. |
 | `readonly` | `boolean \| undefined` |  |  | Makes the text fields read-only and prevents opening the calendar. |
 | `required` | `boolean \| undefined` |  |  | Marks the inputs as required to the browser. |
-| `seconds` | `boolean \| undefined` |  |  | Adds the seconds segment (requires `datetime`). Without it, an incoming value carrying seconds displays truncated and is left untouched until the user commits an edit, at which point seconds zero out. |
+| `seconds` | `boolean \| undefined` |  |  | Adds the seconds segment (requires `type="datetime"`). Without it, an incoming value carrying seconds displays truncated and is left untouched until the user commits an edit, at which point seconds zero out. |
 | `selectable` | `((date: string) => boolean) \| undefined` |  |  | Predicate invoked for each candidate date. Return `false` to disable selection for that value. |
-| `step` | `number \| undefined` |  |  | Minute granularity for the calendar's minute column and arrow stepping (requires `datetime`). Constrains what the component produces, never what it accepts: a typed off-grid value (e.g. `10:07` with `step: 15`) is emitted verbatim, and no c… |
+| `step` | `number \| undefined` |  |  | Minute granularity for the calendar's minute column and arrow stepping (requires `type="datetime"`). Constrains what the component produces, never what it accepts: a typed off-grid value (e.g. `10:07` with `step: 15`) is emitted verbatim, a… |
 | `time` | `string \| string[] \| null \| undefined` |  |  | Companion model for the time part (`v-model:time`), always 24-hour `HH:mm` / `HH:mm:ss` regardless of display. With `floating` it is the only carrier of the time; otherwise it mirrors the time inside `modelValue` (same digits) and writing i… |
 | `transitionDuration` | `number \| undefined` |  |  | Transition duration, in milliseconds, for the popover appearance. |
+| `type` | `DatePickerType \| undefined` | `"date"` |  | What the field edits, and therefore its segments and emitted shape. - `date` (default) — `DD/MM/YYYY`. - `datetime` — adds the time segments and the calendar's time rail. - `month` — `MM/YYYY`, emitting `YYYY-MM`. - `year` — `YYYY`, emittin… |
 | `utc` | `boolean \| undefined` |  |  | Emits values as UTC ISO strings (`...Z`) instead of ISO strings carrying the local offset (`...+01:00`). Emission-only: incoming values are parsed identically either way, so the prop can be added or removed without touching stored values. F… |
 
 ## Events

package/dist/ai/BbBaseInputContainer.md

@@ -36,7 +36,7 @@
 | `reverse` | `boolean \| undefined` | `false` |  | Swap the label and input columns. |
 | `showHint` | `boolean \| undefined` |  |  | Keep the hint permanently visible, regardless of focus. |
 | `tag` | `ContainerTag \| undefined` | `"span"` |  | Element used for the inner wrapper: `span` (default) to remain inline, `div` for a block wrapper, `fieldset` for grouped controls (pair it with `labelTag="legend"`), or `label` to make the whole wrapper activate the control. |
-| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages displayed beneath the input, in their own `aria-live` region. Accepts a string or array; values are rendered one per line, in `--bb-warn` amber. A non-empty list implies the warning state (mirroring how `errors` implies the… |
+| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages displayed beneath the input, in their own `aria-live` region. Accepts a string or array; values are rendered one per line, in `--bb-text-warn` amber (the text-contrast half of the warning pair — the chrome stays on `--bb-wa… |
 
 ## Events
 

package/dist/ai/BbBaseSlider.md

@@ -44,7 +44,7 @@
 - `pointerdown` — `(event: "pointerdown", event: PointerEvent): void`
 - `pointermove` — `(event: "pointermove", event: PointerEvent): void`
 - `pointerup` — `(event: "pointerup", event: PointerEvent): void`
-- `update:modelValue` — `(event: "update:modelValue", event: number \| number[]): void`
+- `update:modelValue` — `(event: "update:modelValue", value: number \| number[]): void`
 
 ## Slots