Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(Calendar): arrow keys skip borrowed adjacent-month days and cross into their month (#7511)

Cindy Zhangd21d77c54118
diff --git a/.changeset/calendar-skip-outside-days.md b/.changeset/calendar-skip-outside-days.md
new file mode 100644
index 0000000000..fb7a158636
--- /dev/null
+++ b/.changeset/calendar-skip-outside-days.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] `Calendar`: the arrow keys, Home and End no longer land on a borrowed adjacent-month day (shown dimmed, exposed as disabled, and inert to Enter, Space and clicks). An arrow crosses into that month and focuses the real day there, including across the two grids of a two-month view; Home and End stop at the first or last enabled day of the week in the month shown. A month with no enabled day holds no Tab stop.
+
+@cixzhang
diff --git a/packages/core/src/Calendar/Calendar.spec.md b/packages/core/src/Calendar/Calendar.spec.md
index 6e76ce6ba8..0fc505646c 100644
--- a/packages/core/src/Calendar/Calendar.spec.md
+++ b/packages/core/src/Calendar/Calendar.spec.md
@@ -96,7 +96,7 @@ intentional decision. A `current` contract contains no unresolved rows.
| FR2 | At most one day button in each month's grid holds `tabIndex={0}`; every other day button in that grid is `-1`. | shipped `useGridFocus` behavior; Grid accessibility contract (pending) | verify |
| FR3 | A disabled day (outside bounds or rejected by a constraint) stays in the grid, is exposed as disabled, and cannot be picked. | shipped source and focused tests | verify |
| 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 | verify |
-| FR5 | Moving the focused day across a month boundary navigates the visible month so the focused day stays visible, in one month or two; an arrow can also land on a borrowed adjacent-month day, which is exposed `aria-disabled` and cannot be picked. | shipped source and focused tests | verify |
+| 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 | verify |
### Allowed variation
@@ -136,8 +136,7 @@ intentional decision. A `current` contract contains no unresolved rows.
when disabled; one day button holds the Tab stop — the selected day in
`single` mode when it is in that month and enabled, else today when it is in
that month and enabled, else the month's first enabled day; a month with no
- enabled day gives it to the grid's first day button that is not natively
- disabled, which can be a borrowed adjacent-month day, or to none.
+ enabled day has no Tab stop.
ArrowLeft and ArrowRight move by a day following the reading direction,
ArrowUp and ArrowDown by a week, Home and End to the first and last enabled day of the
week, PageUp and PageDown by a month, and Enter or Space picks the focused day;
@@ -147,9 +146,6 @@ intentional decision. A `current` contract contains no unresolved rows.
so does an arrow whose direction has no enabled day within a year; a page
onto a day disabled by a constraint focuses that month's first enabled day
instead, and changes nothing when that month has no enabled day.
- Implementation gap: the arrow keys, Home and End can focus a borrowed
- adjacent-month day that is `aria-disabled`, because cell focusability checks
- only native `disabled`.
## Design relationships
@@ -192,10 +188,10 @@ 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"), 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. | `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"); the at-most-one-Tab-stop-per-month (FR2), Home/End and activation keys on Calendar itself under the Grid accessibility contract (`internal/a11y-spec`, pending) | 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` |
+| 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"), 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. | `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"); 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 at-most-one-Tab-stop-per-month (FR2), Home/End and activation keys on Calendar itself under the Grid accessibility contract (`internal/a11y-spec`, pending) | 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` |
## Decision log
diff --git a/packages/core/src/Calendar/Calendar.test.tsx b/packages/core/src/Calendar/Calendar.test.tsx
index 30f0c9ca88..7757145186 100644
--- a/packages/core/src/Calendar/Calendar.test.tsx
+++ b/packages/core/src/Calendar/Calendar.test.tsx
@@ -9,7 +9,6 @@
* SYNC: When Calendar.tsx changes, update tests accordingly
*/
-import {useState} from 'react';
import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
import {act, render, screen, within, waitFor} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
@@ -19,6 +18,7 @@ import {
getAllInjectedCss,
} from '../__tests__/forcedColors';
import * as stylex from '@stylexjs/stylex';
+import {useState} from 'react';
import {Calendar} from './Calendar';
import type {CalendarHandle, ISODateString, DateRange} from './Calendar';
import {calendarStyles} from './styles';
@@ -40,6 +40,24 @@ function politeRegion(): HTMLElement | null {
return document.querySelector('[data-astryx-live-region="polite"]');
}
+/** A controlled Calendar whose owner follows the focus-date changes. */
+function ControlledFocusCalendar({
+ onFocusDateChange,
+}: {
+ onFocusDateChange: (iso: string) => void;
+}) {
+ const [focusDate, setFocusDate] = useState<ISODateString>('2026-01-01');
+ return (
+ <Calendar
+ focusDate={focusDate}
+ onFocusDateChange={iso => {
+ onFocusDateChange(iso);
+ setFocusDate(iso);
+ }}
+ />
+ );
+}
+
/**
* Helper to find a day button by its day number.
* Day buttons are native <button> elements with aria-labels like
@@ -1025,14 +1043,68 @@ describe('Calendar', () => {
expect(document.activeElement).not.toHaveAttribute('aria-disabled');
});
- it('pages from a borrowed adjacent-month day onto the real day in the month already shown', async () => {
+ it('skips borrowed adjacent-month days and crosses into their month instead', async () => {
const user = userEvent.setup();
render(<Calendar focusDate="2026-01-01" />);
- // Home from January 1 lands on the borrowed December 28 in the first row.
+ // January 1, 2026 is a Thursday: the first row borrows December 28–31.
getDayButton(1).focus();
- await user.keyboard('{Home}');
- expect(document.activeElement).toHaveAttribute('data-date', '2025-12-28');
+ await user.keyboard('{ArrowLeft}');
+ await waitFor(() => {
+ expect(politeRegion()).toHaveTextContent('December 2025');
+ });
+ await waitFor(() => {
+ expect(document.activeElement).toHaveAttribute(
+ 'data-date',
+ '2025-12-31',
+ );
+ });
+ expect(document.activeElement).not.toHaveAttribute('aria-disabled');
+ });
+
+ it('in a two-month view an arrow from the first month lands on the real day, never a borrowed one', async () => {
+ const user = userEvent.setup();
+ render(<Calendar focusDate="2026-01-01" numberOfMonths={2} />);
+
+ // January 28 (Wednesday) → ArrowDown → February 4, shown in the second
+ // grid: no page, and never the first day of a new month.
+ getDayButton(28).focus();
+ await user.keyboard('{ArrowDown}');
+ await waitFor(() => {
+ expect(document.activeElement).toHaveAttribute(
+ 'data-date',
+ '2026-02-04',
+ );
+ });
+ expect(document.activeElement).not.toHaveAttribute('aria-disabled');
+ // No page happened: January is still the first grid.
+ expect(screen.getAllByRole('grid')).toHaveLength(2);
+ expect(getDayButton(28)).toBeInTheDocument();
+
+ // February 24 (Tuesday) → ArrowDown → March 3: the view pages so March
+ // is the second month, and focus lands on the real March 3.
+ getDayButton(24, 'February').focus();
+ await user.keyboard('{ArrowDown}');
+ await waitFor(() => {
+ expect(document.activeElement).toHaveAttribute(
+ 'data-date',
+ '2026-03-03',
+ );
+ });
+ expect(document.activeElement).not.toHaveAttribute('aria-disabled');
+ });
+
+ it('pages from a borrowed adjacent-month day onto the real day in the month already shown', async () => {
+ const user = userEvent.setup();
+ render(<Calendar focusDate="2026-01-01" />);
+
+ // A pointer can still land on the borrowed December 28 in the first
+ // row (the keyboard skips it).
+ const borrowed = document.querySelector<HTMLElement>(
+ 'button[data-date="2025-12-28"]',
+ )!;
+ borrowed.focus();
+ expect(document.activeElement).toBe(borrowed);
// PageDown targets January 28, which January's grid already shows: no
// month change, focus moves there and never to a borrowed copy.
@@ -1150,6 +1222,56 @@ describe('Calendar', () => {
expect(onChange).not.toHaveBeenCalled();
});
+ it('an arrow toward a direction where every remaining day is disabled changes nothing', async () => {
+ const user = userEvent.setup();
+ // Only January 2026 is enabled: nothing after January 31 can take focus
+ // (the walk looks a year ahead, so the constraint pins the year too).
+ const januaryOnly = (date: Date) =>
+ date.getFullYear() === 2026 && date.getMonth() === 0;
+ render(
+ <Calendar focusDate="2026-01-01" dateConstraints={[januaryOnly]} />,
+ );
+ getDayButton(28).focus();
+ await user.keyboard('{ArrowDown}');
+ // No month change, no focus drop: still January 28.
+ expect(screen.getByRole('grid')).toHaveAttribute(
+ 'aria-label',
+ 'January 2026',
+ );
+ expect(document.activeElement).toBe(getDayButton(28));
+ });
+
+ it('an arrow resolves the next enabled day in its direction first: weekdays-only ArrowRight from Friday January 30 reaches Monday February 2', async () => {
+ const user = userEvent.setup();
+ const weekdaysOnly = (date: Date) =>
+ date.getDay() !== 0 && date.getDay() !== 6;
+ render(
+ <Calendar focusDate="2026-01-01" dateConstraints={[weekdaysOnly]} />,
+ );
+ getDayButton(30).focus();
+ await user.keyboard('{ArrowRight}');
+ await waitFor(() => {
+ expect(document.activeElement).toHaveAttribute(
+ 'data-date',
+ '2026-02-02',
+ );
+ });
+ // The month paged with it: February's grid is the one shown.
+ expect(screen.getByRole('grid')).toHaveAttribute(
+ 'aria-label',
+ 'February 2026',
+ );
+ });
+
+ it('an arrow whose next day in range does not exist changes nothing: max January 25, ArrowDown from January 21', async () => {
+ const user = userEvent.setup();
+ render(<Calendar focusDate="2026-01-01" max="2026-01-25" />);
+ getDayButton(21).focus();
+ await user.keyboard('{ArrowDown}');
+ expect(politeRegion()?.textContent ?? '').not.toContain('February 2026');
+ expect(document.activeElement).toBe(getDayButton(21));
+ });
+
it('a controlled owner that refuses the month change leaves no stale target to steal focus or Enter later', async () => {
const user = userEvent.setup();
const onChange = vi.fn();
@@ -1572,21 +1694,23 @@ describe('Calendar', () => {
const user = userEvent.setup();
const handleFocusChange = vi.fn();
- render(
- <Calendar focusDate="2026-01-01" onFocusDateChange={handleFocusChange} />,
- );
+ render(<ControlledFocusCalendar onFocusDateChange={handleFocusChange} />);
// Focus Jan 28
const day28 = getDayButton(28);
await user.click(day28);
day28.focus();
- // Press ArrowDown — should move to Feb 4 (+7 days), not Feb 28
+ // Press ArrowDown — should move to Feb 4 (+7 days), not Feb 28. The
+ // borrowed February row in January's grid is skipped; the grid navigates
+ // to February and focuses the real day there.
await user.keyboard('{ArrowDown}');
- // After navigation, Feb 4 should be focused
- const focusedElement = document.activeElement;
- expect(focusedElement).toHaveAttribute('data-date', '2026-02-04');
+ expect(handleFocusChange).toHaveBeenCalledWith('2026-02-01');
+ await waitFor(() => {
+ expect(document.activeElement).toHaveAttribute('data-date', '2026-02-04');
+ });
+ expect(document.activeElement).not.toHaveAttribute('aria-disabled');
});
it('ArrowDown lands on the same weekday +7 days even when earlier days are disabled (complex-2)', async () => {
@@ -1645,9 +1769,7 @@ describe('Calendar', () => {
const user = userEvent.setup();
const handleFocusChange = vi.fn();
- render(
- <Calendar focusDate="2026-01-01" onFocusDateChange={handleFocusChange} />,
- );
+ render(<ControlledFocusCalendar onFocusDateChange={handleFocusChange} />);
const day28 = getDayButton(28);
await user.click(day28);
@@ -1658,7 +1780,10 @@ describe('Calendar', () => {
await user.keyboard('{ArrowDown}');
// Feb 4 (+7 days) — resolved via data-date despite the unparseable label.
- expect(document.activeElement).toHaveAttribute('data-date', '2026-02-04');
+ expect(handleFocusChange).toHaveBeenCalledWith('2026-02-01');
+ await waitFor(() => {
+ expect(document.activeElement).toHaveAttribute('data-date', '2026-02-04');
+ });
});
it('prev button is disabled when focusDate month contains min', () => {
diff --git a/packages/core/src/Calendar/Calendar.tsx b/packages/core/src/Calendar/Calendar.tsx
index d9d6ad1f08..9726349a8e 100644
--- a/packages/core/src/Calendar/Calendar.tsx
+++ b/packages/core/src/Calendar/Calendar.tsx
@@ -984,8 +984,15 @@ function MonthGrid({
} = useGridFocus<HTMLDivElement>({
columns: 7,
cellSelector: '[role="gridcell"]',
+ // A borrowed adjacent-month day is exposed aria-disabled (its click does
+ // nothing, but it can still take pointer focus) and may also be natively
+ // disabled by bounds or a constraint; the keyboard skips it either way
+ // and crosses into that month through the grid edge instead, so focus
+ // lands on the real day in the month now shown (FR5).
isCellFocusable: cell =>
- cell.querySelector('button:not([disabled])') !== null,
+ cell.querySelector(
+ 'button:not([disabled]):not([aria-disabled="true"])',
+ ) !== null,
getFocusTarget: cell => cell.querySelector<HTMLElement>('button'),
hasRovingTabIndex: true,
onNavigateBefore: handleNavigatePrevious,