@12-apps/ui 6.81.0 → 6.83.0

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>
   );
 };

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

@@ -0,0 +1,139 @@
+import type { SxProps, Theme } from '@mui/material/styles/index.js';
+import Box from '@mui/material/Box/index.js';
+import type { FC } from 'react';
+import React, { useEffect, useRef, useState } from 'react';
+
+import { rem, sxRem } from '../../../tokens/relative';
+
+import { moveInGrid } from './Calendar.views';
+
+/** A pick button's smallest edge: a touch target at any width (44 design px). */
+const TARGET_SIZE = sxRem(44);
+
+export interface PickerOption {
+  value: number;
+  label: string;
+  /** The accessible name, when the visible label is an abbreviation ("mar"). */
+  ariaLabel?: string;
+  disabled: boolean;
+  /** The month or year the calendar is showing. */
+  current: boolean;
+}
+
+const inkFor = ({ current, disabled }: PickerOption): string => {
+  if (current) return 'primary.contrastText';
+  return disabled ? 'text.disabled' : 'text.primary';
+};
+
+const optionSx = (option: PickerOption): SxProps<Theme> => ({
+  minHeight: TARGET_SIZE,
+  minWidth: 0,
+  boxSizing: 'border-box',
+  padding: 0,
+  font: 'inherit',
+  typography: 'body1',
+  border: 1,
+  borderColor: option.current ? 'primary.main' : 'divider',
+  borderRadius: 1,
+  backgroundColor: option.current ? 'primary.main' : 'transparent',
+  color: inkFor(option),
+  cursor: option.disabled ? 'not-allowed' : 'pointer',
+  '&:hover': { backgroundColor: option.current || option.disabled ? undefined : 'action.hover' },
+  '&:focus-visible': {
+    outline: (theme: Theme) => `${rem(theme, 2)} solid`,
+    outlineColor: 'primary.main',
+    outlineOffset: sxRem(1),
+  },
+});
+
+// The grid fills the box the day grid leaves (see CalendarSelectorsMonth), so
+// opening it never resizes the calendar: a short grid's rows stretch to fill
+// it, a long one scrolls inside it.
+const gridSx = (columns: number, scrollable: boolean): SxProps<Theme> => ({
+  display: 'grid',
+  gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`,
+  gap: 1,
+  boxSizing: 'border-box',
+  height: '100%',
+  // Room for the focus ring of the edge buttons inside the box.
+  p: 0.5,
+  ...(scrollable ? { alignContent: 'start', overflowY: 'auto' } : { gridAutoRows: '1fr' }),
+});
+
+export interface CalendarPickerGridProps {
+  id: string;
+  ariaLabel: string;
+  columns: number;
+  options: PickerOption[];
+  testId: string;
+  scrollable?: boolean;
+  onPick: (value: number) => void;
+  onDismiss: () => void;
+}
+
+/**
+ * The month or year grid that stands in for the days. One tab stop (roving
+ * `tabIndex`); arrows, Home and End move it, Enter/Space pick, Escape goes back
+ * to the days unchanged. Out-of-bounds options stay focusable and say
+ * `aria-disabled`, so the arrows never skip a hole a reader cannot explain.
+ */
+export const CalendarPickerGrid: FC<CalendarPickerGridProps> = ({
+  id,
+  ariaLabel,
+  columns,
+  options,
+  testId,
+  scrollable = false,
+  onPick,
+  onDismiss,
+}) => {
+  const [active, setActive] = useState(() => Math.max(options.findIndex((option) => option.current), 0));
+  const buttons = useRef<Array<HTMLButtonElement | null>>([]);
+
+  // Also runs on mount: opening the grid puts focus on the shown month/year,
+  // which scrolls a long year list to it.
+  useEffect(() => {
+    buttons.current[active]?.focus();
+  }, [active]);
+
+  const handleKeyDown = (event: React.KeyboardEvent) => {
+    // The calendar's own day keys must not move a day nobody can see.
+    event.stopPropagation();
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      onDismiss();
+      return;
+    }
+    const next = moveInGrid(event.key, active, columns, options.length);
+    if (next === null) return;
+    event.preventDefault();
+    setActive(next);
+  };
+
+  return (
+    <Box id={id} role="group" aria-label={ariaLabel} data-testid={testId} onKeyDown={handleKeyDown} sx={gridSx(columns, scrollable)}>
+      {options.map((option, index) => (
+        <Box
+          key={option.value}
+          component="button"
+          type="button"
+          ref={(node: HTMLButtonElement | null) => {
+            buttons.current[index] = node;
+          }}
+          tabIndex={index === active ? 0 : -1}
+          aria-current={option.current ? 'true' : undefined}
+          aria-disabled={option.disabled || undefined}
+          aria-label={option.ariaLabel}
+          data-testid={`${testId}-${option.value}`}
+          onFocus={() => setActive(index)}
+          onClick={() => {
+            if (!option.disabled) onPick(option.value);
+          }}
+          sx={optionSx(option)}
+        >
+          {option.label}
+        </Box>
+      ))}
+    </Box>
+  );
+};

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

@@ -0,0 +1,163 @@
+import ArrowDropDown from '@mui/icons-material/ArrowDropDown';
+import ChevronLeft from '@mui/icons-material/ChevronLeft';
+import ChevronRight from '@mui/icons-material/ChevronRight';
+import Box from '@mui/material/Box/index.js';
+import Button from '@mui/material/Button/index.js';
+import IconButton from '@mui/material/IconButton/index.js';
+import type { FC } from 'react';
+import React from 'react';
+
+import type { CalendarLabels } from '../../../copy/labels';
+import { sxRem } from '../../../tokens/relative';
+
+import type { CalendarView } from './Calendar.views';
+
+/** Every control in the caption is a touch target at any width (44 design px). */
+const TARGET_SIZE = sxRem(44);
+
+/**
+ * The shown month over every month name, hidden: the button keeps the width of
+ * the longest, so stepping from Agosto to Setembro moves nothing.
+ */
+const MonthText: FC<{ text: string; names: string[] }> = ({ text, names }) => (
+  <Box component="span" sx={{ display: 'inline-grid', justifyItems: 'start' }}>
+    {names.map((name) => (
+      <Box key={name} component="span" aria-hidden sx={{ gridArea: '1 / 1', visibility: 'hidden' }}>
+        {name}
+      </Box>
+    ))}
+    <Box component="span" data-testid="calendar-month-select-text" sx={{ gridArea: '1 / 1' }}>
+      {text}
+    </Box>
+  </Box>
+);
+
+const SelectorButton: FC<{
+  testId: string;
+  text: React.ReactNode;
+  ariaLabel: string;
+  expanded: boolean;
+  controls: string;
+  onClick: () => void;
+}> = ({ testId, text, ariaLabel, expanded, controls, onClick }) => (
+  <Button
+    type="button"
+    color="inherit"
+    data-testid={testId}
+    aria-label={ariaLabel}
+    aria-expanded={expanded}
+    aria-controls={expanded ? controls : undefined}
+    endIcon={<ArrowDropDown />}
+    onClick={onClick}
+    sx={{
+      minHeight: TARGET_SIZE,
+      px: 0.5,
+      whiteSpace: 'nowrap',
+      textTransform: 'none',
+      typography: 'subtitle1',
+      fontWeight: 'bold',
+      border: 1,
+      borderColor: 'divider',
+      backgroundColor: expanded ? 'action.selected' : 'transparent',
+    }}
+  >
+    {text}
+  </Button>
+);
+
+const ARROW_SX = { width: TARGET_SIZE, height: TARGET_SIZE } as const;
+
+export interface CalendarSelectorsCaptionProps {
+  monthText: string;
+  /** Every month's name in the locale, which sizes the month button. */
+  monthNames: string[];
+  year: number;
+  view: CalendarView;
+  labels: CalendarLabels;
+  /** The id of the pick grid each button opens. */
+  monthsId: string;
+  yearsId: string;
+  canGoPrevious: boolean;
+  canGoNext: boolean;
+  onToggle: (view: Exclude<CalendarView, 'days'>) => void;
+  /** Escape on a caption control closes an open grid; with none open it is the host's. */
+  onEscape: () => void;
+  onPreviousMonth: () => void;
+  onNextMonth: () => void;
+}
+
+/**
+ * `<Month> ▾` and `<Year> ▾`, then the month arrows. Its keys are its own: the
+ * container's day keys would otherwise turn Enter on a button into a day pick.
+ * Escape is the exception while no grid is open, so the sheet or popover that
+ * holds the calendar still closes on it.
+ */
+export const CalendarSelectorsCaption: FC<CalendarSelectorsCaptionProps> = ({
+  monthText,
+  monthNames,
+  year,
+  view,
+  labels,
+  monthsId,
+  yearsId,
+  canGoPrevious,
+  canGoNext,
+  onToggle,
+  onEscape,
+  onPreviousMonth,
+  onNextMonth,
+}) => (
+  <Box
+    data-testid="calendar-header"
+    onKeyDown={(event) => {
+      if (event.key === 'Escape' && view === 'days') return;
+      event.stopPropagation();
+      if (event.key === 'Escape') onEscape();
+    }}
+    // Two groups that wrap rather than squeeze: in a 320 sheet the arrows take
+    // a second line, and no button shrinks below a touch target. The month
+    // button is as wide as the longest month name, so whether they wrap depends
+    // on the width only, never on the month shown.
+    sx={{ display: 'flex', flexWrap: 'wrap', alignItems: 'center', gap: 1, mb: 2 }}
+  >
+    <Box sx={{ display: 'flex', gap: 0.5 }}>
+      <SelectorButton
+        testId="calendar-month-select"
+        text={<MonthText text={monthText} names={monthNames} />}
+        ariaLabel={labels.chooseMonth(monthText)}
+        expanded={view === 'months'}
+        controls={monthsId}
+        onClick={() => onToggle('months')}
+      />
+      <SelectorButton
+        testId="calendar-year-select"
+        text={String(year)}
+        ariaLabel={labels.chooseYear(year)}
+        expanded={view === 'years'}
+        controls={yearsId}
+        onClick={() => onToggle('years')}
+      />
+    </Box>
+
+    <Box sx={{ display: 'flex', ml: 'auto' }}>
+      <IconButton
+        aria-label={labels.previousMonth}
+        disabled={!canGoPrevious}
+        onClick={onPreviousMonth}
+        data-testid="calendar-prev-month"
+        sx={ARROW_SX}
+      >
+        <ChevronLeft />
+      </IconButton>
+      <IconButton
+        aria-label={labels.nextMonth}
+        disabled={!canGoNext}
+        onClick={onNextMonth}
+        data-testid="calendar-next-month"
+        sx={ARROW_SX}
+      >
+        <ChevronRight />
+      </IconButton>
+    </Box>
+  </Box>
+);

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

@@ -0,0 +1,137 @@
+import Box from '@mui/material/Box/index.js';
+import type { FC } from 'react';
+import React, { useId } from 'react';
+
+import type { CalendarLabels } from '../../../copy/labels';
+
+import { getMonthLabel } from './Calendar.dates';
+import type { CalendarPicker } from './Calendar.picker';
+import type { MonthMatrix } from './Calendar.types';
+import type { DateBounds } from './Calendar.views';
+import { MONTH_INDEXES, canShiftMonth, isMonthOutOfBounds, isYearOutOfBounds, yearOptions } from './Calendar.views';
+import type { DayCellContext } from './CalendarDayCell';
+import { MONTH_SX, MonthDays } from './CalendarMonth';
+import type { PickerOption } from './CalendarPickerGrid';
+import { CalendarPickerGrid } from './CalendarPickerGrid';
+import { CalendarSelectorsCaption } from './CalendarSelectorsCaption';
+
+/** The days and the open grid share one cell, so opening a grid never resizes the calendar. */
+const BODY_SX = { display: 'grid' } as const;
+
+/** Adds no height of its own; a long year list scrolls inside the days' height. */
+const PICKER_SLOT_SX = {
+  gridArea: '1 / 1',
+  height: 0,
+  minHeight: '100%',
+} as const;
+
+const YEAR_COLUMNS = 4;
+const MONTH_COLUMNS = 3;
+
+export interface CalendarSelectorsMonthProps {
+  matrix: MonthMatrix;
+  locale: string;
+  weekdayNames: string[];
+  dayContext: DayCellContext;
+  bounds: DateBounds;
+  labels: CalendarLabels;
+  picker: CalendarPicker;
+  onPreviousMonth: () => void;
+  onNextMonth: () => void;
+}
+
+const monthOptions = ({ year, month }: MonthMatrix, locale: string, bounds: DateBounds): PickerOption[] =>
+  MONTH_INDEXES.map((index) => ({
+    value: index,
+    label: getMonthLabel(index, locale, 'short'),
+    ariaLabel: getMonthLabel(index, locale, 'long'),
+    disabled: isMonthOutOfBounds(year, index, bounds),
+    current: index === month,
+  }));
+
+// The list is cut at the bounds' years, so only a shown year outside them is
+// disabled.
+const yearPickerOptions = ({ year }: MonthMatrix, bounds: DateBounds): PickerOption[] =>
+  yearOptions(bounds, year).map((option) => ({
+    value: option,
+    label: String(option),
+    disabled: isYearOutOfBounds(option, bounds),
+    current: option === year,
+  }));
+
+/**
+ * The one month of `captionLayout="selectors"`: the month/year caption over the
+ * days, or over the month or year grid that stands in for them.
+ */
+export const CalendarSelectorsMonth: FC<CalendarSelectorsMonthProps> = ({
+  matrix,
+  locale,
+  weekdayNames,
+  dayContext,
+  bounds,
+  labels,
+  picker,
+  onPreviousMonth,
+  onNextMonth,
+}) => {
+  const idPrefix = useId();
+  const monthsId = `${idPrefix}-months`;
+  const yearsId = `${idPrefix}-years`;
+  const shown = new Date(matrix.year, matrix.month, 1);
+
+  const picking = picker.view !== 'days';
+
+  return (
+    <Box sx={MONTH_SX} data-testid="calendar-month-0">
+      <CalendarSelectorsCaption
+        monthText={getMonthLabel(matrix.month, locale, 'long')}
+        monthNames={MONTH_INDEXES.map((index) => getMonthLabel(index, locale, 'long'))}
+        year={matrix.year}
+        view={picker.view}
+        labels={labels}
+        monthsId={monthsId}
+        yearsId={yearsId}
+        canGoPrevious={canShiftMonth(shown, -1, bounds)}
+        canGoNext={canShiftMonth(shown, 1, bounds)}
+        onToggle={picker.toggle}
+        onEscape={picker.dismiss}
+        onPreviousMonth={onPreviousMonth}
+        onNextMonth={onNextMonth}
+      />
+
+      <Box sx={BODY_SX}>
+        {/* The days keep their place while a grid is open, so the calendar keeps their size at every density. */}
+        <Box sx={{ gridArea: '1 / 1', visibility: picking ? 'hidden' : 'visible' }} data-testid="calendar-days">
+          <MonthDays matrix={matrix} monthIndex={0} weekdayNames={weekdayNames} dayContext={dayContext} />
+        </Box>
+        {picking && (
+          <Box sx={PICKER_SLOT_SX}>
+            {picker.view === 'months' && (
+              <CalendarPickerGrid
+                id={monthsId}
+                ariaLabel={labels.months}
+                columns={MONTH_COLUMNS}
+                options={monthOptions(matrix, locale, bounds)}
+                testId="calendar-months"
+                onPick={picker.pickMonth}
+                onDismiss={picker.dismiss}
+              />
+            )}
+            {picker.view === 'years' && (
+              <CalendarPickerGrid
+                id={yearsId}
+                ariaLabel={labels.years}
+                columns={YEAR_COLUMNS}
+                options={yearPickerOptions(matrix, bounds)}
+                testId="calendar-years"
+                scrollable
+                onPick={picker.pickYear}
+                onDismiss={picker.dismiss}
+              />
+            )}
+          </Box>
+        )}
+      </Box>
+    </Box>
+  );
+};

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

@@ -1,5 +1,6 @@
 export { Calendar,Calendar as default } from './Calendar';
 export type {
+  CalendarCaptionLayout,
   CalendarInternalState,
   CalendarProps,
   DateRange,