bitboss-ui 3.0.0-beta.21 → 3.0.0-beta.22

package/dist/ai/BbSpinner.md

@@ -21,7 +21,7 @@ spinner, or vice-versa — `BbProgress` has no indeterminate mode (`null` render
 an empty bar), so this component **is** the library's indeterminate state.
 
 Two props, no slots, no events: `size` (icon scale) and optional `label` (an
-sr-only status announcement). Show the spinner with `v-if` while loading, remove
+visually-hidden status announcement). Show the spinner with `v-if` while loading, remove
 it when done.
 
 **An indeterminate wait**
@@ -47,14 +47,27 @@ earlier:
 				<span class="import-card__title">Import contacts</span>
 				<span class="import-card__meta">contacts.csv · 1,284 rows</span>
 			</div>
-			<BbButton
-				:disabled="phase === 'validating' || phase === 'uploading'"
-				prepend:icon="lucide:upload"
-				variant="outline"
-				@click="onImport"
-			>
-				Import
-			</BbButton>
+			<div class="import-card__actions">
+				<BbButton
+					:disabled="phase !== 'idle' && phase !== 'done'"
+					prepend:icon="lucide:upload"
+					variant="outline"
+					@click="onImport"
+				>
+					Import
+				</BbButton>
+				<!-- Demo control: advances the job one step per click. In an app
+				     the parser and the upload drive these transitions; nothing
+				     here ticks on its own. -->
+				<BbButton
+					v-if="phase === 'validating' || phase === 'uploading'"
+					prepend:icon="lucide:step-forward"
+					variant="ghost"
+					@click="onAdvance"
+				>
+					{{ phase === 'validating' ? 'Validation done' : 'Next chunk' }}
+				</BbButton>
+			</div>
 		</div>
 
 		<div
@@ -89,20 +102,19 @@ const phase = ref<Phase>('idle');
 const progress = ref(0);
 
 const onImport = () => {
+	// Parsing + validating the file: duration unknown → spinner.
 	phase.value = 'validating';
 	progress.value = 0;
-	// Stand-in for parsing + validating the file (duration unknown → spinner).
-	setTimeout(() => {
+};
+
+const onAdvance = () => {
+	if (phase.value === 'validating') {
+		// Rows counted from here on → the bar takes over.
 		phase.value = 'uploading';
-		// Stand-in for a chunked upload (rows counted → progress bar).
-		const timer = setInterval(() => {
-			progress.value = Math.min(progress.value + 20, 100);
-			if (progress.value === 100) {
-				clearInterval(timer);
-				phase.value = 'done';
-			}
-		}, 90);
-	}, 350);
+		return;
+	}
+	progress.value = Math.min(progress.value + 25, 100);
+	if (progress.value === 100) phase.value = 'done';
 };
 </script>
 
@@ -125,6 +137,13 @@ const onImport = () => {
 	justify-content: space-between;
 }
 
