division-ds 0.1.2 → 0.2.1

package/public/docs/components/quantity-stepper.md

@@ -0,0 +1,140 @@
+# QuantityStepper
+
+> A whole number between a lowest and a highest value, with a button on each side. It follows the spinbutton pattern (the standard recipe for a number you nudge up and down), so the keyboard can do everything from inside the field.
+
+- **Best for:** A whole number between real limits, such as a quantity in a cart.
+- **Not for:** A value that isn't a whole number: use Input. A range of hundreds: use Slider or Input.
+- Molecule. Source: `src/components/molecules/quantity-stepper/QuantityStepper.tsx`
+- Rendered docs page: `/components/quantity-stepper`
+
+## Import
+
+```tsx
+import { QuantityStepper, clampQuantity, gridMax } from 'src/components/molecules/quantity-stepper/QuantityStepper'
+```
+
+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. Names the field and both buttons ("Decrease Speed loader quantity"). |
+| `value` | `number` |  | Controlled value (your page holds it). |
+| `defaultValue` | `number` | `min` | Starting value when the component holds the value itself (uncontrolled). |
+| `onValueChange` | `(value: number) => void` |  | Fires with the final value, pulled inside the limits: after a button click, an arrow key, Home/End, or when typing is finished by leaving the field or pressing Enter. |
+| `min` | `number` | `0` | Lowest allowed value. |
+| `max` | `number` | `99` | Highest allowed value. |
+| `step` | `number` | `1` | The size of each step the value snaps to, counted from min. |
+| `disabled` | `boolean` | `false` | Disables the field and both buttons. |
+| `inputSize` | `'sm' \| 'md'` | `'md'` | Size of the field and buttons. |
+| `className` | `string` |  | Combined with the root classes. Where Tailwind utility classes clash, the later one wins. |
+| `ref` | `Ref<HTMLInputElement>` |  | Passed through to the field. |
+| `id` | `string` |  | The field's id, so a FormField's label and error text can point at it. FormField sets it. |
+| `aria-describedby` | `string` |  | The ids of the help and error text, set on the field so screen readers read them out. FormField sets it. |
+| `invalid` | `boolean` |  | Marks the field as invalid: aria-invalid and the invalid border. FormField sets it when there is an error. |
+| `required` | `boolean` |  | Marks the field as required. FormField sets it. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+/** The step grid's own last rung at or below `max` -- the real upper bound the control can reach.
+ *  `max` itself may not be a step away from `min` (min 0, max 99, step 5: the grid is 0, 5, ...,
+ *  95, and 99 is never a rung on it), so this is what `aria-valuemax`, the Increase button's
+ *  disabled state, the focus-on-bound check and End all need instead of `max` directly -- a control
+ *  that can never reach the value it announces as its maximum is worse than one that announces a
+ *  lower, reachable one. */
+export function gridMax(min: number, max: number, step = 1): number
+```
+
+```ts
+/**
+ * Pure. Parses, snaps to the step grid measured from min, then clamps into `[min, gridMax(min,
+ * max, step)]`. Unparseable input returns `min`.
+ *
+ * `min > max` is the caller's error, not this function's to reject: the formula has no branch that
+ * assumes `min <= max`, so it still returns a number rather than throwing -- just not a meaningful
+ * one for an inverted range. Callers are expected to pass a sane range.
+ */
+export function clampQuantity(raw: string | number, min: number, max: number, step = 1): number
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Default
+
+```tsx
+<QuantityStepper label="Speed loader quantity" defaultValue={1} />
+```
+
+### Bounded: with a lowest and a highest allowed number
+
+```tsx
+<div className="flex flex-col gap-2">
+  <QuantityStepper label="Bump helmet quantity" defaultValue={1} min={1} max={4} />
+  <span className="font-mono text-xs text-[var(--color-text-secondary)]">Only four left</span>
+</div>
+```
+
+### Stepping by five
+
+```tsx
+<QuantityStepper label="BB bottle quantity" defaultValue={5} min={0} max={50} step={5} />
+```
+
+### In a cart line
+
+```tsx
+function CartLine() {
+  const price = 38
+  const [qty, setQty] = useState(2)
+  return (
+    <div className="flex items-center gap-4 w-full">
+      <span className="flex-1 font-body text-sm text-[var(--color-text-primary)]">Speed loader</span>
+      <QuantityStepper
+        label="Speed loader quantity"
+        defaultValue={2}
+        min={1}
+        max={9}
+        onValueChange={setQty}
+      />
+      <span className="w-16 text-right font-display font-semibold tabular-nums text-[var(--color-text-primary)]">
+        €{price * qty}
+      </span>
+    </div>
+  )
+}
+
+<CartLine />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `↑` `↓` | One step. |
+| `Page Up` `Page Down` | Ten steps. |
+| `Home` `End` | Jumps to the minimum or maximum. |
+| `Enter` | Confirms what you typed. |
+| `Tab` | Leaves the field and confirms what you typed. Tab doesn't stop on the buttons. |
+
+## Do
+
+- Set a real maximum, like the stock level or an order limit, not an arbitrary 99.
+- Name the field after the item: 'Speed loader quantity'.
+- Show the line total beside it, updating as the value changes.
+
+## Don't
+
+- Don't use it for values that aren't whole numbers; that's an Input.
+- Don't use it for a range of hundreds; that's a Slider or an Input.
+- Don't pull the value back inside the limits while someone's still typing.
+
+## Anatomy
+
+- **Field**: Has role=spinbutton, plus its value and limits, so screen readers know what it is. It's a text field that brings up a number keypad on phones, not the browser's own number input.
+- **Decrease / Increase**: Secondary IconButtons named after the field. As the pattern says, Tab skips them. They're disabled at the lowest and highest value.

package/public/docs/components/radio.md

@@ -0,0 +1,177 @@
+# Radio
+
+> Pick one choice from a set. The whole group is a single tab stop, and the arrow keys move inside it. That’s how native radio buttons behave, and it’s most of the reason this is built on a Radix primitive (Radix is a library of accessible building blocks) instead of three styled inputs.
+
+- **Best for:** One choice from a short set, up to about seven, all shown at once.
+- **Not for:** A yes/no question: use Checkbox or Switch. A longer list: use Select.
+- Atom. Source: `src/components/atoms/radio/Radio.tsx`
+- Rendered docs page: `/components/radio`
+
+## Import
+
+```tsx
+import { Radio, RadioGroup } from 'src/components/atoms/radio/Radio'
+```
+
+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 |
+|---|---|---|---|
+| `value (RadioGroup)` | `string` |  | The selected value, when you control it from outside. |
+| `defaultValue (RadioGroup)` | `string` |  | The starting value, when the group manages it itself (uncontrolled). |
+| `onValueChange (RadioGroup)` | `(value: string) => void` |  | Fires when the selection changes. |
+| `name (RadioGroup)` | `string` |  | The native form field name. |
+| `required (RadioGroup)` | `boolean` |  | Uses the browser’s native form validation. |
+| `disabled (RadioGroup)` | `boolean` |  | Disables every option in the group. |
+| `orientation (RadioGroup)` | `'horizontal' \| 'vertical'` |  | Sets which arrow keys move between options. The visual layout is still up to className. |
+| `aria-label / aria-labelledby (RadioGroup)` | `string` |  | One of these is required. They’re ARIA attributes (from Accessible Rich Internet Applications) that give the group a name screen readers announce. A radiogroup with no name is a bug. |
+| `value (Radio)` | `string` |  | Required. This option’s value. |
+| `disabled (Radio)` | `boolean` |  | Takes just this option out of selection. |
+| `id (Radio)` | `string` |  | Pair it with a real label using htmlFor. |
+| `invalid (Radio)` | `boolean` | `false` | Sets aria-invalid, which tells assistive tech the field has an error, and shows the invalid border. |
+| `className` | `string` |  | Merged with the control's classes. Later Tailwind utilities (Tailwind is the CSS framework the system uses) win. |
+| `ref` | `Ref<HTMLDivElement> (RadioGroup) / Ref<HTMLButtonElement> (Radio)` |  | Passed through to the Radix root element. |
+| `...rest` | `(Radio) Omit<RadioGroup.Item props, 'aria-invalid'>` |  | Every Radix RadioGroup.Item prop except aria-invalid, spread onto the item. aria-invalid is typed away instead of being quietly overridden at runtime, because invalid is the only source of both the attribute and the border. RadioGroup itself excludes nothing. It computes no value of its own that a rest prop could defeat. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### A group
+
+```tsx
+const SPEEDS = ['standard', 'priority', 'overnight'] as const
+
+function LiveExample() {
+  const [value, setValue] = useState<string>('standard')
+  return (
+    <RadioGroup aria-label="Dispatch speed" value={value} onValueChange={setValue}>
+      {SPEEDS.map(speed => (
+        <div key={speed} className="flex items-center gap-2">
+          <Radio value={speed} id={`dispatch-${speed}`} />
+          <label htmlFor={`dispatch-${speed}`} className="capitalize">
+            {speed}
+          </label>
+        </div>
+      ))}
+    </RadioGroup>
+  )
+}
+
+<LiveExample />
+```
+
+### With a default
+
+```tsx
+const SPEEDS = ['standard', 'priority', 'overnight'] as const
+
+<RadioGroup aria-label="Dispatch speed, defaulted" defaultValue="priority">
+  {SPEEDS.map(speed => (
+    <div key={speed} className="flex items-center gap-2">
+      <Radio value={speed} id={`default-${speed}`} />
+      <label htmlFor={`default-${speed}`} className="capitalize">
+        {speed}
+      </label>
+    </div>
+  ))}
+</RadioGroup>
+```
+
+### Horizontal
+
+```tsx
+const SPEEDS = ['standard', 'priority', 'overnight'] as const
+
+<RadioGroup aria-label="Dispatch speed, horizontal" orientation="horizontal" defaultValue="standard" className="flex-row flex-wrap gap-4">
+  {SPEEDS.map(speed => (
+    <div key={speed} className="flex items-center gap-2">
+      <Radio value={speed} id={`horizontal-${speed}`} />
+      <label htmlFor={`horizontal-${speed}`} className="capitalize">
+        {speed}
+      </label>
+    </div>
+  ))}
+</RadioGroup>
+```
+
+### Disabled option
+
+```tsx
+const SPEEDS = ['standard', 'priority', 'overnight'] as const
+
+<RadioGroup aria-label="Dispatch speed, one option disabled" defaultValue="standard">
+  {SPEEDS.map(speed => (
+    <div key={speed} className="flex items-center gap-2">
+      <Radio value={speed} id={`disabled-${speed}`} disabled={speed === 'overnight'} />
+      <label htmlFor={`disabled-${speed}`} className="capitalize">
+        {speed}
+      </label>
+    </div>
+  ))}
+</RadioGroup>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Enters the group at the selected option, or at the first one if nothing’s selected. |
+| `↓` `→` | Selects the next option. |
+| `↑` `←` | Selects the previous option. |
+| `Space` | Selects the focused option. |
+
+## Do
+
+- Name the group: in a form, a fieldset legend that the RadioGroup points at with aria-labelledby; elsewhere, aria-label.
+- Offer a default when one option really is the norm.
+- Keep the set short. Past about seven options, use a Select.
+
+## Don't
+
+- Don't use radios for a yes/no. That's a Checkbox or a Switch.
+- Don't put a radio outside a RadioGroup. Both the roving focus and the value come from the group.
+- Don't make choosing an option perform the action. Put a button after the group.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<FormField label="Difficulty" error={error}>
+  <RadioGroup>
+    <Radio value="easy" />
+  </RadioGroup>
+</FormField>
+```
+
+Right:
+
+```tsx
+<fieldset aria-describedby={error ? 'difficulty-error' : undefined}>
+  <legend id="difficulty-label" className="font-mono text-[11px] font-semibold uppercase tracking-[0.12em] text-[var(--color-text-primary)]">
+    Difficulty
+  </legend>
+  <RadioGroup aria-labelledby="difficulty-label" aria-required="true" value={value} onValueChange={setValue} className="mt-2">
+    {['easy', 'moderate', 'hard'].map(option => (
+      <div key={option} className="flex items-center gap-2">
+        <Radio id={`difficulty-${option}`} value={option} invalid={Boolean(error)} />
+        <label htmlFor={`difficulty-${option}`} className="font-body text-sm">{option}</label>
+      </div>
+    ))}
+  </RadioGroup>
+  {error ? (
+    <p id="difficulty-error" className="mt-1.5 font-body text-sm text-[var(--color-accent-hostile-text)]">{error}</p>
+  ) : null}
+</fieldset>
+```
+
+FormField clones one control and gives it an id and a label; a group of radios has neither. The fieldset and legend name the group, the label styles match FormField, and the error is linked through aria-describedby. Give ErrorSummary the id of the first Radio so its link lands in the group.
+
+## Anatomy
+
+- **RadioGroup**: Has role=radiogroup, which tells assistive tech (screen readers and similar tools) this is a set of radios. It handles roving focus, where only one option is reachable by Tab and the arrows move between the rest, and it owns the value.
+- **Radio**: Has role=radio. A 20px (pixel) square inside a 24px hit area, the region that responds to a click or tap.
+- **Indicator**: A filled 10px square, not a dot. The system’s shape language has no circles.

package/public/docs/components/rating.md

@@ -0,0 +1,106 @@
+# Rating
+
+> A score out of five, either shown or collected. The display is one image that a screen reader reads as one sentence. The input is a radio group, because picking a rating means picking one value.
+
+- **Best for:** Showing or collecting a score out of five.
+- **Not for:** Anything that isn't a rating, such as a difficulty grade.
+- Molecule. Source: `src/components/molecules/rating/Rating.tsx`
+- Rendered docs page: `/components/rating`
+
+## Import
+
+```tsx
+import { Rating, RatingInput } from 'src/components/molecules/rating/Rating'
+```
+
+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 |
+|---|---|---|---|
+| `value (Rating)` | `number` |  | From 0 up to max, rounded to the nearest half for both the drawing and what screen readers say. |
+| `max (Rating)` | `number` | `5` | Number of stars. |
+| `label (Rating)` | `string` |  | What is being rated, read out as "<label> rated 4.5 out of 5". |
+| `showValue (Rating)` | `boolean` | `false` | Prints the rounded value beside the stars, aria-hidden. |
+| `size (Rating)` | `'sm' \| 'md'` | `'md'` | Star size. |
+| `className (Rating)` | `string` |  | Combined with the root classes. Where Tailwind utility classes clash, the later one wins. |
+| `ref (Rating)` | `Ref<HTMLSpanElement>` |  | Passed through to the root span. |
+| `label (RatingInput)` | `string` |  | Required. The radiogroup's name, for example "Rate the Prism holo sight". |
+| `value (RatingInput)` | `number` |  | The selected value, when your page holds it (controlled). |
+| `defaultValue (RatingInput)` | `number` |  | Starting value when the component holds it itself (uncontrolled). |
+| `onValueChange (RatingInput)` | `(value: number) => void` |  | Fires when a star is picked by click or arrow key. |
+| `max (RatingInput)` | `number` | `5` | Number of stars. |
+| `disabled (RatingInput)` | `boolean` |  | Disables every star. |
+| `className (RatingInput)` | `string` |  | Combined with the root classes. |
+| `ref (RatingInput)` | `Ref<HTMLDivElement>` |  | Passed through to the Radix radiogroup root. It's built straight on that, not on the Radio atom: see the anatomy row above. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Display
+
+```tsx
+<div className="flex flex-col gap-3">
+  <Rating value={4.5} label="Prism holo sight" showValue />
+  <Rating value={3} label="Bump helmet" showValue />
+  <Rating value={5} label="Field goggles" showValue />
+  <Rating value={0.5} label="Dummy radio" showValue />
+</div>
+```
+
+### Small, beside a price
+
+```tsx
+<div className="flex items-center gap-2">
+  <span className="font-display font-semibold">€128</span>
+  <Rating value={4} size="sm" label="Prism holo sight" />
+</div>
+```
+
+### Input
+
+```tsx
+function LiveInput() {
+  const [value, setValue] = useState(4)
+  return (
+    <div className="flex items-center gap-3">
+      <RatingInput label="Rate the Prism holo sight" value={value} onValueChange={setValue} />
+      <span className="font-mono text-xs text-[var(--color-text-secondary)]">
+        You rated it {value} {value === 1 ? 'star' : 'stars'}
+      </span>
+    </div>
+  )
+}
+
+<LiveInput />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves into the group, onto the selected star, or the first one. |
+| `←` `↑` `→` `↓` | One star less (Left or Up) or more (Right or Down), selecting as it goes. It wraps round: past the last star goes to the first, and past the first goes to the last. |
+| `Space` | Selects the focused star. |
+
+## Do
+
+- Name what is rated in the display's label when the surrounding page doesn't.
+- Show the number of reviews next to the stars: "4.5 (212)".
+- Label an input with the action: "Rate the Prism holo sight".
+
+## Don't
+
+- Don't use more than five stars.
+- Don't let hovering over a star select anything.
+- Don't use stars for anything that isn't a rating, such as a difficulty grade.
+
+## Anatomy
+
+- **Rating**: Has role=img and the name "4.5 out of 5", so a screen reader treats it as one picture. The stars are aria-hidden (screen readers skip them).
+- **Star**: Full, half or empty. Filled ones use the signal colour; empty ones are a border.selection outline.
+- **Value**: An optional printed number. It's aria-hidden because the name already says it.
+- **RatingInput**: A radiogroup named by label, built straight on Radix RadioGroup (Radix is the library of unstyled, accessible building blocks this system uses) instead of the Radio atom. Radio draws a 20px (pixel) square box with a filled inner square to show it's selected, and a star can't be drawn inside a square without either cropping it or leaving the box empty around it.
+- **Star option**: A 28px radio named "3 stars".

