division-ds 0.1.2 → 0.2.0

package/public/docs/components/tag.md

@@ -0,0 +1,103 @@
+# Tag
+
+> A removable chip for filters and selections. Its dismiss button is named after the thing it removes, so a row of them doesn't sound like six identical 'Remove' buttons to a screen reader.
+
+- **Best for:** A removable chip, such as an active filter or a selected value.
+- **Not for:** A status. Use Badge.
+- Atom. Source: `src/components/atoms/tag/Tag.tsx`
+- Rendered docs page: `/components/tag`
+
+## Import
+
+```tsx
+import { Tag } from 'src/components/atoms/tag/Tag'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `string` |  | The tag text. Required. |
+| `onDismiss` | `() => void` |  | Adds the dismiss button. It runs once the tag has faded out, not on the click. Remove the tag from your list here, and the tags after it slide into its place (M7, a motion token). With reduced motion turned on, it runs at once. |
+| `dismissLabel` | `(text: string) => string` | `t => `Remove ${t}`` | Replaces the built dismiss name, for example with another verb or another language. |
+| `className` | `string` |  | Merged with the component's classes. Later Tailwind utilities (the small styling classes this system uses) win. |
+| `ref` | `Ref<HTMLSpanElement>` |  | Forwarded to the span element. |
+| `...rest` | `Omit<HTMLAttributes<HTMLSpanElement>, 'children'>` |  | Every native span attribute except children, spread onto the root span. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Static tags
+
+```tsx
+<Tag>Holo sight</Tag>
+<Tag>Spare magazine</Tag>
+<Tag>Speed loader</Tag>
+```
+
+### Removable
+
+```tsx
+const FIELD_KIT = ['Holo sight', 'Spare magazine', 'Speed loader', 'Field goggles']
+
+function RemovableExample() {
+  const [tags, setTags] = useState(FIELD_KIT)
+
+  return (
+    <div className="flex flex-col gap-3">
+      <div className="flex flex-wrap gap-2">
+        {tags.length === 0 ? (
+          <span className="text-sm text-[var(--color-text-secondary)]">No filters applied.</span>
+        ) : (
+          tags.map(tag => (
+            <Tag key={tag} onDismiss={() => setTags(current => current.filter(t => t !== tag))}>
+              {tag}
+            </Tag>
+          ))
+        )}
+      </div>
+      {/* The Button atom, not a bare <button>: a hand-rolled one here had no system focus ring
+          at all, only the UA default. `ghost` is the existing variant for a text-weight action. */}
+      <Button variant="ghost" size="sm" wrapperClassName="self-start" onClick={() => setTags(FIELD_KIT)}>
+        Reset
+      </Button>
+    </div>
+  )
+}
+
+<RemovableExample />
+```
+
+### Long text
+
+```tsx
+<Tag onDismiss={() => {}}>Stick battery 11.1 V, 1300 mAh, lithium polymer</Tag>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves focus to the dismiss button, if there is one. The chip itself can't take focus. |
+| `Enter` | Dismisses the tag. |
+| `Space` | Dismisses the tag. |
+
+## Do
+
+- Keep the text short enough to read as a chip.
+- Move focus somewhere sensible after a dismissal: to the next tag, or to the container if the row is now empty.
+- Override dismissLabel when 'Remove' is the wrong verb, for example 'Clear filter'.
+
+## Don't
+
+- Don't make the whole chip clickable as well as its dismiss button. Two targets in one chip leaves people guessing.
+- Don't shrink the dismiss button below 24×24.
+- Don't use a Tag for status. That's a Badge.
+- Don't move the bevel from the backing layer onto the chip. A Tag can hold a dismiss button that takes focus, and clip-path (the CSS, or Cascading Style Sheets, property that cuts the corner) on the chip would clip that button's focus ring, the outline that shows keyboard focus, off the corner it sits in.
+
+## Anatomy
+
+- **Chip**: 28px (pixels) tall. The cut corner, the border.hairline-strong edge and the sunken fill sit on a backing layer, not on the chip itself. That layer is aria-hidden, a setting that hides it from screen readers.
+- **Text**: Required, and a plain string, because the dismiss name is built from it.
+- **Dismiss button**: A ghost IconButton at 24×24. That's the minimum target size in WCAG 2.2 (the Web Content Accessibility Guidelines, the public rulebook for making websites usable by people with disabilities). It only appears when onDismiss is given.

package/public/docs/components/textarea.md

