npm - @cahyo-dimas/freeday - Versions diffs - 1.30.0 → 1.32.0 - Mend

@cahyo-dimas/freeday 1.30.0 → 1.32.0

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 (21) hide show

package/CHANGELOG.md +72 -0
package/COMPONENTS.md +20 -3
package/README.id.md +1 -1
package/README.md +1 -1
package/USAGE.md +7 -0
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 +33 -1
package/dist/freeday.css +21 -1
package/dist/freeday.js +126 -10
package/dist/freeday.tokens.css +12 -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,78 @@
 Semua perubahan penting dicatat di sini. Format longgar mengikuti
 [Keep a Changelog](https://keepachangelog.com/); tiap versi = git tag.
+## [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
+- **`[data-density="comfortable"]` is now a real rule.** The kit shipped only the `compact` block,
+  and its own comment promised per-subtree density — true in one direction only. These are
+  inheriting custom properties, so once `<html>` is compact *every* subtree is compact and a
+  `comfortable` wrapper matched nothing at all. An app that is dense overall (a back office where
+  most screens are data grids) could not opt its shared chrome back out: measured against a sibling
+  product, the logo sat 12px from the edge instead of 16 and the avatar 12 instead of 20 — four
+  pixels in two places, from `--space-4` and `--control-h`, which reads as sloppiness rather than as
+  a token. The workaround, restating the five defaults on a local class, is exactly the copy that
+  goes stale when the kit retunes a step.
+  Note the kit's own README has been telling people to write `data-density="comfortable"` on `<html>`
+  since long before a rule existed for it — harmless there, because it matched the defaults by
+  accident, and broken the moment anyone needed it on a wrapper.
+### Notes on the shape of the fix
+- The five values are **derived from the tokens' own defaults** at build time, not written out a
+  second time. Same key set by construction, so a token that gains a `$compact` value automatically
+  gains its way back out, and a retuned default can never leave the two blocks disagreeing. The
+  report's hand-written block was correct in all five values — this only removes the chance for it
+  to stop being correct.
+### Added — guards
+- `test/build.test.mjs` asserts the two density blocks cover the *same* tokens, that every
+  comfortable value equals the `:root` default, and that none of them equals its compact counterpart
+  (a block that resets nothing is as green as one that works).
+- `browser/theme.mjs` measures it in a real engine: a compact root, a `comfortable` island that
+  returns to a 40px control and `--space-4: 1rem`, and a `compact` island nested back inside that —
+  because the point of the rule is the box that comes out, not the declaration going in.
 ## [1.30.0] — 2026-08-18
 Note 008 (adopting 1.29.0) plus a direct design report: *"the input border looks too dark next to the
 card and button-group borders."*

package/COMPONENTS.md CHANGED Viewed

@@ -232,7 +232,8 @@ utility variant that has to agree with the shell must use `nav`; using `md` leav
 Density: `data-density="compact"` works on `<html>` **or any wrapper** — the selector is a bare
 `[data-density="compact"]` over inheriting custom properties, so one screen can be dense while the
-rest of the app is not.
+rest of the app is not. `data-density="comfortable"` is a real rule too, so the reverse also works:
+a compact root with one region opted back out (shared chrome that must match a sibling product).
 ---
@@ -402,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).
@@ -504,10 +511,20 @@ 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 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.30.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.30.0)
+[![Release](https://img.shields.io/badge/release-v1.32.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.32.0)
 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.30.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.30.0)
+[![Release](https://img.shields.io/badge/release-v1.32.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.32.0)
 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/USAGE.md CHANGED Viewed

@@ -130,6 +130,13 @@ container, a single `<section>`. An app whose two list screens are dense and who
 are not should scope it per screen rather than densifying everything. Set it at one level per screen,
 never per component.
+**And it goes both ways.** `data-density="comfortable"` is a real rule, not just the absence of
+`compact`, so an app that is dense *at the root* can opt one region back out — a header, a toolbar,
+a footer shared with a sibling product that has to line up pixel for pixel. Inheritance only runs
+downhill; without that rule a compact root left every subtree compact and a `comfortable` wrapper
+changed nothing. Do not restate the five values by hand: that copy goes stale the moment the kit
+retunes a step.
 ## 6b. Navigation: one component, two orientations — and never a tab role
 A navigation link is an `<a class="fdy-nav__item">` marked **`aria-current="page"`**. That does not

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

@@ -368,6 +368,18 @@
   --space-6: 1.25rem;
   --control-h: 2rem;
 }
+/* ...and the way back out. Inheritance only runs downhill: once the root is compact every subtree is
+ * compact, and before this rule existed a data-density="comfortable" wrapper matched nothing — so the
+ * comment above was true in one direction only. An app that is dense overall and carries one region
+ * of shared chrome (a header, a toolbar, a footer shared with a sibling product) had to restate the
+ * defaults by hand, which is exactly the local copy that goes stale when the kit retunes them. */
+[data-density="comfortable"] {
+  --space-3: 0.75rem;
+  --space-4: 1rem;
+  --space-5: 1.25rem;
+  --space-6: 1.5rem;
+  --control-h: 2.5rem;
+}
 /* Freeday components — GENERATED by tokens/build.mjs. Do not edit by hand. */
 /* Freeday base layer — reset ringan + default via token */
@@ -998,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;}}
@@ -1102,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/dist/freeday.tokens.css CHANGED Viewed

@@ -367,3 +367,15 @@
   --space-6: 1.25rem;
   --control-h: 2rem;
 }
+/* ...and the way back out. Inheritance only runs downhill: once the root is compact every subtree is
+ * compact, and before this rule existed a data-density="comfortable" wrapper matched nothing — so the
+ * comment above was true in one direction only. An app that is dense overall and carries one region
+ * of shared chrome (a header, a toolbar, a footer shared with a sibling product) had to restate the
+ * defaults by hand, which is exactly the local copy that goes stale when the kit retunes them. */
+[data-density="comfortable"] {
+  --space-3: 0.75rem;
+  --space-4: 1rem;
+  --space-5: 1.25rem;
+  --space-6: 1.5rem;
+  --control-h: 2.5rem;
+}

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.30.0"` (public npm package). `dist/` is
+Lands in `package.json` as `"@cahyo-dimas/freeday": "^1.32.0"` (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.30.0",
+  "version": "1.32.0",
   "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);}