@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/products/tempo-performance.md

@@ -0,0 +1,437 @@
+# Tempo Performance
+
+Tempo Performance is the public benchmark dashboard for the Tempo network.
+
+> [!NOTE]
+> The reference layout on this page is a composition of library components and `style`, not a shipped component. `@tempoxyz/ds` exports no `MetricTile` or `BenchmarkDashboard`. Copy the layout into your app and adapt it. The library has no chart component, so the layout marks where a chart goes.
+
+## Overview
+
+Tempo Performance runs at [perf.tempo.xyz](https://perf.tempo.xyz). It shows one benchmark run at a time:
+
+* **Headline:** Settled TPS, block time, and gas throughput.
+* **Charts:** Block validation, payload building, the transaction pool, persistence, and server resources.
+
+A Methodology page describes the benchmark host, the workload, and the derivation of each metric.
+
+Roles:
+
+* **Protocol and Node Engineers:** Compare nightly runs to catch regressions.
+* **Anyone Evaluating Tempo:** Read the public results.
+
+## Surfaces
+
+Tempo Performance is a responsive web app built with `@tempoxyz/ds`. No native app is documented.
+
+On a phone, the run selects stack at full width, the settled TPS tile spans the column, and the other metric tiles form two columns.
+
+## Key Screens
+
+### Dashboard
+
+```tsx
+import { Button, ChoiceGroup, Field, Grid, Popover, Select, style, Surface, Table } from '@tempoxyz/ds'
+import { InfoCircle } from '@tempoxyz/ds/icons'
+import { useState } from 'react'
+
+export const fill = true
+const nightlies = [
+  'main-2026-10-19-296be2ab',
+  'main-2026-10-17-2c25f7cd',
+  'main-2026-10-16-dee08cf9',
+]
+
+const scenarios = { 'public-mix': 'Public mix · multi-region' }
+
+const metrics = [
+  {
+    definition: 'Number of blocks produced during the benchmark run.',
+    label: 'Blocks',
+    value: '142',
+  },
+  {
+    definition: 'Average wall-clock time between consecutive blocks.',
+    label: 'Block time',
+    value: '633 ms',
+  },
+  {
+    definition:
+      'Average gas per second across the entire run: total gas used ÷ total run duration.',
+    label: 'Avg gas/s',
+    value: '1.38 Ggas/s',
+  },
+  {
+    definition:
+      'Highest gas per second achieved by any single block, from its gas usage and block time.',
+    label: 'Peak gas/s',
+    value: '2.00 Ggas/s',
+  },
+  {
+    definition:
+      'Total configured account set for this run, including txgen senders and pre-state recipients.',
+    label: 'Accounts',
+    value: '1,000',
+  },
+  {
+    definition: 'Number of TIP-20 tokens configured for this benchmark run.',
+    label: 'TIP-20 tokens',
+    value: '4',
+  },
+]
+
+const quantiles = [
+  ['p50', '219.1 ms'],
+  ['p95', '264.4 ms'],
+  ['p99', '452.3 ms'],
+]
+
+function Definition(props: Definition.Props) {
+  return (
+    <Popover.Root>
+      <Popover.Trigger
+        aria-label={`About ${props.label}`}
+        render={<Button shape="icon" size="small" variant="tertiary" />}
+      >
+        <InfoCircle />
+      </Popover.Trigger>
+      <Popover.Popup>
+        <Popover.Title>{props.label}</Popover.Title>
+        <Popover.Description>{props.children}</Popover.Description>
+      </Popover.Popup>
+    </Popover.Root>
+  )
+}
+
+declare namespace Definition {
+  type Props = { children: string; label: string }
+}
+
+export function Demo() {
+  const [nightly, setNightly] = useState<string | null>(nightlies[0] ?? null)
+  const [scenario, setScenario] = useState<string | null>('public-mix')
+  const commit = (nightly ?? '').slice(-8, -1)
+
+  return (
+    <div {...styles.page()}>
+      <header {...styles.bar()}>
+        <span {...styles.brand()}>Tempo Performance</span>
+        <nav aria-label="Performance" {...styles.nav()}>
+          <Button.Link aria-current="page" href="#dashboard" size="small" variant="secondary">
+            Dashboard
+          </Button.Link>
+          <Button.Link href="#methodology" size="small" variant="tertiary">
+            Methodology
+          </Button.Link>
+        </nav>
+      </header>
+
+      <div {...styles.run()}>
+        <div>
+          <h1 {...styles.title()}>Benchmark run</h1>
+          <p {...styles.meta()}>
+            Oct 20, 2026, 3:01 AM ·{' '}
+            <a href="#commit" {...styles.commit()}>
+              {commit}
+            </a>{' '}
+            · 2m 35s ·{' '}
+            <a href="#workflow" {...styles.link()}>
+              GitHub workflow
+            </a>
+          </p>
+        </div>
+        <div {...styles.filters()}>
+          <Field.Root {...styles.filter()}>
+            <Field.Label>Nightly</Field.Label>
+            <Select.Root onValueChange={setNightly} value={nightly}>
+              <Select.Trigger>
+                <Select.Value>
+                  {(value: string) => <span {...styles.mono()}>{value}</span>}
+                </Select.Value>
+                <Select.Icon />
+              </Select.Trigger>
+              <Select.Popup size="small">
+                {nightlies.map((value) => (
+                  <Select.Item key={value} value={value}>
+                    <Select.ItemText>
+                      <span {...styles.mono()}>{value}</span>
+                    </Select.ItemText>
+                  </Select.Item>
+                ))}
+              </Select.Popup>
+            </Select.Root>
+          </Field.Root>
+          <Field.Root {...styles.filter()}>
+            <Field.Label>Scenario</Field.Label>
+            <Select.Root items={scenarios} onValueChange={setScenario} value={scenario}>
+              <Select.Trigger>
+                <Select.Value />
+                <Select.Icon />
+              </Select.Trigger>
+              <Select.Popup size="small">
+                {Object.entries(scenarios).map(([value, label]) => (
+                  <Select.Item key={value} label={label} value={value}>
+                    <Select.ItemText>{label}</Select.ItemText>
+                  </Select.Item>
+                ))}
+              </Select.Popup>
+            </Select.Root>
+          </Field.Root>
+        </div>
+      </div>
+
+      <Surface size="medium">
+        <div {...styles.label()}>
+          Settled TPS
+          <Definition label="Settled TPS">
+            Median transactions per second that landed in blocks for this benchmark run.
+          </Definition>
+        </div>
+        <p {...styles.hero()}>
+          14,960 <span {...styles.unit()}>TPS</span>
+        </p>
+        <p {...styles.caption()}>
+          Median settled throughput across 142 measured blocks. Run duration: 2m 35s.
+        </p>
+      </Surface>
+
+      <Grid fit="small" gap="16">
+        {metrics.map((metric) => (
+          <Surface key={metric.label} size="medium">
+            <div {...styles.label()}>
+              {metric.label}
+              <Definition label={metric.label}>{metric.definition}</Definition>
+            </div>
+            <p {...styles.value()}>{metric.value}</p>
+          </Surface>
+        ))}
+      </Grid>
+
+      <Surface>
+        <Surface.Header {...styles.section()}>
+          <Surface.Title>Block validation</Surface.Title>
+          <ChoiceGroup.Root aria-label="Metric scope" defaultValue="network" size="small">
+            <ChoiceGroup.Item value="network">Network</ChoiceGroup.Item>
+            <ChoiceGroup.Item value="rpc">RPC node</ChoiceGroup.Item>
+            <ChoiceGroup.Item value="validators">Validators</ChoiceGroup.Item>
+          </ChoiceGroup.Root>
+        </Surface.Header>
+        <div {...styles.label()}>
+          <h3 {...styles.heading()}>New payload validation latency</h3>
+          <Definition label="New payload validation latency">
+            Latency percentiles reported by the consensus engine while validating newPayload
+            requests.
+          </Definition>
+        </div>
+        <div {...styles.chart()}>Time-series chart. The library has no chart component yet.</div>
+        <Table.Root size="small">
+          <Table.Caption>Average latency by quantile for this run</Table.Caption>
+          <Table.Head>
+            <Table.Row>
+              <Table.HeaderCell>Quantile</Table.HeaderCell>
+              <Table.HeaderCell>Average</Table.HeaderCell>
+            </Table.Row>
+          </Table.Head>
+          <Table.Body>
+            {quantiles.map(([quantile, average]) => (
+              <Table.Row key={quantile}>
+                <Table.Cell mono>{quantile}</Table.Cell>
+                <Table.Cell numeric>{average}</Table.Cell>
+              </Table.Row>
+            ))}
+          </Table.Body>
+        </Table.Root>
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const bar = style({
+    alignItems: 'center',
+    display: 'flex',
+    flexWrap: 'wrap',
+    gap: '12',
+    justifyContent: 'space-between',
+  })
+
+  export const brand = style({ typography: 'body.b1Strong' })
+
+  export const caption = style({ color: 'content.secondary', margin: '0', typography: 'body.b3' })
+
+  export const chart = style({
+    alignItems: 'center',
+    borderColor: 'line.secondary',
+    borderRadius: 'xs',
+    borderStyle: 'dashed',
+    borderWidth: 'regular',
+    color: 'content.secondary',
+    display: 'flex',
+    justifyContent: 'center',
+    marginBlock: '16',
+    minHeight: '200',
+    padding: '16',
+    textAlign: 'center',
+    typography: 'body.b3',
+  })
+
+  export const commit = style({ color: 'content.primary', typography: 'mono.m1' })
+
+  export const filter = style({ flex: '1 1 14rem !custom', minWidth: '0' })
+
+  export const filters = style({ display: 'flex', flexWrap: 'wrap', gap: '12' })
+
+  export const heading = style({ margin: '0', typography: 'body.b2Strong' })
+
+  export const hero = style({
+    alignItems: 'baseline',
+    columnGap: '8',
+    display: 'flex',
+    fontFamily: 'mono',
+    fontSize: '36',
+    fontVariantNumeric: 'tabular-nums !custom',
+    margin: '0',
+    marginBlock: '8',
+  })
+
+  export const label = style({
+    alignItems: 'center',
+    color: 'content.secondary',
+    columnGap: '4',
+    display: 'flex',
+    typography: 'body.b3',
+  })
+
+  export const link = style({ color: 'content.primary' })
+
+  export const meta = style({ color: 'content.secondary', margin: '0', typography: 'body.b3' })
+
+  export const mono = style({ typography: 'mono.m1' })
+
+  export const nav = style({ columnGap: '4', display: 'flex' })
+
+  export const page = style({
+    backgroundColor: 'background.primary',
+    display: 'flex',
+    flexDirection: 'column',
+    padding: '16',
+    rowGap: '16',
+  })
+
+  export const run = style({
+    alignItems: 'flex-end',
+    display: 'flex',
+    flexWrap: 'wrap',
+    gap: '16',
+    justifyContent: 'space-between',
+  })
+
+  export const section = style({ flexWrap: 'wrap', rowGap: '12' })
+
+  export const title = style({ margin: '0', typography: 'heading.h3' })
+
+  export const unit = style({ color: 'content.secondary', fontSize: '14' })
+
+  export const value = style({
+    fontFamily: 'mono',
+    fontSize: '24',
+    fontVariantNumeric: 'tabular-nums !custom',
+    margin: '0',
+    marginBlockStart: '4',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Products/PerformanceDashboard.tsx)
+
+The dashboard names the run and offers a run picker. Content runs from the headline metric down to the detailed sections.
+
+* **Page Links (aria-current):** Links to Dashboard and Methodology mark the current page. Use links, not tabs, since each is its own page.
+* **Run Header:** Shows the date, the short commit as a monospace link, the duration, and a link to the GitHub workflow.
+* **Run and Scenario (Select):** Selects pick the nightly run and the scenario. Run IDs, such as `main-2026-10-19-296be2ab`, render in monospace.
+* **Hero Metric (Surface):** Holds the settled TPS value and a caption that states its computation.
+* **Metric Tiles (fit=small):** A fitted grid holds one surface per metric. An info button opens each metric's definition.
+* **Sections (ChoiceGroup):** Switches the metric scope (Network, RPC node, or Validators) above a chart and a quantile table.
+
+Patterns:
+
+* [Dashboards](/docs/patterns/dashboards) for the hero metric, tile grid, filters, and sections.
+* [Tables and Lists](/docs/patterns/tables-and-lists) for the quantile table.
+* [Blockchain Values](/docs/patterns/blockchain-values) for commit hashes, gas units, and block counts.
+
+## Content
+
+### Lead With One Hero Metric
+
+Settled TPS is the headline of the run. Give it a caption that states the aggregate and the sample, such as Median settled throughput across 142 measured blocks.
+
+### Define Every Metric
+
+Give every tile and chart a one-sentence definition of the measurement and its aggregate. Start with the noun, as in Average wall-clock time between consecutive blocks.
+
+Open definitions in a [Popover](/docs/components/popover) from an icon button. A [Tooltip](/docs/components/tooltip) stays closed on touch input, so a phone never shows the definition.
+
+**Do:** Open a metric's definition in a `Popover`, with the metric name as its `Popover.Title`.
+
+**Don't:** Put a definition in a `Tooltip`, which stays closed on touch screens.
+
+### Put the Unit With the Value
+
+Write the full unit beside the number, such as 1.38 Ggas/s, and use one format per metric across tiles, legends, and tables.
+
+**Do:** Label the tile Avg gas/s and show 1.38 Ggas/s.
+
+**Don't:** Show 633ms in a tile and 219.1 ms in a legend for the same kind of value.
+
+### Say Submitted or Settled
+
+* **Submitted TPS:** The input of the load generator.
+* **Settled TPS:** The count of transactions included in blocks.
+
+Name the kind in every label, legend, and caption.
+
+### Identify Runs Exactly
+
+Show run IDs in full in the Nightly select, since two runs can share a date. In the run header, use the seven-character commit and link it to GitHub.
+
+### Name Quantiles the Same Way Everywhere
+
+Write quantiles as p50, p95, and p99 everywhere. State whether a chart shows one quantile, as in Persistence (p50), or several.
+
+## Open Gaps
+
+The library has no part for these needs yet. Before you add one, propose it as an issue in the Design System project.
+
+* **Charts:** No time-series, stacked, or bar chart exists, and no axis, legend, or hover readout. Legends also toggle series with Show only this series.
+* **Metric Tile:** A surface with a label, a definition button, and a value. All three Tempo products repeat it.
+* **Monospace Display Type (mono.m1):** The only mono set, at 12px. Hero and tile values pair `fontFamily: 'mono'` with a size token.
+* **Info Button:** Each screen composes the info button and popover for definitions again.
+
+## Related
+
+[Dashboards](/docs/patterns/dashboards)
+
+Covers metric layouts.
+
+[Tables and Lists](/docs/patterns/tables-and-lists)
+
+Covers quantile and timing tables.
+
+[Surface](/docs/components/surface)
+
+Use for tiles and sections.
+
+[Grid](/docs/components/grid)
+
+Use for the tile layout.
+
+[Popover](/docs/components/popover)
+
+Use for metric definitions.
+
+[Select](/docs/components/select)
+
+Use for run and scenario filters.
+
+[ChoiceGroup](/docs/components/choice-group)
+
+Use for the metric scope.