@twoux/ui 0.0.0-stage → 0.1.0

package/agent/docs-md/answer-actions.md

@@ -0,0 +1,81 @@
+# Answer actions
+
+The row under every answer: origin label on the left, then Copy, Helpful, Not helpful, Regenerate and a More menu. Always visible, never only on hover.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- Under every answer the assistant gives in the side panel or on the assistant page.
+- Under a stacked group of answer parts once, after the last part, not after each one.
+- Under an answer that was stopped, so Regenerate and feedback are still reachable.
+
+## When not to use
+
+- For actions on a generated file, such as Download. Those belong in the file's own card.
+- For feedback about the page or product. Use the product feedback route, not answer feedback.
+- Under approval results, notices or the clarifying question card.
+
+## Structure
+
+1. Origin label: "Assistant · from your workspace data" (see AI origin label)
+2. Copy: copies the answer as plain text with record IDs
+3. Helpful and Not helpful: feedback toggles with submitting and sent states
+4. Regenerate: latest answer only
+5. More (⋯): Save as task, Open as page, Copy link
+6. Not helpful form (optional): a short dismissible form under the answer
+
+## Guidelines
+
+- Show at most four icon buttons; anything else goes in More.
+- Keep the row visible at all times. Hover-only actions are invisible to keyboard and touch users.
+- Feedback has three states: default, sending (spinner in the pressed button) and sent. Once sent, the chosen button stays pressed and the other is disabled with a reason.
+- Not helpful opens an optional form under the answer: reasons as checkboxes (Wrong figures, Missed records, Too long, Other) and a note. It can be closed without sending.
+- Same order everywhere: label, Copy, Helpful, Not helpful, Regenerate, More.
+
+## Content
+
+- Tooltips: "Copy", "Helpful", "Not helpful", "Regenerate answer", "More actions".
+- After feedback: "Feedback sent". Disabled reason on the other button: "You marked this as helpful".
+- Copy confirmation is a short tooltip, "Copied", not a toast.
+
+## Accessibility
+
+- Feedback buttons are toggle buttons with aria-pressed, named "Helpful" and "Not helpful".
+- "Feedback sent" and "Copied" are announced as status messages without moving focus.
+- Disabled buttons stay focusable so their reason can be read.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move through the actions after reading the answer |
+| Enter / Space | Press the focused action |
+| Esc | Close the More menu or the Not helpful form |
+
+## Examples
+
+### actions
+
+```tsx
+import { AnswerActions, AssistantMessage, DropdownMenuItem } from "@twoux/ui";
+
+export const meta = { title: "Under every answer", description: "Copy, Helpful, Not helpful and Regenerate (latest answer only), with the rest under More. Always visible, not on hover. Feedback shows sending, then stays pressed.", order: 1 };
+
+export default function Example() {
+	return (
+		<div className="w-full max-w-lg">
+			<AssistantMessage from="24 listings" actions={<AnswerActions text="2 listings close this week with fewer than 10 applicants." onRegenerate={() => {}} onFeedback={() => new Promise((r) => setTimeout(r, 500))} more={<><DropdownMenuItem>Save as task</DropdownMenuItem><DropdownMenuItem>Open as page</DropdownMenuItem><DropdownMenuItem>Copy link</DropdownMenuItem></>} />}>
+				<p><strong>2 listings</strong> close this week with fewer than 10 applicants.</p>
+			</AssistantMessage>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Regenerating an answer
+- Labelling AI output
+- AI origin label
+- Assistant side panel

package/agent/docs-md/app-shell.md

@@ -0,0 +1,114 @@
+# App shell and sidebar navigation
+
+The frame of every screen: a tinted left sidebar for navigation and an inset white canvas with a top bar for breadcrumb, Ask and search.
+
+Kind: component · Group: Navigation · Status: built, import from @twoux/ui
+
+## When to use
+
+- Every signed-in screen uses the same shell, with navigation in the same place and order.
+- Products with more than a handful of sections, where a vertical list scales better than a top bar.
+
+## When not to use
+
+- Switching views of the same data, such as Live or Drafts. Use tabs in the page header.
+- Moving between records in a list. Use J/K with the Side panel.
+- Showing location deeper than two levels. Use the Breadcrumb.
+
+## Structure
+
+1. Sidebar: workspace switcher
+2. Sidebar: personal items (Inbox with count, My candidates, Assistant)
+3. Sidebar: group headings with items (Hiring: Listings, Pipeline, Reports; Workspace: Settings, Members, Billing)
+4. Sidebar footer: setup checklist ("Get set up 3 / 5")
+5. Canvas top bar: breadcrumb, Ask ⌘J, Search or run a command ⌘K
+6. Canvas: page header and content; side panel docks on the right
+7. Optional rail: 48px of icons with names in tooltips and a Collapse sidebar button at the foot
+
+## Guidelines
+
+- Keep the sidebar visible on desktop with text labels on every item. Collapse it to a rail of icons only on workspaces where the content needs the width (trading, editors), with each name in a tooltip, the Collapse sidebar button and ⌘B, and the choice saved per person.
+- Two levels at most: group headings and items. Deeper structure becomes tabs on the page.
+- Mark the current item with aria-current="page" and a filled background, not colour alone.
+- Most used items first, settings last.
+- Below 860px the sidebar hides; the top bar gains an inbox button with the same count, so nothing that needs the person disappears.
+- The top bar holds global tools only (Ask, search); page actions live in the page header.
+- Nav items are at least 24px tall with full-width hit areas, to meet the target size minimum.
+- Use frame="flush" for workspaces whose regions sit edge to edge, divided by hairlines instead of gaps and cards; keep the inset canvas everywhere else.
+
+## Content
+
+- Item labels are short nouns that match the page title they open ("Listings" opens "Listings").
+- Group headings are short and never include the word "navigation".
+- Counts are numbers only and show only when above zero.
+
+## Accessibility
+
+- The sidebar is a nav landmark with a unique label ("Main"); the canvas is main; the side panel is complementary (2.4.1).
+- Navigation order and labels are the same on every page (3.2.3).
+- Search and the command palette provide a second way to reach pages (2.4.5).
+- Each page has a title that names the page and the product (2.4.2).
+- Focus is always visible on nav items, including inside the tinted sidebar (2.4.7).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| G L / G P / G I | Go to Listings, Pipeline or Inbox |
+| ⌘K | Search or run a command |
+| ⌘J | Open the Assistant |
+| Tab | Move through sidebar items in order |
+| ⌘B / Ctrl+B | Collapse or expand the sidebar, when the app offers the rail |
+
+## Examples
+
+### workspace
+
+```tsx
+import type React from "react";
+import { AppShell, Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, Button, PageHeader, SidebarItem, SidebarSection } from "@twoux/ui";
+import { BarChart3, Briefcase, Inbox, Plus, Settings, MessageSquare, Users } from "lucide-react";
+import { useState } from "react";
+
+export const meta = { title: "Hiring workspace", description: "Tinted sidebar with a text label on every item, two levels at most, and the current page marked by fill and aria-current. Below 860px the sidebar moves behind the menu button.", order: 1 };
+
+export default function Example() {
+	const [page, setPage] = useState("Listings");
+	const item = (label: string, icon: React.ReactNode, count?: number) => <SidebarItem key={label} label={label} icon={icon} count={count} current={page === label} onClick={() => setPage(label)} />;
+	return (
+		<div className="h-120 w-full overflow-hidden rounded-sm border border-line">
+			<AppShell
+				sidebar={
+					<>
+						<div className="px-2 pt-1 text-base font-semibold text-ink">TwoUX Hiring</div>
+						<SidebarSection>{[item("Inbox", <Inbox />, 4), item("Assistant", <MessageSquare />)]}</SidebarSection>
+						<SidebarSection title="Hiring">{[item("Listings", <Briefcase />), item("Candidates", <Users />), item("Reports", <BarChart3 />)]}</SidebarSection>
+						<SidebarSection title="Workspace">{[item("Settings", <Settings />)]}</SidebarSection>
+					</>
+				}
+				topBar={
+					<Breadcrumb>
+						<BreadcrumbList>
+							<BreadcrumbItem><BreadcrumbLink href="#hiring">Hiring</BreadcrumbLink></BreadcrumbItem>
+							<BreadcrumbSeparator />
+							<BreadcrumbItem><BreadcrumbPage>{page}</BreadcrumbPage></BreadcrumbItem>
+						</BreadcrumbList>
+					</Breadcrumb>
+				}
+			>
+				<PageHeader title={page} description="24 listings across 6 teams" actions={<><Button variant="outline">Export</Button><Button shortcut="C"><Plus />New listing</Button></>} />
+			</AppShell>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Breadcrumb
+- Page header
+- Inbox (triage)
+- Command palette (⌘K)
+- Side panel (drawer)
+- Setup checklist
+- Usage meter

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

@@ -0,0 +1,89 @@
+# Generated file card
+
+A compact card under an answer for one thing the assistant made: name, type and size, origin label, and up to two actions with the rest in a More menu.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- For each draft or file the assistant produced in an answer.
+- In agent run results when a step produced a file.
+- For a short command or snippet a person will copy into another tool.
+
+## When not to use
+
+- For records that already exist. Cite them by ID instead.
+- For files people attached. Those are context chips in the composer.
+- For a figure or short table that answers the question. Keep it in the answer text.
+
+## Structure
+
+1. Icon for the type (document, table, chart, code)
+2. Title: file name or what it is
+3. Metadata: type, size in KB or MB, rows or words
+4. Origin label with sources on hover
+5. Actions: up to two buttons (Open, Download, Copy, Suggest for record) and More (⋯)
+6. Inline preview (optional): first lines of a snippet, or the chart image
+
+## Guidelines
+
+- One card per output, stacked under the answer in the order they were made.
+- Code and commands preview in the Code block style with Copy; long previews cut at about eight lines with Open for the rest.
+- While a file is being made, the card shows a skeleton line and "Writing job description"; text around it may stream, the card does not.
+- If making the file failed, the card says why and offers Try again; other cards in the answer stay.
+
+## Content
+
+- Sizes in KB, MB or GB with one decimal at most: "1.2 MB".
+- Loading text names the thing: "Writing job description", "Loading 38 listings".
+- Title is the file name or a plain description, never "Artifact" or "Output 1".
+
+## Accessibility
+
+- The card is a group with an accessible name from its title.
+- Action names include the file: "Open job description".
+- The More menu follows the menu button pattern.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Reach the card's actions in order |
+| Enter | Run the focused action |
+| ↓ / ↑ | Move through the More menu |
+| Esc | Close the More menu |
+
+## Examples
+
+### draft
+
+```tsx
+import { ArtifactCard, Button, toast } from "@twoux/ui";
+import { useEffect, useState } from "react";
+
+export const meta = { title: "A draft the assistant made", description: "One card per output, with type and size, the origin label and two actions. While it is being written, the card says so; the draft reaches the record only through Suggest for record.", order: 1 };
+
+export default function Example() {
+	const [writing, setWriting] = useState(true);
+	useEffect(() => { const t = setTimeout(() => setWriting(false), 1400); return () => clearTimeout(t); }, []);
+	return (
+		<div className="w-full max-w-lg">
+			<ArtifactCard
+				title="Job description"
+				meta="Document · 312 words"
+				from="LST-1044 and the hiring handbook"
+				writing={writing}
+				actions={<><Button variant="outline" size="xs" onClick={() => toast("Proposed for LST-1044")}>Suggest for record</Button><Button variant="ghost" size="xs">Open</Button></>}
+				preview={<p>Customer Success Lead, Bristol (hybrid). £45,000 to £52,000. You'll look after 40 hiring teams, help them get value from TwoUX in their first 90 days…</p>}
+			/>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Generated drafts and files
+- Code block
+- AI origin label
+- Answer actions

package/agent/docs-md/ask-on-screen.md

@@ -0,0 +1,72 @@
+# Ask about what's on screen
+
+⌘J or Ask opens the assistant beside the data with the current selection and filters as removable context chips, so the scope of every answer is visible.
+
+Kind: pattern · Group: Patterns: AI
+
+**Problem:** People ask "why are these doing badly?" about the rows in front of them. A floating chat with no context makes them retype what they can see, and answers silently cover the wrong set of records.
+
+**Solution:** The assistant opens in the same side panel as record detail. Selection and active filters become context chips automatically; removing a chip narrows the scope. Starters are based on what is on screen. Answers lead with the figure, then a table, then the reason.
+
+**Built from:** Assistant side panel, Message composer, Follow-ups and starters, Team instructions and files, Side panel (drawer), Bulk action bar
+
+## How it works
+
+1. Open with ⌘J anywhere, or Ask in the bulk bar. No floating chat bubble on every page.
+2. The composer shows context chips for what the assistant can see: "2 listings", "Status is Live, Expiring". Remove a chip to narrow it; @ adds a record.
+3. The empty state offers two or three tasks based on the context, as chips, then the composer.
+4. The answer leads with the figure, then a table, then the reason, with record IDs as citations.
+5. Follow-ups appear under the answer as muted rows; any table in the answer can open as a filtered view.
+
+## When to use
+
+- For questions about records the person can see or has selected: compare, explain, summarise.
+- When the answer will be checked against the list beside it.
+
+## When not to use
+
+- To change records. The assistant proposes; see Propose then apply.
+- For filtering a list by known fields. Filter pills are faster than typing.
+
+## Guidelines
+
+- Scope is always visible and editable; the assistant never reads more than the chips say unless the person widens it.
+- If the answer needs records outside the chips, ask before widening (see Clarifying before acting).
+- A caveat sits by the composer and is specific: "Uses your workspace data only. Check figures before you act on them."
+- Every message aligns to the same side in the side panel and on the page; who wrote it is shown by name ("You", "Assistant"), not by alignment.
+- The composer is pinned to the bottom and only the thread scrolls. While someone reads or copies older messages, new output doesn't scroll them away; show "New answer ↓" instead.
+- The Ask entry point is a secondary button. It never becomes a second primary button on the page and carries no AI styling.
+- After context is added, the assistant says what it will use in one line: "Using 2 listings and team file Salary bands 2026." People can correct it before anything runs.
+- Connecting an outside tool happens in the thread as a short step card, one step at a time, collapsing to "Connected as Leeds hiring team". People don't leave for settings.
+- Errors keep the question: say what failed (no access, connection lost, service error), that nothing changed, and offer Try again with the question still in the composer.
+- A refusal says plainly what the assistant won't do and what it can do instead: "I can't rank candidates for rejection. I can summarise each application against the role's criteria."
+
+## Content
+
+- Call it Assistant. Say what it did ("Read 2 listings and 3,000 views"), not that it is AI. No "magic" or "smart".
+- Starters are broad, runnable tasks, not niche examples.
+
+## Accessibility
+
+- Streamed answers are announced once complete, not word by word.
+- ⌘J returns focus to where it was when the panel closes.
+- The thread is a region named "Assistant conversation"; each finished answer is announced once through a hidden live region.
+
+## Do
+
+- Do turn selection and filters into chips automatically.
+- Do lead answers with the number.
+
+## Don't
+
+- Don't add a floating chat bubble to every page.
+- Don't open with a blank "How can I help?".
+
+## Related
+
+- Propose, then apply
+- Clarifying before acting
+- Citing sources
+- Keyboard-first navigation
+- Assistant side panel
+- Message composer

package/agent/docs-md/assistant-page.md

@@ -0,0 +1,100 @@
+# Assistant page
+
+The same conversation opened as a full page, with Answer and Records tabs and a Sources panel listing every record the answer used.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- Answers that rely on many records and need checking. The Sources panel lists every record so people can verify without hunting.
+- Research-style questions across the whole workspace, such as Thorough answers that also read candidates and past listings.
+- When the person wants to keep the answer as the main task, not as help beside a table.
+
+## When not to use
+
+- A quick question about the rows on screen. Use the Assistant side panel (assistant-panel) so the table stays visible.
+- Watching an agent work through steps over time. Use the Agent run timeline (agent-run).
+- Browsing past conversations. Use Previous conversations (conversation-history).
+
+## Structure
+
+1. Top bar (Answer and Records tabs, Share, Open in side panel)
+2. Centred reading column (thread)
+3. Records tab (the rows the answer used, as a table)
+4. Sources panel (every cited record)
+5. Message box
+
+## Guidelines
+
+- Expand opens the same conversation; "Open in side panel" goes back without losing the thread, context or scroll position.
+- Use a centred reading column and align messages user to the end, assistant to the start, on full, dedicated surfaces.
+- The Sources panel lists every record the answer used. Selecting a citation highlights its source in the panel.
+- The Records tab shows the rows behind the answer as a table that can open as a filtered view, so the claim and the data sit one click apart.
+- Say when there are no sources rather than showing filler: empty states keep trust.
+- Long task conversations get an outline: a list of key moments (question asked, values given, changes applied) that jumps to each message.
+- Long drafts open here beside the conversation rather than in a second panel.
+
+## Content
+
+- Tabs are nouns: Answer and Records (with a count). Avoid branded names for modes or tabs.
+- Source rows show the record ID, title and what was used (for example "Views and applies, last 30 days").
+- Keep the same caveat and origin label as in the panel so the two surfaces read as one product.
+
+## Accessibility
+
+- Answer and Records use the tabs pattern: role="tablist", role="tab" with aria-selected and aria-controls, arrow keys move between tabs.
+- The Sources panel is an aside labelled "Sources" so it is reachable as a landmark.
+- Highlighting a source after a citation is selected must not rely on colour alone; add an outline or marker (SC 1.4.1).
+- New answers are announced through the thread's log region without moving focus (SC 4.1.3).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Left / Right arrow | Move between Answer and Records tabs |
+| Tab | Move from the tabs into the panel content |
+| ⌘J / Ctrl+J | Focus the message box |
+| Enter | Send |
+| Esc | Close an open menu |
+
+## Examples
+
+### page
+
+```tsx
+import { AssistantMessage, AssistantPage, Citation, MessageComposer, SourcesList, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, UserMessage } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "The conversation as a full page", description: "A centred reading column with Answer and Records tabs, and a Sources panel listing every record the answer used. Selecting a citation highlights its source.", order: 1 };
+
+const SOURCES = [{ id: "LST-1041", title: "Frontend Engineer", detail: "Manchester · 6 applicants" }, { id: "LST-1044", title: "Customer Success Lead", detail: "Bristol · 3 applicants" }];
+
+export default function Example() {
+	const [active, setActive] = useState<string>();
+	return (
+		<div className="h-120 w-full overflow-auto rounded-sm border border-line bg-surface">
+			<AssistantPage
+				thread={
+					<>
+						<UserMessage>Which listings close this week with fewer than 10 applicants?</UserMessage>
+						<AssistantMessage from="24 listings">
+							<p><strong>2 listings</strong>: Frontend Engineer <Citation id="LST-1041" active={active === "LST-1041"} onOpen={setActive} /> and Customer Success Lead <Citation id="LST-1044" active={active === "LST-1044"} onOpen={setActive} />.</p>
+						</AssistantMessage>
+					</>
+				}
+				records={<Table aria-label="Records used"><TableHeader><TableRow><TableHead>Listing</TableHead><TableHead className="text-right">Applicants</TableHead></TableRow></TableHeader><TableBody>{SOURCES.map((s) => <TableRow key={s.id}><TableCell>{s.title}</TableCell><TableCell className="tabular text-right">{s.detail?.split("· ")[1]}</TableCell></TableRow>)}</TableBody></Table>}
+				sources={<SourcesList sources={SOURCES} active={active} onSelect={setActive} />}
+				composer={<MessageComposer noun={{ one: "listing", many: "listings" }} onSend={() => {}} placeholder="Ask a follow-up" />}
+			/>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Assistant side panel
+- Citations and sources
+- Message composer
+- Follow-ups and starters
+- Tabs (underline)

package/agent/docs-md/assistant-panel.md

@@ -0,0 +1,142 @@
+# Assistant side panel
+
+A side panel, opened with ⌘J, where people ask about the records on screen and get answers grounded in the current selection and filters.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- Quick questions about the listings or candidates on screen, where the answer needs the data beside it. ⌘J opens the panel with the current selection and filters already attached.
+- When people need to invoke help without leaving the table they are working through. HAX G7 asks for efficient invocation and G8 for efficient dismissal, so the panel opens and closes with one shortcut.
+- When an answer may lead to a change. The panel can hold a proposal next to the rows it affects, so the person can compare before applying.
+
+## When not to use
+
+- Long research answers that need room for sources and a records list. Use the Assistant page (assistant-page) instead, which keeps the same conversation.
+- Repeated tasks with the same shape every week. Use the Task builder (task-builder) so the inputs are slots, not free text.
+- Filling one value per row across a table. Use the AI column (ai-column), which writes into a generated column and cites each row.
+- Do not add a floating chat bubble to every page. The panel opens from ⌘J or Ask in the bulk bar, where the context is.
+
+## Structure
+
+1. Panel bar (Assistant, conversation title, Open as a full page, Previous conversations, Share, New, Close)
+2. Thread (questions, thinking row, answers)
+3. Clarifying question card (docked above the message box when needed)
+4. Message box with context chips
+5. Caveat line
+
+## Guidelines
+
+- Open in the same side panel as row details, in push mode by default, so the table stays readable. Opening the assistant closes the row detail panel and the other way round.
+- Turn the selection and active filters into context chips automatically. Removing a chip narrows what the assistant reads.
+- Lead each answer with the figure, then a small table, then the reason. Every claim about a record carries its record ID as a citation.
+- Changes never apply from the thread. They arrive as Suggested changes with checkboxes and one Apply button, and nothing changes until the person applies.
+- While a response is running, the send button becomes Stop in the same place. Stopping keeps what was written and says it is incomplete.
+- Keep the message box pinned and let only the thread scroll. Do not jump the thread to the bottom while someone is reading an older message.
+- Show the caveat under the message box at all times: what data it uses and what to check.
+
+## Content
+
+- Call it Assistant. Do not use "AI-powered", "smart" or "magic". Say what it read and what it did.
+- Empty state: say what it will use ("Ask about 2 listings. Uses what you have selected and filtered. Nothing changes until you apply it.").
+- Caveat copy is specific: "Uses your workspace data only. Check figures before you act on them."
+- Answers open with the answer. No greeting, no "Great question", no disclaimer about being an AI before the content.
+- Name the conversation from the first question and show it in the panel bar, so it can be found later.
+
+## Accessibility
+
+- Render the panel as an aside with aria-label="Assistant" (complementary landmark). Label it because the row details panel is a second complementary landmark.
+- The thread is a log (role="log", implicit aria-live polite) with an accessible name, so new answers are announced without moving focus (SC 4.1.3).
+- Do not announce every streamed token. Announce the thinking step titles and the finished answer; Stop satisfies SC 2.2.2 for content that auto-updates in parallel with the table.
+- When the panel opens, focus moves to the message box; Esc closes the innermost open layer first (menu, history, then panel) and focus returns to the trigger, as the dialog pattern does (SC 2.4.3).
+- The send button changes its accessible name from "Send (Enter)" to "Stop" while running, which the button pattern allows when the label itself changes.
+- The panel must not cover the focused row in push mode (SC 2.4.11).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| ⌘J / Ctrl+J | Open or close the assistant with the current selection as context |
+| Enter | Send the message |
+| Shift+Enter | New line |
+| Esc | Close the open menu, then history, then the panel |
+| ⌘↵ | Apply the suggested changes in focus |
+
+## Examples
+
+### flow
+
+```tsx
+import { AnswerActions, AssistantMessage, AssistantPanel, Button, Citation, FollowUps, MessageComposer, StepCard, SuggestedChanges, Table, TableBody, TableCell, TableRow, ThinkingSteps, UserMessage, toast } from "@twoux/ui";
+import { useEffect, useState } from "react";
+
+export const meta = { title: "Ask, propose, apply", description: "The assistant reads the selection, thinks in visible steps, answers with the figure first and record IDs, and proposes changes. Nothing changes until you apply; the step card shows progress and Undo follows.", order: 1 };
+
+type Stage = "idle" | "thinking" | "answered" | "applying" | "applied";
+
+export default function Example() {
+	const [open, setOpen] = useState(true);
+	const [stage, setStage] = useState<Stage>("idle");
+	const [t, setT] = useState(0);
+	const [steps, setSteps] = useState<("pending" | "done")[]>(["pending", "pending"]);
+	useEffect(() => {
+		if (stage !== "thinking") return;
+		const i = setInterval(() => setT((x) => x + 0.1), 100);
+		const d = setTimeout(() => setStage("answered"), 1800);
+		return () => { clearInterval(i); clearTimeout(d); };
+	}, [stage]);
+	useEffect(() => {
+		if (stage !== "applying") return;
+		const a = setTimeout(() => setSteps(["done", "pending"]), 600);
+		const b = setTimeout(() => { setSteps(["done", "done"]); setStage("applied"); toast.success("Extended 2 listings by 30 days", { action: { label: "Undo", onClick: () => setStage("answered") } }); }, 1200);
+		return () => { clearTimeout(a); clearTimeout(b); };
+	}, [stage]);
+	return (
+		<div className="flex h-140 w-full overflow-hidden rounded-sm border border-line bg-surface">
+			<div className="grid min-w-0 flex-1 content-start gap-2 p-4">
+				<span className="text-base text-ink-2">2 listings selected</span>
+				{!open && <Button variant="outline" size="sm" shortcut="⌘J" className="justify-self-start" onClick={() => setOpen(true)}>Ask the assistant</Button>}
+			</div>
+			<AssistantPanel caveat="Reads listings and applications, not emails. Check closing dates before you extend a listing."
+				open={open}
+				onOpenChange={setOpen}
+				title="Why are these closing with few applicants?"
+				onOpenPage={() => {}}
+				composer={<MessageComposer noun={{ one: "listing", many: "listings" }} chips={[{ id: "sel", label: "2 selected listings" }, { id: "f", label: "Status is Closing soon" }]} busy={stage === "thinking"} onStop={() => setStage("idle")} onSend={() => { setT(0); setStage("thinking"); }} />}
+			>
+				{stage === "idle" ? (
+					<p className="text-base text-ink-2">Ask about the 2 selected listings, for example “Why are these closing with few applicants?”</p>
+				) : (
+					<>
+						<UserMessage>Why are these closing with few applicants?</UserMessage>
+						<ThinkingSteps done={stage !== "thinking"} seconds={stage === "thinking" ? t : 1.8} steps={[{ title: "Reading 2 listings", detail: "LST-1041, LST-1044" }, { title: "Comparing with 22 similar listings", detail: "Same teams, last 90 days" }, { title: "Checking salary and posting dates" }]} />
+						{stage !== "thinking" && (
+							<AssistantMessage
+								from="2 listings and 22 similar ones"
+								actions={<AnswerActions text="Both close in under 5 days with 9 applicants between them." onRegenerate={() => { setT(0); setStage("thinking"); }} onFeedback={() => new Promise((r) => setTimeout(r, 400))} />}
+								followUps={<FollowUps items={["Which job boards are they on?", "Draft a shorter job description for LST-1044"]} onPick={() => {}} />}
+							>
+								<p><strong>9 applicants</strong> between them, against a median of 38 for similar listings.</p>
+								<Table aria-label="Applicants"><TableBody><TableRow><TableCell>Frontend Engineer <Citation id="LST-1041" /></TableCell><TableCell className="tabular text-right">6</TableCell></TableRow><TableRow><TableCell>Customer Success Lead <Citation id="LST-1044" /></TableCell><TableCell className="tabular text-right">3</TableCell></TableRow></TableBody></Table>
+								<p>Both were posted 9 days ago and close within 5 days. Similar listings stay open 30 days.</p>
+							</AssistantMessage>
+						)}
+						{stage === "answered" && <SuggestedChanges changes={[{ id: "a", label: "Extend Frontend Engineer by 30 days", detail: "LST-1041", before: "Closes 21 Nov", after: "Closes 21 Dec" }, { id: "b", label: "Extend Customer Success Lead by 30 days", detail: "LST-1044", before: "Closes 23 Nov", after: "Closes 23 Dec" }]} onApply={() => { setSteps(["pending", "pending"]); setStage("applying"); }} onDismiss={() => setStage("idle")} />}
+						{(stage === "applying" || stage === "applied") && <StepCard title="Extending 2 listings" steps={[{ label: "Frontend Engineer closes 21 Dec", state: steps[0] }, { label: "Customer Success Lead closes 23 Dec", state: steps[1] }]} />}
+					</>
+				)}
+			</AssistantPanel>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Assistant page
+- Message composer
+- Thinking and steps
+- Suggested changes
+- Citations and sources
+- Previous conversations
+- Side panel (drawer)