@cahyo-dimas/freeday 3.6.0 → 3.8.0

package/adapters/vue/components/FdyDatepicker.vue

@@ -12,6 +12,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 +31,10 @@ 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`. */
+  mode?: FdyDatepickerMode;
   min?: string;
   max?: string;
   locale?: string;
@@ -68,6 +77,9 @@ function pad(n: number): string {
 function toISO(d: Date): string {
   return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
 }
+function toISOMonth(d: Date): string {
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}`;
+}
 function parseISO(s: string | null | undefined): Date | null {
   if (s === null || s === undefined || s === '') return null;
   const parts: string[] = s.split('-');
@@ -78,6 +90,29 @@ function parseISO(s: string | null | undefined): Date | null {
   const d: Date = new Date(y, m - 1, day);
   return Number.isNaN(d.getTime()) ? null : d;
 }
+/** Month mode reads BOTH shapes, and the dropped day is the point: a bound of `2026-03` lands on
+ *  March 1st, which `isMonthDisabled` then compares a whole month against correctly at either end,
+ *  so an app can pass the strings it already stores. A full date still works. */
+function parseISOMonth(s: string | null | undefined): Date | null {
+  if (s === null || s === undefined || s === '') return null;
+  const parts: string[] = s.split('-');
+  if (parts.length < 2) return null;
+  const y: number = Number(parts[0]);
+  const m: number = Number(parts[1]);
+  const day: number = parts.length > 2 ? Number(parts[2]) : 1;
+  const d: Date = new Date(y, m - 1, day);
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+/* The page's own `lang`, which is what COMPONENTS.md has promised all along and what the vanilla
+   enhancer has always done. Handing `undefined` to Intl instead falls back to the BROWSER's
+   language, so an Indonesian reader saw Indonesian month names inside a kit that is English on
+   every other path, and an Indonesian PAGE read by an English browser got English ones. That is
+   the symptom this month mode was asked for, so the fallback has to be the page. */
+function pageLocale(): string {
+  if (typeof document === 'undefined') return 'en';
+  // `||`, not `??`: an empty `lang=""` is not null and Intl throws RangeError on it.
+  return document.documentElement.getAttribute('lang') || 'en';
+}
 function startOfDay(d: Date): Date {
   return new Date(d.getFullYear(), d.getMonth(), d.getDate());
 }
@@ -113,13 +148,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,10 +189,18 @@ 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);
 
@@ -159,10 +211,10 @@ 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' }),
+  (): Intl.DateTimeFormat => new Intl.DateTimeFormat(activeLocale.value, { month: 'short' }),
 );
 const monthNameFmt: 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' }),
 );
 
 interface MonthCell {
@@ -243,21 +295,26 @@ const yearRangeLabel: ComputedRef<string> = computed(
 );
 
 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 ? monthNameFmt.value : 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 +367,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 +376,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 (isMonthDisabled(year, index)) 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 +403,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 +423,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());
 }
 
@@ -394,7 +470,7 @@ function onMonthKeydown(e: KeyboardEvent): void {
     case 'PageUp': moveMonthFocus(focusMonth.value, -1); break;
     case 'PageDown': moveMonthFocus(focusMonth.value, 1); break;
     case 'Enter':
-    case ' ': openMonth(focusMonth.value); break;
+    case ' ': chooseMonth(focusMonth.value); break;
     case 'Escape': closePanel(true); break;
     default: handled = false;
   }
@@ -423,7 +499,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 +648,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'
+            level === 'years'
               ? moveYearFocus(focusYear - 12)
-              : mode === 'months'
+              : level === 'months'
                 ? moveMonthFocus(focusMonth, -1)
                 : (view = addMonths(view, -1))
           "
@@ -576,23 +661,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' ? yearRangeLabel : 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'
+            level === 'years'
               ? moveYearFocus(focusYear + 12)
-              : mode === 'months'
+              : 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 +692,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 +704,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">

package/adapters/vue/components/FdyTableFooter.vue

