DatePicker: Improve screenreader accessibility #1453

c-w · 2017-04-10T22:00:21Z

Pull request checklist

Addresses an existing issue: Date picker: Tab focus issues (accessibility) #1266
Include a change request file if publishing
New feature, bugfix, or enhancement
- Includes tests
Documentation update

Description of changes

The previous/next month/year buttons don't have aria-labels and therefore are indiscernible to screen reader users. This pull request fixes this by enabling consumers of the date-picker to provide aria-labels for the buttons.

This pull request also improves the navigation of the date picker for screen reader users by re-announcing the month and year whenever the user navigates across a month/year boundary. This behavior is adapted from some accessibility best practices laid out by the OAA.

Focus areas to test

Test steps (verified manually on DatePicker.Basic.Example):

Open test site in Edge, turn on Narrator, navigate to the date picker via keyboard, and open the date picker.
Navigate from the last day of a month to the first day of the next month. The new month should be read out by the screen reader.
Navigate to the previous/next month/year buttons. The screen reader should read out "Go to {previous,next} {month,year}"

This is a fix for issue 4 mentioned in #1266

This is a fix for issue 3 mentioned in #1266

cschlechty · 2017-04-13T23:00:59Z

packages/office-ui-fabric-react/src/components/Calendar/CalendarDay.tsx

-          <div className={ css('ms-DatePicker-month', styles.month) }>{ strings.months[navigatedDate.getMonth()] }</div>
-          <div className={ css('ms-DatePicker-year', styles.year) }>{ navigatedDate.getFullYear() }</div>
+          <div role='heading' id={ monthAndYearId } aria-live='assertive' aria-relevant='text' aria-atomic='true'>
+            <div className={ css('ms-DatePicker-month', styles.month) }>{ strings.months[navigatedDate.getMonth()] }</div>


Does this localize well? Won't it be wrong in EMEA?

I agree, the localization approach taken here is likely not ideal. Fixing that is beyond the scope of this pull-request though: I'd just like to focus on the accessibility improvements and leave the localization logic as it currently stands.

cschlechty · 2017-04-13T23:01:28Z

