@twoux/ui 0.0.0-stage → 0.1.0

package/agent/docs-md/error-state.md

@@ -0,0 +1,123 @@
+# Error state (failed to load)
+
+Shown in place of a region that failed to load: what failed, that nothing was lost, and Try again.
+
+Kind: component · Group: Feedback and overlays · Status: built, import from @twoux/ui
+
+## When to use
+
+- A table, list, chart or panel could not fetch its data.
+- Only one region fails while the rest of the page works; the error stays inside that region.
+- The person lacks permission to see a region's data.
+
+## When not to use
+
+- An action failed (save, extend, close). Show a Banner near the action and keep the person's input.
+- Field validation. Use the inline field error and the form error strip (Banner).
+- Nothing matched the filters. That is an Empty state, not an error.
+
+## Structure
+
+1. Region header kept ("Listings")
+2. Icon tile in the error colour
+3. Title: what failed ("Couldn't load listings")
+4. Description: why if known, and what is kept
+5. Try again button (secondary) with its shortcut R
+6. Optional: expandable technical details
+
+## Guidelines
+
+- Replace only the failed region, at the same size, so the header, filters and other regions stay usable.
+- Keep the person's filters, sort and selection; say so in the message.
+- Offer one action, Try again, which re-runs the same request.
+- Retrying swaps back to the Loading skeleton, then to data or the error again.
+- Put raw error codes in an expandable details section, never in the main message.
+
+## Content
+
+- Title says what failed in plain words: "Couldn't load listings".
+- Description says why if known and what is safe: "The server didn't respond. Your filters are kept."
+- Take ownership; never imply the person caused it.
+- No apologies, jokes or exclamation marks. Do not promise that a team has been told unless that is true.
+
+## Accessibility
+
+- The error is identified in text, not only by the red icon (3.3.1, 1.4.1).
+- Announce the failure once through a live region; do not move focus unless the person triggered the load (4.1.3).
+- After Try again succeeds, keep focus on a stable element such as the region header, not on the removed button (2.4.3).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| R | Try again (single-key shortcut, can be turned off) |
+| Tab / Enter | Reach and activate Try again |
+
+## Examples
+
+### table
+
+```tsx
+import { Button, Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, Skeleton } from "@twoux/ui";
+import { CircleAlert } from "lucide-react";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export const meta = { title: "Table failed to load", description: "Only the table is replaced; the header stays. Try again (or R) swaps back to the skeleton, then to the data or the error. Technical details stay folded away.", order: 1 };
+
+export default function Example() {
+	const [loading, setLoading] = useState(false);
+	const ref = useRef<HTMLDivElement>(null);
+	const retry = useCallback(() => {
+		setLoading(true);
+		setTimeout(() => setLoading(false), 1200);
+	}, []);
+
+	// R retries while focus is inside this region and not in a text field
+	useEffect(() => {
+		const el = ref.current;
+		const onKey = (e: KeyboardEvent) => {
+			if (e.key.toLowerCase() === "r" && !e.metaKey && !e.ctrlKey && !loading && !(e.target as HTMLElement).closest("input, textarea")) retry();
+		};
+		el?.addEventListener("keydown", onKey);
+		return () => el?.removeEventListener("keydown", onKey);
+	}, [loading, retry]);
+
+	return (
+		<div ref={ref} className="grid w-full max-w-xl gap-2">
+			<span className="text-base font-medium text-ink">Listings</span>
+			{loading ? (
+				<div className="grid min-h-56 content-start gap-0 overflow-hidden rounded-sm border border-line" aria-busy="true" aria-label="Loading listings">
+					{["w-40", "w-52", "w-36", "w-48", "w-44", "w-32"].map((w) => (
+						<div key={w} className="flex h-9 items-center gap-3 border-b border-line px-3 last:border-b-0">
+							<Skeleton className={`h-2.5 ${w}`} />
+							<Skeleton className="ml-auto h-2.5 w-6" />
+						</div>
+					))}
+				</div>
+			) : (
+				<Empty className="min-h-56 border-solid border-line">
+					<EmptyHeader>
+						<EmptyMedia variant="error"><CircleAlert /></EmptyMedia>
+						<EmptyTitle>Couldn't load listings</EmptyTitle>
+						<EmptyDescription>The server took too long to reply. Your filters are kept.</EmptyDescription>
+					</EmptyHeader>
+					<EmptyContent>
+						<Button variant="outline" size="sm" shortcut="R" onClick={retry}>Try again</Button>
+						<details className="text-sm text-ink-3">
+							<summary className="cursor-pointer rounded-xs hover:text-ink-2">Technical details</summary>
+							<code className="mt-1 block font-mono">504 Gateway Timeout · GET /listings · req 7f3a91</code>
+						</details>
+					</EmptyContent>
+				</Empty>
+			)}
+		</div>
+	);
+}
+```
+
+## Related
+
+- Loading skeleton
+- Empty state
+- Banner (inline alert)
+- Toast

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

