feat(toggle): handle indeterminate state in a select-all checkbox (#161)

Add support for displaying a checkbox with a small dash instead of a tick to indicate that the
option is not exactly checked or unchecked

Author: BalbinaK

packages/toggle/docs/Toggle.mdx

@@ -124,6 +124,77 @@ function Example() {
 }
 ```
 
+## Checkbox with indeterminate state
+
+Sometimes we need to indicate that the state of a single checkbox is
+indeterminate, or "partially checked". The checkbox will appear with a small
+dash instead of a tick to indicate that the option is not exactly checked or
+unchecked.
+
+```jsx example
+function Example() {
+  const [selectAllChecked, setSelectAllChecked] = React.useState(false);
+  const [selectedOptions, setSelectedOptions] = React.useState([
+    { label: 'Apple pie', value: 'apple pie' },
+    { label: 'Pavlova', value: 'pavlova' },
+  ]);
+
+  const options = [
+    { label: 'Apple pie', value: 'apple pie' },
+    { label: 'Carrot cake', value: 'carrot cake' },
+    { label: 'Pavlova', value: 'pavlova' },
+  ];
+
+  const handleSelectAll = (checked) => {
+    if (checked === false) {
+      setSelectedOptions([]);
+    } else {
+      setSelectedOptions(options);
+    }
+    setSelectAllChecked(checked);
+  };
+
+  const handleSelect = (selected) => {
+    let updatedSelected = selectedOptions;
+
+    if (selectedOptions.some((option) => option.value === selected.value)) {
+      updatedSelected = selectedOptions.filter(
+        (option) => option.value !== selected.value,
+      );
+    } else {
+      updatedSelected = [...selectedOptions, selected];
+    }
+
+    if (selectedOptions.length === options.length) setSelectAllChecked(false);
+    if (updatedSelected.length === options.length) setSelectAllChecked(true);
+
+    setSelectedOptions(updatedSelected);
+  };
+
+  return (
+    <>
+      <Toggle
+        onChange={handleSelectAll}
+        checked={selectAllChecked}
+        type="checkbox"
+        label="Select all desserts"
+        indeterminate={
+          selectedOptions.length > 0 &&
+          selectedOptions.length !== options.length
+        }
+      />
+      <Toggle
+        title="Favourite desserts"
+        type="checkbox"
+        selected={selectedOptions}
+        options={options}
+        onChange={handleSelect}
+      />
+    </>
+  );
+}
+```
+
 ## Toggle with multiple options
 
 We've already had a look at checkboxes, but Toggle can also render radio options

packages/toggle/src/component.tsx

@@ -40,7 +40,8 @@ export function Toggle(props: ToggleProps) {
   const isInvalid = props.invalid;
   const isRadioGroup = props.type === 'radio' || props.type === 'radio-button';
 
-  const isControlled = !!props.selected || !!props.checked;
+  const isControlled =
+    props.selected !== undefined || props.checked !== undefined;
 
   return (
     <fieldset
@@ -72,6 +73,7 @@ export function Toggle(props: ToggleProps) {
             label={props.label}
             checked={props.checked}
             defaultChecked={props.defaultChecked}
+            indeterminate={props.indeterminate}
             // @ts-ignore TODO: typecheck
             onChange={(e: boolean) => props.onChange(e)}
             name={`${id}:toggle`}

packages/toggle/src/item.tsx

@@ -6,6 +6,7 @@ interface ItemProps extends Pick<HTMLInputElement, 'type' | 'name'> {
   controlled: boolean;
   option?: ToggleEntry;
   children?: React.ReactNode;
+  indeterminate?: boolean;
   checked?: boolean;
   value?: string; // value for dead toggle
   defaultChecked?: boolean;
@@ -26,19 +27,30 @@ export function Item({
   invalid,
   value,
   helpId,
+  indeterminate = false,
   checked,
   defaultChecked,
   noVisibleLabel,
   labelClassName,
   ...props
 }: ItemProps) {
   const id = useId();
+  const checkboxRef = React.useRef<HTMLInputElement | null>(null);
 
   const labelContent = !children ? label || option?.label : children;
 
+  React.useEffect(() => {
+    if (!checkboxRef.current) {
+      return;
+    }
+    // 'indeterminate' state of checkbox cannot be assigned via HTML: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes
+    checkboxRef.current.indeterminate = indeterminate;
+  }, [indeterminate, checkboxRef]);
+
   return (
     <>
       <input
+        ref={checkboxRef}
         id={id}
         checked={controlled ? checked : undefined}
         defaultChecked={defaultChecked}

packages/toggle/src/props.ts

@@ -84,4 +84,9 @@ export interface ToggleProps {
    * Whether label should be invisible
    */
   noVisibleLabel?: boolean;
+  /**
+   * Whether a single option is indeterminate, or "partially checked."
+   * The checkbox will appear with a small dash instead of a tick to indicate that the option is not exactly checked or unchecked.
+   */
+  indeterminate?: boolean;
 }

packages/toggle/stories/Checkbox.stories.tsx

@@ -1,10 +1,12 @@
+import React from 'react';
 import { useState } from 'react';
 import { Toggle } from '../src';
 
 const metadata = { title: 'Forms/Toggle/Checkbox' };
 export default metadata;
 
-const options = [
+type Option = { label: string; value: string };
+const options: Option[] = [
   { label: 'Apple', value: 'apple' },
   { label: 'Microsoft', value: 'microsoft' },
   { label: 'Amazon', value: 'amazon' },
@@ -56,6 +58,59 @@ export const SingleOptionCheckedUncontrolledDefault = () => {
   );
 };
 
+export const IndeterminateState = () => {
+  const [selectAllChecked, setSelectAllChecked] = useState(false);
+  const [selectedOptions, setSelectedOptions] = useState<Option[]>([]);
+
+  const handleSelectAll = (checked: boolean) => {
+    if (checked === false) {
+      setSelectedOptions([]);
+    } else {
+      setSelectedOptions(options);
+    }
+    setSelectAllChecked(checked);
+  };
+
+  const handleSelect = (selected: Option) => {
+    let updatedSelected = selectedOptions;
+
+    if (selectedOptions.some((option) => option.value === selected.value)) {
+      updatedSelected = selectedOptions.filter(
+        (option) => option.value !== selected.value,
+      );
+    } else {
+      updatedSelected = [...selectedOptions, selected];
+    }
+
+    if (selectedOptions.length === options.length) setSelectAllChecked(false);
+    if (updatedSelected.length === options.length) setSelectAllChecked(true);
+
+    setSelectedOptions(updatedSelected);
+  };
+
+  return (
+    <>
+      <Toggle
+        onChange={handleSelectAll}
+        checked={selectAllChecked}
+        type="checkbox"
+        label="Select all companies"
+        indeterminate={
+          selectedOptions.length > 0 &&
+          selectedOptions.length !== options.length
+        }
+      />
+      <Toggle
+        type="checkbox"
+        title="Companies"
+        options={options}
+        selected={selectedOptions}
+        onChange={handleSelect}
+      />
+    </>
+  );
+};
+
 export const SingleOptionHelpText = () => {
   return (
     <Toggle