@twoux/ui 0.0.0-stage → 0.1.0

package/agent/docs-md/chart-treemap.md

@@ -0,0 +1,98 @@
+# Treemap
+
+Parts of a total as nested rectangles sized by value: squarified so tiles stay readable, names only where they fit, and the tail folded into Other after 12 tiles.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- Showing which of many items make up most of a total, such as cloud spend by service.
+- A total with one level of grouping, where the groups matter as well as the items.
+
+## When not to use
+
+- To compare items precisely. Use the TwoUX Bar chart, because areas are read less exactly than lengths.
+- For five parts or fewer. Use the TwoUX Share bar.
+
+## Structure
+
+1. Title and subtitle
+2. Tiles sized by value, with 2px surface gaps
+3. Name and share inside tiles that can hold them
+4. Other tile in grey
+5. Legend of groups when there are two or more
+6. Tooltip: name, value, share, group
+
+## Guidelines
+
+- Keep to 12 tiles; the rest fold into a grey Other.
+- Use the squarified layout so tiles stay close to square and readable.
+- Without groups every tile is one colour; with groups each group takes its series colour and a legend. Never colour tiles by value.
+- Print a name only where it fits and a share only where there is room; never clip text.
+- Values go in the tooltip and the Table view.
+- Use ChartFrame for the four states: loading keeps the frame, an error says what failed with Try again, an empty period says so, and no match offers Clear filters.
+
+## Content
+
+- Short tile names; the full name is in the tooltip and table.
+- Subtitle gives the period and scope, such as October 2026, all projects.
+
+## Accessibility
+
+- 1.4.1 Use of Color: groups are named in the legend and the tooltip; every value is in the table.
+- 1.1.1 and WAI complex images: the chart has a short generated summary as its accessible name and a Table view with every value.
+- 2.1.1 Keyboard: the chart is one tab stop; arrow keys move between marks and show the same tooltip as hover.
+- 1.4.13 Content on Hover or Focus: the tooltip never covers the mark it describes, stays while the pointer is over the chart and closes with Esc.
+- Accessible description: "Treemap showing cloud spend by service, October 2026."
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Focus the chart |
+| ← → ↑ ↓ | Move to the previous or next mark and show its values |
+| Home End | Jump to the first or last mark |
+| Esc | Hide the tooltip |
+
+## Examples
+
+### cloud-spend
+
+```tsx
+import { ChartFrame, shareTable, Treemap } from "@twoux/ui";
+
+export const meta = { title: "Cloud spend by service", description: "Fifteen services in three groups: the twelfth tile onwards fold into Other. Names show only on tiles big enough to hold them.", order: 1 };
+
+const ITEMS = [
+	{ id: "vm", label: "Virtual machines", value: 48_200, group: "Compute" },
+	{ id: "k8s", label: "Kubernetes", value: 31_400, group: "Compute" },
+	{ id: "fn", label: "Functions", value: 6_900, group: "Compute" },
+	{ id: "gpu", label: "GPU instances", value: 22_800, group: "Compute" },
+	{ id: "obj", label: "Object storage", value: 18_600, group: "Storage" },
+	{ id: "block", label: "Block storage", value: 12_100, group: "Storage" },
+	{ id: "backup", label: "Backups", value: 5_400, group: "Storage" },
+	{ id: "pg", label: "Postgres", value: 19_700, group: "Data" },
+	{ id: "wh", label: "Warehouse", value: 15_300, group: "Data" },
+	{ id: "cache", label: "Cache", value: 4_200, group: "Data" },
+	{ id: "stream", label: "Streaming", value: 3_900, group: "Data" },
+	{ id: "search", label: "Search", value: 2_800, group: "Data" },
+	{ id: "dns", label: "DNS", value: 600, group: "Compute" },
+	{ id: "logs", label: "Log archive", value: 1_100, group: "Storage" },
+	{ id: "etl", label: "ETL jobs", value: 900, group: "Data" },
+];
+const gbp = (n: number) => `£${n.toLocaleString("en-GB")}`;
+
+export default function Example() {
+	return (
+		<ChartFrame className="w-full" title="Cloud spend by service" description="October 2026, all projects" table={shareTable(ITEMS, gbp, "Service")} height={260}>
+			<Treemap items={ITEMS} format={gbp} aria-label="Cloud spend by service, October 2026" />
+		</ChartFrame>
+	);
+}
+```
+
+## Related
+
+- Share bar
+- Bar chart
+- Donut chart

