@twoux/ui 0.0.0-stage → 0.1.0

package/agent/docs-md/data-vis-colours.md

@@ -0,0 +1,76 @@
+# Data visualisation colours
+
+One categorical palette of eight colours in a fixed order, one single-hue ordinal ramp of five steps, and a hard rule that status colours never become a series. Validated on white (#ffffff) with an OKLab and colour vision deficiency (CVD) simulator; every colour reaches at least 3:1.
+
+Kind: foundation · Group: Visual foundation
+
+## Principles
+
+- Fixed order, always. Series take --c1, --c2, --c3 and so on in sequence, so 'Applications' is the same colour in every chart on a page. The categorical palette is applied strictly in sequence and stays consistent across charts.
+- Every mark is visible. All eight categorical colours reach at least 3:1 on white, the WCAG minimum for graphical objects needed to understand a chart.
+- No palette is colour-blind safe. There is no such thing as a true colour-blind safe palette, so colour is never the only way to tell series apart.
+- Status is not data. --ok, --warn and --bad keep their meaning; a series that happens to be 'bad' news is still drawn in its categorical slot.
+
+## When to use
+
+- Categorical (--c1 to --c8): unordered groups such as source (job board, referral, careers site) or listing type. Up to about eight series for line and bar charts.
+- Ordinal ramp (--q1 to --q5): ordered buckets such as days open (0 to 7, 8 to 14...) or match score bands, and sequential heatmaps. More means more contrast with the surface: darker in the light theme, brighter in the dark theme, with a sequential palette for each theme.
+
+## When not to use
+
+- Do not use data colours for buttons, badges, tags or any UI element.
+- Do not use more than three categorical colours in a scatter plot or categorical heatmap; fold the rest into 'Other' or split into small multiples.
+- Do not use pie or donut charts for more than about five slices.
+
+## Guidelines
+
+- Why this order: adjacent pairs were ordered to stay apart. Worst adjacent difference under normal vision is OKLab ΔE 18.0; worst adjacent difference under simulated CVD is ΔE 10.0 (protan, --c3 teal against --c2 orange). Neighbours in a legend or stacked bar are the pairs people compare most, so adjacency is what the order optimises.
+- Why only three for scatter and heatmaps: in those forms any colour can sit next to any other, so all pairs matter, not just neighbours. Only --c1, --c2 and --c3 pass the all-pairs check; from the fourth colour some pair falls too close under CVD.
+- Why one hue for the ramp: --q1 to --q5 are indigo with lightness falling monotonically, so order reads from lightness alone, which survives CVD and greyscale print. One hue also means the ramp cannot be mistaken for categorical series.
+- Limit of the ramp: --q1 is 2.23:1 on white, below 3:1. The lightest bucket must carry a value label or sit inside a bordered cell, so understanding never depends on seeing it.
+- Separate touching segments (stacked bars, pies) with a 2px --surface gap so edges do not rely on hue difference.
+- Charts sit on --surface (#ffffff), the background the palette was validated on. Do not place charts on --bg or tinted cards.
+- Every chart has a legend or direct labels, and a table view of the same data.
+
+## Accessibility
+
+- 3:1 is required for the parts of a chart needed to understand it. When the values are also printed as text, the marks themselves are exempt, which is how --q1 stays usable.
+- Colour is never the only cue: use direct labels, a legend in series order, and patterns or markers where lines cross.
+- CVD was checked with simulation; the worst adjacent case is protan. Simulation models such as Machado et al. are a check, not a guarantee; about 200 million people have some CVD.
+- Offer a 'View as table' toggle on every chart so screen reader and keyboard users get the same data.
+
+## Do
+
+- Assign series in order and keep a series on the same colour across every chart in a view.
+- Fold small categories into 'Other' (drawn in --ink-3) rather than reaching for a ninth colour.
+- Label the lightest ordinal bucket with its value.
+
+## Don't
+
+- Do not use --ok green for 'hired' and --bad red for 'rejected' in a chart; use categorical slots and say the meaning in the legend.
+- Do not use colour for decoration, or give different colours to points in the same series.
+- Do not reorder or skip palette colours to make a chart look nicer.
+
+## Tokens
+
+| Token | Value | Use |
+|---|---|---|
+| `--c1` | `#5753e0` | Series 1, indigo (5.65:1) |
+| `--c2` | `#e0602b` | Series 2, orange (3.57:1) |
+| `--c3` | `#00897b` | Series 3, teal (4.32:1) |
+| `--c4` | `#a87000` | Series 4, ochre (4.21:1) |
+| `--c5` | `#cc4a7a` | Series 5, magenta (4.35:1) |
+| `--c6` | `#008300` | Series 6, green (4.95:1) |
+| `--c7` | `#2a78d6` | Series 7, blue (4.42:1) |
+| `--c8` | `#d93f3e` | Series 8, red (4.44:1) |
+| `--q1` | `#a9a6f3` | Ordinal lowest (2.23:1, needs a label) |
+| `--q2` | `#7f7beb` | Ordinal 2 (3.54:1) |
+| `--q3` | `#5753e0` | Ordinal midpoint (5.65:1) |
+| `--q4` | `#3d39b0` | Ordinal 4 (8.71:1) |
+| `--q5` | `#24226f` | Ordinal highest (13.7:1) |
+
+## Related
+
+- Colours
+- Accessibility
+- Design tokens

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

@@ -0,0 +1,76 @@
+# Data visualisation
+
+Start from the question the person is asking, pick the one chart that answers it, give it a noun title, units and a period, and ship it with a table view and its four states.
+
+Kind: pattern · Group: Patterns: data and dashboards
+
+**Problem:** Hiring leads open dashboards to answer a few questions: is volume going up, did something break, how do teams compare, why did this week drop. When charts are picked for looks, or each team invents its own axis and colour habits, people misread them or stop trusting them.
+
+**Solution:** Name the objective first (trend, anomaly, comparison, investigation), then choose the chart from a fixed table, show the fewest series that answer it, and finish it the same way every time: noun title, period, one y-axis, colours in order, table view, accessible name and the four states.
+
+**Built from:** Line chart card, Bar chart, Stacked area chart, Bar and line chart, Donut chart, Scatter chart, Heatmap, Funnel, Stat card with comparison, Breakdown table, Data visualisation colours, Board and board item
+
+## How it works
+
+1. Write the question in one line, then tag it: trend over time, spotting something unusual, comparing groups, or investigating a known problem.
+2. Choose the chart: change over time is a line; amounts per category or period are bars; parts of a total over time are a stacked area; two to five parts at one moment are a donut; ordered stages are a funnel; two measures across records are a scatter; one number is a stat card.
+3. Show the fewest series that answer the question: up to eight lines or bars, four on a bar and line chart, five parts on a donut. Past that, fold into "Other" or add a series filter.
+4. Finish the chart: noun title, period subtitle, axis titles with units, one y-axis, legend only for two or more series, categorical colours in order.
+5. Add the table view and the accessible name and description.
+6. Build the four states: loading, empty, no match and error.
+
+## When to use
+
+- Whenever a screen shows numbers that people read as a shape: trends, comparisons, splits.
+- On dashboards and report pages, and in a record's detail when history matters, such as applications per day for a listing.
+
+## When not to use
+
+- For decoration or to fill space. If nobody acts on it, leave it out.
+- When the person needs exact values per record. Use the List table or Breakdown table.
+- When there is one number that matters. Use the Stat card with comparison.
+
+## Guidelines
+
+- Never let the chart suggest something the data does not say. Bars and areas start at zero; a line that starts elsewhere says so on the axis.
+- Keep the number of charts per view small, and give charts of equal importance the same size.
+- A series keeps its colour on every chart on the page, and hiding a series never repaints the others.
+- Show gaps where data is missing. A missing day is not a zero.
+- When a chart has three or more series, offer a series filter; with one series, offer neither a filter nor a legend.
+- Thresholds are dashed, fixed lines with a text label, such as "Target 40". They are not a series and never use the status colours on their own.
+
+## Content
+
+- Titles are nouns that name the measure: "Applications", "Time to first reply". Never "Chart 1" or a sentence about the result.
+- Axis titles are one to three words with the unit: "Salary (£k)". Time axes need no title; the dates speak for themselves.
+- Dates on axes are short and UK style: "3 Nov", "Mon", "Nov". Currency carries its symbol: "£32k".
+- State copy follows TwoUX's states pattern: "Loading applications", "No applications in this period", "No data matches these filters" with Clear filters, and "Couldn't load applications" with Try again.
+- Use "previous" and "following", not "above" and "below", and "select", not "click".
+
+## Accessibility
+
+- Give every chart an accessible name matching its visible title and a description in the form "[Chart type] showing [data], [period]."
+- Every chart has a Table view with the same values; it is the long description and the fallback for anyone who reads tables more easily.
+- Colour is never the only cue: series have names in the tooltip and direct labels, groups have shapes or line styles.
+- Marks needed to read the data reach 3:1 against the background; text uses text colours, never the series colour.
+- The plot, legend and popover are reachable by keyboard in a logical order, and pinned popovers stay until dismissed.
+
+## Do
+
+- Do start from the question and name it in the chart title.
+- Do ship a Table view with every chart.
+- Do split two units into two charts side by side.
+
+## Don't
+
+- Don't add a second y-axis.
+- Don't colour each bar of a single series differently.
+- Don't use a donut for change over time or for more than five parts.
+- Don't print values or labels in the series colour.
+
+## Related
+
+- Chart drill-down
+- Comparison over time
+- Empty, loading and error states
+- Filtering and search

package/agent/docs-md/date-picker.md

@@ -0,0 +1,178 @@
+# Date picker
+
+Enter a calendar date, or a range of dates, by typing it or choosing it on a calendar: a closing date, a start date, a reporting period.
+
+Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui
+
+## When to use
+
+- For a date people set on a record: closing date, start date, contract end.
+- For a period that narrows a list or a chart: applications in the last 30 days, a quarter for a report.
+- When people need to see the weekday or the week around a date, such as booking around weekends.
+
+## When not to use
+
+- For a date people know by heart and never browse to, such as a date of birth. Use a Text input (text-input) with the hint dd/mm/yyyy.
+- For booking or moving events in time. Use the Scheduler (scheduler).
+- For a chart's fixed period options such as Daily or Weekly. Use a Segmented control (segmented-control).
+- To show a date. Use Timestamp (timestamp).
+
+## Structure
+
+1. Label
+2. Field: the date as dd/mm/yyyy (From and To for a range)
+3. Calendar button ("Choose date")
+4. Popover: preset periods (range, optional), month heading, previous and next month, grid starting on Monday
+5. Footer: why some dates are unavailable (optional)
+6. Hint or error under the field
+
+## Guidelines
+
+- Typing is the main path: the field accepts 12/03/2026, 12/3/26, 12 Mar 2026 and 2026-03-12, and rewrites the value as 12/03/2026 when people leave it, so they see how it was read.
+- The calendar is the second path: the button at the end of the field, or Alt+↓ in the field. It opens on the value's month, otherwise today's.
+- Values are ISO calendar dates ("2026-03-12"), never a Date at midnight UTC, so they match Timestamp and don't land on the day before west of London.
+- Weeks start on Monday and month and weekday names are UK English.
+- Say why dates are unavailable in the footer, such as "Closing dates must be on a weekday." Unavailable days are skipped by the arrow keys.
+- A range shows two months side by side from 768px, one below. The first pick sets the start, the second the end; days between are filled as people point or move.
+- Preset periods (Last 7 days, Last 30 days, This month…) apply at once. In a filter they are stored by name, so a saved view still means "last 30 days" next month. In a filter bar use DateFilterPill, which reads as a sentence like other filter pills: Applied is in Last 30 days.
+- Check the value when people leave the field and on submit; show the error under the field, never in a toast.
+
+## Content
+
+- The hint is the format: dd/mm/yyyy. Add a reason only when it helps: "The last day applications are accepted."
+- Errors say what to do: "Enter the closing date as dd/mm/yyyy, such as 12/03/2026.", "Choose a date on or after 7 December 2026.", "The end date is before the start date. Change one of them."
+- Preset names say the period: Last 7 days, This month, Last quarter.
+
+## Accessibility
+
+- The popover is a dialog named "Choose date". The grid's day buttons have full names: "Thursday 12 March 2026", with "Today" and "selected" added.
+- The month heading is a polite live region, so changing month is read out.
+- Focus moves to the selected day, or today, when the calendar opens, and back to the field when it closes.
+- Today has a ring and the selected day a fill, and both are named, so neither relies on colour alone.
+- Day cells are 32px, above the 24px minimum target.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Alt+↓ | Open the calendar from the field |
+| Enter (in the field) | Read the typed date |
+| ← → ↑ ↓ | Previous or next day; same day in the previous or next week |
+| Home / End | Start or end of the week |
+| Page Up / Page Down | Previous or next month (Shift for the year) |
+| Enter or Space | Choose the focused day |
+| Esc | Close the calendar without changing the value; focus returns to the field |
+
+## Examples
+
+### closing-date
+
+```tsx
+import { DatePicker, fromIsoDate } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Closing date", description: "Type the date, or press Alt+↓ or the calendar button. Weekends and past dates can't be chosen, and the calendar says why.", order: 1 };
+
+const today = new Date();
+const iso = (d: Date) => `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+
+export default function Example() {
+	const [value, setValue] = useState<string | null>(null);
+	return (
+		<div className="w-72">
+			<DatePicker
+				label="Closing date"
+				value={value}
+				onValueChange={setValue}
+				min={iso(today)}
+				isDateUnavailable={(d) => [0, 6].includes(fromIsoDate(d).getDay())}
+				unavailableReason="Closing dates must be on a weekday."
+				hint="The last day applications are accepted. dd/mm/yyyy"
+				required
+			/>
+		</div>
+	);
+}
+```
+
+### filter-pill
+
+```tsx
+import { DateFilterPill, type DateRangeValue, FilterBar, FilterPill, FilterSummary, dateFilterToValues, describeDateFilter } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "In a filter bar", description: "DateFilterPill sits beside FilterPill and reads as a sentence. Presets and calendar ranges apply at once; typed dates apply on Enter. The value is stored as URL-safe strings.", order: 3 };
+
+const STAGES = [{ value: "screen", label: "Screen", count: 42 }, { value: "interview", label: "Interview", count: 18 }, { value: "offer", label: "Offer", count: 4 }];
+
+export default function Example() {
+	const [stages, setStages] = useState(["interview"]);
+	const [applied, setApplied] = useState<DateRangeValue>({ preset: "last-30-days" });
+	const [closing, setClosing] = useState<DateRangeValue>({});
+	const d = describeDateFilter(applied);
+	return (
+		<div className="grid max-w-full gap-3">
+			<FilterBar>
+				<FilterPill field="Stage" options={STAGES} selected={stages} onChange={setStages} onRemove={() => setStages([])} />
+				<DateFilterPill field="Applied" value={applied} onChange={setApplied} onRemove={() => setApplied({})} />
+				<DateFilterPill field="Closing date" value={closing} onChange={setClosing} presets={[]} />
+			</FilterBar>
+			<FilterSummary shown={12} total={64} noun="candidates" onClear={() => { setStages([]); setApplied({}); setClosing({}); }} />
+			<p className="text-sm text-ink-3">
+				URL: <code className="tabular">?applied={dateFilterToValues(applied).join(",") || "—"}</code>
+				{d && <> · Applied {d.operator} {d.spoken}</>}
+			</p>
+		</div>
+	);
+}
+```
+
+### range-presets
+
+```tsx
+import { DateRangePicker, type DateRangeValue, resolveDateRange, formatDateLong } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Range with presets", description: "Pick a preset or two dates. A preset is kept by name, so a saved view still means last 30 days next month.", order: 2 };
+
+export default function Example() {
+	const [value, setValue] = useState<DateRangeValue>({ preset: "last-30-days" });
+	const { from, to } = resolveDateRange(value);
+	return (
+		<div className="grid w-80 gap-3">
+			<DateRangePicker label="Applied" value={value} onValueChange={setValue} presets maxDays={366} />
+			<p className="text-sm text-ink-2">
+				{from && to ? <>Showing applications from {formatDateLong(from)} to {formatDateLong(to)}.</> : "Choose a period."}
+			</p>
+		</div>
+	);
+}
+```
+
+### states
+
+```tsx
+import { DatePicker } from "@twoux/ui";
+
+export const meta = { title: "States", description: "The error says what to do. Read-only keeps the date selectable and drops the calendar.", order: 4 };
+
+const noop = () => {};
+
+export default function Example() {
+	return (
+		<div className="grid w-72 gap-4">
+			<DatePicker label="Start date" value={null} onValueChange={noop} required error="Enter a start date." />
+			<DatePicker label="Contract end" value="2027-03-31" onValueChange={noop} readOnly />
+			<DatePicker label="Probation review" value="2026-12-07" onValueChange={noop} disabled />
+		</div>
+	);
+}
+```
+
+## Related
+
+- Text input
+- Timestamp
+- Filter pills and filter bar
+- Scheduler
+- Form validation

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

@@ -0,0 +1,75 @@
+# Deleting records
+
+Deleting moves records to Deleted with Undo. Only permanent or cascading deletes ask first, and only the rare, severe ones ask people to type the name.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** Delete is where TwoUX's Undo-first rule meets real loss. Without a shared ladder, teams either confirm every removal or let a single click erase a candidate's history, and typed confirmations spread to places where they only slow people down.
+
+**Solution:** Four levels, chosen by what is lost and who it affects. Remove a part of a form you are editing at once. Delete a record to Deleted, with Undo. Permanently delete in a confirmation dialog that names what goes and what stays. Ask for the typed name only when the delete is permanent and takes other records with it.
+
+**Built from:** Toast, Confirmation dialog, Bulk action bar, Banner (inline alert), Text input, Button, Keyboard shortcut hint
+
+## How it works
+
+1. Remove a part of a form being edited, such as a screening question or a tag: no confirmation, it goes at once, with Undo where it saves straight away.
+2. Delete a record, such as a draft listing or a duplicate candidate: it moves to Deleted, where it can be restored for 30 days. Show "Listing deleted. Undo".
+3. Permanently delete, such as emptying Deleted or erasing a candidate on request: a confirmation dialog titled with the action and count, naming what goes and what stays.
+4. Permanent and cascading, such as deleting a workspace or a team with live listings: the same dialog, plus a warning banner listing what else goes, and a field where the person types the name.
+5. If something must happen first, such as closing a live listing that still has applicants, the dialog says so and links to it. The confirm field and button wait until it is done, and the reason is written in the dialog.
+
+## When to use
+
+- Deleted with Undo: the default for every record people can delete.
+- Confirmation dialog: anything that cannot come back, including bulk permanent deletes.
+- Typed name: permanent deletes that also remove other records or affect other people's work.
+
+## When not to use
+
+- Don't use delete for ending a process. Closing a listing or rejecting a candidate are their own actions with their own wording.
+- Don't ask for a typed name on routine deletes. It slows people down and they learn to type without reading.
+- Don't let the assistant delete. It can propose a delete, which the person applies.
+
+## Guidelines
+
+- Choose the level by three questions: can it come back, does it take other records with it, and what would it cost to redo.
+- The dialog body names the record in bold and states the result: "Permanently delete Priya Shah? Her application, notes and interview feedback are erased. You can't undo this."
+- Say what stays as well as what goes: "Reports keep the anonymised counts."
+- Typed confirmation: single record, type its name; bulk, type "delete". Matching ignores case and extra spaces, and paste works.
+- Always confirm in a dialog, never a popover or a separate page.
+- A bulk delete from the bulk action bar uses the level of its most severe item, and the title carries the count: "Permanently delete 12 candidates?"
+
+## Content
+
+- Use "Remove" for taking something out of a form or list it still exists elsewhere in, and "Delete" for the record itself.
+- Dialog title is the action and count as a question: "Delete workspace?", "Permanently delete 3 listings?"
+- Buttons name the outcome: "Keep candidate" and "Delete permanently". Never "OK" or "Yes".
+- Typed confirmation label: "Type Leeds hiring team to confirm".
+
+## Accessibility
+
+- Delete dialogs use role alertdialog with the title as the label and the consequence as the description.
+- Focus starts on the safe button, or on the typed confirmation field when there is one.
+- The typed confirmation field has a visible label naming the exact text, not only a placeholder.
+- After a delete, focus moves to the next row in the list, or the list heading if none is left, and the toast is announced.
+
+## Do
+
+- Do make Deleted the default and offer Undo.
+- Do state prerequisites in the dialog and link to them.
+- Do scale friction to severity and nothing more.
+
+## Don't
+
+- Don't write "Are you sure?".
+- Don't focus the delete button by default.
+- Don't delete a live listing that has applicants in one step; ask people to close it first.
+
+## Related
+
+- Undo and destructive actions
+- Selection and bulk actions
+- Editing a record: inline, section or whole page
+- Confirmation dialog
+- Toast
+- Bulk action bar