Develop example of date picker design pattern using a combobox that opens a dialog

[ckundo]

Add a mobile-compatible example of a date picker that employs the form of the ARIA 1.1 combobox pattern that pops up a dialog.

Completing this issue will also complete issue #534.

Development is in the issue34-date-picker-examples branch. Use that branch as the base for pull requests related to this issue.

Preview link for feature branch

Date picker combobox example in feature branch

Related to issue #57.

[ckundo]

I'm taking a pass at this now.

[ckundo]

FWIW, there's a solid example of this marked up already at http://www.oaa-accessibility.org/example/15/. Is it worth reaching out to the author to reuse their example here?

[jnurthen]

@jongund @a11ydoer is the code at http://www.oaa-accessibility.org/example/15/ either of yours?

[mcking65]

Here is the initial cut of an example page by @jongund merged into the issue34-date-picker-examples branch with commit 5d16101.

Rather than immediately tackling issue #57, this example could work as an example for the combobox pattern. That pattern needs an example of a combobox that pops up a dialog.

[jongund]

@mcking65 I have pushed a new version of the datepicker example. I had to rewrite most of the code, but it should be much easier to make modifications to the example with the new code base.

[jongund]

Link to the new example:
https://raw.githack.com/w3c/aria-practices/issue34-date-picker-examples/examples/datepicker/datepicker.html

[mcking65]

Per discussion in today's meeting, issues that need further discussion:

1. Where should focus go after a date is chosen from the grid in the dialog? If it goes to the text field, that pops open mobile keyboards. If it goes to the down arrow icon, it is confusing for screen reader and keyboard users who moved focus into the dialog from the text field with down arrow.

2. When should the dialog be visually displayed? It is very common for calendars to display when the text field is focused or clicked. Does that mean the user has to move focus out of the input to get the calendar to disappear?

[accdc]

Hi,
I've been running some experiments, and have created two Auto onFocus ARIA-based date pickers for you to try out using the keyboard and with screen readers.

1. Editable standard input field and no date restrictions.
   http://whatsock.com/tsg/Coding%20Arena/ARIA%20Date%20Pickers/ARIA%20Date%20Picker%20(Basic,%20Auto%20Open)/demo.htm

2. Readonly standard input field with relative forward and backward disabled dates plus disabled weekends.
   http://whatsock.com/tsg/Coding%20Arena/ARIA%20Date%20Pickers/ARIA%20Date%20Picker%20(Basic,%20ReadOnly%20Auto%20Open%20plus%20Disabled%20Ranges)/demo.htm

Directions:

1. Set focus to the input field, the date picker opens automatically.
2. Desktop keyboard users can press the Down arrow to move focus into the calendar to move around as desired, or press Escape to close the calendar before or after moving focus into it.
3. Touch device users can tap the associated toggle button to open or close the calendar as desired.
4. After a date is saved, focus is always set back to the input field.

Personally, I think the keyboard functionality and screen reader feedback is very helpful, and this design pattern is already accessible in JAWS12 through 2019 and in NVDA using IE11, Firefox, and Chrome Canary.
I also just tested this in iOS Safari with VoiceOver, and it works as expected there with no accessibility issues that I can detect, even when focus is returned to the input field.

Some notes, this is not implemented as a combobox because for this, it doesn't need to be. Also, within this design pattern, you will notice that the external toggle button is also in the tab order. Though it can be taken out using tabindex="-1", I don't recommend this as a practice, because there is no guarantee that sighted keyboard only users will always be aware that they can press the Down arrow on the input field to move focus into the date picker, and having an explicit button for this purpose guarantees accessibility for all user types regardless.

The code for these widgets can be found within the Coding Arena in the download at
https://github.com/whatsock/tsg

Best wishes,
Bryan

[accdc]

As a quick update, others at Level Access have been testing the same design pattern I shared here, and behaviorally it does appear to be a reliable one. There were only a few issues with unreliable user expectations, where it wasn't clear that pressing the Down arrow was the expected keystroke for moving focus into the calendar. As a general paradigm however, and with proper visual indicators such as an arrow icon and the like for making it clear when the input field has focus that pressing 'down' is an option, most of this can be addressed by general public exposure and basic training for using these types of widgets, as long as we can establish a general keyboard pattern that we agree upon and publicize clearly.

A quick note regarding the examples I recently posted: At present I have these set not to show onFocus when a touch device is detected, because I’m not sure how disruptive that would be for mobile device users, which unfortunately includes all desktops with touch-support monitors like hybrid laptops. I haven’t found a simple way of differentiating these reliably as yet.

This is something we are going to have to keep in mind for all of our widgets though, because the keyboard paradigm does not always port equally over into touch, especially when some devices do both such as hybrid laptops. This is another reason why it is important to ensure that the extra triggering element remains in the tab order, to account for those who cannot access the standard event trigger when this is focus-based.

[mcking65]

@jongund, here is a summary of today's discussion ...

Where should focus go after a date is chosen from the grid in the dialog?

It should return to the edit field and close the dialog. For most devices and assistive tech, this is the best experience. One compromise is that this does have the downside that it may re-display a touch keyboard.

2. When should the dialog be visually displayed? It is very common for calendars to display when the text field is focused or clicked. Does that mean the user has to move focus out of the input to get the calendar to disappear?

Display the dialog when:

1. The text field receives keyboard focus.
2. The text field or down icon is touched. Note, however, if the text field is touched when the dialog is not open, only open the dialog, DO NOT focus the text field. If the text field is touched when the dialog is open, focus the text field. This should prevent unwanted display of the keyboard.
3. The text field or down icon is clicked with a mouse. Clicking the text field should, as is normally expected, focus the text field.

Close the dialog when:

1. Escape is pressed and focus is either in the dialog or in the text field.
2. Focus is in the text field and tab or shift+tab is pressed.
3. The dialog cancel button is clicked or touched.
4. The dialog is open and the down arrow icon is clicked or touched.

Move keyboard focus into the dialog when:

1. Focus is in the text field and up or down arrow is pressed.
2. The user clicks or touches in the dialog.

[mcking65]

Is it possible we could prevent unwanted display of the touch keyboard when a date is chosen by detecting when a date is chosen by touch? That is, if a date is touched and the dialog is closed, place focus on the down arrow icon. However, if a date is chosen via the keyboard or mouse click, put focus in the text field.

If we did this, we would want the accessible description of the down arrow icon to reference the text field. I am assuming the accessible name would be "Open calendar."

[accdc]

Hi,
Based on our discussion yesterday, I've made several important changes to the ARIA date pickers I've referenced for testing. This will probably help as we try to document a reliable keyboard paradigm for both combobox and non-combobox patterns, as well as to address hybrid patterns that work equally well across both keyboard and touch devices, so please test these using both device types.

James, I tried to locate the test urls you sent me, but I couldn't access this in my IRC history and it doesn't appear to be in the meeting minutes. Either way though, I understand your points about having a need to display the date picker on touch without showing the virtual keyboard, and I have already solved this without requiring focus redirection to do so.

A few notes about the changes.

1. I have made it possible to auto-render the calendar on touch screen devices, which includes hybrid laptops, and mobile devices like iPads and iPhones. This includes relevant state indicators such as aria-expanded where relevant to convey this to screen reader users. For editable date picker input fields, you can touch the input to render the calendar, yet this will not render the virtual keyboard, but if you touch the field again, it will render the virtual keyboard and make the calendar disappear. This works with VoiceOver running by double-tapping the input field as well.
2. For sighted keyboard only users, I have added a visual indicator to convey that the ‘down’ arrow key is active when the calendar is rendered, which disappears when the calendar is closed, to make it clear that you can press the Down arrow to navigate into the date picker after focus is set to the input field.
3. I have updated the instructions at the end of the page to match the page functionality so as not to confuse everybody going forward.

Test urls

1. Editable
   http://whatsock.com/tsg/Coding%20Arena/ARIA%20Date%20Pickers/ARIA%20Date%20Picker%20(Basic,%20Auto%20Open)/demo.htm