@@ -0,0 +1,86 @@
+# Export menu
+
+One Export menu per table: options first (only visible columns, include AI columns), then file formats, then copy to clipboard.
+
+Kind: component · Group: Data · Status: built, import from @twoux/ui
+
+## When to use
+
+- People take table data to another tool. Export is a table-level toolbar action.
+- Several related export actions start one action each; a menu suits 5 to 15 such items.
+
+## When not to use
+
+- For a single format. Use a plain button, "Export CSV", as on chart cards.
+- To choose a value that changes the view. Use a select.
+
+## Structure
+
+1. Export button with a download icon
+2. Menu heading with the shortcut (⇧E)
+3. Options: Only visible columns, Include AI columns (checkable, the menu stays open)
+4. Download CSV, Download JSON
+5. Copy as CSV, Copy as JSON
+
+## Guidelines
+
+- Group items with labelled sections: options, download, copy.
+- Options are checkbox items that toggle without closing the menu.
+- Order by frequency: the most used format first.
+- Confirm a copy or a finished download with a short status message.
+
+## Content
+
+- Use verb plus format, "Download CSV", "Copy as JSON".
+- Checkbox labels state the choice so its opposite is clear, "Only visible columns".
+- Write labels in sentence case on a single line.
+
+## Accessibility
+
+- APG menu button pattern: Enter, Space or Down Arrow opens the menu and focuses the first item.
+- APG menu pattern: options use role="menuitemcheckbox" with aria-checked; Escape closes and returns focus to Export.
+- 4.1.3 Status Messages: "Copied 24 rows as CSV" is announced without moving focus.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| ⇧E | Open the Export menu |
+| ↑ ↓ | Move between items |
+| Space | Toggle an option without closing |
+| Enter | Run the export and close |
+| Esc | Close and return focus to Export |
+
+## Examples
+
+### menu
+
+```tsx
+import { ExportMenu, toast } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Export a table", description: "Options toggle without closing the menu. Downloads and copies run and close, then confirm with a toast. Opens with ⇧E.", order: 1 };
+
+export default function Example() {
+	const [onlyVisible, setOnlyVisible] = useState(true);
+	const [includeAi, setIncludeAi] = useState(false);
+	const scope = `${onlyVisible ? "visible" : "all"} columns${includeAi ? ", with AI columns" : ""}`;
+	return (
+		<ExportMenu
+			onlyVisible={onlyVisible}
+			onOnlyVisibleChange={setOnlyVisible}
+			includeAi={includeAi}
+			onIncludeAiChange={setIncludeAi}
+			onDownload={(f) => toast.success(`listings.${f.toLowerCase()} downloaded`, { description: `24 rows, ${scope}` })}
+			onCopy={(f) => toast.success(`Copied 24 rows as ${f}`)}
+		/>
+	);
+}
+```
+
+## Related
+
+- Data grid
+- List table
+- Breakdown table
+- Line chart card

package/agent/docs-md/feedback-prompt.md

