division-ds 0.1.2 → 0.2.1

package/public/docs/components/icon-button.md

@@ -0,0 +1,127 @@
+# IconButton
+
+> A square button with one icon. It uses exactly the same variants as Button (same source code, so the two can't drift apart). It requires a label, because an icon on its own tells a screen reader nothing.
+
+- **Best for:** An action shown as a single icon, with a label that names the action.
+- **Not for:** An action with a visible word (use Button), or a status (use Badge).
+- Atom. Source: `src/components/atoms/icon-button/IconButton.tsx`
+- Rendered docs page: `/components/icon-button`
+
+## Import
+
+```tsx
+import { IconButton } from 'src/components/atoms/icon-button/IconButton'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | Required. It becomes aria-label. It's required in the types, so an icon button with no name won't compile. |
+| `variant` | `'primary' \| 'secondary' \| 'danger' \| 'ghost'` | `'primary'` | Which fill/border treatment to use. These are Button’s variants minus link, since an icon has no text to underline. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 32 / 40 / 48px (pixels), all above the 24px minimum target size, the smallest area people can reliably click or tap. Button’s xs isn't offered: 32px is the smallest this control goes. |
+| `count` | `number` |  | A number in a corner badge, like items in a cart or unread notifications. It's added to the accessible name, the name screen readers announce (‘Notifications, 3 unread’). It shows as 99+ past 99 and is hidden at 0 unless showZero is set. |
+| `countLabel` | `(count: number) => string` | `String` | Formats the spoken part of the name that comes after the label and a comma: count => `${count} unread`. It always gets the real number, never 99+. |
+| `showZero` | `boolean` | `false` | Shows the badge when the count is 0. |
+| `asChild` | `boolean` | `false` | Renders the child element with the button's classes. Use it for links that look like icon buttons. Combining it with disabled is a type error, so the code won't compile, instead of quietly doing nothing. A link can't really be disabled, so the prop is removed from the types rather than ignored when the page runs. |
+| `fullWidth` | `—` |  | Left out on purpose. An icon button is always square, and stretching it would break that. |
+| `wrapperClassName` | `string` |  | Classes for the focus wrapper, not the button. |
+| `className` | `string` |  | Merged with the component's classes. When Tailwind utility classes clash, the later one wins. |
+| `ref` | `Ref<HTMLButtonElement>` |  | Passed through to the button element. |
+| `...rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'aria-label' \| 'children'>` |  | Every native button prop except aria-label. aria-label is removed from the types rather than quietly overwritten when the page runs. label is the only source of the accessible name, and an aria-label in rest would beat it. children is its own declared prop above, not part of rest. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Variants
+
+```tsx
+<IconButton label="Dismiss" variant="primary"><X aria-hidden="true" /></IconButton>
+<IconButton label="Save" variant="secondary"><Settings aria-hidden="true" /></IconButton>
+<IconButton label="Delete" variant="danger"><Trash2 aria-hidden="true" /></IconButton>
+<IconButton label="Search" variant="ghost"><Search aria-hidden="true" /></IconButton>
+```
+
+### Sizes
+
+```tsx
+<IconButton label="Dismiss" size="sm"><X aria-hidden="true" /></IconButton>
+<IconButton label="Dismiss" size="md"><X aria-hidden="true" /></IconButton>
+<IconButton label="Dismiss" size="lg"><X aria-hidden="true" /></IconButton>
+```
+
+### In context
+
+```tsx
+<div className="flex items-center justify-between w-full max-w-sm">
+  <p className="font-display text-sm font-semibold uppercase tracking-wide">
+    Field kit checklist
+  </p>
+  <IconButton label="Dismiss panel" variant="ghost" size="sm">
+    <X aria-hidden="true" />
+  </IconButton>
+</div>
+```
+
+### With a count
+
+```tsx
+<div className="flex flex-wrap items-center gap-6">
+  <IconButton label="Cart" variant="secondary" count={3} countLabel={n => `${n} replicas`}>
+    <ShoppingCart aria-hidden="true" />
+  </IconButton>
+  <IconButton label="Notifications" variant="ghost" count={128} countLabel={n => `${n} unread`}>
+    <Bell aria-hidden="true" />
+  </IconButton>
+  <IconButton label="Notifications" variant="primary" count={7} countLabel={n => `${n} unread`}>
+    <Bell aria-hidden="true" />
+  </IconButton>
+  <IconButton label="Cart" variant="secondary" count={0} showZero>
+    <ShoppingCart aria-hidden="true" />
+  </IconButton>
+</div>
+```
+
+### Disabled
+
+```tsx
+<IconButton label="Next step" disabled>
+  <ChevronRight aria-hidden="true" />
+</IconButton>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves focus to the button. The ring appears on the wrapper. |
+| `Enter` | Activates it. |
+| `Space` | Activates it. |
+
+## Do
+
+- Make the label describe the action, not the icon: ‘Dismiss alert’, not ‘X’.
+- Mark the icon aria-hidden so it's never announced twice.
+- Pair it with a Tooltip when the icon's meaning isn't obvious.
+- Stick to one icon. Two icons in a square is a dropdown, not a button.
+- Give a count a countLabel that says what's being counted, so the name reads ‘Notifications, 3 unread’ and not just a number.
+
+## Don't
+
+- Don't ship an icon button that only regular users understand.
+- Don't go smaller than sm. 32px is already close to the 24px floor.
+- Don't use danger for a dismiss. Dismissing can be undone.
+- Don't put the count in the label yourself. Pass count, so the badge and the name always match.
+- Don't use a count for a status (online, error). A count is a number. A status is a Badge with a word.
+- Don't try to disable a link (asChild). Render the state you want directly instead (a plain span, or a real disabled icon button) rather than fighting the type error.
+
+## Anatomy
+
+- **Focus wrapper**: A span that isn't clipped, carrying .bevel-focus-wrap. It draws the focus ring (the outline that shows which control the keyboard is on) on :has(:focus-visible), so a mouse click doesn't show it, plus the reticle brackets (corner marks like a targeting sight) that close in on hover. It's always there and never optional.
+- **Square button**: Its width is pinned to the height token, and the padding is removed.
+- **Icon**: Always aria-hidden, an ARIA attribute (Accessible Rich Internet Applications, the labels that tell screen readers what things are) that hides it from screen readers. The label gives the button its name.
+- **aria-label**: Comes from the required label prop, with the count added when there is one.
+- **Count badge**: Optional. It sits on the unclipped wrapper at the top-right corner, so the bevel (the cut corners) can't slice it. Square, mono, accent.signal.fill with its ink, and ringed in the page colour so it stays visible on a primary button. It's aria-hidden because the name already says the number. Past 99 it reads 99+.

package/public/docs/components/input.md

@@ -0,0 +1,200 @@
+# Input
+
+> A single-line text field. It doesn't label itself. The label, help text, error text and the wiring between them are FormField's job. On its own, Input handles the box, its states and the focus ring (the outline that shows which element the keyboard is on). It also has three optional extras inside its right edge: a password reveal, a character counter and a clear button.
+
+- **Best for:** Single-line text, inside a FormField.
+- **Not for:** Several lines of text: use Textarea. Searching the page: use Search.
+- Atom. Source: `src/components/atoms/input/Input.tsx`
+- Rendered docs page: `/components/input`
+
+## Import
+
+```tsx
+import { Input, inputVariants } from 'src/components/atoms/input/Input'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Requires
+
+- A <FormField> around it. On its own the control has no label. FormField adds the label, the help text and the error, and connects their ids.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `inputSize` | `'sm' \| 'md' \| 'lg'` | `'md'` | Called inputSize because size is already a real HTML attribute on input. |
+| `invalid` | `boolean` | `false` | Sets aria-invalid (an ARIA attribute, from Accessible Rich Internet Applications, that tells screen readers the field has an error) and shows the invalid border. It doesn't show any error text. |
+| `size` | `number` |  | The browser's own attribute, still available. |
+| `revealable` | `boolean` | `false` | On type="password", adds a Show password toggle with aria-pressed. The name stays the same, and the pressed state says whether the password is showing. It goes back to hidden when the form submits. Other types ignore it. |
+| `showCount` | `boolean` | `false` | Works with maxLength. It shows 12/80 in mono inside the field and adds it to aria-describedby, the attribute that links extra description to a field. It's merged with any describedby you pass in, which is how FormField keeps its help and error text. It only announces the characters left near the limit (the last tenth, and at least the last three), through a polite live region, an area screen readers read out without interrupting. |
+| `clearable` | `boolean` | `false` | Shows a clear button while the field has a value (never when it's disabled or read-only). Clearing fires onChange with an empty value, so a controlled field clears through its own handler. Then it calls onClear, then puts focus back in the input. |
+| `onClear` | `() => void` |  | Called after the clear button empties the field. |
+| `clearLabel` | `string` | `'Clear'` | The clear button’s name. If the page has more than one, say what it clears: ‘Clear call sign’. |
+| `aiValue` | `string` |  | The value an AI proposed. While the field holds exactly this value it shows the AI-filled state: an ai.border edge, a faint ai.wash tint and a sparkle mark that describes the field as Filled by AI. Once the person changes it, the field looks normal again and a Revert to suggestion button puts the value back through onChange (no button on a disabled or read-only field). An invalid field keeps its invalid border. |
+| `wrapperClassName` | `string` |  | Classes for the wrapper a field with extras renders. Put width classes here when an extra is on. It does nothing on a bare input. |
+| `className` | `string` |  | Merged with the input’s classes. If two clash, the later Tailwind utility wins (Tailwind is the CSS framework this system styles with). |
+| `ref` | `Ref<HTMLInputElement>` |  | Passed through to the input element. |
+| `...rest` | `Omit<InputHTMLAttributes<HTMLInputElement>, 'aria-invalid' \| 'size'>` |  | Every native input prop except aria-invalid, spread onto the element. aria-invalid is removed from the type, so you can't pass it, instead of being quietly overwritten while the page runs. invalid is the only thing that sets both the attribute and the border. If a caller could set one directly, what you see and what screen readers hear could drift apart. size is declared again above as the native number attribute, because inputSize controls the variant. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export const inputVariants = cva( …
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Sizes
+
+```tsx
+<label className="flex flex-col gap-1 text-sm">
+  Small
+  <Input inputSize="sm" placeholder="Call sign" />
+</label>
+<label className="flex flex-col gap-1 text-sm">
+  Medium
+  <Input inputSize="md" placeholder="Call sign" />
+</label>
+<label className="flex flex-col gap-1 text-sm">
+  Large
+  <Input inputSize="lg" placeholder="Call sign" />
+</label>
+```
+
+### States
+
+```tsx
+<label className="flex flex-col gap-1 text-sm">
+  Rest
+  <Input placeholder="Call sign" />
+</label>
+<label className="flex flex-col gap-1 text-sm">
+  Hover (try it)
+  <Input placeholder="Call sign" />
+</label>
+<label className="flex flex-col gap-1 text-sm">
+  Invalid
+  <Input invalid defaultValue="Anvil-3" />
+</label>
+<label className="flex flex-col gap-1 text-sm">
+  Disabled
+  <Input disabled defaultValue="Anvil-3" />
+</label>
+<label className="flex flex-col gap-1 text-sm">
+  Read only
+  <Input readOnly defaultValue="Anvil-3" />
+</label>
+```
+
+### Types
+
+```tsx
+<label className="flex flex-col gap-1 text-sm">
+  Text
+  <Input type="text" placeholder="Site name" />
+</label>
+<label className="flex flex-col gap-1 text-sm">
+  Email
+  <Input type="email" placeholder="scout@fieldops.example" />
+</label>
+<label className="flex flex-col gap-1 text-sm">
+  Number
+  <Input type="number" placeholder="0" className="[font-variant-numeric:tabular-nums]" />
+</label>
+<label className="flex flex-col gap-1 text-sm">
+  Password
+  <Input type="password" placeholder="Team radio passphrase" />
+</label>
+```
+
+### Password reveal
+
+```tsx
+<div className="w-full max-w-xs">
+  <FormField label="Team radio passphrase">
+    <Input type="password" revealable autoComplete="current-password" defaultValue="anvil-north-3" />
+  </FormField>
+</div>
+```
+
+### Character counter
+
+```tsx
+<div className="w-full max-w-xs">
+  <FormField label="Loadout name" help="Shown on your public profile.">
+    <Input maxLength={40} showCount defaultValue="Night recon, woodland" />
+  </FormField>
+</div>
+```
+
+### Clear button
+
+```tsx
+<div className="w-full max-w-xs">
+  <FormField label="Call sign">
+    <Input clearable clearLabel="Clear call sign" defaultValue="Anvil-3" />
+  </FormField>
+</div>
+```
+
+### Filled by AI, with a revert
+
+```tsx
+<div className="w-full max-w-xs">
+  <FormField label="Call sign" help="Suggested from your last order. Edit it and the revert button appears.">
+    <Input aiValue="Anvil-3" defaultValue="Anvil-3" />
+  </FormField>
+</div>
+```
+
+### Labelled the manual way
+
+```tsx
+<div className="flex flex-col gap-1 text-sm max-w-xs">
+  <label htmlFor="input-docs-callsign">Call sign</label>
+  <Input id="input-docs-callsign" aria-describedby="input-docs-callsign-help" />
+  <p id="input-docs-callsign-help" className="text-xs text-[var(--color-text-secondary)]">
+    Letters, numbers and a hyphen. FormField will set this pattern up for you.
+  </p>
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves focus to the input, then to its revert, clear and reveal buttons if they are there. |
+| `Esc` | Nothing by default, even with clearable. Clearing on Escape is a search behaviour, and it lives in the Search molecule. |
+| `Space` | On the reveal toggle, shows or hides the password. On the clear button, empties the field and puts focus back in it. |
+
+## Do
+
+- Label it: with a real <label> today, and with FormField once that ships.
+- Set the right type and autocomplete. They do more for usability than any styling here.
+- Pair invalid with visible error text that the input points to through aria-describedby.
+- Size the field to the expected input. A four-digit code doesn't need a full-width box.
+- Use showCount with maxLength instead of building a counter next to the field. You get the describedby wiring and the near-limit announcement for free.
+- Label a field with extras through FormField or a label htmlFor, never a label wrapped around it. A wrapping label pulls the clear and reveal buttons into the field’s name.
+
+## Don't
+
+- Don't use the placeholder as the label. It disappears the moment someone types.
+- Don't bevel it. A cut corner on a 40px box looks like damage, and it would clip the focus ring.
+- Don't set invalid without saying what's wrong.
+- Don't disable a field to make it read-only. Use readOnly, which you can still focus and copy from.
+- Don't add clearable to a search field. Search already has its own clear button and the Escape key.
+- Don't build your own show-password button next to a revealable field. You'll end up with two.
+- Don't set aiValue on a field the person filled in themselves. The AI look says the machine wrote it.
+
+## Anatomy
+
+- **Input**: 40px (pixels) tall by default. The height comes from the control token, not a hand-picked number.
+- **Border**: border.control at rest, text.muted on hover and hostile.text when invalid. A control's edge tells you something, it isn't decoration, so it doesn't use a hairline token.
+- **Focus ring**: Drawn on the input itself. Form controls aren't bevelled (given a cut corner), so nothing clips it.
+- **Adornments**: Optional extras inside the right edge, in this order: the AI mark or its revert button, the count in mono (a fixed-width typeface), the clear button and the reveal toggle. Turning on any of them wraps the input in a relative box (wrapperClassName styles it) and sizes the right padding to fit them, so text never runs underneath. With none on, the input is bare, with no wrapper.
+- **Placeholder**: text.placeholder, with contrast measured against the control fill it sits on, not the page. It's never a stand-in for a label.

package/public/docs/components/kanban-board.md

@@ -0,0 +1,300 @@
+# KanbanBoard
+
+> Cards in columns that people move between stages: by dragging with a pointer, by dragging with the keyboard, or from each card's Move menu. It's controlled, meaning the board reports a move and the parent updates its items.
+
+- **Best for:** Work items that move through a few named stages, where the point is seeing every stage at once.
+- **Not for:** Records compared across many fields: use DataTable. A single ordered sequence: use Stepper.
+- Organism. Source: `src/components/organisms/kanban-board/KanbanBoard.tsx`
+- Rendered docs page: `/components/kanban-board`
+
+## Import
+
+```tsx
+import { KanbanBoard, applyKanbanMove, groupKanbanItems, kanbanDragOver, kanbanDrop, kanbanMessages, kanbanPosition } from 'src/components/organisms/kanban-board/KanbanBoard'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Requires
+
+- A parent that holds items in state and applies each onMove (applyKanbanMove does the update).
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | Required. Names the board's region. |
+| `columns` | `readonly KanbanColumn[]` |  | Required. { id, title, meta? }, in display order. |
+| `items` | `readonly T[]` |  | Required. Every card. A column shows its items in this array's order. |
+| `getItemId` | `(item: T) => string` |  | Required. |
+| `getColumnId` | `(item: T) => string` |  | Required. The id of the item's column. |
+| `getItemLabel` | `(item: T) => string` |  | Required. The card in plain words. The Move control, its menu and every screen reader announcement use it. |
+| `renderCard` | `(item: T) => ReactNode` |  | Required. The card's body. It can hold one link or button. The board draws the frame. |
+| `renderCardCorner` | `(item: T) => ReactNode` |  | A small mark in the card's bottom-right corner, under the Move control, about 2rem square, such as the owner's avatar. Wrap it in aria-hidden (so screen readers skip it) when the card already prints the same name. |
+| `onMove` | `(itemId: string, toColumnId: string, toIndex: number) => void` |  | Required. Called once per move. toIndex is the card's position in the destination column after the move. A move from the menu puts it last. |
+| `emptyColumnMessage` | `string` | `'Nothing here'` | Shown in a column with no cards. |
+| `columnHeadingLevel` | `2 \| 3 \| 4` | `3` | The heading level of the column titles. Pick one that sits under the page's own heading outline. |
+| `className` | `string` |  | Goes on the region. |
+| `applyKanbanMove()` | `(items, itemId, toColumnId, toIndex, { getItemId, getColumnId, setColumnId }) => T[]` |  | The parent's half of onMove. It returns a new items array with the card in its new column and place. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type KanbanColumn = {
+  id: string
+  title: string
+  /** Beside the title, in mono: a count, a total. */
+  meta?: ReactNode
+}
+```
+
+```ts
+/** Column id to the ids of its cards, in order. What a drag rearranges before `onMove` runs. */
+export type KanbanLayout = Record<string, string[]>
+```
+
+```ts
+/** Where a card is being dropped: on another card (it takes that card's place), or on a column
+ *  with no `itemId` (the end of it; only an empty column is a drop target of its own). */
+export type KanbanTarget = { columnId: string; itemId?: string }
+```
+
+```ts
+export function groupKanbanItems<T>(
+  columns: readonly KanbanColumn[],
+  items: readonly T[],
+  getItemId: (item: T) => string,
+  getColumnId: (item: T) => string
+): KanbanLayout
+```
+
+```ts
+/** The card's column and 0-based index in a layout, and how many cards that column holds. */
+export function kanbanPosition(layout: KanbanLayout, itemId: string)
+```
+
+```ts
+/** The move into another column while the card is still held, so the cards there make room. A
+ *  move inside one column is left to the sortable transforms until the drop. Returns `layout`
+ *  itself when nothing changes, so a state update with it does not render. */
+export function kanbanDragOver(layout: KanbanLayout, itemId: string, target: KanbanTarget): KanbanLayout
+```
+
+```ts
+/** The layout a drop on `target` leaves: across columns as `kanbanDragOver`, inside one column
+ *  the card takes the target card's index. Pure, and what the announcements read ahead of time. */
+export function kanbanDrop(layout: KanbanLayout, itemId: string, target: KanbanTarget): KanbanLayout
+```
+
+```ts
+/** The parent's half of `onMove`: a new `items` array with the card in its new column, placed
+ *  before the card that held `toIndex` there (or after the column's last card). Other cards keep
+ *  their order. `setColumnId` returns the item with its column changed, a copy. */
+export function applyKanbanMove<T>(
+  items: readonly T[],
+  itemId: string,
+  toColumnId: string,
+  toIndex: number,
+  {
+    getItemId,
+    getColumnId,
+    setColumnId,
+  }: { getItemId: (item: T) => string; getColumnId: (item: T) => string; setColumnId: (item: T, columnId: string) => T }
+): T[]
+```
+
+```ts
+/** Every sentence the board speaks, in plain words: a card's name, a column's title and a
+ *  position counted from 1. Exported so the wording is tested as wording. */
+export const kanbanMessages = { …
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Hiring board
+
+```tsx
+type Stage = 'applied' | 'screen' | 'interview' | 'offer'
+
+type Candidate = { id: string; name: string; role: string; stage: Stage; recruiter: string; referral?: boolean }
+
+const STAGES: { id: Stage; title: string }[] = [
+  { id: 'applied', title: 'Applied' },
+  { id: 'screen', title: 'Screening' },
+  { id: 'interview', title: 'Interview' },
+  { id: 'offer', title: 'Offer' },
+]
+
+const CANDIDATES: Candidate[] = [
+  { id: 'c1', name: 'Ilse Varga', role: 'Depot lead, Cluj', stage: 'applied', recruiter: 'Dana Holm', referral: true },
+  { id: 'c2', name: 'Tomas Reyes', role: 'Forklift driver, Arad', stage: 'applied', recruiter: 'Radu Mares' },
+  { id: 'c3', name: 'Mara Lind', role: 'Stock planner, Sibiu', stage: 'applied', recruiter: 'Dana Holm' },
+  { id: 'c4', name: 'Oskar Behn', role: 'Depot lead, Cluj', stage: 'screen', recruiter: 'Radu Mares' },
+  { id: 'c5', name: 'Ana Petrescu', role: 'Dispatcher, Brasov', stage: 'interview', recruiter: 'Dana Holm', referral: true },
+  { id: 'c6', name: 'Jon Arvid', role: 'Stock planner, Sibiu', stage: 'interview', recruiter: 'Radu Mares' },
+]
+
+const accessors = {
+  getItemId: (candidate: Candidate) => candidate.id,
+  getColumnId: (candidate: Candidate) => candidate.stage,
+  setColumnId: (candidate: Candidate, stage: string) => ({ ...candidate, stage: stage as Stage }),
+}
+
+function CandidateCard({ candidate }: { candidate: Candidate }) {
+  return (
+    <div className="flex flex-col gap-1">
+      <p className="font-semibold">{candidate.name}</p>
+      <p className="text-[var(--color-text-secondary)]">{candidate.role}</p>
+      {candidate.referral ? (
+        <Badge tone="signal" emphasis="solid" className="self-start mt-1">
+          Referral
+        </Badge>
+      ) : null}
+    </div>
+  )
+}
+
+function HiringBoard() {
+  const [candidates, setCandidates] = useState(CANDIDATES)
+  const columns: KanbanColumn[] = STAGES.map(stage => ({
+    ...stage,
+    meta: candidates.filter(candidate => candidate.stage === stage.id).length,
+  }))
+  return (
+    <div className="w-full min-w-0">
+      <KanbanBoard
+        label="Hiring board"
+        columns={columns}
+        items={candidates}
+        getItemId={accessors.getItemId}
+        getColumnId={accessors.getColumnId}
+        getItemLabel={candidate => candidate.name}
+        renderCard={candidate => <CandidateCard candidate={candidate} />}
+        renderCardCorner={candidate => <Avatar name={candidate.recruiter} size="sm" />}
+        onMove={(id, stage, index) => setCandidates(current => applyKanbanMove(current, id, stage, index, accessors))}
+        columnHeadingLevel={4}
+      />
+    </div>
+  )
+}
+
+<HiringBoard />
+```
+
+### Work orders, with an empty column
+
+```tsx
+type Order = { id: string; title: string; bay: string; status: 'open' | 'parts' | 'done' }
+
+const ORDER_COLUMNS: KanbanColumn[] = [
+  { id: 'open', title: 'Open' },
+  { id: 'parts', title: 'Waiting for parts' },
+  { id: 'done', title: 'Done' },
+]
+
+const ORDERS: Order[] = [
+  { id: 'wo-31', title: 'Replace dock door seal', bay: 'Bay 2', status: 'open' },
+  { id: 'wo-32', title: 'Recalibrate floor scale', bay: 'Bay 5', status: 'open' },
+  { id: 'wo-29', title: 'Service pallet jack', bay: 'Bay 1', status: 'done' },
+]
+
+const orderAccessors = {
+  getItemId: (order: Order) => order.id,
+  getColumnId: (order: Order) => order.status,
+  setColumnId: (order: Order, status: string) => ({ ...order, status: status as Order['status'] }),
+}
+
+function WorkOrders() {
+  const [orders, setOrders] = useState(ORDERS)
+  return (
+    <div className="w-full min-w-0">
+      <KanbanBoard
+        label="Depot work orders"
+        columns={ORDER_COLUMNS}
+        items={orders}
+        getItemId={orderAccessors.getItemId}
+        getColumnId={orderAccessors.getColumnId}
+        getItemLabel={order => order.title}
+        renderCard={order => (
+          <div className="flex flex-col gap-1">
+            <p className="font-semibold">{order.title}</p>
+            <p className="font-mono text-xs uppercase tracking-[0.12em] text-[var(--color-text-secondary)]">{order.bay}</p>
+          </div>
+        )}
+        onMove={(id, status, index) => setOrders(current => applyKanbanMove(current, id, status, index, orderAccessors))}
+        emptyColumnMessage="No orders waiting"
+        columnHeadingLevel={4}
+      />
+    </div>
+  )
+}
+
+<WorkOrders />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves through each card's own link or button, then its Move control. |
+| `Enter` | On a Move control, opens the menu of the other columns. On a menu item, moves the card to the end of that column. While a card is lifted, drops it. |
+| `Space` | On a Move control, lifts the card. While it is lifted, Space drops it. |
+| `↑` `↓` `←` `→` | While a card is lifted, move it between places in a column and between columns. |
+| `Escape` | While a card is lifted, puts it back where it was (Tab does the same). In the menu, closes it. |
+
+## Do
+
+- Name each card with getItemLabel in words a screen reader listener can tell apart: the candidate, not "Card 3".
+- Put a count or a total in each column's meta, so people can see a column's size without counting.
+- Keep it to the stages of one process, three to six columns.
+- Apply onMove with applyKanbanMove, or with anything that leaves the card at toIndex in its new column.
+
+## Don't
+
+- Don't make the card body a link from edge to edge. Put one link on the card's name.
+- Don't write instructions that only mention dragging. The Move menu is the way to move a card without dragging.
+- Don't reorder items inside renderCard or around the board. The order in items is the order shown.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+onMove={() => {}}  // items never change
+```
+
+Right:
+
+```tsx
+onMove={(id, column, index) => setItems(items => applyKanbanMove(items, id, column, index, accessors))}
+```
+
+The board is controlled. If the parent doesn't apply a move, the card snaps back where it was.
+
+Wrong:
+
+```tsx
+renderCard={job => <a href={job.url} className="block p-3">...</a>}
+```
+
+Right:
+
+```tsx
+renderCard={job => <><a href={job.url}>{job.title}</a><p>{job.team}</p></>}
+```
+
+The board draws the frame and the Move control. A link wrapped around the whole body would swallow the drag and put controls inside each other.
+
+## Anatomy
+
+- **Region**: A section named by label that holds the board.
+- **Scroll track**: Scrolls the columns sideways on a narrow screen. The page never scrolls sideways. Each column is at least 18rem wide (rem is a unit tied to the base font size), so a title, a count and a six-figure total stay on one line, and the cards in every column start at the same height.
+- **Column**: A crosshair frame: the title as a monospaced heading with its meta on the right, then the cards as a list named by the title.
+- **Card**: A panel with the body from renderCard. Down its right edge are the Move control at the top and the renderCardCorner mark, if there is one, in the bottom corner.
+- **Move control**: An IconButton named "Move <label>". Enter or a click opens the menu of other columns. Space lifts the card for a keyboard drag.
+- **Empty column**: A dashed box with emptyColumnMessage. It's where you drop a card into an empty column.
+- **Lifted card**: The copy being dragged, with a 2px (pixel) signal border, over a dashed outline showing where the card will land.