Built-in screen reader

.eslintrc.js

@@ -90,5 +90,6 @@ module.exports = {
     '@typescript-eslint/explicit-function-return-type': 'off', // Want to use it, but it requires return types for all built-in React lifecycle methods.
     '@typescript-eslint/no-non-null-assertion': 'off',
     '@typescript-eslint/no-use-before-define': ['error', { functions: false }],
+    'import/extensions': 'off'
   },
 }

src/App.tsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { useState, useCallback } from 'react'
 import { BrowserRouter, Route } from 'react-router-dom'
 
 import 'normalize.css'
@@ -7,18 +7,111 @@ import './App.css'
 import FocusManager from './components/FocusManager'
 
 import AppRoot from './AppRoot'
+import {
+  ScreenReader,
+  AriaScreenReader,
+  SpeechSynthesisTextToSpeech,
+  NullTextToSpeech,
+  TextToSpeech,
+} from './utils/ScreenReader'
 
 /* istanbul ignore next - unsure how to test */
 window.oncontextmenu = (e: MouseEvent): void => {
   e.preventDefault()
 }
 
-const App = () => (
-  <BrowserRouter>
-    <FocusManager>
-      <Route path="/" component={AppRoot} />
-    </FocusManager>
-  </BrowserRouter>
-)
+export interface Props {
+  tts?: {
+    enabled: TextToSpeech
+    disabled: TextToSpeech
+  }
+}
+
+const App = ({
+  tts = {
+    enabled: new SpeechSynthesisTextToSpeech(),
+    disabled: new NullTextToSpeech(),
+  },
+}: Props) => {
+  const [screenReaderEnabled, setScreenReaderEnabled] = useState(false)
+  const [screenReader, setScreenReader] = useState<ScreenReader>(
+    new AriaScreenReader(tts.disabled)
+  )
+
+  /* istanbul ignore next - need to figure out how to test this */
+  const onKeyPress = useCallback(
+    (event: React.KeyboardEvent) => {
+      if (event.key === 'r') {
+        if (screenReaderEnabled) {
+          screenReader.onScreenReaderDisabled()
+          setScreenReader(new AriaScreenReader(tts.disabled))
+          setScreenReaderEnabled(false)
+        } else {
+          const newScreenReader = new AriaScreenReader(tts.enabled)
+          setScreenReader(newScreenReader)
+          setScreenReaderEnabled(true)
+          newScreenReader.onScreenReaderEnabled()
+        }
+      }
+    },
+    [
+      screenReader,
+      setScreenReader,
+      screenReaderEnabled,
+      setScreenReaderEnabled,
+      tts.disabled,
+      tts.enabled,
+    ]
+  )
+
+  /* istanbul ignore next - need to figure out how to test this */
+  const onClick = useCallback(
+    ({ target }: React.MouseEvent) => {
+      if (target) {
+        const currentPath = window.location.pathname
+
+        setImmediate(() => {
+          // Only send `onClick` to the screen reader if the click didn't
+          // trigger navigation.
+          if (window.location.pathname === currentPath) {
+            screenReader.onClick(target)
+          }
+        })
+      }
+    },
+    [screenReader]
+  )
+
+  /* istanbul ignore next - need to figure out how to test this */
+  const onFocus = useCallback(
+    ({ target }: React.FocusEvent) => {
+      if (target) {
+        const currentPath = window.location.pathname
+
+        setImmediate(() => {
+          // Only send `onFocus` to the screen reader if the focus didn't
+          // trigger navigation.
+          if (window.location.pathname === currentPath) {
+            screenReader.onFocus(target)
+          }
+        })
+      }
+    },
+    [screenReader]
+  )
+
+  return (
+    <BrowserRouter>
+      <FocusManager
+        screenReader={screenReader}
+        onKeyPress={onKeyPress}
+        onClickCapture={onClick}
+        onFocusCapture={onFocus}
+      >
+        <Route path="/" component={AppRoot} />
+      </FocusManager>
+    </BrowserRouter>
+  )
+}
 
 export default App

src/components/FocusManager.test.tsx

