bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/BbProgress.md

@@ -1,96 +1,489 @@
 # BbProgress
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Feedback**
+- Description: Visualizes task or operation progress state.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbProgress.md](./source/BbProgress.md)
+
+## Usage & Guidelines
+
+### When to use
+
+`BbProgress` is for **determinate** progress — a task whose completion you can
+measure: an upload, a multi-step setup, a storage quota. Bind the current value
+with `:model-value` and the bar fills from `min` to `max`. If the wait has no
+measurable end, use [`BbSpinner`](./BbSpinner.md) instead — passing `null` here
+renders an _empty_ bar, not an animated indeterminate state.
+
+The component is purely presentational: it emits no events and never changes the
+value on its own. `v-model` compiles but has nothing to write back — prefer the
+one-way `:model-value` binding and keep the source of truth in your state.
+
+**Profile completeness**
+
+```vue
+<div class="max-w-sm flex flex-col gap-2">
+	<div class="flex justify-between text-sm">
+		<span>Profile completeness</span>
+		<span class="text-[color:var(--bb-text-muted)]">60%</span>
+	</div>
+	<BbProgress :model-value="60" />
+</div>
+```
+
+### Storage quota in real units
+
+`max` lets you feed raw domain units — gigabytes, bytes, steps — straight in,
+and the bar computes the fill; never pre-compute a percentage when you already
+have the real numbers. Pair the bar with a visible textual value so the number
+is legible, not just the geometry. Near a soft cap, retint via the `--fill`
+hook (a theme token — never a hardcoded hex).
+
+**Team plan storage**
 
 ```vue
 <template>
 	<div
-		class="bb-progress"
-		:class="{
-			'bb-progress--horizontal': true,
-		}"
+		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
 	>
-		<div class="bb-progress-bar" :style="{ width: width + '%' }"></div>
+		<div class="flex items-start justify-between gap-3">
+			<div class="flex flex-col gap-0.5">
+				<span class="text-sm font-medium">Storage</span>
+				<span class="text-xs text-[color:var(--bb-text-muted)]">
+					Northwind Billing · Team plan
+				</span>
+			</div>
+			<span class="text-xs tabular-nums text-[color:var(--bb-text-muted)]">
+				{{ usedGb }} / {{ maxGb }} GB
+			</span>
+		</div>
+
+		<BbProgress
+			aria-label="Storage used"
+			:aria-valuetext="`${usedGb} of ${maxGb} gigabytes`"
+			class="[--track:6px]"
+			:max="maxGb"
+			:model-value="usedGb"
+			:style="nearLimit ? { '--fill': 'var(--bb-danger)' } : undefined"
+		/>
+
+		<div class="flex items-center justify-between gap-3">
+			<span class="text-xs text-[color:var(--bb-text-muted)]">
+				{{ remainingGb }} GB free
+				<template v-if="nearLimit"> · nearly full</template>
+			</span>
+			<BbButton href="#billing" text="Upgrade plan" variant="outline" />
+		</div>
 	</div>
 </template>
 
 <script setup lang="ts">
-import { clamp } from '@/utilities/functions/clamp';
-import { getAsPercentageBetween } from '@/utilities/functions/percentage';
-import { computed } from 'vue';
-import type { BbProgressProps } from './types';
-
-/**
- * You can get percentage between 250 and 370 and have it compute it automatically.
- */
-const props = withDefaults(defineProps<BbProgressProps>(), {
-	modelValue: 0,
-	min: 0,
-	max: 100,
-});
+import { BbButton, BbProgress } from 'bitboss-ui';
 
-const width = computed(() =>
-	clamp(
-		getAsPercentageBetween(props.modelValue || props.min, props.min, props.max),
-		0,
-		100
-	)
-);
+// Domain units go straight into `max` / `model-value` — no pre-computed %.
+// Near the cap, retint via the sanctioned `--fill` hook (token, not a hex).
+const usedGb = 42.6;
+const maxGb = 50;
+const remainingGb = Number((maxGb - usedGb).toFixed(1));
+const nearLimit = usedGb / maxGb >= 0.8;
 </script>
+```
+
+`min` shifts the lower bound for ranges that don't start at zero (a sales floor,
+a level's XP band). Out-of-range values are clamped — below `min` renders empty,
+above `max` renders full — and a degenerate range (`max <= min`) safely renders
+an empty bar. Width changes animate over 250 ms on their own; don't add your own
+transition.
+
+**A range that does not start at zero**
+
+```vue
+<div class="max-w-sm flex flex-col gap-2">
+	<div class="flex justify-between text-sm">
+		<span>Q3 sales target</span>
+		<span class="text-[color:var(--bb-text-muted)]">€310k of the €250–370k band</span>
+	</div>
+	<BbProgress :min="250" :max="370" :model-value="310" />
+</div>
+```
+
+### Upload progress
+
+Drive the bar from live state — here each chunk advances the value, and the
+percentage label is derived from the same source of truth.
+
+**Chunked upload**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="flex items-center justify-between gap-3">
+			<span class="flex min-w-0 items-center gap-2 text-sm font-medium">
+				<BbIcon icon="lucide:file-up" size="sm" />
+				<span class="truncate">quarterly-report.pdf</span>
+			</span>
+			<span
+				class="shrink-0 text-xs tabular-nums text-[color:var(--bb-text-muted)]"
+			>
+				{{ uploadedMb }} / {{ totalMb }} MB
+			</span>
+		</div>
+
+		<BbProgress
+			aria-label="Uploading quarterly-report.pdf"
+			:aria-valuetext="`${percent} percent uploaded`"
+			:max="totalMb"
+			:model-value="uploadedMb"
+		/>
+
+		<div class="flex items-center justify-between gap-3">
+			<span class="text-xs tabular-nums text-[color:var(--bb-text-muted)]">
+				{{ percent }}% uploaded
+			</span>
+			<BbButton
+				append:icon="lucide:upload"
+				:disabled="done"
+				:text="done ? 'Uploaded' : 'Upload chunk'"
+				variant="outline"
+				@click="onUploadChunk"
+			/>
+		</div>
+	</div>
+</template>
 