@@ -25,6 +25,28 @@ const props = defineProps<{
    * holds the row you were looking at.
    */
   pageSizes?: readonly number[];
+  /* The strings, six of them, one per thing this band says. The raw path has had a hatch since
+   * 1.39.0 (`data-fdy-text-<key>` read through `textOf()`) and this path had none, so an app that
+   * does not speak English could only rewrite the whole band by hand; one shipped eighty one lines
+   * of its own markup to change five words. Names follow the enhancer's `TEXT` keys where a key
+   * exists, `info`, `prev`, `next`, so one string is not two names across the two paths. The other
+   * three have no twin because on the raw path that markup is the app's own. Defaults stay English
+   * on every path, which COMPONENTS.md promises and the suite enforces. */
+  /**
+   * The range line. `{from}`, `{to}` and `{total}` are substituted, every occurrence, as `textOf()`
+   * does. Default `Showing {from}–{to} of {total}`, the enhancer's `info`.
+   */
+  infoText?: string;
+  /** The visible word beside the rows-per-page control, which also names it. Default `Rows`. */
+  pageSizeLabel?: string;
+  /** Accessible name of the pager landmark. Default `Pagination`. */
+  paginationLabel?: string;
+  /** Accessible name of the previous-page arrow. Default `Previous page`. */
+  prevLabel?: string;
+  /** Accessible name of the next-page arrow. Default `Next page`. */
+  nextLabel?: string;
+  /** Accessible name of a numbered page button. `{n}` substituted. Default `Go to page {n}`. */
+  pageLabel?: string;
 }>();
 
 const emit = defineEmits<{ 'update:page': [page: FdyPageState] }>();
@@ -47,6 +69,13 @@ const pages: ComputedRef<Array<number | 'ellipsis'>> = computed((): Array<number
   pageWindow(currentPage1.value, totalPages.value),
 );
 
+const infoLine: ComputedRef<string> = computed((): string =>
+  (props.infoText ?? 'Showing {from}–{to} of {total}')
+    .replace(/\{from\}/g, String(rangeFrom.value))
+    .replace(/\{to\}/g, String(rangeTo.value))
+    .replace(/\{total\}/g, String(props.page.total)),
+);
+
 const hasPager: ComputedRef<boolean> = computed((): boolean => props.page.size > 0 && totalPages.value > 1);
 const sizes: ComputedRef<readonly number[]> = computed((): readonly number[] => props.pageSizes ?? []);
 /* Just the number. The control sits beside a label reading "Rows", so "20 per page" states the same
@@ -58,6 +87,10 @@ const sizeOptions: ComputedRef<Array<{ value: string; label: string }>> = comput
  * the whole band in that case, and this is where that decision now lives. */
 const visible: ComputedRef<boolean> = computed((): boolean => hasPager.value || sizes.value.length > 0);
 
