@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/hero-visual.md

@@ -0,0 +1,155 @@
+# HeroVisual
+
+Shows animated streaks and a title beside the steps of a setup flow.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/HeroVisual.tsx)
+
+Figma: [Content/Hero Visual](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-4030)
+
+## Overview
+
+A hero visual renders a dark 520px card with the Tempo wordmark at the top and a title block at the bottom. `step` selects the streaks of the current step, and the next step slides new streaks in.
+
+## Examples
+
+### Basic
+
+Compose a title and a description. The card stays dark in both color schemes.
+
+```tsx
+/** Demonstrates HeroVisual in the documentation. @module */
+import { HeroVisual, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.frame()}>
+      <HeroVisual step="connect">
+        <HeroVisual.Title>Your agent</HeroVisual.Title>
+        <HeroVisual.Description>One command, and it can pay its own way.</HeroVisual.Description>
+      </HeroVisual>
+    </div>
+  )
+}
+
+namespace styles {
+  export const frame = style({ maxWidth: '31.25rem !custom', width: '100% !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/HeroVisual/Basic.tsx)
+
+### Steps
+
+Advance `step` with the flow. The title brightens on the steps that complete it.
+
+```tsx
+/** Demonstrates HeroVisual in the documentation. @module */
+import { Button, HeroVisual, style } from '@tempoxyz/ds'
+import { useState } from 'react'
+
+const steps = ['connect', 'approve', 'fund', 'funding', 'funded'] as const
+
+export function Demo() {
+  const [index, setIndex] = useState(0)
+
+  return (
+    <div {...styles.frame()}>
+      <HeroVisual step={steps[index]}>
+        <HeroVisual.Caption>Claude</HeroVisual.Caption>
+        <HeroVisual.Title>Your agent</HeroVisual.Title>
+        <HeroVisual.Description>One command, and it can pay its own way.</HeroVisual.Description>
+      </HeroVisual>
+      <Button onClick={() => setIndex((index + 1) % steps.length)} variant="secondary">
+        Next step
+      </Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const frame = style({
+    display: 'grid',
+    gap: '16',
+    justifyItems: 'start',
+    maxWidth: '31.25rem !custom',
+    width: '100% !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/HeroVisual/Steps.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { HeroVisual } from '@tempoxyz/ds'
+
+<HeroVisual>
+  <HeroVisual.Caption />
+  <HeroVisual.Title />
+  <HeroVisual.Description />
+</HeroVisual>
+```
+
+## Guidelines
+
+### When to Use
+
+* Accompany the steps of an agent or wallet setup flow, beside the form of each step.
+
+### When Not to Use
+
+* Use [SuccessHero](/docs/components/success-hero) once the flow finishes.
+* Use [GetStartedVisual](/docs/components/get-started-visual) for the cards of a get started list.
+
+### Advance the Step With the Flow
+
+* **Agent (connect to funded):** The agent flow runs connect, approve, fund, funding, and funded.
+* **Wallet (wallet to secure):** The wallet flow runs wallet, wallet funding, wallet funded, and secure.
+
+### Keep the Title Short
+
+The title sets at display size and fits about 12 characters on one line.
+
+**Do:** Name the subject of the flow in two words.
+
+```tsx
+<HeroVisual step="connect" style={{ minHeight: 240, width: 320 }}>
+  <HeroVisual.Title>Your agent</HeroVisual.Title>
+</HeroVisual>
+```
+
+**Don't:** Write a sentence in the title.
+
+```tsx
+<HeroVisual step="connect" style={{ minHeight: 240, width: 320 }}>
+  <HeroVisual.Title>Set up your agent to pay for things</HeroVisual.Title>
+</HeroVisual>
+```
+
+## Content
+
+* **Caption:** Name the agent or wallet in one or two words.
+* **Title:** Name the subject of the flow, such as Your agent.
+* **Description:** Write one sentence that states what the flow enables.
+
+## Accessibility
+
+The card renders a `<div>` with no role. Screen readers skip the artwork and the wordmark, and read the text in order.
+
+* **Artwork (aria-hidden):** The streaks and the wordmark are decorative.
+* **HeroVisual.Title (h2):** Announced as a second-level heading.
+* **Reduced Motion (prefers-reduced-motion):** New streaks fade in without movement.
+* **Announce Progress (Your task):** The steps of the flow announce progress, not the card.
+
+## Related
+
+[SuccessHero](/docs/components/success-hero)
+
+Use for the confirmation after the flow finishes.
+
+[Stepper](/docs/components/stepper)
+
+Use for the steps beside the card.

package/dist/docs/components/hex.md

@@ -0,0 +1,487 @@
+# Hex
+
+Shows a hex string, such as an address, truncated to fit.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Hex.tsx)
+
+## Overview
+
+Hex shows a hex string, such as an address or hash, middle-truncated to fit its container. Both ends stay visible, and screen readers read the full value.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Hex, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Hex value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" />
+      <Hex value="0x1234" />
+      <div {...styles.frame()}>
+        <Hex value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" />
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const frame = style({
+    borderColor: 'line.secondary',
+    borderRadius: '2xs',
+    borderStyle: 'dashed',
+    borderWidth: 'regular',
+    boxSizing: 'border-box',
+    maxWidth: '100% !custom',
+    padding: '8',
+    width: '6rem !custom',
+  })
+
+  export const stack = style({ display: 'grid', gap: '12', justifyItems: 'start' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Hex/Basic.tsx)
+
+### Copy
+
+Set `copy` to add a button that copies the full value.
+
+```tsx
+import { CopyButton, Hex, style } from '@tempoxyz/ds'
+
+const address = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
+const transaction = '0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060'
+
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Hex copy value={transaction} />
+      {(['32rem', '20rem', '12rem', '8rem'] as const).map((width) => (
+        <div key={width} {...styles.frame({ style: { width } })}>
+          <Hex copy value={transaction} />
+        </div>
+      ))}
+      <div {...styles.row()}>
+        <CopyButton value={address} />
+        <CopyButton value={address} variant="secondary" />
+        <CopyButton size="large" value={address} variant="primary" />
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const frame = style({
+    borderColor: 'line.secondary',
+    borderRadius: '2xs',
+    borderStyle: 'dashed',
+    borderWidth: 'regular',
+    boxSizing: 'border-box',
+    maxWidth: '100% !custom',
+    padding: '8',
+  })
+
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
+
+  export const stack = style({ display: 'grid', gap: '12', justifyItems: 'start' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Hex/Copy.tsx)
+
+### Evm
+
+Set `evm={false}` for values without a `0x` prefix.
+
+```tsx
+import { Hex } from '@tempoxyz/ds'
+
+export function Demo() {
+  return <Hex evm={false} value="a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718" />
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Hex/Evm.tsx)
+
+### Variant
+
+Set `variant` to `inline` (default) or `filled`.
+
+```tsx
+import { Hex, style } from '@tempoxyz/ds'
+
+const transaction = '0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060'
+
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Hex copy value={transaction} variant="inline" />
+      <div {...styles.resizable()}>
+        <Hex copy value={transaction} variant="filled" />
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const resizable = style({
+    maxWidth: '100% !custom',
+    minWidth: 'min(10rem, 100%) !custom',
+    overflow: 'hidden',
+    resize: 'horizontal !custom',
+    width: '28rem !custom',
+  })
+
+  export const stack = style({ display: 'grid', gap: '12', justifyItems: 'start' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Hex/Variant.tsx)
+
+### Size
+
+Set `size` to `small`, `medium` (default), or `large`.
+
+```tsx
+import { Hex, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      {(['small', 'medium', 'large'] as const).map((size) => (
+        <Hex
+          copy
+          key={size}
+          size={size}
+          value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
+          variant="filled"
+        />
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({ display: 'grid', gap: '12', justifyItems: 'start' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Hex/Size.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Hex } from '@tempoxyz/ds'
+
+<Hex />
+
+<Hex.Root>
+  <Hex.Text />
+  <Hex.Copy />
+</Hex.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Show an address or transaction hash in a row, table, or card where it may not fit.
+* Show a receive address as a standalone field with `variant="filled"`. The whole row copies.
+
+### When Not to Use
+
+* Use [SecretValue](/docs/components/secret-value) for private keys and other secrets. Hex shows its value in the clear.
+* Use [Snippet](/docs/components/snippet) for URLs, commands, and other values that aren't hex.
+* Use [CopyButton](/docs/components/copy-button) alone when the value isn't displayed.
+
+### Always Offer Copy
+
+Set `copy` wherever people need the full value. To name the button, compose the parts and pass `aria-label` to `Hex.Copy`. Link a transaction hash to its block explorer page for verification.
+
+```tsx
+<Hex.Root value={address}>
+  <Hex.Text />
+  <Hex.Copy aria-label="Copy address" />
+</Hex.Root>
+```
+
+**Do:** Add a copy button, named by what it copies.
+
+```tsx
+/** Do example for "Always Offer Copy" on the Hex page: add a copy button, named by what it copies. @module */
+import { Hex } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Hex.Root value="0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060">
+      <Hex.Text />
+      <Hex.Copy aria-label="Copy transaction hash" />
+    </Hex.Root>
+  )
+}
+```
+
+**Don't:** Show a truncated value without a way to copy it.
+
+```tsx
+/**
+ * Don't example for "Always Offer Copy" on the Hex page.
+ * Don't show a truncated value without a way to copy it.
+ * @module
+ */
+import { Hex } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return <Hex value="0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060" />
+}
+```
+
+### Truncate in the Middle
+
+People check an address by its first and last characters. For plain strings, such as a [Toast](/docs/components/toast) message, `formatHex` keeps both ends too.
+
+**Do:** Keep both ends of the value visible.
+
+```tsx
+/** Do example for "Truncate in the Middle" on the Hex page: keep both ends of the value visible. @module */
+import { Hex, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.frame()}>
+      <Hex copy value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const frame = style({ maxWidth: '100% !custom', width: '12rem !custom' })
+}
+```
+
+**Don't:** Truncate the end of an address with an ellipsis.
+
+```tsx
+/**
+ * Don't example for "Truncate in the Middle" on the Hex page.
+ * Don't truncate the end of an address with an ellipsis.
+ * @module
+ */
+import { style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return <span {...styles.text()}>0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045</span>
+}
+
+namespace styles {
+  export const text = style({
+    color: 'content.primary',
+    display: 'block',
+    maxWidth: '100% !custom',
+    overflow: 'hidden',
+    textOverflow: 'ellipsis !custom',
+    typography: 'mono.m1',
+    whiteSpace: 'nowrap',
+    width: '12rem !custom',
+  })
+}
+```
+
+### Show the Full Address Before Sending
+
+Look-alike addresses can match the first and last four characters of a real one. Hex truncates only when its container is narrower than the value, so give it room on a payment review and ask people to check it against its source.
+
+**Do:** Show every character of the recipient on review.
+
+```tsx
+/**
+ * Do example for "Show the Full Address Before Sending" on the Hex page.
+ * Show every character of the recipient on review.
+ * @module
+ */
+import { Hex, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.field()}>
+      <span {...styles.label()}>Recipient</span>
+      <Hex copy value="0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc" variant="filled" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const field = style({ display: 'grid', gap: '4', width: '100% !custom' })
+
+  export const label = style({ color: 'content.secondary', typography: 'body.b2' })
+}
+```
+
+**Don't:** Truncate the address people confirm a payment to.
+
+```tsx
+/**
+ * Don't example for "Show the Full Address Before Sending" on the Hex page.
+ * Don't truncate the address people confirm a payment to.
+ * @module
+ */
+import { Hex, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.field()}>
+      <span {...styles.label()}>Recipient</span>
+      <Hex copy value="0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc" variant="filled" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const field = style({
+    display: 'grid',
+    gap: '4',
+    maxWidth: '100% !custom',
+    width: '12rem !custom',
+  })
+
+  export const label = style({ color: 'content.secondary', typography: 'body.b2' })
+}
+```
+
+### Label Every Value
+
+**Do:** Put a label beside each value, such as Recipient or Transaction hash.
+
+```tsx
+/**
+ * Do example for "Label Every Value" on the Hex page.
+ * Put a label beside each value, such as Recipient or Transaction hash.
+ * @module
+ */
+import { Hex, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Recipient</span>
+        <Hex size="small" value="0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc" />
+      </div>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Transaction hash</span>
+        <Hex
+          size="small"
+          value="0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060"
+        />
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({
+    color: 'content.secondary',
+    flexShrink: '0 !custom',
+    typography: 'body.b2',
+  })
+
+  export const list = style({ display: 'grid', gap: '12', width: '100% !custom' })
+
+  export const row = style({
+    alignItems: 'baseline',
+    display: 'flex',
+    gap: '16',
+    justifyContent: 'space-between',
+    minWidth: '0',
+  })
+}
+```
+
+**Don't:** Show bare hex strings. They don't identify themselves.
+
+```tsx
+/**
+ * Don't example for "Label Every Value" on the Hex page.
+ * Don't show bare hex strings. They don't identify themselves.
+ * @module
+ */
+import { Hex, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      <Hex size="small" value="0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc" />
+      <Hex
+        size="small"
+        value="0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060"
+      />
+    </div>
+  )
+}
+
+namespace styles {
+  export const list = style({ display: 'grid', gap: '12', width: '100% !custom' })
+}
+```
+
+### Pick a Variant
+
+* **Inline (inline):** The default, for text, rows, and table cells.
+* **Filled (filled):** A tinted field that copies on click, for standalone values.
+* **No Prefix (evm={false}):** For hex values without a `0x` prefix.
+
+## Accessibility
+
+Hex renders a `<span>` with the truncated value on screen and the full value for screen readers. With `copy`, the copy button follows the [WAI-ARIA Authoring Practices button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/).
+
+### Semantics
+
+* **Truncated Text (aria-hidden):** Hidden. Screen readers read the full value from hidden text.
+* **Short Values:** Values that fit render as plain text, with no hidden copy of the value.
+* **Hex.Copy (button):** Named "Copy" and the value, or `aria-label`. A copy renames it "Copied" for two seconds and announces it.
+* **Filled Variant (filled):** A click anywhere on the row copies. The button stays the keyboard path.
+
+### Keyboard
+
+* **Move to Copy (Tab):** Moves focus to the copy button. The value takes no focus.
+* **Copy the Value (Enter or Space):** Copies the full value. Focus stays on the button.
+
+### Your Responsibilities
+
+* **Name the Copy Button (aria-label):** Name what it copies, such as "Copy address". The default name reads the full value.
+* **Show a Name:** If a name or contact label exists, show it with the address. A raw hex string is hard to listen to.
+
+## Related
+
+[CopyButton](/docs/components/copy-button)
+
+Use for copying without a visible value.
+
+[Identicon](/docs/components/identicon)
+
+Use for an image beside an address.
+
+[SecretValue](/docs/components/secret-value)
+
+Use for secrets.
+
+[Snippet](/docs/components/snippet)
+
+Use for commands and URLs.
+
+[Blockchain Values](/docs/patterns/blockchain-values)
+
+Covers addresses, hashes, and amounts.