@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/choicebox.md

@@ -0,0 +1,641 @@
+# Choicebox
+
+A selectable tile with an optional icon, title, and description.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Choicebox.tsx)
+
+## Overview
+
+A tile form of a radio, checkbox, or button. Pressing anywhere on the tile operates its control.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Choicebox } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Choicebox.RadioGroup aria-label="Settlement" defaultValue="instant">
+      <Choicebox.Radio value="standard">
+        <Choicebox.Title>Standard</Choicebox.Title>
+        <Choicebox.Description>Settles in one business day</Choicebox.Description>
+      </Choicebox.Radio>
+      <Choicebox.Radio value="instant">
+        <Choicebox.Title>Instant</Choicebox.Title>
+        <Choicebox.Description>Settles in seconds for a small fee</Choicebox.Description>
+      </Choicebox.Radio>
+    </Choicebox.RadioGroup>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Choicebox/Basic.tsx)
+
+### Size
+
+Set `size` on the group to `small`, `medium` (default), or `large`.
+
+```tsx
+import { Choicebox, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {(['small', 'large'] as const).map((size) => (
+        <Choicebox.RadioGroup
+          aria-label={`Settlement ${size}`}
+          defaultValue="instant"
+          key={size}
+          size={size}
+        >
+          <Choicebox.Radio value="standard">
+            <Choicebox.Title>Standard ({size})</Choicebox.Title>
+            <Choicebox.Description>Settles in one business day</Choicebox.Description>
+          </Choicebox.Radio>
+          <Choicebox.Radio value="instant">
+            <Choicebox.Title>Instant ({size})</Choicebox.Title>
+            <Choicebox.Description>Settles in seconds for a small fee</Choicebox.Description>
+          </Choicebox.Radio>
+        </Choicebox.RadioGroup>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({
+    alignItems: 'flex-start',
+    display: 'grid',
+    gap: '24',
+    gridTemplateColumns: 'repeat(auto-fit, minmax(280px, 360px)) !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Choicebox/Size.tsx)
+
+### Disabled
+
+Set `disabled` on a tile to make one option unavailable.
+
+```tsx
+import { Choicebox } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Choicebox.RadioGroup aria-label="Settlement" defaultValue="instant">
+      <Choicebox.Radio value="standard">
+        <Choicebox.Title>Standard</Choicebox.Title>
+        <Choicebox.Description>Settles in one business day</Choicebox.Description>
+      </Choicebox.Radio>
+      <Choicebox.Radio value="instant">
+        <Choicebox.Title>Instant</Choicebox.Title>
+        <Choicebox.Description>Settles in seconds for a small fee</Choicebox.Description>
+      </Choicebox.Radio>
+      <Choicebox.Radio disabled value="wire">
+        <Choicebox.Title>Wire</Choicebox.Title>
+        <Choicebox.Description>Unavailable in your region</Choicebox.Description>
+      </Choicebox.Radio>
+    </Choicebox.RadioGroup>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Choicebox/Disabled.tsx)
+
+### Icon
+
+Add a `Choicebox.Icon` before the title.
+
+```tsx
+import { Choicebox } from '@tempoxyz/ds'
+import { Bank, CreditCard } from '@tempoxyz/ds/icons'
+
+export function Demo() {
+  return (
+    <Choicebox.RadioGroup aria-label="Method" defaultValue="bank">
+      <Choicebox.Radio value="bank">
+        <Choicebox.Icon>
+          <Bank />
+        </Choicebox.Icon>
+        <Choicebox.Title>Bank transfer</Choicebox.Title>
+        <Choicebox.Description>One to two business days</Choicebox.Description>
+      </Choicebox.Radio>
+      <Choicebox.Radio value="card">
+        <Choicebox.Icon>
+          <CreditCard />
+        </Choicebox.Icon>
+        <Choicebox.Title>Card</Choicebox.Title>
+        <Choicebox.Description>Instant, 2.9% fee</Choicebox.Description>
+      </Choicebox.Radio>
+    </Choicebox.RadioGroup>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Choicebox/Icon.tsx)
+
+### ButtonGroup
+
+Use `Choicebox.ButtonGroup` and `Choicebox.Button` for tiles that run an action and hold no value.
+
+```tsx
+import { Choicebox } from '@tempoxyz/ds'
+import { Bank, Wallet } from '@tempoxyz/ds/icons'
+
+export function Demo() {
+  return (
+    <Choicebox.ButtonGroup aria-label="Add funds">
+      <Choicebox.Button onClick={() => alert('Bank transfer')}>
+        <Choicebox.Icon>
+          <Bank />
+        </Choicebox.Icon>
+        <Choicebox.Title>Bank transfer</Choicebox.Title>
+        <Choicebox.Description>Opens your deposit details</Choicebox.Description>
+      </Choicebox.Button>
+      <Choicebox.Button onClick={() => alert('Wallet')}>
+        <Choicebox.Icon>
+          <Wallet />
+        </Choicebox.Icon>
+        <Choicebox.Title>From a wallet</Choicebox.Title>
+      </Choicebox.Button>
+    </Choicebox.ButtonGroup>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Choicebox/ButtonGroup.tsx)
+
+### CheckboxGroup
+
+Use `Choicebox.CheckboxGroup` and `Choicebox.Checkbox` for tiles that allow several selections.
+
+```tsx
+import { Choicebox } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Choicebox.CheckboxGroup aria-label="Alerts" defaultValue={['email']}>
+      <Choicebox.Checkbox value="email">
+        <Choicebox.Title>Email</Choicebox.Title>
+        <Choicebox.Description>Receipts and weekly summaries</Choicebox.Description>
+      </Choicebox.Checkbox>
+      <Choicebox.Checkbox value="push">
+        <Choicebox.Title>Push</Choicebox.Title>
+        <Choicebox.Description>Transfers and security events</Choicebox.Description>
+      </Choicebox.Checkbox>
+    </Choicebox.CheckboxGroup>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Choicebox/CheckboxGroup.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Choicebox } from '@tempoxyz/ds'
+
+<Choicebox.RadioGroup>
+  <Choicebox.Radio>
+    <Choicebox.Icon />
+    <Choicebox.Title />
+    <Choicebox.Description />
+  </Choicebox.Radio>
+</Choicebox.RadioGroup>
+
+<Choicebox.CheckboxGroup>
+  <Choicebox.Checkbox>
+    <Choicebox.Icon />
+    <Choicebox.Title />
+    <Choicebox.Description />
+  </Choicebox.Checkbox>
+</Choicebox.CheckboxGroup>
+
+<Choicebox.ButtonGroup>
+  <Choicebox.Button>
+    <Choicebox.Icon />
+    <Choicebox.Title />
+    <Choicebox.Description />
+  </Choicebox.Button>
+</Choicebox.ButtonGroup>
+```
+
+## Guidelines
+
+### When to Use
+
+* Choose between a few options that each need a description, such as Standard or Instant settlement with time and fee.
+* Choose how to start a flow with `Choicebox.ButtonGroup`, such as Bank transfer or From a wallet.
+* Choose several described options with `Choicebox.CheckboxGroup`, such as alert channels.
+
+### When Not to Use
+
+* If a label alone tells the options apart, use [RadioGroup](/docs/components/radio-group).
+* Use [ChoiceGroup](/docs/components/choice-group) for a short mode switch, such as a chart's time range.
+* Use [Select](/docs/components/select) for more options than fit on screen.
+* Use [Button](/docs/components/button) for a single action, and [Menu](/docs/components/menu) for actions that need no description.
+
+### Pick the Group by What a Tile Does
+
+* **Radio Tiles (Choicebox.RadioGroup):** Hold one value, such as a settlement speed.
+* **Checkbox Tiles (Choicebox.CheckboxGroup):** Hold several values, such as alert channels.
+* **Button Tiles (Choicebox.ButtonGroup):** Run an action, such as opening the next step.
+
+### Keep Tile Text Short
+
+The whole tile's text becomes the accessible name, so long text slows every option for screen reader users.
+
+**Do:** Give each tile a title of one to three words and a one-line description.
+
+```tsx
+/**
+ * Do example for "Keep Tile Text Short" on the Choicebox page.
+ * Give each tile a title of one to three words and a one-line description.
+ * @module
+ */
+import { Choicebox, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Choicebox.RadioGroup aria-label="Settlement" defaultValue="standard" {...styles.group()}>
+      <Choicebox.Radio value="standard">
+        <Choicebox.Title>Standard</Choicebox.Title>
+        <Choicebox.Description>Settles in one business day</Choicebox.Description>
+      </Choicebox.Radio>
+      <Choicebox.Radio value="instant">
+        <Choicebox.Title>Instant</Choicebox.Title>
+        <Choicebox.Description>Settles in seconds for a 1% fee</Choicebox.Description>
+      </Choicebox.Radio>
+    </Choicebox.RadioGroup>
+  )
+}
+
+namespace styles {
+  export const group = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Repeat the question in each title or write paragraphs in the description.
+
+```tsx
+/**
+ * Don't example for "Keep Tile Text Short" on the Choicebox page.
+ * Don't repeat the question in each title or write paragraphs in the description.
+ * @module
+ */
+import { Choicebox, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Choicebox.RadioGroup aria-label="Settlement" defaultValue="standard" {...styles.group()}>
+      <Choicebox.Radio value="standard">
+        <Choicebox.Title>Standard settlement for this payment</Choicebox.Title>
+        <Choicebox.Description>
+          Your payment is processed with our standard settlement option, which usually takes about
+          one business day depending on your bank.
+        </Choicebox.Description>
+      </Choicebox.Radio>
+      <Choicebox.Radio value="instant">
+        <Choicebox.Title>Instant settlement for this payment</Choicebox.Title>
+        <Choicebox.Description>
+          Your payment settles in seconds. A fee applies, shown on the review screen.
+        </Choicebox.Description>
+      </Choicebox.Radio>
+    </Choicebox.RadioGroup>
+  )
+}
+
+namespace styles {
+  export const group = style({ width: '100% !custom' })
+}
+```
+
+### Describe What Sets Each Option Apart
+
+**Do:** Put the deciding difference, such as time or fee, in the same place on every tile.
+
+```tsx
+/**
+ * Do example for "Keep Tile Text Short" on the Choicebox page.
+ * Give each tile a title of one to three words and a one-line description.
+ * @module
+ */
+import { Choicebox, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Choicebox.RadioGroup aria-label="Settlement" defaultValue="standard" {...styles.group()}>
+      <Choicebox.Radio value="standard">
+        <Choicebox.Title>Standard</Choicebox.Title>
+        <Choicebox.Description>Settles in one business day</Choicebox.Description>
+      </Choicebox.Radio>
+      <Choicebox.Radio value="instant">
+        <Choicebox.Title>Instant</Choicebox.Title>
+        <Choicebox.Description>Settles in seconds for a 1% fee</Choicebox.Description>
+      </Choicebox.Radio>
+    </Choicebox.RadioGroup>
+  )
+}
+
+namespace styles {
+  export const group = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Write descriptions that vary in structure or leave out the difference.
+
+```tsx
+/**
+ * Don't example for "Describe What Sets Each Option Apart" on the Choicebox page.
+ * Don't write descriptions that vary in structure or leave out the difference.
+ * @module
+ */
+import { Choicebox, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Choicebox.RadioGroup aria-label="Settlement" defaultValue="standard" {...styles.group()}>
+      <Choicebox.Radio value="standard">
+        <Choicebox.Title>Standard</Choicebox.Title>
+        <Choicebox.Description>Our most popular option</Choicebox.Description>
+      </Choicebox.Radio>
+      <Choicebox.Radio value="instant">
+        <Choicebox.Title>Instant</Choicebox.Title>
+        <Choicebox.Description>For a 1% fee, settles in seconds</Choicebox.Description>
+      </Choicebox.Radio>
+    </Choicebox.RadioGroup>
+  )
+}
+
+namespace styles {
+  export const group = style({ width: '100% !custom' })
+}
+```
+
+### Use Icons on Every Tile or None
+
+**Do:** Add a `Choicebox.Icon` from one icon set to every tile.
+
+```tsx
+/**
+ * Do example for "Use Icons on Every Tile or None" on the Choicebox page.
+ * Add a `Choicebox.Icon` from one icon set to every tile.
+ * @module
+ */
+import { Choicebox, style } from '@tempoxyz/ds'
+import { Bank, Wallet } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Choicebox.ButtonGroup aria-label="Add funds" {...styles.group()}>
+      <Choicebox.Button>
+        <Choicebox.Icon>
+          <Bank />
+        </Choicebox.Icon>
+        <Choicebox.Title>Bank transfer</Choicebox.Title>
+        <Choicebox.Description>Arrives in one business day</Choicebox.Description>
+      </Choicebox.Button>
+      <Choicebox.Button>
+        <Choicebox.Icon>
+          <Wallet />
+        </Choicebox.Icon>
+        <Choicebox.Title>From a wallet</Choicebox.Title>
+        <Choicebox.Description>Send USDC from any address</Choicebox.Description>
+      </Choicebox.Button>
+    </Choicebox.ButtonGroup>
+  )
+}
+
+namespace styles {
+  export const group = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Give icons to only some tiles in a group.
+
+```tsx
+/**
+ * Don't example for "Use Icons on Every Tile or None" on the Choicebox page.
+ * Don't give icons to only some tiles in a group.
+ * @module
+ */
+import { Choicebox, style } from '@tempoxyz/ds'
+import { Bank } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Choicebox.ButtonGroup aria-label="Add funds" {...styles.group()}>
+      <Choicebox.Button>
+        <Choicebox.Icon>
+          <Bank />
+        </Choicebox.Icon>
+        <Choicebox.Title>Bank transfer</Choicebox.Title>
+        <Choicebox.Description>Arrives in one business day</Choicebox.Description>
+      </Choicebox.Button>
+      <Choicebox.Button>
+        <Choicebox.Title>From a wallet</Choicebox.Title>
+        <Choicebox.Description>Send USDC from any address</Choicebox.Description>
+      </Choicebox.Button>
+    </Choicebox.ButtonGroup>
+  )
+}
+
+namespace styles {
+  export const group = style({ width: '100% !custom' })
+}
+```
+
+### Preselect a Safe Default
+
+**Do:** Preselect an option only if it costs nothing extra, such as Standard settlement.
+
+```tsx
+/**
+ * Do example for "Keep Tile Text Short" on the Choicebox page.
+ * Give each tile a title of one to three words and a one-line description.
+ * @module
+ */
+import { Choicebox, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Choicebox.RadioGroup aria-label="Settlement" defaultValue="standard" {...styles.group()}>
+      <Choicebox.Radio value="standard">
+        <Choicebox.Title>Standard</Choicebox.Title>
+        <Choicebox.Description>Settles in one business day</Choicebox.Description>
+      </Choicebox.Radio>
+      <Choicebox.Radio value="instant">
+        <Choicebox.Title>Instant</Choicebox.Title>
+        <Choicebox.Description>Settles in seconds for a 1% fee</Choicebox.Description>
+      </Choicebox.Radio>
+    </Choicebox.RadioGroup>
+  )
+}
+
+namespace styles {
+  export const group = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Preselect an option with a fee.
+
+```tsx
+/**
+ * Don't example for "Preselect a Safe Default" on the Choicebox page.
+ * Don't preselect an option with a fee.
+ * @module
+ */
+import { Choicebox, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Choicebox.RadioGroup aria-label="Settlement" defaultValue="instant" {...styles.group()}>
+      <Choicebox.Radio value="standard">
+        <Choicebox.Title>Standard</Choicebox.Title>
+        <Choicebox.Description>Settles in one business day</Choicebox.Description>
+      </Choicebox.Radio>
+      <Choicebox.Radio value="instant">
+        <Choicebox.Title>Instant</Choicebox.Title>
+        <Choicebox.Description>Settles in seconds for a 1% fee</Choicebox.Description>
+      </Choicebox.Radio>
+    </Choicebox.RadioGroup>
+  )
+}
+
+namespace styles {
+  export const group = style({ width: '100% !custom' })
+}
+```
+
+### Explain Unavailable Options
+
+Leave out options that never apply to the account.
+
+**Do:** If a tile is `disabled`, say why in its description.
+
+```tsx
+/**
+ * Do example for "Explain Unavailable Options" on the Choicebox page.
+ * If a tile is `disabled`, say why in its description.
+ * @module
+ */
+import { Choicebox, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Choicebox.RadioGroup aria-label="Settlement" defaultValue="standard" {...styles.group()}>
+      <Choicebox.Radio value="standard">
+        <Choicebox.Title>Standard</Choicebox.Title>
+        <Choicebox.Description>Settles in one business day</Choicebox.Description>
+      </Choicebox.Radio>
+      <Choicebox.Radio disabled value="wire">
+        <Choicebox.Title>Wire</Choicebox.Title>
+        <Choicebox.Description>Unavailable in your region</Choicebox.Description>
+      </Choicebox.Radio>
+    </Choicebox.RadioGroup>
+  )
+}
+
+namespace styles {
+  export const group = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Disable a tile without a reason.
+
+```tsx
+/**
+ * Don't example for "Explain Unavailable Options" on the Choicebox page.
+ * Don't disable a tile without a reason.
+ * @module
+ */
+import { Choicebox, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Choicebox.RadioGroup aria-label="Settlement" defaultValue="standard" {...styles.group()}>
+      <Choicebox.Radio value="standard">
+        <Choicebox.Title>Standard</Choicebox.Title>
+        <Choicebox.Description>Settles in one business day</Choicebox.Description>
+      </Choicebox.Radio>
+      <Choicebox.Radio disabled value="wire">
+        <Choicebox.Title>Wire</Choicebox.Title>
+        <Choicebox.Description>Settles the same day for a $15 fee</Choicebox.Description>
+      </Choicebox.Radio>
+    </Choicebox.RadioGroup>
+  )
+}
+
+namespace styles {
+  export const group = style({ width: '100% !custom' })
+}
+```
+
+## Content
+
+* **Descriptions:** Fragments without a trailing period, such as Settles in one business day.
+* **Numbers:** Exact fees and times, such as 1% fee, not a small fee.
+
+## Accessibility
+
+Radio tiles follow the [WAI-ARIA radio group pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/), and checkbox tiles the [checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/).
+
+### Semantics
+
+* **Choicebox.RadioGroup (radiogroup):** Pressing anywhere on a tile selects it.
+* **Choicebox.CheckboxGroup (group):** Pressing anywhere on a tile toggles it.
+* **Choicebox.ButtonGroup (group):** Each tile is a native button. Enter and Space run it.
+* **Name (aria-labelledby):** The tile's title and description together name its control.
+* **Icon and Disabled Tiles (aria-disabled):** Icons are hidden from screen readers. A disabled tile marks its control disabled.
+
+### Keyboard
+
+* **Move to a Tile (Tab):** Focuses the checked tile in a radio group. In other groups, each tile is a tab stop.
+* **Select the Next or Previous Tile (Arrow keys):** In a radio group, selects the next or previous enabled tile.
+* **Toggle a Checkbox Tile (Space):** Toggles a checkbox tile.
+* **Activate a Button Tile (Enter or Space):** Activates a button tile.
+
+### Motion
+
+Pressed tiles scale to `scale.press` (0.98), except under `prefers-reduced-motion: reduce`.
+
+### Your Responsibilities
+
+* **Name Each Group (aria-label):** Phrase it as a question, such as "How should this payment settle?"
+
+## Related
+
+[RadioGroup](/docs/components/radio-group)
+
+Use for one choice with short labels.
+
+[CheckboxGroup](/docs/components/checkbox-group)
+
+Use for several choices with short labels.
+
+[ChoiceGroup](/docs/components/choice-group)
+
+Use for switching a view or mode.
+
+[Fieldset](/docs/components/fieldset)
+
+Use for naming a group with a legend.
+
+[Payments](/docs/patterns/payments)
+
+Covers choosing a funding or settlement method.