Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Create Pickers accessibility page #13274

96 changes: 96 additions & 0 deletions docs/data/date-pickers/accessibility/accessibility.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
---
productId: x-date-pickers
title: Date and Time Pickers - Date format and localization
arthurbalduini marked this conversation as resolved.
Show resolved Hide resolved
githubLabel: 'component: pickers'
packageName: '@mui/x-date-pickers'
---

# Date and Time Pickers - Accessibility
arthurbalduini marked this conversation as resolved.
Show resolved Hide resolved

<p class="description">The Date and Time Pickers have complete accessibility support, including built-in keyboard navigation that follows international standards.</p>

## Guidelines

The most commonly encountered conformance guidelines for accessibility are:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

copyediting

Suggested change
The most commonly encountered conformance guidelines for accessibility are:
Common conformance guidelines for accessibility include:

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nitpick: This section is a copy and paste from Data Grid and Tree View a11y pages.
If we apply this change, it would be nice to replicate it on those pages as well. 👍

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@arthurbalduini do you plan on applying these changes?
Or are you leaving that for a separate PR?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After discussing with @samuelsycamore, I will apply these changes and also replicate them to the other pages where they appear on this PR


- Globally accepted standard: [WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/)
- US:
- [ADA](https://www.ada.gov/) - US Department of Justice
- [Section 508](https://www.section508.gov/) - US federal agencies
- Europe: [EAA](https://ec.europa.eu/social/main.jsp?catId=1202) (European Accessibility Act)

WCAG 2.1 has three levels of conformance: A, AA, and AAA.
Level AA meets the most commonly encountered conformance guidelines.
This is the most common target for organizations so what we aims to support very well.
arthurbalduini marked this conversation as resolved.
Show resolved Hide resolved

<!-- Those examples do not cover the clock component -->

arthurbalduini marked this conversation as resolved.
Show resolved Hide resolved
The WAI-ARIA Authoring Practices includes examples on [Date Picker Dialog](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/) and [Date Picker Spin Button](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/examples/datepicker-spinbuttons/) that provide valuable information on how to optimize the accessibility of the Date and Time Pickers.
arthurbalduini marked this conversation as resolved.
Show resolved Hide resolved

## Screen reader compatibility

Date and Time Pickers provide support to ARIA roles and a robust focus management across the interactive elements to convey the necessary information to users, being optimized for use with assistive technologies.
arthurbalduini marked this conversation as resolved.
Show resolved Hide resolved

## Keyboard support

The Date and Time Pickers consist on different associations of Fields, Calendar, Time and Digital Clock components, each of them designed to respond intuitively to keyboard interactions, providing a better experience for users who rely on keyboard navigation.
arthurbalduini marked this conversation as resolved.
Show resolved Hide resolved

Each available component presents its own keyboard support, detailed on the following section:
arthurbalduini marked this conversation as resolved.
Show resolved Hide resolved

### Fields

The following table describes the keyboard support for all [field components](/x/react-date-pickers/fields/)
arthurbalduini marked this conversation as resolved.
Show resolved Hide resolved

| Keys | Description |
| ---------------------------------: | :------------------------------------------- |
| <kbd class="key">Arrow Left</kbd> | Moves focus among date/time sections |
| <kbd class="key">Arrow Right</kbd> | Moves focus among date/time sections |
arthurbalduini marked this conversation as resolved.
Show resolved Hide resolved
| <kbd class="key">Arrow Up</kbd> | Increases focused section value by 1 |
| <kbd class="key">Arrow Down</kbd> | Decreases focused section value section by 1 |
| <kbd class="key">Page Up</kbd> | Increases focused section value section by 5 |
| <kbd class="key">Page Down</kbd> | Decreases focused section value section by 5 |
| <kbd class="key">Home</kbd> | Sets focused section to the first value |
| <kbd class="key">End</kbd> | Sets focused section to the last value |
LukasTy marked this conversation as resolved.
Show resolved Hide resolved

### Date Calendar

All the available [views](/x/react-date-pickers/date-calendar/#views) implement the same basic keyboard support:

| Keys | Description |
| --------------------------------------------------------: | :------------------------------------- |
| <kbd class="key">Tab</kbd> | Moves focus to the next element |
| <kbd class="key">Shift</kbd>+<kbd class="key">Tab</kbd> | Moves focus to the previous element |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nitpick: these are regular keyboard navigations between focusable document items, I'm not sure if we need to mention this behavior here. 🤔
WDYT?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I put that on purpose to leave a breach to mention the component as a whole before talking about day view's specific keyboard support.
I agree this part is quite irrelevant. Do you think that on the Date Calendar section we could only talk about the day view ?

Copy link
Member

@LukasTy LukasTy May 30, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you think that on the Date Calendar section we could only talk about the day view ?

That is an option, but if you think mentioning other views brings value, I'm all for it. 👍

Copy link
Member Author

@arthurbalduini arthurbalduini Jun 5, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have rewritten the sentence on #206e723 to remove the unnecessary mention of the regular keys support. Your opinion would be extremely valuable to me ! 🙂

| <kbd class="key">Arrow Keys (Left, Right, Up, Down)</kbd> | Moves focus among the available values |

In addition to the basic keyboard support above, the day view component implements its own keyboard interactions:
LukasTy marked this conversation as resolved.
Show resolved Hide resolved

| Keys | Description |
| -------------------------------: | :-------------------------------------------------------------------------------- |
| <kbd class="key">Page Up</kbd> | Moves calendar to next month, keeping focus on the same day |
| <kbd class="key">Page Down</kbd> | Moves calendar to previous month, keeping focus on the same day |
| <kbd class="key">Home</kbd> | Moves focus to first day of the week, tresspassing to previous month if necessary |
| <kbd class="key">End</kbd> | Moves focus to last day of the week, tresspassing to next month if necessary |
arthurbalduini marked this conversation as resolved.
Show resolved Hide resolved

### Date Picker

The [Date Picker](/x/react-date-pickers/date-picker/) combines the functionalities of the Date Field and Date Calendar components.

Depending on which component is in focus, the Picker will provide the corresponding keyboard support, either from [DateField](/x/react-date-pickers/accessibility/#fields) or [DateCalendar](/x/react-date-pickers/accessibility/#date-calendar) and any changes made to the value will be consistently reflected across both components.
arthurbalduini marked this conversation as resolved.
Show resolved Hide resolved

### Date Range Calendar

The Date Range Calendar implements a similar keyboard support as day view of the [DateCalendar](/x/react-date-pickers/accessibility/#date-calendar) component, with a difference on the navigation among the previous and next months that must be achieved using the auxiliar arrows.
arthurbalduini marked this conversation as resolved.
Show resolved Hide resolved

| Keys | Description |
| --------------------------------------------------------: | :---------------------------------------- |
| <kbd class="key">Arrow Keys (Left, Right, Up, Down)</kbd> | Moves focus among the available values |
| <kbd class="key">Page Up</kbd> | Moves focus to the last day of the month |
| <kbd class="key">Page Down</kbd> | Moves focus to the first day of the month |
| <kbd class="key">Home</kbd> | Moves focus to first day of the week |
arthurbalduini marked this conversation as resolved.
Show resolved Hide resolved
| <kbd class="key">End</kbd> | Moves focus to last day of the week |
arthurbalduini marked this conversation as resolved.
Show resolved Hide resolved

### Date Range Picker

The [Date Range Picker](/x/react-date-pickers/date-range-picker/) integrates the features of both the Date Range Field and Date Range Calendar components. However it doesn't inherently provides every keyboard support implemented in these components.
arthurbalduini marked this conversation as resolved.
Show resolved Hide resolved

To ensure a more fluid and more accessible user experience, Date Range Picker support the same keyboard navigation and interactions of the [Field](/x/react-date-pickers/accessibility/#fields) components, having the changes being consistently displayed on the calendar component.
arthurbalduini marked this conversation as resolved.
Show resolved Hide resolved
1 change: 1 addition & 0 deletions docs/data/pages.ts
Original file line number Diff line number Diff line change
Expand Up @@ -229,6 +229,7 @@ const pages: MuiPage[] = [
{ pathname: '/x/react-date-pickers', title: 'Overview' },
{ pathname: '/x/react-date-pickers/getting-started' },
{ pathname: '/x/react-date-pickers/base-concepts' },
{ pathname: '/x/react-date-pickers/accessibility' },
{ pathname: '/x/react-date-pickers/faq', title: 'FAQ' },
{
pathname: '/x/react-date-pickers-components',
Expand Down
7 changes: 7 additions & 0 deletions docs/pages/x/react-date-pickers/accessibility.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
import * as React from 'react';
import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
import * as pageProps from 'docsx/data/date-pickers/accessibility/accessibility.md?muiMarkdown';

export default function Page() {
return <MarkdownDocs {...pageProps} />;
}