2. Readonly
   http://whatsock.com/tsg/Coding%20Arena/ARIA%20Date%20Pickers/ARIA%20Date%20Picker%20(Basic,%20ReadOnly%20Auto%20Open%20plus%20Disabled%20Ranges)/demo.htm

Explanation

As a general design pattern, we should not rely upon focus movement hacks to either display or not display specific platform features like virtual keyboards. Instead, we should keep focus in a predictable and accessibility approved location and update functionality accordingly using the attached events for whatever widget currently has focus. This can be done by modifying the event order of precedence when triggered on the input field, and it does not require setting focus to inactive parent elements to trick the browser into doing something different.

The above examples show the results of this methodology, and the only technique that is being used is the utilization and conditional processing of specific attached events on the input field. Specifically, these include the ontouchstart and onfocus event handlers. The ontouchstart handler is always processed before the display of a virtual keyboard, and if returned false (event.preventDefault) is used to cancel this handler, then it will not display the virtual keyboard on the screen, and this event will only fire when the input field is touched using a touch screen. If ontouchstart is canceled, then the onFocus event will not fire either.

So, to achieve the same logic on an auto-opening calendar when focus is set to an editable input field, do the following.

1. Attach both an ontouchstart and onfocus handler to the input.
2. Within the ontouchstart handler, check if the calendar is already open, and if so, do nothing. Otherwise, render the calendar and return false to prevent further processing. The ontouchstart handler will only fire when touched.
3. Within the onfocus handler, check if the calendar is already open, and do nothing if so. Otherwise, render the calendar and provide a help prompt such as a live region to convey to non-sighted screen reader users that the down arrow key is needed to move focus into the calendar. The onfocus handler will fire when keyboard users set focus to the input, and also after ontouchstart fires if ontouchstart is not cancelled beforehand. The touch event can be queried to ensure that keyboard specific instructions are only announced for keyboard users.
4. Add an onclick to the input field, and within that handler, check if the calendar is already open, and close it if so, which will turn the input field into a toggle and allow for the display of the virtual keyboard when the editable input field is touched a second time using a touch device.

Every time a calendar is rendered, preferably within a callback for this purpose, aria-expanded needs to be set on the input field to convey the active state of this calendar for non-sighted screen reader users. Also, if a separate triggering element is present that can be used as a toggle like in the examples above, these too need to include aria-expanded to convey the same thing, since both control the same calendar, and the triggering element that has focus must convey its active state regardless which one it is.

I've also had these example design patterns extensively reviewed internally, and to ensure accessibility for sighted keyboard only users, it is necessary to include a dynamically updated visual indicator such as an arrow icon to convey that the user can press the Down arrow when the input has focus to then move focus into the calendar for navigation. Also, a clear visual indicator does not have to be normalized for different languages like a plain text message would have to be.

By combining all of these things as I did, you can indeed create a reliable and provably accessible auto-renderrable date picker that works across both desktop and touch devices equally within the same design pattern; without having to include focus movement hacks to disrupt native functionality within mobile devices.

To review the code for these widgets, it has already been added to
https://github.com/whatsock/tsg

[accdc]

Hi,
A bit more feedback with continued testing internally for this widget type.

Apparently, for sighted keyboard only users, it can be confusing to only provide Down arrow access into the calendar, because this is not an expected widget type like a list or menu as dropdowns are styled as.

As such, the recommended fix is to provide Down arrow as the intended method for doing this, however pressing Tab will also set focus into the calendar when expanded, which allows all user types to most accessibly use this widget type with the least amount of confusion. Escape can still close the calendar as before to allow keyboard users to continue navigation as expected as well. Also, pressing Shift+Tab will automatically close the calendar when focus is still on the editable input field.

For testing, this functionality has been added to the live demo at
http://whatsock.com/tsg/Coding%20Arena/ARIA%20Date%20Pickers/ARIA%20Date%20Picker%20(Basic,%20Auto%20Open)/demo.htm

[pbossley]

