@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/avatar.md

@@ -0,0 +1,321 @@
+# Avatar
+
+Represents a person, contact, or wallet with an image, initials, or an icon.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Avatar.tsx)
+
+Figma: [Avatar](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=1418-13100)
+
+## Overview
+
+An avatar is a circle that holds an image, or initials or an icon in secondary text on a neutral fill. It leads a list row or a modal header.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Avatar } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Avatar.Root>
+      <Avatar.Fallback>J</Avatar.Fallback>
+    </Avatar.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Avatar/Basic.tsx)
+
+### Size
+
+Set `size` to `16`, `24`, `32`, `40` (default), `48`, or `64`.
+
+```tsx
+import { Avatar, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {(['16', '24', '32', '40', '48', '64'] as const).map((size) => (
+        <Avatar.Root key={size} size={size}>
+          <Avatar.Fallback>J</Avatar.Fallback>
+        </Avatar.Root>
+      ))}
+    </div>
+  )
+}
+
+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/Avatar/Size.tsx)
+
+### Icon
+
+Put an icon in `Avatar.Fallback` for a wallet or app. It renders at 16px in a `24` or `32` avatar, and at 20px in a `40` avatar.
+
+```tsx
+import { Avatar, style } from '@tempoxyz/ds'
+import { Wallet } from '@tempoxyz/ds/icons'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {(['24', '32', '40'] as const).map((size) => (
+        <Avatar.Root key={size} size={size}>
+          <Avatar.Fallback>
+            <Wallet />
+          </Avatar.Fallback>
+        </Avatar.Root>
+      ))}
+    </div>
+  )
+}
+
+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/Avatar/Icon.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Avatar } from '@tempoxyz/ds'
+
+<Avatar />
+
+<Avatar.Root>
+  <Avatar.Image />
+  <Avatar.Fallback />
+</Avatar.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Represent a person or organization beside their name, such as a contact in Send or a merchant in activity.
+* Represent a wallet or app with an icon, such as a connected wallet in a list row.
+
+### When Not to Use
+
+* Use [Identicon](/docs/components/identicon) for an account known only by its address.
+* Use [TokenLogo](/docs/components/token-logo) for the icon of a token or asset.
+* Use [IconTile](/docs/components/icon-tile) for the icon above a centered modal title.
+
+### Choose Avatar or Identicon
+
+* **Person or Organization (Avatar):** A name, shown as initials.
+* **Address Only (Identicon):** An account known only by its address.
+* **Mixed List (Avatar.Fallback):** A mix of both, with an identicon in the fallback.
+
+### Always Include a Fallback
+
+* **People and organizations:** Use initials.
+* **Wallets and apps:** Use an icon.
+* **Accounts known by address:** Use an [Identicon](/docs/components/identicon) with `size="fill"`.
+
+**Do:** Give every avatar a fallback, such as initials, an icon, or an `Identicon`.
+
+```tsx
+/**
+ * Do example for "Always Include a Fallback" on the Avatar page.
+ * Give every avatar a fallback, such as initials, an icon, or an `Identicon`.
+ * @module
+ */
+import { Avatar, Identicon, style } from '@tempoxyz/ds'
+import { Wallet } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Avatar size="40">
+        <Avatar.Fallback>AL</Avatar.Fallback>
+      </Avatar>
+      <Avatar size="40">
+        <Avatar.Fallback>
+          <Wallet />
+        </Avatar.Fallback>
+      </Avatar>
+      <Avatar size="40">
+        <Avatar.Fallback>
+          <Identicon address="0x71C7656EC7ab88b098defB751B7401B5f6d8976F" aria-hidden size="fill" />
+        </Avatar.Fallback>
+      </Avatar>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+}
+```
+
+**Don't:** Leave an empty circle.
+
+```tsx
+/**
+ * Don't example for "Always Include a Fallback" on the Avatar page.
+ * Don't leave an empty circle.
+ * @module
+ */
+import { Avatar, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Avatar size="40" />
+      <Avatar size="40" />
+      <Avatar size="40" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+}
+```
+
+### Pair the Avatar With a Name
+
+Hide the avatar with `aria-hidden` beside a visible name, so screen readers don't read the initials and the name.
+
+**Do:** Show the name, and a detail such as an email, beside each avatar.
+
+```tsx
+/**
+ * Do example for "Pair the Avatar With a Name" on the Avatar page.
+ * Show the name, and a detail such as an email, beside each avatar.
+ * @module
+ */
+import { Avatar, style } from '@tempoxyz/ds'
+
+const contacts = [
+  ['JC', 'Jane Cooper', 'jane@example.com'],
+  ['AL', 'Ada Lovelace', 'ada@example.com'],
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      {contacts.map(([initials, name, email]) => (
+        <div key={name} {...styles.row()}>
+          <Avatar aria-hidden size="40">
+            <Avatar.Fallback>{initials}</Avatar.Fallback>
+          </Avatar>
+          <div {...styles.text()}>
+            <span {...styles.name()}>{name}</span>
+            <span {...styles.detail()}>{email}</span>
+          </div>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const detail = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const list = style({ display: 'grid', gap: '12', width: '100% !custom' })
+
+  export const name = style({ color: 'content.primary', typography: 'body.b2Strong' })
+
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+
+  export const text = style({ display: 'flex', flexDirection: 'column', gap: '4' })
+}
+```
+
+**Don't:** Ask people to pick a recipient from initials alone.
+
+```tsx
+/**
+ * Don't example for "Pair the Avatar With a Name" on the Avatar page.
+ * Don't ask people to pick a recipient from pictures or initials alone.
+ * @module
+ */
+import { Avatar, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {['JC', 'AL', 'MR', 'JD'].map((initials) => (
+        <Avatar key={initials} size="40">
+          <Avatar.Fallback>{initials}</Avatar.Fallback>
+        </Avatar>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+}
+```
+
+### Match Size to the Layout
+
+* **Inline and Dense Rows (24):** Inline with text and in dense table rows.
+* **List Rows (32):** List rows, such as recipients in a modal.
+* **Header Lead (40):** The default. The lead of a header.
+
+### Use Initials for People and Icons for Wallets
+
+* **Person or Contact (Initials):** One or two initials from the name.
+* **Wallet or App (Icon):** One icon from the library, in the text color.
+
+In a modal, leave out brand colors, so every avatar keeps the neutral fill.
+
+## Content
+
+* **Initials:** Use one or two, such as AL for Ada Lovelace. The fallback uppercases them.
+* **Organizations:** Use the first letter of the name, not an unfamiliar abbreviation.
+* **Wallets and apps:** Use an icon instead of letters.
+
+## Accessibility
+
+Renders a `<span>` that holds the fallback.
+
+### Semantics
+
+* **Avatar.Fallback (span):** Plain text. Screen readers read the initials as written.
+* **Icon Fallback (aria-hidden):** Icons without an `aria-label` are hidden, so the avatar is silent.
+
+### Keyboard
+
+An avatar takes no focus. To open a profile, wrap the avatar and name in one link, and let the name label it.
+
+### Your Responsibilities
+
+* **Hide a Duplicate Avatar (aria-hidden):** If the name is visible beside the avatar, hide the root so screen readers skip the initials.
+* **Name a Standalone Avatar (aria-label):** If no name is visible, set `role="img"` and an `aria-label` with the full name on the root.
+
+## Related
+
+[Identicon](/docs/components/identicon)
+
+Use for accounts known by address.
+
+[TokenLogo](/docs/components/token-logo)
+
+Use for token icons.
+
+[IconTile](/docs/components/icon-tile)
+
+Use for the icon above a centered modal title.
+
+[ListGroup](/docs/components/list-group)
+
+Use for lists of people and accounts.

