Cally

Accessibility

What has been tested, and how?

These components aim to be accessible to all users, whether they are using touch screens, keyboards, screen readers, or other assistive technology. ARIA is used when necessary to enhance the underlying HTML. Focus is managed where appropriate. The components have been tested with a variety of browsers and screen readers.

Guarantee…?

In some regards the components offered here are akin to design system components. They are low-level pieces to a larger puzzle. The components themselves strive to offer the best possible accessible baseline. But beyond that, any guarantees that can be made regarding accessibility are limited. The way the components get used and combined can still lead to inaccessible outcomes.

If you are composing these components into more complex interfaces, you will need to test and evaluate accessibility yourself.

Approach

The <calendar-month> component uses a standard <table> to display a grid of dates. Notably, the grid role is not used. Therefore, to navigate the columns, rows, and cells, users can use standard table navigation commands.

Each <table> is labelled with the month name. Each column is labelled with the day name. Each cell contains a button, which displays the date as a number, but is labelled non-visually with the full date e.g. "19 April". The format of the date label depends on the given locale.

aria-pressed is used on buttons to mark selected dates. For single date selection, only one day will ever be marked as pressed. For date ranges, a contiguous set of days will be marked as pressed.

The <calendar-date> and <calendar-range> components use a group role, which is labelled with the month and year(s) currently displayed e.g. "April – June 2024". This is marked as a live region, so changes are communicated to users as they navigate through dates. How this is formatted depends on the given locale.

The "Previous" and "Next" buttons are marked as disabled via aria-disabled, so that focus does not get lost when users reach the min or max date.

Testing

At a minimum testing will be done with the following browser and screen reader combinations:

These combinations were last tested April 2024.

Known issues

There are some minor issues in how date ranges formatted via Intl.DateTimeFormat (e.g. "April – June 2024") get announced. JAWS announces "April en dash June 2024". This may be confusing to users if they do not understand what an "en dash" is. In contrast, VoiceOver and NVDA do not announce the dash at all, announcing "April June 2024". This may obscure the fact that a date range is being announced. There is no viable mitigation for this right now. Locale-aware date formatting is complex, and so we must rely on the native Intl.DateTimeFormat API.

If you have found a bug related to accessibility, please report an issue on github.