bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/composables/useConfirm.md

@@ -0,0 +1,313 @@
+---
+title: useConfirm
+summary: Promise-based confirm dialogs — await the user's yes/no, with yes/no button configs, async onClick busy states, and portal content. Requires exactly one <BbConfirm /> host, mounted at the app root.
+type: composable
+---
+
+# useConfirm
+
+## Summary
+
+`useConfirm` opens a modal confirm dialog and returns a promise that resolves
+with the user's decision. Dialogs are queued — if one is open, the next waits.
+Per the design language, every `destructive` action must pass through a confirm.
+
+**Requires exactly one `<BbConfirm />` host, mounted at the app root** (`App.vue`
+under Vue, `app.vue` under Nuxt, the `createInertiaApp` render root under
+Inertia) — never one per page or per component. With no host, `await confirm(...)`
+never settles and the caller hangs silently. With two hosts, every dialog renders
+twice. See [Agent Contract § Global Host Rule](../guides/agent-contract.md).
+
+## Import
+
+```ts
+import { useConfirm } from 'bitboss-ui';
+
+const { confirm, close, dismissAll } = useConfirm();
+```
+
+**Ownership** — when called inside a component (any effect scope), the
+returned `confirm`'s dialogs are tied to that scope: if it is disposed while a
+dialog is open or queued (browser Back, route change, the component unmounts),
+the dialog is dismissed quietly — promise resolved `false`, no callback runs.
+Call `useConfirm()` outside a component scope (app setup, store, module level)
+for app-lifetime confirms.
+
+## API
+
+### `confirm(message)`
+
+```ts
+declare function confirm(message: BbConfirmMessage): Promise<boolean>;
+```
+
+Resolves with:
+
+- `true` / `false` for the Yes / No outcome (also `false` on `duration`
+  auto-dismiss, on implicit dismiss — backdrop, Escape, X — and on owner-scope
+  disposal).
+- The clicked button's `onClick` return value when `returning: true`.
+
+Rejects **only** when a button's `onClick` throws.
+
+`false` means _not confirmed_, not necessarily _declined_ — decline-only
+behavior belongs in `no.onClick`, not the `if (!ok)` branch.
+
+### `close()`
+
+```ts
+declare function close(): void;
+```
+
+Hides the current dialog without resolving anything. Its purpose is multi-step
+flows: with `autoClose: false` the dialog stays open after the promise resolves,
+and you call `close()` when your flow is done. Don't use it as a substitute for
+the buttons — a `confirm()` closed this way before any button ran leaves its
+promise pending.
+
+### `dismissAll()`
+
+```ts
+declare function dismissAll(): void;
+```
+
+Quietly dismisses the open dialog and any queued ones, regardless of owner:
+pending promises resolve `false`, no callback runs. An imperative escape hatch
+for app-level events — logout, a global error boundary, or router wiring in
+apps that want route-based dismissal.
+
+## `BbConfirmMessage` options
+
+At least one of `title`, `text`, `portal` should be set (dev warning otherwise).
+
+| Option        | Type                                            | Default     | Description                                                                                                                                                                                                                |
+| ------------- | ----------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`       | `string`                                        | —           | Header title. Omit to render no header.                                                                                                                                                                                    |
+| `text`        | `string`                                        | —           | Plain-text body. Takes priority over `portal`.                                                                                                                                                                             |
+| `yes`         | `false \| string \| ConfirmButtonConfig`        | `'OK'`      | Positive button: `false` hides it, a string relabels it, an object gives full control (see below).                                                                                                                         |
+| `no`          | `false \| string \| ConfirmButtonConfig`        | `'Annulla'` | Negative button: same three forms.                                                                                                                                                                                         |
+| `variant`     | `ConfirmVariantType`                            | `'default'` | Dialog tone, applied as a CSS modifier class. `'destructive'` also makes the Yes button destructive.                                                                                                                       |
+| `returning`   | `boolean`                                       | `false`     | Resolve with the clicked button's `onClick` return value instead of `true`/`false`.                                                                                                                                        |
+| `dismissAsNo` | `boolean`                                       | `true`      | Whether user-initiated implicit dismissals (backdrop, Escape, X) invoke `no.onClick`. When `false` they resolve `false` quietly. System-initiated dismissals (`duration`, owner unmount, `dismissAll()`) are always quiet. |
+| `autoClose`   | `boolean`                                       | `true`      | Close after the promise settles. Set `false` for multi-step flows ended by `close()`.                                                                                                                                      |
+| `duration`    | `number`                                        | —           | Auto-dismiss after N ms, resolving `false` quietly (no callback). Implies `autoClose: true`.                                                                                                                               |
+| `persistent`  | `boolean`                                       | `false`     | Block backdrop/Escape/X dismissal. Forced on while a callback runs.                                                                                                                                                        |
+| `hideClose`   | `boolean`                                       | `false`     | Hide the X button. Combine with `persistent` to force a Yes/No choice.                                                                                                                                                     |
+| `actions`     | `false \| ConfirmButtonConfig[]`                | —           | `false` hides the footer entirely (e.g. a portal owns the buttons). An array replaces Yes/No with custom buttons (see below).                                                                                              |
+| `size`        | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` | —           | Maximum dialog width preset.                                                                                                                                                                                               |
+| `fullscreen`  | `boolean \| 'mobile'`                           | —           | Fullscreen dialog; `'mobile'` restricts it to small screens.                                                                                                                                                               |
+| `focusTarget` | `string`                                        | —           | CSS selector to focus after opening (default: first tabbable element).                                                                                                                                                     |
+| `portal`      | `Component \| string`                           | —           | Custom body content. See **Portal modes**.                                                                                                                                                                                 |
+| `portalProps` | `Record<string, unknown>`                       | —           | Data for the portal content.                                                                                                                                                                                               |
+
+### `ConfirmButtonConfig`
+
+| Field                          | Type                                | Default                             | Description                                                                                                                            |
+| ------------------------------ | ----------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `text`                         | `string`                            | `'OK'` / `'Annulla'`                | Button label. Prefer a verb matching the action (_Delete_, _Publish_).                                                                 |
+| `variant`                      | `ButtonVariantType`                 | yes: `'primary'`\*, no: `'outline'` | Button variant. \*Yes inherits `'destructive'` when the confirm variant is.                                                            |
+| `size`                         | `BbButtonProps['size']`             | `'md'`                              | Button size.                                                                                                                           |
+| `prepend:icon` / `append:icon` | `IconType`                          | —                                   | Icon before/after the label (`lucide:*` preferred).                                                                                    |
+| `icon`                         | `IconType`                          | —                                   | Standalone icon button (no label).                                                                                                     |
+| `block`                        | `boolean`                           | —                                   | Stretch to full footer width.                                                                                                          |
+| `onClick`                      | `() => unknown \| Promise<unknown>` | —                                   | Async work done _before_ the dialog closes; the button spins while it runs. Its return value feeds the promise when `returning: true`. |
+
+## Usage examples
+
+### The destructive gate
+
+```vue
+<template>
+	<BbButton prepend:icon="lucide:trash-2" variant="destructive" @click="remove">
+		Delete
+	</BbButton>
+</template>
+
+<script setup lang="ts">
+import { BbButton, useConfirm } from 'bitboss-ui';
+
+const { confirm } = useConfirm();
+
+const remove = async () => {
+	const ok = await confirm({
+		title: 'Delete invoice?',
+		text: 'Invoice INV-2048 will be permanently removed. This cannot be undone.',
+		variant: 'destructive',
+		yes: { text: 'Delete', 'prepend:icon': 'lucide:trash-2' },
+		no: 'Cancel',
+	});
+	if (ok) await api.invoices.delete('INV-2048');
+};
+</script>
+```
+
+### Async work before the dialog closes
+
+Put the work in `onClick` instead of after the `await`: the button shows a
+spinner and the dialog stays open until it settles. Add `returning: true` to get
+the callback's return value.
+
+```ts
+const post = await confirm({
+	title: 'Publish post?',
+	text: 'The post becomes visible to all members.',
+	returning: true,
+	yes: { text: 'Publish', onClick: () => api.posts.publish(draft.id) },
+});
+// post is the api result, or false when the user declined
+```
+
+### Custom footer actions — more than yes/no
+
+Pass an `actions` array to replace the Yes/No footer with your own buttons.
+Clicking any of them resolves `true`; dismissal (backdrop, Escape, X,
+`duration`) resolves `false` without invoking any callback. Defaults per
+button: `variant: 'outline'`, `size: 'md'`.
+
+```ts
+const saved = await confirm({
+	title: 'Unsaved changes',
+	text: 'Save your edits before leaving?',
+	actions: [
+		{ text: 'Discard', variant: 'destructive', onClick: discardDraft },
+		{ text: 'Save', variant: 'primary', onClick: saveDraft },
+	],
+});
+// saved: true (either button ran) | false (dismissed)
+```
+
+With `returning: true` the promise resolves with the clicked button's
+`onClick` return value — the promise type is inferred as the union of all the
+handlers' return types (buttons without a handler contribute `true`):
+
+```ts
+const decision = await confirm({
+	title: 'Publish post?',
+	returning: true,
+	actions: [
+		{ text: 'Publish now', variant: 'primary', onClick: () => 'now' as const },
+		{ text: 'Schedule', onClick: () => 'later' as const },
+	],
+});
+// decision: 'now' | 'later' | false
+// (`as const` keeps the literals; without it each handler infers `string`)
+```
+
+An `actions` array owns the footer: `yes` / `no` are ignored (dev warning) and
+`dismissAsNo` callbacks never fire. Everything else carries over from yes/no:
+
+- While a handler runs, its button spins, the other actions are disabled, and
+  the dialog is locked (`persistent` + `hideClose` forced on).
+- A throwing handler **rejects** the promise and closes the dialog — use
+  `try/catch` when a handler can fail.
+- `duration` still auto-dismisses, resolving `false`.
+- Every `ConfirmButtonConfig` field works per action — `prepend:icon` /
+  `append:icon`, icon-only via `icon`, `block`, `size`, `variant`.
+
+### Acknowledgement — one button
+
+```ts
+await confirm({ title: 'Saved', text: 'Your changes are live.', no: false });
+```
+
+### Named portal — inline content with `portalProps`
+
+Declare `<BbConfirmPortal>` anywhere in the tree; its slot receives
+`{ yes, no, props }` where `props` is your `portalProps`.
+
+```vue
+<template>
+	<BbConfirmPortal name="remove-member">
+		<template #default="{ props }">
+			<div class="text-center">
+				<p class="font-semibold">{{ props.name }}</p>
+				<p class="text-sm text-gray-500">{{ props.role }}</p>
+			</div>
+		</template>
+	</BbConfirmPortal>
+</template>
+```
+
+```ts
+const ok = await confirm({
+	title: 'Remove member?',
+	variant: 'destructive',
+	portal: 'remove-member',
+	portalProps: { name: 'Sofia Esposito', role: 'Editor' },
+	yes: 'Remove',
+	no: 'Cancel',
+});
+```
+
+### Portal owning its own buttons
+
+Hide the footer with `actions: false` and resolve from the slot's `yes` / `no`
+helpers:
+
+```vue
+<BbConfirmPortal name="upload-success">
+	<template #default="{ yes }">
+		<div class="flex flex-col items-center gap-3">
+			<p class="font-semibold">Upload complete</p>
+			<BbButton variant="primary" @click="yes">Got it</BbButton>
+		</div>
+	</template>
+</BbConfirmPortal>
+```
+
+```ts
+await confirm({ portal: 'upload-success', actions: false });
+```
+
+### Component portal — reusable body
+
+`portalProps` are forwarded as component props via `v-bind`:
+
+```ts
+import DeleteConfirmContent from './DeleteConfirmContent.vue';
+
+const ok = await confirm({
+	title: 'Delete file?',
+	portal: DeleteConfirmContent,
+	portalProps: { fileName: 'report.pdf' },
+	yes: 'Delete',
+	no: 'Cancel',
+});
+```
+
+## Portal modes — comparison
+
+|                      | Named portal (`portal: 'name'`)                     | Component portal (`portal: MyComponent`)                           |
+| -------------------- | --------------------------------------------------- | ------------------------------------------------------------------ |
+| Content defined in   | `<template>` via `<BbConfirmPortal name="...">`     | A separate `.vue` file                                             |
+| Reactive local state | Always live — slot closure                          | Snapshot in `portalProps` (pass reactive objects for live updates) |
+| `portalProps` access | Via `props` slot argument                           | Via `defineProps` in the component                                 |
+| Best for             | One-off dialogs that reference local reactive state | Shared, reusable dialog bodies                                     |
+
+## Required app-root setup
+
+Mount `<BbConfirm />` **once, at the app root** — `App.vue` under Vue, `app.vue`
+under Nuxt, the `createInertiaApp` render root under Inertia. A page that calls
+`confirm()` mounts nothing; the self-contained examples in this guide each mount
+their own host only because an example has no app root to mount it in:
+
+```vue
+<template>
+	<RouterView />
+	<BbConfirm />
+</template>
+
+<script setup lang="ts">
+import { BbConfirm } from 'bitboss-ui';
+</script>
+```
+
+`<BbConfirmPortal>` components can be placed anywhere — they register their
+content by name and render nothing themselves.
+
+## Related
+
+- [BbConfirm](../BbConfirm.md) — the dialog render target and its guide.
+- [BbConfirmPortal](../BbConfirmPortal.md) — named portal registration.
+- [BbDialog](../BbDialog.md) — reach for it directly when you need a rich, multi-field modal instead of a decision.
+- [useToast](./useToast.md) — when the message is informational, not a decision.

