@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/checkbox.md

@@ -0,0 +1,467 @@
+# Checkbox
+
+Turns a single independent option on or off.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Checkbox.tsx)
+
+Figma: [Checkbox](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=3086-1190)
+
+## Overview
+
+A hidden native input submits its value with the form.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Checkbox, Field } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Field.Root>
+      <Field.Item>
+        <Checkbox defaultChecked />
+        <Field.Label>Email me receipts</Field.Label>
+      </Field.Item>
+    </Field.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Checkbox/Basic.tsx)
+
+### Checked
+
+Set `defaultChecked` for an uncontrolled checkbox, or `checked` with `onCheckedChange` to control it.
+
+```tsx
+import { Checkbox, Field, style } 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 (
+    <div {...styles.column()}>
+      <Item label="Unchecked" />
+      <Item defaultChecked label="Checked" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const column = style({ display: 'flex', flexDirection: 'column', gap: '16' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Checkbox/Checked.tsx)
+
+### Indeterminate
+
+Set `indeterminate` to show a minus and expose the mixed state.
+
+```tsx
+import { Checkbox, 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 <Item indeterminate label="Indeterminate" />
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Checkbox/Indeterminate.tsx)
+
+### Disabled
+
+```tsx
+import { Checkbox, Field, style } 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 (
+    <div {...styles.column()}>
+      <Item disabled label="Disabled" />
+      <Item defaultChecked disabled label="Disabled checked" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const column = style({ display: 'flex', flexDirection: 'column', gap: '16' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Checkbox/Disabled.tsx)
+
+### Size
+
+Set `size` to `small`, `medium` (default), or `large`.
+
+```tsx
+import { Checkbox, Field, style } 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 (
+    <div {...styles.column()}>
+      {(['small', 'medium', 'large'] as const).map((size) => (
+        <Item defaultChecked key={size} label={size} size={size} />
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const column = style({ display: 'flex', flexDirection: 'column', gap: '16' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Checkbox/Size.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Checkbox } from '@tempoxyz/ds'
+
+<Checkbox />
+```
+
+## Guidelines
+
+### When to Use
+
+* Offer one independent choice that applies on form submit, such as Email me a receipt for each payment.
+* Ask for agreement before a step, such as accepting the API terms before creating a key.
+* Select table rows for a bulk action, such as revoking several API keys.
+
+### When Not to Use
+
+* Use [Switch](/docs/components/switch) for a setting that applies immediately.
+* Use [CheckboxGroup](/docs/components/checkbox-group) for several related options that share one value array.
+* If only one of several options can be chosen, use [RadioGroup](/docs/components/radio-group) or [ChoiceGroup](/docs/components/choice-group).
+* If each option needs an icon or a description, use `Choicebox.Checkbox` from [Choicebox](/docs/components/choicebox).
+
+### Choose Checkbox or Switch by When It Applies
+
+* **Checkbox (on submit):** Applies when the form is submitted.
+* **Switch (on change):** Applies immediately, such as Payment notifications.
+
+Don't put a [Switch](/docs/components/switch) in a form that ends with Save, or a checkbox in a settings list that saves on change.
+
+### Write the Label as the Checked Statement
+
+**Do:** Describe what happens when the box is checked.
+
+```tsx
+/**
+ * Do example for "Write the Label as the Checked Statement" on the Checkbox page.
+ * Describe what happens when the box is checked.
+ * @module
+ */
+import { Checkbox, Field } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root>
+      <Field.Item>
+        <Checkbox defaultChecked />
+        <Field.Label>Email me a receipt for each payment</Field.Label>
+      </Field.Item>
+    </Field.Root>
+  )
+}
+```
+
+**Don't:** Write a negative label, where checking the box means don't.
+
+```tsx
+/**
+ * Don't example for "Write the Label as the Checked Statement" on the Checkbox page.
+ * Don't write a negative label, where checking the box means don't.
+ * @module
+ */
+import { Checkbox, Field } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root>
+      <Field.Item>
+        <Checkbox />
+        <Field.Label>Don't email me payment receipts</Field.Label>
+      </Field.Item>
+    </Field.Root>
+  )
+}
+```
+
+### Make the Label Toggle the Box
+
+Pair the checkbox with `Field.Item` and `Field.Label` from [Field](/docs/components/field), or wrap both in a `<label>`. Pressing the text then toggles the box.
+
+**Do:** Put the checkbox and its `Field.Label` in one `Field.Item`.
+
+```tsx
+/**
+ * Do example for "Make the Label Toggle the Box" on the Checkbox page.
+ * Put the checkbox and its `Field.Label` in one `Field.Item`.
+ * @module
+ */
+import { Checkbox, Field } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root>
+      <Field.Item>
+        <Checkbox />
+        <Field.Label>Email me a receipt for each payment</Field.Label>
+      </Field.Item>
+    </Field.Root>
+  )
+}
+```
+
+**Don't:** Place plain text beside the box. It neither names nor toggles it.
+
+```tsx
+/**
+ * Don't example for "Make the Label Toggle the Box" on the Checkbox page.
+ * Don't place plain text beside the box. It neither names nor toggles it.
+ * @module
+ */
+import { Checkbox, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Checkbox />
+      <span>Email me a receipt for each payment</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '8' })
+}
+```
+
+### Use Indeterminate for Partial Selection Only
+
+Inside a [CheckboxGroup](/docs/components/checkbox-group), set `parent` instead and let the group manage the state.
+
+**Do:** Set `indeterminate` on a box that controls others while only some are checked.
+
+```tsx
+/**
+ * Do example for "Use Indeterminate for Partial Selection Only" on the Checkbox page.
+ * Set `indeterminate` on a box that controls others while only some are checked.
+ * @module
+ */
+import { Checkbox, Field, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      <Field.Root>
+        <Field.Item>
+          <Checkbox indeterminate />
+          <Field.Label>Select all keys</Field.Label>
+        </Field.Item>
+      </Field.Root>
+      <Field.Root>
+        <Field.Item>
+          <Checkbox defaultChecked />
+          <Field.Label>prod-api-01</Field.Label>
+        </Field.Item>
+      </Field.Root>
+      <Field.Root>
+        <Field.Item>
+          <Checkbox />
+          <Field.Label>staging-api-02</Field.Label>
+        </Field.Item>
+      </Field.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const list = style({ display: 'flex', flexDirection: 'column', gap: '12' })
+}
+```
+
+**Don't:** Set `indeterminate` on a box that controls no other boxes.
+
+```tsx
+/**
+ * Don't example for "Use Indeterminate for Partial Selection Only" on the Checkbox page.
+ * Don't set `indeterminate` on a box that controls no other boxes.
+ * @module
+ */
+import { Checkbox, Field } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root>
+      <Field.Item>
+        <Checkbox indeterminate />
+        <Field.Label>Email me a receipt for each payment</Field.Label>
+      </Field.Item>
+    </Field.Root>
+  )
+}
+```
+
+### Leave Consent Unchecked
+
+If a box must be checked to continue, set `required` and show a `Field.Error` when it is unchecked.
+
+**Do:** Leave boxes that record agreement or opt in to email unchecked.
+
+```tsx
+/**
+ * Do example for "Leave Consent Unchecked" on the Checkbox page.
+ * Leave boxes that record agreement or opt in to email unchecked.
+ * @module
+ */
+import { Checkbox, Field } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root>
+      <Field.Item>
+        <Checkbox />
+        <Field.Label>Email me product updates</Field.Label>
+      </Field.Item>
+    </Field.Root>
+  )
+}
+```
+
+**Don't:** Preselect consent.
+
+```tsx
+/** Don't example for "Leave Consent Unchecked" on the Checkbox page. Don't preselect consent. @module */
+import { Checkbox, Field } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root>
+      <Field.Item>
+        <Checkbox defaultChecked />
+        <Field.Label>Email me product updates</Field.Label>
+      </Field.Item>
+    </Field.Root>
+  )
+}
+```
+
+## Content
+
+* **Explanation:** Put it in a `Field.Description` after the `Field.Item`, in the same `Field.Root`.
+* **Links:** Keep them out of the label, where they compete with its press target. Link to terms from the description.
+
+## Accessibility
+
+Follows the [WAI-ARIA checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/).
+
+### Semantics
+
+* **Control (checkbox):** Reports a checked, unchecked, or mixed state to assistive technology.
+* **Native TextInput (input):** A hidden native input submits the value under `name`. Screen readers and Tab skip it.
+* **Indeterminate (mixed):** Shows a minus in the box and exposes the mixed state to assistive technology.
+* **Disabled (aria-disabled):** Dims the box, blocks changes, and removes it from the tab order.
+* **Target Size (36 to 44px):** An invisible hit area extends each indicator past the 24px WCAG 2.2 minimum.
+
+### Keyboard
+
+* **Move to the Checkbox (Tab):** Moves focus to the checkbox. Each one is its own tab stop.
+* **Toggle the Checkbox (Space):** Toggles the checkbox between the checked and unchecked states.
+* **Submit the Form (Enter):** Submits the owning form without toggling, as a native checkbox does.
+
+### Motion
+
+The check animates in with a slight overshoot. Under `prefers-reduced-motion: reduce`, it fades.
+
+### Your Responsibilities
+
+* **Use ARIA Labels Sparingly (aria-label):** Use it only if the layout already shows the label, such as a table row selector.
+* **Explain Disabled Checkboxes:** Say why in nearby text. A disabled checkbox cannot take focus.
+* **Pair Invalid With an Error (Field.Error):** An invalid field outlines the box in red. Add an error message to explain it.
+
+## Related
+
+[CheckboxGroup](/docs/components/checkbox-group)
+
+Use for several related checkboxes.
+
+[Switch](/docs/components/switch)
+
+Use for settings that apply immediately.
+
+[Field](/docs/components/field)
+
+Use for the label and description.
+
+[Choicebox](/docs/components/choicebox)
+
+Use for options that need descriptions.
+
+[Forms](/docs/patterns/forms)
+
+Covers placing checkboxes in a form.