Skip to content

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

TypeScript

fix(Calendar): Shift+Page Up and Shift+Page Down move by a year (#9609)

nynexman446485afaa010ea7
diff --git a/.changeset/calendar-shift-page-year.md b/.changeset/calendar-shift-page-year.md
new file mode 100644
index 0000000000..d675edd693
--- /dev/null
+++ b/.changeset/calendar-shift-page-year.md
@@ -0,0 +1,11 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Calendar: Shift+Page Up and Shift+Page Down now move the focused day to the same date one year earlier or later, as in the WAI-ARIA date picker pattern, instead of one month. A February 29 lands on February 28 in a year without one. The year step follows the same rules as Page Up and Page Down: it changes nothing past `min` or `max`, and on a day that `dateConstraints` disables it focuses that month's first enabled day.
+
+`useGridFocus` now passes the key event to `onPageUp` and `onPageDown`, so a grid can read `event.shiftKey`; callbacks that take no argument keep working.
+
+Fixes #8947.
+
+@nynexman4464
diff --git a/docs/specs/components/Calendar/Calendar.spec.md b/docs/specs/components/Calendar/Calendar.spec.md
index d0b4f30273..c3a8bd5c0d 100644
--- a/docs/specs/components/Calendar/Calendar.spec.md
+++ b/docs/specs/components/Calendar/Calendar.spec.md
@@ -150,7 +150,9 @@ Consumer migration instructions belong in consumer docs and release notes.
ArrowLeft and ArrowRight move by a day following the reading direction
(`design:bidirectionality` DR6),
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;
+ week, PageUp and PageDown by a month, Shift+PageUp and Shift+PageDown by a
+ year (a named exception, as in the APG date picker dialog; a day the target
+ month lacks clamps to its last day), and Enter or Space picks the focused day;
an arrow skips a day disabled by a constraint and continues in the
same direction, crossing the month edge when it must; an arrow or Page key whose target
lies past `min` or `max` changes nothing and keeps focus where it is, and
@@ -205,16 +207,16 @@ 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"); 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` |
-| FR2 (size) | Evidence gap: no test asserts day-button size or text growth | — | — | `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` |
+| 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` |
+| FR2 (size) | Evidence gap: no test asserts day-button size or text growth | — | — | `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
diff --git a/packages/core/api-report.md b/packages/core/api-report.md
index c706431821..bbbdb53f33 100644
--- a/packages/core/api-report.md
+++ b/packages/core/api-report.md
@@ -5899,8 +5899,8 @@ interface UseGridFocusOptions
isCellFocusable?: (cell: HTMLElement) => boolean
onNavigateAfter?: (column: number, offset: number) => void
onNavigateBefore?: (column: number, offset: number) => void
- onPageDown?: () => void
- onPageUp?: () => void
+ onPageDown?: (event: React.KeyboardEvent) => void
+ onPageUp?: (event: React.KeyboardEvent) => void
interface UseGridFocusReturn<T extends HTMLElement = HTMLElement>
focusCell: (index: number) => void
focusFirst: () => void
diff --git a/packages/core/src/Calendar/Calendar.test.tsx b/packages/core/src/Calendar/Calendar.test.tsx
index 9b541e6b2e..09a2fed6c6 100644
--- a/packages/core/src/Calendar/Calendar.test.tsx
+++ b/packages/core/src/Calendar/Calendar.test.tsx
@@ -1127,6 +1127,118 @@ describe('Calendar', () => {
});
});
+ it('moves the focused day by a year with Shift+PageDown and Shift+PageUp', async () => {
+ const user = userEvent.setup();
+ render(<Calendar focusDate="2026-03-01" />);
+
+ getDayButton(15, 'March').focus();
+ await user.keyboard('{Shift>}{PageDown}{/Shift}');
+ await waitFor(() => {
+ expect(politeRegion()).toHaveTextContent('March 2027');
+ });
+ await waitFor(() => {
+ expect(document.activeElement).toHaveAttribute(
+ 'data-date',
+ '2027-03-15',
+ );
+ });
+
+ await user.keyboard('{Shift>}{PageUp}{/Shift}');
+ await waitFor(() => {
+ expect(politeRegion()).toHaveTextContent('March 2026');
+ });
+ await waitFor(() => {
+ expect(document.activeElement).toHaveAttribute(
+ 'data-date',
+ '2026-03-15',
+ );
+ });
+ });
+
+ it('a year from February 29 lands on February 28', async () => {
+ const user = userEvent.setup();
+ render(<Calendar focusDate="2024-02-01" />);
+
+ getDayButton(29, 'February', 2024).focus();
+ await user.keyboard('{Shift>}{PageDown}{/Shift}');
+ await waitFor(() => {
+ expect(document.activeElement).toHaveAttribute(
+ 'data-date',
+ '2025-02-28',
+ );
+ });
+ expect(screen.getByRole('grid')).toHaveAttribute(
+ 'aria-label',
+ 'February 2025',
+ );
+ });
+
+ it('a year step whose target lies past max changes nothing and keeps focus', async () => {
+ const user = userEvent.setup();
+ render(<Calendar focusDate="2026-03-01" max="2027-03-14" />);
+
+ getDayButton(15, 'March').focus();
+ await user.keyboard('{Shift>}{PageDown}{/Shift}');
+ expect(screen.getByRole('grid')).toHaveAttribute(
+ 'aria-label',
+ 'March 2026',
+ );
+ expect(document.activeElement).toBe(getDayButton(15, 'March'));
+ });
+
+ it("a year step onto a day disabled by a constraint focuses that month's first enabled day", async () => {
+ const user = userEvent.setup();
+ // March 1–19, 2027 disabled.
+ const noEarlyMarch2027 = (date: Date) =>
+ !(
+ date.getFullYear() === 2027 &&
+ date.getMonth() === 2 &&
+ date.getDate() < 20
+ );
+ render(
+ <Calendar
+ focusDate="2026-03-01"
+ dateConstraints={[noEarlyMarch2027]}
+ />,
+ );
+
+ getDayButton(15, 'March').focus();
+ await user.keyboard('{Shift>}{PageUp}{/Shift}');
+ await waitFor(() => {
+ expect(document.activeElement).toHaveAttribute(
+ 'data-date',
+ '2025-03-15',
+ );
+ });
+ await user.keyboard('{Shift>}{PageDown}{/Shift}');
+ await user.keyboard('{Shift>}{PageDown}{/Shift}');
+ await waitFor(() => {
+ expect(document.activeElement).toHaveAttribute(
+ 'data-date',
+ '2027-03-20',
+ );
+ });
+ });
+
+ it('in a two-month view a year step forward makes the target month the second one shown', async () => {
+ const user = userEvent.setup();
+ render(<Calendar focusDate="2026-01-01" numberOfMonths={2} />);
+
+ getDayButton(15).focus();
+ await user.keyboard('{Shift>}{PageDown}{/Shift}');
+ await waitFor(() => {
+ expect(document.activeElement).toHaveAttribute(
+ 'data-date',
+ '2027-01-15',
+ );
+ });
+ expect(
+ screen.getAllByRole('grid').map(g => g.getAttribute('aria-label')),
+ ).toEqual(['December 2026', 'January 2027']);
+ const grids = screen.getAllByRole('grid');
+ expect(grids[1].querySelectorAll('button[tabindex="0"]')).toHaveLength(1);
+ });
+
it("pages from the first of two months onto the right day, not the second grid's fallback", async () => {
const user = userEvent.setup();
render(<Calendar focusDate="2026-01-01" numberOfMonths={2} />);
diff --git a/packages/core/src/Calendar/Calendar.tsx b/packages/core/src/Calendar/Calendar.tsx
index 8575df14ff..69b9442840 100644
--- a/packages/core/src/Calendar/Calendar.tsx
+++ b/packages/core/src/Calendar/Calendar.tsx
@@ -107,8 +107,8 @@ import english from '../i18n/generated-english/Calendar/Calendar.generated';
registerEnglishFallback(english);
-/** How a month navigation moves the focused day: by its row offset in days, or by whole months. */
-type NavigationUnit = 'days' | 'months';
+/** How a month navigation moves the focused day: by its row offset in days, or by whole months or years. */
+type NavigationUnit = 'days' | 'months' | 'years';
/** Imperative handle for Calendar handleRef */
export interface CalendarHandle {
@@ -521,13 +521,14 @@ export function Calendar({ref, ...props}: CalendarProps) {
!(minDateForKeys && plainDateIsBefore(pd, minDateForKeys)) &&
!(maxDateForKeys && plainDateIsAfter(pd, maxDateForKeys));
let targetPd: PlainDate;
- if (unit === 'months') {
- // A page targets the same day of the month a month away (clamped to
- // that month's length). Past `min`/`max` nothing moves; a month with
- // no enabled day is no destination either, the same as an arrow with
- // no enabled day in its direction; a target disabled by a constraint
- // lands on that month's first enabled day instead.
- const candidate = plainDateAddMonths(currentPd, delta);
+ if (unit === 'months' || unit === 'years') {
+ // A page or a year step keeps the day of the month and clamps it to the
+ // target month's length. A month with no enabled day is no target, the
+ // same as for an arrow.
+ const candidate = plainDateAddMonths(
+ currentPd,
+ unit === 'years' ? delta * 12 : delta,
+ );
if (!inRange(candidate)) {
return;
}
@@ -964,20 +965,27 @@ function MonthGrid({
[getFocusedDate, onNavigateNext],
);
- // Handle PageUp/PageDown
- const handlePageUp = useCallback(() => {
- const focusedDate = getFocusedDate();
- if (focusedDate) {
- onNavigatePrevious?.(focusedDate, 1, 'months');
- }
- }, [getFocusedDate, onNavigatePrevious]);
+ // PageUp/PageDown move by a month, and with Shift by a year (APG date
+ // picker dialog).
+ const handlePageUp = useCallback(
+ (e: React.KeyboardEvent) => {
+ const focusedDate = getFocusedDate();
+ if (focusedDate) {
+ onNavigatePrevious?.(focusedDate, 1, e.shiftKey ? 'years' : 'months');
+ }
+ },
+ [getFocusedDate, onNavigatePrevious],
+ );
- const handlePageDown = useCallback(() => {
- const focusedDate = getFocusedDate();
- if (focusedDate) {
- onNavigateNext?.(focusedDate, 1, 'months');
- }
- }, [getFocusedDate, onNavigateNext]);
+ const handlePageDown = useCallback(
+ (e: React.KeyboardEvent) => {
+ const focusedDate = getFocusedDate();
+ if (focusedDate) {
+ onNavigateNext?.(focusedDate, 1, e.shiftKey ? 'years' : 'months');
+ }
+ },
+ [getFocusedDate, onNavigateNext],
+ );
// Grid focus navigation.
//
diff --git a/packages/core/src/hooks/useGridFocus.doc.mjs b/packages/core/src/hooks/useGridFocus.doc.mjs
index 0d1e009021..a97adfad3d 100644
--- a/packages/core/src/hooks/useGridFocus.doc.mjs
+++ b/packages/core/src/hooks/useGridFocus.doc.mjs
@@ -67,16 +67,16 @@ export const docs = {
},
{
name: 'options.onPageUp',
- type: '() => void',
+ type: '(event: React.KeyboardEvent) => void',
description:
- 'Callback for Page Up key (e.g., navigate to previous month in calendars).',
+ 'Callback for Page Up key (e.g., navigate to previous month in calendars). Receives the key event, so `event.shiftKey` can select a larger step, such as a year.',
required: false,
},
{
name: 'options.onPageDown',
- type: '() => void',
+ type: '(event: React.KeyboardEvent) => void',
description:
- 'Callback for Page Down key (e.g., navigate to next month in calendars).',
+ 'Callback for Page Down key (e.g., navigate to next month in calendars). Receives the key event, so `event.shiftKey` can select a larger step, such as a year.',
required: false,
},
{
@@ -172,9 +172,9 @@ export const docsDense = {
'options.onNavigateAfter':
'callback when navigation would go after last cell. Receives column index + offset.',
'options.onPageUp':
- 'callback for Page Up key (e.g. navigate to previous month in calendars).',
+ 'callback for Page Up key (e.g. previous month in calendars); receives the key event (shiftKey → e.g. a year).',
'options.onPageDown':
- 'callback for Page Down key (e.g. navigate to next month in calendars).',
+ 'callback for Page Down key (e.g. next month in calendars); receives the key event (shiftKey → e.g. a year).',
'options.hasRovingTabIndex':
'own a single roving tab stop across the grid (one focus target tabindex=0, rest -1); repaired on render + moved with arrows. Attach handleFocus to onFocus. default false.',
},
diff --git a/packages/core/src/hooks/useGridFocus.test.tsx b/packages/core/src/hooks/useGridFocus.test.tsx
index 28fbc20c84..c4a2a33d09 100644
--- a/packages/core/src/hooks/useGridFocus.test.tsx
+++ b/packages/core/src/hooks/useGridFocus.test.tsx
@@ -9,7 +9,7 @@
* SYNC: When useGridFocus.ts changes, update tests to match new behavior
*/
-import {describe, it, expect} from 'vitest';
+import {describe, it, expect, vi} from 'vitest';
import {render, screen, fireEvent} from '@testing-library/react';
import {useGridFocus} from './useGridFocus';
@@ -163,3 +163,21 @@ describe('useGridFocus RTL auto-detection (WCAG 1.3.2)', () => {
expect(screen.getByTestId('cell-3')).toHaveFocus();
});
});
+
+describe('useGridFocus page keys', () => {
+ it('passes the key event to onPageUp and onPageDown', () => {
+ const onPageUp = vi.fn();
+ const onPageDown = vi.fn();
+ render(<Grid seed={4} onPageUp={onPageUp} onPageDown={onPageDown} />);
+ const cell = screen.getByTestId('cell-4');
+ cell.focus();
+ fireEvent.keyDown(cell, {key: 'PageUp', shiftKey: true});
+ fireEvent.keyDown(cell, {key: 'PageDown'});
+ expect(onPageUp).toHaveBeenCalledWith(
+ expect.objectContaining({key: 'PageUp', shiftKey: true}),
+ );
+ expect(onPageDown).toHaveBeenCalledWith(
+ expect.objectContaining({key: 'PageDown', shiftKey: false}),
+ );
+ });
+});
diff --git a/packages/core/src/hooks/useGridFocus.ts b/packages/core/src/hooks/useGridFocus.ts
index 5332f55382..5e929dab06 100644
--- a/packages/core/src/hooks/useGridFocus.ts
+++ b/packages/core/src/hooks/useGridFocus.ts
@@ -80,14 +80,16 @@ export interface UseGridFocusOptions {
onNavigateAfter?: (column: number, offset: number) => void;
/**
- * Callback for Page Up key (e.g., previous month).
+ * Callback for Page Up key (e.g., previous month). It receives the key
+ * event, so `event.shiftKey` can select a larger step, such as a year.
*/
- onPageUp?: () => void;
+ onPageUp?: (event: React.KeyboardEvent) => void;
/**
- * Callback for Page Down key (e.g., next month).
+ * Callback for Page Down key (e.g., next month). It receives the key
+ * event, so `event.shiftKey` can select a larger step, such as a year.
*/
- onPageDown?: () => void;
+ onPageDown?: (event: React.KeyboardEvent) => void;
/**
* Roving-tabindex ownership. When true, the hook manages a single tab stop
@@ -157,7 +159,8 @@ export interface UseGridFocusReturn<T extends HTMLElement = HTMLElement> {
* - End: Move to last cell in row
* - Ctrl+Home: Move to first cell in grid
* - Ctrl+End: Move to last cell in grid
- * - Page Up/Down: Custom callbacks (e.g., month navigation)
+ * - Page Up/Down: Custom callbacks that receive the key event (e.g., month
+ * navigation, or a year with Shift)
*
* The hook enumerates ALL cells matched by `cellSelector` in DOM order and
* computes row/column over that full set, preserving the true grid geometry
@@ -571,11 +574,11 @@ export function useGridFocus<T extends HTMLElement = HTMLElement>(
break;
case 'PageUp':
- onPageUp?.();
+ onPageUp?.(e);
break;
case 'PageDown':
- onPageDown?.();
+ onPageDown?.(e);
break;
default: