add documentation for CheckboxGroup and RadioGroup components

primer · Nov 27, 2024 · d65b102 · d65b102
1 parent 810a183
commit d65b102
Show file tree

Hide file tree

Showing 5 changed files with 451 additions and 0 deletions.
diff --git a/apps/docs/content/components/CheckboxGroup/index.mdx b/apps/docs/content/components/CheckboxGroup/index.mdx
@@ -0,0 +1,49 @@
+---
+title: CheckboxGroup
+description: Use CheckboxGroup to group related checkbox inputs with supporting content
+---
+
+import ComponentLayout from '../../../src/layouts/component-layout'
+export default ComponentLayout
+
+## Usage
+
+The `CheckboxGroup` family of components provide a way to group related [Checkbox](/components/Checkbox) components together with supporting content such as labels, captions, and validation messages. It creates a semantic fieldset structure that helps maintain proper form hierarchy and accessibility.
+
+## Components
+
+### Root
+
+The `CheckboxGroup` component wraps a group of checkboxes in a `fieldset`.
+
+### Label
+
+The `CheckboxGroup.Label` component renders as a `legend` and can be used to provide a heading for the group of checkboxes. The label must always be provided for accessibility purposes, but it can be visually hidden.
+
+### Caption
+
+Use `CheckboxGroup.Caption` to provide additional context or instructions for the group of checkboxes. The caption is automatically associated with the group through ARIA attributes.
+
+### Validation
+
+The `CheckboxGroup.Validation` component can be used to display success or error messages. It supports two variants:
+
+- `success`: Displays a success message with a check circle icon
+- `error`: Displays an error message with an alert icon
+
+## Accessibility
+
+CheckboxGroup enhances accessibility by:
+
+- Using semantic HTML through the `fieldset` and `legend` elements
+- Automatically associating captions and validation messages with the group using `aria-describedby`
+- Supporting visually hidden labels that remain accessible to screen readers
+- Providing clear visual indicators for validation states with supporting icons
+
+Any checkbox inputs within the group should be given their own appropriate labeling and accessibility attributes.
+
+## Related components
+
+- [Checkbox](/components/Checkbox): Used to render an individual checkbox control.
+- [FormControl](/components/FormControl): Used to group individual controls with an associated label.
+- [RadioGroup](/components/RadioGroup): Simialr to `CheckboxGroup`, but used for organizing radio controls.
diff --git a/apps/docs/content/components/CheckboxGroup/react.mdx b/apps/docs/content/components/CheckboxGroup/react.mdx
@@ -0,0 +1,185 @@
+---
+title: CheckboxGroup
+source: https://github.com/primer/brand/blob/main/packages/react/src/forms/CheckboxGroup/CheckboxGroup.tsx
+figma: 'https://www.figma.com/design/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=10467-3273&t=GA5GtEqPtQ9yeRaN-4'
+storybook: '/brand/storybook/?path=/story/components-forms-checkboxgroup--playground'
+description: Use CheckboxGroup to group related checkbox inputs with supporting content
+---
+
+import {Label} from '@primer/react'
+import {PropTableValues} from '../../../src/components'
+
+```js
+import {CheckboxGroup} from '@primer/react-brand'
+```
+
+## Examples
+
+### Basic
+
+`CheckboxGroup` creates a semantic container for multiple related checkboxes.
+
+```jsx live
+<CheckboxGroup>
+  <CheckboxGroup.Label>Choose your favorite features</CheckboxGroup.Label>
+  <FormControl>
+    <FormControl.Label>Actions notifications</FormControl.Label>
+    <Checkbox value="actions" />
+  </FormControl>
+  <FormControl>
+    <FormControl.Label>Packages</FormControl.Label>
+    <Checkbox value="packages" />
+  </FormControl>
+  <FormControl>
+    <FormControl.Label>Codespaces</FormControl.Label>
+    <Checkbox value="codespaces" />
+  </FormControl>
+</CheckboxGroup>
+```
+
+### With caption
+
+Use `CheckboxGroup.Caption` to provide additional context for the group.
+
+```jsx live
+<CheckboxGroup>
+  <CheckboxGroup.Label>Notification preferences</CheckboxGroup.Label>
+  <CheckboxGroup.Caption>
+    Select how you'd like to be notified
+  </CheckboxGroup.Caption>
+  <FormControl>
+    <FormControl.Label>Email notifications</FormControl.Label>
+    <Checkbox value="email" />
+  </FormControl>
+  <FormControl>
+    <FormControl.Label>Browser notifications</FormControl.Label>
+    <Checkbox value="browser" />
+  </FormControl>
+  <FormControl>
+    <FormControl.Label>Mobile notifications</FormControl.Label>
+    <Checkbox value="mobile" />
+  </FormControl>
+</CheckboxGroup>
+```
+
+### With validation
+
+`CheckboxGroup.Validation` can display success or error states with appropriate icons.
+
+```jsx live
+<Stack direction="vertical" gap="spacious">
+  <CheckboxGroup>
+    <CheckboxGroup.Label>Valid selection</CheckboxGroup.Label>
+    <FormControl>
+      <FormControl.Label>Option one</FormControl.Label>
+      <Checkbox value="one" />
+    </FormControl>
+    <FormControl>
+      <FormControl.Label>Option two</FormControl.Label>
+      <Checkbox value="two" />
+    </FormControl>
+    <CheckboxGroup.Validation variant="success">
+      Great choice!
+    </CheckboxGroup.Validation>
+  </CheckboxGroup>
+
+  <CheckboxGroup>
+    <CheckboxGroup.Label>Invalid selection</CheckboxGroup.Label>
+    <FormControl>
+      <FormControl.Label>Option one</FormControl.Label>
+      <Checkbox value="one" />
+    </FormControl>
+    <FormControl>
+      <FormControl.Label>Option two</FormControl.Label>
+      <Checkbox value="two" />
+    </FormControl>
+    <CheckboxGroup.Validation variant="error">
+      Please select at least one option
+    </CheckboxGroup.Validation>
+  </CheckboxGroup>
+</Stack>
+```
+
+### Visually hidden label
+
+When context is clear, labels can be visually hidden while remaining accessible to screen readers.
+
+```jsx live
+<CheckboxGroup>
+  <CheckboxGroup.Label visuallyHidden>Filter options</CheckboxGroup.Label>
+  <Stack direction="vertical" gap="regular">
+    <FormControl>
+      <FormControl.Label>Show all</FormControl.Label>
+      <Checkbox value="all" />
+    </FormControl>
+    <FormControl>
+      <FormControl.Label>Show active only</FormControl.Label>
+      <Checkbox value="active" />
+    </FormControl>
+  </Stack>
+</CheckboxGroup>
+```
+
+### Inline
+
+When space is limited, checkboxes can be arranged horizontally using the [Stack](/components/Stack) component.
+
+```jsx live
+<CheckboxGroup>
+  <CheckboxGroup.Label visuallyHidden>Filter options</CheckboxGroup.Label>
+  <CheckboxGroup.Caption>
+    Some inline checkboxes with a visually hidden label
+  </CheckboxGroup.Caption>
+  <Stack direction="horizontal" gap="normal" padding="none">
+    <FormControl>
+      <FormControl.Label>Choice one</FormControl.Label>
+      <Checkbox value="one" />
+    </FormControl>
+    <FormControl>
+      <FormControl.Label>Choice two</FormControl.Label>
+      <Checkbox value="two" />
+    </FormControl>
+    <FormControl>
+      <FormControl.Label>Choice three</FormControl.Label>
+      <Checkbox value="three" />
+    </FormControl>
+  </Stack>
+</CheckboxGroup>
+```
+
+## Component props
+
+### CheckboxGroup <Label>Required</Label>
+
+| Name       | Type                   | Default | Description                                                      |
+| :--------- | :--------------------- | :-----: | :--------------------------------------------------------------- |
+| `children` | `React.ReactElement[]` |         | CheckboxGroup components and FormControl components              |
+| `id`       | `string`               |         | Sets a custom id. If not provided, a unique id will be generated |
+
+`CheckboxGroup` extends the HTML `fieldset` element and supports all `fieldset` props.
+
+### CheckboxGroup.Label <Label>Required</Label>
+
+| Name             | Type      | Default | Description                             |
+| :--------------- | :-------- | :-----: | :-------------------------------------- |
+| `children`       | `string`  |         | Label text                              |
+| `visuallyHidden` | `boolean` | `false` | Hide label visually but keep accessible |
+
+`CheckboxGroup.Label` extends the HTML `legend` element and supports all `legend` props.
+
+### CheckboxGroup.Caption
+
+| Name       | Type     | Default | Description  |
+| :--------- | :------- | :-----: | :----------- |
+| `children` | `string` |         | Caption text |
+
+`CheckboxGroup.Caption` extends the `span` element and supports all `span` props.
+
+### CheckboxGroup.Validation
+
+| Name       | Type                     | Default | Description                        |
+| :--------- | :----------------------- | :-----: | :--------------------------------- |
+| `children` | `string`                 |         | Validation message                 |
+| `variant`  | `'success'` \| `'error'` |         | Sets the validation state and icon |
+
+`CheckboxGroup.Validation` extends the `span` element and supports all `span` props.
diff --git a/apps/docs/content/components/RadioGroup/index.mdx b/apps/docs/content/components/RadioGroup/index.mdx
@@ -0,0 +1,52 @@
+---
+title: RadioGroup
+description: Use RadioGroup to group related radio inputs with supporting content where only one option can be selected
+---
+
+import ComponentLayout from '../../../src/layouts/component-layout'
+export default ComponentLayout
+
+## Usage
+
+The `RadioGroup` family of components provide a way to group related [Radio](/components/Radio) components together with supporting content such as labels, captions, and validation messages. It creates a semantic fieldset structure that helps maintain proper form hierarchy and accessibility.
+
+> **Important**: When using Radio components within a RadioGroup, ensure you provide the same `name` prop to each Radio. This ensures they are correctly grouped and only one option can be selected at a time.
+
+## Components
+
+### Root
+
+The `RadioGroup` component wraps a group of radio inputs in a `fieldset`.
+
+### Label
+
+The `RadioGroup.Label` component renders as a `legend` and can be used to provide a heading for the group of radio inputs. The label must always be provided for accessibility purposes, but it can be visually hidden.
+
+### Caption
+
+Use `RadioGroup.Caption` to provide additional context or instructions for the group of radio inputs. The caption is automatically associated with the group through ARIA attributes.
+
+### Validation
+
+The `RadioGroup.Validation` component can be used to display success or error messages. It supports two variants:
+
+- `success`: Displays a success message with a check circle icon
+- `error`: Displays an error message with an alert icon
+
+## Accessibility
+
+RadioGroup enhances accessibility by:
+
+- Using semantic HTML through the `fieldset` and `legend` elements
+- Automatically associating captions and validation messages with the group using `aria-describedby`
+- Supporting visually hidden labels that remain accessible to screen readers
+- Providing clear visual indicators for validation states with supporting icons
+- Ensuring only one option can be selected when radio inputs share the same `name` attribute
+
+Any radio inputs within the group should be given their own appropriate labeling and accessibility attributes.
+
+## Related components
+
+- [Radio](/components/Radio): Used to render an individual radio control.
+- [FormControl](/components/FormControl): Used to group individual controls with an associated label.
+- [CheckboxGroup](/components/CheckboxGroup): Similar to `RadioGroup`, but used for organizing checkbox controls that allow multiple selections.