Adds a component to support checkbox and radio groups

.changeset/twenty-needles-sit.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+Adds ChoiceFieldset component

docs/content/ChoiceInputField.mdx

@@ -159,3 +159,9 @@ If the selectable option would be easier to understand with a visual, the `Choic
     hasFigmaComponent: false
   }}
 />
+
+## Related components
+
+- [ChoiceFieldset](/ChoiceFieldset)
+- [Checkbox](/Checkbox)
+- [Radio](/Radio)

docs/content/Radio.mdx

@@ -35,6 +35,8 @@ Please use a [Checkbox](/Checkbox) if the user needs to select more than one opt
 
 Use the `name` prop to group together related `Radio` components in a list.
 
+If you're not building something custom, you should use the [ChoiceFieldset](/ChoiceFieldset) component to render a group of radio inputs.
+
 ```jsx live
 <form>
   <Box sx={{p: 1, display: 'flex', alignItems: 'center'}}>

docs/src/@primer/gatsby-theme-doctocat/nav.yml

@@ -53,6 +53,8 @@
       url: /Buttons
     - title: Checkbox
       url: /Checkbox
+    - title: ChoiceFieldset
+      url: /ChoiceFieldset
     - title: ChoiceInputField
       url: /ChoiceInputField
     - title: CircleBadge

src/Autocomplete/AutocompleteMenu.tsx

@@ -1,14 +1,13 @@
 import React, {useContext, useEffect, useMemo, useRef, useState} from 'react'
+import {scrollIntoView} from '@primer/behaviors'
+import type {ScrollIntoViewOptions} from '@primer/behaviors'
 import {ActionList, ItemProps} from '../ActionList'
 import {useFocusZone} from '../hooks/useFocusZone'
 import {ComponentProps, MandateProps} from '../utils/types'
-import {Box, Spinner} from '../'
+import {Box, Spinner, useSSRSafeId} from '../'
 import {AutocompleteContext} from './AutocompleteContext'
 import {PlusIcon} from '@primer/octicons-react'
 import VisuallyHidden from '../_VisuallyHidden'
-import {uniqueId} from '@primer/behaviors/utils'
-import {scrollIntoView} from '@primer/behaviors'
-import type {ScrollIntoViewOptions} from '@primer/behaviors'
 
 type OnSelectedChange<T> = (item: T | T[]) => void
 type AutocompleteMenuItem = MandateProps<ItemProps, 'id'>
