bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/BbToast.md

@@ -1,218 +1,691 @@
 # BbToast
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Feedback**
+- Description: Shows transient notification messages.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbToast.md](./source/BbToast.md)
+
+## Usage & Guidelines
+
+### When to use
+
+A toast is _transient, floating, and self-dismissing_ feedback: "Changes
+saved", "Upload complete", "Copied to clipboard". It appears in a screen
+corner, stacks with its siblings, and disappears on its own.
+
+Reach for `BbAlert` instead when the message belongs to the page and must stay
+put (a form error summary, a persistent banner). The rule of thumb: **`BbToast`
+for what just happened, `BbAlert` for the current state of the page.**
+
+Toasts are fired imperatively with the `useToast` composable — you don't place
+a `<BbToast>` per message. You mount the host once, then call `toast(...)` from
+anywhere. `toast`, `update`, and `dismiss` all operate on one shared
+module-level stack, so every `useToast()` call in the app talks to the same
+host. The full option table lives in the `useToast` composable doc; this guide
+focuses on behaviour and patterns.
+
+### Setup: mount exactly one host, at the app root
+
+`useToast().toast(...)` enqueues into a shared reactive stack, but nothing
+renders until a `<BbToast />` host is mounted. Put it **once, at the app root**;
+it renders nothing where you place it — regions are teleported to the top layer
+(see below).
+
+```vue
+<template>
+	<RouterView />
+	<BbToast />
+</template>
+
+<script setup lang="ts">
+import { BbToast } from 'bitboss-ui';
+</script>
+```
+
+On Nuxt the host goes in `app.vue`; on Inertia, in the `createInertiaApp`
+render root — one mount above the router, so every page shares it and no page
+mounts its own. **Every example on this page mounts its own `<BbToast />` only
+because a standalone example has no app root to mount it in; in a real app the
+host is already there and the page must not add a second one** (two hosts render
+every message twice, and `BbToast` warns about it in DEV).
+
+Toasts are a client-side surface: fire them from event handlers and
+resolved requests, never during SSR/setup — on the server there is nothing to
+render them into.
+
+The host takes a single prop, `position`, the default corner for toasts that
+don't specify their own (see Positioning).
+
+### Firing a toast
+
+Call `toast(...)` from an event handler. The string shorthand shows a plain
+title; the object form gives you `title`, `text`, a `variant`, an `icon`, and
+per-message options. Built-in variants: `default`, `success`, `info`,
+`warning`, `destructive`.
+
+**Saved confirmation and variant tones**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Alex Rivera</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				alex@northwind.co · Product
+			</p>
+		</div>
+
+		<div class="flex flex-wrap items-center gap-2">
+			<BbButton
+				prepend:icon="lucide:check"
+				variant="primary"
+				@click="saveProfile"
+			>
+				Save profile
+			</BbButton>
+			<BbButton
+				prepend:icon="lucide:info"
+				variant="outline"
+				@click="notify('info')"
+			>
+				Info
+			</BbButton>
+			<BbButton
+				prepend:icon="lucide:triangle-alert"
+				variant="outline"
+				@click="notify('warning')"
+			>
+				Warning
+			</BbButton>
+			<BbButton
+				prepend:icon="lucide:circle-x"
+				variant="outline"
+				@click="notify('destructive')"
+			>
+				Error
+			</BbButton>
+		</div>
+
+		<!--
+			Standalone example: it mounts its own host because it has no app root.
+			A real app mounts exactly one <BbToast /> at the app root, and pages
+			mount none. See ai/guides/agent-contract.md § Global Host Rule.
+		-->
+		<BbToast position="bottom-right" />
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbButton, BbToast, useToast } from 'bitboss-ui';
+
+const { toast } = useToast();
+
+/** Saved confirmation — the everyday toast: tone + matching icon. */
+const saveProfile = () =>
+	toast({
+		title: 'Profile updated',
+		text: 'Name and role are live for your team.',
+		variant: 'success',
+		icon: 'lucide:circle-check',
+		position: 'bottom-right',
+	});
+
+const copy = {
+	info: {
+		title: 'Update available',
+		text: 'BitBoss 2.4 is ready to install.',
+		icon: 'lucide:info' as const,
+	},
+	warning: {
+		title: 'Storage almost full',
+		text: 'You have used 92% of the Northwind quota.',
+		icon: 'lucide:triangle-alert' as const,
+	},
+	destructive: {
+		title: 'Payment failed',
+		text: 'Card ending 4242 was declined. Try another method.',
+		icon: 'lucide:circle-x' as const,
+	},
+} as const;
+
+const notify = (variant: keyof typeof copy) => {
+	const { title, text, icon } = copy[variant];
+	toast({ title, text, variant, icon, position: 'bottom-right' });
+};
+</script>
+```
+
+Three things worth internalising:
+
+- **Variants tint the icon and set announcement priority — nothing else.** A
+  variant toast without an `icon` looks identical to a default one, so pass a
+  matching icon (`lucide:circle-check` for success, `lucide:circle-x` for
+  destructive…) whenever the tone matters visually. No icon is ever implied.
+- `toast(...)` returns the message `id`. Keep it to `update(...)` or
+  `dismiss(...)` that toast later; `dismiss()` with no argument clears the
+  whole stack.
+- `duration` defaults to 4000 ms and must be `> 0` — `toast()` throws
+  otherwise. Use `persistent: true` for "never auto-dismiss", not `duration: 0`.
+- A toast with no `title`, no `text`, and no `portal` renders an empty card
+  (dev builds warn).
+
+#### Project variants
+
+The plugin's `toastVariants` option appends names to the typed union, and any
+plain string is accepted at the call site for one-offs. A custom variant only
+buys you the `bb-toast-message--<variant>` class hook — style it yourself
+(the built-ins just set `--icon-color`). Custom variants announce politely;
+only `warning`/`destructive` are assertive.
+
+### Loading, then resolve
+
+Pass `loading: true` to show a spinner and pin the toast open — **`loading`
+implies `persistent`**, so it ignores the auto-dismiss timer and swipe. When
+the work settles, `update(id, ...)` morphs it in place into a success or error;
+the update restarts the auto-dismiss countdown (remember `loading: false`, or
+the spinner and the pinning stay).
+
+**Background job: loading to done**
 
 ```vue
 <template>
