bitboss-ui 3.0.0-beta.4 → 3.0.0-beta.41

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
@@ -66,7 +79,7 @@ earlier:
 			<span>Validating contacts.csv…</span>
 		</div>
 		<div v-else-if="phase === 'uploading'" class="import-card__upload">
-			<BbProgress :model-value="progress" />
+			<BbProgress label="Upload progress" :model-value="progress" />
 			<span class="import-card__meta">Uploading rows… {{ progress }}%</span>
 		</div>
 		<span v-else-if="phase === 'done'" class="import-card__meta">
@@ -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>
@@ -667,14 +711,14 @@ onMounted(load);
 
 A spinner says "something is happening"; a skeleton says "this exact layout is
 coming". Prefer a skeleton when the incoming content's shape is known and
-stable — `BbTable` ships this built in: pass `loading` (plus a `skeleton` style
-like `'avatar-text'`) and it renders placeholder rows, no spinner overlay
-needed. Use `BbSpinner` when the shape is unknown (first-time search results,
+stable — `BbTable` ships this built in: pass `loading` (and tune a column's
+shape with its `skeleton` option, e.g. `{ key: 'user', skeleton: 'avatar-text' }`)
+and it renders placeholder rows, no spinner overlay needed. Use `BbSpinner` when the shape is unknown (first-time search results,
 mixed content) or the indicator is inline with text.
 
 ```vue
 <!-- Table loads: built-in skeleton rows, not a spinner overlay -->
-<BbTable :items="invoices" :loading="fetching" skeleton="text" … />
+<BbTable :items="invoices" :loading="fetching" … />
 ```
 
 ### Config, platform & performance
@@ -688,6 +732,37 @@ mixed content) or the indicator is inline with text.
   or paint storms, safe to keep on screen indefinitely. Don't "re-theme" it by
   animating SVG geometry attributes; that reintroduces per-frame layout work.
 
+### Restyling with passthrough
+
+`pt` reaches the one part with a class list — or, in the object form, a
+style and attributes. Part: `root` (the spinning glyph, in both branches). No
+states — nothing it paints is a state.
+
+With one part, `pt:root` is plain `class` with extra letters: write `class`
+/ `style` on the tag, as on any element. `pt:root` stays for uniformity —
+the global map, the object form and a wrapper that spreads props address
+every component the same way.
+
+A region wait with no measurable progress, restyled with plain `class`: the
+glyph paints in `currentColor`, so recolor it on `class` and leave the
+wrapper for the operator copy.
+
+**class — fetching invoices**
+
+```vue
+<div class="flex items-center gap-2 text-sm">
+	<BbSpinner class="text-(--bb-text-muted)" size="sm" />
+	Fetching latest invoices…
+</div>
+```
+
+The full grammar, the merge rules and the global map are in the
+[passthrough guide](./guides/passthrough.md).
+
+A `pt` value written in `<script>` (a constant, a preset, a wrapper's
+`pt` prop) is typed as `BbSpinnerProps['pt']`, never an imported `PtValue`: see
+[passthrough § Typing `pt` in `<script>`](./guides/passthrough.md#typing-pt-in-script).
+
 ### Works well with
 
 - `BbButton` — `loading` / async `@click` for action feedback (never a
@@ -717,15 +792,26 @@ 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
-`loading` for action feedback since it wires up ARIA for you.
+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. A spinner without
+`label` is decorative on purpose, so no lint rule asks for one (unlike an
+icon-only BbButton or a BbProgress).
 
 ## 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… |
-| `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… |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `root`. States: —. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbSpinnerProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+| `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 purely decorative. |
+| `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 parsers |
+
+## Passthrough parts and states
+
+`pt:<part>="…"` restyles a part; `pt:<part>:<state>="…"` applies only while the state is on. A component-wide state is on for every part at once; a _per node_ state resolves on each node of a broadcast part (one row, one option, one day). Grammar and merge rules: `guides/passthrough.md`. In `<script>`, type a `pt` value as `<Component>Props['pt']` (`<Component>Props<Row>['pt']` on a generic component); `PtValue` is not exported: `guides/passthrough.md` § Typing `pt` in `<script>`.
+
+| Part | What it is |
+| --- | --- |
+| `root` | The spinning glyph. With a `label`, the status wrapper around it is not a part. |
 
 ## Events
 
@@ -735,6 +821,18 @@ in `role="status"` with that text rendered `sr-only`. Prefer `BbButton`'s
 
 - None.
 
+## Component tree
+
+`BbSpinner` is not one component: rendering it mounts every component below, and each one is live inside it. **Read this before styling, theming or debugging `BbSpinner`, and before concluding a part, a token or a behaviour does not exist** — it may live on a component further down. How to read it:
+
+- **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbSpinner`. A pt part listed as landing there is set on `BbSpinner` (`pt:<part>`).
+- **_public_** nodes are components with their own contract. `BbSpinner` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbSpinner`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
+- **CSS custom properties** listed on a node are declared on THAT node's root and read by elements inside it. Set one on that node's root or on the element inside it that reads it — the pt part that lands there is how you reach it (`pt:box="[--border-color:…]"` on a text input) — never on `BbSpinner`'s root, where the node's own declaration masks it (design-tokens guide, _Overriding one from a consumer app_, rule 0).
+- Listed nodes are the ones `BbSpinner`'s API reaches or that declare a documented CSS variable; the rest fold into "also mounts". The complete tree, repeats and undocumented locals included, is the `tree` field of this component in `components.json`.
+
+- `BbSpinner` _(this component)_
+  - Also mounts `BbIcon`
+
 ## See Also
 
 - [BbProgress](./BbProgress.md) — Visualizes task or operation progress state.