feat(react/Calendar): add tabbing focus support to the Calendar com…

…ponent

packages/react/src/date-pickers/Calendar/Calendar.js

@@ -1,14 +1,24 @@
 import { useConst, usePrevious } from '@tonic-ui/react-hooks';
-import { isNullOrUndefined } from '@tonic-ui/utils';
+import {
+  callEventHandlers,
+  getActiveElement,
+  getAllFocusable,
+  isNullOrUndefined,
+} from '@tonic-ui/utils';
+import differenceInCalendarDays from 'date-fns/differenceInCalendarDays';
+import addMonths from 'date-fns/addMonths';
 import endOfDay from 'date-fns/endOfDay';
 import format from 'date-fns/format';
 import isDate from 'date-fns/isDate';
 import isSameMonth from 'date-fns/isSameMonth';
 import isSameYear from 'date-fns/isSameYear';
 import isValid from 'date-fns/isValid';
 import startOfDay from 'date-fns/startOfDay';
+import startOfMonth from 'date-fns/startOfMonth';
+import startOfWeek from 'date-fns/startOfWeek';
+import subMonths from 'date-fns/subMonths';
 import memoize from 'micro-memoize';
-import React, { forwardRef, useCallback, useEffect, useState } from 'react';
+import React, { forwardRef, useCallback, useEffect, useRef, useState } from 'react';
 import { Box } from '../../box';
 import { validateDate } from '../validation';
 import { CalendarProvider } from './context';