@@ -2,8 +2,13 @@ import React from 'react'
 import { render } from '../../test/testUtils'
 
 import FocusManager from './FocusManager'
+import { AriaScreenReader, NullTextToSpeech } from '../utils/ScreenReader'
 
 it('renders FocusManager', async () => {
-  const { container } = render(<FocusManager>foo</FocusManager>)
+  const { container } = render(
+    <FocusManager screenReader={new AriaScreenReader(new NullTextToSpeech())}>
+      foo
+    </FocusManager>
+  )
   expect(container.firstChild).toMatchSnapshot()
 })

src/components/FocusManager.tsx

@@ -1,6 +1,7 @@
 import React from 'react'
 import { RouteComponentProps, withRouter } from 'react-router-dom'
 import styled from 'styled-components'
+import { ScreenReader } from '../utils/ScreenReader'
 
 const StyledFocusManager = styled.div`
   height: 100%;
@@ -9,17 +10,32 @@ const StyledFocusManager = styled.div`
   }
 `
 
-class FocusManager extends React.Component<RouteComponentProps> {
+export interface Props extends RouteComponentProps {
+  screenReader: ScreenReader
+  onKeyPress?: React.DOMAttributes<HTMLElement>['onKeyPress']
+  onClick?: React.DOMAttributes<HTMLElement>['onClick']
+  onFocus?: React.DOMAttributes<HTMLElement>['onFocus']
+  onKeyPressCapture?: React.DOMAttributes<HTMLElement>['onKeyPressCapture']
+  onClickCapture?: React.DOMAttributes<HTMLElement>['onClickCapture']
+  onFocusCapture?: React.DOMAttributes<HTMLElement>['onFocusCapture']
+}
+
+class FocusManager extends React.Component<Props> {
   public screen = React.createRef<HTMLDivElement>()
+
   public componentDidMount() {
-    this.focus()
+    this.onPageLoad()
   }
+
   public componentDidUpdate(prevProps: RouteComponentProps) {
     if (this.props.location.pathname !== prevProps.location.pathname) {
-      this.focus()
+      this.onPageLoad()
     }
   }
-  public focus = () => {
+
+  public onPageLoad = () => {
+    this.props.screenReader.onPageLoad()
+
     // can't seem to find a better way than this, unfortunately.
     // the delay of 150 is to handle the case the Next button is selected
     // via arrow keys and then clicked. A shorter delay will fail to move
@@ -28,14 +44,23 @@ class FocusManager extends React.Component<RouteComponentProps> {
     window.setTimeout(() => {
       const elementToFocus =
         document.getElementById('audiofocus') || this.screen.current!
-
       elementToFocus && elementToFocus.focus()
       elementToFocus && elementToFocus.click()
     }, 150)
   }
+
   public render() {
     return (
-      <StyledFocusManager ref={this.screen} tabIndex={-1}>
+      <StyledFocusManager
+        ref={this.screen}
+        tabIndex={-1}
+        onKeyPress={this.props.onKeyPress}
+        onClick={this.props.onClick}
+        onFocus={this.props.onFocus}
+        onKeyPressCapture={this.props.onKeyPressCapture}
+        onClickCapture={this.props.onClickCapture}
+        onFocusCapture={this.props.onFocusCapture}
+      >
         {this.props.children}
       </StyledFocusManager>
     )

src/components/LinkButton.tsx

@@ -32,15 +32,9 @@ const LinkButton = (props: Props) => {
     if (onPress) {
       onPress(event)
     } else if (goBack && !to) {
-      // Delay to avoid passing tap to next screen
-      window.setTimeout(() => {
-        history.goBack()
-      }, 100)
+      history.goBack()
     } else if (to && !goBack) {
-      // Delay to avoid passing tap to next screen
-      window.setTimeout(() => {
-        history.push(to)
-      }, 100)
+      history.push(to)
     }
   }
   return (

src/components/Modal.tsx

@@ -54,7 +54,8 @@ const Modal: React.FC<Props> = ({
       document.getElementById('root')! || document.body.firstElementChild
     }
     ariaHideApp
-    role="none"
+    aria-modal
+    role="alertdialog"
     isOpen={isOpen}
     contentLabel={ariaLabel}
     portalClassName="modal-portal"

src/components/YesNoContest.tsx

@@ -361,7 +361,7 @@ export default class YesNoContest extends React.Component<Props> {
           content={
             <Prose>
               {overvoteSelection && (
-                <p>
+                <p id="modalaudiofocus">
                   Do you want to change your vote to{' '}
                   <strong>{YES_NO_VOTES[overvoteSelection]}</strong>? To change
                   your vote, first unselect your vote for{' '}

src/lib/gamepad.test.tsx

@@ -50,7 +50,6 @@ it('gamepad controls work', async () => {
 
   // Go to First Contest
   handleGamepadButtonDown('DPadRight')
-  fireEvent.click(getByText('Start Voting'))
   advanceTimers()
 
   // First Contest Page

src/lib/gamepad.ts

@@ -1,8 +1,7 @@
 import { Button } from 'react-gamepad'
 import mod from '../utils/mod'
 
-export const getActiveElement = () =>
-  document.activeElement! as HTMLInputElement
+export const getActiveElement = () => document.activeElement! as HTMLElement
 
 function getFocusableElements(): HTMLElement[] {
   const tabbableElements = Array.from(
@@ -41,15 +40,15 @@ function handleArrowDown() {
 }
 
 function handleArrowLeft() {
-  const prevButton = document.getElementById('previous') as HTMLButtonElement
+  const prevButton = document.getElementById('previous')
   /* istanbul ignore else */
   if (prevButton) {
     prevButton.click()
   }
 }
 
 function handleArrowRight() {
-  const nextButton = document.getElementById('next') as HTMLButtonElement
+  const nextButton = document.getElementById('next')
   /* istanbul ignore else */
   if (nextButton) {
     nextButton.click()

src/pages/ContestPage.tsx

@@ -1,4 +1,4 @@
-import React, { useContext } from 'react'
+import React, { useContext, useRef } from 'react'
 import { Redirect, RouteComponentProps } from 'react-router-dom'
 import { CandidateVote, OptionalYesNoVote } from '@votingworks/ballot-encoder'
 
@@ -35,6 +35,7 @@ const ContestPage = (props: RouteComponentProps<ContestParams>) => {
     votes,
   } = useContext(BallotContext)
 
+  const rootRef = useRef<HTMLElement>()
   const currentContestIndex = parseInt(contestNumber, 10)
   const contest = contests[currentContestIndex]
 
@@ -58,7 +59,7 @@ const ContestPage = (props: RouteComponentProps<ContestParams>) => {
   // - confirm intent when navigating away without selecting a candidate
 
   return (
-    <Screen>
+    <Screen ref={rootRef as any}>
       {contest.type === 'candidate' && (
         <CandidateContest
           aria-live="assertive"

src/setupTests.tsx

@@ -25,6 +25,39 @@ window.print = jest.fn(() => {
 
 const printMock = mockOf(window.print)
 
+function mockSpeechSynthesis() {
+  const w = window as {
+    speechSynthesis: typeof speechSynthesis
+    SpeechSynthesisUtterance: typeof SpeechSynthesisUtterance
+    SpeechSynthesisEvent: typeof SpeechSynthesisEvent
+  }
+
+  w.speechSynthesis = makeSpeechSynthesisDouble()
+  w.SpeechSynthesisUtterance = jest.fn().mockImplementation(text => ({ text }))
+  w.SpeechSynthesisEvent = jest.fn()
+}
+
+function makeSpeechSynthesisDouble(): typeof speechSynthesis {
+  return {
+    addEventListener: jest.fn(),
+    cancel: jest.fn(),
+    dispatchEvent: jest.fn(),
+    getVoices: jest.fn(),
+    onvoiceschanged: jest.fn(),
+    pause: jest.fn(),
+    paused: false,
+    pending: false,
+    removeEventListener: jest.fn(),
+    resume: jest.fn(),
+    speak: jest.fn(),
+    speaking: false,
+  }
+}
+
+beforeEach(() => {
+  mockSpeechSynthesis()
+})
+
 afterEach(() => {
   fetchMock.restore()
   printMock.mockClear()