package/agent/docs-md/chart-waterfall.md

@@ -0,0 +1,93 @@
+# Waterfall chart
+
+How an opening amount becomes a closing amount: each increase and decrease floats from the running total, joined by connectors, with totals in grey from zero.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- Explaining how a balance or profit moved from one figure to another, such as cash flow for a month.
+- A bridge between two totals where each step matters, such as budget to actual.
+
+## When not to use
+
+- To show a series over time. Use the TwoUX Line chart card.
+- For parts of one total with no order. Use the TwoUX Share bar or Bar chart.
+
+## Structure
+
+1. Title and subtitle
+2. Y axis from zero (or below, when totals go negative)
+3. Total bars in grey from zero
+4. Increase and decrease bars floating from the running total
+5. Connector lines between bars
+6. Value labels with + or − where they fit
+7. Legend: increase, decrease, total
+8. Tooltip: change and running total
+
+## Guidelines
+
+- Increases and decreases take two categorical colours (c1 and c2), never green and red; the + or − on each label carries direction.
+- Totals are grey and start from zero, so they read as levels, not changes.
+- Join bars with thin connectors at the running total.
+- Print a value only where it fits; the tooltip and table always have it.
+- Order steps as the money moved: opening, money in, money out, closing.
+- Use ChartFrame for the four states: loading keeps the frame, an error says what failed with Try again, an empty period says so, and no match offers Clear filters.
+
+## Content
+
+- Use a real minus sign and a plus sign on every change; totals have no sign.
+- Name the legend by meaning (Money in, Money out, Balance), not by colour.
+
+## Accessibility
+
+- 1.4.1 Use of Color: direction is carried by the sign on each label, in the tooltip and in the table, not by colour.
+- 1.1.1 and WAI complex images: the chart has a short generated summary as its accessible name and a Table view with every value.
+- 2.1.1 Keyboard: the chart is one tab stop; arrow keys move between marks and show the same tooltip as hover.
+- 1.4.13 Content on Hover or Focus: the tooltip never covers the mark it describes, stays while the pointer is over the chart and closes with Esc.
+- Accessible description: "Waterfall chart showing cash flow for October 2026."
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Focus the chart |
+| ← → ↑ ↓ | Move to the previous or next mark and show its values |
+| Home End | Jump to the first or last mark |
+| Esc | Hide the tooltip |
+
+## Examples
+
+### cash-flow
+
+```tsx
+import { ChartFrame, Waterfall, type WaterfallStep, waterfallTable } from "@twoux/ui";
+
+export const meta = { title: "Cash flow for the month", description: "Opening balance, money in and money out, then the closing balance as a total. Grey totals, two categorical colours for in and out, a + or − on every change that fits.", order: 1 };
+
+const STEPS: WaterfallStep[] = [
+	{ id: "open", label: "Opening", value: 1_240_000, total: true },
+	{ id: "subs", label: "Subscriptions", value: 486_000 },
+	{ id: "services", label: "Services", value: 92_000 },
+	{ id: "payroll", label: "Payroll", value: -412_000 },
+	{ id: "hosting", label: "Hosting", value: -88_000 },
+	{ id: "rent", label: "Rent", value: -46_000 },
+	{ id: "vat", label: "VAT", value: -131_000 },
+	{ id: "close", label: "Closing", total: true },
+];
+const gbp = (n: number) => (Math.abs(n) >= 1_000_000 ? `£${(n / 1_000_000).toFixed(2)}m` : n === 0 ? "£0" : `£${Math.round(n / 1000)}k`);
+
+export default function Example() {
+	return (
+		<ChartFrame className="w-full" title="Cash flow" description="October 2026, all accounts" table={waterfallTable(STEPS, gbp)}>
+			<Waterfall steps={STEPS} format={gbp} labels={{ increase: "Money in", decrease: "Money out", total: "Balance" }} aria-label="Cash flow, October 2026" />
+		</ChartFrame>
+	);
+}
+```
+
+## Related
+
+- Bar chart
+- Bullet chart
+- Stat card with comparison

