USWDS - Date picker: Prevent focus on mouseover #5774

mahoneycm · 2024-02-15T21:02:15Z

Summary

Fixed a bug that caused mouseover events to focus buttons and prevent keyboard navigation. Now, hovering the mouse over date picker buttons will only cause the hover state.

Breaking change

This is not a breaking change

Related issue

Closes #5752

Related pull requests

Changelog →

An alternative approach to #5778. This approach introduces a separate accessibility issue where screen-readers read the focused date every time a date button is hovered. This includes when a new date is selected via the keyboard while the mouse is hovering over a date. This would introduce confusion for screen reader users.

Preview link

Date Picker →

Date Range Picker →

Problem statement

Hovering the mouse over date picker calendar buttons cause them to gain focus. This is unexpected behavior which also prevents keyboard navigation through calendar buttons.

Solution

Rework the handleMouseoverFromDate() function to target the date buttons of the current month and add the --within-range class. The function no longer calls the renderCalendar() function or sets focus on the hovered dates.

Follows expected mouseover behaviors.
Does not affect date picker or date range usage.

Additionally, I removed the mouseover event listeners and functions from month and year buttons. They did not appear to add any functionality beyond focusing the button on hover, which we want to prevent.

handleMousoverFromDate is maintained in order to properly render date range previews on hover.

Accessibility improvements

This solution improves accessibility interaction in two ways.

VoiceOver

In its current iteration, when using the date picker with a mouse and VoiceOver, it would rapidly call out dates as your mouse moved over them. This, in my opinion, is unexpected behavior. VoiceOver should not read out other buttons or table content upon mouseover events.

With this update, VoiceOver will only call out the buttons when selected via the keyboard.

High zoom magnification behaviors

As depicted in #5752, using the date picker at a high magnification (400%, AA requirement) the mouse would sometimes jump to the selected button, causing a mouseover event, and locking the focus on that button. Keyboard interaction would be prevented by the hovered mouse. For users who rely on keyboard navigation, this would cause confusion as they would not move the mouse to identify the issue.

With this update, users will be able to use expected keyboard interactions without error.

Alternatives considered

blur

I tested calling blur() on the selected element during keyboard interactions, but this caused accessibility issues at high zoom (400%). The window would jump unexpectedly and cause the mouse to move, hovering a new button, which then stole focus once again.

Reassigning focus on render

This was the approach taken in #5778.

I tested storing the focused button value and reapplying focus after the calendar re-rendered. Visually, this solution worked fine but caused the screen reader to call out the focused date every time the mouse hovered a new date. The date wouldn't match what is hovered and could be confusing for users if their mouse accidentally hovered over a date button.

Removing mouseover events altogether

Originally, I had removed mouseover events altogether. This caused a visual regression when selecting a date range for the first time where the range preview would not show.

Additional concerns

Current date picker behaviors cause a new calendar to be rendered after every mouseover and keyboard event. It does so by cloning the existing calendar, setting appropriate classes and returning an HTML template literal. This pattern does not match modern USWDS practices and likely affects performance.

Major changes

Date picker no longer updates focus on mouseover events.
Behavior changes help to meet WCAG AA requirement
Created a new setRangeDates() function to capture repeated behaviors to set range dates within the render calendar and handle mouseover functions.

The intent of this Success Criterion is to support people with low vision who need to enlarge text and read it in a single column. When the browser zoom is used to scale content to 400%, it reflows - i.e., it is presented in one column so that scrolling in more than one direction is not necessary. ¹

Testing and review

Visit date picker.
Test mouse interactions and confirm they work as expected.
Test keyboard interactions and confirm they work as expected.
- Note: Ensure you can use keyboard navigation while the mouse is hovering a date
Test VoiceOver and ensure callouts are expected.
Zoom to 400% magnification and use the keyboard to interact with the date picker. There should be no errors navigating throughout the calendar.
Repeat steps for all variants.
Repeat steps date range picker and its variants.

Tip

When using keyboard navigation with a screenreader, use the screenreader’s Table Navigation controls (varies by screenreader). This can help prevent unexpected interactions. Use default arrow keys when jumping months via dates.

Testing checklist

Expected mouse behaviors work without error
Expected keyboard behaviors work without error
Screenreader behaviors work as expected without error
Component is usable at high magnification without error

WCAG Reflow (Level AA) requirement ↩

…emove-mouseover

mahoneycm · 2024-07-22T17:47:07Z

Reopening this PR due to additional accessibility errors caused by the approach taken in #5778

mahoneycm · 2024-07-22T18:36:56Z

packages/usa-date-picker/src/index.js

+const setRangeDates = (date, rangeDate) => {
+  const rangeConclusionDate = date;
+  const rangeStartDate = rangeDate && min(rangeConclusionDate, rangeDate);
+  const rangeEndDate = rangeDate && max(rangeConclusionDate, rangeDate);
+
+  const withinRangeStartDate = rangeDate && addDays(rangeStartDate, 1);
+  const withinRangeEndDate = rangeDate && subDays(rangeEndDate, 1);


This code was used in the renderCalendar function to set range dates. I moved it to its own function so I can use it to set range dates on mouseover.

mahoneycm · 2024-07-22T20:29:00Z

packages/usa-date-picker/src/index.js


-  const currentCalendarDate = calendarEl.dataset.value;
-  const hoverDate = dateEl.dataset.value;
+  if (selectedDate) return;


Returning early if there is a selected date. This allows us to match current date-range behaviors.

mahoneycm · 2024-07-22T20:29:48Z

packages/usa-date-picker/src/index.js

-    [CALENDAR_MONTH]() {
-      handleMouseoverFromMonth(this);
-    },
-    [CALENDAR_YEAR]() {
-      handleMouseoverFromYear(this);
-    },


Removed mouseover from month and year functions because we do not want to re-render and focus these buttons on hover.

mahoneycm · 2024-07-22T20:30:25Z

packages/usa-date-picker/src/test/date-picker-month-selection.spec.js

-
-    it("should update the focus when moving over a non-selected valid month", () => {
-      EVENTS.mouseover(
-        getCalendarEl().querySelector(
-          '.usa-date-picker__calendar__month[data-label="October"]',
-        ),
-      );
-
-      assert.strictEqual(
-        getCalendarEl(".usa-date-picker__calendar__month--focused").dataset
-          .label,
-        "October",
-        "focuses correct month",
-      );
-    });


Removed test because we are no longer setting focus when month buttons are hovered.

mahoneycm · 2024-07-22T20:30:42Z

packages/usa-date-picker/src/test/date-picker-mousemove.spec.js

-    it("should update the focus when moving over a non-selected valid day", () => {
-      root.dataset.minDate = "2020-06-01";
-      root.dataset.maxDate = "2020-06-24";
-      input.value = "6/20/2020";
-      EVENTS.click(button);
-      assert.strictEqual(
-        getCalendarEl(".usa-date-picker__calendar__date--focused").dataset
-          .value,
-        "2020-06-20",
-        "focuses correct date",
-      );
-
-      EVENTS.mouseover(
-        getCalendarEl().querySelector(
-          '.usa-date-picker__calendar__date[data-day="19"]',
-        ),
-      );
-
-      assert.strictEqual(
-        getCalendarEl(".usa-date-picker__calendar__date--focused").dataset
-          .value,
-        "2020-06-19",
-        "focuses correct date",
-      );
-    });
-


Removed test because we are no longer setting focus when date buttons are hovered.

mahoneycm · 2024-07-22T20:30:52Z

packages/usa-date-picker/src/test/date-picker-year-selection.spec.js

-    it("should update the focus when moving over a non-selected valid year", () => {
-      EVENTS.mouseover(
-        getCalendarEl().querySelector(
-          '.usa-date-picker__calendar__year[data-value="2022"]',
-        ),
-      );
-
-      assert.strictEqual(
-        getCalendarEl(".usa-date-picker__calendar__year--focused").dataset
-          .value,
-        "2022",
-        "focuses correct year",
-      );
-    });


Removed test because we are no longer setting focus when year buttons are hovered.

mahoneycm · 2024-07-22T20:32:24Z

packages/usa-date-picker/src/index.js

+  const dateButtons = calendarEl.querySelectorAll(
+    `.${CALENDAR_DATE_CURRENT_MONTH_CLASS}`,
+  );
+
+  dateButtons.forEach((button) => {
+    const buttonDate = parseDateString(button.dataset.value);
+    if (
+      isDateWithinMinAndMax(
+        buttonDate,
+        withinRangeStartDate,
+        withinRangeEndDate,
+      )
+    ) {
+      button.classList.add(CALENDAR_DATE_WITHIN_RANGE_CLASS);
+    } else {
+      button.classList.remove(CALENDAR_DATE_WITHIN_RANGE_CLASS);
+    }


For each date button in the current calendar month, check if it's value is within the date range.

If it is, add the within range class. If itis not, remove it.

mejiaj

Thanks for the update and such thorough documentation @mahoneycm! The alternatives considered section was really helpful.

A few notes on the PR description:

Is the alternate approach still relevant? Could you add a brief note as to which you favor and why?
Preview links send you to other PR's.

Tested

Component	Before	After
Datepicker	develop	current
Date range	develop	current

No regressions in mouse interactions
No regressions in keyboard interactions
Unit tests pass via npm run test:unit
No regressions on 400% zoom

Tested in Chromium 126 & Samsung S23 Android 13 Chrome.

Minor comments below.

mejiaj · 2024-07-23T17:41:51Z

packages/usa-date-picker/src/index.js

+/**
+ * @typedef {Object} DateRangeContext
+ * @property {Date} rangeStartDate
+ * @property {Date} rangeEndDate
+ * @property {Date} withinRangeStartDate
+ * @property {Date} withinRangeEndDate
+ */


praise: Thanks for adding this, I see the definitions on hover in VS Code.

packages/usa-date-picker/src/index.js

Co-authored-by: James Mejia <james.mejia@gsa.gov>

mahoneycm · 2024-07-23T21:38:24Z

@mejiaj I updated the PR description with the appropriate testing links, and additional information on why the alternative solution failed. I also committed one of your suggestions, and replied to the other comments!

Ready for your re-review 👍

mejiaj

Thanks for the responses, @mahoneycm!

amyleadem

@mahoneycm Looks good to me! The components behave as expected and I no longer experience the error described in the issue. Great work!

I have tagged @amycole501 and @alex-hull to review so that they can confirm the updated keyboard, zoom, and screen reader behavior in the components meets standards.

amycole501

Tested at standard view and 400% in both JAWS and NVDA. The only minor issue I found was NVDA kept wanting to announce the table ("application table") which was a little annoying but not a blocker. The mouseover issue seems to have been fixed!

alex-hull

Agreed with Amy C. I think it looks good!

thisisdano

Great documentation and thorough review. 🎉

mahoneycm added 4 commits February 15, 2024 14:15

Remove mouseover behaviors from date-picker

611bfe1

Remove date-range mouseover unit tests

fb4cf32

Merge branch 'develop' of github.com:uswds/uswds into cm-date-range-r…

ba11fcf

…emove-mouseover

Remove unused definition and iOS check

9a998ec

mahoneycm mentioned this pull request Feb 20, 2024

USWDS - Date picker: Prevent focus on mouseover #5778

Closed

4 tasks

This comment was marked as outdated.

Sign in to view

mahoneycm closed this Feb 20, 2024

mahoneycm reopened this Jun 28, 2024

mahoneycm added 9 commits July 16, 2024 15:58

Create separate mouseover behaviors to handle date range preview

75f6025

Move reused date range calculation to function

9b9959e

Merge branch 'develop' of github.com:uswds/uswds into cm-date-range-r…

fd6f309

…emove-mouseover

Remove mouseover focus tests

bca8a3e

Add JSDoc comments to new functions

31b4bef

Restore mouseover event for unit tests

4a161fe

Replace for..of loop with ForEach; Run prettier

0a9f88d

Rename date button variable

6e811c4

Move handleMouseoverFromDate function to it's original location

0bf9627

mahoneycm marked this pull request as ready for review July 22, 2024 17:47

mahoneycm changed the title ~~Cm date range remove mouseover~~ USWDS - Date picker: Prevent focus on mouseover Jul 22, 2024

mahoneycm added 3 commits July 22, 2024 13:58

Add param types to setRangeDates()

f92144d

Remove console.log

9a1dc10

Improve JSDoc comments for setRangeDates()

0441381

mahoneycm commented Jul 22, 2024

View reviewed changes

mahoneycm requested review from amyleadem and mejiaj July 22, 2024 20:33

mejiaj reviewed Jul 23, 2024

View reviewed changes

Reword comment for clarity

fc08a0d

Co-authored-by: James Mejia <james.mejia@gsa.gov>

mahoneycm requested a review from mejiaj July 23, 2024 21:38

mejiaj approved these changes Jul 24, 2024

View reviewed changes

amyleadem approved these changes Sep 4, 2024

View reviewed changes

amyleadem requested review from amycole501 and alex-hull September 4, 2024 22:07

amycole501 approved these changes Sep 5, 2024

View reviewed changes

alex-hull approved these changes Sep 5, 2024

View reviewed changes

mahoneycm requested a review from thisisdano September 5, 2024 14:44

mahoneycm mentioned this pull request Sep 5, 2024

USWDS-Site - Changelog: Datepicker mouseover behaviors [#5774] uswds/uswds-site#2496

Merged

mahoneycm mentioned this pull request Sep 18, 2024

USWDS-Site: Documentation updates for 3.9.0 uswds/uswds-site#2812

Merged

3 tasks

thisisdano approved these changes Oct 3, 2024

View reviewed changes

thisisdano merged commit 2e398d2 into develop Oct 3, 2024
5 checks passed

thisisdano deleted the cm-date-range-remove-mouseover branch October 3, 2024 03:22

thisisdano mentioned this pull request Oct 4, 2024

USWDS 3.9.0 #6096

Merged

mahoneycm mentioned this pull request Oct 24, 2024

USWDS - Time picker: Add clarity to hint text #6147

Merged

USWDS - Date picker: Prevent focus on mouseover #5774

USWDS - Date picker: Prevent focus on mouseover #5774

Uh oh!

Conversation

mahoneycm commented Feb 15, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Breaking change

Related issue

Related pull requests

Preview link

Problem statement

Solution

Accessibility improvements

Alternatives considered

Additional concerns

Major changes

Testing and review

Testing checklist

Footnotes

Uh oh!

This comment was marked as outdated.

mahoneycm commented Jul 22, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mejiaj left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mahoneycm commented Jul 23, 2024

Uh oh!

mejiaj left a comment

Choose a reason for hiding this comment

Uh oh!

amyleadem left a comment

Choose a reason for hiding this comment

Uh oh!

amycole501 left a comment

Choose a reason for hiding this comment

Uh oh!

alex-hull left a comment

Choose a reason for hiding this comment

Uh oh!

thisisdano left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mahoneycm commented Feb 15, 2024 •

edited

Loading

mahoneycm commented Jul 22, 2024 •

edited

Loading