@tempoxyz/ds 0.3.10 → 0.3.11

package/dist/docs/components/token-logo.md

@@ -0,0 +1,371 @@
+# TokenLogo
+
+Shows a token logo by contract address or symbol.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/TokenLogo.tsx)
+
+Figma: [Elements/Logo](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-2546)
+
+## Overview
+
+A token logo renders a stablecoin's artwork, found by contract address or symbol, with its brand colors. Its `alt` is empty unless set, which suits a logo beside the token name.
+
+## Examples
+
+### Basic
+
+```tsx
+import { style, TokenLogo } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <TokenLogo.Provider>
+      <div {...styles.row()}>
+        <TokenLogo address="0x20c0000000000000000000000000000000000000" />
+        pathUSD
+      </div>
+    </TokenLogo.Provider>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TokenLogo/Basic.tsx)
+
+### Size
+
+Set `size` to `small` (16px), `medium` (20px, default), or `large` (32px).
+
+```tsx
+import { style, TokenLogo } from '@tempoxyz/ds'
+
+const tokens = [
+  ['pathUSD', '0x20c0000000000000000000000000000000000000'],
+  ['USDC.e', '0x20c000000000000000000000b9537d11c60e8b50'],
+  ['EURC.e', '0x20c0000000000000000000001621e21f71cf12fb'],
+  ['USDT0', '0x20c00000000000000000000014f22ca97301eb73'],
+  ['frxUSD', '0x20c0000000000000000000003554d28269e0f3c2'],
+] as const
+
+export function Demo() {
+  return (
+    <TokenLogo.Provider>
+      <div {...styles.grid()}>
+        {tokens.map(([label, address]) => (
+          <div key={address} {...styles.row()}>
+            {(['small', 'medium', 'large'] as const).map((size) => (
+              <TokenLogo address={address} key={size} size={size} />
+            ))}
+            {label}
+          </div>
+        ))}
+      </div>
+    </TokenLogo.Provider>
+  )
+}
+
+namespace styles {
+  export const grid = style({ display: 'grid', gap: '12' })
+
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TokenLogo/Size.tsx)
+
+### Symbol
+
+Pass `symbol` instead of `address` to resolve the token through the token list.
+
+```tsx
+import { style, TokenLogo } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <TokenLogo.Provider>
+      <div {...styles.row()}>
+        <TokenLogo size="large" symbol="pathUSD" />
+        By symbol: pathUSD
+      </div>
+    </TokenLogo.Provider>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TokenLogo/Symbol.tsx)
+
+### Fallback
+
+An unknown address or symbol renders a placeholder.
+
+```tsx
+import { style, TokenLogo } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <TokenLogo.Provider>
+      <div {...styles.grid()}>
+        <div {...styles.row()}>
+          <TokenLogo address="0x0000000000000000000000000000000000000001" size="large" />
+          Unknown address (service placeholder)
+        </div>
+        <div {...styles.row()}>
+          <TokenLogo size="large" symbol="UNKNOWN" />
+          Unknown symbol (fallback)
+        </div>
+      </div>
+    </TokenLogo.Provider>
+  )
+}
+
+namespace styles {
+  export const grid = style({ display: 'grid', gap: '12' })
+
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TokenLogo/Fallback.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { TokenLogo } from '@tempoxyz/ds'
+
+<TokenLogo.Provider>
+  <TokenLogo />
+</TokenLogo.Provider>
+```
+
+## Guidelines
+
+### When to Use
+
+* Show a token's logo beside its symbol in balance lists, token selectors, payment reviews, and activity rows.
+
+### When Not to Use
+
+* Use [Token](/docs/components/token) to show which token an amount is in, and to let a person change it.
+* Use [Identicon](/docs/components/identicon) for an account address.
+* Use [Avatar](/docs/components/avatar) for people and organizations.
+* Use [IconTile](/docs/components/icon-tile) for a feature or category icon.
+* Use [NetworkLogo](/docs/components/network-logo) for the chain a token lives on.
+* Use [AssetChip](/docs/components/asset-chip) to list the assets a row supports.
+
+### Pair the Icon With the Symbol
+
+Many token icons look alike, and an unknown token can copy a well-known icon.
+
+**Do:** Show the symbol beside each token icon.
+
+```tsx
+/**
+ * Do example for "Pair the Icon With the Symbol" on the TokenLogo page.
+ * Show the symbol beside each token icon.
+ * @module
+ */
+import { style, TokenLogo } from '@tempoxyz/ds'
+
+const tokens = [
+  ['pathUSD', '0x20c0000000000000000000000000000000000000'],
+  ['USDC.e', '0x20c000000000000000000000b9537d11c60e8b50'],
+  ['EURC.e', '0x20c0000000000000000000001621e21f71cf12fb'],
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <TokenLogo.Provider>
+      <div {...styles.list()}>
+        {tokens.map(([symbol, address]) => (
+          <div key={address} {...styles.row()}>
+            <TokenLogo address={address} />
+            <span {...styles.symbol()}>{symbol}</span>
+          </div>
+        ))}
+      </div>
+    </TokenLogo.Provider>
+  )
+}
+
+namespace styles {
+  export const list = style({ display: 'grid', gap: '12' })
+
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+
+  export const symbol = style({ color: 'content.primary', typography: 'body.b2Strong' })
+}
+```
+
+**Don't:** Ask people to tell tokens apart by icon alone.
+
+```tsx
+/**
+ * Don't example for "Pair the Icon With the Symbol" on the TokenLogo page.
+ * Don't ask people to tell tokens apart by icon alone.
+ * @module
+ */
+import { style, TokenLogo } from '@tempoxyz/ds'
+
+const addresses = [
+  '0x20c0000000000000000000000000000000000000',
+  '0x20c000000000000000000000b9537d11c60e8b50',
+  '0x20c0000000000000000000001621e21f71cf12fb',
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <TokenLogo.Provider>
+      <div {...styles.row()}>
+        {addresses.map((address) => (
+          <TokenLogo address={address} key={address} />
+        ))}
+      </div>
+    </TokenLogo.Provider>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+}
+```
+
+### Prefer the Address
+
+* **Address (address):** Use it when you have it. It loads the image directly and names one contract.
+* **Symbol (symbol):** Resolves through the token list first, which adds a request. Different tokens can share a symbol.
+* **Lists (TokenLogo.Provider):** Wrap lists so tokens share one lookup per symbol and a default `chainId`.
+
+Pass `resolveSrc` or `resolveAddress` to `TokenLogo.Provider` to load icons or addresses from your own source.
+
+### Show Unknown Tokens as Unknown
+
+A gray circle renders while an icon loads or after it fails.
+
+**Do:** Show the address in a [Hex](/docs/components/hex) beside the symbol of a token that isn't on the
+list.
+
+```tsx
+/**
+ * Do example for "Show Unknown Tokens as Unknown" on the TokenLogo page.
+ * Show the address in a Hex beside the symbol of a token that isn't on the list.
+ * @module
+ */
+import { Hex, style, TokenLogo } from '@tempoxyz/ds'
+
+const address = '0x20c00000000000000000000098a3f2c1e5d70b44'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <TokenLogo address={address} />
+      <div {...styles.text()}>
+        <span {...styles.symbol()}>USDC</span>
+        <Hex size="small" value={address} />
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12', minWidth: '0' })
+
+  export const symbol = style({ color: 'content.primary', typography: 'body.b2Strong' })
+
+  export const text = style({ display: 'grid', gap: '4', minWidth: '0' })
+}
+```
+
+**Don't:** Show only the symbol. Any token can claim it.
+
+```tsx
+/**
+ * Don't example for "Show Unknown Tokens as Unknown" on the TokenLogo page.
+ * Don't show only the symbol. Any token can claim it.
+ * @module
+ */
+import { style, TokenLogo } from '@tempoxyz/ds'
+
+const address = '0x20c00000000000000000000098a3f2c1e5d70b44'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <TokenLogo address={address} />
+      <span {...styles.symbol()}>USDC</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+
+  export const symbol = style({ color: 'content.primary', typography: 'body.b2Strong' })
+}
+```
+
+### Match Size to the Context
+
+* **Small (16px):** Inline beside an amount.
+* **Medium (20px):** The default, and the logo in a [Token](/docs/components/token).
+* **Large (32px):** In asset rows and token pickers.
+
+## Accessibility
+
+A token logo renders a native `<img>`, decorative by default. It is not interactive and takes no focus.
+
+### Semantics
+
+* **Root (img):** Has empty alt text by default, so screen readers skip it beside a visible name.
+* **Loading and Errors:** Renders a gray circle while loading or after an error. Text must identify the token.
+* **Data Status (data-status):** Reports `loading`, `loaded`, or `error` for styling. Screen readers don't announce it.
+
+### Your Responsibilities
+
+* **Name a Standalone Icon (alt):** If the icon stands alone, such as in an icon-only selector, pass the token name.
+
+## Related
+
+[Amount](/docs/components/amount)
+
+Use for token amounts.
+
+[Token](/docs/components/token)
+
+Use for a token pill that labels or picks a token.
+
+[AssetChip](/docs/components/asset-chip)
+
+Use for listing the assets a row supports.
+
+[NetworkLogo](/docs/components/network-logo)
+
+Use for the chain a token lives on.
+
+[Identicon](/docs/components/identicon)
+
+Use for account addresses.
+
+[Avatar](/docs/components/avatar)
+
+Use for people and organizations.
+
+[Select](/docs/components/select)
+
+Use for token selectors.
+
+[Blockchain Values](/docs/patterns/blockchain-values)
+
+Covers tokens and addresses.

package/dist/docs/components/token.md

@@ -0,0 +1,247 @@
+# Token
+
+Shows which token an amount is in, and opens a picker to change it.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Token.tsx)
+
+Figma: [Elements/Token](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-1266)
+
+## Overview
+
+A token renders a pill with a [TokenLogo](/docs/components/token-logo) and the token's symbol. By default it is a button with a chevron that opens a token picker. Set `readOnly` for a static pill.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Token, TokenLogo } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <TokenLogo.Provider>
+      <Token address="0x20c0000000000000000000000000000000000000" symbol="pathUSD" />
+    </TokenLogo.Provider>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Token/Basic.tsx)
+
+### Read-Only
+
+Set `readOnly` to render a span without the chevron, for reviews and receipts.
+
+```tsx
+import { Token, TokenLogo } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <TokenLogo.Provider>
+      <Token address="0x20c0000000000000000000000000000000000000" readOnly symbol="pathUSD" />
+    </TokenLogo.Provider>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Token/ReadOnly.tsx)
+
+### Picker
+
+Pass the token to a trigger's `render`, such as a [Dialog](/docs/components/dialog) trigger, to open a token picker.
+
+```tsx
+import { Dialog, style, Token, TokenLogo } from '@tempoxyz/ds'
+import { useState } from 'react'
+
+const tokens = [
+  ['pathUSD', '0x20c0000000000000000000000000000000000000'],
+  ['USDC.e', '0x20c000000000000000000000b9537d11c60e8b50'],
+  ['USDT0', '0x20c00000000000000000000014f22ca97301eb73'],
+] as const
+
+export function Demo() {
+  const [selected, setSelected] = useState<(typeof tokens)[number]>(tokens[0])
+
+  return (
+    <TokenLogo.Provider>
+      <Dialog.Root>
+        <Dialog.Trigger render={<Token address={selected[1]} symbol={selected[0]} />} />
+        <Dialog.Popup closeButton>
+          <Dialog.Header>
+            <Dialog.Title>Select token</Dialog.Title>
+          </Dialog.Header>
+          <Dialog.Body>
+            <div {...styles.list()}>
+              {tokens.map((token) => (
+                <Dialog.Close
+                  key={token[1]}
+                  onClick={() => setSelected(token)}
+                  render={<button type="button" {...styles.option()} />}
+                >
+                  <TokenLogo address={token[1]} size="large" />
+                  {token[0]}
+                </Dialog.Close>
+              ))}
+            </div>
+          </Dialog.Body>
+        </Dialog.Popup>
+      </Dialog.Root>
+    </TokenLogo.Provider>
+  )
+}
+
+namespace styles {
+  export const list = style({ display: 'grid', gap: '4' })
+
+  export const option = style({
+    alignItems: 'center',
+    backgroundColor: 'transparent !custom',
+    border: 'none !custom',
+    borderRadius: 'xs',
+    color: 'content.primary',
+    cursor: 'pointer',
+    display: 'flex',
+    gap: '12',
+    padding: '12',
+    textAlign: 'start',
+    typography: 'body.b2Strong',
+    selectors: { '&:hover': { backgroundColor: 'container.regular' } },
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Token/Picker.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Token } from '@tempoxyz/ds'
+
+<Token />
+```
+
+## Guidelines
+
+### When to Use
+
+* Name the token after the digits in an [AmountInput](/docs/components/amount-input), and let a person change it.
+* Name a fixed token in a review or a receipt with `readOnly`.
+
+### When Not to Use
+
+* Use [TokenLogo](/docs/components/token-logo) for a logo beside a symbol in a list row.
+* Use [AssetChip](/docs/components/asset-chip) to list the assets a row supports.
+* Use [Select](/docs/components/select) to choose a token in a form field with a label.
+
+### Show the Chevron Only on a Picker
+
+The chevron tells people that the token opens a picker.
+
+**Do:** Set `readOnly` in reviews and receipts, where the token can't change.
+
+```tsx
+/**
+ * Do example for "Show the Chevron Only on a Picker" on the Token page.
+ * Render a read-only pill where the token can't change.
+ * @module
+ */
+import { style, Token, TokenLogo } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <TokenLogo.Provider>
+      <div {...styles.row()}>
+        <span {...styles.amount()}>25.00</span>
+        <Token address="0x20c0000000000000000000000000000000000000" readOnly symbol="pathUSD" />
+      </div>
+    </TokenLogo.Provider>
+  )
+}
+
+namespace styles {
+  export const amount = style({ color: 'content.primary', typography: 'heading.h2' })
+
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+}
+```
+
+**Don't:** Show the chevron on a token that opens nothing.
+
+```tsx
+/**
+ * Don't example for "Show the Chevron Only on a Picker" on the Token page.
+ * A chevron on a token that can't change promises a picker that never opens.
+ * @module
+ */
+import { style, Token, TokenLogo } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <TokenLogo.Provider>
+      <div {...styles.row()}>
+        <span {...styles.amount()}>25.00</span>
+        <Token address="0x20c0000000000000000000000000000000000000" symbol="pathUSD" />
+      </div>
+    </TokenLogo.Provider>
+  )
+}
+
+namespace styles {
+  export const amount = style({ color: 'content.primary', typography: 'heading.h2' })
+
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+}
+```
+
+### Prefer the Address
+
+* **Address (address):** Loads the logo directly. `symbol` still labels the pill.
+* **Symbol (symbol):** Resolves the logo through the token list first.
+
+## Content
+
+### Use the Token's Symbol
+
+Write the symbol as the token defines it, such as pathUSD or USDC.e. Keep amounts, network names, and verbs outside the pill.
+
+## Accessibility
+
+A token renders a native `<button>` built on Base UI Button, or a `<span>` when `readOnly`. The logo and the chevron are hidden from screen readers.
+
+### Semantics
+
+* **Root (button):** The symbol names the button. A picker trigger adds popup state.
+* **Read-Only (readOnly):** Renders a span, so screen readers read the symbol as text.
+
+### Keyboard
+
+* **Move Focus to the Token (Tab):** Moves focus to the token.
+* **Open the Picker (Enter or Space):** Opens the picker that the token triggers.
+
+### Your Responsibilities
+
+* **Open a Picker (render):** Pass the token to a picker trigger's `render`. If nothing opens, set `readOnly`.
+* **Describe the Action (aria-label):** If the symbol alone doesn't say what the token does, add a label that keeps the symbol.
+
+## Related
+
+[TokenLogo](/docs/components/token-logo)
+
+Use for token logos.
+
+[AmountInput](/docs/components/amount-input)
+
+Use for entering an amount beside a token.
+
+[AssetChip](/docs/components/asset-chip)
+
+Use for listing the assets a row supports.
+
+[Dialog](/docs/components/dialog)
+
+Use for a token picker.