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