@tempoxyz/ds 0.3.10 → 0.3.11

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

@@ -0,0 +1,528 @@
+# RadioGroup
+
+Lets you pick a single option from a short list.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/RadioGroup.tsx)
+
+Figma: [Radio Group](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=3506-3363) (`RadioGroup.Root`)
+
+## Overview
+
+Arrow keys move focus and selection together.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Field, RadioGroup } from '@tempoxyz/ds'
+
+function Choice(props: { label: string; value: string }) {
+  return (
+    <Field.Root>
+      <Field.Item>
+        <RadioGroup.Item value={props.value} />
+        <Field.Label>{props.label}</Field.Label>
+      </Field.Item>
+    </Field.Root>
+  )
+}
+
+export function Demo() {
+  return (
+    <RadioGroup.Root aria-label="Plan" defaultValue="pro">
+      <Choice label="Free" value="free" />
+      <Choice label="Pro" value="pro" />
+      <Choice label="Team" value="team" />
+    </RadioGroup.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/RadioGroup/Basic.tsx)
+
+### Size
+
+Set `size` on `RadioGroup.Root` to `small`, `medium` (default), or `large`.
+
+```tsx
+import { Field, RadioGroup, style } from '@tempoxyz/ds'
+
+function Choice(props: { label: string; value: string }) {
+  return (
+    <Field.Root>
+      <Field.Item>
+        <RadioGroup.Item value={props.value} />
+        <Field.Label>{props.label}</Field.Label>
+      </Field.Item>
+    </Field.Root>
+  )
+}
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {(['small', 'medium', 'large'] as const).map((size) => (
+        <RadioGroup.Root aria-label={`Plan ${size}`} defaultValue="pro" key={size} size={size}>
+          <Choice label={`Free (${size})`} value="free" />
+          <Choice label={`Pro (${size})`} value="pro" />
+        </RadioGroup.Root>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ display: 'flex', flexWrap: 'wrap', gap: '48' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/RadioGroup/Size.tsx)
+
+### Disabled
+
+Set `disabled` on a `RadioGroup.Item` to disable one option, or on `RadioGroup.Root` to disable the group.
+
+```tsx
+import { Field, RadioGroup, style } from '@tempoxyz/ds'
+
+function Choice(props: { disabled?: boolean; label: string; value: string }) {
+  return (
+    <Field.Root>
+      <Field.Item>
+        <RadioGroup.Item disabled={props.disabled} value={props.value} />
+        <Field.Label>{props.label}</Field.Label>
+      </Field.Item>
+    </Field.Root>
+  )
+}
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <RadioGroup.Root aria-label="Plan" defaultValue="pro">
+        <Choice label="Free" value="free" />
+        <Choice label="Pro" value="pro" />
+        <Choice disabled label="Team" value="team" />
+      </RadioGroup.Root>
+      <RadioGroup.Root aria-label="Disabled plan" defaultValue="pro" disabled>
+        <Choice label="Free" value="free" />
+        <Choice label="Pro" value="pro" />
+      </RadioGroup.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ display: 'flex', flexWrap: 'wrap', gap: '48' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/RadioGroup/Disabled.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Field, RadioGroup } from '@tempoxyz/ds'
+
+<RadioGroup.Root>
+  <Field.Root>
+    <Field.Item>
+      <RadioGroup.Item />
+      <Field.Label />
+    </Field.Item>
+  </Field.Root>
+</RadioGroup.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Pick one of two to five options that people compare side by side.
+* Choose a setting with a few fixed values, such as a payout schedule or API key permissions.
+
+### When Not to Use
+
+* Use [Checkbox](/docs/components/checkbox) or [CheckboxGroup](/docs/components/checkbox-group) for several picks, or for a single yes or no.
+* Use [Select](/docs/components/select) for more than five options, or when space is tight.
+* Use [ChoiceGroup](/docs/components/choice-group) to switch a view or mode, such as 24H and 7D.
+* Use [Choicebox](/docs/components/choicebox) when each option needs an icon or a description.
+* Use [Switch](/docs/components/switch) for a single setting that applies immediately.
+
+### Ask One Question
+
+Name the group with its question: point `aria-labelledby` at visible text, set `aria-label`, or use a `Fieldset.Legend`.
+
+**Do:** Make every option answer the group's question.
+
+```tsx
+/**
+ * Do example for "Ask One Question" on the RadioGroup page.
+ * Make every option answer the group's question.
+ * @module
+ */
+import { Field, Fieldset, RadioGroup } from '@tempoxyz/ds'
+
+const options = ['Read only', 'Read and write', 'Admin']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Fieldset.Root>
+      <Fieldset.Legend>Who can use this key?</Fieldset.Legend>
+      <RadioGroup.Root defaultValue="Read only">
+        {options.map((option) => (
+          <Field.Root key={option}>
+            <Field.Item>
+              <RadioGroup.Item value={option} />
+              <Field.Label>{option}</Field.Label>
+            </Field.Item>
+          </Field.Root>
+        ))}
+      </RadioGroup.Root>
+    </Fieldset.Root>
+  )
+}
+```
+
+**Don't:** Mix in an option that answers a different question.
+
+```tsx
+/**
+ * Don't example for "Ask One Question" on the RadioGroup page.
+ * Don't mix in an option that answers a different question.
+ * @module
+ */
+import { Field, Fieldset, RadioGroup } from '@tempoxyz/ds'
+
+const options = ['Read only', 'Expires in 30 days', 'Admin']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Fieldset.Root>
+      <Fieldset.Legend>Who can use this key?</Fieldset.Legend>
+      <RadioGroup.Root defaultValue="Read only">
+        {options.map((option) => (
+          <Field.Root key={option}>
+            <Field.Item>
+              <RadioGroup.Item value={option} />
+              <Field.Label>{option}</Field.Label>
+            </Field.Item>
+          </Field.Root>
+        ))}
+      </RadioGroup.Root>
+    </Fieldset.Root>
+  )
+}
+```
+
+### Preselect Only a Safe Default
+
+**Do:** Preselect the option with the least access, such as Read only.
+
+```tsx
+/**
+ * Do example for "Preselect Only a Safe Default" on the RadioGroup page.
+ * Preselect the option with the least access, such as Read only.
+ * @module
+ */
+import { Field, RadioGroup } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <RadioGroup.Root aria-label="Key permissions" defaultValue="read">
+      <Field.Root>
+        <Field.Item>
+          <RadioGroup.Item value="read" />
+          <Field.Label>Read only</Field.Label>
+        </Field.Item>
+      </Field.Root>
+      <Field.Root>
+        <Field.Item>
+          <RadioGroup.Item value="write" />
+          <Field.Label>Read and write</Field.Label>
+        </Field.Item>
+      </Field.Root>
+    </RadioGroup.Root>
+  )
+}
+```
+
+**Don't:** Preselect an option that grants more access or moves funds.
+
+```tsx
+/**
+ * Don't example for "Preselect Only a Safe Default" on the RadioGroup page.
+ * Don't preselect an option that grants more access or moves funds.
+ * @module
+ */
+import { Field, RadioGroup } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <RadioGroup.Root aria-label="Key permissions" defaultValue="write">
+      <Field.Root>
+        <Field.Item>
+          <RadioGroup.Item value="read" />
+          <Field.Label>Read only</Field.Label>
+        </Field.Item>
+      </Field.Root>
+      <Field.Root>
+        <Field.Item>
+          <RadioGroup.Item value="write" />
+          <Field.Label>Read and write</Field.Label>
+        </Field.Item>
+      </Field.Root>
+    </RadioGroup.Root>
+  )
+}
+```
+
+If no option is safe, leave the group empty, set `required`, and ask for a choice on submit. A group cannot return to empty after a pick. If no choice is a valid answer, add an option such as None.
+
+### Order Options Logically
+
+With no natural order, list the most common option first. Keep the same order wherever the question appears.
+
+**Do:** List time periods in order, from Daily to Monthly.
+
+```tsx
+/**
+ * Do example for "Order Options Logically" on the RadioGroup page.
+ * List time periods in order, from Daily to Monthly.
+ * @module
+ */
+import { Field, RadioGroup } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <RadioGroup.Root aria-label="Payout schedule" defaultValue="weekly">
+      {['Daily', 'Weekly', 'Monthly'].map((label) => (
+        <Field.Root key={label}>
+          <Field.Item>
+            <RadioGroup.Item value={label.toLowerCase()} />
+            <Field.Label>{label}</Field.Label>
+          </Field.Item>
+        </Field.Root>
+      ))}
+    </RadioGroup.Root>
+  )
+}
+```
+
+**Don't:** Mix the order of options that have a sequence.
+
+```tsx
+/**
+ * Don't example for "Order Options Logically" on the RadioGroup page.
+ * Don't mix the order of options that have a sequence.
+ * @module
+ */
+import { Field, RadioGroup } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <RadioGroup.Root aria-label="Payout schedule" defaultValue="weekly">
+      {['Monthly', 'Daily', 'Weekly'].map((label) => (
+        <Field.Root key={label}>
+          <Field.Item>
+            <RadioGroup.Item value={label.toLowerCase()} />
+            <Field.Label>{label}</Field.Label>
+          </Field.Item>
+        </Field.Root>
+      ))}
+    </RadioGroup.Root>
+  )
+}
+```
+
+### Keep Options in a Column
+
+**Do:** Keep the default column, so each radio lines up with its label.
+
+```tsx
+/**
+ * Do example for "Keep Options in a Column" on the RadioGroup page.
+ * Keep the default column, so each radio lines up with its label.
+ * @module
+ */
+import { Field, RadioGroup } from '@tempoxyz/ds'
+
+const options = ['Read only', 'Read and write', 'Admin']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <RadioGroup.Root aria-label="Key permissions" defaultValue="Read only">
+      {options.map((option) => (
+        <Field.Root key={option}>
+          <Field.Item>
+            <RadioGroup.Item value={option} />
+            <Field.Label>{option}</Field.Label>
+          </Field.Item>
+        </Field.Root>
+      ))}
+    </RadioGroup.Root>
+  )
+}
+```
+
+**Don't:** Lay radios out in a wrapping row.
+
+```tsx
+/**
+ * Don't example for "Keep Options in a Column" on the RadioGroup page.
+ * Don't lay radios out in a wrapping row.
+ * @module
+ */
+import { Field, RadioGroup, style } from '@tempoxyz/ds'
+
+const options = ['Read only', 'Read and write', 'Admin']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <RadioGroup.Root aria-label="Key permissions" defaultValue="Read only" {...styles.row()}>
+      {options.map((option) => (
+        <Field.Root key={option}>
+          <Field.Item>
+            <RadioGroup.Item value={option} />
+            <Field.Label>{option}</Field.Label>
+          </Field.Item>
+        </Field.Root>
+      ))}
+    </RadioGroup.Root>
+  )
+}
+
+namespace styles {
+  export const row = style({ columnGap: '12', flexDirection: 'row', flexWrap: 'wrap', rowGap: '8' })
+}
+```
+
+### Label Every Option
+
+Set `disabled` on an item only with a nearby reason, such as Requires a verified domain.
+
+**Do:** Wrap each radio in a `Field.Item` with a `Field.Label`, and add a `Field.Description` after it.
+
+```tsx
+/**
+ * Do example for "Label Every Option" on the RadioGroup page.
+ * Wrap each radio in a `Field.Item` with a `Field.Label`, and add a `Field.Description` after it.
+ * @module
+ */
+import { Field, RadioGroup } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <RadioGroup.Root aria-label="Payout schedule" defaultValue="weekly">
+      <Field.Root>
+        <Field.Item>
+          <RadioGroup.Item value="weekly" />
+          <Field.Label>Weekly</Field.Label>
+        </Field.Item>
+        <Field.Description>Every Monday in USDC.</Field.Description>
+      </Field.Root>
+      <Field.Root>
+        <Field.Item>
+          <RadioGroup.Item value="monthly" />
+          <Field.Label>Monthly</Field.Label>
+        </Field.Item>
+        <Field.Description>On the first day of each month.</Field.Description>
+      </Field.Root>
+    </RadioGroup.Root>
+  )
+}
+```
+
+**Don't:** Place plain text beside a radio. A press on it selects nothing.
+
+```tsx
+/**
+ * Don't example for "Label Every Option" on the RadioGroup page.
+ * Don't place plain text beside a radio. A press on it selects nothing.
+ * @module
+ */
+import { RadioGroup, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <RadioGroup.Root aria-label="Payout schedule" defaultValue="weekly">
+      <div {...styles.option()}>
+        <RadioGroup.Item value="weekly" />
+        <span>Weekly: every Monday in USDC.</span>
+      </div>
+      <div {...styles.option()}>
+        <RadioGroup.Item value="monthly" />
+        <span>Monthly: on the first day of each month.</span>
+      </div>
+    </RadioGroup.Root>
+  )
+}
+
+namespace styles {
+  export const option = style({ alignItems: 'center', display: 'flex', gap: '8' })
+}
+```
+
+## Content
+
+* **Option labels:** Keep them short and parallel, such as Read only and Read and write. Don't repeat words from the question in every option.
+
+## Accessibility
+
+RadioGroup follows the [WAI-ARIA Authoring Practices radio group pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/).
+
+### Semantics
+
+* **RadioGroup.Root (radiogroup):** Groups the radios. Screen readers announce them as one set.
+* **RadioGroup.Item (radio):** Announced with its checked state. A hidden native input submits the value under the group's `name`.
+* **Disabled Items (aria-disabled):** A disabled item, or every item in a disabled group, stays visible but dimmed.
+* **Checked State (dot):** The checked radio fills in and shows a mark, so selection does not rely on color alone.
+* **Target Size (16, 20, 24px):** The hit area reaches 10px past each radio, and a label in `Field.Item` adds to it.
+
+### Keyboard
+
+* **Enter the Group (Tab):** Moves focus into the group, onto the checked radio. The group is one Tab stop.
+* **Leave the Group (Shift+Tab):** Moves focus out of the group.
+* **Select the Next Radio (Down or Right Arrow):** Moves focus to the next radio and selects it, wrapping from last to first.
+* **Select the Previous Radio (Up or Left Arrow):** Moves focus to the previous radio and selects it, wrapping from first to last.
+
+Arrow keys skip disabled radios.
+
+### Your Responsibilities
+
+* **Keep Changes Cheap (onValueChange):** Arrow keys select as they move. Avoid costly work on each change.
+
+## Related
+
+[ChoiceGroup](/docs/components/choice-group)
+
+Use for switching views and modes.
+
+[Choicebox](/docs/components/choicebox)
+
+Use for options with icons or descriptions.
+
+[Select](/docs/components/select)
+
+Use for longer lists.
+
+[Checkbox](/docs/components/checkbox)
+
+Use for independent choices.
+
+[Fieldset](/docs/components/fieldset)
+
+Use for naming a group with a legend.