division-ds 0.1.2 → 0.2.1

package/public/docs/components/chat-message.md

@@ -0,0 +1,157 @@
+# ChatMessage
+
+> One turn in a conversation with an assistant: the person's words in a bubble, the reply at full width, or a centred system line. While a reply is still streaming in, it sets aria-busy (an ARIA, Accessible Rich Internet Applications, attribute that tells screen readers the content isn't finished) and shows a caret that doesn't blink.
+
+- **Best for:** Each turn inside a ChatThread.
+- **Not for:** Comments or an activity history between people: use Timeline.
+- **Also on this page:** `ResponseFeedback`
+- Molecule. Source: `src/components/molecules/chat-message/ChatMessage.tsx`
+- Rendered docs page: `/components/chat-message`
+
+## Import
+
+```tsx
+import { ChatMessage } from 'src/components/molecules/chat-message/ChatMessage'
+import { ResponseFeedback } from 'src/components/molecules/chat-message/ResponseFeedback'
+```
+
+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 ChatThread around it. Outside one, a message still shows, but nothing announces it when it finishes.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `role` | `'user' \| 'assistant' \| 'system'` |  | Required. Who's speaking. system is a quiet, centred status line. |
+| `author` | `string` |  | Required. "You", "Assistant". It names the message. |
+| `time` | `string` |  | The date and time in ISO format (the international standard way of writing them), for <time dateTime>. |
+| `timeLabel` | `string` |  | The time as shown on screen: "09:40". |
+| `streaming` | `boolean` | `false` | The text is still arriving: sets aria-busy and shows a caret. Inside a ChatThread, the finished text is announced once, when this turns false. |
+| `actions` | `ReactNode` |  | Small buttons under an assistant message. They aren't shown on a user message. |
+| `className` | `string` |  | Goes on the article. |
+| `onSubmit (ResponseFeedback)` | `(vote: 'helpful' \| 'not-helpful') => void \| Promise<void>` |  | Required. Runs on a thumbs up or down. Return a promise to show "Submitting feedback" until it settles; a rejection puts the buttons back. |
+| `onDetail (ResponseFeedback)` | `(text: string) => void` |  | Offers an optional, dismissable "what was wrong" box after a Not helpful vote. Leave it out for no such step. |
+| `className (ResponseFeedback)` | `string` |  | Goes on the group. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type ChatMessageRole = 'user' | 'assistant' | 'system'
+```
+
+```ts
+export type FeedbackVote = 'helpful' | 'not-helpful'
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### The three roles
+
+```tsx
+<div className="flex w-full max-w-xl flex-col gap-6">
+  <ChatMessage role="user" author="You" time="2026-10-15T09:40:00+03:00" timeLabel="09:40">
+    Which replicas are running low at Depot 4?
+  </ChatMessage>
+  <ChatMessage
+    role="assistant"
+    author="Assistant"
+    time="2026-10-15T09:40:00+03:00"
+    timeLabel="09:40"
+    actions={
+      <>
+        <Button size="xs" variant="ghost" iconStart={<Copy />}>
+          Copy
+        </Button>
+        <Button size="xs" variant="ghost" iconStart={<RotateCcw />}>
+          Retry
+        </Button>
+      </>
+    }
+  >
+    Two are under their reorder point: the K-41 field radio (6 left, reorder at 10) and the trail
+    pack (3 left, reorder at 8). Everything else has at least two weeks of cover.
+  </ChatMessage>
+  <ChatMessage role="system" author="Status">
+    Assistant stopped
+  </ChatMessage>
+</div>
+```
+
+### While the reply is still streaming in: aria-busy, an ARIA (Accessible Rich Internet Applications) attribute that tells screen readers the message isn't finished, and a cursor that doesn't blink
+
+```tsx
+<div className="flex w-full max-w-xl flex-col gap-6">
+  <ChatMessage role="assistant" author="Assistant" streaming>
+    Depot 4 holds 1,240 replicas across 38 lines. The busiest
+  </ChatMessage>
+</div>
+```
+
+### Feedback on a reply: thumbs up or down, one vote, and an optional detail step after Not helpful
+
+```tsx
+const pretendSend = () => new Promise<void>(resolve => setTimeout(resolve, 800))
+
+<div className="flex w-full max-w-xl flex-col gap-6">
+  <ChatMessage
+    role="assistant"
+    author="Assistant"
+    actions={<ResponseFeedback onSubmit={pretendSend} onDetail={() => {}} />}
+  >
+    Depot 4 holds 1,240 replicas. Eleven are below their reorder point.
+  </ChatMessage>
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves to the controls inside the message: a ToolCall's details, an approval's buttons, the actions. |
+
+## Do
+
+- Keep streaming true until the last piece of text has arrived, then set it to false once.
+- Put tool calls and approvals in the assistant message where they happened, in order with its text.
+- Use a system line for events in the conversation itself: stopped, retried, context cleared.
+- Give every message an author, including a system line ("Status"). It names the article.
+- Put ResponseFeedback in the actions of a generated reply once it has finished streaming, so a vote rates the whole reply.
+
+## Don't
+
+- Don't animate the text in yourself. useStreamedText or your stream supplies it, and the thread handles announcing it.
+- Don't put actions on the person's own message. Editing a sent message is a different flow.
+- Don't colour the assistant's text. The bubble, the alignment and the author line already tell the roles apart.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<ChatMessage role="assistant" author="Assistant">{partial}<span className="animate-pulse">▍</span></ChatMessage>
+```
+
+Right:
+
+```tsx
+<ChatMessage role="assistant" author="Assistant" streaming={!done}>{partial}</ChatMessage>
+```
+
+streaming sets aria-busy, draws a caret that doesn't blink, and tells the thread to announce the text once, when it's finished. A hand-made blinking caret flashes for the whole stream.
+
+## Anatomy
+
+- **Article**: Named by the author line, so a screen reader hears who's speaking first. Has aria-busy while streaming.
+- **Author line**: The author as a label in monospaced type, then the time in a <time dateTime> element.
+- **Bubble (user)**: The person's words on surface.sunken, aligned right, at most 85% of the width.
+- **Body (assistant)**: Full width, with no bubble: text, paragraphs, and ToolCall and ApprovalRequest blocks stacked in a column.
+- **Caret**: A solid block in the signal colour after the last paragraph while streaming, drawn with the CSS ::after rule. It never blinks.
+- **Actions**: Small buttons under an assistant message: Copy, Retry, and ResponseFeedback (thumbs up and down).
+- **System line**: A centred label in monospaced type between two thin lines: "Assistant stopped". Its author is there for screen readers only.

