division-ds 0.1.2 → 0.2.1

package/public/docs/components/alert-dialog.md

@@ -0,0 +1,292 @@
+# AlertDialog
+
+> Asks for confirmation before something with real consequences. It shows a question, says what will happen, and offers Cancel and the action. Screen readers announce it as an alert, a click outside won't dismiss it, and focus starts on Cancel. If the action returns a promise (a value that finishes later, such as a server call), the dialog stays open and shows it's busy until that work is done.
+
+- **Best for:** Confirming an action that matters and can't be undone, such as a delete.
+- **Not for:** Something that can be undone: just do it and offer Undo in a Toast. A form or a task: use Dialog.
+- Organism. Source: `src/components/organisms/alert-dialog/AlertDialog.tsx`
+- Rendered docs page: `/components/alert-dialog`
+
+## Import
+
+```tsx
+import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogFooter, AlertDialogTrigger } from 'src/components/organisms/alert-dialog/AlertDialog'
+```
+
+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 |
+|---|---|---|---|
+| `open (AlertDialog)` | `boolean` |  | Whether it is open, when your code controls that (controlled mode). |
+| `defaultOpen (AlertDialog)` | `boolean` | `false` | Whether it starts open, when the component tracks its own state (uncontrolled mode). |
+| `onOpenChange (AlertDialog)` | `(open: boolean) => void` |  | Called on every open and close. It isn't called when someone tries to close it while the action is busy. |
+| `asChild (Trigger)` | `boolean` |  | Uses its single child as the trigger instead of adding its own button. Pass a Button. |
+| `ref (Trigger)` | `Ref<HTMLButtonElement>` |  | The trigger button. |
+| `title (Content)` | `string` |  | Required. The question, and the name screen readers say. |
+| `description (Content)` | `string` |  | Required. What confirming does. Screen readers read it as the accessible description. |
+| `size (Content)` | `'sm' \| 'md'` | `'md'` | Maximum width: 24rem or 32rem (rem is a unit based on the root text size, usually 16 pixels). |
+| `className (Content)` | `string` |  | Added to the panel classes. Where two Tailwind utility classes clash, the later one wins. |
+| `ref (Content)` | `Ref<HTMLDivElement>` |  | The element with the role alertdialog. |
+| `onPointerDownOutside / onInteractOutside (Content)` | `—` |  | Not available: a click outside never dismisses an alert dialog. |
+| `className (Footer)` | `string` |  | Added to the button row classes. |
+| `children (Cancel)` | `ReactNode` | `'Cancel'` | The label. Name what the person keeps, for example Keep editing. |
+| `ref (Cancel)` | `Ref<HTMLButtonElement>` |  | The Cancel button, which gets focus when the dialog opens. |
+| `tone (Action)` | `'hostile' \| 'default'` | `'hostile'` | hostile (the danger button) for something that can't be undone. default (the primary button) for a confirm that's safe but still matters. |
+| `onClick (Action)` | `(event) => void \| Promise<unknown>` |  | Runs on confirm, then closes the dialog. If it returns a promise, the dialog stays open and busy until the promise settles: success closes it, failure keeps it open. Calling event.preventDefault() also keeps it open. |
+| `loading (Action)` | `boolean` | `false` | Marks it busy from outside, for work you track yourself. It holds the dialog open the same way a pending promise does. |
+| `loadingLabel (Action)` | `string` | `'Working'` | Text you can't see that screen readers announce while it's busy. |
+| `ref (Action)` | `Ref<HTMLButtonElement>` |  | The action button. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Delete while the request is still running: the action button shows it's busy and the dialog waits
+
+```tsx
+const request = (fail = false) =>
+  new Promise<void>((resolve, reject) =>
+    window.setTimeout(() => (fail ? reject(new Error('The server did not answer.')) : resolve()), 1000)
+  )
+
+function DeleteExample() {
+  const { toast } = useToast()
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger asChild>
+        <Button variant="danger">Delete depot</Button>
+      </AlertDialogTrigger>
+      <AlertDialogContent
+        title="Delete Brasov north?"
+        description="Its 12 open manifests move to the unassigned queue. The depot cannot be restored."
+      >
+        <AlertDialogFooter>
+          <AlertDialogCancel />
+          <AlertDialogAction
+            loadingLabel="Deleting depot"
+            onClick={() => request().then(() => toast({ tone: 'ok', title: 'Depot deleted' }))}
+          >
+            Delete depot
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}
+
+<DeleteExample />
+```
+
+### A failed request: the dialog stays open and a toast says why
+
+```tsx
+const request = (fail = false) =>
+  new Promise<void>((resolve, reject) =>
+    window.setTimeout(() => (fail ? reject(new Error('The server did not answer.')) : resolve()), 1000)
+  )
+
+function FailureExample() {
+  const { toast } = useToast()
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger asChild>
+        <Button variant="secondary">Revoke API key</Button>
+      </AlertDialogTrigger>
+      <AlertDialogContent
+        title="Revoke the warehouse key?"
+        description="Scripts that use it stop working at once. This demo always fails, to show the dialog staying open."
+        size="sm"
+      >
+        <AlertDialogFooter>
+          <AlertDialogCancel>Keep key</AlertDialogCancel>
+          <AlertDialogAction
+            loadingLabel="Revoking key"
+            onClick={() =>
+              request(true).catch((error: Error) => {
+                toast({ tone: 'hostile', title: 'Key not revoked', description: error.message })
+                throw error
+              })
+            }
+          >
+            Revoke key
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}
+
+<FailureExample />
+```
+
+### A safe confirm that still has consequences, with the default tone
+
+```tsx
+function DefaultToneExample() {
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger asChild>
+        <Button>Publish prices</Button>
+      </AlertDialogTrigger>
+      <AlertDialogContent
+        title="Publish the autumn prices?"
+        description="Customers see them on every replica page as soon as you publish."
+        size="sm"
+      >
+        <AlertDialogFooter>
+          <AlertDialogCancel>Not yet</AlertDialogCancel>
+          <AlertDialogAction tone="default">Publish</AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}
+
+<DefaultToneExample />
+```
+
+### Type the name to confirm, for the costliest actions
+
+```tsx
+const request = (fail = false) =>
+  new Promise<void>((resolve, reject) =>
+    window.setTimeout(() => (fail ? reject(new Error('The server did not answer.')) : resolve()), 1000)
+  )
+
+const ACCOUNT = 'northfield-supply'
+
+function TypeToConfirmExample() {
+  const [typed, setTyped] = useState('')
+  const matches = typed.trim() === ACCOUNT
+  return (
+    <AlertDialog onOpenChange={() => setTyped('')}>
+      <AlertDialogTrigger asChild>
+        <Button variant="danger">Delete account</Button>
+      </AlertDialogTrigger>
+      <AlertDialogContent
+        title="Delete the account?"
+        description="Its 212 orders, saved kit lists and team access are removed for good."
+      >
+        <FormField label="Account name" help={`Type ${ACCOUNT} to enable Delete account.`}>
+          <Input
+            value={typed}
+            onChange={event => setTyped(event.target.value)}
+            autoComplete="off"
+            spellCheck={false}
+            className="font-mono"
+          />
+        </FormField>
+        <AlertDialogFooter>
+          <AlertDialogCancel />
+          <AlertDialogAction disabled={!matches} loadingLabel="Deleting account" onClick={() => request()}>
+            Delete account
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}
+
+<TypeToConfirmExample />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves between Cancel, the action and any field, looping around inside the dialog. |
+| `Enter` | Presses the focused button. Focus starts on Cancel, so an accidental Enter cancels. |
+| `Esc` | Cancels and sends focus back to whatever opened it. It waits while the action is busy. |
+
+## Do
+
+- Write the title as the question, with the thing it's about: 'Delete Brasov north?', not 'Are you sure?'.
+- Say in the description exactly what will be lost or changed, with numbers where you have them.
+- Label the action with the verb and the thing: 'Delete depot', never 'OK' or 'Yes'.
+- Return the promise from onClick for anything that calls a server.
+- For something very costly, add a field asking for the name, and disable the action until it matches (see the last example).
+
+## Don't
+
+- Don't use it for something that can be undone. Do the thing and offer Undo in a toast.
+- Don't use it for a form or a task. That's a Dialog.
+- Don't add a close button or close it on a click outside. The only choices are Cancel or the action.
+- Don't open one from a dropdown menu item. The item is gone by the time the dialog closes, so focus has nowhere to go back to.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<Dialog>
+  <DialogContent title="Delete depot?">
+    <DialogFooter>
+      <DialogClose asChild><Button variant="secondary">Cancel</Button></DialogClose>
+      <Button variant="danger" onClick={remove}>Delete</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+Right:
+
+```tsx
+<AlertDialog>
+  <AlertDialogContent title="Delete depot?" description="Its open manifests move to the unassigned queue.">
+    <AlertDialogFooter>
+      <AlertDialogCancel />
+      <AlertDialogAction onClick={remove}>Delete depot</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+Dialog has the role dialog (the label screen readers use to describe it), closes when someone clicks the scrim behind it, and focuses the first control. A destructive confirm needs the role alertdialog, no dismissal from outside, and focus on Cancel. AlertDialog does all three.
+
+Wrong:
+
+```tsx
+const [busy, setBusy] = useState(false)
+<AlertDialog open={open} onOpenChange={next => { if (!busy) setOpen(next) }}>
+  ...
+  <AlertDialogAction loading={busy} onClick={async event => {
+    event.preventDefault(); setBusy(true); await remove(); setBusy(false); setOpen(false)
+  }}>Delete</AlertDialogAction>
+```
+
+Right:
+
+```tsx
+<AlertDialogAction onClick={() => remove()}>Delete</AlertDialogAction>
+```
+
+Return the promise. The action goes busy, Cancel and Escape wait, and the dialog closes when the work succeeds or stays open when it fails. You don't need any state of your own.
+
+Wrong:
+
+```tsx
+<AlertDialogAction onClick={() => remove()}>Delete</AlertDialogAction>
+// remove() rejects, and nothing tells the person
+```
+
+Right:
+
+```tsx
+<AlertDialogAction onClick={() => remove().catch(error => {
+  toast({ tone: 'hostile', title: 'Not deleted', description: error.message })
+  throw error
+})}>Delete</AlertDialogAction>
+```
+
+When the promise fails, the dialog stays open but shows nothing on its own. Report the failure, then throw the error again so the dialog stays open for a retry or a Cancel.
+
+## Anatomy
+
+- **Scrim**: The dimmed layer over the page, coloured surface.scrim. The page under it is inert (it can't be clicked or focused) and hidden from screen readers. Unlike Dialog, clicking it does nothing: the person has to choose.
+- **Surface**: The same panel as Dialog: surface.base, a strong hairline border, the corner crosshair and the M7 motion for opening and closing. Its role is alertdialog.
+- **Title**: Required. The question. It's an h2 (a second-level heading) and the dialog's accessible name, the name screen readers say for it.
+- **Description**: Required. What confirming does. Screen readers announce it with the title.
+- **Body**: Optional. A list of what will be lost, or a field to type a name into.
+- **Footer**: Cancel first, then the action. There's no close button.

package/public/docs/components/alert.md

@@ -0,0 +1,175 @@
+# Alert
+
+> A message that sits in the page. It shows its tone three ways, as an icon, a word and a colour, so it still reads on a greyscale screen and through a screen reader.
+
+- **Best for:** A message that sits in the page and stays there: a warning about this screen, or a failed load with a retry.
+- **Not for:** Something that will go away on its own: use Toast.
+- Molecule. Source: `src/components/molecules/alert/Alert.tsx`
+- Rendered docs page: `/components/alert`
+
+## Import
+
+```tsx
+import { Alert } from 'src/components/molecules/alert/Alert'
+```
+
+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` | `'info' \| 'ok' \| 'warning' \| 'hostile'` | `'info'` | Which colour, icon and word the alert carries. |
+| `title` | `string` |  | Required. Screen readers hear the tone word in front of it. |
+| `children` | `ReactNode` |  | The body text. |
+| `live` | `boolean` | `false` | Only for an alert added after the page has loaded. It sets the role screen readers use to announce it: hostile and warning get role=alert (announced at once), info and ok get role=status (announced politely). |
+| `onDismiss` | `() => void` |  | Adds the dismiss button. It runs once the alert has faded and its height has collapsed (M7), not on the click itself, so remove the alert from the page here. With reduced motion it runs straight away. |
+| `dismissLabel` | `string` | `'Dismiss'` | The name screen readers give the dismiss button. |
+| `action` | `ReactNode` |  | For example, a small Button. |
+| `compact` | `boolean` | `false` | One line, for a toolbar, table header or card. The body sits inside the title paragraph, so pass plain inline text, not blocks. |
+| `className` | `string` |  | Merged onto the root. |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed through to the root DOM element. |
+| `...rest` | `Omit<HTMLAttributes<HTMLDivElement>, 'title' \| 'role'>` |  | You can't set role yourself: live decides it. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Tones
+
+```tsx
+<div className="flex flex-col gap-4 w-full">
+  <Alert tone="info" title="Depot hours changed">
+    Weekend pickup now opens at 8am.
+  </Alert>
+  <Alert tone="ok" title="Manifest saved" />
+  <Alert tone="warning" title="Depot closes early">
+    The Brasov depot closes at 4pm today for maintenance.
+  </Alert>
+  <Alert tone="hostile" title="Sync failed">
+    The last manifest sync could not reach the server.
+  </Alert>
+</div>
+```
+
+### With body and action
+
+```tsx
+<Alert
+  title="Offline"
+  action={
+    <Button variant="secondary" size="sm">
+      Retry
+    </Button>
+  }
+>
+  Changes are kept on this device.
+</Alert>
+```
+
+### Compact
+
+```tsx
+<div className="flex flex-col gap-3 w-full">
+  <Alert compact tone="info" title="Depot hours changed">
+    Weekend pickup opens at 8am.
+  </Alert>
+  <Alert
+    compact
+    tone="warning"
+    title="Low stock"
+    action={
+      <Button variant="secondary" size="sm">
+        Reorder
+      </Button>
+    }
+  >
+    Three replicas left.
+  </Alert>
+</div>
+```
+
+### Dismissible (it has a close button), without the live prop, because it was on the page from the start
+
+```tsx
+function DismissibleExample() {
+  const [dismissed, setDismissed] = useState(false)
+
+  return dismissed ? (
+    <Button variant="secondary" size="sm" onClick={() => setDismissed(false)}>
+      Restore alert
+    </Button>
+  ) : (
+    <Alert
+      tone="warning"
+      title="Depot closes early"
+      onDismiss={() => setDismissed(true)}
+      dismissLabel="Dismiss depot notice"
+    >
+      The Brasov depot closes at 4pm today for maintenance.
+    </Alert>
+  )
+}
+
+<DismissibleExample />
+```
+
+### Live: it appears after a click, and a screen reader announces it straight away
+
+```tsx
+function LiveExample() {
+  const [shown, setShown] = useState(false)
+
+  return (
+    <div className="flex flex-col gap-3 w-full">
+      <Button
+        variant="secondary"
+        size="sm"
+        wrapperClassName="self-start"
+        onClick={() => setShown(true)}
+      >
+        Trigger a live alert
+      </Button>
+      {shown ? (
+        <Alert live tone="hostile" title="Sync failed" onDismiss={() => setShown(false)}>
+          The last manifest sync could not reach the server.
+        </Alert>
+      ) : null}
+    </div>
+  )
+}
+
+<LiveExample />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Reaches the action, then the dismiss button. The alert itself isn't a stop. |
+
+## Do
+
+- Start the title with what happened, and the body with what to do.
+- Use live only when the alert appears in response to something the person did.
+- Name the dismiss button for what it closes when there's more than one alert on a page.
+- Use compact where a full alert would push the content it describes out of view, and keep the body to a short phrase.
+- After dismiss, move keyboard focus to the next sensible control. The alert's own dismiss button disappears with it, and focus would otherwise drop back to the top of the page.
+
+## Don't
+
+- Don't use an alert for something that will go away on its own. That's a Toast.
+- Don't colour the body text in the tone.
+- Don't put paragraphs or lists inside a compact alert. It's one line of text.
+- Don't stack more than two alerts. The second one is usually detail for the first.
+
+## Anatomy
+
+- **Container**: A raised surface with a 1px (one pixel) border in the tone's text colour on all four sides. There's no stripe down one side.
+- **Icon**: Shows the tone without relying on colour. Marked aria-hidden, so screen readers skip it.
+- **Tone word**: 'Warning:' before the title. It's hidden on screen and read out by screen readers.
+- **Title**: Required.
+- **Body**: In secondary text, not in the tone colour.
+- **Action**: Optional, usually a small Button.
+- **Dismiss**: Optional. A ghost IconButton (an icon-only button with no fill).
+- **Compact layout**: One line: a 16px icon, then the title and body as one sentence, then the action and dismiss button. Long text wraps onto a new line instead of being cut off.

package/public/docs/components/approval-request.md

@@ -0,0 +1,148 @@
+# ApprovalRequest
+
+> A pause before an action that changes something in the real world (a side effect). It shows a preview of exactly what will happen, Approve and Reject buttons, and then a status line that takes keyboard focus.
+
+- **Best for:** An assistant is about to send, change or spend something outside the conversation.
+- **Not for:** Confirming a destructive action on an ordinary screen: use AlertDialog.
+- Molecule. Source: `src/components/molecules/approval-request/ApprovalRequest.tsx`
+- Rendered docs page: `/components/approval-request`
+
+## Import
+
+```tsx
+import { ApprovalRequest } from 'src/components/molecules/approval-request/ApprovalRequest'
+```
+
+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 parent that holds the state and sets it to approved or rejected in onApprove and onReject.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` |  | Required. The action as a question. It also names the section. |
+| `state` | `'pending' \| 'approved' \| 'rejected'` |  | Required. Pending shows the buttons; approved or rejected shows the status line. |
+| `onApprove` | `() => void` |  | Required. Run the action, then set state to approved. |
+| `onReject` | `() => void` |  | Required. Set state to rejected. Nothing else happens. |
+| `approveLabel` | `string` | `'Approve'` | The approve button. Say the action, like "Send". |
+| `rejectLabel` | `string` | `'Reject'` | The reject button, like "Don't send". |
+| `approvedLabel` | `string` | `'Approved by you'` | The status line once approved. |
+| `rejectedLabel` | `string` | `'Rejected'` | The status line once rejected. |
+| `className` | `string` |  | Goes on the section. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type ApprovalState = 'pending' | 'approved' | 'rejected'
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Pending: approve or reject, and the keyboard focus then moves to the result
+
+```tsx
+function LiveApproval() {
+  const [state, setState] = useState<ApprovalState>('pending')
+  return (
+    <div className="flex w-full max-w-xl flex-col items-start gap-3">
+      <ApprovalRequest
+        title="Send this reorder to the supplier?"
+        state={state}
+        onApprove={() => setState('approved')}
+        onReject={() => setState('rejected')}
+        approveLabel="Send reorder"
+        rejectLabel="Don't send"
+        className="w-full"
+      >
+        <p>To: Arad replica supply</p>
+        <p>10 × K-41 field radio, 8 × trail pack. Delivery to Depot 4 by Thursday 22 October.</p>
+      </ApprovalRequest>
+      {state === 'pending' ? null : (
+        <Button size="sm" variant="ghost" onClick={() => setState('pending')}>
+          Reset the example
+        </Button>
+      )}
+    </div>
+  )
+}
+
+<LiveApproval />
+```
+
+### Resolved
+
+```tsx
+<div className="flex w-full max-w-xl flex-col gap-3">
+  <ApprovalRequest title="Move the Friday pickup to Thursday?" state="approved" onApprove={() => {}} onReject={() => {}}>
+    Pickup at Depot 4, Thursday 08:00 instead of Friday 08:00.
+  </ApprovalRequest>
+  <ApprovalRequest title="Cancel order ORD-1182?" state="rejected" onApprove={() => {}} onReject={() => {}}>
+    Two replicas, already packed.
+  </ApprovalRequest>
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves to Approve, then Reject. |
+| `Enter` `Space` | Approves or rejects. Focus then moves to the status line that replaces the buttons. |
+
+## Do
+
+- Ask before every action that reaches outside the conversation: a message sent, a record changed, money spent.
+- Name the buttons for the action ("Send", "Don't send") when the title alone leaves any doubt.
+- Keep the decided request in the thread. It's the record of what was agreed.
+
+## Don't
+
+- Don't run the action before onApprove. The preview is a promise of what will happen, not a report.
+- Don't focus the Approve button when the request appears: someone in the middle of typing would approve it with their next Enter.
+- Don't summarise the preview. Show the email, the change, the amount.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<ApprovalRequest title="Send the email?" ...>An email to the depot lead.</ApprovalRequest>
+```
+
+Right:
+
+```tsx
+<ApprovalRequest title="Send this email to Ilse Varga?" ...><p>Subject: Thursday pickup</p><p>Hi Ilse, ...</p></ApprovalRequest>
+```
+
+A person can only approve what they can see. The preview is the content itself, not a summary of it.
+
+Wrong:
+
+```tsx
+{state === "pending" && <ApprovalRequest ... />}
+```
+
+Right:
+
+```tsx
+<ApprovalRequest state={state} ... />
+```
+
+Removing it from the page once it's decided drops focus back to the page and wipes the record of what was decided. The component swaps its own buttons for a status line instead.
+
+## Anatomy
+
+- **Section**: Named by the title. Outlined in the signal colour while pending, and a thin line once it's decided.
+- **Label**: "Needs your approval" with a shield icon while pending, then "Approval".
+- **Title**: The action as a question: "Send this order to Arad depot?"
+- **Preview**: Exactly what will happen, beside a thin line.
+- **Actions**: Approve (primary) and Reject (secondary). Neither has focus when the request appears.
+- **Status line**: Takes the place of the buttons: "Approved by you" or "Rejected". It has tabIndex -1 so it can receive focus from code, and focus moves here when the decision was made here.