@twoux/ui 0.0.0-stage → 0.1.1

package/agent/docs-md/task-builder.md

@@ -0,0 +1,87 @@
+# Task builder
+
+Repeated tasks written as a sentence with editable slots that reuse filter values, with Run blocked until every required slot is filled.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- Tasks people run often with the same shape, such as "Find Live listings under 3% and draft new titles for hiring managers".
+- When the inputs map to filters already in TwoUX, so slots reuse those values.
+- When an answer should be saved and rerun on a schedule.
+
+## When not to use
+
+- A one-off question. Use the Message composer (message-composer).
+- A prompt that runs per row with typed outputs. Use the Prompt editor (prompt-editor).
+- Browsing ready-made tasks. Use the Templates gallery (templates-gallery).
+
+## Structure
+
+1. Sentence with slots (dashed when empty, filled when set)
+2. Actions (Schedule, Save as task, Run ⌘↵)
+3. Inline error naming the empty slot
+
+## Guidelines
+
+- Make the critical slots prominent and say which can be left empty.
+- An empty slot is dashed and blocks Run; the message says which slot.
+- Filled slots show as regular text; empty ones as placeholders.
+- Do not overload the sentence with slots.
+- Scheduled runs notify before they act and land in the Inbox when they need approval.
+- An empty slot shows its field name in italics in a dashed box; once filled it shows the value as normal text.
+- The popover field label matches the slot name exactly, so people know which slot they are editing.
+- Slots hold one value each. Status belongs in a badge and several related values in a key-value list, not in slots.
+
+## Content
+
+- Write the sentence as an instruction in plain words; slot placeholders match the filter field names.
+- Error: "Choose who gets the titles before you run this."
+
+## Accessibility
+
+- Each slot is a button whose name includes the slot and value ("Status: Live") (SC 4.1.2).
+- Slots open a menu or listbox following the menu button pattern.
+- The disabled Run has its reason in text next to it (SC 3.3.1, 3.3.2).
+- Dashed versus solid is not the only cue; empty slots show placeholder text (SC 1.4.1).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move between slots |
+| Enter / Space | Open a slot's options |
+| ⌘↵ / Ctrl+Enter | Run when all required slots are filled |
+
+## Examples
+
+### weekly
+
+```tsx
+import { TaskBuilder, toast } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "A task written as a sentence", description: "Slots are dashed until set. Run (⌘↵) is blocked while a required slot is empty, and the message names it.", order: 1 };
+
+export default function Example() {
+	const [v, setV] = useState<Record<string, string>>({ when: "Every Monday" });
+	return (
+		<div className="w-full max-w-xl">
+			<TaskBuilder
+				value={v}
+				onChange={setV}
+				onRun={() => toast.success("Task started")}
+				onSave={() => toast("Saved as a task")}
+				onSchedule={() => toast("Scheduled")}
+				parts={[{ id: "when", placeholder: "When", options: ["Every Monday", "Every day at 9:00", "Once"], required: true }, ", summarise", { id: "which", placeholder: "which listings", options: ["listings closing this week", "listings with no applicants", "all open listings"], required: true }, "and send it to", { id: "who", placeholder: "who", options: ["me", "the hiring managers", "#hiring on Slack"], required: true }, "."]}
+			/>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Templates gallery
+- Prompt editor with fields
+- Agent run timeline

package/agent/docs-md/team-instructions.md

@@ -0,0 +1,72 @@
+# Team instructions and files
+
+Shared instructions and files set once for the workspace, visible and editable, and named in the assistant's empty state and citations when used.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- Rules the assistant should always follow for the team, such as UK English or never contacting candidates without asking.
+- Reference files such as salary bands or hiring policy that answers should cite.
+
+## When not to use
+
+- Personal preferences for one person. Use writing style in the Message composer (message-composer).
+- Rules that grant or block actions. Use Agent permissions (agent-permissions).
+
+## Structure
+
+1. Instructions card (text, Edit, set by and scope)
+2. Files card (file list, Add a file)
+3. Privacy note
+
+## Guidelines
+
+- Shared context is visible and editable, not hidden in a system prompt.
+- Show who set it and that it applies to everyone in the workspace.
+- The empty state says it is in use ("Using team instructions and 3 files").
+- Answers cite the file when they rely on it.
+- Keep conversations private unless shared.
+
+## Content
+
+- Instructions are short imperatives in plain English.
+- Scope line: "Set by Rahul S. · applies to everyone in TwoUX".
+
+## Accessibility
+
+- Edit and Add a file are icon buttons with names (SC 4.1.2).
+- Card headings label each section (SC 2.4.6, 1.3.1).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move to Edit or Add a file |
+| Enter | Edit instructions or add a file |
+
+## Examples
+
+### instructions
+
+```tsx
+import { TeamInstructions, toast } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Shared context, visible", description: "Instructions and files the assistant reads for everyone, shown with who set them. Edit in place.", order: 1 };
+
+export default function Example() {
+	const [text, setText] = useState("Write in UK English. Always state the salary range. Never comment on age, nationality or gaps in employment.");
+	return (
+		<div className="w-full max-w-lg">
+			<TeamInstructions text={text} setBy="Priya Shah" files={[{ name: "Salary bands 2026.pdf", size: "220 KB" }, { name: "Hiring handbook.docx", size: "1.4 MB" }]} onSave={(t) => { setText(t); toast.success("Instructions saved"); }} onAddFile={() => toast("Choose a file")} />
+		</div>
+	);
+}
+```
+
+## Related
+
+- Assistant side panel
+- Citations and sources
+- Connected tools

package/agent/docs-md/templates-gallery.md

@@ -0,0 +1,85 @@
+# Templates gallery
+
+A dialog with categories on the left, search on top and cards that say what each template does and which tools it uses; picking one opens it as a draft task.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- Starting a new task from a proven pattern, such as sourcing or reporting.
+- Showing what agents can do to people who have not used them.
+
+## When not to use
+
+- Running a saved task you already use. Use / in the Message composer (message-composer).
+- Quick prompts in the empty state. Use starters (follow-ups-starters).
+
+## Structure
+
+1. Category nav with search
+2. Heading and Close
+3. Template cards (name, what it does, tools used)
+
+## Guidelines
+
+- Picking a template opens it as a draft task, never runs it.
+- Cards say what the template does and which tools it uses.
+- Search and categories make browsing easy.
+- Expose the inputs the template needs before running.
+- Curate and retire templates so the gallery stays current.
+
+## Content
+
+- Names are tasks ("Find hiring managers for open roles").
+- Descriptions say the outcome in one line.
+
+## Accessibility
+
+- The gallery is a dialog labelled "Start from a template"; focus moves in on open, Esc closes and focus returns (APG dialog).
+- The category nav marks the current item with aria-current (SC 4.1.2, 1.3.1).
+- Search announces the number of matching templates (SC 4.1.3).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move between search, categories and cards |
+| Enter | Open the template as a draft |
+| Esc | Close the gallery |
+
+## Examples
+
+### gallery
+
+```tsx
+import { Button, TemplatesGallery, toast } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Start from a template", description: "Categories, search and cards that say what each template does and which tools it uses. Picking one opens a draft task; it never runs.", order: 1 };
+
+export default function Example() {
+	const [open, setOpen] = useState(false);
+	return (
+		<>
+			<Button variant="outline" onClick={() => setOpen(true)}>Browse templates</Button>
+			<TemplatesGallery
+				open={open}
+				onOpenChange={setOpen}
+				onPick={(t) => { setOpen(false); toast(`Opened “${t.name}” as a draft`); }}
+				templates={[
+					{ id: "1", name: "Weekly pipeline summary", does: "Summarises new applicants and stage changes every Monday.", tools: ["Listings", "Slack"], category: "Reporting" },
+					{ id: "2", name: "Listings at risk", does: "Finds listings closing soon with few applicants and proposes extensions.", tools: ["Listings"], category: "Listings" },
+					{ id: "3", name: "Interview slots", does: "Suggests interview times from interviewers' calendars.", tools: ["Calendar"], category: "Interviews" },
+					{ id: "4", name: "Job description review", does: "Checks a draft for salary, inclusive language and length.", tools: ["Listings", "Team files"], category: "Listings" },
+				]}
+			/>
+		</>
+	);
+}
+```
+
+## Related
+
+- Task builder
+- Prompt editor with fields
+- Follow-ups and starters

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

@@ -0,0 +1,160 @@
+# Text input
+
+Lets people type a single line of text, such as a job title, a salary or a search term.
+
+Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui
+
+## When to use
+
+- For short free text that cannot be listed in advance: job title, salary, a reference number. For dates use the Date picker (date-picker).
+- For search inside a view, with a search icon and an accessible label.
+- With a prefix or suffix for units the person should not type: £ and per year.
+
+## When not to use
+
+- To pick one option from a short known list. Use Radio buttons (up to seven) or a select.
+- For a yes/no setting. Use a Checkbox or Switch.
+- For choosing from existing categories. Use Combobox (combobox) so people choose instead of type; for several free values use Tag input (tag-input).
+
+## Structure
+
+1. Label
+2. Required marker (optional)
+3. Field with prefix/suffix (optional)
+4. Hint text (optional)
+5. Error message (when invalid)
+
+## Guidelines
+
+- 32px high, 6px radius, 13px text. Label sits above the field, left-aligned, 6px gap.
+- Hint text sits under the field and stays visible while typing. Use it for format and examples.
+- No placeholder in place of a label. Use placeholders only for a short example, or not at all.
+- Focus shows an primary border and a soft 3px ring. Invalid shows a red border plus a text message under the field.
+- Check the value when the person leaves the field, not while they type. Clear the error as soon as the value is fixed.
+- Accept common variations (18000, 18,000, £18k) and convert them, then show the cleaned value.
+
+## Content
+
+- Labels are short nouns in sentence case without a colon: Job title, Salary, Closing date.
+- Hint text says why or in what format: Shown on the listing and in search results.
+- Mark required fields with an asterisk after the label.
+- Error text uses UK English and says how to fix it: Enter at least £23,400.
+
+## Accessibility
+
+- Every field has a visible label tied to it with for/id. A placeholder is not a label.
+- Link hint and error to the field with aria-describedby; set aria-invalid="true" when it fails.
+- Field border needs 3:1 against the surface; typed text and hint text 4.5:1.
+- The asterisk is decorative (aria-hidden). Use the required attribute so screen readers announce it.
+- Error is not shown by colour alone: red border plus written message.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab / Shift+Tab | Move into and out of the field |
+| / | Focus the search field of the current view (single-key shortcut, can be turned off) |
+| Esc | Leave the search field |
+
+## Examples
+
+### affixes
+
+```tsx
+import { InputGroup, InputGroupAddon, InputGroupInput, Kbd, TextField } from "@twoux/ui";
+import { Search } from "lucide-react";
+
+export const meta = { title: "Prefix and suffix", description: "Units, currency and icons sit inside the field so the value reads as one thing. Built on shadcn's InputGroup.", order: 2 };
+
+export default function Example() {
+	return (
+		<div className="grid w-80 gap-4">
+			<TextField label="Salary" prefix="£" suffix="per year" defaultValue="32,000" inputMode="numeric" />
+			<InputGroup>
+				<InputGroupAddon><Search /></InputGroupAddon>
+				<InputGroupInput aria-label="Search listings" placeholder="Search listings" />
+				<InputGroupAddon align="inline-end"><Kbd>/</Kbd></InputGroupAddon>
+			</InputGroup>
+		</div>
+	);
+}
+```
+
+### field
+
+```tsx
+import { TextField } from "@twoux/ui";
+
+export const meta = { title: "With label and hint", description: "Every input has a visible label. The hint says what good input looks like. TextField links label, hint and error to the input for screen readers.", order: 1 };
+
+export default function Example() {
+	return (
+		<div className="grid w-80 gap-4">
+			<TextField label="Job title" hint="Shown on the listing and in search results." required defaultValue="Junior Product Designer" />
+			<TextField label="Hiring manager" optional placeholder="Search people" />
+		</div>
+	);
+}
+```
+
+### password
+
+```tsx
+import { InputGroupButton, TextField } from "@twoux/ui";
+import { Eye, EyeOff } from "lucide-react";
+import { useState } from "react";
+
+export const meta = { title: "Password with live feedback", description: "Type to see the message switch from what is missing to a green confirmation. The show and hide button names its action for screen readers. Pattern from Clerk.", order: 4 };
+
+export default function Example() {
+	const [value, setValue] = useState("correct-horse-42");
+	const [show, setShow] = useState(false);
+	const ok = value.length >= 8;
+	return (
+		<div className="w-80">
+			<TextField
+				label="Password"
+				type={show ? "text" : "password"}
+				value={value}
+				onChange={(e) => setValue(e.target.value)}
+				error={value && !ok ? "Use 8 or more characters." : undefined}
+				success={ok ? "Your password meets the requirements." : undefined}
+				suffix={
+					<InputGroupButton size="icon-xs" aria-label={show ? "Hide password" : "Show password"} onClick={() => setShow((s) => !s)}>
+						{show ? <EyeOff /> : <Eye />}
+					</InputGroupButton>
+				}
+			/>
+		</div>
+	);
+}
+```
+
+### states
+
+```tsx
+import { TextField } from "@twoux/ui";
+
+export const meta = { title: "States", description: "Error replaces the hint and says how to fix it. Disabled fields keep their value readable.", order: 3 };
+
+export default function Example() {
+	return (
+		<div className="grid w-80 gap-4">
+			<TextField label="Salary" prefix="£" defaultValue="18,000" required error="Enter at least £23,400, the UK minimum for a full-time role." />
+			<TextField label="Listing ID" defaultValue="LST-1041" disabled />
+		</div>
+	);
+}
+```
+
+## Related
+
+- Form validation
+- Date picker
+- Combobox
+- Tag input
+- Tooltip
+- Keyboard shortcut hint
+- Sign in
+- Onboarding step
+- File drop

package/agent/docs-md/thinking-steps.md

@@ -0,0 +1,89 @@
+# Thinking and steps
+
+A row that shows what the assistant is doing in words with a running timer, then collapses to "Thought for 2.1s · 4 steps" and expands on request.
+
+Kind: component · Group: AI and agents · Status: built, import from @twoux/ui
+
+## When to use
+
+- Any response that takes more than about a second, so people know what is happening instead of watching a bare spinner.
+- When the answer depends on what was read: steps say "Read 2 listings and 3,000 views" so people can judge scope.
+- Keeping the reasoning in the history after the answer arrives, so it can be checked later.
+
+## When not to use
+
+- Responses under a second. Stream the answer directly; short loading states flicker.
+- Multi-step agent work that changes records. Use the Agent run timeline (agent-run) with states and Stop.
+- Progress of applying approved changes. Use the Step card (step-card).
+
+## Structure
+
+1. Header (status mark, "Thinking", timer)
+2. Step list (short title and one line of detail each)
+3. Collapsed summary button ("Thought for Xs · N steps")
+
+## Guidelines
+
+- Say the current step in words ("Reading 9 listings"), never only an animation.
+- Show a running timer while thinking. When the answer starts, collapse to "Thought for 2.1s · 4 steps" with a check.
+- Each step has a short title and one line of detail. Keep plan, execution and evidence apart.
+- If the person answered clarifying questions, add a step "Using your answers" with their choices.
+- Stopping during thinking marks the header "Stopped" and removes unfinished steps; nothing is changed.
+
+## Content
+
+- Use present participles for running steps ("Reading listings", "Comparing with the board median") and past tense once done.
+- Include counts and time: "Read 2 listings and 3,000 views · 4s".
+- Do not write "Thinking deeply" or anything that implies a person or magic.
+
+## Accessibility
+
+- The thinking row is a polite live region; announce each step title, not the timer ticks (SC 4.1.3).
+- The running timer updates in parallel with other content, so Stop must be available (SC 2.2.2); the pulse animation is decorative and stops when done.
+- The collapsed summary is a disclosure button with aria-expanded; Enter or Space toggles the steps.
+- Step states use an icon shape as well as colour (SC 1.4.1).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Enter / Space | Expand or collapse finished steps |
+| Tab | Move to the summary button |
+
+## Examples
+
+### steps
+
+```tsx
+import { Button, ThinkingSteps } from "@twoux/ui";
+import { useEffect, useState } from "react";
+
+export const meta = { title: "Say what it is doing", description: "The current step in words with a running timer, never only an animation. When the answer starts, it collapses to a summary you can open.", order: 1 };
+
+const STEPS = [{ title: "Reading 24 listings", detail: "Open and closing soon" }, { title: "Comparing applicants with last quarter" }, { title: "Checking salary bands", detail: "Against the 2026 bands file" }, { title: "Writing the answer" }];
+
+export default function Example() {
+	const [n, setN] = useState(1);
+	const [t, setT] = useState(0);
+	const done = n > STEPS.length;
+	useEffect(() => {
+		if (done) return;
+		const i = setInterval(() => setT((x) => x + 0.1), 100);
+		const s = setTimeout(() => setN((x) => x + 1), 700);
+		return () => { clearInterval(i); clearTimeout(s); };
+	}, [n, done]);
+	return (
+		<div className="grid w-full max-w-md gap-3">
+			<ThinkingSteps done={done} seconds={t} steps={STEPS.slice(0, Math.min(n, STEPS.length))} />
+			<Button variant="outline" size="sm" className="justify-self-start" onClick={() => { setN(1); setT(0); }}>Replay</Button>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Assistant side panel
+- Agent run timeline
+- Step card
+- Clarifying question card