package/agent/docs-md/checkbox.md

@@ -0,0 +1,131 @@
+# Checkbox
+
+Lets people choose any number of options, or confirm one setting that is applied when they save.
+
+Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui
+
+## When to use
+
+- To pick any number of options from a list, including none.
+- To select table rows for bulk actions, with a header checkbox that selects all.
+- For a single setting in a form that is applied when the person saves: Show salary on listing.
+- As a parent with an indeterminate dash when only some children are selected.
+
+## When not to use
+
+- For one choice out of several. Use Radio.
+- For a setting that takes effect at once. Use Switch.
+- To switch the view of other content. Use Segmented control.
+
+## Structure
+
+1. Box (15px)
+2. Check or dash mark
+3. Label
+4. Hint (optional)
+5. Group label (for sets)
+
+## Guidelines
+
+- Box is 15px, 4px radius. Checked and indeterminate fill with primary.
+- The label is part of the click target. Clicking either toggles the box.
+- List options vertically, one per line. Horizontal only for two short options with clear spacing.
+- Indeterminate is visual only; clicking it selects all rows.
+- Opt-in checkboxes start unticked.
+
+## Content
+
+- Write labels positively: Accept CVs by email, not Don't accept CVs by email.
+- Keep labels short, sentence case, no end punctuation.
+- Group labels say what to choose: Columns to show.
+
+## Accessibility
+
+- Use a native input type="checkbox" with a label element. Space toggles it.
+- Parent checkboxes expose aria-checked="mixed" when partly selected.
+- Wrap related checkboxes in a fieldset with a legend, or role="group" with aria-labelledby.
+- The 15px box is below 24px, so the label is clickable and rows are 36px apart to meet target spacing.
+- Unchecked border and checked fill need 3:1 against white.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Space | Toggle the focused checkbox |
+| X | Select the focused table row (single-key shortcut, can be turned off) |
+| Shift+J / Shift+K | Extend row selection down or up |
+
+## Examples
+
+### select-all
+
+```tsx
+import { Checkbox } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Select all", description: "The parent shows indeterminate when only some rows are selected. Clicking it selects all; clicking again clears all.", order: 3 };
+
+const roles = ["Junior Product Designer", "Graduate Data Analyst", "Junior QA Engineer"];
+
+export default function Example() {
+	const [sel, setSel] = useState<string[]>([roles[0]]);
+	const all = sel.length === roles.length ? true : sel.length ? "indeterminate" : false;
+	return (
+		<div className="w-72 overflow-hidden rounded-sm border border-line bg-surface">
+			<label className="flex h-row cursor-pointer items-center gap-2.5 bg-surface-2 px-3 text-sm font-medium text-ink-2">
+				<Checkbox checked={all} onCheckedChange={() => setSel(all === true ? [] : roles)} aria-label="Select all listings" />
+				{sel.length ? `${sel.length} of ${roles.length} selected` : "Select all"}
+			</label>
+			{roles.map((r) => (
+				<label key={r} className="flex h-row cursor-pointer items-center gap-2.5 border-t border-line px-3 hover:bg-surface-2">
+					<Checkbox checked={sel.includes(r)} onCheckedChange={(v) => setSel((s) => (v ? [...s, r] : s.filter((x) => x !== r)))} />
+					{r}
+				</label>
+			))}
+		</div>
+	);
+}
+```
+
+### states
+
+```tsx
+import { Checkbox } from "@twoux/ui";
+
+export const meta = { title: "States", description: "Unchecked, checked, indeterminate (some children selected) and disabled. The box is 16px; its row is 24px so it is easy to hit.", order: 1 };
+
+export default function Example() {
+	return (
+		<div className="flex items-center gap-6">
+			<Checkbox aria-label="Unchecked" />
+			<Checkbox aria-label="Checked" defaultChecked />
+			<Checkbox aria-label="Some selected" checked="indeterminate" />
+			<Checkbox aria-label="Disabled" disabled />
+			<Checkbox aria-label="Disabled and checked" disabled defaultChecked />
+		</div>
+	);
+}
+```
+
+### with-label
+
+```tsx
+import { CheckboxField } from "@twoux/ui";
+
+export const meta = { title: "With label and hint", description: "The label is clickable and part of the target. A hint explains the consequence, not the control.", order: 2 };
+
+export default function Example() {
+	return (
+		<div className="grid gap-3">
+			<CheckboxField id="ex-salary" label="Show salary on listing" hint="Listings with a salary get about a third more applies." defaultChecked />
+			<CheckboxField id="ex-email" label="Accept CVs by email" />
+		</div>
+	);
+}
+```
+
+## Related
+
+- Radio
+- Switch
+- Form validation

