@tempoxyz/ds 0.3.10 → 0.3.11

package/dist/docs/components/status-row.md

@@ -0,0 +1,174 @@
+# StatusRow
+
+Follows the status of one payment or task while it runs.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/StatusRow.tsx)
+
+Figma: [Messaging/Status Row](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-3981)
+
+## Overview
+
+A status row renders a tinted row with a leading mark, a title over a description, and an optional trailing [StatusChip](/docs/components/status-chip). It announces a change of its text to screen readers, so it can update in place as the task moves on.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Spinner, StatusChip, StatusRow } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <StatusRow>
+      <StatusRow.Icon>
+        <Spinner />
+      </StatusRow.Icon>
+      <StatusRow.Content>
+        <StatusRow.Title>Waiting for $10.00</StatusRow.Title>
+        <StatusRow.Description>
+          Usually under a minute on Tempo. You can leave this page.
+        </StatusRow.Description>
+      </StatusRow.Content>
+      <StatusChip intent="warning" size="small">
+        Pending
+      </StatusChip>
+    </StatusRow>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/StatusRow/Basic.tsx)
+
+### Intent
+
+Set `intent` to `neutral` (default) while the task runs, or `positive` once it is done.
+
+```tsx
+import { StatusRow } from '@tempoxyz/ds'
+import { CheckCircle } from '@tempoxyz/ds/icons'
+
+export function Demo() {
+  return (
+    <StatusRow intent="positive">
+      <StatusRow.Icon>
+        <CheckCircle />
+      </StatusRow.Icon>
+      <StatusRow.Content>
+        <StatusRow.Title>Received $10.00</StatusRow.Title>
+        <StatusRow.Description>The funds are in your wallet.</StatusRow.Description>
+      </StatusRow.Content>
+    </StatusRow>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/StatusRow/Intent.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { StatusRow } from '@tempoxyz/ds'
+
+<StatusRow>
+  <StatusRow.Icon />
+  <StatusRow.Content>
+    <StatusRow.Title />
+    <StatusRow.Description />
+  </StatusRow.Content>
+</StatusRow>
+```
+
+## Guidelines
+
+### When to Use
+
+* Follow a deposit, a payment, or an authorization that completes within minutes.
+* Confirm in place that the task finished.
+
+### When Not to Use
+
+* Use [Alert](/docs/components/alert) for guidance that is not tied to a running task.
+* Use [Toast](/docs/components/toast) to confirm an action briefly and out of the flow.
+* Use [ListGroup](/docs/components/list-group) for a list of finished payments.
+
+### Match the Mark to the State
+
+* **Running (neutral):** A spinner, with a chip that names the step.
+* **Done (positive):** A check in the positive color, without a chip.
+
+### State the Task and the Wait
+
+**Do:** Name the amount in the title and the expected wait in the description.
+
+```tsx
+import { Spinner, StatusRow } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <StatusRow>
+      <StatusRow.Icon>
+        <Spinner />
+      </StatusRow.Icon>
+      <StatusRow.Content>
+        <StatusRow.Title>Waiting for $10.00</StatusRow.Title>
+        <StatusRow.Description>Usually under a minute on Tempo.</StatusRow.Description>
+      </StatusRow.Content>
+    </StatusRow>
+  )
+}
+```
+
+**Don't:** Ask people to wait without saying for what or for how long.
+
+```tsx
+import { Spinner, StatusRow } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <StatusRow>
+      <StatusRow.Icon>
+        <Spinner />
+      </StatusRow.Icon>
+      <StatusRow.Content>
+        <StatusRow.Title>Please wait</StatusRow.Title>
+        <StatusRow.Description>Something is happening.</StatusRow.Description>
+      </StatusRow.Content>
+    </StatusRow>
+  )
+}
+```
+
+## Content
+
+### Write the Title and the Description
+
+Start the title with the state and the amount, such as Waiting for $10.00. In the description, give the expected wait and whether people can leave the page.
+
+## Accessibility
+
+A status row renders a `<div>` with the `status` role, so screen readers announce a change of its text politely. The leading mark is hidden.
+
+### Semantics
+
+* **Root (status):** Screen readers announce a change of the text without moving focus.
+* **Icon (aria-hidden):** The spinner and the check are hidden, so the title carries the state.
+
+### Your Responsibilities
+
+* **Update the Row in Place (SC 4.1.3):** Change the text of the mounted row, so the status role announces it.
+
+## Related
+
+[StatusChip](/docs/components/status-chip)
+
+Use for the status at the end of the row.
+
+[Spinner](/docs/components/spinner)
+
+Use for the leading mark while the task runs.
+
+[Alert](/docs/components/alert)
+
+Use for guidance that is not tied to a running task.

package/dist/docs/components/stepper.md