package/public/docs/components/score-ring.md

@@ -0,0 +1,95 @@
+# ScoreRing
+
+> One 0 to 100 score shown as a ring with the number in its centre, split into bands the way Lighthouse (Google’s website audit tool) bands its scores. It’s a meter, so a screen reader, the software that reads the page aloud, hears both the score and its band.
+
+- **Best for:** A 0 to 100 score with good and bad bands, like an audit, a health check or a quality score. Several side by side read as one report.
+- **Not for:** Progress through a task: use Progress. A number with a change over time: use Stat. Parts of a whole: use a donut ChartPanel.
+- Atom. Source: `src/components/atoms/score-ring/ScoreRing.tsx`
+- Rendered docs page: `/components/score-ring`
+
+## Import
+
+```tsx
+import { ScoreRing, scoreBand } from 'src/components/atoms/score-ring/ScoreRing'
+```
+
+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. What’s being scored. It’s both the accessible name and the caption. |
+| `value` | `number` |  | Required. 0 to 100, clamped and rounded to a whole number. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The ring is 56, 96 or 128px (pixels) wide. |
+| `className` | `string` |  | Merged with the meter’s classes. Later Tailwind utilities (Tailwind is the CSS framework the system uses) win. |
+| `ref` | `Ref<HTMLDivElement>` |  | Points to the meter. |
+| `...rest` | `Omit<HTMLAttributes<HTMLDivElement>, 'children'>` |  | Every native div prop except children, spread onto the meter. The ring draws its own content. |
+| `scoreBand()` | `(value: number) => 'hostile' \| 'warning' \| 'ok'` |  | The banding the ring uses. It’s exported so a table or a sentence beside the ring agrees with it. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type ScoreBand = 'hostile' | 'warning' | 'ok'
+```
+
+```ts
+/** Lighthouse's own bands, and its own words for them: 0-49 poor, 50-89 needs improvement, 90-100
+ *  good. Exported so a table or a summary sentence beside the rings can band a score the same way. */
+export function scoreBand(value: number): ScoreBand
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### A report like Lighthouse (Google's website audit tool): four scores in a row
+
+```tsx
+<ScoreRing label="Performance" value={42} />
+<ScoreRing label="Accessibility" value={98} />
+<ScoreRing label="Best practices" value={77} />
+<ScoreRing label="SEO" value={100} />
+```
+
+### Sizes: sm, md and lg
+
+```tsx
+<ScoreRing label="Stock health" value={64} size="sm" />
+<ScoreRing label="Stock health" value={64} />
+<ScoreRing label="Stock health" value={64} size="lg" />
+```
+
+### The band boundaries: 49, 50, 89 and 90
+
+```tsx
+<ScoreRing label="Depot A" value={49} size="sm" />
+<ScoreRing label="Depot B" value={50} size="sm" />
+<ScoreRing label="Depot C" value={89} size="sm" />
+<ScoreRing label="Depot D" value={90} size="sm" />
+```
+
+## Keyboard
+
+Not focusable. No keyboard behaviour of its own.
+
+## Do
+
+- Put several rings in a row for one report, like Lighthouse’s four scores.
+- Name what’s being scored in a word or two.
+- State the weakest score in the sentence beside the rings.
+
+## Don't
+
+- Don't use it for a value that isn't out of 100. Rescale it first, or use Stat.
+- Don't colour the number. The arc carries the band, and the number stays text.primary.
+
+## Anatomy
+
+- **Ring**: A hairline track plus an arc as long as the score, with square (butt) ends.
+- **Arc colour**: Set by band: hostile below 50, warning from 50 to 89, ok from 90. Colour is never the only signal, because the number is always printed.
+- **Ticks**: Three marks outside the ring at 0, 50 and 90. They mark the start and the two band boundaries.
+- **Number**: The score in display figures, centred in the ring.
+- **Label**: Mono (a monospaced font), uppercase, under the ring. It’s also the meter’s accessible name, the name assistive tech announces for it.

