division-ds 0.1.2 → 0.2.1

package/public/docs/components/pagination.md

@@ -0,0 +1,212 @@
+# Pagination
+
+> Moves through a long list one page at a time. The current page gets the signal fill. Where there are too many pages to fit, a gap stands in for the run that's hidden.
+
+- **Best for:** Moving through a long list or table one page at a time.
+- **Not for:** Steps in a form: use Stepper. Fewer than two pages: don't render anything.
+- Molecule. Source: `src/components/molecules/pagination/Pagination.tsx`
+- Rendered docs page: `/components/pagination`
+
+## Import
+
+```tsx
+import { Pagination, paginationRange } from 'src/components/molecules/pagination/Pagination'
+```
+
+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 |
+|---|---|---|---|
+| `page` | `number` |  | Counts from 1. A number outside the range is pulled back into it. |
+| `pageCount` | `number` |  | Below 1, nothing renders. |
+| `onPageChange` | `(page: number) => void` |  | It's never called with the page you're already on. |
+| `variant` | `'numbered' \| 'compact' \| 'select'` | `'numbered'` | What sits between Previous and Next: the page buttons, a 'Page 3 of 20' readout (which screen readers announce politely, without interrupting, when it changes), or a page Select. Only use 'select' up to a few dozen pages. |
+| `siblings` | `number` | `1` | How many pages show on each side of the current page, for 'numbered'. |
+| `showFirstLast` | `boolean` | `false` | Adds First page and Last page icon buttons at the ends. Like Previous and Next, they go aria-disabled at the first and last page. |
+| `showLabels` | `boolean` | `false` | Shows Previous and Next as text buttons ('Previous', 'Next') with their chevrons, instead of icons alone. |
+| `showJump` | `boolean` | `false` | Adds a 'Go to page' field. Enter or Go jumps there, and a number past either end goes to that end. |
+| `totalItems` | `number` |  | Together with pageSize, it shows the range on view ('21–40 of 400') at the start and lays the control out as a table footer. |
+| `pageSize` | `number` |  | Items per page, used for the range text and the rows-per-page Select. |
+| `onPageSizeChange` | `(pageSize: number) => void` |  | Together with pageSize, it shows a rows-per-page Select. When it fires, reset page to 1: the old page may not exist any more. |
+| `pageSizeOptions` | `number[]` | `[10, 20, 50, 100]` | The rows-per-page choices. |
+| `label` | `string` | `'Pagination'` | The name of the nav landmark (a region screen readers can jump to). |
+| `className` | `string` |  | Added to the nav element. |
+| `ref` | `Ref<HTMLElement>` |  | Passed through to the nav DOM node (the element in the page). |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+/** Pure. 1-based. Always includes page 1, the last page, the current page and `siblings` pages
+ *  either side of it. A gap stands for two or more hidden pages; a single hidden page is shown
+ *  instead, because a gap that hides one number costs the same space as the number. */
+export function paginationRange(page: number, pageCount: number, siblings = 1): (number | 'gap')[]
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Few pages
+
+```tsx
+<Pagination page={2} pageCount={5} onPageChange={() => {}} label="Pagination, few pages" />
+```
+
+### Many pages
+
+```tsx
+function ManyPagesExample() {
+  const [page, setPage] = useState(1)
+  const perPage = 20
+  const total = 400
+  const from = (page - 1) * perPage + 1
+  const to = Math.min(page * perPage, total)
+
+  return (
+    <div>
+      <Pagination page={page} pageCount={20} onPageChange={setPage} label="Pagination, many pages" />
+      <p className="font-mono text-xs text-[var(--color-text-muted)] mt-3">
+        Showing {from} to {to} of {total} depots
+      </p>
+    </div>
+  )
+}
+
+<ManyPagesExample />
+```
+
+### Wider context: two page numbers on each side of the current page
+
+```tsx
+<Pagination
+  page={10}
+  pageCount={20}
+  siblings={2}
+  onPageChange={() => {}}
+  label="Pagination, wider context"
+/>
+```
+
+### First and last
+
+```tsx
+function Live(props: Omit<Parameters<typeof Pagination>[0], 'page' | 'onPageChange'>) {
+  const [page, setPage] = useState(4)
+  return <Pagination {...props} page={page} onPageChange={setPage} />
+}
+
+<Live pageCount={20} showFirstLast label="Pagination, first and last" />
+```
+
+### With labels
+
+```tsx
+function Live(props: Omit<Parameters<typeof Pagination>[0], 'page' | 'onPageChange'>) {
+  const [page, setPage] = useState(4)
+  return <Pagination {...props} page={page} onPageChange={setPage} />
+}
+
+<Live pageCount={20} showLabels label="Pagination, with labels" />
+```
+
+### Compact
+
+```tsx
+function Live(props: Omit<Parameters<typeof Pagination>[0], 'page' | 'onPageChange'>) {
+  const [page, setPage] = useState(4)
+  return <Pagination {...props} page={page} onPageChange={setPage} />
+}
+
+<Live variant="compact" pageCount={20} showFirstLast label="Pagination, compact" />
+```
+
+### Page select
+
+```tsx
+function Live(props: Omit<Parameters<typeof Pagination>[0], 'page' | 'onPageChange'>) {
+  const [page, setPage] = useState(4)
+  return <Pagination {...props} page={page} onPageChange={setPage} />
+}
+
+<Live variant="select" pageCount={12} label="Pagination, page select" />
+```
+
+### Go to page
+
+```tsx
+function Live(props: Omit<Parameters<typeof Pagination>[0], 'page' | 'onPageChange'>) {
+  const [page, setPage] = useState(4)
+  return <Pagination {...props} page={page} onPageChange={setPage} />
+}
+
+<Live pageCount={48} showJump label="Pagination, go to page" />
+```
+
+### Table footer
+
+```tsx
+function TableFooterExample() {
+  const total = 397
+  const [page, setPage] = useState(2)
+  const [pageSize, setPageSize] = useState(20)
+  return (
+    <div className="w-full">
+      <Pagination
+        page={page}
+        pageCount={Math.ceil(total / pageSize)}
+        onPageChange={setPage}
+        totalItems={total}
+        pageSize={pageSize}
+        onPageSizeChange={size => {
+          setPageSize(size)
+          setPage(1)
+        }}
+        showFirstLast
+        label="Pagination, table footer"
+      />
+    </div>
+  )
+}
+
+<TableFooterExample />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves across Previous, each page, and Next. |
+| `Enter` `Space` | Goes to that page. |
+| `Enter` | In the Go to page field, jumps to the page you typed. |
+
+## Do
+
+- Say how many results there are somewhere near it: 'Showing 41 to 60 of 312'.
+- After a change, move focus to the top of the new page of results.
+- Keep siblings at 1 on narrow layouts.
+- Under a data table, pass totalItems and pageSize. The footer then says what's on view, so you don't need a separate line of text.
+- Use variant 'compact' where space is tight, such as a card or a phone layout.
+
+## Don't
+
+- Don't paginate fewer than two pages; render nothing.
+- Don't disable the current page; Tab would skip it.
+- Don't use pagination for steps in a form.
+- Don't use variant 'select' for hundreds of pages. A list that long needs showJump instead.
+- Don't round the buttons into circles or pills; the square and the cut corner are this system's shape.
+
+## Anatomy
+
+- **nav**: The navigation region, named 'Pagination'.
+- **Previous / Next**: Ghost IconButtons (icon-only buttons with no fill). At the first and last page they're aria-disabled rather than disabled. ARIA (Accessible Rich Internet Applications) attributes tell screen readers about a control, and aria-disabled only marks the button as unavailable. It stays a real stop when you press Tab, so keyboard focus never drops to the page body when one stops working.
+- **Page**: A small Button named 'Page n', with tabular figures (digits that all take the same width).
+- **Current page**: The primary fill, with aria-current=page so screen readers say it's the current one. It isn't disabled, so Tab still reaches it.
+- **Gap**: An ellipsis that stands for two or more hidden pages. It's aria-hidden, so screen readers skip it.
+- **First / Last**: Optional (showFirstLast). Ghost IconButtons, aria-disabled at the first and last page.
+- **Readout or page Select**: Takes the place of the page buttons when variant is 'compact' or 'select'.
+- **Range and rows per page**: Optional (totalItems, pageSize, onPageSizeChange). These turn the control into a table footer: the range at the start, the controls at the end.
+- **Go to page**: Optional (showJump). A small number Input with a visible label, and a Go button.

package/public/docs/components/product-card.md

@@ -0,0 +1,172 @@
+# ProductCard
+
+> One product as one link. Clicking anywhere on the card opens it, Add to cart stays a separate control, and a grid of cards adapts to the space it's given.
+
+- **Best for:** One product in a shop grid, where the whole card opens it and Add to cart sits on it.
+- **Not for:** A general content panel: use Card.
+- **Also on this page:** `ProductGrid`
+- Organism. Source: `src/components/organisms/product-card/ProductCard.tsx`
+- Rendered docs page: `/components/product-card`
+
+## Import
+
+```tsx
+import { ProductCard, ProductGrid } from 'src/components/organisms/product-card/ProductCard'
+```
+
+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 |
+|---|---|---|---|
+| `product (ProductCard)` | `Product` |  | Required. id, name, href and price (in the currency's minor unit, so cents for EUR). rating, image, badge and soldOut are optional. |
+| `onAddToCart` | `(product: Product) => void` |  | Draws Add to cart. Leave it out for a card that only links to the product. |
+| `headingLevel` | `2 \| 3 \| 4` | `3` | Pick the level that fits the page's heading outline. |
+| `currency` | `string` | `'EUR'` | Passed to formatMoney. |
+| `locale` | `string` | `'en-IE'` | Passed to formatMoney. |
+| `renderLink` | `(props: LinkRenderProps) => ReactNode` | `a plain anchor` | Draws the name's link. It must pass className through, because that class carries the stretched click area and the focus ring. |
+| `renderMedia` | `(product: Product) => ReactNode` | `the product's image, 4:3, cover` | Draws the picture instead of the image or the placeholder, for example a staged cutout. Keep the 4:3 box and keep it decorative. The badge still sits over it. |
+| `className (ProductCard)` | `string` |  | Merged with the root classes. Later Tailwind utilities win. |
+| `ref (ProductCard)` | `Ref<HTMLElement>` |  | Points at the article element. |
+| `products (Grid)` | `Product[]` |  | Required. |
+| `label (Grid)` | `string` |  | Required. The list's accessible name, the name a screen reader announces for it. |
+| `emptyMessage (Grid)` | `string` | `'No products match.'` | Announced by a status message that's always on the page when products is empty. The list itself keeps rendering (so its ref stays stable), but it's hidden while there's nothing in it. |
+| `className (Grid)` | `string` |  | Merged with the list's own classes. Later Tailwind utilities win. |
+| `ref (Grid)` | `Ref<HTMLUListElement>` |  | Points at the list element. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type Product = {
+  id: string
+  name: string
+  href: string
+  /** In the currency's minor unit (cents for EUR). */
+  price: number
+  /** The price before a sale, in the currency's minor unit (cents for EUR): struck through, and
+   *  read as "was". */
+  compareAtPrice?: number
+  rating?: { value: number; count: number }
+  /** Without one, the card draws a decorative placeholder. `alt` defaults to '': the title names
+   *  the product. */
+  image?: { src: string; alt?: string }
+  /** A short solid tag, e.g. "New" or "Sale". */
+  badge?: string
+  soldOut?: boolean
+}
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### One product
+
+```tsx
+const REPLICA: Product = {
+  id: 'kestrel-k',
+  name: 'Kestrel K compact replica',
+  href: '#kestrel-k',
+  price: 12900,
+  compareAtPrice: 14900,
+  rating: { value: 4.5, count: 128 },
+  badge: 'Sale',
+}
+
+function OneProductExample() {
+  const { toast } = useToast()
+  return (
+    <div className="max-w-xs">
+      <ProductCard
+        product={REPLICA}
+        headingLevel={4}
+        onAddToCart={product => toast({ title: 'Added to cart', description: product.name, tone: 'ok' })}
+      />
+    </div>
+  )
+}
+
+<OneProductExample />
+```
+
+### A grid
+
+```tsx
+const RANGE: Product[] = [
+  { id: 'kestrel-c', name: 'Kestrel C carbine replica', href: '#kestrel-c', price: 13900, rating: { value: 4.5, count: 212 } },
+  { id: 'prism-holo-sight', name: 'Prism holo sight', href: '#prism-holo-sight', price: 4900, badge: 'New' },
+  { id: 'speed-loader', name: 'Speed loader, 150 BBs', href: '#speed-loader', price: 790, rating: { value: 4, count: 87 } },
+  { id: 'kestrel-l', name: 'Kestrel L rifle replica', href: '#kestrel-l', price: 15900, soldOut: true },
+  { id: 'bbs-028', name: 'Precision BBs 0.28 g, 2,700', href: '#bbs-028', price: 590 },
+  { id: 'field-goggles', name: 'Field goggles', href: '#field-goggles', price: 3400, compareAtPrice: 3900, badge: 'Sale' },
+]
+
+function AGridExample() {
+  const { toast } = useToast()
+  return (
+    <ProductGrid
+      label="Hexline range"
+      products={RANGE}
+      headingLevel={4}
+      onAddToCart={product => toast({ title: 'Added to cart', description: product.name, tone: 'ok' })}
+    />
+  )
+}
+
+<AGridExample />
+```
+
+### A custom picture through renderMedia
+
+```tsx
+const STAGED: Product = { id: 'harrier-lr', name: 'Harrier LR bolt-action replica', href: '#harrier-lr', price: 17900, rating: { value: 4.5, count: 37 } }
+
+<div className="max-w-xs">
+  <ProductCard
+    product={STAGED}
+    headingLevel={4}
+    renderMedia={product => (
+      <div aria-hidden="true" className="flex aspect-[4/3] items-center justify-center bg-[var(--color-surface-sunken)] p-4">
+        <img src={`/media/products/cutout/${product.id}-640.webp`} alt="" loading="lazy" className="max-h-full w-full object-contain" />
+      </div>
+    )}
+  />
+</div>
+```
+
+### Nothing matches
+
+```tsx
+<ProductGrid label="Hexline range, filtered" products={[]} emptyMessage="No products match these filters." />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves to the product's link, then to Add to cart, then to the next card. |
+| `Enter` | On the link, opens the product. On Add to cart, adds it. |
+
+## Do
+
+- Give the grid a label that says what it holds.
+- Store prices in the currency's minor unit (cents for EUR). The card formats them.
+- Pass headingLevel so the names fit the page's heading outline.
+
+## Don't
+
+- Don't put another link or button in the card body. Only Add to cart sits above the stretched link.
+- Don't colour the price. It's text.primary.
+- Don't write alt text (the image description for screen readers) that repeats the name.
+
+## Anatomy
+
+- **Image**: Optional. Without one, there's a decorative placeholder. renderMedia can draw something else in the same box.
+- **Badge**: Optional. A short solid tag over the corner of the picture, like New or Sale. It sits outside the text flow, so names line up along a row of cards.
+- **Name**: The heading, and the link. Its click area and its focus ring (the outline keyboard users see) cover the whole card.
+- **Rating**: Optional. Screen readers hear the stars as 'rated 4.5 out of 5', and the review count is plain text.
+- **Price**: In text.primary, with tabular (equal-width) figures. A sale adds the old price struck through, which screen readers hear as "was".
+- **Add to cart**: Sits above the link as its own target, and it's named after the product.

package/public/docs/components/progress.md

@@ -0,0 +1,101 @@
+# Progress
+
+> A progress bar that's either determinate (it knows how far along the task is) or indeterminate (it doesn't). The readout is real text in the DOM (the Document Object Model, the live page structure the browser builds) from the very first render. That's motion token M3's rule, and it means a screen reader, the software that reads the page aloud for blind and low-vision people, never hears a number roll.
+
+- **Best for:** Showing how far a measurable task has got. Switch to indeterminate once you no longer know how much is left.
+- **Not for:** A wait with no measurable work. Use Spinner.
+- Atom. Source: `src/components/atoms/progress/Progress.tsx`
+- Rendered docs page: `/components/progress`
+
+## Import
+
+```tsx
+import { Progress } from 'src/components/atoms/progress/Progress'
+```
+
+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. The bar’s accessible name. |
+| `value` | `number \| null` |  | null means indeterminate. The value is clamped to [0, max], so an out-of-range value shows as complete instead of overflowing the track. |
+| `max` | `number` | `100` | The value at which the bar is complete. |
+| `showValue` | `boolean` | `false` | Shows the percentage (or "In progress") as a readout. |
+| `tone` | `'signal' \| 'ok' \| 'warning' \| 'hostile'` | `'signal'` | The fill colour. signal paints accent.signal.indicator to match Slider. On the track in light theme that’s a 2.15:1 contrast ratio, below the 3:1 a bar needs when it’s the only sign of progress. So set showValue there. |
+| `className` | `string` |  | Merged with the outer wrapper’s classes. Later Tailwind utilities (Tailwind is the CSS framework the system is styled with) win. |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed through to the Radix Progress root, which is the bar itself. Radix is the library of accessible building blocks this component sits on. |
+| `...rest` | `Omit<HTMLAttributes<HTMLDivElement>, 'children'>` |  | Every native div prop except children, spread onto the outer wrapper, so a molecule can attach a data-testid there. children is typed away because this component draws its own label row and track, and a children prop would be thrown away without any warning. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Determinate
+
+```tsx
+<div className="w-full max-w-sm">
+  <Progress label="Uploading manifest" value={40} />
+</div>
+```
+
+### With a readout
+
+```tsx
+<div className="w-full max-w-sm">
+  <Progress label="Uploading manifest" value={65} showValue />
+</div>
+```
+
+### Custom max
+
+```tsx
+<div className="w-full max-w-sm">
+  <Progress label="Packing crates" value={3} max={12} showValue />
+</div>
+```
+
+### Indeterminate
+
+```tsx
+<div className="w-full max-w-sm">
+  <Progress label="Syncing manifest" value={null} showValue />
+</div>
+```
+
+### Tones
+
+```tsx
+<div className="flex flex-col gap-4 w-full max-w-sm">
+  <Progress label="Signal supply run" value={40} tone="signal" showValue />
+  <Progress label="BB reserves" value={82} tone="ok" showValue />
+  <Progress label="Gas reserves" value={22} tone="warning" showValue />
+  <Progress label="Battery reserves" value={6} tone="hostile" showValue />
+</div>
+```
+
+## Keyboard
+
+Not focusable. No keyboard behaviour of its own.
+
+## Do
+
+- Name what’s progressing, not the act of progressing.
+- Use showValue whenever the number itself is useful to the reader.
+- Switch to null the moment you stop knowing how much is left. Don’t freeze at 90%.
+
+## Don't
+
+- Don't animate the number up from zero and call that animated value the readout. The real value belongs in the DOM straight away.
+- Don't use Progress for a wait with no measurable work. That's a Spinner.
+- Don't put the padded readout into the accessible name. That's exactly why the pad is a separate aria-hidden span, and label is what Radix announces.
+- Don't rely on the tone alone to say something failed. Say it in text.
+
+## Anatomy
+
+- **Label**: Required. Set in mono (a monospaced font, where every character is the same width) and uppercase. It’s also the bar’s accessible name, the name assistive tech such as a screen reader announces for it.
+- **Readout**: Optional, and the star of the row: 24px (pixels) Oxanium against an 11px label. It uses tabular figures, digits that all take the same width, so the number doesn’t jitter as it changes.
+- **Leading zeros**: These are padding, not part of the value. They’re dimmed to numeral.pad and marked aria-hidden (an ARIA attribute, from Accessible Rich Internet Applications, that hides an element from assistive tech). So the readout keeps a fixed three-digit width, while a screen reader still hears 40%, not zero four zero percent.
+- **Track**: 6px tall, a sunken surface, no border. It’s the same track as Slider.
+- **Indicator**: It’s moved rather than resized. That way the browser animates a transform, which is cheap, instead of recalculating the layout.

package/public/docs/components/prompt-input.md

@@ -0,0 +1,151 @@
+# PromptInput
+
+> The box where a person writes to an assistant. It grows to fit the text, has one Send/Stop button and can show suggestions. Enter sends, and Shift+Enter starts a new line.
+
+- **Best for:** The message box under a ChatThread.
+- **Not for:** A long field in a form: use Textarea inside a FormField.
+- Molecule. Source: `src/components/molecules/prompt-input/PromptInput.tsx`
+- Rendered docs page: `/components/prompt-input`
+
+## Import
+
+```tsx
+import { PromptInput } from 'src/components/molecules/prompt-input/PromptInput'
+```
+
+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 keeps the draft in state and clears it in onSubmit.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | Required. Names the box. It's hidden on screen. |
+| `value` | `string` |  | Required. The draft. Controlled, meaning your page holds it. |
+| `onValueChange` | `(value: string) => void` |  | Required. |
+| `onSubmit` | `(value: string) => void` |  | Required. Fires on Enter, Send or a suggestion, and never with a blank draft. Clear the draft here. |
+| `busy` | `boolean` | `false` | Send turns into Stop, and Enter sends nothing. |
+| `onStop` | `() => void` |  | Runs on Stop, and on Escape in the box while busy. |
+| `suggestions` | `readonly string[]` |  | Ready-made prompts shown as chips. Clicking one submits it. |
+| `editableSuggestions` | `boolean` | `false` | Clicking a suggestion puts its text in the box to edit instead of sending it. Use it when a person will likely change the prompt first. The chips then stay usable while busy. |
+| `placeholder` | `string` |  | Shown in the empty box. |
+| `disabled` | `boolean` | `false` | Nothing can be typed or sent. Say why somewhere nearby. |
+| `hint` | `string` | `'Enter to send, Shift+Enter for a new line'` | The line under the box, which is also its description. |
+| `className` | `string` |  | Added to the form. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### With suggestions
+
+```tsx
+function DraftExample() {
+  const [value, setValue] = useState('')
+  const [sent, setSent] = useState<string | null>(null)
+  return (
+    <div className="flex w-full max-w-xl flex-col gap-3">
+      <PromptInput
+        label="Message the assistant"
+        placeholder="Ask about stock, orders or depots"
+        value={value}
+        onValueChange={setValue}
+        onSubmit={text => {
+          setSent(text)
+          setValue('')
+        }}
+        suggestions={['Summarise stock at Depot 4', 'Which replicas are running low?']}
+      />
+      <p className="font-body text-sm text-[var(--color-text-secondary)]" aria-live="polite">
+        {sent === null ? 'Nothing sent yet.' : `Sent: ${sent}`}
+      </p>
+    </div>
+  )
+}
+
+<DraftExample />
+```
+
+### Busy: a Stop button takes the place of Send, and pressing Escape stops it too
+
+```tsx
+function BusyExample() {
+  const [value, setValue] = useState('')
+  const [busy, setBusy] = useState(true)
+  return (
+    <div className="flex w-full max-w-xl flex-col gap-3">
+      <PromptInput
+        label="Message the assistant, while it works"
+        value={value}
+        onValueChange={setValue}
+        onSubmit={() => setValue('')}
+        busy={busy}
+        onStop={() => setBusy(false)}
+      />
+      {busy ? null : (
+        <Button size="sm" variant="ghost" wrapperClassName="self-start" onClick={() => setBusy(true)}>
+          Make it busy again
+        </Button>
+      )}
+    </div>
+  )
+}
+
+<BusyExample />
+```
+
+### Disabled
+
+```tsx
+<div className="flex w-full max-w-xl flex-col gap-2">
+  <PromptInput label="Message the assistant (disabled)" value="" onValueChange={() => {}} onSubmit={() => {}} disabled />
+  <p className="font-body text-sm text-[var(--color-text-secondary)]">The assistant is offline until 14:00.</p>
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Enter` | Sends the draft. Does nothing while busy, or while someone's composing characters with an IME (Input Method Editor, the tool used to type languages like Chinese or Japanese). |
+| `Shift` `Enter` | Starts a new line. |
+| `Escape` | While busy, stops the reply. |
+
+## Do
+
+- Clear the draft in onSubmit, and set busy as soon as the request starts.
+- Wire up onStop whenever the reply can be stopped. A reply that streams in with no Stop is a wait with no way out.
+- Offer two to four suggestions in an empty thread, and drop them once the conversation has started.
+
+## Don't
+
+- Don't disable the box while busy; a person may be writing the next message while the reply arrives.
+- Don't wrap it in a FormField. Its label is hidden on purpose, and it brings its own hint.
+- Don't move focus into it when the reply finishes. It never left, unless the person moved it.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+{busy ? <Button onClick={stop}>Stop</Button> : <Button type="submit">Send</Button>}
+```
+
+Right:
+
+```tsx
+<PromptInput busy={busy} onStop={stop} ... />
+```
+
+Swapping two buttons drops keyboard focus to the page at the moment they switch. PromptInput keeps one button and changes its label and what it does.
+
+## Anatomy
+
+- **Form**: Paints surface.base itself, as every form does.
+- **Suggestions**: A group of chips above the box. Clicking one submits its text (disabled while busy), or with editableSuggestions puts it in the box to edit.
+- **Box**: A Textarea with a label that's hidden on screen but read by screen readers. It grows from one line to about eight, then scrolls inside.
+- **Send / Stop**: One button: a primary Send with an arrow, or, while busy, a secondary Stop with a square.
+- **Hint**: One line under the box, which is also the box's description: "Enter to send, Shift+Enter for a new line".