-<style lang="postcss">
-@import './index.css';
-</style>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbButton, BbIcon, BbProgress } from 'bitboss-ui';
+
+// Real units drive the bar via `max` — no need to pre-compute a percentage for
+// the component. The label is derived from the same source of truth.
+const totalMb = 512;
+const chunkMb = 64;
+
+const uploadedMb = ref(0);
+const percent = computed(() => Math.round((uploadedMb.value / totalMb) * 100));
+const done = computed(() => uploadedMb.value >= totalMb);
+
+/** Advance one simulated chunk; clamps at the file size. */
+const onUploadChunk = () => {
+	uploadedMb.value = Math.min(totalMb, uploadedMb.value + chunkMb);
+};
+</script>
 ```
 
-## Types
+For real uploads, pair with `BbDropzone` (it captures and validates files but
+does **not** upload) and feed the bar from your request layer's progress
+events, then confirm with `useToast`:
+
+```vue
+<BbDropzone v-model="file" :accept="['.csv']" />
+<BbProgress v-if="uploading" :max="totalBytes" :model-value="sentBytes" />
+```
 
 ```ts
-export type BbProgressProps = {
-	/**
-	 * Used by v-model. It's a number contained between `min` and `max` that corresponds to the current value.
-	 *
-	 * @defaultValue `0`
-	 */
-	modelValue: number | null;
-	/**
-	 * Minimum value. Lower cap.
-	 *
-	 * @defaultValue `0`
-	 */
-	min?: number;
-	/**
-	 * Maximum value. Upper cap.
-	 *
-	 * @defaultValue `100`
-	 */
-	max?: number;
+const { toast } = useToast();
+await axios.post('/imports', form, {
+	onUploadProgress: (e) => (sentBytes.value = e.loaded),
+});
+toast({ title: 'Import complete', variant: 'success' });
+```
+
+### Handing off to an unmeasurable phase
+
+Uploads often finish before the work does: the server still parses rows,
+transcodes, indexes — with no measurable progress. Swap the bar for
+[`BbSpinner`](./BbSpinner.md) at that boundary instead of faking a bar that
+creeps toward 99%. The determinate phase gets `BbProgress`, the indeterminate
+one gets a spinner, and completion is derived from your own state — the bar
+emits nothing.
+
+**CSV import: upload, then processing**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="flex items-center justify-between gap-3">
+			<span class="flex min-w-0 items-center gap-2 text-sm font-medium">
+				<BbIcon icon="lucide:file-spreadsheet" size="sm" />
+				<span class="truncate">contacts.csv</span>
+			</span>
+			<span
+				class="shrink-0 text-xs tabular-nums text-[color:var(--bb-text-muted)]"
+			>
+				{{ statusLabel }}
+			</span>
+		</div>
+
+		<!-- Measurable phase: the bar, in real units via `max`. -->
+		<BbProgress
+			v-if="phase === 'idle' || phase === 'uploading'"
+			aria-label="Uploading contacts.csv"
+			:max="totalKb"
+			:model-value="sentKb"
+		/>
+		<!-- Unmeasurable phase: swap to a spinner — never fake a creeping bar. -->
+		<div
+			v-else-if="phase === 'processing'"
+			class="flex items-center gap-2 text-sm text-[color:var(--bb-text-muted)]"
+			role="status"
+		>
+			<BbSpinner size="sm" />
+			Processing 1,284 rows…
+		</div>
+		<div v-else class="flex items-center gap-2 text-sm">
+			<BbIcon icon="lucide:check" size="sm" />
+			1,284 contacts imported
+		</div>
+
+		<div class="flex justify-end">
+			<BbButton
+				:disabled="phase === 'uploading' || phase === 'processing'"
+				prepend:icon="lucide:upload"
+				:text="phase === 'done' ? 'Import again' : 'Import contacts'"
+				variant="outline"
+				@click="onStartImport"
+			/>
+		</div>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { computed, onUnmounted, ref } from 'vue';
+import { BbButton, BbIcon, BbProgress, BbSpinner } from 'bitboss-ui';
+
+type Phase = 'idle' | 'uploading' | 'processing' | 'done';
+
+// Simulated transfer: the upload is measurable (bytes sent), the server-side
+// row parsing that follows is not — that boundary is where the bar hands off
+// to BbSpinner.
+const totalKb = 640;
+const chunkKb = 80;
+
+const phase = ref<Phase>('idle');
+const sentKb = ref(0);
+
+let timer: ReturnType<typeof setInterval> | undefined;
+onUnmounted(() => {
+	if (timer !== undefined) clearInterval(timer);
+});
+
+const statusLabel = computed(() => {
+	if (phase.value === 'uploading') return `${sentKb.value} / ${totalKb} KB`;
+	if (phase.value === 'processing') return 'Upload complete';
+	if (phase.value === 'done') return 'Done';
+	return `${totalKb} KB`;
+});
+
+/** Run the upload → processing → done sequence with deterministic timers. */
+const onStartImport = () => {
+	phase.value = 'uploading';
+	sentKb.value = 0;
+	timer = setInterval(() => {
+		sentKb.value = Math.min(totalKb, sentKb.value + chunkKb);
+		if (sentKb.value < totalKb) return;
+		if (timer !== undefined) clearInterval(timer);
+		phase.value = 'processing';
+		setTimeout(() => {
+			phase.value = 'done';
+		}, 500);
+	}, 70);
 };
+</script>
 ```
 
-## Styles
+### Onboarding steps
+
+Multi-step flows read better with a completion bar than with a spinner: set
+`max` to the number of steps and pass the 1-based current step. The built-in
+width transition animates each advance for free.
 
-```css
-.bb-progress {
-	background-color: color-mix(in srgb, var(--bb-panel) 92%, var(--bb-text));
-	border-radius: var(--bb-radius);
+**Workspace setup**
 
-	&.bb-progress--vertical {
-		/* Add styles for vertical progress bar if needed */
-	}
+```vue
+<template>
+	<div
+		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="flex items-center justify-between gap-3">
+			<div class="flex flex-col gap-0.5">
+				<span class="text-sm font-medium">Workspace setup</span>
+				<span class="text-xs text-[color:var(--bb-text-muted)]">{{
+					steps[step]
+				}}</span>
+			</div>
+			<span class="text-xs tabular-nums text-[color:var(--bb-text-muted)]">
+				Step {{ step + 1 }} of {{ steps.length }}
+			</span>
+		</div>
+
+		<BbProgress
+			aria-label="Workspace setup progress"
+			:aria-valuetext="`Step ${step + 1} of ${steps.length}`"
+			:max="steps.length"
+			:model-value="step + 1"
+		/>
+
+		<ul class="flex flex-col gap-1.5">
+			<li
+				v-for="(label, index) in steps"
+				:key="label"
+				class="flex items-center gap-2 text-sm"
+				:class="index <= step ? '' : 'text-[color:var(--bb-text-muted)]'"
+			>
+				<BbIcon
+					:icon="index < step ? 'lucide:circle-check' : 'lucide:circle'"
+					size="sm"
+				/>
+				{{ label }}
+			</li>
+		</ul>
+
+		<div class="flex items-center justify-between gap-3">
+			<BbButton
+				:disabled="step === 0"
+				text="Back"
+				variant="ghost"
+				@click="onBack"
+			/>
+			<BbButton
+				append:icon="lucide:arrow-right"
+				:disabled="step === steps.length - 1"
+				text="Continue"
+				@click="onContinue"
+			/>
+		</div>
+	</div>
+</template>
 
-	&.bb-progress--horizontal {
-		height: var(--bb-progress-track);
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbIcon, BbProgress } from 'bitboss-ui';
 
-		.bb-progress-bar {
-			height: 100%;
-		}
-	}
+// `max` = number of steps, model = 1-based current step: the bar shows how far
+// through onboarding the user is, and each advance animates via the built-in
+// width transition.
+const steps = [
+	'Create workspace',
+	'Invite teammates',
+	'Connect billing',
+	'Create first project',
+];
+const step = ref(0);
 
