@tempoxyz/ds 0.3.10 → 0.3.13

package/dist/docs/product/components/badged-logo.md

@@ -0,0 +1,116 @@
+# BadgedLogo
+
+Marks a token or an app with a small badge on the corner of its logo.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/BadgedLogo.tsx)
+
+Figma: [Elements/Badged Logo](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5606-2531) (`BadgedLogo.Root`)
+
+## Overview
+
+A badged logo insets a 44px logo in a 56px box and overlaps its lower trailing corner with a 20px badge. The badge holds one icon, such as an arrow that marks the destination of a transfer.
+
+## Examples
+
+### Token
+
+```tsx
+/** Renders a token logo with an arrow badge on the BadgedLogo page. @module */
+import { BadgedLogo, TokenLogo } from '@tempoxyz/ds'
+import { ArrowRight } from '@tempoxyz/ds/icons'
+
+export function Demo() {
+  return (
+    <BadgedLogo.Root>
+      <TokenLogo symbol="USDC" />
+      <BadgedLogo.Badge>
+        <ArrowRight />
+      </BadgedLogo.Badge>
+    </BadgedLogo.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/BadgedLogo/Basic.tsx)
+
+### App
+
+An app without artwork takes a tile with the first letter of its name.
+
+```tsx
+/** Renders an app tile with an arrow badge on the BadgedLogo page. @module */
+import { BadgedLogo } from '@tempoxyz/ds'
+import { ArrowRight } from '@tempoxyz/ds/icons'
+
+export function Demo() {
+  return (
+    <BadgedLogo.Root>
+      <BadgedLogo.Tile>A</BadgedLogo.Tile>
+      <BadgedLogo.Badge>
+        <ArrowRight />
+      </BadgedLogo.Badge>
+    </BadgedLogo.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/BadgedLogo/App.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { BadgedLogo } from '@tempoxyz/ds'
+
+<BadgedLogo.Root>
+  <BadgedLogo.Tile />
+  <BadgedLogo.Badge />
+</BadgedLogo.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Mark the token or the app at one end of a transfer, such as the destination of a send.
+
+### When Not to Use
+
+* Use [TokenLogo](token-logo.md) for a token without a badge.
+* Use [Avatar](avatar.md) for a person, a contact, or a wallet.
+* Use [IconTile](icon-tile.md) for one icon above the title of a modal.
+
+### Put the Logo First and the Badge Last
+
+Pass one logo, then one `BadgedLogo.Badge`. The root sizes the logo to 44px, so leave its size unset.
+
+### Use One Small Icon in the Badge
+
+The badge centers one 12px icon in the primary color. Do not put text or a second icon in it.
+
+## Content
+
+Fill a `BadgedLogo.Tile` with the first letter of the app's name, in uppercase.
+
+## Accessibility
+
+A badged logo renders `<span>` elements with no role and takes no focus.
+
+* **Logo (img):** A token logo with `alt` announces its name.
+* **Badge (aria-hidden):** An icon without `aria-label` stays hidden.
+* **Meaning in Text:** Name what the badge means in text beside it.
+
+## Related
+
+[TokenLogo](token-logo.md)
+
+Use for a token logo without a badge.
+
+[Avatar](avatar.md)
+
+Use for people, contacts, and wallets.
+
+[IconTile](icon-tile.md)
+
+Use for one icon above the title of a modal.

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

@@ -0,0 +1,379 @@
+# Banner
+
+Shows a full-width message about the system or page.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Banner.tsx)
+
+## Overview
+
+A full-width strip for a message about the whole product or page.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Banner } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Banner>
+      <Banner.Content>Tempo mainnet is live.</Banner.Content>
+      <Banner.Action>Read more</Banner.Action>
+      <Banner.Dismiss />
+    </Banner>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Banner/Basic.tsx)
+
+### Intent
+
+Set `intent` to `neutral` (default), `info`, `positive`, `warning`, or `negative`.
+
+```tsx
+import { Banner, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      {(['neutral', 'info', 'positive', 'warning', 'negative'] as const).map((intent) => (
+        <Banner intent={intent} key={intent}>
+          <Banner.Content>Tempo mainnet is live.</Banner.Content>
+          <Banner.Action>Read more</Banner.Action>
+          <Banner.Dismiss />
+        </Banner>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({ display: 'flex', flexDirection: 'column', gap: '8' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Banner/Intent.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Banner } from '@tempoxyz/ds'
+
+<Banner>
+  <Banner.Content />
+  <Banner.Action />
+  <Banner.Dismiss />
+</Banner>
+```
+
+## Guidelines
+
+### When to Use
+
+* Report a condition that affects the whole product or page, such as degraded RPC service or paused deposits.
+* Announce maintenance or a change for every account, such as a new webhook retry policy.
+* Mark the environment, such as a testnet build of Tempo Wallet.
+
+### When Not to Use
+
+* Use [Alert](alert.md) for a message about one section, form, or field.
+* Use [Toast](toast.md) to confirm that an action finished, such as Payment sent.
+* If an action needs a decision before it continues, use [AlertDialog](alert-dialog.md).
+* Use `Field.Error` from [Field](field.md) for a validation message on one input.
+
+### Choose an Intent by Severity
+
+* **Neutral (neutral):** The default. Announcements with no severity, such as a testnet notice.
+* **Info (info):** Context that needs no action now, such as upcoming maintenance.
+* **Positive (positive):** A resolved condition, such as resumed deposits.
+* **Warning (warning):** Degraded service or a step to take soon, such as delayed deposits.
+* **Negative (negative):** An outage or failure that blocks work, such as paused payments.
+
+### State Severity in the Text
+
+Banner has no icon part, so the text carries the severity. The `intent` tint doesn't reach screen reader users or forced-colors modes.
+
+**Do:** Name the affected feature and the impact, such as delayed deposits.
+
+```tsx
+/**
+ * Do example for "State Severity in the Text" on the Banner page.
+ * Name the affected feature and the impact, such as delayed deposits.
+ * @module
+ */
+import { Banner } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Banner intent="warning">
+      <Banner.Content>Deposits from Ethereum are delayed by about 20 minutes.</Banner.Content>
+      <Banner.Action>View status</Banner.Action>
+    </Banner>
+  )
+}
+```
+
+**Don't:** Rely on the `negative` tint to say that something is broken.
+
+```tsx
+/**
+ * Don't example for "State Severity in the Text" on the Banner page.
+ * Don't rely on the `negative` tint to say that something is broken.
+ * @module
+ */
+import { Banner } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Banner intent="negative">
+      <Banner.Content>Heads up</Banner.Content>
+      <Banner.Action>Learn more</Banner.Action>
+    </Banner>
+  )
+}
+```
+
+### Show One Banner at a Time
+
+Hold the less severe messages until the current one clears. Place the banner above the page header.
+
+**Do:** Show the single most urgent banner above the page content.
+
+```tsx
+/**
+ * Do example for "Show One Banner at a Time" on the Banner page.
+ * Show the single most urgent banner above the page content.
+ * @module
+ */
+import { Banner, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <Banner intent="negative">
+        <Banner.Content>Payments are paused while we fix an RPC outage.</Banner.Content>
+      </Banner>
+      <div {...styles.content()}>
+        <div {...styles.label()}>Balance</div>
+        <div {...styles.value()}>$1,250.00</div>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const content = style({
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '4',
+    padding: '16',
+  })
+
+  export const label = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const page = style({ display: 'flex', flexDirection: 'column', width: '100% !custom' })
+
+  export const value = style({ color: 'content.primary', typography: 'heading.h2' })
+}
+```
+
+**Don't:** Stack several banners of different intents.
+
+```tsx
+/**
+ * Don't example for "Show One Banner at a Time" on the Banner page.
+ * Don't stack several banners of different intents.
+ * @module
+ */
+import { Banner, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <Banner intent="negative">
+        <Banner.Content>Payments are paused.</Banner.Content>
+      </Banner>
+      <Banner intent="info">
+        <Banner.Content>Maintenance on Oct 22 at 14:00 UTC.</Banner.Content>
+      </Banner>
+      <Banner>
+        <Banner.Content>Webhooks now retry for 24 hours.</Banner.Content>
+        <Banner.Dismiss />
+      </Banner>
+    </div>
+  )
+}
+
+namespace styles {
+  export const page = style({ display: 'flex', flexDirection: 'column', width: '100% !custom' })
+}
+```
+
+### Limit Dismissal to Announcements
+
+`Banner.Dismiss` only renders the button. Remove the banner in its `onClick`, and store the dismissal so the banner doesn't return on the next page.
+
+**Do:** Add `Banner.Dismiss` to announcements and `info` messages.
+
+```tsx
+/**
+ * Do example for "Limit Dismissal to Announcements" on the Banner page.
+ * Add `Banner.Dismiss` to announcements and `info` messages.
+ * @module
+ */
+import { Banner, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <Banner intent="info">
+        <Banner.Content>Maintenance starts Oct 22 at 14:00 UTC.</Banner.Content>
+        <Banner.Dismiss />
+      </Banner>
+    </div>
+  )
+}
+
+namespace styles {
+  export const page = style({ display: 'flex', flexDirection: 'column', width: '100% !custom' })
+}
+```
+
+**Don't:** Let people dismiss an active outage. Remove the banner when the condition ends.
+
+```tsx
+/**
+ * Don't example for "Limit Dismissal to Announcements" on the Banner page.
+ * Don't let people dismiss an active outage. Remove the banner when the condition ends.
+ * @module
+ */
+import { Banner, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <Banner intent="negative">
+        <Banner.Content>Payments are paused during an RPC outage.</Banner.Content>
+        <Banner.Dismiss />
+      </Banner>
+    </div>
+  )
+}
+
+namespace styles {
+  export const page = style({ display: 'flex', flexDirection: 'column', width: '100% !custom' })
+}
+```
+
+### Offer One Action
+
+**Do:** Add at most one `Banner.Action`, such as View status.
+
+```tsx
+/**
+ * Do example for "Offer One Action" on the Banner page.
+ * Add at most one `Banner.Action`, such as View status.
+ * @module
+ */
+import { Banner, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <Banner intent="warning">
+        <Banner.Content>Deposits from Ethereum are delayed by about 20 minutes.</Banner.Content>
+        <Banner.Action>View status</Banner.Action>
+      </Banner>
+    </div>
+  )
+}
+
+namespace styles {
+  export const page = style({ display: 'flex', flexDirection: 'column', width: '100% !custom' })
+}
+```
+
+**Don't:** Add several actions to one banner.
+
+```tsx
+/** Don't example for "Offer One Action" on the Banner page. Don't add several actions to one banner. @module */
+import { Banner, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <Banner intent="warning">
+        <Banner.Content>Deposits are delayed.</Banner.Content>
+        <Banner.Action>Status</Banner.Action>
+        <Banner.Action>Support</Banner.Action>
+        <Banner.Action>Retry</Banner.Action>
+      </Banner>
+    </div>
+  )
+}
+
+namespace styles {
+  export const page = style({ display: 'flex', flexDirection: 'column', width: '100% !custom' })
+}
+```
+
+## Content
+
+* Lead with what changed and who it affects, then what to do: Deposits from Ethereum are delayed by about 20 minutes.
+* Keep it to one or two short sentences.
+* Give times with a time zone, such as Maintenance starts Oct 22 at 14:00 UTC.
+* Describe the condition, not the intent. Write Payments are paused, not Error or Warning.
+* Name the destination in the action label, such as View status. Avoid Click here and Learn more.
+
+## Accessibility
+
+Renders a plain `div` with no role and no live region. The action and dismiss controls are native buttons, and the banner never takes focus.
+
+### Semantics
+
+* **Banner (div):** Not a landmark or live region. Screen readers read it in order, so place it before the main content.
+* **Banner.Action (button):** To make it a link, pass `render` with a link and `nativeButton={false}`.
+* **Banner.Dismiss (button):** Named "Dismiss" by default. Its close icon is decorative.
+
+### Keyboard
+
+* **Move to the Next Control (Tab):** Focuses the action, then the dismiss button.
+* **Activate the Button (Enter or Space):** Activates the action or the dismiss button.
+
+### Your Responsibilities
+
+* **Announce Late Banners (role):** If a banner appears after page load, add `role="status"`, or `role="alert"` for an outage.
+* **Move Focus on Dismiss:** After a dismissal, move focus to the start of the main content.
+* **Name Each Dismiss (aria-label):** If a page has several, name each one, such as "Dismiss maintenance notice".
+
+## Related
+
+[Alert](alert.md)
+
+Use for a message about one section.
+
+[Toast](toast.md)
+
+Use for confirming a finished action.
+
+[AlertDialog](alert-dialog.md)
+
+Use for a decision before an action continues.
+
+[Feedback and Status](../patterns/feedback-and-status.md)
+
+Covers choosing a message component.

