@tempoxyz/ds 0.3.9 → 0.3.11

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

@@ -0,0 +1,521 @@
+# CheckboxGroup
+
+Shares one value array across a group of checkboxes.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/CheckboxGroup.tsx)
+
+## Overview
+
+Each [Checkbox](/docs/components/checkbox) inside it joins the array under its `value`.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <CheckboxGroup aria-label="Currencies" defaultValue={['usdc']}>
+      {(['USDC', 'USDT', 'EURC'] as const).map((label) => (
+        <Field.Root key={label}>
+          <Field.Item>
+            <Checkbox value={label.toLowerCase()} />
+            <Field.Label>{label}</Field.Label>
+          </Field.Item>
+        </Field.Root>
+      ))}
+    </CheckboxGroup>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/CheckboxGroup/Basic.tsx)
+
+### Parent
+
+For a select-all box, pass every option to `allValues` and add a `Checkbox` with `parent`.
+
+```tsx
+import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'
+
+function Item(props: Checkbox.Props & { label: string }) {
+  const { label, ...checkbox } = props
+
+  return (
+    <Field.Root>
+      <Field.Item>
+        <Checkbox {...checkbox} />
+        <Field.Label>{label}</Field.Label>
+      </Field.Item>
+    </Field.Root>
+  )
+}
+
+export function Demo() {
+  return (
+    <CheckboxGroup
+      allValues={['usdc', 'usdt', 'eurc']}
+      aria-label="Currencies"
+      defaultValue={['usdc']}
+    >
+      <Checkbox aria-label="All currencies" parent />
+      <Item label="USDC" name="usdc" value="usdc" />
+      <Item label="USDT" name="usdt" value="usdt" />
+      <Item label="EURC" name="eurc" value="eurc" />
+    </CheckboxGroup>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/CheckboxGroup/Parent.tsx)
+
+### Disabled
+
+Set `disabled` to disable every checkbox in the group.
+
+```tsx
+import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <CheckboxGroup aria-label="Currencies" defaultValue={['usdc']} disabled>
+      {(['USDC', 'USDT', 'EURC'] as const).map((label) => (
+        <Field.Root key={label}>
+          <Field.Item>
+            <Checkbox value={label.toLowerCase()} />
+            <Field.Label>{label}</Field.Label>
+          </Field.Item>
+        </Field.Root>
+      ))}
+    </CheckboxGroup>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/CheckboxGroup/Disabled.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { CheckboxGroup, Checkbox } from '@tempoxyz/ds'
+
+<CheckboxGroup>
+  <Checkbox />
+</CheckboxGroup>
+```
+
+## Guidelines
+
+### When to Use
+
+* Choose any number of related options from a short list, such as webhook events or accepted currencies.
+* Add a select-all box over that list with a `parent` checkbox.
+
+### When Not to Use
+
+* If only one option can be chosen, use [RadioGroup](/docs/components/radio-group).
+* Use [Combobox](/docs/components/combobox) with `multiple` for a long list filtered by typing, such as assets.
+* If each option needs an icon or a description, use `Choicebox.CheckboxGroup` from [Choicebox](/docs/components/choicebox).
+* Use a single [Checkbox](/docs/components/checkbox) for one independent choice.
+* If choices apply immediately, as in a settings list, use a [Switch](/docs/components/switch) for each.
+
+### Name the Group With Its Question
+
+Give the group an `aria-label`, or a `Field.Label` inside a `Field.Root`.
+
+**Do:** Phrase the name as the question the options answer.
+
+```tsx
+/**
+ * Do example for "Name the Group With Its Question" on the CheckboxGroup page.
+ * Phrase the name as the question the options answer.
+ * @module
+ */
+import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'
+
+const events = ['Payment confirmed', 'Payment failed', 'Refund issued']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root>
+      <Field.Label>Which events should this webhook send?</Field.Label>
+      <CheckboxGroup defaultValue={['Payment confirmed']}>
+        {events.map((event) => (
+          <Field.Root key={event}>
+            <Field.Item>
+              <Checkbox value={event} />
+              <Field.Label>{event}</Field.Label>
+            </Field.Item>
+          </Field.Root>
+        ))}
+      </CheckboxGroup>
+    </Field.Root>
+  )
+}
+```
+
+**Don't:** Use a generic name, such as Options.
+
+```tsx
+/**
+ * Don't example for "Name the Group With Its Question" on the CheckboxGroup page.
+ * Don't use a generic name, such as Options.
+ * @module
+ */
+import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'
+
+const events = ['Payment confirmed', 'Payment failed', 'Refund issued']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root>
+      <Field.Label>Options</Field.Label>
+      <CheckboxGroup defaultValue={['Payment confirmed']}>
+        {events.map((event) => (
+          <Field.Root key={event}>
+            <Field.Item>
+              <Checkbox value={event} />
+              <Field.Label>{event}</Field.Label>
+            </Field.Item>
+          </Field.Root>
+        ))}
+      </CheckboxGroup>
+    </Field.Root>
+  )
+}
+```
+
+### Stack Options in a Column
+
+**Do:** Keep the default column, so each box lines up with its label.
+
+```tsx
+/**
+ * Do example for "Stack Options in a Column" on the CheckboxGroup page.
+ * Keep the default column, so each box lines up with its label.
+ * @module
+ */
+import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'
+
+const events = ['Payment confirmed', 'Payment failed', 'Refund issued']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <CheckboxGroup aria-label="Webhook events" defaultValue={['Payment confirmed']}>
+      {events.map((event) => (
+        <Field.Root key={event}>
+          <Field.Item>
+            <Checkbox value={event} />
+            <Field.Label>{event}</Field.Label>
+          </Field.Item>
+        </Field.Root>
+      ))}
+    </CheckboxGroup>
+  )
+}
+```
+
+**Don't:** Run options together in a wrapping row.
+
+```tsx
+/**
+ * Don't example for "Stack Options in a Column" on the CheckboxGroup page.
+ * Don't run options together in a wrapping row.
+ * @module
+ */
+import { Checkbox, CheckboxGroup, Field, style } from '@tempoxyz/ds'
+
+const events = ['Payment confirmed', 'Payment failed', 'Refund issued']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <CheckboxGroup aria-label="Webhook events" defaultValue={['Payment confirmed']}>
+      <div {...styles.row()}>
+        {events.map((event) => (
+          <Field.Root key={event}>
+            <Field.Item>
+              <Checkbox value={event} />
+              <Field.Label>{event}</Field.Label>
+            </Field.Item>
+          </Field.Root>
+        ))}
+      </div>
+    </CheckboxGroup>
+  )
+}
+
+namespace styles {
+  export const row = style({ columnGap: '12', display: 'flex', flexWrap: 'wrap', rowGap: '8' })
+}
+```
+
+### Keep the List Short and Ordered
+
+Sort long lists of names alphabetically. If the list no longer fits without scrolling, switch to a [Combobox](/docs/components/combobox) with `multiple`.
+
+**Do:** Order options predictably, such as by payment lifecycle.
+
+```tsx
+/**
+ * Do example for "Keep the List Short and Ordered" on the CheckboxGroup page.
+ * Order options predictably, such as by payment lifecycle.
+ * @module
+ */
+import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'
+
+const events = ['Payment created', 'Payment confirmed', 'Payment refunded']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <CheckboxGroup aria-label="Webhook events" defaultValue={['Payment confirmed']}>
+      {events.map((event) => (
+        <Field.Root key={event}>
+          <Field.Item>
+            <Checkbox value={event} />
+            <Field.Label>{event}</Field.Label>
+          </Field.Item>
+        </Field.Root>
+      ))}
+    </CheckboxGroup>
+  )
+}
+```
+
+**Don't:** List options in an arbitrary order.
+
+```tsx
+/**
+ * Don't example for "Keep the List Short and Ordered" on the CheckboxGroup page.
+ * Don't list options in an arbitrary order.
+ * @module
+ */
+import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'
+
+const events = ['Payment refunded', 'Payment created', 'Payment confirmed']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <CheckboxGroup aria-label="Webhook events" defaultValue={['Payment confirmed']}>
+      {events.map((event) => (
+        <Field.Root key={event}>
+          <Field.Item>
+            <Checkbox value={event} />
+            <Field.Label>{event}</Field.Label>
+          </Field.Item>
+        </Field.Root>
+      ))}
+    </CheckboxGroup>
+  )
+}
+```
+
+### Put the Parent Box First
+
+**Do:** Put the `parent` checkbox first, and label it after the set, such as All events.
+
+```tsx
+/**
+ * Do example for "Put the Parent Box First" on the CheckboxGroup page.
+ * Put the `parent` checkbox first, and label it after the set, such as All events.
+ * @module
+ */
+import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'
+
+const events = ['Payment confirmed', 'Payment failed', 'Refund issued']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <CheckboxGroup
+      allValues={events}
+      aria-label="Webhook events"
+      defaultValue={['Payment confirmed']}
+    >
+      <Field.Root>
+        <Field.Item>
+          <Checkbox parent />
+          <Field.Label>All events</Field.Label>
+        </Field.Item>
+      </Field.Root>
+      {events.map((event) => (
+        <Field.Root key={event}>
+          <Field.Item>
+            <Checkbox value={event} />
+            <Field.Label>{event}</Field.Label>
+          </Field.Item>
+        </Field.Root>
+      ))}
+    </CheckboxGroup>
+  )
+}
+```
+
+**Don't:** Put a generic Select all after the options.
+
+```tsx
+/**
+ * Don't example for "Put the Parent Box First" on the CheckboxGroup page.
+ * Don't put a generic Select all after the options.
+ * @module
+ */
+import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'
+
+const events = ['Payment confirmed', 'Payment failed', 'Refund issued']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <CheckboxGroup
+      allValues={events}
+      aria-label="Webhook events"
+      defaultValue={['Payment confirmed']}
+    >
+      {events.map((event) => (
+        <Field.Root key={event}>
+          <Field.Item>
+            <Checkbox value={event} />
+            <Field.Label>{event}</Field.Label>
+          </Field.Item>
+        </Field.Root>
+      ))}
+      <Field.Root>
+        <Field.Item>
+          <Checkbox parent />
+          <Field.Label>Select all</Field.Label>
+        </Field.Item>
+      </Field.Root>
+    </CheckboxGroup>
+  )
+}
+```
+
+### Validate the Group as a Whole
+
+**Do:** If at least one option is required, show one `Field.Error` for the group.
+
+```tsx
+/**
+ * Do example for "Validate the Group as a Whole" on the CheckboxGroup page.
+ * If at least one option is required, show one `Field.Error` for the group.
+ * @module
+ */
+import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'
+
+const events = ['Payment confirmed', 'Payment failed', 'Refund issued']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root invalid>
+      <Field.Label>Which events should this webhook send?</Field.Label>
+      <CheckboxGroup defaultValue={[]}>
+        {events.map((event) => (
+          <Field.Root key={event}>
+            <Field.Item>
+              <Checkbox value={event} />
+              <Field.Label>{event}</Field.Label>
+            </Field.Item>
+          </Field.Root>
+        ))}
+      </CheckboxGroup>
+      <Field.Error match>Select at least one event</Field.Error>
+    </Field.Root>
+  )
+}
+```
+
+**Don't:** Mark each checkbox invalid.
+
+```tsx
+/**
+ * Don't example for "Validate the Group as a Whole" on the CheckboxGroup page.
+ * Don't mark each checkbox invalid.
+ * @module
+ */
+import { Checkbox, CheckboxGroup, Field } from '@tempoxyz/ds'
+
+const events = ['Payment confirmed', 'Payment failed', 'Refund issued']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root>
+      <Field.Label>Which events should this webhook send?</Field.Label>
+      <CheckboxGroup defaultValue={[]}>
+        {events.map((event) => (
+          <Field.Root invalid key={event}>
+            <Field.Item>
+              <Checkbox value={event} />
+              <Field.Label>{event}</Field.Label>
+            </Field.Item>
+            <Field.Error match>Select this event</Field.Error>
+          </Field.Root>
+        ))}
+      </CheckboxGroup>
+    </Field.Root>
+  )
+}
+```
+
+## Content
+
+* **Labels:** Write parallel labels, such as Payment confirmed, Payment failed, and Refund issued.
+* **Defaults:** Preselect only options that match a saved value or a safe default.
+
+## Accessibility
+
+Wraps related checkboxes in a named `group`. Each checkbox follows the [WAI-ARIA checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/).
+
+### Semantics
+
+* **Group (group):** Name it with `aria-label` or a `Field.Label`, or screen readers announce an unnamed group.
+* **Checkboxes (checkbox):** Each keeps its own role and state, and adds its `value` to the group. See [Checkbox](/docs/components/checkbox#accessibility).
+* **Parent Checkbox (aria-controls):** Points at the checkboxes it controls. Reports a mixed state while only some are checked.
+* **Disabled (aria-disabled):** Disables every checkbox and removes them from the tab order.
+
+### Keyboard
+
+* **Move Between Checkboxes (Tab and Shift+Tab):** Moves focus between checkboxes. Each checkbox is its own Tab stop.
+* **Toggle a Checkbox (Space):** Toggles the focused checkbox.
+* **Toggle the Parent Checkbox (Space):** Checks every option, then clears them. A third press restores the original selection.
+
+### Focus
+
+Focus stays on a parent checkbox when it changes the other options.
+
+### Your Responsibilities
+
+* **Label Every Checkbox:** Give each checkbox its own label.
+* **Explain Disabled Options (disabled):** Disables every checkbox. Explain nearby why the options are locked.
+
+## Related
+
+[Checkbox](/docs/components/checkbox)
+
+Use for a single choice.
+
+[Choicebox](/docs/components/choicebox)
+
+Use for options with descriptions.
+
+[Combobox](/docs/components/combobox)
+
+Use for choosing several items from a long list.
+
+[Fieldset](/docs/components/fieldset)
+
+Use for grouping fields under a legend.
+
+[Field](/docs/components/field)
+
+Use for naming the group and showing its error.