division-ds 0.1.2 → 0.2.1

package/public/docs/components/toast.md

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

package/public/docs/components/tool-call.md

@@ -0,0 +1,107 @@
+# ToolCall
+
+> A tool the assistant ran, shown right where it ran. It has the status as a word and a small symbol, a title, the tool name and how long it took, with the input and output folded away behind a button.
+
+- **Best for:** An assistant reply that ran a tool, such as a query, a lookup or a calculation.
+- **Not for:** An action with side effects that needs a yes first: use ApprovalRequest.
+- Molecule. Source: `src/components/molecules/tool-call/ToolCall.tsx`
+- Rendered docs page: `/components/tool-call`
+
+## Import
+
+```tsx
+import { ToolCall } from 'src/components/molecules/tool-call/ToolCall'
+```
+
+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 |
+|---|---|---|---|
+| `name` | `string` |  | Required. The tool's own name, shown in a monospaced font. |
+| `title` | `string` |  | A plain-language description of the call, shown above the name. |
+| `status` | `'running' \| 'done' \| 'failed'` |  | Required. Shown as a word, a symbol and a colour. |
+| `duration` | `string` |  | How long it took, for example "1.2 s". |
+| `input` | `ReactNode` |  | What the assistant sent the tool. Folded away by default. |
+| `output` | `ReactNode` |  | What came back. Folded away by default. |
+| `defaultOpen` | `boolean` | `false` | Starts with the details showing. |
+| `className` | `string` |  | Added to the panel. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type ToolCallStatus = 'running' | 'done' | 'failed'
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Running, done and failed
+
+```tsx
+<div className="flex w-full max-w-xl flex-col gap-3">
+  <ToolCall name="query_stock_levels" title="Read stock levels at Depot 4" status="running" />
+  <ToolCall
+    name="query_stock_levels"
+    title="Read stock levels at Depot 4"
+    status="done"
+    duration="1.2 s"
+    input={'{ "depot": 4, "below_reorder_point": true }'}
+    output={'[\n  { "sku": "K-41", "on_hand": 6, "reorder_at": 10 },\n  { "sku": "TP-08", "on_hand": 3, "reorder_at": 8 }\n]'}
+  />
+  <ToolCall
+    name="fetch_supplier_lead_times"
+    title="Check supplier lead times"
+    status="failed"
+    duration="4.0 s"
+    output="Timed out after 4 s. The supplier feed did not answer."
+  />
+</div>
+```
+
+### Without a title, details open
+
+```tsx
+<div className="flex w-full max-w-xl flex-col gap-3">
+  <ToolCall
+    name="count_pallets"
+    status="done"
+    duration="0.3 s"
+    input={'{ "depot": 4, "bay": 2 }'}
+    output="14 pallets"
+    defaultOpen
+  />
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves to "Show details". |
+| `Enter` `Space` | Shows or hides the input and output. |
+
+## Do
+
+- Give each call a title a person understands: "Read stock levels at Depot 4", not just the function name.
+- Show the call even when it's boring. Seeing the work is how a reader learns to trust it, or to catch a mistake.
+- Mention a failure in the reply text too, along with what the assistant did instead.
+
+## Don't
+
+- Don't give a call its own live region (an area screen readers announce on change). The thread's busy status speaks for the whole turn.
+- Don't open the details by default for long payloads. The reply is what matters, and the payload is the evidence.
+- Don't use a ToolCall for something with a side effect the person hasn't agreed to. Ask with ApprovalRequest first.
+
+## Anatomy
+
+- **Panel**: A thin frame on surface.raised. It's marked as a separate block, so the message's screen reader announcement skips it.
+- **Status glyph**: A Spinner while running, a check when done, an alert circle when failed. Decoration only.
+- **Title and name**: The title written for people, then the tool's own name in a monospaced font. With no title, the name comes first.
+- **Status badge**: Running, Done or Failed as a word in the tone's colour. Colour is never the only signal.
+- **Duration**: In a monospaced font with equal-width digits, for example "1.2 s".
+- **Details**: A "Show details" button (with aria-expanded, which tells screen readers whether it's open) above Input and Output. Those wrap onto new lines instead of scrolling sideways.

package/public/docs/components/tooltip.md

@@ -0,0 +1,108 @@
+# Tooltip
+
+> Extra text that shows on hover or focus. It never holds information people can only get there. It doesn't appear on touch screens, it goes away, and someone may never trigger it.
+
+- **Best for:** Extra detail on hover or focus for an element that can take focus, such as an IconButton.
+- **Not for:** The only label, or the only explanation of an error. Use the label prop or visible text.
+- Atom. Source: `src/components/atoms/tooltip/Tooltip.tsx`
+- Rendered docs page: `/components/tooltip`
+
+## Import
+
+```tsx
+import { Tooltip, TooltipProvider } from 'src/components/atoms/tooltip/Tooltip'
+```
+
+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
+
+- One <TooltipProvider> near the root of the app. AppShell and the demo layout each mount one, so a screen doesn't add its own.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `content` | `string` |  | Required. The extra text. |
+| `children` | `ReactElement` |  | A single element that can take focus. |
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Which side of the trigger the content opens on. |
+| `className` | `string` |  | Merged with the content’s classes. Later Tailwind utilities (the small styling classes this system uses) win. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### On a button
+
+```tsx
+<Tooltip content="Sends the manifest to the depot; can't be undone once confirmed.">
+  <Button>Dispatch</Button>
+</Tooltip>
+```
+
+### On an icon button
+
+```tsx
+<Tooltip content="Uses the last known GPS fix, not live signal.">
+  <IconButton label="Recalculate route">
+    <Compass aria-hidden="true" className="w-4 h-4" />
+  </IconButton>
+</Tooltip>
+```
+
+### Sides
+
+```tsx
+<Tooltip content="Opens above the trigger." side="top">
+  <Button variant="secondary">Top</Button>
+</Tooltip>
+<Tooltip content="Opens right of the trigger." side="right">
+  <Button variant="secondary">Right</Button>
+</Tooltip>
+<Tooltip content="Opens below the trigger." side="bottom">
+  <Button variant="secondary">Bottom</Button>
+</Tooltip>
+<Tooltip content="Opens left of the trigger." side="left">
+  <Button variant="secondary">Left</Button>
+</Tooltip>
+```
+
+### Keyboard
+
+```tsx
+<p className="text-sm text-[var(--color-text-secondary)] max-w-md">
+  Press Tab to move to the trigger and the tooltip appears. Press Escape and it goes away,
+  without you moving the pointer. That's a rule in WCAG 2.2 (the Web Content Accessibility
+  Guidelines, the public rulebook for making websites usable by people with disabilities).
+  Its success criterion (SC) 1.4.13 says this kind of content has to stay dismissible (you
+  can close it), hoverable (you can move the pointer onto it) and persistent (it stays
+  until you do).
+</p>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves focus to the trigger and shows the tooltip. Tabbing on to the next element hides it again. |
+| `Esc` | Dismisses it without moving the pointer. That's required by SC 1.4.13, a success criterion (one numbered rule) in WCAG, the Web Content Accessibility Guidelines. |
+
+## Do
+
+- Use it for the extra detail, never the essential one.
+- Put it on an element that can take focus. A tooltip on a <div> doesn't reach anyone using a keyboard.
+- Keep it to one sentence.
+- Pair it with an IconButton whose label already names the action. Then the tooltip adds detail instead of repeating the name.
+
+## Don't
+
+- Don't put a tooltip on a disabled control. It can't take focus, so nobody can reach the tooltip.
+- Don't put interactive content inside one. A tooltip is text only and never takes focus.
+- Don't use it as the only label for an icon button. label does that job.
+- Don't make it the only place an error is explained.
+
+## Anatomy
+
+- **Provider**: Mounted once in AppShell. It sets the 300ms (millisecond) delay, and the 150ms skip window for moving between triggers.
+- **Trigger**: Uses asChild, so no wrapper element is added and the focus order stays as it was.
+- **Content**: Portalled, meaning it's rendered in a separate layer of the page, outside its trigger. It enters with motion token M1, is capped at 260px (pixels) wide and has the cut bottom-right corner. It's a single object with its own fill and holds nothing that takes focus, so the cut doesn't need an unclipped wrapper. The trigger, not the panel, is what takes focus.