SegmentedControl a11y fixes

.changeset/eleven-jokes-think.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+Addresses feedback from the accessibility team about our SegmentedControl component. These changes include an update to ActionMenu that allows u to specify the ID of the DOM node that labels the menu.

docs/content/SegmentedControl.mdx

@@ -9,16 +9,48 @@ storybook: '/react/storybook/?path=/story/components-segmentedcontrol'
 
 import data from '../../src/SegmentedControl/SegmentedControl.docs.json'
 
+<Note variant="warning">
+
+A `SegmentedControl` should not be used in a form as a replacement for something like a [RadioGroup](/RadioGroup) or [Select](/Select). See the [Accessibility section](https://primer.style/design/components/segmented-control#accessibility) of the SegmentedControl interface guidelines for more details.
+
+</Note>
+
 ## Examples
 
-### Uncontrolled (default)
+### With a label above and caption below
 
 ```jsx live
-<SegmentedControl aria-label="File view">
-  <SegmentedControl.Button defaultSelected>Preview</SegmentedControl.Button>
-  <SegmentedControl.Button>Raw</SegmentedControl.Button>
-  <SegmentedControl.Button>Blame</SegmentedControl.Button>
-</SegmentedControl>
+<FormControl>
+  <FormControl.Label id="scLabel-horiz" as="span">
+    File view
+  </FormControl.Label>
+  <SegmentedControl aria-labelledby="scLabel-horiz" aria-describedby="scCaption-horiz">
+    <SegmentedControl.Button defaultSelected>Preview</SegmentedControl.Button>
+    <SegmentedControl.Button>Raw</SegmentedControl.Button>
+    <SegmentedControl.Button>Blame</SegmentedControl.Button>
+  </SegmentedControl>
+  <FormControl.Caption id="scCaption-horiz">Change the way the file is viewed</FormControl.Caption>
+</FormControl>
+```
+
+### With a label and caption on the left
+
+```jsx live
+<Box display="flex">
+  <Box flexGrow={1}>
+    <Text fontSize={2} fontWeight="bold" id="scLabel-vert" display="block">
+      File view
+    </Text>
+    <Text color="fg.subtle" fontSize={1} id="scCaption-vert" display="block">
+      Change the way the file is viewed
+    </Text>
+  </Box>
+  <SegmentedControl aria-labelledby="scLabel-vert" aria-describedby="scCaption-vert">
+    <SegmentedControl.Button defaultSelected>Preview</SegmentedControl.Button>
+    <SegmentedControl.Button>Raw</SegmentedControl.Button>
+    <SegmentedControl.Button>Blame</SegmentedControl.Button>
+  </SegmentedControl>
+</Box>
 ```
 
 ### Controlled
@@ -109,40 +141,6 @@ render(Controlled)
 </SegmentedControl>
 ```
 
-### With a label and caption on the left
-
-```jsx live
-<Box display="flex">
-  <Box flexGrow={1}>
-    <Text fontSize={2} fontWeight="bold" id="scLabel-vert" display="block">
-      File view
-    </Text>
-    <Text color="fg.subtle" fontSize={1} id="scCaption-vert" display="block">
-      Change the way the file is viewed
-    </Text>
-  </Box>
-  <SegmentedControl aria-labelledby="scLabel-vert" aria-describedby="scCaption-vert">
-    <SegmentedControl.Button defaultSelected>Preview</SegmentedControl.Button>
-    <SegmentedControl.Button>Raw</SegmentedControl.Button>
-    <SegmentedControl.Button>Blame</SegmentedControl.Button>
-  </SegmentedControl>
-</Box>
-```
-
-### With a label above and caption below
-
-```jsx live
-<FormControl>
-  <FormControl.Label id="scLabel-horiz">File view</FormControl.Label>
-  <SegmentedControl aria-labelledby="scLabel-horiz" aria-describedby="scCaption-horiz">
-    <SegmentedControl.Button defaultSelected>Preview</SegmentedControl.Button>
-    <SegmentedControl.Button>Raw</SegmentedControl.Button>
-    <SegmentedControl.Button>Blame</SegmentedControl.Button>
-  </SegmentedControl>
-  <FormControl.Caption id="scCaption-horiz">Change the way the file is viewed</FormControl.Caption>
-</FormControl>
-```
-
 ### With something besides the first option selected
 
 ```jsx live

generated/components.json

@@ -2692,6 +2692,12 @@
               "defaultValue": "false",
               "description": "Whether the label should be visually hidden"
             },
