@tempoxyz/ds 0.3.10 → 0.3.13

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

@@ -0,0 +1,639 @@
+# Surface
+
+A card container for grouping related content.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Surface.tsx)
+
+Figma: [Content/Card](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-5510)
+
+## Overview
+
+A surface renders a `div` with a thin border by default. Its `size` sets the corner radius and the padding to the same value.
+
+## Examples
+
+### Basic
+
+```tsx
+import { style, Surface } from '@tempoxyz/ds'
+import { SwapHorizontal } from '@tempoxyz/ds/icons'
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      <Surface>
+        <Surface.Header>
+          <Surface.Title>
+            <SwapHorizontal />
+            Routes
+          </Surface.Title>
+        </Surface.Header>
+        <Surface.Description>
+          Move stablecoins between Tempo and other networks.
+        </Surface.Description>
+        <Surface.Links>
+          <a href="#basic">Make a transfer</a>
+          <a href="#basic">Accept deposits</a>
+          <a href="#basic">Supported routes</a>
+        </Surface.Links>
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const grid = style({
+    alignItems: 'start',
+    backgroundColor: 'background.primary',
+    display: 'grid',
+    gap: '12',
+    padding: '16',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(14rem, 1fr)) !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Surface/Basic.tsx)
+
+### Header
+
+Place a `Surface.Title` and an optional action inside `Surface.Header`.
+
+```tsx
+import { Button, style, Surface, TokenLogo } from '@tempoxyz/ds'
+
+const balances = [
+  ['Bridged USDC (Stargate)', '0x20c000000000000000000000b9537d11c60e8b50', '$2.02'],
+  ['pathUSD', '0x20c0000000000000000000000000000000000000', '$0.12'],
+  ['USDT0', '0x20c00000000000000000000014f22ca97301eb73', '$0.10'],
+] as const
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      <Surface>
+        <Surface.Header>
+          <Surface.Title>Balances</Surface.Title>
+          <Button size="small" variant="tertiary">
+            View all
+          </Button>
+        </Surface.Header>
+        {balances.map(([name, address, amount]) => (
+          <div key={address} {...styles.balance()}>
+            <TokenLogo address={address} />
+            <span {...styles.name()}>{name}</span>
+            {amount}
+          </div>
+        ))}
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const balance = style({
+    alignItems: 'center',
+    columnGap: '12',
+    display: 'flex',
+    paddingBlock: '8',
+    typography: 'body.b1Strong',
+  })
+
+  export const grid = style({
+    backgroundColor: 'background.primary',
+    display: 'grid',
+    padding: '16',
+  })
+
+  export const name = style({ flex: '1 !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Surface/Header.tsx)
+
+### List
+
+A [ListGroup](list-group.md) inside a surface bleeds into its padding, so a row's hover fill reaches the edges of the surface. Each row is 44px, and a [Select](select.md) in a row hugs its value at the end of the row.
+
+```tsx
+/** Renders a small surface whose list holds a network picker and a row of token logos, for the Surface docs. @module */
+import { ListGroup, NetworkLogo, Select, style, Surface, TokenLogo } from '@tempoxyz/ds'
+
+const networks = [
+  { available: true, id: 'tempo', name: 'Tempo' },
+  { available: false, id: 'ethereum', name: 'Ethereum' },
+  { available: false, id: 'base', name: 'Base' },
+] as const
+
+const stablecoins = [
+  ['pathUSD', '0x20c0000000000000000000000000000000000000'],
+  ['Bridged USDC (Stargate)', '0x20c000000000000000000000b9537d11c60e8b50'],
+  ['USDT0', '0x20c00000000000000000000014f22ca97301eb73'],
+] as const
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      <Surface size="small">
+        <ListGroup>
+          <ListGroup.Row>
+            <ListGroup.Label id="surface-list-network">Network</ListGroup.Label>
+            <Select.Root value="tempo">
+              <Select.Trigger aria-labelledby="surface-list-network">
+                <Select.Value>
+                  {() => (
+                    <span {...styles.value()}>
+                      <NetworkLogo network="tempo" size="medium" />
+                      Tempo
+                    </span>
+                  )}
+                </Select.Value>
+                <Select.Icon />
+              </Select.Trigger>
+              <Select.Popup align="end">
+                {networks.map((network) => (
+                  <Select.Item disabled={!network.available} key={network.id} value={network.id}>
+                    <Select.ItemPrefix>
+                      <NetworkLogo network={network.id} size="medium" />
+                    </Select.ItemPrefix>
+                    <Select.ItemText>{network.name}</Select.ItemText>
+                    {network.available ? null : <Select.ItemSuffix>Coming soon</Select.ItemSuffix>}
+                  </Select.Item>
+                ))}
+              </Select.Popup>
+            </Select.Root>
+          </ListGroup.Row>
+          <ListGroup.Row>
+            <ListGroup.Label>Supported stablecoins</ListGroup.Label>
+            <span {...styles.coins()}>
+              {stablecoins.map(([symbol, address]) => (
+                <TokenLogo address={address} alt={symbol} key={address} />
+              ))}
+            </span>
+          </ListGroup.Row>
+        </ListGroup>
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const coins = style({ display: 'flex', gap: '4', marginInlineStart: 'auto !custom' })
+
+  export const grid = style({ display: 'grid', maxWidth: '25rem !custom', width: '100% !custom' })
+
+  export const value = style({ alignItems: 'center', display: 'flex', gap: '8' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Surface/List.tsx)
+
+### Size
+
+Set `size` to `small`, `medium`, or `large` (default).
+
+```tsx
+import { style, Surface } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      {(['large', 'medium', 'small'] as const).map((size) => (
+        <Surface key={size} size={size}>
+          Size {size}
+        </Surface>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  // Surfaces keep their content height instead of stretching to the tallest one in a row.
+  export const grid = style({
+    alignItems: 'start',
+    backgroundColor: 'background.primary',
+    display: 'grid',
+    gap: '12',
+    padding: '16',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(14rem, 1fr)) !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Surface/Size.tsx)
+
+### Render
+
+Pass a `button` or link to `render` for a pressable surface with hover, press, and focus styles.
+
+```tsx
+import { style, Surface } from '@tempoxyz/ds'
+import { SwapHorizontal } from '@tempoxyz/ds/icons'
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      <Surface render={<a href="#render" />}>
+        <Surface.Header>
+          <Surface.Title>
+            <SwapHorizontal />
+            Routes
+          </Surface.Title>
+        </Surface.Header>
+        <Surface.Description>
+          Move stablecoins between Tempo and other networks.
+        </Surface.Description>
+      </Surface>
+      <Surface render={<button type="button" />}>Interactive button</Surface>
+      <Surface render={<a href="#render" />}>Interactive link</Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  // Surfaces keep their content height instead of stretching to the tallest one in a row.
+  export const grid = style({
+    alignItems: 'start',
+    backgroundColor: 'background.primary',
+    display: 'grid',
+    gap: '12',
+    padding: '16',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(14rem, 1fr)) !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Surface/Render.tsx)
+
+### Disabled
+
+Set `disabled` on a pressable surface to block interaction.
+
+```tsx
+import { style, Surface } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      <Surface disabled render={<button type="button" />}>
+        Disabled button
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const grid = style({
+    alignItems: 'start',
+    backgroundColor: 'background.primary',
+    display: 'grid',
+    padding: '16',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(14rem, 1fr)) !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Surface/Disabled.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Surface } from '@tempoxyz/ds'
+
+<Surface>
+  <Surface.Header>
+    <Surface.Title />
+  </Surface.Header>
+  <Surface.Description />
+  <Surface.Links />
+</Surface>
+```
+
+## Guidelines
+
+### When to Use
+
+* Group related content into a card, such as a wallet's Balance, an Activity list, or an API key's details.
+* Make a whole card pressable when it leads to one place, such as a project card that opens its dashboard.
+
+### When Not to Use
+
+* Use [Alert](alert.md) for a message about a section, and [Banner](banner.md) for one about the page.
+* Use [Dialog](dialog.md) or [Popover](popover.md) for content that opens over the page.
+* Use [Stack](stack.md) or [Inset](inset.md) to space content without a visible container.
+* Use [Frame](frame.md) inside a surface for a card with a footer of actions.
+
+### Name Each Card
+
+Start a card with a `Surface.Header` that holds a `Surface.Title`. Put a card-level action at the end of the header, such as a `small` `tertiary` [Button](button.md).
+
+**Do:** Name the card with a `Surface.Title`, and put its action at the end of the header.
+
+```tsx
+/**
+ * Do example for "Name Each Card" on the Surface page.
+ * Name the card with a `Surface.Title`, and put its action at the end of the header.
+ * @module
+ */
+import { Amount, Button, ListGroup, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.canvas()}>
+      <Surface size="medium">
+        <Surface.Header>
+          <Surface.Title>Balances</Surface.Title>
+          <Button size="small" variant="tertiary">
+            View all
+          </Button>
+        </Surface.Header>
+        <ListGroup dividers={false}>
+          <ListGroup.Row>
+            <ListGroup.Label>USDC</ListGroup.Label>
+            <Amount value="1250.00" />
+          </ListGroup.Row>
+          <ListGroup.Row>
+            <ListGroup.Label>pathUSD</ListGroup.Label>
+            <Amount value="80.25" />
+          </ListGroup.Row>
+        </ListGroup>
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const canvas = style({
+    backgroundColor: 'background.primary',
+    borderRadius: 'sm',
+    boxSizing: 'border-box',
+    padding: '12',
+    width: '100% !custom',
+  })
+}
+```
+
+**Don't:** Start a card with its content.
+
+```tsx
+/** Don't example for "Name Each Card" on the Surface page. Don't start a card with its content. @module */
+import { Amount, ListGroup, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.canvas()}>
+      <Surface size="medium">
+        <ListGroup dividers={false}>
+          <ListGroup.Row>
+            <ListGroup.Label>USDC</ListGroup.Label>
+            <Amount value="1250.00" />
+          </ListGroup.Row>
+          <ListGroup.Row>
+            <ListGroup.Label>pathUSD</ListGroup.Label>
+            <Amount value="80.25" />
+          </ListGroup.Row>
+        </ListGroup>
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const canvas = style({
+    backgroundColor: 'background.primary',
+    borderRadius: 'sm',
+    boxSizing: 'border-box',
+    padding: '12',
+    width: '100% !custom',
+  })
+}
+```
+
+### Match Size to Density
+
+* **Large (24px):** The default, for page cards such as Balances.
+* **Medium (16px):** For dashboard tiles, such as TPS.
+* **Small (12px):** For compact tiles, such as Block time.
+
+Keep one size across cards that sit side by side.
+
+### Keep Pressable Cards Free of Other Controls
+
+A surface rendered as a link or button is one target, and screen readers announce the whole card as one control.
+
+**Do:** Make the whole card one link with a short title.
+
+```tsx
+/**
+ * Do example for "Keep Pressable Cards Free of Other Controls" on the Surface page.
+ * Make the whole card one link with a short title.
+ * @module
+ */
+import { style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.canvas()}>
+      <Surface render={<a href="#" />} size="medium">
+        <span {...styles.title()}>Production key</span>
+        <span {...styles.meta()}>Created 3 days ago</span>
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const canvas = style({
+    backgroundColor: 'background.primary',
+    borderRadius: 'sm',
+    padding: '16',
+    width: '16rem !custom',
+  })
+
+  export const meta = style({ color: 'content.secondary', display: 'block', typography: 'body.b3' })
+
+  export const title = style({ display: 'block', typography: 'body.b1Strong' })
+}
+```
+
+**Don't:** Place a button inside a pressable card.
+
+```tsx
+/**
+ * Don't example for "Keep Pressable Cards Free of Other Controls" on the Surface page.
+ * Don't place a button inside a pressable card.
+ * @module
+ */
+import { Button, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.canvas()}>
+      <Surface render={<a href="#" />} size="medium">
+        <span {...styles.title()}>Production key</span>
+        <span {...styles.meta()}>Created 3 days ago</span>
+        <Button size="small" {...styles.action()}>
+          Revoke key
+        </Button>
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const action = style({ marginBlockStart: '12' })
+
+  export const canvas = style({
+    backgroundColor: 'background.primary',
+    borderRadius: 'sm',
+    padding: '16',
+    width: '16rem !custom',
+  })
+
+  export const meta = style({ color: 'content.secondary', display: 'block', typography: 'body.b3' })
+
+  export const title = style({ display: 'block', typography: 'body.b1Strong' })
+}
+```
+
+### Don't Nest Surfaces
+
+Divide the content of one surface with [ListGroup](list-group.md), a [Table](table.md), or a [Separator](separator.md). A table placed directly inside a surface bleeds 12px into its padding, so its rows end 12px inside the edges of a large surface and its text stays on the content edge. The surface draws no border around it.
+
+**Do:** Divide one surface with ListGroup.
+
+```tsx
+/** Do example for "Don't Nest Surfaces" on the Surface page: divide one surface with ListGroup. @module */
+import { Amount, Hex, ListGroup, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.canvas()}>
+      <Surface size="medium">
+        <ListGroup>
+          <ListGroup.Row>
+            <ListGroup.Label>Amount</ListGroup.Label>
+            <Amount symbol="USDC" value="48.50" />
+          </ListGroup.Row>
+          <ListGroup.Row>
+            <ListGroup.Label>Recipient</ListGroup.Label>
+            <Hex value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" />
+          </ListGroup.Row>
+        </ListGroup>
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const canvas = style({
+    backgroundColor: 'background.primary',
+    borderRadius: 'sm',
+    boxSizing: 'border-box',
+    padding: '12',
+    width: '100% !custom',
+  })
+}
+```
+
+**Don't:** Place surfaces inside a surface.
+
+```tsx
+/** Don't example for "Don't Nest Surfaces" on the Surface page. Don't place surfaces inside a surface. @module */
+import { Amount, Hex, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.canvas()}>
+      <Surface size="medium" {...styles.outer()}>
+        <Surface size="small" {...styles.row()}>
+          <span>Amount</span>
+          <Amount symbol="USDC" value="48.50" />
+        </Surface>
+        <Surface size="small" {...styles.row()}>
+          <span>Recipient</span>
+          <Hex value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" />
+        </Surface>
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const canvas = style({
+    backgroundColor: 'background.primary',
+    borderRadius: 'sm',
+    boxSizing: 'border-box',
+    padding: '12',
+    width: '100% !custom',
+  })
+
+  export const outer = style({ display: 'flex', flexDirection: 'column', gap: '8' })
+
+  export const row = style({
+    alignItems: 'center',
+    backgroundColor: 'container.regular',
+    display: 'flex',
+    justifyContent: 'space-between',
+  })
+}
+```
+
+## Content
+
+* Write titles as short nouns, such as Balances, Activity, or Routes.
+* Keep `Surface.Description` to one or two sentences.
+* Use `Surface.Links` for two or three follow-up tasks, written as verbs, such as Make a transfer.
+
+## Accessibility
+
+A surface takes its semantics from the element you render, such as a `section`, a `button`, or a link.
+
+### Semantics
+
+* **Default Element (div):** Carries no role.
+* **Surface.Title (h2):** Lets screen reader users find the card by heading.
+* **Surface.Description (p):** A plain paragraph under the title.
+* **Pressable Cards (button or link):** The whole card becomes one control, named by its text.
+* **Disabled (aria-disabled):** Dims the card and drops pointer events. Only a button also stops keyboard activation.
+
+### Keyboard
+
+For a pressable surface rendered as a button or link:
+
+* **Move Focus to the Card (Tab):** Moves focus to the card.
+* **Activate a Link or Button (Enter):** Activates a link or button card.
+* **Activate a Button (Space):** Activates a button card.
+
+### Your Responsibilities
+
+* **Name Regions (aria-labelledby):** If the card is a distinct region, render a section labelled by its title.
+* **Fit the Outline (h2):** Place cards where their title's heading level fits the page outline.
+* **Keep Pressable Text Short:** The card's full content becomes its accessible name, so keep its text short.
+* **Disabling Link Cards (href):** A link can't be disabled. Remove its `href` when it must not work.
+
+## Related
+
+[Frame](frame.md)
+
+Use for a header, body, and footer inside a card.
+
+[ListGroup](list-group.md)
+
+Use for divided content in a card.
+
+[Grid](grid.md)
+
+Use for laying out several cards.
+
+[Dashboards](../patterns/dashboards.md)
+
+Covers metric tiles.