@12-apps/ui 6.81.0 → 6.83.0

package/src/components/data-display/LazyImage/LazyImage.md

@@ -241,6 +241,7 @@ wrapping element, rounded to match the image:
 | `lazy` | `boolean` | `true` | Enable lazy loading |
 | `loadingState` | `'skeleton' \| 'spinner' \| 'placeholder' \| 'none'` | `'skeleton'` | Type of loading indicator. `'placeholder'` shows the `placeholder` image until the real image has faded in over it; set a `width` (or `"100%"`) with it |
 | `placeholder` | `string` | - | Low-res image shown while loading, only under `loadingState="placeholder"` (ignored otherwise). See [With Placeholder](#with-placeholder) |
+| `placeholderAlt` | `string` | `` `${alt} (loading)` `` | The placeholder image's `alt` while the real one loads (`UI_LABELS[locale].lazyImage.loadingAlt(alt)`) |
 | `rootMargin` | `string` | `'100px'` | Intersection Observer margin |
 | `threshold` | `number \| number[]` | `0` | Intersection Observer threshold |
 
@@ -249,6 +250,7 @@ wrapping element, rounded to match the image:
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `fallback` | `string \| ReactNode` | - | Fallback content on error |
+| `fallbackAlt` | `string` | `` `${alt} (fallback)` `` | A string `fallback` image's `alt` after the real one failed (`UI_LABELS[locale].lazyImage.fallbackAlt(alt)`) |
 | `retryOnError` | `boolean` | `false` | Retry loading on error |
 | `maxRetries` | `number` | `3` | Maximum retry attempts |
 | `retryDelay` | `number` | `1000` | Delay between retries (ms) |

package/src/components/data-display/Stepper/Stepper.md

@@ -25,6 +25,11 @@ interface StepperProps {
     state: { completed: boolean; active: boolean },
   ) => React.ReactNode;
   className?: string;
+  // The words the stepper adds to your step labels; any key left out reads in
+  // English: step(position, label) → `Step ${position}: ${label}`, optional →
+  // "optional", completed → "completed", current → "current".
+  // A pt-BR host passes UI_LABELS["pt-BR"].stepper.
+  labels?: Partial<StepperLabels>;
 }
 ```
 

package/src/components/data-display/Table/Table.md

@@ -58,6 +58,7 @@ import { Table } from '@procurement/ui';
 - **virtualScrolling** `boolean` - Enable virtual scrolling for large datasets
 - **loading** `boolean` - Show loading state
 - **hoverable** `boolean` - Enable row hover effects
+- **labels** `Partial<TableLabels>` - The accessible names the table adds: `sortBy(header)` (default `` `Sort by ${header}` ``), `selectRow(rowNumber)` (`` `select row ${rowNumber}` ``) and `selectAllRows` (`select all`). Any key left out keeps its English wording; a host passes `DATA_GRID_COPY[locale]` or `UI_LABELS[locale].table`
 
 ### Visual Effects
 

package/src/components/data-display/Timeline/Timeline.md

@@ -60,6 +60,7 @@ const items = [
 | animated      | `boolean`                              | `true`       | Enable slide-in animations               |
 | alternating   | `boolean`                              | `false`      | Alternate item positions (vertical only) |
 | onItemClick   | `(item: TimelineItem) => void`         | -            | Callback when item is clicked            |
+| labels        | `Partial<TimelineLabels>`              | English pack | The expand toggle's names (`Expand item details` / `Collapse item details`) and each card's (`` `Timeline item: ${title}` ``); any key left out reads in English. A pt-BR host passes `UI_LABELS['pt-BR'].timeline` |
 
 ### TimelineItem
 

package/src/components/feedback/Dialog/Dialog.md

@@ -31,6 +31,7 @@ The Dialog component provides a powerful, flexible modal dialog system with mult
 | `title` | `ReactNode` | `undefined` | Dialog title content |
 | `description` | `string` | `undefined` | Dialog subtitle/description text |
 | `showCloseButton` | `boolean` | `true` | Whether to show close button in header |
+| `closeLabel` | `string` | `close` | The close button's accessible name; a host passes `CHROME_COPY[locale].closePanel` |
 | `backdrop` | `boolean` | `true` | Whether to show backdrop overlay |
 | `persistent` | `boolean` | `false` | If true, prevents dismissal via backdrop or escape key |
 | `glass` | `boolean` | `false` | Enables glass morphism effect with backdrop blur |
@@ -48,6 +49,7 @@ The Dialog component provides a powerful, flexible modal dialog system with mult
 | `title` | `ReactNode` | `undefined` | Header title content |
 | `subtitle` | `ReactNode` | `undefined` | Header subtitle content |
 | `showCloseButton` | `boolean` | `true` | Whether to show close button |
+| `closeLabel` | `string` | `close` | The close button's accessible name; a host passes `CHROME_COPY[locale].closePanel` |
 | `onClose` | `() => void` | `undefined` | Callback when close button is clicked |
 | `children` | `ReactNode` | `undefined` | Custom header content (overrides title/subtitle) |
 | `dataTestId` | `string` | `undefined` | Custom test ID for testing |

package/src/components/feedback/StackedModal/StackedModal.md

@@ -126,6 +126,7 @@ new component that portals should too.
 | `onClose` | `() => void` | - | Callback when modal is closed |
 | `navigationTitle` | `string` | - | Title displayed in modal header |
 | `hideClose` | `boolean` | `false` | Drop the header's ✕ — the content owns the dismiss |
+| `closeLabel` | `string` | `close` | The header ✕'s accessible name (it carries only a glyph); a host passes `CHROME_COPY[locale].closePanel` |
 | `hideHeader` | `boolean` | `false` | Draw no header bar at all, for a root panel whose content brings its own header (✕ and name). Pass `aria-labelledby` naming that header's title (a dev warning fires without it). Root panel only |
 | `children` | `ReactNode` | - | Modal content |
 | `glass` | `boolean` | `false` | Enable glass morphism effect |

package/src/components/feedback/Toast/Toast.md

@@ -28,6 +28,7 @@ The Toast component provides a non-intrusive notification system for displaying
 | duration   | `number`                                                                | `5000`      | Auto-dismiss duration in milliseconds    |
 | persistent | `boolean`                                                               | `false`     | If true, toast won't auto-dismiss        |
 | closable   | `boolean`                                                               | `true`      | If true, shows a close button            |
+| closeLabel | `string`                                                                | `close`     | The close button's accessible name; a host passes `CHROME_COPY[locale].dismissToast`. Overrides the container's |
 | glass      | `boolean`                                                               | `false`     | Enables glass morphism effect            |
 | action     | `{ label: string; onClick: () => void }`                                | `undefined` | Action button configuration              |
 | promise    | `{ loading: string; success: string; error: string }`                   | `undefined` | Messages for promise-based notifications |
@@ -41,6 +42,7 @@ The Toast component provides a non-intrusive notification system for displaying
 | position   | `'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'` | `'bottom-right'`     | Position of the toast container     |
 | maxToasts  | `number`                                                                                          | `5`                  | Maximum number of toasts to display |
 | gap        | `number`                                                                                          | `12`                 | Gap between toasts in pixels        |
+| closeLabel | `string`                                                                                          | `close`              | Applied to every toast that sets no `closeLabel` of its own |
 | className  | `string`                                                                                          | `undefined`          | CSS class name for styling          |
 | dataTestId | `string`                                                                                          | `'toast-container'`  | Test ID for testing and automation  |
 

package/src/components/form/Button/Button.md

@@ -57,6 +57,7 @@ import { Button } from '@procurement/ui';
 | `color`      | `'primary' \| 'secondary' \| 'success' \| 'warning' \| 'info' \| 'danger' \| 'neutral'`      | `'primary'` | Color theme                               |
 | `size`       | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`                                        | `'md'`      | Button size                               |
 | `loading`    | `boolean`                                                                     | `false`     | Shows loading spinner over the label, sets `aria-busy`, disables button |
+| `loadingLabel` | `string`                                                                    | `loading`   | React Native only: the busy spinner's accessible name (`UI_LABELS[locale].common.loading`) |
 | `disabled`   | `boolean`                                                                     | `false`     | Disables button interaction               |
 | `icon`       | `ReactNode`                                                                   | -           | Icon element to display before text       |
 | `glow`       | `boolean`                                                                     | `false`     | Adds glow visual effect                   |

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

@@ -50,10 +50,15 @@ const endOfMonth = (date: Date): Date =>
 const dayKey = (date: Date): string =>
   `${date.getFullYear()}-${date.getMonth()}-${date.getDate()}`;
 
+/**
+ * The weeks of `month`. `fixedWeeks` always gives six, the next month's days
+ * filling the rest, so a calendar's height does not change from month to month.
+ */
 export const generateMonthMatrix = (
   month: number,
   year: number,
   firstDayOfWeek = 0,
+  fixedWeeks = false,
 ): MonthMatrix => {
   const firstDay = new Date(year, month, 1);
   const lastDay = endOfMonth(firstDay);
@@ -78,7 +83,7 @@ export const generateMonthMatrix = (
 
     // Stop on a week boundary once the month is behind us, so a month that fits
     // in five rows does not get a trailing sixth.
-    if (currentWeek.length === 0 && currentDate > lastDay) break;
+    if (!fixedWeeks && currentWeek.length === 0 && currentDate > lastDay) break;
   }
 
   return { weeks, month, year };
@@ -98,3 +103,13 @@ export const getWeekdayNames = (locale = 'en-US', firstDayOfWeek = 0): string[]
 
 export const getMonthName = (month: number, year: number, locale = 'en-US'): string =>
   new Date(year, month, 1).toLocaleDateString(locale, { month: 'long', year: 'numeric' });
+
+/**
+ * A month's name on its own, as the selectors caption and month grid show it:
+ * capitalised (pt-BR's `Intl` writes "março"), and `short` without the
+ * trailing abbreviation dot ("mar." → "mar").
+ */
+export const getMonthLabel = (month: number, locale = 'en-US', width: 'long' | 'short' = 'long'): string => {
+  const name = new Date(2025, month, 1).toLocaleDateString(locale, { month: width }).replace(/\.$/, '');
+  return width === 'long' ? name.charAt(0).toLocaleUpperCase(locale) + name.slice(1) : name;
+};

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

@@ -10,6 +10,7 @@ const CALENDAR_DEFAULTS = {
   minRangeLength: 1,
   allowSameDayRange: true,
   autoFocus: false,
+  captionLayout: 'arrows',
 } as const satisfies Partial<CalendarProps>;
 
 // Strips explicitly-undefined props before the merge, so `prop={undefined}` still
@@ -28,5 +29,8 @@ export const resolveCalendarProps = (props: CalendarProps): ResolvedCalendarProp
   // date does not.
   const defaultMonths = merged.selectionMode === 'range' ? 2 : 1;
 
+  // The selectors caption names ONE month and one year, so it shows one month.
+  if (merged.captionLayout === 'selectors') return { ...merged, monthsToShow: 1 };
+
   return { ...merged, monthsToShow: merged.numberOfMonths ?? defaultMonths };
 };

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 && (