package/public/docs/components/chat-thread.md

@@ -0,0 +1,244 @@
+# ChatThread
+
+> A scrolling log of ChatMessages. It follows new text only while the reader is at the end, and it announces each finished reply to screen readers once.
+
+- **Best for:** A conversation with an assistant, above a PromptInput, where replies stream in.
+- **Not for:** A record of events on one thing: use Timeline.
+- Organism. Source: `src/components/organisms/chat-thread/ChatThread.tsx`
+- Rendered docs page: `/components/chat-thread`
+
+## Import
+
+```tsx
+import { ChatThread } from 'src/components/organisms/chat-thread/ChatThread'
+```
+
+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 height, because the thread scrolls and the page doesn't. Use h-[28rem], or flex-1 min-h-0 inside a column.
+- ChatMessage children, so the thread can announce each finished reply.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | Required. Names the log. |
+| `busy` | `boolean` | `false` | The assistant is working. Shows a working line and makes one announcement when it starts. |
+| `busyLabel` | `string` | `'Assistant is working'` | The working line's words, and what gets announced. |
+| `jumpLabel` | `string` | `'Jump to latest'` | The jump button's words. |
+| `className` | `string` |  | Goes on the root. Give the thread a height here. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### A live conversation: send anything, watch the reply stream in, press Stop to end it, or scroll up while it's still arriving
+
+```tsx
+type Turn =
+  | { id: number; role: 'user'; text: string }
+  | { id: number; role: 'assistant'; text: string; tool?: ToolCallStatus; approval?: boolean }
+  | { id: number; role: 'system'; text: string }
+
+const REPLIES = [
+  'Depot 4 holds 1,240 replicas across 38 lines. Two lines are under their reorder point: the K-41 field radio has 6 left against a reorder point of 10, and the trail pack has 3 left against 8. Everything else has at least two weeks of cover at the current rate. The reorder above covers both lines; once it is approved, the supplier confirms within a working day.',
+  'Inbound this week: one delivery from Arad on Thursday morning, 22 pallets, booked into bay 2. Outbound: nine shipments, the largest to Sibiu on Friday. Nothing is waiting on a person except the reorder above.',
+]
+
+const HISTORY: Turn[] = [
+  { id: 1, role: 'user', text: 'Summarise stock at Depot 4.' },
+  {
+    id: 2,
+    role: 'assistant',
+    text: 'Depot 4 is in good shape: 1,240 replicas on hand and nothing overdue. Two lines are low, so I have drafted a reorder for you to check.',
+    tool: 'done',
+    approval: true,
+  },
+]
+
+function LiveConversation() {
+  const [turns, setTurns] = useState<Turn[]>(HISTORY)
+  const [draft, setDraft] = useState('')
+  const [phase, setPhase] = useState<'idle' | 'tool' | 'streaming'>('idle')
+  const [approval, setApproval] = useState<ApprovalState>('pending')
+  const [replyIndex, setReplyIndex] = useState(0)
+  const nextId = useRef(HISTORY.length + 1)
+  const activeId = useRef<number | null>(null)
+  const reply = useStreamedText(REPLIES[replyIndex % REPLIES.length], { active: phase === 'streaming' })
+
+  const updateActive = (change: (turn: Turn & { role: 'assistant' }) => Turn) =>
+    setTurns(list => list.map(turn => (turn.id === activeId.current && turn.role === 'assistant' ? change(turn) : turn)))
+
+  const addStopped = () => {
+    const id = nextId.current++
+    setTurns(list => [...list, { id, role: 'system', text: 'Assistant stopped' }])
+  }
+
+  // The tool "runs" for a moment, then the reply starts streaming.
+  useEffect(() => {
+    if (phase !== 'tool') return
+    const timer = window.setTimeout(() => {
+      updateActive(turn => ({ ...turn, tool: 'done' }))
+      setPhase('streaming')
+    }, 1200)
+    return () => window.clearTimeout(timer)
+  }, [phase])
+
+  // Finished or stopped: keep what arrived, and hand the thread a message that is no longer streaming.
+  useEffect(() => {
+    if (phase !== 'streaming' || !reply.done) return
+    updateActive(turn => ({ ...turn, text: reply.text }))
+    if (reply.stopped) addStopped()
+    setPhase('idle')
+    setReplyIndex(index => index + 1)
+  }, [phase, reply.done, reply.text, reply.stopped])
+
+  const send = (text: string) => {
+    const question = nextId.current++
+    const answer = nextId.current++
+    activeId.current = answer
+    setTurns(list => [...list, { id: question, role: 'user', text }, { id: answer, role: 'assistant', text: '', tool: 'running' }])
+    setDraft('')
+    setPhase('tool')
+  }
+
+  const stop = () => {
+    if (phase === 'streaming') {
+      reply.stop()
+      return
+    }
+    // Stopped before any text: the empty reply goes, the system line says what happened.
+    setTurns(list => list.filter(turn => turn.id !== activeId.current))
+    addStopped()
+    setPhase('idle')
+  }
+
+  const busy = phase !== 'idle'
+
+  return (
+    <div className="flex w-full max-w-2xl flex-col border border-[var(--color-border-hairline-strong)]">
+      <ChatThread label="Conversation with the assistant" busy={phase === 'tool'} className="h-[28rem]">
+        {turns.map(turn => {
+          if (turn.role === 'user') {
+            return (
+              <ChatMessage key={turn.id} role="user" author="You">
+                {turn.text}
+              </ChatMessage>
+            )
+          }
+          if (turn.role === 'system') {
+            return (
+              <ChatMessage key={turn.id} role="system" author="Status">
+                {turn.text}
+              </ChatMessage>
+            )
+          }
+          const streaming = phase === 'streaming' && turn.id === activeId.current
+          const text = streaming ? reply.text : turn.text
+          return (
+            <ChatMessage key={turn.id} role="assistant" author="Assistant" streaming={streaming}>
+              {turn.tool === undefined ? null : (
+                <ToolCall
+                  name="query_stock_levels"
+                  title="Read stock levels at Depot 4"
+                  status={turn.tool}
+                  duration={turn.tool === 'done' ? '1.2 s' : undefined}
+                  input={'{ "depot": 4 }'}
+                  output={turn.tool === 'done' ? '{ "on_hand": 1240, "lines": 38, "below_reorder_point": 2 }' : undefined}
+                />
+              )}
+              {text === '' ? null : <p>{text}</p>}
+              {turn.approval ? (
+                <ApprovalRequest
+                  title="Send this reorder to the supplier?"
+                  state={approval}
+                  onApprove={() => setApproval('approved')}
+                  onReject={() => setApproval('rejected')}
+                  approveLabel="Send reorder"
+                  rejectLabel="Don't send"
+                >
+                  <p>To: Arad replica supply</p>
+                  <p>10 × K-41 field radio, 8 × trail pack, to Depot 4 by Thursday 22 October.</p>
+                </ApprovalRequest>
+              ) : null}
+            </ChatMessage>
+          )
+        })}
+      </ChatThread>
+      <PromptInput
+        label="Message the assistant"
+        placeholder="Ask about stock, orders or depots"
+        value={draft}
+        onValueChange={setDraft}
+        onSubmit={send}
+        busy={busy}
+        onStop={stop}
+        className="p-4 border-t border-[var(--color-border-hairline-strong)]"
+      />
+    </div>
+  )
+}
+
+<LiveConversation />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves to the log, then into the controls inside messages, then to Jump to latest when it's shown. |
+| `ArrowUp` `ArrowDown` | With the log focused, scrolls it. |
+| `PageUp` `PageDown` | With the log focused, scrolls it a page at a time. |
+
+## Do
+
+- Give the thread a fixed or flexible height so the thread scrolls, not the page.
+- Set busy as soon as the request starts. Clear it when the last fragment has arrived or the reply is stopped.
+- After a Stop, add a system line ("Assistant stopped") so the record and the announcement both say what happened.
+- Keep the PromptInput outside the thread, directly under it.
+
+## Don't
+
+- Don't scroll the thread yourself on new messages. It follows the end only while the reader is there.
+- Don't move focus into the thread when a reply arrives. Focus stays where the person put it.
+- Don't add a second live region (an area screen readers announce changes from) for replies or tool calls. The thread's status is the only voice.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<div role="log" aria-live="polite">{messages}</div>
+```
+
+Right:
+
+```tsx
+<ChatThread label="Conversation with the assistant">{messages}</ChatThread>
+```
+
+A polite live log makes a screen reader read a streaming reply aloud one fragment at a time. The thread keeps the log quiet and announces each finished reply once.
+
+Wrong:
+
+```tsx
+useEffect(() => endRef.current?.scrollIntoView({ behavior: "smooth" }), [messages])
+```
+
+Right:
+
+```tsx
+<ChatThread ...>  // follows the end only while the reader is there
+```
+
+Scrolling on every change yanks away a reader who scrolled up to read. And smooth scrolling on every fragment means the screen never stops moving.
+
+## Anatomy
+
+- **Log**: Has role="log" and is named by label. aria-live is off, so screen readers don't read every change. It's a tab stop (a place the Tab key lands) so a keyboard can scroll it, and it scrolls inside its own height.
+- **Messages**: ChatMessage children, oldest first, 24px (pixels) apart.
+- **Working line**: Shown while busy: the conveyor Spinner and "Assistant is working" at the end of the log.
+- **Jump to latest**: Appears only when the reader has scrolled away from the end. It jumps instantly and puts focus on the log.
+- **Status**: A visually hidden role="status" that screen readers hear. It says the busy label once when work starts, and each finished reply once.

