@twoux/ui 0.0.0-stage → 0.1.0

package/agent/docs-md/sign-in.md

@@ -0,0 +1,114 @@
+# Sign in
+
+Provider buttons first, then email. Single sign-on is found from the email domain, and an email link means no password to remember.
+
+Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui
+
+## When to use
+
+- The first screen of an account: sign in and create account in one flow.
+- Letting people choose how they sign in: a provider, single sign-on or an email link.
+
+## When not to use
+
+- Asking for anything beyond how to sign in. Setup questions belong in Onboarding step (onboarding-step).
+- Gating content that people could read first. Show it before asking them to sign in.
+
+## Structure
+
+1. Provider buttons (logo and "Continue with" name)
+2. Divider ("or")
+3. Work email field
+4. Continue button (becomes "Continue with SSO" for SSO domains)
+5. Error under the field
+
+## Guidelines
+
+- Put provider buttons first, then email. One primary action: the email button.
+- Find single sign-on from the email domain. Say "twoux.example signs in with single sign-on" and change the button to Continue with SSO.
+- Use an email link so there is no password to remember or retype.
+- Put errors under the field and say what to do, for example "This email uses Google to sign in. Continue with Google instead."
+- Do not reveal which part was wrong, or whether an account exists, unless the product already shows that elsewhere. Use the same message either way.
+- Set autocomplete on every field (email, current-password, one-time-code) so browsers and password managers can fill them.
+- Validate on press, not on every keystroke, and keep the email people typed after an error.
+
+## Content
+
+- Button: "Continue with Google", "Continue with email", "Continue with SSO".
+- Field error: "Enter your work email, for example sam@company.com."
+- Do not write "Wrong password" or "No account found". Write what to try next.
+
+## Accessibility
+
+- The email field has a visible label and the right type and autocomplete values (SC 1.3.5, 3.3.2).
+- The error is linked to the field with aria-invalid and the field description, and is announced when it appears (SC 3.3.1, 4.1.3).
+- Signing in never depends on remembering or transcribing a password alone: providers and email links are alternatives (SC 3.3.8).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move through the provider buttons, the email field and the primary button |
+| Enter | In the email field, submit the form |
+| Space or Enter | Press the focused provider button |
+
+## Examples
+
+### error
+
+```tsx
+import { SignInOptions } from "@twoux/ui";
+
+export const meta = { title: "Say what to do next", description: "The error sits under the field and names the way in. It does not say which part was wrong.", order: 2 };
+
+export default function Example() {
+	return (
+		<div className="w-full max-w-sm">
+			<SignInOptions
+				providers={["google"]}
+				error="This email signs in with Google. Continue with Google instead."
+				onProvider={() => {}}
+				onEmail={() => {}}
+			/>
+		</div>
+	);
+}
+```
+
+### sign-in
+
+```tsx
+import { SignInOptions, toast, type ProviderId } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Providers, then email", description: "Providers first. An email on a single sign-on domain changes the button to Continue with SSO. Try sam@twoux.example.", order: 1 };
+
+export default function Example() {
+	const [busy, setBusy] = useState<ProviderId | "email" | "sso" | undefined>();
+	const run = (what: ProviderId | "email" | "sso", message: string) => {
+		setBusy(what);
+		setTimeout(() => { setBusy(undefined); toast.success(message); }, 900);
+	};
+	return (
+		<div className="grid w-full max-w-sm gap-4">
+			<h1 className="text-xl font-semibold text-ink">Sign in to TwoUX</h1>
+			<SignInOptions
+				providers={["google", "microsoft"]}
+				ssoDomains={["twoux.example"]}
+				busy={busy}
+				onProvider={(p) => run(p, "Opened the sign-in window")}
+				onEmail={(email) => run("email", `Sign-in link sent to ${email}. Check your inbox.`)}
+				onSso={(domain) => run("sso", `Continuing with ${domain}`)}
+			/>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Provider logo
+- Onboarding step
+- Text input
+- Form validation
+- Error messages

package/agent/docs-md/spacing.md

@@ -0,0 +1,55 @@
+# Spacing
+
+Spacing sits on a 4px grid with 2px for fine detail. Space shows relationship: closer means related. Apps use role utilities: fixed ones inside controls that never change, and region ones between parts that tighten by themselves in a workspace.
+
+Kind: foundation · Group: Visual foundation
+
+## Principles
+
+- Proximity is meaning. Related items sit closer than unrelated ones, and items of the same kind share the same gap.
+- 4px grid. Spacing is built from small multiples, from 2px to 40px on a 4px grid.
+- Spacing comes from components and tokens, not from pixel values typed into a page.
+
+## Guidelines
+
+- Use the role utilities, not numbers. Inside a control: gap-hair (2px), gap-tight (4px), gap-control (6px, icon to label in buttons, menu items and badges only), gap-inline (8px). Between parts: gap-group. Inside a card, pane or panel: p-region. Page sides and top: px-page, pt-page-top.
+- Fixed roles never change; region roles change with the layout. On an inset canvas a region is padded 16px, groups sit 16px apart and the page has 24px sides and a 20px top. In a workspace (AppShell frame="flush") regions are padded 8px, groups 12px, the page 12px and 8px, and regions meet at a 1px line.
+- Inside a group (a form field's label, input and help text) use 4 to 8px; between groups use gap-group so the grouping is visible.
+- Below 860px every page, workspace or not, uses the inset values with 16px page sides, so stacked panes do not crowd.
+- The numeric steps (p-2, gap-3) are for TwoUX's own components. twoux check warns on them in app code and names the role to use.
+- Every value sits on the 4px grid except two documented ones: 6px between an icon and its label in a row (gap-control), and the padding inside controls generated from shadcn, which stays as shadcn ships it so every button, input and menu keeps its shape.
+
+## Accessibility
+
+- Spacing between small targets counts: a target under 24 by 24px still passes if a 24px circle around it does not overlap another target.
+- Content must reflow at 320 CSS px; fixed gaps must not force horizontal scrolling outside tables.
+
+## Do
+
+- Use the same gap between all rows of a property list.
+- Let the component own its internal padding.
+
+## Don't
+
+- Do not add margin to a component from outside to nudge it into place.
+- Do not invent in-between values like 13px or 18px.
+
+## Tokens
+
+| Token | Value | Use |
+|---|---|---|
+| `--spacing-hair` | `2px` | Fixed. Icon to text nudges, keycap padding, badge inset (gap-hair, p-hair) |
+| `--spacing-tight` | `4px` | Fixed. Inside a control; label to help text |
+| `--spacing-control` | `6px` | Fixed. Icon to label inside buttons, menu items and badges only |
+| `--spacing-inline` | `8px` | Fixed. Between controls in a row; field label to input |
+| `--spacing-group` | `16px · 12px in a workspace` | Region. Between groups and sections (gap-group) |
+| `--spacing-region` | `16px · 8px in a workspace` | Region. Inside a card, pane or panel (p-region) |
+| `--spacing-page` | `24px · 12px in a workspace` | Region. Page sides (px-page) |
+| `--spacing-page-top` | `20px · 8px in a workspace` | Region. Page top (pt-page-top) |
+| `--spacing-region-gap` | `16px · 1px in a workspace` | Region. Between cards on a page; in a workspace regions meet at a divider |
+
+## Related
+
+- Content density
+- Layout
+- Design tokens

package/agent/docs-md/split-button.md

@@ -0,0 +1,100 @@
+# Split button
+
+A button joined to a chevron: the button runs the usual action (Import data), the chevron opens its variants (Import all, Import selection).
+
+Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui
+
+## When to use
+
+- One action is the usual choice and a few close variants of it are needed now and then, such as Import data with Import all and Import selection.
+- Space is tight and the variants belong together, as in a table header toolbar.
+
+## When not to use
+
+- For unrelated actions. Use separate buttons, or a Dropdown menu behind More actions.
+- When no option is clearly the usual one. Use a menu button (Button with a chevron) so people choose every time.
+- For a destructive main action. Put destructive variants in the menu, never on the main part.
+
+## Structure
+
+1. Main part: icon (optional) and label
+2. Divider
+3. Chevron part with its own name, opening a menu
+
+## Guidelines
+
+- Use SplitButton instead of joining a Button and a menu by hand, so the parts, divider, names and menu alignment are the same everywhere.
+- The main part runs the action at once; the chevron only opens the menu. Repeat the main action first in the menu so the list is complete.
+- Outline by default. Use the primary variant only when it is the view's one primary action.
+- Disable a variant that can't run yet (Import selection with nothing selected) rather than hiding it, and say why nearby.
+
+## Content
+
+- Main label: a verb and an object, Import data. Menu items: short variants, Import all, Import selection.
+- Name the chevron by what it opens: More import options.
+
+## Accessibility
+
+- Two buttons in a group: the main button, then a menu button with aria-haspopup, aria-expanded and its own accessible name.
+- 2.5.8 Target size: the chevron part is at least 24px wide.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move from the main part to the chevron |
+| Enter / Space | Run the main action, or open the menu from the chevron |
+| ↓ (chevron) | Open the menu on the first item |
+| Esc | Close the menu and return to the chevron |
+
+## Examples
+
+### import
+
+```tsx
+import { DropdownMenuItem, DropdownMenuSeparator, SplitButton, toast } from "@twoux/ui";
+import { FileSpreadsheet, Upload } from "lucide-react";
+
+export const meta = { title: "Import data", description: "The main part runs the usual action. The chevron, named “More import options”, opens its variants; Import selection is disabled until rows are selected.", order: 1 };
+
+export default function Example() {
+	return (
+		<div className="flex flex-wrap items-center gap-3">
+			<SplitButton
+				onClick={() => toast("Choose a CSV or Excel file to import")}
+				menuLabel="More import options"
+				menu={
+					<>
+						<DropdownMenuItem onSelect={() => toast("Importing all rows from the file")}>Import all</DropdownMenuItem>
+						<DropdownMenuItem disabled>Import selection</DropdownMenuItem>
+						<DropdownMenuSeparator />
+						<DropdownMenuItem onSelect={() => toast("Downloaded the import template")}><FileSpreadsheet />Download template</DropdownMenuItem>
+					</>
+				}
+			>
+				<Upload />Import data
+			</SplitButton>
+			<SplitButton
+				variant="default"
+				onClick={() => toast.success("Published 12 products")}
+				menuLabel="More publish options"
+				menu={
+					<>
+						<DropdownMenuItem onSelect={() => toast.success("Published 12 products")}>Publish now</DropdownMenuItem>
+						<DropdownMenuItem onSelect={() => toast("Scheduled for 9:00 tomorrow")}>Schedule for tomorrow</DropdownMenuItem>
+					</>
+				}
+			>
+				Publish 12 products
+			</SplitButton>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Button
+- Dropdown menu
+- Dense table
+- CSV import

package/agent/docs-md/stat-compare.md

@@ -0,0 +1,82 @@
+# Stat card with comparison
+
+One number that matters, with its change against a named previous period shown by arrow, sign and colour, and an optional faint previous-period line.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- A quick view of how one metric is doing, alone or beside related stats.
+- The number is the answer; a chart would add reading time without insight.
+
+## When not to use
+
+- For one metric over time. Use the TwoUX Line chart card.
+- For plain text or labels.
+
+## Structure
+
+1. Label with period ("Applications · last 30 days")
+2. Value
+3. Change: arrow, signed percentage, comparison text
+4. Optional mini chart: current solid, previous dashed grey
+5. Legend (This period, Previous period)
+
+## Guidelines
+
+- The number leads; label and change are secondary.
+- Show change with an arrow, a sign and colour together, never colour alone.
+- Say what the change compares against, "vs 264 the 30 days before".
+- Draw the previous period as a dashed grey line behind the current one.
+- Loading shows a skeleton of the number and change; an error shows "Couldn't load" with Try again in the card; no data shows a dash and "No data for this period", never 0.
+- When the stat has a target, say it in text ("18 of 25 roles filled") rather than a ring or donut.
+
+## Content
+
+- Label with the metric and the period, and include units.
+- Round the value for reading, keep the exact value in the tooltip.
+- Keep any description to two lines; longer text is truncated with the full text in a tooltip.
+
+## Accessibility
+
+- 1.4.1 Use of Color: good or bad change is also shown by arrow and sign.
+- 1.1.1 Non-text Content: the mini chart has a text alternative or is hidden because the figures are in text.
+- 1.4.11 Non-text Contrast: the arrow and line reach 3:1 unless the text carries the same information.
+- A missing value reads "No data for this period" to screen readers, not "dash".
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Focus the card when it links to a report |
+
+## Examples
+
+### kpis
+
+```tsx
+import { StatCompare } from "@twoux/ui";
+
+export const meta = { title: "Key numbers", description: "One number, its change against a named period, and whether that change is good, said in colour and in words. Time to hire going down is good; applications going down is not.", order: 1 };
+
+export default function Example() {
+	return (
+		<div className="grid w-full grid-cols-3 gap-3 max-md:grid-cols-1">
+			{[
+				{ label: "Applications this month", value: "595", change: "+12%", period: "October", good: true, spark: [42, 48, 51, 47, 55, 60, 58, 66] },
+				{ label: "Median time to hire", value: "23 days", change: "-4 days", period: "last quarter", good: true, spark: [31, 30, 29, 27, 27, 25, 24, 23] },
+				{ label: "Offer acceptance", value: "71%", change: "-6 pts", period: "last quarter", good: false, spark: [80, 79, 77, 78, 75, 74, 72, 71] },
+			].map((s) => (
+				<div key={s.label} className="rounded-sm border border-line bg-surface p-4 shadow-card"><StatCompare {...s} /></div>
+			))}
+		</div>
+	);
+}
+```
+
+## Related
+
+- Line chart card
+- Breakdown table
+- Data visualisation colours
+- Usage meter

package/agent/docs-md/static-dashboard.md

@@ -0,0 +1,75 @@
+# Static dashboard
+
+A fixed overview page where the team sees the same items in the same order, most important first, answering the day's questions at a glance.
+
+Kind: pattern · Group: Patterns: data and dashboards
+
+**Problem:** A hiring lead opens the overview to answer a few questions fast: how many applications came in, which listings need attention, what is stuck. If the page is a wall of charts, or each team lays it out differently, the answer takes minutes instead of seconds.
+
+**Solution:** Lay the page out in three bands on a 12-column grid: a top band with page actions and the headline numbers, a middle band of charts and short lists that explain those numbers, and a bottom band for setup help and updates. The order is set by the product team from research and does not change per person.
+
+**Built from:** Page header, Segmented control, Stat card with comparison, Line chart card, Funnel, List table, Status badge, Banner (inline alert), Card, Empty state, Loading skeleton, Error state (failed to load)
+
+## How it works
+
+1. Write down the three to five questions the page must answer, such as "Are applications up or down this week?" and "Which listings expire in the next 7 days?". Every item must answer one of them.
+2. Top band: the page header with page-level actions (period control, Post a listing) and a row of up to four key metrics with comparisons.
+3. Middle band: charts and short lists that give the context behind the key metrics, such as applications per week and candidates waiting over 5 days.
+4. Bottom band: getting started help for new workspaces, and short notes on product updates with a link to read more.
+5. Size items from the 12-column grid: 3 columns for a small item, 6 for medium, 9 for large, 12 for full width. Height follows the content.
+6. Give every item a way out to the full view ("View all 23 listings") so the dashboard stays a summary.
+
+## When to use
+
+- For a team-wide overview where everyone should see the same numbers in the same order, such as the weekly hiring report shared with department heads.
+- When the order of items matters to getting the job done, for example during a hiring campaign where the funnel must stay in view.
+- As the default home of a workspace before you know enough about how people want to rearrange it.
+
+## When not to use
+
+- When people in different roles need different items, such as a recruiter watching their own pipeline and a lead watching cost per hire. Use the configurable dashboard.
+- To browse, filter or edit records. Link to the List table instead of embedding a full table.
+- For a single metric explored in depth. Give it its own report page with a chart and a Breakdown table.
+
+## Guidelines
+
+- Keep to about seven items on one dashboard and about seven series or rows inside any one item. If you need more, split into a parent overview and child dashboards, such as one per department.
+- Decide whether the page is operational (what needs action today) or analytical (trends over months). A mix is fine, but put the operational items first.
+- Page-level controls change every item at once and always have a value, so the period uses a segmented control or dropdown, not a filter pill.
+- Each item loads, fails and shows empty on its own. One failed chart shows an error state in its card; the rest of the page still works.
+- Design the narrow layout too: on a phone the bands stack into one column in priority order, and dense charts are replaced by their headline number and a link to the full chart.
+- Make the dashboard the first link in the side navigation when it is the landing page for returning users.
+
+## Content
+
+- Item titles name what is measured and the scope: "Applications this week", "Listings expiring in 7 days".
+- Every number says what it compares against, using the Comparison over time pattern: "+12% vs previous 7 days".
+- Use "previous" and "following", not "above" and "below": the layout stacks differently on narrow screens.
+- Update notes are one sentence and a link, such as "You can now schedule the weekly hiring report. Set up a schedule".
+
+## Accessibility
+
+- The page has one h1; each item title is an h2 and any sub-heading inside an item is an h3, so screen reader users can jump between items by heading.
+- Focus order follows the visual order, band by band and left to right.
+- Every chart has its data available as a table (the Chart or Table switch) and a text summary of the headline.
+- Status in items is a word in a badge, never colour alone.
+
+## Do
+
+- Do put the item that answers the most frequent question in the first row.
+- Do link each item to the page where the work happens.
+- Do show the time the data was last updated in the page header.
+
+## Don't
+
+- Don't show long lists such as activity logs; show the top five and link to the rest.
+- Don't put complex filtering inside items. Send people to the list or report page for that.
+- Don't mix fixed items and movable items on one page.
+
+## Related
+
+- Configurable dashboard
+- Dashboard items
+- Comparison over time
+- Empty, loading and error states
+- Board and board item

package/agent/docs-md/status-badge.md

@@ -0,0 +1,140 @@
+# Status badge
+
+Shows the system state of a record, such as Live, Draft or Closed early, in one short word or phrase.
+
+Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui
+
+## When to use
+
+- To show workflow or system state of a listing or candidate: Live, Expires in 3 days, Closed early, Draft.
+- In table rows, where a word reads faster than an icon alone.
+- Next to the object it describes, never floating on its own.
+
+## When not to use
+
+- For user-made categories such as Design or Graduate scheme. Use Tag.
+- To start an action or change state. Use a Dropdown menu or Button; the badge is static.
+- For counts on tabs or filters. Use a plain count next to the label.
+
+## Structure
+
+1. Bordered container (20px)
+2. Status text
+3. Dot or icon (optional)
+
+## Guidelines
+
+- 20px high, 4px radius, 12px medium text, 1px border in the tone colour on a tinted background.
+- Five tones with fixed meaning: ok (green), warn (amber), bad (red), mute (grey), accent (primary, for Featured).
+- Match the tone to the meaning, not to how much attention you want.
+- Keep the same tone for the same status everywhere in the product.
+- Do not truncate. If the text is long, rewrite it; badges cannot be focused to reveal the rest.
+
+## Content
+
+- One to three words, sentence case: Expires in 3 days, not EXPIRING SOON.
+- Use plain words people use, not system codes.
+- Prefer a specific state over a vague one: Closed early, not Inactive.
+
+## Accessibility
+
+- The text carries the meaning; colour only reinforces it.
+- Text on the tinted background needs 4.5:1; the border 3:1 is not required because the text identifies it.
+- Badges are not interactive: no tabindex, no tooltip that holds needed information.
+- When a status changes live (for example after an agent run), announce it with a status message.
+
+## Examples
+
+### dot
+
+```tsx
+import { Badge } from "@twoux/ui";
+
+export const meta = {
+	title: "With dot",
+	description: "A leading dot helps scanning down a long column. The word stays.",
+	order: 2,
+};
+
+export default function Example() {
+	return (
+		<div className="flex flex-wrap items-center gap-2">
+			<Badge variant="success" dot>Live</Badge>
+			<Badge variant="warning" dot>Needs you</Badge>
+			<Badge variant="destructive" dot>Failed</Badge>
+		</div>
+	);
+}
+```
+
+### in-table
+
+```tsx
+import { Badge } from "@twoux/ui";
+
+export const meta = {
+	title: "In a table",
+	description: "One badge per row, in its own column, left aligned so the words line up.",
+	order: 3,
+};
+
+const rows = [
+	["Junior Product Designer", "success", "Live", "86"],
+	["Graduate Data Analyst", "warning", "Expires in 3 days", "54"],
+	["Marketing Assistant", "secondary", "Draft", "0"],
+	["Customer Success Associate", "destructive", "Closed early", "19"],
+] as const;
+
+export default function Example() {
+	return (
+		<table className="w-full max-w-xl border-collapse overflow-hidden rounded-sm border border-line-strong bg-surface text-left">
+			<thead>
+				<tr className="h-8 bg-surface-2 text-sm text-ink-2">
+					<th className="px-3 font-medium">Role</th>
+					<th className="px-3 font-medium">Status</th>
+					<th className="px-3 text-right font-medium">Applies</th>
+				</tr>
+			</thead>
+			<tbody>
+				{rows.map(([role, variant, label, applies]) => (
+					<tr key={role} className="h-row border-t border-line">
+						<td className="px-3 font-medium">{role}</td>
+						<td className="px-3"><Badge variant={variant}>{label}</Badge></td>
+						<td className="tabular px-3 text-right">{applies}</td>
+					</tr>
+				))}
+			</tbody>
+		</table>
+	);
+}
+```
+
+### statuses
+
+```tsx
+import { Badge } from "@twoux/ui";
+
+export const meta = {
+	title: "Record status",
+	description: "Always a word. Colour repeats the meaning but never carries it alone.",
+	order: 1,
+};
+
+export default function Example() {
+	return (
+		<div className="flex flex-wrap items-center gap-2">
+			<Badge variant="success">Live</Badge>
+			<Badge variant="warning">Expires in 3 days</Badge>
+			<Badge variant="destructive">Closed early</Badge>
+			<Badge variant="secondary">Draft</Badge>
+			<Badge variant="default">Featured</Badge>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Tag
+- Tooltip
+- Tabs (underline)

package/agent/docs-md/step-card.md

@@ -0,0 +1,75 @@
+# Step card
+
+The proposal turns into a step card while changes apply: each change shows a spinner then a check, with an "N / M" counter, and the table updates row by row.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- Applying approved changes that take more than an instant, so people can see each one land.
+- When the table should update as each step finishes, so the result can be checked in place.
+
+## When not to use
+
+- Scheduled or long agent runs with waiting steps. Use the Agent run timeline (agent-run).
+- Reasoning before an answer. Use Thinking and steps (thinking-steps).
+
+## Structure
+
+1. Header ("Applying 2 changes" and counter)
+2. Step rows (spinner or check, change label)
+3. Footer note ("Working…" then "Applied 2 changes.")
+
+## Guidelines
+
+- Each step has a visible state: pending with spinner, then done with a check. A failed step says why and keeps the others.
+- Show the counter ("1 / 2") so progress reads without counting icons.
+- Finish with a summary and an Undo toast.
+- Keep the step card in the thread as a record of what was done.
+
+## Content
+
+- Use the same label as the proposal row so people recognise each change.
+- Finish in past tense with a count: "Applied 2 changes."
+
+## Accessibility
+
+- Announce the counter and the final summary through a status region (SC 4.1.3); do not announce every spinner.
+- Spinners are aria-hidden and the state is also given in text (SC 1.3.1, 1.4.1).
+- Spinner motion stops when the step ends; runs over five seconds need Stop (SC 2.2.2).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| ⌘Z / Ctrl+Z | Undo the applied changes from the toast |
+
+## Examples
+
+### apply
+
+```tsx
+import { Button, StepCard } from "@twoux/ui";
+import { useEffect, useState } from "react";
+
+export const meta = { title: "Applying, step by step", description: "Each change shows pending, then done. A failed step says why and keeps the others. The counter reads progress without counting icons.", order: 1 };
+
+export default function Example() {
+	const [n, setN] = useState(0);
+	useEffect(() => { if (n < 3) { const t = setTimeout(() => setN((x) => x + 1), 700); return () => clearTimeout(t); } }, [n]);
+	const state = (i: number) => (i >= n ? "pending" : i === 2 ? "failed" : "done") as "pending" | "done" | "failed";
+	return (
+		<div className="grid w-full max-w-md gap-2">
+			<StepCard title="Extending 3 listings" steps={[{ label: "Frontend Engineer closes 21 Dec", state: state(0) }, { label: "Data Analyst closes 12 Jan", state: state(1) }, { label: "QA Engineer", state: state(2), reason: n > 2 ? "Already closed. Reopen it first." : undefined }]} />
+			<Button variant="outline" size="sm" className="justify-self-start" onClick={() => setN(0)}>Replay</Button>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Suggested changes
+- Agent run timeline
+- Toast
+- Plan preview