@@ -146,6 +145,7 @@ function AutocompleteMenu<T extends AutocompleteItemProps>(props: AutocompleteMe
   const listContainerRef = useRef<HTMLDivElement>(null)
   const [highlightedItem, setHighlightedItem] = useState<T>()
   const [sortedItemIds, setSortedItemIds] = useState<Array<number | string>>(items.map(({id: itemId}) => itemId))
+  const generatedUniqueId = useSSRSafeId(id)
 
   const selectableItems = useMemo(
     () =>
@@ -219,7 +219,7 @@ function AutocompleteMenu<T extends AutocompleteItemProps>(props: AutocompleteMe
               leadingVisual: () => <PlusIcon />,
               onAction: (item: T) => {
                 // TODO: make it possible to pass a leadingVisual when using `addNewItem`
-                addNewItem.handleAddItem({...item, id: item.id || uniqueId(), leadingVisual: undefined})
+                addNewItem.handleAddItem({...item, id: item.id || generatedUniqueId, leadingVisual: undefined})
 
                 if (selectionVariant === 'multiple') {
                   setInputValue('')
@@ -230,7 +230,14 @@ function AutocompleteMenu<T extends AutocompleteItemProps>(props: AutocompleteMe
           ]
         : [])
     ],
-    [sortedAndFilteredItemsToRender, addNewItem, setAutocompleteSuggestion, selectionVariant, setInputValue]
+    [
+      sortedAndFilteredItemsToRender,
+      addNewItem,
+      setAutocompleteSuggestion,
+      selectionVariant,
+      setInputValue,
+      generatedUniqueId
+    ]
   )
 
   useFocusZone(

src/ChoiceFieldset/ChoiceFieldCaption.tsx

@@ -0,0 +1,6 @@
+import React from 'react'
+import {ChoiceInputField} from '..'
+
+const ChoiceFieldCaption: React.FC = ({children}) => <ChoiceInputField.Caption>{children}</ChoiceInputField.Caption>
+
+export default ChoiceFieldCaption

src/ChoiceFieldset/ChoiceFieldLabel.tsx

@@ -0,0 +1,6 @@
+import React from 'react'
+import {ChoiceInputField} from '..'
+
+const ChoiceFieldLabel: React.FC = ({children}) => <ChoiceInputField.Label>{children}</ChoiceInputField.Label>
+
+export default ChoiceFieldLabel

src/ChoiceFieldset/ChoiceFieldset.tsx

@@ -0,0 +1,137 @@
+import React, {ComponentProps} from 'react'
+import {Box, useSSRSafeId} from '..'
+import createSlots from '../utils/create-slots'
+import {FormValidationStatus} from '../utils/types/FormValidationStatus'
+import ValidationAnimationContainer from '../_ValidationAnimationContainer'
+import InputValidation from '../_InputValidation'
+import ChoiceFieldsetListItem from './ChoiceFieldsetListItem'
+import ChoiceFieldsetDescription from './ChoiceFieldsetDescription'
+import ChoiceFieldsetLegend from './ChoiceFieldsetLegend'
+import ChoiceFieldsetList from './ChoiceFieldsetList'
+import ChoiceFieldsetValidation from './ChoiceFieldsetValidation'
+
+export interface ChoiceFieldsetProps<T = Record<string, FormValidationStatus>> {
+  children?: React.ReactNode
+  /**
+   * Whether the fieldset is NOT ready for user input
+   */
+  disabled?: boolean
+  /**
+   * The unique identifier for this fieldset. Used to associate the validation text with the fieldset
+   * If an ID is not passed, one will be automatically generated
+   */
+  id?: string
+  /**
+   * The unique identifier used to associate radio inputs with eachother
+   * If a name is not passed and the fieldset renders radio inputs, a name will be automatically generated
+   */
+  name?: string
+  /**
+   * The callback that is called when a user toggles a choice on or off
+   */
+  onSelect?: (selectedValues: string[]) => void
+  /**
+   * Whether this field must have a value for the user to complete their task
+   */
+  required?: boolean
+  /**
+   * The selected values
+   */
+  selected?: string[]
+  /**
+   * A map of validation statuses and their associated validation keys. When one of the validation keys is passed to the `validationResult` prop,
+   * the associated validation message will be rendered in the correct style
+   */
+  validationMap?: T
+  /**
+   * The key of the validation message to show
+   */
+  validationResult?: keyof T
+}
+
+export interface ChoiceFieldsetContext extends ChoiceFieldsetProps {
+  validationMessageId: string
+}
+
+const {Slots, Slot} = createSlots(['Description', 'ChoiceList', 'Legend', 'Validation'])
+export {Slot}
+
+const ChoiceFieldset = <T extends Record<string, FormValidationStatus>>({
+  children,
+  disabled,
+  id,
+  name,
+  onSelect,
+  required,
+  selected,
+  validationMap,
+  validationResult
+}: ChoiceFieldsetProps<T>) => {
+  const fieldsetId = useSSRSafeId(id)
+  const validationChildren: React.ReactElement[] | undefined | null = React.Children.map(children, child =>
+    React.isValidElement(child) && child.type === ChoiceFieldsetValidation ? child : null
+  )?.filter(Boolean)
+  const validationChildToRender = validationChildren?.find(child => child.props.validationKey === validationResult)
+  const validationMessageId = validationChildToRender ? `${fieldsetId}-validationMsg` : undefined
+
+  return (
+    <Slots
+      context={{
+        disabled,
+        name,
+        onSelect,
+        required,
+        selected,
+        validationMessageId
+      }}
+    >
+      {slots => {
+        const isLegendVisible = React.isValidElement(slots.Legend) && slots.Legend.props.isVisible
+
+        return (
+          <div>
+            <Box
+              as="fieldset"
+              border="none"
+              margin={0}
+              padding={0}
+              aria-describedby={[validationMessageId].filter(Boolean).join(' ')}
+            >
+              {React.Children.toArray(children).filter(
+                child => React.isValidElement(child) && child.type !== ChoiceFieldsetValidation
+              )}
+              <Box mb={isLegendVisible ? 3 : undefined}>
+                {slots.Legend}
+                {slots.Description}
+              </Box>
+              {slots.ChoiceList}
+            </Box>
+            {validationChildToRender && (
+              <Box mt={3}>
+                {validationMap && validationResult && validationMessageId && (
+                  <ValidationAnimationContainer show>
+                    <InputValidation validationStatus={validationMap[validationResult]} id={validationMessageId}>
+                      {validationChildToRender}
+                    </InputValidation>
+                  </ValidationAnimationContainer>
+                )}
+              </Box>
+            )}
+          </div>
+        )
+      }}
+    </Slots>
+  )
+}
+
+export type InputFieldComponentProps = ComponentProps<typeof ChoiceFieldset>
+export type {ChoiceFieldsetListProps} from './ChoiceFieldsetList'
+export type {ChoiceFieldsetLegendProps} from './ChoiceFieldsetLegend'
+export type {ChoiceFieldProps} from './ChoiceFieldsetListItem'
+export default Object.assign(ChoiceFieldset, {
+  Description: ChoiceFieldsetDescription,
+  Item: ChoiceFieldsetListItem,
+  Legend: ChoiceFieldsetLegend,
+  List: ChoiceFieldsetList,
+  Validation: ChoiceFieldsetValidation
+})

src/ChoiceFieldset/ChoiceFieldsetDescription.tsx

@@ -0,0 +1,15 @@
+import React from 'react'
+import {Text} from '..'
+import {ChoiceFieldsetContext, Slot} from './ChoiceFieldset'
+
+const ChoiceFieldsetDescription: React.FC = ({children}) => (
+  <Slot name="Description">
+    {({disabled}: ChoiceFieldsetContext) => (
+      <Text color={disabled ? 'fg.muted' : 'fg.default'} fontSize={1}>
+        {children}
+      </Text>
+    )}
+  </Slot>
+)
+
+export default ChoiceFieldsetDescription

src/ChoiceFieldset/ChoiceFieldsetLegend.tsx

@@ -0,0 +1,39 @@
+import React from 'react'
+import {Box} from '..'
+import VisuallyHidden from '../_VisuallyHidden'
+import {ChoiceFieldsetContext, Slot} from './ChoiceFieldset'
+
+export interface ChoiceFieldsetLegendProps {
+  /**
+   * Whether to visually hide the fieldset legend
+   */
+  visuallyHidden?: boolean
+}
+
+const ChoiceFieldsetLegend: React.FC<ChoiceFieldsetLegendProps> = ({children, visuallyHidden}) => (
+  <Slot name="Legend">
+    {({required, disabled}: ChoiceFieldsetContext) => (
+      <VisuallyHidden
+        as="legend"
+        isVisible={!visuallyHidden}
+        title={required ? 'required field' : undefined}
+        sx={{
+          color: disabled ? 'fg.muted' : undefined,
+          fontSize: 2,
+          padding: 0
+        }}
+      >
+        {required ? (
+          <Box display="flex" as="span">
+            <Box mr={1}>{children}</Box>
+            <span>*</span>
+          </Box>
+        ) : (
+          children
+        )}
+      </VisuallyHidden>
+    )}
+  </Slot>
+)
+
+export default ChoiceFieldsetLegend

src/ChoiceFieldset/ChoiceFieldsetList.tsx

@@ -0,0 +1,80 @@
+import React from 'react'
+import styled from 'styled-components'
+import {useSSRSafeId} from '..'
+import {get} from '../constants'
+import {Slot, ChoiceFieldsetContext} from './ChoiceFieldset'
+import ChoiceFieldsetListContext from './ChoiceFieldsetListContext'
+
+export interface ChoiceFieldsetListProps {
+  /**
+   * Whether multiple items or a single item can be selected
+   */
+  selectionVariant?: 'single' | 'multiple'
+}
+
+const List = styled.ul`
+  display: flex;
+  flex-direction: column;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+
+  > li + li {
+    margin-top: ${get('space.2')};
+  }
+`
+
+const getSelectedCheckboxes = (
+  value: string,
+  checked: boolean,
+  selectedValues: string[],
+  selectionVariant?: ChoiceFieldsetListProps['selectionVariant']
+): string[] => {
+  if (checked) {
+    return selectionVariant === 'multiple' ? [...selectedValues, value] : [value]
+  }
+
+  return selectedValues.filter(selectedValue => selectedValue !== value)
+}
+
+const ChoiceFieldsetList: React.FC<ChoiceFieldsetListProps> = ({selectionVariant, children}) => {
+  const ssrSafeUniqueName = useSSRSafeId()
+
+  return (
+    <Slot name="ChoiceList">
+      {({name, onSelect, disabled, selected = []}: ChoiceFieldsetContext) => {
+        return (
+          <ChoiceFieldsetListContext.Provider
+            value={{
+              disabled,
+              selected,
+              name: name || ssrSafeUniqueName,
+              onChange: e => {
+                const updatedSelections = getSelectedCheckboxes(
+                  e.currentTarget.value,
+                  e.currentTarget.checked,
+                  selected,
+                  selectionVariant
+                )
+                onSelect && onSelect(updatedSelections)
+              },
+              selectionVariant
+            }}
+          >
+            <List>
+              {React.Children.map(children, (child, i) => (
+                <li key={i}>{child}</li>
+              ))}
+            </List>
+          </ChoiceFieldsetListContext.Provider>
+        )
+      }}
+    </Slot>
+  )
+}
+
+ChoiceFieldsetList.defaultProps = {
+  selectionVariant: 'single'
+}
+
+export default ChoiceFieldsetList

src/ChoiceFieldset/ChoiceFieldsetListContext.tsx

@@ -0,0 +1,11 @@
+import {ChangeEventHandler, createContext} from 'react'
+
+const ChoiceFieldsetListContext = createContext<{
+  disabled?: boolean
+  name: string
+  onChange: ChangeEventHandler<HTMLInputElement>
+  selected?: string[]
+  selectionVariant?: 'single' | 'multiple'
+} | null>(null)
+
+export default ChoiceFieldsetListContext