[DatePicker][A11y] Fix TAB keyboard trap and add DPAD month navigation.

This change fixes a keyboard trap in MaterialDatePicker where the TAB key focus was stuck within the month grid. TAB navigation is now limited to the days within the current month, allowing focus to move out of the picker.

For navigating between months, this change introduces DPAD (left/right arrow key) navigation. When on the first or last valid day of the month, the arrow keys will navigate to the previous or next month.

This CL also prevents keyboard focus from landing on disabled dates. Since GridView does not natively support skipping disabled items, custom logic has been added to find and focus on the nearest valid day during keyboard navigation.

Finally, a bug that caused focus to incorrectly jump to a previous, non-visible month during TAB navigation has been fixed. This was caused by RecyclerView's view-recycling mechanism. The solution ensures that only the currently visible month is focusable, preventing focus from moving to off-screen months.

PiperOrigin-RevId: 834271529

Author: Material Design Team

lib/java/com/google/android/material/datepicker/MaterialCalendar.java

@@ -96,6 +96,7 @@ enum CalendarSelector {
   private View dayFrame;
   private MaterialButton monthDropSelect;
   private AccessibilityManager accessibilityManager;
+  @Nullable private PagerSnapHelper pagerSnapHelper;
 
   @NonNull
   public static <T> MaterialCalendar<T> newInstance(
@@ -228,6 +229,17 @@ public void onDayClick(long day) {
                   }
                 }
               }
+            },
+            new OnMonthNavigationListener() {
+              @Override
+              public boolean onMonthNavigationPrevious() {
+                return handleNavigateToMonthForKeyboard(/* forward= */ false, themedContext);
+              }
+
+              @Override
+              public boolean onMonthNavigationNext() {
+                return handleNavigateToMonthForKeyboard(/* forward= */ true, themedContext);
+              }
             });
     recyclerView.setAdapter(monthsPagerAdapter);
 
@@ -242,13 +254,13 @@ public void onDayClick(long day) {
       yearSelector.addItemDecoration(createItemDecoration());
     }
 
+    if (!MaterialDatePicker.isFullscreen(themedContext)) {
+      pagerSnapHelper = new PagerSnapHelper();
+      pagerSnapHelper.attachToRecyclerView(recyclerView);
+    }
     if (root.findViewById(R.id.month_navigation_fragment_toggle) != null) {
       addActionsToMonthNavigation(root, monthsPagerAdapter);
     }
-
-    if (!MaterialDatePicker.isFullscreen(themedContext)) {
-      new PagerSnapHelper().attachToRecyclerView(recyclerView);
-    }
     recyclerView.scrollToPosition(monthsPagerAdapter.getPosition(current));
     setUpForAccessibility();
     updateAccessibilityPaneTitle(root);
@@ -334,6 +346,44 @@ CalendarConstraints getCalendarConstraints() {
     return calendarConstraints;
   }
 
