@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/snippet.md

@@ -0,0 +1,424 @@
+# Snippet
+
+Shows a command or value with a copy button.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Snippet.tsx)
+
+Figma: [Content/Code Snippet](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-3317)
+
+## Overview
+
+Snippet renders a command or value in a `<code>` element, with a copy button in the corner. A click anywhere on the command copies it.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Snippet, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return <Snippet {...styles.snippet()}>pnpm add @tempoxyz/ds</Snippet>
+}
+
+namespace styles {
+  export const snippet = style({ maxWidth: '28rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Snippet/Basic.tsx)
+
+### Wrap
+
+The first word, the program, renders in the primary color. Long commands wrap, and wrapped lines align with the arguments.
+
+```tsx
+import { Snippet, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Snippet {...styles.snippet()}>
+      claude "Read https://tempo.xyz/SKILL.md and connect to my Tempo wallet"
+    </Snippet>
+  )
+}
+
+namespace styles {
+  export const snippet = style({ maxWidth: '24.75rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Snippet/Wrap.tsx)
+
+### Prompt
+
+Set `prompt` to a glyph, or to `false` to hide it. It defaults to `$`.
+
+```tsx
+import { Snippet, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Snippet prompt={false} {...styles.snippet()}>
+      https://ds.tempo.xyz
+    </Snippet>
+  )
+}
+
+namespace styles {
+  export const snippet = style({ maxWidth: '28rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Snippet/Prompt.tsx)
+
+### Tabs
+
+Pass a [Tabs](/docs/components/tabs) list as `tabs` to switch between commands. Wrap the snippet in `Tabs.Root`, and pass the command of the active tab as `children`.
+
+```tsx
+import { Snippet, style, Tabs } from '@tempoxyz/ds'
+import { useState } from 'react'
+
+export const fill = true
+const commands = {
+  bun: 'bun add @tempoxyz/ds zyzz',
+  npm: 'npm install @tempoxyz/ds zyzz',
+  pnpm: 'pnpm add @tempoxyz/ds zyzz',
+} as const
+
+const managers = ['npm', 'pnpm', 'bun'] as const
+
+export function Demo() {
+  const [manager, setManager] = useState<(typeof managers)[number]>('npm')
+
+  return (
+    <Tabs.Root
+      onValueChange={(value) => {
+        const entry = managers.find((item) => item === value)
+        if (entry) setManager(entry)
+      }}
+      value={manager}
+    >
+      <Snippet
+        labels={{ copy: 'Copy install command' }}
+        tabs={
+          <Tabs.List aria-label="Package manager">
+            {managers.map((entry) => (
+              <Tabs.Tab key={entry} value={entry}>
+                {entry}
+              </Tabs.Tab>
+            ))}
+            <Tabs.Indicator />
+          </Tabs.List>
+        }
+        {...styles.snippet()}
+      >
+        {commands[manager]}
+      </Snippet>
+    </Tabs.Root>
+  )
+}
+
+namespace styles {
+  export const snippet = style({ maxWidth: '28rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Snippet/Tabs.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Snippet, Tabs } from '@tempoxyz/ds'
+
+<Tabs.Root>
+  <Snippet
+    tabs={
+      <Tabs.List>
+        <Tabs.Tab />
+        <Tabs.Indicator />
+      </Tabs.List>
+    }
+  />
+</Tabs.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Show a command, such as an install command or a `curl` request.
+* Show a value to paste elsewhere, such as a webhook URL or an RPC endpoint, with `prompt={false}`.
+* Show one command per tool, such as an agent or a package manager, with `tabs`.
+
+### When Not to Use
+
+* Use [SecretValue](/docs/components/secret-value) for API keys and other secrets, which stay masked.
+* Use [Hex](/docs/components/hex) with `copy` for addresses and hashes, which truncates the middle to fit.
+* Use [CopyButton](/docs/components/copy-button) to add copying beside your own text.
+* Use [Tabs](/docs/components/tabs) with panels to switch content other than commands.
+
+### Copy Exactly What You Show
+
+Snippet copies its `children`, never the prompt.
+
+**Do:** Pass only the command, so the pasted text runs as is.
+
+```tsx
+/**
+ * Do example for "Copy Exactly What You Show" on the Snippet page.
+ * Pass only the command, so the pasted text runs as is.
+ * @module
+ */
+import { Snippet, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return <Snippet {...styles.snippet()}>pnpm add @tempoxyz/ds</Snippet>
+}
+
+namespace styles {
+  export const snippet = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Type a leading `$` into the command.
+
+```tsx
+/**
+ * Don't example for "Copy Exactly What You Show" on the Snippet page.
+ * Don't type a leading `$` into the command.
+ * @module
+ */
+import { Snippet, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return <Snippet {...styles.snippet()}>$ pnpm add @tempoxyz/ds</Snippet>
+}
+
+namespace styles {
+  export const snippet = style({ width: '100% !custom' })
+}
+```
+
+### Show the Prompt Only for Shell Commands
+
+The `$` marks text to run in a terminal.
+
+**Do:** Set `prompt={false}` for a URL or other value.
+
+```tsx
+/**
+ * Do example for "Show the Prompt Only for Shell Commands" on the Snippet page.
+ * Set `prompt={false}` for a URL or other value.
+ * @module
+ */
+import { Snippet, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Snippet prompt={false} {...styles.snippet()}>
+      https://example.com/webhooks/tempo
+    </Snippet>
+  )
+}
+
+namespace styles {
+  export const snippet = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Show a shell prompt before a value that isn't a command.
+
+```tsx
+/**
+ * Don't example for "Show the Prompt Only for Shell Commands" on the Snippet page.
+ * Don't show a shell prompt before a value that isn't a command.
+ * @module
+ */
+import { Snippet, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return <Snippet {...styles.snippet()}>https://example.com/webhooks/tempo</Snippet>
+}
+
+namespace styles {
+  export const snippet = style({ width: '100% !custom' })
+}
+```
+
+### Keep One Command per Snippet
+
+Long commands wrap. Use a code block for multi-line scripts and config files.
+
+**Do:** Split a multi-step setup into one snippet per command.
+
+```tsx
+/**
+ * Do example for "Keep One Command per Snippet" on the Snippet page.
+ * Split a multi-step setup into one snippet per command.
+ * @module
+ */
+import { Snippet, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Snippet>pnpm add @tempoxyz/ds</Snippet>
+      <Snippet>pnpm build</Snippet>
+      <Snippet>pnpm dev</Snippet>
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({ display: 'grid', gap: '8', width: '100% !custom' })
+}
+```
+
+**Don't:** Chain several commands into one snippet.
+
+```tsx
+/**
+ * Don't example for "Keep One Command per Snippet" on the Snippet page.
+ * Don't chain several commands into one snippet.
+ * @module
+ */
+import { Snippet, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return <Snippet {...styles.snippet()}>pnpm add @tempoxyz/ds && pnpm build && pnpm dev</Snippet>
+}
+
+namespace styles {
+  export const snippet = style({ width: '100% !custom' })
+}
+```
+
+### Switch Alternatives with Tabs
+
+If the command differs per tool, such as a package manager, show one snippet with a tab per tool.
+
+**Do:** Show one command per package manager in one snippet with tabs.
+
+```tsx
+/**
+ * Do example for "Switch Alternatives with Tabs" on the Snippet page.
+ * Show one command per package manager in one snippet with tabs.
+ * @module
+ */
+import { Snippet, style, Tabs } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Tabs.Root defaultValue="npm" {...styles.root()}>
+      <Snippet
+        tabs={
+          <Tabs.List aria-label="Package manager">
+            <Tabs.Tab value="npm">npm</Tabs.Tab>
+            <Tabs.Tab value="pnpm">pnpm</Tabs.Tab>
+            <Tabs.Tab value="bun">bun</Tabs.Tab>
+            <Tabs.Indicator />
+          </Tabs.List>
+        }
+      >
+        npm install @tempoxyz/ds
+      </Snippet>
+    </Tabs.Root>
+  )
+}
+
+namespace styles {
+  export const root = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Stack one snippet per package manager.
+
+```tsx
+/**
+ * Don't example for "Switch Alternatives with Tabs" on the Snippet page.
+ * Don't stack one snippet per package manager.
+ * @module
+ */
+import { Snippet, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Snippet>npm install @tempoxyz/ds</Snippet>
+      <Snippet>pnpm add @tempoxyz/ds</Snippet>
+      <Snippet>bun add @tempoxyz/ds</Snippet>
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({ display: 'grid', gap: '8', width: '100% !custom' })
+}
+```
+
+## Content
+
+* Write commands that run unchanged. If a value differs per person, read it from an environment variable, such as `$TEMPO_API_KEY`, not a placeholder.
+* Never put a real secret in a snippet.
+* Introduce each snippet with a sentence that states what it does and where to run it.
+
+## Accessibility
+
+The command renders in a `<code>` element. The copy button follows the [WAI-ARIA button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/), and the tabs follow the [WAI-ARIA tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).
+
+### Semantics
+
+* **Command (code):** Wraps to its width, so the whole command stays visible without scrolling.
+* **Prompt (aria-hidden):** Hidden from screen readers, and never selected or copied with the command.
+* **Copy Button (button):** Named "Copy" unless you pass `labels.copy`. Reads "Copied" for two seconds, and a hidden live region announces each copy.
+* **Tabs (tablist):** Switches the command in place. A click on a tab never copies, and the list needs its own name.
+
+### Keyboard
+
+* **Move Through the Snippet (Tab):** Moves focus to the active tab, if any, then to the copy button.
+* **Switch the Command (Arrow keys):** Moves between tabs. Enter or Space shows the command of the focused tab.
+* **Copy the Command (Enter or Space):** Copies the command from the copy button. Focus stays on the button.
+
+A click anywhere on the command also copies, unless your `onClick` calls `preventDefault()`. The button is the keyboard path.
+
+### Your Responsibilities
+
+* **Label Each Snippet (labels.copy):** If a page shows several snippets, put a visible heading before each, and name each copy button, such as "Copy install command".
+* **Name the Tabs (SC 4.1.2):** Name the tab list, such as "Package manager", and pass the command of the active tab as the children.
+
+## Related
+
+[CopyButton](/docs/components/copy-button)
+
+Use for copying beside your own layout.
+
+[SecretValue](/docs/components/secret-value)
+
+Use for secrets.
+
+[Hex](/docs/components/hex)
+
+Use for addresses and hashes.
+
+[Kbd](/docs/components/kbd)
+
+Use for keyboard shortcuts.
+
+[Tabs](/docs/components/tabs)
+
+Use for switching between related views.

package/dist/docs/components/spinner.md

@@ -0,0 +1,216 @@
+# Spinner
+
+Shows that something is loading.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Spinner.tsx)
+
+Figma: [Spinner](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=1186-3872)
+
+## Overview
+
+An indeterminate loading indicator whose arc draws in the current text color, optionally on an elevated tile. Pass `aria-label` to name what loads.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Spinner } from '@tempoxyz/ds'
+
+export function Demo() {
+  return <Spinner aria-label="Loading transactions" />
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Spinner/Basic.tsx)
+
+### Elevated
+
+Set `elevated` to place the spinner on a 44px raised tile with a shadow.
+
+```tsx
+import { Spinner } from '@tempoxyz/ds'
+
+export function Demo() {
+  return <Spinner aria-label="Loading quote" elevated />
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Spinner/Elevated.tsx)
+
+### Size
+
+Set `size="40"` for a 40px ring with a thicker stroke, such as a spinner that fills an empty panel.
+
+```tsx
+/** Renders the 16px and 40px spinner rings side by side. @module */
+import { Spinner } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div style={{ alignItems: 'center', display: 'flex', gap: 24 }}>
+      <Spinner aria-label="Loading balance" />
+      <Spinner aria-label="Loading activity" size="40" />
+    </div>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Spinner/Size.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Spinner } from '@tempoxyz/ds'
+
+<Spinner />
+```
+
+## Guidelines
+
+### When to Use
+
+* Mark a region busy for a short, unknown time, such as a table that refreshes after a filter change.
+* Mark a small area that fetches data, such as a quote card or an address lookup.
+* Hold the place of a result with no predictable shape, such as a quote that returns a price or an error.
+
+### When Not to Use
+
+* Use `loading` on a [Button](/docs/components/button) while its action runs, not a spinner beside it.
+* Use [Skeleton](/docs/components/skeleton) for content with a known shape, such as activity rows or metric tiles.
+* Use [Progress](/docs/components/progress) for measurable work, or any wait over about 10 seconds.
+* Use [LoadingDots](/docs/components/loading-dots) for a short wait inside a line of text.
+
+### Match the Indicator to the Wait
+
+* **Under About 300 ms (nothing):** Show nothing. Render the result when it arrives.
+* **About 300 ms to 10 Seconds (Spinner):** Mark the busy region or control.
+* **Over About 10 Seconds (Progress):** Show a value for measurable work.
+
+Once a spinner appears, keep it for at least about 500 ms so it doesn't flash. For whole pages, see [Loading](/docs/patterns/loading).
+
+### Use One Spinner per Region
+
+**Do:** Center one spinner where the content will appear, and keep loaded content visible.
+
+```tsx
+/**
+ * Do example for "Use One Spinner per Region" on the Spinner page.
+ * Center one spinner where the content will appear, and keep loaded content visible.
+ * @module
+ */
+import { Spinner, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <Surface size="small" {...styles.card()}>
+        <div {...styles.label()}>Balance</div>
+        <div {...styles.value()}>1,250.00 USDC</div>
+      </Surface>
+      <Surface size="small" {...styles.region()}>
+        <Spinner aria-label="Loading activity" />
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const card = style({ display: 'flex', flexDirection: 'column', gap: '4' })
+
+  export const label = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const page = style({
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '12',
+    width: '100% !custom',
+  })
+
+  export const region = style({
+    alignItems: 'center',
+    display: 'flex',
+    height: '6rem !custom',
+    justifyContent: 'center',
+  })
+
+  export const value = style({ color: 'content.primary', typography: 'heading.h2' })
+}
+```
+
+**Don't:** Cover the whole page, which blocks content that already loaded.
+
+```tsx
+/**
+ * Don't example for "Use One Spinner per Region" on the Spinner page.
+ * Don't cover the whole page, which blocks content that already loaded.
+ * @module
+ */
+import { Spinner, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="small" {...styles.page()}>
+      <Spinner aria-label="Loading" />
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const page = style({
+    alignItems: 'center',
+    boxSizing: 'border-box',
+    display: 'flex',
+    height: '10rem !custom',
+    justifyContent: 'center',
+    width: '100% !custom',
+  })
+}
+```
+
+### Place It Beside a Status Line
+
+Show the spinner inline beside a short status line, such as Approving. For a pending action, use `loading` on a [Button](/docs/components/button).
+
+## Accessibility
+
+A spinner renders an indeterminate `progressbar` named "Loading". It is not a live region, so it is read only when the reader reaches it.
+
+### Semantics
+
+* **Root (progressbar):** Named "Loading", with no value, so it reads as indeterminate.
+* **Custom Name (aria-label):** Replaces the default name.
+* **Ring (aria-hidden):** A hidden SVG that stops rotating under reduced motion.
+* **Color (3:1):** Uses the text color. Keep 3:1 contrast against the background.
+
+### Your Responsibilities
+
+* **Say What Is Loading (aria-label):** Name what loads, such as "Loading transactions". Several spinners named "Loading" are indistinguishable.
+* **Announce the Result (SC 4.1.3):** A spinner isn't announced. Announce the result or an error in a status message or a [Toast](/docs/components/toast).
+* **Mark the Region Busy (aria-busy):** Set `aria-busy` on the loading region, so assistive technology waits for its content.
+
+## Related
+
+[Skeleton](/docs/components/skeleton)
+
+Use for content with a known shape.
+
+[Progress](/docs/components/progress)
+
+Use for measurable work.
+
+[LoadingDots](/docs/components/loading-dots)
+
+Use for a wait inside a line of text.
+
+[Button](/docs/components/button)
+
+Use for an action's loading state.
+
+[Loading](/docs/patterns/loading)
+
+Covers choosing a loading indicator.