@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/stack.md

@@ -0,0 +1,299 @@
+# Stack
+
+Lays out children in a vertical column.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Stack.tsx)
+
+## Overview
+
+Stack applies a spacing token `gap` between its children and stretches them to its width by default.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Stack } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Stack gap="12">
+      <span>Card content</span>
+      <span>Second line</span>
+    </Stack>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Stack/Basic.tsx)
+
+### Gap
+
+Set `gap` to a spacing token. It defaults to `16`.
+
+```tsx
+import { Inline, Stack, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Inline align="start" gap="32" wrap>
+      {(['4', '12', '24'] as const).map((gap) => (
+        <Stack gap={gap} key={gap}>
+          {[1, 2, 3].map((n) => (
+            <span key={n} {...styles.chip()}>
+              gap {gap}
+            </span>
+          ))}
+        </Stack>
+      ))}
+    </Inline>
+  )
+}
+
+namespace styles {
+  export const chip = style({
+    backgroundColor: 'container.regular',
+    borderRadius: 'full',
+    cornerShape: 'round',
+    paddingBlock: '4',
+    paddingInline: '12',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Stack/Gap.tsx)
+
+### Align
+
+Set `align` to `start`, `center`, `end`, or `stretch` (default).
+
+```tsx
+import { Inline, Stack, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Inline align="start" gap="32" wrap>
+      {(['start', 'center', 'end', 'stretch'] as const).map((align) => (
+        <Stack align={align} gap="8" key={align} {...styles.column()}>
+          <span {...styles.chip()}>{align}</span>
+          <span {...styles.chip()}>Second line</span>
+        </Stack>
+      ))}
+    </Inline>
+  )
+}
+
+namespace styles {
+  export const chip = style({
+    backgroundColor: 'container.regular',
+    borderRadius: 'full',
+    cornerShape: 'round',
+    paddingBlock: '4',
+    paddingInline: '12',
+  })
+
+  export const column = style({ width: '10rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Stack/Align.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Stack } from '@tempoxyz/ds'
+
+<Stack />
+```
+
+## Guidelines
+
+### When to Use
+
+* Space siblings vertically, such as form fields, settings sections, or cards in a column.
+* Place a label above its value, such as Recipient over a 0x address.
+
+### When Not to Use
+
+* Use [Inline](/docs/components/inline) for a horizontal row.
+* Use [Grid](/docs/components/grid) for collections in columns.
+* Use [ListGroup](/docs/components/list-group) for a divided list of settings or details.
+
+### Use Gap Instead of Margins
+
+Space siblings with `gap`, not child margins. See [Layout](/docs/foundations/layout).
+
+**Do:** Set one `gap` on the Stack.
+
+```tsx
+/** Do example for "Use Gap Instead of Margins" on the Stack page: set one `gap` on the Stack. @module */
+import { Stack, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Stack gap="12" {...styles.canvas()}>
+      <Surface size="small">Balance</Surface>
+      <Surface size="small">Activity</Surface>
+      <Surface size="small">Access keys</Surface>
+    </Stack>
+  )
+}
+
+namespace styles {
+  export const canvas = style({
+    backgroundColor: 'background.primary',
+    borderRadius: 'sm',
+    boxSizing: 'border-box',
+    padding: '12',
+    width: '100% !custom',
+  })
+}
+```
+
+**Don't:** Set margins on each child, which drift apart and leave space after the last one.
+
+```tsx
+/**
+ * Don't example for "Use Gap Instead of Margins" on the Stack page.
+ * Don't set margins on each child, which drift apart and leave space after the last one.
+ * @module
+ */
+import { style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.canvas()}>
+      <Surface size="small" {...styles.first()}>
+        Balance
+      </Surface>
+      <Surface size="small" {...styles.second()}>
+        Activity
+      </Surface>
+      <Surface size="small" {...styles.third()}>
+        Access keys
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const canvas = style({
+    backgroundColor: 'background.primary',
+    borderRadius: 'sm',
+    boxSizing: 'border-box',
+    padding: '12',
+    width: '100% !custom',
+  })
+
+  export const first = style({ marginBlockEnd: '4' })
+
+  export const second = style({ marginBlockEnd: '24' })
+
+  export const third = style({ marginBlockEnd: '16' })
+}
+```
+
+### Choose Gap by Relationship
+
+Nest stacks so the space inside a group is smaller than the space between groups, such as `4` between a label and its value and `24` between pairs.
+
+**Do:** Nest stacks so each label sits closer to its own value.
+
+```tsx
+/**
+ * Do example for "Choose Gap by Relationship" on the Stack page.
+ * Nest stacks so each label sits closer to its own value.
+ * @module
+ */
+import { Stack, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Stack gap="24" {...styles.column()}>
+      <Stack gap="4">
+        <span {...styles.label()}>Recipient</span>
+        <span {...styles.value()}>0x71C7…976F</span>
+      </Stack>
+      <Stack gap="4">
+        <span {...styles.label()}>Amount</span>
+        <span {...styles.value()}>250.00 USDC</span>
+      </Stack>
+    </Stack>
+  )
+}
+
+namespace styles {
+  export const column = style({ width: '100% !custom' })
+
+  export const label = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const value = style({ color: 'content.primary', typography: 'body.b1Strong' })
+}
+```
+
+**Don't:** Space every item the same, which hides the groups.
+
+```tsx
+/**
+ * Don't example for "Choose Gap by Relationship" on the Stack page.
+ * Don't space every item the same, which hides the groups.
+ * @module
+ */
+import { Stack, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Stack gap="16" {...styles.column()}>
+      <span {...styles.label()}>Recipient</span>
+      <span {...styles.value()}>0x71C7…976F</span>
+      <span {...styles.label()}>Amount</span>
+      <span {...styles.value()}>250.00 USDC</span>
+    </Stack>
+  )
+}
+
+namespace styles {
+  export const column = style({ width: '100% !custom' })
+
+  export const label = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const value = style({ color: 'content.primary', typography: 'body.b1Strong' })
+}
+```
+
+## Accessibility
+
+Stack adds no role, name, or keyboard behavior.
+
+### Semantics
+
+* **Element (div):** Carries no role by default.
+* **Render (render):** Swaps in a semantic element, such as a nav for links, or a list so screen readers announce the count.
+
+### Your Responsibilities
+
+* **Match DOM and Visual Order (SC 1.3.2, SC 2.4.3):** Don't reorder children with CSS. [Reading](https://www.w3.org/WAI/WCAG22/Understanding/meaningful-sequence.html) and [focus](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) order follow the DOM.
+
+## Related
+
+[Inline](/docs/components/inline)
+
+Use for horizontal rows.
+
+[Grid](/docs/components/grid)
+
+Use for columns of items.
+
+[Separator](/docs/components/separator)
+
+Use for a rule between groups.
+
+[Layout](/docs/foundations/layout)
+
+Covers the spacing scale.

package/dist/docs/components/status-chip.md

@@ -0,0 +1,226 @@
+# StatusChip
+
+Names the status of a payment, an authorization, or a network.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/StatusChip.tsx)
+
+Figma: [Elements/Network Chip](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-3090), [Messaging/Status Chip](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-3776)
+
+## Overview
+
+A status chip renders a short label in a tinted pill, led by a dot in the color of its `intent`. A loading chip replaces the dot with a spinner, for a status that is still in progress. A network chip names a network at a fixed minimum width.
+
+## Examples
+
+### Basic
+
+```tsx
+import { StatusChip } from '@tempoxyz/ds'
+
+export function Demo() {
+  return <StatusChip intent="warning">Pending</StatusChip>
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/StatusChip/Basic.tsx)
+
+### Intent
+
+Set `intent` to `neutral` (default), `positive`, `warning`, or `negative`.
+
+```tsx
+import { StatusChip, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <StatusChip intent="positive">Authorized</StatusChip>
+      <StatusChip intent="warning">Needs approval</StatusChip>
+      <StatusChip intent="negative">Failed</StatusChip>
+      <StatusChip intent="neutral">Expired</StatusChip>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/StatusChip/Intent.tsx)
+
+### Size
+
+Set `size` to `medium` (28px, default) or `small` (24px).
+
+```tsx
+import { StatusChip, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <StatusChip intent="positive">Live</StatusChip>
+      <StatusChip intent="positive" size="small">
+        Live
+      </StatusChip>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '8' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/StatusChip/Size.tsx)
+
+### Loading
+
+Set `loading` for a status in progress, such as Processing.
+
+```tsx
+import { StatusChip } from '@tempoxyz/ds'
+
+export function Demo() {
+  return <StatusChip loading>Processing</StatusChip>
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/StatusChip/Loading.tsx)
+
+### Network
+
+Set `network` for a chip that names a network, such as Mainnet or Testnet. It keeps an 80px minimum width, with the dot closer to the label.
+
+```tsx
+import { StatusChip, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <StatusChip intent="positive" network>
+        Mainnet
+      </StatusChip>
+      <StatusChip intent="warning" network>
+        Testnet
+      </StatusChip>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '8' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/StatusChip/Network.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { StatusChip } from '@tempoxyz/ds'
+
+<StatusChip />
+```
+
+## Guidelines
+
+### When to Use
+
+* Show where a payment, a deposit, or an authorization stands, such as Pending or Authorized.
+* Show whether a network is live or a testnet, with `network`.
+
+### When Not to Use
+
+* Use [Badge](/docs/components/badge) for a category or an attribute that is not a status.
+* Use [Alert](/docs/components/alert) to explain a status and what to do next.
+* Use [AssetChip](/docs/components/asset-chip) for the assets a row supports.
+
+### Pick the Intent From the Outcome
+
+* **Positive:** The action is done, or the item is live.
+* **Warning:** The item waits on a person or a later step.
+* **Negative:** The action failed and needs attention.
+* **Neutral:** The item ended without an outcome.
+
+### Name Only Statuses
+
+**Do:** Place the chip at the end of the row whose status it names.
+
+```tsx
+import { ListGroup, StatusChip } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <ListGroup variant="boxed">
+      <ListGroup.Row>
+        <ListGroup.Info>
+          <ListGroup.Title>Claude</ListGroup.Title>
+          <ListGroup.Description>$10.00 a month</ListGroup.Description>
+        </ListGroup.Info>
+        <StatusChip intent="positive" size="small">
+          Authorized
+        </StatusChip>
+      </ListGroup.Row>
+    </ListGroup>
+  )
+}
+```
+
+**Don't:** Use a status chip for a category. Use a [Badge](/docs/components/badge).
+
+```tsx
+import { ListGroup, StatusChip } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <ListGroup variant="boxed">
+      <ListGroup.Row>
+        <ListGroup.Info>
+          <ListGroup.Title>Claude</ListGroup.Title>
+          <ListGroup.Description>$10.00 a month</ListGroup.Description>
+        </ListGroup.Info>
+        <StatusChip intent="positive" size="small">
+          Agent
+        </StatusChip>
+      </ListGroup.Row>
+    </ListGroup>
+  )
+}
+```
+
+## Content
+
+### Write the Status
+
+Write one or two words that name the state, such as Pending, Live, or Needs approval. Use sentence case, and leave out words such as Status.
+
+## Accessibility
+
+A status chip renders a `<span>` that screen readers read as text in place. The dot and the spinner are hidden, so the label alone carries the status.
+
+### Semantics
+
+* **Root (span):** Screen readers read the label in place, without the dot.
+* **Loading (aria-hidden):** The spinner is hidden, so screen readers read the label once.
+
+### Your Responsibilities
+
+* **Name the Status in Text (SC 1.4.1):** The intent color is decorative, so the label must name the status.
+* **Announce a Change (aria-live):** Wrap a chip that changes in place in a polite live region.
+
+## Related
+
+[Badge](/docs/components/badge)
+
+Use for categories and attributes.
+
+[Alert](/docs/components/alert)
+
+Use for a status that needs an explanation.
+
+[StatusRow](/docs/components/status-row)
+
+Use for a status that follows a payment in a row.

package/dist/docs/components/status-indicator.md

@@ -0,0 +1,119 @@
+# StatusIndicator
+
+Names the status of a system or a service with a dot and a label.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/StatusIndicator.tsx)
+
+Figma: [Status indicator](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=3065-474)
+
+## Overview
+
+A status indicator renders a short secondary label, led by an 8px dot in the color of its `intent`. It has no fill, so it sits quietly beside a title or in a list of services.
+
+## Examples
+
+### Basic
+
+```tsx
+import { StatusIndicator } from '@tempoxyz/ds'
+
+export function Demo() {
+  return <StatusIndicator intent="positive">Operational</StatusIndicator>
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/StatusIndicator/Basic.tsx)
+
+### Intent
+
+Set `intent` to `neutral` (default), `positive`, `warning`, or `negative`. Each colors the dot.
+
+```tsx
+import { StatusIndicator, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <StatusIndicator intent="neutral">Idle</StatusIndicator>
+      <StatusIndicator intent="positive">Operational</StatusIndicator>
+      <StatusIndicator intent="warning">Degraded</StatusIndicator>
+      <StatusIndicator intent="negative">Down</StatusIndicator>
+    </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/StatusIndicator/Intent.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { StatusIndicator } from '@tempoxyz/ds'
+
+<StatusIndicator />
+```
+
+## Guidelines
+
+### When to Use
+
+* Show the live status of a system, a service, or a connection, such as Operational or Degraded.
+
+### When Not to Use
+
+* Use a [StatusChip](/docs/components/status-chip) for the status of a payment or an authorization.
+* Use a [Badge](/docs/components/badge) for a category or an attribute.
+* Use an [Alert](/docs/components/alert) for a status that needs an explanation.
+
+### Match the Intent to the Status
+
+* **Healthy (positive):** A service that works as expected, such as an online validator.
+* **Degraded (warning):** A service that works with delays or reduced capacity right now.
+* **Down (negative):** A service that fails or can't be reached, such as an offline node.
+* **Idle (neutral):** A service that is paused, idle, or in a state that isn't known yet.
+
+### Name the Status in the Label
+
+**Do:** Name the status in a word, so it doesn't depend on the dot color.
+
+```tsx
+<StatusIndicator intent="negative">Down</StatusIndicator>
+```
+
+**Don't:** Label the dot with the name of the service alone.
+
+```tsx
+<StatusIndicator intent="negative">API</StatusIndicator>
+```
+
+## Content
+
+* Keep the label to one or two words in sentence case, such as Operational or Partial outage.
+* Use one word for one status across a product.
+
+## Accessibility
+
+A status indicator renders a `<span>` with no role. The dot is hidden, so screen readers read the label alone.
+
+* **Dot (aria-hidden):** Hides the dot from screen readers, so the label carries the status.
+* **Live Updates (role):** If the status changes in place, set `role="status"` so the change is announced.
+
+## Related
+
+[StatusChip](/docs/components/status-chip)
+
+Use for the status of a payment or an authorization.
+
+[Badge](/docs/components/badge)
+
+Use for categories and attributes.
+
+[Alert](/docs/components/alert)
+
+Use for a status that needs an explanation.