-	<div class="bb-toast" :class="{ [`bb-toast--${placement}`]: true }">
-		<TransitionGroup name="toast">
-			<BbToastMessage
-				v-for="message in state.stack"
-				:key="message.id"
-				v-bind="message"
-				@click:close="dismiss"
-			/>
-		</TransitionGroup>
+	<div
+		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">invoice-INV-1042.pdf</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				248 KB · ready to upload
+			</p>
+		</div>
+
+		<BbButton prepend:icon="lucide:upload" variant="primary" @click="upload">
+			Upload invoice
+		</BbButton>
+
+		<!--
+			Standalone example: it mounts its own host because it has no app root.
+			A real app mounts exactly one <BbToast /> at the app root, and pages
+			mount none. See ai/guides/agent-contract.md § Global Host Rule.
+		-->
+		<BbToast position="bottom-right" />
 	</div>
 </template>
 
 <script setup lang="ts">
-import { state, useToast } from '../../composables/useToast';
+import { BbButton, BbToast, useToast } from 'bitboss-ui';
 
-const { dismiss } = useToast();
+const { toast, update } = useToast();
 
-import BbToastMessage from './BbToastMessage.vue';
-import type { BbToastProps } from './types';
+/** Background job: loading pins the toast, then update morphs it in place. */
+const upload = () => {
+	const id = toast({
+		title: 'Uploading invoice-INV-1042.pdf…',
+		loading: true,
+		position: 'bottom-right',
+	});
 
-withDefaults(defineProps<BbToastProps>(), {
-	placement: 'bottom',
-});
+	setTimeout(() => {
+		update(id, {
+			title: 'Upload complete',
+			text: 'invoice-INV-1042.pdf is in the workspace.',
+			variant: 'success',
+			icon: 'lucide:circle-check',
+			loading: false,
+		});
+	}, 900);
+};
 </script>
