Accessibility fixes for ToggleSwitch

.changeset/honest-gorillas-drive.md

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

packages/react/src/ToggleSwitch/ToggleSwitch.docs.json

@@ -95,6 +95,18 @@
  "defaultValue": "'start'",
  "description": "Whether the \"on\" and \"off\" labels should appear before or after the switch.\n\n**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."
  },
+ {
+ "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."
+ },
+ {
+ "name": "loadingLabel",
+ "type": "string",
+ "defaultValue": "'Loading'",
+ "description": "The text that is announced to AT such as screen readers when the switch is in a loading state."
+ },
  {
  "name": "buttonType",
  "type": "'button' | 'submit' | 'reset'",

packages/react/src/ToggleSwitch/ToggleSwitch.features.stories.tsx

@@ -1,4 +1,5 @@
-import React from 'react'
+import React, {useState} from 'react'
+import {useSafeTimeout} from '..'
 import ToggleSwitch from './ToggleSwitch'
 import {action} from 'storybook/actions'
 import ToggleSwitchStoryWrapper from './ToggleSwitchStoryWrapper'
@@ -68,6 +69,65 @@ export const Loading = () => (
  </ToggleSwitchStoryWrapper>
 )
 
+type LoadingWithDelayProps = {
+ loadingDelay: number
+ loadingLabelDelay: number
+}
+
+export const LoadingWithDelay = (args: LoadingWithDelayProps) => {
+ const {loadingDelay, loadingLabelDelay} = args
+
+ const [isLoading, setIsLoading] = useState(false)
+ const [timeoutId, setTimeoutId] = useState<number | null>(null)
+ const [toggleState, setToggleState] = useState(false)
+
+ const {safeSetTimeout, safeClearTimeout} = useSafeTimeout()
+
+ const handleToggleClick = () => {
+ setIsLoading(true)
+
+ if (timeoutId) {
+ safeClearTimeout(timeoutId)
+ setTimeoutId(null)
+ }
+
+ setTimeoutId(safeSetTimeout(() => setIsLoading(false), loadingDelay) as unknown as number)
+ }
+
+ return (
+ <ToggleSwitchStoryWrapper>
+ <span id="toggle" style={{fontWeight: 'bold', fontSize: 'var(--base-size-14)'}}>
+ Enable feature
+ </span>
+ <ToggleSwitch
+ loading={isLoading}
+ loadingLabel={`${toggleState ? 'Enabling' : 'Disabling'} feature`}
+ loadingLabelDelay={loadingLabelDelay}
+ aria-labelledby="toggle"
+ onClick={handleToggleClick}
+ onChange={(on: boolean) => setToggleState(on)}
+ />
+ </ToggleSwitchStoryWrapper>
+ )
+}
+
+LoadingWithDelay.args = {
+ loadingDelay: 5000,
+ loadingLabelDelay: 2000,
+}
+LoadingWithDelay.argTypes = {
+ loadingDelay: {
+ control: {
+ type: 'number',
+ },
+ },
+ loadingLabelDelay: {
+ control: {
+ type: 'number',
+ },
+ },
+}
+
 export const LabelEnd = () => (
  <ToggleSwitchStoryWrapper>
  <span id="toggle" className={styles.ToggleLabel}>

packages/react/src/ToggleSwitch/ToggleSwitch.figma.tsx

@@ -21,7 +21,13 @@ figma.connect(
  }),
  },
  example: ({size, checked, labelposition, loading}) => (
- <ToggleSwitch size={size} checked={checked} statusLabelPosition={labelposition} loading={loading} />
+ <ToggleSwitch
+ aria-labelledby=""
+ size={size}
+ checked={checked}
+ statusLabelPosition={labelposition}
+ loading={loading}
+ />
  ),
  },
 )

packages/react/src/ToggleSwitch/ToggleSwitch.test.tsx

@@ -1,6 +1,6 @@
 import {describe, expect, it, vi} from 'vitest'
 import React from 'react'
-import {render} from '@testing-library/react'
+import {render, waitFor} from '@testing-library/react'
 import ToggleSwitch from './'
 import userEvent from '@testing-library/user-event'
 
