add CheckboxGroup docs

packages/web-ui/src/BaseCheckboxGroup/BaseCheckboxGroup.props.ts

@@ -10,18 +10,18 @@ export interface BaseCheckboxGroupProps extends ComponentPropsWithoutRef<'fields
   value?: BaseCheckboxGroupContextValue['value'];
   onValueChange?: (value: Array<string>) => void;
   /**
-   * The label for the radio group. This should contain the question being
-   * answered by the radio group.
+   * The label for the checkbox group. This should contain the question being
+   * answered by the checkbox group.
    *
    * If you don't include a label you need to ensure you use the `aria-label`
-   * or `aria-labelledby` prop to properly associate a label with the radio
+   * or `aria-labelledby` prop to properly associate a label with the checkbox
    * group.
    */
   label?: ReactNode;
   /**
-   * Helper text for the radio group. Provides a hint such as specific
-   * requirements for what to choose. When displayed, child `Radio` or
-   * `RadioTile` components will not display `helperText`.
+   * Helper text for the checkbox group. Provides a hint such as specific
+   * requirements for what to choose. When displayed, child `Checkbox` or
+   * `CheckboxTile` components will not display `helperText`.
    */
   helperText?: ReactNode;
   /**
@@ -42,8 +42,8 @@ export interface BaseCheckboxGroupProps extends ComponentPropsWithoutRef<'fields
    */
   showErrorMessageIcon?: boolean;
   /**
-   * Set the width of the RadioGroup children, separate to the width of the
-   * entire RadioGroup.
+   * Set the width of the CheckboxGroup children, separate to the width of the
+   * entire CheckboxGroup.
    */
   contentWidth?: BoxProps['width'];
 }

packages/web-ui/src/Checkbox/Checkbox.docs.mdx

