@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/gauge.md

@@ -0,0 +1,299 @@
+# Gauge
+
+Shows a measurement within a range as a ring.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Gauge.tsx)
+
+## Overview
+
+A gauge is a ring that shows a measurement within a range, such as usage or a score.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Gauge } from '@tempoxyz/ds'
+
+export function Demo() {
+  return <Gauge aria-label="Storage used" showValue value={72} />
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Gauge/Basic.tsx)
+
+### Intent
+
+Set `intent` to `neutral` (default) or `positive`.
+
+```tsx
+import { Gauge, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {(['neutral', 'positive'] as const).map((intent, index) => (
+        <Gauge aria-label={intent} intent={intent} key={intent} showValue value={20 + index * 20} />
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '16' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Gauge/Intent.tsx)
+
+### Size
+
+Set `size` to `small`, `medium` (default), or `large`.
+
+```tsx
+import { Gauge, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Gauge aria-label="Small" size="small" value={72} />
+      <Gauge aria-label="Medium" size="medium" value={72} />
+      <Gauge aria-label="Large" showValue size="large" value={72} />
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '16' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Gauge/Size.tsx)
+
+### ShowValue
+
+Set `showValue` to print the value inside the ring.
+
+```tsx
+import { Gauge, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Gauge aria-label="Hidden value" value={40} />
+      <Gauge aria-label="Shown value" showValue value={40} />
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '16' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Gauge/ShowValue.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Gauge } from '@tempoxyz/ds'
+
+<Gauge />
+```
+
+## Guidelines
+
+### When to Use
+
+* Show how much of a limit is used, such as API requests against a quota.
+* Show a ratio in a metric tile, such as gas used against the gas limit.
+* Show a score with a fixed range, such as validator uptime.
+
+### When Not to Use
+
+* Use [Progress](/docs/components/progress) for a task that advances, such as an upload.
+* Use [Skeleton](/docs/components/skeleton) or [Spinner](/docs/components/spinner) while the measurement loads.
+* Use [Slider](/docs/components/slider) when the user sets the value.
+* Use plain text if the value has no fixed maximum, such as 4,812 TPS.
+
+### Show the Value in Text
+
+Set `showValue` to print the percentage in the ring.
+
+**Do:** Pair the ring with its label and the absolute values beside it.
+
+```tsx
+/**
+ * Do example for "Show the Value in Text" on the Gauge page.
+ * Pair the ring with its label and the absolute values beside it.
+ * @module
+ */
+import { Gauge, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Gauge aria-labelledby="gauge-requests" max={10000} showValue value={7200} />
+      <div {...styles.text()}>
+        <div {...styles.label()} id="gauge-requests">
+          API requests this month
+        </div>
+        <div {...styles.value()}>7,200 of 10,000</div>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.primary', typography: 'body.b2' })
+
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+
+  export const text = style({ display: 'flex', flexDirection: 'column', gap: '4' })
+
+  export const value = style({ color: 'content.secondary', typography: 'body.b3' })
+}
+```
+
+**Don't:** Show a ring without its value or what it measures.
+
+```tsx
+/**
+ * Don't example for "Show the Value in Text" on the Gauge page.
+ * Don't show a ring without its value or what it measures.
+ * @module
+ */
+import { Gauge } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return <Gauge aria-label="Usage" max={10000} value={7200} />
+}
+```
+
+### Pass the Real Range
+
+The ring, `showValue`, and the accessible value derive the percentage from `min` (default 0) and `max` (default 100).
+
+**Do:** Set `max` to the actual bound, such as `value={7200}` with `max={10000}`.
+
+```tsx
+/**
+ * Do example for "Pass the Real Range" on the Gauge page.
+ * Set `max` to the actual bound, such as `value={7200}` with `max={10000}`.
+ * @module
+ */
+import { Gauge, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Gauge aria-labelledby="gauge-range" max={10000} showValue value={7200} />
+      <div {...styles.text()}>
+        <div {...styles.label()} id="gauge-range">
+          API requests this month
+        </div>
+        <div {...styles.value()}>7,200 of 10,000</div>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.primary', typography: 'body.b2' })
+
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+
+  export const text = style({ display: 'flex', flexDirection: 'column', gap: '4' })
+
+  export const value = style({ color: 'content.secondary', typography: 'body.b3' })
+}
+```
+
+**Don't:** Pass a raw count against the default `max` of 100.
+
+```tsx
+/**
+ * Don't example for "Pass the Real Range" on the Gauge page.
+ * Don't pass a raw count against the default `max` of 100.
+ * @module
+ */
+import { Gauge, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Gauge aria-labelledby="gauge-default" showValue value={7200} />
+      <div {...styles.text()}>
+        <div {...styles.label()} id="gauge-default">
+          API requests this month
+        </div>
+        <div {...styles.value()}>7,200 of 10,000</div>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.primary', typography: 'body.b2' })
+
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+
+  export const text = style({ display: 'flex', flexDirection: 'column', gap: '4' })
+
+  export const value = style({ color: 'content.secondary', typography: 'body.b3' })
+}
+```
+
+### Choose an Intent
+
+* **Most Measurements (neutral):** The default, for a measurement such as API requests against a quota.
+* **Full Is Good (positive):** A measurement where a full value is good, such as 100% uptime.
+* **Nearing a Limit (Alert):** There is no `warning` intent. Add a `warning` [Alert](/docs/components/alert) with the next step.
+
+### Match Size to Context
+
+* **Small (32px):** Table cells and dense lists. Print the value beside it.
+* **Medium (48px):** The default, for metric tiles and cards.
+* **Large (80px):** A featured measurement, such as plan usage in billing.
+
+## Content
+
+* **Label:** Name the measurement, not the component, such as Gas used.
+
+## Accessibility
+
+A gauge renders a `meter`. It follows the [WAI-ARIA Authoring Practices meter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/meter/). It is not a live region, so a changed value is read only on the next visit.
+
+### Semantics
+
+* **Root (meter):** Reports its minimum, maximum, and value to assistive technology.
+* **Value Text (72%):** Defaults to the value as a locale-formatted percentage of the range.
+* **Ring (aria-hidden):** Hidden. Assistive technology reads the value text instead.
+* **Visible Value (showValue):** Shows the number. It ignores `format`, which changes only the announced text.
+* **Arc Color (foreground):** Green for positive intent, on a gray track. Keep the gauge on a plain surface.
+* **Reduced Motion (reduce):** Under reduced motion, the arc doesn't animate between values.
+
+### Your Responsibilities
+
+* **Name the Gauge (SC 4.1.2):** Use `aria-label` or `aria-labelledby`. The gauge renders no label.
+* **Describe Non-Percentage Values (getAriaValueText):** Use it if a percentage doesn't describe the value, such as "7.2 of 10 GB".
+
+## Related
+
+[Progress](/docs/components/progress)
+
+Use for a task that advances.
+
+[Alert](/docs/components/alert)
+
+Use for a warning when usage nears a limit.
+
+[Dashboards](/docs/patterns/dashboards)
+
+Covers laying out metric tiles.