@@ -0,0 +1,88 @@
+# Feedback prompt
+
+A small "Was this helpful?" block with Yes and No buttons, a thank you once voted, and an optional short follow-up form.
+
+Kind: component · Group: Feedback and overlays · Status: built, import from @twoux/ui
+
+## When to use
+
+- At the end of help topics, help centre articles and beta feature pages.
+- At the end of a report people have just read, to learn if it was useful.
+- On a beta feature's page, to learn whether it is worth keeping.
+
+## When not to use
+
+- Under assistant answers; they use the good and bad controls by the origin label.
+- As a modal or toast, or before people have read the content.
+- For surveys of more than three questions; link to a survey page instead.
+
+## Structure
+
+1. Question as a small heading: "Was this helpful?"
+2. Optional one-line description
+3. Yes and No buttons (text, with an optional thumb icon)
+4. States: default, sending (button spinner), sent (chosen answer selected and thank you text), failed (message and Try again)
+5. Optional follow-up revealed after the vote: one to three fields, a privacy line and Send
+
+## Guidelines
+
+- Send the vote on click; send the follow-up separately with its own Send button.
+- Once voted, the buttons are replaced by the chosen answer and the thank you; the vote can't be sent twice.
+- One feedback prompt per page or panel.
+- Free-text fields carry the privacy line and a 500 character limit with a count.
+- On failure, show the message inline with Try again; keep any typed text.
+
+## Content
+
+- Question names the thing: "Was this help topic helpful?" or simply "Was this helpful?" when the context is clear.
+- Sent: "Thanks, your feedback is recorded."
+- Follow-up label: "What was missing? (optional)". Privacy line: "Don't include candidate names or other personal details."
+
+## Accessibility
+
+- Yes and No are real buttons with visible text; an icon alone is not enough.
+- After a successful vote, focus moves to the thank you text.
+- The failed state is announced in a live region.
+- The follow-up fields have visible labels and follow the form validation rules.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move to Yes, then No |
+| Enter / Space | Send the vote |
+| Tab (after voting) | Reach the optional follow-up fields and Send |
+
+## Examples
+
+### helpful
+
+```tsx
+import { CheckboxField, FeedbackPrompt } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Was this helpful?", description: "One vote, sent on click and never twice. After voting, an optional comment with the privacy line and a 500 character limit. Failures keep what was typed and offer Try again.", order: 1 };
+
+export default function Example() {
+	const [fail, setFail] = useState(false);
+	return (
+		<div className="grid w-full max-w-md gap-4">
+			<CheckboxField id="fb-fail" label="Simulate a failed send" checked={fail} onCheckedChange={(v) => setFail(v === true)} />
+			<div className="rounded-sm border border-line bg-surface p-4">
+				<FeedbackPrompt
+					description="About the screening questions guide"
+					onVote={() => new Promise((res, rej) => setTimeout(() => (fail ? rej(new Error("offline")) : res()), 600))}
+					onFollowUp={() => new Promise((res) => setTimeout(res, 600))}
+				/>
+			</div>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Collecting product feedback
+- Help panel
+- Button
+- Text input

package/agent/docs-md/field-mapping.md

@@ -0,0 +1,78 @@
+# Field mapping
+
+A list of target fields, each with the source column that fills it: required fields marked, type mismatches warned in words, and other source columns skipped or created as new columns. Used by imports and, later, automations.
+
+Kind: component · Group: Data · Status: built, import from @twoux/ui
+
+## When to use
+
+- When data from one place fills fields in another: a CSV import, a connected service, an automation step.
+
+## When not to use
+
+- For choosing which columns show. Use the Columns menu.
+
+## Structure
+
+1. Headings: Field in the table, Column in the file
+2. Row: type icon, field name, Required, arrow, source select with a sample value
+3. Warning under a row: 3 of 20 values aren't an email address
+4. Other columns in the file: Don't import or Create column
+
+## Guidelines
+
+- Map by name automatically, ignoring case and punctuation, and let people change every pair.
+- Mark required fields in words, and check them when people submit, not by disabling the button.
+- Warn about values that don't fit the field type under that row, with how many.
+- Offer Create column for source columns no field uses, defaulting to Don't import.
+
+## Content
+
+- Warnings name the column and the type: "3 of 20 values in E-mail aren't an email address."
+
+## Accessibility
+
+- Each select is labelled by its field name; warnings are linked with aria-describedby.
+- Warnings carry an icon and words, not colour alone.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move between selects |
+| Space / Enter | Open a select |
+
+## Examples
+
+### automation
+
+```tsx
+import { type ExtraColumns, type FieldMap, FieldMapping, type MappingSource, type MappingTarget, autoMapFields } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Map a form's answers to table fields", description: "Fields with matching names are paired automatically. Required fields are marked, values that don't fit the field type are warned about, and unused columns can become new columns.", order: 1 };
+
+const TARGETS: MappingTarget[] = [
+	{ id: "name", label: "Name", kind: "text", required: true },
+	{ id: "email", label: "Work email", kind: "email", required: true },
+	{ id: "size", label: "Company size", kind: "number" },
+	{ id: "start", label: "Start date", kind: "date" },
+];
+const SOURCES: MappingSource[] = [
+	{ id: "q1", label: "Your name", samples: ["Ana Silva", "Ben Hughes", "Chloe Patel"] },
+	{ id: "q2", label: "Email", samples: ["ana@harbourvale.co.uk", "ben at brightwater", "chloe@mosaiclending.co.uk"] },
+	{ id: "q3", label: "Company size", samples: ["240", "about 150", "410"] },
+	{ id: "q4", label: "How did you hear about us?", samples: ["Event", "Search"] },
+];
+
+export default function Example() {
+	const [map, setMap] = useState<FieldMap>(() => ({ ...autoMapFields(TARGETS, SOURCES), name: "q1" }));
+	const [extra, setExtra] = useState<ExtraColumns>({});
+	return <FieldMapping className="w-full max-w-2xl" targets={TARGETS} sources={SOURCES} value={map} onChange={setMap} extra={extra} onExtraChange={setExtra} sourceHeading="Answer in the form" />;
+}
+```
+
+## Related
+
+- CSV import
+- Sheet grid

package/agent/docs-md/file-drop.md

@@ -0,0 +1,110 @@
+# File drop
+
+Drop a file or choose one. Accepted types and the size limit show before choosing, and a preview replaces the icon once a file is picked.
+
+Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui
+
+## When to use
+
+- A single file the product needs, such as a logo, an avatar or a CSV.
+- Where dragging a file in is a shortcut, not the only way.
+
+## When not to use
+
+- Attaching files to a message. Use the Message composer (message-composer).
+- Importing many files with progress. Use a list with a status per file.
+
+## Structure
+
+1. Label
+2. Drop area (icon or preview, "Drop a file here", accepted types and limit)
+3. Remove and Replace or Upload buttons
+4. Hidden native file input
+5. Error under the area
+
+## Guidelines
+
+- Show accepted types and the size limit before anyone chooses a file.
+- Let people choose with a button as well as drop. Drag and drop is never the only way.
+- Errors name the file's size or type and say what to choose, for example "That file is 14.2 MB. Choose one up to 10 MB."
+- The preview replaces the icon, with Remove and Replace beside it.
+- Use a visible label, and a native file input that is hidden visually but still labelled and focusable by the Upload button.
+
+## Content
+
+- Hint: "PNG or JPEG, up to 10 MB".
+- Wrong type: "That file type isn't supported. Choose PNG or JPEG."
+
+## Accessibility
+
+- The visible label is attached to the real input, which keeps its accessible name and value (SC 3.3.2, 4.1.2).
+- The error is linked to the field with aria-invalid and announced when it appears (SC 3.3.1, 4.1.3).
+- The drag state is not conveyed by colour alone: the text changes to "Drop to upload" (SC 1.4.1).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move to the Upload button |
+| Enter or Space | Open the system file chooser |
+| Tab, then Enter | Remove or replace the chosen file |
+
+## Examples
+
+### logo
+
+```tsx
+import { FileDrop } from "@twoux/ui";
+import { useEffect, useState } from "react";
+
+export const meta = { title: "Upload a logo", description: "Types and limit show first. Drop a PNG or JPEG, or press Upload. Try a file over 10 MB or a PDF to see the error.", order: 1 };
+
+export default function Example() {
+	const [url, setUrl] = useState<string>();
+	useEffect(() => () => { if (url) URL.revokeObjectURL(url); }, [url]);
+	return (
+		<div className="w-full max-w-md">
+			<FileDrop
+				id="company-logo"
+				label="Company logo"
+				accept="image/png,image/jpeg"
+				hint="PNG or JPEG, up to 10 MB"
+				maxBytes={10e6}
+				preview={url}
+				onFile={(f) => setUrl(URL.createObjectURL(f))}
+				onRemove={() => setUrl(undefined)}
+			/>
+		</div>
+	);
+}
+```
+
+### server-error
+
+```tsx
+import { FileDrop } from "@twoux/ui";
+
+export const meta = { title: "An error from the server", description: "The message names what is wrong with the file and what to choose instead.", order: 2 };
+
+export default function Example() {
+	return (
+		<div className="w-full max-w-md">
+			<FileDrop
+				id="hiring-csv"
+				label="Candidates file"
+				accept="text/csv"
+				hint="CSV, up to 5 MB"
+				error="Row 14 has no email address. Add one and choose the file again."
+				onFile={() => {}}
+			/>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Form validation
+- Text input
+- Message composer
+- Provider logo

package/agent/docs-md/filter-bar.md

@@ -0,0 +1,138 @@
+# Filter pills and filter bar
+
+Filters applied from one button in the toolbar and shown as segmented chips on their own row: each reads as a sentence, values apply as soon as they are ticked, and the row appears only while something is filtered.
+
+Kind: component · Group: Data · Status: built, import from @twoux/ui
+
+## When to use
+
+- People filter a table by a few properties and need to see every active filter without opening anything.
+- People combine several properties, values and operators on a large collection.
+- Results load quickly enough for each change to apply live.
+
+## When not to use
+
+- When there are many fields to filter by, as in candidate search. Use the TwoUX Filter panel.
+- For collections under about five items. Do not filter at all.
+- For settings that always have a value, such as a chart's date range or Daily and Weekly. Use a rectangle control or the TwoUX segmented control.
+
+## Structure
+
+1. Filter button in the toolbar (F): fields, then the chosen field’s values beside them
+2. Filter row, shown only once a filter is applied
+3. Applied filter chip: field, operator, value, remove
+4. Add another filter (+)
+5. Result count
+6. Clear
+
+## Guidelines
+
+- Shape says what a control does. A filter is a segmented chip (field, operator, value, remove) on the filter row; actions and view settings are buttons in the toolbar.
+- Each chip reads field, operator, value, for example "Status is any of Live, Expiring". Three or more values are counted: "3 statuses".
+- Put the filter button in the toolbar. Picking a field opens its values beside the field list, and the chip appears on the filter row only once a value is ticked, never as an empty suggestion.
+- List values apply as soon as they are ticked and show how many rows each matches. Typed values (numbers, dates) apply on Enter.
+- Put the result count and Clear at the end of the filter row, and filter the full collection, not only the loaded rows.
+- Each chip can be removed on its own with the remove button at its end; + after the chips adds another field.
+
+## Content
+
+- Use "is", "is not" and "is any of" as operators, matching the field, operator, value token model.
+- Dates offer quick picks first, then "in the last N days", then a calendar.
+- Write the result count as a full phrase, "24 listings", not a bare number.
+- Show the field name before the value so values like "2" or "London" are never ambiguous.
+
+## Accessibility
+
+- 4.1.3 Status Messages: announce the updated result count without moving focus.
+- 4.1.2 Name, Role, Value: each remove button is named "Remove Status filter"; ticked values expose their checked state.
+- 1.4.11 Non-text Contrast: the chip border must reach 3:1 against the filter row, since it is the chip’s only boundary.
+- 2.1.4 Character Key Shortcuts: F can be turned off with the other single-key shortcuts.
+- Moving focus or scroll back to the top after each change is avoided so people keep their place.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| F | Open the field list |
+| ↑ ↓, Enter | Move through and choose fields or values |
+| Space | Tick or untick a list value (applies at once) |
+| Enter | Apply a typed number or date |
+| Esc | Close the values, then the field list, and return focus to the filter button |
+
+## Examples
+
+### listings
+
+```tsx
+import { Badge, FilterButton, type FilterFieldDef, FilterRow, type FilterValue, Table, TableBody, TableCell, TableRow, Timestamp, dateFilterFromValues, resolveDateRange } from "@twoux/ui";
+import { useState } from "react";
+import { LISTINGS, type Listing, STATUS_VARIANT } from "../list-table/data";
+
+export const meta = {
+	title: "Filter listings",
+	description: "The filter button sits in the toolbar. Pick a field, then tick its values beside the list: each tick applies at once, and the filter shows as a chip on its own row only once it has a value. A date field (Closing date) opens typed dates and a calendar instead. + adds another field; Clear removes them all.",
+	order: 1,
+};
+
+const FIELDS = [
+	{ id: "status", label: "Status", noun: { one: "status", many: "statuses" } },
+	{ id: "location", label: "Location", noun: { one: "location", many: "locations" } },
+	{ id: "role", label: "Role", noun: { one: "role", many: "roles" } },
+] as const;
+
+export default function Example() {
+	const [filters, setFilters] = useState<FilterValue>({ status: ["Open", "Closing soon"] });
+	const matches = (l: Listing, skip?: string) =>
+		Object.entries(filters).every(([f, vals]) => {
+			if (f === skip) return true;
+			if (f !== "closes") return vals.includes(String(l[f as keyof Listing]));
+			// A date field holds dateFilterToValues; resolveDateRange turns it into the dates to compare.
+			const { from, to } = resolveDateRange(dateFilterFromValues(vals, []));
+			return (!from || l.closes >= from) && (!to || l.closes <= to);
+		});
+	const rows = LISTINGS.filter((l) => matches(l));
+	// Counts reflect the other filters, so people see what a tick will give them.
+	const fields: FilterFieldDef[] = [
+		...FIELDS.map((f) => ({
+			id: f.id,
+			label: f.label,
+			valueNoun: f.noun,
+			options: [...new Set(LISTINGS.map((l) => String(l[f.id])))].sort().map((v) => ({ value: v, label: v, count: LISTINGS.filter((l) => matches(l, f.id) && String(l[f.id]) === v).length })),
+		})),
+		// Closing dates are in the future, so "last 30 days" presets mean nothing here: typed dates and the calendar only.
+		{ id: "closes", label: "Closing date", kind: "date", presets: [], group: "All fields" },
+	];
+
+	return (
+		<div className="grid w-full max-w-2xl overflow-hidden rounded-sm border border-line bg-surface">
+			<div className="flex items-center gap-2 border-b border-line px-3 py-2">
+				<span className="text-base font-medium text-ink">Listings</span>
+				<span className="flex-1" />
+				<FilterButton fields={fields} value={filters} onChange={setFilters} />
+			</div>
+			<FilterRow fields={fields} value={filters} onChange={setFilters} shown={rows.length} total={LISTINGS.length} noun="listings" className="border-b border-line bg-surface-2 px-3 py-2" />
+			<div className="max-h-56 overflow-y-auto">
+				<Table aria-label="Filtered listings">
+					<TableBody>
+						{rows.map((l) => (
+							<TableRow key={l.id}>
+								<TableCell className="font-medium text-ink">{l.role}</TableCell>
+								<TableCell className="text-ink-2">{l.location}</TableCell>
+								<TableCell className="text-ink-2"><Timestamp value={l.closes} format="date" short /></TableCell>
+								<TableCell><Badge variant={STATUS_VARIANT[l.status]} dot>{l.status}</Badge></TableCell>
+							</TableRow>
+						))}
+					</TableBody>
+				</Table>
+			</div>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Filter panel
+- Saved views
+- List table
+- Data grid