division-ds 0.1.2 → 0.2.1

package/public/docs/components/stat.md

@@ -0,0 +1,106 @@
+# Stat
+
+> One number that matters, and how it has moved. The number is the star of the show. The label is small, set in a monospaced font and kept quiet.
+
+- **Best for:** One headline number and how it has moved. Up to four in a row.
+- **Not for:** A value that only makes sense as a chart: use ChartPanel.
+- Molecule. Source: `src/components/molecules/stat/Stat.tsx`
+- Rendered docs page: `/components/stat`
+
+## Import
+
+```tsx
+import { Stat } from 'src/components/molecules/stat/Stat'
+```
+
+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` |  | The stat's name, for example "Kits dispatched". |
+| `value` | `number \| string` |  | Whole numbers get padded. Anything else (for example "4.2k") is shown exactly as given. |
+| `unit` | `string` |  | Shown beside the value, for example "kg". |
+| `padTo` | `number` |  | Pads a whole-number value to this many digits with dimmed zeros that screen readers skip (aria-hidden). |
+| `delta` | `{ value: string; direction: 'up' \| 'down'; sentiment: 'positive' \| 'negative' \| 'neutral'; period: string }` |  | value comes already formatted (for example "12%"). direction picks the arrow. sentiment picks the colour, and it doesn't depend on direction: fewer failed syncs is down, and that's positive. period is what the number is compared with, for example "last week". It's both shown and spoken. |
+| `className` | `string` |  | Merged with the root classes. If two Tailwind utilities clash, the later one wins. |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed through to the root div. |
+| `...rest` | `HTMLAttributes<HTMLDivElement>` |  | Any standard div attribute, applied to the root div. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type StatDelta = {
+  /** Already formatted, e.g. "12%". */
+  value: string
+  direction: 'up' | 'down'
+  /** Whether this movement is good. Independent of direction: fewer failed syncs is down AND good. */
+  sentiment: 'positive' | 'negative' | 'neutral'
+  /** What it is compared with, e.g. "last week". Spoken and shown. */
+  period: string
+}
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### A row of stats
+
+```tsx
+<div className="grid grid-cols-2 sm:grid-cols-4 gap-6 w-full">
+  <Stat
+    label="Kits dispatched"
+    value={18}
+    padTo={3}
+    delta={{ value: '12%', direction: 'up', sentiment: 'positive', period: 'last week' }}
+  />
+  <Stat
+    label="Failed syncs"
+    value={3}
+    delta={{ value: '40%', direction: 'down', sentiment: 'positive', period: 'last week' }}
+  />
+  <Stat
+    label="Depots offline"
+    value={2}
+    delta={{ value: '1', direction: 'up', sentiment: 'negative', period: 'last week' }}
+  />
+  <Stat label="Payload" value={24} unit="kg" />
+</div>
+```
+
+### Without a delta
+
+```tsx
+<div className="max-w-[10rem] w-full">
+  <Stat label="Kits dispatched" value={18} padTo={3} />
+</div>
+```
+
+## Keyboard
+
+Not focusable. No keyboard behaviour of its own.
+
+## Do
+
+- Lay several Stats out in a plain div grid. Each one renders its own dl (description list), so you don't need a list element around them.
+- Set sentiment by what the change means, not by its direction: fewer failed syncs is down, and that's positive.
+- Say what the delta is compared with.
+- Only pad when every value in a row has the same fixed width.
+
+## Don't
+
+- Don't pad a value whose width isn't fixed. The zeros would be made up.
+- Don't put more than four stats in a row.
+- Don't use a Stat for a value that only makes sense as a chart.
+
+## Anatomy
+
+- **Label**: A dt (the "term" element of an HTML description list), in text.secondary.
+- **Value**: A dd (the matching "description" element) at 36px (pixels), set in Oxanium with tabular figures, so every digit is the same width.
+- **Pad**: Optional leading zeros in numeral.pad. They're aria-hidden, so screen readers skip them, and they only appear when the width is real.
+- **Unit**: A short suffix beside the value, for example kg.
+- **Delta**: The change. An arrow shows the direction, colour shows whether it's good or bad, and a spoken sentence says both for screen reader users.

package/public/docs/components/status-tracker.md

@@ -0,0 +1,145 @@
+# StatusTracker
+
+> Health over time, drawn as a row of thin bars with one bar per period. The oldest is on the left. Each bar says its status in words and shows them in a tooltip when you hover over it or reach it with the keyboard. The whole row is a single Tab stop, and the arrow keys move along it.
+
+- **Best for:** The health history of one service or device, such as uptime over 30 or 90 days.
+- **Not for:** A current status: use Badge. A measured value: use Sparkline.
+- Molecule. Source: `src/components/molecules/status-tracker/StatusTracker.tsx`
+- Rendered docs page: `/components/status-tracker`
+
+## Import
+
+```tsx
+import { StatusTracker, statusTrackerText } from 'src/components/molecules/status-tracker/StatusTracker'
+```
+
+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
+
+- The root TooltipProvider (AppShell and DemoLayout mount it).
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | Required. Names the row, for example "Uptime, last 30 days". |
+| `items` | `readonly StatusTrackerItem[]` |  | Required. Oldest first. |
+| `summary` | `ReactNode` |  | Shown on the right of the label row, for example "99.2% up". |
+| `statusLabels` | `Partial<Record<StatusTrackerStatus, string>>` |  | Replaces the status words: Operational, Degraded, Down, No data. |
+| `className` | `string` |  | Added to the root. |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed through to the root. |
+| `id (StatusTrackerItem)` | `string` |  | Required. A key that never changes for that item. |
+| `status (StatusTrackerItem)` | `'ok' \| 'warning' \| 'hostile' \| 'neutral'` |  | Required. ok means up. warning means degraded. hostile means down or failed. neutral means no data. |
+| `label (StatusTrackerItem)` | `string` |  | Required. The period and what happened, for example "12 Oct: 2 alerts, 14 min degraded". |
+| `statusTrackerText()` | `(item, words?) => string` |  | Builds the text a bar uses for its name and tooltip, for example "Degraded. 12 Oct: 2 alerts". |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type StatusTrackerStatus = 'ok' | 'warning' | 'hostile' | 'neutral'
+```
+
+```ts
+export type StatusTrackerItem = {
+  /** Stable key. */
+  id: string
+  /** ok up or healthy; warning degraded; hostile down or failed; neutral no data. */
+  status: StatusTrackerStatus
+  /** The period and what happened in it: "12 Oct: 2 alerts, 14 min degraded". */
+  label: string
+}
+```
+
+```ts
+/** Text of one bar: the status word first, then the caller's label. Shared by the accessible name
+ *  and the tooltip, so what is heard and what is seen are the same sentence. */
+export function statusTrackerText(item: StatusTrackerItem, words: Record<StatusTrackerStatus, string> = STATUS_WORDS)
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Thirty days, with a summary
+
+```tsx
+const THIRTY: StatusTrackerItem[] = Array.from({ length: 30 }, (_, index) => {
+  const day = new Date(Date.UTC(2026, 8, 16 + index))
+  const date = day.toLocaleDateString('en-GB', { day: 'numeric', month: 'short', timeZone: 'UTC' })
+  if (index === 8) return { id: `d${index}`, status: 'warning', label: `${date}: 2 alerts, 14 min degraded` }
+  if (index === 19) return { id: `d${index}`, status: 'hostile', label: `${date}: 41 min down` }
+  if (index === 23) return { id: `d${index}`, status: 'warning', label: `${date}: 1 alert, 6 min degraded` }
+  if (index === 26) return { id: `d${index}`, status: 'neutral', label: `${date}: no readings` }
+  return { id: `d${index}`, status: 'ok', label: `${date}: no alerts` }
+})
+
+<div className="w-full max-w-xl">
+  <StatusTracker label="Uptime, last 30 days" summary="99.2% up" items={THIRTY} />
+</div>
+```
+
+### Ninety days in the same width
+
+```tsx
+const NINETY: StatusTrackerItem[] = Array.from({ length: 90 }, (_, index) => ({
+  id: `n${index}`,
+  status: index % 37 === 12 ? 'hostile' : index % 23 === 5 ? 'warning' : 'ok',
+  label: `Day ${index + 1} of 90`,
+}))
+
+<div className="w-full max-w-xl">
+  <StatusTracker label="Uptime, last 90 days" summary="99.6% up" items={NINETY} />
+</div>
+```
+
+### Other status words
+
+```tsx
+<div className="w-full max-w-xs">
+  <StatusTracker
+    label="Door sensor, last 8 hours"
+    statusLabels={{ ok: 'Closed', warning: 'Left open', hostile: 'Forced', neutral: 'Offline' }}
+    items={[
+      { id: 'h1', status: 'ok', label: '02:00 to 03:00' },
+      { id: 'h2', status: 'ok', label: '03:00 to 04:00' },
+      { id: 'h3', status: 'warning', label: '04:00 to 05:00, open 9 min' },
+      { id: 'h4', status: 'ok', label: '05:00 to 06:00' },
+      { id: 'h5', status: 'neutral', label: '06:00 to 07:00' },
+      { id: 'h6', status: 'ok', label: '07:00 to 08:00' },
+      { id: 'h7', status: 'ok', label: '08:00 to 09:00' },
+      { id: 'h8', status: 'ok', label: '09:00 to 10:00' },
+    ]}
+  />
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves into the row, landing on the last bar that had focus (the newest one the first time), and moves out again. |
+| `ArrowLeft` `ArrowRight` | Moves one bar older or newer and shows its tooltip. |
+| `Home` `End` | Jumps to the oldest or the newest bar. |
+| `Escape` | Hides the tooltip. Focus stays on the bar. |
+
+## Do
+
+- Write each item label with its period and what happened, not just the status. The status word is added for you.
+- Put the headline figure in summary, so the row has a number people can read before they explore it.
+- Use neutral for periods with no data, so a gap looks like a gap and not like a healthy day.
+
+## Don't
+
+- Don't start an item label with the status word as well. It's already said first.
+- Don't use it for more than about 90 bars. At a 320px-wide screen the bars get thinner than 2px.
+- Don't make a bar do anything when clicked. It's a reading, not a control.
+
+## Anatomy
+
+- **Label row**: The label in a monospaced font on the left, and the optional summary on the right.
+- **List**: A ul (bulleted list element) named by the label, with one li (list item) per bar, so a screen reader hears how many bars there are and where each one sits.
+- **Bar**: A block 32px (pixels) tall in the status colour. It has role="img" and aria-roledescription="status bar", which tell screen readers what it is, and its name is the status word plus the label.
+- **Tooltip**: The same text as the name, shown on hover and on keyboard focus.