package/agent/docs-md/choosing-selection-control.md

@@ -0,0 +1,71 @@
+# Choosing a selection control
+
+Pick the control from three questions: one choice or many, how many options, and does it apply at once or on Save.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** The same kind of choice ends up as a radio group on one form, a dropdown on another and a switch on a third, so people can't predict when a change takes effect.
+
+**Solution:** One choice from up to seven: radio. One choice from eight or more: select. Many from up to seven: checkboxes. Many from eight or more: multiselect. On or off with immediate effect: switch. On or off applied on Save: checkbox. Two to three view options: segmented control.
+
+**Built from:** Radio, Checkbox, Switch, Segmented control, Combobox, Text input
+
+## How it works
+
+1. One option or many? Many means checkboxes or a multiselect.
+2. How many options? Up to seven show all of them (radio or checkboxes); eight or more use a Combobox (combobox), with multiple for several.
+3. For on or off: does it take effect at once (switch) or when the form is saved (checkbox)?
+4. If both the on and off states need explaining, use two radio options with descriptions instead.
+
+## When to use
+
+- Radio: Work pattern on a listing (On-site, Hybrid, Remote (UK)).
+- Select: Location from the list of offices; multiselect: Skills from a long list.
+- Switch: "Email me when a listing closes" in notification settings, saved at once. Checkbox: "Offer visa sponsorship" in the Create listing form.
+
+## When not to use
+
+- Segmented control for a form value. It switches views or settings of what is shown, such as Daily or Weekly.
+- A switch inside a form with a Save button; people expect a switch to act at once.
+- Any selection control for a filter on a list page; filters use the filter pills.
+
+## Guidelines
+
+- When a choice reveals sub-options, use a different control for the parent than for the children: a checkbox that reveals radio options, not checkboxes inside checkboxes.
+- Place revealed sub-options after the whole radio group, never between two radio options.
+- Use the same parent control for the same kind of reveal everywhere on a page.
+- Order options logically: by frequency, by the order of the hiring process, or alphabetically for long lists.
+- Give options short descriptions only when they help people choose; keep the sentence structure the same across options.
+
+## Content
+
+- Switch labels describe the setting when on: "Email me when a listing closes".
+- Checkbox labels describe what ticking does: "Offer visa sponsorship".
+- When every option shares a subject, put it in the group label ("Work pattern") and keep options short.
+
+## Accessibility
+
+- Radio and checkbox groups are fieldsets with a legend that is the group label.
+- A switch uses role="switch" and announces on or off.
+- Revealed sub-options follow their parent in the focus order.
+
+## Do
+
+- Do show all options when there are seven or fewer.
+- Do use a switch only for changes that apply at once.
+- Do use radio options with descriptions when both on and off need explaining.
+
+## Don't
+
+- Don't hide three options in a dropdown.
+- Don't nest the same control type for parent and sub-options.
+- Don't put controls between radio options.
+
+## Related
+
+- Inline editing and validation
+- Filtering and search
+- Radio
+- Checkbox
+- Switch
+- Segmented control

package/agent/docs-md/citations-sources.md

