division-ds 0.1.1 → 0.2.0

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

@@ -0,0 +1,169 @@
+# 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.
+- 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'
+```
+
+## 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,99 @@
+# 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'
+```
+
+## 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.fill 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,149 @@
+# 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'
+```
+
+## 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".

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

@@ -0,0 +1,138 @@
+# 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'
+```
+
+## 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.