+            {
+              "name": "as",
+              "type": "'label' | 'legend' | 'span'",
+              "defaultValue": "'label'",
+              "description": "The label element can be changed to a 'legend' when it's being used to label a fieldset, or a 'span' when it's being used to label an element that is not a form input. For example: when using a FormControl to render a labeled SegementedControl, the label should be a 'span'"
+            },
             {
               "name": "sx",
               "type": "SystemStyleObject"

src/ActionMenu.tsx

@@ -89,7 +89,12 @@ type MenuOverlayProps = Partial<OverlayProps> &
      */
     children: React.ReactNode
   }
-const Overlay: React.FC<React.PropsWithChildren<MenuOverlayProps>> = ({children, align = 'start', ...overlayProps}) => {
+const Overlay: React.FC<React.PropsWithChildren<MenuOverlayProps>> = ({
+  children,
+  align = 'start',
+  'aria-labelledby': ariaLabelledby,
+  ...overlayProps
+}) => {
   // we typecast anchorRef as required instead of optional
   // because we know that we're setting it in context in Menu
   const {anchorRef, renderAnchor, anchorId, open, onOpen, onClose} = React.useContext(MenuContext) as MandateProps<
@@ -117,7 +122,7 @@ const Overlay: React.FC<React.PropsWithChildren<MenuOverlayProps>> = ({children,
           value={{
             container: 'ActionMenu',
             listRole: 'menu',
-            listLabelledBy: anchorId,
+            listLabelledBy: ariaLabelledby || anchorId,
             selectionAttribute: 'aria-checked', // Should this be here?
             afterSelect: onClose,
           }}

src/FormControl/FormControl.docs.json

@@ -49,6 +49,12 @@
           "defaultValue": "false",
           "description": "Whether the label should be visually hidden"
         },
+        {
+          "name": "as",
+          "type": "'label' | 'legend' | 'span'",
+          "defaultValue": "'label'",
+          "description": "The label element can be changed to a 'legend' when it's being used to label a fieldset, or a 'span' when it's being used to label an element that is not a form input. For example: when using a FormControl to render a labeled SegementedControl, the label should be a 'span'"
+        },
         {
           "name": "sx",
           "type": "SystemStyleObject"

src/FormControl/_FormControlLabel.tsx

@@ -1,6 +1,6 @@
 import React from 'react'
 import {SxProp} from '../sx'
-import InputLabel from '../_InputLabel'
+import InputLabel, {LegendOrSpanProps, LabelProps} from '../_InputLabel'
 import {FormControlContext} from './FormControl'
 import {Slot} from './slots'
 
@@ -9,15 +9,12 @@ export type Props = {
    * Whether the label should be visually hidden
    */
   visuallyHidden?: boolean
+  id?: string
 } & SxProp
 
-const FormControlLabel: React.FC<React.PropsWithChildren<{htmlFor?: string; id?: string} & Props>> = ({
-  children,
-  htmlFor,
-  id,
-  visuallyHidden,
-  sx,
-}) => (
+const FormControlLabel: React.FC<
+  React.PropsWithChildren<{htmlFor?: string} & (LegendOrSpanProps | LabelProps) & Props>
+> = ({children, htmlFor, id, visuallyHidden, sx}) => (
   <Slot name="Label">
     {({disabled, id: formControlId, required}: FormControlContext) => (
       <InputLabel

src/SegmentedControl/SegmentedControl.stories.tsx

@@ -112,7 +112,7 @@ export const Playground: Story<Args> = args => (
     variant={parseVariantFromArgs(args)}
     size={args.size}
   >
-    <SegmentedControl.Button selected aria-label={'Preview'} leadingIcon={EyeIcon}>
+    <SegmentedControl.Button defaultSelected aria-label={'Preview'} leadingIcon={EyeIcon}>
       Preview
     </SegmentedControl.Button>
     <SegmentedControl.Button aria-label={'Raw'} leadingIcon={FileCodeIcon}>

src/SegmentedControl/SegmentedControl.test.tsx

@@ -45,7 +45,7 @@ describe('SegmentedControl', () => {
     SegmentedControl,
   })
 
-  it('renders with a selected segment', () => {
+  it('renders with a selected segment - controlled', () => {
     const {getByText} = render(
       <SegmentedControl aria-label="File view">
         {segmentData.map(({label}, index) => (
@@ -61,6 +61,22 @@ describe('SegmentedControl', () => {
     expect(selectedButton?.getAttribute('aria-current')).toBe('true')
   })
 
+  it('renders with a selected segment - uncontrolled', () => {
+    const {getByText} = render(
+      <SegmentedControl aria-label="File view">
+        {segmentData.map(({label}, index) => (
+          <SegmentedControl.Button defaultSelected={index === 1} key={label}>
+            {label}
+          </SegmentedControl.Button>
+        ))}
+      </SegmentedControl>,
+    )
+
+    const selectedButton = getByText('Raw').closest('button')
+
+    expect(selectedButton?.getAttribute('aria-current')).toBe('true')
+  })
+
   it('renders the dropdown variant', () => {
     act(() => {
       matchMedia.useMediaQuery(viewportRanges.narrow)

src/SegmentedControl/SegmentedControl.tsx

@@ -68,7 +68,7 @@ const Root: React.FC<React.PropsWithChildren<SegmentedControlProps>> = ({
   const selectedSegments = React.Children.toArray(children).map(
     child =>
       React.isValidElement<SegmentedControlButtonProps | SegmentedControlIconButtonProps>(child) &&
-      child.props.selected,
+      (child.props.defaultSelected || child.props.selected),
   )
   const hasSelectedButton = selectedSegments.some(isSelected => isSelected)
   const selectedIndexExternal = hasSelectedButton ? selectedSegments.indexOf(true) : 0
@@ -102,40 +102,48 @@ const Root: React.FC<React.PropsWithChildren<SegmentedControlProps>> = ({
   if (!ariaLabel && !ariaLabelledby) {
     // eslint-disable-next-line no-console
     console.warn(
-      'Use the `aria-label` or `aria-labelledby` prop to provide an accessible label for assistive technology',
+      'Use the `aria-label` or `aria-labelledby` prop to provide an accessible label for assistive technologies',
     )
   }
 
   return responsiveVariant === 'dropdown' ? (
     // Render the 'dropdown' variant of the SegmentedControlButton or SegmentedControlIconButton
-    <ActionMenu>
-      <ActionMenu.Button leadingIcon={getChildIcon(selectedChild)}>{getChildText(selectedChild)}</ActionMenu.Button>
-      <ActionMenu.Overlay>
-        <ActionList selectionVariant="single">
-          {React.Children.map(children, (child, index) => {
-            const ChildIcon = getChildIcon(child)
-            // Not a valid child element - skip rendering
-            if (!React.isValidElement<SegmentedControlButtonProps | SegmentedControlIconButtonProps>(child)) {
-              return null
-            }
+    <>
+      <ActionMenu>
+        {/*
+          The aria-label is only provided as a backup when the designer or engineer neglects to show a label for the SegmentedControl.
+          The best thing to do is to have a visual label who's id is referenced using the `aria-labelledby` prop.
+        */}
+        <ActionMenu.Button aria-label={ariaLabel} leadingIcon={getChildIcon(selectedChild)}>
+          {getChildText(selectedChild)}
+        </ActionMenu.Button>
+        <ActionMenu.Overlay aria-labelledby={ariaLabelledby}>
+          <ActionList selectionVariant="single">
+            {React.Children.map(children, (child, index) => {
+              const ChildIcon = getChildIcon(child)
+              // Not a valid child element - skip rendering
+              if (!React.isValidElement<SegmentedControlButtonProps | SegmentedControlIconButtonProps>(child)) {
+                return null
+              }
 
-            return (
-              <ActionList.Item
-                key={`segmented-control-action-btn-${index}`}
-                selected={index === selectedIndex}
-                onSelect={(event: React.MouseEvent<HTMLLIElement> | React.KeyboardEvent<HTMLLIElement>) => {
-                  isUncontrolled && setSelectedIndexInternalState(index)
-                  onChange && onChange(index)
-                  child.props.onClick && child.props.onClick(event as React.MouseEvent<HTMLLIElement>)
-                }}
-              >
-                {ChildIcon && <ChildIcon />} {getChildText(child)}
-              </ActionList.Item>
-            )
-          })}
-        </ActionList>
-      </ActionMenu.Overlay>
-    </ActionMenu>
+              return (
+                <ActionList.Item
+                  key={`segmented-control-action-btn-${index}`}
+                  selected={index === selectedIndex}
+                  onSelect={(event: React.MouseEvent<HTMLLIElement> | React.KeyboardEvent<HTMLLIElement>) => {
+                    isUncontrolled && setSelectedIndexInternalState(index)
+                    onChange && onChange(index)
+                    child.props.onClick && child.props.onClick(event as React.MouseEvent<HTMLLIElement>)
+                  }}
+                >
+                  {ChildIcon && <ChildIcon />} {getChildText(child)}
+                </ActionList.Item>
+              )
+            })}
+          </ActionList>
+        </ActionMenu.Overlay>
+      </ActionMenu>
+    </>
   ) : (
     // Render a segmented control
     <SegmentedControlList