@twoux/ui 0.0.0-stage → 0.1.0

package/agent/docs-md/selection-bulk-actions.md

@@ -0,0 +1,70 @@
+# Selection and bulk actions
+
+Pick rows with X or checkboxes, then act on all of them from one bar above the table that says how many rows it will touch.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** Extending, closing or exporting listings one by one is slow, and bulk actions placed in different spots on each page are missed or misfired.
+
+**Solution:** Selecting rows shows the bulk action bar directly above the table, with the actions, the count and Esc to clear. Filters and column headers stay where they were.
+
+**Built from:** List table, Data grid, Bulk action bar, Checkbox, Toast, Confirmation dialog, Keyboard shortcut hint
+
+## How it works
+
+1. Select a row with its checkbox or X; ⇧J extends the selection downward. The header checkbox selects only the rows on the current page.
+2. The bulk action bar appears directly above the table: the actions with their shortcuts on the left, the count ("2 listings selected") and Clear selection (Esc) on the right.
+3. If more rows match than are on screen, the bar offers "Select all 412", and the count updates to say so.
+4. Choosing an action runs it on the selected rows. Reversible actions show a toast with Undo; irreversible ones confirm first.
+5. If an action cannot apply to some selected rows, say how many and why before it runs.
+
+## When to use
+
+- When the same action is often applied to many rows: extend, close, assign, export, ask the assistant.
+
+## When not to use
+
+- For an action on one record. Use the row's actions or the side panel.
+- When the action needs per-row input, such as different closing dates. Use inline editing in the data grid.
+
+## Guidelines
+
+- Every bulk action is also available on a single selected row. The bar only adds the multi-row case.
+- Labels are verb plus noun and say how many rows: "Close 2 listings".
+- Keep the filters visible while rows are selected; the bar sits between the filters and the table instead of replacing the toolbar.
+- Changing filters or sort clears the selection, so an action never touches rows the person can no longer see.
+- Bulk results confirm in one toast ("2 listings extended") with Undo, not one toast per row.
+- A bulk action that can't apply to the current selection stays in the bar as unavailable, with a reason: "Available when all selected listings are Live".
+- The bar holds every action that can run on more than one record; row menus never offer "Close all" or similar.
+- Order bar actions the same way as the page header: status actions first, destructive near the end, the main action last.
+- Beyond four actions, the rest go in a More menu in the bar.
+
+## Content
+
+- Count format: "2 listings selected" in the bar, "2 of 24 selected" in the table footer.
+- Destructive bulk confirmations name the count and the consequence: "Close 2 listings? They stop taking applications now."
+
+## Accessibility
+
+- Selected rows set aria-selected="true"; the selection is also shown with a tick, not colour alone.
+- Announce the selection count when it changes.
+- The header checkbox shows an indeterminate state when some rows are selected.
+- Unavailable bulk actions use aria-disabled so their reason can be reached by keyboard.
+
+## Do
+
+- Do keep the count in the bar beside Clear selection, and name it in the toolbar's label so screen readers hear it before the actions.
+- Do offer Undo after a reversible bulk action.
+
+## Don't
+
+- Don't replace the filter bar with the bulk bar; people lose sight of what they selected from.
+- Don't silently skip rows an action can't apply to.
+
+## Related
+
+- Undo and destructive actions
+- Keyboard-first navigation
+- Data export
+- Ask about what's on screen
+- Bulk action bar

package/agent/docs-md/separator.md