@@ -0,0 +1,451 @@
+# Stepper
+
+Shows progress through a fixed sequence of steps.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Stepper.tsx)
+
+Figma: [Controls/Stepper](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-1489) (`Stepper.Root`)
+
+## Overview
+
+A stepper renders the steps as a row of 24px segments, 4px apart. Pass `aria-label` to name the flow, such as Account setup.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Stepper, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return <Stepper.Root aria-label="Account setup" count={3} value={1} {...styles.stepper()} />
+}
+
+namespace styles {
+  export const stepper = style({ maxWidth: '24rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Stepper/Basic.tsx)
+
+### Value
+
+Set `count` to the number of steps and `value` to the current step, from `1` to `count`.
+
+```tsx
+import { Stepper, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      {[1, 2, 3].map((value) => (
+        <Stepper.Root aria-label="Account setup" count={3} key={value} value={value} />
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '16',
+    maxWidth: '24rem !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Stepper/Value.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Stepper } from '@tempoxyz/ds'
+
+<Stepper.Root />
+```
+
+## Guidelines
+
+### When to Use
+
+* Show a multi-step flow with a fixed number of steps, such as onboarding (Create passkey, Back up, Add funds) or a send flow (Recipient, Amount, Review).
+* Split one long setup form into short screens, such as business verification before API key access.
+
+### When Not to Use
+
+* Use [Progress](/docs/components/progress) for measurable work, such as a file upload or a sync to the latest block.
+* Use [Tabs](/docs/components/tabs) for sections in any order. A stepper is not interactive, and its segments don't link to steps.
+* Use [Breadcrumbs](/docs/components/breadcrumbs) to show where a page sits in the hierarchy.
+* Use one form, laid out with [Field](/docs/components/field) and [Fieldset](/docs/components/fieldset), when the task fits on one screen.
+
+### Keep the Step Count Fixed
+
+Set `count` once for the whole flow, and aim for three to five steps. Merge short steps before you add segments. If an answer skips a step, keep its segment and move past it.
+
+**Do:** Keep the same total on every step.
+
+```tsx
+/** Do example for "Keep the Step Count Fixed" on the Stepper page: keep the same total on every step. @module */
+import { Stepper, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.flow()}>
+      <div {...styles.screen()}>
+        <Stepper.Root aria-label="Account setup" count={4} value={1} />
+        <span {...styles.step()}>Step 1 of 4</span>
+      </div>
+      <div {...styles.screen()}>
+        <Stepper.Root aria-label="Account setup" count={4} value={2} />
+        <span {...styles.step()}>Step 2 of 4</span>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const flow = style({
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '24',
+    width: '100% !custom',
+  })
+
+  export const screen = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })
+
+  export const step = style({ color: 'content.secondary', typography: 'body.b3' })
+}
+```
+
+**Don't:** Change the total partway, which makes the progress look wrong.
+
+```tsx
+/**
+ * Don't example for "Keep the Step Count Fixed" on the Stepper page.
+ * Don't change the total partway, which makes the progress look wrong.
+ * @module
+ */
+import { Stepper, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.flow()}>
+      <div {...styles.screen()}>
+        <Stepper.Root aria-label="Account setup" count={3} value={1} />
+        <span {...styles.step()}>Step 1 of 3</span>
+      </div>
+      <div {...styles.screen()}>
+        <Stepper.Root aria-label="Account setup" count={5} value={2} />
+        <span {...styles.step()}>Step 2 of 5</span>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const flow = style({
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '24',
+    width: '100% !custom',
+  })
+
+  export const screen = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })
+
+  export const step = style({ color: 'content.secondary', typography: 'body.b3' })
+}
+```
+
+### Label the Current Step in Text
+
+The segments carry no text. Place a visible step number and a heading above the stepper, such as Step 2 of 3 above Enter amount.
+
+**Do:** Pair the stepper with the step number and the step's title.
+
+```tsx
+/**
+ * Do example for "Label the Current Step in Text" on the Stepper page.
+ * Pair the stepper with the step number and the step's title.
+ * @module
+ */
+import { Stepper, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.flow()}>
+      <Stepper.Root aria-label="Send payment" count={3} value={2} />
+      <span {...styles.step()}>Step 2 of 3</span>
+      <span {...styles.title()}>Enter amount</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const flow = style({
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '8',
+    width: '100% !custom',
+  })
+
+  export const step = style({
+    color: 'content.secondary',
+    marginBlockStart: '8',
+    typography: 'body.b3',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
+}
+```
+
+**Don't:** Show the segments without any text.
+
+```tsx
+/**
+ * Don't example for "Label the Current Step in Text" on the Stepper page.
+ * Don't show the segments without any text.
+ * @module
+ */
+import { Stepper, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.flow()}>
+      <Stepper.Root count={3} value={2} />
+    </div>
+  )
+}
+
+namespace styles {
+  export const flow = style({ width: '100% !custom' })
+}
+```
+
+### Let People Go Back
+
+Give every step after the first a Back button before the primary action, and keep the values already entered. Make the last step a review with a specific primary action, such as Confirm payment, and set `value` to `count` there.
+
+**Do:** Offer Back before the primary action.
+
+```tsx
+/** Do example for "Let People Go Back" on the Stepper page: offer Back before the primary action. @module */
+import { Button, Stepper, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.flow()}>
+      <Stepper.Root aria-label="Send payment" count={3} value={2} />
+      <span {...styles.step()}>Step 2 of 3</span>
+      <span {...styles.title()}>Enter amount</span>
+      <div {...styles.actions()}>
+        <Button variant="secondary">Back</Button>
+        <Button>Continue</Button>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const actions = style({
+    columnGap: '8',
+    display: 'flex',
+    justifyContent: 'flex-end',
+    marginBlockStart: '16',
+  })
+
+  export const flow = style({
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '8',
+    width: '100% !custom',
+  })
+
+  export const step = style({
+    color: 'content.secondary',
+    marginBlockStart: '8',
+    typography: 'body.b3',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
+}
+```
+
+**Don't:** Leave a step with only a way forward.
+
+```tsx
+/**
+ * Don't example for "Let People Go Back" on the Stepper page.
+ * Don't leave a step with only a way forward.
+ * @module
+ */
+import { Button, Stepper, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.flow()}>
+      <Stepper.Root aria-label="Send payment" count={3} value={2} />
+      <span {...styles.step()}>Step 2 of 3</span>
+      <span {...styles.title()}>Enter amount</span>
+      <div {...styles.actions()}>
+        <Button>Continue</Button>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const actions = style({
+    columnGap: '8',
+    display: 'flex',
+    justifyContent: 'flex-end',
+    marginBlockStart: '16',
+  })
+
+  export const flow = style({
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '8',
+    width: '100% !custom',
+  })
+
+  export const step = style({
+    color: 'content.secondary',
+    marginBlockStart: '8',
+    typography: 'body.b3',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
+}
+```
+
+### Keep It in One Place
+
+Place the stepper in the same spot on every step. In a [Dialog](/docs/components/dialog) or a [Frame](/docs/components/frame), center it in the header, with the Back button on the left from the second step.
+
+**Do:** Place the stepper at the top, above the step's heading.
+
+```tsx
+/**
+ * Do example for "Label the Current Step in Text" on the Stepper page.
+ * Pair the stepper with the step number and the step's title.
+ * @module
+ */
+import { Stepper, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.flow()}>
+      <Stepper.Root aria-label="Send payment" count={3} value={2} />
+      <span {...styles.step()}>Step 2 of 3</span>
+      <span {...styles.title()}>Enter amount</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const flow = style({
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '8',
+    width: '100% !custom',
+  })
+
+  export const step = style({
+    color: 'content.secondary',
+    marginBlockStart: '8',
+    typography: 'body.b3',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
+}
+```
+
+**Don't:** Place the stepper below the step's content.
+
+```tsx
+/**
+ * Don't example for "Keep It in One Place" on the Stepper page.
+ * Don't place the stepper below the step's content.
+ * @module
+ */
+import { Stepper, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.flow()}>
+      <span {...styles.step()}>Step 2 of 3</span>
+      <span {...styles.title()}>Enter amount</span>
+      <Stepper.Root aria-label="Send payment" count={3} value={2} {...styles.stepper()} />
+    </div>
+  )
+}
+
+namespace styles {
+  export const flow = style({
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '8',
+    width: '100% !custom',
+  })
+
+  export const step = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const stepper = style({ marginBlockStart: '16' })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
+}
+```
+
+## Content
+
+* Write step titles as short tasks or nouns, such as Recipient, Amount, and Review.
+* Match the visible step text to the announced value, Step 2 of 3.
+* Before the first step, list what people need, such as an ID or a funded wallet.
+
+## Accessibility
+
+A stepper renders a `progressbar` whose value is the current step. The segments are visual only.
+
+### Semantics
+
+* **Root (progressbar):** Its value is the current step, 1 to `count`.
+* **Value Text (aria-valuetext):** Reads as "Step 2 of 4".
+* **Name (aria-label):** Named "Progress" by default.
+* **No Focus Stop (not focusable):** Tab moves past it to the next control.
+
+### Your Responsibilities
+
+* **Name the Flow (aria-label):** Name the flow, such as "Account setup". Don't repeat the step text, which is already read.
+* **Label Each Step (SC 1.3.1):** Name the current step in visible text, so progress doesn't rely on color alone.
+* **Move Focus on Advance:** When the step changes, move focus to the new step's heading, so screen readers announce the new step.
+
+## Related
+
+[Progress](/docs/components/progress)
+
+Use for measurable work.
+
+[Dialog](/docs/components/dialog)
+
+Use for flows that open over the page.
+
+[Forms](/docs/patterns/forms)
+
+Covers laying out each step.
+
+[Payments](/docs/patterns/payments)
+
+Covers send and review flows.