package/public/docs/components/checkbox.md

@@ -0,0 +1,149 @@
+# Checkbox
+
+> A checkbox with three states: off, on and mixed. Radix (the open-source library of accessible building blocks underneath it) handles the semantics and the keyboard behaviour. The look comes from the system's shape language: a square with no rounding and a tick in ink.
+
+- **Best for:** An on/off choice that applies when the form is saved, or a parent whose children are partly selected.
+- **Not for:** A setting that takes effect the moment you flip it. Use Switch for that.
+- Atom. Source: `src/components/atoms/checkbox/Checkbox.tsx`
+- Rendered docs page: `/components/checkbox`
+
+## Import
+
+```tsx
+import { Checkbox } from 'src/components/atoms/checkbox/Checkbox'
+```
+
+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 |
+|---|---|---|---|
+| `checked` | `boolean \| 'indeterminate'` |  | The checked state, when your code controls it. |
+| `defaultChecked` | `boolean` |  | The starting state when the checkbox manages itself (uncontrolled). It's narrower than Radix's own boolean \| 'indeterminate'. The tick or dash can only follow a checked value the caller passed in. Radix would track an uncontrolled mixed state internally but never hand it back, so that state is excluded instead of being drawn with the wrong mark. |
+| `onCheckedChange` | `(checked: boolean \| 'indeterminate') => void` |  | Runs every time it toggles. |
+| `disabled` | `boolean` |  | Takes it out of the tab order and stops it toggling. |
+| `required` | `boolean` |  | Uses the browser's built-in form validation. |
+| `name` | `string` |  | The field name sent with a native form. |
+| `value` | `string \| number \| readonly string[]` |  | The field value sent with a native form. |
+| `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. |
+| `id` | `string` |  | Pair it with a real label through htmlFor. |
+| `className` | `string` |  | Merged with the control's classes. If two clash, the later Tailwind utility wins (Tailwind is the CSS framework this system styles with). |
+| `ref` | `Ref<HTMLButtonElement>` |  | Passed through to the Radix root button. |
+| `...rest` | `Omit<CheckboxProps, 'aria-invalid' \| 'defaultChecked'>` |  | Every Radix Checkbox.Root prop except aria-invalid, spread onto the root. 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. defaultChecked is declared again above, narrowed to boolean. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### States
+
+```tsx
+<div className="flex items-center gap-2">
+  <Checkbox id="state-unchecked" />
+  <label htmlFor="state-unchecked">Unchecked</label>
+</div>
+<div className="flex items-center gap-2">
+  <Checkbox id="state-checked" checked />
+  <label htmlFor="state-checked">Checked</label>
+</div>
+<div className="flex items-center gap-2">
+  <Checkbox id="state-indeterminate" checked="indeterminate" />
+  <label htmlFor="state-indeterminate">Mixed</label>
+</div>
+<div className="flex items-center gap-2">
+  <Checkbox id="state-disabled" disabled />
+  <label htmlFor="state-disabled">Disabled</label>
+</div>
+```
+
+### A group
+
+```tsx
+const KIT_ITEMS = ['Speed loader', 'Rail light', 'Spare battery', 'First aid kit']
+
+const slug = (s: string) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-')
+
+function GroupExample() {
+  const [checkedItems, setCheckedItems] = useState<Record<string, boolean>>({
+    'Speed loader': true,
+    'Rail light': true,
+    'Spare battery': false,
+    'First aid kit': false,
+  })
+
+  const checkedCount = KIT_ITEMS.filter(item => checkedItems[item]).length
+  const parentChecked: boolean | 'indeterminate' =
+    checkedCount === 0 ? false : checkedCount === KIT_ITEMS.length ? true : 'indeterminate'
+
+  function setAll(value: boolean) {
+    setCheckedItems(Object.fromEntries(KIT_ITEMS.map(item => [item, value])))
+  }
+
+  return (
+    <div className="flex flex-col gap-2">
+      <div className="flex items-center gap-2">
+        <Checkbox
+          id="kit-parent"
+          checked={parentChecked}
+          onCheckedChange={checked => setAll(checked === true)}
+        />
+        <label htmlFor="kit-parent" className="font-medium">
+          Pack full field kit
+        </label>
+      </div>
+      <div className="flex flex-col gap-2 pl-6">
+        {KIT_ITEMS.map(item => (
+          <div key={item} className="flex items-center gap-2">
+            <Checkbox
+              id={`kit-item-${slug(item)}`}
+              checked={checkedItems[item]}
+              onCheckedChange={checked =>
+                setCheckedItems(prev => ({ ...prev, [item]: checked === true }))
+              }
+            />
+            <label htmlFor={`kit-item-${slug(item)}`}>{item}</label>
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+<GroupExample />
+```
+
+### Invalid
+
+```tsx
+<div className="flex items-center gap-2">
+  <Checkbox id="state-invalid" invalid />
+  <label htmlFor="state-invalid">Confirm waiver on file</label>
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves focus to it. |
+| `Space` | Toggles it. |
+| `Enter` | Nothing. That's how a native checkbox behaves, so it isn't a bug to fix. |
+
+## Do
+
+- Give it a real <label htmlFor>, or let FormField do it.
+- Use the mixed state for a parent whose children are partly selected.
+- Put the label on the right and make it part of the clickable target.
+
+## Don't
+
+- Don't use a checkbox for something that takes effect right away. That's a Switch.
+- Don't rely on the fill colour alone. The tick and the dash are what show the state.
+- Don't nest checkbox groups more than one level deep.
+
+## Anatomy
+
+- **Root**: A button with role=checkbox, which tells screen readers it's a checkbox. A native input can't be styled this way. The box is 20px (pixels) and the hit area, the part you can click or tap, is 24px.
+- **Indicator**: A tick when checked, a dash when mixed. The shape changes, so the state never depends on colour alone.
+- **Hit area**: A ::before inset of -2px, which clears the 24×24 minimum in WCAG 2.2 (the Web Content Accessibility Guidelines, the public rulebook for making websites usable by people with disabilities).

package/public/docs/components/checkout-form.md

@@ -0,0 +1,128 @@
+# CheckoutForm
+
+> Shipping, delivery and payment in three steps, with the order summary beside them. It's a demo: no payment is ever taken, and the card fields say so.
+
+- **Best for:** A demo checkout: shipping, delivery and payment in three steps beside the order summary.
+- **Not for:** Taking a real payment. It's a demo and never charges.
+- Organism. Source: `src/components/organisms/checkout-form/CheckoutForm.tsx`
+- Rendered docs page: `/components/checkout-form`
+
+## Import
+
+```tsx
+import { CheckoutForm, DELIVERY_OPTIONS } from 'src/components/organisms/checkout-form/CheckoutForm'
+```
+
+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 |
+|---|---|---|---|
+| `lines` | `CartLine[]` |  | Required. What's being bought. The order summary lists them. |
+| `countries` | `SelectOption[]` |  | Required. The options for the country Select. |
+| `deliveryOptions` | `DeliveryOption[]` | `DELIVERY_OPTIONS` | Prices in the currency's smallest unit. Zero shows as Free. |
+| `onPlaceOrder` | `(order: CheckoutOrder) => void \| { error: string } \| Promise<void \| { error: string }>` |  | Required. Gets the contact details, addresses, delivery id and total, and never a card field. If it rejects, an alert appears that lets the person try again, so the failure isn't lost. Resolving { error } shows that specific message in the same alert. |
+| `headingLevel` | `2 \| 3` | `2` | The level of the 'Checkout' heading. Steps and the order summary sit one level below it, and never below ErrorSummary's own fixed h4 (level-4 heading). |
+| `currency` | `string` | `'EUR'` | Passed to formatMoney. |
+| `locale` | `string` | `'en-IE'` | Passed to formatMoney. |
+| `className` | `string` |  | Merged with the root classes. Later Tailwind utilities win. |
+| `ref` | `Ref<HTMLDivElement>` |  | The root. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type DeliveryOption = {
+  id: string
+  label: string
+  detail: string
+  /** In the currency's minor unit (cents for EUR). Zero shows as "Free". */
+  price: number
+}
+```
+
+```ts
+export const DELIVERY_OPTIONS: DeliveryOption[] = [
+  { id: 'standard', label: 'Standard', detail: '3 to 5 working days', price: 0 },
+  { id: 'express', label: 'Express', detail: 'Next working day', price: 1200 },
+]
+```
+
+```ts
+export type CheckoutAddress = { line1: string; line2: string; city: string; postalCode: string; country: string }
+```
+
+```ts
+/** What the form hands over. No card field ever leaves it, demo or not. */
+export type CheckoutOrder = {
+  email: string
+  name: string
+  phone: string
+  shipping: CheckoutAddress
+  deliveryId: string
+  billing: CheckoutAddress | 'same-as-shipping'
+  /** In the currency's minor unit: the lines plus delivery. */
+  total: number
+}
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Three steps, a demo order
+
+```tsx
+const LINES: CartLine[] = [
+  { id: 'kestrel-c', name: 'Kestrel C carbine replica', unitPrice: 13900, quantity: 1 },
+  { id: 'prism-holo-sight', name: 'Prism holo sight', unitPrice: 4900, quantity: 2 },
+  { id: 'beam-600', name: 'Beam 600 rail light', unitPrice: 2400, quantity: 1 },
+]
+
+const COUNTRIES = [
+  { value: 'ie', label: 'Ireland' },
+  { value: 'ro', label: 'Romania' },
+  { value: 'de', label: 'Germany' },
+  { value: 'fr', label: 'France' },
+  { value: 'es', label: 'Spain' },
+]
+
+const wait = (ms: number) => new Promise(resolve => window.setTimeout(resolve, ms))
+
+<CheckoutForm lines={LINES} countries={COUNTRIES} onPlaceOrder={() => wait(800).then(() => undefined)} headingLevel={3} />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves through the fields, then Back and Continue. |
+| `Enter` | In a field, goes on to the next step, or places the order on the last one. |
+| `↑` `↓` | In the delivery options, moves and picks. |
+| `Space` | On the billing checkbox, toggles it. |
+
+## Do
+
+- Pass the cart lines, so the order summary and the total come from the same numbers.
+- Keep the demo notice whenever the card fields are fake.
+- Store prices in the currency's smallest unit (cents for EUR).
+
+## Don't
+
+- Don't make the Stepper clickable. Back and Continue move between steps.
+- Don't ask for the billing address unless it's different from shipping.
+- Don't validate a card number in a demo. Nothing's charged.
+
+## Anatomy
+
+- **Stepper**: Shows where the person is. It isn't clickable, so nobody can skip to a step whose fields don't exist yet.
+- **Step heading**: Read as 'Step 2 of 3: Delivery' by a screen reader. Focus (where keyboard input goes) lands here on Continue and Back.
+- **Error summary**: Lists the step's missing or wrong fields and takes focus. Each entry jumps to its field.
+- **Delivery options**: A radio group with prices, and nothing picked in advance.
+- **Billing**: Uses the shipping address by default. Unticking the box asks for a billing address.
+- **Demo notice**: An info Alert above the card fields saying no payment is taken.
+- **Order summary**: Lines, subtotal, delivery and total, formatted by formatMoney.
+- **Confirmation**: A status line that's always on the page and confirms the order.
+- **Placement alert**: Also always on the page. If onPlaceOrder rejects, or resolves { error } with a specific message, this alert says so, instead of the button just quietly stopping being busy. Everything already typed stays put for another try.