@twoux/ui 0.0.0-stage → 0.1.1

package/agent/docs-md/content-density.md

@@ -0,0 +1,61 @@
+# Content density
+
+TwoUX ships one density: compact. Controls are 28 or 32px high and table rows 36px. Spacing that protects reading and pointing is kept, so compact never means cramped targets. Tool pages that pass three tests use workspace density: the same sizes with the chrome and gaps taken out.
+
+Kind: foundation · Group: Visual foundation
+
+## Principles
+
+- Compact only. Compact suits data-heavy views such as dashboards, resource lists and details; that is every main view in TwoUX, so a second mode would double the testing for little gain.
+- One density means one set of numbers. People, reviewers and code generators never have to ask which mode a screen is in.
+- Dense data, roomy reading. Informational content such as alerts and help keeps more space even in compact mode; TwoUX keeps 14px text and wider line height in AI answers and descriptions.
+- Workspace density takes away chrome, never size. A trading or operations screen fits every region in view by dropping the canvas margin, card frames and gaps between regions, not by shrinking text or targets.
+
+## Guidelines
+
+- Control heights: --h-sm 28px for toolbars, filters and buttons inside rows or panels; --h-md 32px for primary forms and page-level actions; --row 36px for table and list rows.
+- Every pointer target is at least 24 by 24 CSS px, or has enough clear space around it. Icon buttons at --h-sm (28px square) pass outright.
+- Small targets inside dropdowns and pickers keep extra padding, even in compact mode.
+- Never shrink alerts, validation messages or empty states to save space.
+- One variant, for data rather than people: Table and SheetGrid take size="dense" (28px rows, the same 13px text) for spreadsheet-like data such as inventories, ledgers, imports and mapping. It is chosen per table by whoever builds the screen, never a switch people turn on.
+- Use workspace density only when all three are true: people watch and act on several regions at once; experts work in it for long, repeated sessions; the content is mostly numbers or tables scanned across many rows. Trading, operations consoles, data workspaces and editors pass; forms, settings, onboarding, record detail, list pages and glance dashboards do not.
+- Workspace density is a layout, not a size: AppShell frame="flush" with the sidebar as a rail, regions in a Pane layout divided by 1px lines, 8px padding inside panes, charts flush (the default inside a flush shell), and size="dense" for spreadsheet-like tables.
+- Even in a workspace, text stays on TwoUX's type scale (13px body, 12px meta, never smaller), targets at 24px or more, and alerts, validation messages and empty states keep their size.
+- Below 900px a workspace stacks its panes and the page scrolls; it never becomes a separate mobile app.
+- Choose workspace density per page when the page is designed, never as a switch people turn on. Salt's high density (20px controls, 11px text) is the counter-example: Salt itself says it does not meet WCAG 2.2 AA, target size included, and is not recommended as a default.
+
+## Accessibility
+
+- Target size minimum is 24 by 24 CSS px at AA, with a spacing exception for smaller targets.
+- Compact rows must still reflow and stay readable at 400% zoom; tables may scroll horizontally inside their own container.
+- Because density is not a user setting, zoom and text-size support carry the job of making things bigger.
+
+## Do
+
+- Use --row for every list and table, including the inbox and AI history.
+- Check targets with the 24px circle test when placing icon buttons side by side.
+
+## Don't
+
+- Do not add a 'comfortable' variant to a single component.
+- Do not shrink text below --t-sm to fit more in a row.
+- Do not use workspace density to fit more on a page that fails one of the three tests; give it the inset canvas.
+
+## Tokens
+
+| Token | Value | Use |
+|---|---|---|
+| `--h-sm` | `28px` | Small controls: toolbars, filters, in-row and in-panel buttons |
+| `--h-md` | `32px` | Default controls: forms, page actions |
+| `--row` | `36px` | Table and list row height: the 32px control plus 2px above and below |
+| `--size-row-dense` | `28px` | Table and SheetGrid size="dense", spreadsheet-like data only |
+
+## Related
+
+- Spacing
+- Typography
+- Layout
+- Accessibility
+- Dense table
+- Pane layout
+- App shell and sidebar navigation

package/agent/docs-md/conversation-history.md

