@tempoxyz/ds 0.3.9 → 0.3.11

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

@@ -0,0 +1,631 @@
+# AlertDialog
+
+Asks you to confirm a critical action before it happens.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/AlertDialog.tsx)
+
+## Overview
+
+A modal confirmation that blocks the page until the user decides. It never closes on an outside press. It takes the parts and the `small` size of a [Dialog](/docs/components/dialog). Reserve it for decisions that need an explicit answer.
+
+## Examples
+
+### Basic
+
+```tsx
+import { AlertDialog, Button, ButtonGroup } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <AlertDialog.Root>
+      <AlertDialog.Trigger render={<Button />}>Delete key</AlertDialog.Trigger>
+      <AlertDialog.Popup>
+        <AlertDialog.Header>
+          <AlertDialog.Title>Delete this key?</AlertDialog.Title>
+          <AlertDialog.Description>
+            Apps that use this key stop working immediately. You cannot undo this.
+          </AlertDialog.Description>
+        </AlertDialog.Header>
+        <ButtonGroup>
+          <AlertDialog.Close render={<Button size="large" variant="secondary" />}>
+            Cancel
+          </AlertDialog.Close>
+          <AlertDialog.Close render={<Button size="large" variant="danger" />}>
+            Delete key
+          </AlertDialog.Close>
+        </ButtonGroup>
+      </AlertDialog.Popup>
+    </AlertDialog.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/AlertDialog/Basic.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { AlertDialog, ButtonGroup } from '@tempoxyz/ds'
+
+<AlertDialog.Root>
+  <AlertDialog.Trigger />
+  <AlertDialog.Popup>
+    <AlertDialog.Header>
+      <AlertDialog.Title />
+      <AlertDialog.Description />
+    </AlertDialog.Header>
+    <AlertDialog.Body />
+    <ButtonGroup>
+      <AlertDialog.Close />
+    </ButtonGroup>
+  </AlertDialog.Popup>
+</AlertDialog.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Confirm an action you can't undo, such as Revoke key, Delete webhook, or Remove passkey.
+* Ask before discarding unsaved work, such as Discard changes? on a settings page with edits.
+
+### When Not to Use
+
+* Use a [Dialog](/docs/components/dialog) for a task with fields, or to review a payment before sending it.
+* For reversible actions, such as archiving an address, act at once and offer Undo in a [Toast](/docs/components/toast). The toast dismisses itself, so keep another way to restore the item.
+* Use an [Alert](/docs/components/alert) or [Banner](/docs/components/banner) for a warning that needs no decision.
+* Use a [Toast](/docs/components/toast) to report that an action finished.
+
+### Focus the Safe Action
+
+Opening focuses the first tabbable element in the popup. Place Cancel first in the DOM, or pass its ref to `initialFocus` on `AlertDialog.Popup`, so an Enter press right after opening cancels.
+
+**Do:** Start focus on Cancel.
+
+```tsx
+/** Do example for "Focus the Safe Action" on the AlertDialog page: start focus on Cancel. @module */
+import { Button, style } from '@tempoxyz/ds'
+import { Focus } from '../../../components/mdx/Access.js'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.popup()}>
+      <span {...styles.title()}>Delete this webhook?</span>
+      <p {...styles.description()}>
+        Payment events stop reaching api.acme.com/hooks. You can’t undo this.
+      </p>
+      <div {...styles.actions()}>
+        <Focus>
+          <Button size="small" variant="secondary">
+            Cancel
+          </Button>
+        </Focus>
+        <Button size="small">Delete webhook</Button>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const actions = style({
+    alignItems: 'center',
+    columnGap: '8',
+    display: 'flex',
+    justifyContent: 'flex-end',
+    marginTop: '16',
+  })
+
+  export const description = style({
+    color: 'content.secondary',
+    margin: '0 !custom',
+    typography: 'body.b2',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexDirection: 'column',
+    padding: '24',
+    rowGap: '8',
+    width: '17rem !custom',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
+}
+```
+
+**Don't:** Start focus on the destructive action, where one Enter press confirms it.
+
+```tsx
+/**
+ * Don't example for "Focus the Safe Action" on the AlertDialog page.
+ * Don't start focus on the destructive action, where one Enter press confirms it.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+import { Focus } from '../../../components/mdx/Access.js'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.popup()}>
+      <span {...styles.title()}>Delete this webhook?</span>
+      <p {...styles.description()}>
+        Payment events stop reaching api.acme.com/hooks. You can’t undo this.
+      </p>
+      <div {...styles.actions()}>
+        <Button size="small" variant="secondary">
+          Cancel
+        </Button>
+        <Focus>
+          <Button size="small">Delete webhook</Button>
+        </Focus>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const actions = style({
+    alignItems: 'center',
+    columnGap: '8',
+    display: 'flex',
+    justifyContent: 'flex-end',
+    marginTop: '16',
+  })
+
+  export const description = style({
+    color: 'content.secondary',
+    margin: '0 !custom',
+    typography: 'body.b2',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexDirection: 'column',
+    padding: '24',
+    rowGap: '8',
+    width: '17rem !custom',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
+}
+```
+
+### Always Offer Cancel
+
+Only Escape, `closeButton` and `AlertDialog.Close` close the dialog, so render a Cancel button with `AlertDialog.Close`.
+
+**Do:** Pair the confirm button with Cancel.
+
+```tsx
+/** Do example for "Always Offer Cancel" on the AlertDialog page: pair the confirm button with Cancel. @module */
+import { Button, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.popup()}>
+      <span {...styles.title()}>Revoke this API key?</span>
+      <p {...styles.description()}>
+        Apps that use the Production server key stop working immediately. You can’t undo this.
+      </p>
+      <div {...styles.actions()}>
+        <Button size="small" variant="secondary">
+          Cancel
+        </Button>
+        <Button size="small">Revoke key</Button>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const actions = style({
+    columnGap: '8',
+    display: 'flex',
+    justifyContent: 'flex-end',
+    marginTop: '16',
+  })
+
+  export const description = style({
+    color: 'content.secondary',
+    margin: '0 !custom',
+    typography: 'body.b2',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexDirection: 'column',
+    padding: '24',
+    rowGap: '8',
+    width: '17rem !custom',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
+}
+```
+
+**Don't:** Render the confirm button alone. An outside press doesn't close the dialog.
+
+```tsx
+/**
+ * Don't example for "Always Offer Cancel" on the AlertDialog page.
+ * Don't render the confirm button alone. An outside press doesn't close the dialog.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.popup()}>
+      <span {...styles.title()}>Revoke this API key?</span>
+      <p {...styles.description()}>
+        Apps that use the Production server key stop working immediately. You can’t undo this.
+      </p>
+      <div {...styles.actions()}>
+        <Button size="small">Revoke key</Button>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const actions = style({
+    alignItems: 'center',
+    columnGap: '8',
+    display: 'flex',
+    justifyContent: 'flex-end',
+    marginTop: '16',
+  })
+
+  export const description = style({
+    color: 'content.secondary',
+    margin: '0 !custom',
+    typography: 'body.b2',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexDirection: 'column',
+    padding: '24',
+    rowGap: '8',
+    width: '17rem !custom',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
+}
+```
+
+### Show Progress on the Confirm Button
+
+If the action waits on the network, such as revoking a key:
+
+1. Render the confirm button without `AlertDialog.Close`, and control `open` on `AlertDialog.Root`.
+2. Set `loading` while the request runs.
+3. Close the dialog on success. Show any error inside the dialog.
+
+**Do:** Set `loading` on the confirm button and keep the dialog open.
+
+```tsx
+/**
+ * Do example for "Show Progress on the Confirm Button" on the AlertDialog page.
+ * Set `loading` on the confirm button and keep the dialog open.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.popup()}>
+      <span {...styles.title()}>Revoke this API key?</span>
+      <p {...styles.description()}>
+        Apps that use the Production server key stop working immediately. You can’t undo this.
+      </p>
+      <div {...styles.actions()}>
+        <Button size="small" variant="secondary">
+          Cancel
+        </Button>
+        <Button size="small" loading>
+          Revoke key
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const actions = style({
+    alignItems: 'center',
+    columnGap: '8',
+    display: 'flex',
+    justifyContent: 'flex-end',
+    marginTop: '16',
+  })
+
+  export const description = style({
+    color: 'content.secondary',
+    margin: '0 !custom',
+    typography: 'body.b2',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexDirection: 'column',
+    padding: '24',
+    rowGap: '8',
+    width: '17rem !custom',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
+}
+```
+
+**Don't:** Add a separate spinner and leave the buttons active.
+
+```tsx
+/**
+ * Don't example for "Show Progress on the Confirm Button" on the AlertDialog page.
+ * Don't add a separate spinner and leave the buttons active.
+ * @module
+ */
+import { Button, Spinner, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.popup()}>
+      <span {...styles.title()}>Revoke this API key?</span>
+      <p {...styles.description()}>
+        Apps that use the Production server key stop working immediately. You can’t undo this.
+      </p>
+      <div {...styles.actions()}>
+        <Spinner aria-label="Revoking key" />
+        <Button size="small" variant="secondary">
+          Cancel
+        </Button>
+        <Button size="small">Revoke key</Button>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const actions = style({
+    alignItems: 'center',
+    columnGap: '8',
+    display: 'flex',
+    justifyContent: 'flex-end',
+    marginTop: '16',
+  })
+
+  export const description = style({
+    color: 'content.secondary',
+    margin: '0 !custom',
+    typography: 'body.b2',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexDirection: 'column',
+    padding: '24',
+    rowGap: '8',
+    width: '17rem !custom',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
+}
+```
+
+## Content
+
+### Ask a Specific Question
+
+Write the title as one question that names the action and its object, such as Revoke this API key?
+
+### State the Consequence
+
+Always include an `AlertDialog.Description`. Say what stops working, then whether it can be recovered, without repeating the title.
+
+### Repeat the Action Verb on the Confirm Button
+
+Label the confirm button with the verb from the trigger and title, such as Revoke key after Revoke this API key?
+
+**Do:** Repeat the action's verb on the confirm button, such as Revoke key.
+
+```tsx
+/** Do example for "Always Offer Cancel" on the AlertDialog page: pair the confirm button with Cancel. @module */
+import { Button, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.popup()}>
+      <span {...styles.title()}>Revoke this API key?</span>
+      <p {...styles.description()}>
+        Apps that use the Production server key stop working immediately. You can’t undo this.
+      </p>
+      <div {...styles.actions()}>
+        <Button size="small" variant="secondary">
+          Cancel
+        </Button>
+        <Button size="small">Revoke key</Button>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const actions = style({
+    columnGap: '8',
+    display: 'flex',
+    justifyContent: 'flex-end',
+    marginTop: '16',
+  })
+
+  export const description = style({
+    color: 'content.secondary',
+    margin: '0 !custom',
+    typography: 'body.b2',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexDirection: 'column',
+    padding: '24',
+    rowGap: '8',
+    width: '17rem !custom',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
+}
+```
+
+**Don't:** Ask Are you sure? or label the confirm button OK.
+
+```tsx
+/**
+ * Don't example for "Repeat the Action Verb on the Confirm Button" on the AlertDialog page.
+ * Don't ask Are you sure? or label the confirm button OK.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.popup()}>
+      <span {...styles.title()}>Are you sure?</span>
+      <p {...styles.description()}>This action cannot be undone.</p>
+      <div {...styles.actions()}>
+        <Button size="small" variant="secondary">
+          Cancel
+        </Button>
+        <Button size="small">OK</Button>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const actions = style({
+    columnGap: '8',
+    display: 'flex',
+    justifyContent: 'flex-end',
+    marginTop: '16',
+  })
+
+  export const description = style({
+    color: 'content.secondary',
+    margin: '0 !custom',
+    typography: 'body.b2',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexDirection: 'column',
+    padding: '24',
+    rowGap: '8',
+    width: '17rem !custom',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
+}
+```
+
+### Avoid Two Cancels
+
+If the action cancels something, such as a scheduled payment, label the pair Keep payment and Cancel payment. A plain Cancel beside Cancel payment is ambiguous.
+
+## Accessibility
+
+Follows the [WAI-ARIA alert dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/).
+
+### Semantics
+
+* **AlertDialog.Trigger (button):** Announces the dialog and whether it is open.
+* **AlertDialog.Popup (alertdialog):** The dialog is always modal.
+* **AlertDialog.Title (h2):** Names the popup. Include it in every alert dialog.
+* **AlertDialog.Description (aria-describedby):** Describes the popup. Include it in every alert dialog.
+* **Page Behind (inert):** The page behind ignores input and stops scrolling.
+* **Reduced Motion (prefers-reduced-motion):** The dialog fades in and out without scaling or sliding.
+
+### Keyboard
+
+* **Open or Activate (Enter or Space):** Opens the dialog from the trigger, and activates the focused action.
+* **Move to the Next Action (Tab):** Moves focus to the next action, wrapping from the last to the first.
+* **Move to the Previous Action (Shift+Tab):** Moves focus to the previous action, wrapping from the first to the last.
+* **Close the Alert Dialog (Escape):** Closes the dialog and returns focus to the trigger that opened it.
+
+### Focus
+
+* **Opening:** Focuses the first tabbable element, or the popup on touch. Pass `initialFocus` to start on Cancel.
+* **Trapping:** Focus stays inside the popup while it is open, and Tab never leaves it.
+* **Outside Press:** Does not close the popup. Only Escape, `closeButton` or `AlertDialog.Close` closes it.
+* **Closing:** Focus returns to the trigger. Pass `finalFocus` when the trigger is gone, such as after deleting its row.
+
+### Your Responsibilities
+
+* **Render a Title and Description:** Always render both in `AlertDialog.Header`. Without them, the popup has no name or description.
+
+## Related
+
+[Dialog](/docs/components/dialog)
+
+Use for focused tasks with fields.
+
+[Button](/docs/components/button)
+
+Use for each action in the footer.
+
+[ButtonGroup](/docs/components/button-group)
+
+Use for the Cancel and confirm actions.
+
+[Menu](/docs/components/menu)
+
+Use for opening a confirmation from a destructive item.
+
+[Toast](/docs/components/toast)
+
+Use for Undo after reversible actions.
+
+[Destructive Actions](/docs/patterns/destructive-actions)
+
+Covers deleting and revoking.