package/public/docs/components/search.md

@@ -0,0 +1,116 @@
+# Search
+
+> A search field inside a search landmark (a region of the page that screen readers can jump straight to). Enter submits, Escape clears, and a one-key shortcut can move focus to it from anywhere on the page.
+
+- **Best for:** Searching the content of the page that shows the results, inside a search landmark.
+- **Not for:** Suggestions that appear as you type, or jumping to an action: use CommandPalette.
+- Molecule. Source: `src/components/molecules/search/Search.tsx`
+- Rendered docs page: `/components/search`
+
+## Import
+
+```tsx
+import { Search } from 'src/components/molecules/search/Search'
+```
+
+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 name screen readers use for the field, and for the search landmark. |
+| `value` | `string` |  | The value, when your page holds it (controlled). |
+| `defaultValue` | `string` | `''` | Starting value when the component holds it itself (uncontrolled). |
+| `onValueChange` | `(value: string) => void` |  | Called whenever the value changes, clearing included. |
+| `onSearch` | `(query: string) => void` |  | Called on Enter with the value, spaces trimmed from both ends. It isn't called for an empty query. |
+| `placeholder` | `string` | `'Search'` |  |
+| `shortcut` | `string` |  | One printable key, for example "/". It moves focus to the field from anywhere on the page, except while someone is typing in another text field. While the field is empty, it shows as a Kbd hint. |
+| `inputSize` | `'sm' \| 'md' \| 'lg'` | `'md'` |  |
+| `className` | `string` |  | Combined with the root classes. Where Tailwind utility classes clash, the later one wins. |
+| `ref` | `Ref<HTMLInputElement>` |  | Passed through to the input element. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Default
+
+```tsx
+<div className="max-w-xs w-full">
+  <Search label="Search the catalogue" />
+</div>
+```
+
+### With a shortcut
+
+```tsx
+<div className="max-w-xs w-full">
+  <Search label="Search the manifest" shortcut="/" />
+  <p className="font-body text-xs text-[var(--color-text-secondary)] mt-3">
+    Press / anywhere on this page to focus it.
+  </p>
+</div>
+```
+
+### Submitting
+
+```tsx
+function SubmittingExample() {
+  const [result, setResult] = useState<string | null>(null)
+
+  return (
+    <div className="max-w-xs w-full">
+      <Search label="Search the depot list" onSearch={query => setResult(query)} />
+      <p className="font-body text-xs text-[var(--color-text-secondary)] mt-3">
+        {result ? `Searched for: ${result}` : 'Press Enter to search.'}
+      </p>
+    </div>
+  )
+}
+
+<SubmittingExample />
+```
+
+### Sizes
+
+```tsx
+<div className="max-w-xs w-full">
+  <Search label="Search, small" placeholder="Small" inputSize="sm" />
+</div>
+<div className="max-w-xs w-full">
+  <Search label="Search, medium" placeholder="Medium" inputSize="md" />
+</div>
+<div className="max-w-xs w-full">
+  <Search label="Search, large" placeholder="Large" inputSize="lg" />
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Enter` | Submits the query, spaces trimmed. |
+| `Escape` | Clears the field. |
+| `/` | Moves focus to the field, unless another text field has focus. It works for whichever key the shortcut prop names. |
+| `Tab` | Moves between the field and the clear button. |
+
+## Do
+
+- Name what's being searched: 'Search the catalogue', not 'Search'.
+- Pick a shortcut that isn't a letter people type in forms; '/' is the usual one.
+- Keep results on the page that owns the search, not in a popup under the field.
+
+## Don't
+
+- Don't add suggestions that appear as you type. That's the command palette's job, and it has a listbox built for it.
+- Don't search on every keystroke without saying so. Results that shift while someone types are hard to follow with a screen reader.
+- Don't put two search landmarks on one page without giving them different labels.
+
+## Anatomy
+
+- **Landmark**: A form with role=search, named by label, so people using a screen reader can jump to it.
+- **Icon**: Decoration only. It's aria-hidden, so screen readers skip it.
+- **Field**: An Input of type search. The browser's own clear button is hidden, because you can't reach it with the keyboard.
+- **Clear button**: Only shows while there's text. It puts focus back in the field.
+- **Shortcut hint**: A Kbd (the keyboard-key badge), aria-hidden, and only shown while the field is empty. Screen readers get the shortcut from aria-keyshortcuts on the field instead.