@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/patterns/dashboards.md

@@ -0,0 +1,638 @@
+# Dashboards
+
+Summarizes system metrics, such as throughput, in tiles, filters, and charts.
+
+## Overview
+
+A dashboard addresses one question, such as how the latest benchmark run performed. [Tempo Performance](/docs/products/tempo-performance) uses the pattern: a run header, filters for the run and scenario, a row of metric tiles, and sections of charts.
+
+> [!NOTE]
+> The library has no chart component. The examples are reference layouts with placeholder bars drawn with `style`. Render the plot with your charting library.
+
+## Recommended Structure
+
+Build the page in this order, from top to bottom.
+
+* **Header (1):** The page title, the run's date, commit, and duration, and a [Badge](/docs/components/badge) for its type, such as Nightly.
+* **Filters (2):** One row of labelled controls that apply on change.
+* **Metric Tiles (3):** Four to eight headline numbers in [Surface](/docs/components/surface) tiles, most important first.
+* **Chart Sections (4):** One [Surface](/docs/components/surface) per chart, under section headings such as Throughput.
+* **Detail Tables (5):** A [Table](/docs/components/table) of exact values, such as p50, p95, and p99 timings.
+
+```tsx
+import { Badge, Button, ChoiceGroup, Field, Grid, Popover, Select, Skeleton, Stack, style, Surface } from '@tempoxyz/ds'
+import { InfoCircle } from '@tempoxyz/ds/icons'
+import { useState } from 'react'
+
+export const fill = true
+const runs = {
+  'main-2026-10-17-8c1d04ef': 'main-2026-10-17-8c1d04ef',
+  'main-2026-10-18-a41f9e20': 'main-2026-10-18-a41f9e20',
+  'main-2026-10-19-296be2ab': 'main-2026-10-19-296be2ab',
+}
+
+const scenarios = { mix: 'Public mix, multi-region', transfers: 'Transfers, single region' }
+
+const metrics = [
+  ['Settled TPS', '14,960', 'TPS', 'Median settled throughput across 142 measured blocks.'],
+  ['Block time', '633', 'ms', 'Median time between consecutive blocks.'],
+  ['Blocks', '142', undefined, 'Blocks produced during the measured window.'],
+  ['Avg gas/s', '1.38', 'Ggas', 'Mean gas processed per second.'],
+  ['Peak gas/s', '2.00', 'Ggas', 'Highest gas processed in any one second.'],
+  ['Accounts', '1,000', undefined, 'Accounts sending transactions during the run.'],
+] as const
+
+const throughput = [14.2, 14.8, 15.1, 14.6, 15.4, 14.9, 15.0, 14.4, 15.2, 14.7, 15.3, 14.9]
+
+function Metric(props: { info: string; label: string; unit?: string | undefined; value: string }) {
+  return (
+    <Surface size="small">
+      <dt {...styles.label()}>
+        {props.label}
+        <Popover.Root>
+          <Popover.Trigger
+            aria-label={`About ${props.label}`}
+            openOnHover
+            render={<Button shape="icon" size="small" variant="tertiary" />}
+          >
+            <InfoCircle />
+          </Popover.Trigger>
+          <Popover.Popup>
+            <Popover.Title>{props.label}</Popover.Title>
+            <Popover.Description>{props.info}</Popover.Description>
+          </Popover.Popup>
+        </Popover.Root>
+      </dt>
+      <dd {...styles.value()}>
+        {props.value}
+        {props.unit && <span {...styles.unit()}> {props.unit}</span>}
+      </dd>
+    </Surface>
+  )
+}
+
+export function Demo() {
+  const [quantile, setQuantile] = useState('p50')
+
+  return (
+    <Stack gap="24" {...styles.page()}>
+      <header {...styles.header()}>
+        <Badge size="small">Nightly</Badge>
+        <h1 {...styles.title()}>Benchmark run</h1>
+        <p {...styles.meta()}>
+          Oct 20, 2026, 3:01 AM · Commit <code {...styles.mono()}>296be2a</code> · 2m 35s
+        </p>
+      </header>
+      <div {...styles.filters()}>
+        <Field.Root {...styles.filter()}>
+          <Field.Label>Run</Field.Label>
+          <Select.Root defaultValue="main-2026-10-19-296be2ab" items={runs}>
+            <Select.Trigger>
+              <Select.Value {...styles.mono()} />
+              <Select.Icon />
+            </Select.Trigger>
+            <Select.Popup size="small">
+              {Object.entries(runs).map(([value, label]) => (
+                <Select.Item key={value} value={value}>
+                  <Select.ItemText {...styles.mono()}>{label}</Select.ItemText>
+                </Select.Item>
+              ))}
+            </Select.Popup>
+          </Select.Root>
+        </Field.Root>
+        <Field.Root {...styles.filter()}>
+          <Field.Label>Scenario</Field.Label>
+          <Select.Root defaultValue="mix" items={scenarios}>
+            <Select.Trigger>
+              <Select.Value />
+              <Select.Icon />
+            </Select.Trigger>
+            <Select.Popup size="small">
+              {Object.entries(scenarios).map(([value, label]) => (
+                <Select.Item key={value} value={value}>
+                  <Select.ItemText>{label}</Select.ItemText>
+                </Select.Item>
+              ))}
+            </Select.Popup>
+          </Select.Root>
+        </Field.Root>
+        <div {...styles.quantile()}>
+          <span id="quantile-label" {...styles.legend()}>
+            Timing quantile
+          </span>
+          <ChoiceGroup.Root
+            aria-labelledby="quantile-label"
+            onValueChange={(value) => setQuantile(String(value))}
+            size="small"
+            value={quantile}
+          >
+            <ChoiceGroup.Item value="p50">p50</ChoiceGroup.Item>
+            <ChoiceGroup.Item value="p95">p95</ChoiceGroup.Item>
+            <ChoiceGroup.Item value="p99">p99</ChoiceGroup.Item>
+          </ChoiceGroup.Root>
+        </div>
+      </div>
+      <dl {...styles.tiles()}>
+        {metrics.map(([label, value, unit, info]) => (
+          <Metric info={info} key={label} label={label} unit={unit} value={value} />
+        ))}
+      </dl>
+      <Grid fit="large" gap="16">
+        <Surface render={<section aria-labelledby="tps-title" />} size="medium">
+          <Surface.Header>
+            <Surface.Title id="tps-title">Settled TPS</Surface.Title>
+          </Surface.Header>
+          <div
+            aria-label="Settled TPS per block, between 14,200 and 15,400"
+            role="img"
+            {...styles.plot()}
+          >
+            {throughput.map((value, index) => (
+              <span key={index} {...styles.bar({ style: { height: `${(value - 13) * 40}%` } })} />
+            ))}
+          </div>
+          <p {...styles.caption()}>Thousands of transactions per second, per block</p>
+        </Surface>
+        <Surface render={<section aria-labelledby="validation-title" />} size="medium">
+          <Surface.Header>
+            <Surface.Title id="validation-title">Block validation ({quantile})</Surface.Title>
+          </Surface.Header>
+          <Skeleton {...styles.plot()} />
+          <p role="status" {...styles.caption()}>
+            Loading chart data
+          </p>
+        </Surface>
+      </Grid>
+    </Stack>
+  )
+}
+
+namespace styles {
+  export const bar = style({
+    backgroundColor: 'accent.blue.background',
+    borderTopLeftRadius: '3xs',
+    borderTopRightRadius: '3xs',
+    flex: '1 !custom',
+  })
+
+  export const caption = style({ color: 'content.secondary', margin: '0', typography: 'body.b3' })
+
+  export const filter = style({ flex: '1 1 12rem !custom', minWidth: '0' })
+
+  export const filters = style({
+    alignItems: 'flex-end',
+    display: 'flex',
+    flexWrap: 'wrap',
+    gap: '12',
+  })
+
+  export const header = style({
+    alignItems: 'flex-start',
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '8',
+  })
+
+  export const label = style({
+    alignItems: 'center',
+    color: 'content.secondary',
+    columnGap: '4',
+    display: 'flex',
+    marginBlockEnd: '8',
+    typography: 'body.b3',
+    // A 24px info button keeps the label line at its text height.
+    selectors: { '& button': { height: '24', marginBlock: '-4px !custom' } },
+  })
+
+  export const legend = style({ color: 'content.primary', typography: 'body.b3Strong' })
+
+  export const meta = style({ color: 'content.secondary', margin: '0', typography: 'body.b3' })
+
+  export const mono = style({ typography: 'mono.m1' })
+
+  export const page = style({
+    backgroundColor: 'background.primary',
+    padding: '16',
+    '@media 640': { padding: '32' },
+  })
+
+  export const plot = style({
+    alignItems: 'flex-end',
+    display: 'flex',
+    gap: '4',
+    height: '160',
+    marginBlockEnd: '12',
+  })
+
+  export const quantile = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })
+
+  export const tiles = style({
+    display: 'grid',
+    gap: '12',
+    gridTemplateColumns: 'repeat(2, minmax(0, 1fr)) !custom',
+    margin: '0',
+    '@media 768': { gridTemplateColumns: 'repeat(3, minmax(0, 1fr)) !custom' },
+    '@media 1280': { gridTemplateColumns: 'repeat(6, minmax(0, 1fr)) !custom' },
+  })
+
+  export const title = style({ margin: '0', typography: 'heading.h2' })
+
+  export const unit = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const value = style({
+    fontVariantNumeric: 'tabular-nums !custom',
+    margin: '0',
+    typography: 'heading.h2',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/DashboardsOverview.tsx)
+
+## Metric Tiles
+
+Each tile holds a label, a value, a unit in a separate smaller span after the value, and an optional info button. Mark up the tiles as a `dl`, with each label in a `dt` and the value and unit together in a `dd`.
+
+**Do:** Label every tile and set the unit beside the value.
+
+```tsx
+/**
+ * Do example for "Dashboards" on the Dashboards page.
+ * Label every tile and set the unit beside the value.
+ * @module
+ */
+import { style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="small" {...styles.tile()}>
+      <p {...styles.label()}>Block time</p>
+      <p {...styles.value()}>
+        633<span {...styles.unit()}> ms</span>
+      </p>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.secondary', margin: '0', typography: 'body.b3' })
+
+  export const tile = style({
+    boxShadow: '0 0 0 1px light-dark(#0000001a, #ffffff1f) !custom',
+    width: '10rem !custom',
+  })
+
+  export const unit = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const value = style({
+    fontVariantNumeric: 'tabular-nums !custom',
+    margin: '0',
+    paddingBlockStart: '8',
+    typography: 'heading.h2',
+  })
+}
+```
+
+**Don't:** Show a bare number without its label or unit.
+
+```tsx
+/**
+ * Don't example for "Dashboards" on the Dashboards page.
+ * Don't show a bare number without its label or unit.
+ * @module
+ */
+import { style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="small" {...styles.tile()}>
+      <p {...styles.value()}>633</p>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const tile = style({
+    boxShadow: '0 0 0 1px light-dark(#0000001a, #ffffff1f) !custom',
+    width: '10rem !custom',
+  })
+
+  export const value = style({ margin: '0', typography: 'heading.h1' })
+}
+```
+
+### Put Definitions in a Popover
+
+A [Tooltip](/docs/components/tooltip) stays closed on touch input, and screen readers do not announce it. Put the definition in a [Popover](/docs/components/popover), and set `openOnHover` on `Popover.Trigger`. Write it in one or two sentences, such as Median settled throughput across 142 measured blocks.
+
+### Show Change With Text
+
+If a tile compares against a baseline, state the direction and the baseline in text, such as +4.2% vs previous run. Color can reinforce the change but never carries it alone.
+
+## Filters
+
+* **Short or Medium List (Select):** One choice from a short or medium list, such as the scenario.
+* **Long List (Combobox):** One choice from a long, searchable list, such as 60 run IDs.
+* **Few Short Options (ChoiceGroup):** Two to four short options that readers compare often, such as p50, p95, and p99.
+
+**Do:** If a few short options fit, use a [ChoiceGroup](/docs/components/choice-group).
+
+```tsx
+/**
+ * Do example for "Show Change With Text" on the Dashboards page.
+ * If a few short options fit, use a ChoiceGroup.
+ * @module
+ */
+import { ChoiceGroup } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ChoiceGroup.Root aria-label="Timing quantile" defaultValue="p95" size="small">
+      <ChoiceGroup.Item value="p50">p50</ChoiceGroup.Item>
+      <ChoiceGroup.Item value="p95">p95</ChoiceGroup.Item>
+      <ChoiceGroup.Item value="p99">p99</ChoiceGroup.Item>
+    </ChoiceGroup.Root>
+  )
+}
+```
+
+**Don't:** Hide three short options behind a [Select](/docs/components/select).
+
+```tsx
+/**
+ * Don't example for "Show Change With Text" on the Dashboards page.
+ * Don't hide three short options behind a Select.
+ * @module
+ */
+import { Select, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.frame()}>
+      <Select.Root defaultValue="p95" items={{ p50: 'p50', p95: 'p95', p99: 'p99' }}>
+        <Select.Trigger aria-label="Timing quantile">
+          <Select.Value />
+          <Select.Icon />
+        </Select.Trigger>
+      </Select.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const frame = style({ width: '8rem !custom' })
+}
+```
+
+* **Visible labels:** Label every filter. Name a [ChoiceGroup](/docs/components/choice-group) with `aria-labelledby`.
+* **Apply on change:** Do not add an Apply button for single-choice controls.
+* **State in the URL:** Keep filter state in the URL, so a shared link opens the same view.
+* **Scope in titles:** Name the active scope in chart titles, such as Block validation (p95).
+* **One control size:** In dense dashboards, use `small` for every control in the row.
+
+## Values and Identifiers
+
+* **Tabular figures:** Set metric values in tabular figures, so digits keep their width on update. [Amount](/docs/components/amount) and `numeric` table cells apply them already.
+* **Monospace identifiers:** Set commits and run IDs in monospace. [Hex](/docs/components/hex) and `mono` table cells apply it already.
+* **One precision:** Round to the precision readers act on, such as 1.38, not 1.3812. Keep it the same across tiles, charts, and runs.
+* **Larger units:** Switch to a larger unit before values pass four digits, such as 1.38 Ggas.
+
+## Chart Containers
+
+Frame every chart the same way, whatever library renders it.
+
+* **Labelled Section (section):** Render each medium [Surface](/docs/components/surface) as a section, labelled by its title.
+* **Fixed Height (12rem):** Keep the plot area at one height in every state and at every width.
+* **Caption (Units and scope):** Place it below the plot, such as Milliseconds per block, p50.
+* **Legend and Contrast (3:1):** Label series in a legend, and give each color 3:1 contrast. Teal falls short on light surfaces.
+* **Text Alternative (role=img):** Summarize the plot in `aria-label`, such as its range. If readers need the values, add a [Table](/docs/components/table).
+
+```tsx
+import { Alert, ChoiceGroup, Empty, Skeleton, Stack, style, Surface } from '@tempoxyz/ds'
+import { ChartBar } from '@tempoxyz/ds/icons'
+import { useState } from 'react'
+
+export const fill = true
+const latency = [42, 38, 45, 51, 40, 37, 44, 48, 39, 41, 46, 43, 38, 40]
+
+type State = 'empty' | 'error' | 'loaded' | 'loading'
+
+export function Demo() {
+  const [state, setState] = useState<State>('loaded')
+
+  return (
+    <Stack gap="16">
+      <ChoiceGroup.Root
+        aria-label="Chart 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.Item value="error">Error</ChoiceGroup.Item>
+      </ChoiceGroup.Root>
+      <Surface render={<section aria-labelledby="latency-title" />} size="medium">
+        <Surface.Header>
+          <Surface.Title id="latency-title">New payload validation latency</Surface.Title>
+        </Surface.Header>
+        {/* The plot area keeps one height in every state, so the grid around it never shifts. */}
+        <div {...styles.area()}>
+          {state === 'loaded' && (
+            <div
+              aria-label="Validation latency per block, p50, between 37 and 51 ms"
+              role="img"
+              {...styles.plot()}
+            >
+              {latency.map((value, index) => (
+                <span key={index} {...styles.bar({ style: { height: `${value * 1.6}%` } })} />
+              ))}
+            </div>
+          )}
+          {state === 'loading' && <Skeleton {...styles.fill()} />}
+          {state === 'empty' && (
+            <Empty.Root>
+              <Empty.Icon>
+                <ChartBar />
+              </Empty.Icon>
+              <Empty.Title>No blocks in this range</Empty.Title>
+              <Empty.Description>Pick a longer range or another run.</Empty.Description>
+            </Empty.Root>
+          )}
+          {state === 'error' && (
+            <Alert intent="negative">
+              <Alert.Icon />
+              <Alert.Content>
+                Validator telemetry didn't load.
+                <Alert.Action>Retry</Alert.Action>
+              </Alert.Content>
+            </Alert>
+          )}
+        </div>
+        <p role="status" {...styles.caption()}>
+          {state === 'loading' ? 'Loading chart data' : 'Milliseconds per block, p50'}
+        </p>
+      </Surface>
+    </Stack>
+  )
+}
+
+namespace styles {
+  export const area = style({
+    alignItems: 'center',
+    display: 'flex',
+    height: '200',
+    justifyContent: 'center',
+    marginBlockEnd: '12',
+  })
+
+  export const bar = style({
+    backgroundColor: 'accent.blue.background',
+    borderTopLeftRadius: '3xs',
+    borderTopRightRadius: '3xs',
+    flex: '1 !custom',
+  })
+
+  export const caption = style({ color: 'content.secondary', margin: '0', typography: 'body.b3' })
+
+  export const fill = style({ alignSelf: 'stretch', flex: '1 !custom' })
+
+  export const plot = style({
+    alignItems: 'flex-end',
+    alignSelf: 'stretch',
+    display: 'flex',
+    flex: '1 !custom',
+    gap: '4',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/DashboardsChartStates.tsx)
+
+## Grid Reflow
+
+Lay out tiles in a [Grid](/docs/components/grid) with `fit="small"` and charts with `fit="large"`, which keeps each chart at least 20rem wide. Neither needs a media query. On narrow screens, stack charts instead of shrinking them. [Responsive Layout](/docs/patterns/responsive-layout#app-shell-with-content) covers the full-width shell.
+
+## States
+
+* **Empty (Empty):** Inside the plot area, state why and what to try next, such as No blocks in this range.
+* **Error (negative):** Place an [Alert](/docs/components/alert) with a Retry action inside the failed chart. Other charts keep working.
+* **Partial Data:** Name what is missing, such as Loading validator telemetry, instead of hiding the section.
+* **Updating:** Show when data last changed, such as Updated 30 s ago. Update values in place without layout shift.
+
+**Do:** Show titles at once, and hold the plot height with a [Skeleton](/docs/components/skeleton) while
+data loads.
+
+```tsx
+/**
+ * Do example for "Show Change With Text" on the Dashboards page.
+ * Show titles at once, and hold the plot height with a Skeleton while data loads.
+ * @module
+ */
+import { Skeleton, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="medium" {...styles.card()}>
+      <Surface.Header>
+        <Surface.Title>Gas throughput</Surface.Title>
+      </Surface.Header>
+      <Skeleton {...styles.plot()} />
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    boxShadow: '0 0 0 1px light-dark(#0000001a, #ffffff1f) !custom',
+    width: '16rem !custom',
+  })
+
+  export const plot = style({ height: '120' })
+}
+```
+
+**Don't:** Collapse the chart to a [Spinner](/docs/components/spinner), which shifts every section
+below it.
+
+```tsx
+/**
+ * Don't example for "Show Change With Text" on the Dashboards page.
+ * Don't collapse the chart to a Spinner, which shifts every section below it.
+ * @module
+ */
+import { Spinner, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="medium" {...styles.card()}>
+      <Surface.Header>
+        <Surface.Title>Gas throughput</Surface.Title>
+        <Spinner aria-label="Loading gas throughput" />
+      </Surface.Header>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    boxShadow: '0 0 0 1px light-dark(#0000001a, #ffffff1f) !custom',
+    width: '16rem !custom',
+  })
+}
+```
+
+## Accessibility
+
+* **Description Lists (dl):** Screen readers pair each value with its label, and read the unit with the value.
+* **Info Buttons (About Block time):** Name each by its metric. Give it more room on touch screens.
+* **Announce Once (status):** Announce loading and errors once, through a status region or a [Alert](/docs/components/alert). Do not announce every live update.
+
+## Related
+
+[Surface](/docs/components/surface)
+
+Use for tiles and chart containers.
+
+[Grid](/docs/components/grid)
+
+Use for reflowing tiles and charts.
+
+[ChoiceGroup](/docs/components/choice-group)
+
+Use for a few short filter options.
+
+[Select](/docs/components/select)
+
+Use for filters with a medium list.
+
+[Combobox](/docs/components/combobox)
+
+Use for filters with a long list.
+
+[Popover](/docs/components/popover)
+
+Use for metric definitions.
+
+[Skeleton](/docs/components/skeleton)
+
+Use for loading plots.
+
+[Responsive Layout](/docs/patterns/responsive-layout)
+
+Covers the shared breakpoints.
+
+[Tables and Lists](/docs/patterns/tables-and-lists)
+
+Covers exact values.
+
+[Tempo Performance](/docs/products/tempo-performance)
+
+Covers the benchmark dashboard.