package/dist/ai/composables/useCountdown.md

@@ -0,0 +1,86 @@
+---
+title: useCountdown
+summary: Reactive countdown timer with start, pause, reset, and formatted time output.
+type: composable
+---
+
+# useCountdown
+
+## Summary
+
+`useCountdown` creates a reactive countdown timer with a fixed 100 ms tick. It tracks elapsed and remaining time, exposes a progress percentage, and provides formatted time broken down by days, hours, minutes, and seconds.
+
+Use it for resend-code timers, session-expiry warnings, auto-save countdowns — anywhere a duration must be displayed while it runs.
+
+## Import
+
+```ts
+import { useCountdown } from 'bitboss-ui';
+```
+
+## API
+
+### Setup
+
+```ts
+type UseCountdownOptions = {
+	duration: number; // total duration in milliseconds (required, throws if falsy)
+	onStart?: () => void; // called each time the timer starts or restarts
+	onStop?: () => void; // called whenever the timer stops: pause, reset, and completion
+	onFinish?: () => void; // called on completion, after onStop
+};
+
+const countdown = useCountdown(options);
+```
+
+The timer does not start on creation — call `start()`. Resolution is the 100 ms
+tick, so keep durations in multiples of 100 ms.
+
+### Returned values
+
+| Name                 | Type                                             | Description                                                                                      |
+| -------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
+| `elapsed`            | `ComputedRef<number>`                            | Milliseconds elapsed since start.                                                                |
+| `remaining`          | `ComputedRef<number>`                            | Milliseconds remaining.                                                                          |
+| `remainingFormatted` | `ComputedRef<{ days, hours, minutes, seconds }>` | Remaining broken into time units.                                                                |
+| `progress`           | `ComputedRef<number>`                            | Percentage elapsed (0–100).                                                                      |
+| `running`            | `Ref<boolean>`                                   | `true` while the timer is active (paused does not change this).                                  |
+| `paused`             | `Ref<boolean>`                                   | `true` while the timer is paused.                                                                |
+| `start()`            | `() => void`                                     | Starts, or resumes after `pause()`. No-op while running or once finished — use `restart()` then. |
+| `restart()`          | `() => void`                                     | Resets to the full duration and starts immediately.                                              |
+| `pause()`            | `() => void`                                     | Pauses without resetting (fires `onStop`).                                                       |
+| `reset()`            | `() => void`                                     | Stops and resets elapsed to 0 (fires `onStop` unless paused).                                    |
+
+The timer cleans up its interval automatically via `onBeforeUnmount`.
+
+## Usage Example
+
+```vue
+<template>
+	<div>
+		<p>
+			{{ remainingFormatted.minutes }}m {{ remainingFormatted.seconds }}s
+			remaining
+		</p>
+		<BbProgress :model-value="progress" />
+		<BbButton @click="start" :disabled="running && !paused">Start</BbButton>
+		<BbButton @click="pause" :disabled="!running || paused">Pause</BbButton>
+		<BbButton @click="reset">Reset</BbButton>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbButton, BbProgress, useCountdown } from 'bitboss-ui';
+
+const { remainingFormatted, progress, running, paused, start, pause, reset } =
+	useCountdown({
+		duration: 5 * 60 * 1000, // reservation held for 5 minutes
+		onFinish: () => releaseReservation(),
+	});
+</script>
+```
+
+## Related Components
+
+- [BbProgress](../BbProgress.md) — visualize `progress` as a progress bar.
+- [BbSpinner](../BbSpinner.md) — indicate loading/pending state while timer runs.

