@twoux/ui 0.0.0-stage → 0.1.1

package/agent/docs-md/avatar.md

@@ -0,0 +1,82 @@
+# Avatar and avatar stack
+
+Shows who owns or is linked to a record, as a photo or initials, and several people as an overlapping stack with +N.
+
+Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui
+
+## When to use
+
+- To show the owner of a listing or the recruiter on a candidate, next to their name or in a table cell.
+- A stack when several people relate to one record and space is short.
+
+## When not to use
+
+- When each person must be clearly identified. List names in full.
+- For a single person in a stack. Use one avatar.
+- For teams or categories. Use Tag.
+
+## Structure
+
+1. Circle (22px)
+2. Photo or initials
+3. Stack: overlapping avatars with 2px white ring
+4. +N overflow count
+
+## Guidelines
+
+- 22px circle, 10px semibold white initials on a colour assigned per person; photo when one exists.
+- Stack shows up to three, overlapping by 6px with a 2px white ring, then +N in small grey text.
+- +N reveals the hidden names on hover or focus.
+- Each person keeps the same colour everywhere.
+
+## Content
+
+- Initials stand in when there is no photo, and are hidden from screen readers when the name is shown.
+- The +N count says how many people are hidden, not the total.
+- Tooltips on avatars show the full name, matching the alt text.
+
+## Accessibility
+
+- Standalone avatars have alt text with the person's name; next to a visible name they are decorative (empty alt).
+- A stack has a label (for example Candidates) and screen reader text for +N: 3 more candidates.
+- White initials need 4.5:1 on the assigned colour; pick colours that pass.
+- If the avatar opens a tooltip or popover it must be focusable.
+- Interactive avatars are 22px, so keep 24px spacing from other targets.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab to +N | Focus the overflow count and show hidden names |
+
+## Examples
+
+### people
+
+```tsx
+import { AvatarStack, PersonAvatar } from "@twoux/ui";
+
+export const meta = { title: "Owners and interviewers", description: "Initials on a colour fixed per person (white text at 5.8:1 or more). A stack shows three, then +N, which names the rest on hover or focus.", order: 1 };
+
+export default function Example() {
+	return (
+		<div className="grid gap-4">
+			<div className="flex items-center gap-3">
+				<PersonAvatar name="Priya Shah" size="lg" /><PersonAvatar name="Tom Becker" /><PersonAvatar name="Amara Okafor" size="sm" />
+				<span className="text-base text-ink-2">Priya Shah owns this listing</span>
+			</div>
+			<div className="flex items-center gap-3">
+				<AvatarStack label="Interviewers" people={[{ name: "Priya Shah" }, { name: "Tom Becker" }, { name: "Amara Okafor" }, { name: "Liam Walsh" }, { name: "Sofia Romano" }]} />
+				<span className="text-base text-ink-2">5 interviewers</span>
+			</div>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Tag
+- Tooltip
+- Status badge
+- Provider logo

package/agent/docs-md/banner.md

@@ -0,0 +1,106 @@
+# Banner (inline alert)
+
+A persistent message inside the page about a condition that affects what the person is looking at, with at most one action.
+
+Kind: component · Group: Feedback and overlays · Status: built, import from @twoux/ui
+
+## When to use
+
+- A condition on the current page that stays true until it is resolved, such as "Two listings expire this week."
+- Something blocks a task until fixed, such as form errors before Publish.
+- Data-loss or connection problems that affect the whole page. These may sit above the page header.
+
+## When not to use
+
+- Confirming an action the person just took. Use a Toast.
+- Background events that need someone to act later. Use the Inbox.
+- A whole region failed to load. Use the Error state in place of that region.
+- Feature announcements or tips. Leave them out, or put them in the setup checklist in the sidebar.
+
+## Structure
+
+1. Icon (info, warning or error)
+2. Message: one sentence
+3. Dismiss (ghost), only when nothing is blocked
+4. One action (secondary button), such as Review
+5. Form variant: error strip with count and "Go to first" link
+
+## Guidelines
+
+- Place the banner in context: above the table it refers to, or above the submit button for form problems.
+- Show one banner per region. If several apply, order them from most to least severe.
+- Offer Dismiss only when nothing is blocked and no action is required. Condition banners clear themselves when the condition ends.
+- At most one action, as a secondary button on the right. Dismiss sits before it as a ghost button.
+- Use neutral styling for information and keep red for errors that stop the task.
+- The form error strip counts the problems and links to the first one: "2 fields need fixing before you can publish. Go to first".
+
+## Content
+
+- Say what is true and what to do: the condition, then a verb on the button ("Review").
+- One or two short sentences, sentence case, no title when one sentence is enough.
+- For errors, say what went wrong and how to recover, without blaming the person.
+- No apologies, no "please", no exclamation marks.
+
+## Accessibility
+
+- Information banners that appear after load sit in a polite live region; the form error strip uses role="alert" because it reports a blocking problem (4.1.3).
+- The icon is never the only cue: the sentence states severity in words, and the icon has an accessible label (1.4.1).
+- Errors name the field and describe the problem in text, and "Go to first" moves focus to it (3.3.1).
+- A banner must not be sticky over content in a way that hides the focused element (2.4.11).
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Reaches Dismiss, then the action |
+| Enter | Activates the focused button or the "Go to first" link |
+
+## Examples
+
+### states
+
+```tsx
+import { Alert, AlertAction, AlertDescription, AlertTitle, Button } from "@twoux/ui";
+import { CircleAlert, Info, TriangleAlert } from "lucide-react";
+import { useState } from "react";
+
+export const meta = { title: "Information, warning and error", description: "Information is neutral and can be dismissed. A warning names one next step. An error that blocks publishing counts the problems and links to the first.", order: 1 };
+
+export default function Example() {
+	const [showInfo, setShowInfo] = useState(true);
+	return (
+		<div className="grid w-full max-w-xl gap-3">
+			{showInfo && (
+				<Alert>
+					<Info />
+					<AlertTitle>Salary bands were updated on 3 November.</AlertTitle>
+					<AlertAction>
+						<Button variant="ghost" size="sm" onClick={() => setShowInfo(false)}>Dismiss</Button>
+					</AlertAction>
+				</Alert>
+			)}
+			<Alert variant="warning">
+				<TriangleAlert />
+				<AlertTitle>4 listings close this week with no applicants.</AlertTitle>
+				<AlertAction>
+					<Button variant="outline" size="sm">Review</Button>
+				</AlertAction>
+			</Alert>
+			<Alert variant="destructive">
+				<CircleAlert />
+				<AlertTitle>2 fields need fixing before you can publish.</AlertTitle>
+				<AlertDescription>
+					<a href="#salary" className="font-medium text-ink underline decoration-bad-line underline-offset-2 hover:decoration-bad">Go to first</a>
+				</AlertDescription>
+			</Alert>
+		</div>
+	);
+}
+```
+
+## Related
+
+- Toast
+- Error state (failed to load)
+- Notifications vs inbox vs toast
+- Page header

package/agent/docs-md/board.md

@@ -0,0 +1,163 @@
+# Board and board item
+
+A dashboard grid of self-contained items, such as charts, stats and lists, that people can reorder, resize and remove to build the overview they need.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- For an overview page people tailor to their own job, such as a hiring lead choosing which pipeline charts to watch.
+- When each item stands alone and can be read without the others.
+
+## When not to use
+
+- For a fixed report everyone reads the same way. Lay it out with a plain grid; rearranging adds work without benefit.
+- For a list of records. Use the List table.
+
+## Structure
+
+1. Board: a grid of up to 4 columns that stacks on narrow screens
+2. Board item: drag handle, title and optional description, settings menu
+3. Item content (padded by default)
+4. Item footer (optional), such as a link to the full report
+5. Empty slot: what shows when no items are on the board
+
+## Guidelines
+
+- Each item does one job: one chart, one stat, one short list. Its title names what it shows.
+- Put the most important item first: the first row is what people see before they scroll.
+- Every drag has two alternatives: the keyboard (pick up with Enter or Space, move with arrows, drop with Enter, Esc to cancel) and the item menu (Move earlier, Move later, Wider, Narrower).
+- Announce every pick-up, move, resize, drop and removal to screen readers.
+- Show an empty state with a way to add the first item when the board has none.
+- Save the layout per person, so a change on one screen doesn't move someone else's dashboard.
+- Add items opens the items palette in the side panel. Removed items return to the palette, so Remove and Add undo each other.
+- Offer Reset to default layout in the page's more menu, applied at once with Undo in a toast.
+- Save the layout on the server as each change happens, per person and per column count (4, 2 and 1), and restore it on reload and on other devices.
+- The board has 4 columns on wide screens, 2 on tablet widths and 1 on phones; items span 1 to 4 columns and keep their order when stacking.
+- When the board has no items, its empty state offers Add items and Reset to default layout.
+- While dragging, show a drop preview of the item's size. Items swap where there is room and push others along where there is not; dropping outside the board returns the item to where it was.
+- Moving an item keeps its size and its own settings. Heights snap to fixed row steps; the default height fits the default content.
+- Show every stage of a drag. Ready: the grip darkens on hover and focus, with a grab cursor and a tooltip saying how to move it. Dragging: a lifted copy follows the pointer, the board tints to show where drops are allowed, and a dashed slot shows exactly where the item will land.
+- Other items glide to make room (180ms, off with reduced motion) instead of jumping. On drop, a short highlight settles on the moved item and the new position is announced. Esc cancels and puts it back.
+- Work out the landing slot against where items were when the drag started, so the slot doesn't jump as items move aside.
+
+## Content
+
+- Item titles are nouns for what is shown: “Applications this month”, not “Chart 1”.
+- The menu says what will happen to the item: “Move earlier”, “Wider”, “Remove from dashboard”.
+
+## Accessibility
+
+- The drag handle is a button named “Move <title>”, with a description of the keys.
+- Dragging is never the only way to move or resize (2.5.7 Dragging Movements).
+- Moves and resizes are announced in a live region (4.1.3 Status Messages).
+- Each item is an article labelled by its title, so screen reader users can jump between items.
+- Every board item region has an accessible name, and the board offers a keyboard way to jump between items.
+- Use a grab cursor on handles and a grabbing cursor while dragging, in addition to the handle icon.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Enter / Space (handle) | Pick up the item, or drop it |
+| Arrow keys | Move the picked-up item one place |
+| Esc | Cancel and put the item back |
+| Tab | Reach the handle, the item's controls and its settings menu |
+
+## Examples
+
+### hiring-overview
+
+```tsx
+import { Board, BoardItem, type BoardItemData, Button, DropdownMenuItem, Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, toast } from "@twoux/ui";
+import { LayoutDashboard } from "lucide-react";
+import type React from "react";
+import { useState } from "react";
+
+export const meta = { title: "Hiring overview", description: "Drag an item by its handle, or focus the handle and press Enter, then the arrow keys. The ⋯ menu moves and resizes without dragging. Every change is announced.", order: 1 };
+
+const DEFAULT: BoardItemData[] = [
+	{ id: "apps", title: "Applications this month", columnSpan: 1 },
+	{ id: "open", title: "Open listings", columnSpan: 1 },
+	{ id: "tth", title: "Median time to hire", columnSpan: 2 },
+	{ id: "stages", title: "Pipeline by stage", columnSpan: 2 },
+	{ id: "closing", title: "Closing this week", columnSpan: 2 },
+];
+
+const STAGES = [["Applied", 412], ["Screen", 126], ["Interview", 48], ["Offer", 9]] as const;
+
+// Colour says whether a change is good, not which way it went.
+function Stat({ value, change, note, tone = "neutral" }: { value: string; change: string; note: string; tone?: "good" | "neutral" }) {
+	return (
+		<div className="grid gap-0.5">
+			<span className="tabular text-2xl font-semibold text-ink">{value}</span>
+			<span className="text-sm text-ink-2"><span className={tone === "good" ? "font-medium text-ok" : "font-medium text-ink"}>{change}</span> {note}</span>
+		</div>
+	);
+}
+
+function content(id: string) {
+	if (id === "apps") return <Stat value="595" change="↑ 12%" note="vs October" tone="good" />;
+	if (id === "open") return <Stat value="14" change="↓ 2" note="vs last week" />;
+	if (id === "tth") return <Stat value="23 days" change="↓ 4 days" note="vs last quarter" tone="good" />;
+	if (id === "stages")
+		return (
+			<ul className="grid gap-1.5">
+				{STAGES.map(([s, n]) => (
+					<li key={s} className="grid grid-cols-[72px_1fr_40px] items-center gap-2 text-sm">
+						<span className="text-ink-2">{s}</span>
+						<span className="h-2 overflow-hidden rounded-xs bg-hover" aria-hidden="true">
+							<span className="block h-full w-(--w) rounded-xs bg-primary" style={{ "--w": `${(n / 412) * 100}%` } as React.CSSProperties} />
+						</span>
+						<span className="tabular text-right text-ink">{n}</span>
+					</li>
+				))}
+			</ul>
+		);
+	return (
+		<ul className="grid gap-1 text-sm">
+			{[["Frontend Engineer", "Fri 21 Nov"], ["Customer Success Lead", "Sun 23 Nov"]].map(([r, d]) => (
+				<li key={r} className="flex justify-between gap-2"><span className="truncate text-ink">{r}</span><span className="tabular shrink-0 text-ink-3">{d}</span></li>
+			))}
+		</ul>
+	);
+}
+
+export default function Example() {
+	const [items, setItems] = useState(DEFAULT);
+	return (
+		<Board
+			className="w-full"
+			aria-label="Hiring overview"
+			items={items}
+			onItemsChange={setItems}
+			empty={
+				<Empty className="min-h-48">
+					<EmptyHeader>
+						<EmptyMedia variant="icon"><LayoutDashboard /></EmptyMedia>
+						<EmptyTitle>No items on this dashboard</EmptyTitle>
+						<EmptyDescription>Add the charts and lists you want to watch.</EmptyDescription>
+					</EmptyHeader>
+					<EmptyContent><Button variant="outline" size="sm" onClick={() => setItems(DEFAULT)}>Restore default items</Button></EmptyContent>
+				</Empty>
+			}
+			renderItem={(it) => (
+				<BoardItem
+					id={it.id}
+					header={it.title}
+					footer={it.id === "stages" ? <a href="#pipeline" className="font-medium text-primary-ink hover:underline">Open pipeline report</a> : undefined}
+					settings={<DropdownMenuItem onSelect={() => toast(`Opened ${it.title}`)}>View details</DropdownMenuItem>}
+				>
+					{content(it.id)}
+				</BoardItem>
+			)}
+		/>
+	);
+}
+```
+
+## Related
+
+- Line chart card
+- Stat card with comparison
+- Empty state

package/agent/docs-md/breadcrumb.md

@@ -0,0 +1,89 @@
+# Breadcrumb
+
+A short trail in the top bar showing where the page sits in the hierarchy, ending with the current page.
+
+Kind: component · Group: Navigation · Status: built, import from @twoux/ui
+
+## When to use
+
+- On pages below the top level, to show the section they belong to ("Hiring > Listings").
+- On a record's full page, so the person can go back up to the list ("Hiring > Listings > Junior Product Designer").
+
+## When not to use
+
+- As main navigation. The sidebar is the main navigation; the breadcrumb supplements it.
+- Linking to sibling or related pages. Use tabs or the sidebar.
+- Showing the path the person took. Breadcrumbs show hierarchy, not history; use the browser's Back.
+
+## Structure
+
+1. Section name (link when it has its own page)
+2. Chevron separator (decorative)
+3. Current page (not a link, darker text)
+
+## Guidelines
+
+- Sits at the left of the top bar on every page; top-level pages (Inbox, Assistant) show their name only.
+- The last item is the current page, styled darker and not a link.
+- Names match page titles exactly.
+- When space runs out, collapse middle items behind an ellipsis button; the current page always stays visible.
+- Keep it on one line; never wrap.
+
+## Content
+
+- Use the page and section names exactly as shown in the sidebar.
+- For a record, end with its title; add the ID only when titles can repeat.
+
+## Accessibility
+
+- Wrap it in a nav landmark labelled "Breadcrumb" containing an ordered list (1.3.1).
+- The current item has aria-current="page"; when it is not a link this is optional but still set for clarity.
+- Separators are decorative and hidden from assistive technology.
+- Breadcrumbs help meet 2.4.8 Location by showing where the page sits.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move through the links in the trail |
+| Enter | Follow the focused link |
+
+## Examples
+
+### trail
+
+```tsx
+import { Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator } from "@twoux/ui";
+
+export const meta = { title: "Where the page sits", description: "Names match page titles. The current page is the last item, darker and not a link. On narrow screens middle items collapse behind the ellipsis; the trail never wraps.", order: 1 };
+
+export default function Example() {
+	return (
+		<div className="grid w-full max-w-xl gap-4">
+			<Breadcrumb>
+				<BreadcrumbList>
+					<BreadcrumbItem><BreadcrumbLink href="#listings">Listings</BreadcrumbLink></BreadcrumbItem>
+					<BreadcrumbSeparator />
+					<BreadcrumbItem><BreadcrumbLink href="#l1040">Junior Product Designer</BreadcrumbLink></BreadcrumbItem>
+					<BreadcrumbSeparator />
+					<BreadcrumbItem><BreadcrumbPage>Screening questions</BreadcrumbPage></BreadcrumbItem>
+				</BreadcrumbList>
+			</Breadcrumb>
+			<Breadcrumb>
+				<BreadcrumbList>
+					<BreadcrumbItem><BreadcrumbLink href="#settings">Settings</BreadcrumbLink></BreadcrumbItem>
+					<BreadcrumbSeparator />
+					<BreadcrumbItem><BreadcrumbEllipsis /></BreadcrumbItem>
+					<BreadcrumbSeparator />
+					<BreadcrumbItem><BreadcrumbPage>Email templates</BreadcrumbPage></BreadcrumbItem>
+				</BreadcrumbList>
+			</Breadcrumb>
+		</div>
+	);
+}
+```
+
+## Related
+
+- App shell and sidebar navigation
+- Page header

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

@@ -0,0 +1,97 @@
+# Breakdown table
+
+A table under a chart that splits its figure by team, location or owner, with current and previous periods side by side and change in both units.
+
+Kind: component · Group: Data visualisation · Status: built, import from @twoux/ui
+
+## When to use
+
+- A chart needs its exact values and a split by dimension; the table doubles as the chart's long description.
+- People compare values across rows.
+
+## When not to use
+
+- For many columns people edit. Use the TwoUX Data grid.
+- For record lists. Use the TwoUX List table.
+
+## Structure
+
+1. Breakdown switch (By team, By location, By owner)
+2. Export CSV
+3. Columns: dimension, This period, Previous period, Change, Change %
+
+## Guidelines
+
+- Sit directly under the chart it explains.
+- Show change with sign and arrow, not colour alone.
+- Show a dash when there is nothing to compare, with hidden text for screen readers.
+- Sort by the current period by default and allow sorting by any column.
+- When a chart offers drill-down, the breakdown table is where the same split lives in full; a popover breakdown never holds data that is not also here.
+- Each row's count can link to the filtered List table behind it; link the count or the name, not both.
+- Rows follow the chart's filters and series toggles, so the table and chart never disagree.
+
+## Content
+
+- Right-align numbers with consistent decimals.
+- Column headers state the period, "This period", "Previous period".
+- Write change with its sign, "+12" and "−8%", so direction reads without colour.
+
+## Accessibility
+
+- 1.3.1 Info and Relationships: real table markup with scoped headers.
+- APG sortable table: aria-sort on the sorted header only.
+- The By team, By location, By owner switch exposes the pressed state.
+- When the chart filters change, announce the new row count politely without moving focus.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Tab | Move to the switch, Export and sortable headers |
+| Enter / Space | Change breakdown or sort |
+
+## Examples
+
+### by-team
+
+```tsx
+import type React from "react";
+import { CartesianChart, ChartFrame, ChartLegend, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, seriesColor } from "@twoux/ui";
+import { APPLICATIONS, WEEKS } from "../chart-card-line/data";
+
+export const meta = { title: "Chart with its breakdown", description: "The table under the chart splits the same figure by team, with current, previous and change. The colour key in each row ties it to the chart.", order: 1 };
+
+export default function Example() {
+	return (
+		<ChartFrame className="w-full" title="Applications per week" description="Last 8 weeks" legend={<ChartLegend items={APPLICATIONS.map((s, i) => ({ id: s.id, label: s.label, color: seriesColor(i), shape: "line" }))} />}>
+			<CartesianChart kind="line" x={WEEKS} series={APPLICATIONS} height={180} aria-label="Applications per week by team" />
+			<div className="overflow-hidden rounded-xs border border-line">
+				<Table aria-label="Applications by team">
+					<TableHeader><TableRow><TableHead>Team</TableHead><TableHead className="text-right">This week</TableHead><TableHead className="text-right">Last week</TableHead><TableHead className="text-right">Change</TableHead></TableRow></TableHeader>
+					<TableBody>
+						{APPLICATIONS.map((s, i) => {
+							const [now, prev] = [s.data[s.data.length - 1] ?? 0, s.data[s.data.length - 2] ?? 0];
+							const pct = Math.round(((now - prev) / (prev || 1)) * 100);
+							return (
+								<TableRow key={s.id}>
+									<TableCell><span className="inline-flex items-center gap-2"><span aria-hidden="true" className="h-0.5 w-3 rounded-full bg-(--c)" style={{ "--c": seriesColor(i) } as React.CSSProperties} />{s.label}</span></TableCell>
+									<TableCell className="tabular text-right font-medium">{now}</TableCell>
+									<TableCell className="tabular text-right text-ink-2">{prev}</TableCell>
+									<TableCell className="tabular text-right">{pct >= 0 ? "↑" : "↓"} {Math.abs(pct)}%</TableCell>
+								</TableRow>
+							);
+						})}
+					</TableBody>
+				</Table>
+			</div>
+		</ChartFrame>
+	);
+}
+```
+
+## Related
+
+- Line chart card
+- Bar chart
+- Stat card with comparison
+- Export menu

package/agent/docs-md/bulk-action-bar.md

@@ -0,0 +1,112 @@
+# Bulk action bar
+
+A grey band directly above the table while rows are selected: the actions that apply to every selected row, the count and Clear selection.
+
+Kind: component · Group: Data · Status: built, import from @twoux/ui
+
+## When to use
+
+- People act on several records at once; checkboxes plus batch actions is the standard pattern.
+- An action applies to all selected items, such as extending or closing listings.
+- People select rows from the keyboard with X or Shift with J and K, then act without reaching for the mouse.
+
+## When not to use
+
+- For one or two actions on a single row. Use inline row actions or the side panel.
+- For actions on the whole table regardless of selection, such as Export. Put them in the table toolbar.
+
+## Structure
+
+1. Band directly above the table, below any filters; the header row stays visible
+2. Actions with icons and shortcuts, up to four (Ask, Extend 30 days, Duplicate); the rest in More
+3. Destructive action (Close listings)
+4. Count ("2 listings selected") and Clear selection (Esc)
+
+## Guidelines
+
+- Show the bar only while rows are selected, and always show how many.
+- Place the bar directly above the table, below the filters, so the filters and the column headers stay in view.
+- Show up to four actions as buttons. The rest, and any that don't fit the width, move into a More menu that keeps their shortcuts; never shrink actions to icons only.
+- Exit by clearing the selection or pressing Esc.
+- Disable row-level actions while the bulk bar is showing so the two do not compete.
+- Confirm destructive bulk actions in a dialog that states the count and consequence, and offer Undo when the action can be reversed.
+- Selection on the header checkbox covers the visible page only, and actions affect only selected rows.
+
+## Content
+
+- Label actions verb plus noun, "Close listings", and put the count in confirmations, "Close 2 listings?".
+- Show each action's shortcut on the button.
+- Put destructive actions last.
+
+## Accessibility
+
+- APG toolbar pattern: role="toolbar" with aria-label "Bulk actions", one tab stop, arrow keys between buttons.
+- 4.1.3 Status Messages: announce "2 listings selected" when the count changes.
+- 2.4.11 Focus Not Obscured: the bar sits in the page flow above the table, so it never covers a focused row.
+- 2.5.8 Target Size: every button is at least 24 by 24 CSS pixels.
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| ← → | Move between actions |
+| T | Extend 30 days |
+| D | Duplicate |
+| ⇧C | Close listings (asks to confirm) |
+| ⌘J | Ask the assistant about the selection |
+| Esc | Clear the selection |
+
+## Examples
+
+### selection
+
+```tsx
+import { BulkActionBar, Button, Checkbox, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, toast } from "@twoux/ui";
+import { CalendarPlus, Copy } from "lucide-react";
+import { useState } from "react";
+import { LISTINGS } from "../list-table/data";
+
+export const meta = { title: "Act on selected listings", description: "While rows are selected, a band appears directly above the table with the actions, then the count and Clear selection. The header row and any filters stay in view. Arrow keys move between its buttons; Esc clears.", order: 1 };
+
+const ROWS = LISTINGS.slice(0, 4);
+
+export default function Example() {
+	const [sel, setSel] = useState<string[]>([ROWS[0].id, ROWS[2].id]);
+	const toggle = (id: string) => setSel((s) => (s.includes(id) ? s.filter((x) => x !== id) : [...s, id]));
+	const all = sel.length === ROWS.length ? true : sel.length ? "indeterminate" : false;
+	const setAll = (v: boolean) => setSel(v ? ROWS.map((r) => r.id) : []);
+	const n = sel.length;
+	return (
+		<div className="w-full max-w-xl overflow-hidden rounded-sm border border-line bg-surface">
+			<BulkActionBar count={n} noun={n === 1 ? "listing" : "listings"} onClear={() => setSel([])} actions={[
+					{ label: "Extend 30 days", icon: <CalendarPlus />, shortcut: "T", onSelect: () => toast.success(`Extended ${n} listing${n === 1 ? "" : "s"} by 30 days`, { action: { label: "Undo", onClick: () => {} } }) },
+					{ label: "Duplicate", icon: <Copy />, shortcut: "D", onSelect: () => toast.success(`Duplicated ${n} listing${n === 1 ? "" : "s"}`) },
+				]} />
+			<Table aria-label="Listings">
+				<TableHeader>
+					<TableRow className="hover:bg-transparent">
+						<TableHead className="w-9"><Checkbox aria-label="Select all on this page" checked={all} onCheckedChange={(v) => setAll(!!v)} /></TableHead>
+						<TableHead>Role</TableHead>
+						<TableHead>Location</TableHead>
+					</TableRow>
+				</TableHeader>
+				<TableBody>
+					{ROWS.map((r) => (
+						<TableRow key={r.id} data-state={sel.includes(r.id) ? "selected" : undefined}>
+							<TableCell><Checkbox checked={sel.includes(r.id)} onCheckedChange={() => toggle(r.id)} aria-label={`Select ${r.role}`} /></TableCell>
+							<TableCell className="font-medium text-ink">{r.role}</TableCell>
+							<TableCell className="text-ink-2">{r.location}</TableCell>
+						</TableRow>
+					))}
+				</TableBody>
+			</Table>
+		</div>
+	);
+}
+```
+
+## Related
+
+- List table
+- Data grid
+- Export menu