Address additional ToggleSwitch a11y feedback

.changeset/honest-gorillas-drive.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+Address additional ToggleSwitch a11y feedback

script/test-e2e

@@ -1,10 +1,11 @@
 #!/bin/bash
 
+args="$@"
 set -x
 
 docker run --rm \
  --network host \
  -v $(pwd):/workspace \
  -w /workspace \
  -it mcr.microsoft.com/playwright:v1.37.0-jammy \
- /bin/bash -c "npm install && STORYBOOK_URL=http://host.docker.internal:6006 npx playwright test $@"
+ /bin/bash -c "npm install && STORYBOOK_URL=http://host.docker.internal:6006 npx playwright test $args"

src/ToggleSwitch/ToggleSwitch.docs.json

@@ -65,7 +65,13 @@
  "type": "'start' | 'end'",
  "defaultValue": "'start'",
  "description": "<div>Whether the \"on\" and \"off\" labels should appear before or after the switch.</div> <div> <Text fontWeight=\"bold\">This should only be changed when the switch's alignment needs to be adjusted.</Text> For example: It needs to be left-aligned because the label appears above it and the caption appears below it. </div>"
+ },
+ {
+ "name": "loadingLabelDelay",
+ "type": "number",
+ "defaultValue": "2000",
+ "description": "When the switch is in the loading state, this value controls the amount of delay in milliseconds before the word \"Loading\" is announced to screen readers."
  }
  ],
  "subcomponents": []
-}
+}

src/ToggleSwitch/ToggleSwitch.features.stories.tsx

@@ -1,8 +1,9 @@
-import React from 'react'
-import ToggleSwitch from './ToggleSwitch'
+import React, {useState} from 'react'
+import ToggleSwitch, {ToggleSwitchProps} from './ToggleSwitch'
 import {Box, Text} from '..'
 import {action} from '@storybook/addon-actions'
 import ToggleSwitchStoryWrapper from './ToggleSwitchStoryWrapper'