@@ -0,0 +1,75 @@
+# Separator
+
+A thin line that divides groups of content or menu items. With a label, it separates two ways of doing the same thing, such as “or”.
+
+Kind: component · Group: Content · Status: built, import from @twoux/ui
+
+## When to use
+
+- To divide groups inside a card, panel or menu when spacing alone is not enough.
+- With a label, between two routes to the same result: “or” between sign in with Google and the email form.
+
+## When not to use
+
+- Between every row or field. Use spacing; lines everywhere add noise.
+- To separate sections of a page. Use headings and space.
+
+## Structure
+
+1. Line: 1px, light edge colour
+2. Label (optional): short word centred on the line, on the surface colour
+
+## Guidelines
+
+- Prefer space first. Add a line only where groups would otherwise run together.
+- Keep the label to one or two words in lower case: “or”, “or continue with”.
+- Lines run the full width of their container, or align with the content inset in menus.
+
+## Content
+
+- Label in lower case with no full stop: “or”.
+
+## Accessibility
+
+- A purely visual line is decorative, so screen readers skip it. Mark it as a separator only when it divides a menu or a toolbar.
+- The label is real text, so it is read in order between the two groups.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| None | Not focusable |
+
+## Examples
+
+### plain-and-labelled
+
+```tsx
+import { FieldSeparator, Separator } from "@twoux/ui";
+
+export const meta = { title: "Plain and labelled", description: "A plain line divides groups when space alone is not enough. A labelled one sits between two routes to the same result.", order: 1 };
+
+export default function Example() {
+	return (
+		<div className="grid w-full max-w-sm gap-6">
+			<div className="grid gap-3 rounded-sm border border-line bg-surface p-4">
+				<div className="grid gap-0.5">
+					<span className="text-base font-medium text-ink">Senior Product Designer</span>
+					<span className="text-sm text-ink-3">Leeds · Hybrid</span>
+				</div>
+				<Separator />
+				<div className="flex justify-between text-base text-ink-2">
+					<span>Applicants</span>
+					<span className="tabular text-ink">38</span>
+				</div>
+			</div>
+			<FieldSeparator>or</FieldSeparator>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Card
+- Dropdown menu

package/agent/docs-md/setup-checklist.md

@@ -0,0 +1,92 @@
+# Setup checklist
+
+A short list in the sidebar of the few things that make the product useful, with progress shown as "2 of 4".
+
+Kind: component · Group: Navigation · Status: built, import from @twoux/ui
+
+## When to use
+
+- Showing the next few things that make an empty workspace useful.
+- Setup that people can do in any order and return to later.
+
+## When not to use
+
+- A fixed sequence. Use Stepper (stepper) or Onboarding step (onboarding-step).
+- Teaching the interface. Use contextual help, not a modal tour.
+
+## Structure
+
+1. Heading ("Get set up")
+2. Progress text ("2 of 4") and bar
+3. Tasks (status, label, Start)
+4. Dismiss button
+
+## Guidelines
+
+- Keep it to three to five tasks that make the product useful.
+- Put it in the sidebar and let people dismiss it.
+- Show progress as text, "2 of 4", with the bar as extra.
+- Start opens the task in place. Never a modal tour or a full-page takeover.
+- When everything is done, collapse it or let it disappear.
+
+## Content
+
+- Tasks begin with a verb: "Connect Slack", "Invite a teammate".
+- Start button text stays "Start"; the task name is read out with it.
+
+## Accessibility
+
+- The checklist is a labelled section with a list; done tasks say "done" for assistive technology (SC 1.3.1, 1.4.1).
+- Start and Dismiss have names that include what they act on (SC 2.4.6).
+- The progress bar is decorative; the count is text (SC 1.4.1).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move through Start buttons and Dismiss |
+| Enter or Space | Start a task or hide the checklist |
+
+## Examples
+
+### sidebar
+
+```tsx
+import { Button, SetupChecklist, type SetupItem } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Get set up in the sidebar", description: "Start does the task in place. Finish all four and the checklist goes away; Hide closes it sooner.", order: 1 };
+
+const TASKS = [
+	{ id: "slack", label: "Connect Slack" },
+	{ id: "invite", label: "Invite a teammate" },
+	{ id: "import", label: "Import your candidates" },
+	{ id: "agent", label: "Turn on the daily summary" },
+];
+
+export default function Example() {
+	const [done, setDone] = useState<string[]>(["slack"]);
+	const [hidden, setHidden] = useState(false);
+	const items: SetupItem[] = TASKS.map((t) => ({ ...t, done: done.includes(t.id), onStart: () => setDone((d) => [...d, t.id]) }));
+	const finished = done.length === TASKS.length;
+	return (
+		<div className="grid w-full max-w-64 gap-3">
+			{!hidden && !finished && <SetupChecklist items={items} onDismiss={() => setHidden(true)} />}
+			{(hidden || finished) && (
+				<div className="grid gap-2 text-sm text-ink-2">
+					<p>{finished ? "Setup is complete." : "The setup checklist is hidden."}</p>
+					<Button variant="outline" size="sm" onClick={() => { setDone(["slack"]); setHidden(false); }}>Start again</Button>
+				</div>
+			)}
+		</div>
+	);
+}
+```
+
+## Related
+
+- Onboarding to an empty workspace
+- Empty state
+- Onboarding step
+- App shell and sidebar navigation
+- Stepper

package/agent/docs-md/shape-elevation.md

@@ -0,0 +1,55 @@
+# Shape and elevation
+
+Four radii, each tied to a role, and two shadows. The page is flat; only layers that float above it (menus, popovers, toasts, dialogs) get a real shadow.
+
+Kind: foundation · Group: Visual foundation
+
+## Principles
+
+- Radius follows role, and stays tight: 4 to 8px. Small parts are tightest, overlays the roundest.
+- Flat by default. Raised and overlay elevation are used sparingly because they make a UI busy. Borders and surface changes do the grouping.
+- A shadow means 'this floats'. If it casts a --shadow-pop, it sits above the page and can be dismissed.
+
+## Guidelines
+
+- rounded-xs 4px: parts that sit inside a control or a row. Badges, checkboxes, keycaps, menu and palette items, segments, skeleton bars, tags.
+- rounded-sm 6px: controls and cards. Buttons, inputs, toggles, the segmented track, banners, cards, empty and error states.
+- rounded-md 8px: layers that float. Menus, popovers, the command palette, toasts and dialogs.
+- rounded-lg 12px and rounded-xl 16px stay in the scale for marketing surfaces; product UI does not use them.
+- Fully round (99px or 50%) is only for avatars, dots and pill toggles.
+- --shadow-pop is for overlays only: command menu, menus, popovers, toasts, tooltips and dialogs, the UI that floats over other UI.
+- --shadow-sm is a 1px lift on primary and secondary buttons and the AI composer, a tactile cue rather than elevation.
+- Known drift: the side panel uses a raw shadow value and several components use raw 2, 3 and 5px radii and raw z-index values. These should become tokens (for example a --shadow-panel and a --z-* scale).
+
+## Accessibility
+
+- A shadow is never the only boundary of a control; it also has a border or fill that meets 3:1 where the boundary matters.
+- Overlays must not hide the element that has focus.
+
+## Do
+
+- Match radius to role: a button inside a card still uses rounded-sm.
+- Pair --shadow-pop with --surface: each elevation has its own surface and shadow.
+
+## Don't
+
+- Do not put a shadow on a card that sits on the canvas.
+- Do not invent radii like 5px or 10px.
+
+## Tokens
+
+| Token | Value | Use |
+|---|---|---|
+| `rounded-xs` | `4px` | Badges, checkboxes, keycaps, menu items, segments |
+| `rounded-sm` | `6px` | Buttons, inputs, toggles, banners, cards |
+| `rounded-md` | `8px` | Menus, popovers, palette, toasts, dialogs |
+| `--shadow-sm` | `0 1px 2px rgba(23,23,40,.05)` | Button lift, composer |
+| `--shadow-pop` | `0 0 0 1px var(--line), 0 10px 28px -8px rgba(23,23,40,.20)` | Floating layers only |
+| `--ring` | `0 0 0 2px var(--surface), 0 0 0 4px color-mix(in srgb, var(--accent) 55%, transparent)` | Focus ring on :focus-visible |
+
+## Related
+
+- Colours
+- Layout
+- Motion
+- Design tokens

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

@@ -0,0 +1,211 @@
+# Sheet grid
+
+A spreadsheet of records with typed columns, a menu per column, row numbers and a status row for computed columns, and Excel and Google Sheets keys: select ranges, copy and paste to and from either, fill, clear and undo. size="dense" gives 28px rows for spreadsheet-like data.
+
+Kind: component · Group: Data · Status: built, import from @twoux/ui
+
+## When to use
+
+- People build a table of records and add columns that are typed, calculated or filled in per row, such as a work email looked up for every person.
+- The table is wider than the screen and people compare values across columns, so the name column must stay in view.
+- People work as they would in Excel or Google Sheets: they paste blocks of values in, fill down, copy ranges out and undo mistakes.
+- Spreadsheet-like data, such as inventories, ledgers and imports, where people need many rows in view: use size="dense".
+
+## When not to use
+
+- For scanning and triage of records. Use the List table; a static table is simpler to read.
+- For editing a few columns of known data without computed columns. Use the Data grid.
+- For deep edits of one record. Use the side panel.
+
+## Structure
+
+1. Header row: type icon (or the service's logo), column name, sort arrow, menu
+2. Filter row (optional): a search field under each header
+3. Status row for computed columns: Up to date, 62%, 3 errors
+4. Pinned row numbers (with checkbox and ⋮ row menu when set) and frozen first columns
+5. Group rows (optional): label, count and each total column's sum, collapsible
+6. Cells: values, Tag for select, Switch with its word, n/a, or Waiting, Writing, Looking up, Failed with the reason, Not found; the selected range in indigo
+7. Totals row (optional), then Add row, Add 10 rows, the status line and the sum and count of the selection
+
+## Guidelines
+
+- Every column shows its type in the header: an icon for text, number, date and select, the formula mark, the AI origin mark, or the logo of the service an enrichment uses.
+- The grid has one tab stop. Arrow keys move between cells; Up from the first row reaches the column headers, where Enter opens the column menu.
+- The column menu holds rename, change type, sort, filter, wrap text, pin or unpin, column width, hide, insert left or right and delete. Delete happens at once with Undo.
+- Columns resize from the header: drag its right edge (60 to 640px) or double-click the edge to fit the widest value. From the keyboard, ⌥⇧ with an arrow on a header, or Column width in the column menu (Wider, Narrower, Fit to content).
+- Pin any column from its menu to keep it in view when scrolling sideways; pinned columns move to the left edge and show a pin in the header. Pinned columns never take more than 60% of the grid's width.
+- You always see where you are and which record changes: the row being edited is tinted (--color-active-row), and its row number and column header turn primary, as in Google Sheets. The active cell has a 2px primary outline on the surface. Under the pointer, the row takes --color-hover and the cell --color-selected. A select's list opens below the cell, never over it.
+- Select columns read as selectors: the value with a chevron, shown on row hover and focus. A second click on the active cell, a click on the chevron, Enter or any letter opens the list. Don't show select values as badges in an editable grid; badges read as status, not as something to change.
+- The row header is one compact slot: the row number, replaced by a checkbox on hover, on focus and while any row is checked, then the ⋮ menu, shown on hover. On touch screens both stay visible.
+- Computed columns show their progress in the status row and their state in each cell, in words. A run never overwrites a typed value.
+- Pressing Enter on a failed cell runs it again; the status line states the cost first.
+- Keys follow Excel and Google Sheets: Shift with an arrow extends the selection, ⌘ or Ctrl with an arrow jumps to the edge of the data, ⌘C and ⌘V copy and paste, ⌘D and ⌘R fill, ⌘Z undoes. Ctrl replaces ⌘ on Windows and Linux.
+- Copy puts tab-separated values on the clipboard, so a range pastes straight into Excel or Google Sheets, and numbers stay numbers.
+- Paste reads tab-separated values from Excel or Sheets into the range starting at the active cell, and checks each value against its column's type. Cells that don't fit keep their value, are outlined in red with the reason, and the status line says how many were left and why. Nothing is dropped without saying so.
+- Paste, fill, clear and edits can all be undone (⌘Z) and redone (⌘⇧Z or Ctrl+Y), and each one is announced: “Pasted 12 cells”, “Undid paste of 12 cells”.
+- Use size="dense" (28px rows) for spreadsheet-like data. It is a variant for that data, never a row height setting; offer Wrap text per column for long values.
+- Tab moves out of the grid unless a cell is being edited, where it saves and moves right, so the grid stays one tab stop.
+- With onOpenRow, the name cell shows Open on hover and focus and the row menu has Open too; ⇧F10 opens the row menu from the keyboard.
+- Pair the grid with a ShortcutSheet group from sheetGridShortcuts(), which writes ⌘ on a Mac and Ctrl elsewhere, and list the same groups on the page with ShortcutList, so the keys are visible without pressing ? or ⌘/.
+- Add row and Add 10 rows put the new rows at the bottom, scroll there and make the first new cell active, so people can type straight away.
+
+## Content
+
+- Keep the three empty-looking states apart: a dash when there is nothing, Not found when the service looked and found nothing, and Failed with the reason.
+- Status row words: Up to date, 62%, 3 errors, Out of date. Never a bare spinner.
+- Right-align numbers; show dates as 14 Mar 2026.
+- Status line messages say what happened and to how many cells: Copied 6 cells, Pasted 12 cells. 2 cells left as they were, Filled down 4 cells, Cleared 3 cells.
+- Rejection reasons say what to enter: “Enter a number, such as 1200.”, “Choose one of Lead, Qualified, Proposal.”
+
+## Accessibility
+
+- APG grid pattern: role grid, roving focus on cells, aria-sort on the sorted header, row numbers as row headers.
+- 2.1.1 Keyboard: every column action is in a menu reached from the header by keyboard.
+- 1.4.1 Use of colour: failed cells carry an icon and the reason, not only red.
+- 4.1.3 Status messages: saves, clears and retries are announced from the status line.
+- 2.4.11 Focus not obscured: cells scroll clear of the sticky header and frozen columns.
+- APG grid: aria-multiselectable on the grid and aria-selected on cells in the range; selections are announced as “6 cells selected: Job title to Seniority, rows 1 to 3.”
+- 4.1.3 Status messages: copy, paste, fill, clear, undo and redo are announced from the status line, including the reason any cell was rejected.
+- 3.3.1 Error identification: a rejected paste cell has aria-invalid, a red dashed outline and its reason in text, not colour alone.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| ← → ↑ ↓ | Move one cell; up from row 1 to the filter row and the headers |
+| ⌘ / Ctrl + arrow | Jump to the edge of the data in that direction |
+| Home / End | First or last cell in the row |
+| ⌘ Home / ⌘ End (Ctrl on Windows) | First or last cell in the sheet |
+| Page Up / Page Down | Move 10 rows |
+| ⇧ + arrow, ⇧ Home / End | Extend the selection |
+| ⌘ ⇧ + arrow | Extend the selection to the edge of the data |
+| ⇧ click, click and drag | Select a range with the mouse |
+| ⌘ A | Select all cells |
+| Ctrl Space | Select the column |
+| ⇧ Space | Select or deselect the rows of the selected cells (with row selection) |
+| ⌘ C | Copy the range as tab-separated values, for here, Excel or Google Sheets |
+| ⌘ X | Copy the range and clear it |
+| ⌘ V | Paste from here, Excel or Google Sheets into the range from the active cell; each value is checked |
+| Delete / Backspace | Clear the editable cells in the range |
+| ⌘ D | Fill down: the top row of the range into the rows below (one row: from the row above) |
+| ⌘ R | Fill right: the left column of the range into the columns to its right |
+| ⌘ Z | Undo the last edit, paste, clear or fill |
+| ⌘ ⇧ Z / Ctrl Y | Redo |
+| Enter / F2 | Edit; on a header, open the column menu; on a failed cell, run it again; on a group row, collapse or expand |
+| Any character | Start editing and replace the value; on a select cell, open the list |
+| Space (yes or no cell) | Turn it on or off |
+| Enter (editing) | Save and move down |
+| ⇧ Enter (editing) | Save and move up |
+| Tab (editing) | Save and move right |
+| ⇧ Tab (editing) | Save and move left |
+| ⌘ Enter (editing) | Save the value into every selected cell |
+| Esc (editing) | Cancel the edit |
+| Esc | Clear the selection back to the active cell |
+| ⇧ F10 / Menu key, right click | Open the row's actions |
+| Alt ↓ | Open the column menu from a header |
+| ⌥ ⇧ ← / → (Alt Shift on Windows) | On a header: make the column narrower or wider by 16px |
+| ⌘ ; (Ctrl ; on Windows) | Put today's date in a date cell |
+| ⌘ / (Ctrl / on Windows), ? | Show every shortcut |
+| Tab | Leave the grid (one tab stop) |
+
+## Examples
+
+### dense
+
+```tsx
+import { Button, type SheetCellChange, SheetGrid, type SheetRow, ShortcutSheet, sheetGridShortcuts } from "@twoux/ui";
+import { Keyboard } from "lucide-react";
+import { useState } from "react";
+import { PROSPECT_COLUMNS, prospectRows } from "../dense-table/prospects-data";
+
+export const meta = {
+	title: "Dense, with spreadsheet keys",
+	description: "The TwoUX prospects table at size=\"dense\" for 28px rows. Shift+arrows or drag to select, ⌘C to copy as tab-separated values, ⌘V to paste from here, Excel or Google Sheets (each value is checked against its column), ⌘D and ⌘R to fill, Delete to clear, ⌘Z to undo. Press ? for every key.",
+	order: 2,
+};
+
+export default function Example() {
+	const [columns, setColumns] = useState(PROSPECT_COLUMNS);
+	const [single, setSingle] = useState(true);
+	const [rows, setRows] = useState<SheetRow[]>(() => prospectRows(30));
+	const onCellsChange = (changes: SheetCellChange[]) =>
+		setRows((rs) => rs.map((r) => {
+			const mine = changes.filter((c) => c.rowId === r.id);
+			return mine.length ? { ...r, values: { ...r.values, ...Object.fromEntries(mine.map((c) => [c.columnId, c.value])) } } : r;
+		}));
+	return (
+		<div className="grid w-full gap-2">
+			<div className="flex items-center gap-2">
+				<span className="text-sm text-ink-2">TwoUX prospects · {rows.length} people</span>
+				<span className="flex-1" />
+				<Button variant="ghost" size="sm" onClick={() => document.dispatchEvent(new KeyboardEvent("keydown", { key: "?" }))}><Keyboard />Keys (?)</Button>
+			</div>
+			<SheetGrid
+				size="dense"
+				aria-label="TwoUX prospects"
+				className="h-96 w-full"
+				columns={columns}
+				onColumnsChange={setColumns}
+				rows={rows}
+				onCellChange={(id, col, v) => setRows((rs) => rs.map((r) => (r.id === id ? { ...r, values: { ...r.values, [col]: v } } : r)))}
+				onCellsChange={onCellsChange}
+				onAddRows={(n) => setRows((rs) => [...rs, ...Array.from({ length: n }, (_, i) => ({ id: `new-${rs.length + i}`, values: { subscribed: false } }))])}
+			/>
+			<ShortcutSheet singleKeys={single} onSingleKeysChange={setSingle} groups={sheetGridShortcuts()} />
+		</div>
+	);
+}
+```
+
+### prospects
+
+```tsx
+import { SheetGrid, type SheetColumn, type SheetRow, type SheetSort } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Prospects with computed columns", description: "Focus a cell and use the arrow keys. Enter edits, Esc cancels, Tab saves and moves on. Press Up from the first row to reach the headers, then Enter for the column menu. Enter on a failed cell runs it again.", order: 1 };
+
+const COLUMNS: SheetColumn[] = [
+	{ id: "name", label: "Name", type: "text", width: 160, pinned: true, locked: true },
+	{ id: "title", label: "Job title", type: "text", width: 200 },
+	{ id: "seniority", label: "Seniority", type: "select", width: 120, options: ["Mid", "Senior", "Director", "VP"] },
+	{ id: "size", label: "Company size", type: "number", width: 130 },
+	{ id: "summary", label: "Summarise role", type: "ai", width: 260, costPerRow: 1, status: { done: 3, total: 5, running: true } },
+	{ id: "email", label: "Work email", type: "enrichment", provider: "hubspot", width: 230, costPerRow: 0.5, status: { done: 5, total: 5, errors: 1 } },
+];
+
+export default function Example() {
+	const [columns, setColumns] = useState(COLUMNS);
+	const [sort, setSort] = useState<SheetSort>(null);
+	const [rows, setRows] = useState<SheetRow[]>([
+		{ id: "1", values: { name: "Ana Silva", title: "Head of Revenue Operations", seniority: "Senior", size: 240 }, computed: { summary: { state: "done", value: "Leads a function; shortlists tools." }, email: { state: "done", value: "ana.silva@harbourvale.co.uk" } } },
+		{ id: "2", values: { name: "Ben Hughes", title: "Chief Operating Officer", seniority: "VP", size: 160 }, computed: { summary: { state: "done", value: "Runs the business; owns the budget." }, email: { state: "not-found" } } },
+		{ id: "3", values: { name: "Chloe Patel", title: "", seniority: "Mid", size: 410 }, computed: { summary: { state: "failed", reason: "Job title is empty." }, email: { state: "done", value: "chloe.patel@mosaiclending.co.uk" } } },
+		{ id: "4", values: { name: "Daniel Murray", title: "IT Director", seniority: "Director", size: 1200 }, computed: { summary: { state: "writing" }, email: { state: "failed", reason: "No company domain." } } },
+		{ id: "5", values: { name: "Ella Brennan", title: "Operations Manager", seniority: "Mid", size: 130 }, computed: { summary: { state: "queued" }, email: { state: "done", value: "ella.brennan@orrin.dev" } } },
+	]);
+	return (
+		<SheetGrid
+			aria-label="Prospects"
+			className="h-96 w-full"
+			columns={columns}
+			onColumnsChange={setColumns}
+			rows={rows}
+			onCellChange={(id, col, v) => setRows((rs) => rs.map((r) => (r.id === id ? { ...r, values: { ...r.values, [col]: v } } : r)))}
+			sort={sort}
+			onSortChange={setSort}
+			onRetryCell={(id, col) => setRows((rs) => rs.map((r) => (r.id === id ? { ...r, computed: { ...r.computed, [col]: { state: "queued" } } } : r)))}
+			onAddRows={(n) => setRows((rs) => [...rs, ...Array.from({ length: n }, (_, i) => ({ id: `n${rs.length + i}`, values: {} }))])}
+		/>
+	);
+}
+```
+
+## Related
+
+- Data grid
+- Columns menu
+- Run status bar
+- Action catalogue
+- AI column
+- Dense table

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

@@ -0,0 +1,134 @@
+# Side panel (drawer)
+
+A panel on the right that shows the selected row's detail beside the table, in push (default) or overlay mode; 440px by default and resizable from 360px to half the canvas in push mode.
+
+Kind: component · Group: Feedback and overlays · Status: built, import from @twoux/ui
+
+## When to use
+
+- Viewing or editing one record while the list stays in view, such as a listing's figures beside the listings table.
+- Working down a list one record at a time: J and K move the selection and the panel follows.
+- Secondary tasks that should not take the person off the page, such as the Assistant's quick questions.
+
+## When not to use
+
+- The full picture of one record, with history and long sections. Open the full page (⇧↵).
+- A decision that must interrupt the task. Use a Confirmation dialog.
+- Confirming an action. Use a Toast.
+- Comparing many records side by side. Use the table with the chosen columns.
+
+## Structure
+
+1. Control bar without a title: previous, next, position ("3 of 9"), open full page, close
+2. Record ID, title and status line
+3. Tabs (Overview, Candidates, Activity)
+4. Sections split by full-width rules, each with a 13px heading and one action on the right
+5. Empty fields show "Add"
+6. Pinned footer: destructive action left, primary right
+
+## Guidelines
+
+- Push mode (default) on list pages: the table narrows so filters, page actions and the first columns stay usable and nothing is hidden behind the panel.
+- Overlay mode when the page is narrower than about 1100px, or for wide content (dashboards, wide tables) that pushing would crush. The first columns stay visible.
+- One component with mode="push" | "overlay"; the person can switch with ⇧P and the choice is remembered.
+- Opens only from a person's action (Enter or a click on a row), never on its own.
+- Esc closes it and focus returns to the row it came from.
+- Do not repeat table header actions inside the panel; the footer holds actions for this record only.
+- Below 860px the panel takes the full width of the canvas.
+- A panel for one thing, such as settings or a form, has its title in the 44px header bar, with the object it belongs to beside it in muted text (Table settings · People) and Close on the right. A record panel that steps through a list keeps previous, next and the position in the bar, and shows the record's name and status under it.
+
+## Content
+
+- The control bar has no title; the record's own title sits below it, matching the row the person picked.
+- Section headings are short nouns ("Performance", "Funnel", "Details") with one action each.
+- Empty fields say "Add" and the field name rather than a dash, so the gap is an invitation, not an error.
+- Figures sit next to a comparison ("vs board median") so a number can be judged without leaving.
+
+## Accessibility
+
+- The panel is a non-modal complementary region with a label; it does not trap focus, so J/K keep driving the table (2.1.2).
+- In overlay mode the panel must not cover the focused row; the table scrolls the active row into the visible part (2.4.11).
+- Tabs inside the panel follow the APG tabs pattern with arrow keys between tabs.
+- Push and overlay both reflow to a single column at 320px wide without horizontal scrolling of text (1.4.10).
+- Focus order inside the panel follows reading order: control bar, title, tabs, sections, footer (2.4.3).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Enter | Open the panel for the focused row |
+| J / K | Next or previous row; the panel follows |
+| ⇧↵ | Open the record as a full page |
+| ⇧P | Switch between push and overlay |
+| Esc | Close the panel and return focus to the row |
+
+## Examples
+
+### record
+
+```tsx
+import { Badge, Button, PanelMode, SegmentedControl, Segment, SidePanel, Table, TableBody, TableCell, TableRow, Timestamp } from "@twoux/ui";
+import { useState } from "react";
+import { LISTINGS, STATUS_VARIANT } from "../list-table/data";
+
+export const meta = { title: "Record beside the list", description: "Push mode narrows the table so the first columns stay usable; overlay floats over it. J and K move through records with the panel following; Esc closes and focus returns to the row.", order: 1 };
+
+const ROWS = LISTINGS.slice(0, 6);
+
+export default function Example() {
+	const [open, setOpen] = useState<number | null>(1);
+	const [mode, setMode] = useState<PanelMode>("push");
+	const rec = open === null ? null : ROWS[open];
+	return (
+		<div className="grid w-full gap-2">
+			<SegmentedControl value={mode} onValueChange={(v) => setMode(v as PanelMode)} size="sm" aria-label="Panel mode" className="justify-self-start">
+				<Segment value="push">Push</Segment><Segment value="overlay">Overlay</Segment>
+			</SegmentedControl>
+			<div className="flex h-96 overflow-hidden rounded-sm border border-line bg-surface">
+				<div className="min-w-0 flex-1 overflow-auto">
+					<Table aria-label="Listings">
+						<TableBody>
+							{ROWS.map((l, i) => (
+								<TableRow key={l.id} data-state={open === i ? "selected" : undefined} tabIndex={0} onClick={() => setOpen(i)} onKeyDown={(e) => { if (e.key === "Enter") setOpen(i); }} className="cursor-default">
+									<TableCell className="font-medium text-ink">{l.role}</TableCell>
+									<TableCell className="text-ink-2">{l.location}</TableCell>
+									<TableCell><Badge variant={STATUS_VARIANT[l.status]} dot>{l.status}</Badge></TableCell>
+								</TableRow>
+							))}
+						</TableBody>
+					</Table>
+				</div>
+				{rec && (
+					<SidePanel
+						open={open !== null}
+						onOpenChange={(o) => !o && setOpen(null)}
+						mode={mode}
+						label="Listing details"
+						title={rec.role}
+						meta={<span className="flex items-center gap-2"><span className="font-mono">{rec.id}</span><Badge variant={STATUS_VARIANT[rec.status]} dot>{rec.status}</Badge></span>}
+						position={{ index: open ?? 0, total: ROWS.length }}
+						onPrevious={() => setOpen((o) => Math.max(0, (o ?? 0) - 1))}
+						onNext={() => setOpen((o) => Math.min(ROWS.length - 1, (o ?? 0) + 1))}
+						onOpenFull={() => {}}
+						footer={<Button size="sm">Edit listing</Button>}
+					>
+						<dl className="grid grid-cols-[120px_1fr] gap-x-3 gap-y-2 text-base">
+							<dt className="text-ink-2">Location</dt><dd className="text-ink">{rec.location}</dd>
+							<dt className="text-ink-2">Applicants</dt><dd className="tabular text-ink">{rec.applicants}</dd>
+							<dt className="text-ink-2">Closes</dt><dd><Timestamp value={`${rec.closes}T17:00:00Z`} format="absolute" /></dd>
+							<dt className="text-ink-2">Hiring manager</dt><dd><Button variant="link" size="xs">Add</Button></dd>
+						</dl>
+					</SidePanel>
+				)}
+			</div>
+		</div>
+	);
+}
+```
+
+## Related
+
+- App shell and sidebar navigation
+- Command palette (⌘K)
+- Confirmation dialog
+- Loading skeleton