package/dist/ai/composables/useId.md

@@ -0,0 +1,60 @@
+---
+title: useId
+summary: Generate a unique, hydration-safe DOM id (prefixed bb-ui-) for aria wiring in custom markup.
+type: composable
+---
+
+# useId
+
+## Summary
+
+`useId` wraps Vue's built-in `useId()` and prefixes the result with `bb-ui-`.
+It returns a ref holding the id plus a `refresh()` function that generates a
+new one. Because it delegates to Vue's `useId`, the value is stable across
+SSR and client hydration.
+
+This is mostly internal glue — every `Bb*` input already wires its own
+`id`/`for`/aria attributes. Reach for it only when you write custom markup
+that needs an id for accessibility wiring (`aria-labelledby`,
+`aria-describedby`, a hand-written `<label for>`). Do **not** use it for
+entity ids, `v-for` keys over data, or anything persisted.
+
+## Import
+
+```ts
+import { useId } from 'bitboss-ui';
+```
+
+## API
+
+```ts
+const { id, refresh } = useId();
+```
+
+| Name      | Type          | Description                                                     |
+| --------- | ------------- | --------------------------------------------------------------- |
+| `id`      | `Ref<string>` | The generated id, e.g. `bb-ui-v-0`. HTML5-safe characters only. |
+| `refresh` | `() => void`  | Replaces `id.value` with a freshly generated id.                |
+
+Call it during `setup` (a Vue `useId` requirement).
+
+## Usage Example
+
+```vue
+<template>
+	<section :aria-labelledby="id">
+		<h3 :id="id" class="text-sm font-medium">Storage used</h3>
+		<BbProgress :model-value="72" />
+	</section>
+</template>
+
+<script setup lang="ts">
+import { BbProgress, useId } from 'bitboss-ui';
+
+const { id } = useId();
+</script>
+```
+
+## Related
+
+- [BbProgress](../BbProgress.md) — like all library components, manages its own internal ids; you only need `useId` for your own markup.