+import {StoryFn} from '@storybook/react'
 
 export default {
  title: 'Components/ToggleSwitch/Features',
@@ -67,6 +68,59 @@ export const Loading = () => (
  </ToggleSwitchStoryWrapper>
 )
 
+type LoadingWithDelayProps = {
+ loadingDelay: number
+}
+
+export const LoadingWithDelay: StoryFn<ToggleSwitchProps & LoadingWithDelayProps> = args => {
+ const {loadingDelay, loadingLabelDelay} = args
+
+ const [isLoading, setIsLoading] = useState(false)
+ const [timeoutId, setTimeoutId] = useState<number | null>(null)
+
+ const handleToggleClick = () => {
+ setIsLoading(true)
+
+ if (timeoutId) {
+ clearTimeout(timeoutId)
+ setTimeoutId(null)
+ }
+
+ setTimeoutId(setTimeout(() => setIsLoading(false), loadingDelay) as unknown as number)
+ }
+
+ return (
+ <ToggleSwitchStoryWrapper>
+ <Text id="toggle" fontWeight={'bold'} fontSize={1}>
+ Toggle label
+ </Text>
+ <ToggleSwitch
+ loading={isLoading}
+ loadingLabelDelay={loadingLabelDelay}
+ aria-labelledby="toggle"
+ onClick={handleToggleClick}
+ />
+ </ToggleSwitchStoryWrapper>
+ )
+}
+
+LoadingWithDelay.args = {
+ loadingDelay: 5000,
+ loadingLabelDelay: 2000,
+}
+LoadingWithDelay.argTypes = {
+ loadingDelay: {
+ control: {
+ type: 'number',
+ },
+ },
+ loadingLabelDelay: {
+ control: {
+ type: 'number',
+ },
+ },
+}
+
 export const LabelEnd = () => (
  <ToggleSwitchStoryWrapper>
  <Text id="toggle" fontWeight={'bold'} fontSize={1}>

src/ToggleSwitch/ToggleSwitch.test.tsx

@@ -1,5 +1,5 @@
 import React from 'react'
-import {render} from '@testing-library/react'
+import {render, waitFor} from '@testing-library/react'
 import ToggleSwitch from './'
 import {behavesAsComponent, checkExports, checkStoriesForAxeViolations} from '../utils/testing'
 import userEvent from '@testing-library/user-event'
@@ -55,7 +55,7 @@ describe('ToggleSwitch', () => {
  expect(toggleSwitch).toHaveAttribute('aria-pressed', 'false')
  })
 
- it("renders a switch who's state is loading", async () => {
+ it('renders a switch whose state is loading', async () => {
  const user = userEvent.setup()
  const {getByLabelText, container} = render(
  <>
@@ -103,6 +103,22 @@ describe('ToggleSwitch', () => {
  expect(toggleSwitch).toHaveAttribute('aria-pressed', 'true')
  })
 
+ it('ensures the status label cannot toggle a disabled switch', async () => {
+ const user = userEvent.setup()
+ const {getByLabelText, getByText} = render(
+ <>
+ <div id="switchLabel">{SWITCH_LABEL_TEXT}</div>
+ <ToggleSwitch aria-labelledby="switchLabel" disabled />
+ </>,
+ )
+ const toggleSwitch = getByLabelText(SWITCH_LABEL_TEXT)
+ const toggleSwitchStatusLabel = getByText('Off')
+
+ expect(toggleSwitch).toHaveAttribute('aria-pressed', 'false')
+ await user.click(toggleSwitchStatusLabel)
+ expect(toggleSwitch).toHaveAttribute('aria-pressed', 'false')
+ })
+
  it('switches from off to on with a controlled prop', async () => {
  const user = userEvent.setup()
  const ControlledSwitchComponent = () => {
@@ -180,5 +196,19 @@ describe('ToggleSwitch', () => {
  expect(ref).toHaveBeenCalledWith(expect.any(HTMLButtonElement))
  })
 
+ it('displays a loading label', async () => {
+ const TEST_ID = 'a test id'
+
+ const {getByTestId} = render(
+ <>
+ <span id="label">label</span>
+ <ToggleSwitch data-testid={TEST_ID} aria-labelledby="label" loadingLabelDelay={0} loading />
+ </>,
+ )
+
+ const toggleSwitch = getByTestId(TEST_ID)
+ await waitFor(() => expect(toggleSwitch).toHaveTextContent('Loading'))
+ })
+
  checkStoriesForAxeViolations('ToggleSwitch.features', '../ToggleSwitch/')
 })

src/ToggleSwitch/ToggleSwitch.tsx

@@ -1,4 +1,5 @@
 import React, {MouseEventHandler, useCallback, useEffect} from 'react'
+import {useId} from '../hooks/useId'
 import styled, {css} from 'styled-components'
 import {variant} from 'styled-system'
 import Box from '../Box'
@@ -8,11 +9,14 @@ import {get} from '../constants'
 import {useProvidedStateOrCreate} from '../hooks'
 import sx, {BetterSystemStyleObject, SxProp} from '../sx'
 import {CellAlignment} from '../DataTable/column'
+import VisuallyHidden from '../_VisuallyHidden'
 
 const TRANSITION_DURATION = '80ms'
 const EASE_OUT_QUAD_CURVE = 'cubic-bezier(0.5, 1, 0.89, 1)'
 
 export interface ToggleSwitchProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'>, SxProp {
+ /** The id of the DOM node that labels the switch */
+ ['aria-labelledby']: string
  /** Uncontrolled - whether the switch is turned on */
  defaultChecked?: boolean
  /** Whether the switch is ready for user input */
@@ -31,6 +35,9 @@ export interface ToggleSwitchProps extends Omit<React.HTMLAttributes<HTMLDivElem
  * **This should only be changed when the switch's alignment needs to be adjusted.** For example: It needs to be left-aligned because the label appears above it and the caption appears below it.
  */
  statusLabelPosition?: CellAlignment
+ /** If the switch is in the loading state, this value controls the amount of delay in milliseconds before
+ * the word "Loading" is announced to screen readers. Default: 2000. */
+ loadingLabelDelay?: number
 }
 
 const sizeVariants = variant({
@@ -127,8 +134,12 @@ const SwitchButton = styled.button<SwitchButtonProps>`
  }
 
  ${props => {
- if (props.disabled) {
+ if (props['aria-disabled']) {
  return css`
+ @media (forced-colors: active) {
+ border-color: GrayText;
+ }
+
  background-color: ${get('colors.switchTrack.disabledBg')};
  border-color: transparent;
  cursor: not-allowed;
@@ -166,11 +177,12 @@ const SwitchButton = styled.button<SwitchButtonProps>`
  ${sx}
  ${sizeVariants}
 `
-const ToggleKnob = styled.div<{checked?: boolean; disabled?: boolean}>`
+const ToggleKnob = styled.div<{checked?: boolean; 'aria-disabled': React.AriaAttributes['aria-disabled']}>`
  background-color: ${get('colors.switchKnob.bg')};
  border-width: 1px;
  border-style: solid;
- border-color: ${props => (props.disabled ? get('colors.switchTrack.disabledBg') : get('colors.switchKnob.border'))};
+ border-color: ${props =>
+ props['aria-disabled'] ? get('colors.switchTrack.disabledBg') : get('colors.switchKnob.border')};
  border-radius: calc(${get('radii.2')} - 1px); /* -1px to account for 1px border around the control */
  width: 50%;
  position: absolute;
@@ -187,8 +199,12 @@ const ToggleKnob = styled.div<{checked?: boolean; disabled?: boolean}>`
  }
 
  ${props => {
- if (props.disabled) {
+ if (props['aria-disabled']) {
  return css`
+ @media (forced-colors: active) {
+ color: GrayText;
+ }
+
  border-color: ${get('colors.switchTrack.disabledBg')};
  `
  }
@@ -219,27 +235,63 @@ const ToggleSwitch = React.forwardRef<HTMLButtonElement, React.PropsWithChildren
  onClick,
  size = 'medium',
  statusLabelPosition = 'start',
+ loadingLabelDelay = 2000,
  sx: sxProp,
  ...rest
  } = props
  const isControlled = typeof checked !== 'undefined'
  const [isOn, setIsOn] = useProvidedStateOrCreate<boolean>(checked, onChange, Boolean(defaultChecked))
  const acceptsInteraction = !disabled && !loading
+
+ const [loadingLabelTimeoutId, setLoadingLabelTimeoutId] = React.useState<number | null>(null)
+ const [isLoadingLabelVisible, setIsLoadingLabelVisible] = React.useState(false)
+ const loadingLabelId = useId('loadingLabel')
+
+ const resetLoadingLabel = useCallback(() => {
+ if (loadingLabelTimeoutId) {
+ clearTimeout(loadingLabelTimeoutId)
+ setLoadingLabelTimeoutId(null)
+ }
+
+ if (isLoadingLabelVisible) {
+ setIsLoadingLabelVisible(false)
+ }
+ }, [loadingLabelTimeoutId, isLoadingLabelVisible])
+
  const handleToggleClick: MouseEventHandler = useCallback(
  e => {
+ if (disabled || loading) return
+
  if (!isControlled) {
  setIsOn(!isOn)
+ resetLoadingLabel()
  }
  onClick && onClick(e)
  },
- [onClick, isControlled, isOn, setIsOn],
+ [disabled, isControlled, loading, onClick, setIsOn, isOn, resetLoadingLabel],
  )
 
  useEffect(() => {
- if (onChange && isControlled) {
+ if (onChange && isControlled && !disabled) {
  onChange(Boolean(checked))
  }
- }, [onChange, checked, isControlled])
+ }, [onChange, checked, isControlled, disabled])
+
+ if (loading) {
+ if (!loadingLabelTimeoutId) {
+ setLoadingLabelTimeoutId(
+ setTimeout(() => {
+ setLoadingLabelTimeoutId(null)
+ setIsLoadingLabelVisible(true)
+ }, loadingLabelDelay) as unknown as number,
+ )
+ }
+ } else {
+ resetLoadingLabel()
+ }
+
+ let switchButtonDescribedBy = loadingLabelId
+ if (ariaDescribedby) switchButtonDescribedBy = `${switchButtonDescribedBy} ${ariaDescribedby}`
 
  return (
  <Box
@@ -249,13 +301,20 @@ const ToggleSwitch = React.forwardRef<HTMLButtonElement, React.PropsWithChildren
  sx={sxProp}
  {...rest}
  >
+ {isLoadingLabelVisible ? (
+ <VisuallyHidden>
+ <span aria-live="polite" id={loadingLabelId}>
+ Loading
+ </span>
+ </VisuallyHidden>
+ ) : null}
  {loading ? <Spinner size="small" /> : null}
  <Text
  color={acceptsInteraction ? 'fg.default' : 'fg.muted'}
  fontSize={size === 'small' ? 0 : 1}
  mx={2}
  aria-hidden="true"
- sx={{position: 'relative', cursor: 'pointer'}}
+ sx={{position: 'relative', cursor: acceptsInteraction ? 'pointer' : 'not-allowed'}}
  onClick={handleToggleClick}
  >
  <Box textAlign="right" sx={isOn ? null : hiddenTextStyles}>
@@ -269,11 +328,11 @@ const ToggleSwitch = React.forwardRef<HTMLButtonElement, React.PropsWithChildren
  ref={ref}
  onClick={handleToggleClick}
  aria-labelledby={ariaLabelledby}
- aria-describedby={ariaDescribedby}
+ aria-describedby={switchButtonDescribedBy}
  aria-pressed={isOn}
  checked={isOn}
  size={size}
- disabled={!acceptsInteraction}
+aria-disabled={!acceptsInteraction}
  >
  <Box aria-hidden="true" display="flex" alignItems="center" width="100%" height="100%" overflow="hidden">
  <Box
@@ -305,7 +364,7 @@ const ToggleSwitch = React.forwardRef<HTMLButtonElement, React.PropsWithChildren
  <CircleIcon size={size} />
  </Box>
  </Box>
- <ToggleKnob aria-hidden="true" disabled={!acceptsInteraction} checked={isOn} />
+ <ToggleKnob aria-hidden="true" aria-disabled={!acceptsInteraction} checked={isOn} />
  </SwitchButton>
  </Box>
  )

src/ToggleSwitch/__snapshots__/ToggleSwitch.test.tsx.snap

@@ -219,10 +219,11 @@ exports[`ToggleSwitch renders consistently 1`] = `
  </div>
  </span>
  <button
+ aria-describedby="loadingLabel"
+ aria-disabled={false}
  aria-pressed={false}
  checked={false}
  className="c4"
- disabled={false}
  onClick={[Function]}
  size="medium"
  >
@@ -272,10 +273,10 @@ exports[`ToggleSwitch renders consistently 1`] = `
  </div>
  </div>
  <div
+ aria-disabled={false}
  aria-hidden="true"
  checked={false}
  className="c8"
- disabled={false}
  />
  </button>
 </div>