package/dist/docs/components/badge.md

@@ -0,0 +1,339 @@
+# Badge
+
+Labels a status or category in a compact chip.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Badge.tsx)
+
+Figma: [Badge](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=1186-3286), [Icon Badge](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=1191-4539)
+
+## Overview
+
+A compact chip at least 80px wide, in one of five `variant` fills and two sizes, or a square or round chip that holds one icon. It renders a `<span>` unless you pass `render`.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Badge } from '@tempoxyz/ds'
+
+export function Demo() {
+  return <Badge>Routes</Badge>
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Badge/Basic.tsx)
+
+### Variant
+
+Set `variant` to `soft` (default), `outlined`, `elevated`, `inverse`, or `accent`.
+
+```tsx
+import { Badge, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Badge>Routes</Badge>
+      <Badge variant="outlined">Testnet</Badge>
+      <Badge variant="elevated">New</Badge>
+      <Badge variant="inverse">Recommended</Badge>
+      <Badge variant="accent">Beta</Badge>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({
+    alignItems: 'center',
+    backgroundColor: 'container.regular',
+    borderRadius: 'xs',
+    display: 'flex',
+    flexWrap: 'wrap',
+    gap: '8',
+    padding: '16',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Badge/Variant.tsx)
+
+### Size
+
+Set `size` to `small` (28px) or `medium` (32px, the default).
+
+```tsx
+import { Badge, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {(['small', 'medium'] as const).map((size) => (
+        <Badge key={size} size={size}>
+          {size}
+        </Badge>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Badge/Size.tsx)
+
+### Shape
+
+Set `shape="icon"` for a badge that holds one icon. A `medium` icon badge is a 32px square, and a `small` one is a 24px circle.
+
+```tsx
+import { Badge, style } from '@tempoxyz/ds'
+import { ArrowRight } from '@tempoxyz/ds/icons'
+
+export function Demo() {
+  return (
+    <div {...styles.rows()}>
+      {(['medium', 'small'] as const).map((size) => (
+        <div key={size} {...styles.row()}>
+          {(['soft', 'outlined', 'elevated', 'inverse', 'accent'] as const).map((variant) => (
+            <Badge key={variant} shape="icon" size={size} variant={variant}>
+              <ArrowRight />
+            </Badge>
+          ))}
+        </div>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
+
+  export const rows = style({ display: 'grid', gap: '12' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Badge/Shape.tsx)
+
+### Render
+
+Pass a `button` or link to `render` for an interactive badge with pointer, focus, and press feedback.
+
+```tsx
+import { Badge, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {(['small', 'medium'] as const).map((size) => (
+        <Badge key={size} render={<button type="button" />} size={size}>
+          Stablecoins
+        </Badge>
+      ))}
+      <Badge render={<button type="button" />} variant="accent">
+        Accent chip
+      </Badge>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Badge/Render.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Badge } from '@tempoxyz/ds'
+
+<Badge />
+```
+
+## Guidelines
+
+### When to Use
+
+* Label an attribute next to a title or row value, such as Routes, New address, or Testnet.
+* Label the status of a record in words, such as Confirmed, Pending, or Failed.
+* Build compact filters, such as Stablecoins, with `render={<button type="button" />}`.
+
+### When Not to Use
+
+* Use an [Alert](/docs/components/alert) or [Banner](/docs/components/banner) for a message that needs a sentence.
+* Use a [Button](/docs/components/button) for an action, such as Retry.
+* Use the `status` of a [Table](/docs/components/table) cell to color a status in a table.
+* Use a [ChoiceGroup](/docs/components/choice-group) to switch between two to four views.
+* Use [Kbd](/docs/components/kbd) for keyboard keys.
+
+### Choose a Variant by Emphasis
+
+* **Soft (soft):** The default. Attributes and categories on any surface.
+* **Outlined (outlined):** Lower emphasis, such as a network beside its name.
+* **Elevated (elevated):** A white fill that stands out on a tinted surface.
+* **Inverse (inverse):** The strongest fill, for one recommended option.
+* **Accent (accent):** Something new or highlighted, such as Beta.
+
+### Keep One Variant per Context
+
+Use one variant for every badge in a list or column, so only the label differs.
+
+**Do:** Keep one variant per list or column, so only the status differs.
+
+```tsx
+/**
+ * Do example for "Keep One Variant per Context" on the Badge page.
+ * Keep one variant per list or column, so only the status differs.
+ * @module
+ */
+import { Badge, style } from '@tempoxyz/ds'
+
+const payments = [
+  { address: '0x8f3c…a21b', status: 'Confirmed', variant: 'outlined' },
+  { address: '0x41d0…9c7e', status: 'Pending', variant: 'outlined' },
+  { address: '0xb27a…04f5', status: 'Failed', variant: 'outlined' },
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      {payments.map((payment) => (
+        <div {...styles.row()} key={payment.address}>
+          <span>{payment.address}</span>
+          <Badge size="small" variant={payment.variant}>
+            {payment.status}
+          </Badge>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const list = style({
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '12',
+    width: '100% !custom',
+  })
+
+  export const row = style({
+    alignItems: 'center',
+    display: 'flex',
+    justifyContent: 'space-between',
+    typography: 'mono.m1',
+  })
+}
+```
+
+**Don't:** Mix `soft`, `outlined`, and `inverse` badges in one list.
+
+```tsx
+/**
+ * Don't example for "Keep One Variant per Context" on the Badge page.
+ * Don't mix `soft`, `outlined`, and `inverse` tags in one list.
+ * @module
+ */
+import { Badge, style } from '@tempoxyz/ds'
+
+const payments = [
+  { address: '0x8f3c…a21b', status: 'Confirmed', variant: 'soft' },
+  { address: '0x41d0…9c7e', status: 'Pending', variant: 'outlined' },
+  { address: '0xb27a…04f5', status: 'Failed', variant: 'inverse' },
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      {payments.map((payment) => (
+        <div {...styles.row()} key={payment.address}>
+          <span>{payment.address}</span>
+          <Badge size="small" variant={payment.variant}>
+            {payment.status}
+          </Badge>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const list = style({
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '12',
+    width: '100% !custom',
+  })
+
+  export const row = style({
+    alignItems: 'center',
+    display: 'flex',
+    justifyContent: 'space-between',
+    typography: 'mono.m1',
+  })
+}
+```
+
+### Make a Badge Interactive Only for an Action
+
+* **Display (span):** A status or attribute. Keep the default `span`.
+* **Action (render):** Pass a button or link only if the badge does something.
+
+## Content
+
+* Keep the text to one or two words in sentence case, such as Expiring soon.
+* Describe a state, not an action. Write Failed, not Retry.
+* Use one word for one state across a product, such as Confirmed everywhere, not Confirmed in one place and Complete in another.
+* Tags don't wrap, so a long label overflows its cell.
+
+## Accessibility
+
+A badge renders a `<span>` with no role, so screen readers read its text inline.
+
+### Semantics
+
+* **Root (span):** Screen readers read its text in place, as part of the surrounding content.
+* **Render (render):** Takes the semantics of the button or link you pass, with a focus outline and press scale.
+* **Variant (variant):** Changes only the fill, sets no state or role, and isn't announced. The text must name it.
+
+### Keyboard
+
+A static badge takes no focus. A badge rendered as a button or link is a native control:
+
+* **Move Focus to the Badge (Tab):** Moves focus to the badge.
+* **Activate or Follow (Enter):** Activates a button badge or follows a link badge.
+* **Activate a Button Badge (Space):** Activates a button badge.
+
+### Your Responsibilities
+
+* **Name Meaningful Icons (aria-label):** If an icon badge carries meaning, set `role="img"` and an `aria-label` that names it.
+* **Use Native Controls (button or a):** Pass a native button or link to `render`, so keyboards reach it. Don't add `onClick` to a static span.
+* **Add Context (aria-describedby):** If a badge sits apart from its subject, add context, so "Pending" isn't read alone.
+* **Report Toggle State (aria-pressed):** A filter badge must report whether it is pressed, so its state is announced.
+* **Size Interactive Badges (24px):** Both sizes clear the 24px minimum target. Use medium where people tap.
+
+## Related
+
+[Table](/docs/components/table)
+
+Use for status columns.
+
+[Alert](/docs/components/alert)
+
+Use for messages about a section.
+
+[ChoiceGroup](/docs/components/choice-group)
+
+Use for switching views.
+
+[Feedback and Status](/docs/patterns/feedback-and-status)
+
+Covers status conventions.