@twoux/ui 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,103 @@
+# Filter panel
+
+A side panel of collapsible filter sections for searches with many fields, with live counts per option and a main action that says how many rows it will act on.
+
+Kind: component · Group: Data · Status: built, import from @twoux/ui
+
+## When to use
+
+- Search across many dimensions at once, such as candidates by location, team, experience and salary. That is faceted navigation.
+- People set filters across several categories, which work best placed vertically on the left.
+- People need counts per option to avoid zero-result combinations.
+
+## When not to use
+
+- For two or three filters on a table. Use the TwoUX Filter bar so filters stay inline.
+- Inside a dropdown or menu when there are several categories; multiple categories should never go in a menu.
+- For saved combinations people reuse. Use TwoUX Saved views.
+
+## Structure
+
+1. Header (Filters, count of active filters, Clear all)
+2. Collapsible sections with set-value count
+3. Options with result counts
+4. Results table
+5. Footer ("Showing 5 of 412 candidates", Save search, main action with count)
+
+## Guidelines
+
+- Sections collapse, and each closed section shows how many values are set.
+- Show the most used sections open and the rest collapsed.
+- Each option shows how many results it matches.
+- The result count updates live and the main action states its scope, "Add 412 to pipeline".
+- Offer Clear all for the panel and a clear per section.
+
+## Content
+
+- Section titles are the field names people use, not database names.
+- Write "Any team" or "Any time" when a section has no value, so the default is explicit.
+- Keep counts in the same place on every option so they scan down the column.
+
+## Accessibility
+
+- APG disclosure pattern: each section header is a button with aria-expanded; Enter or Space toggles it.
+- 4.1.3 Status Messages: the live result count is announced as a full phrase, "412 candidates".
+- 2.1.1 Keyboard: every section, option and Clear all can be reached and used from the keyboard.
+- 1.3.1 Info and Relationships: options are grouped under their section with a group label.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab / ⇧Tab | Move between sections and controls |
+| Enter / Space (section) | Expand or collapse the section |
+| Space (option) | Tick or untick an option |
+
+## Examples
+
+### candidates
+
+```tsx
+import { Button, FilterPanel, type FilterSection, Table, TableBody, TableCell, TableRow, toast } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Search candidates by many fields", description: "Sections collapse and show how many values are set. Each option shows its count. The footer says what the main action will affect.", order: 1 };
+
+const PEOPLE = [
+	{ name: "Amara Okafor", stage: "Screen", source: "Referral", location: "Leeds" },
+	{ name: "Tom Becker", stage: "Applied", source: "Job board", location: "Manchester" },
+	{ name: "Priya Shah", stage: "Interview", source: "Careers page", location: "London" },
+	{ name: "Liam Walsh", stage: "Applied", source: "Job board", location: "Leeds" },
+	{ name: "Sofia Romano", stage: "Offer", source: "Agency", location: "Remote (UK)" },
+	{ name: "Hana Kim", stage: "Screen", source: "Job board", location: "Glasgow" },
+];
+type K = "stage" | "source" | "location";
+
+export default function Example() {
+	const [value, setValue] = useState<Record<string, string[]>>({ stage: ["Applied", "Screen"] });
+	const match = (p: (typeof PEOPLE)[number], skip?: K) => (Object.entries(value) as [K, string[]][]).every(([k, v]) => k === skip || !v.length || v.includes(p[k]));
+	const rows = PEOPLE.filter((p) => match(p));
+	const section = (id: K, title: string, open?: boolean): FilterSection => ({ id, title, defaultOpen: open, options: [...new Set(PEOPLE.map((p) => p[id]))].sort().map((v) => ({ value: v, label: v, count: PEOPLE.filter((p) => match(p, id) && p[id] === v).length })) });
+	return (
+		<div className="grid h-96 w-full grid-cols-[240px_1fr] overflow-hidden rounded-sm border border-line bg-surface max-md:grid-cols-1">
+			<FilterPanel className="border-r border-line" value={value} onChange={setValue} sections={[section("stage", "Stage", true), section("source", "Source", true), section("location", "Location")]} />
+			<div className="flex min-h-0 flex-col">
+				<div className="min-h-0 flex-1 overflow-auto">
+					<Table aria-label="Candidates"><TableBody>{rows.map((p) => <TableRow key={p.name}><TableCell className="font-medium text-ink">{p.name}</TableCell><TableCell className="text-ink-2">{p.stage}</TableCell><TableCell className="text-ink-2">{p.location}</TableCell></TableRow>)}</TableBody></Table>
+				</div>
+				<div className="flex items-center justify-between gap-2 border-t border-line px-3 py-2">
+					<span className="tabular text-sm text-ink-2" aria-live="polite">Showing {rows.length} of {PEOPLE.length} candidates</span>
+					<Button size="sm" disabled={!rows.length} onClick={() => toast.success(`Added ${rows.length} to the pipeline`)}>Add {rows.length} to pipeline</Button>
+				</div>
+			</div>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Filter pills and filter bar
+- Saved views
+- List table
+- Bulk action bar

package/agent/docs-md/filtering-search.md

@@ -0,0 +1,79 @@
+# Filtering and search
+
+Narrow a list to the rows that matter with filter pills that apply as you tick, show counts, and live in the URL.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** Hiring teams work through hundreds of listings and candidates and need to narrow them quickly. If every screen filters differently, people relearn the controls each time and links to a filtered list break.
+
+**Solution:** Use the filter bar (pills) for list pages and the filter panel only for search across many fields. List values apply on tick with match counts, typed values apply on Enter, and the whole query is stored in the URL.
+
+**Built from:** Filter pills and filter bar, Filter panel, List table, Data grid, Pagination and counts, Empty state, Saved views
+
+## How it works
+
+1. Show one or two of the most used fields as dashed pills next to Filter (F). Everything else sits behind Filter in a type-ahead list grouped into most used and all fields.
+2. Opening a pill shows its values with the number of rows each one matches. Ticking a list value applies it at once; numbers and dates apply on Enter.
+3. An applied filter becomes a solid pill that reads as a sentence: field, operator, value, for example "Status is any of Live, Expiring". Its remove button sits on the left.
+4. Clear and the result count sit straight after the pills, so the person sees what is applied and how many rows match without opening anything.
+5. Every change to a filter updates the URL, so reload, back and a shared link all reproduce the same list.
+6. If nothing matches, the table is replaced by a zero results state with Clear filters as the action.
+
+## When to use
+
+- On any list page with more than one screen of rows: listings, candidates, pipeline, inbox.
+- When people mostly narrow by two or three known fields such as status, location or team.
+- Use the filter panel instead of pills when there are many fields to filter by, as in candidate search, and the panel can stay open beside the results.
+
+## When not to use
+
+- To find one known record by name or ID. Use search in the command palette (⌘K) or the view's search (/) instead.
+- For view settings that always have a value, such as a chart's date range or Daily vs Weekly. Pills are removable, so these use a rectangle (segmented control or dropdown) instead.
+- When several tables share one page. Filters in the URL become ambiguous, so filter each table locally and do not persist.
+
+## Guidelines
+
+- Filters act on the whole collection, not just the rows loaded on screen. The count says so: "Showing 5 of 412 candidates".
+- Apply on tick because TwoUX's queries return fast; filter interactively when results come back almost instantly and in a batch when they are slow.
+- If a query will take more than about a second, dim the results and show a progress indicator rather than redrawing after every tick.
+- Show match counts on every list option so people avoid combinations that return nothing.
+- Never put a filter row inside each column header. The pill bar keeps the whole query in one visible, shareable place.
+- Validate filter values read from the URL and fall back to defaults when they are invalid. Never put personal data in the URL.
+- Offer a plain search box alone when people know the exact name, such as a candidate's surname. Add pills when they choose among known values, such as stage or location.
+- Show and/or wording only once two or more filters are applied; one filter reads as a plain sentence.
+- Returning to a list by Back, the breadcrumb or the sidebar restores the filters the person left with.
+- When a page has two filterable lists, only the main one writes its filters to the URL; the other keeps its filters on screen only.
+
+## Content
+
+- Pill text follows field, operator, value in sentence case: "Posted is in the last 30 days".
+- Zero results heading: "No listings match these filters", then one sentence suggesting the likeliest fix, then a Clear filters button.
+- Counts use the noun of the list: "14 listings", not "14 results".
+
+## Accessibility
+
+- Announce the new result count in a polite live region after each change, without moving focus.
+- Each pill's remove button is its own Tab stop, named after its filter: "Remove Status filter".
+- The value list is a combobox with a listbox: arrow keys move, Space ticks, Enter applies a typed value, Esc closes and returns focus to the pill.
+- F to open Filter is a single-key shortcut, so it can be turned off in the shortcut sheet.
+
+## Do
+
+- Do keep the active query visible as pills at all times.
+- Do show how many rows each value matches.
+- Do write filters to the URL on every change.
+
+## Don't
+
+- Don't hide applied filters behind a single "3 filters" badge on desktop.
+- Don't add an Apply button to a fast list filter; it adds a step for nothing.
+- Don't use the empty state illustration and copy for a failed load. That is an error state.
+
+## Related
+
+- Saved views
+- Selection and bulk actions
+- Empty, loading and error states
+- Keyboard-first navigation
+- Filter pills and filter bar
+- Filter panel

package/agent/docs-md/follow-ups-starters.md

@@ -0,0 +1,79 @@
+# Follow-ups and starters
+
+Follow-ups continue an answer as muted rows under a "Follow-ups" label; starters appear only in the empty state as suggested tasks based on what is on screen.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- In the empty state, to show two or three tasks based on the selection, instead of a blank "How can I help?".
+- After an answer, to offer one or two ways to go deeper and one to widen.
+- To prompt checking, such as "Show who viewed these but didn't apply", not only moving on.
+
+## When not to use
+
+- Asking for missing details. Use the Clarifying question card (clarifying-question).
+- Reusable workflows. Use the Templates gallery (templates-gallery) or saved tasks via / (message-composer).
+- Inside an answer's body. Follow-ups sit after the answer actions, never inside the answer.
+
+## Structure
+
+1. Starters: "Try asking" label, bulb icon, two or three chips, Hide
+2. Follow-ups: "Follow-ups" label, rows with a ↳ icon, muted text, full width
+
+## Guidelines
+
+- Starters are based on what is selected ("Why are these 2 doing badly?") or, with nothing selected, on common tasks.
+- Show three or fewer. Too many options cause scanning fatigue.
+- Anchor follow-ups in the last answer and keep them visually apart from it.
+- Selecting a follow-up sends it; selecting a starter that needs editing fills the box instead.
+- Starters can be hidden. Do not show them everywhere.
+- Starters fill the composer for editing and show an edit icon; slots in them are dashed until filled. Follow-ups send at once.
+- A prompt has no state: picking it inserts or sends once, and it doesn't stay selected.
+- Follow-ups that narrow an answer offer up to five options, most likely first, each under 72 characters.
+
+## Content
+
+- Write them as the person would ask, specific to the data: "Which of these close this week?"
+- Sentence case, no exclamation marks, no trailing arrow.
+- Include at least one prompt that helps check the answer, not only extend it.
+
+## Accessibility
+
+- Each follow-up and starter is a button with its full text as the name (SC 4.1.2).
+- Group them under a visible label ("Follow-ups", "Try asking") that is programmatically associated (SC 1.3.1).
+- Rows are full width and at least 24 by 24 px targets (SC 2.5.8).
+- Starters and follow-ups are buttons whose names say what happens: "Insert: Which listings close this week?" or "Ask: Compare with last month".
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move to the next suggestion |
+| Enter / Space | Send the follow-up, or fill the box with the starter |
+
+## Examples
+
+### suggestions
+
+```tsx
+import { FollowUps, Starters, toast } from "@twoux/ui";
+
+export const meta = { title: "Starters and follow-ups", description: "Starters come from what is selected; follow-ups continue the last answer, muted and apart from it. Three at most.", order: 1 };
+
+export default function Example() {
+	return (
+		<div className="grid w-full max-w-lg gap-6">
+			<Starters items={["Why are these 2 doing badly?", "Compare applicants with last quarter", "Draft a shorter description"]} onPick={(q) => toast(q)} onHide={() => {}} />
+			<FollowUps items={["Which job boards are they on?", "Show the same for Design", "Extend both by 30 days"]} onPick={(q) => toast(q)} />
+		</div>
+	);
+}
+```
+
+## Related
+
+- Assistant side panel
+- Message composer
+- Templates gallery
+- Clarifying question card

package/agent/docs-md/form-validation.md

@@ -0,0 +1,95 @@
+# Form validation
+
+Tells people which fields need fixing and how, at the field and in a summary at the top on submit.
+
+Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui
+
+## When to use
+
+- On any form where a value can be wrong or missing: a new listing, a salary, a closing date.
+- Field errors as soon as the person leaves a field with a wrong value.
+- The summary strip when someone submits and one or more fields fail.
+
+## When not to use
+
+- For errors not tied to a field, such as a server failure. Use a banner above the form or the table error state.
+- To confirm success on every field. Use a Toast for the completed action instead.
+- Before the person has touched the field. Leave untouched fields neutral until submit.
+
+## Structure
+
+1. Error summary strip (on submit)
+2. Count of problems
+3. Go to first link
+4. Field with red border
+5. Inline error message
+
+## Guidelines
+
+- Check a field when the person leaves it. Recheck on each keystroke once it is in error, and clear the error when fixed.
+- On submit, check the whole form. Show the red strip at the top: 2 fields need fixing before you can publish.
+- The strip has a Go to first link that scrolls to and focuses the first field in error.
+- The summary adds to inline errors; it never replaces them.
+- Message sits directly under the field, replacing the hint, in 12px red text.
+- Keep everything the person typed. Never clear a form on error.
+
+## Content
+
+- Say what to do, not what went wrong in system terms: Pick a date after today.
+- For empty fields, instruct: Enter a job title. For wrong values, describe the limit: Enter at least £23,400.
+- No please, sorry, oops, invalid or blaming words.
+- Use the field label in the message so it reads as one thing, and use the same words in the summary.
+- The summary counts problems in plain words: 2 fields need fixing before you can publish.
+
+## Accessibility
+
+- Each failed field has aria-invalid="true" and aria-describedby pointing at its message.
+- Errors are in text, not only red. The border colour is a second cue.
+- The strip uses role="alert" so it is announced at once; Go to first moves focus to the field.
+- Messages suggest a fix whenever the system knows one.
+- Red text and the red border meet 4.5:1 and 3:1 on white.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Leave a field and trigger its check |
+| Enter on Go to first | Move focus to the first field in error |
+
+## Examples
+
+### summary
+
+```tsx
+import { Button, ErrorSummary, TextField } from "@twoux/ui";
+import { useState } from "react";
+export const meta = {"title": "Validate on submit, then summarise", "description": "Press Publish. On submit, each field shows its own error and the summary at the top counts the problems and links to each field.", "order": 1};
+
+export default function Example() {
+	const [title, setTitle] = useState("");
+	const [salary, setSalary] = useState("18000");
+	const [sent, setSent] = useState(false);
+	const errs = [
+		!title.trim() && { field: "Job title", message: "Enter a job title.", href: "#fv-title" },
+		Number(salary.replace(/\D/g, "")) < 23400 && { field: "Salary", message: "Enter at least £23,400.", href: "#fv-salary" },
+	].filter(Boolean) as { field: string; message: string; href: string }[];
+	const show = sent ? errs : [];
+	return (
+		<form className="grid w-96 gap-4" noValidate onSubmit={(e) => { e.preventDefault(); setSent(true); }}>
+			<ErrorSummary errors={show} />
+			<TextField id="fv-title" label="Job title" required error={show.find((e) => e.field === "Job title")?.message} value={title} onChange={(e) => setTitle(e.target.value)} />
+			<TextField id="fv-salary" label="Salary" required hint="Per year, before tax." error={show.find((e) => e.field === "Salary")?.message} prefix="£" value={salary} onChange={(e) => setSalary(e.target.value)} inputMode="numeric" />
+			<div><Button type="submit" variant="default">Publish listing</Button></div>
+		</form>
+	);
+}
+```
+
+## Related
+
+- Text input
+- Button
+- Checkbox
+- Radio
+- Sign in
+- File drop

package/agent/docs-md/generated-columns.md

@@ -0,0 +1,65 @@
+# Generated table columns and enrichment
+
+Add an AI column, test it on three rows, see the cost per row, then run it with progress and Stop. Each cell shows its own state and cites its record.
+
+Kind: pattern · Group: Patterns: AI
+
+**Problem:** Running a prompt across 1,000 rows is expensive and hard to undo, and wrong answers hide among right ones. Without a shared flow, each table runs AI differently and overwrites real data.
+
+**Solution:** Generated columns are separate from real data, carry the origin mark, and run on demand: test on a few rows first, show cost, then run with a progress bar and Stop. Cells fill one by one; failures say why; stale cells are marked out of date.
+
+**Built from:** AI column, Data grid, Prompt editor with fields, AI origin label, Citations and sources, Toast
+
+## How it works
+
+1. Add a column from a short list ("Suggested title", "Risk of closing empty") or describe your own in the prompt editor, with fields from the row as removable chips.
+2. Test on 3 rows before anything else; results appear in place for review.
+3. Before running on all rows, show the cost per row and in total, and the number of rows.
+4. Run fills cells one by one with a visible state (queued, writing, done, failed) and a progress bar with Stop.
+5. A failed cell says why ("The listing has no description") with Try again; "Not found" means the model looked and found nothing; a dash means nothing to do.
+6. When source data changes, mark the column out of date instead of rewriting it silently.
+
+## When to use
+
+- To add a judgement or summary to many rows at once in the data grid.
+
+## When not to use
+
+- In the list table. Generated columns live only in the data grid.
+- To change real fields. A generated column never overwrites real data; applying a suggestion to a real field goes through Propose then apply.
+
+## Guidelines
+
+- Default to testing when a run is expensive or affects many rows.
+- Show cost where the decision is made, on the Run button, in credits with the unit stated.
+- Each cell cites the record it used and shows when it was written.
+- Cells can be corrected one at a time or in bulk.
+- Runs keep a history so people can see and undo earlier runs.
+
+## Content
+
+- Run button: "Run on 412 rows · about 412 credits".
+- Column header shows the origin mark and the time written: "Likely reason · 2 min ago".
+
+## Accessibility
+
+- Cell states are text ("Writing", "Failed"), not only spinners or colours.
+
+## Do
+
+- Do test on a few rows first.
+- Do show cost before running.
+
+## Don't
+
+- Don't auto-run a new column on every row.
+- Don't rewrite stale cells silently.
+
+## Related
+
+- Labelling AI output
+- Citing sources
+- Showing reasoning and progress
+- Data export
+- AI column
+- Prompt editor with fields

package/agent/docs-md/generated-drafts-files.md

@@ -0,0 +1,71 @@
+# Generated drafts and files
+
+Show what the assistant makes (a job description, a CSV, a chart) as a card under the answer. Short things are read and copied in place; long drafts open on the assistant page. Anything that would change a record goes through Suggested changes.
+
+Kind: pattern · Group: Patterns: AI
+
+**Problem:** Hiring teams ask the assistant for things they will use elsewhere: a job description for a new role, a CSV of expiring listings, a chart of applications by week. Pasted into the answer text, these are hard to copy, easy to lose and easy to mistake for saved data.
+
+**Solution:** Each output becomes a generated file card stacked under the answer, with name, type, size and origin label, and its own actions. Short, self-contained output stays inline. Long drafts open beside the conversation on the assistant page. Saving a draft into a listing is a suggested change the person applies.
+
+**Built from:** Generated file card, Assistant side panel, Assistant page, Suggested changes, Code block, AI origin label, Dropdown menu
+
+## How it works
+
+1. When an answer produces something to keep, place it as a card below the answer text, one card per output, never inside a paragraph.
+2. Choose inline or open by length and intent: a short snippet, a CSV or a chart image stays inline with Copy or Download; a full job description opens to read and edit.
+3. Open shows the draft on the assistant page in the Answer area, with the conversation still beside it.
+4. If the draft belongs on a record (the description of LST-1044), the card's main action is "Suggest for LST-1044", which adds it to Suggested changes with before and after.
+5. Applying works like every proposal: step card, toast with Undo.
+
+## When to use
+
+- For drafts people will edit or reuse: job descriptions, interview question sets, rejection email drafts for a recruiter to send themselves.
+- For files to download: CSV of listings, a chart as PNG.
+- For a chart the assistant drew from listings data, shown inline with Download and a data table on Open.
+
+## When not to use
+
+- For a figure or a short table that answers the question. Keep it in the answer.
+- For direct edits to a record field. Use Suggested changes.
+- For exports of a table view. Use the Export menu on the table.
+
+## Guidelines
+
+- Keep file actions in the card and answer actions in the answer row, so Copy on the card copies the file and Copy under the answer copies the answer.
+- Two visible actions at most on a card; the rest go in a More menu.
+- Every card carries the origin label and the records it drew on, as the answer does.
+- A draft is never saved anywhere until the person downloads, copies or applies it. Say so on the card.
+- Drafts about candidates are for a person to review and send. The assistant never sends or decides on its own.
+
+## Content
+
+- Card title is the file name or what it is: "Job description, Junior Product Designer", "expiring-listings.csv".
+- Metadata uses standard units and plain types: "CSV · 14 KB · 38 rows".
+- Main action verbs: "Open", "Download", "Copy", "Suggest for LST-1044".
+
+## Accessibility
+
+- Each card is a group named by its title; its actions are named with the file, such as "Download expiring-listings.csv".
+- Generated charts include a text summary and the data as a table on Open.
+- Opening a draft moves focus to its heading; closing returns focus to the card.
+
+## Do
+
+- Do stack each output in its own card under the answer.
+- Do route record changes through Suggested changes.
+- Do show size and row counts before download.
+
+## Don't
+
+- Don't nest file cards inside answer text.
+- Don't put a Save to record button on a draft.
+- Don't mix file actions into the answer actions row.
+
+## Related
+
+- Propose, then apply
+- Citing sources
+- Labelling AI output
+- Data export
+- Generated file card

package/agent/docs-md/grouped-list.md

@@ -0,0 +1,89 @@
+# Grouped list
+
+A compact list of records split under group headers (such as candidates by stage), each header showing its count.
+
+Kind: component · Group: Data · Status: built, import from @twoux/ui
+
+## When to use
+
+- Records fall into a small number of meaningful groups that people scan one at a time, such as pipeline stages.
+- A short list where a full table would be heavy; simple vertical content reads better as a simple list.
+
+## When not to use
+
+- When people sort or compare many attributes across all records. Use the TwoUX List table.
+- For nested hierarchies more than one level deep. Use a tree.
+- For more than about seven groups at once; split with a filter or Saved view instead.
+
+## Structure
+
+1. Group header (name, count, optional action)
+2. Rows: ID, title, secondary text, owner avatar, date
+3. Divider between rows
+
+## Guidelines
+
+- Each group header has a tinted background so rows read as belonging to it.
+- Show the count beside every group name.
+- Keep the same row layout in every group so columns line up down the list.
+- Allow groups to collapse when lists are long.
+
+## Content
+
+- Group names are the states people use, "Interviewing", "Screening", "Offer accepted".
+- Order groups by workflow, not alphabetically.
+- Keep row text to the ID, name, role, owner and date; open the row for more.
+
+## Accessibility
+
+- 1.3.1 Info and Relationships: each group is a list with a heading, so the grouping is available to assistive technology.
+- APG disclosure pattern: collapsible headers are buttons with aria-expanded.
+- 2.1.1 Keyboard: J and K move through rows across groups, as in the List table.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| J / K | Move to the next or previous row |
+| Enter | Open the row |
+| Enter / Space (header) | Collapse or expand the group |
+
+## Examples
+
+### by-stage
+
+```tsx
+import { Badge, Button, GroupedList, ListGroup } from "@twoux/ui";
+
+export const meta = { title: "Candidates by stage", description: "Each tinted header names the group and counts it. Every row keeps the same layout so columns line up. Headers collapse with Enter or Space.", order: 1 };
+
+const STAGES = [
+	{ stage: "Interview", people: [["Priya Shah", "Frontend Engineer", "28 Oct"], ["Sofia Romano", "Junior Product Designer", "20 Oct"]] },
+	{ stage: "Screen", people: [["Amara Okafor", "Junior Product Designer", "2 Nov"]] },
+	{ stage: "Applied", people: [["Tom Becker", "Frontend Engineer", "4 Nov"], ["Liam Walsh", "Data Analyst", "5 Nov"], ["Hana Kim", "QA Engineer", "5 Nov"]] },
+];
+
+export default function Example() {
+	return (
+		<GroupedList className="w-full max-w-xl" aria-label="Candidates by stage">
+			{STAGES.map((g) => (
+				<ListGroup key={g.stage} title={g.stage} count={g.people.length} defaultOpen={g.stage !== "Applied"} action={g.stage === "Applied" ? <Button variant="ghost" size="xs">Screen all</Button> : undefined}>
+					{g.people.map(([name, role, date]) => (
+						<li key={name} className="grid h-9 grid-cols-[1fr_auto_auto] items-center gap-3 px-3 text-base hover:bg-hover">
+							<span className="min-w-0 truncate"><span className="font-medium text-ink">{name}</span> <span className="text-ink-3">· {role}</span></span>
+							<Badge variant="secondary">{g.stage}</Badge>
+							<span className="tabular w-14 text-right text-sm text-ink-3">{date}</span>
+						</li>
+					))}
+				</ListGroup>
+			))}
+		</GroupedList>
+	);
+}
+```
+
+## Related
+
+- List table
+- Saved views
+- Filter pills and filter bar