+```
+
+`update` on an id that has already left the stack is a safe no-op. For a
+message that must never auto-dismiss, pass `persistent: true`; add
+`hideClose: true` only when your code will `dismiss(id)` itself — otherwise the
+user has no way out.
+
+### Upsert by id: one toast per concern
+
+Passing your own `id` makes `toast(...)` an upsert: if that toast is still
+live it is patched in place (and its countdown restarts) instead of stacking a
+duplicate. Use a stable id for repeatable events — autosave ticks, connection
+status, "copied" — so hammering the action never floods the corner.
+
+**Autosave that never stacks duplicates**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Proposal — Acme Studio</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Draft · last edited just now · {{ saveCount }} saves this session
+			</p>
+		</div>
+
+		<BbButton prepend:icon="lucide:save" variant="outline" @click="save">
+			Save draft
+		</BbButton>
+
+		<!--
+			Standalone example: it mounts its own host because it has no app root.
+			A real app mounts exactly one <BbToast /> at the app root, and pages
+			mount none. See ai/guides/agent-contract.md § Global Host Rule.
+		-->
+		<BbToast position="bottom-right" />
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbToast, useToast } from 'bitboss-ui';
+
+const { toast } = useToast();
+const saveCount = ref(0);
 
-<style lang="postcss">
-@import './index.css';
-</style>
+// A stable id makes toast() an upsert: repeated saves patch the same
+// message (and restart its countdown) instead of stacking duplicates.
+const save = () => {
+	saveCount.value++;
+	toast({
+		id: 'draft-autosave',
+		title: 'Draft saved',
+		text: `Revision #${saveCount.value} stored just now.`,
+		variant: 'success',
+		icon: 'lucide:cloud-upload',
+		position: 'bottom-right',
+	});
+};
+</script>
 ```
 
-## Types
+Fields you omit in an upsert keep their previous value; fields you pass
+(including `undefined`-able ones like `text` or `icon`) are overwritten. This
+is the same mechanism `update(id, ...)` uses — the difference is that `update`
+never creates, while `toast({ id })` creates or patches.
+
+### Stacking, timers and dismissal
+
+Behaviour you get for free — don't rebuild any of it:
+
+- Toasts sharing a corner stack as a pile, newest in front; only the front
+  three are visible, older ones fade behind.
+- Hovering or focusing the stack fans it out and **pauses every auto-dismiss
+  timer**; timers also pause while the browser tab is hidden, and resume with
+  the time remaining.
+- Users dismiss with the ✕ (revealed on hover/focus, unless `hideClose`) or by
+  swiping the toast toward its nearest screen edge. Persistent toasts ignore
+  swipe so they can't be lost by accident.
+- Dismissal plays a ~300 ms exit slide; the pile closes up immediately.
+- Under 600 px viewports the stack goes full-width with tighter margins.
+
+### Positioning
+
+A toast renders in one of six corners: `top-left`, `top-center`, `top-right`,
+`bottom-left`, `bottom-center`, `bottom-right`. Resolution order per message:
+
+1. `toast({ position })` — per-message override;
+2. the host's `position` prop;
+3. the plugin's `toastPosition` config (library default `bottom-right`).
 
 ```ts