@@ -36,6 +36,31 @@ const [checked, setChecked] = React.useState(false);
 <Checkbox value="1" label="One" checked={checked} onCheckedChange={c => setChecked(c)} />
 ```
 
+## Keyboard interactions
+
+<Stack spacing={1} divider={<Divider />}>
+  <Box display="flex" alignItems="baseline">
+    <Box width={300}>
+      <Text component="span" variant="legalNote">
+        {'Key'}
+      </Text>
+    </Box>
+    <Text component="span" variant="legalNote">
+      {'Description'}
+    </Text>
+  </Box>
+  {[{ key: 'Space', description: 'Checks/unchecks the checkbox.' }].map(kbi => (
+    <Box display="flex" alignItems="baseline">
+      <Box width={300}>
+        <kbd>{kbi.key}</kbd>
+      </Box>
+      <Text component="span" variant="body">
+        {kbi.description}
+      </Text>
+    </Box>
+  ))}
+</Stack>
+
 ## Props
 
 <ArgTypes of={Stories} />

packages/web-ui/src/CheckboxGroup/CheckboxGroup.docs.mdx

@@ -0,0 +1,81 @@
+import { Meta, Description, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './CheckboxGroup.stories';
+import { Stack } from '../Stack';
+import { Box } from '../Box';
+import { Text } from '../Text';
+import { Divider } from '../Divider';
+
+<Meta of={Stories} />
+
+# CheckboxGroup
+
+<Description of={Stories} />
+
+## Contents
+
+- [Alternatives](#alternatives)
+- [Accessibility](#accessibility)
+- [Helper text](#helper-text)
+- [Error message](#error-message)
+- [Content width](#content-width)
+- [Controlled](#controlled)
+- [Props](#props)
+
+<Canvas of={Stories.Workshop} />
+
+## Alternatives
+
+- [CheckboxGridGroup](?path=/docs/components-checkboxgridgroup--documentation) - For presenting checkboxes in columns or a grid layout.
+- [RadioGroup](?path=/docs/components-radiogroup--documentation) - For single-select
+- [RadioGridGroup](?path=/docs/components-radiogridgroup--documentation) - For single-select in columns or a grid layout.
+
+## Accessibility
+
+The necessary aria props, such as `aria-labelledby`, `aria-describedby` and
+`aria-errormessage` are handled internally, however you can pass these and
+other aria props, such as `aria-label`, to the `CheckboxGroup`, `Checkbox` &
+`CheckboxTile` components yourself if you need to.
+
+## Helper text
+
+The Checkbox group can display a secondary message as a helper text. This can be
+either above or below the group's checkbox items. While the checkbox items can also
+display a helper text, these will not be displayed if the checkbox group has a
+helper text.
+
+<Canvas of={Stories.CheckboxHelperText} />
+
+## Error message
+
+You can display an error using the `error` & `errorMessage` props.
+
+<Canvas of={Stories.ShowingError} />
+
+## Content width
+
+The width of the `CheckboxGroup` should be set by the parent layout, however it is
+possible to independently set the width of the children using `contentWidth`
+prop. This property is most useful when using the `CheckboxGroup` with the
+`CheckboxTile` component.
+
+By default it will set the width of the children to fit their content, however
+you can set it to a specific width, or to `100%` to take up the full width of
+the `CheckboxGroup`.
+
+This is a responsive property, so you are able to set different widths for
+different breakpoints.
+
+<Canvas of={Stories.ContentWidth} />
+
+## Controlled
+
+A controlled value can be provided using the value prop, which accepts a string
+array, corresponding to the value props of each child `Checkbox`. The
+`onValueChange` event is fired when the user selects or deselects a `Checkbox`
+child of the group.
+
+<Canvas of={Stories.Controlled} />
+
+## Props
+
+<ArgTypes of={Stories} />

packages/web-ui/src/CheckboxGroup/CheckboxGroup.stories.tsx

@@ -5,6 +5,9 @@ import { Flex } from '../Flex';
 import { Text } from '../Text';
 import { Checkbox } from '../Checkbox';
 import { CheckboxTile } from '../CheckboxTile';
+import { useState } from 'react';
+import { Box } from '../Box';
+import { colors } from '@utilitywarehouse/colour-system';
 
 const meta: Meta<typeof CheckboxGroup> = {
   title: 'Web UI / Components / Checkbox / CheckboxGroup',
@@ -75,3 +78,77 @@ export const Controlled: Story = {
     );
   },
 };
+
+export const CheckboxHelperText: Story = {
+  name: 'Checkbox HelperText',
+  render: args => {
+    return (
+      <CheckboxGroup {...args}>
+        <Checkbox value="1" label="One" helperText="One helper text" />
+        <Checkbox value="2" label="Two" helperText="Two helper text" />
+        <Checkbox value="3" label="Three" helperText="Three helper text" />
+      </CheckboxGroup>
+    );
+  },
+  args: {
+    helperText: 'Please choose wisely.',
+  },
+};
+
+export const ShowingError: Story = {
+  name: 'Error message',
+  render: args => {
+    const [selected, setSelected] = useState<Array<string>>([]);
+    return (
+      <CheckboxGroup
+        {...args}
+        value={selected}
+        onValueChange={setSelected}
+        error={selected.length < 2}
+      >
+        <Checkbox value="1" label="Bear" />
+        <Checkbox value="2" label="Koala" />
+        <Checkbox value="3" label="Wolf" />
+        <Checkbox value="4" label="Horse" />
+        <Checkbox value="5" label="Chicken" />
+        <Checkbox value="6" label="Peacock" />
+      </CheckboxGroup>
+    );
+  },
+  args: {
+    errorMessage: 'Please pick two.',
+    label: 'What are your two favourite animals?',
+    helperTextPosition: 'bottom',
+  },
+};
+
+export const ContentWidth: Story = {
+  name: 'Content Width',
+  render: args => {
+    return (
+      <CheckboxGroup {...args} helperText="Setting the width of the children elements">
+        <CheckboxTile value="1" label="One" />
+        <CheckboxTile value="2" label="Two" />
+        <CheckboxTile value="3" label="Three" />
+      </CheckboxGroup>
+    );
+  },
+  args: { contentWidth: '200px' },
+};
+
+export const Wrap: Story = {
+  name: 'Wrap',
+  render: args => {
+    return (
+      <Box height={800} width={400} padding={2} border="2px solid" borderColor={colors.grey500}>
+        <CheckboxGroup {...args} direction="row" helperText="Child elements will wrap by default">
+          <CheckboxTile value="1" label="One" />
+          <CheckboxTile value="2" label="Two" />
+          <CheckboxTile value="3" label="Three" />
+          <CheckboxTile value="4" label="Four" />
+          <CheckboxTile value="5" label="Five" />
+        </CheckboxGroup>
+      </Box>
+    );
+  },
+};

packages/web-ui/src/CheckboxGroup/CheckboxGroup.tsx

@@ -20,6 +20,16 @@ const StyledContentContainer = styled(Flex)({
   },
 });
 
+/**
+ * Set of interactive buttons where multiple options can be selected at a time.
+ * The `CheckboxGroup` uses a fieldset to group related `Checkbox` controls.
+ *
+ * The `CheckboxGroup` is responsible for handling the value, helper text, error
+ * state, error message, and disabled state, as well as determining the presentation and
+ * selection of the items in the list.
+ *
+ * > This component does not need to be wrapped in a `ThemeProvider` and can be used standalone with other component libraries.
+ */
 export const CheckboxGroup = React.forwardRef<HTMLFieldSetElement, CheckboxGroupProps>(
   ({ contentWidth = 'fit-content', direction = 'column', children, className, ...props }, ref) => {
     return (

packages/web-ui/src/RadioGroup/RadioGroup.docs.mdx

@@ -32,6 +32,8 @@ import { Divider } from '../Divider';
 ## Alternatives
 
 - [RadioGridGroup](?path=/docs/components-radiogridgroup--documentation) - For presenting radios in columns or a grid layout.
+- [CheckboxGroup](?path=/docs/components-checkboxgroup--documentation) - For multi-select.
+- [CheckboxGridGroup](?path=/docs/components-checkboxgridgroup--documentation) - For multi-select in columns or grid layout.
 
 ## Accessibility