@@ -0,0 +1,78 @@
+# Previous conversations
+
+A searchable list opened from the clock in the panel bar: scheduled tasks first, then recent conversations, with a dot for a new answer and "Needs you" for one waiting.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- Returning to an earlier answer or a run waiting for you.
+- Finding conversations by their title, named from the first question.
+
+## When not to use
+
+- Handling everything that needs you across the product. Use the Inbox (inbox).
+- Auditing agent actions. Use the Agent run timeline (agent-run) log.
+
+## Structure
+
+1. Search field
+2. Scheduled tasks
+3. Recent conversations (title, status dot or Needs you badge, date)
+
+## Guidelines
+
+- Name conversations from the first question so they are findable.
+- Mark a new answer with a dot and a waiting run with "Needs you".
+- Selecting a past conversation lets people continue it or start from it.
+- Offer deletion and keep history private by default.
+- Title each conversation from its first question or a short summary, never "New conversation".
+- Group by Today, Yesterday, Previous 7 days, then month; show local time with the full date and time on hover.
+- Delete has Undo. Conversations are never removed automatically without notice; the retention period is stated at the top of the list.
+- History is the person's record of conversations; what the assistant keeps between conversations lives in Team instructions, where it can be seen and edited.
+
+## Content
+
+- Dates are short and relative where recent ("Yesterday", "Mon", "2 Nov").
+
+## Accessibility
+
+- The search field filters the list; announce the result count (SC 4.1.3).
+- The new-answer dot has a text equivalent ("New answer") (SC 1.4.1, 1.3.1).
+- Esc closes the history and returns focus to the clock button (SC 2.4.3).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Esc | Close the list |
+| Tab / Shift+Tab | Move through conversations |
+| Enter | Open a conversation |
+
+## Examples
+
+### history
+
+```tsx
+import { ConversationHistory, toast } from "@twoux/ui";
+
+export const meta = { title: "Find past conversations", description: "Named from the first question, scheduled tasks first, a dot for a new answer and Needs you for a waiting run.", order: 1 };
+
+export default function Example() {
+	return (
+		<div className="w-full max-w-md rounded-sm border border-line bg-surface p-3">
+			<ConversationHistory
+				scheduled={[{ id: "s1", title: "Weekly listing check", date: "Mon", status: "needs-you" }]}
+				recent={[{ id: "r1", title: "Why are these closing with few applicants?", date: "Today", status: "new" }, { id: "r2", title: "Compare Design applicants with last quarter", date: "Tue" }, { id: "r3", title: "Draft a shorter description for LST-1044", date: "3 Nov" }]}
+				onOpen={(id) => toast(`Opened ${id}`)}
+			/>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Assistant side panel
+- Inbox (triage)
+- Agent run timeline

package/agent/docs-md/create-record.md

@@ -0,0 +1,80 @@
+# Creating a record: dialog, single page or steps
+
+Pick the creation surface by how much people must decide: a small dialog for a name or two, one page for most records, steps only for long or high-stakes set-ups. Fill everything else with visible defaults.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** Each team builds creation differently: a wizard for a three-field listing, a modal stacked on a modal for a new location, forms that ask for things the product could have guessed. People abandon long forms and get lost in short wizards.
+
+**Solution:** Count the decisions people must make, not the fields that exist. Ask only for what has no good default; put the rest under Additional settings with the default showing. Use a dialog for up to three short fields, one page for most records, and the Stepper only when steps depend on each other, settings can't be changed after creation, or the result reaches people outside the workspace.
+
+**Built from:** Page header, Breadcrumb, Card, Text input, Combobox, Date picker, Form validation, Stepper, Side panel (drawer), Button, Toast, Confirmation dialog
+
+## How it works
+
+1. List every field, then sort it: required with no good default, expected by at least 8 in 10 people (such as salary on a listing), and everything else. Only the first two groups go in the main section.
+2. Choose the surface. A dialog for one to three short fields, such as a new saved view or a new tag. A single page for most records, such as Create listing. The Stepper for long or dependent set-ups, such as Publish listing to job boards. When fields appear based on earlier answers, count the longest version of the form.
+3. Show defaults as real values in the fields: Closing date 6 December 2026 (30 days), Hiring manager: you. Values TwoUX decides later say so in the hint: "Reference number is assigned when you save."
+4. Put the remaining fields in a collapsed Additional settings section at the end, each with its default filled in.
+5. The primary button stays enabled. On submit, validate, show the error summary and move focus to the first problem.
+6. On success, open the new record (side panel or page, as Record detail says) and show a toast such as "Listing created".
+
+## When to use
+
+- Dialog: one to three short fields that can all be changed later, with nothing to look up elsewhere.
+- Single page: most records, from a draft listing to a new candidate with CV upload, up to about 15 main fields or 5 groups.
+- Stepper: more than about 15 main fields or 5 groups, later steps that change with earlier answers, settings that cannot be changed after creation, or one group complex enough to need its own page, such as application questions with their own rules.
+- If length, complexity and recovery still leave it open, use frequency: one page for records people create often, steps for set-ups done rarely.
+
+## When not to use
+
+- Don't use steps to make a short form feel lighter. Three steps of two fields each is slower than one page.
+- Don't use this for changing one value on an existing record. Use inline editing.
+- Don't create records the assistant suggested without the person applying the proposal. Use Propose, then apply.
+
+## Guidelines
+
+- Order the main fields the way the list shows them. The field order on Create listing becomes the default column order in the Listings table.
+- Defaults must match what TwoUX will actually save. If the hint says "Closes after 30 days", the listing closes after 30 days.
+- Never ask for something the workspace already knows. Prefill the team, office address and hiring manager from the person and workspace.
+- When a field needs something that does not exist yet, such as a new location, offer "Create Leeds office" inside the select for a name only, or open an overlay side panel for more. When it is saved, select it in the field and return focus there.
+- Never stack a dialog on a dialog, and never run a Stepper inside a side panel or dialog.
+- Leaving with unsaved input asks "Discard new listing?" with Keep editing focused. Leaving an untouched form closes without asking.
+- Stepper flows: three to five steps, seven at most, one page per step, a Review step at the end with Edit links back to each step, in the same order as the steps.
+- In a Stepper, check each step when people press Next and keep them on it until it passes. The Review step checks everything again and links each problem to the step that holds it.
+
+## Content
+
+- Page title and button use the same verb and object: page "Create listing", button "Create listing". Cancel is "Cancel".
+- Section headings are nouns: "Role", "Location and pay", "Additional settings". Not "Enter role details".
+- Hints say what happens if the field is left as it is: "If you leave this blank, the listing stays open until you close it."
+- Mark optional fields "(optional)"; don't mark required ones.
+
+## Accessibility
+
+- One h1 per page (the page title); each section is an h2 in a labelled group.
+- Additional settings is a disclosure button with aria-expanded. When it opens, focus stays on the button.
+- The Stepper names the current step in text ("Step 2 of 4: Application questions") and moves focus to the step heading on Next and Back.
+- When a sub-create side panel closes, focus returns to the field that opened it.
+
+## Do
+
+- Do let people create with one press of Create when the defaults are right.
+- Do show every default in the field or hint, never hidden behind a setting.
+- Do keep the Review step free of editing; it links back to steps instead.
+
+## Don't
+
+- Don't disable Create until the form is valid. Validate on submit and say what is missing.
+- Don't add a sidebar item for a create page; it opens from the page header of the list.
+- Don't open a dialog to create something from inside another dialog.
+
+## Related
+
+- Editing a record: inline, section or whole page
+- Deleting records
+- Inline editing and validation
+- Record detail: side panel, overlay or full page
+- Stepper
+- Form validation
+- Page header

package/agent/docs-md/csv-import.md

@@ -0,0 +1,88 @@
+# CSV import
+
+A two-step dialog: choose a CSV file, its delimiter and header row; then match columns, read the problems before importing, preview the first 20 rows with problem cells marked, and import with the count on the button.
+
+Kind: component · Group: Data · Status: built, import from @twoux/ui
+
+## When to use
+
+- Bringing rows from a spreadsheet into a table.
+
+## When not to use
+
+- For a single file attached to a record. Use File drop.
+- For syncing a connected service. Use the connector and an automation.
+
+## Structure
+
+1. Step 1: File drop, Use the sample file, Delimiter, First row contains column names
+2. Step 2: problem summary with what happens to bad rows
+3. Field mapping
+4. Preview of the first 20 rows, or only rows with problems, with Fix on problem cells
+5. Footer: Back, Cancel, Import 1,248 rows
+
+## Guidelines
+
+- Show problems before importing, in a summary at the top that says what will happen to bad rows: skipped, or imported with the cells left empty.
+- Mark problem cells in the preview with an icon and a word, and let people fix them in place.
+- Put the number of rows on the Import button, so the result is known before pressing it.
+- Accept the file by drop or by the Upload button, state the type and size limit, and explain a wrong file in words.
+- Detect the delimiter and header row, and let people change both.
+- Read dates day first, as in the UK (02/11/2026 is 2 November), accept ISO 8601 and written months (14 Mar 2026), and mark anything else, including impossible dates such as 31/02/2026, as Not a date. Hand dates to the app as ISO 8601 so it never re-reads them.
+
+## Content
+
+- Summary: "3 rows have an invalid email. They will be skipped or you can fix them."
+- Wrong file: "That isn't a CSV file. Save the sheet as CSV and choose it again."
+
+## Accessibility
+
+- Progress is written as Step 2 of 2.
+- The summary takes focus after a failed Import; problem cells have the word, not only a tint.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Esc | Close the dialog |
+| Enter (fixing) | Save the fixed value |
+| Esc (fixing) | Cancel the fix |
+
+## Examples
+
+### leads
+
+```tsx
+import { Button, CsvImport, type MappingTarget, toast } from "@twoux/ui";
+import { FileUp } from "lucide-react";
+import { useState } from "react";
+
+export const meta = { title: "Import event leads", description: "Use the sample file or choose your own CSV. The summary says what happens to rows with problems before anything is imported, and the button states how many rows will be added.", order: 1 };
+
+const TARGETS: MappingTarget[] = [
+	{ id: "name", label: "Name", kind: "text", required: true },
+	{ id: "email", label: "Work email", kind: "email" },
+	{ id: "company", label: "Company", kind: "text" },
+	{ id: "size", label: "Company size", kind: "number" },
+];
+const SAMPLE = {
+	name: "leads.csv",
+	text: "Full name,E-mail,Company,Headcount,Country\nMaya Fischer,maya.fischer@larkfield.energy,Larkfield Energy,3100,UK\nRuairi Doyle,ruairi.doyle@pennine,Pennine Freight,1200,Ireland\nSana Iqbal,sana.iqbal@mosaiclending.co.uk,Mosaic Lending,410,UK\n,info@copperleaf.co.uk,Copperleaf Foods,780,UK\nTheo Clarke,theo.clarke@orrin.dev,Orrin Software,about 130,UK\nGrace Ndlovu,grace.ndlovu@harbourvale.co.uk,Harbour & Vale,240,UK",
+};
+
+export default function Example() {
+	const [open, setOpen] = useState(false);
+	return (
+		<>
+			<Button variant="outline" onClick={() => setOpen(true)}><FileUp />Import CSV</Button>
+			<CsvImport open={open} onOpenChange={setOpen} targets={TARGETS} tableName="People" sample={SAMPLE} aliases={{ email: ["e-mail"], size: ["headcount"] }} onImport={(r) => toast.success(`Imported ${r.rows.length} rows${r.skipped ? `, skipped ${r.skipped}` : ""}`)} />
+		</>
+	);
+}
+```
+
+## Related
+
+- Field mapping
+- File drop
+- Sheet grid

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

@@ -0,0 +1,78 @@
+# Dashboard items
+
+The catalogue of item types a dashboard is built from, such as key metrics, charts, short lists, alerts, quick links, getting started and feature news, and what each one should contain.
+
+Kind: pattern · Group: Patterns: data and dashboards
+
+**Problem:** Without a shared catalogue, every new dashboard item invents its own header, actions and amount of data. Items grow into mini reports with their own filters and tables, and the dashboard stops being readable at a glance.
+
+**Solution:** Every item is a board item with the same anatomy: title, optional description, at most one header action, a more menu, content, and an optional footer link. The content is one of a small set of types, each with a clear job and size, and each links to the page where the full data lives.
+
+**Built from:** Board and board item, Card, Stat card with comparison, Line chart card, Bar chart, Funnel, List table, Status badge, Banner (inline alert), Stepper, Dropdown menu, Empty state, Loading skeleton, Error state (failed to load), AI origin label
+
+## How it works
+
+1. Key metrics (full width): two to four Stat cards with comparison, such as Live listings, Applications this week, Median days to first review, Offers accepted. Each opens its report.
+2. Chart (medium or large): one chart that explains a key metric, such as applications per week or the views to offers funnel, with the Chart or Table switch and a View report link.
+3. List or table (medium or large): the top five records that need attention, such as listings expiring in 7 days or candidates waiting over 5 days, with status badges and "View all 23" in the footer.
+4. Status and alerts (small or full width): what is wrong now and what to do, such as "Indeed sync failed for 2 listings" with Retry sync. It shows "No issues" when all is well rather than disappearing.
+5. Quick links and resources (small): three to five links to frequent destinations or help, such as Post a listing, Import candidates, Interview scorecard guide.
+6. Getting started (medium): the workspace setup checklist for new teams, with progress such as "2 of 5 done". People can dismiss it once they are set up.
+7. Feature news (small): one product update in a sentence with one link. It is dismissible, and there is never more than one on a dashboard.
+
+## When to use
+
+- Whenever you add anything to a static or configurable dashboard: pick a type from this catalogue first.
+- When a summary can be read on its own without the other items.
+- When the item has a clear destination for people who need more detail.
+
+## When not to use
+
+- For data people need to filter, sort and act on in bulk. Link to the List table.
+- For long text or logs, such as the full activity history of a listing. Put it on the record page.
+- For a single number with no comparison and no action. Fold it into the key metrics row or leave it out.
+
+## Guidelines
+
+- One item, one job. Combine at most two visual types in an item, such as a chart with its breakdown table, never a chart, a table and a list.
+- At most one action in the header, for the most common next step. Everything else goes in the more menu: Preferences first, then other actions by how often they are used, then Remove from dashboard last.
+- Show all the content by default. Preferences can hide parts, such as a column or the table under a chart, but only on configurable dashboards.
+- Keep the content light: no inline filters beyond a period or one select, no row selection, no editing. Link out for anything more.
+- Size by content: small (1 of 4 columns) for one number or a few links, medium (2) for a chart or short list, large (3) for a chart that compares several series, full width (4) for key metrics.
+- An AI summary item, if offered, carries the origin label, cites the records it used by ID and only suggests. It never ranks, rejects or advances candidates.
+- Give each item's title heading level 2 (level={2} on ChartFrame, BoardItem and ChangeList) so the page outline runs from the h1 straight to the items and screen reader users can jump between them.
+
+## Content
+
+- Title is a noun phrase with scope: "Candidates waiting over 5 days", not "Waiting" or "Widget 3".
+- Footer links say how many: "View all 23 listings", not "See more".
+- Item menu labels are verbs or plain nouns: "Preferences", "View report", "Remove from dashboard".
+- An item with nothing to show explains why and what to do: "No listings expire in the next 7 days."
+
+## Accessibility
+
+- Each item is a region labelled by its h2 title.
+- Key metric changes are read as words: "Up 12% vs previous 7 days", not only an arrow and a colour.
+- A table inside a narrow item scrolls inside the item, not the page, and keeps its header row.
+- Alerts that appear after load are announced politely; failures that block work use the error state in the item.
+
+## Do
+
+- Do treat each item as an executive summary of its subject.
+- Do give every list and chart item a link to its full page.
+- Do keep loading, empty and error states inside the item's frame so the layout does not jump.
+
+## Don't
+
+- Don't add actions that belong on another page, such as Post a listing inside a chart item.
+- Don't use expanding footers or accordions inside items.
+- Don't show more than one feature news item, and never one that cannot be dismissed.
+
+## Related
+
+- Static dashboard
+- Configurable dashboard
+- Board and board item
+- Stat card with comparison
+- Line chart card
+- Onboarding to an empty workspace

package/agent/docs-md/data-export.md

@@ -0,0 +1,61 @@
+# Data export
+
+One Export menu on every table: choose what to include first, then the format, then copy instead of download if you want.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** People export to share with hiring managers or to work in a spreadsheet. When each table exports differently, they get files with hidden columns, raw field names or AI guesses mixed with real data.
+
+**Solution:** Export (⇧E) opens one menu: options first (visible columns only, include AI columns, selected rows or all matching rows), then formats, then copy to clipboard. The file matches what is on screen.
+
+**Built from:** Export menu, List table, Data grid, Bulk action bar, Toast, Inbox (triage)
+
+## How it works
+
+1. Export sits in the table toolbar with the other global table actions, and in the bulk bar when rows are selected.
+2. Options come first: rows (selected, or all N matching the filters), visible columns only, include AI columns.
+3. Then the format (CSV, Excel), then Copy to clipboard for quick pastes.
+4. Small exports download at once with a toast. Exports likely to take more than about ten seconds run in the background with progress, and finish with an Inbox item linking to the file.
+5. If the export fails, say why and offer Try again in a banner, not a toast.
+
+## When to use
+
+- On any list table, data grid, breakdown table or chart that has a table view.
+
+## When not to use
+
+- To share a view with a colleague inside TwoUX. Share the view's link instead (Saved views).
+- As a fix for missing analysis. If many people export the same table, add the analysis to the product.
+
+## Guidelines
+
+- The file matches the screen: same rows, same visible columns, same order, column names as shown, not database field names.
+- AI columns are excluded by default and, when included, are named with a suffix such as "(AI)" so generated values are never mistaken for real data.
+- Say the scope in numbers before export: "Export 412 candidates".
+- Long exports do not block the page; people can keep working.
+
+## Content
+
+- Menu label: "Export". Actions name the scope: "Export 2 rows as CSV".
+
+## Accessibility
+
+- Announce "Export ready" or "Export failed" as a status message.
+- The export menu is a standard menu button reachable by keyboard; ⇧E opens it.
+
+## Do
+
+- Do export what the person sees.
+- Do label AI columns in the file.
+
+## Don't
+
+- Don't put Export in a different place on each table.
+- Don't block the screen while a large export runs.
+
+## Related
+
+- Selection and bulk actions
+- Generated table columns and enrichment
+- Notifications: inbox, bell, toast or email digest
+- Export menu

package/agent/docs-md/data-grid.md

@@ -0,0 +1,137 @@
+# Data grid
+
+An editable, spreadsheet-like grid for enriching and exporting many columns, with pinned columns, cell-by-cell keyboard navigation, a totals row and AI-generated columns.
+
+Kind: component · Group: Data · Status: built, import from @twoux/ui
+
+## When to use
+
+- People edit, enrich or export many columns of data, and cells contain interactive or editable content.
+- The table is wider than the screen and people compare values across columns, so the identifying column must stay in view.
+- People need summary content such as totals kept in view while they scroll, for example total salary or average apply rate.
+
+## When not to use
+
+- For scanning and triage of records. Use the TwoUX List table; a static table keeps reading simpler.
+- For deep edits of one record. Use the side panel or full record page; in-place editing only works for narrow edits.
+- For a handful of records. Use the TwoUX List table without pagination or totals.
+- For spreadsheet work: selecting ranges, copying to and pasting from Excel or Google Sheets, fill down and undo. Use the Sheet grid, with size="dense" for 28px rows.
+
+## Structure
+
+1. Toolbar (view name, Columns, Group, Export)
+2. Pinned header row with column type icons
+3. Pinned checkbox and identifying columns
+4. Scrollable data cells
+5. AI column (tinted, with run state per cell)
+6. Pinned totals row
+7. Status line for save and validation messages
+
+## Guidelines
+
+- The grid has one tab stop. Arrow keys move between cells, Home and End go to the first and last cell in the row.
+- Enter or F2 starts editing, Escape cancels, Enter or Tab commits. Validation is per field.
+- Pin the checkbox and Role columns while scrolling sideways, and the header and totals row while scrolling down.
+- Mark editable columns in the header and show the edit affordance on hover.
+- The totals row is chosen per column (sum, average, empty percentage) and counts only rows on screen; say so in the label.
+- The AI column runs on demand with progress, Stop and per-cell state, and never overwrites real data.
+- The Data grid keeps 36px rows. For spreadsheet-like data where people need many rows in view, use the Sheet grid with size="dense" instead of changing the Data grid's height.
+
+## Content
+
+- Each column shows its type icon so people recognise number, money, person, link, date and AI columns at a glance.
+- Right-align numbers and money with consistent decimals.
+- Keep three empty states apart: a dash when there is nothing, "Not found" when the AI looked and found nothing, and a red message with Retry when it failed.
+- Validation messages name the field and the rule, for example "Enter at least £23,400, the UK minimum for a full-time role."
+
+## Accessibility
+
+- APG grid pattern: role="grid", roving focus on cells, aria-selected on selected rows, aria-sort on the sorted header.
+- 2.1.1 Keyboard: every cell action, including sort, hide, totals and AI run, works from the keyboard.
+- 3.3.1 Error Identification: invalid values stay in edit with a red outline and a text message, not the outline alone.
+- 4.1.3 Status Messages: save confirmations and AI progress are announced from the status line without moving focus.
+- 2.4.11 Focus Not Obscured: pinned columns and rows must not hide the focused cell; scroll it into view.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| ← → ↑ ↓ | Move one cell |
+| Home / End | First or last cell in the row |
+| Enter / F2 | Edit the focused cell |
+| Enter (editing) | Save and stay |
+| Tab (editing) | Save and move to the next cell |
+| Esc (editing) | Cancel the edit |
+| ⇧Space | Select or deselect the active row; the bulk action bar shows above the header |
+
+## Examples
+
+### enrich
+
+```tsx
+import { DataGrid, type GridColumn, type GridRow, toast } from "@twoux/ui";
+import { Copy, Trash2 } from "lucide-react";
+import { useState } from "react";
+
+export const meta = { title: "Enrich listings in place", description: "Focus the grid, move with the arrow keys and press Enter, F2 or just type to edit. Esc cancels; Enter saves and stays; Tab saves and moves on. Salary must be a whole number above the minimum.", order: 1 };
+
+const COLUMNS: GridColumn[] = [
+	{ id: "role", label: "Role", width: 220, pin: true },
+	{ id: "team", label: "Team", width: 130, editable: true },
+	{ id: "location", label: "Location", width: 140, editable: true },
+	{ id: "salary", label: "Salary from (£)", width: 150, editable: true, type: "number", total: "average", validate: (v) => (!/^[0-9]+$/.test(v.replace(/,/g, "")) ? "Enter a whole number, such as 32000." : Number(v.replace(/,/g, "")) < 23400 ? "Enter at least £23,400, the full-time minimum." : undefined) },
+	{ id: "applicants", label: "Applicants", width: 120, type: "number", total: "sum" },
+	{ id: "manager", label: "Hiring manager", width: 160, editable: true },
+];
+
+export default function Example() {
+	const [rows, setRows] = useState<GridRow[]>([
+		{ id: "1", role: "Junior Product Designer", team: "Design", location: "Leeds", salary: 30000, applicants: 38, manager: "Priya Shah" },
+		{ id: "2", role: "Frontend Engineer", team: "Engineering", location: "Manchester", salary: 52000, applicants: 112, manager: "Tom Becker" },
+		{ id: "3", role: "Data Analyst", team: "Data", location: "Remote (UK)", salary: 41000, applicants: 64, manager: "" },
+		{ id: "4", role: "Recruitment Coordinator", team: "People", location: "London", salary: 29000, applicants: 0, manager: "Amara Okafor" },
+		{ id: "5", role: "Customer Success Lead", team: "Customer", location: "Bristol", salary: 45000, applicants: 21, manager: "" },
+	]);
+	const [selected, setSelected] = useState<string[]>([]);
+	const n = selected.length;
+	const noun = n === 1 ? "listing" : "listings";
+	const duplicate = () => {
+		setRows((rs) => [...rs, ...rs.filter((r) => selected.includes(r.id)).map((r, i) => ({ ...r, id: `${r.id}-copy-${rs.length + i}`, role: `${r.role} (copy)` }))]);
+		toast.success(`Duplicated ${n} ${noun}`);
+		setSelected([]);
+	};
+	const remove = () => {
+		const before = rows;
+		setRows((rs) => rs.filter((r) => !selected.includes(r.id)));
+		toast(`Deleted ${n} ${noun}`, { action: { label: "Undo", onClick: () => setRows(before) } });
+		setSelected([]);
+	};
+	return (
+		<DataGrid
+			className="w-full"
+			aria-label="Listings"
+			columns={COLUMNS}
+			rows={rows}
+			onCellChange={(id, col, v) => setRows((r) => r.map((x) => (x.id === id ? { ...x, [col]: v } : x)))}
+			selectedRowIds={selected}
+			onSelectedRowIdsChange={setSelected}
+			noun={noun}
+			bulkActions={[
+				{ label: "Duplicate", icon: <Copy />, onSelect: duplicate },
+				{ label: "Delete", icon: <Trash2 />, destructive: true, onSelect: remove },
+			]}
+		/>
+	);
+}
+```
+
+## Related
+
+- List table
+- Columns menu
+- Export menu
+- Saved views
+- Filter pills and filter bar
+- Bulk action bar
+- Sheet grid
+- Dense table