@@ -46,6 +56,7 @@ const Calendar = forwardRef((
     maxDate: maxDateProp,
     minDate: minDateProp,
     onChange: onChangeProp,
+    onKeyDown: onKeyDownProp,
     onError: onErrorProp,
     shouldDisableDate,
     ...rest
@@ -61,6 +72,9 @@ const Calendar = forwardRef((
     // Return initial date if it is valid, otherwise return today
     return isValid(initialDate) ? initialDate : today;
   });
+  const navigationRef = useRef();
+  const monthViewRef = useRef();
+  const nextFocusIndexRef = useRef();
   const [activeDate, setActiveDate] = useState(initialActiveDate);
   const [date, setDate] = useState(initialDate);
   const previousDate = usePrevious(date);
@@ -77,6 +91,256 @@ const Calendar = forwardRef((
   const minDate = mapValueToStartOfDay(minDateProp);
   const validationError = validateDate(date, { maxDate, minDate, shouldDisableDate });
   const previousValidationError = usePrevious(validationError);
+  const getFocusableNavigationElements = useCallback(() => {
+    if (!navigationRef.current) {
+      return [];
+    }
+    const focusableElements = getAllFocusable(navigationRef.current);
+    return focusableElements;
+  }, []);
+  const getFocusableMonthViewElements = useCallback(() => {
+    if (!monthViewRef.current) {
+      return [];
+    }
+    const focusableElements = getAllFocusable(monthViewRef.current);
+    return focusableElements;
+  }, []);
+  const eventHandler = {};
+
+  // Navigate the menu items using keyboard.
+  eventHandler.onKeyDown = (event) => {
+    const key = event?.key;
+    const shiftKey = event?.shiftKey;
+    const focusableMonthViewElements = getFocusableMonthViewElements();
+    const activeElement = getActiveElement(event.target);
+
+    const focusOnDay = (offset) => {
+      const focusIndex = focusableMonthViewElements.indexOf(activeElement);
+      if (focusIndex < 0) {
+        return;
+      }
+
+      const nextFocusIndex = focusIndex + offset;
+      if (nextFocusIndex < 0 || nextFocusIndex >= focusableMonthViewElements.length) {
+        const nextActiveDate = offset < 0 ? subMonths(activeDate, 1) : addMonths(activeDate, 1);
+        setActiveDate(nextActiveDate);
+
+        if (nextFocusIndex < 0) {
+          // Example #1: No days from the previous month in the first row (focusIndex=0, offset=-7, nextFocusIndex=-7)
+          //
+          // With the current focus on day 1 in the first row and `nextFocusIndex` set to -7:
+          //
+          // ```
+          //  Su  Mo  Tu  We  Th  Fr  Sa
+          // [ 1]  2   3   4   5   6   7
+          //   8   9  10  11  12  13  14
+          //  15  16  17  18  19  20  21
+          //  22  23  24  25  26  27  28
+          //  29  30  31   1   2   3   4
+          // ```
+          //
+          // The focus will be shifted to the appropriate position in the previous month, based on the offset:
+          //
+          // ```
+          //  Su  Mo  Tu  We  Th  Fr  Sa
+          //   1   2   3   4   5   6   7
+          //   8   9  10  11  12  13  14
+          //  15  16  17  18  19  20  21
+          //  22  23  24  25  26  27  28
+          // [24] 25  26  27  28  29  30
+          // ```
+          //
+          // Example #2: Contains days from the previous month in the first row (focusIndex=4, offset=-7, nextFocusIndex=-3)
+          //
+          // With the current focus on day 1 in the first row and `nextFocusIndex` set to -3:
+          //
+          // ```
+          //  Su  Mo  Tu  We  Th  Fr  Sa
+          //  27  28  29  30 [ 1]  2   3
+          //   4   5   6   7   8   9  10
+          //  11  12  13  14  15  16  17
+          //  18  19  20  21  22  23  24
+          //  25  26  27  28  29  30  31
+          // ```
+          //
+          // Days 27, 28, 29, and 30 in the first row are part of the previous month and are not focusable (tabIndex of -1).
+          // To correctly adjust the focus, subtract 7 to align with the corresponding day in the preceding week:
+          //
+          // ```
+          //  Su  Mo  Tu  We  Th  Fr  Sa
+          //  30  31   1   2   3   4   5
+          //   6   7   8   9  10  11  12
+          //  13  14  15  16  17  18  19
+          //  20  21  22  23 [24] 25  26
+          //  27  28  29  30   1   2   3
+          // ```
+
+          nextFocusIndexRef.current = nextFocusIndex;
+
+          // Verify whether the first row includes days from the previous month
+          const firstFocusableElementInMonthView = focusableMonthViewElements[0];
+          if (firstFocusableElementInMonthView?.tabIndex < 0) {
+            nextFocusIndexRef.current -= 7;
+          }
+        } else if (nextFocusIndex >= focusableMonthViewElements.length) {
+          // Example #1: No days from the next month in the last row (focusIndex=34, offset=7, nextFocusIndex=41)
+          //
+          // With the current focus on day 31 in the last row and `nextFocusIndex` set to 41:
+          //
+          // ```
+          //  Su  Mo  Tu  We  Th  Fr  Sa
+          //  27  28  29  30   1   2   3
+          //   4   5   6   7   8   9  10
+          //  11  12  13  14  15  16  17
+          //  18  19  20  21  22  23  24
+          //  25  26  27  28  29  30 [31]
+          // ```
+          //
+          // The focus will be shifted to the appropriate position in the next month, based on the offset:
+          //
+          // ```
+          //  Su  Mo  Tu  We  Th  Fr  Sa
+          //   1   2   3   4   5   6 [ 7]
+          //   8   9  10  11  12  13  14
+          //  15  16  17  18  19  20  21
+          //  22  23  24  25  26  27  28
+          //  29  30   1   2   3   4   5
+          // ```
+          //
+          // Example #2: Contains days from the next month in the last row (focusIndex=30, offset=7, nextFocusIndex=37)
+          //
+          // With the current focus on day 31 in the last row and `nextFocusIndex` set to 37:
+          //
+          // ```
+          //  Su  Mo  Tu  We  Th  Fr  Sa
+          //   1   2   3   4   5   6   7
+          //   8   9  10  11  12  13  14
+          //  15  16  17  18  19  20  21
+          //  22  23  24  25  26  27  28
+          //  29  30 [31]  1   2   3   4
+          // ```
+          //
+          // Days 1, 2, 3, and 4 in the last row are part of the next month and are not focusable (tabIndex of -1).
+          // To correctly adjust the focus, add 7 to align with the corresponding day in the following week:
+          //
+          // ```
+          //  Su  Mo  Tu  We  Th  Fr  Sa
+          //  29  30  31   1   2   3   4
+          //   5   6 [ 7]  8   9  10  11
+          //  12  13  14  15  16  17  18
+          //  19  20  21  22  23  24  25
+          //  26  27  28  29  30   1   2
+          // ```
+
+          nextFocusIndexRef.current = nextFocusIndex - focusableMonthViewElements.length;
+
+          // Verify whether the last row includes days from the next month
+          const lastFocusableElementInMonthView = focusableMonthViewElements[focusableMonthViewElements.length - 1];
+          if (lastFocusableElementInMonthView?.tabIndex < 0) {
+            nextFocusIndexRef.current += 7;
+          }
+        }
+        return;
+      }
+
+      const nextFocusableElement = focusableMonthViewElements[nextFocusIndex];
+      if (!nextFocusableElement) {
+        return;
+      }
+
+      if (nextFocusableElement?.tabIndex < 0) {
+        const nextActiveDate = offset < 0 ? subMonths(activeDate, 1) : addMonths(activeDate, 1);
+        setActiveDate(nextActiveDate);
+        nextFocusIndexRef.current = offset < 0
+          ? nextFocusIndex - 7
+          : (nextFocusIndex + 7) - focusableMonthViewElements.length;
+        return;
+      }
+
+      nextFocusableElement?.focus();
+    };
+
+    const focusOnPreviousDay = () => focusOnDay(-1);
+    const focusOnNextDay = () => focusOnDay(1);
+    const focusOnPreviousWeek = () => focusOnDay(-7);
+    const focusOnNextWeek = () => focusOnDay(7);
+    const focusOnFirstDay = () => {
+      const firstFocusableNode = focusableMonthViewElements.find(node => node?.tabIndex >= 0);
+      if (firstFocusableNode) {
+        firstFocusableNode?.focus();
+      }
+    };
+    const focusOnLastDay = () => {
+      const lastFocusableNode = focusableMonthViewElements.reverse().find(node => node?.tabIndex >= 0);
+      if (lastFocusableNode) {
+        lastFocusableNode?.focus();
+      }
+    };
+
+    // Prevents default page scrolling for ArrowLeft, ArrowRight, ArrowDown, ArrowUp, Home, End, and Tab keys.
+    if (key === 'ArrowLeft') {
+      event.preventDefault();
+      focusOnPreviousDay();
+    }
+    if (key === 'ArrowRight') {
+      event.preventDefault();
+      focusOnNextDay();
+    }
+    if (key === 'ArrowUp') {
+      event.preventDefault();
+      focusOnPreviousWeek();
+    }
+    if (key === 'ArrowDown') {
+      event.preventDefault();
+      focusOnNextWeek();
+    }
+    if (key === 'Home') {
+      event.preventDefault();
+      focusOnFirstDay();
+    }
+    if (key === 'End') {
+      event.preventDefault();
+      focusOnLastDay();
+    }
+    if (key === 'Tab') {
+      const focusableNavigationElements = getFocusableNavigationElements();
+      const focusableMonthViewElements = getFocusableMonthViewElements();
+      const activeElement = getActiveElement(event.target);
+      const isLastNavigationElementFocused = !isNullOrUndefined(activeElement) &&
+        (activeElement === focusableNavigationElements[focusableNavigationElements.length - 1]);
+
+      // If the last focusable navigation element (e.g., "Next month" button) is focused and the TAB key is pressed
+      if (isLastNavigationElementFocused && !shiftKey) {
+        const today = new Date();
+        // Determine the date to focus on (either provided date or today's date)
+        const nextFocusDate = date ? startOfDay(date) : startOfDay(today);
+        // Get the start date of the month view based on the next focus date
+        const startDateOfMonthView = startOfWeek(startOfMonth(nextFocusDate), {
+          weekStartsOn: firstDayOfWeek,
+        });
+        const nextFocusIndex = differenceInCalendarDays(nextFocusDate, startDateOfMonthView);
+        nextFocusIndexRef.current = nextFocusIndex;
+        setActiveDate(nextFocusDate);
+        return;
+      }
+
+      // Handle TAB key navigation within the month view
+      if (focusableMonthViewElements.indexOf(activeElement) >= 0) {
+        if (shiftKey) { // TAB + SHIFT pressed
+          // Move focus to the first focusable element in the month view
+          // This allows the user to cycle focus back to the navigation if needed
+          const firstFocusableMonthViewElement = focusableMonthViewElements[0];
+          firstFocusableMonthViewElement.focus();
+        } else { // TAB pressed
+          // Move focus to the last focusable element in the month view
+          // This allows the user to move focus outside the calendar
+          const lastFocusableMonthViewElement = focusableMonthViewElements[focusableMonthViewElements.length - 1];
+          lastFocusableMonthViewElement.focus();
+        }
+        return;
+      }
+    }
+  };
 
   useEffect(() => {
     if (validationError !== previousValidationError) {
@@ -102,6 +366,26 @@ const Calendar = forwardRef((
     }
   }, [date, previousDate, activeDate]);
 
+  useEffect(() => {
+    if (isNullOrUndefined(nextFocusIndexRef.current)) {
+      return;
+    }
+
+    const nextFocusIndex = nextFocusIndexRef.current;
+    const focusableMonthViewElements = getFocusableMonthViewElements();
+    const el = nextFocusIndex < 0
+      ? focusableMonthViewElements[focusableMonthViewElements.length + nextFocusIndex]
+      : focusableMonthViewElements[nextFocusIndex];
+
+    // Reset the reference to avoid unintended focus changes in future renders
+    nextFocusIndexRef.current = null;
+
+    // Use requestAnimationFrame to ensure that the focus is set after the DOM has been updated
+    requestAnimationFrame(() => {
+      el && el?.focus();
+    });
+  }, [activeDate, getFocusableMonthViewElements]); // Re-run effect when activeDate changes
+
   const onChange = useCallback((nextDate) => {
     const isControlled = (dateProp !== undefined);
     if (!isControlled) {
@@ -122,17 +406,21 @@ const Calendar = forwardRef((
     setActiveDate,
     shouldDisableDate,
   });
-  const styleProps = useCalendarStyle();
+
+  const tabIndex = -1;
+  const styleProps = useCalendarStyle({ tabIndex });
 
   return (
     <CalendarProvider value={context}>
       <Box
         ref={ref}
+        onKeyDown={callEventHandlers(onKeyDownProp, eventHandler.onKeyDown)}
+        tabIndex={tabIndex}
         {...styleProps}
         {...rest}
       >
-        <Navigation />
-        <MonthView />
+        <Navigation ref={navigationRef} />
+        <MonthView ref={monthViewRef} />
       </Box>
     </CalendarProvider>
   );

packages/react/src/date-pickers/Calendar/MonthView/Day.js

@@ -1,5 +1,6 @@
 import { useEventCallback } from '@tonic-ui/react-hooks';
 import { dataAttr } from '@tonic-ui/utils';
+import formatISO from 'date-fns/formatISO';
 import isAfter from 'date-fns/isAfter';
 import isBefore from 'date-fns/isBefore';
 import isSameDay from 'date-fns/isSameDay';
@@ -41,6 +42,9 @@ const Day = forwardRef((
   })();
   const isSelected = isSameDay(date, new Date(selectedDate));
   const isToday = isSameDay(date, new Date());
+  // Manage focus on the active date within the month view by adjusting the `tabIndex`.
+  // If the date is within the same month as the `activeDate`, set `tabIndex` to 0 to make it focusable; otherwise, set it to -1.
+  const tabIndex = isSameMonth(date, activeDate) ? 0 : -1;
   const styleProps = useDayStyle({
     isSameMonth: isSameMonth(date, activeDate),
     isSelectable,
@@ -54,9 +58,11 @@ const Day = forwardRef((
   return (
     <Box
       ref={ref}
+      data-date={formatISO(date, { representation: 'date' })}
       // Only use `aria-selected` with these roles: `option`, `tab`, `menuitemradio`, `treeitem`, `gridcell`, `row`, `rowheader`, and `columnheader`.
       data-selected={dataAttr(isSelected)}
       onClick={isSelectable ? handleClick : undefined}
+      tabIndex={tabIndex}
       {...styleProps}
       {...rest}
     >