-export type BbToastProps = {
-	/**
-	 * Placement of the messages on the screen.
-	 *
-	 * @defaultValue `'bottom'`
-	 */
-	placement?:
-		| 'bottom'
-		| 'bottom-start'
-		| 'bottom-end'
-		| 'top'
-		| 'top-start'
-		| 'top-end';
+// A single toast, bottom-centre, regardless of the global default:
+toast({ title: 'Link copied', position: 'bottom-center' });
+```
+
+Pick one corner per product and stick to it; per-message positions are for rare
+cases (e.g. a copy control at the top of the screen). Messages with different
+positions form independent stacks.
+
+### Action buttons
+
+Pass an `actions` array to render buttons in a row below the text. While a
+button's `onClick` runs it shows a spinner, its siblings are disabled, and the
+auto-dismiss countdown is held; the toast dismisses itself when the callback
+resolves. A rejected callback keeps the toast open and the countdown resumes.
+Defaults per button: `variant: 'primary'`, `size: 'sm'`.
+
+The classic application is the **undo pattern** (Gmail's "Conversation deleted
+— Undo"): commit the delete immediately, no confirm dialog, and let the toast
+carry the escape hatch. The action's closure keeps the removed record; if the
+toast expires, the delete simply stands.
+
+**Delete with undo**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Saved replies</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Delete commits immediately — Undo lives on the toast.
+			</p>
+		</div>
+
+		<ul v-if="replies.length" class="flex flex-col gap-1.5">
+			<li
+				v-for="reply in replies"
+				:key="reply.id"
+				class="flex items-center justify-between gap-2"
+			>
+				<span class="truncate text-sm">{{ reply.title }}</span>
+				<BbButton
+					icon="lucide:trash-2"
+					size="xs"
+					variant="ghost"
+					@click="removeReply(reply)"
+				>
+					Delete {{ reply.title }}
+				</BbButton>
+			</li>
+		</ul>
+		<p v-else class="text-sm text-[color:var(--bb-text-muted)]">
+			No saved replies left.
+		</p>
+
+		<!--
+			Standalone example: it mounts its own host because it has no app root.
+			A real app mounts exactly one <BbToast /> at the app root, and pages
+			mount none. See ai/guides/agent-contract.md § Global Host Rule.
+		-->
+		<BbToast position="bottom-right" />
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbToast, useToast } from 'bitboss-ui';
+
+type Reply = { id: string; title: string };
+
+const { toast } = useToast();
+
+const replies = ref<Reply[]>([
+	{ id: 'thanks', title: 'Thanks, we are on it' },
+	{ id: 'refund', title: 'Refund processed' },
+	{ id: 'escalate', title: 'Escalated to engineering' },
+]);
+
+// The delete commits immediately — no confirm dialog. The Undo action's
+// closure keeps the removed row; the toast dismisses itself when the
+// callback resolves. If the toast expires, the delete simply stands.
+const removeReply = (reply: Reply) => {
+	const index = replies.value.indexOf(reply);
+	replies.value = replies.value.filter((entry) => entry.id !== reply.id);
+	toast({
+		title: `“${reply.title}” deleted`,
+		duration: 5000,
+		position: 'bottom-right',
+		actions: [
+			{
+				text: 'Undo',
+				size: 'xs',
+				onClick: () => {
+					replies.value.splice(Math.min(index, replies.value.length), 0, reply);
+				},
+			},
+		],
+	});
 };
+</script>
+```
+
+Failure and re-purposing compose into the retry pattern: a **rejected**
+handler keeps the toast open for another attempt, and a handler that calls
+`update(id, ...)` **takes ownership** — instead of dismissing, the toast
+morphs in place with a fresh countdown (e.g. into a success confirmation).
+
+**Retry that fails once, then morphs into success**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Workspace sync</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Northwind · last synced 12 minutes ago
+			</p>
+		</div>
+
+		<BbButton
+			prepend:icon="lucide:refresh-cw"
+			size="xs"
+			variant="outline"
+			@click="sync"
+		>
+			Sync now (fails once)
+		</BbButton>
+
+		<!--
+			Standalone example: it mounts its own host because it has no app root.
+			A real app mounts exactly one <BbToast /> at the app root, and pages
+			mount none. See ai/guides/agent-contract.md § Global Host Rule.
+		-->
+		<BbToast position="bottom-right" />
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbButton, BbToast, useToast } from 'bitboss-ui';
+
+const { toast, update } = useToast();
+
+// Fails on the first attempt, succeeds on the second.
+let attempts = 0;
+const syncApi = () =>
+	new Promise<void>((resolve, reject) => {
+		attempts += 1;
+		setTimeout(
+			() => (attempts % 2 ? reject(new Error('offline')) : resolve()),
+			900
+		);
+	});
+
+// Three action behaviours in one toast:
+// - while Retry runs it spins, Ignore is disabled, and the countdown is held;
+// - a REJECTED handler keeps the toast open (countdown resumes) — first click;
+// - a handler that calls update() takes ownership: the toast morphs in place
+//   with a fresh countdown instead of dismissing — second click.
+const sync = () => {
+	attempts = 0;
+	const id = toast({
+		title: 'Sync failed',
+		text: 'Could not reach Northwind. Retry fails once, then succeeds.',
+		variant: 'destructive',
+		icon: 'lucide:circle-x',
+		duration: 10000,
+		position: 'bottom-right',
+		actions: [
+			{
+				text: 'Retry',
+				variant: 'primary',
+				onClick: async () => {
+					await syncApi();
+					update(id, {
+						title: 'Workspace synced',
+						text: undefined,
+						variant: 'success',
+						icon: 'lucide:circle-check',
+						actions: [],
+						duration: 3000,
+					});
+				},
+			},
+			{ text: 'Ignore' },
+		],
+	});
+};
+</script>
 ```
 
-## Styles
-
-```css
-.bb-toast {
-	--page-margin: 20px;
-	--spacing: 12px;
-	--min-h: 50px;
-	--w: 300px;
-	--color: var(--bb-primary);
-	--padding-x: 12px;
-	--padding-y: 8px;
-	display: flex;
-	flex-direction: column;
-	gap: var(--spacing);
-	margin: var(--page-margin);
-	min-width: min(calc(100vw - var(--page-margin) * 2), var(--min-w));
-	position: fixed;
-	z-index: 10;
-
-	&[class*='bb-toast--bottom'] {
-		bottom: 0;
-
-		&.bb-toast--bottom {
-			left: 50%;
-			transform: translateX(-50%);
-			align-items: center;
-		}
-		&.bb-toast--bottom-start {
-			left: 0;
-			align-items: start;
-		}
-		&.bb-toast--bottom-end {
-			right: 0;
-			align-items: end;
-		}
-	}
-
-	&[class*='bb-toast--top'] {
-		top: 0;
-
-		&.bb-toast--top {
-			left: 50%;
-			transform: translateX(-50%);
-			align-items: center;
-		}
-		&.bb-toast--top-start {
-			left: 0;
-			align-items: start;
-		}
-		&.bb-toast--top-end {
-			right: 0;
-			align-items: end;
-		}
-	}
-
-	.toast-move,
-	.toast-enter-active,
-	.toast-leave-active {
-		transition: all 0.5s ease;
-	}
-
-	.toast-enter-from,
-	.toast-leave-to {
-		opacity: 0;
-	}
-
-	.toast-leave-active {
-		/* leaving items taken out of layout flow for correct animation calculation */
-	}
-}
-
-.bb-toast-message {
-	-webkit-backdrop-filter: blur(8px);
-	align-items: center;
-	backdrop-filter: blur(8px);
-	background-color: var(--bb-panel);
-	border-radius: 8px;
-	border: 1px solid var(--bb-border);
-	color: var(--bb-text);
-	display: grid;
-	gap: 8px;
-	grid-template-columns: auto 1fr;
-	max-width: min(calc(100vw - var(--page-margin) * 2), var(--w));
-	min-height: var(--min-h);
-	padding: var(--padding-y) var(--padding-x);
-	position: relative;
-	width: var(--w);
-
-	&:has(.bb-toast-message__icon-container:empty) {
-		grid-template-columns: 0px 1fr;
-		gap: 0;
-		.bb-toast-message__icon-container {
-			display: none;
-		}
-	}
-
-	.bb-toast-message__icon {
-		color: var(--color);
-		width: 24px;
-		height: 24px;
-	}
-
-	.bb-toast-message__content {
-		grid-column-start: 2;
-		grid-row-start: 1;
-	}
-
-	.bb-toast-message__title {
-		color: var(--color);
-		font-size: 14px;
-		font-weight: 600;
-		line-height: 1.4;
-		margin-bottom: 4px;
-	}
-
-	.bb-toast-message__text {
-		font-size: 13px;
-		font-weight: 400;
-		line-height: 1.4;
-		opacity: 0.9;
-	}
-
-	.bb-toast-message__close {
-		background: transparent;
-		border: none;
-		border-radius: 4px;
-		color: var(--bb-text);
-		grid-column-start: 2;
-		grid-row-start: 1;
-		float: right;
-		position: relative;
-		z-index: 1;
-		margin: calc(var(--padding-y) * -1) calc(var(--padding-x) * -1)
-			calc(var(--padding-y) * -1) 0px;
-		outline: none;
-		padding: 8px;
-		transition: all 0.2s ease;
-		width: fit-content;
-		opacity: 0.6;
-
-		&:hover {
-			opacity: 1;
-			background-color: rgba(0, 0, 0, 0.05);
-		}
-
-		&:focus-visible {
-			box-shadow: 0 0 0 2px var(--bb-ring);
-			opacity: 1;
-		}
-
-		svg {
-			width: 12px;
-			height: 12px;
-		}
-	}
-
-	&:hover {
-		.bb-toast-message__close {
-			opacity: 0.8;
-		}
-	}
-}
+A toast that needs more than one or two actions, or must not be missed, is
+usually a `BbDialog`/`BbConfirm`, not a toast.
+
+### Custom content with BbToastPortal
+
+When a toast needs richer content than icon + title + text + actions — an
+avatar, a release card, a custom layout — register named content with
+`<BbToastPortal>` and fire a toast that references it by `portal` name,
+passing data through `portalProps`. Portal content replaces the whole body
+(icon, title, text and `actions` are not rendered); the close button still
+overlays unless `hideClose`.
+
+**An interactive invite toast**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Invite teammate</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Portal toast with avatar + custom actions.
+			</p>
+		</div>
+
+		<BbButton prepend:icon="lucide:user-plus" variant="primary" @click="invite">
+			Send invite
+		</BbButton>
+
+		<!--
+			Standalone example: it mounts its own host because it has no app root.
+			A real app mounts exactly one <BbToast /> at the app root, and pages
+			mount none. See ai/guides/agent-contract.md § Global Host Rule.
+		-->
+		<BbToast position="bottom-right" />
+
+		<BbToastPortal v-slot="{ props, close }" name="invite">
+			<div class="flex items-center gap-3">
+				<BbAvatar size="sm">{{ props.initials }}</BbAvatar>
+				<div class="min-w-0 flex-1">
+					<p class="text-sm font-semibold">{{ props.name }} was invited</p>
+					<p class="text-xs text-[color:var(--bb-text-muted)]">
+						Northwind · Design
+					</p>
+					<div class="mt-2 flex gap-2">
+						<BbButton size="xs" @click="close">Got it</BbButton>
+						<BbButton size="xs" variant="outline" @click="close">Undo</BbButton>
+					</div>
+				</div>
+			</div>
+		</BbToastPortal>
+	</div>
+</template>
+
+<script setup lang="ts">
+import {
+	BbAvatar,
+	BbButton,
+	BbToast,
+	BbToastPortal,
+	useToast,
+} from 'bitboss-ui';
+
+const { toast } = useToast();
+
+const invite = () =>
+	toast({
+		portal: 'invite',
+		portalProps: { name: 'Ada Lovelace', initials: 'AL' },
+		duration: 8000,
+		position: 'bottom-right',
+	});
+</script>
 ```
+
+- `<BbToastPortal name="...">` renders nothing where it sits — mount it
+  anywhere (the layout next to the host is idiomatic). Its default slot
+  receives `{ toast, props, close }`: `props` is the firing call's
+  `portalProps`, `close` dismisses that specific toast. One registered portal
+  can back many live toasts with different `portalProps`.
+- Alternatively pass a component directly: `toast({ portal: MyCard,
+portalProps: {...} })`. It receives `portalProps` as props plus a `close`
+  function prop.
+
+Use portals sparingly — if all you need is buttons under the message, the
+`actions` option above is the lighter tool.
+
+### Top layer, modals and panels
+
+The host teleports its stacks into the browser top layer via the Popover API,
+so toasts paint above dialogs, off-canvas panels, and dropdowns. Two behaviours
+follow, both automatic:
+
+- **Open modal (`BbDialog`/`BbOffCanvas`):** the region moves _inside_ the
+  top-most modal, because a modal makes everything outside itself inert — this
+  keeps toasts clickable while the modal is open.
+- **Open non-modal panels:** an off-canvas sheet claims its screen edge and
+  the toast stack yields — a bottom sheet pushes bottom stacks up, a right
+  panel pushes right stacks left — sliding in step with the panel.
+
+There is nothing to configure; just don't fight it with manual `z-index` or by
+mounting extra hosts inside overlays.
+
+### Works well with
+
+- `useToast` — the API surface; see its composable doc for the option table.
+- `useConfirm` / `BbConfirm` — confirm the destructive action first, toast the
+  outcome after.
+- `BbDropzone` + `BbProgress` — capture the file in the page, run the upload
+  behind a `loading` toast, resolve it with `update`.
+- `BbAlert` — mirror anything the user must still act on into the page; the
+  toast is gone in four seconds.
+
+### Gotchas & anti-patterns
+
+- **No host, no toasts**: `toast(...)` without a mounted `<BbToast />`
+  enqueues silently — and the messages never expire, because the dismiss timer
+  lives inside the host. Mount exactly one host, at the app root — never one per
+  page or per component.
+- Don't hand-roll notification markup or timers; between variants, upsert,
+  portals, and persistence the component covers it.
+- Don't put must-act information only in a toast — it self-dismisses.
+- `hideClose` + `persistent` without a code path to `dismiss(id)` traps the
+  message on screen forever.
+- A `variant` without an `icon` is invisible tone: it only changes screen
+  reader priority.
+- Fire toasts from user/network events, not from component `setup()` during
+  SSR.
+
+### Accessibility
+
+- Tone maps to live-region semantics per message: `warning` and `destructive`
+  announce as `role="alert"` / `aria-live="assertive"`; every other variant
+  (including custom ones) uses `role="status"` / `aria-live="polite"`. Don't
+  overuse the loud variants.
+- Each toast is `aria-atomic`, so an `update(...)` re-announces the whole
+  message — the loading → success morph reads correctly.
+- The close button carries a localised `aria-label` (plugin `locale`) and is
+  keyboard reachable; timers pause while the stack has focus, so keyboard
+  users aren't racing the countdown.
+- Because toasts self-dismiss, never put information a user _must_ act on only
+  in a toast — mirror critical state in the page (a `BbAlert` or inline copy).
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `position` | `BbToastPosition \| undefined` |  |  |  |
+
+## Events
+
+- None.
+
+## Slots
+
+- None.
+
+## See Also
+
+- [BbAlert](./BbAlert.md) — Shows contextual status messages.