@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/choice-group.md

@@ -0,0 +1,516 @@
+# ChoiceGroup
+
+A segmented control for a few mutually exclusive options.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/ChoiceGroup.tsx)
+
+Figma: [Base - Segment Item](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=3075-548) (`ChoiceGroup.Item`), [Controls/Segmented Control Item Small](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-5484) (`ChoiceGroup.Item`), [Segmented Control](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=3075-535) (`ChoiceGroup.Root`)
+
+## Overview
+
+A single-select control with radio semantics. One option is always selected.
+
+## Examples
+
+### Basic
+
+```tsx
+import { ChoiceGroup } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <ChoiceGroup.Root aria-label="Amount" defaultValue="50">
+      <ChoiceGroup.Item value="20">$20</ChoiceGroup.Item>
+      <ChoiceGroup.Item value="50">$50</ChoiceGroup.Item>
+      <ChoiceGroup.Item value="100">$100</ChoiceGroup.Item>
+    </ChoiceGroup.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/ChoiceGroup/Basic.tsx)
+
+### Size
+
+Set `size` to `small`, `medium` (default), or `large`.
+
+```tsx
+import { ChoiceGroup, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      {(['small', 'medium', 'large'] as const).map((size) => (
+        <ChoiceGroup.Root aria-label={`Amount ${size}`} defaultValue="50" key={size} size={size}>
+          <ChoiceGroup.Item value="20">$20</ChoiceGroup.Item>
+          <ChoiceGroup.Item value="50">$50</ChoiceGroup.Item>
+          <ChoiceGroup.Item value="100">$100</ChoiceGroup.Item>
+        </ChoiceGroup.Root>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({
+    alignItems: 'flex-start',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '16',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/ChoiceGroup/Size.tsx)
+
+### Variant
+
+Set `variant` to `default` or `chips`. `chips` renders a horizontally scrolling row of chips, with an optional `ChoiceGroup.ItemIcon`.
+
+```tsx
+import { ChoiceGroup, style } from '@tempoxyz/ds'
+import { Coins, Ethereum, Globe } from '@tempoxyz/ds/icons'
+
+const networks = [
+  { icon: <Coins />, label: 'Tempo' },
+  { icon: <Ethereum />, label: 'Ethereum' },
+  { icon: <Globe />, label: 'Base' },
+  { icon: <Globe />, label: 'Arbitrum' },
+  { icon: <Globe />, label: 'Optimism' },
+]
+
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      {(['small', 'medium', 'large'] as const).map((size) => (
+        <ChoiceGroup.Root
+          aria-label={`Network ${size}`}
+          defaultValue="Tempo"
+          key={size}
+          size={size}
+          variant="chips"
+        >
+          {networks.map((network) => (
+            <ChoiceGroup.Item key={network.label} value={network.label}>
+              <ChoiceGroup.ItemIcon>{network.icon}</ChoiceGroup.ItemIcon>
+              {network.label}
+            </ChoiceGroup.Item>
+          ))}
+        </ChoiceGroup.Root>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({
+    alignItems: 'flex-start',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '16',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/ChoiceGroup/Variant.tsx)
+
+### Field
+
+Wrap the group in a `Field.Root`. The `Field.Label` names the group, and a `Field.Description` adds a hint below it.
+
+```tsx
+import { ChoiceGroup, Field, style } from '@tempoxyz/ds'
+import { Coins, Ethereum, Globe } from '@tempoxyz/ds/icons'
+
+const networks = [
+  { icon: <Coins />, label: 'Tempo' },
+  { icon: <Ethereum />, label: 'Ethereum' },
+  { icon: <Globe />, label: 'Base' },
+]
+
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Field.Root>
+        <Field.Label>Amount</Field.Label>
+        <ChoiceGroup.Root defaultValue="50">
+          <ChoiceGroup.Item value="20">$20</ChoiceGroup.Item>
+          <ChoiceGroup.Item value="50">$50</ChoiceGroup.Item>
+          <ChoiceGroup.Item value="100">$100</ChoiceGroup.Item>
+        </ChoiceGroup.Root>
+        <Field.Description>Charged to your saved card.</Field.Description>
+      </Field.Root>
+      <Field.Root>
+        <Field.Label>Network</Field.Label>
+        <ChoiceGroup.Root defaultValue="Tempo" variant="chips">
+          {networks.map((network) => (
+            <ChoiceGroup.Item key={network.label} value={network.label}>
+              <ChoiceGroup.ItemIcon>{network.icon}</ChoiceGroup.ItemIcon>
+              {network.label}
+            </ChoiceGroup.Item>
+          ))}
+        </ChoiceGroup.Root>
+      </Field.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '24',
+    maxWidth: '320px !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/ChoiceGroup/Field.tsx)
+
+### Disabled
+
+Set `disabled` on a `ChoiceGroup.Item` to make one option unavailable.
+
+```tsx
+import { ChoiceGroup } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <ChoiceGroup.Root aria-label="Amount" defaultValue="50">
+      <ChoiceGroup.Item value="20">$20</ChoiceGroup.Item>
+      <ChoiceGroup.Item value="50">$50</ChoiceGroup.Item>
+      <ChoiceGroup.Item value="100">$100</ChoiceGroup.Item>
+      <ChoiceGroup.Item disabled value="other">
+        Other
+      </ChoiceGroup.Item>
+    </ChoiceGroup.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/ChoiceGroup/Disabled.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { ChoiceGroup } from '@tempoxyz/ds'
+
+<ChoiceGroup.Root>
+  <ChoiceGroup.Item>
+    <ChoiceGroup.ItemIcon />
+  </ChoiceGroup.Item>
+</ChoiceGroup.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Switch between two to four short options that change a view, such as the 1H, 24H, 7D, and 30D range on a TPS chart.
+* Pick a preset value, such as $20, $50, or $100 on Add funds.
+* Filter by one option from a longer set with `variant="chips"`, such as the network for a deposit.
+
+### When Not to Use
+
+* If options need longer labels or are submitted with a form, use [RadioGroup](/docs/components/radio-group).
+* Use [Select](/docs/components/select) for many options, or when space is limited.
+* Use [Tabs](/docs/components/tabs) to switch between panels, such as Overview, Activity, and Settings.
+* If each option needs an icon and a description, use [Choicebox](/docs/components/choicebox).
+* Use [Switch](/docs/components/switch) for an on or off setting, not On and Off segments.
+* Use [Button](/docs/components/button) for actions such as Send, Receive, and Swap.
+
+### Keep Options Few and Short
+
+Use two to four options of one or two words each, at similar lengths. Items never wrap.
+
+**Do:** Use short, parallel labels that fit side by side.
+
+```tsx
+/**
+ * Do example for "Keep Options Few and Short" on the ChoiceGroup page.
+ * Use short, parallel labels that fit side by side.
+ * @module
+ */
+import { ChoiceGroup } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ChoiceGroup.Root aria-label="Time range" defaultValue="24h">
+      <ChoiceGroup.Item value="1h">1H</ChoiceGroup.Item>
+      <ChoiceGroup.Item value="24h">24H</ChoiceGroup.Item>
+      <ChoiceGroup.Item value="7d">7D</ChoiceGroup.Item>
+      <ChoiceGroup.Item value="30d">30D</ChoiceGroup.Item>
+    </ChoiceGroup.Root>
+  )
+}
+```
+
+**Don't:** Use phrases that overflow the control.
+
+```tsx
+/**
+ * Don't example for "Keep Options Few and Short" on the ChoiceGroup page.
+ * Don't use phrases that overflow the control.
+ * @module
+ */
+import { ChoiceGroup } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ChoiceGroup.Root aria-label="Time range" defaultValue="24h">
+      <ChoiceGroup.Item value="1h">Last hour</ChoiceGroup.Item>
+      <ChoiceGroup.Item value="24h">Last 24 hours</ChoiceGroup.Item>
+      <ChoiceGroup.Item value="7d">Last 7 days</ChoiceGroup.Item>
+      <ChoiceGroup.Item value="30d">Last 30 days</ChoiceGroup.Item>
+    </ChoiceGroup.Root>
+  )
+}
+```
+
+### Always Keep One Option Selected
+
+The selection can't be cleared.
+
+**Do:** On first render, set `defaultValue`, or `value` with `onValueChange`, to the current mode.
+
+```tsx
+/**
+ * Do example for "Always Keep One Option Selected" on the ChoiceGroup page.
+ * On first render, set `defaultValue`, or `value` with `onValueChange`, to the current mode.
+ * @module
+ */
+import { ChoiceGroup } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ChoiceGroup.Root aria-label="Amount" defaultValue="50">
+      <ChoiceGroup.Item value="20">$20</ChoiceGroup.Item>
+      <ChoiceGroup.Item value="50">$50</ChoiceGroup.Item>
+      <ChoiceGroup.Item value="100">$100</ChoiceGroup.Item>
+    </ChoiceGroup.Root>
+  )
+}
+```
+
+**Don't:** Render the group with no option selected.
+
+```tsx
+/**
+ * Don't example for "Always Keep One Option Selected" on the ChoiceGroup page.
+ * Don't render the group with no option selected.
+ * @module
+ */
+import { ChoiceGroup } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ChoiceGroup.Root aria-label="Amount">
+      <ChoiceGroup.Item value="20">$20</ChoiceGroup.Item>
+      <ChoiceGroup.Item value="50">$50</ChoiceGroup.Item>
+      <ChoiceGroup.Item value="100">$100</ChoiceGroup.Item>
+    </ChoiceGroup.Root>
+  )
+}
+```
+
+### Apply the Choice Immediately
+
+If the choice waits for a form submit, use [RadioGroup](/docs/components/radio-group).
+
+**Do:** Update the view when the selection changes, such as redrawing the chart for 7D.
+
+```tsx
+/**
+ * Do example for "Apply the Choice Immediately" on the ChoiceGroup page.
+ * Update the view when the selection changes, such as redrawing the chart for 7D.
+ * @module
+ */
+import { ChoiceGroup } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ChoiceGroup.Root aria-label="Time range" defaultValue="24h" size="small">
+      <ChoiceGroup.Item value="1h">1H</ChoiceGroup.Item>
+      <ChoiceGroup.Item value="24h">24H</ChoiceGroup.Item>
+      <ChoiceGroup.Item value="7d">7D</ChoiceGroup.Item>
+      <ChoiceGroup.Item value="30d">30D</ChoiceGroup.Item>
+    </ChoiceGroup.Root>
+  )
+}
+```
+
+**Don't:** Add an Apply button.
+
+```tsx
+/** Don't example for "Apply the Choice Immediately" on the ChoiceGroup page. Don't add an Apply button. @module */
+import { Button, ChoiceGroup, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <ChoiceGroup.Root aria-label="Time range" defaultValue="24h" size="small">
+        <ChoiceGroup.Item value="1h">1H</ChoiceGroup.Item>
+        <ChoiceGroup.Item value="24h">24H</ChoiceGroup.Item>
+        <ChoiceGroup.Item value="7d">7D</ChoiceGroup.Item>
+        <ChoiceGroup.Item value="30d">30D</ChoiceGroup.Item>
+      </ChoiceGroup.Root>
+      <Button size="small" variant="secondary">
+        Apply
+      </Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '8' })
+}
+```
+
+### Choose a Variant by Option Count
+
+* **Few Short Options (default):** Two to four options in one track, marked by a sliding pill.
+* **Longer Filter Sets (chips):** A scrolling row of chips for options that outgrow the width, such as networks for a deposit.
+
+### Match the Height of Nearby Controls
+
+`small`, `medium`, and `large` tracks are 32, 48, and 56px tall. A `medium` track fills its row and gives each item an equal width, as tall as [TextInput](/docs/components/text-input).
+
+**Do:** Use `small` in a dashboard toolbar beside a small [Select](/docs/components/select).
+
+```tsx
+/**
+ * Do example for "Match the Height of Nearby Controls" on the ChoiceGroup page.
+ * Use `small` in a dashboard toolbar beside a small Select.
+ * @module
+ */
+import { ChoiceGroup, Select, style } from '@tempoxyz/ds'
+
+const items = { usdc: 'USDC', usdt: 'USDT' }
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.toolbar()}>
+      <ChoiceGroup.Root aria-label="Time range" defaultValue="24h" size="small">
+        <ChoiceGroup.Item value="1h">1H</ChoiceGroup.Item>
+        <ChoiceGroup.Item value="24h">24H</ChoiceGroup.Item>
+        <ChoiceGroup.Item value="7d">7D</ChoiceGroup.Item>
+      </ChoiceGroup.Root>
+      <Select.Root aria-label="Asset" defaultValue="usdc" items={items}>
+        <Select.Trigger {...styles.select()}>
+          <Select.Value />
+          <Select.Icon />
+        </Select.Trigger>
+      </Select.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const toolbar = style({ alignItems: 'center', display: 'flex', gap: '8' })
+
+  export const select = style({ width: '7rem !custom' })
+}
+```
+
+**Don't:** Mix sizes in one toolbar.
+
+```tsx
+/**
+ * Don't example for "Match the Height of Nearby Controls" on the ChoiceGroup page.
+ * Don't mix sizes in one toolbar.
+ * @module
+ */
+import { ChoiceGroup, Select, style } from '@tempoxyz/ds'
+
+const items = { usdc: 'USDC', usdt: 'USDT' }
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.toolbar()}>
+      <ChoiceGroup.Root aria-label="Time range" defaultValue="24h" size="large">
+        <ChoiceGroup.Item value="1h">1H</ChoiceGroup.Item>
+        <ChoiceGroup.Item value="24h">24H</ChoiceGroup.Item>
+        <ChoiceGroup.Item value="7d">7D</ChoiceGroup.Item>
+      </ChoiceGroup.Root>
+      <Select.Root aria-label="Asset" defaultValue="usdc" items={items}>
+        <Select.Trigger {...styles.select()}>
+          <Select.Value />
+          <Select.Icon />
+        </Select.Trigger>
+      </Select.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const toolbar = style({ alignItems: 'center', display: 'flex', gap: '8' })
+
+  export const select = style({ width: '7rem !custom' })
+}
+```
+
+## Content
+
+* Write labels as compact units, such as 1H and 7D, or as words. Use one style across all options, and don't mix 1 hour with 7D, or Ethereum with ETH.
+* Use numerals for numbers and amounts, such as $20 and 30D.
+
+## Accessibility
+
+Follows the [WAI-ARIA radio group pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/).
+
+### Semantics
+
+* **ChoiceGroup.Root (radiogroup):** Groups the items as one set of choices.
+* **ChoiceGroup.Item (radio):** Named by its text. A hidden native radio beside it submits the value.
+* **Decoration (aria-hidden):** The sliding pill and item icons are hidden from screen readers.
+* **Selected (aria-checked):** The selected item sits on a pill or tinted chip, and its text darkens.
+* **Disabled Item (disabled):** Makes the option unavailable and dims it to 32% opacity.
+* **Target Size (28 to 48px):** Small items sit close to the WCAG 2.2 minimum. Avoid them for primary controls.
+
+### Keyboard
+
+* **Move into the Group (Tab):** Moves focus onto the checked item. The group is one tab stop.
+* **Move out of the Group (Shift+Tab):** Moves focus out of the group.
+* **Select the Next Item (Right Arrow or Down Arrow):** Moves focus to the next item and selects it, wrapping at the end.
+* **Select the Previous Item (Left Arrow or Up Arrow):** Moves focus to the previous item and selects it, wrapping at the start.
+
+### Motion
+
+Under `prefers-reduced-motion: reduce`, the pill moves without sliding and items don't scale when pressed.
+
+### Your Responsibilities
+
+* **Name the Group (aria-labelledby):** Use a `Field.Label` in a `Field.Root`, `aria-label`, or a visible question such as "Amount".
+* **Give Every Item Text:** Item icons are hidden, so an icon-only item has no accessible name.
+
+## Related
+
+[RadioGroup](/docs/components/radio-group)
+
+Use for one choice in a form.
+
+[Tabs](/docs/components/tabs)
+
+Use for switching between panels.
+
+[Select](/docs/components/select)
+
+Use for longer lists.
+
+[Choicebox](/docs/components/choicebox)
+
+Use for options with descriptions.
+
+[Dashboards](/docs/patterns/dashboards)
+
+Covers filters above charts.