@cahyo-dimas/freeday 3.7.0 → 3.9.0

package/adapters/react/usePopover.ts

@@ -3,24 +3,56 @@ import { useEffect, type RefObject } from 'react';
 // React port of adapters/vue/usePopover.ts. Lifts a dropdown panel into the top layer via the
 // native Popover API so it escapes any ancestor overflow clip (a .fdy-card, a scroll container),
 // then positions it `fixed` against its trigger (flip above when there's no room below; match the
-// trigger width). Degrades to the panel's own [hidden]/absolute CSS where Popover is unavailable.
+// trigger width; line either edge up with the trigger's). Degrades to the panel's own
+// [hidden]/absolute CSS where Popover is unavailable.
 
 interface PopoverElement extends HTMLElement {
   showPopover(): void;
   hidePopover(): void;
 }
 
+/**
+ * Which of the panel's edges lines up with the trigger's. `'start'` (the default everywhere it is
+ * omitted) puts the panel's LEFT edge on the trigger's left edge, right for an input-shaped
+ * dropdown. `'end'` puts its RIGHT edge on the trigger's right edge, which is what a panel much
+ * wider than its trigger needs when the trigger sits in a right-hand gutter or a table header.
+ * Same two names as the raw path's `place()`, so one concept does not grow a second vocabulary.
+ */
+export type FdyPopoverAlign = 'start' | 'end';
+
 const GAP = 4; // ~ --space-1
 const supported: boolean =
   typeof HTMLElement !== 'undefined'
   && typeof (HTMLElement.prototype as Partial<PopoverElement>).showPopover === 'function';
 
