@twoux/ui 0.0.0-stage → 0.1.1

package/agent/docs-md/stepper.md

@@ -0,0 +1,92 @@
+# Stepper
+
+A vertical list of numbered steps for a task done in order, such as setting up a workspace or publishing a listing, showing what is done, what is current and what is left.
+
+Kind: component · Group: Navigation · Status: built, import from @twoux/ui
+
+## When to use
+
+- For a task of 3 to 6 steps that must happen in order, where knowing what is left helps people finish.
+- For a setup checklist on an empty workspace, where each step unlocks the next.
+
+## When not to use
+
+- For sections people can visit in any order. Use Tabs.
+- For one long form. Split it with headings; steps add clicks without reducing work.
+- For background progress, such as an upload. Use a progress bar or status.
+
+## Structure
+
+1. Marker: number, or a check when done
+2. Line joining the markers, primary up to the current step
+3. Title, and an optional one-line description
+4. Current step: primary marker, aria-current="step"
+5. Later steps: faded
+
+## Guidelines
+
+- Keep it to 3 to 6 steps. More than that, group steps or simplify the task.
+- Let people go back to any done step; never skip ahead to a step that depends on an unfinished one.
+- Keep entered data when people go back and forward.
+- Check each step when people press Next and keep them on it until it passes, with errors at the field. A final Review step checks everything again and links each problem to its step.
+- Mark a done step with a check and the line in primary up to the current step, so progress reads at a glance.
+- Place it beside the step's content on wide screens, and above it on narrow ones.
+
+## Content
+
+- Step titles are short verb phrases in sentence case: “Add the role”, “Set salary”, “Review and publish”.
+- The description says what the step needs, in a few words: “Title, team and location”.
+
+## Accessibility
+
+- Use an ordered list, so screen readers announce the count and position.
+- The current step has aria-current="step"; done and current states are also given in text, not by colour alone.
+- Done steps that can be revisited are buttons with a visible focus ring.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Reaches each done step that can be revisited |
+| Enter / Space | Goes back to that step |
+
+## Examples
+
+### publish
+
+```tsx
+import { Button, Stepper } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Publish a listing", description: "Done steps show a check and can be revisited. Later steps stay faded and locked until the one before is finished.", order: 1 };
+
+const STEPS = [
+	{ title: "Add the role", description: "Title, team and location" },
+	{ title: "Set salary", description: "Band and benefits" },
+	{ title: "Screening questions", description: "Up to 5 questions" },
+	{ title: "Review and publish" },
+];
+
+export default function Example() {
+	const [current, setCurrent] = useState(1);
+	return (
+		<div className="grid w-full max-w-lg grid-cols-[200px_1fr] gap-8 max-sm:grid-cols-1">
+			<Stepper steps={STEPS} current={current} onStepSelect={setCurrent} aria-label="Publish a listing" />
+			<div className="grid content-start gap-3">
+				<span className="text-md font-semibold text-ink">{STEPS[Math.min(current, STEPS.length - 1)].title}</span>
+				<span className="text-base text-ink-2">Step {Math.min(current + 1, STEPS.length)} of {STEPS.length}</span>
+				<div className="flex gap-2">
+					<Button variant="outline" size="sm" disabled={current === 0} onClick={() => setCurrent((c) => c - 1)}>Back</Button>
+					<Button size="sm" disabled={current >= STEPS.length} onClick={() => setCurrent((c) => c + 1)}>{current >= STEPS.length - 1 ? "Publish" : "Continue"}</Button>
+				</div>
+			</div>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Tabs (underline)
+- Card
+- Onboarding step

package/agent/docs-md/suggested-changes.md

@@ -0,0 +1,91 @@
+# Suggested changes
+
+A proposal card listing each change with a checkbox and before and after, applied with one button and undoable afterwards.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- Any time the assistant or an agent would change records: extend, rename, close, email.
+- When several changes are proposed and people may want only some of them.
+
+## When not to use
+
+- Read-only answers. Show the figure and table without a proposal (assistant-panel).
+- Actions set to Allow in Agent permissions; those run and appear in the Agent run timeline (agent-run) with Undo.
+- Generated values that fill a new column. Use the AI column (ai-column), which never overwrites real data.
+
+## Structure
+
+1. Header ("Suggested changes · 2")
+2. Change rows (checkbox, change, detail line, inline diff)
+3. Footer (note "Nothing changes until you apply.", Dismiss, Edit, Apply N changes ⌘↵)
+4. Undo toast after applying
+
+## Guidelines
+
+- Nothing runs until the person applies. Say so in the footer.
+- Each change has a checkbox, ticked by default, and shows the before and after (strikethrough and inserted text).
+- The Apply button counts what it will change ("Apply 2 changes") and updates as boxes are unticked.
+- Edit opens the changes for adjustment; Dismiss removes the card without changing anything.
+- After applying, show a toast with Undo (⌘Z) that restores the previous values.
+- Match friction to risk: changes that reach people outside the workspace need a stronger confirmation.
+
+## Content
+
+- Write each change as a plain action: "Extend Operations Coordinator by 30 days", with the consequence on the next line ("New closing date 6 Dec").
+- State what does not change ("Title only. Description stays the same.").
+- After Undo: "Undone. Nothing was changed."
+
+## Accessibility
+
+- Each change is a native checkbox with its label, so the change and its detail are read together (SC 1.3.1, 4.1.2).
+- Before and after use del and ins elements and text, not colour alone (SC 1.4.1).
+- Applying changes records data, so it must be reversible or confirmed (SC 3.3.4): this card is the review step and Undo makes it reversible.
+- The applied and undone messages are status messages in a role="status" toast (SC 4.1.3).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Space | Tick or untick the focused change |
+| ⌘↵ / Ctrl+Enter | Apply the ticked changes |
+| ⌘Z / Ctrl+Z | Undo from the toast |
+
+## Examples
+
+### proposal
+
+```tsx
+import { SuggestedChanges, toast } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "A proposal you apply", description: "Each change ticked by default with before and after. Apply counts what it will change; ⌘↵ applies. Undo follows.", order: 1 };
+
+export default function Example() {
+	const [k, setK] = useState(0);
+	return (
+		<div className="w-full max-w-lg">
+			<SuggestedChanges
+				key={k}
+				changes={[
+					{ id: "1", label: "Rename Frontend Engineer", detail: "LST-1041", before: "Frontend Engineer", after: "Frontend Engineer (React)" },
+					{ id: "2", label: "Add salary range", detail: "LST-1041", after: "£48,000 to £56,000" },
+					{ id: "3", label: "Extend closing date by 30 days", detail: "LST-1041", before: "21 Nov", after: "21 Dec" },
+				]}
+				onApply={(ids) => { toast.success(`Applied ${ids.length} changes`, { action: { label: "Undo", onClick: () => setK((x) => x + 1) } }); setK((x) => x + 1); }}
+				onDismiss={() => toast("Dismissed")}
+				onEdit={() => toast("Opened for editing")}
+			/>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Step card
+- Agent permissions
+- Assistant side panel
+- Toast
+- Change review

package/agent/docs-md/switch.md

@@ -0,0 +1,78 @@
+# Switch
+
+Turns one setting on or off with immediate effect, without a Save button.
+
+Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui
+
+## When to use
+
+- For a setting that applies the moment it is flipped: Email me when someone applies.
+- For preferences in popovers and panels: Wrap long text, Single-key shortcuts.
+- When the label describes the on state clearly enough on its own.
+
+## When not to use
+
+- In a form that needs Save or Publish. Use Checkbox.
+- When both states need explaining, such as cost differences. Use Radio.
+- For more than two options. Use Radio or Segmented control.
+
+## Structure
+
+1. Track (28 x 16px)
+2. Thumb
+3. Label
+4. Description (optional)
+
+## Guidelines
+
+- Track 28 x 16px, thumb 12px. On fills primary; off is grey.
+- The change applies at once. Confirm it with a short toast when the effect is not visible on screen.
+- Label to the left in settings rows, right of the switch in inline lists; keep one pattern per surface.
+- If disabled, say why nearby.
+- Movement of the thumb is the main cue; colour is the second.
+
+## Content
+
+- Label says what is on when the switch is on. Read it with on/off after it to test.
+- The label never changes with the state.
+- Lead with the key word, no question: Single-key shortcuts, not Do you want single-key shortcuts?
+
+## Accessibility
+
+- Use role="switch" (or a native checkbox) with aria-checked true/false.
+- Space toggles; Enter may also toggle.
+- Label tied with for/id so the label row is part of the target; the 28 x 16 track alone is under 24px high.
+- Off track and on fill need 3:1 against the surface.
+- Changing a switch must not move focus or open a new view.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Space | Toggle the focused switch |
+| Enter | Also toggles (optional) |
+
+## Examples
+
+### settings
+
+```tsx
+import { SwitchField } from "@twoux/ui";
+export const meta = {"title": "Settings that apply at once", "description": "A switch changes something immediately, so there is no Save button. The label says what is on.", "order": 1};
+
+export default function Example() {
+	return (
+		<div className="grid w-96 gap-4 rounded-sm border border-line bg-surface p-4 shadow-card">
+			<SwitchField id="sw-email" label="Email me when someone applies" hint="One email per applicant." defaultChecked />
+			<SwitchField id="sw-keys" label="Single-key shortcuts" hint="Turn off if you use a screen reader or voice control." defaultChecked />
+			<SwitchField id="sw-digest" label="Weekly summary" disabled />
+		</div>
+	);
+}
+```
+
+## Related
+
+- Checkbox
+- Segmented control
+- Keyboard shortcut hint

package/agent/docs-md/table-settings.md

@@ -0,0 +1,81 @@
+# Table settings
+
+Settings for one table in the side panel: how duplicates are handled with the consequence written out, deleting empty rows, and sharing as a template with who can use it. Saved with Save; closing with changes asks first.
+
+Kind: component · Group: Data · Status: built, import from @twoux/ui
+
+## When to use
+
+- For rules that apply to a whole table rather than one column.
+
+## When not to use
+
+- For column set-up. Use the column menu.
+
+## Structure
+
+1. Duplicate rows: match on, Keep the oldest, Keep the newest, Keep both, each with what happens
+2. Empty rows: Delete empty rows automatically
+3. Share as a template: checkbox, who can use it, link with Copy
+4. Footer: Cancel, Save
+
+## Guidelines
+
+- Write out the consequence of each duplicate rule, including overwritten values and runs that cost credits again.
+- Use checkboxes and radios in this form, saved with Save; a switch is only for changes that apply at once.
+- Ask before discarding only when something changed, and warn before leaving the page while dirty.
+- Say what a template shares and what it never shares.
+
+## Content
+
+- "Rows and looked-up values are never shared."
+
+## Accessibility
+
+- Radio groups are labelled by their heading; hints are linked to each option.
+- The discard dialog puts focus on Keep editing.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| ⌘ Enter | Save |
+| Esc | Close; asks first when there are changes |
+
+## Examples
+
+### settings
+
+```tsx
+import { Button, TableSettings, type TableSettingsValue } from "@twoux/ui";
+import { Settings } from "lucide-react";
+import { useState } from "react";
+
+export const meta = { title: "Settings for the People table", description: "Change a setting and close the panel: it asks before discarding. Close without changes and it doesn't ask. Each duplicate rule says what happens to existing rows and credits.", order: 1 };
+
+export default function Example() {
+	const [open, setOpen] = useState(false);
+	const [value, setValue] = useState<TableSettingsValue>({ duplicates: "keep-oldest", matchOn: "email", deleteEmptyRows: false, template: { shared: false, audience: "workspace" } });
+	return (
+		<>
+			<Button variant="outline" onClick={() => setOpen(true)}><Settings />Table settings</Button>
+			<TableSettings
+				open={open}
+				onOpenChange={setOpen}
+				mode="overlay"
+				value={value}
+				onSave={async (v) => { await new Promise((r) => setTimeout(r, 400)); setValue(v); }}
+				columns={[{ id: "email", label: "Work email" }, { id: "name", label: "Name" }]}
+				tableName="People"
+				workspaceName="TwoUX"
+				templateLink="https://app.example.com/t/people"
+			/>
+		</>
+	);
+}
+```
+
+## Related
+
+- Side panel (drawer)
+- Sheet grid

package/agent/docs-md/tabs.md

@@ -0,0 +1,85 @@
+# Tabs (underline)
+
+Splits one record or page into sections such as Overview, Candidates and Activity, one visible at a time.
+
+Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui
+
+## When to use
+
+- To split a record into separate sections people do not need side by side: Overview, Candidates, Activity.
+- When each section is substantial and can have its own URL.
+- With a count when the number helps people decide to open the tab: Candidates 42.
+
+## When not to use
+
+- To switch between views of the same data, such as All / Active. Use Segmented control.
+- For steps in a flow. Use a stepper or separate pages.
+- When people must compare content across sections. Show it on one page.
+- For app navigation. Use the sidebar.
+
+## Structure
+
+1. Tab list with bottom rule
+2. Tab label
+3. Count (optional)
+4. Active underline (2px primary)
+5. Tab panel
+
+## Guidelines
+
+- Single row, 20px gap, 13px medium labels. Active tab gets primary text and a 2px primary underline: two cues, not one.
+- Two to seven tabs. Order by use, most used first; the first tab is the default.
+- No nested tabs and no disabled tabs; hide a tab that does not apply.
+- If tabs overflow on narrow screens, the list scrolls sideways; it never wraps to a second row.
+- Put shared headings and actions above the tab list, not inside one panel.
+
+## Content
+
+- One or two words, nouns, sentence case: Activity, not View all activity.
+- Labels must not overlap in meaning.
+- Counts need screen reader text: 42 candidates, not just 42.
+
+## Accessibility
+
+- role="tablist" with a label, role="tab" with aria-selected and aria-controls, role="tabpanel" labelled by its tab.
+- Tab enters the list on the active tab; Left and Right arrows move between tabs; Home and End jump.
+- Panels load instantly, so tabs activate on focus (automatic activation).
+- The underline indicator has 3:1 against white.
+- Tab hit area is the full label height (about 36px), above the 24px minimum.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Left / Right | Previous or next tab |
+| Home / End | First or last tab |
+| Tab | Move from the tab list into the panel |
+
+## Examples
+
+### underline
+
+```tsx
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@twoux/ui";
+export const meta = {"title": "Sections of one record", "description": "Underline tabs split one page into sections. Counts help people decide where to go. Arrow keys switch tabs.", "order": 1};
+
+export default function Example() {
+	return (
+		<Tabs defaultValue="overview" className="w-full max-w-lg">
+			<TabsList>
+				<TabsTrigger value="overview">Overview</TabsTrigger>
+				<TabsTrigger value="candidates" count={54}>Candidates</TabsTrigger>
+				<TabsTrigger value="activity">Activity</TabsTrigger>
+			</TabsList>
+			<TabsContent value="overview" className="text-ink-2">Views, applies and the funnel for this listing.</TabsContent>
+			<TabsContent value="candidates" className="text-ink-2">54 people applied. 16 are shortlisted.</TabsContent>
+			<TabsContent value="activity" className="text-ink-2">Edited by Rahul S. 2 days ago.</TabsContent>
+		</Tabs>
+	);
+}
+```
+
+## Related
+
+- Segmented control
+- Status badge

package/agent/docs-md/tag-input.md

@@ -0,0 +1,108 @@
+# Tag input
+
+Enter several short values that don't come from a list, typed or pasted, and see at once which are wrong: email addresses to invite, allowed domains, keywords.
+
+Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui
+
+## When to use
+
+- For free values with no list to pick from: invite emails, allowed domains, search keywords.
+- When people paste a list from a spreadsheet, an email client or another tool.
+
+## When not to use
+
+- When the values come from a list, such as skills or locations. Use Combobox (combobox) with multiple.
+- For one value. Use a Text input (text-input).
+- For labels on a record that people only read. Use Tag (tag).
+- For many rows of values with several fields each. Use a Sheet grid (sheet-grid).
+
+## Structure
+
+1. Label
+2. Field holding the tags, then the text input
+3. Tag: text and remove button; an invalid tag adds an alert icon and its reason
+4. Hint, or what just happened (added, already added, not added)
+5. Count when there is a limit: 3 of 10
+6. Error under the field
+
+## Guidelines
+
+- Enter, comma or leaving the field adds the typed text. Tab adds it only when there is text, so the field never traps focus.
+- Pasted text is split on commas, semicolons, new lines and tabs, so a column from Excel or a list from Outlook works.
+- A duplicate (ignoring case) isn't added again: the existing tag is highlighted and the hint line says it is already added.
+- An invalid value stays as a marked tag with its reason; the error under the field counts them. Nothing is dropped without saying so.
+- Values past the limit stay in the input, and the hint line says how many weren't added.
+- Fix a value by pressing Enter on its tag, or double-clicking it: the text goes back into the input.
+
+## Content
+
+- The hint names the separators and the thing: Separate addresses with commas or new lines.
+- Messages say what happened and what to do: "anna@acme.co.uk is already added.", "Not an email address.", "2 addresses aren't valid. Fix or remove them."
+
+## Accessibility
+
+- The tags are a list named by the field label. Each tag's name includes its reason when it isn't valid.
+- Adding, removing and paste summaries ("12 added, 2 not valid") are announced politely.
+- The field is one tab stop; arrow keys move between tags, so long lists don't flood the tab order.
+- Error is shown with an icon and words as well as colour.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Enter or comma | Add the typed text |
+| ← or Backspace at the start of the input | Move to the last tag |
+| ← → | Move between tags; → from the last tag returns to the input |
+| Backspace / Delete (on a tag) | Remove it; focus moves to the tag before or after |
+| Enter (on a tag) | Put its text back in the input to fix it |
+| Esc (on a tag) | Return to the input |
+
+## Examples
+
+### invite
+
+```tsx
+import { TagInput } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Invite by email", description: "Type or paste addresses. Duplicates are reported, invalid ones stay marked with the reason. Try pasting: ben@acme.co.uk; anna@acme.co.uk; chris@acme", order: 1 };
+
+const isEmail = (v: string) => (/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(v) ? undefined : "Not an email address.");
+
+export default function Example() {
+	const [value, setValue] = useState<string[]>(["anna@acme.co.uk"]);
+	return (
+		<div className="w-96 max-w-full">
+			<TagInput label="Email addresses" noun={{ one: "address", many: "addresses" }} value={value} onValueChange={setValue} validateValue={isEmail} max={10} name="invite" required />
+		</div>
+	);
+}
+```
+
+### states
+
+```tsx
+import { TagInput } from "@twoux/ui";
+
+export const meta = { title: "States", description: "Invalid values are counted under the field. Read-only tags stay focusable and readable.", order: 2 };
+
+const noop = () => {};
+const domain = (v: string) => (/^[a-z0-9-]+(\.[a-z0-9-]+)+$/i.test(v) ? undefined : "Not a domain, such as acme.co.uk.");
+
+export default function Example() {
+	return (
+		<div className="grid w-96 max-w-full gap-4">
+			<TagInput label="Allowed domains" noun={{ one: "domain", many: "domains" }} value={["acme.co.uk", "acme com", "acme.com"]} onValueChange={noop} validateValue={domain} />
+			<TagInput label="Keywords" noun={{ one: "keyword", many: "keywords" }} value={["Data engineer", "Analytics", "Remote"]} onValueChange={noop} readOnly />
+		</div>
+	);
+}
+```
+
+## Related
+
+- Tag
+- Combobox
+- Text input
+- Sheet grid
+- Form validation

package/agent/docs-md/tag.md

@@ -0,0 +1,79 @@
+# Tag
+
+Labels a record with a category people chose, such as Design, Hybrid or Graduate scheme.
+
+Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui
+
+## When to use
+
+- For descriptive categories that classify or group records: team, contract type, work mode.
+- For user-defined values that people add and remove.
+- When one record belongs to several categories.
+
+## When not to use
+
+- For system state such as Live or Closed. Use Status badge.
+- As a button. Use Button or a selectable control.
+
+## Structure
+
+1. Container (22px, 4px corners)
+2. Colour dot (optional)
+3. Text
+4. Remove button (optional)
+
+## Guidelines
+
+- 22px high, 4px corners, white with a 1px grey border, 12px text, so it reads quieter than a status badge. Not fully round: in TwoUX a pill means a filter you can remove.
+- Add a colour dot only when the colour means something, such as the team.
+- Removable tags put a small x after the text.
+- Show up to three in a table cell; summarise the rest as +N so the row stays scannable.
+- Never wrap a tag over two lines. Truncate with a tooltip showing the full text.
+
+## Content
+
+- One or two words, ideally under 20 characters.
+- Sentence case unless a proper noun: Graduate scheme, not Graduate Scheme.
+- Use the same wording everywhere so filters match.
+
+## Accessibility
+
+- Text contrast 4.5:1 on white; the dot is decorative and hidden from assistive technology.
+- The remove button is a real button named Remove Design.
+- Remove buttons need a 24px target or enough spacing from neighbours.
+- Colour never carries the only meaning; the text names the category.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move to a removable tag's remove button |
+| Enter / Space | Remove the tag |
+
+## Examples
+
+### tags
+
+```tsx
+import { Tag, TagList } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Categories on a listing", description: "Tags are quieter than status badges and have 4px corners (pills mean filters). A dot only when the colour means something. In a table cell, three at most, then +N.", order: 1 };
+
+export default function Example() {
+	const [tags, setTags] = useState(["Design", "Hybrid", "Graduate scheme"]);
+	return (
+		<div className="grid gap-4">
+			<div className="flex flex-wrap gap-1.5">{tags.map((t, i) => <Tag key={t} color={i === 0 ? "var(--color-c1)" : undefined} onRemove={() => setTags((x) => x.filter((y) => y !== t))}>{t}</Tag>)}</div>
+			<div className="flex items-center gap-3 text-base text-ink-2">In a table cell: <TagList tags={["Engineering", "Remote", "Senior", "Visa sponsorship", "Urgent"]} /></div>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Status badge
+- Avatar and avatar stack
+- Tag input
+- Combobox