-	.bb-progress-bar {
-		background-color: var(--bb-primary);
-		border-radius: var(--bb-radius);
-		transition: all 0.3s; /* or adjust the transition duration as needed */
-	}
-}
+const onBack = () => {
+	step.value -= 1;
+};
+
+const onContinue = () => {
+	step.value += 1;
+};
+</script>
 ```
+
+### Styling the track
+
+There are no color or size props. The component exposes two CSS hooks —
+`--track` (track height, default `4px`) and `--fill` (fill color, default
+`var(--bb-primary)`, painted over a subtle track tint) — so quota bars can
+shift color without touching internals. The storage example above uses both
+hooks; the snippet below is the minimal `--track` override. Anything beyond
+these two hooks means restyling component internals — keep such overrides in a
+token/theme layer, not scattered per-usage.
+
+**A thicker track via the --track hook**
+
+```vue
+<div class="max-w-sm">
+	<BbProgress class="[--track:8px]" :model-value="45" />
+</div>
+```
+
+### Works well with
+
+- `BbDropzone` — captures the files; you upload and drive the bar (see above).
+- [`BbSpinner`](./BbSpinner.md) — for the phases you _can't_ measure (e.g.
+  server-side processing after the upload hits 100%). Swap components, don't
+  fake a creeping bar — see the CSV import example above.
+- `useToast` — announce completion once the task finishes; the bar alone is a
+  silent visual.
+- `BbTable` — for table data loads use its built-in `loading` skeleton, not a
+  progress bar.
+
+### Gotchas & anti-patterns
+
+- **`modelValue: null` renders an empty bar.** There is no indeterminate
+  animation; for unknown waits use `BbSpinner`.
+- **Don't restate the built-in ARIA.** The bar already exposes
+  `role="progressbar"` with `aria-valuemin/max/now` — wrapping it in another
+  `role="progressbar"` double-announces (see Accessibility). Add a label, not
+  a role.
+- **No events.** Don't listen for `update:modelValue` or a "complete" event —
+  derive completion from your own state (`value >= max`).
+- Don't pre-compute percentages when you hold real units — pass `max` instead.
+- Don't animate the width yourself (CSS transitions or manual `setInterval`
+  easing) — the 250 ms transition is built in.
+- Don't rebuild the bar from `<div>`s to get a different height — override
+  `--track`.
+
+### Accessibility
+
+The bar carries its own ARIA: `role="progressbar"` with `aria-valuemin`,
+`aria-valuemax`, and `aria-valuenow` kept in sync with `min`/`max`/the model
+value (out-of-range values are clamped, matching the visual fill). A `null`
+value reports `aria-valuenow` = `min`, matching the empty bar it renders —
+the component never signals "indeterminate" to assistive tech, because it has
+no indeterminate mode (that's `BbSpinner`). Do **not** wrap the component in
+another `role="progressbar"`.
+
+What's still on you:
+
+- **An accessible name.** Pass `aria-label` (or `aria-labelledby`) — it falls
+  through to the progressbar element.
+- **A visible textual value** beside the bar (`72%`, `220 / 500 GB`) so the
+  number is legible, not just the geometry. Add `aria-valuetext` when raw
+  numbers read poorly (units, steps).
+
+**A labelled, unit-aware bar**
+
+```vue
+<div class="max-w-sm flex flex-col gap-2">
+	<div class="flex justify-between text-sm">
+		<span>Storage used</span>
+		<span class="text-[color:var(--bb-text-muted)]">220 / 500 GB</span>
+	</div>
+	<BbProgress
+		aria-label="Storage used"
+		aria-valuetext="220 of 500 gigabytes"
+		:max="500"
+		:model-value="220"
+	/>
+</div>
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `string \| undefined` |  |  | Accessible name for the progress bar, forwarded to `aria-label`. A `progressbar` with no name is announced only as a bare percentage, so give it one whenever the surrounding text doesn't already name it (e.g. `"Upload"`). Matches the `label… |
+| `max` | `number \| undefined` | `100` |  | Maximum value. Upper cap. |
+| `min` | `number \| undefined` | `0` |  | Minimum value. Lower cap. |
+| `modelValue` | `number \| null` | `0` | yes | The current progress value — a number between `min` and `max`. This is a one-way input prop (BbProgress is a display component and never emits `update:modelValue`); `null` means no value and renders an empty bar. |
+
+## Events
+
+- None.
+
+## Slots
+
+- None.
+
+## See Also
+
+- [BbSpinner](./BbSpinner.md) — Indicates ongoing loading or pending operations.