package/dist/docs/product/components/bar-chart.md

@@ -0,0 +1,208 @@
+# BarChart
+
+Shows values over time as stacked bars, such as the daily spend of each agent.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/BarChart.tsx)
+
+Figma: [Data/Chart Tooltip](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-5422) (`BarChart.Tooltip`), [Data/Stacked Bar Chart](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-4523)
+
+## Overview
+
+A bar chart renders one bar per entry of its data, with a segment for each series stacked from the baseline. A value axis with three even ticks leads the plot, labels name the bars under it, and a legend names each series. Hovering a bar, or moving to it with the arrow keys, shows the value of each series. Values are zero or more, such as spend or counts. Chart a signed change, such as a refund, another way.
+
+## Examples
+
+### Basic
+
+```tsx
+import { BarChart } from '@tempoxyz/ds'
+
+const days = ['Oct 1', 'Oct 2', 'Oct 3', 'Oct 4', 'Oct 5', 'Oct 6', 'Today']
+
+export function Demo() {
+  return (
+    <BarChart
+      aria-label="Spend by agent"
+      data={days.map((day, index) => ({
+        claude: [1.2, 0.8, 2.1, 0, 1.6, 2.4, 1.1][index]!,
+        codex: [0.4, 0.9, 0.3, 0, 1.2, 0.6, 0.8][index]!,
+        day,
+      }))}
+      format={(value) => `$${value}`}
+      index="day"
+      series={[
+        { color: '#d97757', key: 'claude', label: 'Claude' },
+        { color: '#10a37f', key: 'codex', label: 'Codex' },
+      ]}
+    />
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/BarChart/Basic.tsx)
+
+### Ticks
+
+Pass `ticks` to label only some bars, such as every seventh day.
+
+```tsx
+import { BarChart } from '@tempoxyz/ds'
+
+const days = Array.from({ length: 30 }, (_, index) => (index === 29 ? 'Today' : `Oct ${index + 1}`))
+
+export function Demo() {
+  return (
+    <BarChart
+      aria-label="Spend over 30 days"
+      data={days.map((day, index) => ({ claude: ((index * 7) % 11) / 4, day }))}
+      format={(value) => `$${value}`}
+      index="day"
+      series={[{ color: '#d97757', key: 'claude', label: 'Claude' }]}
+      ticks={['Oct 1', 'Oct 8', 'Oct 15', 'Oct 22', 'Today']}
+    />
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/BarChart/Ticks.tsx)
+
+### Tooltip
+
+`BarChart.Tooltip` renders the card that a hovered bar shows, which also renders alone.
+
+```tsx
+import { BarChart } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <BarChart.Tooltip
+      items={[
+        { color: '#0a0a0a', label: 'CLI', value: '$3.27' },
+        { color: '#10a37f', label: 'Codex', value: '$0.90' },
+        { color: '#1f1f1f', label: 'Cursor', value: '$0.10' },
+      ]}
+      label="Oct 12"
+      total="$4.32"
+    />
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/BarChart/Tooltip.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { BarChart } from '@tempoxyz/ds'
+
+<BarChart />
+<BarChart.Tooltip />
+```
+
+## Guidelines
+
+### When to Use
+
+* Show how a value changes over days or weeks, and which series make it up.
+
+### When Not to Use
+
+* Use [SplitBar](split-bar.md) to split one total between two parts.
+* Use [Table](table.md) when people need to read or compare exact values.
+* Use [Gauge](gauge.md) for one value against a limit.
+
+### Keep Each Series in One Color
+
+**Do:** Give each series a color that stays the same wherever it appears, such as the agent's own color.
+
+```tsx
+import { BarChart } from '@tempoxyz/ds'
+
+const days = ['Oct 1', 'Oct 2', 'Oct 3', 'Today']
+
+export function Demo() {
+  return (
+    <BarChart
+      aria-label="Spend by agent"
+      data={days.map((day, index) => ({ claude: index + 1, codex: 1, day }))}
+      format={(value) => `$${value}`}
+      height={140}
+      index="day"
+      series={[
+        { color: '#d97757', key: 'claude', label: 'Claude' },
+        { color: '#10a37f', key: 'codex', label: 'Codex' },
+      ]}
+    />
+  )
+}
+```
+
+**Don't:** Use the positive and negative colors for series. They mean a status.
+
+```tsx
+import { BarChart } from '@tempoxyz/ds'
+
+const days = ['Oct 1', 'Oct 2', 'Oct 3', 'Today']
+
+export function Demo() {
+  return (
+    <BarChart
+      aria-label="Spend by agent"
+      data={days.map((day, index) => ({ claude: index + 1, codex: 1, day }))}
+      format={(value) => `$${value}`}
+      height={140}
+      index="day"
+      series={[
+        { color: '#13a963', key: 'claude', label: 'Claude' },
+        { color: '#eb3417', key: 'codex', label: 'Codex' },
+      ]}
+    />
+  )
+}
+```
+
+### Label a Few Bars
+
+* **Every Bar (up to 7):** Label every bar of a week.
+* **Every Seventh Bar (ticks):** Label every seventh bar of a month.
+
+## Content
+
+### Format Values the Same Way
+
+Pass one `format` for the axis, the tooltip, and the total, such as whole dollars. Name each series with the name people know it by, such as Claude.
+
+## Accessibility
+
+A bar chart renders a `<div>` with the `figure` role. Its plot takes focus, and the arrow keys move between bars and show their tooltip.
+
+### Semantics
+
+* **Root (figure):** Screen readers announce the chart by its `aria-label`.
+* **Legend (text):** The legend names each series in text, so color is never the only cue.
+
+### Keyboard
+
+* **Move Focus to the Plot (Tab):** Moves focus to the plot, which shows the first bar's tooltip.
+* **Move Between Bars (Left or Right Arrow):** Moves to the previous or next bar and shows its tooltip.
+
+### Your Responsibilities
+
+* **Name the Chart (aria-label):** Pass `aria-label`, or `aria-labelledby` pointing at the chart's heading.
+* **Offer the Values (Table):** Offer the same values in a [Table](table.md) when people need exact values.
+
+## Related
+
+[SplitBar](split-bar.md)
+
+Use for one total split between two parts.
+
+[AgentLogo](agent-logo.md)
+
+Use for the agent of each series.
+
+[Table](table.md)
+
+Use for exact values.