@tempoxyz/ds 0.3.10 → 0.3.11

package/dist/docs/patterns/feedback-and-status.md

@@ -0,0 +1,518 @@
+# Feedback and Status
+
+Name each system state once, and choose [Toast](/docs/components/toast), [Alert](/docs/components/alert), or [Banner](/docs/components/banner) by urgency.
+
+## Overview
+
+Every action needs a response, and every change of state needs a visible result. Two questions pick the component: what the message describes (one action, one section, or the whole product), and how soon the reader must act. Match the weight of the message to the weight of the event, since overused loud feedback trains people to ignore it.
+
+[Loading](/docs/patterns/loading) and [Empty States](/docs/patterns/empty-states) cover the states before content arrives.
+
+## Components
+
+| Component | Scope | Lifetime | Typical use |
+| --- | --- | --- | --- |
+| [Field](/docs/components/field) `Field.Error` | One value | Until corrected | Enter 1,250.00 USDC or less |
+| [Badge](/docs/components/badge), or `status` on a [Table](/docs/components/table) cell | One record | While the state holds | A transaction or a webhook delivery |
+| [Toast](/docs/components/toast) | One action | Seconds | The result of an action the reader started |
+| [Alert](/docs/components/alert) | One section | Until resolved | Couldn't load older activity |
+| [Banner](/docs/components/banner) | Whole product | Until resolved or dismissed | Testnet faucets are paused for maintenance |
+| [AlertDialog](/docs/components/alert-dialog) | One decision | Until answered | Revoke this API key? |
+
+* **Toast:** Dismisses itself after five seconds by default, so never put information in it that the reader must keep or act on. Offer its action elsewhere too. Set `timeout: 0` for a toast with Undo, and show critical errors inline instead.
+* **Alert:** Sits beside the decision it affects, with one action at most. Do not use it for a passing confirmation such as Address copied.
+* **Banner:** Describes the product, not one piece of content. Show at most one at a time, and never for a routine confirmation.
+
+## State Vocabulary
+
+Each state has one word, one component, and one icon.
+
+* **Unavailable (No icon):** The value does not exist now, such as a missing price. Show Unavailable in gray in its place.
+* **Couldn't Load (AlertCircle):** A request for the region's content failed. Use a negative [Alert](/docs/components/alert) or an [Empty](/docs/components/empty) state, with a retry.
+* **Pending (Pending):** Submitted and waiting for inclusion in a block. Use a [Badge](/docs/components/badge) with the icon.
+* **Confirmed (CheckCircle):** Included in a block. Use a [Badge](/docs/components/badge) with the icon.
+* **Failed (AlertCircle):** Rejected or reverted by the network. Use a [Badge](/docs/components/badge) with the icon, and the reason nearby.
+* **Amount Hidden (EyeOff):** The reader hid amounts on this device. Show a fixed mask, read aloud as Amount hidden.
+
+In a [Table](/docs/components/table), set `status` on `Table.Cell` to `warning`, `positive`, or `negative` for Pending, Confirmed, and Failed. The cell colors its text, so keep the same word.
+
+```tsx
+import { Alert, Badge, ListGroup, style, Surface } from '@tempoxyz/ds'
+import { AlertCircle, CheckCircle, Pending } from '@tempoxyz/ds/icons'
+
+export const fill = true
+function Balances() {
+  return (
+    <Surface>
+      <Surface.Header>
+        <Surface.Title>Balances</Surface.Title>
+      </Surface.Header>
+      <ListGroup.Root>
+        <ListGroup.Row>
+          <ListGroup.Info>
+            <ListGroup.Title>USDC</ListGroup.Title>
+            <ListGroup.Description>1,000.00 USDC</ListGroup.Description>
+          </ListGroup.Info>
+          $1,000.00
+        </ListGroup.Row>
+        <ListGroup.Row>
+          <ListGroup.Info>
+            <ListGroup.Title>EURC</ListGroup.Title>
+            <ListGroup.Description>500.00 EURC</ListGroup.Description>
+          </ListGroup.Info>
+          <span {...styles.muted()}>Unavailable</span>
+        </ListGroup.Row>
+      </ListGroup.Root>
+    </Surface>
+  )
+}
+
+function Activity() {
+  return (
+    <Surface>
+      <Surface.Header>
+        <Surface.Title>Activity</Surface.Title>
+      </Surface.Header>
+      <ListGroup.Root>
+        <ListGroup.Row>
+          <ListGroup.Info>
+            <ListGroup.Title>Sent 25.00 USDC</ListGroup.Title>
+            <ListGroup.Description>To 0x71C7…976F</ListGroup.Description>
+          </ListGroup.Info>
+          <Badge>
+            <Pending />
+            Pending
+          </Badge>
+        </ListGroup.Row>
+        <ListGroup.Row>
+          <ListGroup.Info>
+            <ListGroup.Title>Received 120.00 USDC</ListGroup.Title>
+            <ListGroup.Description>From 0x3C44…93BC</ListGroup.Description>
+          </ListGroup.Info>
+          <Badge>
+            <CheckCircle />
+            Confirmed
+          </Badge>
+        </ListGroup.Row>
+        <ListGroup.Row>
+          <ListGroup.Info>
+            <ListGroup.Title>Sent 40.00 USDC</ListGroup.Title>
+            <ListGroup.Description>
+              Not enough USDC left to cover the network fee
+            </ListGroup.Description>
+          </ListGroup.Info>
+          <Badge>
+            <AlertCircle />
+            Failed
+          </Badge>
+        </ListGroup.Row>
+      </ListGroup.Root>
+      <Alert intent="negative" {...styles.alert()}>
+        <Alert.Icon />
+        <Alert.Content>
+          Couldn't load older activity.
+          <Alert.Action>Try again</Alert.Action>
+        </Alert.Content>
+      </Alert>
+    </Surface>
+  )
+}
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      <Balances />
+      <Activity />
+    </div>
+  )
+}
+
+namespace styles {
+  export const alert = style({ marginBlockStart: '16' })
+
+  export const grid = style({
+    alignItems: 'start',
+    backgroundColor: 'background.primary',
+    display: 'grid',
+    gap: '16',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(18rem, 1fr)) !custom',
+    padding: '16',
+  })
+
+  export const muted = style({ color: 'content.secondary', typography: 'body.b2' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/StatusVocabulary.tsx)
+
+This reference layout shows five of the states, built from [Surface](/docs/components/surface), [ListGroup](/docs/components/list-group), [Badge](/docs/components/badge), and [Alert](/docs/components/alert).
+
+* **Unavailable:** Keep the rest of the row, since the token balance is still known. If the reason helps the reader act, state it nearby.
+* **Couldn't load:** Name the content, such as Couldn't load activity. If part of a region failed, keep what loaded and use an alert. If all of it failed, use an [empty state](/docs/patterns/empty-states) with Try again.
+* **Pending:** Keep the transaction in activity with its amount and recipient, from submission until inclusion in a block (see [Loading](/docs/patterns/loading#show-pending-transactions)).
+* **Failed:** Keep the row in activity and state the reason (see [Errors and Validation](/docs/patterns/errors-and-validation#explain-transaction-failures)).
+* **Amount hidden:** Mask every amount, as [Blockchain Values](/docs/patterns/blockchain-values#hidden-amounts) describes.
+
+## Urgency
+
+Rank each message before you choose how to show it.
+
+* **Low (Toast):** An expected confirmation, such as Address copied.
+* **Medium (Alert):** Information that affects a decision. Place it beside the decision.
+* **High (Banner or Alert):** A condition that blocks work or puts funds at risk. Keep it until the condition clears.
+* **Critical (AlertDialog):** A decision the reader must make first (see [Destructive Actions](/docs/patterns/destructive-actions)).
+
+## Intent
+
+Choose the intent from the meaning of the message. Keep it consistent across [Toast](/docs/components/toast), [Alert](/docs/components/alert), and [Banner](/docs/components/banner).
+
+* **Neutral (neutral):** General information with no judgment.
+* **Tip (tip):** Helpful context that does not need action.
+* **Positive (positive):** A successful result, such as Confirmed.
+* **Warning (warning):** A risk to weigh before continuing, and Pending.
+* **Negative (negative):** A failure or a blocked task.
+
+## Guidelines
+
+### Choose a Channel by Scope
+
+Show each message in the smallest region it describes, from the [Components](#components) table.
+
+**Do:** Report a problem with one section in an alert inside that section.
+
+```tsx
+/**
+ * Do example for "Choose a Channel by Scope" on the Feedback and Status page.
+ * Report a problem with one section in an alert inside that section.
+ * @module
+ */
+import { Alert, ListGroup, Stack, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="small" {...styles.fill()}>
+      <Stack gap="12">
+        <Surface.Title>Activity</Surface.Title>
+        <ListGroup.Root>
+          <ListGroup.Row>
+            <ListGroup.Info>
+              <ListGroup.Title>Received 120.00 USDC</ListGroup.Title>
+              <ListGroup.Description>From 0x8f3a…12c4</ListGroup.Description>
+            </ListGroup.Info>
+          </ListGroup.Row>
+        </ListGroup.Root>
+        <Alert intent="negative">
+          <Alert.Icon />
+          <Alert.Content>
+            Couldn't load older activity.
+            <Alert.Action>Try again</Alert.Action>
+          </Alert.Content>
+        </Alert>
+      </Stack>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const fill = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Use a page-wide banner for a problem with one section.
+
+```tsx
+/**
+ * Don't example for "Choose a Channel by Scope" on the Feedback and Status page.
+ * Don't use a page-wide banner for a problem with one section.
+ * @module
+ */
+import { Banner, ListGroup, Stack, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Stack gap="16" {...styles.fill()}>
+      <Banner intent="negative">
+        <Banner.Content>Couldn't load older activity.</Banner.Content>
+        <Banner.Action>Try again</Banner.Action>
+      </Banner>
+      <Surface size="small">
+        <Stack gap="12">
+          <Surface.Title>Activity</Surface.Title>
+          <ListGroup.Root>
+            <ListGroup.Row>
+              <ListGroup.Info>
+                <ListGroup.Title>Received 120.00 USDC</ListGroup.Title>
+                <ListGroup.Description>From 0x8f3a…12c4</ListGroup.Description>
+              </ListGroup.Info>
+            </ListGroup.Row>
+          </ListGroup.Root>
+        </Stack>
+      </Surface>
+    </Stack>
+  )
+}
+
+namespace styles {
+  export const fill = style({ width: '100% !custom' })
+}
+```
+
+### Pair Color With Text and an Icon
+
+Each state has a word and an icon as well as a color, so it reads the same in grayscale, in high contrast, and on a screen reader.
+
+**Do:** Show the state's word, with its icon before the text.
+
+```tsx
+/**
+ * Do example for "Pair Color With Text and an Icon" on the Feedback and Status page.
+ * Show the state's word, with its icon before the text.
+ * @module
+ */
+import { Badge, style } from '@tempoxyz/ds'
+import { AlertCircle, CheckCircle, Pending } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Badge>
+        <Pending />
+        Pending
+      </Badge>
+      <Badge>
+        <CheckCircle />
+        Confirmed
+      </Badge>
+      <Badge>
+        <AlertCircle />
+        Failed
+      </Badge>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
+}
+```
+
+**Don't:** Use colored dots or tints alone to show a state.
+
+```tsx
+/**
+ * Don't example for "Pair Color With Text and an Icon" on the Feedback and Status page.
+ * Don't use colored dots or tints alone to show a state.
+ * @module
+ */
+import { Alert, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {(['warning', 'positive', 'negative'] as const).map((intent) => (
+        <Alert intent={intent} key={intent}>
+          <Alert.Icon />
+        </Alert>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
+}
+```
+
+### Use the Same Word Everywhere
+
+Use the vocabulary words for every product and transaction type, including payments, deposits, and swaps. Do not swap in synonyms such as Success, Settled, Complete, Processing, or Error.
+
+**Do:** Use Pending and Confirmed for every transaction type.
+
+```tsx
+/**
+ * Do example for "Use the Same Word Everywhere" on the Feedback and Status page.
+ * Use Pending and Confirmed for every transaction type.
+ * @module
+ */
+import { Badge, ListGroup, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ListGroup.Root {...styles.fill()}>
+      <ListGroup.Row>
+        <ListGroup.Label>Payment</ListGroup.Label>
+        <Badge>Confirmed</Badge>
+      </ListGroup.Row>
+      <ListGroup.Row>
+        <ListGroup.Label>Deposit</ListGroup.Label>
+        <Badge>Confirmed</Badge>
+      </ListGroup.Row>
+      <ListGroup.Row>
+        <ListGroup.Label>Swap</ListGroup.Label>
+        <Badge>Pending</Badge>
+      </ListGroup.Row>
+    </ListGroup.Root>
+  )
+}
+
+namespace styles {
+  export const fill = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Describe the same state with different words and colors.
+
+```tsx
+/**
+ * Don't example for "Use the Same Word Everywhere" on the Feedback and Status page.
+ * Don't describe the same state with different words and colors.
+ * @module
+ */
+import { Badge, ListGroup, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ListGroup.Root {...styles.fill()}>
+      <ListGroup.Row>
+        <ListGroup.Label>Payment</ListGroup.Label>
+        <Badge>Success!</Badge>
+      </ListGroup.Row>
+      <ListGroup.Row>
+        <ListGroup.Label>Deposit</ListGroup.Label>
+        <Badge>Settled</Badge>
+      </ListGroup.Row>
+      <ListGroup.Row>
+        <ListGroup.Label>Swap</ListGroup.Label>
+        <Badge>Processing</Badge>
+      </ListGroup.Row>
+    </ListGroup.Root>
+  )
+}
+
+namespace styles {
+  export const fill = style({ width: '100% !custom' })
+}
+```
+
+### Never Show a Stand-In as a Real Value
+
+A zero, a dash, or a stale number reads as a real measurement. If there is no value, show Unavailable. If the request failed, show Couldn't load.
+
+**Do:** Show Unavailable when a value has no source.
+
+```tsx
+/**
+ * Do example for "Never Show a Stand-In as a Real Value" on the Feedback and Status page.
+ * Show Unavailable when a value has no source.
+ * @module
+ */
+import { ListGroup, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ListGroup.Root {...styles.fill()}>
+      <ListGroup.Row>
+        <ListGroup.Info>
+          <ListGroup.Title>EURC</ListGroup.Title>
+          <ListGroup.Description>500.00 EURC</ListGroup.Description>
+        </ListGroup.Info>
+        <span {...styles.muted()}>Unavailable</span>
+      </ListGroup.Row>
+    </ListGroup.Root>
+  )
+}
+
+namespace styles {
+  export const fill = style({ width: '100% !custom' })
+
+  export const muted = style({ color: 'content.secondary', typography: 'body.b2' })
+}
+```
+
+**Don't:** Show $0.00 for a price you don't know.
+
+```tsx
+/**
+ * Don't example for "Never Show a Stand-In as a Real Value" on the Feedback and Status page.
+ * Don't show $0.00 for a price you don't know.
+ * @module
+ */
+import { ListGroup, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ListGroup.Root {...styles.fill()}>
+      <ListGroup.Row>
+        <ListGroup.Info>
+          <ListGroup.Title>EURC</ListGroup.Title>
+          <ListGroup.Description>500.00 EURC</ListGroup.Description>
+        </ListGroup.Info>
+        $0.00
+      </ListGroup.Row>
+    </ListGroup.Root>
+  )
+}
+
+namespace styles {
+  export const fill = style({ width: '100% !custom' })
+}
+```
+
+## States
+
+* **Default:** No message. Records show their status badge.
+* **Error:** Couldn't load for a failed request, Failed for a rejected transaction, and a field error for a bad value.
+* **Empty:** An empty state that states the cause (see [Empty States](/docs/patterns/empty-states)).
+* **Success:** Confirmed on the record, and a positive [Toast](/docs/components/toast) for a finished action.
+
+## Content
+
+* **Outcome First:** Lead with the result, such as "Payment sent", then add detail.
+* **Tense:** Use the past tense for finished actions and the present tense for ongoing state.
+* **One Sentence:** Keep toasts and alerts to one sentence.
+
+## Accessibility
+
+* **Toasts (F6):** Toasts are announced, and hover or focus pauses their timers. Pass `priority: 'high'` only for urgent toasts.
+* **Alerts (alert or status):** Warning and negative alerts interrupt the screen reader. Info and positive alerts announce politely.
+* **Banners (role):** A [Banner](/docs/components/banner) renders no live region. Add `role="status"` or `role="alert"` only if it renders after page load.
+* **Status Changes:** A change from Pending to Confirmed is not announced. If the reader started the transaction in this session, use a [Toast](/docs/components/toast).
+
+## Related
+
+[Badge](/docs/components/badge)
+
+Use for record status.
+
+[Alert](/docs/components/alert)
+
+Use for section messages.
+
+[Banner](/docs/components/banner)
+
+Use for product-wide messages.
+
+[Toast](/docs/components/toast)
+
+Use for confirmations.
+
+[SecretValue](/docs/components/secret-value)
+
+Use for masked secrets.
+
+[Loading](/docs/patterns/loading)
+
+Covers Pending transactions.
+
+[Blockchain Values](/docs/patterns/blockchain-values)
+
+Covers amounts and addresses.