@12-apps/ui 6.80.0 → 6.82.0

package/src/components/form/Calendar/Calendar.hooks.ts

@@ -8,10 +8,12 @@ import type { MonthMatrix, ResolvedCalendarProps } from './Calendar.types';
 
 const startOfMonth = (date: Date): Date => new Date(date.getFullYear(), date.getMonth(), 1);
 
-// Which day the calendar opens on: whatever is already chosen, else today.
+// Which day the calendar opens on: whatever is already chosen, else the first
+// of `defaultMonth`, else today.
 const initialFocus = (props: ResolvedCalendarProps, today: Date): Date => {
   if (props.selectionMode === 'single' && props.value) return normalizeDate(props.value);
   if (props.selectionMode === 'range' && props.range.start) return normalizeDate(props.range.start);
+  if (props.defaultMonth) return normalizeDate(startOfMonth(props.defaultMonth));
   return today;
 };
 
@@ -44,22 +46,24 @@ const useVisibleMonths = ({
   currentMonth,
   monthsToShow,
   firstDayOfWeek,
+  fixedWeeks,
 }: {
   currentMonth: Date;
   monthsToShow: number;
   firstDayOfWeek: number;
+  fixedWeeks: boolean;
 }): MonthMatrix[] =>
   useMemo(() => {
     const matrices: MonthMatrix[] = [];
     let cursor = currentMonth;
 
     for (let i = 0; i < monthsToShow; i++) {
-      matrices.push(generateMonthMatrix(cursor.getMonth(), cursor.getFullYear(), firstDayOfWeek));
+      matrices.push(generateMonthMatrix(cursor.getMonth(), cursor.getFullYear(), firstDayOfWeek, fixedWeeks));
       cursor = addMonths(cursor, 1);
     }
 
     return matrices;
-  }, [currentMonth, monthsToShow, firstDayOfWeek]);
+  }, [currentMonth, monthsToShow, firstDayOfWeek, fixedWeeks]);
 
 // A click either sets a single date or advances the range by one step; the range
 // rules themselves live in nextRangeStep.