@@ -46,7 +46,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(
  <>
@@ -94,6 +94,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 = () => {
@@ -157,6 +173,18 @@ describe('ToggleSwitch', () => {
  expect(toggleSwitch).toBeInTheDocument()
  })
 
+ it('renders a switch that has button type button', () => {
+ const {getByLabelText} = render(
+ <>
+ <div id="switchLabel">{SWITCH_LABEL_TEXT}</div>
+ <ToggleSwitch aria-labelledby="switchLabel" />
+ </>,
+ )
+
+ const toggleSwitch = getByLabelText(SWITCH_LABEL_TEXT)
+ expect(toggleSwitch).toHaveAttribute('type', 'button')
+ })
+
  it('supports a `ref` on the inner <button> element', () => {
  const ref = vi.fn()
 
@@ -171,15 +199,17 @@ describe('ToggleSwitch', () => {
  expect(ref).toHaveBeenCalledWith(expect.any(HTMLButtonElement))
  })
 
- it('renders a switch that has button type button', () => {
- const {getByLabelText} = render(
+ it('displays a loading label', async () => {
+ const TEST_ID = 'a test id'
+
+ const {getByTestId} = render(
  <>
- <div id="switchLabel">{SWITCH_LABEL_TEXT}</div>
- <ToggleSwitch aria-labelledby="switchLabel" />
+ <span id="label">label</span>
+ <ToggleSwitch data-testid={TEST_ID} aria-labelledby="label" loadingLabelDelay={0} loading />
  </>,
  )
 
- const toggleSwitch = getByLabelText(SWITCH_LABEL_TEXT)
- expect(toggleSwitch).toHaveAttribute('type', 'button')
+ const toggleSwitch = getByTestId(TEST_ID)
+await waitFor(() => expect(toggleSwitch).toHaveTextContent('Loading'))
  })
 })

packages/react/src/ToggleSwitch/ToggleSwitch.tsx

@@ -6,16 +6,21 @@ import Box from '../Box'
 import Spinner from '../Spinner'
 import Text from '../Text'
 import {get} from '../constants'
-import {useProvidedStateOrCreate} from '../hooks'
+import {useProvidedStateOrCreate, useId} from '../hooks'
 import type {BetterSystemStyleObject, SxProp} from '../sx'
 import sx from '../sx'
 import getGlobalFocusStyles from '../internal/utils/getGlobalFocusStyles'
+import VisuallyHidden from '../_VisuallyHidden'
 import type {CellAlignment} from '../DataTable/column'
+import {AriaStatus} from '../live-region'
+import useSafeTimeout from '../hooks/useSafeTimeout'
 
 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 */
@@ -34,6 +39,16 @@ 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 `loadingLabel` is announced to screen readers.
+ * @default 2000
+ */
+ loadingLabelDelay?: number
+ /** The text to describe what is loading. It should be descriptive and not verbose.
+ * This is primarily used for AT (screen readers) to convey what is currently loading.
+ */
+ loadingLabel?: string
  /** type of button to account for behavior when added to a form*/
  buttonType?: 'button' | 'submit' | 'reset'
 }
@@ -122,7 +137,7 @@ const SwitchButton = styled.button<SwitchButtonProps>`
  }
  }
 
- &:hover:not(:disabled),
+ &:hover:not(:disabled):not([aria-disabled='true']),
  &:focus:focus-visible {
  background-color: ${get('colors.switchTrack.hoverBg')};
  }
@@ -133,8 +148,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;
@@ -147,7 +166,7 @@ const SwitchButton = styled.button<SwitchButtonProps>`
  background-color: ${get('colors.switchTrack.checked.bg')};
  border-color: var(--control-checked-borderColor-rest, transparent);
 
- &:hover:not(:disabled),
+ &:hover:not(:disabled):not([aria-disabled='true']),
  &:focus:focus-visible {
  background-color: ${get('colors.switchTrack.checked.hoverBg')};
  }
@@ -172,11 +191,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;
@@ -193,8 +213,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')};
  `
  }
@@ -226,27 +250,50 @@ const ToggleSwitch = React.forwardRef<HTMLButtonElement, React.PropsWithChildren
  buttonType = 'button',
  size = 'medium',
  statusLabelPosition = 'start',
+ loadingLabelDelay = 2000,
+ loadingLabel = 'Loading',
  sx: sxProp,
  ...rest
  } = props
  const isControlled = typeof checked !== 'undefined'
  const [isOn, setIsOn] = useProvidedStateOrCreate<boolean>(checked, onChange, Boolean(defaultChecked))
  const acceptsInteraction = !disabled && !loading
+
+ const [isLoadingLabelVisible, setIsLoadingLabelVisible] = React.useState(false)
+ const loadingLabelId = useId('loadingLabel')
+
+ const {safeSetTimeout} = useSafeTimeout()
+
  const handleToggleClick: MouseEventHandler = useCallback(
  e => {
+ if (disabled || loading) return
+
  if (!isControlled) {
  setIsOn(!isOn)
  }
  onClick && onClick(e)
  },
- [onClick, isControlled, isOn, setIsOn],
+ [disabled, isControlled, loading, onClick, setIsOn, isOn],
  )
 
  useEffect(() => {
- if (onChange && isControlled) {
+ if (onChange && isControlled && !disabled) {
  onChange(Boolean(checked))
  }
- }, [onChange, checked, isControlled, buttonType])
+ }, [onChange, checked, isControlled, disabled])
+
+ useEffect(() => {
+ if (!loading && isLoadingLabelVisible) {
+ setIsLoadingLabelVisible(false)
+ } else if (loading && !isLoadingLabelVisible) {
+ safeSetTimeout(() => {
+ setIsLoadingLabelVisible(true)
+ }, loadingLabelDelay)
+ }
+ }, [loading, isLoadingLabelVisible, loadingLabelDelay, safeSetTimeout])
+
+ let switchButtonDescribedBy = loadingLabelId
+ if (ariaDescribedby) switchButtonDescribedBy = `${switchButtonDescribedBy} ${ariaDescribedby}`
 
  return (
  <Box
@@ -256,13 +303,19 @@ const ToggleSwitch = React.forwardRef<HTMLButtonElement, React.PropsWithChildren
  sx={sxProp}
  {...rest}
  >
- {loading ? <Spinner size="small" /> : null}
+ <VisuallyHidden>
+ <AriaStatus announceOnShow id={loadingLabelId}>
+ {isLoadingLabelVisible && loadingLabel}
+ </AriaStatus>
+ </VisuallyHidden>
+
+ {loading ? <Spinner size="small" srText={null} /> : 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}>
@@ -277,11 +330,11 @@ const ToggleSwitch = React.forwardRef<HTMLButtonElement, React.PropsWithChildren
  type={buttonType}
  onClick={handleToggleClick}
  aria-labelledby={ariaLabelledby}
- aria-describedby={ariaDescribedby}
+ aria-describedby={isLoadingLabelVisible || ariaDescribedby ? switchButtonDescribedBy : undefined}
  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
@@ -313,7 +366,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>
  )