@tempoxyz/ds 0.3.10 → 0.3.13

package/dist/docs/product/components/accordion.md

@@ -0,0 +1,489 @@
+# Accordion
+
+Stacks collapsible sections that each reveal a labelled panel.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Accordion.tsx)
+
+## Overview
+
+Each trigger toggles a labelled panel. By default, one item is open at a time.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Accordion, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Accordion.Root defaultValue={['one']} {...styles.root()}>
+      <Accordion.Item value="one">
+        <Accordion.Trigger>What is Tempo?</Accordion.Trigger>
+        <Accordion.Panel>A blockchain for payments.</Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item value="two">
+        <Accordion.Trigger>How do fees work?</Accordion.Trigger>
+        <Accordion.Panel>Fees are paid in stablecoins.</Accordion.Panel>
+      </Accordion.Item>
+    </Accordion.Root>
+  )
+}
+
+namespace styles {
+  export const root = style({ maxWidth: '28rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Accordion/Basic.tsx)
+
+### Size
+
+Set `size` to `small`, `medium` (default), or `large`.
+
+```tsx
+import { Accordion, Stack, style } from '@tempoxyz/ds'
+
+export const fill = true
+function Items(props: Accordion.Root.Props) {
+  return (
+    <Accordion.Root {...props}>
+      <Accordion.Item value="one">
+        <Accordion.Trigger>What is Tempo?</Accordion.Trigger>
+        <Accordion.Panel>A blockchain for payments.</Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item value="two">
+        <Accordion.Trigger>How do fees work?</Accordion.Trigger>
+        <Accordion.Panel>Fees are paid in stablecoins.</Accordion.Panel>
+      </Accordion.Item>
+    </Accordion.Root>
+  )
+}
+
+export function Demo() {
+  return (
+    <Stack gap="32" {...styles.stack()}>
+      {(['small', 'medium', 'large'] as const).map((size) => (
+        <Items defaultValue={['one']} key={size} size={size} />
+      ))}
+    </Stack>
+  )
+}
+
+namespace styles {
+  export const stack = style({ maxWidth: '28rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Accordion/Size.tsx)
+
+### Multiple
+
+Set `multiple` on `Accordion.Root` to keep several items open at once.
+
+```tsx
+import { Accordion, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Accordion.Root multiple {...styles.root()}>
+      <Accordion.Item value="one">
+        <Accordion.Trigger>What is Tempo?</Accordion.Trigger>
+        <Accordion.Panel>A blockchain for payments.</Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item value="two">
+        <Accordion.Trigger>How do fees work?</Accordion.Trigger>
+        <Accordion.Panel>Fees are paid in stablecoins.</Accordion.Panel>
+      </Accordion.Item>
+    </Accordion.Root>
+  )
+}
+
+namespace styles {
+  export const root = style({ maxWidth: '28rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Accordion/Multiple.tsx)
+
+### Disabled
+
+Set `disabled` on an `Accordion.Item` to block it from opening.
+
+```tsx
+import { Accordion, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Accordion.Root {...styles.root()}>
+      <Accordion.Item value="one">
+        <Accordion.Trigger>What is Tempo?</Accordion.Trigger>
+        <Accordion.Panel>A blockchain for payments.</Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item disabled value="three">
+        <Accordion.Trigger>Disabled</Accordion.Trigger>
+        <Accordion.Panel>Hidden.</Accordion.Panel>
+      </Accordion.Item>
+    </Accordion.Root>
+  )
+}
+
+namespace styles {
+  export const root = style({ maxWidth: '28rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Accordion/Disabled.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Accordion } from '@tempoxyz/ds'
+
+<Accordion.Root>
+  <Accordion.Item>
+    <Accordion.Trigger />
+    <Accordion.Panel />
+  </Accordion.Item>
+</Accordion.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Shorten a page of related, optional content, such as fee help answers or advanced webhook settings.
+* Let people scan summaries and open only the sections they need.
+
+### When Not to Use
+
+* Use [Tabs](tabs.md) to switch between views of equal weight, such as Balances and Activity.
+* Use [ListGroup](list-group.md) for facts people check at a glance, such as the amount and fee of a payment.
+* Use [Stepper](stepper.md) for steps people complete in order.
+* If most people need the content, keep it visible in a [Surface](surface.md), such as the amount and fee on a payment review.
+
+### Summarize the Panel in the Trigger
+
+A closed panel shows only its trigger. Write each trigger so people can tell what the panel holds before they open it.
+
+**Do:** Write triggers that say what each panel contains.
+
+```tsx
+/**
+ * Do example for "Summarize the Panel in the Trigger" on the Accordion page.
+ * Write triggers that say what each panel contains.
+ * @module
+ */
+import { Accordion } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Accordion.Root>
+      <Accordion.Item value="cost">
+        <Accordion.Trigger>What does a transfer cost?</Accordion.Trigger>
+        <Accordion.Panel>Each transfer pays a network fee in a stablecoin.</Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item value="settle">
+        <Accordion.Trigger>When does a payment settle?</Accordion.Trigger>
+        <Accordion.Panel>A payment settles when its block is final.</Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item value="tokens">
+        <Accordion.Trigger>Which tokens can pay fees?</Accordion.Trigger>
+        <Accordion.Panel>Supported stablecoins, such as PathUSD and USDC.</Accordion.Panel>
+      </Accordion.Item>
+    </Accordion.Root>
+  )
+}
+```
+
+**Don't:** Use labels such as Details, More info, or Other.
+
+```tsx
+/**
+ * Don't example for "Summarize the Panel in the Trigger" on the Accordion page.
+ * Don't use labels such as Details, More info, or Other.
+ * @module
+ */
+import { Accordion } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Accordion.Root>
+      <Accordion.Item value="details">
+        <Accordion.Trigger>Details</Accordion.Trigger>
+        <Accordion.Panel>Each transfer pays a network fee in a stablecoin.</Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item value="more">
+        <Accordion.Trigger>More info</Accordion.Trigger>
+        <Accordion.Panel>A payment settles when its block is final.</Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item value="other">
+        <Accordion.Trigger>Other</Accordion.Trigger>
+        <Accordion.Panel>Supported stablecoins, such as PathUSD and USDC.</Accordion.Panel>
+      </Accordion.Item>
+    </Accordion.Root>
+  )
+}
+```
+
+### Open the Item Most People Need
+
+Opening one item closes the others. Open the item most people need with `defaultValue`. If people compare panels, such as two groups of webhook settings, set `multiple`.
+
+**Do:** Open one item by default, the one most people need.
+
+```tsx
+/**
+ * Do example for "Open the Item Most People Need" on the Accordion page.
+ * Open one item by default, the one most people need.
+ * @module
+ */
+import { Accordion } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Accordion.Root defaultValue={['cost']}>
+      <Accordion.Item value="cost">
+        <Accordion.Trigger>What does a transfer cost?</Accordion.Trigger>
+        <Accordion.Panel>Each transfer pays a network fee in a stablecoin.</Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item value="settle">
+        <Accordion.Trigger>When does a payment settle?</Accordion.Trigger>
+        <Accordion.Panel>A payment settles when its block is final.</Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item value="tokens">
+        <Accordion.Trigger>Which tokens can pay fees?</Accordion.Trigger>
+        <Accordion.Panel>Supported stablecoins, such as PathUSD and USDC.</Accordion.Panel>
+      </Accordion.Item>
+    </Accordion.Root>
+  )
+}
+```
+
+**Don't:** Open every item when people read one at a time.
+
+```tsx
+/**
+ * Don't example for "Open the Item Most People Need" on the Accordion page.
+ * Don't open every item when people read one at a time.
+ * @module
+ */
+import { Accordion } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Accordion.Root defaultValue={['cost', 'settle', 'tokens']} multiple>
+      <Accordion.Item value="cost">
+        <Accordion.Trigger>What does a transfer cost?</Accordion.Trigger>
+        <Accordion.Panel>Each transfer pays a network fee in a stablecoin.</Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item value="settle">
+        <Accordion.Trigger>When does a payment settle?</Accordion.Trigger>
+        <Accordion.Panel>A payment settles when its block is final.</Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item value="tokens">
+        <Accordion.Trigger>Which tokens can pay fees?</Accordion.Trigger>
+        <Accordion.Panel>Supported stablecoins, such as PathUSD and USDC.</Accordion.Panel>
+      </Accordion.Item>
+    </Accordion.Root>
+  )
+}
+```
+
+### Keep Panels Short and Flat
+
+Keep each panel to a few short paragraphs, a list, or a small form. Link to a separate page for more.
+
+**Do:** Answer in a sentence or two inside the panel.
+
+```tsx
+/**
+ * Do example for "Keep Panels Short and Flat" on the Accordion page.
+ * Answer in a sentence or two inside the panel.
+ * @module
+ */
+import { Accordion } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Accordion.Root defaultValue={['retry']}>
+      <Accordion.Item value="retry">
+        <Accordion.Trigger>Retry policy</Accordion.Trigger>
+        <Accordion.Panel>Failed deliveries retry 5 times over 24 hours.</Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item value="signing">
+        <Accordion.Trigger>Signing secret</Accordion.Trigger>
+        <Accordion.Panel>Each delivery is signed with the webhook's secret.</Accordion.Panel>
+      </Accordion.Item>
+    </Accordion.Root>
+  )
+}
+```
+
+**Don't:** Nest an accordion inside a panel.
+
+```tsx
+/**
+ * Don't example for "Keep Panels Short and Flat" on the Accordion page.
+ * Don't nest an accordion inside a panel.
+ * @module
+ */
+import { Accordion } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Accordion.Root defaultValue={['retry']}>
+      <Accordion.Item value="retry">
+        <Accordion.Trigger>Retry policy</Accordion.Trigger>
+        <Accordion.Panel>
+          <Accordion.Root defaultValue={['attempts']} size="small">
+            <Accordion.Item value="attempts">
+              <Accordion.Trigger>Attempts</Accordion.Trigger>
+              <Accordion.Panel>Failed deliveries retry 5 times over 24 hours.</Accordion.Panel>
+            </Accordion.Item>
+          </Accordion.Root>
+        </Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item value="signing">
+        <Accordion.Trigger>Signing secret</Accordion.Trigger>
+        <Accordion.Panel>Each delivery is signed with the webhook's secret.</Accordion.Panel>
+      </Accordion.Item>
+    </Accordion.Root>
+  )
+}
+```
+
+### Keep Collapsed Content Reachable
+
+Closed panels unmount. Set the prop that matches the content, on `Accordion.Root` or an `Accordion.Panel`.
+
+* **Searchable Text (hiddenUntilFound):** Lets find in page search closed panels and open the one that matches.
+* **Form Inputs (keepMounted):** Keeps the values of form inputs when their panel closes.
+
+### Explain Instead of Disabling
+
+A disabled item hides content without a reason. Remove the item, or keep it enabled and explain in the panel what is unavailable.
+
+**Do:** Keep the item enabled, and state in the panel when it becomes available.
+
+```tsx
+/**
+ * Do example for "Explain Instead of Disabling" on the Accordion page.
+ * Keep the item enabled, and state in the panel when it becomes available.
+ * @module
+ */
+import { Accordion } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Accordion.Root defaultValue={['withdraw']}>
+      <Accordion.Item value="deposit">
+        <Accordion.Trigger>Deposit funds</Accordion.Trigger>
+        <Accordion.Panel>Send USDC to your wallet address.</Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item value="withdraw">
+        <Accordion.Trigger>Withdraw funds</Accordion.Trigger>
+        <Accordion.Panel>Withdrawals open after you verify your identity.</Accordion.Panel>
+      </Accordion.Item>
+    </Accordion.Root>
+  )
+}
+```
+
+**Don't:** Disable an item without a reason.
+
+```tsx
+/**
+ * Don't example for "Explain Instead of Disabling" on the Accordion page.
+ * Don't disable an item without a reason.
+ * @module
+ */
+import { Accordion } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Accordion.Root>
+      <Accordion.Item value="deposit">
+        <Accordion.Trigger>Deposit funds</Accordion.Trigger>
+        <Accordion.Panel>Send USDC to your wallet address.</Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item disabled value="withdraw">
+        <Accordion.Trigger>Withdraw funds</Accordion.Trigger>
+        <Accordion.Panel>Withdrawals open after you verify your identity.</Accordion.Panel>
+      </Accordion.Item>
+    </Accordion.Root>
+  )
+}
+```
+
+## Content
+
+* Use questions for help content and nouns for settings groups, such as Retry policy.
+* Keep one form across items: all questions or all nouns.
+* Answer in the first sentence of the panel, then add detail.
+* Don't repeat the trigger at the top of its panel.
+
+## Accessibility
+
+Each item pairs a heading button with its panel, following the [WAI-ARIA Accordion pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) for required keys.
+
+### Semantics
+
+* **Accordion.Trigger (button):** A native button inside a heading, reachable by heading navigation.
+* **Expanded State (aria-expanded):** Reports whether the panel is open. `aria-controls` points at the panel.
+* **Accordion.Panel (region):** Each panel is labelled by its trigger.
+* **Disabled Items (aria-disabled):** A disabled trigger stays in the tab order.
+* **Chevron (aria-hidden):** Hidden from assistive technology.
+
+### Keyboard
+
+* **Move to the Next Trigger (Tab):** Moves focus to the next trigger or into the open panel.
+* **Move to the Previous Control (Shift+Tab):** Moves focus to the previous trigger or control.
+* **Open or Close the Item (Enter or Space):** Opens or closes the focused item. Without `multiple`, it also closes the open one.
+
+The arrow keys do not move focus between triggers.
+
+### Focus
+
+* **Focus Stays Put:** Focus stays on the trigger when its panel opens or closes.
+* **Closed Panels (keepMounted):** A closed panel unmounts by default and leaves the tab order.
+
+### Motion
+
+* **Reduced Motion (prefers-reduced-motion):** Panels fade without animating their height, and the chevron flips instantly.
+
+### Your Responsibilities
+
+* **Fit the Outline (h3):** Triggers render inside an `h3`, so place the accordion under an `h2`.
+* **Keep Triggers Plain:** Don't put controls inside a trigger. It is already a button.
+
+## Related
+
+[Tabs](tabs.md)
+
+Use for switching between views.
+
+[ListGroup](list-group.md)
+
+Use for expanding a detail under one row.
+
+[Stepper](stepper.md)
+
+Use for sequential steps.
+
+[Surface](surface.md)
+
+Use for content that stays visible.

package/dist/docs/product/components/address-card.md

@@ -0,0 +1,147 @@
+# AddressCard
+
+Shows a wallet address to receive funds, with its QR code and networks.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/AddressCard.tsx)
+
+Figma: [Content/Address Card](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-4005)
+
+## Overview
+
+An address card renders a bordered receive card. A QR code of the address sits beside the shortened address, a copy button, and the networks that the address accepts.
+
+## Examples
+
+### Basic
+
+Pass the full `address`. The card shows its first and last four characters.
+
+```tsx
+/** Demonstrates AddressCard in the documentation. @module */
+import { AddressCard, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.frame()}>
+      <AddressCard address="0x7a3f2c9b1e4d8a6f0c5b3e7d9a1f4c8e2b6d91c2" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const frame = style({ maxWidth: '28.75rem !custom', width: '100% !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/AddressCard/Basic.tsx)
+
+### Networks
+
+Add `AddressCard.Networks` with one `AddressCard.Network` per network. Set `selected` on the picked one.
+
+```tsx
+/** Demonstrates AddressCard in the documentation. @module */
+import { AddressCard, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.frame()}>
+      <AddressCard address="0x7a3f2c9b1e4d8a6f0c5b3e7d9a1f4c8e2b6d91c2">
+        <AddressCard.Networks>
+          <AddressCard.Network network="ethereum" selected>
+            Ethereum
+          </AddressCard.Network>
+          <AddressCard.Network network="base">Base</AddressCard.Network>
+          <AddressCard.Network network="solana">Solana</AddressCard.Network>
+          <AddressCard.Network network="tempo">Tempo</AddressCard.Network>
+        </AddressCard.Networks>
+      </AddressCard>
+    </div>
+  )
+}
+
+namespace styles {
+  export const frame = style({ maxWidth: '28.75rem !custom', width: '100% !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/AddressCard/Networks.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { AddressCard } from '@tempoxyz/ds'
+
+<AddressCard>
+  <AddressCard.Networks>
+    <AddressCard.Network />
+  </AddressCard.Networks>
+</AddressCard>
+```
+
+## Guidelines
+
+### When to Use
+
+* Show the address that a person sends funds to, such as on a deposit screen.
+* Let a person scan the address from another device or copy it.
+
+### When Not to Use
+
+* Use [Hex](hex.md) for an address inside a row or a sentence.
+* Use [Qr](qr.md) alone for a code that encodes something other than an address.
+
+### List Only the Accepted Networks
+
+**Do:** List the networks that the address accepts.
+
+```tsx
+<AddressCard address="0x7a3f2c9b1e4d8a6f0c5b3e7d9a1f4c8e2b6d91c2">
+  <AddressCard.Networks>
+    <AddressCard.Network network="tempo" selected>
+      Tempo
+    </AddressCard.Network>
+    <AddressCard.Network network="base">Base</AddressCard.Network>
+  </AddressCard.Networks>
+</AddressCard>
+```
+
+**Don't:** Leave out the networks when the address accepts only some of them.
+
+```tsx
+<AddressCard address="0x7a3f2c9b1e4d8a6f0c5b3e7d9a1f4c8e2b6d91c2" />
+```
+
+### Keep the Full Address
+
+Pass the whole address. The card shortens the text, and the copy button and QR code use the full value.
+
+## Content
+
+* **Label:** Name the address from the reader's view, such as Your wallet address.
+* **Networks:** Name each network as its brand does, such as Ethereum or Base.
+
+## Accessibility
+
+The card renders a `<div>` with no role. Screen readers read the full address, the named QR code, the copy button, and the network group.
+
+* **Address (Full value):** Screen readers read every character, not the shortened text.
+* **Copy (button):** The copy button announces Copied after a copy.
+* **Networks (group):** The label names the group of network chips.
+* **Pick a Network (aria-pressed):** A chip with an onClick announces its selected state.
+
+## Related
+
+[Hex](hex.md)
+
+Use for an address inside a row or a sentence.
+
+[Qr](qr.md)
+
+Use for a QR code of another value.
+
+[AssetChip](asset-chip.md)
+
+Use for the chips of supported assets.