bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/recipes/inertia/wizard-form.md

@@ -0,0 +1,1477 @@
+---
+title: Wizard Form (Inertia)
+summary: Mailchimp-grade 4-step campaign wizard for Laravel + Inertia — BbBaseButton stepper with done/current/upcoming/locked states, per-step validation gating Next behind a BbAlert summary merging form.errors, BbSmoothHeight step swaps, the step mirrored into the URL with no extra visit, a usePromiseForm draft with save-draft everywhere, and useConfirmOnRouteLeave guarding unsaved changes, all through one coopting page context.
+---
+
+# Recipe: Wizard Form (Inertia)
+
+The same Mailchimp-grade "Create campaign" wizard adapted for **Laravel +
+Inertia**: four steps (Audience → Content → Schedule → Review) behind a
+custom stepper header, per-step validation gating forward progress, the
+active step mirrored into the URL, save-draft everywhere, and a dirty-state
+leave guard. Anatomy, components, the context shape, copy and data are
+identical to the Vue recipe; only the data/URL/mutation layer changes — the
+draft is a [`usePromiseForm`](../../guides/inertia-helpers.md) whose
+`form.errors` merge straight into the per-step validation, the step mirrors
+into the URL without an Inertia visit (it's pure display state), and
+[`useConfirmOnRouteLeave`](../../guides/inertia-helpers.md) replaces
+`onBeforeRouteLeave`.
+
+Sibling recipes: [Vue](../vue/wizard-form.md) ·
+[Nuxt](../nuxt/wizard-form.md).
+
+## Prerequisites
+
+- `<BbConfirm />` and `<BbToast />` mounted once in the app layout.
+- From the [Inertia Helpers](../../guides/inertia-helpers.md) toolkit:
+  `usePromiseForm`, `useConfirmOnRouteLeave`, `useProp`, `useQuery`,
+  `useResourceContext`.
+- [App Layout](../../guides/app-layout.md) and
+  [Page Shell](../../guides/page-shell.md) copied into
+  `src/components/layout/` per their guides — the page renders inside this
+  chrome.
+- Controller: `Inertia::render('Campaigns/Edit', ['campaign' => $campaign,
+'draft' => $draft])` — `campaign` is the record, `draft` the saved field
+  values (matching `CampaignDraft` verbatim, camelCase — the `FormRequest`
+  behind the mutation routes below is assumed to key its `422` validation
+  messages the same way). Mutation routes: `PUT /campaigns/:id` (save
+  draft), `POST /campaigns/:id/send-test`, `POST /campaigns/:id/send`,
+  `DELETE /campaigns/:id`; small JSON endpoints back the segment lookups:
+  `GET /segments/search?q=`, `GET /segments/:id`,
+  `GET /segments/:id/estimate`, `GET /segments/:id/detail`.
+
+## Key ideas
+
+- **One coopting page context.** `provideCampaignWizard()` joins the
+  page-shell stack once and owns the draft, the current step, the live
+  validation, and every action. All seven leaves call
+  `useCampaignWizard()` and nothing else — the only prop on the page is
+  the id the segment peek renders.
+- **The stepper is derived state, not navigation chrome.** A step is
+  reachable exactly when every step before it validates — the same
+  predicate `goNext()` uses — so jumping from the header can never outrun
+  the validation gate. Steps already passed show `done` (checkmarked),
+  reachable future steps stay numbered (`upcoming`), and `locked` steps
+  render as disabled `BbBaseButton`s.
+- **Validation merges `form.errors` live — no manual bookkeeping.**
+  `issues` recomputes from the client-side checks _and_
+  `usePromiseForm`'s already-reactive `form.errors`, folded onto the step
+  that owns each field, so a failed save surfaces exactly like a blocked
+  Next. The `BbAlert` summary and inline field errors still appear only
+  after a blocked Next (`attempted`), and shrink live as each problem
+  clears.
+- **The draft and campaign arrive as page props — there is no loading
+  state.** `usePromiseForm` seeds itself from the `draft` prop once;
+  `ctx.loading` stays permanently `false`. The requested `?step` is
+  clamped to the first incomplete step **at setup**, synchronously — no
+  deferred fetch to wait on.
+- **The step mirrors into the URL without an Inertia visit.** The step is
+  pure client display state, not server data, so changing it updates
+  `history.replaceState` directly instead of round-tripping through
+  `router.visit` — unlike a tabs-as-filters page, no prop on this page
+  depends on which step is showing.
+- **One `BbSmoothHeight` wraps the alert + step outlet together**, so the
+  step swap _and_ the validation summary appearing both glide instead of
+  snapping. Conditional regions inside a step (the scheduled-date fields)
+  need no wrapper of their own — the same resize observer catches them.
+- **Back and Save draft are always free; validation only guards forward.**
+  The page's one `variant="primary"` is the final Send/Schedule submit,
+  with `:loading` riding `ctx.submitting` (`usePromiseForm`'s
+  `isSubmitting`).
+- **Leaving is guarded by `form.isDirty` — no snapshots.**
+  `useConfirmOnRouteLeave` reads `draft.isDirty` and whitelists the
+  campaign's own save/send/send-test URLs so submitting can't block
+  itself; `draft.defaults()` re-baselines after a successful save/send so
+  the follow-up navigate-away never re-prompts, and discarding sets a
+  local flag before its own delete + navigate for the same reason.
+
+## Page anatomy
+
+```
+CampaignWizard/
+	Index.vue          ← assembly: PageShell slots, stepper, BbSmoothHeight outlet, footer
+	context.ts         ← coopting page context (shell + usePromiseForm draft + step + validation + actions)
+	StepperHeader.vue  ← BbBaseButton steps with done/current/upcoming/locked states
+	AudienceStep.vue   ← segment select, audience filters, live recipient estimate
+	ContentStep.vue    ← subject/preheader, body, template picker, send-test
+	ScheduleStep.vue   ← send-now vs scheduled, date + timezone
+	ReviewStep.vue     ← read-only summary with per-section Edit links
+	WizardFooter.vue   ← Back · Save draft · Next / Send with :loading
+	SegmentPeek.vue    ← sidebar workbench for the selected segment
+```
+
+Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
+(left nav + fat footer) and [Page Shell](../../guides/page-shell.md).
+Wizard archetype: no filter rail, no tabs, no table, no pagination, no bulk
+bar — the work surface is the step outlet.
+
+## Action inventory
+
+| #   | Action                      | Trigger                          | Mechanism                                                                   |
+| --- | --------------------------- | -------------------------------- | --------------------------------------------------------------------------- |
+| 1   | Advance a step (validated)  | footer **Next** (secondary)      | `goNext()` — blocks and raises the `BbAlert` summary on issues              |
+| 2   | Go back                     | footer **Back** (ghost)          | `goBack()` — never validated                                                |
+| 3   | Jump to an unlocked step    | stepper header                   | `goToStep()`; locked steps are disabled `BbBaseButton`s                     |
+| 4   | Edit a section from Review  | per-section **Edit** links       | `goToStep()` back to that step                                              |
+| 5   | Save draft                  | footer ghost, on every step      | `saveDraft()` → `usePromiseForm.put` (whitelisted) + toast                  |
+| 6   | Send a test email           | Content step ghost               | `sendTest()` → `post` to `/campaigns/:id/send-test`                         |
+| 7   | Send / schedule campaign    | Review, the page's one `primary` | `submit()` with `:loading`, whole-wizard validation, `put` then `post`      |
+| 8   | Discard draft               | topbar, destructive              | `useConfirm` → `remove` (DELETE) + `router.visit('/campaigns')`             |
+| 9   | Peek the segment            | segment name (Audience & Review) | `peekSegment()` → shell stack                                               |
+| 10  | Leave with unsaved changes  | any Inertia visit                | `useConfirmOnRouteLeave` guard → `useConfirm`                               |
+| 11  | Restore position on refresh | URL `?step=N`                    | read via `useQuery()`, clamped at setup; changes via `history.replaceState` |
+
+## The code
+
+### context.ts
+
+```ts
+// CampaignWizard/context.ts
+import {
+	computed,
+	inject,
+	provide,
+	reactive,
+	ref,
+	watch,
+	watchEffect,
+	type ComputedRef,
+	type InjectionKey,
+	type Ref,
+} from 'vue';
+import { router } from '@inertiajs/vue3';
+import { useConfirm, useToast } from 'bitboss-ui';
+import {
+	usePageShellContext,
+	type PageShellContext,
+} from '@/components/layout/usePageShellContext';
+import { useConfirmOnRouteLeave } from '@/composables/useConfirmOnRouteLeave';
+import { usePromiseForm } from '@/composables/usePromiseForm';
+import { useProp } from '@/composables/useProp';
+import { useQuery } from '@/composables/useQuery';
+import type { Campaign, Segment } from '@/types';
+
+/** What the sidebar can show: the audience segment behind the campaign. */
+export type PeekItem = { type: 'segment'; id: number };
+
+export type StepKey = 'audience' | 'content' | 'schedule' | 'review';
+export type StepStatus = 'done' | 'current' | 'upcoming' | 'locked';
+export type SendMode = 'now' | 'scheduled';
+
+export const STEPS: { key: StepKey; label: string }[] = [
+	{ key: 'audience', label: 'Audience' },
+	{ key: 'content', label: 'Content' },
+	{ key: 'schedule', label: 'Schedule' },
+	{ key: 'review', label: 'Review' },
+];
+
+export interface CampaignTemplate {
+	id: string;
+	name: string;
+	description: string;
+}
+
+export const TEMPLATES: CampaignTemplate[] = [
+	{
+		id: 'product-update',
+		name: 'Product update',
+		description: 'Hero image, feature blocks, one CTA.',
+	},
+	{
+		id: 'newsletter',
+		name: 'Newsletter',
+		description: 'Multi-story digest with section dividers.',
+	},
+	{
+		id: 'plain-text',
+		name: 'Plain text',
+		description: 'No chrome — reads like a personal email.',
+	},
+];
+
+export const TIMEZONES = [
+	{ label: 'Rome (CET)', value: 'Europe/Rome' },
+	{ label: 'London (GMT)', value: 'Europe/London' },
+	{ label: 'New York (ET)', value: 'America/New_York' },
+	{ label: 'Chicago (CT)', value: 'America/Chicago' },
+	{ label: 'Los Angeles (PT)', value: 'America/Los_Angeles' },
+	{ label: 'Tokyo (JST)', value: 'Asia/Tokyo' },
+	{ label: 'Sydney (AEST)', value: 'Australia/Sydney' },
+];
+
+export const COUNTRIES = [
+	{ label: 'Italy', value: 'IT' },
+	{ label: 'France', value: 'FR' },
+	{ label: 'Germany', value: 'DE' },
+	{ label: 'United Kingdom', value: 'GB' },
+	{ label: 'United States', value: 'US' },
+	{ label: 'Canada', value: 'CA' },
+];
+
+/** Everything the four steps edit. Persisted verbatim by saveDraft/submit.
+ *
+ * `type`, not `interface`: only a type alias satisfies `usePromiseForm`'s
+ * `Record<string, FormValue>` constraint (implicit index signature). */
+export type CampaignDraft = {
+	// Audience
+	segmentId: number | null;
+	/** Empty array = every country in the segment. */
+	countries: string[];
+	/** Skip contacts already emailed in the last 7 days. */
+	excludeRecent: boolean;
+	// Content
+	subject: string;
+	preheader: string;
+	body: string;
+	templateId: string | null;
+	// Schedule
+	sendMode: SendMode;
+	/** ISO string from BbDatePickerInput; only meaningful when scheduled. */
+	sendAt: string | null;
+	timezone: string;
+};
+
+export interface StepIssue {
+	/** Draft field the issue belongs to — leaves match on it for inline errors. */
+	field: string;
+	message: string;
+}
+
+export interface CampaignWizardContext {
+	// -- Coopted contexts ------------------------------------------------------
+	shell: PageShellContext<PeekItem>;
+	// -- Wizard state ----------------------------------------------------------
+	loading: Ref<boolean>;
+	campaign: Ref<Campaign | null>;
+	draft: CampaignDraft;
+	step: Ref<StepKey>;
+	dirty: ComputedRef<boolean>;
+	lastSavedAt: Ref<string | null>;
+	submitting: Ref<boolean>;
+	// -- Validation ------------------------------------------------------------
+	issues: ComputedRef<Record<StepKey, StepIssue[]>>;
+	/** Steps whose Next was blocked at least once — only they show errors. */
+	attempted: Record<StepKey, boolean>;
+	stepStatus: (key: StepKey) => StepStatus;
+	fieldErrors: (step: StepKey, field: string) => string[];
+	// -- Audience intel --------------------------------------------------------
+	selectedSegment: Ref<Segment | null>;
+	estimatedRecipients: Ref<number | null>;
+	// -- Peek grammar ----------------------------------------------------------
+	peekSegment: () => void;
+	// -- Actions (complete: API + state + toast) --------------------------------
+	goToStep: (key: StepKey) => void;
+	goBack: () => void;
+	goNext: () => void;
+	saveDraft: () => Promise<void>;
+	sendTest: () => Promise<void>;
+	submit: () => Promise<void>;
+	discardDraft: () => Promise<void>;
+}
+
+const key: InjectionKey<CampaignWizardContext> = Symbol('campaign-wizard');
+
+/** Which step owns each server-validated field — used to route a failed
+ * save's `form.errors` onto the right step, merged into `issues` below. */
+const FIELDS_BY_STEP: Record<StepKey, (keyof CampaignDraft)[]> = {
+	audience: ['segmentId'],
+	content: ['subject', 'body', 'templateId'],
+	schedule: ['sendAt', 'timezone'],
+	review: [],
+};
+const stepForField = (field: string): StepKey | undefined =>
+	(Object.keys(FIELDS_BY_STEP) as StepKey[]).find((stepKey) =>
+		(FIELDS_BY_STEP[stepKey] as string[]).includes(field)
+	);
+
+export function provideCampaignWizard(): CampaignWizardContext {
+	const { toast } = useToast();
+	const { confirm } = useConfirm();
+
+	// -- Coopt the specific contexts: once, here, for the whole page. ----------
+	const shell = usePageShellContext<PeekItem>();
+
+	// -- Wizard state -----------------------------------------------------------
+	// The record and the saved draft arrive as page props — no fetch, no
+	// loading state. `usePromiseForm` seeds itself once from `draft`; every
+	// further edit is local until saveDraft/submit visits the server.
+	const campaign = useProp<Campaign>('campaign');
+	const campaignId = campaign.value.id;
+	const loading = ref(false);
+
+	const initialDraft = useProp<CampaignDraft>('draft').value;
+	const {
+		form: draft,
+		put,
+		post,
+		remove,
+		isSubmitting,
+	} = usePromiseForm<CampaignDraft>({ ...initialDraft });
+
+	// -- Validation ---------------------------------------------------------------
+	// Live on every keystroke; SURFACED only per `attempted` (set when a Next,
+	// submit or save is blocked), so untouched steps never open covered in red.
+	const issues = computed<Record<StepKey, StepIssue[]>>(() => {
+		const audience: StepIssue[] = [];
+		if (draft.segmentId === null)
+			audience.push({
+				field: 'segmentId',
+				message: 'Choose the segment this campaign goes to.',
+			});
+
+		const content: StepIssue[] = [];
+		if (!draft.subject.trim())
+			content.push({ field: 'subject', message: 'Write a subject line.' });
+		else if (draft.subject.length > 150)
+			content.push({
+				field: 'subject',
+				message: 'Keep the subject under 150 characters.',
+			});
+		if (!draft.body.trim())
+			content.push({
+				field: 'body',
+				message: 'The email body cannot be empty.',
+			});
+		if (draft.templateId === null)
+			content.push({ field: 'templateId', message: 'Pick a template.' });
+
+		const schedule: StepIssue[] = [];
+		if (draft.sendMode === 'scheduled') {
+			if (!draft.sendAt)
+				schedule.push({ field: 'sendAt', message: 'Pick a send date.' });
+			if (!draft.timezone)
+				schedule.push({ field: 'timezone', message: 'Pick a timezone.' });
+		}
+
+		// Merge server (422) errors onto the step that owns each field —
+		// `form.errors` is already reactive, so no separate bookkeeping is
+		// needed, unlike a manual snapshot/errors ref.
+		const withServerErrors = (
+			stepKey: StepKey,
+			list: StepIssue[]
+		): StepIssue[] => [
+			...list,
+			...FIELDS_BY_STEP[stepKey]
+				.filter((field) => draft.errors[field])
+				.map((field) => ({ field, message: draft.errors[field] as string })),
+		];
+
+		return {
+			audience: withServerErrors('audience', audience),
+			content: withServerErrors('content', content),
+			schedule: withServerErrors('schedule', schedule),
+			review: [],
+		};
+	});
+
+	const attempted = reactive<Record<StepKey, boolean>>({
+		audience: false,
+		content: false,
+		schedule: false,
+		review: false,
+	});
+
+	const fieldErrors = (stepKey: StepKey, field: string): string[] =>
+		attempted[stepKey]
+			? issues.value[stepKey]
+					.filter((issue) => issue.field === field)
+					.map((issue) => issue.message)
+			: [];
+
+	// -- Step machine ---------------------------------------------------------------
+	const step = ref<StepKey>('audience');
+
+	const indexOf = (stepKey: StepKey) =>
+		STEPS.findIndex((item) => item.key === stepKey);
+
+	// The single gating predicate: a step is reachable when every step
+	// before it validates. Next, the stepper, and submit all derive from it.
+	const unlocked = (stepKey: StepKey) =>
+		STEPS.slice(0, indexOf(stepKey)).every(
+			(item) => issues.value[item.key].length === 0
+		);
+
+	const stepStatus = (stepKey: StepKey): StepStatus => {
+		if (stepKey === step.value) return 'current';
+		// Only steps already passed count as done — unlocked future steps stay
+		// numbered (upcoming), not checkmarked.
+		if (indexOf(stepKey) < indexOf(step.value)) return 'done';
+		return unlocked(stepKey) ? 'upcoming' : 'locked';
+	};
+
+	const firstIncompleteStep = (): StepKey =>
+		STEPS.find((item) => issues.value[item.key].length > 0)?.key ?? 'review';
+
+	const goToStep = (stepKey: StepKey) => {
+		if (stepKey !== step.value && stepStatus(stepKey) === 'locked') return;
+		step.value = stepKey;
+	};
+
+	const goBack = () => {
+		const previous = STEPS[indexOf(step.value) - 1];
+		if (previous) step.value = previous.key;
+	};
+
+	const goNext = () => {
+		const current = step.value;
+		if (issues.value[current].length > 0) {
+			attempted[current] = true; // raises the alert + inline errors
+			return;
+		}
+		attempted[current] = false;
+		const next = STEPS[indexOf(current) + 1];
+		if (next) step.value = next.key;
+	};
+
+	// The draft is already loaded (a page prop), so the requested step is
+	// clamped synchronously here — no deferred fetch to wait on.
+	const query = useQuery();
+	const requestedStep = STEPS[Number(query.step) - 1]?.key ?? 'audience';
+	step.value =
+		stepStatus(requestedStep) === 'locked'
+			? firstIncompleteStep()
+			: requestedStep;
+
+	// Mirror the step into the URL. This is pure client display state (no
+	// page prop depends on it), so it updates history directly instead of
+	// round-tripping through an Inertia visit.
+	watch(step, (next) => {
+		const url = new URL(window.location.href);
+		url.searchParams.set('step', String(indexOf(next) + 1));
+		window.history.replaceState(history.state, '', url);
+	});
+
+	// -- Audience intel ---------------------------------------------------------------
+	// Small JSON endpoints, not Inertia visits — resolving the segment must
+	// not re-render the page. Same resolve-by-id pattern as the flagship's
+	// customer pill.
+	const selectedSegment = ref<Segment | null>(null);
+	watchEffect(async () => {
+		selectedSegment.value =
+			draft.segmentId === null
+				? null
+				: await fetch(`/segments/${draft.segmentId}`).then((res) => res.json());
+	});
+
+	const estimatedRecipients = ref<number | null>(null);
+	watchEffect(async () => {
+		if (draft.segmentId === null) {
+			estimatedRecipients.value = null;
+			return;
+		}
+		const params = new URLSearchParams();
+		draft.countries.forEach((code) => params.append('countries[]', code));
+		params.set('excludeRecent', String(draft.excludeRecent));
+		estimatedRecipients.value = await fetch(
+			`/segments/${draft.segmentId}/estimate?${params.toString()}`
+		).then((res) => res.json());
+	});
+
+	// -- Peek grammar ----------------------------------------------------------------
+	const peekSegment = () => {
+		if (draft.segmentId !== null)
+			shell.push({ type: 'segment', id: draft.segmentId }, true);
+	};
+
+	// -- Persistence + dirty guard ------------------------------------------------------
+	const lastSavedAt = ref<string | null>(null);
+	const dirty = computed(() => draft.isDirty);
+
+	// Set right before a deliberate delete, so the guard below never
+	// double-prompts on the navigate-away that follows it.
+	const discarded = ref(false);
+
+	const campaignUrl = `/campaigns/${campaignId}`;
+	useConfirmOnRouteLeave({
+		disabled: () => discarded.value || !dirty.value,
+		whitelist: [campaignUrl, `${campaignUrl}/send`, `${campaignUrl}/send-test`],
+		title: 'Leave campaign setup?',
+		text: 'You have unsaved changes. Leave and lose them, or stay and save the draft.',
+	});
+
+	// -- Actions --------------------------------------------------------------------
+	// After a failed save/send, form.errors is already populated by Inertia;
+	// jump to whichever step owns the first offending field, same surfacing
+	// as a blocked Next.
+	const surfaceServerErrors = () => {
+		const brokenStep = Object.keys(draft.errors)
+			.map(stepForField)
+			.find((found): found is StepKey => Boolean(found));
+		if (brokenStep) {
+			attempted[brokenStep] = true;
+			step.value = brokenStep;
+		}
+	};
+
+	const saveDraft = async () => {
+		try {
+			await put(campaignUrl);
+			draft.defaults(); // re-baseline: this save is the new "clean" state
+			lastSavedAt.value = new Date().toISOString();
+			toast({ title: 'Draft saved.', variant: 'success' });
+		} catch {
+			surfaceServerErrors();
+		}
+	};
+
+	const sendTest = async () => {
+		if (issues.value.content.length > 0) {
+			attempted.content = true; // same surfacing as a blocked Next
+			return;
+		}
+		await post(`${campaignUrl}/send-test`);
+		toast({ title: 'Test email sent to your address.', variant: 'success' });
+	};
+
+	const submit = async () => {
+		// Whole-wizard validation: land the user on the first broken step.
+		const incomplete = STEPS.find((item) => issues.value[item.key].length > 0);
+		if (incomplete) {
+			attempted[incomplete.key] = true;
+			step.value = incomplete.key;
+			return;
+		}
+		try {
+			await put(campaignUrl);
+			await post(`${campaignUrl}/send`);
+			draft.defaults(); // the guard has nothing left to protect
+			toast({
+				title:
+					draft.sendMode === 'now'
+						? 'Campaign is on its way.'
+						: 'Campaign scheduled.',
+				variant: 'success',
+			});
+			router.visit(campaignUrl);
+		} catch {
+			surfaceServerErrors();
+		}
+	};
+
+	const discardDraft = async () => {
+		const ok = await confirm({
+			variant: 'destructive',
+			title: 'Discard draft',
+			text: `Delete "${campaign.value?.name ?? 'this campaign'}" and everything entered so far? This cannot be undone.`,
+			yes: 'Discard',
+			no: 'Keep draft',
+		});
+		if (!ok) return;
+		discarded.value = true; // don't double-prompt via the leave guard
+		await remove(campaignUrl);
+		toast({ title: 'Draft discarded.', variant: 'success' });
+		router.visit('/campaigns');
+	};
+
+	const ctx: CampaignWizardContext = {
+		shell,
+		loading,
+		campaign,
+		draft,
+		step,
+		dirty,
+		lastSavedAt,
+		submitting: isSubmitting,
+		issues,
+		attempted,
+		stepStatus,
+		fieldErrors,
+		selectedSegment,
+		estimatedRecipients,
+		peekSegment,
+		goToStep,
+		goBack,
+		goNext,
+		saveDraft,
+		sendTest,
+		submit,
+		discardDraft,
+	};
+	provide(key, ctx);
+	return ctx;
+}
+
+export function useCampaignWizard(): CampaignWizardContext {
+	const ctx = inject(key);
+	if (!ctx)
+		throw new Error('useCampaignWizard() called outside CampaignWizard');
+	return ctx;
+}
+```
+
+### Index.vue — the assembly
+
+```vue
+<!-- CampaignWizard/Index.vue -->
+<template>
+	<PageShell>
+		<!-- Topbar: breadcrumbs left; save state + the destructive escape right.
+		     Wizard archetype: no page search, no filter rail, no tabs. -->
+		<template #topbar>
+			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
+				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
+				     without it their overflow recompute fights the flex layout every frame. -->
+				<BbBreadcrumbs class="min-w-0 flex-auto" :items="crumbs" />
+				<div class="flex shrink-0 items-center gap-3">
+					<span v-if="savedLabel" class="text-xs text-gray-500">{{
+						savedLabel
+					}}</span>
+					<BbButton
+						prepend:icon="lucide:trash-2"
+						variant="destructive"
+						@click="ctx.discardDraft"
+					>
+						Discard draft
+					</BbButton>
+				</div>
+			</div>
+		</template>
+
+		<div class="mx-auto flex w-full max-w-3xl flex-col gap-5 p-4">
+			<header class="flex flex-col gap-0.5">
+				<h1 class="text-lg font-semibold">
+					{{ ctx.campaign.value?.name ?? 'New campaign' }}
+				</h1>
+				<p class="text-sm text-gray-500">
+					Set up the audience, content and schedule, then review and send.
+				</p>
+			</header>
+
+			<StepperHeader />
+
+			<!-- One wrapper around the alert AND the step outlet: the step swap
+			     and the validation summary appearing/shrinking both glide. -->
+			<!-- Enable height motion only after mount so first paint does not
+			     animate in; later step swaps still glide. -->
+			<BbSmoothHeight :disabled="!stepHeightReady">
+				<div class="flex flex-col gap-4">
+					<BbAlert
+						v-if="summaryIssues.length"
+						hide-close
+						icon="lucide:circle-x"
+						:title="`Fix ${summaryIssues.length} ${summaryIssues.length === 1 ? 'issue' : 'issues'} to continue`"
+						variant="destructive"
+					>
+						<template #text>
+							<ul class="list-disc pl-4">
+								<li v-for="issue in summaryIssues" :key="issue.field">
+									{{ issue.message }}
+								</li>
+							</ul>
+						</template>
+					</BbAlert>
+
+					<div v-if="ctx.loading.value" class="flex justify-center p-10">
+						<BbSpinner />
+					</div>
+					<AudienceStep v-else-if="ctx.step.value === 'audience'" />
+					<ContentStep v-else-if="ctx.step.value === 'content'" />
+					<ScheduleStep v-else-if="ctx.step.value === 'schedule'" />
+					<ReviewStep v-else />
+				</div>
+			</BbSmoothHeight>
+
+			<WizardFooter />
+		</div>
+
+		<!-- Clicking the segment's NAME peeks it — Audience step and Review. -->
+		<template #sidebar>
+			<SegmentPeek
+				v-if="ctx.shell.current.value?.type === 'segment'"
+				:segment-id="ctx.shell.current.value.id"
+			/>
+		</template>
+	</PageShell>
+</template>
+
+<script setup lang="ts">
+import { computed, onMounted, ref } from 'vue';
+import {
+	BbAlert,
+	BbBreadcrumbs,
+	BbButton,
+	BbSmoothHeight,
+	BbSpinner,
+} from 'bitboss-ui';
+import PageShell from '@/components/layout/PageShell.vue';
+import { provideCampaignWizard } from './context';
+import AudienceStep from './AudienceStep.vue';
+import ContentStep from './ContentStep.vue';
+import ReviewStep from './ReviewStep.vue';
+import ScheduleStep from './ScheduleStep.vue';
+import SegmentPeek from './SegmentPeek.vue';
+import StepperHeader from './StepperHeader.vue';
+import WizardFooter from './WizardFooter.vue';
+
+const ctx = provideCampaignWizard();
+
+/** Keep SmoothHeight off while the first paint settles; enable after 300ms
+ * for step-to-step glides. */
+const stepHeightReady = ref(false);
+onMounted(() => {
+	setTimeout(() => {
+		stepHeightReady.value = true;
+	}, 300);
+});
+
+const crumbs = computed(() => [
+	{ key: 'dashboard', text: 'Dashboard', href: '/dashboard' },
+	{ key: 'campaigns', text: 'Campaigns', href: '/campaigns' },
+	{ key: 'setup', text: ctx.campaign.value?.name ?? 'New campaign' },
+]);
+
+// The summary shows only the CURRENT step's issues, and only once the user
+// tried to leave it — it shrinks live as each problem is fixed.
+const summaryIssues = computed(() =>
+	ctx.attempted[ctx.step.value] ? ctx.issues.value[ctx.step.value] : []
+);
+
+const savedLabel = computed(() => {
+	if (ctx.dirty.value) return 'Unsaved changes';
+	if (!ctx.lastSavedAt.value) return null;
+	const time = new Date(ctx.lastSavedAt.value).toLocaleTimeString('en-US', {
+		hour: 'numeric',
+		minute: '2-digit',
+	});
+	return `Draft saved at ${time}`;
+});
+</script>
+```
+
+### StepperHeader.vue
+
+```vue
+<!-- CampaignWizard/StepperHeader.vue -->
+<template>
+	<nav aria-label="Campaign setup steps" class="flex items-center gap-1">
+		<template v-for="(stepMeta, index) in STEPS" :key="stepMeta.key">
+			<!-- Connector line between steps. -->
+			<div
+				v-if="index > 0"
+				aria-hidden="true"
+				class="h-px min-w-3 flex-1 bg-[var(--bb-border)]"
+			/>
+
+			<!-- The primitive gives element semantics + disabled handling; the
+			     look is entirely ours. Done and upcoming steps jump, locked
+			     steps are inert. -->
+			<BbBaseButton
+				:aria-current="status(stepMeta.key) === 'current' ? 'step' : undefined"
+				class="flex items-center gap-2 rounded-[var(--bb-radius)] px-2 py-1.5 text-sm focus-visible:ring-2 focus-visible:ring-[var(--bb-primary)]"
+				:class="{
+					'bg-[var(--bb-hover)] font-medium':
+						status(stepMeta.key) === 'current',
+					'hover:bg-[var(--bb-hover)]': ['done', 'upcoming'].includes(
+						status(stepMeta.key)
+					),
+					'text-gray-400': status(stepMeta.key) === 'locked',
+				}"
+				:disabled="status(stepMeta.key) === 'locked'"
+				@click="() => ctx.goToStep(stepMeta.key)"
+			>
+				<span
+					class="flex size-5 shrink-0 items-center justify-center rounded-full border text-xs"
+					:class="{
+						'border-transparent bg-[var(--bb-primary)] text-[var(--bb-primary-fg)]':
+							status(stepMeta.key) === 'done',
+						'border-[var(--bb-primary)] text-[color:var(--bb-primary)]':
+							status(stepMeta.key) === 'current',
+						'border-[var(--bb-border)]': status(stepMeta.key) === 'locked',
+					}"
+				>
+					<BbIcon
+						v-if="status(stepMeta.key) === 'done'"
+						icon="lucide:check"
+						size="12"
+					/>
+					<template v-else>{{ index + 1 }}</template>
+				</span>
+				{{ stepMeta.label }}
+			</BbBaseButton>
+		</template>
+	</nav>
+</template>
+
+<script setup lang="ts">
+import { BbBaseButton, BbIcon } from 'bitboss-ui';
+import { STEPS, useCampaignWizard, type StepKey } from './context';
+
+const ctx = useCampaignWizard();
+
+const status = (key: StepKey) => ctx.stepStatus(key);
+</script>
+```
+
+### AudienceStep.vue
+
+```vue
+<!-- CampaignWizard/AudienceStep.vue -->
+<template>
+	<section class="flex flex-col gap-4">
+		<div class="flex flex-col gap-0.5">
+			<h2 class="text-base font-semibold">Who gets this email?</h2>
+			<p class="text-sm text-gray-500">
+				Pick a segment, then narrow it with delivery filters.
+			</p>
+		</div>
+
+		<!-- Query-aware items function: the select searches the API as you type. -->
+		<BbSelect
+			v-model="ctx.draft.segmentId"
+			:errors="segmentErrors"
+			item-text="name"
+			item-value="id"
+			:items="searchSegments"
+			label="Segment"
+			label-mode="outside"
+			placeholder="Search segments…"
+			required
+		/>
+
+		<!-- Resolved segment + live estimate: the context owns both fetches. -->
+		<div
+			v-if="ctx.selectedSegment.value"
+			class="flex flex-col gap-1 rounded-[var(--bb-radius)] border p-3 text-sm"
+		>
+			<div class="flex items-center justify-between gap-2">
+				<BbButton size="sm" variant="link" @click="ctx.peekSegment">
+					{{ ctx.selectedSegment.value.name }}
+				</BbButton>
+				<span class="text-xs text-gray-500">
+					Last synced {{ shortDate(ctx.selectedSegment.value.lastSyncedAt) }}
+				</span>
+			</div>
+			<p class="text-gray-500">
+				{{ number.format(ctx.selectedSegment.value.contactCount) }} contacts in
+				the segment ·
+				<strong class="text-[var(--bb-text)]">
+					{{
+						ctx.estimatedRecipients.value === null
+							? '…'
+							: number.format(ctx.estimatedRecipients.value)
+					}}
+				</strong>
+				estimated recipients after filters
+			</p>
+		</div>
+
+		<BbSelect
+			v-model="ctx.draft.countries"
+			:items="COUNTRIES"
+			item-text="label"
+			item-value="value"
+			label="Limit to countries"
+			label-mode="outside"
+			multiple
+			placeholder="All countries"
+		/>
+
+		<BbSwitch
+			v-model="ctx.draft.excludeRecent"
+			description="Avoids fatigue: anyone who already received a campaign this week is skipped."
+			label="Skip contacts emailed in the last 7 days"
+		/>
+	</section>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbButton, BbSelect, BbSwitch } from 'bitboss-ui';
+import { COUNTRIES, useCampaignWizard } from './context';
+import type { Segment } from '@/types';
+
+const ctx = useCampaignWizard();
+
+// A small JSON endpoint, not an Inertia visit — searching the segment
+// picker must not re-render the page.
+const searchSegments = (query: string): Promise<Segment[]> =>
+	fetch(`/segments/search?q=${encodeURIComponent(query)}`).then((res) =>
+		res.json()
+	);
+
+// Inline errors appear only after a blocked Next (attempted), per the context.
+const segmentErrors = computed(() => ctx.fieldErrors('audience', 'segmentId'));
+
+const number = new Intl.NumberFormat('en-US');
+const shortDate = (value: string) =>
+	new Date(value).toLocaleDateString('en-US', {
+		month: 'short',
+		day: 'numeric',
+	});
+</script>
+```
+
+### ContentStep.vue
+
+```vue
+<!-- CampaignWizard/ContentStep.vue -->
+<template>
+	<section class="flex flex-col gap-4">
+		<div class="flex flex-col gap-0.5">
+			<h2 class="text-base font-semibold">What does it say?</h2>
+			<p class="text-sm text-gray-500">
+				Subject and preheader are what people see in the inbox list.
+			</p>
+		</div>
+
+		<BbTextInput
+			v-model="ctx.draft.subject"
+			:description="`${ctx.draft.subject.length}/150 characters`"
+			:errors="errorsFor('subject')"
+			label="Subject line"
+			label-mode="outside"
+			placeholder="The July roast drop is here — 20% off subscriptions"
+			required
+		/>
+
+		<BbTextInput
+			v-model="ctx.draft.preheader"
+			description="Optional. Shows after the subject in most inboxes — keep it under 90 characters."
+			label="Preheader"
+			label-mode="outside"
+			placeholder="Three new single origins, roasted this week."
+		/>
+
+		<!-- Fixed rows on purpose: an auto-growing textarea inside BbSmoothHeight
+		     would re-animate the outlet on every line break while typing. -->
+		<BbTextarea
+			v-model="ctx.draft.body"
+			:errors="errorsFor('body')"
+			label="Body"
+			label-mode="outside"
+			placeholder="Write the email…"
+			required
+			:rows="10"
+		/>
+
+		<BbRadioGroup
+			v-model="ctx.draft.templateId"
+			:errors="errorsFor('templateId')"
+			item-text="name"
+			item-value="id"
+			:items="TEMPLATES"
+			legend="Template"
+			name="template"
+			required
+		>
+			<!-- Name + one-line description per option, from the same items. -->
+			<template #label="{ item, text }">
+				<span class="flex flex-col">
+					<span>{{ text }}</span>
+					<span class="text-xs text-gray-500">{{ item.description }}</span>
+				</span>
+			</template>
+		</BbRadioGroup>
+
+		<!-- Auto-loading: the button tracks the async handler by itself. -->
+		<div>
+			<BbButton
+				prepend:icon="lucide:send"
+				variant="ghost"
+				@click="ctx.sendTest"
+			>
+				Send test email
+			</BbButton>
+		</div>
+	</section>
+</template>
+
+<script setup lang="ts">
+import { BbButton, BbRadioGroup, BbTextarea, BbTextInput } from 'bitboss-ui';
+import { TEMPLATES, useCampaignWizard } from './context';
+
+const ctx = useCampaignWizard();
+
+const errorsFor = (field: string) => ctx.fieldErrors('content', field);
+</script>
+```
+
+### ScheduleStep.vue
+
+```vue
+<!-- CampaignWizard/ScheduleStep.vue -->
+<template>
+	<section class="flex flex-col gap-4">
+		<div class="flex flex-col gap-0.5">
+			<h2 class="text-base font-semibold">When does it go out?</h2>
+			<p class="text-sm text-gray-500">
+				Send it as soon as you confirm, or pick a date.
+			</p>
+		</div>
+
+		<BbRadioGroup
+			v-model="ctx.draft.sendMode"
+			item-text="label"
+			item-value="value"
+			:items="[
+				{
+					label: 'Send now — goes out as soon as you confirm on Review',
+					value: 'now',
+				},
+				{ label: 'Schedule for later', value: 'scheduled' },
+			]"
+			legend="When to send"
+			name="send-mode"
+		/>
+
+		<!-- No inner BbSmoothHeight: the page-level wrapper's resize observer
+		     already animates this region appearing and disappearing. -->
+		<div
+			v-if="ctx.draft.sendMode === 'scheduled'"
+			class="grid gap-4 sm:grid-cols-2"
+		>
+			<BbDatePickerInput
+				v-model="ctx.draft.sendAt"
+				description="Campaigns go out at 9:00 AM local to the timezone you pick."
+				:errors="errorsFor('sendAt')"
+				label="Send date"
+				label-mode="outside"
+				:min="today"
+				required
+			/>
+			<BbSelect
+				v-model="ctx.draft.timezone"
+				:errors="errorsFor('timezone')"
+				item-text="label"
+				item-value="value"
+				:items="TIMEZONES"
+				label="Timezone"
+				label-mode="outside"
+				required
+			/>
+		</div>
+	</section>
+</template>
+
+<script setup lang="ts">
+import { BbDatePickerInput, BbRadioGroup, BbSelect } from 'bitboss-ui';
+import { TIMEZONES, useCampaignWizard } from './context';
+
+const ctx = useCampaignWizard();
+
+const errorsFor = (field: string) => ctx.fieldErrors('schedule', field);
+
+// BbDatePickerInput's min takes YYYY-MM-DD.
+const today = new Date().toISOString().slice(0, 10);
+</script>
+```
+
+### ReviewStep.vue
+
+```vue
+<!-- CampaignWizard/ReviewStep.vue -->
+<template>
+	<section class="flex flex-col gap-5">
+		<div class="flex flex-col gap-0.5">
+			<h2 class="text-base font-semibold">Review and send</h2>
+			<p class="text-sm text-gray-500">
+				Everything below is what goes out. Edit any section — your progress is
+				kept.
+			</p>
+		</div>
+
+		<!-- Audience -->
+		<section
+			class="flex flex-col gap-2 rounded-[var(--bb-radius)] border p-3 text-sm"
+		>
+			<div class="flex items-center justify-between gap-2">
+				<h3 class="text-xs font-semibold uppercase tracking-wide text-gray-500">
+					Audience
+				</h3>
+				<BbButton
+					prepend:icon="lucide:pencil"
+					size="sm"
+					variant="ghost"
+					@click="() => ctx.goToStep('audience')"
+				>
+					Edit
+				</BbButton>
+			</div>
+			<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
+				<dt class="text-gray-500">Segment</dt>
+				<dd>
+					<BbButton size="sm" variant="link" @click="ctx.peekSegment">
+						{{ ctx.selectedSegment.value?.name ?? '—' }}
+					</BbButton>
+				</dd>
+				<dt class="text-gray-500">Countries</dt>
+				<dd>{{ countryNames || 'All countries' }}</dd>
+				<dt class="text-gray-500">Fatigue filter</dt>
+				<dd>
+					{{
+						ctx.draft.excludeRecent
+							? 'Skipping contacts emailed in the last 7 days'
+							: 'Off'
+					}}
+				</dd>
+				<dt class="text-gray-500">Estimated recipients</dt>
+				<dd class="font-medium">
+					{{
+						ctx.estimatedRecipients.value === null
+							? '—'
+							: number.format(ctx.estimatedRecipients.value)
+					}}
+				</dd>
+			</dl>
+		</section>
+
+		<!-- Content -->
+		<section
+			class="flex flex-col gap-2 rounded-[var(--bb-radius)] border p-3 text-sm"
+		>
+			<div class="flex items-center justify-between gap-2">
+				<h3 class="text-xs font-semibold uppercase tracking-wide text-gray-500">
+					Content
+				</h3>
+				<BbButton
+					prepend:icon="lucide:pencil"
+					size="sm"
+					variant="ghost"
+					@click="() => ctx.goToStep('content')"
+				>
+					Edit
+				</BbButton>
+			</div>
+			<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
+				<dt class="text-gray-500">Subject</dt>
+				<dd class="font-medium">{{ ctx.draft.subject }}</dd>
+				<dt class="text-gray-500">Preheader</dt>
+				<dd>{{ ctx.draft.preheader || '—' }}</dd>
+				<dt class="text-gray-500">Template</dt>
+				<dd>{{ templateName }}</dd>
+				<dt class="text-gray-500">Body</dt>
+				<dd class="text-gray-500">{{ bodyExcerpt }}</dd>
+			</dl>
+		</section>
+
+		<!-- Schedule -->
+		<section
+			class="flex flex-col gap-2 rounded-[var(--bb-radius)] border p-3 text-sm"
+		>
+			<div class="flex items-center justify-between gap-2">
+				<h3 class="text-xs font-semibold uppercase tracking-wide text-gray-500">
+					Schedule
+				</h3>
+				<BbButton
+					prepend:icon="lucide:pencil"
+					size="sm"
+					variant="ghost"
+					@click="() => ctx.goToStep('schedule')"
+				>
+					Edit
+				</BbButton>
+			</div>
+			<p>{{ scheduleSummary }}</p>
+		</section>
+	</section>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbButton } from 'bitboss-ui';
+import { COUNTRIES, TEMPLATES, TIMEZONES, useCampaignWizard } from './context';
+
+const ctx = useCampaignWizard();
+
+const number = new Intl.NumberFormat('en-US');
+
+const countryNames = computed(() =>
+	ctx.draft.countries
+		.map(
+			(code) =>
+				COUNTRIES.find((country) => country.value === code)?.label ?? code
+		)
+		.join(', ')
+);
+
+const templateName = computed(
+	() =>
+		TEMPLATES.find((template) => template.id === ctx.draft.templateId)?.name ??
+		'—'
+);
+
+const bodyExcerpt = computed(() =>
+	ctx.draft.body.length > 140
+		? `${ctx.draft.body.slice(0, 140)}…`
+		: ctx.draft.body
+);
+
+const scheduleSummary = computed(() => {
+	if (ctx.draft.sendMode === 'now')
+		return 'Sends immediately after you confirm.';
+	if (!ctx.draft.sendAt) return '—';
+	const date = new Date(ctx.draft.sendAt).toLocaleDateString('en-US', {
+		weekday: 'short',
+		month: 'short',
+		day: 'numeric',
+		year: 'numeric',
+	});
+	const zone =
+		TIMEZONES.find((timezone) => timezone.value === ctx.draft.timezone)
+			?.label ?? ctx.draft.timezone;
+	return `Scheduled for ${date} · 9:00 AM · ${zone}`;
+});
+</script>
+```
+
+### WizardFooter.vue
+
+```vue
+<!-- CampaignWizard/WizardFooter.vue -->
+<template>
+	<footer class="flex items-center justify-between gap-2 border-t pt-4">
+		<!-- Back is always free — never validated, only bounded. -->
+		<BbButton
+			:disabled="isFirst"
+			prepend:icon="lucide:chevron-left"
+			variant="ghost"
+			@click="ctx.goBack"
+		>
+			Back
+		</BbButton>
+
+		<div class="flex items-center gap-2">
+			<!-- On every step, whatever the validation state. -->
+			<BbButton
+				prepend:icon="lucide:save"
+				variant="ghost"
+				@click="ctx.saveDraft"
+			>
+				Save draft
+			</BbButton>
+
+			<BbButton
+				v-if="!isReview"
+				append:icon="lucide:chevron-right"
+				variant="secondary"
+				@click="ctx.goNext"
+			>
+				Next
+			</BbButton>
+
+			<!-- The page's single primary. -->
+			<BbButton
+				v-else
+				:loading="ctx.submitting.value"
+				prepend:icon="lucide:send"
+				variant="primary"
+				@click="ctx.submit"
+			>
+				{{
+					ctx.draft.sendMode === 'now' ? 'Send campaign' : 'Schedule campaign'
+				}}
+			</BbButton>
+		</div>
+	</footer>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbButton } from 'bitboss-ui';
+import { STEPS, useCampaignWizard } from './context';
+
+const ctx = useCampaignWizard();
+
+const isFirst = computed(() => ctx.step.value === STEPS[0].key);
+const isReview = computed(() => ctx.step.value === 'review');
+</script>
+```
+
+### SegmentPeek.vue
+
+```vue
+<!-- CampaignWizard/SegmentPeek.vue -->
+<template>
+	<div v-if="segment" class="flex flex-col gap-4 text-sm">
+		<header class="flex flex-col gap-0.5">
+			<h2 class="text-base font-semibold">{{ segment.name }}</h2>
+			<p class="text-xs text-gray-500">
+				{{ number.format(segment.contactCount) }} contacts · last synced
+				{{ longDate(segment.lastSyncedAt) }}
+			</p>
+		</header>
+
+		<!-- Stat strip. -->
+		<div class="grid grid-cols-3 gap-2">
+			<div class="rounded-[var(--bb-radius)] border p-2">
+				<p class="text-xs text-gray-500">Avg. open rate</p>
+				<p class="font-semibold">{{ percent(segment.openRate) }}</p>
+			</div>
+			<div class="rounded-[var(--bb-radius)] border p-2">
+				<p class="text-xs text-gray-500">Avg. click rate</p>
+				<p class="font-semibold">{{ percent(segment.clickRate) }}</p>
+			</div>
+			<div class="rounded-[var(--bb-radius)] border p-2">
+				<p class="text-xs text-gray-500">Unsubscribes / mo</p>
+				<p class="font-semibold">
+					{{ number.format(segment.monthlyUnsubscribes) }}
+				</p>
+			</div>
+		</div>
+
+		<!-- The segment's definition, so "who is in here" is answerable in place. -->
+		<section class="flex flex-col gap-1.5">
+			<h3 class="text-xs font-semibold uppercase tracking-wide text-gray-500">
+				Conditions
+			</h3>
+			<ul class="flex flex-col gap-1">
+				<li v-for="rule in segment.rules" :key="rule" class="flex gap-2">
+					<BbIcon
+						class="mt-0.5 shrink-0 text-gray-400"
+						icon="lucide:filter"
+						size="14"
+					/>
+					<span>{{ rule }}</span>
+				</li>
+			</ul>
+		</section>
+
+		<!-- Recent campaigns to this segment: fatigue check before sending. -->
+		<section class="flex flex-col gap-1.5">
+			<h3 class="text-xs font-semibold uppercase tracking-wide text-gray-500">
+				Recent campaigns
+			</h3>
+			<ul class="flex flex-col">
+				<li
+					v-for="recent in segment.recentCampaigns"
+					:key="recent.id"
+					class="flex items-center justify-between gap-2 border-b py-1.5 last:border-b-0"
+				>
+					<span>{{ recent.name }}</span>
+					<span class="text-xs text-gray-500">{{
+						longDate(recent.sentAt)
+					}}</span>
+				</li>
+			</ul>
+		</section>
+
+		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
+			<BbButton
+				append:icon="lucide:arrow-up-right"
+				:href="`/segments/${segment.id}`"
+				size="sm"
+				variant="ghost"
+			>
+				Open segment
+			</BbButton>
+		</footer>
+	</div>
+
+	<div v-else class="flex justify-center p-8">
+		<BbSpinner />
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
+import { useResourceContext } from '@/composables/useResourceContext';
+import type { SegmentDetail } from '@/types';
+
+const props = defineProps<{ segmentId: number }>();
+
+// A small JSON endpoint, not a page visit — opening the peek never
+// re-renders the wizard underneath it. Re-fetches whenever the stack shows
+// a different segment.
+const { data: segment } = useResourceContext<SegmentDetail, number>(
+	() => props.segmentId,
+	(id) => fetch(`/segments/${id}/detail`).then((res) => res.json())
+);
+
+const number = new Intl.NumberFormat('en-US');
+const percent = (value: number) => `${(value * 100).toFixed(1)}%`;
+const longDate = (value: string) =>
+	new Date(value).toLocaleDateString('en-US', {
+		month: 'short',
+		day: 'numeric',
+		year: 'numeric',
+	});
+</script>
+```
+
+## Why it is built this way
+
+- **The context coopts, leaves consume.** `shell` is joined once in
+  `provideCampaignWizard()`; seven components share the draft, the step
+  machine, validation and every action through one `useCampaignWizard()`
+  call. The only data prop on the page is `SegmentPeek`'s `segment-id`;
+  no component receives a callback.
+- **One gating predicate rules everything.** `unlocked(step)` — every
+  step before it validates — drives the stepper's `upcoming`/`locked`
+  states, `goToStep`'s guard, and (via `issues[current]`) `goNext`. A
+  stepper jump is therefore exactly as safe as pressing Next the right
+  number of times; the header can never smuggle the user past validation.
+  Only steps already passed count as `done` — a defaulted step (Schedule
+  starts valid on "send now") stays numbered (`upcoming`), not
+  checkmarked, until the user actually moves past it, though it is
+  jumpable straight away: there is genuinely nothing left to do there.
+- **`form.errors` is the error contract for saves, with zero extra
+  bookkeeping.** It is already reactive, so `issues` simply folds it onto
+  the step that owns each field (`FIELDS_BY_STEP`) — no manual
+  `serverErrors` ref to clear and repopulate. A failed save renders in the
+  exact same `BbAlert` summary and inline errors as a client-side block,
+  and `surfaceServerErrors()` jumps the user to the first broken step.
+  Field names stay camelCase (`segmentId`, not `segment_id`) to keep the
+  context's shape identical across all three platforms — the `FormRequest`
+  behind the mutation routes is assumed to key its messages the same way.
+- **No loading state, because there is nothing to load.** `campaign` and
+  `draft` arrive as page props; `usePromiseForm` seeds itself from `draft`
+  once and `ctx.loading` stays `false` for the whole page's life. The
+  requested `?step` is clamped **synchronously at setup** — unlike the
+  Vue/Nuxt recipes, there is no fetch to wait on before it's safe to do so.
+- **The step mirrors via `history.replaceState`, not a visit.** Unlike a
+  tab switch on a listing page, no page prop depends on which wizard step
+  is showing, so round-tripping through `router.visit` would only add
+  latency and risk resetting local form edits for no benefit — a direct
+  history update keeps the URL shareable at zero cost.
+- **Steps are four components, not one with a `type` prop.** Each step
+  owns its inputs, its formatting helpers, and nothing else; the assembly
+  is a `v-if` chain inside the `BbSmoothHeight` outlet. A single
+  `WizardStep` with a renderer switch is the API-monster seed.
+- **`BbBaseButton` is the right stepper primitive.** The steps are
+  clickable surfaces whose look is entirely bespoke — token-styled pills
+  with a number/check bullet — and the primitive contributes what CSS
+  can't: a real `<button>`, native `disabled` for locked steps, and a
+  focus scaffold (the visible ring is ours, per its guide). `aria-current="step"`
+  is set manually — the prop-based `ariaCurrentValue` only applies to
+  exact-active _links_.
+- **One `BbSmoothHeight`, wrapping alert + outlet.** Both height changes
+  on this page — the step swap and the summary toggling — animate through
+  the same wrapper, so they compose into one glide when Next is blocked.
+  Regions that appear _inside_ a step (the scheduled-date grid) are caught
+  by the same resize observer; and the body textarea keeps fixed `rows`
+  because an auto-growing textarea inside the wrapper would re-animate the
+  outlet on every line break. Height motion is enabled only after mount
+  (`:disabled` until a 300ms `onMounted` flag flips), so the first paint
+  never animates in.
+- **The guard drives off `form.isDirty`, whitelisted against its own
+  saves.** `useConfirmOnRouteLeave` reads `dirty` (an alias for
+  `draft.isDirty`) and whitelists `campaignUrl` and its `/send` and
+  `/send-test` children, so `saveDraft`/`sendTest`/`submit` can never
+  block themselves. `draft.defaults()` re-baselines the dirty tracking
+  right after a successful save/send, so the follow-up `router.visit`
+  away from the page never re-prompts; `discardDraft` sets a local
+  `discarded` flag before its own delete + navigate for the same reason —
+  the same "nothing left to protect" guarantee the Vue/Nuxt snapshot reset
+  gives, expressed with Inertia's own dirty tracking instead.
+- **Sizing:** everything follows `md`-first — footer, topbar and step
+  forms use default-size buttons and regular inputs; `sm` appears only on
+  the dense inline surfaces (Review's Edit/segment links, the peek
+  footer). One `variant="primary"` (Send/Schedule); Next is `secondary`;
+  Save draft, Back and Send test are ghosts; the two destructive actions
+  (discard, leave-with-changes) both ride `useConfirm`.
+
+## Variations
+
+- **Branching steps**: make `STEPS` a computed — e.g. an A/B test
+  campaign inserts a "Variants" step after Content. The status predicate,
+  URL mapping and footer already work off the array, so nothing else
+  changes.
+- **Autosave**: debounce a watcher on `draft` that calls a silent
+  `saveDraft` (no toast); the footer button and the topbar save-state stay
+  as the manual escape, and the leave guard almost never fires.
+- **Vertical checklist stepper** (Mailchimp's actual layout): swap
+  `StepperHeader` for a left rail where each step row also shows its
+  one-line summary and the step bodies expand in place — the context and
+  its predicate are unchanged.
+- **Send time**: add an hour `BbSelect` beside the timezone and fold it
+  into `sendAt` on save, replacing the fixed 9:00 AM policy.