packages/office-ui-fabric-react/src/components/Calendar/CalendarDay.tsx


    return (
      <div className={ css('ms-DatePicker-dayPicker', styles.dayPicker) }>
        <div className={ css('ms-DatePicker-header', styles.header) }>
-          <div className={ css('ms-DatePicker-month', styles.month) }>{ strings.months[navigatedDate.getMonth()] }</div>
-          <div className={ css('ms-DatePicker-year', styles.year) }>{ navigatedDate.getFullYear() }</div>
+          <div role='heading' id={ monthAndYearId } aria-live='assertive' aria-relevant='text' aria-atomic='true'>


Add a heading level if you're adding heading.

We have no way of knowing what the correct level here would be, so I removed the role.

cschlechty · 2017-04-13T23:01:58Z

packages/office-ui-fabric-react/src/components/Calendar/CalendarDay.tsx

+          <div role='heading' id={ monthAndYearId } aria-live='assertive' aria-relevant='text' aria-atomic='true'>
+            <div className={ css('ms-DatePicker-month', styles.month) }>{ strings.months[navigatedDate.getMonth()] }</div>
+            <div className={ css('ms-DatePicker-year', styles.year) }>{ navigatedDate.getFullYear() }</div>
+          </div>
        </div>
        <div className={ css('ms-DatePicker-monthComponents', styles.monthComponents) }>
          <div className={ css('ms-DatePicker-navContainer', styles.navContainer) }>
            <span


Why do we not use a true button?

This was here before my pull-request, so that's a question for the original author: @dzearing.

cschlechty · 2017-04-13T23:03:03Z

packages/office-ui-fabric-react/src/components/Calendar/CalendarDay.tsx

        </div>
        <div className={ css('ms-DatePicker-monthComponents', styles.monthComponents) }>
          <div className={ css('ms-DatePicker-navContainer', styles.navContainer) }>
            <span
              className={ css('ms-DatePicker-prevMonth js-prevMonth', styles.prevMonth) }
              onClick={ this._onSelectPrevMonth }
              onKeyDown={ this._onPrevMonthKeyDown }
+              aria-controls={ monthAndYearId }
+              aria-label={ strings.nextMonthAriaLabel }
+              role='button'


button implies we handle spacebar as well.

Done in 12c53ed.

cschlechty · 2017-04-13T23:04:37Z

packages/office-ui-fabric-react/src/components/Calendar/CalendarDay.tsx


    return (
      <div className={ css('ms-DatePicker-dayPicker', styles.dayPicker) }>
        <div className={ css('ms-DatePicker-header', styles.header) }>
-          <div className={ css('ms-DatePicker-month', styles.month) }>{ strings.months[navigatedDate.getMonth()] }</div>
-          <div className={ css('ms-DatePicker-year', styles.year) }>{ navigatedDate.getFullYear() }</div>
+          <div role='heading' id={ monthAndYearId } aria-live='assertive' aria-relevant='text' aria-atomic='true'>


Why is this assertive?

Making the month display assertive makes the control much nicer to use with a screen reader: when navigating between a month boundary (e.g. from the 30th of one month to the 1st of the next month), we'll re-announce the month's name which provides more context to the user. It's better to hear "1 January 2017" than just "1".

c-w · 2017-04-17T18:35:06Z

@cschlechty: I addressed your comments -- could you please take another look?

cschlechty · 2017-04-18T18:42:28Z

packages/office-ui-fabric-react/src/components/Calendar/CalendarDay.tsx


    return (
      <div className={ css('ms-DatePicker-dayPicker', styles.dayPicker) }>
        <div className={ css('ms-DatePicker-header', styles.header) }>
-          <div className={ css('ms-DatePicker-month', styles.month) }>{ strings.months[navigatedDate.getMonth()] }</div>
-          <div className={ css('ms-DatePicker-year', styles.year) }>{ navigatedDate.getFullYear() }</div>
+          <div id={ monthAndYearId } aria-live='assertive' aria-relevant='text' aria-atomic='true'>


Can you use passive, instead?

Done in 0e1ca9a.

cschlechty · 2017-04-18T18:47:00Z

packages/office-ui-fabric-react/src/components/Calendar/CalendarDay.tsx

        </div>
        <div className={ css('ms-DatePicker-monthComponents', styles.monthComponents) }>
          <div className={ css('ms-DatePicker-navContainer', styles.navContainer) }>
            <span
              className={ css('ms-DatePicker-prevMonth js-prevMonth', styles.prevMonth) }
              onClick={ this._onSelectPrevMonth }
              onKeyDown={ this._onPrevMonthKeyDown }
+              aria-controls={ monthAndYearId }


aria-controls specifies the html it has control over. shouldn't this point to the body of the calendar?

Done in cd30b5d.

cschlechty

There's a few suggestions.

c-w added 3 commits April 10, 2017 14:49

Announce year/month when it changes

eb5d41b

This is a fix for issue 4 mentioned in #1266

Add aria labels to date picker icon-navigation

487930e

This is a fix for issue 3 mentioned in #1266

Add change file

172ce2b

msftclas added the cla-not-required label Apr 10, 2017

c-w added 5 commits April 11, 2017 10:48

Merge branch 'master' into bugfix/date-picker-screenreader

91f342e

Merge branch 'master' into bugfix/date-picker-screenreader

6191f82

Merge branch 'master' into bugfix/date-picker-screenreader

5ed61b9

Merge branch 'master' into bugfix/date-picker-screenreader

2c5cdb3

Merge branch 'master' into bugfix/date-picker-screenreader

a6e5f58

micahgodbolt added the Area: Accessibility label Apr 13, 2017

Merge branch 'master' into bugfix/date-picker-screenreader

e689ab9

cschlechty requested changes Apr 13, 2017

View reviewed changes

micahgodbolt and others added 4 commits April 14, 2017 14:14

Merge branch 'master' into bugfix/date-picker-screenreader

d3ca58e

Merge branch 'master' into bugfix/date-picker-screenreader

f9d13b5

Accessibility: trigger actions via spacebar

12c53ed

Remove heading role

0d07189

c-w added 2 commits April 18, 2017 09:08

Merge branch 'master' into bugfix/date-picker-screenreader

f6cf89f

Merge branch 'master' into bugfix/date-picker-screenreader

d60045e

cschlechty reviewed Apr 18, 2017

View reviewed changes

cschlechty approved these changes Apr 18, 2017

View reviewed changes

c-w added 3 commits April 18, 2017 11:57

Reduce live-level

0e1ca9a

Move up aria-controls target

cd30b5d

Fix build

d26c8fb

cschlechty merged commit 876d40b into microsoft:master Apr 18, 2017

microsoft locked as resolved and limited conversation to collaborators Aug 31, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DatePicker: Improve screenreader accessibility #1453

DatePicker: Improve screenreader accessibility #1453

c-w commented Apr 10, 2017

cschlechty Apr 13, 2017

c-w Apr 17, 2017

cschlechty Apr 13, 2017

c-w Apr 17, 2017

cschlechty Apr 13, 2017

c-w Apr 17, 2017

cschlechty Apr 13, 2017

c-w Apr 17, 2017

cschlechty Apr 13, 2017

c-w Apr 17, 2017

c-w commented Apr 17, 2017

cschlechty Apr 18, 2017

c-w Apr 18, 2017

cschlechty Apr 18, 2017

c-w Apr 18, 2017

cschlechty left a comment

DatePicker: Improve screenreader accessibility #1453

DatePicker: Improve screenreader accessibility #1453

Conversation

c-w commented Apr 10, 2017

Pull request checklist

Description of changes

Focus areas to test

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

c-w commented Apr 17, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cschlechty left a comment

Choose a reason for hiding this comment