Add ARIA attributes for better accessibility

[basham]

While react-day-picker works with the keyboard, its semantics could be improved by adding the appropriate ARIA attributes, so screen readers will better interpret how the component works.

Probably the best React exemplar I've found which achieves this nicely is react-widgets Calendar. However, I see the customizability of the react-day-picker project being much more ideal. I really like the clean, small ES6 implementation with no dependencies outside of React.

The following are some suggestions based on my research. Some suggestions are a result of adding back certain semantics which were lost due to switching from <table> to <div>. Suggestions are organized by the element to which it affects, identified by its class name.

.DayPicker-Month

• Add role="grid" attribute; grid cells need an ancestor grid.

Authors MUST ensure that elements with role gridcell are owned by elements with role row, which in turn are owned by an element with role rowgroup, grid or treegrid.

• Add aria-readonly="true" attribute to indicate that the child grid cells will never be edited; by default, grid cells are assumed to be editable.

A grid is considered editable unless otherwise specified. To make a grid read-only, set the aria-readonly attribute of the grid to true. The value of the grid element's aria-readonly attribute is implicitly propagated to all of its owned gridcell elements, and will be exposed through the accessibility API.

• Add aria-labelledby attribute to explicitly indicate the .DayPicker-Caption element is labeling the month grid.
• Add aria-activedescendant attribute to explicitly indicate which .DayPicker-Day is in focus.

.DayPicker-Caption

• Add unique id to work with .DayPicker-Month enhancements.

.DayPicker-Weekdays

• Add role="rowgroup" attribute, which is equivalent to using <thead> element.

.DayPicker-Weekday

• Add role="columnheader" attribute, which is equivalent to using the <th> element.

.DayPicker-Body

• Add role="rowgroup" attribute, which is equivalent to using <tbody> element.

.DayPicker-Day

• Add unique id to work with .DayPicker-Month enhancements.
• Add aria-disabled="true|false" attribute to indicate if the cell is selectable; this suggests that not every day within a given range of dates has to be selectable.
• Add aria-selected="true|false" attribute to indicate if the cell is selected.

gridcell elements with the aria-selected attribute set can be selected for user interaction

• Add title="Today" attribute to a day which is today; if not wanting the tooltip to appear, then use aria-label="Today" attribute. Alternatively, this suggestion could be implemented via a custom day component, rather than in this project.

Additional considerations

Since aria-labelledby and aria-activedescendant reference an id, it may be good to dynamically generate unique ids for elements they reference, so you avoid the problem of having different instances of react-day-picker accidentally cross-reference each other.

[gpbl]

@basham thanks for taking the time to write this, it is really helpful 👍. Many suggestions are trivial to implement (see unit test below).

For supporting aria-selected and aria-disabled I need to treat selected and disabled as "special" modifiers: I'll open a separate issue for this.

title or aria-label attributes raise a problem with localization. "Today" is a default modifier but developers may want to implement other labels, such as "Bookable" or "Free" or whatever. I need to think about it, maybe adding labels prop...

let captionElements = getElementsByClassName(dayPickerNode, "DayPicker-Caption");
let monthElements = getElementsByClassName(dayPickerNode, "DayPicker-Month");
let weekdaysElements = getElementsByClassName(dayPickerNode, "DayPicker-Weekdays");
let weekdayElements = getElementsByClassName(dayPickerNode, "DayPicker-Weekday");
let bodyElements = getElementsByClassName(dayPickerNode, "DayPicker-Body");
let weekElements = getElementsByClassName(dayPickerNode, "DayPicker-Week");
let dayElements = getElementsByClassName(dayPickerNode, "DayPicker-Day");

expect(dayPickerNode.getAttribute("role")).to.equal("widget");
expect(monthElements.every(el => el.getAttribute("role") === "grid")).to.be.true;
expect(monthElements.every(el => el.getAttribute("aria-readonly"))).to.equal("true");

monthElements.forEach((el, i) => {
  let captionId = captionElements[i].getAttribute("id");
  expect(el.getAttribute("aria-labelledby")).to.equal(captionId);
});

expect(weekdaysElements.every(el => el.getAttribute("role"))).to.equal("rowgroup");
expect(weekdayElements.every(el => el.getAttribute("role") === "columnheader")).to.be.true;
expect(bodyElements.every(el => el.getAttribute("role") === "rowgroup")).to.be.true;
expect(weekElements.every(el => el.getAttribute("role") === "row")).to.be.true;
expect(dayElements.every(el => el.getAttribute("role") === "gridcell")).to.be.true;