package/dist/docs/components/get-started-visual.md

@@ -0,0 +1,117 @@
+# GetStartedVisual
+
+Illustrates one step of a get started flow at the top of its card.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/GetStartedVisual.tsx)
+
+Figma: [Content/Get Started Visual](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-3110)
+
+## Overview
+
+A get started visual renders a 320 by 160px illustration on a dark ground. `step` selects the artwork of connecting, adding funds, or adding a passkey.
+
+## Examples
+
+### Basic
+
+Set `step` to `connect` (default), `funds`, or `passkey`.
+
+```tsx
+/** Demonstrates GetStartedVisual in the documentation. @module */
+import { GetStartedVisual, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.frame()}>
+      <GetStartedVisual step="connect" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const frame = style({ maxWidth: '20rem !custom', width: '100% !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/GetStartedVisual/Basic.tsx)
+
+### Steps
+
+Each step of the flow has its own artwork.
+
+```tsx
+/** Demonstrates GetStartedVisual in the documentation. @module */
+import { GetStartedVisual, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <GetStartedVisual step="connect" />
+      <GetStartedVisual step="funds" />
+      <GetStartedVisual step="passkey" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ display: 'flex', flexWrap: 'wrap', gap: '16' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/GetStartedVisual/Steps.tsx)
+
+## Anatomy
+
+Import the component.
+
+```tsx
+import { GetStartedVisual } from '@tempoxyz/ds'
+
+<GetStartedVisual />
+```
+
+## Guidelines
+
+### When to Use
+
+* Open each card of a get started list, above the title of its step.
+
+### When Not to Use
+
+* Use [Visual](/docs/components/visual) for the top of a modal.
+* Use [IconTile](/docs/components/icon-tile) for a step that needs only an icon.
+
+### Match the Artwork to the Step
+
+**Do:** Show the funds artwork on the step that adds funds.
+
+```tsx
+<GetStartedVisual step="funds" />
+```
+
+**Don't:** Reuse one artwork for every step.
+
+```tsx
+<GetStartedVisual step="passkey" />
+```
+
+### Use One Visual per Card
+
+Place one visual at the top of a card. Two visuals in one card compete for attention.
+
+## Accessibility
+
+The visual renders a `<div>` with no role and takes no focus. Screen readers skip the artwork.
+
+* **Artwork (aria-hidden):** Decorative, so screen readers skip it.
+* **Name the Step in Text (Your task):** The title of the card names the step.
+
+## Related
+
+[Visual](/docs/components/visual)
+
+Use for the illustration at the top of a modal.
+
+[HeroVisual](/docs/components/hero-visual)
+
+Use for the hero card beside a setup flow.