+  /**
+   * Handles navigating to the adjacent month in response to keyboard navigation.
+   *
+   * <p>This method pages horizontally to switch months in non-fullscreen mode. In fullscreen mode,
+   * this method returns {@code false} because months are scrolled vertically.
+   *
+   * @param forward {@code true} to navigate to the next month, {@code false} to navigate to the
+   *     previous month.
+   * @param context The context.
+   * @return {@code true} if the event was handled.
+   */
+  private boolean handleNavigateToMonthForKeyboard(boolean forward, @NonNull Context context) {
+    if (MaterialDatePicker.isFullscreen(context)) {
+      return false;
+    }
+
+    // Do not navigate if scroll is in progress. Return true to indicate the event was handled,
+    // but in practice navigation is ignored during scroll.
+    if (recyclerView.getScrollState() != RecyclerView.SCROLL_STATE_IDLE) {
+      return true;
+    }
+
+    MonthsPagerAdapter adapter = (MonthsPagerAdapter) recyclerView.getAdapter();
+    if (adapter == null || current == null) {
+      return false;
+    }
+
+    int currentItem = adapter.getPosition(current);
+    int newItem = currentItem + (forward ? 1 : -1);
+
+    if (newItem >= 0 && newItem < adapter.getItemCount()) {
+      adapter.setKeyboardFocusDirection(forward ? View.FOCUS_FORWARD : View.FOCUS_BACKWARD);
+      setCurrentMonth(adapter.getPageMonth(newItem));
+      return true;
+    }
+    return false;
+  }
+
   /**
    * Changes the currently displayed month to {@code moveTo}.
    *
@@ -361,9 +411,22 @@ void setCurrentMonth(Month moveTo) {
         postSmoothRecyclerViewScroll(moveToPosition);
       }
     }
+    updateCurrentVisibleMonth();
     updateNavigationButtonsEnabled(moveToPosition);
   }
 
+  private void updateCurrentVisibleMonth() {
+    Context context = getContext();
+    if (context == null || MaterialDatePicker.isFullscreen(context)) {
+      return;
+    }
+
+    MonthsPagerAdapter adapter = (MonthsPagerAdapter) recyclerView.getAdapter();
+    if (adapter != null) {
+      adapter.setVisibleMonth(current);
+    }
+  }
+
   @Nullable
   @Override
   public DateSelector<S> getDateSelector() {
@@ -379,6 +442,20 @@ interface OnDayClickListener {
     void onDayClick(long day);
   }
 
+  /**
+   * Listener for month navigation events.
+   *
+   * <p>This listener is used by {@link MaterialCalendarGridView} to signal when keyboard navigation
+   * reaches the start or end of a month, allowing the calendar to scroll to the previous or next
+   * month.
+   */
+  interface OnMonthNavigationListener {
+
+    boolean onMonthNavigationPrevious();
+
+    boolean onMonthNavigationNext();
+  }
+
   /** Returns the pixel height of each {@link android.view.View} representing a day. */
   @Px
   static int getDayHeight(@NonNull Context context) {
@@ -472,18 +549,34 @@ public void onInitializeAccessibilityNodeInfo(
         new OnScrollListener() {
           @Override
           public void onScrolled(@NonNull RecyclerView recyclerView, int dx, int dy) {
-            int currentItem;
-            if (dx < 0) {
-              currentItem = getLayoutManager().findFirstVisibleItemPosition();
-            } else {
-              currentItem = getLayoutManager().findLastVisibleItemPosition();
+            int position =
+                dx < 0
+                    ? getLayoutManager().findFirstVisibleItemPosition()
+                    : getLayoutManager().findLastVisibleItemPosition();
+            if (pagerSnapHelper == null) {
+              current = monthsPagerAdapter.getPageMonth(position);
+            }
+            monthDropSelect.setText(monthsPagerAdapter.getPageTitle(position));
+            updateNavigationButtonsEnabled(position);
+          }
+
+          @Override
+          public void onScrollStateChanged(@NonNull RecyclerView recyclerView, int newState) {
+            if (newState != RecyclerView.SCROLL_STATE_IDLE || pagerSnapHelper == null) {
+              return;
             }
-            Month moveToMonth = monthsPagerAdapter.getPageMonth(currentItem);
-            current = moveToMonth;
-            monthDropSelect.setText(monthsPagerAdapter.getPageTitle(currentItem));
 
-            int currentMonthPosition = monthsPagerAdapter.getPosition(moveToMonth);
-            updateNavigationButtonsEnabled(currentMonthPosition);
+            // If horizontal mode, find the snapped view and set it as the current month.
+            View snapView = pagerSnapHelper.findSnapView(getLayoutManager());
+            if (snapView != null) {
+              int snapPosition = recyclerView.getChildAdapterPosition(snapView);
+              if (snapPosition != RecyclerView.NO_POSITION) {
+                current = monthsPagerAdapter.getPageMonth(snapPosition);
+                monthDropSelect.setText(monthsPagerAdapter.getPageTitle(snapPosition));
+                updateNavigationButtonsEnabled(snapPosition);
+              }
+            }
+            updateCurrentVisibleMonth();
           }
         });
 
@@ -500,6 +593,7 @@ public void onClick(View view) {
           @Override
           public void onClick(View view) {
             int currentItem = getLayoutManager().findFirstVisibleItemPosition();
+            monthsPagerAdapter.setKeyboardFocusDirection(View.FOCUS_FORWARD);
             setCurrentMonth(monthsPagerAdapter.getPageMonth(currentItem + 1));
           }
         });
@@ -508,6 +602,7 @@ public void onClick(View view) {
           @Override
           public void onClick(View view) {
             int currentItem = getLayoutManager().findLastVisibleItemPosition();
+            monthsPagerAdapter.setKeyboardFocusDirection(View.FOCUS_BACKWARD);
             setCurrentMonth(monthsPagerAdapter.getPageMonth(currentItem - 1));
           }
         });
@@ -517,8 +612,12 @@ public void onClick(View view) {
   }
 
   private void updateNavigationButtonsEnabled(int currentMonthPosition) {
-    monthNext.setEnabled(currentMonthPosition + 1 < recyclerView.getAdapter().getItemCount());
-    monthPrev.setEnabled(currentMonthPosition - 1 >= 0);
+    if (monthNext != null) {
+      monthNext.setEnabled(currentMonthPosition + 1 < recyclerView.getAdapter().getItemCount());
+    }
+    if (monthPrev != null) {
+      monthPrev.setEnabled(currentMonthPosition - 1 >= 0);
+    }
   }
 
   private void postSmoothRecyclerViewScroll(final int position) {