+.import-card__actions {
+	align-items: center;
+	display: flex;
+	flex-shrink: 0;
+	gap: 6px;
+}
+
 .import-card__titles {
 	display: flex;
 	flex-direction: column;
@@ -185,13 +204,13 @@ internals.
 
 ```vue
 <div class="flex items-center gap-4">
-	<span class="inline-flex items-center gap-2 text-[color:var(--bb-text-muted)]">
+	<span class="inline-flex items-center gap-2 text-(--bb-text-muted)">
 		<BbSpinner size="sm" /> Muted
 	</span>
-	<span class="inline-flex items-center gap-2 text-[color:var(--bb-primary)]">
+	<span class="inline-flex items-center gap-2 text-(--bb-primary)">
 		<BbSpinner size="sm" /> Brand
 	</span>
-	<span class="inline-flex items-center gap-2 text-[color:var(--bb-danger)]">
+	<span class="inline-flex items-center gap-2 text-(--bb-danger)">
 		<BbSpinner size="sm" /> Retrying…
 	</span>
 </div>
@@ -225,15 +244,28 @@ panel body (and let the trigger button use its own `loading` prop):
 	<div class="results-panel">
 		<div class="results-panel__head">
 			<span class="results-panel__title">Invoices</span>
-			<BbButton
-				:loading="loading"
-				prepend:icon="lucide:refresh-cw"
-				size="sm"
-				variant="outline"
-				@click="onRefresh"
-			>
-				Refresh
-			</BbButton>
+			<div class="results-panel__actions">
+				<BbButton
+					:loading="loading"
+					prepend:icon="lucide:refresh-cw"
+					size="sm"
+					variant="outline"
+					@click="onRefresh"
+				>
+					Refresh
+				</BbButton>
+				<!-- Demo control: plays the response arriving. In an app the
+				     fetch's own completion does this; nothing here ticks on its own. -->
+				<BbButton
+					v-if="loading"
+					prepend:icon="lucide:check"
+					size="sm"
+					variant="ghost"
+					@click="onResponse"
+				>
+					Deliver results
+				</BbButton>
+			</div>
 		</div>
 
 		<div v-if="loading" class="results-panel__status" role="status">
@@ -276,14 +308,15 @@ const loading = ref(false);
 
 const onRefresh = () => {
 	loading.value = true;
-	setTimeout(() => {
-		invoices.value = [
-			{ id: 'INV-1045', customer: 'Umbrella', amount: '€5,120.00' },
-			{ id: 'INV-1044', customer: 'Hooli', amount: '€2,340.00' },
-			{ id: 'INV-1043', customer: 'Stark Industries', amount: '€8,900.00' },
-		];
-		loading.value = false;
-	}, 800);
+};
+
+const onResponse = () => {
+	invoices.value = [
+		{ id: 'INV-1045', customer: 'Umbrella', amount: '€5,120.00' },
+		{ id: 'INV-1044', customer: 'Hooli', amount: '€2,340.00' },
+		{ id: 'INV-1043', customer: 'Stark Industries', amount: '€8,900.00' },
+	];
+	loading.value = false;
 };
 </script>
 
@@ -306,6 +339,12 @@ const onRefresh = () => {
 	justify-content: space-between;
 }
 
+.results-panel__actions {
+	align-items: center;
+	display: flex;
+	gap: 6px;
+}
+
 .results-panel__title {
 	font-size: 14px;
 	font-weight: 500;
@@ -385,14 +424,21 @@ on the container makes the state audible to assistive tech, per the
 
 				<div class="pending-list__trail">
 					<span class="pending-list__role">{{ member.role }}</span>
-					<span
-						v-if="pendingId === member.email"
-						class="pending-list__status"
-						role="status"
-					>
-						<BbSpinner size="xs" />
-						Saving…
-					</span>
+					<template v-if="pendingId === member.email">
+						<span class="pending-list__status" role="status">
+							<BbSpinner size="xs" />
+							Saving…
+						</span>
+						<!-- Demo control: plays the save response. In an app the
+						     request's completion clears `pendingId`; nothing ticks. -->
+						<BbButton
+							aria-label="Mark as saved"
+							icon="lucide:check"
+							size="sm"
+							variant="ghost"
+							@click="onSaved"
+						/>
+					</template>
 					<BbButton
 						v-else
 						size="sm"
@@ -442,9 +488,10 @@ const pendingId = ref<string | null>(null);
 
 const onSave = (email: string) => {
 	pendingId.value = email;
-	setTimeout(() => {
-		pendingId.value = null;
-	}, 700);
+};
+
+const onSaved = () => {
+	pendingId.value = null;
 };
 </script>
 
@@ -535,14 +582,15 @@ const onSave = (email: string) => {
 				<span class="section-shell__title">Revenue overview</span>
 				<span class="section-shell__meta">Last 30 days · Northwind</span>
 			</div>
+			<!-- Demo control: stands in for the request settling / being re-run.
+			     In an app the fetch flips `loading`; nothing here ticks on its own. -->
 			<BbButton
-				:disabled="loading"
-				prepend:icon="lucide:refresh-cw"
+				:prepend:icon="loading ? 'lucide:check' : 'lucide:refresh-cw'"
 				size="sm"
 				variant="outline"
-				@click="onReload"
+				@click="loading ? deliver() : reload()"
 			>
-				Reload
+				{{ loading ? 'Deliver data' : 'Reload' }}
 			</BbButton>
 		</div>
 
@@ -560,34 +608,30 @@ const onSave = (email: string) => {
 </template>
 
 <script setup lang="ts">
-import { onMounted, ref } from 'vue';
+import { ref } from 'vue';
 import { BbButton, BbSpinner } from 'bitboss-ui';
 
 type Stat = { label: string; value: string };
 
 // First paint of an empty section: center a spinner with a line naming what is
-// coming. A bare spinner in a blank region tells users nothing.
+// coming. A bare spinner in a blank region tells users nothing. The example
+// mounts IN that state — no timer resolves it; the button plays the response.
 const stats = ref<Stat[]>([]);
 const loading = ref(true);
 
-const load = () => {
-	loading.value = true;
-	stats.value = [];
-	setTimeout(() => {
-		stats.value = [
-			{ label: 'Collected', value: '€48,210' },
-			{ label: 'Outstanding', value: '€12,940' },
-			{ label: 'Overdue', value: '€3,180' },
-		];
-		loading.value = false;
-	}, 800);
+const deliver = () => {
+	stats.value = [
+		{ label: 'Collected', value: '€48,210' },
+		{ label: 'Outstanding', value: '€12,940' },
+		{ label: 'Overdue', value: '€3,180' },
+	];
+	loading.value = false;
 };
 
-const onReload = () => {
-	load();
+const reload = () => {
+	stats.value = [];
+	loading.value = true;
 };
-
-onMounted(load);
 </script>
 
 <style scoped>
@@ -717,14 +761,14 @@ By default the spinner is decorative — no live region and no ARIA role. Pair i
 with adjacent visible text (`Loading results…`) and put `role="status"` /
 `aria-live="polite"` on the text container you control. When the spinner stands
 alone (icon-only pending affordance), set `label` so the component wraps itself
-in `role="status"` with that text rendered `sr-only`. Prefer `BbButton`'s
+in `role="status"` with that text rendered visually hidden (`bb-sr-only`). Prefer `BbButton`'s
 `loading` for action feedback since it wires up ARIA for you.
 
 ## Props
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `label` | `string \| undefined` |  |  | Accessible loading announcement. When set, the spinner is wrapped in a `role="status"` element containing this text rendered `sr-only`, so screen readers announce the loading state. When omitted the markup is unchanged and the spinner is pu… |
+| `label` | `string \| undefined` |  |  | Accessible loading announcement. When set, the spinner is wrapped in a `role="status"` element containing this text rendered `bb-sr-only`, so screen readers announce the loading state. When omitted the markup is unchanged and the spinner is… |
 | `size` | `number \| ({ size?: any; } & string) \| keyof Sizes \| undefined` | `"md"` |  | Defines the component size. Accepted values: - A key from the provided size map (`keyof T`), e.g. `'sm' \| 'md' \| 'lg'` - A custom CSS size string (e.g. `'20px'`, `'1.5rem'`, `'2em'`) - A number, typically interpreted as pixels by size par… |
 
 ## Events

package/dist/ai/BbSwitch.md

@@ -39,10 +39,10 @@ the switch has focus — pin it open with `persistent-hint`.
 
 ```vue
 <template>
-	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+	<div class="grid max-w-sm gap-3 rounded-(--bb-radius) border p-4">
 		<div class="flex flex-col gap-0.5">
 			<p class="text-sm font-medium">Account security</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Preferences take effect as soon as you flip them.
 			</p>
 		</div>
@@ -88,10 +88,10 @@ state maps to. Handy when the switch drives an enum-like setting.
 
 ```vue
 <template>
-	<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-4">
+	<div class="grid max-w-sm gap-2 rounded-(--bb-radius) border p-4">
 		<div class="flex flex-col gap-0.5">
 			<p class="text-sm font-medium">Profile visibility</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Stores an enum string instead of a boolean.
 			</p>
 		</div>
@@ -102,7 +102,7 @@ state maps to. Handy when the switch drives an enum-like setting.
 			name="visibility"
 			true-value="public"
 		/>
-		<p class="text-xs text-[color:var(--bb-text-muted)]">
+		<p class="text-xs text-(--bb-text-muted)">
 			Stored value: <code>{{ visibility }}</code>
 		</p>
 	</div>
@@ -133,10 +133,10 @@ the user cannot queue conflicting toggles.
 
 ```vue
 <template>
-	<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-4">
+	<div class="grid max-w-sm gap-2 rounded-(--bb-radius) border p-4">
 		<div class="flex flex-col gap-0.5">
 			<p class="text-sm font-medium">Workspace</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Northwind Billing — flips save immediately and revert on failure.
 			</p>
 		</div>
@@ -151,7 +151,7 @@ the user cannot queue conflicting toggles.
 		<p v-if="error" class="text-xs text-red-600" data-testid="error">
 			{{ error }}
 		</p>
-		<p class="text-xs text-[color:var(--bb-text-muted)]" data-testid="status">
+		<p class="text-xs text-(--bb-text-muted)" data-testid="status">
 			{{ saving ? 'Saving…' : maintenance ? 'Enabled' : 'Disabled' }}
 		</p>
 	</div>
@@ -233,10 +233,10 @@ its focus ring (style against `focusVisible`).
 
 ```vue
 <template>
-	<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-4">
+	<div class="grid max-w-sm gap-2 rounded-(--bb-radius) border p-4">
 		<div class="flex flex-col gap-0.5">
 			<p class="text-sm font-medium">Appearance</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				The icon slot replaces the whole track — style checked state yourself.
 			</p>
 		</div>
@@ -291,10 +291,10 @@ a stage pill next to the flag name:
 
 ```vue
 <template>
-	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+	<div class="grid max-w-sm gap-3 rounded-(--bb-radius) border p-4">
 		<div class="flex flex-col gap-0.5">
 			<p class="text-sm font-medium">Feature flags</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Workspace experiments for Northwind Billing.
 			</p>
 		</div>
@@ -365,16 +365,22 @@ const usageAnalytics = ref(true);
 
 ```vue
 <template>
-	<div class="grid max-w-md gap-2 rounded-[var(--bb-radius)] border p-3">
+	<div class="grid max-w-md gap-2 rounded-(--bb-radius) border p-3">
 		<div class="flex flex-col gap-0.5 pb-1">
 			<p class="text-sm font-medium">Playback</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Label-heavy rows with the control pinned to the trailing edge.
 			</p>
 		</div>
+		<!-- `reverse` puts the label first; the ratio pattern then reads in that
+		     VISUAL order (label 6 : control 2 → 75% / 25%). The ratio alone
+		     leaves the switch at the START of its track, a quarter-width in
+		     from the edge — `input-position="right"` is what pins it to the
+		     trailing edge. -->
 		<BbSwitch
 			v-model="autoplay"
 			direction="xxxxxx xx"
+			input-position="right"
 			label="Autoplay videos"
 			name="autoplay"
 			reverse
@@ -382,12 +388,13 @@ const usageAnalytics = ref(true);
 		<BbSwitch
 			v-model="captions"
 			direction="xxxxxx xx"
+			input-position="right"
 			label="Always show captions"
 			name="captions"
 			reverse
 		/>
 		<!-- A described row keeps the same trailing edge: `input-position`
-		     applies on the description path too, and the switch pins to the
+		     applies on the description path too, and the switch aligns with the
 		     label's FIRST line rather than the centre of the two-line block. -->
 		<BbSwitch
 			v-model="downloads"
@@ -422,10 +429,10 @@ What a panel must not do is both.
 
 ```vue
 <template>
-	<div class="grid max-w-md gap-3 rounded-[var(--bb-radius)] border p-4">
+	<div class="grid max-w-md gap-3 rounded-(--bb-radius) border p-4">
 		<div class="flex flex-col gap-0.5">
 			<p class="text-sm font-medium">Email notifications</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Sent to alex@northwind.io — changes apply immediately.
 			</p>
 		</div>
@@ -439,7 +446,7 @@ What a panel must not do is both.
 				:name="pref.key"
 			/>
 		</div>
-		<p class="text-xs text-[color:var(--bb-text-muted)]" data-testid="summary">
+		<p class="text-xs text-(--bb-text-muted)" data-testid="summary">
 			{{ enabledCount }} of {{ preferences.length }} notifications on
 		</p>
 	</div>

package/dist/ai/BbSwitchGroup.md

@@ -44,7 +44,7 @@ stored value with `item-text` / `item-value` — never pre-map into
 
 ```vue
 <template>
-	<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-3">
+	<div class="grid max-w-sm gap-2 rounded-(--bb-radius) border p-3">
 		<BbSwitchGroup
 			v-model="channels"
 			compact
@@ -55,7 +55,7 @@ stored value with `item-text` / `item-value` — never pre-map into
 			legend="Where should we reach you?"
 			name="workspace-notifications"
 		/>
-		<p class="text-xs text-[color:var(--bb-text-muted)]" data-testid="summary">
+		<p class="text-xs text-(--bb-text-muted)" data-testid="summary">
 			{{ channels.length }} channel{{ channels.length === 1 ? '' : 's' }} active
 		</p>
 	</div>
@@ -115,7 +115,7 @@ explains the limit.
 
 ```vue
 <template>
-	<div class="max-w-sm rounded-[var(--bb-radius)] border p-3">
+	<div class="max-w-sm rounded-(--bb-radius) border p-3">
 		<BbSwitchGroup
 			v-model="channels"
 			compact
@@ -163,7 +163,7 @@ prop; when a dead row adds nothing, filter the item out of `items`.
 
 ```vue
 <template>
-	<div class="max-w-sm rounded-[var(--bb-radius)] border p-3">
+	<div class="max-w-sm rounded-(--bb-radius) border p-3">
 		<BbSwitchGroup
 			v-model="enabled"
 			compact
@@ -213,7 +213,7 @@ explains why:
 
 ```vue
 <template>
-	<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-3">
+	<div class="grid max-w-sm gap-2 rounded-(--bb-radius) border p-3">
 		<BbSwitchGroup
 			compact
 			item-text="label"
@@ -227,15 +227,12 @@ explains why:
 		/>
 		<p
 			v-if="error"
-			class="text-xs text-[color:var(--bb-danger)]"
+			class="text-xs text-(--bb-danger)"
 			data-testid="flags-error"
 		>
 			{{ error }}
 		</p>
-		<p
-			class="text-xs text-[color:var(--bb-text-muted)]"
-			data-testid="flags-status"
-		>
+		<p class="text-xs text-(--bb-text-muted)" data-testid="flags-status">
 			{{ saving ? 'Saving…' : `${enabled.length} of ${flags.length} flags on` }}
 		</p>
 	</div>
@@ -310,9 +307,7 @@ involved. See the [fetch-items](../../ai/guides/fetch-items-playbook.md) and
 
 ```vue
 <template>
-	<div
-		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
-	>
+	<div class="flex max-w-sm flex-col gap-3 rounded-(--bb-radius) border p-3">
 		<BbRadioGroup
 			v-model="plan"
 			compact
@@ -338,7 +333,7 @@ involved. See the [fetch-items](../../ai/guides/fetch-items-playbook.md) and
 			name="alert-channels-by-plan"
 			persistent-hint
 		/>
-		<p class="channel-summary text-xs text-[color:var(--bb-text-muted)]">
+		<p class="channel-summary text-xs text-(--bb-text-muted)">
 			{{ enabled.length }} channel{{ enabled.length === 1 ? '' : 's' }} on
 		</p>
 	</div>