-function place(panel: HTMLElement, trigger: HTMLElement): void {
-  const r: DOMRect = trigger.getBoundingClientRect();
+function place(
+  panel: HTMLElement,
+  trigger: HTMLElement,
+  align: FdyPopoverAlign | undefined,
+  matchWidth: boolean | undefined,
+): void {
+  /* Take the panel out of the flow BEFORE measuring anything. Until this runs the panel is still
+   * `position:absolute` with `top:calc(100% + …)` from its component's stylesheet, an author rule
+   * outranks the popover UA style, and in the top layer that `100%` resolves against the viewport.
+   * So a panel that has just been shown sits one viewport height down the page and drags the
+   * document's scrollable overflow with it. Where scrollbars take layout space (every Windows and
+   * Linux browser; macOS overlay scrollbars hide it) the document gains a classic scrollbar for the
+   * duration, documentElement.clientWidth drops by its width, and the page relays out that much
+   * narrower. A trigger rect read in that instant belongs to a layout the next three lines undo:
+   * measured 741 instead of 756 for a combo in a 24px gutter, a scrollbar's width to the left. */
   panel.style.position = 'fixed';
   panel.style.margin = '0';
   panel.style.inset = 'auto';
-  panel.style.minWidth = `${r.width}px`;
+  const r: DOMRect = trigger.getBoundingClientRect();
+  /* The trigger's width as a FLOOR, and `matchWidth !== false` rather than a truthiness test, the
+     same spelling the raw `place()` uses. It is what keeps the four input-shaped panels looking
+     like one control with its list hanging off it, and it is not cosmetic: `.fdy-combo__listbox`,
+     `.fdy-autocomplete__listbox` and `.fdy-cascade__panel` are `min-width:100%`, and once the panel
+     is `fixed` in the top layer that 100% is the VIEWPORT, so without this line a 220px combo opens
+     a 1000px listbox. A panel whose stylesheet asks for a width of its own opts out instead:
+     `.fdy-filter` wants `min-width:14rem` and hangs off a 24px funnel, and an inline floor of 24px
+     outranks the rule, which left the typed filter panel 206px wide against the 224 it asked for. */
+  if (matchWidth !== false) panel.style.minWidth = `${r.width}px`;
   const ph: number = panel.offsetHeight;
   const pw: number = panel.offsetWidth;
   const vw: number = document.documentElement.clientWidth;
@@ -28,16 +60,29 @@ function place(panel: HTMLElement, trigger: HTMLElement): void {
   const below: number = vh - r.bottom - GAP;
   const above: number = r.top - GAP;
   const top: number = ph <= below || below >= above ? r.bottom + GAP : Math.max(GAP, r.top - GAP - ph);
-  let left: number = r.left;
-  if (left + pw > vw - GAP) left = Math.max(GAP, vw - GAP - pw);
+  let left: number = align === 'end' ? r.right - pw : r.left;
+  /* Clamped on BOTH sides, and that is not belt-and-braces: the first line keeps a start-aligned
+     panel on screen, the second keeps an end-aligned one on screen when the panel is wider than the
+     room to the left of its trigger. Keeping only one of them trades an overflow on one edge for an
+     overflow on the other. */
+  if (left + pw > vw - GAP) left = vw - GAP - pw;
+  if (left < GAP) left = GAP;
   panel.style.top = `${Math.round(top)}px`;
   panel.style.left = `${Math.round(left)}px`;
 }
 
+/**
+ * Anchor a dropdown `panelRef` to `triggerRef` in the top layer while `open` is true. The panel
+ * element must carry `popover="manual"`. `align` and `matchWidth` are plain values, not an options
+ * object, so the effect below can list them in its dependencies without a caller having to
+ * memoise anything. Omitting them means `'start'` and `true`.
+ */
 export function usePopover(
   panelRef: RefObject<HTMLElement | null>,
   triggerRef: RefObject<HTMLElement | null>,
   open: boolean,
+  align?: FdyPopoverAlign,
+  matchWidth?: boolean,
 ): void {
   useEffect((): void | (() => void) => {
     const panel: PopoverElement | null = panelRef.current as PopoverElement | null;
@@ -45,12 +90,12 @@ export function usePopover(
     if (!supported || panel === null || trigger === null) return;
 
     function reposition(): void {
-      if (panel !== null && trigger !== null && panel.matches(':popover-open')) place(panel, trigger);
+      if (panel !== null && trigger !== null && panel.matches(':popover-open')) place(panel, trigger, align, matchWidth);
     }
 
     if (open) {
       if (!panel.matches(':popover-open')) panel.showPopover();
-      place(panel, trigger);
+      place(panel, trigger, align, matchWidth);
       window.addEventListener('scroll', reposition, true);
       window.addEventListener('resize', reposition);
       return (): void => {
@@ -60,5 +105,5 @@ export function usePopover(
       };
     }
     return;
-  }, [open, panelRef, triggerRef]);
+  }, [open, panelRef, triggerRef, align, matchWidth]);
 }

package/adapters/vue/components/FdyDatepicker.vue

@@ -1,6 +1,31 @@
 <script setup lang="ts">
 import { computed, nextTick, onBeforeUnmount, onMounted, ref, useId, type ComputedRef, type Ref } from 'vue';
 import { usePopover } from '../usePopover';
+/* The month and year grids, which `FdyMonthpicker` reads from the same module. They were written
+   here and moved out when the month picker arrived: a second copy of the bounds rule is a second
+   place to fix it, and this release spent three items on exactly that failure in the panel-position
+   logic (#079). What the two components do differently with the grid stays in each of them, which
+   is one branch: whether choosing a month commits or walks down into its days. */
+import {
+  YEARS_PER_PAGE,
+  addMonths,
+  monthCells as buildMonthCells,
+  monthDisabled,
+  monthFormatters,
+  monthKeyIntent,
+  pageLocale,
+  parseISOMonth,
+  startOfDay,
+  startOfMonth,
+  toISOMonth,
+  yearCells as buildYearCells,
+  yearKeyIntent,
+  yearPageStart,
+  yearRangeLabel,
+  type FdyMonthCell,
+  type FdyMonthFormatters,
+  type FdyYearCell,
+} from '../../core/month-grid.js';
 
 // A Vue-native binding over freeday's `.fdy-datepicker` / `.fdy-cal__*` classes
 // (see src/components/datepicker.css). freeday ships the styled trigger+popover
@@ -12,6 +37,12 @@ import { usePopover } from '../usePopover';
 // over the same kit classes. Open/close (outside-click + focusout) mirrors the
 // already-approved FdyCombo.vue pattern. Range mode is out of scope (v1 = single date).
 
+/** Which grid is on screen. The drill goes days -> months -> years and back down. */
+type CalendarLevel = 'days' | 'months' | 'years';
+
+/** What the picker answers with: a day (`YYYY-MM-DD`) or a whole month (`YYYY-MM`). */
+type FdyDatepickerMode = 'day' | 'month';
+
 interface DayCell {
   date: Date;
   iso: string;
@@ -25,7 +56,18 @@ interface DayCell {
 }
 
 const props = defineProps<{
+  /** ISO `YYYY-MM-DD`, or `YYYY-MM` when `mode` is `'month'`. `''`/`null` for empty. */
   modelValue: string | null;
+  /**
+   * `'day'` (default) answers with a date. `'month'` opens on the month grid, stops there, and
+   * answers with `YYYY-MM`.
+   *
+   * @deprecated Use `FdyMonthpicker` for a month. This prop makes `modelValue`, `min` and `max`
+   * carry two different formats while a *different* prop decides which, so the type cannot state
+   * what to store in them. `FdyMonthpicker` has one format per prop and no mode to read. Still
+   * works, unchanged, and removed in 4.0.
+   */
+  mode?: FdyDatepickerMode;
   min?: string;
   max?: string;
   locale?: string;
@@ -78,12 +120,6 @@ function parseISO(s: string | null | undefined): Date | null {
   const d: Date = new Date(y, m - 1, day);
   return Number.isNaN(d.getTime()) ? null : d;
 }
-function startOfDay(d: Date): Date {
-  return new Date(d.getFullYear(), d.getMonth(), d.getDate());
-}
-function startOfMonth(d: Date): Date {
-  return new Date(d.getFullYear(), d.getMonth(), 1);
-}
 function sameDay(a: Date | null, b: Date | null): boolean {
   return a !== null && b !== null && a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
 }
@@ -92,11 +128,6 @@ function addDays(d: Date, n: number): Date {
   x.setDate(x.getDate() + n);
   return x;
 }
-function addMonths(d: Date, n: number): Date {
-  const x: Date = new Date(d);
-  x.setMonth(x.getMonth() + n);
-  return x;
-}
 
 const baseId: string = useId();
 const triggerId: ComputedRef<string> = computed((): string => props.id ?? `${baseId}-trigger`);
@@ -113,13 +144,22 @@ const open: Ref<boolean> = ref(false);
 // scroll container; positions against the trigger.
 usePopover(panelEl, triggerEl, open);
 
-const selectedDate: ComputedRef<Date | null> = computed((): Date | null => parseISO(props.modelValue));
-const minDate: ComputedRef<Date | null> = computed((): Date | null => parseISO(props.min));
-const maxDate: ComputedRef<Date | null> = computed((): Date | null => parseISO(props.max));
+const isMonthMode: ComputedRef<boolean> = computed((): boolean => props.mode === 'month');
+/** Resolved once here so every formatter below reads the same tag. */
+const activeLocale: ComputedRef<string> = computed((): string => props.locale ?? pageLocale());
+/** Reading `props.mode` inside the computeds below is what keeps them in step with it. */
+function parseValue(s: string | null | undefined): Date | null {
+  return props.mode === 'month' ? parseISOMonth(s) : parseISO(s);
+}
+const selectedDate: ComputedRef<Date | null> = computed((): Date | null => parseValue(props.modelValue));
+const minDate: ComputedRef<Date | null> = computed((): Date | null => parseValue(props.min));
+const maxDate: ComputedRef<Date | null> = computed((): Date | null => parseValue(props.max));
 const isDisabled: ComputedRef<boolean> = computed((): boolean => props.disabled === true);
 const isReadonly: ComputedRef<boolean> = computed((): boolean => props.readonly === true);
 const isInvalid: ComputedRef<boolean> = computed((): boolean => props.invalid === true);
-const displayPlaceholder: ComputedRef<string> = computed((): string => props.placeholder ?? 'Select date');
+const displayPlaceholder: ComputedRef<string> = computed(
+  (): string => props.placeholder ?? (isMonthMode.value ? 'Select month' : 'Select date'),
+);
 const showClear: ComputedRef<boolean> = computed(
   (): boolean => props.clearable === true && selectedDate.value !== null && isDisabled.value === false && isReadonly.value === false,
 );
@@ -145,119 +185,67 @@ const effectiveFocusDate: ComputedRef<Date> = computed((): Date => {
   return new Date(view.value.getFullYear(), view.value.getMonth(), Math.min(f.getDate(), daysInMonth));
 });
 
-/* 'days' | 'months', the calendar drills one level up instead of growing furniture beside the title.
-   Before this the only pointer route to another month was one click per month: August 2026 to March
-   2022 is fifty-three of them, and the Shift+PageUp jump had no affordance at all. */
-const mode: Ref<'days' | 'months' | 'years'> = ref('days');
+/* Which grid is showing, and the calendar drills one level up instead of growing furniture beside
+   the title. Before this the only pointer route to another month was one click per month: August
+   2026 to March 2022 is fifty-three of them, and the Shift+PageUp jump had no affordance at all.
+   Named `level`, not `mode`: `mode` is the PROP that decides what the picker answers with, and one
+   name for both would read as the same thing in a template that mentions them together.
+
+   Month mode has no level below months, so the day grid is unreachable by construction rather
+   than by every path remembering not to ask for it. */
+function startLevel(): CalendarLevel {
+  return props.mode === 'month' ? 'months' : 'days';
+}
+const level: Ref<CalendarLevel> = ref(startLevel());
 const focusMonth: Ref<number> = ref(0);
 const focusYear: Ref<number> = ref(0);
 
-/* A page of twelve years, ALIGNED so pages tile: 2016-2027, 2028-2039. Anchoring the page on the
-   year in view would make the arrows land on overlapping windows, and the same year would sit at a
-   different spot every time you stepped. */
-const YEARS_PER_PAGE = 12;
-const yearPageStart = (year: number): number => Math.floor(year / YEARS_PER_PAGE) * YEARS_PER_PAGE;
-
-const monthCellFmt: ComputedRef<Intl.DateTimeFormat> = computed(
-  (): Intl.DateTimeFormat => new Intl.DateTimeFormat(props.locale, { month: 'short' }),
-);
-const monthNameFmt: ComputedRef<Intl.DateTimeFormat> = computed(
-  (): Intl.DateTimeFormat => new Intl.DateTimeFormat(props.locale, { month: 'long', year: 'numeric' }),
+const formatters: ComputedRef<FdyMonthFormatters> = computed(
+  (): FdyMonthFormatters => monthFormatters(activeLocale.value),
 );
 
-interface MonthCell {
-  index: number;
-  label: string;
-  ariaLabel: string;
-  selected: boolean;
-  today: boolean;
-  disabled: boolean;
-  focusable: boolean;
-}
-
-/** A month is only unreachable when the WHOLE month falls outside min/max. Checked against the
- *  bounds directly, not by testing both ends with isDayDisabled: a range that sits INSIDE one month
- *  disables both ends while the middle is perfectly selectable. */
-function isMonthDisabled(year: number, month: number): boolean {
-  const first: Date = new Date(year, month, 1);
-  const last: Date = new Date(year, month + 1, 0);
-  if (minDate.value !== null && startOfDay(last).getTime() < startOfDay(minDate.value).getTime()) return true;
-  if (maxDate.value !== null && startOfDay(first).getTime() > startOfDay(maxDate.value).getTime()) return true;
-  return false;
-}
-
-const monthCells: ComputedRef<MonthCell[]> = computed((): MonthCell[] => {
-  const year: number = view.value.getFullYear();
-  const today: Date = new Date();
-  const sel: Date | null = selectedDate.value;
-  return Array.from({ length: 12 }, (_unused: unknown, index: number): MonthCell => {
-    const cellDate: Date = new Date(year, index, 1);
-    return {
-      index,
-      label: monthCellFmt.value.format(cellDate),
-      ariaLabel: monthNameFmt.value.format(cellDate),
-      selected: sel !== null && sel.getFullYear() === year && sel.getMonth() === index,
-      today: today.getFullYear() === year && today.getMonth() === index,
-      disabled: isMonthDisabled(year, index),
-      focusable: index === focusMonth.value,
-    };
-  });
-});
-
-interface YearCell {
-  year: number;
-  selected: boolean;
-  today: boolean;
-  disabled: boolean;
-  focusable: boolean;
-}
-
-/** A year is unreachable only when EVERY month in it falls outside min/max, the same rule
- *  isMonthDisabled applies one level down, and for the same reason. */
-function isYearDisabled(year: number): boolean {
-  if (minDate.value !== null && startOfDay(new Date(year, 11, 31)).getTime() < startOfDay(minDate.value).getTime()) return true;
-  if (maxDate.value !== null && startOfDay(new Date(year, 0, 1)).getTime() > startOfDay(maxDate.value).getTime()) return true;
-  return false;
-}
+const monthCells: ComputedRef<FdyMonthCell[]> = computed((): FdyMonthCell[] => buildMonthCells({
+  year: view.value.getFullYear(),
+  selected: selectedDate.value,
+  min: minDate.value,
+  max: maxDate.value,
+  focusMonth: focusMonth.value,
+  formatters: formatters.value,
+}));
 
 const yearPage: ComputedRef<number> = computed((): number => yearPageStart(focusYear.value));
 
-const yearCells: ComputedRef<YearCell[]> = computed((): YearCell[] => {
-  const start: number = yearPage.value;
-  const thisYear: number = new Date().getFullYear();
-  const sel: Date | null = selectedDate.value;
-  return Array.from({ length: YEARS_PER_PAGE }, (_unused: unknown, index: number): YearCell => {
-    const year: number = start + index;
-    return {
-      year,
-      selected: sel !== null && sel.getFullYear() === year,
-      today: thisYear === year,
-      disabled: isYearDisabled(year),
-      focusable: year === focusYear.value,
-    };
-  });
-});
+const yearCells: ComputedRef<FdyYearCell[]> = computed((): FdyYearCell[] => buildYearCells({
+  pageStart: yearPage.value,
+  selected: selectedDate.value,
+  min: minDate.value,
+  max: maxDate.value,
+  focusYear: focusYear.value,
+}));
 
-const yearRangeLabel: ComputedRef<string> = computed(
-  (): string => `${yearPage.value} – ${yearPage.value + YEARS_PER_PAGE - 1}`,
-);
+const yearRangeText: ComputedRef<string> = computed((): string => yearRangeLabel(yearPage.value));
 
 const monthFmt: ComputedRef<Intl.DateTimeFormat> = computed(
-  (): Intl.DateTimeFormat => new Intl.DateTimeFormat(props.locale, { month: 'long', year: 'numeric' }),
+  (): Intl.DateTimeFormat => new Intl.DateTimeFormat(activeLocale.value, { month: 'long', year: 'numeric' }),
 );
 const valueFmt: ComputedRef<Intl.DateTimeFormat> = computed(
-  (): Intl.DateTimeFormat => new Intl.DateTimeFormat(props.locale, { day: '2-digit', month: 'short', year: 'numeric' }),
+  (): Intl.DateTimeFormat => new Intl.DateTimeFormat(activeLocale.value, { day: '2-digit', month: 'short', year: 'numeric' }),
 );
 const dayLabelFmt: ComputedRef<Intl.DateTimeFormat> = computed(
-  (): Intl.DateTimeFormat => new Intl.DateTimeFormat(props.locale, { weekday: 'long', day: 'numeric', month: 'long', year: 'numeric' }),
+  (): Intl.DateTimeFormat => new Intl.DateTimeFormat(activeLocale.value, { weekday: 'long', day: 'numeric', month: 'long', year: 'numeric' }),
 );
 const dowFmt: ComputedRef<Intl.DateTimeFormat> = computed(
-  (): Intl.DateTimeFormat => new Intl.DateTimeFormat(props.locale, { weekday: 'short' }),
+  (): Intl.DateTimeFormat => new Intl.DateTimeFormat(activeLocale.value, { weekday: 'short' }),
 );
 
-const displayValue: ComputedRef<string> = computed((): string =>
-  selectedDate.value !== null ? valueFmt.value.format(selectedDate.value) : displayPlaceholder.value,
-);
+/* Month mode shows the month through the SAME formatter the month cells and the day grid's title
+   already use, which is the whole point of the mode: <input type="month"> names the month in the
+   browser's language, this names it in the page's. */
+const displayValue: ComputedRef<string> = computed((): string => {
+  if (selectedDate.value === null) return displayPlaceholder.value;
+  const fmt: Intl.DateTimeFormat = isMonthMode.value ? formatters.value.name : valueFmt.value;
+  return fmt.format(selectedDate.value);
+});
 
 const weekdayHeaders: ComputedRef<string[]> = computed((): string[] => {
   const monday: Date = new Date(2024, 0, 1); // a known Monday
@@ -310,7 +298,7 @@ function moveFocus(next: Date): void {
 
 function openMonthGrid(): void {
   focusMonth.value = view.value.getMonth();
-  mode.value = 'months';
+  level.value = 'months';
   void nextTick((): void => focusMonthCell());
 }
 
@@ -319,6 +307,25 @@ function focusMonthCell(): void {
   cell?.focus();
 }
 
+/* What a month cell DOES, decided in one place for the click handler and the Enter key alike. In
+   day mode a month is a step on the way down; in month mode it is the answer. */
+function chooseMonth(index: number): void {
+  if (isMonthMode.value) pickMonth(index);
+  else openMonth(index);
+}
+
+function pickMonth(index: number): void {
+  const year: number = view.value.getFullYear();
+  if (monthDisabled(year, index, minDate.value, maxDate.value)) return;
+  const first: Date = new Date(year, index, 1);
+  focusMonth.value = index;
+  focusDate.value = first;
+  const iso: string = toISOMonth(first);
+  emit('update:modelValue', iso);
+  emit('change', iso);
+  closePanel(true);
+}
+
 /* Picking a month is NAVIGATION, not selection: it drops back to the day grid with the roving cell
    clamped into the new month, so nothing is committed until a day is chosen. */
 function openMonth(index: number): void {
@@ -327,13 +334,13 @@ function openMonth(index: number): void {
   const day: number = Math.min(focusDate.value.getDate(), daysInMonth);
   view.value = new Date(year, index, 1);
   focusDate.value = new Date(year, index, day);
-  mode.value = 'days';
+  level.value = 'days';
   void nextTick((): void => focusCell());
 }
 
 function openYearGrid(): void {
   focusYear.value = view.value.getFullYear();
-  mode.value = 'years';
+  level.value = 'years';
   void nextTick((): void => focusYearCell());
 }
 
@@ -347,7 +354,7 @@ function focusYearCell(): void {
 function openYear(year: number): void {
   view.value = new Date(year, view.value.getMonth(), 1);
   focusMonth.value = view.value.getMonth();
-  mode.value = 'months';
+  level.value = 'months';
   void nextTick((): void => focusMonthCell());
 }
 
@@ -358,47 +365,29 @@ function moveYearFocus(year: number): void {
 }
 
 function onYearKeydown(e: KeyboardEvent): void {
-  let handled: boolean = true;
-  switch (e.key) {
-    case 'ArrowLeft': moveYearFocus(focusYear.value - 1); break;
-    case 'ArrowRight': moveYearFocus(focusYear.value + 1); break;
-    case 'ArrowUp': moveYearFocus(focusYear.value - 3); break;
-    case 'ArrowDown': moveYearFocus(focusYear.value + 3); break;
-    case 'Home': moveYearFocus(yearPageStart(focusYear.value)); break;
-    case 'End': moveYearFocus(yearPageStart(focusYear.value) + YEARS_PER_PAGE - 1); break;
-    case 'PageUp': moveYearFocus(focusYear.value - YEARS_PER_PAGE); break;
-    case 'PageDown': moveYearFocus(focusYear.value + YEARS_PER_PAGE); break;
-    case 'Enter':
-    case ' ': openYear(focusYear.value); break;
-    case 'Escape': closePanel(true); break;
-    default: handled = false;
-  }
-  if (handled) { e.preventDefault(); e.stopPropagation(); }
+  const intent = yearKeyIntent(e.key, focusYear.value);
+  if (intent.action === 'none') return;
+  e.preventDefault();
+  e.stopPropagation();
+  if (intent.action === 'focus') moveYearFocus(intent.year);
+  else if (intent.action === 'choose') openYear(intent.year);
+  else closePanel(true);
 }
 
+/** `index` is already 0-11: the wrap lives in `monthKeyIntent`, so it is applied in one place. */
 function moveMonthFocus(index: number, yearDelta: number): void {
   if (yearDelta !== 0) view.value = addMonths(view.value, yearDelta * 12);
-  focusMonth.value = (index + 12) % 12;
+  focusMonth.value = index;
   void nextTick((): void => focusMonthCell());
 }
 
 function onMonthKeydown(e: KeyboardEvent): void {
-  let handled: boolean = true;
-  switch (e.key) {
-    case 'ArrowLeft': moveMonthFocus(focusMonth.value - 1, 0); break;
-    case 'ArrowRight': moveMonthFocus(focusMonth.value + 1, 0); break;
-    case 'ArrowUp': moveMonthFocus(focusMonth.value - 3, 0); break;
-    case 'ArrowDown': moveMonthFocus(focusMonth.value + 3, 0); break;
-    case 'Home': moveMonthFocus(0, 0); break;
-    case 'End': moveMonthFocus(11, 0); break;
-    case 'PageUp': moveMonthFocus(focusMonth.value, -1); break;
-    case 'PageDown': moveMonthFocus(focusMonth.value, 1); break;
-    case 'Enter':
-    case ' ': openMonth(focusMonth.value); break;
-    case 'Escape': closePanel(true); break;
-    default: handled = false;
-  }
-  if (handled) e.preventDefault();
+  const intent = monthKeyIntent(e.key, focusMonth.value);
+  if (intent.action === 'none') return;
+  e.preventDefault();
+  if (intent.action === 'focus') moveMonthFocus(intent.index, intent.yearDelta);
+  else if (intent.action === 'choose') chooseMonth(intent.index);
+  else closePanel(true);
 }
 
 function pick(d: Date): void {
@@ -423,7 +412,16 @@ function openPanel(): void {
   if (isDisabled.value || isReadonly.value || open.value) return;
   focusDate.value = selectedDate.value ?? focusDate.value ?? new Date();
   view.value = new Date(focusDate.value.getFullYear(), focusDate.value.getMonth(), 1);
+  /* Reopening starts at the mode's own floor. Without this a month picker that drilled to the year
+     grid and was dismissed would open on years the next time, and a keyboard user would land on a
+     grid that cannot answer. */
+  level.value = startLevel();
   open.value = true;
+  if (isMonthMode.value) {
+    focusMonth.value = view.value.getMonth();
+    void nextTick((): void => focusMonthCell());
+    return;
+  }
   void nextTick((): void => focusCell());
 }
 
@@ -563,11 +561,11 @@ onBeforeUnmount((): void => {
         <button
           type="button"
           class="fdy-cal__nav"
-          :aria-label="mode === 'years' ? prevYearsLabelText : mode === 'months' ? prevYearLabelText : prevMonthLabelText"
+          :aria-label="level === 'years' ? prevYearsLabelText : level === 'months' ? prevYearLabelText : prevMonthLabelText"
           @click="
-            mode === 'years'
-              ? moveYearFocus(focusYear - 12)
-              : mode === 'months'
+            level === 'years'
+              ? moveYearFocus(focusYear - YEARS_PER_PAGE)
+              : level === 'months'
                 ? moveMonthFocus(focusMonth, -1)
                 : (view = addMonths(view, -1))
           "
@@ -576,23 +574,23 @@ onBeforeUnmount((): void => {
           :id="titleId"
           type="button"
           class="fdy-cal__title"
-          :aria-label="mode === 'years' ? undefined : mode === 'months' ? chooseYearLabelText : chooseMonthLabelText"
-          @click="mode === 'months' ? openYearGrid() : openMonthGrid()"
-        >{{ mode === 'years' ? yearRangeLabel : mode === 'months' ? String(view.getFullYear()) : monthFmt.format(view) }}</button>
+          :aria-label="level === 'years' ? undefined : level === 'months' ? chooseYearLabelText : chooseMonthLabelText"
+          @click="level === 'months' ? openYearGrid() : openMonthGrid()"
+        >{{ level === 'years' ? yearRangeText : level === 'months' ? String(view.getFullYear()) : monthFmt.format(view) }}</button>
         <button
           type="button"
           class="fdy-cal__nav"
-          :aria-label="mode === 'years' ? nextYearsLabelText : mode === 'months' ? nextYearLabelText : nextMonthLabelText"
+          :aria-label="level === 'years' ? nextYearsLabelText : level === 'months' ? nextYearLabelText : nextMonthLabelText"
           @click="
-            mode === 'years'
-              ? moveYearFocus(focusYear + 12)
-              : mode === 'months'
+            level === 'years'
+              ? moveYearFocus(focusYear + YEARS_PER_PAGE)
+              : level === 'months'
                 ? moveMonthFocus(focusMonth, 1)
                 : (view = addMonths(view, 1))
           "
         >›</button>
       </div>
-      <div v-if="mode === 'years'" class="fdy-cal__grid fdy-cal__grid--years" role="grid" :aria-labelledby="titleId" @keydown="onYearKeydown">
+      <div v-if="level === 'years'" class="fdy-cal__grid fdy-cal__grid--years" role="grid" :aria-labelledby="titleId" @keydown="onYearKeydown">
         <button
           v-for="cell in yearCells"
           :key="cell.year"
@@ -607,7 +605,7 @@ onBeforeUnmount((): void => {
           @click="openYear(cell.year)"
         >{{ cell.year }}</button>
       </div>
-      <div v-else-if="mode === 'months'" class="fdy-cal__grid fdy-cal__grid--months" role="grid" :aria-labelledby="titleId" @keydown="onMonthKeydown">
+      <div v-else-if="level === 'months'" class="fdy-cal__grid fdy-cal__grid--months" role="grid" :aria-labelledby="titleId" @keydown="onMonthKeydown">
         <button
           v-for="cell in monthCells"
           :key="cell.index"
@@ -619,7 +617,7 @@ onBeforeUnmount((): void => {
           :aria-selected="cell.selected ? 'true' : undefined"
           :disabled="cell.disabled"
           :tabindex="cell.focusable ? 0 : -1"
-          @click="openMonth(cell.index)"
+          @click="chooseMonth(cell.index)"
         >{{ cell.label }}</button>
       </div>
       <div v-else class="fdy-cal__grid" role="grid" :aria-labelledby="titleId" @keydown="onGridKeydown">