@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/patterns/destructive-actions.md

@@ -0,0 +1,626 @@
+# Destructive Actions
+
+Match the safeguard on a destructive action to its impact and its reversibility.
+
+## Overview
+
+A destructive action removes something the reader may want back, such as a webhook, an API key, a team member, or a pending payment. Weigh each action on two axes:
+
+* **Reversible or Not:** Can the reader undo it or restore what was lost?
+* **Impact:** Does it affect one item, other people, or funds?
+
+Add friction in proportion to the risk. Too few safeguards lose data. Too many train readers to confirm without reading.
+
+## Structure
+
+1. **Trigger:** Names the action, such as Delete webhook, after the safe actions or at the end of a [Menu](/docs/components/menu).
+2. **Safeguard:** Undo, a confirmation, or a typed confirmation, chosen by risk.
+3. **Confirmation:** An [AlertDialog](/docs/components/alert-dialog) names the object, states the consequence, and repeats the verb on its button.
+4. **Result:** The item disappears, a [Toast](/docs/components/toast) confirms it, and focus moves to the list.
+
+```tsx
+import { AlertDialog, Button, ButtonGroup } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <AlertDialog.Root>
+      <AlertDialog.Trigger render={<Button />}>Delete webhook</AlertDialog.Trigger>
+      <AlertDialog.Popup>
+        <AlertDialog.Header>
+          <AlertDialog.Title>Delete this webhook?</AlertDialog.Title>
+          <AlertDialog.Description>
+            Tempo stops sending payment events to this endpoint. You can add it again later.
+          </AlertDialog.Description>
+        </AlertDialog.Header>
+        {/* Cancel comes first, so it takes focus on open and Enter by habit keeps the webhook. */}
+        <ButtonGroup>
+          <AlertDialog.Close render={<Button size="large" variant="secondary" />}>
+            Cancel
+          </AlertDialog.Close>
+          <AlertDialog.Close render={<Button size="large" />}>Delete webhook</AlertDialog.Close>
+        </ButtonGroup>
+      </AlertDialog.Popup>
+    </AlertDialog.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/DeleteWebhook.tsx)
+
+This reference layout uses [AlertDialog](/docs/components/alert-dialog) and [Button](/docs/components/button). Cancel comes first in the markup, so it takes focus when the dialog opens.
+
+## Guidelines
+
+### Match the Safeguard to the Risk
+
+Prefer Undo to confirmation wherever you can build it.
+
+* **Easy to Reverse (Toast):** Act at once and offer Undo, such as for a removed contact or an archived notification.
+* **Recoverable With Effort (AlertDialog):** Confirm first, and state how to restore it, such as for a webhook or a team member.
+* **Irreversible (AlertDialog):** Always confirm, and state that the action cannot be undone.
+* **Irreversible and Wide-Reaching (Type to confirm):** Ask the reader to type the object's name or authenticate again.
+
+Actions that move funds, such as a payment or a swap, use the review step as the confirmation (see [Payments](/docs/patterns/payments)). Do not add an [AlertDialog](/docs/components/alert-dialog) after a payment review, since a second prompt trains readers to dismiss prompts.
+
+### Name the Action and Its Consequence
+
+* **Title (Question):** Name the verb and the object, such as Revoke the Production key?
+* **Description (1 to 2 sentences):** State the consequence, including whether it is reversible. Do not soften it.
+* **Actions (secondary + primary):** Repeat the title's verb on the confirm button, in the [action order](/docs/patterns/forms#order-actions).
+
+**Do:** Name the object and the consequence, and repeat the verb on the button.
+
+```tsx
+/**
+ * Do example for "Name the Action and Its Consequence" on the Destructive Actions page.
+ * Name the object and the consequence, and repeat the verb on the button.
+ * @module
+ */
+import { Button, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="medium" {...styles.fill()}>
+      <div {...styles.copy()}>
+        <p {...styles.title()}>Revoke the Production key?</p>
+        <p {...styles.text()}>
+          Apps that use this key stop working immediately. You can't undo this.
+        </p>
+      </div>
+      <div {...styles.actions()}>
+        <Button size="small" variant="secondary">
+          Cancel
+        </Button>
+        <Button size="small">Revoke key</Button>
+      </div>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const actions = style({
+    columnGap: '8',
+    display: 'flex',
+    justifyContent: 'flex-end',
+    marginTop: '16',
+  })
+
+  export const copy = style({ display: 'grid', gap: '4' })
+
+  export const fill = style({ width: '100% !custom' })
+
+  export const text = style({ color: 'content.secondary', margin: '0', typography: 'body.b2' })
+
+  export const title = style({ margin: '0', typography: 'body.b1Strong' })
+}
+```
+
+**Don't:** Ask a bare Are you sure? with Yes and No buttons.
+
+```tsx
+/**
+ * Don't example for "Name the Action and Its Consequence" on the Destructive Actions page.
+ * Don't ask a bare Are you sure? with Yes and No buttons.
+ * @module
+ */
+import { Button, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="medium" {...styles.fill()}>
+      <div {...styles.copy()}>
+        <p {...styles.title()}>Are you sure?</p>
+        <p {...styles.text()}>This action can't be undone.</p>
+      </div>
+      <div {...styles.actions()}>
+        <Button size="small" variant="secondary">
+          No
+        </Button>
+        <Button size="small">Yes</Button>
+      </div>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const actions = style({
+    columnGap: '8',
+    display: 'flex',
+    justifyContent: 'flex-end',
+    marginTop: '16',
+  })
+
+  export const copy = style({ display: 'grid', gap: '4' })
+
+  export const fill = style({ width: '100% !custom' })
+
+  export const text = style({ color: 'content.secondary', margin: '0', typography: 'body.b2' })
+
+  export const title = style({ margin: '0', typography: 'body.b1Strong' })
+}
+```
+
+### Label Buttons With the Verb and Object
+
+Use the same specific verb in the trigger, the dialog title, and the confirm button. Show the amount for any action that moves funds.
+
+* **Delete:** The item is gone for good, and no one can restore it later.
+* **Remove:** The item still exists elsewhere, such as a member removed from a team.
+* **Revoke:** Access ends, such as an access key or an app's permission.
+* **Cancel Payment:** A pending transfer stops. Never write only "Cancel", the label that closes the dialog.
+
+### Start Focus on the Safe Choice
+
+`AlertDialog.Popup` focuses its first tabbable element on open. If that is the destructive button, pass a ref to the Cancel button as `initialFocus`. If the item and its trigger disappear, pass `finalFocus`.
+
+* **On Open (initialFocus):** Focus Cancel, so a habitual Enter keeps the data.
+* **After Removal (finalFocus):** Focus the next item or the list heading, not the body.
+
+### Type to Confirm Irreversible Actions
+
+```tsx
+import { AlertDialog, Badge, Button, ButtonGroup, Field, ListGroup, style, Surface, TextInput, Toast } from '@tempoxyz/ds'
+import { useState } from 'react'
+
+export const fill = true
+const key = 'Production'
+
+function KeyRow() {
+  const toast = Toast.useToast()
+  const [invalid, setInvalid] = useState(false)
+  const [open, setOpen] = useState(false)
+  const [pending, setPending] = useState(false)
+  const [revoked, setRevoked] = useState(false)
+  const [typed, setTyped] = useState('')
+
+  return (
+    <ListGroup.Root dividers={false}>
+      <ListGroup.Row>
+        <ListGroup.Info>
+          <ListGroup.Title>{key}</ListGroup.Title>
+          <ListGroup.Description>Last used 2 minutes ago</ListGroup.Description>
+        </ListGroup.Info>
+        {revoked ? (
+          <Badge>Revoked</Badge>
+        ) : (
+          <AlertDialog.Root
+            onOpenChange={(next) => {
+              setOpen(next)
+              setInvalid(false)
+              setTyped('')
+            }}
+            open={open}
+          >
+            <AlertDialog.Trigger render={<Button size="small" />}>Revoke key</AlertDialog.Trigger>
+            <AlertDialog.Popup size="medium">
+              <form
+                noValidate
+                onSubmit={(event) => {
+                  event.preventDefault()
+                  if (typed !== key) return setInvalid(true)
+
+                  setPending(true)
+                  setTimeout(() => {
+                    setPending(false)
+                    setOpen(false)
+                    setRevoked(true)
+                    toast.add({ intent: 'positive', title: `${key} key revoked` })
+                  }, 1000)
+                }}
+              >
+                <AlertDialog.Header>
+                  <AlertDialog.Title>Revoke the {key} key?</AlertDialog.Title>
+                  <AlertDialog.Description>
+                    Apps that use this key stop working immediately. You can't undo this.
+                  </AlertDialog.Description>
+                </AlertDialog.Header>
+                <AlertDialog.Body>
+                  <Field.Root disabled={pending} invalid={invalid}>
+                    <Field.Label>Type {key} to confirm</Field.Label>
+                    <TextInput.Group>
+                      <TextInput.Control
+                        autoComplete="off"
+                        onValueChange={(value) => {
+                          setTyped(value)
+                          if (invalid && value === key) setInvalid(false)
+                        }}
+                        spellCheck={false}
+                        value={typed}
+                      />
+                    </TextInput.Group>
+                    <Field.Error match={invalid}>Type {key} exactly as shown.</Field.Error>
+                  </Field.Root>
+                </AlertDialog.Body>
+                <ButtonGroup>
+                  <AlertDialog.Close
+                    disabled={pending}
+                    render={<Button size="large" variant="secondary" />}
+                  >
+                    Cancel
+                  </AlertDialog.Close>
+                  <Button loading={pending} size="large" type="submit">
+                    Revoke key
+                  </Button>
+                </ButtonGroup>
+              </form>
+            </AlertDialog.Popup>
+          </AlertDialog.Root>
+        )}
+      </ListGroup.Row>
+    </ListGroup.Root>
+  )
+}
+
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <Toast.Provider>
+        <Surface {...styles.card()}>
+          <Surface.Header>
+            <Surface.Title>API keys</Surface.Title>
+          </Surface.Header>
+          <KeyRow />
+        </Surface>
+        <Toast.Viewport />
+      </Toast.Provider>
+    </div>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    boxSizing: 'border-box',
+    maxWidth: '26rem !custom',
+    width: '100% !custom',
+  })
+
+  export const page = style({
+    backgroundColor: 'background.primary',
+    display: 'grid',
+    justifyItems: 'center',
+    padding: '16',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/RevokeKey.tsx)
+
+Any text other than Production shows an error.
+
+* **Ask for the Name (Field.Label):** Ask for the key's name, not DELETE, in a visible label.
+* **Keep the Button Enabled (Field.Error):** If the text does not match, show an error.
+
+**Do:** Ask for typed confirmation only for irreversible actions that affect other people or systems.
+
+```tsx
+/**
+ * Do example for "Type to Confirm Irreversible Actions" on the Destructive Actions page.
+ * Ask for typed confirmation only for irreversible actions that affect other people or systems.
+ * @module
+ */
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.fill()}>
+      <Field.Label>Type Production to confirm</Field.Label>
+      <TextInput.Group>
+        <TextInput.Control defaultValue="Produc" />
+      </TextInput.Group>
+      <Field.Description>Revoking this key stops every app that uses it.</Field.Description>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const fill = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Ask for typed confirmation on reversible actions, such as removing a contact.
+
+```tsx
+/**
+ * Don't example for "Type to Confirm Irreversible Actions" on the Destructive Actions page.
+ * Don't ask for typed confirmation on reversible actions, such as removing a contact.
+ * @module
+ */
+import { Button, Field, style, Surface, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="medium" {...styles.fill()}>
+      <div {...styles.copy()}>
+        <p {...styles.title()}>Remove Ada from contacts?</p>
+        <p {...styles.text()}>You can add Ada again later.</p>
+      </div>
+      <Field.Root {...styles.field()}>
+        <Field.Label>Type "Ada" to confirm</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control />
+        </TextInput.Group>
+      </Field.Root>
+      <div {...styles.actions()}>
+        <Button size="small" variant="secondary">
+          Cancel
+        </Button>
+        <Button size="small">Remove contact</Button>
+      </div>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const actions = style({
+    columnGap: '8',
+    display: 'flex',
+    justifyContent: 'flex-end',
+    marginTop: '16',
+  })
+
+  export const copy = style({ display: 'grid', gap: '4' })
+
+  export const field = style({ marginTop: '16' })
+
+  export const fill = style({ width: '100% !custom' })
+
+  export const text = style({ color: 'content.secondary', margin: '0', typography: 'body.b2' })
+
+  export const title = style({ margin: '0', typography: 'body.b1Strong' })
+}
+```
+
+### Offer Undo When You Can
+
+```tsx
+import { Button, Identicon, ListGroup, style, Surface, Toast } from '@tempoxyz/ds'
+import { useState } from 'react'
+
+export const fill = true
+type Contact = { address: string; name: string }
+
+const initial: readonly Contact[] = [
+  { address: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F', name: 'Ada' },
+  { address: '0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC', name: 'Payroll' },
+  { address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', name: 'Treasury' },
+]
+
+function Contacts() {
+  const toast = Toast.useToast()
+  const [contacts, setContacts] = useState(initial)
+
+  return (
+    <Surface {...styles.card()}>
+      <Surface.Header>
+        <Surface.Title>Contacts</Surface.Title>
+      </Surface.Header>
+      <ListGroup.Root>
+        {contacts.map((contact) => (
+          <ListGroup.Row key={contact.address}>
+            <Identicon address={contact.address} aria-hidden size="24" />
+            <ListGroup.Info>
+              <ListGroup.Title>{contact.name}</ListGroup.Title>
+              <ListGroup.Description>
+                {contact.address.slice(0, 6)}…{contact.address.slice(-4)}
+              </ListGroup.Description>
+            </ListGroup.Info>
+            <Button
+              aria-label={`Remove ${contact.name}`}
+              onClick={() => {
+                // Removing a contact is easy to reverse, so it happens at once with an Undo.
+                const index = contacts.indexOf(contact)
+                setContacts((current) => current.filter((item) => item !== contact))
+                toast.add({
+                  action: {
+                    label: 'Undo',
+                    onClick: () =>
+                      setContacts((current) => [
+                        ...current.slice(0, index),
+                        contact,
+                        ...current.slice(index),
+                      ]),
+                  },
+                  title: `${contact.name} removed`,
+                })
+              }}
+              size="small"
+              variant="tertiary"
+            >
+              Remove
+            </Button>
+          </ListGroup.Row>
+        ))}
+      </ListGroup.Root>
+    </Surface>
+  )
+}
+
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <Toast.Provider>
+        <Contacts />
+        <Toast.Viewport />
+      </Toast.Provider>
+    </div>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    boxSizing: 'border-box',
+    maxWidth: '26rem !custom',
+    width: '100% !custom',
+  })
+
+  export const page = style({
+    backgroundColor: 'background.primary',
+    display: 'grid',
+    justifyItems: 'center',
+    padding: '16',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/RemoveContact.tsx)
+
+Undo in the [Toast](/docs/components/toast) restores the contact in place.
+
+* **Skip the Confirmation (action):** If an action is easy to reverse, run it at once and offer Undo in a toast.
+* **Keep Another Way Back:** A toast dismisses itself, so keep another way back, such as adding the contact again.
+
+### Save the Filled Button for the Decision
+
+Give a reversible removal in a list a `tertiary` button, and keep the `primary` button for the confirm step. In a [Menu](/docs/components/menu), give destructive items `intent="negative"` and place them last, after a `Menu.Separator`.
+
+**Do:** Use `tertiary` buttons for a reversible removal, and keep `primary` for the confirm step.
+
+```tsx
+/**
+ * Do example for "Save the Filled Button for the Decision" on the Destructive Actions page.
+ * Use `tertiary` buttons for a reversible removal, and keep `primary` for the confirm step.
+ * @module
+ */
+import { Button, ListGroup, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ListGroup.Root {...styles.fill()}>
+      {['Ada', 'Payroll', 'Treasury'].map((name) => (
+        <ListGroup.Row key={name}>
+          <ListGroup.Label>{name}</ListGroup.Label>
+          <Button size="small" variant="tertiary">
+            Remove
+          </Button>
+        </ListGroup.Row>
+      ))}
+    </ListGroup.Root>
+  )
+}
+
+namespace styles {
+  export const fill = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Fill a list with `primary` buttons, which hides the one that matters.
+
+```tsx
+/**
+ * Don't example for "Save the Filled Button for the Decision" on the Destructive Actions page.
+ * Don't fill a list with `primary` buttons, which hides the one that matters.
+ * @module
+ */
+import { Button, ListGroup, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ListGroup.Root {...styles.fill()}>
+      {['Ada', 'Payroll', 'Treasury'].map((name) => (
+        <ListGroup.Row key={name}>
+          <ListGroup.Label>{name}</ListGroup.Label>
+          <Button size="small">Delete</Button>
+        </ListGroup.Row>
+      ))}
+    </ListGroup.Root>
+  )
+}
+
+namespace styles {
+  export const fill = style({ width: '100% !custom' })
+}
+```
+
+### Warn Before the Action
+
+If the consequence is not obvious, state it in an [Alert](/docs/components/alert) beside the button. Readers who skim past dialogs still read it.
+
+**Do:** State the specific consequence next to the action.
+
+```tsx
+<Alert intent="warning">
+  <Alert.Icon />
+  <Alert.Content>Revoking this key stops 3 apps from sending payments.</Alert.Content>
+</Alert>
+<Inline>
+  <Button>Revoke key</Button>
+</Inline>
+```
+
+**Don't:** Write an alarming warning that names no consequence.
+
+```tsx
+<Alert intent="negative">
+  <Alert.Icon />
+  <Alert.Content>Warning! Be careful!</Alert.Content>
+</Alert>
+<Inline>
+  <Button>Revoke key</Button>
+</Inline>
+```
+
+## States
+
+* **Loading (loading):** Confirm shows progress, Cancel is disabled, and the dialog stays open until the request ends.
+* **Error:** Keep the dialog open and state the failure in it, so the reader can try again.
+* **Empty:** After the last item goes, the list shows its first use [empty state](/docs/patterns/empty-states).
+* **Disabled:** If the reader lacks permission, state who can act instead of a silent disabled button.
+
+## Accessibility
+
+* **Named Dialogs (alertdialog):** Always include the title and description, which name the popup.
+* **Escape Cancels (Escape):** Closes the dialog without running the action, as a close button does.
+* **Specific Trigger Names:** Give each repeated trigger a specific name, such as Remove Ada.
+* **Undo Toasts (F6):** Toasts are announced and F6 focuses them. Hover, focus, or a background window pauses timers.
+
+## Related
+
+[AlertDialog](/docs/components/alert-dialog)
+
+Use for confirmations.
+
+[Button](/docs/components/button)
+
+Use for the confirm and cancel actions.
+
+[Toast](/docs/components/toast)
+
+Use for Undo.
+
+[Menu](/docs/components/menu)
+
+Use for destructive items in a menu.
+
+[Forms](/docs/patterns/forms)
+
+Covers typed input and action order.
+
+[Payments](/docs/patterns/payments)
+
+Covers reviewing transfers.