division-ds 0.1.2 → 0.2.1

package/public/docs/components/kbd.md

@@ -0,0 +1,72 @@
+# Kbd
+
+> A small keycap that shows a key's name. Making shortcuts easy to find was one of the motifs from the G1 mood board (the project's first approval step) worth keeping: if a surface has a shortcut, the surface says so.
+
+- **Best for:** Showing a keyboard shortcut next to the action it triggers, with one Kbd per key.
+- **Not for:** Anything that isn't a key, such as a status: use Badge.
+- Atom. Source: `src/components/atoms/kbd/Kbd.tsx`
+- Rendered docs page: `/components/kbd`
+
+## Import
+
+```tsx
+import { Kbd } from 'src/components/atoms/kbd/Kbd'
+```
+
+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 |
+|---|---|---|---|
+| `children` | `ReactNode` |  | The key's name, for example "Esc" or "⌘". |
+| `className` | `string` |  | Merged with the component's classes. When Tailwind utility classes clash, the later one wins. |
+| `ref` | `Ref<HTMLElement>` |  | Passed through to the kbd element. |
+| `...rest` | `HTMLAttributes<HTMLElement>` |  | Every native attribute, passed onto the kbd element, such as a title, or an aria-label for a symbol key (aria-label is the name screen readers read out). |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Single keys
+
+```tsx
+<Kbd>Esc</Kbd>
+<Kbd>Tab</Kbd>
+<Kbd>Enter</Kbd>
+<Kbd>Space</Kbd>
+<Kbd>/</Kbd>
+```
+
+### A chord: one cap per key
+
+```tsx
+<span className="flex items-center gap-1">
+  <Kbd>Ctrl</Kbd>
+  <span className="text-[var(--color-text-muted)] text-sm">+</span>
+  <Kbd>K</Kbd>
+</span>
+<span className="text-sm text-[var(--color-text-secondary)]">Open the command palette</span>
+```
+
+## Keyboard
+
+Not focusable. No keyboard behaviour of its own.
+
+## Do
+
+- Use one Kbd per physical key, and put them side by side for a chord (keys pressed together).
+- Put it next to the action it triggers, in the same row or the same tooltip.
+- Write the key name the way the keyboard prints it.
+
+## Don't
+
+- Don’t bevel it. Cut corners are for surfaces and controls, not 24px chrome.
+- Don’t put a whole chord inside one Kbd ("Ctrl+K" in a single cap).
+- Don’t use it for anything that isn’t a key. It’s not a badge.
+
+## Anatomy
+
+- **kbd element**: The HTML element made for keys. Screen readers announce it as keyboard input.
+- **Hairline border**: A one-pixel border in border.hairline-strong, with no bevel (cut corners).
+- **Mono legend**: JetBrains Mono, uppercase, 11px (pixels): the tertiary type role.

package/public/docs/components/link.md

