@tempoxyz/ds 0.3.10 → 0.3.13

package/dist/docs/product/components/asset-chip.md

@@ -0,0 +1,294 @@
+# AssetChip
+
+Labels a supported asset or network in a small chip, which can also pick one.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/AssetChip.tsx)
+
+Figma: [Elements/Asset Chip](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-2626)
+
+## Overview
+
+An asset chip renders a small gray label for something a row or value supports, such as the assets a network accepts. Place a [TokenLogo](token-logo.md) before the text to add a 12px token logo. Give it an `onClick` to pick one asset from a short set.
+
+## Examples
+
+### Basic
+
+```tsx
+import { AssetChip, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <AssetChip>USDC</AssetChip>
+      <AssetChip>USDT</AssetChip>
+    </div>
+  )
+}
+
+namespace styles {
+  // Chips sit on a modal's elevated surface in the designs, and share the page's fill otherwise.
+  export const row = style({
+    alignItems: 'center',
+    backgroundColor: 'background.elevated',
+    borderRadius: 'xs',
+    display: 'flex',
+    gap: '4',
+    padding: '16',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/AssetChip/Basic.tsx)
+
+### Logo
+
+A nested [TokenLogo](token-logo.md) renders at 12px, whatever its `size`.
+
+```tsx
+import { AssetChip, style, TokenLogo } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <TokenLogo.Provider>
+      <div {...styles.row()}>
+        <AssetChip>
+          <TokenLogo address="0x20c0000000000000000000000000000000000000" />
+          pathUSD
+        </AssetChip>
+        <AssetChip>
+          <TokenLogo address="0x20c000000000000000000000b9537d11c60e8b50" />
+          USDC.e
+        </AssetChip>
+      </div>
+    </TokenLogo.Provider>
+  )
+}
+
+namespace styles {
+  // Chips sit on a modal's elevated surface in the designs, and share the page's fill otherwise.
+  export const row = style({
+    alignItems: 'center',
+    backgroundColor: 'background.elevated',
+    borderRadius: 'xs',
+    display: 'flex',
+    gap: '4',
+    padding: '16',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/AssetChip/Logo.tsx)
+
+### Selectable
+
+An `onClick` renders a button. Set `selected` on the picked chip, which fills dark.
+
+```tsx
+import { AssetChip, style } from '@tempoxyz/ds'
+import { useState } from 'react'
+
+const assets = ['USDC', 'USDT', 'pathUSD'] as const
+
+export function Demo() {
+  const [asset, setAsset] = useState<(typeof assets)[number]>(assets[0])
+
+  return (
+    <div aria-label="Pay with" role="group" {...styles.row()}>
+      {assets.map((entry) => (
+        <AssetChip key={entry} onClick={() => setAsset(entry)} selected={asset === entry}>
+          {entry}
+        </AssetChip>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  // Chips sit on a modal's elevated surface in the designs, and share the page's fill otherwise.
+  export const row = style({
+    alignItems: 'center',
+    backgroundColor: 'background.elevated',
+    borderRadius: 'xs',
+    display: 'flex',
+    gap: '4',
+    padding: '16',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/AssetChip/Selectable.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { AssetChip, TokenLogo } from '@tempoxyz/ds'
+
+<AssetChip>
+  <TokenLogo />
+</AssetChip>
+```
+
+## Guidelines
+
+### When to Use
+
+* List the assets a network supports under the title of a network row.
+* Name a supported asset after a value, such as an address that accepts USDC.
+* Pick one asset from a short set, such as the asset to pay with.
+
+### When Not to Use
+
+* Use [Badge](badge.md) to show a status, such as Pending.
+* Use [Token](token.md) for a token that a person can change.
+* Use [Button](button.md) for an action other than picking an asset.
+
+### List What a Row Supports
+
+Asset chips stay quiet, so they don't compete with the row title or with status tags.
+
+**Do:** Place the chips under the row title, one per supported asset.
+
+```tsx
+/**
+ * Do example for "List What a Row Supports" on the AssetChip page.
+ * Place asset chips under the title of a network row.
+ * @module
+ */
+import { AssetChip, NetworkLogo, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <NetworkLogo network="base" size="large" />
+      <div {...styles.text()}>
+        <span {...styles.title()}>Base</span>
+        <div {...styles.chips()}>
+          <AssetChip>USDC</AssetChip>
+          <AssetChip>USDT</AssetChip>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const chips = style({ display: 'flex', gap: '4' })
+
+  // The row sits on a modal's elevated surface, as in the designs, so the chips keep their fill.
+  export const row = style({
+    alignItems: 'center',
+    backgroundColor: 'background.elevated',
+    borderRadius: 'xs',
+    display: 'flex',
+    gap: '12',
+    padding: '16',
+  })
+
+  export const text = style({ display: 'grid', gap: '4' })
+
+  export const title = style({ color: 'content.primary', typography: 'body.b2Strong' })
+}
+```
+
+**Don't:** Use an asset chip to show a status. Use a [Badge](badge.md).
+
+```tsx
+/**
+ * Don't example for "List What a Row Supports" on the AssetChip page.
+ * An asset chip used as a status reads as a supported asset.
+ * @module
+ */
+import { AssetChip, NetworkLogo, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <NetworkLogo network="base" size="large" />
+      <div {...styles.text()}>
+        <span {...styles.title()}>Base</span>
+        <div {...styles.chips()}>
+          <AssetChip>Congested</AssetChip>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const chips = style({ display: 'flex', gap: '4' })
+
+  // The row sits on a modal's elevated surface, as in the designs, so the chips keep their fill.
+  export const row = style({
+    alignItems: 'center',
+    backgroundColor: 'background.elevated',
+    borderRadius: 'xs',
+    display: 'flex',
+    gap: '12',
+    padding: '16',
+  })
+
+  export const text = style({ display: 'grid', gap: '4' })
+
+  export const title = style({ color: 'content.primary', typography: 'body.b2Strong' })
+}
+```
+
+### Add a Logo Only When It Helps
+
+* **Text:** The default, for a list of familiar assets.
+* **Logo:** For an asset that people find by its logo.
+
+## Content
+
+### Use the Symbol
+
+Write the asset's ticker symbol, such as USDC or pathUSD, or the network's name, such as Base. Don't add words such as Supported or Accepted. The row title gives that context.
+
+## Accessibility
+
+An asset chip renders a `<span>` with no role, so screen readers read its text inline. With an `onClick`, it renders a `<button>` that takes focus and announces `selected` as pressed.
+
+### Semantics
+
+* **Root (span):** Screen readers read its text in place, as part of the surrounding content.
+* **Logo (alt):** A nested token logo has empty alt text, so screen readers read the symbol once, from the chip text.
+* **Selected (aria-pressed):** A chip with an `onClick` announces `selected` as pressed, so screen readers read the pick.
+
+### Keyboard
+
+A static chip takes no focus. A chip with an `onClick` is a native button:
+
+* **Move Focus to the Chip (Tab):** Moves focus to the next chip in the set.
+* **Pick the Asset (Enter or Space):** Runs the chip's `onClick`, which sets the picked asset.
+
+### Your Responsibilities
+
+* **Keep Chips Beside Their Row:** Keep the chips next to the row title, so screen readers read the assets with it.
+* **Name the Set (aria-label):** Wrap selectable chips in a group with a label, so screen readers read what they pick.
+
+## Related
+
+[TokenLogo](token-logo.md)
+
+Use for token logos.
+
+[Token](token.md)
+
+Use for a token that a person can change.
+
+[NetworkLogo](network-logo.md)
+
+Use for network logos.
+
+[Badge](badge.md)
+
+Use for statuses.
+
+[ListGroup](list-group.md)
+
+Use for network and asset lists.