[basham]

Figured most of these suggestions would be really easy to implement. Thanks for the quick work on this.

I also assumed that aria-disabled, aria-selected, title and aria-label would need some additional work and experimentation. Glad to see those issues are getting special attention.

[basham]

I retract my suggestion of having aria-activedescendant on .DayPicker-Month. Turns out that approach would be most appropriate if you would leave focus only on .DayPicker[role="widget"] and it would never move elsewhere in the widget.

Since you're already managing focus on widget descendants, it's probably best to just leave the code as-is. Additionally, focus is a more established feature than aria-activedescendant, so what you've already done is a more backwards compatible approach.

References

• 3.2.2. Using activedescendant to Manage Focus for Widget Children
• 3.2.3. Managing Visual Focus with tabindex Alone

[ezufelt]

Would be happy to test a PR with a screen-reader.

[davidgilbertson]

I'm sure you know already, but you can easily test the compliance here: https://validator.w3.org/nu/#textarea

At the moment it's the only thing stopping our site from passing WCAG AA, so looking forward to this one!

(BTW, great component)

[gpbl]

Hi @davidgilbertson yes thank you for the link!
I won't forget this issue... I'm just a bit overwhelmed by the quantity of things i've to read and pay attention to :-)

[davidgilbertson]

If I am able to get this change set up as a task in my project, would you consider a pull request?

[gpbl]

I would really appreciate any help, @davidgilbertson!

[davidgilbertson]

OK it looks like I can get this as a task in my next sprint. To be clear I plan to fix these three issues thrown by the w3 validator:

• Bad value widget for attribute role on element div.
• Element attr not allowed as child of element div in this context.
• An element with role=row must be contained in, or owned by, an element with role=treegrid or role=grid or role=rowgroup.

Should come up a few weeks from now.

[davidgilbertson]

I'm interested, what is <attr> in the source? I've never seen that before and can't find any info on it.

[gpbl]

OMG @davidgilbertson I think that attr was meant abbr 😭 fixed with #106! Great you've found it!

[davidgilbertson]

Happens to the best of us. :)

[ragesoss]

Hi! This is just to say that my project has really appreciate this react-day-picker, and we're looking forward to improvements in accessibility. One of my colleagues uses a screen reader, and cannot use the calendar in our app. There are, in particular, two issues for screen readers:

• Day cells are not clickable
  • We solved that problem on a derivative "weekday picker" by changing divs to buttons,: ntdb/react-weekday-picker@64d1be8
• There is no indication of selected/not-selected/disabled state.
  • This is what adding the aria-selected attributes would do.

Echoing @ezufelt above, I'm happy to help test any patches that might fix those issues.

[gpbl]

Thanks @ragesoss! There's a PR from @limscoder that may add some improvements for ARIA, but I'm not sure if it fixes all the issues. Going to check it out soon.

[davidgilbertson]

FWIW...

After thinking about this for a while, if I couldn't see (or was a keyboard navigator), I would much rather just type a date than navigate a calendar, so we are aria-hiding the calendar and just having an input field to type date.

[ragesoss]

@davidgilbertson That makes sense for picking a single date — I know that's what my colleague Helaine prefers when it's a matter of one date — but will it work for a calendar that is being used to select multiple dates? In my app, we use it with three states and lots of selected dates at once.

[basham]

@davidgilbertson I work for Indiana University, and consulting with our assistive technologies team, they say the same thing. A text input is much simpler to use for a keyboard user. And a text input is much easier to understand for those navigating with only a screen reader.

Assuming that's the case and assuming the intention is to select one date at a time, I think it's less imperative that this date picker can be controlled with a keyboard. I think we need to think about what is the best way to provide equivalent controls with a text input. Perhaps this text control is another project. Maybe it is a sub-component of this project.

My current thought is that Facebook's date input for events is a rather fantastic exemplar. The up/down arrow keys toggles through the month/day/year based on the placement of the keyboard cursor, providing very quick non-calendar-based input.

[gpbl]

@ragesoss is right saying that for multiple days input fields would not be enough.
I think we can't escape it, this component must support users adopting assistive technologies.

There are already three pull requests (two of them are rather old) waiting to be analyzed and merged. It seems, however, they require a good amount of work 😅 I'm committed to work again on this soon!