@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/progress.md

@@ -0,0 +1,388 @@
+# Progress
+
+Shows how far a task has advanced.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Progress.tsx)
+
+Figma: [Progress](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=3048-372) (`Progress.Root`)
+
+## Overview
+
+A bar that fills in the `intent` color as a task advances, with an optional label and printed value.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Progress, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Progress.Root value={60} {...styles.progress()}>
+      <Progress.Label>Uploading</Progress.Label>
+      <Progress.Value />
+      <Progress.Track>
+        <Progress.Indicator />
+      </Progress.Track>
+    </Progress.Root>
+  )
+}
+
+namespace styles {
+  export const progress = style({ maxWidth: '24rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Progress/Basic.tsx)
+
+### Intent
+
+Set `intent` to `neutral` (default) or `positive`.
+
+```tsx
+import { Progress, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      {(['neutral', 'positive'] as const).map((intent, index) => (
+        <Progress.Root intent={intent} key={intent} value={20 + index * 20}>
+          <Progress.Label>{intent}</Progress.Label>
+          <Progress.Value />
+          <Progress.Track>
+            <Progress.Indicator />
+          </Progress.Track>
+        </Progress.Root>
+      ))}
+    </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/Progress/Intent.tsx)
+
+### Value
+
+If the remaining work is unknown, pass `value={null}` for an indeterminate bar.
+
+```tsx
+import { Progress, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Progress.Root value={null} {...styles.progress()}>
+      <Progress.Label>Indeterminate</Progress.Label>
+      <Progress.Track>
+        <Progress.Indicator />
+      </Progress.Track>
+    </Progress.Root>
+  )
+}
+
+namespace styles {
+  export const progress = style({ maxWidth: '24rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Progress/Value.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Progress } from '@tempoxyz/ds'
+
+<Progress.Root>
+  <Progress.Label />
+  <Progress.Value />
+  <Progress.Track>
+    <Progress.Indicator />
+  </Progress.Track>
+</Progress.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Report measurable work, such as an upload of a payouts CSV or an export of 1,240 transactions.
+* Count through a batch, such as 3 of 5 payments in a payout run.
+* Track a long sync with a known end, such as block indexing up to the current height.
+* Show an indeterminate bar for a named task of unknown length, such as a bridge deposit confirmation.
+
+### When Not to Use
+
+* Use [Gauge](/docs/components/gauge) for a measurement that does not advance, such as storage used.
+* Use [Spinner](/docs/components/spinner) for a short wait in a region or control.
+* Use [Skeleton](/docs/components/skeleton) for content with a known shape.
+* Use `loading` on a [Button](/docs/components/button) while its action runs.
+* Use [Stepper](/docs/components/stepper) for a fixed sequence of steps, such as account setup.
+
+### Show Determinate Progress When You Can Measure It
+
+A rough count of steps is enough. Keep `value={null}` for work with no measurable end.
+
+**Do:** Pass a `value` for an upload whose size you know.
+
+```tsx
+/**
+ * Do example for "Show Determinate Progress When You Can Measure It" on the Progress page.
+ * Pass a `value` for an upload whose size you know.
+ * @module
+ */
+import { Progress, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Progress.Root value={60} {...styles.progress()}>
+      <Progress.Label>Uploading payouts.csv</Progress.Label>
+      <Progress.Value />
+      <Progress.Track>
+        <Progress.Indicator />
+      </Progress.Track>
+    </Progress.Root>
+  )
+}
+
+namespace styles {
+  export const progress = style({ maxWidth: '20rem !custom' })
+}
+```
+
+**Don't:** Show an indeterminate bar for work you can measure.
+
+```tsx
+/**
+ * Don't example for "Show Determinate Progress When You Can Measure It" on the Progress page.
+ * Don't show an indeterminate bar for work you can measure.
+ * @module
+ */
+import { Progress, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Progress.Root value={null} {...styles.progress()}>
+      <Progress.Label>Uploading payouts.csv</Progress.Label>
+      <Progress.Track>
+        <Progress.Indicator />
+      </Progress.Track>
+    </Progress.Root>
+  )
+}
+
+namespace styles {
+  export const progress = style({ maxWidth: '20rem !custom' })
+}
+```
+
+### Name the Task
+
+Add `Progress.Value` to print the percentage, or pass it a function child for units, such as 3 of 5 files. Without a visible label, pass `aria-label`.
+
+**Do:** Put a `Progress.Label` in every bar.
+
+```tsx
+/** Do example for "Name the Task" on the Progress page: put a `Progress.Label` in every bar. @module */
+import { Progress, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Progress.Root value={60} {...styles.progress()}>
+      <Progress.Label>Exporting 1,240 transactions</Progress.Label>
+      <Progress.Value />
+      <Progress.Track>
+        <Progress.Indicator />
+      </Progress.Track>
+    </Progress.Root>
+  )
+}
+
+namespace styles {
+  export const progress = style({ maxWidth: '20rem !custom' })
+}
+```
+
+**Don't:** Show a bar without a name for its task.
+
+```tsx
+/** Don't example for "Name the Task" on the Progress page. Don't show a bar without a name for its task. @module */
+import { Progress, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Progress.Root value={60} {...styles.progress()}>
+      <Progress.Value />
+      <Progress.Track>
+        <Progress.Indicator />
+      </Progress.Track>
+    </Progress.Root>
+  )
+}
+
+namespace styles {
+  export const progress = style({ maxWidth: '20rem !custom' })
+}
+```
+
+### Move Forward Only
+
+Use an indeterminate bar for a phase you cannot measure.
+
+**Do:** If a task has phases, such as upload then verification, change the label for each.
+
+```tsx
+/**
+ * Do example for "Move Forward Only" on the Progress page.
+ * If a task has phases, such as upload then verification, change the label for each.
+ * @module
+ */
+import { Progress, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.steps()}>
+      <Progress.Root value={90} {...styles.progress()}>
+        <Progress.Label>Uploading payouts.csv</Progress.Label>
+        <Progress.Value />
+        <Progress.Track>
+          <Progress.Indicator />
+        </Progress.Track>
+      </Progress.Root>
+      <div {...styles.step()}>Then</div>
+      <Progress.Root value={10} {...styles.progress()}>
+        <Progress.Label>Verifying payments</Progress.Label>
+        <Progress.Value />
+        <Progress.Track>
+          <Progress.Indicator />
+        </Progress.Track>
+      </Progress.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const progress = style({ maxWidth: '20rem !custom' })
+
+  export const step = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const steps = style({
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '12',
+    width: '100% !custom',
+  })
+}
+```
+
+**Don't:** Let the value decrease or restart at 0 under the same label.
+
+```tsx
+/**
+ * Don't example for "Move Forward Only" on the Progress page.
+ * Don't let the value decrease or restart at 0 under the same label.
+ * @module
+ */
+import { Progress, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.steps()}>
+      <Progress.Root value={90} {...styles.progress()}>
+        <Progress.Label>Uploading payouts.csv</Progress.Label>
+        <Progress.Value />
+        <Progress.Track>
+          <Progress.Indicator />
+        </Progress.Track>
+      </Progress.Root>
+      <div {...styles.step()}>Then</div>
+      <Progress.Root value={10} {...styles.progress()}>
+        <Progress.Label>Uploading payouts.csv</Progress.Label>
+        <Progress.Value />
+        <Progress.Track>
+          <Progress.Indicator />
+        </Progress.Track>
+      </Progress.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const progress = style({ maxWidth: '20rem !custom' })
+
+  export const step = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const steps = style({
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '12',
+    width: '100% !custom',
+  })
+}
+```
+
+### Report the Outcome
+
+* **Success (positive):** Set `intent` to `positive` and change the label. Then replace the bar with the result, such as a link to the file.
+* **Failure (Alert):** Progress has no `negative` intent. Replace the bar with a `negative` [Alert](/docs/components/alert) that offers Retry.
+
+## Content
+
+* **Label:** A verb ending in -ing and its object, such as Uploading payouts.csv.
+* **Units:** If a percentage hides the size of the job, count files, payments, or blocks.
+* **Time estimate:** Add one only when it is reliable, and round it, such as About 2 minutes left.
+
+## Accessibility
+
+The bar is not a live region. A changed value is read only when the reader returns to it.
+
+### Semantics
+
+* **Progress.Root (progressbar):** Reports its range and value to assistive technology.
+* **Value Text (aria-valuetext):** Defaults to a locale percentage, such as "60%". `format` and `getAriaValueText` change it.
+* **Progress.Label (aria-labelledby):** Names the bar.
+* **Progress.Value (aria-hidden):** Screen readers skip it and read the value text once.
+* **Indeterminate Bars (value={null}):** Reports no current value. Under reduced motion, the sliding segment becomes a dimmed full bar.
+
+### Your Responsibilities
+
+* **Describe Units (getAriaValueText):** Use it for a value with units, such as "3 of 5 files".
+* **Announce Completion (SC 4.1.3):** Announce the result, such as "Upload complete", in a status message or toast.
+* **Keep Label and Value Visible (4px):** The track is thin. The label and value carry the information for anyone who cannot see the fill.
+
+## Related
+
+[Gauge](/docs/components/gauge)
+
+Use for a measurement within a range.
+
+[Spinner](/docs/components/spinner)
+
+Use for a short wait of unknown length.
+
+[Skeleton](/docs/components/skeleton)
+
+Use for content with a known shape.
+
+[Loading](/docs/patterns/loading)
+
+Covers choosing a loading indicator.

package/dist/docs/components/qr.md

@@ -0,0 +1,314 @@
+# Qr
+
+Renders a value as a QR code.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Qr.tsx)
+
+## Overview
+
+Qr renders a value as a QR code in the foreground color on a transparent ground.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Qr } from '@tempoxyz/ds'
+
+export function Demo() {
+  return <Qr value="tempo:0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" />
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Qr/Basic.tsx)
+
+### Size
+
+Set `size` to `small`, `medium` (default), or `large`.
+
+```tsx
+import { Qr, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {(['small', 'medium', 'large'] as const).map((size) => (
+        <Qr key={size} size={size} value="tempo:0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" />
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'start', display: 'flex', flexWrap: 'wrap', gap: '16' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Qr/Size.tsx)
+
+### Arena
+
+Pass an image URL to `arena` to draw a logo in the center.
+
+```tsx
+import { Qr } from '@tempoxyz/ds'
+import pathUsd from '../../coins/PathUSD.svg'
+
+export function Demo() {
+  return <Qr arena={pathUsd} value="https://example.org" />
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Qr/Arena.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Qr } from '@tempoxyz/ds'
+
+<Qr />
+```
+
+## Guidelines
+
+### When to Use
+
+* Show a deposit address in a receive flow, for a scan from another wallet.
+* Move a link from a computer to a phone, such as a payment request.
+
+### When Not to Use
+
+* Use a link or `Button.Link` ([Button](/docs/components/button)) for a URL opened on the same device.
+* Use [Hex](/docs/components/hex) with `copy` alone when the reader needs the value on the same device. A phone cannot scan its own screen.
+
+### Show the Address as Text Too
+
+Many people cannot scan: someone on the same phone, a screen reader user, or someone without a camera.
+
+* **Copy:** Put the address beside the code with [Hex](/docs/components/hex) and `copy`.
+* **Match:** The text must match what the code encodes. If the code holds a URI, such as `tempo:` and the address, show the same address. Never encode a different value, such as a tracking link.
+* **Network:** A code does not show its network. State what the address accepts, such as Send USDC on Tempo to this address.
+
+**Do:** Show the address with a copy button, and the network it accepts, beside the code.
+
+```tsx
+/**
+ * Do example for "Show the Address as Text Too" on the Qr page.
+ * Show the address with a copy button, and the network it accepts, beside the code.
+ * @module
+ */
+import { Hex, Qr, style } from '@tempoxyz/ds'
+
+const address = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Qr aria-label="Deposit address QR code" size="small" value={address} />
+      <span {...styles.note()}>Send USDC on Tempo to this address</span>
+      <Hex copy size="small" value={address} variant="filled" {...styles.hex()} />
+    </div>
+  )
+}
+
+namespace styles {
+  export const hex = style({ width: '100% !custom' })
+
+  export const note = style({
+    color: 'content.secondary',
+    textAlign: 'center',
+    typography: 'body.b3',
+  })
+
+  export const stack = style({
+    display: 'grid',
+    gap: '12',
+    justifyItems: 'center',
+    width: '100% !custom',
+  })
+}
+```
+
+**Don't:** Show a code without the value it encodes.
+
+```tsx
+/**
+ * Don't example for "Show the Address as Text Too" on the Qr page.
+ * Don't show a code without the value it encodes.
+ * @module
+ */
+import { Qr } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return <Qr size="small" value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" />
+}
+```
+
+### Keep Contrast and Clear Space
+
+* **Dark mode:** The modules turn light on a dark ground, and some scanners cannot read inverted codes. If older scanners matter, use a light panel and set `color` to a dark value with 3:1 contrast in both schemes.
+* **Clear space:** Keep borders, text, and controls off the edges of the code.
+
+**Do:** Place the code on a plain background with space around it.
+
+```tsx
+/**
+ * Do example for "Keep Contrast and Clear Space" on the Qr page.
+ * Place the code on a plain background with space around it.
+ * @module
+ */
+import { Qr, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.panel()}>
+      <Qr
+        aria-label="Deposit address QR code"
+        size="small"
+        value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
+      />
+    </div>
+  )
+}
+
+namespace styles {
+  export const panel = style({
+    backgroundColor: 'background.primary',
+    borderRadius: 'sm',
+    padding: '24',
+  })
+}
+```
+
+**Don't:** Place the code over an image or gradient.
+
+```tsx
+/**
+ * Don't example for "Keep Contrast and Clear Space" on the Qr page.
+ * Don't place the code over an image or gradient.
+ * @module
+ */
+import { Qr, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.panel()}>
+      <Qr
+        aria-label="Deposit address QR code"
+        size="small"
+        value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
+      />
+    </div>
+  )
+}
+
+namespace styles {
+  export const panel = style({
+    backgroundImage: 'linear-gradient(135deg, #3b82f6, #a855f7 50%, #f97316) !custom',
+    borderRadius: 'sm',
+    padding: '4',
+  })
+}
+```
+
+### Use a Logo Only at Larger Sizes
+
+`arena` draws a logo in the center and raises error correction to medium, so scanners recover the covered modules. Use the token's logo or Tempo's.
+
+**Do:** Add a logo only to a `medium` or `large` code.
+
+```tsx
+/**
+ * Do example for "Use a Logo Only at Larger Sizes" on the Qr page.
+ * Add a logo only to a `medium` or `large` code.
+ * @module
+ */
+import { Qr } from '@tempoxyz/ds'
+import pathUsd from '../../coins/PathUSD.svg'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Qr
+      arena={pathUsd}
+      aria-label="Deposit address QR code"
+      size="medium"
+      value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
+    />
+  )
+}
+```
+
+**Don't:** Add a logo to a `small` code.
+
+```tsx
+/**
+ * Don't example for "Use a Logo Only at Larger Sizes" on the Qr page.
+ * Don't add a logo to a `small` code.
+ * @module
+ */
+import { Qr } from '@tempoxyz/ds'
+import pathUsd from '../../coins/PathUSD.svg'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Qr
+      arena={pathUsd}
+      aria-label="Deposit address QR code"
+      size="small"
+      value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
+    />
+  )
+}
+```
+
+### Size for the Screen
+
+* **Small (160px):** In a panel beside other content.
+* **Medium (240px):** The default, for a receive dialog.
+* **Large (320px):** The roomiest size, for a code with a logo.
+
+## Accessibility
+
+Qr renders an `<svg>` with the `img` role. It is not interactive and takes no focus.
+
+### Semantics
+
+* **Root (img):** An image that screen readers announce by its name.
+* **Name (aria-label):** Defaults to "QR code for" and the full value.
+* **Arena (Arena):** Set `arena` to an image URL to add a logo, announced as a nested image.
+* **Modules (foreground):** On a transparent ground, so the code follows the light or dark scheme.
+
+### Your Responsibilities
+
+* **Name It by Purpose (aria-label):** Describe what it encodes, such as "Deposit address QR code".
+* **Name the Logo (arena):** Pass a node with its own accessible name, or make sure the logo's name adds no noise.
+
+## Related
+
+[Hex](/docs/components/hex)
+
+Use for showing and copying the address.
+
+[CopyButton](/docs/components/copy-button)
+
+Use for copying a value.
+
+[Snippet](/docs/components/snippet)
+
+Use for links and other values.
+
+[Payments](/docs/patterns/payments)
+
+Covers send and receive flows.
+
+[Tempo Wallet](/docs/products/tempo-wallet)
+
+Covers the receive screen.