diff --git a/docs/specs/components/Calendar/Calendar.spec.md b/docs/specs/components/Calendar/Calendar.spec.md index f44572035a3a0..c830ca45cd0c7 100644 --- a/docs/specs/components/Calendar/Calendar.spec.md +++ b/docs/specs/components/Calendar/Calendar.spec.md @@ -19,6 +19,7 @@ verified_by: packages/core/src/Calendar/CalendarToday.ssr.test.tsx, packages/core/src/Calendar/__tests__/CalendarTodayHydration.interaction.browser.spec.ts, packages/core/src/Calendar/__tests__/CalendarTextSize.interaction.browser.spec.ts, + packages/core/src/Calendar/__tests__/CalendarMonthButtonPress.interaction.browser.spec.ts, packages/core/src/Calendar/getInitialFocusDate.test.ts, packages/core/src/Calendar/hooks/calendarHooks.calendarSystems.test.tsx, packages/core/src/utils/calendarSystem.test.ts, @@ -55,15 +56,15 @@ system_specs: ## Contract at a glance -| Area | Contract | -| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Public contract | `Calendar` and `CalendarProps` are exported from `@astryxdesign/core/Calendar`; `mode` selects a single date or a range, with `value`/`defaultValue`/`onChange`, bounds, constraints, span limits, focus date, display options, and an optional `calendar` (`CalendarSystem`). Every value stays a Gregorian ISO date. The public `useCalendarDays` and `useCalendarNavigation` hooks take an optional `calendar` too (FR11). | -| Behavior | One or two months of the resolved calendar system render as day grids under weekday headers (DD1); a day is picked by pointer or keyboard; each month grid holds at most one roving Tab stop, which arrow, Home/End, and Page keys move, following the reading direction. Page keys step calendar months, and with Shift calendar years. | -| End-user impact | A keyboard or screen-reader user meets a named month grid, moves through it by day, week, and month (and year with Shift and a Page key), and hears each day's name, selection, today marker, and disabled state, in the calendar the application chose. | -| Builder impact | Optional: set `calendar` on the Calendar or its provider; for a calendar that needs `Temporal`, load a polyfill where the runtime lacks it. A theme styles the range bands through `calendar-range` and `calendar-range-preview`. | -| Compatibility/readiness | The `calendar` prop is additive and the default stays Gregorian. A provider locale with a `-u-ca-` keyword keeps Gregorian dates (`spec:AST-111` DEC-2); set `calendar` to choose one. Calendars that need `Temporal` fall back to Gregorian where it is missing (the `spec:AST-013` FR12 exception). The month buttons use native `disabled` at a bound and scale under reduced motion, a key-moved Tab stop can go stale, and the Calendar grows wider than a phone screen at the largest text sizes; all are listed under Current-state impact. | -| Review checks | Reject a day grid without `role="grid"` or a name, two days in one month holding a Tab stop, an arrow key that stops following the reading direction, a selection or today state carried only by colour, a weekday header cut to a fixed number of characters, or a header row mixing abbreviated and short names. | -| Governing rules | DD1 for the weekday headers; `architecture:public-component-api/INV1,INV5–INV8`; `architecture:component-theming-surface/INV3–INV7`; `spec:AST-020/FR15`; `spec:AST-085/FR1, FR4`; `spec:AST-102` FR4; `spec:AST-111` FR1–FR8, FR20, AR1; `spec:AST-013` FR12; `design:bidirectionality` DR6; `design:reduced-motion` DR1; `architecture:internationalization` INV8. | +| Area | Contract | +| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Public contract | `Calendar` and `CalendarProps` are exported from `@astryxdesign/core/Calendar`; `mode` selects a single date or a range, with `value`/`defaultValue`/`onChange`, bounds, constraints, span limits, focus date, display options, and an optional `calendar` (`CalendarSystem`). Every value stays a Gregorian ISO date. The public `useCalendarDays` and `useCalendarNavigation` hooks take an optional `calendar` too (FR11). | +| Behavior | One or two months of the resolved calendar system render as day grids under weekday headers (DD1); a day is picked by pointer or keyboard; each month grid holds at most one roving Tab stop, which arrow, Home/End, and Page keys move, following the reading direction. Page keys step calendar months, and with Shift calendar years. | +| End-user impact | A keyboard or screen-reader user meets a named month grid, moves through it by day, week, and month (and year with Shift and a Page key), and hears each day's name, selection, today marker, and disabled state, in the calendar the application chose. | +| Builder impact | Optional: set `calendar` on the Calendar or its provider; for a calendar that needs `Temporal`, load a polyfill where the runtime lacks it. A theme styles the range bands through `calendar-range` and `calendar-range-preview`. | +| Compatibility/readiness | The `calendar` prop is additive and the default stays Gregorian. A provider locale with a `-u-ca-` keyword keeps Gregorian dates (`spec:AST-111` DEC-2); set `calendar` to choose one. Calendars that need `Temporal` fall back to Gregorian where it is missing (the `spec:AST-013` FR12 exception). A key-moved Tab stop can go stale, and the Calendar grows wider than a phone screen at the largest text sizes; all are listed under Current-state impact. | +| Review checks | Reject a day grid without `role="grid"` or a name, two days in one month holding a Tab stop, an arrow key that stops following the reading direction, a selection or today state carried only by colour, a weekday header cut to a fixed number of characters, or a header row mixing abbreviated and short names. | +| Governing rules | DD1 for the weekday headers; `architecture:public-component-api/INV1,INV5–INV8`; `architecture:component-theming-surface/INV3–INV7`; `spec:AST-020/FR15`; `spec:AST-085/FR1, FR4`; `spec:AST-102` FR4; `spec:AST-111` FR1–FR8, FR20, AR1; `spec:AST-013` FR12; `design:bidirectionality` DR6; `design:reduced-motion` DR1; `architecture:internationalization` INV8. | This table is a review projection; the body below is authoritative. @@ -129,7 +130,7 @@ Consumer migration instructions belong in consumer docs and release notes. | FR3 | A disabled day (outside bounds or rejected by a constraint) stays in the grid, stays focusable with `aria-disabled` and no native `disabled`, never holds the grid's Tab stop, and cannot be picked. Implementation gap: once a key move (arrow, Home, End, or Page key) has placed the Tab stop, it stays on that day when every day of the month becomes disabled (for example a range span cap in a two-month view). | `spec:AST-085` FR1, FR2; shipped source and focused tests | | FR4 | In `range` mode the first pick starts the range and the second ends it, a second pick before the start swapping the two so the end never precedes the start; `minRangeSpan`/`maxRangeSpan` bound it. Escape, or picking the start day again when `minRangeSpan` is above 1, clears an in-progress range. | shipped source and focused tests | | FR5 | Moving the focused day across a month boundary navigates the visible month so the focused day stays visible, in one month or two; a borrowed adjacent-month day is exposed `aria-disabled` and cannot be picked; arrow keys, Home and End skip it, and a page never lands on it. | shipped source and focused tests | -| FR6 | The month header shows the month and year between Previous and Next month buttons (ghost, icon-only Buttons whose chevrons mirror under RTL), which carry `calendar-nav` with `data-nav` and `data-disabled`. A button whose direction would leave `min` or `max` MUST stay focusable with `aria-disabled`, change nothing, and keep focus (`spec:AST-085` FR1, FR4). Implementation gap: it is natively disabled, so a focused button that reaches the bound drops focus. The month buttons are `component:Button`s, so their press scale MUST NOT apply under reduced motion (`design:reduced-motion` DR1). Implementation gap: it still applies under reduced motion. | `spec:AST-085`; shipped source and focused tests; `design:reduced-motion` DR1 | +| FR6 | The month header shows the month and year between Previous and Next month buttons (ghost, icon-only Buttons whose chevrons mirror under RTL), which carry `calendar-nav` with `data-nav` and `data-disabled`. A button whose direction would leave `min` or `max` MUST stay focusable with `aria-disabled`, change nothing, and keep focus (`spec:AST-085` FR1, FR4). The month buttons are `component:Button`s, so their press scale MUST NOT apply under reduced motion (`design:reduced-motion` DR1). | `spec:AST-085`; shipped source and focused tests; `design:reduced-motion` DR1 | | FR8 | The grid shows the months of the resolved calendar system (`spec:AST-111` FR2). Each grid lays out one calendar month: its first day sits in its weekday column and outside days fill the other cells. The default grid has six rows for every month, including the five- or six-day thirteenth month of the Coptic and Ethiopic calendars; `hasVariableRowCount` gives each month only the rows it needs. A leap month is a distinct month with its own name. The month heading, each grid's name, day-button names, and announcements use the calendar, and day numbers are the calendar's days in the locale's digits. Every name gives the month and day that the grid shows, and `iso8601` uses the Gregorian month names. `value`, `min`, `max`, `focusDate`, and every callback stay Gregorian ISO dates in every calendar. | `spec:AST-111` FR3, FR4, FR6; `Temporal` month structure | | FR9 | Previous and Next move one calendar month. PageUp and PageDown move the focused day one calendar month, keep its day of the month, and clamp it to the target month's length. Shift+PageUp and Shift+PageDown move the focused day one calendar year, to the same month of that year; a leap month that the target year does not have becomes its common counterpart (Adar I becomes Adar). In the Gregorian calendar a year step lands on the same day one year away, clamped. `min` and `max` bound navigation by day in every calendar, and a year step meets them and constraints as a month step does (AR1). | `spec:AST-111` FR7; APG date picker dialog keyboard model | | FR10 | `hasWeekNumbers` shows ISO 8601 week numbers in every calendar. Each row shows the ISO 8601 week number of its Thursday, the ISO week that holds most of its days. | `spec:AST-111` FR8 | @@ -292,20 +293,20 @@ button. ## Verification map -| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | -| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -| FR1–FR5 | `Calendar.test.tsx` structure ("renders a valid APG grid: one grid, header row of columnheaders inside it, week rows of gridcells", "with week numbers, the header row's corner cell is a named columnheader, so every row child is a grid cell"), locale digits ("shows day and week numbers in the locale digits in %s" for `fa-IR`, `ar-EG`, and `en`), selection ("handles reverse range selection (end before start)", "caps the range highlight next to a disabled mid-range day (#2715)", "Escape cancels range selection in progress", "clears the in-progress start when the anchor is clicked again"), bounds ("prev button is disabled when focusDate month contains min", "next button is disabled when focusDate month contains max"), and navigation ("navigates to next month", "calls onFocusDateChange when navigating") suites | single, range, two months, bounded | A missing header row, a reverse pick that does not swap, a range highlight that reaches a disabled day, or a Previous/Next button enabled past `min`/`max` fails. Day or week numbers in Latin digits under `fa-IR` or `ar-EG` fail. | `audit:Calendar/behavior` | -| AR1 | `Calendar.test.tsx` ("has accessible grid structure", "sets aria-multiselectable on both grids in a two-month range view", "does not set aria-multiselectable in single mode", "announces the new month politely when clicking next", "displays day names") and `useGridFocus.test.tsx` ("ArrowDown moves the tab stop one row down", "flips ArrowLeft/ArrowRight under RTL"); `Calendar.test.tsx` "ArrowUp skips a disabled cell in the same column to the next enabled row (complex-2)" for the disabled-day skip; `Calendar.test.tsx` Page-key cases ("moves the focused day by a month with PageDown and PageUp, into the month now shown", "pages from a borrowed adjacent-month day onto the real day in the month already shown", "an arrow past max changes nothing and leaves no pending target behind", "a page into a month with no enabled day changes nothing and keeps focus", "a page onto a day disabled by a constraint moves the month and focuses its first enabled day", "a page whose target lies past max changes nothing and keeps focus", "in a two-month view a boundary blocks only out-of-range targets, not month movement", "in a two-month view PageDown from the second month moves both months and a later Next click selects no stale day", "moves the focused day by a year with Shift+PageDown and Shift+PageUp", "a year from February 29 lands on February 28", "a year step whose target lies past max changes nothing and keeps focus", "a year step onto a day disabled by a constraint focuses that month's first enabled day", "in a two-month view a year step forward makes the target month the second one shown"); borrowed-day cases ("skips borrowed adjacent-month days and crosses into their month instead", "in a two-month view an arrow from the first month lands on the real day, never a borrowed one", "an arrow toward a direction where every remaining day is disabled changes nothing", "an arrow resolves the next enabled day in its direction first: weekdays-only ArrowRight from Friday January 30 reaches Monday February 2", "an arrow whose next day in range does not exist changes nothing: max January 25, ArrowDown from January 21"); the single-Tab-stop assertion in the AST-085 range-cap case (FR2). `Calendar.test.tsx` selection-state accessible-name cases ("appends 'selected' to the selected day's button name in single mode", "marks range start, end, and in-range days in their accessible names"). Evidence gap: no Calendar-level test of Home, End, Enter, or Space; no test covers the Tab stop after a key move followed by a pointer pick or a fully disabled month | LTR and RTL; month boundary; selected, today, disabled days | A day loses its role, name or state, two days in one month hold a Tab stop, or an arrow, Home/End, Page or activation key stops moving or picking. | `audit:Calendar/accessibility` | -| FR6 | `Calendar.test.tsx` navigation, bound, theming-target ("renders the astryx-calendar-nav target on both month-nav buttons", "reflects the disabled nav state as a data attribute at the range edges", "keeps the default nav rendering unchanged (still a ghost icon button)"), and RTL month-navigation cases | Previous and Next; at `min` and `max`; `dir="rtl"` | A button enabled past a bound, a missing `calendar-nav` target or state attribute, or a lost shared chevron wrapper fails. Evidence gap: no test asserts focus kept at a bound (the FR6 gap), the mirrored chevron pixels, or the press under reduced motion. | `audit:Calendar/behavior` | -| FR7 | `Calendar.test.tsx` month-change announcement cases ("does not announce on initial render", "announces the new month politely when clicking next", "announces the next month when paging the grid with PageDown", "announces both months in a two-month view", "does not announce when selecting a date leaves the visible month unchanged") and range announcement cases ("announces the start pick and prompts for an end date", "announces the completed range in chronological order for a reverse pick") | Month buttons, Page keys, handle; single and two months; range start, complete, cleared | A missing, extra, or out-of-order announcement fails. Evidence gap: no test reaches the cleared-start announcement (the cleared-range case sets no `minRangeSpan`). | `audit:Calendar/accessibility` | -| FR1 (labels) | `Calendar.test.tsx` ("starts each stand-alone month label with a capital in %s", "leaves the month label as Intl gives it where CLDR does not capitalize in %s"), `plainDate.test.ts` `plainDateFormatStandaloneMonthYear` | es, fr, pl, ru two-month view; vi, de, en | A lower-case stand-alone month where CLDR titlecases it, a capital where it does not, or a second month left lower case fails. | `audit:Calendar/behavior` | -| FR8–FR10, AR1 (calendars) | `Calendar.calendarSystems.test.tsx` ("lays out Aban 1405 with its calendar day numbers and labels", "keeps the fixed six-row grid", "reports a pick as a Gregorian ISO date", "steps one calendar month with Previous and Next", "pages one calendar month and clamps the day of the month", "bounds the month buttons by day", "shows ISO 8601 week numbers", "numbers Sunday-start rows like the same Gregorian rows", "writes day numbers and labels in the locale", "shows Adar I and Adar II as distinct months of a leap year", "steps a year from Adar I to Adar with Shift+PageDown, clamped", "keeps six rows for the five-day thirteenth month", "gives the thirteenth month only its rows with hasVariableRowCount", "steps a year to the same month with Shift+PageUp", "names the era of each month", "names each day by the month and day the grid shows when Intl disagrees", Gregorian year-paging cases); `Calendar.test.tsx` ("numbers each row by the ISO week of its Thursday" for Sunday, Monday, and Saturday starts and across a year end); `Calendar.ssr.test.tsx` server render and hydration with `Temporal` on both sides, neither side, and the browser only; `calendarSystem.test.ts` month structure at known dates, labels of every Gregorian-aligned calendar, and contiguity, length, and months-per-year invariants for every calendar from 1900 through 2100; `i18n/__tests__/calendarSystem.test.tsx` resolution order and the fallback without `Temporal`; real Chromium and Firefox runs with native `Temporal`, with a polyfill, and without `Temporal` | Persian, Hebrew leap year, Ethiopic thirteenth month, Japanese era change, Chinese leap month; `fa-IR` digits; Sunday and Saturday week starts; no `Temporal` | A month start, length, label, or step that differs from `Temporal`, a vanished leap month, a non-ISO value, a row not numbered by its Thursday's ISO week, or a crash or missing warning without `Temporal` fails. Evidence gap: no Safari or WebKit run. | `audit:Calendar/behavior` | +| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | +| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | +| FR1–FR5 | `Calendar.test.tsx` structure ("renders a valid APG grid: one grid, header row of columnheaders inside it, week rows of gridcells", "with week numbers, the header row's corner cell is a named columnheader, so every row child is a grid cell"), locale digits ("shows day and week numbers in the locale digits in %s" for `fa-IR`, `ar-EG`, and `en`), selection ("handles reverse range selection (end before start)", "caps the range highlight next to a disabled mid-range day (#2715)", "Escape cancels range selection in progress", "clears the in-progress start when the anchor is clicked again"), bounds ("prev button is disabled when focusDate month contains min", "next button is disabled when focusDate month contains max"), and navigation ("navigates to next month", "calls onFocusDateChange when navigating") suites | single, range, two months, bounded | A missing header row, a reverse pick that does not swap, a range highlight that reaches a disabled day, or a Previous/Next button enabled past `min`/`max` fails. Day or week numbers in Latin digits under `fa-IR` or `ar-EG` fail. | `audit:Calendar/behavior` | +| AR1 | `Calendar.test.tsx` ("has accessible grid structure", "sets aria-multiselectable on both grids in a two-month range view", "does not set aria-multiselectable in single mode", "announces the new month politely when clicking next", "displays day names") and `useGridFocus.test.tsx` ("ArrowDown moves the tab stop one row down", "flips ArrowLeft/ArrowRight under RTL"); `Calendar.test.tsx` "ArrowUp skips a disabled cell in the same column to the next enabled row (complex-2)" for the disabled-day skip; `Calendar.test.tsx` Page-key cases ("moves the focused day by a month with PageDown and PageUp, into the month now shown", "pages from a borrowed adjacent-month day onto the real day in the month already shown", "an arrow past max changes nothing and leaves no pending target behind", "a page into a month with no enabled day changes nothing and keeps focus", "a page onto a day disabled by a constraint moves the month and focuses its first enabled day", "a page whose target lies past max changes nothing and keeps focus", "in a two-month view a boundary blocks only out-of-range targets, not month movement", "in a two-month view PageDown from the second month moves both months and a later Next click selects no stale day", "moves the focused day by a year with Shift+PageDown and Shift+PageUp", "a year from February 29 lands on February 28", "a year step whose target lies past max changes nothing and keeps focus", "a year step onto a day disabled by a constraint focuses that month's first enabled day", "in a two-month view a year step forward makes the target month the second one shown"); borrowed-day cases ("skips borrowed adjacent-month days and crosses into their month instead", "in a two-month view an arrow from the first month lands on the real day, never a borrowed one", "an arrow toward a direction where every remaining day is disabled changes nothing", "an arrow resolves the next enabled day in its direction first: weekdays-only ArrowRight from Friday January 30 reaches Monday February 2", "an arrow whose next day in range does not exist changes nothing: max January 25, ArrowDown from January 21"); the single-Tab-stop assertion in the AST-085 range-cap case (FR2). `Calendar.test.tsx` selection-state accessible-name cases ("appends 'selected' to the selected day's button name in single mode", "marks range start, end, and in-range days in their accessible names"). Evidence gap: no Calendar-level test of Home, End, Enter, or Space; no test covers the Tab stop after a key move followed by a pointer pick or a fully disabled month | LTR and RTL; month boundary; selected, today, disabled days | A day loses its role, name or state, two days in one month hold a Tab stop, or an arrow, Home/End, Page or activation key stops moving or picking. | `audit:Calendar/accessibility` | +| FR6 | `Calendar.test.tsx` navigation, bound ("a month button that reaches the bound keeps focus and stays focusable"), `CalendarMonthButtonPress.interaction.browser.spec.ts` (a held press scales a month button, and not under reduced motion), theming-target ("renders the astryx-calendar-nav target on both month-nav buttons", "reflects the disabled nav state as a data attribute at the range edges", "keeps the default nav rendering unchanged (still a ghost icon button)"), and RTL month-navigation cases | Previous and Next; at `min` and `max`; `dir="rtl"` | A button enabled past a bound, a missing `calendar-nav` target or state attribute, or a lost shared chevron wrapper fails. Evidence gap: no test asserts the mirrored chevron pixels. | `audit:Calendar/behavior` | +| FR7 | `Calendar.test.tsx` month-change announcement cases ("does not announce on initial render", "announces the new month politely when clicking next", "announces the next month when paging the grid with PageDown", "announces both months in a two-month view", "does not announce when selecting a date leaves the visible month unchanged") and range announcement cases ("announces the start pick and prompts for an end date", "announces the completed range in chronological order for a reverse pick") | Month buttons, Page keys, handle; single and two months; range start, complete, cleared | A missing, extra, or out-of-order announcement fails. Evidence gap: no test reaches the cleared-start announcement (the cleared-range case sets no `minRangeSpan`). | `audit:Calendar/accessibility` | +| FR1 (labels) | `Calendar.test.tsx` ("starts each stand-alone month label with a capital in %s", "leaves the month label as Intl gives it where CLDR does not capitalize in %s"), `plainDate.test.ts` `plainDateFormatStandaloneMonthYear` | es, fr, pl, ru two-month view; vi, de, en | A lower-case stand-alone month where CLDR titlecases it, a capital where it does not, or a second month left lower case fails. | `audit:Calendar/behavior` | +| FR8–FR10, AR1 (calendars) | `Calendar.calendarSystems.test.tsx` ("lays out Aban 1405 with its calendar day numbers and labels", "keeps the fixed six-row grid", "reports a pick as a Gregorian ISO date", "steps one calendar month with Previous and Next", "pages one calendar month and clamps the day of the month", "bounds the month buttons by day", "shows ISO 8601 week numbers", "numbers Sunday-start rows like the same Gregorian rows", "writes day numbers and labels in the locale", "shows Adar I and Adar II as distinct months of a leap year", "steps a year from Adar I to Adar with Shift+PageDown, clamped", "keeps six rows for the five-day thirteenth month", "gives the thirteenth month only its rows with hasVariableRowCount", "steps a year to the same month with Shift+PageUp", "names the era of each month", "names each day by the month and day the grid shows when Intl disagrees", Gregorian year-paging cases); `Calendar.test.tsx` ("numbers each row by the ISO week of its Thursday" for Sunday, Monday, and Saturday starts and across a year end); `Calendar.ssr.test.tsx` server render and hydration with `Temporal` on both sides, neither side, and the browser only; `calendarSystem.test.ts` month structure at known dates, labels of every Gregorian-aligned calendar, and contiguity, length, and months-per-year invariants for every calendar from 1900 through 2100; `i18n/__tests__/calendarSystem.test.tsx` resolution order and the fallback without `Temporal`; real Chromium and Firefox runs with native `Temporal`, with a polyfill, and without `Temporal` | Persian, Hebrew leap year, Ethiopic thirteenth month, Japanese era change, Chinese leap month; `fa-IR` digits; Sunday and Saturday week starts; no `Temporal` | A month start, length, label, or step that differs from `Temporal`, a vanished leap month, a non-ISO value, a row not numbered by its Thursday's ISO week, or a crash or missing warning without `Temporal` fails. Evidence gap: no Safari or WebKit run. | `audit:Calendar/behavior` | | FR11 (hooks) | `calendarHooks.calendarSystems.test.tsx` ("matches the released output for %s" against a fixed copy of the Gregorian grid algorithm, "gives the same output with calendar gregory", "lays out Aban 1405 in the Persian calendar", "reads Hebrew leap-year months as Temporal numbers them", "reads the year numbers of the Buddhist and Minguo calendars", "ignores the provider calendar" for both hooks, "matches the released months and label in %s", "steps Persian months and labels them in the calendar", "steps through Adar I, Adar II, and the thirteenth month", "labels %s months as Calendar heads them", "feeds visibleCalendarMonths into useCalendarDays in %s", "fall back to Gregorian months and warn once"); the unchanged `useCalendarDays.test.ts` and `useCalendarNavigation.test.ts` | | FR12 (server) | `CalendarToday.ssr.test.tsx` (server markup with no today marker, a hidden grid, an empty month label and unavailable month buttons; no mismatch; the browser's month and today after hydration with no announcement; a two-month pick that keeps both months), `getInitialFocusDate.test.ts` ("waits for today when there is no focus date or value"), and the real-browser `CalendarTodayHydration.interaction.browser.spec.ts` over the Calendar Today Hydration fixture stories (server render on one date, hydration on the next) | -| FR2 (size) | `CalendarTextSize.interaction.browser.spec.ts` (an enlarged day number stays inside its day button; an enlarged weekday name stays inside its header and clear of the next; at twice the text size the calendar fits a 390px container; the default size keeps the element sizes) | — | — | `audit:Calendar/layout` | -| DD1 | `Calendar.test.tsx` ("displays day names", "uses the provider locale for weekday header names", "rotates localized day names by numeric weekday index", "shows abbreviated weekday names in a locale where all seven fit in four characters", "keeps short weekday names in %s, where an abbreviated name runs past four characters" for `pt-PT` and `pl-PL`, "shows the platform abbreviated names for a locale with no shipped weekday data" for `id-ID`, "shows the platform narrow names for an unshipped locale whose abbreviated names run past four characters" for `sw-KE`); `getWeekdayHeaderNames.test.ts`; `scripts/generate-cldr-weekdays.test.mjs` ("matches every generated locale to its pinned raw CLDR source", "picks abbreviated names only where all seven fit in four characters") | English; a locale whose abbreviated names are all within four characters, such as `fr`; a locale above it, such as `pt-PT` or `pl`; `weekStartsOn` rotation; with week numbers | A locale within the limit showing short names, a locale above it showing abbreviated names, a row mixing the two, or a name cut short fails. | `audit:Calendar/layout` | -| AR1 (browser) | `Calendar.a11y.test.tsx` and `Calendar.a11y.chromium.spec.ts` over the shared grid states | Every representative state | A lost grid name, role, or start neighbourhood fails; browser-owned outcomes are reported. | `audit:Calendar/accessibility` | -| ORD1, ORD2, PR1 | ORD1 and ORD2 are covered by the FR3–FR5 and AR1 rows. Evidence gap: no test asserts the absence of per-cell listeners | — | — | `audit:Calendar/behavior` | +| FR2 (size) | `CalendarTextSize.interaction.browser.spec.ts` (an enlarged day number stays inside its day button; an enlarged weekday name stays inside its header and clear of the next; at twice the text size the calendar fits a 390px container; the default size keeps the element sizes) | — | — | `audit:Calendar/layout` | +| DD1 | `Calendar.test.tsx` ("displays day names", "uses the provider locale for weekday header names", "rotates localized day names by numeric weekday index", "shows abbreviated weekday names in a locale where all seven fit in four characters", "keeps short weekday names in %s, where an abbreviated name runs past four characters" for `pt-PT` and `pl-PL`, "shows the platform abbreviated names for a locale with no shipped weekday data" for `id-ID`, "shows the platform narrow names for an unshipped locale whose abbreviated names run past four characters" for `sw-KE`); `getWeekdayHeaderNames.test.ts`; `scripts/generate-cldr-weekdays.test.mjs` ("matches every generated locale to its pinned raw CLDR source", "picks abbreviated names only where all seven fit in four characters") | English; a locale whose abbreviated names are all within four characters, such as `fr`; a locale above it, such as `pt-PT` or `pl`; `weekStartsOn` rotation; with week numbers | A locale within the limit showing short names, a locale above it showing abbreviated names, a row mixing the two, or a name cut short fails. | `audit:Calendar/layout` | +| AR1 (browser) | `Calendar.a11y.test.tsx` and `Calendar.a11y.chromium.spec.ts` over the shared grid states | Every representative state | A lost grid name, role, or start neighbourhood fails; browser-owned outcomes are reported. | `audit:Calendar/accessibility` | +| ORD1, ORD2, PR1 | ORD1 and ORD2 are covered by the FR3–FR5 and AR1 rows. Evidence gap: no test asserts the absence of per-cell listeners | — | — | `audit:Calendar/behavior` | ## Current-state impact @@ -318,12 +319,6 @@ button. pointer pick can leave it there (always when the picked day comes later in the grid), and when every day of that month becomes disabled it stays on a disabled day, so Tab can land on an unselected or disabled day. -- **Month buttons under reduced motion (FR6).** The Previous and Next buttons - scale on a press when the person prefers reduced motion, as `component:Button` - FR15 records, against `design:reduced-motion` DR1. -- **Month buttons at a bound (FR6).** Previous and Next become natively - disabled at `min` and `max`, so a keyboard user on the button that reaches the - bound loses focus, against `spec:AST-085` FR1 and FR4. ## Decision log diff --git a/packages/core/src/Calendar/Calendar.test.tsx b/packages/core/src/Calendar/Calendar.test.tsx index 2f4ce37dfec9d..97ebfe9271a04 100644 --- a/packages/core/src/Calendar/Calendar.test.tsx +++ b/packages/core/src/Calendar/Calendar.test.tsx @@ -2211,6 +2211,20 @@ describe('Calendar', () => { expect(nextButton).toHaveAttribute('aria-disabled', 'true'); }); + it('a month button that reaches the bound keeps focus and stays focusable', async () => { + const user = userEvent.setup(); + render(); + const next = getButton('Next month'); + await user.click(next); + // February holds max: the button is aria-disabled, focusable, and focused. + expect(next).toHaveAttribute('aria-disabled', 'true'); + expect(next).not.toHaveAttribute('disabled'); + expect(document.activeElement).toBe(next); + await user.keyboard('{Enter}'); + expect(screen.getByText(/February 2026/)).toBeInTheDocument(); + expect(document.activeElement).toBe(next); + }); + it('outside days are not clickable when hasOutsideDays is true', async () => { const user = userEvent.setup(); const handleChange = vi.fn(); diff --git a/packages/core/src/Calendar/__tests__/CalendarMonthButtonPress.interaction.browser.spec.ts b/packages/core/src/Calendar/__tests__/CalendarMonthButtonPress.interaction.browser.spec.ts new file mode 100644 index 0000000000000..c225e802aa952 --- /dev/null +++ b/packages/core/src/Calendar/__tests__/CalendarMonthButtonPress.interaction.browser.spec.ts @@ -0,0 +1,60 @@ +// Copyright (c) Meta Platforms, Inc. and affiliates. + +/** + * @file CalendarMonthButtonPress.interaction.browser.spec.ts + * @input The built default Calendar story in a real browser + * @output Proof that a held mouse press scales a month button with full + * motion and leaves it unscaled under reduced motion + * @position Interaction evidence for the Calendar month buttons' press in + * packages/core/src/Calendar + */ + +import {expect, test} from '@astryxdesign/a11y-spec/playwright'; +import { + DEFAULT_STORYBOOK_DIR, + serveStorybook, + type StaticServer, +} from '@astryxdesign/a11y-spec/storybook'; + +let storybook: StaticServer; + +test.beforeAll(async () => { + storybook = await serveStorybook( + process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR, + ); +}); + +test.afterAll(async () => { + await storybook?.close(); +}); + +for (const motion of ['no-preference', 'reduce'] as const) { + test(`a held press on a month button ${motion === 'reduce' ? 'does not scale it under reduced motion' : 'scales it'}`, async ({ + page, + }) => { + await page.emulateMedia({reducedMotion: motion}); + await page.goto( + `${storybook.origin}/iframe.html?id=core-calendar--default&viewMode=story`, + ); + const next = page.getByRole('button', {name: 'Next month'}); + await next.waitFor(); + const box = await next.boundingBox(); + if (box == null) { + throw new Error('no Next month button'); + } + await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2); + await page.mouse.down(); + // Let the press transition run to its end. + await page.waitForTimeout(400); + const transform = await next.evaluate( + button => getComputedStyle(button).transform, + ); + await page.mouse.up(); + if (motion === 'reduce') { + expect(['none', 'matrix(1, 0, 0, 1, 0, 0)']).toContain(transform); + } else { + expect(transform).not.toBe('none'); + expect(transform).not.toBe('matrix(1, 0, 0, 1, 0, 0)'); + } + }); +}