@twoux/ui 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,116 @@
+# Items palette
+
+A searchable list, in a side panel beside a configurable dashboard, of the items a person can add, each with a title, a short description, its type and an Add to dashboard button.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- With a configurable dashboard, to add items that are not on the board yet.
+- As the place removed items return to, so people can add them back.
+- When new item types ship, so people find them without a layout being changed for them.
+
+## When not to use
+
+- On a static dashboard. There is nothing to add.
+- To pick records or templates. Use the command palette or the templates gallery.
+- To change what an item on the board shows. Use Preferences in that item's menu.
+
+## Structure
+
+1. Panel header: "Add items", item count and close
+2. Search field that filters by title and description
+3. Palette item: drag handle, title, one-line description, type tag (Chart, List, Key metrics), Add to dashboard button
+4. Zero results: message with Clear search
+5. Empty palette: "All items are on your dashboard"
+
+## Guidelines
+
+- List only items that are not on the board. When one is added it leaves the palette; when it is removed it comes back.
+- Palette items describe; they do not preview. No live numbers, charts or menus, only title, description and type.
+- Every palette item has an Add to dashboard button as well as its drag handle. The button adds the item at the end of the board in its default size. Keyboard users add with the button, then place the item with the board's own keyboard move; there is no separate keyboard drag from the palette.
+- While dragging, the palette item takes the shape of its default size on the board and shows a drop preview.
+- Add search once there are more than about ten items, and show a zero results message with Clear search.
+- The panel pushes the board, stays open while people add several items, and closes with Esc or Add items again.
+
+## Content
+
+- Descriptions say what the item answers: "Applications per week for the last 12 weeks, compared with the previous period."
+- Type tags use one word or two: Chart, List, Key metrics, Links, Alerts.
+- Zero results: "No items match \"cost\"." with Clear search.
+
+## Accessibility
+
+- The panel is a complementary region labelled "Add items"; focus moves to its search field when it opens and returns to Add items when it closes.
+- Add to dashboard is named with the item: "Add Applications this week to dashboard".
+- After an add, announce "Applications this week added to the end of the dashboard" and keep focus in the palette on the next item.
+- Dragging from the palette is never required; the button covers the same result with a single action.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab / Shift+Tab | Move between search, palette items and their Add buttons |
+| Enter (Add button) | Add the item to the end of the board |
+| Esc | Cancel a pick-up, or close the panel |
+| Then, on the board | Use the new item's handle (Enter, arrows, Enter) or its menu to move it |
+
+## Examples
+
+### add-items
+
+```tsx
+import { Board, BoardItem, type BoardItemData, Button, ItemsPalette, type PaletteItem, SidePanel, StatCompare, toast } from "@twoux/ui";
+import { Plus } from "lucide-react";
+import { useState } from "react";
+
+export const meta = { title: "Add items to a dashboard", description: "The palette lists only what isn't on the board. Add puts an item at the end in its default size; drag drops it where you let go. Removing an item returns it to the palette.", order: 1 };
+
+const CATALOGUE: PaletteItem[] = [
+	{ id: "apps", title: "Applications this month", description: "Total applications and change against last month", type: "Key metrics" },
+	{ id: "tth", title: "Median time to hire", description: "Days from opening a listing to an accepted offer", type: "Key metrics" },
+	{ id: "accept", title: "Offer acceptance", description: "Share of offers accepted this quarter", type: "Key metrics" },
+	{ id: "closing", title: "Closing this week", description: "Listings that close in the next 7 days", type: "List" },
+];
+const VALUES: Record<string, [string, string, string, boolean]> = { apps: ["595", "+12%", "October", true], tth: ["23 days", "-4 days", "last quarter", true], accept: ["71%", "-6 pts", "last quarter", false] };
+
+export default function Example() {
+	const [items, setItems] = useState<BoardItemData[]>([{ id: "apps", title: "Applications this month" }]);
+	const [open, setOpen] = useState(true);
+	const palette = CATALOGUE.filter((c) => !items.some((i) => i.id === c.id));
+	const add = (id: string, at = items.length) => {
+		const c = CATALOGUE.find((x) => x.id === id);
+		if (!c) return;
+		setItems((x) => { const n = [...x]; n.splice(at, 0, { id, title: c.title }); return n; });
+		toast.success(`Added ${c.title}`);
+	};
+	return (
+		<div className="flex h-104 w-full overflow-hidden rounded-sm border border-line bg-bg">
+			<div className="min-w-0 flex-1 overflow-auto p-3">
+				<div className="mb-2 flex justify-end"><Button variant="outline" size="sm" onClick={() => setOpen(true)}><Plus />Add items</Button></div>
+				<Board
+					items={items}
+					onItemsChange={setItems}
+					onAddFromPalette={add}
+					empty={<p className="rounded-sm border border-dashed border-line-strong p-8 text-center text-base text-ink-2">Drag an item here, or use Add.</p>}
+					renderItem={(it) => (
+						<BoardItem id={it.id} header={it.title}>
+							{VALUES[it.id] ? <StatCompare label="" value={VALUES[it.id][0]} change={VALUES[it.id][1]} period={VALUES[it.id][2]} good={VALUES[it.id][3]} /> : <p className="text-sm text-ink-2">Frontend Engineer · Fri 21 Nov</p>}
+						</BoardItem>
+					)}
+				/>
+			</div>
+			<SidePanel open={open} onOpenChange={setOpen} label="Add items" title="Add items" meta={`${palette.length} available`}>
+				<ItemsPalette items={palette} onAdd={(id) => add(id)} />
+			</SidePanel>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Board and board item
+- Configurable dashboard
+- Dashboard items
+- Side panel (drawer)

package/agent/docs-md/keyboard-model.md

@@ -0,0 +1,47 @@
+# Keyboard model
+
+TwoUX is built to be driven from the keyboard. ⌘K runs any command, ⌘J opens the assistant, ? shows every shortcut, J and K move through lists, and Esc always closes the innermost layer first.
+
+Kind: foundation · Group: Key principles
+
+## Principles
+
+- Shortcuts are accelerators, not the only path. Everything is also reachable by Tab and by the command menu. APG: do not use shortcuts as a substitute for navigation.
+- Few, mnemonic, and familiar. APG warns that too many shortcuts add cognitive load and recommends mnemonics and known conventions.
+- Discoverable. Shortcuts are shown in tooltips, menus and buttons as keycaps, so people learn them where they already look.
+- Can be turned off. Single-key shortcuts have a switch; ⌘ shortcuts stay on.
+
+## Guidelines
+
+- Global: ⌘K command menu; ⌘J ask the assistant; ? shortcut sheet; / search this view; G then L go to listings; G then P go to pipeline; ⌘Z undo last action.
+- Lists: J next row, K previous row, X select, ⇧J extend selection, ↵ open in side panel, ⇧↵ open as full page, ⇧P toggle side by side.
+- Actions on the current row or selection: C new listing, E edit, F add filter, T extend 30 days, D duplicate, ⇧E export, ⇧V columns.
+- Destructive actions need Shift: ⇧C close listing. Shift keeps a stray keypress from doing harm, and the toast offers Undo.
+- Inside popovers, menus and the command menu: ↑ and ↓ move, ↵ chooses, Tab changes scope or moves, Esc closes.
+- Esc order, innermost first: 1. open popover or menu; 2. assistant sub-menus and history; 3. the assistant panel; 4. the side panel; 5. clear the row selection. One press closes one layer, and focus returns to what opened it.
+- No browser or OS conflicts: avoid ⌘ plus a single key that the browser owns (find, refresh, bookmarks) and modifier combinations with Tab, Enter, Space or Escape.
+- Single-key shortcuts are ignored while focus is in a text field.
+
+## Accessibility
+
+- 2.1.4: single-character shortcuts can be turned off in the shortcut sheet ('Turn off if you use a screen reader or voice control').
+- All functionality is available through the keyboard, with or without shortcuts.
+- J and K move a visible focus or active-row indicator and scroll the row into view.
+- The focused row stays visible when the side panel or bulk bar is open.
+
+## Do
+
+- Show the keycap in the button or tooltip for any action that has a shortcut.
+- Add new shortcuts to the shortcut sheet and the command menu at the same time.
+
+## Don't
+
+- Do not bind a destructive action to a single unshifted key.
+- Do not override ⌘S, ⌘F, ⌘L or ⌘R.
+- Do not make Esc close more than one layer at a time.
+
+## Related
+
+- Accessibility
+- Consistency
+- Layout

package/agent/docs-md/keyboard-navigation.md

@@ -0,0 +1,68 @@
+# Keyboard-first navigation
+
+Every action has a key shown on its button. J/K move, Enter opens, Esc steps back one layer at a time, ⌘K runs anything, ⌘J asks the assistant.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** Power users triage hundreds of rows a day. If shortcuts differ per screen, or Esc sometimes closes a panel and sometimes clears a selection, people stop trusting the keyboard.
+
+**Solution:** One keyboard model across TwoUX: the same keys mean the same thing everywhere, shortcuts are shown on buttons, ? opens the full list, and single-key shortcuts can be turned off.
+
+**Built from:** Command palette (⌘K), Shortcut sheet (?), Keyboard shortcut hint, List table, Side panel (drawer), Assistant side panel, Inbox (triage)
+
+## How it works
+
+1. J and K move the row focus; X selects; ⇧J extends the selection.
+2. Enter opens the focused row in the side panel; ⇧↵ opens the full page.
+3. Esc closes the top-most layer only, in this order: open menu or popover, then text field edit, then dialog, then side panel, then selection.
+4. ⌘K opens the command palette: actions on the current selection first, then Go to. ↑↓ move, ↵ runs, Tab changes scope.
+5. ⌘J opens the assistant with the current selection and filters as context.
+6. ? opens the shortcut sheet, which also holds the switch for single-key shortcuts.
+
+## When to use
+
+- On every screen. A new action is not finished until it has a key, a place in ⌘K and a hint on its button.
+
+## When not to use
+
+- Don't add single-key shortcuts inside text fields or the composer; there the keys type text.
+- Don't make a shortcut the only path to an action; every action is also a visible control.
+
+## Guidelines
+
+- Show the shortcut on the button or menu item itself so people learn it by using the product.
+- Keep the set small and mnemonic: C create, E edit, F filter, T extend, D duplicate.
+- Avoid ⌘ plus a single key that the browser or OS owns, except deliberate, well-used ones such as ⌘K.
+- Single-key shortcuts can be turned off; ⌘ shortcuts stay on.
+- Focus is always visible and never lost to the page body when a row or panel disappears.
+- Use the same keys as tools people already know (J/K, ⌘K) instead of inventing new ones.
+
+## Content
+
+- Hints use symbols: ⌘K, ⇧↵, Esc. Shown in a muted key cap after the label.
+- The shortcut sheet groups keys by Navigate, Table and Act.
+
+## Accessibility
+
+- Everything works by keyboard alone.
+- Lists use roving tabindex so Tab enters and leaves a list in one step and arrows move inside it.
+- Single-character shortcuts can be turned off for screen reader and voice control users.
+- Closing a layer returns focus to the element that opened it.
+
+## Do
+
+- Do keep Esc's order the same on every screen.
+- Do list every shortcut in ? and in ⌘K.
+
+## Don't
+
+- Don't let one Esc press close two layers.
+- Don't reuse a key for different actions on different pages.
+
+## Related
+
+- Record detail: side panel, overlay or full page
+- Selection and bulk actions
+- Ask about what's on screen
+- Command palette (⌘K)
+- Shortcut sheet (?)

package/agent/docs-md/keyboard-shortcut-hint.md

@@ -0,0 +1,87 @@
+# Keyboard shortcut hint
+
+Prints the key or keys that run an action, on its button, menu item or tooltip, so people learn shortcuts by using the product.
+
+Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui
+
+## When to use
+
+- On buttons and menu items whose action has a shortcut: Try again R, Edit E.
+- In tooltips of icon-only buttons.
+- In the command palette, the ? shortcut sheet and footers that list navigation keys.
+
+## When not to use
+
+- For shortcuts that do not work in the current context. Leave the hint out.
+- As the only way to reach an action. Every shortcut duplicates a visible control.
+- Inside body text as decoration. Use plain text such as press Esc.
+
+## Structure
+
+1. Key cap (18px, mono 10.5px)
+2. Further key caps for chords or sequences
+
+## Guidelines
+
+- Key cap is 18px high, 4px radius, 2px bottom border, grey surface. On buttons it shrinks to 16px and sits after the label.
+- On primary buttons the cap is translucent white so it keeps contrast on primary.
+- Chords show keys side by side (⌘ K); sequences show them in order (G then L).
+- Render ⌘ on Mac and Ctrl elsewhere.
+- Reserve shortcuts for frequent actions; keep them to one or two keys and never override copy, paste or undo.
+
+## Content
+
+- Use symbols for modifiers and capitals for letters: ⌘, ⇧, ↵, Esc, E.
+- Use mnemonic keys: E for Edit, C for Create, F for Filter.
+- The same action keeps the same key everywhere.
+
+## Accessibility
+
+- Single-key shortcuts (J, K, X, E, /) can be turned off in the shortcut sheet; ⌘ shortcuts stay on.
+- Shortcuts avoid keys used by screen readers, such as Caps Lock and Insert combinations.
+- The hint is visual. The full list is in the ? sheet so assistive technology users can find it.
+- Every action also works by Tab and Enter.
+- Key cap text has at least 4.5:1 contrast on its background.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| ⌘K | Open the command palette |
+| ? | Open the shortcut sheet |
+| G then L | Go to listings |
+| J / K | Next or previous row |
+| C | New listing |
+| E | Edit |
+
+## Examples
+
+### keys
+
+```tsx
+import { Kbd } from "@twoux/ui";
+
+export const meta = {
+	title: "Keys",
+	description: "One Kbd per key. Use symbols for modifiers: ⌘ ⇧ ⌥ ↵.",
+	order: 1,
+};
+
+export default function Example() {
+	return (
+		<dl className="grid grid-cols-[auto_1fr] items-center gap-x-6 gap-y-2">
+			<dd className="flex gap-0.5"><Kbd>⌘</Kbd><Kbd>K</Kbd></dd><dt className="text-ink-2">Search or run a command</dt>
+			<dd className="flex gap-0.5"><Kbd>J</Kbd><Kbd>K</Kbd></dd><dt className="text-ink-2">Next and previous row</dt>
+			<dd className="flex gap-0.5"><Kbd>⇧</Kbd><Kbd>H</Kbd></dd><dt className="text-ink-2">Snooze</dt>
+			<dd className="flex gap-0.5"><Kbd>Esc</Kbd></dd><dt className="text-ink-2">Close</dt>
+		</dl>
+	);
+}
+```
+
+## Related
+
+- Button
+- Dropdown menu
+- Tooltip
+- Switch

package/agent/docs-md/keyboard-shortcut-sheet.md

@@ -0,0 +1,90 @@
+# Shortcut sheet (?)
+
+A panel listing every shortcut by task, opened with ?, which also holds the switch to turn single-key shortcuts off.
+
+Kind: component · Group: Navigation · Status: built, import from @twoux/ui
+
+## When to use
+
+- Reference for people who want to learn the faster path after using the visible controls.
+- The single place to turn single-key shortcuts off.
+- Supporting expert users who already rely on shortcuts and want the full list in one view.
+
+## When not to use
+
+- As the main way to discover shortcuts. Show each key on its button, menu item and palette row.
+- Searching for an action to run. Use the Command palette.
+
+## Structure
+
+1. Toggle: Single-key shortcuts, with the note "Turn off if you use a screen reader or voice control. ⌘ shortcuts stay on."
+2. Group: Navigate (⌘K, G L, G P, /)
+3. Group: Table (J K, X, ⇧J, ↵)
+4. Group: Act (C, E, F, ⌘Z)
+5. Each row: action name left, key caps right
+
+## Guidelines
+
+- Opens with ? from anywhere outside a text field, and from the Help menu.
+- Group shortcuts by task, a handful per group, so the sheet can be scanned.
+- Single-key shortcuts (C, E, F, J, K, X, R, G sequences) can be turned off; ⌘ shortcuts stay on.
+- Single-key shortcuts never fire while focus is in a text input.
+- Avoid keys that clash with the browser, the operating system or screen readers, and never override copy, paste or save.
+- Prefer one or two letters with a mnemonic (C create, E edit, F filter) over stacked modifiers.
+
+## Content
+
+- Action names match the button labels they belong to.
+- Show keys as the symbols printed on the keyboard (⌘, ⇧, ↵) and give the Windows equivalent.
+- The off switch says who it is for in plain words.
+
+## Accessibility
+
+- Meets 2.1.4 Character Key Shortcuts by letting people turn single-key shortcuts off.
+- Every shortcut is an extra route; the same action is reachable by Tab and Enter (2.1.1).
+- Shown as a modal dialog with a heading; Esc closes it and focus returns (2.4.3).
+- The toggle is a real switch with its state exposed (4.1.2).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| ? | Open the shortcut sheet |
+| Esc | Close it |
+| Tab | Reach the single-key shortcut switch |
+
+## Examples
+
+### sheet
+
+```tsx
+import { Button, ShortcutSheet } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Every shortcut, by task", description: "Press ? anywhere outside a text field. The switch at the top turns single-key shortcuts off for screen reader and voice control users; ⌘ shortcuts stay on.", order: 1 };
+
+export default function Example() {
+	const [single, setSingle] = useState(true);
+	return (
+		<div className="grid justify-items-start gap-2">
+			<Button variant="outline" onClick={() => document.dispatchEvent(new KeyboardEvent("keydown", { key: "?" }))}>Show shortcuts (?)</Button>
+			<span className="text-sm text-ink-2">Single-key shortcuts are {single ? "on" : "off"}.</span>
+			<ShortcutSheet
+				singleKeys={single}
+				onSingleKeysChange={setSingle}
+				groups={[
+					{ title: "Navigate", items: [{ keys: ["⌘", "K"], action: "Search or run a command" }, { keys: ["G", "L"], action: "Go to Listings" }, { keys: ["G", "I"], action: "Go to Inbox" }, { keys: ["/"], action: "Search this list" }] },
+					{ title: "Table", items: [{ keys: ["J"], action: "Next row" }, { keys: ["K"], action: "Previous row" }, { keys: ["X"], action: "Select row" }, { keys: ["↵"], action: "Open in side panel" }] },
+					{ title: "Act", items: [{ keys: ["C"], action: "New listing" }, { keys: ["F"], action: "Add a filter" }, { keys: ["⌘", "Z"], action: "Undo" }] },
+				]}
+			/>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Command palette (⌘K)
+- App shell and sidebar navigation
+- Page header

package/agent/docs-md/labelling-ai-output.md

@@ -0,0 +1,66 @@
+# Labelling AI output
+
+Mark generated content with one small origin mark next to it. No AI colour, no sparkle on every button, no "AI-powered" copy.
+
+Kind: pattern · Group: Patterns: AI
+
+**Problem:** People need to know which values a model wrote before they rely on them. But products that colour and sparkle every AI feature teach people to ignore the marks, and each team styles them differently.
+
+**Solution:** Generated content carries the origin mark and a line such as "Assistant · from your workspace data". Generated cells get the mark and a faint neutral tint and show when they were written. Buttons that start AI work look like every other button.
+
+**Built from:** AI origin label, AI column, Assistant side panel, Suggested changes, Export menu, Colours
+
+## How it works
+
+1. Put the origin mark next to the generated output itself: under an answer, in a generated column header, on a drafted field.
+2. When a whole group is generated, label the group header once instead of every item.
+3. Say what produced it and from what: "Assistant · from your workspace data".
+4. When a person edits a generated value, it becomes theirs and the mark goes; the original stays in history.
+5. Exports name generated columns so they are never mistaken for real data.
+
+## When to use
+
+- For any value, text or chart the assistant or an agent produced that a person has not yet edited.
+
+## When not to use
+
+- On buttons and entry points. Name the action instead ("Ask", "Suggest titles").
+- For non-generative automation such as rules or sorting.
+
+## Guidelines
+
+- One mark, used only for generated output, never as decoration.
+- No separate AI colour. The tint on generated cells is a neutral surface so status and data colours keep their meaning.
+- Label the action, not the technology: "Summarised from 12 notes" beats "AI-generated".
+- Pair the mark with a way to see why: hovering it shows the sources and when it was written.
+- Feedback (good, bad) sits under every answer next to the mark.
+- The origin label is only for generative output. Rule-based automation (auto-close on expiry, duplicate detection) says what rule did it instead: "Closed automatically on 6 Dec".
+- The more control an action hands over, the clearer its label before it runs: "Runs as Listings checker · changes need approval" on a scheduled task.
+- If the whole surface is the assistant, don't repeat the mark on every part. The answer row carries it once.
+
+## Content
+
+- Use "Assistant" as the name. Avoid "magic", "smart" and "AI-powered".
+- Mark text is short: "Assistant · 2 min ago".
+
+## Accessibility
+
+- The mark has a text label for screen readers ("Written by Assistant"); it is not only an icon or a tint.
+- The tint meets contrast for the text on it.
+
+## Do
+
+- Do label generated output close to where it appears.
+- Do remove the mark once a person has edited the value.
+
+## Don't
+
+- Don't give AI features their own colour or gradient.
+- Don't add a sparkle to every button that calls a model.
+
+## Related
+
+- Citing sources
+- Generated table columns and enrichment
+- Ask about what's on screen
+- AI origin label

package/agent/docs-md/layout.md

@@ -0,0 +1,47 @@
+# Layout
+
+One app shell for the whole product: a 224px side navigation on the grey --bg, and an inset white canvas where the work happens. Record details open in a side panel that overlays by default and can push the list aside. Below 860px the shell collapses to one column.
+
+Kind: foundation · Group: Visual foundation
+
+## Principles
+
+- One shell, every screen. A product uses only one app layout; TwoUX has one, so navigation never moves.
+- Familiar beats novel. A left nav with a central canvas is the layout people already know from other work tools.
+- Keep the list in view. Opening a record should not lose the user's place in the list; a split view shows item details next to the collection.
+- Design for widths, not devices. Don't design for specific screen sizes or devices.
+
+## Guidelines
+
+- Shell: .app is a two-column grid, side nav 224px and canvas 1fr, on --bg. The canvas is --surface with 8px margin, a 1px --line border and --r-lg corners, so the work area reads as one sheet inset in the chrome.
+- Canvas anatomy, top to bottom: a 44px top bar (breadcrumb, Ask ⌘J, command search ⌘K), the page header (h1 at --t-2xl and up to two actions), then content. Repeated across every view in the same order.
+- Side panel, overlay (default): 440px, slides over the right of the canvas, below the top bar. Use it to peek at a record while moving through the list with J and K. It suits tables with few important columns.
+- Side panel, push (side by side, ⇧P): the page gets a right margin so the list and panel sit together without overlap. Use it when comparing a record with its neighbours or when the hidden columns matter. People can change the panel position, and TwoUX remembers the choice.
+- Full page (Open, ⇧↵): for editing and long reading. Modal dialogs are only for short, blocking decisions such as confirming a close.
+- Breakpoints: at 860px and below the side nav hides and grids go to one column; at 1100px and above wide dashboard tiles may span two columns. Components also use 560, 640 and 760px; these should be folded into the two shell breakpoints.
+- Reading width: AI answers and long descriptions are capped near 80 characters even on wide canvases.
+
+## Accessibility
+
+- An overlay panel must not entirely cover the focused element; when a row behind the panel has focus, scroll it clear or switch to push.
+- At 320 CSS px wide the page reflows to one column; data tables may scroll inside their own container.
+- Navigation keeps the same relative order on every page.
+- Moving focus into the panel on open and back to the row on close keeps focus order meaningful.
+
+## Do
+
+- Use the shell component for every route, including settings and the assistant.
+- Open records in the side panel from lists; open them as a page from links elsewhere.
+
+## Don't
+
+- Do not build a second layout for one feature.
+- Do not use a modal to show record details.
+- Do not let an overlay panel cover the selected row.
+
+## Related
+
+- Content density
+- Keyboard model
+- Shape and elevation
+- Spacing