+function pageAriaLabel(page1: number): string {
+  return (props.pageLabel ?? 'Go to page {n}').replace(/\{n\}/g, String(page1));
+}
+
 function goTo(page1: number): void {
   const clamped: number = Math.min(Math.max(1, page1), totalPages.value);
   emit('update:page', { index: clamped - 1, size: props.page.size, total: props.page.total });
@@ -76,10 +109,10 @@ function onSize(value: string): void {
 
 <template>
   <div v-if="visible" class="fdy-table-footer">
-    <span class="fdy-table-footer__info">Showing {{ rangeFrom }}–{{ rangeTo }} of {{ page.total }}</span>
+    <span class="fdy-table-footer__info">{{ infoLine }}</span>
 
     <div v-if="sizes.length > 0" class="fdy-table-footer__size">
-      <span :id="sizeLabelId">Rows</span>
+      <span :id="sizeLabelId">{{ pageSizeLabel ?? 'Rows' }}</span>
       <!-- The kit's own listbox, not a native <select>: an OS menu is unthemeable, and on macOS it
            drops a dark panel into a light page. FdyCombo's own header says exactly that. -->
       <FdyCombo
@@ -90,13 +123,13 @@ function onSize(value: string): void {
       />
     </div>
 
-    <nav v-if="hasPager" class="fdy-pagination" aria-label="Pagination">
+    <nav v-if="hasPager" class="fdy-pagination" :aria-label="paginationLabel ?? 'Pagination'">
       <ul class="fdy-pagination__list">
         <li>
           <button
             type="button"
             class="fdy-pagination__link"
-            aria-label="Previous page"
+            :aria-label="prevLabel ?? 'Previous page'"
             :disabled="currentPage1 === 1"
             @click="goTo(currentPage1 - 1)"
           >‹</button>
@@ -104,13 +137,13 @@ function onSize(value: string): void {
         <li v-for="(p, i) in pages" :key="typeof p === 'number' ? p : `gap-${i}`">
           <span v-if="p === 'ellipsis'" class="fdy-pagination__ellipsis">…</span>
           <span v-else-if="p === currentPage1" class="fdy-pagination__link" aria-current="page">{{ p }}</span>
-          <button v-else type="button" class="fdy-pagination__link" :aria-label="`Go to page ${p}`" @click="goTo(p)">{{ p }}</button>
+          <button v-else type="button" class="fdy-pagination__link" :aria-label="pageAriaLabel(p)" @click="goTo(p)">{{ p }}</button>
         </li>
         <li>
           <button
             type="button"
             class="fdy-pagination__link"
-            aria-label="Next page"
+            :aria-label="nextLabel ?? 'Next page'"
             :disabled="currentPage1 === totalPages"
             @click="goTo(currentPage1 + 1)"
           >›</button>

package/dist/freeday-datepicker.js

@@ -11,6 +11,8 @@
  *               <div data-fdy-datepicker data-role="to" data-placeholder="To"></div>
  *             </div>
  *    The range links the two: the end can never precede the start (out-of-range days disable).
+ *  - Month:  <div data-fdy-datepicker data-mode="month" data-value="2026-10"></div>
+ *    The calendar opens ON the month grid and stops there; the value is "YYYY-MM".
  *
  * Emits a bubbling "fdy-datepicker-change" CustomEvent on the wrapper: detail {value, date}.
  * Keyboard in the grid: ←/→ ±1 day, ↑/↓ ±1 week, Home/End week edge, PageUp/Down ±month,
@@ -39,6 +41,11 @@
   var TEXT = {
     label: 'Date',
     placeholder: 'Choose a date',
+    /* The month mode's own pair. Reusing `label` and `placeholder` would name a month field "Date"
+       and ask the reader to "Choose a date" on a control that cannot express a day, so every caller
+       would have to pass both attributes to undo a default that was simply wrong for the mode. */
+    labelMonth: 'Month',
+    placeholderMonth: 'Choose a month',
     prevMonth: 'Previous month',
     nextMonth: 'Next month',
     prevYear: 'Previous year',
@@ -69,6 +76,7 @@
   function uid(p) { uidSeq += 1; return p + '-' + uidSeq; }
   function pad(n) { return n < 10 ? '0' + n : '' + n; }
   function toISO(d) { return d.getFullYear() + '-' + pad(d.getMonth() + 1) + '-' + pad(d.getDate()); }
+  function toISOMonth(d) { return d.getFullYear() + '-' + pad(d.getMonth() + 1); }
   function parseISO(s) {
     if (!s) return null;
     var p = String(s).split('-');
@@ -76,6 +84,17 @@
     var d = new Date(Number(p[0]), Number(p[1]) - 1, Number(p[2]));
     return isNaN(d.getTime()) ? null : d;
   }
+  /* Month mode reads BOTH shapes, and the day it drops is the point: a bound of "2026-03" lands on
+     March 1st, and monthDisabled then compares a whole month against it correctly at either end,
+     so an app can pass the same strings it stores. A full date still works for a host that keeps
+     its bounds in one format across a form. */
+  function parseISOMonth(s) {
+    if (!s) return null;
+    var p = String(s).split('-');
+    if (p.length < 2) return null;
+    var d = new Date(Number(p[0]), Number(p[1]) - 1, p.length > 2 ? Number(p[2]) : 1);
+    return isNaN(d.getTime()) ? null : d;
+  }
   function startOfDay(d) { return new Date(d.getFullYear(), d.getMonth(), d.getDate()); }
   function sameDay(a, b) { return !!a && !!b && a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate(); }
   function addDays(d, n) { var x = new Date(d); x.setDate(x.getDate() + n); return x; }
@@ -102,11 +121,16 @@
     wrap.dataset.fdyDpReady = '1';
     wrap.classList.add('fdy-datepicker');
 
-    var placeholder = wrap.getAttribute('data-placeholder') || textOf(wrap, 'placeholder');
-    var label = wrap.getAttribute('data-label') || textOf(wrap, 'label');
-    var selected = parseISO(wrap.getAttribute('data-value'));
-    var minDate = parseISO(wrap.getAttribute('data-min'));
-    var maxDate = parseISO(wrap.getAttribute('data-max'));
+    /* `data-mode="month"` makes the month grid the DESTINATION rather than a waypoint: the panel
+       opens on it, Enter and a click commit from it, the day grid is never built, and the value is
+       "YYYY-MM". Anything else, including the attribute's absence, is the day picker unchanged. */
+    var monthOnly = wrap.getAttribute('data-mode') === 'month';
+    var parseVal = monthOnly ? parseISOMonth : parseISO;
+    var placeholder = wrap.getAttribute('data-placeholder') || textOf(wrap, monthOnly ? 'placeholderMonth' : 'placeholder');
+    var label = wrap.getAttribute('data-label') || textOf(wrap, monthOnly ? 'labelMonth' : 'label');
+    var selected = parseVal(wrap.getAttribute('data-value'));
+    var minDate = parseVal(wrap.getAttribute('data-min'));
+    var maxDate = parseVal(wrap.getAttribute('data-max'));
     var rangeStart = null, rangeEnd = null; // for in-range shading
     var view = startOfDay(selected || new Date());
     view = new Date(view.getFullYear(), view.getMonth(), 1);
@@ -116,7 +140,7 @@
        August 2026 to March 2022 is fifty-three of them. Shift+PageUp already jumped a year, but a
        shortcut nobody can see is not an affordance, the repo's own test helper clicked "previous
        month" twenty-four times to reach a date two years back. */
-    var mode = 'days';
+    var mode = monthOnly ? 'months' : 'days';
     var focusMonth = null;
     var focusYear = null;
 
@@ -152,7 +176,10 @@
 
     function updateDisplay() {
       if (selected) {
-        valueSpan.textContent = valueFmt.format(selected);
+        /* Through the same `Intl` formatter the month CELLS and the day grid's title already use,
+           which is the whole reason this mode exists: <input type="month"> names the month in the
+           browser's language, this names it in the page's. */
+        valueSpan.textContent = (monthOnly ? monthNameFmt : valueFmt).format(selected);
         valueSpan.classList.remove('fdy-datepicker__value--placeholder');
       } else {
         valueSpan.textContent = placeholder;
@@ -196,6 +223,10 @@
     }
 
     function render() {
+      /* The floor of the drill, stated once here rather than at every caller that could lower it:
+         in month mode there is no level below months, so the day grid is unreachable by
+         construction instead of by every path remembering not to ask for it. */
+      if (monthOnly && mode === 'days') mode = 'months';
       if (mode === 'years') { renderYears(); return; }
       if (mode === 'months') { renderMonths(); return; }
       panel.innerHTML = '';
@@ -300,7 +331,7 @@
         }
         if (monthDisabled(year, m)) btn.disabled = true;
         btn.tabIndex = m === focusMonth ? 0 : -1;
-        btn.addEventListener('click', (function (mm) { return function () { openMonth(mm); }; })(m));
+        btn.addEventListener('click', (function (mm) { return function () { chooseMonth(mm); }; })(m));
         grid.appendChild(btn);
       }
       grid.addEventListener('keydown', onMonthKey);
@@ -414,6 +445,28 @@
       if (cell) 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(m) {
+      if (monthOnly) pickMonth(m);
+      else openMonth(m);
+    }
+
+    function pickMonth(m) {
+      var year = view.getFullYear();
+      if (monthDisabled(year, m)) return;
+      selected = new Date(year, m, 1);
+      focusMonth = m;
+      focusDate = selected;
+      updateDisplay();
+      /* The same event name, so a host already listening keeps listening, and `date` is still a
+         real Date (the first of the month) rather than a second shape to parse. */
+      wrap.dispatchEvent(new CustomEvent('fdy-datepicker-change', {
+        bubbles: true, detail: { value: toISOMonth(selected), date: new Date(selected) }
+      }));
+      close(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(m) {
@@ -445,7 +498,7 @@
         case 'PageUp': moveMonthFocus(focusMonth, -1); break;
         case 'PageDown': moveMonthFocus(focusMonth, 1); break;
         case 'Enter':
-        case ' ': openMonth(focusMonth); break;
+        case ' ': chooseMonth(focusMonth); break;
         case 'Escape': close(true); break;
         default: handled = false;
       }
@@ -539,14 +592,15 @@
     function open() {
       if (stateDisabled || stateReadonly) return;
       if (!panel.hidden) return;
-      mode = 'days';
+      mode = monthOnly ? 'months' : 'days';
       focusDate = selected || focusDate || new Date();
       view = new Date(focusDate.getFullYear(), focusDate.getMonth(), 1);
+      if (monthOnly) focusMonth = view.getMonth();
       var p = popCtl(); if (p) p.show(); else panel.hidden = false;
       trigger.setAttribute('aria-expanded', 'true');
       trigger.classList.add('is-open');
       render();
-      focusFocusDate();
+      if (monthOnly) focusMonthCell(); else focusFocusDate();
       document.addEventListener('click', onDocClick, true);
     }
 
@@ -572,10 +626,10 @@
     var api = {
       wrap: wrap,
       setState: setState,
-      getValue: function () { return selected ? toISO(selected) : ''; },
+      getValue: function () { return selected ? (monthOnly ? toISOMonth(selected) : toISO(selected)) : ''; },
       clear: function () { selected = null; updateDisplay(); if (!panel.hidden) render(); },
-      setMin: function (iso) { minDate = parseISO(iso); if (!panel.hidden) render(); },
-      setMax: function (iso) { maxDate = parseISO(iso); if (!panel.hidden) render(); },
+      setMin: function (iso) { minDate = parseVal(iso); if (!panel.hidden) render(); },
+      setMax: function (iso) { maxDate = parseVal(iso); if (!panel.hidden) render(); },
       setRange: function (fromIso, toIso) {
         rangeStart = parseISO(fromIso);
         rangeEnd = parseISO(toIso);

package/dist/freeday-menu.js

@@ -36,7 +36,21 @@
       its[(index + its.length) % its.length].focus();
     }
     var _pop = null;
-    function popCtl() { if (_pop === null && window.FreedayPopover) _pop = window.FreedayPopover.attach(menu, trigger, { matchWidth: false }); return _pop; }
+    /* `.fdy-menu--end` is the kit's existing spelling for "align this menu to the right", and the
+       stylesheet has always honoured it (left:auto;right:0). The popover path replaces that with
+       inline `fixed` coordinates, so without this line the class was silently dropped the moment
+       the menu went into the top layer: an account menu in a page gutter overshot its avatar and
+       ran to 4px off the screen edge. Reported from an app that patched it with a `translate`
+       hack keyed to the kit's own GAP. */
+    function popCtl() {
+      if (_pop === null && window.FreedayPopover) {
+        _pop = window.FreedayPopover.attach(menu, trigger, {
+          matchWidth: false,
+          align: menu.classList.contains('fdy-menu--end') ? 'end' : 'start'
+        });
+      }
+      return _pop;
+    }
     function open(index) {
       var p = popCtl(); if (p) p.show(); else menu.hidden = false;
       trigger.setAttribute('aria-expanded', 'true');