package/public/docs/components/stepper.md

@@ -0,0 +1,147 @@
+# Stepper
+
+> Shows where someone is in a flow of several steps. Finished steps get a check mark, the current one is filled with the signal colour, and the rest wait as outlines.
+
+- **Best for:** Showing where someone is in a flow of two to five steps.
+- **Not for:** Sections that are equally important: use Tabs. Also not for a single step.
+- Molecule. Source: `src/components/molecules/stepper/Stepper.tsx`
+- Rendered docs page: `/components/stepper`
+
+## Import
+
+```tsx
+import { Stepper } from 'src/components/molecules/stepper/Stepper'
+```
+
+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 |
+|---|---|---|---|
+| `steps` | `Step[]` |  | Required. { label: string; description?: string }. |
+| `current` | `number` |  | Counts from 0. steps.length means every step is complete. |
+| `label` | `string` | `'Progress'` | The list's accessible name, the name screen readers announce. |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Horizontal runs in a row from sm up and stacks below it. Vertical is a column at every width, with connectors. |
+| `className` | `string` |  | Merged with the root classes. If two Tailwind utilities clash, the later one wins. |
+| `ref` | `Ref<HTMLOListElement>` |  | Passed through to the root ol. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type Step = { label: string; description?: string }
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Checkout
+
+```tsx
+const CHECKOUT_STEPS: Step[] = [
+  { label: 'Shipping' },
+  { label: 'Payment' },
+  { label: 'Review', description: 'Check the manifest' },
+]
+
+<div className="w-full">
+  <Stepper steps={CHECKOUT_STEPS} current={1} label="Checkout progress" />
+</div>
+```
+
+### Complete
+
+```tsx
+const CHECKOUT_STEPS: Step[] = [
+  { label: 'Shipping' },
+  { label: 'Payment' },
+  { label: 'Review', description: 'Check the manifest' },
+]
+
+<div className="w-full">
+  <Stepper steps={CHECKOUT_STEPS} current={3} label="Checkout progress" />
+</div>
+```
+
+### Vertical, with descriptions
+
+```tsx
+const SHIPMENT_STEPS: Step[] = [
+  { label: 'Ordered', description: 'Paid on 12 October' },
+  { label: 'Packed', description: 'At the Brasov depot' },
+  { label: 'Shipped', description: 'With the courier' },
+  { label: 'Delivered' },
+]
+
+<div className="w-full max-w-xs">
+  <Stepper steps={SHIPMENT_STEPS} current={2} orientation="vertical" label="Shipment progress" />
+</div>
+```
+
+### Live: move through the steps with Back and Continue
+
+```tsx
+const CHECKOUT_STEPS: Step[] = [
+  { label: 'Shipping' },
+  { label: 'Payment' },
+  { label: 'Review', description: 'Check the manifest' },
+]
+
+function LiveStepper() {
+  const [current, setCurrent] = useState(0)
+  return (
+    <div className="flex flex-col gap-6 w-full">
+      <Stepper steps={CHECKOUT_STEPS} current={current} label="Checkout progress" />
+      <div className="flex gap-3">
+        <Button
+          variant="secondary"
+          size="sm"
+          disabled={current === 0}
+          onClick={() => setCurrent(c => Math.max(0, c - 1))}
+        >
+          Back
+        </Button>
+        <Button
+          size="sm"
+          disabled={current >= CHECKOUT_STEPS.length}
+          onClick={() => setCurrent(c => Math.min(CHECKOUT_STEPS.length, c + 1))}
+        >
+          Continue
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+<LiveStepper />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+|  | Not interactive. Put Back and Continue buttons in the flow itself. |
+
+## Do
+
+- Keep it to five steps or fewer.
+- Name steps for what happens in them: 'Shipping', not 'Step 1'.
+- Label the list after the flow: 'Checkout progress'.
+- Use vertical beside other content, or when steps have descriptions, like a shipment on an order page.
+
+## Don't
+
+- Don't make steps clickable so people can skip ahead.
+- Don't use a Stepper for equally important sections. That's what Tabs is for.
+- Don't show a Stepper for a single step.
+
+## Anatomy
+
+- **List**: An ol (numbered list element) named by label.
+- **Marker**: A 28px (pixel) square. Done: signal fill with a check. Current: signal fill with its number, without leading zeros, because dimmed zeros can't keep enough contrast against the fill. Upcoming: an outline with the two-digit number, leading zero included.
+- **Connector**: A 2px line that turns the signal colour once the step before it is done. Horizontal: hidden when the steps stack, below the sm breakpoint (the small-screen width). Vertical: always shown, running down between the markers.
+- **Label**: In a monospaced font, with its status spelled out in words for screen readers.
+- **Description**: Optional, under the label. The vertical layout gives it the most room.

package/public/docs/components/switch.md

@@ -0,0 +1,153 @@
+# Switch
+
+> An on/off control that acts right away. The thumb's position shows the state, so the meaning still comes through with colour turned off. It takes effect the moment it's flipped.
+
+- **Best for:** An on/off setting that takes effect the moment it's flipped.
+- **Not for:** A choice in a form that needs a Save. Use Checkbox.
+- Atom. Source: `src/components/atoms/switch/Switch.tsx`
+- Rendered docs page: `/components/switch`
+
+## Import
+
+```tsx
+import { Switch } from 'src/components/atoms/switch/Switch'
+```
+
+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
+
+- Its own label. A Switch isn't a FormField child (FormField takes Input, Textarea, Select or QuantityStepper). Give it an id and put a <label htmlFor> beside it.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `checked` | `boolean` |  | The checked state, when your code controls it. |
+| `defaultChecked` | `boolean` |  | The starting state, when the switch manages itself. |
+| `onCheckedChange` | `(checked: boolean) => void` |  | Fires the moment it's flipped. |
+| `disabled` | `boolean` |  | Takes it out of the tab order and blocks toggling. |
+| `required` | `boolean` |  | The browser's own form validation. |
+| `name` | `string` |  | The browser's own form field name. |
+| `value` | `string` |  | The browser's own form field value. |
+| `id` | `string` |  | Pair it with a real label through htmlFor. |
+| `className` | `string` |  | Merged with the control's classes. Later Tailwind utilities (the small styling classes this system uses) win. |
+| `ref` | `Ref<HTMLButtonElement>` |  | Forwarded to the root button from Radix, the open-source library this switch is built on. |
+| `...rest` | `ButtonHTMLAttributes<HTMLButtonElement>` |  | Every other Radix Switch.Root prop, which means every native button attribute, spread onto the root button. For example aria-describedby, or aria-label when no label element points at it. aria-* attributes are ARIA (Accessible Rich Internet Applications) settings that give screen readers extra information. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Off and on
+
+```tsx
+<div className="flex items-center gap-3">
+  <Switch id="state-off" />
+  <label htmlFor="state-off">Off</label>
+</div>
+<div className="flex items-center gap-3">
+  <Switch id="state-on" defaultChecked />
+  <label htmlFor="state-on">On</label>
+</div>
+```
+
+### Live
+
+```tsx
+function LiveExample() {
+  const [on, setOn] = useState(false)
+  return (
+    <div className="flex items-center gap-4">
+      <div className="flex items-center gap-3">
+        <Switch id="live-beacon" checked={on} onCheckedChange={setOn} />
+        <label htmlFor="live-beacon">Field beacon</label>
+      </div>
+      <p className="text-sm text-[var(--color-text-secondary)]">
+        {on ? 'Broadcasting position.' : 'Beacon is off.'}
+      </p>
+    </div>
+  )
+}
+
+<LiveExample />
+```
+
+### Disabled
+
+```tsx
+<div className="flex items-center gap-3">
+  <Switch id="state-disabled-off" disabled />
+  <label htmlFor="state-disabled-off">Disabled, off</label>
+</div>
+<div className="flex items-center gap-3">
+  <Switch id="state-disabled-on" disabled defaultChecked />
+  <label htmlFor="state-disabled-on">Disabled, on</label>
+</div>
+```
+
+### A settings row
+
+```tsx
+<div className="flex w-full items-start justify-between gap-4">
+  <div>
+    <label htmlFor="settings-offline-maps" className="font-medium">
+      Offline maps
+    </label>
+    <p className="text-sm text-[var(--color-text-secondary)]">
+      Download the current route area before you lose signal.
+    </p>
+  </div>
+  <Switch id="settings-offline-maps" defaultChecked />
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves focus to it. |
+| `Space` | Toggles it. |
+| `Enter` | Toggles it. Radix allows this on a switch, though not on a checkbox. |
+
+## Do
+
+- Use it only when flipping it takes effect right away.
+- Label it with the thing being switched, not with ‘on’ or ‘off’.
+- Show the result of the switch near it if the effect isn't visible.
+
+## Don't
+
+- Don't put a switch in a form that needs a Save. Use a Checkbox.
+- Don't put ‘on’/‘off’ text inside the track. The position already says it, and the text won't fit at 24px.
+- Don't make the thumb take longer than --duration-base (a timing token) to arrive. A slow switch feels broken. The settle after it arrives only changes its shape, and it ends within --duration-slow, because the state is already readable.
+- Don't use the squash on anything that isn't a small physical object under the user's finger. On a panel or a page it looks like a wobble.
+- Don't add a rebound to the thumb. It gives once against the edge and stops. A switch that keeps moving after the state has landed looks unsure.
+- Don't fill the track with the accent when it's on. Thumb and track changing colour together, mid-flight, is what made the flip look like a twitch.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<FormField label="Email notifications">
+  <Switch />
+</FormField>
+```
+
+Right:
+
+```tsx
+<div className="flex items-center gap-3">
+  <Switch id="notify" checked={on} onCheckedChange={setOn} />
+  <label htmlFor="notify">Email notifications</label>
+</div>
+```
+
+FormField passes its child an invalid prop, and Switch doesn't take one. A switch acts at once, so it has no error state to show.
+
+## Anatomy
+
+- **Root**: role=switch, which tells screen readers (software that reads the page aloud) what it is. A 44×24 track.
+- **Thumb**: A 16px (pixel) square, 3px from the track edge in both states, travelling 22px. Its position is the state signal. It's text.primary when off and accent.signal.indicator when on. Held down, it stretches 4px away from the edge it rests on: to the right when off, to the left when on, so it never leaves the track. Flipped, it speeds up across the track, gets a little longer in flight and a little shorter against the far edge, then goes back to its own shape. One give, no bounce.
+- **Track fill**: The control fill, on and off. When it's on, only the border turns to accent.signal.indicator. The track doesn't fill with the accent, so the thumb is the one thing that changes colour during a flip.