@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/alert.md

@@ -0,0 +1,448 @@
+# Alert
+
+Shows an inline message tied to nearby content.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Alert.tsx)
+
+Figma: [Alert](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=3056-453)
+
+## Overview
+
+An inline message on a tinted container, with a square indicator in the color of its `intent`. It is a live region, so screen readers announce it when it appears.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Alert } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Alert>
+      <Alert.Icon />
+      <Alert.Content>Changes may take a few minutes to appear.</Alert.Content>
+    </Alert>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Alert/Basic.tsx)
+
+### Intent
+
+Set `intent` to `neutral` (default), `positive`, `warning`, `negative`, `tip`, or `special`.
+
+```tsx
+import { Alert, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      {(['neutral', 'positive', 'warning', 'negative', 'tip', 'special'] as const).map((intent) => (
+        <Alert intent={intent} key={intent}>
+          <Alert.Icon />
+          <Alert.Content>You need to deposit $25.00 to continue.</Alert.Content>
+        </Alert>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '12',
+    maxWidth: '36rem !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Alert/Intent.tsx)
+
+### Title and Action
+
+Add an `Alert.Title` above the message, and an `Alert.Action` after it, inside `Alert.Content`.
+
+```tsx
+import { Alert, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Alert intent="warning" {...styles.note()}>
+      <Alert.Icon />
+      <Alert.Content>
+        <Alert.Title>New address</Alert.Title>
+        Check the first and last 4 characters.
+        <Alert.Action>View details</Alert.Action>
+      </Alert.Content>
+    </Alert>
+  )
+}
+
+namespace styles {
+  export const note = style({ maxWidth: '24rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Alert/Title.tsx)
+
+### Inline
+
+The content flows as text, so inline elements such as `strong` stay on the lines of the message.
+
+```tsx
+/** Renders a warning whose message holds inline `strong` text, for the Alert docs. @module */
+import { Alert } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Alert intent="warning" role="note">
+      <Alert.Icon />
+      <Alert.Content>
+        Only send <strong>supported stablecoins</strong> on <strong>Tempo</strong>. Sending other
+        tokens or using a different network may result in permanent loss.
+      </Alert.Content>
+    </Alert>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Alert/Inline.tsx)
+
+### Dismiss
+
+Add an `Alert.Dismiss` after `Alert.Content`. Remove the alert in its `onClick`.
+
+```tsx
+import { Alert, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Alert intent="tip" {...styles.note()}>
+      <Alert.Icon />
+      <Alert.Content>
+        <Alert.Title>Fee token</Alert.Title>
+        Fees are paid in USDC. Change it in Settings.
+      </Alert.Content>
+      <Alert.Dismiss />
+    </Alert>
+  )
+}
+
+namespace styles {
+  export const note = style({ maxWidth: '24rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Alert/Dismiss.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Alert } from '@tempoxyz/ds'
+
+<Alert>
+  <Alert.Icon />
+  <Alert.Content>
+    <Alert.Title />
+    <Alert.Action />
+  </Alert.Content>
+  <Alert.Dismiss />
+</Alert>
+```
+
+## Guidelines
+
+### When to Use
+
+* Explain a condition that affects nearby content, such as higher network fees above the Send payment form.
+* Keep a result visible beside its section, such as a failed webhook delivery.
+* Give guidance before a task, such as a note that testnet tokens have no value.
+* Add optional context with `tip`, such as the token that pays network fees.
+
+### When Not to Use
+
+* Use [Banner](/docs/components/banner) for a message about the whole product or page, such as an outage.
+* Use [Toast](/docs/components/toast) to confirm that an action finished, such as Payment sent.
+* If an action needs a decision before it continues, use [AlertDialog](/docs/components/alert-dialog).
+* Use `Field.Error` from [Field](/docs/components/field) for a validation message on one input.
+* Use [Badge](/docs/components/badge) for a one-word status on a table row or card, such as Pending.
+
+### Choose an Intent by Severity
+
+* **Neutral (default):** Context that needs no action, such as when deposits confirm.
+* **Positive (positive):** A result that stays in place, such as a verified webhook endpoint.
+* **Warning (warning):** An avoidable risk, such as sending to an address new to Tempo.
+* **Negative (negative):** A blocking failure, such as balances that couldn't load.
+* **Tip (tip):** Optional context, such as the token that pays the network fee.
+* **Special (special):** A new feature to announce, such as vaults for idle USDC balances.
+
+Use `warning` before a risky step and `negative` before one that can't be undone. Never use `positive` as decoration.
+
+### Pair the Icon With Text That States the Outcome
+
+Add `Alert.Icon` to every alert. It draws a square in the color of the intent.
+
+**Do:** Combine `Alert.Icon` with a sentence that names the condition.
+
+```tsx
+/**
+ * Do example for "Pair the Icon With Text That States the Outcome" on the Alert page.
+ * Combine `Alert.Icon` with a sentence that names the condition.
+ * @module
+ */
+import { Alert } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Alert intent="warning">
+      <Alert.Icon />
+      <Alert.Content>
+        Network fees are higher than usual.
+        <Alert.Action>Review fees</Alert.Action>
+      </Alert.Content>
+    </Alert>
+  )
+}
+```
+
+**Don't:** Leave out the icon or let the tint carry the warning.
+
+```tsx
+/**
+ * Don't example for "Pair the Icon With Text That States the Outcome" on the Alert page.
+ * Don't leave out the icon or let the tint carry the warning.
+ * @module
+ */
+import { Alert } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Alert intent="warning">
+      <Alert.Content>
+        Network fees
+        <Alert.Action>Review</Alert.Action>
+      </Alert.Content>
+    </Alert>
+  )
+}
+```
+
+### Place It Beside What It Describes
+
+Remove the alert when its condition ends, such as when fees return to normal. In a [Dialog](/docs/components/dialog), show one alert at full width, below the input it describes.
+
+**Do:** Put the alert directly above the form it describes, or directly below its control.
+
+```tsx
+/**
+ * Do example for "Place It Beside What It Describes" on the Alert page.
+ * Put the callout directly above the form it describes, or directly below its control.
+ * @module
+ */
+import { Alert, Button, Field, Stack, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Stack gap="16" {...styles.fill()}>
+      <div {...styles.activity()}>
+        <div {...styles.heading()}>Recent activity</div>
+        <div>Sent 25.00 USDC to 0x8f3c…a21b</div>
+        <div>Received 120.00 USDC from 0x41d0…9c7e</div>
+      </div>
+      <Alert intent="warning">
+        <Alert.Icon />
+        <Alert.Content>Network fees are higher than usual.</Alert.Content>
+      </Alert>
+      <Field.Root>
+        <Field.Label>Amount</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control defaultValue="50.00" />
+        </TextInput.Group>
+      </Field.Root>
+      <Button>Send payment</Button>
+    </Stack>
+  )
+}
+
+namespace styles {
+  export const activity = style({
+    color: 'content.secondary',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '4',
+    typography: 'body.b2',
+  })
+
+  export const fill = style({ width: '100% !custom' })
+
+  export const heading = style({ color: 'content.primary', typography: 'body.b2' })
+}
+```
+
+**Don't:** Place it at the top of a long page, away from its content.
+
+```tsx
+/**
+ * Don't example for "Place It Beside What It Describes" on the Alert page.
+ * Don't place it at the top of a long page, away from its content.
+ * @module
+ */
+import { Alert, Button, Field, Stack, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Stack gap="16" {...styles.fill()}>
+      <Alert intent="warning">
+        <Alert.Icon />
+        <Alert.Content>Network fees are higher than usual.</Alert.Content>
+      </Alert>
+      <div {...styles.activity()}>
+        <div {...styles.heading()}>Recent activity</div>
+        <div>Sent 25.00 USDC to 0x8f3c…a21b</div>
+        <div>Received 120.00 USDC from 0x41d0…9c7e</div>
+      </div>
+      <Field.Root>
+        <Field.Label>Amount</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control defaultValue="50.00" />
+        </TextInput.Group>
+      </Field.Root>
+      <Button>Send payment</Button>
+    </Stack>
+  )
+}
+
+namespace styles {
+  export const activity = style({
+    color: 'content.secondary',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '4',
+    typography: 'body.b2',
+  })
+
+  export const fill = style({ width: '100% !custom' })
+
+  export const heading = style({ color: 'content.primary', typography: 'body.b2' })
+}
+```
+
+### Offer One Action
+
+For more options than one action, link to a page that explains them.
+
+**Do:** Offer the one action that resolves the message.
+
+```tsx
+/** Do example for "Offer One Action" on the Alert page: offer the one action that resolves the message. @module */
+import { Alert } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Alert intent="negative">
+      <Alert.Icon />
+      <Alert.Content>
+        <Alert.Title>Webhook delivery failed</Alert.Title>
+        Your endpoint returned 500.
+        <Alert.Action>Retry</Alert.Action>
+      </Alert.Content>
+    </Alert>
+  )
+}
+```
+
+**Don't:** Line up several actions inside one alert.
+
+```tsx
+/**
+ * Don't example for "Offer One Action" on the Alert page.
+ * Don't line up several actions inside one callout.
+ * @module
+ */
+import { Alert } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Alert intent="negative">
+      <Alert.Icon />
+      <Alert.Content>
+        Webhook delivery failed.
+        <Alert.Action>Retry</Alert.Action>
+        <Alert.Action>Logs</Alert.Action>
+        <Alert.Action>Docs</Alert.Action>
+      </Alert.Content>
+    </Alert>
+  )
+}
+```
+
+To link elsewhere, pass `Alert.Action` a `render` with an `a` element and `nativeButton={false}`.
+
+## Content
+
+* Lead with the condition, then the consequence or next step: Network fees are higher than usual. Your payment may take longer to confirm.
+* Keep it to one or two sentences. Add an `Alert.Title` of two or three words, such as New address, when the message needs a label.
+* Describe the condition, not the intent. Write Webhook delivery failed, not Error.
+* Use specific values, such as the amount needed: You need to deposit $25.00 to continue.
+* Start the action label with a verb, such as Review fees or Add funds.
+
+## Accessibility
+
+An alert is a live region whose role depends on `intent`. It does not move focus when it appears.
+
+### Semantics
+
+* **Neutral, Positive, Tip, and Special (status):** Announced at the next pause.
+* **Warning and Negative (alert):** Interrupts the screen reader.
+* **Role Override (role):** Replaces either default, such as `role="note"` for static text.
+* **Alert.Icon (aria-hidden):** Never announced. The text carries the meaning.
+* **Alert.Action (button):** A native button. Enter and Space activate it.
+* **Contrast (content.primary):** Text stays primary on every tint and scheme. Keep the background.
+
+### Keyboard
+
+* **Move to the Action (Tab):** Moves focus to the alert's action, if any.
+* **Activate the Action (Enter or Space):** Activates the action.
+
+### Your Responsibilities
+
+* **Reserve Assertive Intents (warning or negative):** They interrupt the screen reader, so use them only for a message the reader must act on.
+* **Insert It When the Condition Occurs:** An alert present on first render may not be announced. Insert it after the failed request.
+* **Render the Region First:** If one alert shows several messages, render the live region before you change its content.
+* **Remove It on Dismiss (onClick):** `Alert.Dismiss` only renders the button. Remove the alert and move focus in `onClick`.
+
+## Related
+
+[Banner](/docs/components/banner)
+
+Use for a message about the whole page.
+
+[Toast](/docs/components/toast)
+
+Use for confirming a finished action.
+
+[Field](/docs/components/field)
+
+Use for validation messages on an input.
+
+[Errors and Validation](/docs/patterns/errors-and-validation)
+
+Covers reporting failures.
+
+[Feedback and Status](/docs/patterns/feedback-and-status)
+
+Covers choosing a message component.