Skip to content

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

TypeScript

fix(DateInput): a focused sheet month arrow that hides at the range end hands focus on first (#10231)

Cindy Zhang2bbaeada805d
diff --git a/.changeset/touch-date-month-arrow-focus.md b/.changeset/touch-date-month-arrow-focus.md
new file mode 100644
index 0000000000..96cd3d5a30
--- /dev/null
+++ b/.changeset/touch-date-month-arrow-focus.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] DateInput's touch sheet keeps keyboard focus when the month reaches the end of the range, by an arrow press or a swipe, while a month arrow holds focus. That arrow hides there, so focus now moves first to the other month arrow, or to the month-and-year button when both arrows hide. Before, focus fell to the page.
+
+@cixzhang
diff --git a/docs/specs/components/DateInput/DateInput.spec.md b/docs/specs/components/DateInput/DateInput.spec.md
index 3be5ebdc23..3a199400fd 100644
--- a/docs/specs/components/DateInput/DateInput.spec.md
+++ b/docs/specs/components/DateInput/DateInput.spec.md
@@ -185,6 +185,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| FR19 | The bottom-sheet calendar's weekday row MUST show the weekday names `component:Calendar` DD1 sets for the provider locale, in the order of the panes' day columns (`weekStartsOn`), so both pickers label a locale's columns alike. |
| FR20 | The pointer field reads and writes typed dates in the resolved calendar (`spec:AST-111` FR2), and its Calendar shows that calendar. It reads the dates `Intl.DateTimeFormat` writes for the locale and calendar, in any Unicode decimal digits and with month and era names of the locale and English; in the Gregorian calendar, text that matches none of these forms, or that these forms read as a date the calendar does not have, still commits on Enter or blur when `parseDateInput` reads it, so `13/5/2026` in `en-US` commits as 13 May 2026 (`spec:AST-111` FR9). A typed year is a year of the calendar (`spec:AST-111` FR10). It rejects a date the calendar does not have and never adjusts it; a typed date outside `min`, `max`, or `dateConstraints` shows and announces an out-of-range error that writes the bounds in the calendar, and Enter or blur keeps both kinds of rejected text so the person can correct it, while unreadable text reverts (`spec:AST-111` FR11). While a person types, `onChange` fires only for complete input, at most once for each distinct value in one typing session, and a one-digit day stays open until another digit, Enter, or blur, so a day the month lacks is never reported as another date; a two-digit year and input without a year commit on Enter or blur, in every calendar system, and a year of one or three digits is not a date: like other text the field cannot finish, Enter or blur keeps it and shows the unreadable message as the field status (`spec:AST-111` FR12, AR3). Each rejection is announced once: a shown status announces itself, and the field's alert carries only a rejection that no status shows. `date`, `date_long`, and `date_weekday` write the committed text in the calendar and read back as the same date; `system_date` stays Gregorian ISO and the field reads ISO input with it (`spec:AST-111` FR13). Text from a custom `format` function that the field cannot read back cannot be re-committed after an edit (`spec:AST-111` FR14). Values stay Gregorian ISO dates (`spec:AST-111` FR3). | `spec:AST-111` FR3, FR9–FR14; current source; parser, round-trip, and calendar typed-entry tests |
| FR21 | With a calendar other than `gregory` or `iso8601`, every presentation that would show the native control — `adaptive-native`, the default, deprecated `touch` and `always`, and an explicit `native` — shows the popover on a fine pointer and the bottom sheet on a coarse pointer, because the native control is Gregorian (`spec:AST-111` FR15). An explicit `native` also warns once in development. The bottom sheet shows months of the calendar: each scroller pane lays out one calendar month with calendar labels and day names and the locale's digits, as `component:Calendar` shows it, and every pane keeps the six-row height, including the five- or six-day thirteenth month of the Coptic and Ethiopic calendars. The month wheel lists the months of the selected calendar year, leap months by name; a year change keeps the month when the new year has it and otherwise moves to its common counterpart (Adar I becomes Adar); year labels carry the era where the calendar has one, such as `令和8`, and a year whose first and last days fall in different eras keeps one row, labeled with the era year of the date the wheels show: that year, the selected month, and the day the picker keeps, clamped to the month, else the month's first day. So 2019 reads `平成31` with January selected and `令和元` with July, and the row's text and accessible name change as the month wheel turns, while its size stays the same. The month and year heading takes its era from the same date when the shown month spans an era change, so January 1989 reads `昭和64年1月` for a kept day of 3; every other heading names the era of the month's middle day. A pane's grid name always takes the era of its month's middle day, so that pane reads `平成元年1月`. The closed sheet field writes the committed text in the calendar (`spec:AST-111` FR16). Values stay Gregorian ISO dates (`spec:AST-111` FR3). | `spec:AST-111` FR3, FR15, FR16; current source; calendar presentation, touch calendar, and no-`Temporal` tests |
+| FR22 | In the touch sheet, a month arrow at the range end is hidden; if it held focus, focus moves first to the other month arrow, or to the month-and-year button when both are hidden (`spec:AST-085/FR4`). | `spec:AST-085/FR4`; current source and sheet arrow tests |
### Allowed variation
@@ -417,6 +418,7 @@ clear-glyph target of its own.
| FR19 | `DateInputTouch.test.tsx` "labels the columns with three-letter weekday names", "labels the columns in %s with the same names as the Calendar header" for `fr-FR`, `pt-PT`, `pl-PL`, and `id-ID`, "rotates the weekday header with weekStartsOn" | English; a locale within Calendar DD1's four-character limit; locales above it; a locale with no shipped weekday data; `weekStartsOn` rotation | A weekday row that differs from the Calendar header names for the same locale, or that does not rotate with `weekStartsOn`, fails. | — |
| FR20, AR3, AR9 | `calendarDateParser.test.ts` reading, year, rejection-kind, completeness, committed-text, and calendar-name cases; `calendarDateParser.roundtrip.test.ts` committed text and format hint of every calendar in its native locale, English, and Swedish, sampled from 1900 through 2100; `DateInput.calendar.test.tsx` ("reports one Persian date typed in Persian digits, only when complete", "reads a plain Adar in a Hebrew leap year as Adar II", "reads Japanese era dates and rejects a year outside its era", "rejects a date the calendar does not have and keeps it on blur", "shows an out-of-range error with the bounds in the calendar", "announces a different message for each kind of rejection", "fires once for a day-first date typed one key at a time", "commits Gregorian text that only parseDateInput reads, on blur only", "commits a day-first date that does not exist month-first, on blur only", "commits a month-first date that does not exist day-first, on blur", "never falls back to a month-first reading in a day-first locale", "keeps a one-digit year on %s and announces it as invalid", "reports no date while %s %s text grows to a day the month lacks", "reports a retyped date again after the caller keeps its value", "still rejects a Gregorian date that does not exist in either order", "never reads a date that does not exist in another calendar with parseDateInput", "shows a format hint in the empty focused field", "shows a caller placeholder instead of the format hint", "uses max when max is before today", "uses min when min is after today", "uses the nearest weekday when today is a disabled Saturday", "names the calendar in the description", "names no calendar when the field uses the provider calendar", "names the Gregorian calendar inside a Persian provider", "names no calendar for an iso8601 field in a Gregorian provider", "names the Persian calendar without a provider calendar"); real Chromium and Firefox typing with native `Temporal`, a polyfill, and no `Temporal` | Persian digits, Hebrew leap year, Japanese era change, Buddhist bounds, partial input, Gregorian day-first typing, a one-digit Gregorian year, no `Temporal` | A typed date reported before it is complete, an adjusted date, a failed round trip, Gregorian text that FR20 says commits failing to commit on blur, a one-digit year that commits or reverts silently, a rejection announced twice, a shared rejection message, a missing hint, a hint that replaces a caller placeholder, a hint example the field rejects, a calendar description that is missing or that repeats the provider's calendar, or a non-ISO value fails. Evidence gap: no WebKit run; no server render and hydrate test. | `audit:DateInput/behavior` |
| FR21 | `DateInput.calendarPresentation.test.tsx` (every presentation and deprecated `nativePicker` value in Gregorian and Persian on fine and coarse pointers; "warns once when an explicit native cannot show the calendar"); `DateInputTouch.calendar.test.tsx` ("lays out a Persian month with its days, labels and locale digits", "shows Adar I and Adar II as separate months in a Hebrew leap year", "keeps six rows for the Ethiopic thirteenth month", "lists 13 months in a Hebrew leap year and 12 in a common year", "labels Japanese years with their era", and the month-model round trips); `calendarSystem.test.ts` `formatCalendarYearLabel` and `calendarYearSpansEras` cases (2019 in January and May, 1989 on January 3 and 22, 1926, 1912, and 2020); `DateInputTouch.calendar.test.tsx` "names the era of the shown month for a year with an era change" and the split-month heading cases (January 3, 1989; December 26, 1926); `calendarSystem.test.ts` `formatCalendarMonthLabel` kept-day cases; `DateInput.noTemporal.test.tsx`; real Chromium, Firefox, and WebKit bottom sheets and popovers with native `Temporal`, a polyfill, and no `Temporal` | Persian, Hebrew leap and common years, Ethiopic thirteenth month, Japanese eras, no `Temporal` | A native date control for a non-Gregorian calendar, a wheel with 12 months for a 13-month year, a pane of another height, a lost leap month, a missing era, a year with an era change labeled with an era other than that of the shown date, or a non-ISO value fails | `audit:DateInput/behavior` |
+| FR22 | `DateInputTouch.test.tsx` "moves focus to the other arrow when the focused arrow reaches the end of the range and hides" and "moves focus to the other arrow when a swipe reaches the end of the range while an arrow holds focus" | Sheet month arrows at the first and last month of a range | Focus left on a hidden arrow, or dropped to the document body, fails. | `audit:DateInput/behavior` |
| Theming anatomy | `DateInput.test.tsx` clear-icon and calendar-toggle icon theme-target cases; `themingTargets.test.ts`; `scripts/check-knowledge.mjs` | Toggle, clear glyph, disabled root | A missing or moved target, or a stale anatomy mapping, fails. | `audit:DateInput/theming` |
## Current-state impact
diff --git a/packages/core/src/DateInput/DateInputTouch.test.tsx b/packages/core/src/DateInput/DateInputTouch.test.tsx
index 9024ebce7b..344ae40d1b 100644
--- a/packages/core/src/DateInput/DateInputTouch.test.tsx
+++ b/packages/core/src/DateInput/DateInputTouch.test.tsx
@@ -1041,6 +1041,58 @@ describe('DateInput — calendar surface', () => {
}
});
+ it('moves focus to the other arrow when the focused arrow reaches the end of the range and hides', () => {
+ renderAndOpen(
+ <Controlled initial="2026-03-10" min="2026-02-01" max="2026-04-30" />,
+ );
+ const previous = screen.getByRole('button', {name: 'Previous month'});
+ act(() => previous.focus());
+ fireEvent.click(previous);
+ // February is the first month: the arrow hides, and focus stays in the
+ // sheet, on the other arrow.
+ expect(screen.getByRole('button', {name: 'Next month'})).toHaveFocus();
+
+ const next = screen.getByRole('button', {name: 'Next month'});
+ fireEvent.click(next);
+ fireEvent.click(next);
+ // April is the last month.
+ expect(screen.getByRole('button', {name: 'Previous month'})).toHaveFocus();
+ });
+
+ it('moves focus to the other arrow when a swipe reaches the end of the range while an arrow holds focus', async () => {
+ await withLayout(async () => {
+ render(
+ <Controlled initial="2026-03-10" min="2026-01-01" max="2026-04-30" />,
+ );
+ fireEvent.click(field());
+ const previous = screen.getByRole('button', {name: 'Previous month'});
+ act(() => previous.focus());
+ fireEvent.click(previous);
+ // February: the arrow is still shown, and keeps focus.
+ expect(
+ screen.getByRole('button', {name: 'Previous month'}),
+ ).toHaveFocus();
+ const scroller = document.querySelector<HTMLElement>(
+ '[data-scroller="months"]',
+ )!;
+ // A finger takes the scroller from the steer, then swipes to January,
+ // the first month: Previous month hides.
+ const touchStart = new Event('touchstart', {bubbles: true});
+ const point = {identifier: 1, clientX: 100, clientY: 100};
+ Object.defineProperties(touchStart, {
+ touches: {value: [point]},
+ targetTouches: {value: [point]},
+ changedTouches: {value: [point]},
+ });
+ scroller.dispatchEvent(touchStart);
+ scroller.scrollLeft = 0;
+ fireEvent.scroll(scroller);
+ await waitFor(() =>
+ expect(screen.getByRole('button', {name: 'Next month'})).toHaveFocus(),
+ );
+ });
+ });
+
it('shows both arrows when there is somewhere to go in each direction', () => {
renderAndOpen(
<Controlled initial="2026-03-10" min="2026-01-01" max="2026-12-31" />,
diff --git a/packages/core/src/DateInput/TouchDateField.tsx b/packages/core/src/DateInput/TouchDateField.tsx
index 5f90e8b227..4d8996f552 100644
--- a/packages/core/src/DateInput/TouchDateField.tsx
+++ b/packages/core/src/DateInput/TouchDateField.tsx
@@ -58,6 +58,8 @@ import {
useState,
useTransition,
} from 'react';
+import {flushSync} from 'react-dom';
+import {moveFocusLeftBehind, noteFocusWithin} from '../utils/focusReturn';
import * as stylex from '@stylexjs/stylex';
import {inputDisabledFocusStyles} from '../Field/inputDisabledFocus';
import {BottomSheet} from '../BottomSheet';
@@ -679,6 +681,9 @@ export function TouchDateField({
);
const [isWheelOpen, setIsWheelOpen] = useState(false);
const scrollerHandleRef = useRef<MonthScrollerHandle | null>(null);
+ const previousArrowRef = useRef<HTMLButtonElement | null>(null);
+ const nextArrowRef = useRef<HTMLButtonElement | null>(null);
+ const monthYearButtonRef = useRef<HTMLButtonElement | null>(null);
// Pending focus handoff from the clear button; see handleClear.
const clearFocusTimerRef = useRef<number | null>(null);
// Releases the focus timer on unmount.
@@ -896,6 +901,55 @@ export function TouchDateField({
[monthIndex, minMonthIndex, maxMonthIndex],
);
+ // An arrow at the range end hides, and a hidden element loses focus. So
+ // when a move to `target` hides the focused arrow, focus moves to the other
+ // arrow, or to the month-and-year button when both hide. The move renders
+ // first, because in a two-month range the other arrow is hidden until then.
+ const moveMonth = useCallback(
+ (target: number, move: () => void) => {
+ const previousHides = target <= minMonthIndex;
+ const nextHides = target >= maxMonthIndex;
+ const previousArrow = previousArrowRef.current;
+ const nextArrow = nextArrowRef.current;
+ const focusOnPrevious = previousHides
+ ? noteFocusWithin(previousArrow)
+ : null;
+ const focusOnNext = nextHides ? noteFocusWithin(nextArrow) : null;
+ const focusOnArrow = focusOnPrevious ?? focusOnNext;
+ if (focusOnArrow == null) {
+ move();
+ return;
+ }
+ // eslint-disable-next-line @eslint-react/dom-no-flush-sync -- the other arrow must be shown before it can take focus
+ flushSync(move);
+ const isOnPrevious = focusOnPrevious != null;
+ const otherArrowHides = isOnPrevious ? nextHides : previousHides;
+ const destination = otherArrowHides
+ ? monthYearButtonRef.current
+ : isOnPrevious
+ ? nextArrowRef.current
+ : previousArrowRef.current;
+ moveFocusLeftBehind(
+ focusOnArrow,
+ destination,
+ isOnPrevious ? previousArrow : nextArrow,
+ );
+ },
+ [minMonthIndex, maxMonthIndex],
+ );
+
+ const stepMonthFromArrow = useCallback(
+ (delta: -1 | 1) => {
+ const target = clampIndex(
+ monthIndex + delta,
+ minMonthIndex,
+ maxMonthIndex,
+ );
+ moveMonth(target, () => stepMonth(delta));
+ },
+ [monthIndex, minMonthIndex, maxMonthIndex, moveMonth, stepMonth],
+ );
+
// A wheel commit steers the scroller immediately, even though it is behind
// the wheels: it keeps its layout box while hidden, so by the time the
// wheels close it is already resting on the new month.
@@ -927,9 +981,10 @@ export function TouchDateField({
if (isWheelOpen) {
return;
}
- setMonthIndex(next);
+ // A swipe to the range end hides an arrow, as a press does.
+ moveMonth(next, () => setMonthIndex(next));
},
- [isWheelOpen],
+ [isWheelOpen, moveMonth],
);
/**
@@ -989,6 +1044,7 @@ export function TouchDateField({
<div {...stylex.props(styles.surface)}>
<div {...stylex.props(styles.header)}>
<button
+ ref={monthYearButtonRef}
type="button"
onClick={() => setIsWheelOpen(open => !open)}
aria-expanded={isWheelOpen}
@@ -1048,8 +1104,9 @@ export function TouchDateField({
styles.monthArrow,
!canStepBack && styles.monthArrowUnavailable,
]}
+ ref={previousArrowRef}
isDisabled={!canStepBack}
- onClick={() => stepMonth(-1)}
+ onClick={() => stepMonthFromArrow(-1)}
label={t('@astryx.calendar.previousMonth')}
icon={
<span {...stylex.props(styles.monthArrowIcon, rtlStyles.mirror)}>
@@ -1064,8 +1121,9 @@ export function TouchDateField({
styles.monthArrow,
!canStepForward && styles.monthArrowUnavailable,
]}
+ ref={nextArrowRef}
isDisabled={!canStepForward}
- onClick={() => stepMonth(1)}
+ onClick={() => stepMonthFromArrow(1)}
label={t('@astryx.calendar.nextMonth')}
icon={
<span {...stylex.props(styles.monthArrowIcon, rtlStyles.mirror)}>
diff --git a/packages/core/src/DateInput/__tests__/DateInputSheetMonthArrowFocus.a11y.chromium.spec.ts b/packages/core/src/DateInput/__tests__/DateInputSheetMonthArrowFocus.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..b4ec3730d3
--- /dev/null
+++ b/packages/core/src/DateInput/__tests__/DateInputSheetMonthArrowFocus.a11y.chromium.spec.ts
@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y scope core/DateInput
+
+/**
+ * @file DateInputSheetMonthArrowFocus.a11y.chromium.spec.ts
+ * @input The built `Core/DateInput` WithMinMax story (min January 15, max
+ * February 15) in its bottom-sheet presentation, on a phone profile
+ * @output Real-engine proof that Enter on a sheet month arrow that steps to
+ * the end of the range keeps focus in the sheet, on the other arrow, in both
+ * directions (component:DateInput FR22)
+ * @position A hidden element loses focus only in a real engine; jsdom keeps
+ * it. DateInputTouch.test.tsx holds the destination rule.
+ */
+
+import {expect, test, type Page} 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();
+});
+
+test.use({hasTouch: true, isMobile: true, viewport: {width: 390, height: 800}});
+
+async function openSheet(page: Page) {
+ await page.goto(
+ `${storybook.origin}/iframe.html?id=core-dateinput--with-min-max&viewMode=story&args=presentation:adaptive-bottom-sheet`,
+ );
+ await page.locator('input').first().click();
+ const header = page.locator('dialog[open] [data-title="month-year"]');
+ await expect(header).toBeVisible();
+ return header;
+}
+
+/**
+ * The focused element's accessible label, or its tag when it has none, read
+ * after two frames: the engine moves focus off an element hidden by a step
+ * only once it renders that step.
+ */
+async function focusedAfterRender(page: Page) {
+ return page.evaluate(
+ async () =>
+ new Promise<string>(resolve => {
+ requestAnimationFrame(() =>
+ requestAnimationFrame(() => {
+ const active = document.activeElement as HTMLElement | null;
+ resolve(
+ active?.getAttribute('aria-label') ?? active?.tagName ?? '',
+ );
+ }),
+ );
+ }),
+ );
+}
+
+test('Enter on Previous month at the first month moves focus to Next month', async ({
+ page,
+}) => {
+ const header = await openSheet(page);
+ await expect(header).toHaveText('February 2026');
+ await page.getByRole('button', {name: 'Previous month'}).focus();
+ await page.keyboard.press('Enter');
+ await expect(header).toHaveText('January 2026');
+ expect(await focusedAfterRender(page)).toBe('Next month');
+});
+
+test('Enter on Next month at the last month moves focus to Previous month', async ({
+ page,
+}) => {
+ const header = await openSheet(page);
+ await page.getByRole('button', {name: 'Previous month'}).click();
+ await expect(header).toHaveText('January 2026');
+ await page.getByRole('button', {name: 'Next month'}).focus();
+ await page.keyboard.press('Enter');
+ await expect(header).toHaveText('February 2026');
+ expect(await focusedAfterRender(page)).toBe('Previous month');
+});