@@ -0,0 +1,79 @@
+# Citations and sources
+
+Record IDs inline in answers that open the record, plus a Sources panel on the full page listing every record and file the answer used.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- Every claim about a record or figure in an answer or an AI column cell.
+- When an answer relies on a team file, cite the file.
+
+## When not to use
+
+- Generic wording with no factual claim. Do not add filler citations.
+- To label content as generated. Use the AI origin label (ai-origin-label).
+
+## Structure
+
+1. Inline citation (record ID, for example LST-1044)
+2. Sources panel (record rows, files)
+3. Highlight state on the cited source
+
+## Guidelines
+
+- Citations are record IDs that open the record, so checking takes one click.
+- In the panel, a citation focuses the row in the table; on the full page it highlights the source in the Sources panel.
+- Place citations at the end of the claim they support, consistently.
+- Say when a source is missing or stale rather than showing an empty state that implies success.
+- Point to the exact data used where possible (views, applies, period).
+
+## Content
+
+- Use the record's own ID format (LST-1044), not numbers like [1], so the citation is meaningful on its own.
+- Sources list title, ID and what was read.
+
+## Accessibility
+
+- Citations are links with an accessible name that includes the record, for example "LST-1044, Operations Coordinator" (SC 2.4.6, 4.1.2).
+- Do not signal citations by colour alone; use the chip shape (SC 1.4.1).
+- Moving focus to the cited row must keep that row visible (SC 2.4.11).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move to the next citation |
+| Enter | Open or highlight the cited record |
+
+## Examples
+
+### cite
+
+```tsx
+import { Citation, SourcesList } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Every claim names its record", description: "Citations are record IDs at the end of the claim. Selecting one highlights the source; on a list page it would focus the row.", order: 1 };
+
+const SRC = [{ id: "LST-1041", title: "Frontend Engineer", detail: "6 applicants · closes 21 Nov" }, { id: "LST-1044", title: "Customer Success Lead", detail: "3 applicants · closes 23 Nov" }];
+
+export default function Example() {
+	const [a, setA] = useState<string>();
+	return (
+		<div className="grid w-full max-w-2xl grid-cols-[1fr_240px] gap-4 max-md:grid-cols-1">
+			<p className="text-base text-ink">Two listings close this week with fewer than 10 applicants: Frontend Engineer <Citation id="LST-1041" active={a === "LST-1041"} onOpen={setA} /> and Customer Success Lead <Citation id="LST-1044" active={a === "LST-1044"} onOpen={setA} />.</p>
+			<SourcesList sources={SRC} active={a} onSelect={setA} />
+		</div>
+	);
+}
+```
+
+## Related
+
+- Assistant page
+- AI column
+- Team instructions and files
+- AI origin label
+- Confidence note
+- Why this choice

package/agent/docs-md/citing-sources.md

@@ -0,0 +1,63 @@
+# Citing sources
+
+Every claim in an answer links to the record it came from by ID; clicking opens the record in the side panel, and the full page lists every record used.
+
+Kind: pattern · Group: Patterns: AI
+
+**Problem:** People can't act on an answer they can't check, and generic "Sources" lists at the bottom don't say which claim came from where.
+
+**Solution:** Citations are record IDs (LST-1044) placed right after the claim. They open the record in the side panel. The full-page view adds a Sources panel listing every record and file the answer used, and highlights the one being cited.
+
+**Built from:** Citations and sources, Assistant side panel, Assistant page, Side panel (drawer), AI column, Team instructions and files
+
+## How it works
+
+1. Place the record ID straight after the sentence it supports.
+2. Hover or focus shows a preview: record title, the figure used, when it was updated.
+3. Click opens the record in the side panel next to the answer.
+4. When the answer relied on a team file, cite the file by name.
+5. Expanded to a full page, a Sources panel lists every record and file used, and citations highlight their source.
+
+## When to use
+
+- For every factual claim about workspace data in an answer, a generated cell or an agent step.
+
+## When not to use
+
+- To decorate an answer with sources that don't support a specific claim; that builds false trust.
+- For reasoning steps; those are progress, not evidence (see Showing reasoning and progress).
+
+## Guidelines
+
+- Cite at the claim, not in a list at the end, so people can tell sourced claims from synthesis.
+- Use descriptive citations (the record ID and title on hover), never "Source 1".
+- If a source is missing or deleted, say so openly instead of hiding the gap.
+- Keep citation style identical in answers, AI columns and agent runs.
+- Say what data the answer could not see, so people know when to rely on their own judgement.
+
+## Content
+
+- Citations use the record ID as it appears in the product: "LST-1044".
+- Sources panel heading: "Sources", each item with title, type and last updated.
+
+## Accessibility
+
+- Citations are links with accessible names that include the record title, not just the ID.
+- Citation previews open on focus as well as hover and close with Esc.
+
+## Do
+
+- Do link each claim to its record.
+- Do cite team files by name.
+
+## Don't
+
+- Don't list sources only at the bottom.
+- Don't show a citation that doesn't support the claim.
+
+## Related
+
+- Ask about what's on screen
+- Labelling AI output
+- Generated table columns and enrichment
+- Citations and sources