Sorry if I missed this somewhere in the comments, but some programatically associated keyboard instructions for screen reader reliant users e.g. maybe with aria-describedby might help a lot in ensuring a minimum of problems for users encountering this for the first time.

[frastlin]

@accdc I like that example, but for some reason, when using NVDA and Firefox, I get the following behavior:

1. When hitting down arrow in brows mode over the top of the text input, the calendar expands and when I hit enter on the dialogue, I am taken to a place with only the navigation buttons, not the dates.
2. When I switch a month in the calendar view, the instruction text is read again. this is really annoying when quickly moving through dates.

I really like this functionality as a calendar though.

@pbossley yes,, there should be something similar to "pres down arrow to view calendar", but it is not a very big deal as long as there is a button in the next index that when clicked will open the calendar.

[accdc]

Thanks @frastlin,
I see what you mean, for now I've disabled the auto-announcement of the help text every time a new month is rendered, and it will only announce the help text the first time the calendar is opened and focus is set within it.

I also reproduced the arrowing you mentioned in NVDA, and this is a combination of things, not so easily addressed for this type of auto-opening widget.

The way that the input field works, is by using an onFocus handler to auto render the date picker visually, and this is necessary for sighted keyboard only users.

However, NVDA, when arrowing down the page in Browse Mode, will automatically trigger the onFocus handler upon any element that has one attached, which is why the calendar is auto-opening when you read it without entering Applications Mode first as it does when you press Tab instead. So, this is why when you press Down again you arrow passed the edit field instead of opening the calendar as you would expect.

For this to work in NVDA, you would have to press Enter on the edit field first to enter Applications Mode before you use the Down arrow to set focus into the calendar.

Unfortunately there appears to be no way to prevent NVDA from doing this auto-onFocus triggering prematurely, which is another reason why it is important to make sure there is a second button-like triggering element that performs the same action next to the input field, so that non-standard keystrokes and unexpected circumstances like these can be circumvented by manually activating the associated toggle button instead.

[frastlin]

NVDA still says something about a new dialogue every month.
Maybe if the user focuses the button and the button is expanded, then it will collapse.
The dialogue puts you into the navigation area and it is not clear how to get into the calendar when you are in the navigation area. I would say if one is in the navigation area, and they press escape, it jumps them into the calendar, and if they are in the calendar, then escape closes the calendar.

[accdc]

Hi @frastlin,

With some experimentation, I was able to track down an order of events that allows for NVDA to auto-close the calendar when arrowing. So, you can now arrow down the page using NVDA + Firefox in Browse Mode, and when you arrow past the edit field it will automatically close the calendar. This means, however, that you will have to manually activate the trigger button in order to open the calendar if you go past the focusable edit field.

Also, I changed which elements are exposed in the accessibility tree, and which ones have accessible names, so you should now find it much less verbose when switching between months. You will still hear the word 'dialog' however, but this is something that NVDA does automatically when focus is set within an ARIA dialog widget, and this is impossible to turn off. Even so though, you should find that the feedback is more understandable. I also disabled the announcement of table feedback which had to do with exposed element structures in the accessibility tree, since the column and row counts were not actually helpful in any way when announced as part of this navigation.

Relevant test pages:
Editable: http://whatsock.com/tsg/Coding%20Arena/ARIA%20Date%20Pickers/ARIA%20Date%20Picker%20(Basic,%20Auto%20Open)/demo.htm
Readonly: http://whatsock.com/tsg/Coding%20Arena/ARIA%20Date%20Pickers/ARIA%20Date%20Picker%20(Basic,%20ReadOnly%20Auto%20Open%20plus%20Disabled%20Ranges)/demo.htm

Does this work better for you?

[frastlin]

yes, that's almost perfect. The only thing is that the aria-expanded attribute doesn't show collapsed when I arrow down to the button. Everything else works perfectly.

[shirsha]