@@ -0,0 +1,98 @@
+# Link
+
+> A link inside text. It's underlined, because in a paragraph colour alone isn't enough to show that something is a link.
+
+- **Best for:** Text that takes you somewhere: another page, a section or another site.
+- **Not for:** Something that does an action. Use Button for that (its link variant if it's inside running text).
+- Atom. Source: `src/components/atoms/link/Link.tsx`
+- Rendered docs page: `/components/link`
+
+## Import
+
+```tsx
+import { Link, linkVariants } from 'src/components/atoms/link/Link'
+```
+
+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 |
+|---|---|---|---|
+| `tone` | `'signal' \| 'quiet'` | `'signal'` | Which colour treatment to use. |
+| `external` | `boolean` | `false` | Opens the link in a new tab. It adds target="_blank", the rel hardening (attributes that stop the new page reaching back into yours), a trailing icon and the hidden "(opens in a new tab)" warning. Using it together with target or rel is a type error, so it can't fail silently. external already sets those values, so those props are removed from the type instead of being quietly overwritten while the page runs. |
+| `href` | `string` |  | Where the link goes. |
+| `className` | `string` |  | Merged with the component classes. If two clash, the later Tailwind utility wins (Tailwind is the CSS framework this system styles with). |
+| `ref` | `Ref<HTMLAnchorElement>` |  | Passed through to the anchor element. |
+| `...rest` | `AnchorHTMLAttributes<HTMLAnchorElement>` |  | Every native anchor prop. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export const linkVariants = cva( …
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### In running text
+
+```tsx
+<p className="text-sm text-[var(--color-text-secondary)] max-w-md">
+  Check the <Link href="/kits">field kit index</Link> before you head out, and read the{' '}
+  <Link href="https://example.com" external tone="quiet">
+    supplier notes
+  </Link>{' '}
+  if the hop-up looks off.
+</p>
+```
+
+### Tones
+
+```tsx
+<Link href="/kits" tone="signal">
+  Field kits
+</Link>
+<Link href="/kits" tone="quiet">
+  Field kits
+</Link>
+```
+
+### External
+
+```tsx
+<Link href="https://example.com" external>
+  Supplier
+</Link>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves focus to it. The focus ring (the outline that shows which element the keyboard is on) is drawn on the link itself, and nothing clips it here. |
+| `Enter` | Follows the link. |
+
+## Do
+
+- Keep the underline on links inside running text.
+- Put the destination in the link text: 'the field kit index', not 'click here'.
+- Set external on anything that leaves the app, so screen readers announce the new tab.
+- Use quiet in dense lists where every row is a link anyway.
+
+## Don't
+
+- Don't use a link for something that does an action. That's a Button.
+- Don't open a new tab without external. The rel hardening and the warning both come with it.
+- Don't remove the underline to make a paragraph look tidier.
+- Don't pass target or rel together with external. Those props are removed from the type, so you can't override them. If you need different values, render a plain anchor yourself.
+
+## Anatomy
+
+- **Anchor**: The browser's own <a> element. You can focus it and use it from the keyboard without any extra work.
+- **Underline**: 1px (pixel) thick, sitting 2px below the text. It gets thicker on hover in the signal tone.
+- **External icon**: Hidden from screen readers with aria-hidden (an ARIA attribute, from Accessible Rich Internet Applications). It only shows when external is set.
+- **Hidden warning**: ‘(opens in a new tab)’, added to the accessible name, which is what screen readers announce for the link.

package/public/docs/components/list-item.md

@@ -0,0 +1,241 @@
+# ListItem
+
+> One row of a list: something at the start (a picture or icon), a title and description, extra details on the right, and actions at the end. A row that goes somewhere is one real link or button stretched over the whole row. Its actions sit beside it, never inside it.
+
+- **Best for:** A row people scan in a List: media, a title, meta and one or two actions.
+- **Not for:** Data in a table that people compare across columns: use DataTable.
+- **Also on this page:** `List`
+- Molecule. Source: `src/components/molecules/list-item/ListItem.tsx`
+- Rendered docs page: `/components/list-item`
+
+## Import
+
+```tsx
+import { List, ListItem } from 'src/components/molecules/list-item/ListItem'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Requires
+
+- A <List> around the rows (a ul with role="list"), or as="div" on a row that stands alone.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `ReactNode` |  | Required. The main line, and the name screen readers give the row’s link or button. |
+| `description` | `ReactNode` |  | A second line under the title, in secondary text. |
+| `media` | `ReactNode` |  | Something at the start of the row: an Avatar, an icon (hidden from screen readers with aria-hidden), a thumbnail. |
+| `meta` | `ReactNode` |  | Right-aligned monospaced text: a time, a price, a count. |
+| `actions` | `ReactNode` |  | Controls at the end. Each one can still be focused and clicked on its own. |
+| `href` | `string` |  | Makes the row one link to this address, named by the title. |
+| `renderLink` | `(props: LinkRenderProps) => ReactNode` | `a plain <a>` | Draws the row link when href is set. Pass your router's link here. It has to pass className through. |
+| `onActivate` | `() => void` |  | Makes the row one button, named by the title. Ignored when href is set. |
+| `as` | `'li' \| 'div'` | `'li'` | li inside a List. div for a row on its own. |
+| `dividers (List)` | `boolean` | `true` | A thin line between rows. |
+| `className` | `string` |  | Extra CSS classes, merged with the outer element's own classes on List or ListItem. |
+| `ref` | `Ref<HTMLElement>` |  | Passed through to the ul (List) or the row element (ListItem). |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Sessions: plain rows with one action each
+
+```tsx
+function DeviceIcon({ icon: Icon }: { icon: typeof Monitor }) {
+  return (
+    <span className="flex size-9 items-center justify-center border border-[var(--color-border-hairline-strong)] text-[var(--color-text-secondary)]">
+      <Icon aria-hidden="true" className="size-4" />
+    </span>
+  )
+}
+
+function SessionsExample() {
+  const [sessions, setSessions] = useState([
+    { id: 'win', device: 'Chrome on Windows', where: 'Brasov, Romania', when: 'Now', icon: Monitor },
+    { id: 'ios', device: 'Safari on iPhone', where: 'Brasov, Romania', when: '2 h ago', icon: Smartphone },
+    { id: 'tab', device: 'Firefox on Android tablet', where: 'Cluj-Napoca, Romania', when: '3 d ago', icon: Tablet },
+  ])
+  return (
+    <div className="w-full max-w-xl">
+      <List aria-label="Signed-in sessions">
+        {sessions.map(session => (
+          <ListItem
+            key={session.id}
+            media={<DeviceIcon icon={session.icon} />}
+            title={session.device}
+            description={session.where}
+            meta={session.when}
+            actions={
+              session.id === 'win' ? (
+                <Badge tone="ok">This device</Badge>
+              ) : (
+                <Button
+                  size="sm"
+                  variant="secondary"
+                  aria-label={`Sign out of ${session.device}`}
+                  onClick={() => setSessions(all => all.filter(s => s.id !== session.id))}
+                >
+                  Sign out
+                </Button>
+              )
+            }
+          />
+        ))}
+      </List>
+    </div>
+  )
+}
+
+<SessionsExample />
+```
+
+### Notifications: each row one link, with an archive action beside it
+
+```tsx
+<div className="w-full max-w-xl">
+  <List aria-label="Notifications">
+    <ListItem
+      className="px-2"
+      title="Order 1042 shipped"
+      description="Your carbine replica left the depot."
+      meta="09:14"
+      href="#order-1042"
+      actions={
+        <IconButton label="Archive: Order 1042 shipped" variant="ghost" size="sm">
+          <Archive />
+        </IconButton>
+      }
+    />
+    <ListItem
+      className="px-2"
+      title="Back in stock"
+      description="The holo sight on your wishlist is available again."
+      meta="Yesterday"
+      href="#wishlist"
+      actions={
+        <IconButton label="Archive: Back in stock" variant="ghost" size="sm">
+          <Archive />
+        </IconButton>
+      }
+    />
+    <ListItem
+      className="px-2"
+      title="Training moved"
+      description="Saturday’s training starts at 10:00, not 09:00."
+      meta="Mon"
+      href="#events"
+      actions={
+        <IconButton label="Archive: Training moved" variant="ghost" size="sm">
+          <Archive />
+        </IconButton>
+      }
+    />
+  </List>
+</div>
+```
+
+### Team members: avatars, the whole row a button
+
+```tsx
+function TeamExample() {
+  const [chosen, setChosen] = useState<string | null>(null)
+  const team = [
+    { name: 'Ilse Varga', email: 'ilse@hexline.example', role: 'Captain' },
+    { name: 'Tomas Reyes', email: 'tomas@hexline.example', role: 'Medic' },
+    { name: 'Ana Popescu', email: 'ana@hexline.example', role: 'Scout' },
+  ]
+  return (
+    <div className="w-full max-w-xl">
+      <List aria-label="Squad members">
+        {team.map(member => (
+          <ListItem
+            key={member.email}
+            className="px-2"
+            media={<Avatar name={member.name} />}
+            title={member.name}
+            description={member.email}
+            meta={member.role}
+            onActivate={() => setChosen(member.name)}
+          />
+        ))}
+      </List>
+      <p className="mt-3 text-sm text-[var(--color-text-secondary)]" aria-live="polite">
+        {chosen ? `Opened ${chosen}.` : 'Choose a member to open their profile.'}
+      </p>
+    </div>
+  )
+}
+
+<TeamExample />
+```
+
+### A standalone row, outside a List
+
+```tsx
+<div className="w-full max-w-xl">
+  <ListItem as="div" title="Spare magazine, 120 rounds" description="Mid-cap, steel" meta="€14.90" />
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves to the row’s link or button, then to each of its actions, then to the next row. |
+| `Enter` | Follows the row’s link, or presses its button. |
+| `Space` | Presses the row’s button (a link row ignores Space, like any link). |
+
+## Do
+
+- Put rows in a List, and give the List an aria-label (a name only screen readers hear) when no heading names it.
+- Use href when the row opens a page, and onActivate when it does something right there.
+- Keep actions to one or two. Put the rest in a DropdownMenu.
+- When an action repeats on every row, name it after its row ("Sign out of Chrome on Windows"), with aria-label or the IconButton label.
+
+## Don't
+
+- Don't make a row clickable with onClick on the row. Use href or onActivate.
+- Don't wrap a ListItem in a link or a button.
+- Don't use it for data people compare across columns. That's what DataTable is for.
+- Don't put long paragraphs in description. People scan a row, they don't read it.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<li onClick={open}>…<Button>Remove</Button></li>
+```
+
+Right:
+
+```tsx
+<ListItem title="Ilse Varga" onActivate={open} actions={<Button>Remove</Button>} />
+```
+
+A clickable li isn't a control. It can't take keyboard focus, and screen readers read it as plain text. onActivate (or href) turns the title into a real button (or link) that covers the row, and Remove keeps its own tab stop.
+
+Wrong:
+
+```tsx
+<a href="/orders/1"><ListItem title="Order shipped" actions={<Button>Archive</Button>} /></a>
+```
+
+Right:
+
+```tsx
+<ListItem title="Order shipped" href="/orders/1" actions={<Button>Archive</Button>} />
+```
+
+A button inside a link is invalid HTML, and screen readers announce the two as one merged control. href stretches the link over the row without wrapping the actions.
+
+## Anatomy
+
+- **List**: A ul with role="list" written out, so screen readers announce how many items there are even without bullets. Thin dividers between rows by default.
+- **Media**: Optional, at the start: an Avatar, an icon, a thumbnail. Centred against the text.
+- **Title and description**: The title is primary text, semibold. With href or onActivate it becomes the row’s one link or button, stretched over the row and underlined on hover. The description is secondary text, 14px (pixels).
+- **Meta**: Optional, right-aligned monospaced text with tabular figures (digits all the same width, so numbers line up): a time, a price, a count.
+- **Actions**: Optional controls at the end, layered above the stretched link, each with its own tab stop. On a narrow screen, meta and actions wrap under the text.

package/public/docs/components/loading-animation.md

@@ -0,0 +1,72 @@
+# LoadingAnimation
+
+> A loading state that fills a whole panel, drawn as an animated instrument dial in WebGL (the browser's graphics engine for drawing with the graphics card). The three dials follow the same rules. They draw themselves from the outside in, and their structure drifts. One mechanism clicks to its next detent using the system's snap easing (the motion where things arrive a little large and settle), and the signal accent colour only appears on the part that shows progress.
+
+- **Best for:** A wait that takes over a whole panel or page, like a route loading, a report building or a first sync.
+- **Not for:** A wait inside a button or a line of text: use Spinner. A wait with a known end: use Progress.
+- Atom. Source: `src/components/atoms/loading-animation/LoadingAnimation.tsx`
+- Rendered docs page: `/components/loading-animation`
+
+## Import
+
+```tsx
+import { LoadingAnimation } from 'src/components/atoms/loading-animation/LoadingAnimation'
+```
+
+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 |
+|---|---|---|---|
+| `variant` | `'aperture' \| 'gyro' \| 'reticle'` | `'aperture'` | Aperture: shaded blades stepping round a spinning core. Gyro: nested rings turning against each other. Reticle: a progress ring filling up from a marker at 12 o’clock. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | A 96px, 160px or 240px square (px means pixels). It shrinks with its container below that size, but never grows. |
+| `label` | `string` |  | Status text that is hidden on screen. Passing it turns the loader into a live region, an area screen readers announce when it changes. |
+| `className` | `string` |  | Merged with the component classes. If two clash, the later Tailwind utility wins (Tailwind is the CSS framework this system styles with). |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed through to the root div. |
+| `...rest` | `Omit<HTMLAttributes<HTMLDivElement>, 'role'>` |  | Every native div prop except role, for the same reason as Spinner: label is the only thing that sets role="status". |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Three dials, md
+
+```tsx
+<LoadingAnimation variant="aperture" label="Loading field kits" />
+<LoadingAnimation variant="gyro" label="Syncing manifest" />
+<LoadingAnimation variant="reticle" label="Acquiring position" />
+```
+
+### Aperture, three sizes
+
+```tsx
+<LoadingAnimation variant="aperture" size="sm" label="Loading field kits" />
+<LoadingAnimation variant="aperture" size="md" label="Loading field kits" />
+<LoadingAnimation variant="aperture" size="lg" label="Loading field kits" />
+```
+
+## Keyboard
+
+Not focusable. No keyboard behaviour of its own.
+
+## Do
+
+- Use it for a wait that takes over a panel or a page, like a route loading, a report building or a first sync.
+- Pass label, and say what is loading: ‘Loading field kits’, not ‘Loading’.
+- Pick one dial for each product surface and stick with it. The three are a family. They aren't meant to rotate.
+
+## Don't
+
+- Don't put it in a button or a line of text. That's Spinner, which doesn't use up a WebGL context.
+- Don't show more than a handful at once. Each one uses a WebGL context (one slot of the browser's graphics engine), and browsers cap how many you get.
+- Don't rely on the motion. When someone has reduced motion turned on, it shows one still frame, so the label has to carry the meaning.
+- Don't use it for a wait with a known end. That's Progress.
+
+## Anatomy
+
+- **div**: The root: a square box at the size you pick. It gets role="status", which makes screen readers announce it, only when it has a label.
+- **Stage**: A layer that holds the WebGL canvas, hidden from screen readers with aria-hidden (an ARIA attribute, from Accessible Rich Internet Applications). It fades in once the first frame is drawn.
+- **Dial**: Rings, tick crowns and arcs in text.primary, text.secondary, border.control and border.hairline.strong. One moving part is in accent.signal.fill.
+- **Fallback**: If WebGL isn't available, the Conveyor spinner shows in the same box. It's aria-hidden, so the label is still read only once.
+- **sr-only label**: The text screen readers announce (sr-only means it's for screen readers only). It's only there when you pass label.