@twoux/ui 0.0.0-stage → 0.1.1

package/agent/docs-md/saved-views.md

@@ -0,0 +1,149 @@
+# Saved views
+
+Named, reusable combinations of filters, sort order and column choices, also kept in the URL so a link reproduces the view.
+
+Kind: component · Group: Data · Status: built, import from @twoux/ui
+
+## When to use
+
+- People apply the same filter configuration on every visit; saving it reduces memory load and repeat work.
+- A team needs shared starting points, such as "Expiring this week".
+- Expert users want to customise the interface to their own needs.
+
+## When not to use
+
+- For one-off filtering. Use the TwoUX Filter bar; a URL already preserves the state.
+- For display choices only. Use the TwoUX Columns menu, which is saved per person per table.
+
+## Structure
+
+1. View switcher (tabs or select) with live counts
+2. Save view (rectangle button, shown when filters are on)
+3. Unsaved changes indicator
+4. Manage: rename, update, set default, delete
+
+## Guidelines
+
+- A view stores filters, sort order and column choices together.
+- Keep filter state in the URL. On arrival, apply the default view unless the URL carries filter parameters.
+- Show unsaved changes and let people return to the saved state in one step.
+- Confirm before deleting or overwriting a view, naming the view in the dialog.
+- Show only the metadata people need to tell views apart, such as name and live count.
+
+## Content
+
+- Name views after what they show, "Expiring this week", not "View 3".
+- Use fixed action labels for the lifecycle: "Save view", "Update view", "Delete view", "Set as default".
+- Confirmation text says what will change, for example that deleting removes the saved filters and columns.
+- Most people will not customise, so ship sensible default views.
+
+## Accessibility
+
+- 4.1.2 Name, Role, Value: the view switcher exposes the current view as selected.
+- APG dialog pattern: the delete confirmation traps focus, closes on Escape and returns focus to the trigger.
+- 4.1.3 Status Messages: "View saved" is announced without moving focus.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab, ← → | Move between views |
+| Enter | Apply the view |
+| Esc | Close the save or manage dialog |
+
+## Examples
+
+### views
+
+```tsx
+import { FilterBar, FilterPill, SavedViews, type SavedView, toast } from "@twoux/ui";
+import { useState } from "react";
+
+export const meta = { title: "Views with live counts", description: "A view stores filters, sort and columns together. Change a filter and the view shows Unsaved changes, with Reset and Update one click away. The ⋮ menu renames, sets the default or deletes the current view; deleting offers Undo.", order: 1 };
+
+const OPTIONS = ["Open", "Closing soon", "Draft", "Closed"].map((v) => ({ value: v, label: v }));
+
+export default function Example() {
+	const [views, setViews] = useState<SavedView[]>([
+		{ id: "all", name: "All listings", count: 24 },
+		{ id: "open", name: "Open", count: 14 },
+		{ id: "closing", name: "Closing soon", count: 4 },
+	]);
+	const [saved, setSaved] = useState<Record<string, string[]>>({ all: [], open: ["Open", "Closing soon"], closing: ["Closing soon"] });
+	const [defaultId, setDefaultId] = useState("all");
+	const [view, setView] = useState("open");
+	const [status, setStatus] = useState(saved.open);
+	const current = saved[view] ?? [];
+	const dirty = status.length !== current.length || status.some((s) => !current.includes(s));
+	const open = (id: string) => { setView(id); setStatus(saved[id] ?? []); };
+	const nameOf = (id: string) => views.find((v) => v.id === id)?.name ?? "";
+
+	return (
+		<div className="grid w-full max-w-2xl gap-3">
+			<SavedViews
+				views={views}
+				value={view}
+				onValueChange={open}
+				dirty={dirty}
+				defaultId={defaultId}
+				onReset={() => setStatus(current)}
+				onSave={() => {
+					const before = current;
+					setSaved((s) => ({ ...s, [view]: status }));
+					toast.success(`Updated “${nameOf(view)}”`, { action: { label: "Undo", onClick: () => setSaved((s) => ({ ...s, [view]: before })) } });
+				}}
+				onSaveAs={(name) => {
+					const id = `${name.toLowerCase().replace(/\W+/g, "-")}-${views.length}`;
+					setSaved((s) => ({ ...s, [id]: status }));
+					setViews((v) => [...v, { id, name, count: 6 }]);
+					setView(id);
+					toast.success(`Saved “${name}”`);
+				}}
+				onRename={(id, name) => {
+					const before = nameOf(id);
+					const rename = (to: string) => setViews((v) => v.map((x) => (x.id === id ? { ...x, name: to } : x)));
+					rename(name);
+					toast.success(`Renamed “${before}” to “${name}”`, { action: { label: "Undo", onClick: () => rename(before) } });
+				}}
+				onSetDefault={(id) => {
+					const before = defaultId;
+					setDefaultId(id);
+					toast.success(`“${nameOf(id)}” opens by default`, { action: { label: "Undo", onClick: () => setDefaultId(before) } });
+				}}
+				onDelete={(id) => {
+					const index = views.findIndex((v) => v.id === id);
+					const removed = views[index];
+					const next = views.filter((v) => v.id !== id);
+					const wasDefault = id === defaultId;
+					setViews(next);
+					// Deleting the default hands it to the first view left; the open view moves to the default.
+					const fallback = wasDefault ? next[0].id : defaultId;
+					if (wasDefault) setDefaultId(fallback);
+					open(fallback);
+					toast.success(`Deleted “${removed.name}”`, {
+						action: {
+							label: "Undo",
+							onClick: () => {
+								setViews((v) => [...v.slice(0, index), removed, ...v.slice(index)]);
+								if (wasDefault) setDefaultId(id);
+								open(id);
+							},
+						},
+					});
+				}}
+			/>
+			<FilterBar>
+				<FilterPill field="Status" options={OPTIONS} selected={status} onChange={setStatus} />
+			</FilterBar>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Filter pills and filter bar
+- Filter panel
+- Columns menu
+- List table
+- Data grid

package/agent/docs-md/saving-views.md

@@ -0,0 +1,68 @@
+# Saved views
+
+Store a filtered, sorted, column-chosen list under a name so people and teams return to it in one click.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** People rebuild the same filters every morning, and teams share screenshots of lists instead of links. Without one way to save, each screen invents its own favourites.
+
+**Solution:** When filters are on, Save view stores filters, sort and columns together with a name. Views show live counts, mark unsaved changes, and reproduce from the URL.
+
+**Built from:** Saved views, Filter pills and filter bar, Columns menu, List table, Data grid, Tabs (underline)
+
+## How it works
+
+1. Save view appears only once at least one filter, sort or column change differs from the default.
+2. Save view asks for a name (required) and an optional description, validating duplicate names inline.
+3. The view appears as a tab or sidebar item with its live row count, for example "Live 14".
+4. If the person changes a saved view, its name shows an unsaved mark and the menu offers Update view, Save as new and Revert.
+5. The view's state also lives in the URL, so a copied link opens the same view for anyone with access.
+
+## When to use
+
+- For lists people check repeatedly with the same filters, such as "My live listings" or "Closing this week".
+- To give a team a shared starting point that everyone sees the same way.
+
+## When not to use
+
+- For a one-off filter. The URL already makes it shareable; use Filtering and search.
+- For per-person display choices such as row density or wrapping. Those belong in the Columns menu and are remembered automatically.
+
+## Guidelines
+
+- A view stores filters, sort order, visible columns and grouping. Opening it restores all four.
+- A default view loads when the page opens, unless the URL already carries filters.
+- Changing a saved view never overwrites it silently. Updating needs an explicit Update view.
+- Deleting a view uses a simple confirmation, because a team view can be in other people's sidebars.
+- Keep the number of pinned views short; long rows of tabs slow the choice down.
+- Group the views list into Team views and My views, and add a search box once there are more than about ten.
+- People can set any view as their own default with Set as default. It is unavailable while the current view has unsaved changes, and the reason is shown.
+- Update view shows the filters before and after in the menu, then saves with Undo in the toast.
+- People can drop unsaved changes in any of three ways: Revert, choosing the view again, or Clear filters.
+
+## Content
+
+- Name views by what they contain, not who made them: "Closing this week", not "Rahul's view".
+- Menu actions: "Save view", "Save as new view", "Update view", "Revert changes", "Delete view".
+
+## Accessibility
+
+- The unsaved mark is text ("Edited") as well as a dot, so it does not rely on colour.
+- Confirm a save with a status message announced politely, not a moved focus.
+
+## Do
+
+- Do show the live count on each view.
+- Do mark a modified view and offer Revert.
+
+## Don't
+
+- Don't save a view automatically when filters change.
+- Don't store a view only in local storage; it must reproduce from its link.
+
+## Related
+
+- Filtering and search
+- Keyboard-first navigation
+- Saved views
+- Columns menu

package/agent/docs-md/scheduler.md

@@ -0,0 +1,258 @@
+# Scheduler
+
+Interviews, shifts or bookings on a day, week or month grid, with people or rooms as resources. Click a free time to add, click an event to open it, and drag, use the keyboard or the event menu to move it. Below 768px it becomes an agenda list.
+
+Kind: component · Group: Data · Status: built, import from @twoux/ui
+
+## When to use
+
+- Booking and arranging time-bound records where free time matters, such as interviews across several interviewers, shifts or room bookings.
+- Seeing who is busy when, side by side, before choosing a time.
+
+## When not to use
+
+- For a list of upcoming items with no need to see free time; use a Grouped list or List table with Timestamps.
+- For a record's history of changes; use Timeline.
+- For picking one date in a form; use a date field.
+- For editing recurring series; the Scheduler shows events the app has already expanded and has no recurrence editor.
+
+## Structure
+
+1. Toolbar: Today, Previous, Next, period heading, time zone, Day / Week / Month
+2. Resource legend: stripe and name
+3. Time gutter, 24-hour, with a labelled now line
+4. Column headers: days, or resources in day view
+5. All-day row
+6. 30-minute slots
+7. Event: resource stripe, title, detail, time, resource, status badge, ⋮ menu
+8. Month cells with up to three events and +N more
+9. Agenda list grouped by day, below 768px
+
+## Guidelines
+
+- Switch Day, Week and Month with the segmented control; they are views of the same data.
+- Open an event in the side panel with onSelectEvent, so people keep their place in the schedule.
+- Create from a free time with onCreate and a dialog of up to three fields; the time comes from the slot.
+- Apply every move at once with a toast offering Undo. Confirm first only if the move contacts someone outside the workspace, such as re-sending a candidate invite.
+- Every drag has a keyboard path (Space, arrows, Enter, Esc) and a menu path (the event's ⋮: earlier, later, other day, longer, shorter, another resource).
+- Resource colour is a left stripe from the series colours; text stays ink and the resource is always named.
+- Keep day and week views to working hours (dayStart, dayEnd) and use workWeek when weekends are never booked.
+- Below 768px the grid becomes an agenda grouped by day, so the schedule reflows to 320px without sideways scrolling.
+- Loading shows skeleton rows inside the frame; an error says what failed with Try again; an empty period says so and stays clickable.
+
+## Content
+
+- Times are 24-hour with an en dash: 09:30–10:15. Weeks start on Monday. Day headings read Thursday 12 November.
+- Write the time zone once in the toolbar: Times in GMT. Details in the side panel use Timestamp in absolute format.
+- Name the noun in the empty message: No interviews this week. Choose a free time to add one.
+- Status is a word in a Badge (Confirmed, Tentative), never a colour alone.
+
+## Accessibility
+
+- 2.1.1 Keyboard: the grid is one tab stop with roving focus; arrows walk free times and events in time order, and Enter opens or adds.
+- 2.5.7 Dragging Movements: moving and resizing also work with Space and arrows, and from the event menu with single clicks.
+- 4.1.3 Status Messages: pick-up, each step, drop and cancel are announced in a polite live region.
+- Month view follows the APG calendar grid: arrows by day and week, Enter lists the day's events.
+- 1.4.1 Use of Color: resources and status are written in words; colour repeats them.
+- 1.4.10 Reflow: the agenda replaces the grid below 768px.
+- 2.1.4 Character Key Shortcuts: T, J, K, D, W and M stop when single-key shortcuts are turned off; keys inside the focused grid are not affected.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| T | Go to today |
+| J K | Next or previous day, week or month |
+| D W M | Day, week or month view |
+| ↑ ↓ | Previous or next free time or event in the column |
+| ← → | Same time in the previous or next column |
+| Home End | First or last time in the column |
+| Page up Page down | Previous or next period |
+| Enter | Open the event, or add one at the free time |
+| Space | Pick up the event to move it |
+| ↑ ↓ ← → (moving) | Move by one slot, or to the next day or interviewer |
+| ⇧↑ ⇧↓ (moving) | Make it shorter or longer |
+| Enter Space (moving) | Drop it here |
+| Esc | Cancel the move and put it back |
+| ⇧F10 | Open the event menu |
+
+## Examples
+
+### interviews
+
+```tsx
+import {
+	Badge, Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, RadioField, RadioGroup,
+	Scheduler, SidePanel, TextField, Timestamp, formatTimeRange, toast, type SchedulerEvent, type SchedulerSlot, type SchedulerView,
+} from "@twoux/ui";
+import { useState } from "react";
+import { INTERVIEWERS, INTERVIEWS, NOW, STATUS_VARIANT } from "./data";
+
+export const meta = {
+	title: "Interview week",
+	description: "Three interviewers, one week. Click an interview to open it beside the schedule; click a free time to add one. Drag to move or the bottom edge to change the length; Space, arrows and Enter do the same from the keyboard, and the ⋮ menu offers the same moves. Every move has Undo.",
+	order: 1,
+};
+
+const TYPES = ["Phone screen", "Technical interview", "Final interview"];
+const name = (id?: string) => INTERVIEWERS.find((r) => r.id === id)?.label;
+
+export default function Example() {
+	const [events, setEvents] = useState(INTERVIEWS);
+	const [view, setView] = useState<SchedulerView>("week");
+	const [date, setDate] = useState(NOW);
+	const [openId, setOpenId] = useState<string | null>(null);
+	const [draft, setDraft] = useState<SchedulerSlot | null>(null);
+	const [candidate, setCandidate] = useState("");
+	const [type, setType] = useState(TYPES[0]);
+	const [interviewer, setInterviewer] = useState("tom");
+	const [error, setError] = useState<string | undefined>();
+	const open = events.find((e) => e.id === openId) ?? null;
+
+	const move = (ev: SchedulerEvent, to: SchedulerSlot) => {
+		const before = events;
+		setEvents((list) => list.map((e) => (e.id === ev.id ? { ...e, start: to.start.toISOString(), end: to.end.toISOString(), resourceId: to.resourceId } : e)));
+		toast.success(`${ev.title} moved to ${to.start.toLocaleDateString("en-GB", { weekday: "long" })} ${formatTimeRange(to.start, to.end)}`, { action: { label: "Undo", onClick: () => setEvents(before) } });
+	};
+	const startCreate = (slot: SchedulerSlot) => {
+		setDraft(slot); setCandidate(""); setType(TYPES[0]); setInterviewer(slot.resourceId ?? "tom"); setError(undefined);
+	};
+	const create = (e: React.FormEvent) => {
+		e.preventDefault();
+		if (!draft) return;
+		if (!candidate.trim()) { setError("Enter the candidate's name."); return; }
+		const id = `INT-${300 + events.length}`;
+		setEvents((list) => [...list, { id, title: type, detail: candidate.trim(), start: draft.start.toISOString(), end: draft.end.toISOString(), resourceId: interviewer, status: "Tentative" }]);
+		setDraft(null);
+		toast.success(`${type} added for ${candidate.trim()}`, { action: { label: "Undo", onClick: () => setEvents((list) => list.filter((x) => x.id !== id)) } });
+	};
+
+	return (
+		<div className="flex w-full overflow-hidden rounded-sm">
+			<div className="min-w-0 flex-1">
+				<Scheduler
+					aria-label="Interviews"
+					noun="interviews"
+					resourceTitle="Interviewer"
+					events={events}
+					resources={INTERVIEWERS}
+					view={view}
+					onViewChange={setView}
+					date={date}
+					onDateChange={setDate}
+					now={NOW}
+					workWeek
+					height={460}
+					selectedId={openId ?? undefined}
+					statusVariant={STATUS_VARIANT}
+					onSelectEvent={(e) => setOpenId(e.id)}
+					onCreate={startCreate}
+					onMove={move}
+				/>
+			</div>
+			{open && (
+				<SidePanel
+					open
+					onOpenChange={(o) => !o && setOpenId(null)}
+					mode="overlay"
+					label="Interview details"
+					title={open.detail ? `${open.title}, ${open.detail}` : open.title}
+					meta={<span className="flex items-center gap-2"><span className="font-mono">{open.id}</span>{open.status && <Badge variant={STATUS_VARIANT(open.status)}>{open.status}</Badge>}</span>}
+					footer={<Button size="sm" variant="outline">Edit interview</Button>}
+				>
+					<dl className="grid grid-cols-2 gap-x-3 gap-y-2 text-base">
+						<dt className="text-ink-2">Starts</dt><dd><Timestamp value={open.start} format="absolute" /></dd>
+						<dt className="text-ink-2">Ends</dt><dd><Timestamp value={open.end} format="absolute" /></dd>
+						<dt className="text-ink-2">Interviewer</dt><dd className="text-ink">{name(open.resourceId) ?? "Not assigned"}</dd>
+						<dt className="text-ink-2">Role</dt><dd className="text-ink">Senior Backend Engineer</dd>
+					</dl>
+				</SidePanel>
+			)}
+			<Dialog open={!!draft} onOpenChange={(o) => !o && setDraft(null)}>
+				<DialogContent>
+					<form onSubmit={create} className="grid gap-4" noValidate>
+						<DialogHeader>
+							<DialogTitle>Add interview</DialogTitle>
+							<DialogDescription>{draft && <Timestamp value={draft.start} format="absolute" />}{draft && `, until ${formatTimeRange(draft.start, draft.end).split("–")[1]}`}</DialogDescription>
+						</DialogHeader>
+						<TextField label="Candidate" required value={candidate} onChange={(e) => { setCandidate(e.target.value); setError(undefined); }} error={error} autoFocus />
+						<fieldset className="grid gap-2">
+							<legend className="mb-2 text-base font-medium text-ink">Interview type</legend>
+							<RadioGroup value={type} onValueChange={setType}>
+								{TYPES.map((t) => <RadioField key={t} id={`type-${t}`} value={t} label={t} />)}
+							</RadioGroup>
+						</fieldset>
+						<fieldset className="grid gap-2">
+							<legend className="mb-2 text-base font-medium text-ink">Interviewer</legend>
+							<RadioGroup value={interviewer} onValueChange={setInterviewer}>
+								{INTERVIEWERS.map((r) => <RadioField key={r.id} id={`who-${r.id}`} value={r.id} label={r.label} />)}
+							</RadioGroup>
+						</fieldset>
+						<DialogFooter>
+							<Button type="button" variant="outline" onClick={() => setDraft(null)}>Cancel</Button>
+							<Button type="submit">Add interview</Button>
+						</DialogFooter>
+					</form>
+				</DialogContent>
+			</Dialog>
+		</div>
+	);
+}
+```
+
+### states
+
+```tsx
+import { SegmentedControl, Segment, Scheduler, type SchedulerView } from "@twoux/ui";
+import { useState } from "react";
+import { INTERVIEWERS, INTERVIEWS, NOW, STATUS_VARIANT } from "./data";
+
+export const meta = {
+	title: "Agenda, loading, empty and error",
+	description: "Below 768px the grid becomes this agenda, grouped by day, so the schedule reflows to 320px; it is also the list view for screen reader users who prefer one. Loading keeps the frame with skeleton rows, an error says what failed with Try again, and an empty week says so.",
+	order: 2,
+};
+
+type Demo = "agenda" | "loading" | "error" | "empty";
+
+export default function Example() {
+	const [demo, setDemo] = useState<Demo>("agenda");
+	const [view, setView] = useState<SchedulerView>("week");
+	const [date, setDate] = useState(NOW);
+	return (
+		<div className="grid w-full max-w-md gap-3">
+			<SegmentedControl value={demo} onValueChange={(v) => setDemo(v as Demo)} size="sm" aria-label="State" className="justify-self-start">
+				<Segment value="agenda">Agenda</Segment><Segment value="loading">Loading</Segment><Segment value="error">Error</Segment><Segment value="empty">Empty</Segment>
+			</SegmentedControl>
+			<Scheduler
+				aria-label="Interviews"
+				noun="interviews"
+				resourceTitle="Interviewer"
+				events={demo === "empty" ? [] : INTERVIEWS}
+				resources={INTERVIEWERS}
+				view={view}
+				onViewChange={setView}
+				date={date}
+				onDateChange={setDate}
+				now={NOW}
+				workWeek
+				layout="agenda"
+				status={demo === "loading" ? "loading" : demo === "error" ? "error" : "ready"}
+				onRetry={() => setDemo("agenda")}
+				statusVariant={STATUS_VARIANT}
+				onSelectEvent={() => {}}
+				onMove={() => {}}
+			/>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Side panel (drawer)
+- Segmented control
+- Grouped list
+- List table
+- Dropdown menu
+- Confirmation dialog

package/agent/docs-md/secondary-panels.md

@@ -0,0 +1,72 @@
+# Secondary panels: which right-hand panel
+
+TwoUX has one right-hand panel slot. Record detail, the assistant, help and filters each have a clear job, only one is open at a time, and none is ever required to finish a task.
+
+Kind: pattern · Group: Patterns: general
+
+**Problem:** When every feature adds its own panel, people can't tell which icon opens what, panels pile up and crush the table, and tasks end up depending on something hidden behind a toggle.
+
+**Solution:** Choose the panel by what the person is trying to do: look at a record (side panel), ask about the data (assistant panel), learn how something works (help panel), narrow a large search (filter panel). Opening one replaces the one already in the slot.
+
+**Built from:** Side panel (drawer), Assistant side panel, Help panel, Filter panel, App shell and sidebar navigation
+
+## How it works
+
+1. Name the person's goal: review a record, get an answer about the data, learn the product, or narrow results.
+2. Pick the panel: side panel for a record, assistant panel for questions, help panel for guidance, filter panel for searches with many fields.
+3. Check the main task can be finished without the panel. If it can't, the content belongs in the page.
+4. Open the panel only from a person's action; opening it moves the previous panel out of the slot, and closing it brings that panel back.
+
+## When to use
+
+- For supporting information or tools that relate to the page the person is on.
+- When the person benefits from seeing the list and the extra content side by side.
+- When the extra content should stay open while people move through records with J and K.
+
+## When not to use
+
+- For a decision that must interrupt the task. Use a confirmation dialog.
+- For a long, standalone task such as editing a whole listing. Use a full page.
+- For content unrelated to the current page, such as account settings.
+
+## Guidelines
+
+- At most three panel types on any page. If a fourth is needed, one of them is probably a page or a dialog.
+- Triggers sit in a fixed order wherever they appear: record detail opens from the row, then Assistant (⌘J), then Help.
+- Panels are secondary: they can speed a task up, but every task can be completed without opening one.
+- Help panel content is read-only; side panel, assistant and filter panel content can be interactive.
+- Below 860px the open panel takes the full width of the canvas and has a clear close button.
+
+## Content
+
+- Trigger buttons have text or a tooltip with the panel name and shortcut: "Assistant ⌘J", "Help".
+- The panel heading names what is inside: the record title, "Assistant", or the help topic.
+- Close buttons are named for the panel: "Close help", "Close assistant".
+
+## Accessibility
+
+- Every panel is a labelled complementary region, not a modal, unless it overlays content (then it follows the dialog pattern).
+- Opening a panel from a control moves focus into it; Esc closes it and focus returns to the control.
+- The panel never hides the focused element on the page (2.4.11).
+
+## Do
+
+- Do choose the panel from the person's goal.
+- Do keep panel triggers in the same order on every page.
+- Do restore the previous panel when the newer one closes.
+
+## Don't
+
+- Don't open two right-hand panels at once.
+- Don't open a panel on page load.
+- Don't hide a required step inside a panel.
+
+## Related
+
+- Record detail: side panel, overlay or full page
+- Ask about what's on screen
+- Contextual help
+- Side panel (drawer)
+- Assistant side panel
+- Help panel
+- Filter panel

package/agent/docs-md/segmented-control.md

@@ -0,0 +1,88 @@
+# Segmented control
+
+Switches between two or three views or settings of the same content, such as All, Active and Backlog.
+
+Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui
+
+## When to use
+
+- To switch how the same data is shown or filtered: All / Active / Backlog, Chart / Table.
+- For a view setting that always has a value: Rows per page 25 / 50 / 100, Daily / Weekly.
+- When there are two or three short options and room to show them.
+
+## When not to use
+
+- For separate sections of a record. Use Tabs.
+- For more than three options. Use a Dropdown menu or select.
+- For an on/off setting. Use Switch.
+- For choices inside a form that is saved later. Use Radio.
+
+## Structure
+
+1. Group label (often visually hidden)
+2. Track
+3. Segment buttons
+4. Selected segment (white, raised)
+
+## Guidelines
+
+- Track is grey with a 2px inset; segments are 24px high, 12px medium text; selected segment is white with a hairline shadow.
+- The change applies immediately, like a switch.
+- Equal weight for all segments; one is always selected.
+- Deactivate at most one segment, and give the reason in a tooltip.
+
+## Content
+
+- One word per segment where possible.
+- Sentence case, parallel words: All, Active, Backlog.
+- Icon-only segments need alternative text naming the view.
+
+## Accessibility
+
+- TwoUX renders it as a group of toggle buttons: role="group" with aria-label, each button with aria-pressed.
+- Every segment label stays the same when pressed; state comes from aria-pressed.
+- Segments are 24px high, exactly the WCAG 2.5.8 minimum; do not make them smaller.
+- The selected segment differs by fill and shadow, with 3:1 against the track.
+- Visible focus ring on each segment.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move to each segment |
+| Enter / Space | Select the focused segment |
+
+## Examples
+
+### views
+
+```tsx
+import { Segment, SegmentedControl } from "@twoux/ui";
+import { List, Rows3 } from "lucide-react";
+import { useState } from "react";
+export const meta = {"title": "Views of the same data", "description": "Two or three options, one always selected. Switches how the same list is shown; it never navigates.", "order": 1};
+
+export default function Example() {
+	const [v, setV] = useState("active");
+	const [d, setD] = useState("list");
+	return (
+		<div className="flex flex-wrap items-center gap-4">
+			<SegmentedControl aria-label="Listings to show" value={v} onValueChange={setV}>
+				<Segment value="all">All</Segment>
+				<Segment value="active">Active</Segment>
+				<Segment value="closed">Closed</Segment>
+			</SegmentedControl>
+			<SegmentedControl aria-label="Layout" size="sm" value={d} onValueChange={setD}>
+				<Segment value="list" aria-label="List"><List /></Segment>
+				<Segment value="board" aria-label="Board"><Rows3 /></Segment>
+			</SegmentedControl>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Tabs (underline)
+- Radio
+- Switch