package/dist/docs/components/grid.md

@@ -0,0 +1,288 @@
+# Grid
+
+Lays out children on a responsive grid.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Grid.tsx)
+
+## Overview
+
+Grid places children on equal tracks, either a fixed `columns` count or as many as the width allows with `fit`.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Grid, Inset, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Grid columns="3" gap="16">
+      {[1, 2, 3].map((n) => (
+        <Inset key={n} space="16" {...styles.card()}>
+          Column {n}
+        </Inset>
+      ))}
+    </Grid>
+  )
+}
+
+namespace styles {
+  export const card = style({ backgroundColor: 'background.elevated', borderRadius: 'sm' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Grid/Basic.tsx)
+
+### Fit
+
+Set `fit` to `small`, `medium`, or `large` for tracks of at least 10rem, 14rem, or 20rem. It overrides `columns`.
+
+```tsx
+import { Grid, Inset, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Grid fit="medium" gap="16">
+      {[1, 2, 3, 4].map((n) => (
+        <Inset key={n} block="24" inline="32" {...styles.card()}>
+          Fit {n}
+        </Inset>
+      ))}
+    </Grid>
+  )
+}
+
+namespace styles {
+  export const card = style({ backgroundColor: 'background.elevated', borderRadius: 'sm' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Grid/Fit.tsx)
+
+### Columns
+
+Set `columns` to `1`, `2`, `3`, `4`, `6`, or `12` equal tracks.
+
+```tsx
+import { Grid, Inset, Stack, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Stack gap="24">
+      {(['2', '3', '4'] as const).map((columns) => (
+        <Grid columns={columns} gap="8" key={columns}>
+          {Array.from({ length: Number(columns) }, (_, index) => (
+            <Inset key={index} space="16" {...styles.card()}>
+              {columns} columns
+            </Inset>
+          ))}
+        </Grid>
+      ))}
+    </Stack>
+  )
+}
+
+namespace styles {
+  export const card = style({ backgroundColor: 'background.elevated', borderRadius: 'sm' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Grid/Columns.tsx)
+
+### Gap
+
+Set `gap` to a spacing token. `rowGap` and `columnGap` override it on one axis.
+
+```tsx
+import { Grid, Inset, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Grid columnGap="8" columns="3" rowGap="32">
+      {[1, 2, 3, 4, 5, 6].map((n) => (
+        <Inset key={n} space="16" {...styles.card()}>
+          Column {n}
+        </Inset>
+      ))}
+    </Grid>
+  )
+}
+
+namespace styles {
+  export const card = style({ backgroundColor: 'background.elevated', borderRadius: 'sm' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Grid/Gap.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Grid } from '@tempoxyz/ds'
+
+<Grid />
+```
+
+## Guidelines
+
+### When to Use
+
+* Lay out similar items, such as metric tiles, token balance cards, or API key cards.
+* Build a two-dimensional page layout with a fixed structure, such as a 12-column dashboard.
+
+### When Not to Use
+
+* Use [Table](/docs/components/table) for records to compare across columns, such as transactions.
+* Use [Stack](/docs/components/stack) for one column, and [Inline](/docs/components/inline) for one row.
+
+### Prefer Fit Over Fixed Columns
+
+**Do:** Set `fit` so tiles drop to fewer columns as the width shrinks.
+
+```tsx
+/**
+ * Do example for "Prefer Fit Over Fixed Columns" on the Grid page.
+ * Set `fit` so tiles drop to fewer columns as the width shrinks.
+ * @module
+ */
+import { Grid, style, Surface } from '@tempoxyz/ds'
+
+const metrics = [
+  ['TPS', '4,218'],
+  ['Block time', '0.5s'],
+  ['Finality', '0.6s'],
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Grid fit="small" gap="12" {...styles.canvas()}>
+      {metrics.map(([label, value]) => (
+        <Surface key={label} size="medium">
+          <span {...styles.label()}>{label}</span>
+          <span {...styles.value()}>{value}</span>
+        </Surface>
+      ))}
+    </Grid>
+  )
+}
+
+namespace styles {
+  export const canvas = style({
+    backgroundColor: 'background.primary',
+    borderRadius: 'sm',
+    boxSizing: 'border-box',
+    padding: '12',
+    width: '100% !custom',
+  })
+
+  export const label = style({
+    color: 'content.secondary',
+    display: 'block',
+    typography: 'body.b3',
+  })
+
+  export const value = style({ display: 'block', typography: 'heading.h3' })
+}
+```
+
+**Don't:** Force four fixed columns into a narrow container.
+
+```tsx
+/**
+ * Don't example for "Prefer Fit Over Fixed Columns" on the Grid page.
+ * Don't force four fixed columns into a narrow container.
+ * @module
+ */
+import { Grid, style, Surface } from '@tempoxyz/ds'
+
+const metrics = [
+  ['TPS', '4,218'],
+  ['Block time', '0.5s'],
+  ['Finality', '0.6s'],
+  ['Gas price', '0.1 gwei'],
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Grid columns="4" gap="12" {...styles.canvas()}>
+      {metrics.map(([label, value]) => (
+        <Surface key={label} size="medium">
+          <span {...styles.label()}>{label}</span>
+          <span {...styles.value()}>{value}</span>
+        </Surface>
+      ))}
+    </Grid>
+  )
+}
+
+namespace styles {
+  export const canvas = style({
+    backgroundColor: 'background.primary',
+    borderRadius: 'sm',
+    boxSizing: 'border-box',
+    padding: '12',
+    width: '100% !custom',
+  })
+
+  export const label = style({
+    color: 'content.secondary',
+    display: 'block',
+    typography: 'body.b3',
+  })
+
+  export const value = style({ display: 'block', typography: 'heading.h3' })
+}
+```
+
+### Change Columns at Breakpoints
+
+If a layout needs a set count per width, change `gridTemplateColumns` under a [breakpoint](/docs/foundations/layout#breakpoints) key. Write the narrowest layout as the base style.
+
+* **Base (0 to 767px):** One column on phones, with no media key.
+* **Tablet ('@media 768'):** More columns from 48rem.
+* **Desktop ('@media 1024'):** The full count from 64rem. Use `'@media <1024'` for anything narrower.
+
+### Pick a Gap From the Scale
+
+* **Cards (24):** The default, for cards.
+* **Dense Tiles (12 or 16):** For dense dashboard tiles.
+
+## Accessibility
+
+Grid has no role, name, or keyboard behavior.
+
+### Semantics
+
+* **Default Element (div):** Has no role. Screen readers pass over it.
+* **Semantic Element (render):** If the children are items or links, render a list or nav, such as `render={<ul />}`.
+
+### Your Responsibilities
+
+* **Match DOM and Visual Order (Tab):** Don't reorder children with CSS or grid placement. Reading and focus follow the DOM ([SC 1.3.2](https://www.w3.org/WAI/WCAG22/Understanding/meaningful-sequence.html), [SC 2.4.3](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html)).
+
+## Related
+
+[Surface](/docs/components/surface)
+
+Use for the cards inside a grid.
+
+[Table](/docs/components/table)
+
+Use for comparing records.
+
+[Dashboards](/docs/patterns/dashboards)
+
+Covers metric tile layouts.
+
+[Responsive Layout](/docs/patterns/responsive-layout)
+
+Covers adapting pages across breakpoints.