package/dist/ai/composables/useMobile.md

@@ -0,0 +1,85 @@
+---
+title: useMobile
+summary: Reactive isMobile flag using the same viewport breakpoint the library's adaptive components use.
+type: composable
+---
+
+# useMobile
+
+## Summary
+
+`useMobile` returns the library-wide `isMobile` signal: `true` while the
+viewport width is **below** `config.mobileMaxWidth` (a Vite plugin option,
+default `768`). It is the exact same signal adaptive components
+(BbDialog, BbDropdown, BbPopover, BbSelect, BbOffCanvas, …) use to switch to
+their mobile/sheet presentation, so any JS-level layout decision you base on
+it stays in lockstep with theirs.
+
+Use it when custom behavior must agree with the library's adaptive switch —
+e.g. collapsing a filter sidebar into an off-canvas on mobile. Do **not**
+use it for plain responsive styling: that is CSS's job (Tailwind
+breakpoints). Note that Tailwind's `md:` breakpoint (`min-width: 768px`)
+happens to align with the default `mobileMaxWidth`.
+
+## Import
+
+```ts
+import { useMobile } from 'bitboss-ui';
+```
+
+## API
+
+```ts
+const { isMobile } = useMobile();
+```
+
+| Name       | Type                   | Description                                           |
+| ---------- | ---------------------- | ----------------------------------------------------- |
+| `isMobile` | `ComputedRef<boolean>` | `true` when viewport width `< config.mobileMaxWidth`. |
+
+The underlying width signal is a single module-level `useWindowSize()` from
+`@vueuse/core` — the whole library shares one `resize` listener, so calling
+`useMobile` in many components costs nothing.
+
+**SSR:** there is no `window` on the server; the width only becomes real
+after client mount. Treat `isMobile` as a client-side signal and avoid
+letting it change server-rendered markup, or you invite hydration
+mismatches.
+
+## Usage Example
+
+```vue
+<template>
+	<div class="flex gap-6">
+		<aside v-if="!isMobile" class="w-64">
+			<MemberFilters v-model="filters" />
+		</aside>
+		<template v-else>
+			<BbButton
+				prepend:icon="lucide:filter"
+				variant="outline"
+				@click="filtersOpen = true"
+			>
+				Filters
+			</BbButton>
+			<BbOffCanvas v-model="filtersOpen">
+				<MemberFilters v-model="filters" />
+			</BbOffCanvas>
+		</template>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbOffCanvas, useMobile } from 'bitboss-ui';
+
+const { isMobile } = useMobile();
+const filtersOpen = ref(false);
+const filters = ref({ status: 'active' });
+</script>
+```
+
+## Related
+
+- [BbOffCanvas](../BbOffCanvas.md) — the natural home for mobile-only panels.
+- [Installation and plugin setup](../guides/installation-and-plugin-setup.md) — where `mobileMaxWidth` is configured.