Please see the following comments regarding the date picker:
• Format (mm/dd/yy) is present in the form of a placeholder.
• NVDA/Firefox and NVDA/Chrome skips the "Date" heading, the date input field and the "pick a date" button in virtual mode.
• In IE11, user is unable to access the calendar dialog via keyboard or JAWS. The dialog is not opened when the user tabs to input field.
• JAWS/IE11 narrates the date input field as "date link".
• JAWS/IE11 narrates the "pick a date" button as combo box dialog in virtual mode.
• Keyboard only and screen reader user is unable access the date picker dialog once the dialog is closed via [esc] or "cancel" button. They have to tab out of the input field and tab back to it to access the dialog.
• "Pick a date" button does not pass the required color contrast ratio of 3:1
• Keyboard user and screen reader users (in forms mode) unable to access the "Pick a date" button as it has tabindex of "-1"

[jongund]

Siri, When the focus is in the textbox and the calendar is not showing, the calendar should open using the down arrow key as part of the combobox design pattern. https://raw.githack.com/w3c/aria-practices/issue34-date-picker-examples/examples/datepicker/datepicker.html Jon From: Shirisha Balusani <[email protected]> Sent: Saturday, March 30, 2019 7:08 PM To: w3c/aria-practices <[email protected]> Cc: Gunderson, Jon R <[email protected]>; Mention <[email protected]> Subject: Re: [w3c/aria-practices] Develop example of date picker design pattern using a combobox that opens a dialog (#34) Please see the following comments regarding the date picker: • Format (mm/dd/yy) is present in the form of a placeholder. • NVDA/Firefox and NVDA/Chrome skips the "Date" heading, the date input field and the "pick a date" button in virtual mode. • In IE11, user is unable to access the calendar dialog via keyboard or JAWS. The dialog is not opened when the user tabs to input field. • JAWS/IE11 narrates the date input field as "date link". • JAWS/IE11 narrates the "pick a date" button as combo box dialog in virtual mode. • Keyboard only and screen reader user is unable access the date picker dialog once the dialog is closed via [esc] or "cancel" button. They have to tab out of the input field and tab back to it to access the dialog. • "Pick a date" button does not pass the required color contrast ratio of 3:1 • Keyboard user and screen reader users (in forms mode) unable to access the "Pick a date" button as it has tabindex of "-1" — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub<#34 (comment)>, or mute the thread<https://github.com/notifications/unsubscribe-auth/ABcE7Ny70Vp4oR2xZJ1z1-XKBOLzEy8Pks5vb_xEgaJpZM4ITfeK>.

[mbgower]

Nice prototype! A couple of comments:

• With that nice rich calendar UI, why not throw in a Help button to tell a keyboard user about all the keyboard interactions? Would be very unobtrusive and a nice precedent to set.

• I didn't feel like the dropdown icon gave me enough of a visual hint that I moved to the calendar with a down arrow. I don't have anything super helpful to suggest at this second (other than maybe adding some actual text about that shortcut; especially if you do give an easy affordance to more keyboard help once in, that is the only real thing that needs to be intuitive).

• On consideration, I think the fact the calendar appeared on focus was what threw me off a bit here. If it was a second tabstop you could just make the calendar open on Enter and put focus right in it. Was that tried? I can't see a usability issue with that. It's not like many UIs will have tons of date entry fields :)

[mbgower]

BTW, @mcking65 , I recognized your fingerprints all over this. Takes me back to a few sessions we spent on this at IBM.

[a11ydoer]

@jongund @mcking65 and I reviewed the example together. Updates by Jon are coming up. (ie. Two of them are 1)removing aria-expanded and 2)adding autocomplete in input type="text")

[a11ydoer]

Updated example by @jongund This will be discussed at ARIA -APG meeting on May 21, 2019
https://raw.githack.com/w3c/aria-practices/issue34-date-picker-examples/examples/datepicker/datepicker-combobox.html

[smhigley]

From the meeting: one of the questions was whether the supplemental button next to the input should exist as a semantic button. Keeping it a <button> means that there will be two form controls exposed to screen readers for the one calendar control.

There is already the guideline that there should be one tab stop for the control. Should there also be pattern guidance for only exposing one semantic form control per combobox?

[jnurthen]

In the current example the keyboard pops up on iOS when selecting a date in the calendar. Suggest not moving focus to the text field to avoid this problem.