@@ -0,0 +1,146 @@
+# Textarea
+
+> A text box for several lines. It has the same chrome (border, fill and states) as Input, resizes vertically and shows four rows by default. Like Input, it doesn't label itself.
+
+- **Best for:** Free text over several lines, inside a FormField.
+- **Not for:** A single line. Use Input.
+- Atom. Source: `src/components/atoms/textarea/Textarea.tsx`
+- Rendered docs page: `/components/textarea`
+
+## Import
+
+```tsx
+import { Textarea, textareaVariants } from 'src/components/atoms/textarea/Textarea'
+```
+
+## Requires
+
+- A <FormField> around it. On its own the control has no label. FormField supplies the label, the help text and the error, and links up their ids.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `invalid` | `boolean` | `false` | Sets aria-invalid and the invalid border. aria-invalid is an ARIA (Accessible Rich Internet Applications) attribute that tells screen readers the value has a problem. It doesn't render error text. |
+| `rows` | `number` | `4` | The browser's own rows attribute. Size it to the answer you expect. |
+| `aiValue` | `string` |  | The value an AI proposed, with the same contract as Input. The mark and the revert button sit in the top right corner. While the field holds exactly this value it shows the AI-filled state: an ai.border edge, a faint ai.wash tint and a sparkle mark that describes the field as Filled by AI. Once the person changes it, the field looks normal again and a Revert to suggestion button puts the value back through onChange (no button on a disabled or read-only field). An invalid field keeps its invalid border. |
+| `className` | `string` |  | Merged with the control's classes. Later Tailwind utilities (the small styling classes this system uses) win. |
+| `ref` | `Ref<HTMLTextAreaElement>` |  | Forwarded to the textarea element. |
+| `...rest` | `Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'aria-invalid'>` |  | Every native textarea prop except aria-invalid, spread onto the element. aria-invalid is removed from the type instead of being quietly overridden at runtime. invalid is the only source of both the attribute and the border, so letting a caller set one directly would let what people see and what screen readers hear drift apart. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export const textareaVariants = cva( …
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Default
+
+```tsx
+<label className="flex flex-col gap-1 text-sm w-full max-w-xs">
+  Field notes
+  <Textarea placeholder="What did you observe on site?" />
+</label>
+```
+
+### Rows
+
+```tsx
+<label className="flex flex-col gap-1 text-sm w-full max-w-xs">
+  Short (2 rows)
+  <Textarea rows={2} placeholder="One-line summary, wraps if needed" />
+</label>
+<label className="flex flex-col gap-1 text-sm w-full max-w-xs">
+  Tall (8 rows)
+  <Textarea rows={8} placeholder="Full incident report" />
+</label>
+```
+
+### States
+
+```tsx
+<label className="flex flex-col gap-1 text-sm w-full max-w-xs">
+  Invalid
+  <Textarea invalid defaultValue="Site coordinates unclear" />
+</label>
+<label className="flex flex-col gap-1 text-sm w-full max-w-xs">
+  Disabled
+  <Textarea disabled defaultValue="Locked until review closes" />
+</label>
+{/* read-only is a different state from disabled and looks different — the text stays
+    selectable and the control stays in the tab order, so `read-only:text-[...]` dims the
+    text without the disabled fill. It was styled but never demonstrated. */}
+<label className="flex flex-col gap-1 text-sm w-full max-w-xs">
+  Read-only
+  <Textarea readOnly defaultValue="Submitted 14:02, no further edits" />
+</label>
+```
+
+### Filled by AI, with a revert
+
+```tsx
+const AI_NOTES = 'Ships with two midcaps and a sling. Ask for the 1.2 J spring if you play indoors.'
+
+<div className="flex flex-col gap-2 w-full max-w-sm">
+  <label htmlFor="ai-notes" className="text-sm">Order notes</label>
+  <AiLabel explanation="Drafted from the replica's listing. Check the details before you send it." />
+  <Textarea id="ai-notes" aiValue={AI_NOTES} defaultValue={AI_NOTES} />
+</div>
+```
+
+### With a counter
+
+```tsx
+function CounterExample() {
+  const max = 140
+  const [value, setValue] = useState('')
+  return (
+    <label className="flex flex-col gap-1 text-sm w-full max-w-xs">
+      Field day summary
+      <Textarea
+        value={value}
+        onChange={e => setValue(e.target.value)}
+        maxLength={max}
+        aria-describedby="textarea-docs-counter"
+      />
+      <span id="textarea-docs-counter" className="text-xs text-[var(--color-text-secondary)]">
+        {value.length} / {max}
+      </span>
+    </label>
+  )
+}
+
+<CounterExample />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves focus to it. |
+| `Enter` | Starts a new line. It doesn't submit the form. |
+
+## Do
+
+- Size rows to the answer you expect.
+- Leave vertical resize on. Taking it away doesn't help anyone.
+- Show a character counter as text the field points to with aria-describedby, not as a colour change.
+
+## Don't
+
+- Don't allow horizontal resize. It breaks the layout around it.
+- Don't bevel it. The cut would land exactly where the resize grip is, and clip-path (the CSS, or Cascading Style Sheets, property that cuts the corner) would take the focus ring with it. Input's page states the general rule.
+- Don't reach for inputVariants here. The shared heights are wrong for a box with several lines, and the small duplication is on purpose.
+- Don't trap Enter to submit unless there's another way to add a line.
+
+## Anatomy
+
+- **Textarea**: Four rows, never shorter than 88px (pixels), vertical resize only.
+- **Border**: The same three states as Input.
+- **Focus ring**: The outline that shows keyboard focus. It sits on the control itself.

package/public/docs/components/timeline.md

@@ -0,0 +1,150 @@
+# Timeline
+
+> Events in time order down a vertical line. Each one has a square marker with an icon, a title line, a time and an optional body. You can group them by day, or not.
+
+- **Best for:** A record of what happened to one thing, newest or oldest first: a shipment, a depot, an account.
+- **Not for:** Steps of a flow someone is going through: use Stepper. Rows people sort and compare: use DataTable.
+- Molecule. Source: `src/components/molecules/timeline/Timeline.tsx`
+- Rendered docs page: `/components/timeline`
+
+## Import
+
+```tsx
+import { Timeline, TimelineGroup, TimelineItem } from 'src/components/molecules/timeline/Timeline'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label (Timeline)` | `string` |  | Required. Names the list. |
+| `className (Timeline)` | `string` |  | Added to the root ol. |
+| `title (TimelineGroup)` | `string` |  | Required. A day or a period, for example "Today". |
+| `level (TimelineGroup)` | `2 \| 3 \| 4` | `3` | The heading level of the group title (2 means an h2, and so on). |
+| `icon (TimelineItem)` | `ReactNode` |  | Required. A lucide icon, there for decoration only. |
+| `tone (TimelineItem)` | `'neutral' \| 'signal' \| 'ok' \| 'warning' \| 'hostile' \| 'info'` | `'neutral'` | Colours the marker, with the same meanings as Badge. The title still says it in words. |
+| `title (TimelineItem)` | `ReactNode` |  | Required. What happened, in one line. |
+| `meta (TimelineItem)` | `ReactNode` |  | Beside the title: who did it, or a Badge with the outcome. |
+| `time (TimelineItem)` | `string` |  | Required. An ISO datetime (a date and time written in the international standard format), used for <time dateTime>. |
+| `timeLabel (TimelineItem)` | `string` |  | Required. What people see, for example "09:40" or "Mon 12 Oct". |
+| `details (TimelineItem)` | `ReactNode` |  | Extra information, folded away behind a "Show details" button. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type TimelineTone = 'neutral' | 'signal' | 'ok' | 'warning' | 'hostile' | 'info'
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Grouped by day
+
+```tsx
+<div className="w-full max-w-xl">
+  <Timeline label="Activity on Depot 4">
+    <TimelineGroup title="Today" level={4}>
+      <TimelineItem
+        icon={<Truck />}
+        tone="info"
+        title="Shipment SHP-204 left for Sibiu"
+        meta="Dispatch"
+        time="2026-10-15T09:40:00+03:00"
+        timeLabel="09:40"
+      >
+        Nine items, 22.1 kg, with the regular courier.
+      </TimelineItem>
+      <TimelineItem
+        icon={<Phone />}
+        title="Call with Ilse Varga"
+        meta={
+          <>
+            <span>Oskar Behn</span>
+            <Badge tone="ok">Resolved</Badge>
+          </>
+        }
+        time="2026-10-15T08:15:00+03:00"
+        timeLabel="08:15"
+        details="Agreed to move the Friday pickup to Thursday morning. Bay 2 stays free until noon."
+      >
+        The late pallet from Arad is booked for tomorrow.
+      </TimelineItem>
+    </TimelineGroup>
+    <TimelineGroup title="Yesterday" level={4}>
+      <TimelineItem
+        icon={<TriangleAlert />}
+        tone="warning"
+        title="Floor scale out of calibration"
+        time="2026-10-14T16:05:00+03:00"
+        timeLabel="16:05"
+      >
+        Readings 0.4 kg high. Work order WO-32 opened.
+      </TimelineItem>
+      <TimelineItem
+        icon={<PackageCheck />}
+        tone="ok"
+        title="Inbound delivery checked in"
+        time="2026-10-14T10:30:00+03:00"
+        timeLabel="10:30"
+      />
+    </TimelineGroup>
+  </Timeline>
+</div>
+```
+
+### Without groups
+
+```tsx
+<div className="w-full max-w-xl">
+  <Timeline label="Work order WO-29">
+    <TimelineItem icon={<Wrench />} title="Opened" time="2026-10-09T08:00:00+03:00" timeLabel="Fri 9 Oct" />
+    <TimelineItem
+      icon={<Wrench />}
+      tone="signal"
+      title="Assigned to Mara Lind"
+      time="2026-10-12T11:20:00+03:00"
+      timeLabel="Mon 12 Oct"
+    />
+    <TimelineItem
+      icon={<CircleCheck />}
+      tone="ok"
+      title="Closed: pallet jack serviced"
+      time="2026-10-13T15:45:00+03:00"
+      timeLabel="Tue 13 Oct"
+    />
+  </Timeline>
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves to each "Show details" button, and to any link inside an event. |
+| `Enter` `Space` | On "Show details": shows or hides the details. |
+
+## Do
+
+- Label the timeline for what it records, for example "Activity on Depot 4".
+- Group by day once there are more than a handful of events.
+- Keep the title to one line and put the rest in the body or details.
+- Pick a tone for what the event means (ok for done, hostile for failed), and say it in the title too.
+
+## Don't
+
+- Don't use a Timeline for a flow someone is going through. That's what Stepper is for.
+- Don't put the only copy of something important in details.
+- Don't colour every marker. Neutral is the default for a reason.
+
+## Anatomy
+
+- **List**: An ol (numbered list element) named by label. It holds items, groups, or both.
+- **Group**: A list item with a heading in a monospaced font, a thin line running to the edge, and its own ol.
+- **Marker**: A 28px (pixel) square holding the icon, outlined and coloured by tone.
+- **Rail**: A thin line from each marker to the next. There's none after the last event in a list.
+- **Title line**: The title, then meta, then the time on the right inside a <time dateTime> element, which gives machines the exact date.
+- **Body**: Optional text under the title.
+- **Details**: Optional, hidden behind a "Show details" button. The button has aria-expanded, which tells screen readers whether the details are open.

package/public/docs/components/toast.md

@@ -0,0 +1,192 @@
+# Toast
+
+> A short message that pops up, stays a few seconds and goes away. Hostile toasts (errors) interrupt and stay longer. Everything else waits its turn.
+
+- **Best for:** Confirming something the person just did, for a few seconds.
+- **Not for:** The only copy of important information: use Alert. Also not for a change the page already shows.
+- Molecule. Source: `src/components/molecules/toast/Toast.tsx`
+- Rendered docs page: `/components/toast`
+
+## Import
+
+```tsx
+import { Toaster, useToast } from 'src/components/molecules/toast/Toast'
+```
+
+## Requires
+
+- One <Toaster> near the root of the app, wrapped around everything that calls useToast(). AppShell and the demo layout each mount one. Outside it, useToast() throws an error.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title (ToastOptions)` | `string` |  | Required. Screen readers hear the tone word before it. |
+| `description (ToastOptions)` | `string` |  | Optional body text. |
+| `tone (ToastOptions)` | `'info' \| 'ok' \| 'warning' \| 'hostile'` | `'info'` | Which colour, icon and word the toast has. |
+| `duration (ToastOptions)` | `number` | `5000` | How many milliseconds before it goes away on its own. 8000 for hostile. |
+| `action (ToastOptions)` | `{ label: string; altText: string; onAction: () => void }` |  | Optional. Radix (the library the toast is built on) requires altText: what to do somewhere else if someone can't reach the toast in time. |
+| `replace (ToastOptions)` | `string` |  | Optional. Closes any open toast raised with the same string as this one opens, so an action repeated quickly ("Alert acknowledged" three times) shows one toast instead of a stack. |
+| `useToast()` | `{ toast: (options: ToastOptions) => string; dismiss: (id: string) => void }` |  | Shows a toast (and returns its id) or closes one. Throws an error outside a Toaster. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type ToastOptions = {
+  title: string
+  description?: string
+  tone?: Tone
+  /** ms before it leaves on its own. Default 5000; 8000 for hostile. */
+  duration?: number
+  /** Radix requires altText: the way to do the same thing for someone who cannot reach the toast
+   *  before it leaves. */
+  action?: { label: string; altText: string; onAction: () => void }
+  /** Any open toast raised with the same string closes as this one opens, so a repeated action
+   *  ("Alert acknowledged" three times) shows one toast, not a stack over the page. */
+  replace?: string
+}
+```
+
+```ts
+export function useToast(): ToastApi
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Tones
+
+```tsx
+function TonesExample() {
+  const { toast } = useToast()
+
+  return (
+    <div className="flex flex-wrap gap-3">
+      <Button variant="secondary" size="sm" onClick={() => toast({ title: 'Depot hours changed', tone: 'info' })}>
+        Info
+      </Button>
+      <Button variant="secondary" size="sm" onClick={() => toast({ title: 'Manifest saved', tone: 'ok' })}>
+        Ok
+      </Button>
+      <Button variant="secondary" size="sm" onClick={() => toast({ title: 'Depot closes early', tone: 'warning' })}>
+        Warning
+      </Button>
+      <Button variant="secondary" size="sm" onClick={() => toast({ title: 'Sync failed', tone: 'hostile' })}>
+        Hostile
+      </Button>
+    </div>
+  )
+}
+
+<TonesExample />
+```
+
+### With a description
+
+```tsx
+function WithDescriptionExample() {
+  const { toast } = useToast()
+
+  return (
+    <Button
+      variant="secondary"
+      size="sm"
+      onClick={() => toast({ title: 'Manifest saved', description: 'Twelve items, filed to Brasov north.', tone: 'ok' })}
+    >
+      Save manifest
+    </Button>
+  )
+}
+
+<WithDescriptionExample />
+```
+
+### With an action
+
+```tsx
+function WithActionExample() {
+  const { toast } = useToast()
+
+  return (
+    <Button
+      variant="secondary"
+      size="sm"
+      onClick={() =>
+        toast({
+          title: 'Item removed',
+          action: {
+            label: 'Undo',
+            altText: 'Undo from the manifest history',
+            onAction: () => toast({ title: 'Item restored', tone: 'ok' }),
+          },
+        })
+      }
+    >
+      Remove item
+    </Button>
+  )
+}
+
+<WithActionExample />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `F8` | Moves focus into the notification region. |
+| `Tab` | Moves through the toast's action and close button. A toast with focus pauses its timer. |
+| `Escape` | Closes the toast that has focus. |
+
+## Do
+
+- Use a toast to confirm something the person just did.
+- Give every action an altText that says where else it can be done.
+- Keep the title under about six words.
+- After an action runs, focus goes back to where it was before it entered the toast. If the action changes the page (Undo puts a row back), move focus to what changed yourself.
+- A toast follows the innermost open overlay (a dialog or panel on top of the page). If it's raised while one is open, or is already showing when one opens, it shows inside that overlay, and it moves back to the page corner when the overlay closes. AlertDialog is the exception: its toasts always show in the page corner, above the scrim (the dimmed layer behind the dialog).
+
+## Don't
+
+- Don't put the only copy of important information in a toast. It goes away.
+- Don't show a toast for a change the page already shows.
+- Don't line up more than three at once.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+function SettingsForm() {
+  return (
+    <Toaster>
+      <Form />
+    </Toaster>
+  )
+}
+```
+
+Right:
+
+```tsx
+// once, at the root
+<Toaster>
+  <App />
+</Toaster>
+
+// anywhere below it
+const { toast } = useToast()
+toast({ title: 'Settings saved', tone: 'ok' })
+```
+
+A screen that mounts its own Toaster gets a second viewport (the corner where toasts appear) and a second live region (the area screen readers listen to for announcements). Rely on the one at the root and call useToast().
+
+## Anatomy
+
+- **Toaster**: The provider and the viewport, mounted once in the app shell.
+- **Viewport**: The area where toasts appear: bottom right, 360px (pixels) wide, full width on a phone. Pressing F8 moves focus into it.
+- **Toast**: Built like Alert, on the sunken surface: icon, tone word, title, description, action and a close button. Hovering over it pauses its timer too.
+- **Action**: Optional. Needs altText, which says how to do the same thing somewhere else.