@@ -215,6 +219,9 @@ export const useCalendar = (props: ResolvedCalendarProps) => {
     currentMonth: state.currentMonth,
     monthsToShow,
     firstDayOfWeek,
+    // The selectors caption steps month by month under the thumb; six weeks
+    // every time keep it, and a sheet anchored below, where they are.
+    fixedWeeks: props.captionLayout === 'selectors',
   });
 
   const weekdayNames = useMemo(
@@ -264,6 +271,9 @@ export const useCalendar = (props: ResolvedCalendarProps) => {
     gridRef,
     today,
     focusedDate: state.focusedDate,
+    setFocusedDate: state.setFocusedDate,
+    currentMonth: state.currentMonth,
+    setCurrentMonth: state.setCurrentMonth,
     hoveredDate: state.hoveredDate,
     monthMatrices,
     weekdayNames,

package/src/components/form/Calendar/Calendar.md

@@ -50,6 +50,9 @@ export interface CalendarProps {
   locale?: string; // e.g. 'en-US'
   showOutsideDays?: boolean; // days from prev/next month
   showWeekNumbers?: boolean;
+  captionLayout?: 'arrows' | 'selectors'; // default: 'arrows'; 'selectors' shows one month
+  defaultMonth?: Date; // month shown while nothing is chosen; default: today's month
+  labels?: Partial<CalendarLabels>; // selectors caption's names; English pack fills the rest
 
   // Constraints
   minDate?: Date;
@@ -128,6 +131,74 @@ export interface CalendarProps {
 - Header buttons move month (or year with modifier keys if desired).
 - Month pagination respects `minDate`/`maxDate`.
 
+### Opening month: `defaultMonth`
+
+The calendar opens on the chosen `value` (single) or `range.start` (range);
+with neither, on `defaultMonth` when given, else on today's month. It is read
+once, on mount, like the value it stands in for. A birth-date picker passes a
+month decades back (the storefront's Perfil field passes January 2001) rather
+than opening on today. It is not clamped: a `defaultMonth` outside
+`minDate`/`maxDate` opens on that month with every day disabled, so pass one
+inside the bounds.
+
+### Month and year selectors: `captionLayout="selectors"` (FUT-4121)
+
+Opt-in; the default `'arrows'` caption is unchanged. For a date far from today
+— a birth date — where ~360 arrow taps would separate today from 30 years ago.
+
+- The caption holds a `<Month> ▾` button, a `<Year> ▾` button and the
+  previous/next month arrows. Always one month (`numberOfMonths` is ignored);
+  `renderHeader` applies to the `'arrows'` caption only.
+- **Year button** swaps the day grid for a year grid: 4 columns, newest year
+  first, from `maxDate`'s year down to `minDate`'s (1900–2099 without bounds;
+  the shown year is always listed, `aria-disabled` when outside the bounds). The shown year is highlighted
+  (`aria-current="true"`) and takes focus, which scrolls the list to it.
+  Picking a year returns to that year's days, in the same month, pulled inside
+  the bounds (December in a year capped at October shows October).
+- **Month button** swaps in a 3 × 4 month grid. Months with no day inside
+  `minDate`/`maxDate` are `aria-disabled` and ignore a tap. Picking returns to
+  the days.
+- Pressing the open grid's button again, or a month arrow, goes back to the
+  days. The arrows are disabled at the first and last month the bounds allow.
+- Days outside `minDate`/`maxDate` stay disabled as in any layout.
+- Nothing moves as the month changes: the month always shows six weeks (the
+  next month's days fill the rest), the month button keeps the width of the
+  longest month name, and an open month or year grid takes the days' place at
+  their size. Whether the arrows share the caption's row depends on the width
+  only (at 296 px they take a row of their own).
+- Example — 14/03/1990 from January 2001: `2001 ▾` → 1990 → `Janeiro ▾` →
+  mar → 14, five taps.
+
+```tsx
+import { Calendar } from '@12-apps/ui';
+import { UI_LABELS } from '@12-apps/ui/locales';
+
+<Calendar
+  ariaLabel="Data de nascimento"
+  locale="pt-BR"
+  captionLayout="selectors"
+  defaultMonth={new Date(2001, 0, 1)}
+  minDate={new Date(1900, 0, 1)}
+  maxDate={thirteenYearsAgo}
+  labels={UI_LABELS['pt-BR'].calendar}
+  value={birthDate}
+  onChange={setBirthDate}
+/>;
+```
+
+**Copy.** Month names and years come from `Intl` in `locale` (the long name,
+capitalised, on the button; the short one, without its dot, in the grid with
+the long one as its accessible name). The accessible names come from
+`labels` (`CalendarLabels` in `copy/labels.ts`): `chooseMonth(month)`,
+`chooseYear(year)`, `previousMonth`, `nextMonth`, and the two grids' names
+`months`/`years`. The English pack answers for any key left out; a pt-BR host
+passes `UI_LABELS['pt-BR'].calendar` ("Março, escolher mês", "Mês anterior",
+"Anos"…).
+
+**Size.** Every caption control and every month/year button is at least 44
+design px tall at any width. In a 320 sheet the two arrows wrap under the
+month/year buttons rather than squeezing them (`SelectorsFitA320Sheet`).
+
 ### States & Styles (suggested class hooks)
 
 - `.cal-root`, `.cal-header`, `.cal-nav`, `.cal-grid`, `.cal-weekdays`, `.cal-row`, `.cal-cell`
@@ -151,6 +222,24 @@ export interface CalendarProps {
 
 - Focus should remain inside the grid; header nav is reachable via Tab.
 
+**Selectors caption (`captionLayout="selectors"`).**
+
+- The month and year buttons are real buttons named by `labels`
+  (`chooseMonth`/`chooseYear`, which start with the visible text), with
+  `aria-expanded` and, while their grid is open, `aria-controls` pointing at
+  it. The arrows are named `previousMonth`/`nextMonth`.
+- Each grid is a `role="group"` named `months`/`years`, with ONE tab stop
+  (roving `tabIndex`). Opening it focuses the shown month/year. Arrows move by
+  one (left/right) or one row (up/down), Home/End to the ends, Enter/Space
+  pick, Escape returns to the days unchanged with focus on the button that
+  opened the grid (Escape on a caption button closes it too). Out-of-bounds months stay focusable and say
+  `aria-disabled`.
+- A pick shows that month's days and moves focus to the day grid's tab stop.
+- The caption and the grids keep their keys to themselves: Enter on a caption
+  button activates it rather than picking the focused day. The day keys
+  (arrows, Home/End, PageUp/PageDown, Shift+PageUp/PageDown) work in the day
+  view exactly as in the `'arrows'` layout.
+
 ---
 
 ## Keyboard Selection Logic (range)
@@ -197,6 +286,8 @@ export interface CalendarProps {
 - `Date/Calendar/WithFooterApplyClear`
 - `Date/Calendar/WeekNumbers`
 - `Date/Calendar/RTL`
+- `Form/Calendar/MonthYearSelectors` — `captionLayout="selectors"` with `defaultMonth` and bounds (FUT-4121)
+- `Form/Calendar/Tests/SelectorsPickABirthDate`, `SelectorsKeyboard`, `SelectorsFitA320Sheet` — the five-tap journey, the grids' keys and focus, and the 320 fit with 44px targets
 
 ---
 
@@ -282,6 +373,23 @@ const nextButton = await canvas.findByTestId('calendar-next-month');
 await userEvent.click(nextButton);
 ```
 
+#### `calendar-month-select` / `calendar-year-select`
+
+- **Element:** the selectors caption's month and year buttons
+- **Only with:** `captionLayout="selectors"` (absent otherwise)
+- **Attributes:** `aria-expanded`, `aria-controls` while open
+- **Test Tip:** `expect(canvas.getByTestId('calendar-year-select')).toHaveTextContent('2001')`
+
+#### `calendar-months` / `calendar-months-${index}`
+
+- **Element:** the month grid (`role="group"`) and each month button, by 0-based month
+- **Only with:** `captionLayout="selectors"`, while the month grid is open
+
+#### `calendar-years` / `calendar-years-${year}`
+
+- **Element:** the year grid (`role="group"`) and each year button, by full year
+- **Only with:** `captionLayout="selectors"`, while the year grid is open
+
 ### Calendar Grid Elements
 
 #### `calendar-grid`
@@ -516,6 +624,14 @@ expect(style.cursor).toBe('not-allowed');
 - **Impact:** Custom disabled dates have `aria-disabled="true"`
 - **Test Tip:** Verify callback determines which dates are disabled
 
+#### `captionLayout`
+- **Values:** `'arrows'` (default) | `'selectors'`
+- **Impact:** `'selectors'` adds `calendar-month-select`/`calendar-year-select`, names the arrows, shows one month, and hides `calendar-grid` while a month or year grid is open
+
+#### `defaultMonth`
+- **Values:** `Date`
+- **Impact:** the month on screen at mount when there is no `value`/`range.start` — pin it in a test instead of depending on today
+
 #### `autoFocus`
 - **Values:** `boolean`
 - **Impact:** Calendar grid receives focus on mount
@@ -812,3 +928,8 @@ try {
   - Added `calendar-date-${date}`
   - Added `calendar-selected-date`
   - Added `calendar-today`
+
+- **2026-10-27 (FUT-4121):** month/year selectors and the opening month
+  - Added `captionLayout`, `defaultMonth`, `labels` (`CalendarLabels`)
+  - Added `calendar-month-select`, `calendar-year-select`
+  - Added `calendar-months`, `calendar-months-${index}`, `calendar-years`, `calendar-years-${year}`

package/src/components/form/Calendar/Calendar.picker.ts

@@ -0,0 +1,89 @@
+import type React from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import type { CalendarView, DateBounds } from './Calendar.views';
+import { clampMonthToBounds, landingDay } from './Calendar.views';
+
+/** The day a keyboard user lands on after a pick: the grid's one tab stop. */
+const FOCUSED_DAY = '[role="gridcell"][tabindex="0"]';
+
+/** The selector a dismissed grid hands focus back to. */
+const TOGGLE_OF: Record<Exclude<CalendarView, 'days'>, string> = {
+  months: '[data-testid="calendar-month-select"]',
+  years: '[data-testid="calendar-year-select"]',
+};
+
+interface CalendarPickerArgs {
+  rootRef: React.RefObject<HTMLElement | null>;
+  bounds: DateBounds;
+  currentMonth: Date;
+  focusedDate: Date;
+  setCurrentMonth: (month: Date) => void;
+  setFocusedDate: (date: Date) => void;
+}
+
+export interface CalendarPicker {
+  view: CalendarView;
+  /** Opens a pick grid, or goes back to the days when it is already open. */
+  toggle: (view: Exclude<CalendarView, 'days'>) => void;
+  pickYear: (year: number) => void;
+  pickMonth: (month: number) => void;
+  /** Back to the days with nothing changed (Escape), focus on the grid's own button. */
+  dismiss: () => void;
+  /** Back to the days, focus left where it is (a month arrow was used). */
+  showDays: () => void;
+}
+
+/**
+ * The month/year views of `captionLayout="selectors"`. A pick shows that month
+ * and puts focus on its day grid, so the keyboard carries on where the eye
+ * already is; a dismiss returns focus to the button that opened the grid.
+ */
+export const useCalendarPicker = ({
+  rootRef,
+  bounds,
+  currentMonth,
+  focusedDate,
+  setCurrentMonth,
+  setFocusedDate,
+}: CalendarPickerArgs): CalendarPicker => {
+  const [view, setView] = useState<CalendarView>('days');
+  // Focus can only move once the next view is on screen, so a change of view
+  // leaves a note for the effect below.
+  const pendingFocus = useRef<string | null>(null);
+
+  useEffect(() => {
+    const selector = pendingFocus.current;
+    if (!selector) return;
+    pendingFocus.current = null;
+    const root = rootRef.current;
+    // A custom `renderDay` has no gridcell button: the container takes focus,
+    // and the arrow keys still move the day from there.
+    (root?.querySelector<HTMLElement>(selector) ?? root)?.focus();
+  }, [view, rootRef]);
+
+  const toggle = useCallback(
+    (target: Exclude<CalendarView, 'days'>) => setView((current) => (current === target ? 'days' : target)),
+    [],
+  );
+
+  const land = (year: number, month: number) => {
+    setCurrentMonth(new Date(year, month, 1));
+    setFocusedDate(landingDay(year, month, focusedDate.getDate(), bounds));
+    pendingFocus.current = FOCUSED_DAY;
+    setView('days');
+  };
+
+  const pickYear = (year: number) => land(year, clampMonthToBounds(year, currentMonth.getMonth(), bounds));
+  const pickMonth = (month: number) => land(currentMonth.getFullYear(), month);
+
+  const dismiss = () => {
+    if (view === 'days') return;
+    pendingFocus.current = TOGGLE_OF[view];
+    setView('days');
+  };
+
+  const showDays = useCallback(() => setView('days'), []);
+
+  return { view, toggle, pickYear, pickMonth, dismiss, showDays };
+};

package/src/components/form/Calendar/Calendar.tsx

@@ -1,15 +1,19 @@
 import type { SxProps, Theme } from '@mui/material/styles/index.js';
 import Box from '@mui/material/Box/index.js';
 import Paper from '@mui/material/Paper/index.js';
-import React from 'react';
+import React, { useCallback, useRef } from 'react';
 
+import { EN_US_UI_LABELS } from '../../../en-US.labels';
 import { rem, sxRem } from '../../../tokens/relative';
+import { resolveLabels } from '../../../utils/resolve-labels';
 
 import { resolveCalendarProps } from './Calendar.helpers';
 import { useCalendar } from './Calendar.hooks';
-import type { CalendarProps } from './Calendar.types';
+import { useCalendarPicker } from './Calendar.picker';
+import type { CalendarProps, ResolvedCalendarProps } from './Calendar.types';
 import type { DayCellContext } from './CalendarDayCell';
 import { CalendarMonth } from './CalendarMonth';
+import { CalendarSelectorsMonth } from './CalendarSelectorsMonth';
 
 const containerSx = (monthsToShow: number): SxProps<Theme> => ({
   p: 3,
@@ -24,54 +28,98 @@ const containerSx = (monthsToShow: number): SxProps<Theme> => ({
   },
 });
 
+type CalendarState = ReturnType<typeof useCalendar>;
+
+const buildDayContext = (props: ResolvedCalendarProps, calendar: CalendarState): DayCellContext => ({
+  selectionMode: props.selectionMode,
+  value: props.value,
+  range: props.range,
+  showOutsideDays: props.showOutsideDays,
+  renderDay: props.renderDay,
+  dayClassName: props.dayClassName,
+  hoveredDate: calendar.hoveredDate,
+  focusedDate: calendar.focusedDate,
+  today: calendar.today,
+  isDisabled: calendar.isDisabled,
+  onSelect: calendar.handleDateClick,
+  onHover: calendar.handleDateMouseEnter,
+  onHoverEnd: calendar.handleDateMouseLeave,
+});
+
+// The container is the forwarded ref's AND the picker's: focus falls back to it.
+const useRootRef = (forwarded: React.ForwardedRef<HTMLDivElement>) => {
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  const setRoot = useCallback(
+    (node: HTMLDivElement | null) => {
+      rootRef.current = node;
+      if (typeof forwarded === 'function') forwarded(node);
+      else if (forwarded) forwarded.current = node;
+    },
+    [forwarded],
+  );
+  return { rootRef, setRoot };
+};
+
 export const Calendar = React.forwardRef<HTMLDivElement, CalendarProps>((componentProps, ref) => {
   const props = resolveCalendarProps(componentProps);
   const { monthsToShow, locale, renderHeader, renderFooter, className, ariaLabel } = props;
 
   const calendar = useCalendar(props);
-
-  const dayContext: DayCellContext = {
-    selectionMode: props.selectionMode,
-    value: props.value,
-    range: props.range,
-    showOutsideDays: props.showOutsideDays,
-    renderDay: props.renderDay,
-    dayClassName: props.dayClassName,
-    hoveredDate: calendar.hoveredDate,
-    focusedDate: calendar.focusedDate,
-    today: calendar.today,
-    isDisabled: calendar.isDisabled,
-    onSelect: calendar.handleDateClick,
-    onHover: calendar.handleDateMouseEnter,
-    onHoverEnd: calendar.handleDateMouseLeave,
-  };
+  const { rootRef, setRoot } = useRootRef(ref);
+  const bounds = { minDate: props.minDate, maxDate: props.maxDate };
+  const picker = useCalendarPicker({ rootRef, bounds, ...calendar });
+  const dayContext = buildDayContext(props, calendar);
+  // The selectors caption always resolves to one month (see the helpers).
+  const firstMonth = calendar.monthMatrices[0];
 
   return (
     <Paper
-      ref={ref}
+      ref={setRoot}
       className={className}
       role="application"
       aria-label={ariaLabel}
       tabIndex={0}
-      onKeyDown={calendar.handleKeyDown}
+      // The day keys belong to the days: with a month or year grid open there
+      // is no focused day on screen to move.
+      onKeyDown={picker.view === 'days' ? calendar.handleKeyDown : undefined}
       data-testid="calendar-container"
       sx={containerSx(monthsToShow)}
     >
       <Box ref={calendar.gridRef} sx={{ display: 'flex', gap: 3, flexWrap: 'wrap' }}>
-        {calendar.monthMatrices.map((matrix, index) => (
-          <CalendarMonth
-            key={`month-${matrix.year}-${matrix.month}`}
-            matrix={matrix}
-            monthIndex={index}
-            monthsToShow={monthsToShow}
+        {props.captionLayout === 'selectors' && firstMonth ? (
+          <CalendarSelectorsMonth
+            matrix={firstMonth}
             locale={locale}
             weekdayNames={calendar.weekdayNames}
-            renderHeader={renderHeader}
-            onPreviousMonth={calendar.goToPreviousMonth}
-            onNextMonth={calendar.goToNextMonth}
             dayContext={dayContext}
+            bounds={bounds}
+            labels={resolveLabels(EN_US_UI_LABELS.calendar, props.labels)}
+            picker={picker}
+            onPreviousMonth={() => {
+              picker.showDays();
+              calendar.goToPreviousMonth();
+            }}
+            onNextMonth={() => {
+              picker.showDays();
+              calendar.goToNextMonth();
+            }}
           />
-        ))}
+        ) : (
+          calendar.monthMatrices.map((matrix, index) => (
+            <CalendarMonth
+              key={`month-${matrix.year}-${matrix.month}`}
+              matrix={matrix}
+              monthIndex={index}
+              monthsToShow={monthsToShow}
+              locale={locale}
+              weekdayNames={calendar.weekdayNames}
+              renderHeader={renderHeader}
+              onPreviousMonth={calendar.goToPreviousMonth}
+              onNextMonth={calendar.goToNextMonth}
+              dayContext={dayContext}
+            />
+          ))
+        )}
       </Box>
 
       {renderFooter && (

package/src/components/form/Calendar/Calendar.types.ts

@@ -1,3 +1,5 @@
+import type { CalendarLabels } from '../../../copy/labels';
+
 export type SelectionMode = 'single' | 'range';
 
 export interface DateRange {
@@ -17,6 +19,14 @@ export interface DayRenderArgs {
   hovered?: boolean;
 }
 
+/**
+ * What the caption above the days holds. `'arrows'` (the default) is the month
+ * title between previous/next arrows. `'selectors'` replaces the title with a
+ * month button and a year button that swap the day grid for a month grid or a
+ * year grid — for dates far from today, such as a birth date.
+ */
+export type CalendarCaptionLayout = 'arrows' | 'selectors';
+
 export interface HeaderRenderContext {
   month: number;
   year: number;
@@ -46,6 +56,19 @@ export interface CalendarProps {
   locale?: string; // e.g. 'en-US'
   showOutsideDays?: boolean; // days from prev/next month
   showWeekNumbers?: boolean;
+  /** default: 'arrows'. `'selectors'` always shows one month. */
+  captionLayout?: CalendarCaptionLayout;
+  /**
+   * The month the calendar opens on when nothing is chosen yet (no `value`, no
+   * `range.start`). Default: today's month. Read once, on mount.
+   */
+  defaultMonth?: Date;
+  /**
+   * The selectors caption's accessible names (`captionLayout="selectors"`);
+   * the English pack answers for any key left out. A pt-BR host passes
+   * `UI_LABELS['pt-BR'].calendar`.
+   */
+  labels?: Partial<CalendarLabels>;
 
   // Constraints
   minDate?: Date;
@@ -79,7 +102,8 @@ type CalendarDefaultedKeys =
   | 'showOutsideDays'
   | 'minRangeLength'
   | 'allowSameDayRange'
-  | 'autoFocus';
+  | 'autoFocus'
+  | 'captionLayout';
 
 // CalendarProps with the defaults already applied, plus the month count resolved
 // from numberOfMonths and the selection mode.

package/src/components/form/Calendar/Calendar.views.ts

@@ -0,0 +1,101 @@
+/**
+ * The month and year views of `captionLayout="selectors"`: which years the
+ * list offers, which months are out of reach, and where the day grid lands
+ * after a pick. Pure, so the rules are tested without rendering anything.
+ */
+import { normalizeDate } from './Calendar.dates';
+
+export type CalendarView = 'days' | 'months' | 'years';
+
+const MONTHS_PER_YEAR = 12;
+
+/**
+ * The year list's span when the host gives no bound: the common date-picker
+ * window, wide enough for a birth date and for an appointment years ahead.
+ */
+export const DEFAULT_MIN_YEAR = 1900;
+export const DEFAULT_MAX_YEAR = 2099;
+
+export interface DateBounds {
+  minDate?: Date;
+  maxDate?: Date;
+}
+
+const startOfMonth = (year: number, month: number): Date => normalizeDate(new Date(year, month, 1));
+const endOfMonth = (year: number, month: number): Date => normalizeDate(new Date(year, month + 1, 0));
+
+/**
+ * Every year the list offers, newest first. The shown year is always in it, so
+ * a calendar opened outside its own bounds still has a highlighted year to
+ * start from rather than a list that does not contain where you are.
+ */
+export const yearOptions = ({ minDate, maxDate }: DateBounds, shownYear: number): number[] => {
+  const first = Math.min(minDate?.getFullYear() ?? DEFAULT_MIN_YEAR, shownYear);
+  const last = Math.max(maxDate?.getFullYear() ?? DEFAULT_MAX_YEAR, shownYear);
+  return Array.from({ length: last - first + 1 }, (_, index) => last - index);
+};
+
+/**
+ * Whether the year lies wholly outside the bounds — only ever the shown year,
+ * listed so the list contains where the calendar is.
+ */
+export const isYearOutOfBounds = (year: number, { minDate, maxDate }: DateBounds): boolean =>
+  (minDate !== undefined && year < minDate.getFullYear()) ||
+  (maxDate !== undefined && year > maxDate.getFullYear());
+
+/** Whether no day of the month can be picked because of `minDate`/`maxDate`. */
+export const isMonthOutOfBounds = (
+  year: number,
+  month: number,
+  { minDate, maxDate }: DateBounds,
+): boolean =>
+  (minDate !== undefined && endOfMonth(year, month) < normalizeDate(minDate)) ||
+  (maxDate !== undefined && startOfMonth(year, month) > normalizeDate(maxDate));
+
+/** The month to show in `year`: the one asked for, pulled inside the bounds. */
+export const clampMonthToBounds = (year: number, month: number, { minDate, maxDate }: DateBounds): number => {
+  if (minDate && year === minDate.getFullYear() && month < minDate.getMonth()) return minDate.getMonth();
+  if (maxDate && year === maxDate.getFullYear() && month > maxDate.getMonth()) return maxDate.getMonth();
+  return month;
+};
+
+/**
+ * The day focus lands on in the picked month: the same day of the month as
+ * before (the 31st becomes the month's last day), held inside the bounds.
+ */
+export const landingDay = (year: number, month: number, dayOfMonth: number, bounds: DateBounds): Date => {
+  const lastDay = new Date(year, month + 1, 0).getDate();
+  const day = normalizeDate(new Date(year, month, Math.min(dayOfMonth, lastDay)));
+  if (bounds.minDate && day < normalizeDate(bounds.minDate)) return normalizeDate(bounds.minDate);
+  if (bounds.maxDate && day > normalizeDate(bounds.maxDate)) return normalizeDate(bounds.maxDate);
+  return day;
+};
+
+/** Whether the arrow that moves `delta` months from `month` leads anywhere pickable. */
+export const canShiftMonth = (month: Date, delta: number, bounds: DateBounds): boolean => {
+  const target = new Date(month.getFullYear(), month.getMonth() + delta, 1);
+  return !isMonthOutOfBounds(target.getFullYear(), target.getMonth(), bounds);
+};
+
+/** The twelve month indexes, for the month grid. */
+export const MONTH_INDEXES = Array.from({ length: MONTHS_PER_YEAR }, (_, index) => index);
+
+// A lookup rather than a switch, like the day grid's: one entry per move.
+const GRID_MOVES: Record<string, (index: number, columns: number, length: number) => number> = {
+  ArrowLeft: (index) => index - 1,
+  ArrowRight: (index) => index + 1,
+  ArrowUp: (index, columns) => index - columns,
+  ArrowDown: (index, columns) => index + columns,
+  Home: () => 0,
+  End: (_, __, length) => length - 1,
+};
+
+/**
+ * Where focus moves in a month or year grid for a key, held to the grid; null
+ * when the key is not a move.
+ */
+export const moveInGrid = (key: string, index: number, columns: number, length: number): number | null => {
+  const move = GRID_MOVES[key];
+  if (!move) return null;
+  return Math.min(Math.max(move(index, columns, length), 0), length - 1);
+};

package/src/components/form/Calendar/CalendarMonth.tsx

@@ -25,7 +25,7 @@ const GRID_SX = { display: 'grid', gridTemplateColumns: 'repeat(7, minmax(0, 1fr
  * their gaps (7 × 40 + 6 × 4 design px). Months side by side keep a 280 basis,
  * so a multi-month calendar still wraps rather than squeezing every month.
  */
-const MONTH_SX = { flex: `1 1 ${sxRem(280)}`, minWidth: 0, maxWidth: sxRem(304) } as const;
+export const MONTH_SX = { flex: `1 1 ${sxRem(280)}`, minWidth: 0, maxWidth: sxRem(304) } as const;
 
 // Only the outermost months carry arrows; the ones between get a spacer so their
 // titles stay centred.
@@ -89,6 +89,29 @@ const WeekdayHeader: FC<{ weekdayNames: string[] }> = ({ weekdayNames }) => (
   </Box>
 );
 
+/** The weekday row and the day grid under a month's caption. */
+export const MonthDays: FC<{
+  matrix: MonthMatrix;
+  monthIndex: number;
+  weekdayNames: string[];
+  dayContext: DayCellContext;
+}> = ({ matrix, monthIndex, weekdayNames, dayContext }) => (
+  <>
+    <WeekdayHeader weekdayNames={weekdayNames} />
+
+    <Box
+      role="grid"
+      aria-labelledby={`month-${monthIndex}`}
+      data-testid="calendar-grid"
+      sx={GRID_SX}
+    >
+      {matrix.weeks.flat().map((day) => (
+        <CalendarDayCell key={day.key} day={day} {...dayContext} />
+      ))}
+    </Box>
+  </>
+);
+
 export interface CalendarMonthProps {
   matrix: MonthMatrix;
   monthIndex: number;
@@ -130,18 +153,12 @@ export const CalendarMonth: FC<CalendarMonthProps> = ({
         onNextMonth={onNextMonth}
       />
 
-      <WeekdayHeader weekdayNames={weekdayNames} />
-
-      <Box
-        role="grid"
-        aria-labelledby={`month-${monthIndex}`}
-        data-testid="calendar-grid"
-        sx={GRID_SX}
-      >
-        {matrix.weeks.flat().map((day) => (
-          <CalendarDayCell key={day.key} day={day} {...dayContext} />
-        ))}
-      </Box>
+      <MonthDays
+        matrix={matrix}
+        monthIndex={monthIndex}
+        weekdayNames={weekdayNames}
+        dayContext={dayContext}
+      />
     </Box>
   );
 };