npm - @cahyo-dimas/freeday - Versions diffs - 1.31.0 → 1.32.1 - Mend

@cahyo-dimas/freeday 1.31.0 → 1.32.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/CHANGELOG.md +59 -0
package/COMPONENTS.md +20 -3
package/README.id.md +1 -1
package/README.md +1 -1
package/adapters/blazor/FdyCombo.razor +1 -1
package/adapters/react/components/FdyCombo.tsx +1 -1
package/adapters/react/components/FdyDatepicker.tsx +163 -3
package/adapters/vue/components/FdyCombo.vue +1 -1
package/adapters/vue/components/FdyDatepicker.vue +152 -4
package/dist/freeday-datepicker.js +123 -4
package/dist/freeday-select.js +3 -6
package/dist/freeday.bundle.css +21 -1
package/dist/freeday.css +21 -1
package/dist/freeday.js +126 -10
package/docs/agent-onboarding.md +23 -0
package/docs/getting-started.md +1 -1
package/docs/reference-screen.html +1 -1
package/package.json +1 -1
package/src/components/combo.css +7 -0
package/src/components/datepicker.css +14 -1

package/CHANGELOG.md CHANGED Viewed

@@ -3,6 +3,65 @@
 Semua perubahan penting dicatat di sini. Format longgar mengikuti
 [Keep a Changelog](https://keepachangelog.com/); tiap versi = git tag.
+## [1.32.1] — 2026-08-18
+Docs only. Asked by a consumer: *"if I upgrade, will the agent in my project know what it gained?"*
+The answer was no, and two reasons why.
+### Fixed
+- **`docs/agent-onboarding.md` never mentioned the changelog.** It is the file a consuming agent
+  reads first, and it listed everything in the package except the one file that says what changed
+  between the version the project had and the one it now has. It now points at
+  `node_modules/@cahyo-dimas/freeday/CHANGELOG.md` explicitly, plus a short *reach for this instead
+  of hand-rolling that* table covering the last nine releases — the additions most likely to replace
+  something an app already worked around.
+- **Three classes existed only in shorthand** in `COMPONENTS.md` — `.fdy-label--required`,
+  `.fdy-cal__month` and `.fdy-cal__grid--months` were written as `(+--required)` and `__month`, so
+  the full name appeared **zero** times and a grep for the class found nothing. The drift guard
+  cannot see this either: it verifies fully-written names and skips shorthand by design, so a class
+  introduced only in shorthand is invisible to both the reader and the test.
+## [1.32.0] — 2026-08-18
+Improvement note 004, both halves: a calendar you could not steer, and a check mark that talked.
+### Added
+- **The calendar title is a control.** It was a `<div>` — the only thing naming the month, and not
+  clickable — so the only pointer route to another month was one click per month: August 2026 to
+  March 2022 is **53 clicks**. `Shift`+`PageUp` already jumped a year (APG, correct) but had no
+  affordance whatsoever; the reporting repo's own Playwright helper clicked "previous month"
+  **twenty-four times** and shipped, which is the strongest possible evidence that nobody finds a
+  shortcut nothing mentions.
+  Pressing the title now drills to a 12-cell month grid where the arrows step **years**. Same
+  journey: **7 clicks**. Picking a month is navigation, not selection — the day grid comes back with
+  the roving cell clamped into the new month and nothing is committed until a day is chosen.
+  Shipped in the vanilla enhancer, Vue and React; `FdyDateRange` composes the picker in both
+  adapters and the Blazor `FdyDatepicker` wraps the enhancer, so all of them inherit it.
+  New classes: `.fdy-cal__grid--months`, `.fdy-cal__month`. The month grid mirrors the day grid's
+  keyboard contract (arrows ±1/±3, Home/End, PageUp/PageDown a year, Enter/Space to choose), and
+  `COMPONENTS.md` now states the `Shift`+`PageUp` shortcut it never mentioned.
+### Fixed
+- **A combo option's accessible name no longer changes when it is selected.** The tick lived inside
+  `role="option"` as text, so the selected option announced `✓August` while every other announced
+  `August`: the state was read twice — once as `aria-selected`, once as decoration — and
+  `getByRole('option', { name: 'August' })` stopped matching the one option that was selected. The
+  glyph is now painted by CSS with alt text (`content:"✓" / ""`), the same technique
+  `.fdy-label--required` uses. The conditional disappears from all four stacks, and the vanilla
+  enhancer's `optionLabel` loses the sibling-walk it needed to skip a glyph.
+### Notes on the shape of the fix
+- **A bug written and caught inside this change:** swapping the calendar head with `v-if`/`v-else`
+  destroys the very button the user just pressed, focus falls to `<body>`, and the panel's own
+  `focusout` handler closes it mid-navigation. The head is now one element set whose labels and
+  handlers switch, and `focusout` ignores a **null** `relatedTarget` — focus lost because an element
+  was removed is not focus leaving the control, and a pointer that really lands outside is handled
+  by the mousedown path.
+- The report's `aria-hidden` suggestion would also have worked; CSS alt text was chosen because it
+  removes the conditional from four implementations instead of adding an attribute to each.
+### Added — guards
+- `browser/harness.mjs` gains **`axName(selector)`** — the accessible name as the *engine* computes
+  it (CDP `Accessibility.getPartialAXTree`). This mattered immediately: the first version of the
+  name invariant read `textContent`, which never contains CSS generated content, so it passed with
+  the tick back in the accessibility tree. With `axName`, that mutation reports `"✓ Badge"`.
+- Real-click drill specs for the vanilla enhancer, Vue and React: the title is a `<button>`, drilling
+  shows 12 months and moves focus into the grid, the arrows step years, and picking a month commits
+  nothing.
 ## [1.31.0] — 2026-08-18
 Improvement note 002: density was a one-way door.
 ### Added

package/COMPONENTS.md CHANGED Viewed

@@ -307,7 +307,7 @@ native control, otherwise a `<div>` + explicitly associated label.
 </fieldset>
 ```
-**`--required` marks the label, not the accessibility tree.** The control already carries
+**`.fdy-label--required` marks the label, not the accessibility tree.** The control already carries
 `required`; the asterisk is painted through `::after` with CSS alt text, so a screen reader never
 reads "star" after the label — something a `<span>` you have to remember to mark `aria-hidden`
 cannot guarantee.
@@ -403,12 +403,18 @@ Fully styleable dropdown, APG combobox+listbox. Needs `freeday-select.js`.
     </button>
     <ul class="fdy-combo__listbox" role="listbox" aria-labelledby="st-l" hidden>
       <li class="fdy-combo__option" role="option" data-value="paid" aria-selected="false"><span class="fdy-combo__check"></span>Paid</li>
-      <li class="fdy-combo__option" role="option" data-value="pending" aria-selected="true"><span class="fdy-combo__check">✓</span>Pending</li>
+      <li class="fdy-combo__option" role="option" data-value="pending" aria-selected="true"><span class="fdy-combo__check"></span>Pending</li>
     </ul>
   </div>
 </div>
 ```
+**The selected tick is CSS.** `.fdy-combo__check` is an empty box in the markup; the glyph is painted
+by the stylesheet on `[aria-selected="true"]` with alt text, so it never enters the accessibility
+tree. That keeps an option's accessible name **identical whether or not it is selected** — the state
+is carried by `aria-selected` alone, announced once, and `getByRole('option', { name: 'August' })`
+keeps matching after selection. Do not put a glyph in that span.
 ## Autocomplete — `.fdy-autocomplete`
 > **Typed wrapper: `<FdyAutocomplete>`** — Vue (`v-model`) · React (`value`/`onChange`) · Blazor (`@bind-Value`). In those stacks use the wrapper; the markup below is for stacks without an adapter (and is what the wrapper renders).
@@ -505,10 +511,21 @@ Input-styled trigger + calendar popover. Needs `freeday-datepicker.js`. **Author
 — the enhancer builds everything.
 - `.fdy-datepicker` (+`--error`) · `__trigger` `__value` (+`--placeholder`) `__icon` `__clear`
-  `__panel`; calendar internals `.fdy-cal__head` `__nav` `__title` `__grid` `__dow` `__day`
+  `__panel`; calendar internals `.fdy-cal__head` `__nav` `__title` `__grid` (+`--months`) `__dow`
+  `__day` `__month`
 - Range: wrap two pickers in `.fdy-daterange` + `data-fdy-daterange` (`role="group"`), children
   get `data-role="from"` / `"to"`; separator `.fdy-daterange__sep`. The end can't precede the start.
   **Typed wrapper: `<FdyDateRange>`** (Vue/React/Blazor) — use it in those stacks.
+**Getting to a distant month.** The title is a **button**: press it and the day grid becomes a
+12-cell month grid (`.fdy-cal__grid--months` of `.fdy-cal__month`) for the current year, where the
+arrows step **years** instead of months. Pick a
+month and you are back on days — choosing a month is navigation, so nothing is committed until a day
+is selected. From August 2026 to March 2022 that is 7 clicks; walking month by month is 53.
+Keyboard, in the day grid: arrows move a day, `Home`/`End` the week, `PageUp`/`PageDown` a month,
+and **`Shift`+`PageUp`/`PageDown` a year** (WAI-ARIA APG). The month grid mirrors it: arrows ±1/±3
+months, `Home`/`End` January/December, `PageUp`/`PageDown` a year, `Enter`/`Space` to choose.
 - Attributes: `data-value="YYYY-MM-DD"`, `data-placeholder`, `data-label`, `data-fdy-no-icon`
 ```html

package/README.id.md CHANGED Viewed

@@ -5,7 +5,7 @@
 > **Lebih banyak _free day_ buat dev — UI kit-nya sudah siap pakai.**
 [![Live docs](https://img.shields.io/badge/docs-live-2050d8?style=flat-square)](https://cahyo-dimas.github.io/freeday-ui-kit/)
-[![Release](https://img.shields.io/badge/release-v1.31.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.31.0)
+[![Release](https://img.shields.io/badge/release-v1.32.1-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.32.1)
 UI KIT yang token-driven & framework-agnostic — satu sumber kebenaran untuk warna, tipografi,
 spasi, dan komponen. Blueprint: `docs/superpowers/specs/2026-07-21-freeday-ui-kit-design.md`.

package/README.md CHANGED Viewed

@@ -5,7 +5,7 @@
 > **More free days for devs — the UI kit is ready to use.**
 [![Live docs](https://img.shields.io/badge/docs-live-2050d8?style=flat-square)](https://cahyo-dimas.github.io/freeday-ui-kit/)
-[![Release](https://img.shields.io/badge/release-v1.31.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.31.0)
+[![Release](https://img.shields.io/badge/release-v1.32.1-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.32.1)
 A token-driven, framework-agnostic UI kit — one source of truth for color, typography,
 spacing, and components. Blueprint: `docs/superpowers/specs/2026-07-21-freeday-ui-kit-design.md`.

package/adapters/blazor/FdyCombo.razor CHANGED Viewed

@@ -21,7 +21,7 @@
             bool selected = Equals(opt.Value, Value);
             <li class="fdy-combo__option" role="option" data-value="@KeyOf(opt.Value)"
                 aria-selected="@(selected ? "true" : "false")">
-                <span class="fdy-combo__check">@(selected ? "✓" : "")</span>@opt.Label
+                <span class="fdy-combo__check"></span>@opt.Label
             </li>
         }
     </ul>

package/adapters/react/components/FdyCombo.tsx CHANGED Viewed

@@ -165,7 +165,7 @@ export function FdyCombo<T extends string>(props: FdyComboProps<T>): JSX.Element
             onClick={(): void => choose(i)}
             onMouseMove={(): void => setHighlight(i)}
           >
-            <span className="fdy-combo__check">{opt.value === props.value ? '✓' : ''}</span>{opt.label}
+            <span className="fdy-combo__check" />{opt.label}
           </li>
         ))}
       </ul>

package/adapters/react/components/FdyDatepicker.tsx CHANGED Viewed

@@ -21,6 +21,16 @@ interface DayCell {
   focusable: boolean;
 }
+interface MonthCell {
+  index: number;
+  label: string;
+  ariaLabel: string;
+  selected: boolean;
+  today: boolean;
+  disabled: boolean;
+  focusable: boolean;
+}
 export interface FdyDatepickerProps {
   value: string | null;
   onChange: (value: string) => void;
@@ -38,6 +48,11 @@ export interface FdyDatepickerProps {
   /** Show a clear (×) button in the trigger when a date is set, so an optional date can be unset. Calls onChange('') to reset. Off by default. */
   clearable?: boolean;
   /** aria-label for the previous-month nav button. Default 'Previous month' — override for non-English UIs (month/weekday names already follow `locale`). */
+  /** aria-label for the title button that drills to the month grid. Default 'Choose month'. */
+  chooseMonthLabel?: string;
+  /** aria-labels for the year arrows shown in the month grid. Defaults 'Previous year' / 'Next year'. */
+  prevYearLabel?: string;
+  nextYearLabel?: string;
   prevMonthLabel?: string;
   /** aria-label for the next-month nav button. Default 'Next month'. */
   nextMonthLabel?: string;
@@ -104,6 +119,12 @@ export function FdyDatepicker(props: FdyDatepickerProps): JSX.Element {
   const pendingFocusRef = useRef<string | null>(null);
   const [open, setOpen] = useState<boolean>(false);
+  /* '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. */
+  const [mode, setMode] = useState<'days' | 'months'>('days');
+  const [focusMonth, setFocusMonth] = useState<number>(0);
+  const monthRefs = useRef<Record<number, HTMLButtonElement | null>>({});
+  const pendingMonthFocusRef = useRef<number | null>(null);
   // Render the calendar panel in the top layer (popover) so it never gets clipped by a card or
   // scroll container; positions against the trigger.
@@ -122,6 +143,17 @@ export function FdyDatepicker(props: FdyDatepickerProps): JSX.Element {
   const isInvalid: boolean = props.invalid === true;
   const displayPlaceholder: string = props.placeholder ?? 'Select date';
   const showClear: boolean = props.clearable === true && selectedDate !== null && !isDisabled && !isReadonly;
+  const chooseMonthLabelText: string = props.chooseMonthLabel ?? 'Choose month';
+  const prevYearLabelText: string = props.prevYearLabel ?? 'Previous year';
+  const nextYearLabelText: string = props.nextYearLabel ?? 'Next year';
+  const monthCellFmt: Intl.DateTimeFormat = useMemo(
+    (): Intl.DateTimeFormat => new Intl.DateTimeFormat(props.locale, { month: 'short' }),
+    [props.locale],
+  );
+  const monthNameFmt: Intl.DateTimeFormat = useMemo(
+    (): Intl.DateTimeFormat => new Intl.DateTimeFormat(props.locale, { month: 'long', year: 'numeric' }),
+    [props.locale],
+  );
   const prevMonthLabelText: string = props.prevMonthLabel ?? 'Previous month';
   const nextMonthLabelText: string = props.nextMonthLabel ?? 'Next month';
   const clearLabelText: string = props.clearLabel ?? 'Clear date';
@@ -167,6 +199,35 @@ export function FdyDatepicker(props: FdyDatepickerProps): JSX.Element {
     return false;
   }
+  /** A month is only unreachable when the WHOLE month falls outside min/max — 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 !== null && startOfDay(last).getTime() < startOfDay(minDate).getTime()) return true;
+    if (maxDate !== null && startOfDay(first).getTime() > startOfDay(maxDate).getTime()) return true;
+    return false;
+  }
+  const monthCells: MonthCell[] = useMemo((): MonthCell[] => {
+    const year: number = viewMonth.getFullYear();
+    const today: Date = new Date();
+    const sel: Date | null = parseISO(props.value);
+    return Array.from({ length: 12 }, (_unused: unknown, index: number): MonthCell => {
+      const cellDate: Date = new Date(year, index, 1);
+      return {
+        index,
+        label: monthCellFmt.format(cellDate),
+        ariaLabel: monthNameFmt.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,
+      };
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [viewMonth, props.value, focusMonth, monthCellFmt, monthNameFmt, minDate, maxDate]);
   const gridCells: DayCell[] = useMemo((): DayCell[] => {
     const first: Date = new Date(viewMonth.getFullYear(), viewMonth.getMonth(), 1);
     const offset: number = (first.getDay() + 6) % 7; // Monday-first
@@ -203,6 +264,57 @@ export function FdyDatepicker(props: FdyDatepickerProps): JSX.Element {
     dayRefs.current[iso]?.focus();
   });
+  useEffect((): void => {
+    if (pendingMonthFocusRef.current === null) return;
+    const index: number = pendingMonthFocusRef.current;
+    pendingMonthFocusRef.current = null;
+    monthRefs.current[index]?.focus();
+  });
+  function openMonthGrid(): void {
+    setFocusMonth(viewMonth.getMonth());
+    setMode('months');
+    pendingMonthFocusRef.current = viewMonth.getMonth();
+  }
+  /* Picking a month is NAVIGATION, not selection: 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 {
+    const year: number = viewMonth.getFullYear();
+    const daysInMonth: number = new Date(year, index + 1, 0).getDate();
+    const next: Date = new Date(year, index, Math.min(focusDate.getDate(), daysInMonth));
+    setViewMonth(new Date(year, index, 1));
+    setFocusDate(next);
+    setMode('days');
+    pendingFocusRef.current = toISO(next);
+  }
+  function moveMonthFocus(index: number, yearDelta: number): void {
+    if (yearDelta !== 0) setViewMonth(addMonths(viewMonth, yearDelta * 12));
+    const next: number = (index + 12) % 12;
+    setFocusMonth(next);
+    pendingMonthFocusRef.current = next;
+  }
+  function onMonthKeydown(e: React.KeyboardEvent): void {
+    let handled: boolean = true;
+    switch (e.key) {
+      case 'ArrowLeft': moveMonthFocus(focusMonth - 1, 0); break;
+      case 'ArrowRight': moveMonthFocus(focusMonth + 1, 0); break;
+      case 'ArrowUp': moveMonthFocus(focusMonth - 3, 0); break;
+      case 'ArrowDown': moveMonthFocus(focusMonth + 3, 0); break;
+      case 'Home': moveMonthFocus(0, 0); break;
+      case 'End': moveMonthFocus(11, 0); break;
+      case 'PageUp': moveMonthFocus(focusMonth, -1); break;
+      case 'PageDown': moveMonthFocus(focusMonth, 1); break;
+      case 'Enter':
+      case ' ': openMonth(focusMonth); break;
+      case 'Escape': closePanel(true); break;
+      default: handled = false;
+    }
+    if (handled) e.preventDefault();
+  }
   function moveFocus(next: Date): void {
     setFocusDate(next);
     setViewMonth(new Date(next.getFullYear(), next.getMonth(), 1));
@@ -295,8 +407,14 @@ export function FdyDatepicker(props: FdyDatepickerProps): JSX.Element {
   }
   // Close when focus leaves the control entirely (e.g. Shift+Tab off the trigger).
+  /* A null relatedTarget means focus fell to <body> — which is what happens when the element the
+     user just pressed is REMOVED by the click it triggered (drilling into the month grid replaces
+     the grid, and with it the cell that had focus). That is not focus leaving the control, and
+     closing on it made the panel vanish mid-navigation. A pointer that really lands outside is
+     handled by the mousedown listener, which is the reliable path for that case. */
   const onFocusout = (e: React.FocusEvent<HTMLDivElement>): void => {
     const next: EventTarget | null = e.relatedTarget;
+    if (next === null) return;
     if (rootRef.current !== null && !(next instanceof Node && rootRef.current.contains(next))) closePanel(false);
   };
@@ -352,15 +470,55 @@ export function FdyDatepicker(props: FdyDatepickerProps): JSX.Element {
       ) : null}
       <div ref={panelRef} className="fdy-datepicker__panel" role="dialog" aria-modal="false" aria-labelledby={titleId} hidden={!open}>
+        {/* ONE head for both modes on purpose: swapping it destroys the very button the user just
+            pressed, focus falls to <body>, and the panel's own focusout handler closes it. */}
         <div className="fdy-cal__head">
-          <button type="button" className="fdy-cal__nav" aria-label={prevMonthLabelText} onClick={(): void => setViewMonth(addMonths(viewMonth, -1))}>
+          <button
+            type="button"
+            className="fdy-cal__nav"
+            aria-label={mode === 'months' ? prevYearLabelText : prevMonthLabelText}
+            onClick={(): void => { if (mode === 'months') moveMonthFocus(focusMonth, -1); else setViewMonth(addMonths(viewMonth, -1)); }}
+          >
             &lsaquo;
           </button>
-          <div id={titleId} className="fdy-cal__title">{monthFmt.format(viewMonth)}</div>
-          <button type="button" className="fdy-cal__nav" aria-label={nextMonthLabelText} onClick={(): void => setViewMonth(addMonths(viewMonth, 1))}>
+          <button
+            id={titleId}
+            type="button"
+            className="fdy-cal__title"
+            aria-label={mode === 'months' ? undefined : chooseMonthLabelText}
+            onClick={(): void => { if (mode === 'months') setMode('days'); else openMonthGrid(); }}
+          >
+            {mode === 'months' ? String(viewMonth.getFullYear()) : monthFmt.format(viewMonth)}
+          </button>
+          <button
+            type="button"
+            className="fdy-cal__nav"
+            aria-label={mode === 'months' ? nextYearLabelText : nextMonthLabelText}
+            onClick={(): void => { if (mode === 'months') moveMonthFocus(focusMonth, 1); else setViewMonth(addMonths(viewMonth, 1)); }}
+          >
             &rsaquo;
           </button>
         </div>
+        {mode === 'months' ? (
+          <div className="fdy-cal__grid fdy-cal__grid--months" role="grid" aria-labelledby={titleId} onKeyDown={onMonthKeydown}>
+            {monthCells.map((cell: MonthCell) => (
+              <button
+                key={cell.index}
+                ref={(el: HTMLButtonElement | null): void => { monthRefs.current[cell.index] = el; }}
+                type="button"
+                className={['fdy-cal__month', cell.today ? 'is-today' : '', cell.selected ? 'is-selected' : ''].filter(Boolean).join(' ')}
+                role="gridcell"
+                aria-label={cell.ariaLabel}
+                aria-selected={cell.selected ? true : undefined}
+                disabled={cell.disabled}
+                tabIndex={cell.focusable ? 0 : -1}
+                onClick={(): void => openMonth(cell.index)}
+              >
+                {cell.label}
+              </button>
+            ))}
+          </div>
+        ) : (
         <div className="fdy-cal__grid" role="grid" aria-labelledby={titleId} onKeyDown={onGridKeydown}>
           {weekdayHeaders.map((w: string): JSX.Element => (
             <div key={w} className="fdy-cal__dow" role="columnheader" aria-label={w}>{w}</div>
@@ -384,6 +542,8 @@ export function FdyDatepicker(props: FdyDatepickerProps): JSX.Element {
             </button>
           ))}
         </div>
+        )}
       </div>
     </div>
   );

package/adapters/vue/components/FdyCombo.vue CHANGED Viewed

@@ -233,7 +233,7 @@ onBeforeUnmount((): void => {
         @click="choose(i)"
         @mousemove="setHighlight(i)"
       >
-        <span class="fdy-combo__check">{{ opt.value === modelValue ? '✓' : '' }}</span>{{ opt.label }}
+        <span class="fdy-combo__check"></span>{{ opt.label }}
       </li>
     </ul>
   </div>

package/adapters/vue/components/FdyDatepicker.vue CHANGED Viewed

@@ -45,6 +45,11 @@ const props = defineProps<{
   nextMonthLabel?: string;
   /** aria-label for the clear button (when `clearable`). Default 'Clear date'. */
   clearLabel?: string;
+  /** aria-label for the title button that drills to the month grid. Default 'Choose month'. */
+  chooseMonthLabel?: string;
+  /** aria-labels for the year arrows shown in the month grid. Defaults 'Previous year' / 'Next year'. */
+  prevYearLabel?: string;
+  nextYearLabel?: string;
 }>();
 const emit = defineEmits<{
@@ -116,6 +121,9 @@ const showClear: ComputedRef<boolean> = computed(
 const prevMonthLabelText: ComputedRef<string> = computed((): string => props.prevMonthLabel ?? 'Previous month');
 const nextMonthLabelText: ComputedRef<string> = computed((): string => props.nextMonthLabel ?? 'Next month');
 const clearLabelText: ComputedRef<string> = computed((): string => props.clearLabel ?? 'Clear date');
+const chooseMonthLabelText: ComputedRef<string> = computed((): string => props.chooseMonthLabel ?? 'Choose month');
+const prevYearLabelText: ComputedRef<string> = computed((): string => props.prevYearLabel ?? 'Previous year');
+const nextYearLabelText: ComputedRef<string> = computed((): string => props.nextYearLabel ?? 'Next year');
 const view: Ref<Date> = ref(startOfMonth(selectedDate.value ?? new Date()));
 const focusDate: Ref<Date> = ref(selectedDate.value ?? new Date());
@@ -129,6 +137,58 @@ 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'> = ref('days');
+const focusMonth: Ref<number> = ref(0);
+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' }),
+);
+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,
+    };
+  });
+});
 const monthFmt: ComputedRef<Intl.DateTimeFormat> = computed(
   (): Intl.DateTimeFormat => new Intl.DateTimeFormat(props.locale, { month: 'long', year: 'numeric' }),
 );
@@ -195,6 +255,54 @@ function moveFocus(next: Date): void {
   void nextTick((): void => focusCell());
 }
+function openMonthGrid(): void {
+  focusMonth.value = view.value.getMonth();
+  mode.value = 'months';
+  void nextTick((): void => focusMonthCell());
+}
+function focusMonthCell(): void {
+  const cell: HTMLElement | null = panelEl.value?.querySelector('.fdy-cal__month[tabindex="0"]') ?? null;
+  cell?.focus();
+}
+/* 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 {
+  const year: number = view.value.getFullYear();
+  const daysInMonth: number = new Date(year, index + 1, 0).getDate();
+  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';
+  void nextTick((): void => focusCell());
+}
+function moveMonthFocus(index: number, yearDelta: number): void {
+  if (yearDelta !== 0) view.value = addMonths(view.value, yearDelta * 12);
+  focusMonth.value = (index + 12) % 12;
+  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();
+}
 function pick(d: Date): void {
   if (isDayDisabled(d)) return;
   const day: Date = startOfDay(d);
@@ -290,8 +398,14 @@ function onDocPointerDown(e: MouseEvent): void {
 }
 // Close when focus leaves the control entirely (e.g. Shift+Tab off the trigger).
+/* A null relatedTarget means focus fell to <body> — which is what happens when the element the
+ * user just pressed is REMOVED by the click it triggered (drilling into the month grid replaces
+ * the grid, and with it the cell that had focus). That is not focus leaving the control, and
+ * closing on it made the panel vanish mid-navigation. A pointer that really lands outside is
+ * handled by the mousedown listener, which is the reliable path for that case. */
 function onFocusout(e: FocusEvent): void {
   const next: EventTarget | null = e.relatedTarget;
+  if (next === null) return;
   if (rootEl.value !== null && !(next instanceof Node && rootEl.value.contains(next))) {
     closePanel(false);
   }
@@ -344,12 +458,46 @@ onBeforeUnmount((): void => {
     </button>
     <div ref="panelEl" class="fdy-datepicker__panel" role="dialog" aria-modal="false" popover="manual" :aria-labelledby="titleId" :hidden="!open">
+      <!-- ONE head for both modes on purpose: swapping it with v-if destroys the very button the user
+           just pressed, focus falls to <body>, and the panel's own focusout handler closes it. The
+           labels and handlers switch; the elements do not. -->
       <div class="fdy-cal__head">
-        <button type="button" class="fdy-cal__nav" :aria-label="prevMonthLabelText" @click="view = addMonths(view, -1)">‹</button>
-        <div :id="titleId" class="fdy-cal__title">{{ monthFmt.format(view) }}</div>
-        <button type="button" class="fdy-cal__nav" :aria-label="nextMonthLabelText" @click="view = addMonths(view, 1)">›</button>
+        <button
+          type="button"
+          class="fdy-cal__nav"
+          :aria-label="mode === 'months' ? prevYearLabelText : prevMonthLabelText"
+          @click="mode === 'months' ? moveMonthFocus(focusMonth, -1) : (view = addMonths(view, -1))"
+        >‹</button>
+        <button
+          :id="titleId"
+          type="button"
+          class="fdy-cal__title"
+          :aria-label="mode === 'months' ? undefined : chooseMonthLabelText"
+          @click="mode === 'months' ? (mode = 'days') : openMonthGrid()"
+        >{{ mode === 'months' ? String(view.getFullYear()) : monthFmt.format(view) }}</button>
+        <button
+          type="button"
+          class="fdy-cal__nav"
+          :aria-label="mode === 'months' ? nextYearLabelText : nextMonthLabelText"
+          @click="mode === 'months' ? moveMonthFocus(focusMonth, 1) : (view = addMonths(view, 1))"
+        >›</button>
+      </div>
+      <div v-if="mode === '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"
+          type="button"
+          class="fdy-cal__month"
+          :class="{ 'is-today': cell.today, 'is-selected': cell.selected }"
+          role="gridcell"
+          :aria-label="cell.ariaLabel"
+          :aria-selected="cell.selected ? 'true' : undefined"
+          :disabled="cell.disabled"
+          :tabindex="cell.focusable ? 0 : -1"
+          @click="openMonth(cell.index)"
+        >{{ cell.label }}</button>
       </div>
-      <div class="fdy-cal__grid" role="grid" :aria-labelledby="titleId" @keydown="onGridKeydown">
+      <div v-else class="fdy-cal__grid" role="grid" :aria-labelledby="titleId" @keydown="onGridKeydown">
         <div v-for="w in weekdayHeaders" :key="w" class="fdy-cal__dow" role="columnheader" :aria-label="w">{{ w }}</div>
         <button
           v-for="cell in gridCells"

package/dist/freeday-datepicker.js CHANGED Viewed

@@ -39,6 +39,8 @@
   var monthFmt = new Intl.DateTimeFormat(LOCALE, { month: 'long', year: 'numeric' });
   var valueFmt = new Intl.DateTimeFormat(LOCALE, { day: '2-digit', month: 'short', year: 'numeric' });
   var dayLabelFmt = new Intl.DateTimeFormat(LOCALE, { weekday: 'long', day: 'numeric', month: 'long', year: 'numeric' });
+  var monthCellFmt = new Intl.DateTimeFormat(LOCALE, { month: 'short' });
+  var monthNameFmt = new Intl.DateTimeFormat(LOCALE, { month: 'long', year: 'numeric' });
   function weekdayHeaders() {
     var monday = new Date(2024, 0, 1); // a known Monday
@@ -64,6 +66,13 @@
     var view = startOfDay(selected || new Date());
     view = new Date(view.getFullYear(), view.getMonth(), 1);
     var focusDate = null;
+    /* 'days' | 'months' — the calendar drills one level up rather than growing furniture beside the
+       title. Before this, the only pointer route to another month was one click per month: from
+       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 focusMonth = null;
     var trigger = document.createElement('button');
     trigger.type = 'button';
@@ -111,6 +120,25 @@
       return false;
     }
+    function monthDisabled(year, month) {
+      var last = new Date(year, month + 1, 0);
+      var first = new Date(year, month, 1);
+      if (minDate && startOfDay(last).getTime() < startOfDay(minDate).getTime()) return true;
+      if (maxDate && startOfDay(first).getTime() > startOfDay(maxDate).getTime()) return true;
+      return false;
+    }
+    function titleButton(text, aria, onClick) {
+      var b = document.createElement('button');
+      b.type = 'button';
+      b.className = 'fdy-cal__title';
+      b.id = uid('fdy-cal-title');
+      b.textContent = text;
+      b.setAttribute('aria-label', aria);
+      b.addEventListener('click', onClick);
+      return b;
+    }
     function navButton(glyph, aria, onClick) {
       var b = document.createElement('button');
       b.type = 'button';
@@ -122,13 +150,16 @@
     }
     function render() {
+      if (mode === 'months') { renderMonths(); return; }
       panel.innerHTML = '';
       var head = document.createElement('div');
       head.className = 'fdy-cal__head';
-      var title = document.createElement('div');
-      title.className = 'fdy-cal__title';
-      title.id = uid('fdy-cal-title');
-      title.textContent = monthFmt.format(view);
+      var title = titleButton(monthFmt.format(view), monthFmt.format(view) + ', pilih bulan', function () {
+        mode = 'months';
+        focusMonth = view.getMonth();
+        render();
+        focusMonthCell();
+      });
       panel.setAttribute('aria-labelledby', title.id);
       head.appendChild(navButton('‹', 'Bulan sebelumnya', function () { view = addMonths(view, -1); render(); }));
       head.appendChild(title);
@@ -184,6 +215,93 @@
       panel.appendChild(grid);
     }
+    function renderMonths() {
+      panel.innerHTML = '';
+      var year = view.getFullYear();
+      var head = document.createElement('div');
+      head.className = 'fdy-cal__head';
+      var title = titleButton(String(year), year + ', kembali ke tanggal', function () {
+        mode = 'days';
+        render();
+        focusFocusDate();
+      });
+      panel.setAttribute('aria-labelledby', title.id);
+      head.appendChild(navButton('‹', 'Tahun sebelumnya', function () { view = addMonths(view, -12); render(); focusMonthCell(); }));
+      head.appendChild(title);
+      head.appendChild(navButton('›', 'Tahun berikutnya', function () { view = addMonths(view, 12); render(); focusMonthCell(); }));
+      panel.appendChild(head);
+      var grid = document.createElement('div');
+      grid.className = 'fdy-cal__grid fdy-cal__grid--months';
+      grid.setAttribute('role', 'grid');
+      grid.setAttribute('aria-labelledby', title.id);
+      var today = new Date();
+      if (focusMonth === null) focusMonth = view.getMonth();
+      for (var m = 0; m < 12; m++) {
+        var cellDate = new Date(year, m, 1);
+        var btn = document.createElement('button');
+        btn.type = 'button';
+        btn.className = 'fdy-cal__month';
+        btn.setAttribute('role', 'gridcell');
+        btn.setAttribute('aria-label', monthNameFmt.format(cellDate));
+        btn.textContent = monthCellFmt.format(cellDate);
+        if (today.getFullYear() === year && today.getMonth() === m) btn.classList.add('is-today');
+        if (selected && selected.getFullYear() === year && selected.getMonth() === m) {
+          btn.classList.add('is-selected');
+          btn.setAttribute('aria-selected', 'true');
+        }
+        if (monthDisabled(year, m)) btn.disabled = true;
+        btn.tabIndex = m === focusMonth ? 0 : -1;
+        btn.addEventListener('click', (function (mm) { return function () { openMonth(mm); }; })(m));
+        grid.appendChild(btn);
+      }
+      grid.addEventListener('keydown', onMonthKey);
+      panel.appendChild(grid);
+    }
+    function focusMonthCell() {
+      var cell = panel.querySelector('.fdy-cal__month[tabindex="0"]');
+      if (cell) cell.focus();
+    }
+    /* 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) {
+      var dim = new Date(view.getFullYear(), m + 1, 0).getDate();
+      var day = focusDate ? Math.min(focusDate.getDate(), dim) : 1;
+      view = new Date(view.getFullYear(), m, 1);
+      focusDate = new Date(view.getFullYear(), m, day);
+      mode = 'days';
+      render();
+      focusFocusDate();
+    }
+    function moveMonthFocus(index, yearDelta) {
+      if (yearDelta) view = addMonths(view, yearDelta * 12);
+      focusMonth = (index + 12) % 12;
+      render();
+      focusMonthCell();
+    }
+    function onMonthKey(e) {
+      var handled = true;
+      switch (e.key) {
+        case 'ArrowLeft': moveMonthFocus(focusMonth - 1, 0); break;
+        case 'ArrowRight': moveMonthFocus(focusMonth + 1, 0); break;
+        case 'ArrowUp': moveMonthFocus(focusMonth - 3, 0); break;
+        case 'ArrowDown': moveMonthFocus(focusMonth + 3, 0); break;
+        case 'Home': moveMonthFocus(0, 0); break;
+        case 'End': moveMonthFocus(11, 0); break;
+        case 'PageUp': moveMonthFocus(focusMonth, -1); break;
+        case 'PageDown': moveMonthFocus(focusMonth, 1); break;
+        case 'Enter':
+        case ' ': openMonth(focusMonth); break;
+        case 'Escape': close(true); break;
+        default: handled = false;
+      }
+      if (handled) e.preventDefault();
+    }
     function focusFocusDate() {
       var cell = panel.querySelector('.fdy-cal__day[tabindex="0"]');
       if (cell) cell.focus();
@@ -232,6 +350,7 @@
     function popCtl() { if (_pop === null && window.FreedayPopover) _pop = window.FreedayPopover.attach(panel, trigger); return _pop; }
     function open() {
       if (!panel.hidden) return;
+      mode = 'days';
       focusDate = selected || focusDate || new Date();
       view = new Date(focusDate.getFullYear(), focusDate.getMonth(), 1);
       var p = popCtl(); if (p) p.show(); else panel.hidden = false;

package/dist/freeday-select.js CHANGED Viewed

@@ -13,7 +13,7 @@
  *     </button>
  *     <ul class="fdy-combo__listbox" role="listbox" hidden>
  *       <li class="fdy-combo__option" role="option" data-value="x"
- *           aria-selected="true"><span class="fdy-combo__check">✓</span>Label</li>
+ *           aria-selected="true"><span class="fdy-combo__check"></span>Label</li>
  *     </ul>
  *   </div>
  *
@@ -25,10 +25,9 @@
   var seq = 0;
   var openClose = null; // close() of the currently-open combo, or null
+  /* The tick lives in CSS now, so the option's text IS its label — no sibling walk to skip a glyph. */
   function optionLabel(opt) {
-    var check = opt.querySelector('.fdy-combo__check');
-    var node = check && check.nextSibling ? check.nextSibling.textContent : opt.textContent;
-    return (node || '').trim();
+    return (opt.textContent || '').trim();
   }
   function initCombo(root) {
@@ -99,8 +98,6 @@
       options.forEach(function (other) {
         var on = other === opt;
         other.setAttribute('aria-selected', on ? 'true' : 'false');
-        var check = other.querySelector('.fdy-combo__check');
-        if (check) check.textContent = on ? '✓' : '';
       });
       root.setAttribute('data-value', opt.getAttribute('data-value') || '');
       valueEl.textContent = optionLabel(opt);

package/dist/freeday.bundle.css CHANGED Viewed

@@ -1010,7 +1010,14 @@ a { color: var(--color-primary); }
 .fdy-combo__option.is-highlighted{background:var(--color-surface-3);}
 .fdy-combo__option[aria-selected="true"]{background:var(--color-primary-soft);color:var(--color-primary-strong);font-weight:var(--weight-semibold);}
 .fdy-combo__option.is-highlighted[aria-selected="true"]{box-shadow:inset 0 0 0 2px color-mix(in srgb,var(--color-primary) 55%,transparent);}
+/* The tick is CSS, not content (#004 §2). Inside role="option" it joined the option's ACCESSIBLE
+   NAME, so the selected option announced "✓August" while every other announced "August": the state
+   was read twice — once as aria-selected, once as decoration — and a test asking for an option by
+   its own label stopped matching the one that was selected. The `/ ""` is alt text: the glyph is
+   painted, the accessibility tree gets nothing. Same reasoning as .fdy-label--required (1.29.0).
+   The empty box still reserves its width, so labels stay aligned whether selected or not. */
 .fdy-combo__check{display:inline-flex;justify-content:center;width:var(--space-4);flex:none;font-weight:var(--weight-bold);color:var(--color-primary);}
+.fdy-combo__option[aria-selected="true"] .fdy-combo__check::after{content:"✓" / "";}
 @media (prefers-reduced-motion:no-preference){.fdy-combo__listbox:not([hidden]){animation:fdy-combo-in var(--dur-fast) var(--ease-standard);}}
 @keyframes fdy-combo-in{from{opacity:0;transform:translateY(-4px);}to{opacity:1;transform:none;}}
@@ -1114,7 +1121,20 @@ a { color: var(--color-primary); }
 /* Calendar grid */
 .fdy-cal__head{display:flex;align-items:center;gap:var(--space-2);margin-bottom:var(--space-2);}
-.fdy-cal__title{flex:1;text-align:center;font-weight:var(--weight-semibold);font-size:var(--text-sm);color:var(--color-text);text-transform:capitalize;}
+/* The title is a CONTROL now (#004 §1): it drills to the month grid, so it needs the UA button box
+   reset and the same hover/focus treatment as the arrows beside it. */
+.fdy-cal__title{flex:1;appearance:none;border:0;background:transparent;padding:var(--space-1) var(--space-2);border-radius:var(--radius-sm);text-align:center;font-family:inherit;font-weight:var(--weight-semibold);font-size:var(--text-sm);color:var(--color-text);text-transform:capitalize;cursor:pointer;}
+.fdy-cal__title:hover{background:var(--color-surface-2);}
+.fdy-cal__title:focus-visible{outline:none;box-shadow:0 0 0 3px color-mix(in srgb,var(--color-primary) 26%,transparent);}
+/* Month grid — 3×4 over the same track width as the 7-column day grid, so the panel does not resize
+   when you drill and the pointer does not have to travel. */
+.fdy-cal__grid--months{grid-template-columns:repeat(3,1fr);gap:var(--space-1);}
+.fdy-cal__month{display:inline-flex;align-items:center;justify-content:center;height:2.25rem;border:0;border-radius:var(--radius-sm);background:transparent;color:var(--color-text);font-family:inherit;font-size:var(--text-sm);text-transform:capitalize;cursor:pointer;}
+.fdy-cal__month:hover{background:var(--color-surface-2);}
+.fdy-cal__month:focus-visible{outline:none;box-shadow:0 0 0 3px color-mix(in srgb,var(--color-primary) 26%,transparent);}
+.fdy-cal__month:disabled{opacity:.4;cursor:not-allowed;background:transparent;}
+.fdy-cal__month.is-today{font-weight:var(--weight-bold);box-shadow:inset 0 0 0 1.5px var(--color-border-strong);}
+.fdy-cal__month.is-selected{background:var(--color-primary);color:var(--color-on-primary);font-weight:var(--weight-semibold);}
 .fdy-cal__nav{display:inline-flex;align-items:center;justify-content:center;width:1.75rem;height:1.75rem;flex:none;border:0;border-radius:var(--radius-sm);background:transparent;color:var(--color-text-muted);font-size:var(--text-lg);line-height:1;cursor:pointer;}
 .fdy-cal__nav:hover{background:var(--color-surface-2);color:var(--color-text);}
 .fdy-cal__nav:focus-visible{outline:none;box-shadow:0 0 0 3px color-mix(in srgb,var(--color-primary) 26%,transparent);}

package/dist/freeday.css CHANGED Viewed

@@ -627,7 +627,14 @@ a { color: var(--color-primary); }
 .fdy-combo__option.is-highlighted{background:var(--color-surface-3);}
 .fdy-combo__option[aria-selected="true"]{background:var(--color-primary-soft);color:var(--color-primary-strong);font-weight:var(--weight-semibold);}
 .fdy-combo__option.is-highlighted[aria-selected="true"]{box-shadow:inset 0 0 0 2px color-mix(in srgb,var(--color-primary) 55%,transparent);}
+/* The tick is CSS, not content (#004 §2). Inside role="option" it joined the option's ACCESSIBLE
+   NAME, so the selected option announced "✓August" while every other announced "August": the state
+   was read twice — once as aria-selected, once as decoration — and a test asking for an option by
+   its own label stopped matching the one that was selected. The `/ ""` is alt text: the glyph is
+   painted, the accessibility tree gets nothing. Same reasoning as .fdy-label--required (1.29.0).
+   The empty box still reserves its width, so labels stay aligned whether selected or not. */
 .fdy-combo__check{display:inline-flex;justify-content:center;width:var(--space-4);flex:none;font-weight:var(--weight-bold);color:var(--color-primary);}
+.fdy-combo__option[aria-selected="true"] .fdy-combo__check::after{content:"✓" / "";}
 @media (prefers-reduced-motion:no-preference){.fdy-combo__listbox:not([hidden]){animation:fdy-combo-in var(--dur-fast) var(--ease-standard);}}
 @keyframes fdy-combo-in{from{opacity:0;transform:translateY(-4px);}to{opacity:1;transform:none;}}
@@ -731,7 +738,20 @@ a { color: var(--color-primary); }
 /* Calendar grid */
 .fdy-cal__head{display:flex;align-items:center;gap:var(--space-2);margin-bottom:var(--space-2);}
-.fdy-cal__title{flex:1;text-align:center;font-weight:var(--weight-semibold);font-size:var(--text-sm);color:var(--color-text);text-transform:capitalize;}
+/* The title is a CONTROL now (#004 §1): it drills to the month grid, so it needs the UA button box
+   reset and the same hover/focus treatment as the arrows beside it. */
+.fdy-cal__title{flex:1;appearance:none;border:0;background:transparent;padding:var(--space-1) var(--space-2);border-radius:var(--radius-sm);text-align:center;font-family:inherit;font-weight:var(--weight-semibold);font-size:var(--text-sm);color:var(--color-text);text-transform:capitalize;cursor:pointer;}
+.fdy-cal__title:hover{background:var(--color-surface-2);}
+.fdy-cal__title:focus-visible{outline:none;box-shadow:0 0 0 3px color-mix(in srgb,var(--color-primary) 26%,transparent);}
+/* Month grid — 3×4 over the same track width as the 7-column day grid, so the panel does not resize
+   when you drill and the pointer does not have to travel. */
+.fdy-cal__grid--months{grid-template-columns:repeat(3,1fr);gap:var(--space-1);}
+.fdy-cal__month{display:inline-flex;align-items:center;justify-content:center;height:2.25rem;border:0;border-radius:var(--radius-sm);background:transparent;color:var(--color-text);font-family:inherit;font-size:var(--text-sm);text-transform:capitalize;cursor:pointer;}
+.fdy-cal__month:hover{background:var(--color-surface-2);}
+.fdy-cal__month:focus-visible{outline:none;box-shadow:0 0 0 3px color-mix(in srgb,var(--color-primary) 26%,transparent);}
+.fdy-cal__month:disabled{opacity:.4;cursor:not-allowed;background:transparent;}
+.fdy-cal__month.is-today{font-weight:var(--weight-bold);box-shadow:inset 0 0 0 1.5px var(--color-border-strong);}
+.fdy-cal__month.is-selected{background:var(--color-primary);color:var(--color-on-primary);font-weight:var(--weight-semibold);}
 .fdy-cal__nav{display:inline-flex;align-items:center;justify-content:center;width:1.75rem;height:1.75rem;flex:none;border:0;border-radius:var(--radius-sm);background:transparent;color:var(--color-text-muted);font-size:var(--text-lg);line-height:1;cursor:pointer;}
 .fdy-cal__nav:hover{background:var(--color-surface-2);color:var(--color-text);}
 .fdy-cal__nav:focus-visible{outline:none;box-shadow:0 0 0 3px color-mix(in srgb,var(--color-primary) 26%,transparent);}

package/dist/freeday.js CHANGED Viewed

@@ -1346,6 +1346,8 @@
   var monthFmt = new Intl.DateTimeFormat(LOCALE, { month: 'long', year: 'numeric' });
   var valueFmt = new Intl.DateTimeFormat(LOCALE, { day: '2-digit', month: 'short', year: 'numeric' });
   var dayLabelFmt = new Intl.DateTimeFormat(LOCALE, { weekday: 'long', day: 'numeric', month: 'long', year: 'numeric' });
+  var monthCellFmt = new Intl.DateTimeFormat(LOCALE, { month: 'short' });
+  var monthNameFmt = new Intl.DateTimeFormat(LOCALE, { month: 'long', year: 'numeric' });
   function weekdayHeaders() {
     var monday = new Date(2024, 0, 1); // a known Monday
@@ -1371,6 +1373,13 @@
     var view = startOfDay(selected || new Date());
     view = new Date(view.getFullYear(), view.getMonth(), 1);
     var focusDate = null;
+    /* 'days' | 'months' — the calendar drills one level up rather than growing furniture beside the
+       title. Before this, the only pointer route to another month was one click per month: from
+       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 focusMonth = null;
     var trigger = document.createElement('button');
     trigger.type = 'button';
@@ -1418,6 +1427,25 @@
       return false;
     }
+    function monthDisabled(year, month) {
+      var last = new Date(year, month + 1, 0);
+      var first = new Date(year, month, 1);
+      if (minDate && startOfDay(last).getTime() < startOfDay(minDate).getTime()) return true;
+      if (maxDate && startOfDay(first).getTime() > startOfDay(maxDate).getTime()) return true;
+      return false;
+    }
+    function titleButton(text, aria, onClick) {
+      var b = document.createElement('button');
+      b.type = 'button';
+      b.className = 'fdy-cal__title';
+      b.id = uid('fdy-cal-title');
+      b.textContent = text;
+      b.setAttribute('aria-label', aria);
+      b.addEventListener('click', onClick);
+      return b;
+    }
     function navButton(glyph, aria, onClick) {
       var b = document.createElement('button');
       b.type = 'button';
@@ -1429,13 +1457,16 @@
     }
     function render() {
+      if (mode === 'months') { renderMonths(); return; }
       panel.innerHTML = '';
       var head = document.createElement('div');
       head.className = 'fdy-cal__head';
-      var title = document.createElement('div');
-      title.className = 'fdy-cal__title';
-      title.id = uid('fdy-cal-title');
-      title.textContent = monthFmt.format(view);
+      var title = titleButton(monthFmt.format(view), monthFmt.format(view) + ', pilih bulan', function () {
+        mode = 'months';
+        focusMonth = view.getMonth();
+        render();
+        focusMonthCell();
+      });
       panel.setAttribute('aria-labelledby', title.id);
       head.appendChild(navButton('‹', 'Bulan sebelumnya', function () { view = addMonths(view, -1); render(); }));
       head.appendChild(title);
@@ -1491,6 +1522,93 @@
       panel.appendChild(grid);
     }
+    function renderMonths() {
+      panel.innerHTML = '';
+      var year = view.getFullYear();
+      var head = document.createElement('div');
+      head.className = 'fdy-cal__head';
+      var title = titleButton(String(year), year + ', kembali ke tanggal', function () {
+        mode = 'days';
+        render();
+        focusFocusDate();
+      });
+      panel.setAttribute('aria-labelledby', title.id);
+      head.appendChild(navButton('‹', 'Tahun sebelumnya', function () { view = addMonths(view, -12); render(); focusMonthCell(); }));
+      head.appendChild(title);
+      head.appendChild(navButton('›', 'Tahun berikutnya', function () { view = addMonths(view, 12); render(); focusMonthCell(); }));
+      panel.appendChild(head);
+      var grid = document.createElement('div');
+      grid.className = 'fdy-cal__grid fdy-cal__grid--months';
+      grid.setAttribute('role', 'grid');
+      grid.setAttribute('aria-labelledby', title.id);
+      var today = new Date();
+      if (focusMonth === null) focusMonth = view.getMonth();
+      for (var m = 0; m < 12; m++) {
+        var cellDate = new Date(year, m, 1);
+        var btn = document.createElement('button');
+        btn.type = 'button';
+        btn.className = 'fdy-cal__month';
+        btn.setAttribute('role', 'gridcell');
+        btn.setAttribute('aria-label', monthNameFmt.format(cellDate));
+        btn.textContent = monthCellFmt.format(cellDate);
+        if (today.getFullYear() === year && today.getMonth() === m) btn.classList.add('is-today');
+        if (selected && selected.getFullYear() === year && selected.getMonth() === m) {
+          btn.classList.add('is-selected');
+          btn.setAttribute('aria-selected', 'true');
+        }
+        if (monthDisabled(year, m)) btn.disabled = true;
+        btn.tabIndex = m === focusMonth ? 0 : -1;
+        btn.addEventListener('click', (function (mm) { return function () { openMonth(mm); }; })(m));
+        grid.appendChild(btn);
+      }
+      grid.addEventListener('keydown', onMonthKey);
+      panel.appendChild(grid);
+    }
+    function focusMonthCell() {
+      var cell = panel.querySelector('.fdy-cal__month[tabindex="0"]');
+      if (cell) cell.focus();
+    }
+    /* 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) {
+      var dim = new Date(view.getFullYear(), m + 1, 0).getDate();
+      var day = focusDate ? Math.min(focusDate.getDate(), dim) : 1;
+      view = new Date(view.getFullYear(), m, 1);
+      focusDate = new Date(view.getFullYear(), m, day);
+      mode = 'days';
+      render();
+      focusFocusDate();
+    }
+    function moveMonthFocus(index, yearDelta) {
+      if (yearDelta) view = addMonths(view, yearDelta * 12);
+      focusMonth = (index + 12) % 12;
+      render();
+      focusMonthCell();
+    }
+    function onMonthKey(e) {
+      var handled = true;
+      switch (e.key) {
+        case 'ArrowLeft': moveMonthFocus(focusMonth - 1, 0); break;
+        case 'ArrowRight': moveMonthFocus(focusMonth + 1, 0); break;
+        case 'ArrowUp': moveMonthFocus(focusMonth - 3, 0); break;
+        case 'ArrowDown': moveMonthFocus(focusMonth + 3, 0); break;
+        case 'Home': moveMonthFocus(0, 0); break;
+        case 'End': moveMonthFocus(11, 0); break;
+        case 'PageUp': moveMonthFocus(focusMonth, -1); break;
+        case 'PageDown': moveMonthFocus(focusMonth, 1); break;
+        case 'Enter':
+        case ' ': openMonth(focusMonth); break;
+        case 'Escape': close(true); break;
+        default: handled = false;
+      }
+      if (handled) e.preventDefault();
+    }
     function focusFocusDate() {
       var cell = panel.querySelector('.fdy-cal__day[tabindex="0"]');
       if (cell) cell.focus();
@@ -1539,6 +1657,7 @@
     function popCtl() { if (_pop === null && window.FreedayPopover) _pop = window.FreedayPopover.attach(panel, trigger); return _pop; }
     function open() {
       if (!panel.hidden) return;
+      mode = 'days';
       focusDate = selected || focusDate || new Date();
       view = new Date(focusDate.getFullYear(), focusDate.getMonth(), 1);
       var p = popCtl(); if (p) p.show(); else panel.hidden = false;
@@ -2410,7 +2529,7 @@
  *     </button>
  *     <ul class="fdy-combo__listbox" role="listbox" hidden>
  *       <li class="fdy-combo__option" role="option" data-value="x"
- *           aria-selected="true"><span class="fdy-combo__check">✓</span>Label</li>
+ *           aria-selected="true"><span class="fdy-combo__check"></span>Label</li>
  *     </ul>
  *   </div>
  *
@@ -2422,10 +2541,9 @@
   var seq = 0;
   var openClose = null; // close() of the currently-open combo, or null
+  /* The tick lives in CSS now, so the option's text IS its label — no sibling walk to skip a glyph. */
   function optionLabel(opt) {
-    var check = opt.querySelector('.fdy-combo__check');
-    var node = check && check.nextSibling ? check.nextSibling.textContent : opt.textContent;
-    return (node || '').trim();
+    return (opt.textContent || '').trim();
   }
   function initCombo(root) {
@@ -2496,8 +2614,6 @@
       options.forEach(function (other) {
         var on = other === opt;
         other.setAttribute('aria-selected', on ? 'true' : 'false');
-        var check = other.querySelector('.fdy-combo__check');
-        if (check) check.textContent = on ? '✓' : '';
       });
       root.setAttribute('data-value', opt.getAttribute('data-value') || '');
       valueEl.textContent = optionLabel(opt);

package/docs/agent-onboarding.md CHANGED Viewed

@@ -91,6 +91,7 @@ Blazor). Then verify the agent can actually read those files — an agent that c
 | `docs/integrations.md` | How to bridge third-party libraries (validation, charts, dates, i18n…). |
 | `docs/reference-screen.html` | A full screen assembled from the shell down. Open it in a browser. |
 | `docs/agent-onboarding.md` | This file. |
+| `CHANGELOG.md` | **What changed between the version this project had and the one it has now** — read it after every upgrade; each entry says what broke, what is new, and why. |
 | `dist/` | Built CSS + enhancers. **`freeday.bundle.css` = tokens + components** (what `@cahyo-dimas/freeday/css` resolves to); `freeday.css` is components **only**, `freeday.tokens.css` tokens only — linking `freeday.css` alone leaves every `var(--…)` unresolved. Plus `freeday-*.js` and the `.d.ts` files. |
 | `src/components/*.css` | The authoritative source for every class, when a doc is ambiguous. |
 | `tokens/tokens.json` | Every token in W3C DTCG format — machine-readable. |
@@ -101,6 +102,28 @@ The live docs (with an interactive playground) are at
 apps under `examples/` (Vue, React, Blazor) that are **not** in the npm tarball — is at
 <https://github.com/cahyo-dimas/freeday-ui-kit>.
+### After an upgrade, read the changelog first
+`npm i @cahyo-dimas/freeday@latest` does not tell you what you gained. Read
+`node_modules/@cahyo-dimas/freeday/CHANGELOG.md` down to the version this project was on before —
+it is written for exactly this moment, and it is the difference between adopting a new affordance
+and re-implementing it locally.
+Recent additions most likely to replace something an app hand-rolled (all detailed in
+`COMPONENTS.md`):
+| Reach for | Instead of |
+|---|---|
+| `.fdy-btn--stretch` | a hand-rolled overlay to make a card or list row clickable |
+| `[data-fdy-number]` | a bare `<input type="number">` with the browser's own spin buttons |
+| `clearable` on `FdyCfl` / `FdyDatepicker` | a value that can be set but never unset |
+| `row.waiting(label)` on an upload row | a second status line saying the server is still working |
+| `.fdy-label--required` | a `<span>` asterisk you have to remember to `aria-hidden` |
+| `.fdy-text-warning` / `-danger` / `-success` | a caption class on a line that should stand out |
+| `.fdy-icon` | your own `width:1em;height:1em` rule, once per project |
+| `data-density="comfortable"` | restating the default spacing tokens on a wrapper |
+| the calendar's month grid (press the title) | clicking "previous month" thirty times |
 ## 3. Starting a new screen
 The order matters; skipping to components is what produces flat, identical-card screens.

package/docs/getting-started.md CHANGED Viewed

@@ -184,7 +184,7 @@ live docs also have a copy button per component.
 ```bash
 npm i @cahyo-dimas/freeday
 ```
-Lands in `package.json` as `"@cahyo-dimas/freeday": "^1.31.0"` (public npm package). `dist/` is
+Lands in `package.json` as `"@cahyo-dimas/freeday": "^1.32.1"` (public npm package). `dist/` is
 committed and published → no build step; `npm ci` runs without auth.
 ### 2. Import the CSS + enhancers **once** in your entry (`src/main.ts`)

package/docs/reference-screen.html CHANGED Viewed

@@ -211,7 +211,7 @@
                     <span class="fdy-combo__value" id="f-st-v">All</span>
                   </button>
                   <ul class="fdy-combo__listbox" role="listbox" aria-labelledby="f-st" hidden>
-                    <li class="fdy-combo__option" role="option" data-value="all" aria-selected="true"><span class="fdy-combo__check">✓</span>All</li>
+                    <li class="fdy-combo__option" role="option" data-value="all" aria-selected="true"><span class="fdy-combo__check"></span>All</li>
                     <li class="fdy-combo__option" role="option" data-value="open" aria-selected="false"><span class="fdy-combo__check"></span>Open</li>
                     <li class="fdy-combo__option" role="option" data-value="overdue" aria-selected="false"><span class="fdy-combo__check"></span>Overdue</li>
                   </ul>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@cahyo-dimas/freeday",
-  "version": "1.31.0",
+  "version": "1.32.1",
   "description": "Freeday — token-driven, framework-agnostic UI KIT (design source-of-truth).",
   "type": "module",
   "license": "MIT",

package/src/components/combo.css CHANGED Viewed

@@ -27,6 +27,13 @@
 .fdy-combo__option.is-highlighted{background:var(--color-surface-3);}
 .fdy-combo__option[aria-selected="true"]{background:var(--color-primary-soft);color:var(--color-primary-strong);font-weight:var(--weight-semibold);}
 .fdy-combo__option.is-highlighted[aria-selected="true"]{box-shadow:inset 0 0 0 2px color-mix(in srgb,var(--color-primary) 55%,transparent);}
+/* The tick is CSS, not content (#004 §2). Inside role="option" it joined the option's ACCESSIBLE
+   NAME, so the selected option announced "✓August" while every other announced "August": the state
+   was read twice — once as aria-selected, once as decoration — and a test asking for an option by
+   its own label stopped matching the one that was selected. The `/ ""` is alt text: the glyph is
+   painted, the accessibility tree gets nothing. Same reasoning as .fdy-label--required (1.29.0).
+   The empty box still reserves its width, so labels stay aligned whether selected or not. */
 .fdy-combo__check{display:inline-flex;justify-content:center;width:var(--space-4);flex:none;font-weight:var(--weight-bold);color:var(--color-primary);}
+.fdy-combo__option[aria-selected="true"] .fdy-combo__check::after{content:"✓" / "";}
 @media (prefers-reduced-motion:no-preference){.fdy-combo__listbox:not([hidden]){animation:fdy-combo-in var(--dur-fast) var(--ease-standard);}}
 @keyframes fdy-combo-in{from{opacity:0;transform:translateY(-4px);}to{opacity:1;transform:none;}}

package/src/components/datepicker.css CHANGED Viewed

@@ -29,7 +29,20 @@
 /* Calendar grid */
 .fdy-cal__head{display:flex;align-items:center;gap:var(--space-2);margin-bottom:var(--space-2);}
-.fdy-cal__title{flex:1;text-align:center;font-weight:var(--weight-semibold);font-size:var(--text-sm);color:var(--color-text);text-transform:capitalize;}
+/* The title is a CONTROL now (#004 §1): it drills to the month grid, so it needs the UA button box
+   reset and the same hover/focus treatment as the arrows beside it. */
+.fdy-cal__title{flex:1;appearance:none;border:0;background:transparent;padding:var(--space-1) var(--space-2);border-radius:var(--radius-sm);text-align:center;font-family:inherit;font-weight:var(--weight-semibold);font-size:var(--text-sm);color:var(--color-text);text-transform:capitalize;cursor:pointer;}
+.fdy-cal__title:hover{background:var(--color-surface-2);}
+.fdy-cal__title:focus-visible{outline:none;box-shadow:0 0 0 3px color-mix(in srgb,var(--color-primary) 26%,transparent);}
+/* Month grid — 3×4 over the same track width as the 7-column day grid, so the panel does not resize
+   when you drill and the pointer does not have to travel. */
+.fdy-cal__grid--months{grid-template-columns:repeat(3,1fr);gap:var(--space-1);}
+.fdy-cal__month{display:inline-flex;align-items:center;justify-content:center;height:2.25rem;border:0;border-radius:var(--radius-sm);background:transparent;color:var(--color-text);font-family:inherit;font-size:var(--text-sm);text-transform:capitalize;cursor:pointer;}
+.fdy-cal__month:hover{background:var(--color-surface-2);}
+.fdy-cal__month:focus-visible{outline:none;box-shadow:0 0 0 3px color-mix(in srgb,var(--color-primary) 26%,transparent);}
+.fdy-cal__month:disabled{opacity:.4;cursor:not-allowed;background:transparent;}
+.fdy-cal__month.is-today{font-weight:var(--weight-bold);box-shadow:inset 0 0 0 1.5px var(--color-border-strong);}
+.fdy-cal__month.is-selected{background:var(--color-primary);color:var(--color-on-primary);font-weight:var(--weight-semibold);}
 .fdy-cal__nav{display:inline-flex;align-items:center;justify-content:center;width:1.75rem;height:1.75rem;flex:none;border:0;border-radius:var(--radius-sm);background:transparent;color:var(--color-text-muted);font-size:var(--text-lg);line-height:1;cursor:pointer;}
 .fdy-cal__nav:hover{background:var(--color-surface-2);color:var(--color-text);}
 .fdy-cal__nav:focus-visible{outline:none;box-shadow:0 0 0 3px color-mix(in srgb,var(--color-primary) 26%,transparent);}