package/agent/docs-md/clarify-before-acting.md

@@ -0,0 +1,69 @@
+# Clarifying before acting
+
+When the answer would change the result, ask with a question card above the composer: options with a recommended default, number keys, Skip and Next.
+
+Kind: pattern · Group: Patterns: AI
+
+**Problem:** An assistant that guesses rewrites the wrong listings; one that asks too much becomes a form. Without a rule, each feature decides differently when to ask.
+
+**Solution:** Ask only when the answer changes the result, at most three questions, one at a time. Each has a recommended option first, a one-line explanation per option, and "Use defaults" to skip the rest.
+
+**Built from:** Clarifying question card, Assistant side panel, Message composer, Radio, Agent run timeline
+
+## How it works
+
+1. Before acting, check whether the request is ambiguous in a way that changes the outcome (which listings, which period, who receives it).
+2. If yes, show the question card docked above the composer: "1 / 2", the question, then options.
+3. Options have a title and one line each, the recommended one first and marked, Other last with free text.
+4. Number keys 1 to 4 pick an option; Previous, Skip and Next ↵ move through the questions.
+5. The thread shows "Waiting for your answer" with a timer; in an agent run the step is marked Needs you and appears in the Inbox.
+6. Once answered, the card collapses into a one-line summary of the choice, and the work continues.
+
+## When to use
+
+- When the request is ambiguous and the action is costly to get wrong.
+- When an agent hits a decision it is not allowed to make alone.
+
+## When not to use
+
+- When the answer can be inferred from context chips or retrieved from data; don't ask what you already know.
+- For low-stakes answers; answer first and offer follow-ups instead.
+- For approving a concrete change; use Propose then apply.
+
+## Guidelines
+
+- At most three questions per request, one at a time.
+- Every question has a default and "Use defaults" skips the rest.
+- Options before free text; the composer stays available for anything the options miss.
+- Say why the answer matters in the option's line ("Leaves listings that are doing well alone").
+- An unanswered question never blocks forever; in a scheduled run it expires and the run reports that nothing ran.
+- Ask first when the stakes are high or confidence is low; otherwise answer for the common case and offer follow-up options to narrow it.
+- If the person may not know the answer, say where to find it: "Salary bands are in Team files" with a link.
+- Values needed to carry out an action (dates, amounts) are not clarifying questions; use an input card (see Asking for details inside the answer).
+
+## Content
+
+- Questions are short and specific: "Which titles should I rewrite?"
+- Mark the default "(Recommended)" in text, not only with a colour.
+
+## Accessibility
+
+- Options are a radio group: arrows move, Space or the number key selects, Enter goes to Next.
+- Focus moves into the card when it appears and returns to the composer when it closes.
+
+## Do
+
+- Do put the recommended option first.
+- Do let people skip with defaults.
+
+## Don't
+
+- Don't ask more than three questions.
+- Don't ask for information already in context.
+
+## Related
+
+- Ask about what's on screen
+- Agents acting on your behalf
+- Propose, then apply
+- Clarifying question card