@tempoxyz/ds 0.3.10 → 0.3.13

package/dist/docs/product/patterns/tables-and-lists.md

@@ -0,0 +1,964 @@
+# Tables and Lists
+
+Present records, such as payments and API keys, to scan, compare, and act on.
+
+## Overview
+
+Tempo collections include wallet activity, scheduled payouts, API keys, webhooks, and blocks. Each needs a structure that fits its reading pattern, consistent alignment, and clear loading, empty, and narrow-screen states.
+
+> [!NOTE]
+> The live examples are reference layouts built from library components and `style`, not shipped components. No data grid component exists, so sorting, selection, and paging state live in your app.
+
+## Choose a Structure
+
+* **Table (Table):** Records compared across the same columns, such as payments, payouts, API keys, or blocks.
+* **ListGroup (ListGroup):** The key-value details of one record, settings, and navigation lists.
+* **Stacked List Items:** Items with a main line and a few attributes, such as activity. Also narrow-screen tables.
+
+**Do:** Use [ListGroup](../components/list-group.md) with `ListGroup.Label` for the fields of one
+record.
+
+```tsx
+/**
+ * Do example for "Tables and Lists" on the Tables and Lists page.
+ * Use ListGroup with `ListGroup.Label` for the fields of one record.
+ * @module
+ */
+import { ListGroup, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="small" {...styles.card()}>
+      <ListGroup.Root>
+        <ListGroup.Row>
+          <ListGroup.Label>Status</ListGroup.Label>
+          Confirmed
+        </ListGroup.Row>
+        <ListGroup.Row>
+          <ListGroup.Label>Amount</ListGroup.Label>
+          $1,200.00
+        </ListGroup.Row>
+        <ListGroup.Row>
+          <ListGroup.Label>Network fee</ListGroup.Label>
+          $0.00003
+        </ListGroup.Row>
+      </ListGroup.Root>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    boxShadow: '0 0 0 1px light-dark(#0000001a, #ffffff1f) !custom',
+    width: '16rem !custom',
+  })
+}
+```
+
+**Don't:** Build a two-column Field and Value table for a single record.
+
+```tsx
+/**
+ * Don't example for "Tables and Lists" on the Tables and Lists page.
+ * Don't build a two-column Field and Value table for a single record.
+ * @module
+ */
+import { style, Surface, Table } from '@tempoxyz/ds'
+
+const fields = [
+  ['Status', 'Confirmed'],
+  ['Amount', '$1,200.00'],
+  ['Network fee', '$0.00003'],
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="small" {...styles.card()}>
+      <Table.Root size="small">
+        <Table.Head>
+          <Table.Row>
+            <Table.HeaderCell>Field</Table.HeaderCell>
+            <Table.HeaderCell>Value</Table.HeaderCell>
+          </Table.Row>
+        </Table.Head>
+        <Table.Body>
+          {fields.map(([field, value]) => (
+            <Table.Row key={field}>
+              <Table.Cell>{field}</Table.Cell>
+              <Table.Cell>{value}</Table.Cell>
+            </Table.Row>
+          ))}
+        </Table.Body>
+      </Table.Root>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    boxShadow: '0 0 0 1px light-dark(#0000001a, #ffffff1f) !custom',
+    width: '16rem !custom',
+  })
+}
+```
+
+## Recommended Structure
+
+Place a table in a [Surface](../components/surface.md), with a `Surface.Header` above it for the title and actions. A direct child `table` bleeds into the padding of the surface, so row fills and dividers reach its edges.
+
+* **Header (1):** The title of the collection, filters, and actions such as Export CSV.
+* **Table (2):** The table itself, named by a caption or by `aria-labelledby`.
+* **Footer (3):** The visible range, such as 1–20 of 248, and pagination or a Load more button.
+
+## Align Columns by Content
+
+* **Start-Align Text:** Start-align text, such as names, descriptions, and dates.
+* **Monospace Identifiers (mono):** Use it for hashes and other identifiers. Shorten them in the middle with `formatHex`.
+* **Amount Last:** Put the amount in the last column where possible. The last column aligns to the end automatically.
+
+**Do:** End-align amounts and their headers with `justify="end"` and `numeric` cells, so decimals line
+up.
+
+```tsx
+/**
+ * Do example for "Tables and Lists" on the Tables and Lists page.
+ * End-align amounts and their headers with `justify="end"` and `numeric` cells, so decimals line up.
+ * @module
+ */
+import { style, Table } from '@tempoxyz/ds'
+
+const rows = [
+  ['Payroll', '$1,200.00'],
+  ['Hosting', '$48.50'],
+  ['Refund', '$9.99'],
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Table.Root size="small" {...styles.table()}>
+      <Table.Head>
+        <Table.Row>
+          <Table.HeaderCell>Payment</Table.HeaderCell>
+          <Table.HeaderCell justify="end">Amount</Table.HeaderCell>
+        </Table.Row>
+      </Table.Head>
+      <Table.Body>
+        {rows.map(([payment, amount]) => (
+          <Table.Row key={payment}>
+            <Table.Cell>{payment}</Table.Cell>
+            <Table.Cell justify="end" numeric>
+              {amount}
+            </Table.Cell>
+          </Table.Row>
+        ))}
+      </Table.Body>
+    </Table.Root>
+  )
+}
+
+namespace styles {
+  export const table = style({ maxWidth: '16rem !custom' })
+}
+```
+
+**Don't:** Start-align amounts. Digits of different lengths do not line up.
+
+```tsx
+/**
+ * Don't example for "Tables and Lists" on the Tables and Lists page.
+ * Don't start-align amounts. Digits of different lengths do not line up.
+ * @module
+ */
+import { style, Table } from '@tempoxyz/ds'
+
+const rows = [
+  ['$1,200.00', 'Payroll'],
+  ['$48.50', 'Hosting'],
+  ['$9.99', 'Refund'],
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Table.Root size="small" {...styles.table()}>
+      <Table.Head>
+        <Table.Row>
+          <Table.HeaderCell>Amount</Table.HeaderCell>
+          <Table.HeaderCell>Payment</Table.HeaderCell>
+        </Table.Row>
+      </Table.Head>
+      <Table.Body>
+        {rows.map(([amount, payment]) => (
+          <Table.Row key={payment}>
+            <Table.Cell>{amount}</Table.Cell>
+            <Table.Cell>{payment}</Table.Cell>
+          </Table.Row>
+        ))}
+      </Table.Body>
+    </Table.Root>
+  )
+}
+
+namespace styles {
+  export const table = style({ maxWidth: '16rem !custom' })
+}
+```
+
+## Keep Multi-Line Rows Readable
+
+A row with a wrapped description or a second line of detail grows taller than its neighbours. Keep each value whole and each row anchored to its first line.
+
+* **Top-Align Tall Rows (verticalAlign):** If any cell in a table wraps or adds a subtitle, top-align every cell, so each row reads from its first line.
+* **Keep Dates Whole (nowrap):** Keep a date and its time on one line. If the column is narrow, drop the time from secondary dates.
+* **Shorten Every Identifier (formatHex):** Shorten each address inside a compound value, such as a route. A symbol, such as USDC, stays whole.
+* **Wrap Prose Only (Table.Subtitle):** Let only sentences wrap. Put a secondary value in a `Table.Subtitle` below the cell's first line.
+
+**Do:** Top-align a tall row, keep the date on one line, and shorten each address in the route.
+
+```tsx
+/**
+ * Do example for "Keep Multi-Line Rows Readable" on the Tables and Lists page.
+ * Top-align a row whose cells wrap, keep dates whole, and shorten each address in a compound value.
+ * @module
+ */
+import { formatHex, style, Table } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Table.Root size="small" {...styles.table()}>
+      <Table.Head>
+        <Table.Row>
+          <Table.HeaderCell>Route</Table.HeaderCell>
+          <Table.HeaderCell>Updated</Table.HeaderCell>
+        </Table.Row>
+      </Table.Head>
+      <Table.Body>
+        <Table.Row>
+          <Table.Cell mono {...styles.top()}>
+            {formatHex('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', { evm: false })} →{' '}
+            {formatHex('0x20c0000000000000000000000000000000000000')}
+            <Table.Subtitle>Chain 792703809 → 4217</Table.Subtitle>
+          </Table.Cell>
+          <Table.Cell {...styles.date()}>Oct 9, 2026, 12:04 AM</Table.Cell>
+        </Table.Row>
+      </Table.Body>
+    </Table.Root>
+  )
+}
+
+namespace styles {
+  export const date = style({ verticalAlign: 'top', whiteSpace: 'nowrap' })
+
+  export const table = style({ maxWidth: '18rem !custom' })
+
+  export const top = style({ verticalAlign: 'top' })
+}
+```
+
+**Don't:** Let a full address or a date wrap across lines in a middle-aligned row.
+
+```tsx
+/**
+ * Don't example for "Keep Multi-Line Rows Readable" on the Tables and Lists page.
+ * A full address wraps across lines, the date breaks mid-value, and middle alignment staggers the row.
+ * @module
+ */
+import { style, Table } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Table.Root size="small" {...styles.table()}>
+      <Table.Head>
+        <Table.Row>
+          <Table.HeaderCell>Route</Table.HeaderCell>
+          <Table.HeaderCell>Updated</Table.HeaderCell>
+        </Table.Row>
+      </Table.Head>
+      <Table.Body>
+        <Table.Row>
+          <Table.Cell {...styles.wrap()}>
+            EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v →
+            0x20c0000000000000000000000000000000000000
+            <Table.Subtitle>Chain 792703809 → 4217</Table.Subtitle>
+          </Table.Cell>
+          <Table.Cell {...styles.narrow()}>Oct 9, 2026, 12:04 AM</Table.Cell>
+        </Table.Row>
+      </Table.Body>
+    </Table.Root>
+  )
+}
+
+namespace styles {
+  export const narrow = style({ width: '5rem !custom' })
+
+  export const table = style({ maxWidth: '18rem !custom', tableLayout: 'fixed !custom' })
+
+  export const wrap = style({ overflowWrap: 'anywhere' })
+}
+```
+
+## Select Rows and Act in Bulk
+
+If an action applies to several records at once, such as pausing payouts or revoking keys, add a leading column of small [Checkbox](../components/checkbox.md) controls. Select rows in the example to show the bulk actions.
+
+```tsx
+import { Amount, Badge, Button, Checkbox, Inset, style, Surface, Table } from '@tempoxyz/ds'
+import { ArrowDown, ArrowUp, Sort } from '@tempoxyz/ds/icons'
+import { useState } from 'react'
+
+export const fill = true
+const payouts = [
+  {
+    amount: '1200.00',
+    date: '2026-10-20',
+    id: 'p1',
+    recipient: 'Ada Lovelace',
+    status: 'Scheduled',
+  },
+  { amount: '48.50', date: '2026-10-18', id: 'p2', recipient: 'Grace Hopper', status: 'Scheduled' },
+  { amount: '310.00', date: '2026-10-21', id: 'p3', recipient: 'Alan Turing', status: 'Paused' },
+  {
+    amount: '9.99',
+    date: '2026-10-19',
+    id: 'p4',
+    recipient: 'Katherine Johnson',
+    status: 'Scheduled',
+  },
+]
+
+type Column = 'amount' | 'date'
+
+export function Demo() {
+  const [selected, setSelected] = useState<readonly string[]>([])
+  const [sort, setSort] = useState<{ column: Column; direction: 'ascending' | 'descending' }>({
+    column: 'date',
+    direction: 'descending',
+  })
+
+  const rows = [...payouts].sort((a, b) => {
+    const order =
+      sort.column === 'amount' ? Number(a.amount) - Number(b.amount) : a.date.localeCompare(b.date)
+    return sort.direction === 'ascending' ? order : -order
+  })
+  const all = selected.length === payouts.length
+  const some = selected.length > 0 && !all
+
+  function toggle(column: Column) {
+    setSort((current) => ({
+      column,
+      direction:
+        current.column === column && current.direction === 'descending'
+          ? 'ascending'
+          : 'descending',
+    }))
+  }
+
+  function header(column: Column, label: string) {
+    const active = sort.column === column
+    const Icon = (() => {
+      if (!active) return Sort
+      return sort.direction === 'ascending' ? ArrowUp : ArrowDown
+    })()
+
+    return (
+      <Table.HeaderCell
+        aria-sort={active ? sort.direction : undefined}
+        justify={column === 'amount' ? 'end' : 'start'}
+      >
+        <button onClick={() => toggle(column)} type="button" {...styles.sort()}>
+          {label}
+          <Icon aria-hidden="true" />
+        </button>
+      </Table.HeaderCell>
+    )
+  }
+
+  return (
+    <Inset
+      aria-label="Scheduled payouts"
+      role="region"
+      space="16"
+      tabIndex={0}
+      {...styles.region()}
+    >
+      <Surface {...styles.surface()}>
+        <Surface.Header>
+          <Surface.Title>Scheduled payouts</Surface.Title>
+          <div {...styles.actions()}>
+            <span role="status" {...styles.count()}>
+              {selected.length > 0 ? `${selected.length} selected` : ''}
+            </span>
+            {selected.length > 0 ? (
+              <>
+                <Button onClick={() => setSelected([])} size="small" variant="tertiary">
+                  Clear
+                </Button>
+                <Button size="small" variant="secondary">
+                  Pause
+                </Button>
+                <Button size="small">Cancel payouts</Button>
+              </>
+            ) : (
+              <Button size="small" variant="secondary">
+                Export CSV
+              </Button>
+            )}
+          </div>
+        </Surface.Header>
+        <Table.Root>
+          <Table.Head>
+            <Table.Row>
+              <Table.HeaderCell {...styles.check()}>
+                <Checkbox
+                  aria-label="Select all payouts"
+                  checked={all}
+                  indeterminate={some}
+                  onCheckedChange={() => setSelected(all ? [] : payouts.map((payout) => payout.id))}
+                  size="small"
+                />
+              </Table.HeaderCell>
+              <Table.HeaderCell>Recipient</Table.HeaderCell>
+              {header('date', 'Date')}
+              <Table.HeaderCell>Status</Table.HeaderCell>
+              {header('amount', 'Amount')}
+            </Table.Row>
+          </Table.Head>
+          <Table.Body>
+            {rows.map((payout) => {
+              const checked = selected.includes(payout.id)
+
+              return (
+                <Table.Row data-selected={checked || undefined} key={payout.id} {...styles.row()}>
+                  <Table.Cell {...styles.check()}>
+                    <Checkbox
+                      aria-label={`Select payout to ${payout.recipient}`}
+                      checked={checked}
+                      onCheckedChange={() =>
+                        setSelected(
+                          checked
+                            ? selected.filter((id) => id !== payout.id)
+                            : [...selected, payout.id],
+                        )
+                      }
+                      size="small"
+                    />
+                  </Table.Cell>
+                  <Table.Cell>{payout.recipient}</Table.Cell>
+                  <Table.Cell>
+                    <time dateTime={payout.date}>
+                      {new Date(`${payout.date}T12:00:00`).toLocaleDateString(undefined, {
+                        day: 'numeric',
+                        month: 'short',
+                      })}
+                    </time>
+                  </Table.Cell>
+                  <Table.Cell>
+                    <Badge size="small">{payout.status}</Badge>
+                  </Table.Cell>
+                  <Table.Cell justify="end" numeric>
+                    <Amount align="right" currency="USD" value={payout.amount} />
+                  </Table.Cell>
+                </Table.Row>
+              )
+            })}
+          </Table.Body>
+        </Table.Root>
+      </Surface>
+    </Inset>
+  )
+}
+
+namespace styles {
+  export const actions = style({ alignItems: 'center', columnGap: '8', display: 'flex' })
+
+  export const check = style({ width: '1px !custom' })
+
+  export const count = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const region = style({ backgroundColor: 'background.primary', overflowX: 'auto' })
+
+  export const row = style({
+    selectors: { '&[data-selected]': { backgroundColor: 'container.regular' } },
+  })
+
+  export const sort = style({
+    alignItems: 'center',
+    appearance: 'none !custom',
+    backgroundColor: 'transparent !custom',
+    border: 'none !custom',
+    borderRadius: '3xs',
+    color: 'inherit !custom',
+    columnGap: '4',
+    cursor: 'pointer',
+    display: 'inline-flex',
+    font: 'inherit !custom',
+    outlineColor: 'transparent !custom',
+    outlineOffset: '2',
+    outlineStyle: 'solid !custom',
+    outlineWidth: '2',
+    padding: '0',
+    transitionDuration: '160',
+    transitionProperty: 'color, outline-color',
+    transitionTimingFunction: 'snappy',
+    selectors: {
+      '&:focus-visible': { outlineColor: 'border.focus' },
+      '&:hover': { color: 'content.primary' },
+    },
+  })
+
+  export const surface = style({ minWidth: '36rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/TablesSelection.tsx)
+
+* **Name Each Checkbox:** Name each checkbox by its row, such as Select payout to Ada Lovelace.
+* **Header Checkbox (indeterminate):** The header checkbox selects every row on the page. It shows this state while only some rows are selected.
+* **Selection Count:** Show the count, such as 2 selected, beside the bulk actions and a Clear action.
+* **Select All Matching:** If more pages exist, state that the header selects this page only. Offer to select all matches.
+
+Confirm a destructive bulk action in an [AlertDialog](../components/alert-dialog.md) that names the count, such as Cancel 2 payouts, as [Destructive Actions](destructive-actions.md) describes.
+
+## Sort Columns
+
+[Table](../components/table.md) has no built-in sorting. Put a `button` inside each sortable `Table.HeaderCell`. Set `aria-sort` to `ascending` or `descending` on the sorted column.
+
+* **Direction:** Show the sort direction with an arrow, and mark other sortable columns with the sort icon.
+* **Default order:** Sort activity newest first. A first click on a numeric column sorts largest first.
+* **Whole data set:** Sort every record, not only the rows on the current page.
+
+## Paginate or Load More
+
+* **Pagination (Pagination):** For lists revisited by position or shared, such as invoices, audit logs, or blocks. Give each page a URL.
+* **Load More:** For feeds read from the top, such as wallet activity. Append the next batch below the current rows.
+* **Infinite Scroll (Avoid):** On the web, it hides the footer and leaves no position to return to.
+
+Show the range beside either control, such as Showing 20 of 248. After Load more, keep focus on the button.
+
+Below 640px, show Previous and Next with a Page 1 of 3 label between them, as in the stacked example. Use `medium` pagination for touch targets.
+
+## Choose a Density
+
+* **Small (32px):** For dense consoles and dashboards with many rows. Pair with small buttons.
+* **Medium (40px):** The default size, for most tables in consoles and settings.
+* **Large (56px):** For touch-first screens and rows with two lines or an [Avatar](../components/avatar.md).
+
+Use one density per table. [ListGroup](../components/list-group.md) keep one 36px height for key-value facts.
+
+## Keep Headers in View
+
+If a long table scrolls, set `sticky` on `Table.Head`. This works inside a container with a fixed height or with the page. Header cells take the surface background, so rows pass beneath them. An ancestor with `overflow: hidden` stops the header from sticking.
+
+## States
+
+Keep the headers and filters in place in every state, so the table does not jump.
+
+```tsx
+import { Amount, Button, ChoiceGroup, Empty, Hex, Skeleton, Stack, style, Table } from '@tempoxyz/ds'
+import { History } from '@tempoxyz/ds/icons'
+import { useState } from 'react'
+
+export const fill = true
+const activity = [
+  ['0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060', 'Sent', '-1200.00'],
+  ['0x91bd07e1c3e05a2277a1c0d94f2a91c3b6a900fa2b585dd299e03d12fa4293bc', 'Received', '4005.00'],
+  ['0xc3e05a2291bd07e14f2a91c3b6a900fa2b585dd299e03d12fa4293bc77a1c0d9', 'Sent', '-48.50'],
+  ['0x77a1c0d94f2a91c3b6a900fa2b585dd299e03d12fa4293bcc3e05a2291bd07e1', 'Received', '250.00'],
+  ['0x2b585dd299e03d12fa4293bc77a1c0d94f2a91c3b6a900fac3e05a2291bd07e1', 'Sent', '-9.99'],
+  ['0xd299e03d12fa4293bc77a1c0d94f2a91c3b6a900fa2b585dc3e05a2291bd07e1', 'Received', '1250.50'],
+  ['0x4f2a91c3b6a900fa2b585dd299e03d12fa4293bc77a1c0d9c3e05a2291bd07e1', 'Sent', '-310.00'],
+  ['0xb6a900fa2b585dd299e03d12fa4293bc77a1c0d94f2a91c3c3e05a2291bd07e1', 'Received', '75.25'],
+] as const
+
+type State = 'empty' | 'loaded' | 'loading'
+
+export function Demo() {
+  const [state, setState] = useState<State>('loaded')
+
+  return (
+    <Stack gap="16">
+      <ChoiceGroup.Root
+        aria-label="Table state"
+        onValueChange={(value) => setState(value as State)}
+        size="small"
+        value={state}
+      >
+        <ChoiceGroup.Item value="loaded">Loaded</ChoiceGroup.Item>
+        <ChoiceGroup.Item value="loading">Loading</ChoiceGroup.Item>
+        <ChoiceGroup.Item value="empty">Empty</ChoiceGroup.Item>
+      </ChoiceGroup.Root>
+      <div aria-labelledby="activity-title" role="region" tabIndex={0} {...styles.scroll()}>
+        <Table.Root aria-busy={state === 'loading' || undefined} size="small">
+          <Table.Caption id="activity-title">Recent activity</Table.Caption>
+          <Table.Head sticky>
+            <Table.Row>
+              <Table.HeaderCell>Transaction</Table.HeaderCell>
+              <Table.HeaderCell>Type</Table.HeaderCell>
+              <Table.HeaderCell justify="end">Amount</Table.HeaderCell>
+            </Table.Row>
+          </Table.Head>
+          <Table.Body>
+            {state === 'loaded' &&
+              activity.map(([hash, type, amount]) => (
+                <Table.Row key={hash}>
+                  <Table.Cell>
+                    <div {...styles.hash()}>
+                      <Hex value={hash} />
+                    </div>
+                  </Table.Cell>
+                  <Table.Cell>{type}</Table.Cell>
+                  <Table.Cell numeric>
+                    <Amount
+                      align="right"
+                      sign={amount.startsWith('-') ? '−' : '+'}
+                      symbol="USDC"
+                      value={amount.replace('-', '')}
+                    />
+                  </Table.Cell>
+                </Table.Row>
+              ))}
+            {state === 'loading' &&
+              ['60%', '45%', '70%', '50%'].map((width) => (
+                <Table.Row key={width}>
+                  <Table.Cell>
+                    <Skeleton shape="pill" style={{ height: 12, width }} />
+                  </Table.Cell>
+                  <Table.Cell>
+                    <Skeleton shape="pill" style={{ height: 12, width: '4rem' }} />
+                  </Table.Cell>
+                  <Table.Cell>
+                    <Skeleton
+                      shape="pill"
+                      style={{ height: 12, marginInlineStart: 'auto', width: '5rem' }}
+                    />
+                  </Table.Cell>
+                </Table.Row>
+              ))}
+            {state === 'empty' && (
+              <Table.Row>
+                <Table.Cell colSpan={3}>
+                  <Empty.Root>
+                    <Empty.Icon>
+                      <History />
+                    </Empty.Icon>
+                    <Empty.Title>No activity yet</Empty.Title>
+                    <Empty.Description>Payments you send or receive appear here.</Empty.Description>
+                    <Empty.Actions>
+                      <Button size="small">Add funds</Button>
+                    </Empty.Actions>
+                  </Empty.Root>
+                </Table.Cell>
+              </Table.Row>
+            )}
+          </Table.Body>
+        </Table.Root>
+      </div>
+      {state === 'loaded' && (
+        <div {...styles.footer()}>
+          <span {...styles.count()}>Showing 8 of 24</span>
+          <Button size="small" variant="secondary">
+            Load more
+          </Button>
+        </div>
+      )}
+    </Stack>
+  )
+}
+
+namespace styles {
+  export const count = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const footer = style({
+    alignItems: 'center',
+    display: 'flex',
+    flexWrap: 'wrap',
+    gap: '12',
+    justifyContent: 'space-between',
+  })
+
+  export const hash = style({ maxWidth: '12rem !custom' })
+
+  export const scroll = style({
+    backgroundColor: 'background.elevated',
+    borderColor: 'line.secondary',
+    borderRadius: 'sm',
+    borderStyle: 'solid',
+    borderWidth: 'regular',
+    maxHeight: '18rem !custom',
+    overflowY: 'auto',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/TablesStates.tsx)
+
+* **Loading (aria-busy):** Keep the headers and show three to five placeholder rows. Mark the table busy.
+* **Empty (Empty):** If no records exist yet, offer the action that creates the first one. [Empty States](empty-states.md) covers the variants.
+* **Error (negative):** Show a negative [Alert](../components/alert.md) above the table with Retry. Keep rows that already loaded.
+* **Updating:** Keep the current rows while a sort or filter loads. Replace them when the new rows arrive.
+
+**Do:** Explain an empty result in a row that spans every column, with a way out.
+
+```tsx
+/**
+ * Do example for "Tables and Lists" on the Tables and Lists page.
+ * Explain an empty result in a row that spans every column, with a way out.
+ * @module
+ */
+import { Button, style, Table } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Table.Root size="small" {...styles.table()}>
+      <Table.Head>
+        <Table.Row>
+          <Table.HeaderCell>Key</Table.HeaderCell>
+          <Table.HeaderCell>Last used</Table.HeaderCell>
+        </Table.Row>
+      </Table.Head>
+      <Table.Body>
+        <Table.Row>
+          <Table.Cell colSpan={2}>
+            <div {...styles.empty()}>
+              <span {...styles.text()}>No keys match Staging.</span>
+              <Button size="small" variant="secondary">
+                Clear filter
+              </Button>
+            </div>
+          </Table.Cell>
+        </Table.Row>
+      </Table.Body>
+    </Table.Root>
+  )
+}
+
+namespace styles {
+  export const empty = style({
+    alignItems: 'center',
+    display: 'flex',
+    flexDirection: 'column',
+    paddingBlock: '16',
+    rowGap: '12',
+  })
+
+  export const table = style({ maxWidth: '17rem !custom' })
+
+  export const text = style({ color: 'content.secondary', typography: 'body.b2' })
+}
+```
+
+**Don't:** Leave headers above an empty body.
+
+```tsx
+/**
+ * Don't example for "Tables and Lists" on the Tables and Lists page.
+ * Don't leave headers above an empty body.
+ * @module
+ */
+import { style, Table } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Table.Root size="small" {...styles.table()}>
+      <Table.Head>
+        <Table.Row>
+          <Table.HeaderCell>Key</Table.HeaderCell>
+          <Table.HeaderCell>Last used</Table.HeaderCell>
+        </Table.Row>
+      </Table.Head>
+      <Table.Body />
+    </Table.Root>
+  )
+}
+
+namespace styles {
+  export const table = style({ maxWidth: '17rem !custom' })
+}
+```
+
+## Below 640px
+
+Tables with more than two or three columns do not fit a phone. Turn each row into a stacked list item: the main text and amount on the first line, the date and status beneath. Below 640px, the preview switches layouts.
+
+```tsx
+import { Amount, Badge, ListGroup, Pagination, Stack, style, Surface, Table } from '@tempoxyz/ds'
+
+export const fill = true
+const payments = [
+  { amount: '1200.00', date: 'Oct 20', recipient: 'Ada Lovelace', status: 'Confirmed' },
+  { amount: '48.50', date: 'Oct 19', recipient: 'Grace Hopper', status: 'Confirmed' },
+  { amount: '310.00', date: 'Oct 18', recipient: 'Alan Turing', status: 'Pending' },
+  { amount: '9.99', date: 'Oct 18', recipient: 'Katherine Johnson', status: 'Failed' },
+] as const
+
+const intents = { Confirmed: 'positive', Failed: 'negative', Pending: 'warning' } as const
+
+export function Demo() {
+  return (
+    <Stack gap="16" {...styles.demo()}>
+      <h2 id="payments-title" {...styles.title()}>
+        Payments
+      </h2>
+      {/* Both layouts render, and `display: none` keeps only the visible one in the accessibility tree. */}
+      <div {...styles.wide()}>
+        <Surface>
+          <Table.Root aria-labelledby="payments-title">
+            <Table.Head>
+              <Table.Row>
+                <Table.HeaderCell>Recipient</Table.HeaderCell>
+                <Table.HeaderCell>Date</Table.HeaderCell>
+                <Table.HeaderCell>Status</Table.HeaderCell>
+                <Table.HeaderCell justify="end">Amount</Table.HeaderCell>
+              </Table.Row>
+            </Table.Head>
+            <Table.Body>
+              {payments.map((payment) => (
+                <Table.Row key={payment.recipient}>
+                  <Table.Cell>{payment.recipient}</Table.Cell>
+                  <Table.Cell>{payment.date}</Table.Cell>
+                  <Table.Cell status={intents[payment.status]}>{payment.status}</Table.Cell>
+                  <Table.Cell numeric>
+                    <Amount align="right" currency="USD" value={payment.amount} />
+                  </Table.Cell>
+                </Table.Row>
+              ))}
+            </Table.Body>
+          </Table.Root>
+        </Surface>
+      </div>
+      <div {...styles.narrow()}>
+        <Surface size="small">
+          <ListGroup.Root aria-labelledby="payments-title" role="list">
+            {payments.map((payment) => (
+              <ListGroup.Row key={payment.recipient} role="listitem">
+                <ListGroup.Info>
+                  <ListGroup.Title>{payment.recipient}</ListGroup.Title>
+                  <ListGroup.Description>{payment.date}</ListGroup.Description>
+                </ListGroup.Info>
+                <span {...styles.end()}>
+                  <Amount currency="USD" value={payment.amount} />
+                  <Badge size="small">{payment.status}</Badge>
+                </span>
+              </ListGroup.Row>
+            ))}
+          </ListGroup.Root>
+        </Surface>
+      </div>
+      <div {...styles.footer()}>
+        <span {...styles.count()}>1–4 of 12</span>
+        <div {...styles.wide()}>
+          <Pagination>
+            <Pagination.Previous disabled />
+            <Pagination.Page current href="#">
+              1
+            </Pagination.Page>
+            <Pagination.Page href="#">2</Pagination.Page>
+            <Pagination.Page href="#">3</Pagination.Page>
+            <Pagination.Next href="#" />
+          </Pagination>
+        </div>
+        <div {...styles.narrow()}>
+          <Pagination>
+            <Pagination.Previous disabled />
+            <Pagination.Ellipsis>Page 1 of 3</Pagination.Ellipsis>
+            <Pagination.Next href="#" />
+          </Pagination>
+        </div>
+      </div>
+    </Stack>
+  )
+}
+
+namespace styles {
+  export const count = style({
+    color: 'content.secondary',
+    display: 'none',
+    typography: 'body.b3',
+    '@media 640': { display: 'inline' },
+  })
+
+  export const demo = style({ backgroundColor: 'background.primary', padding: '16' })
+
+  export const end = style({
+    alignItems: 'flex-end',
+    display: 'flex',
+    flexDirection: 'column',
+    flexShrink: '0 !custom',
+    rowGap: '4',
+  })
+
+  export const footer = style({
+    alignItems: 'center',
+    display: 'flex',
+    flexWrap: 'wrap',
+    gap: '12',
+    justifyContent: 'space-between',
+  })
+
+  export const narrow = style({ '@media 640': { display: 'none' } })
+
+  export const title = style({ margin: '0', typography: 'heading.h3' })
+
+  export const wide = style({ display: 'none', '@media 640': { display: 'block' } })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/TablesResponsive.tsx)
+
+* **Switch Layouts (sm):** Render a table from this breakpoint and a list below it. Only the visible layout stays in the accessibility tree.
+* **Same Records and Actions:** Keep records, order, and actions the same in both layouts. Put columns that do not fit in the detail view.
+* **Scroll to Compare (tabIndex=0):** Keep a table only to compare values across columns, and [scroll it inside its own region](responsive-layout.md#scroll-wide-content-inside-its-own-region).
+
+## Content
+
+* **Headers:** Put the unit of a metric in its header, such as p99 (ms). Keep the token on each amount, because one table can mix assets.
+* **Missing values:** Show a missing value as a word, such as None or Never, instead of an empty cell.
+* **Dates:** Format dates the same way in every row, as [Blockchain Values](blockchain-values.md#timestamps) describes, and keep each date on one line.
+
+## Accessibility
+
+* **Native Table (scope=col):** A native table with column headers. Pass `scope="row"` for a row header. Do not use it for layout.
+* **Clickable Rows (interactive):** Adds hover and focus styles only. Put a link or button in each clickable row.
+* **Live Counts (status):** Announce the selection count and loaded batches through an always-rendered status region.
+* **Status Text (status):** Colors text only. The text must state the status, such as Failed.
+
+## Related
+
+[Table](../components/table.md)
+
+Use for tabular data.
+
+[ListGroup](../components/list-group.md)
+
+Use for details, settings, and stacked items.
+
+[Pagination](../components/pagination.md)
+
+Use for paged lists.
+
+[Checkbox](../components/checkbox.md)
+
+Use for row selection.
+
+[Responsive Layout](responsive-layout.md)
+
+Covers the shared breakpoints.
+
+[Loading](loading.md)
+
+Covers skeletons and spinners.
+
+[Empty States](empty-states.md)
+
+Covers first use and no results.
+
+[Destructive Actions](destructive-actions.md)
+
+Covers confirming bulk actions.