division-ds 0.1.2 → 0.2.0

package/public/docs/components/radio.md

@@ -0,0 +1,140 @@
+# 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'
+```
+
+## 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 with aria-label or a FormField legend.
+- 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.
+
+## 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,104 @@
+# 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'
+```
+
+## 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,93 @@
+# 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'
+```
+
+## 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,114 @@
+# 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'
+```
+
+## 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.

package/public/docs/components/section-heading.md

@@ -0,0 +1,111 @@
+# SectionHeading
+
+> The heading that opens a section of a page: a title under a hairline, with an optional description and an optional action. The page tells it which heading level to use, because only the page knows its own outline.
+
+- **Best for:** Opening a section of a page, at the level that carries on the outline.
+- **Not for:** The page title: use PageHeader.
+- Molecule. Source: `src/components/molecules/section-heading/SectionHeading.tsx`
+- Rendered docs page: `/components/section-heading`
+
+## Import
+
+```tsx
+import { SectionHeading } from 'src/components/molecules/section-heading/SectionHeading'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` |  | Required. The heading text. |
+| `level` | `2 \| 3 \| 4` |  | Required, with no default. The heading level the page outline needs at this point. Leave it out and the code won't compile. |
+| `description` | `ReactNode` |  | One or two sentences under the title. |
+| `action` | `ReactNode` |  | A single control at the end of the row, usually a link to the full list. |
+| `index` | `number` |  | The section's position in a numbered run of sections, drawn above the title. It's decoration and never part of the heading's name. |
+| `id` | `string` |  | Goes on the heading element, not the wrapper, so a section can point aria-labelledby at it (that's how the section gets its name for screen readers). |
+| `className` | `string` |  | Added to the root. Where Tailwind utility classes clash, the later one wins. |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed through to the root element. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Title only
+
+```tsx
+<SectionHeading level={4} title="Top-rated replicas" />
+```
+
+### With a description and an action
+
+```tsx
+<SectionHeading
+  level={4}
+  title="Top-rated accessories"
+  description="Optics and parts, ordered by what the reviews say."
+  action={<Link href="#accessories">All accessories</Link>}
+/>
+```
+
+### Numbered, in a run
+
+```tsx
+<div className="flex flex-col gap-10">
+  <SectionHeading level={4} index={1} title="Replicas" description="Three lengths on one receiver." />
+  <SectionHeading level={4} index={2} title="Optics" description="A tube sight and a holo sight." />
+  <SectionHeading
+    level={4}
+    index={3}
+    title="Parts and accessories"
+    action={
+      <Button asChild variant="secondary" size="sm">
+        <a href="#parts">All parts</a>
+      </Button>
+    }
+  />
+</div>
+```
+
+### Naming its section
+
+```tsx
+<section aria-labelledby="section-heading-docs-care">
+  <SectionHeading
+    level={4}
+    id="section-heading-docs-care"
+    title="Care plans"
+    description="The section below is a region named “Care plans”. It takes that name from this heading, which carries the id."
+  />
+  <p className="mt-4 font-body text-sm text-[var(--color-text-primary)]">
+    A chrono check, a tune and upgrade fitting, billed monthly.
+  </p>
+</section>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves to the action, if there is one. The heading itself isn't a Tab stop. |
+
+## Do
+
+- Pass the level that carries on the page outline: h2 under the page h1, h3 inside an h2 section.
+- Give the heading an id and point the section at it with aria-labelledby, so the region has a name.
+- Name the action after where it goes: "All replicas", not "View all" four times on one page.
+- Number every section in a run, or none of them.
+
+## Don't
+
+- Don't use it as the page title. A page has one h1, and that isn't a section opener.
+- Don't pick a level for its size. The size is the same at every level; the level is about the outline.
+- Don't put more than one control in the action slot. A second one belongs in the section body.
+- Don't stack one straight under another. A section heading opens content, not a second heading.
+
+## Anatomy
+
+- **Rule**: A hairline along the top, in border.hairline-strong. It marks where the section starts.
+- **Index**: Optional. A two-digit number in monospace type, on its own line above the title, and aria-hidden so screen readers skip it. The leading zero is in numeral.pad and the digit in accent.signal.text. It sits above the title, not in front, so the title keeps the same left edge as its description and its section.
+- **Title**: The heading element, h2 to h4 (heading levels 2 to 4). Oxanium, uppercase, 20px (pixels), going up to 24px when the heading has 42rem or more of width.
+- **Description**: Optional. Body text in text.secondary, at most 60 characters a line.
+- **Action**: Optional. One control at the far end of the row. It drops under the text when there isn't room.