fix(DateInput, DateTimeInput): the sheet's calendar pages like UIDatePicker

.changeset/calendar-pages-like-uidatepicker.md

@@ -0,0 +1,16 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Under a finger, the calendar in the DateInput and DateTimeInput bottom sheets now pages its months like the iOS date picker:
+
+- A swipe moves at most one month, chosen at the lift by iOS's paging rule: a quick flick, or a drag past half a month. It settles on iOS's paging curve.
+- The month title follows the drag and the settle. It changes when the next month is more than half in view.
+- An arrow scrolls one month. A second tap mid-scroll goes on to the month after.
+- In the sheet, a drag is decided once it has moved 10 px either way. It pages the calendar if it has moved 10 px sideways by then, and moves the sheet otherwise.
+- A horizontal trackpad swipe moves the calendar with it and pages at the release, like a drag.
+- With Reduce Motion on, the arrows' step and a swipe's settle cross-fade in 200 ms instead of travelling.
+
+With a mouse, the calendar still scrolls natively. With any pointer, PageUp and PageDown now move the keyboard focus by a month, and by a year with Shift.
+
+@vjeux

apps/storybook/stories/DateInput.stories.tsx

@@ -594,6 +594,25 @@ export const WithMinMax: Story = {
   },
 };
 
+/**
+ * The bottom-sheet calendar pages its months like the iOS date picker. One
+ * month moves per swipe, and the title follows the drag.
+ */
+export const BottomSheetCalendar: Story = {
+  render: args => {
+    const [value, setValue] = useState<ISODateString | undefined>(
+      '2026-10-15' as ISODateString,
+    );
+    return <DateInput {...args} value={value} onChange={setValue} />;
+  },
+  args: {
+    label: 'Date',
+    presentation: 'bottom-sheet',
+    min: '2026-01-01' as ISODateString,
+    max: '2026-12-31' as ISODateString,
+  },
+};
+
 export const WithMaxDateInLayout: Story = {
   render: args => {
     const [value, setValue] = useState<ISODateString | undefined>(undefined);

apps/storybook/stories/MonthPagerProofs.stories.tsx

@@ -0,0 +1,72 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MonthPagerProofs.stories.tsx
+ * @input Uses React and the internal MonthPager (packages/core/src/DateInput)
+ * @output The month pager alone, whatever the primary pointer: 2026 from
+ *   March, its shown month in a read-only field
+ * @position A checked-in reproduction path for the trackpad proofs in
+ *   packages/core/src/DateInput/__tests__/MonthPager.interaction.browser.spec.ts.
+ *   WebKit's driver sends a trackpad's precise deltas only from a desktop
+ *   context, where the sheets show the mouse calendar instead.
+ */
+
+import type {Meta, StoryObj} from '@storybook/react';
+import {useState} from 'react';
+import {MonthPager} from '../../../packages/core/src/DateInput/MonthPager';
+import {
+  createMonthModel,
+  fromMonthIndex,
+  toMonthIndex,
+} from '../../../packages/core/src/DateInput/monthGeometry';
+
+const FIRST = toMonthIndex(2026, 1);
+const LAST = toMonthIndex(2026, 12);
+const MARCH = toMonthIndex(2026, 3);
+const TODAY = {year: 2026, month: 3, day: 15};
+const GREGORY = createMonthModel('gregory');
+
+/**
+ * The readout takes the theme's text colour on the theme's surface, not the
+ * browser's white field.
+ */
+const READOUT_STYLE = {color: 'inherit', backgroundColor: 'transparent'};
+
+const meta = {
+  title: 'Core/MonthPager',
+  tags: ['no-visual', '!autodocs'],
+  parameters: {layout: 'centered'},
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** The pager alone. Its field names the month it shows. */
+export const Pager: Story = {
+  render: () => {
+    const [shown, setShown] = useState(MARCH);
+    const {year, month} = fromMonthIndex(shown);
+    return (
+      <div style={{display: 'grid', gap: 16, inlineSize: 360}}>
+        <input
+          aria-label="Shown month"
+          readOnly
+          style={READOUT_STYLE}
+          value={`${year}-${String(month).padStart(2, '0')}`}
+        />
+        <MonthPager
+          monthModel={GREGORY}
+          minMonthIndex={FIRST}
+          maxMonthIndex={LAST}
+          initialMonthIndex={MARCH}
+          onVisibleMonthChange={setShown}
+          selectedDate={null}
+          today={TODAY}
+          isDateDisabled={() => false}
+          weekStartsOn={0}
+          onSelect={() => {}}
+        />
+      </div>
+    );
+  },
+};

packages/core/src/DateInput/DateInputTouch.calendar.test.tsx

@@ -19,13 +19,14 @@ import {
   type ISODateTimeString,
 } from '../DateTimeInput/DateTimeInput';
 import {InternationalizationProvider} from '../i18n/InternationalizationProvider';
+import {monthGridKeyTarget} from './MonthPane';
 import {createMonthModel, dateInMonth} from './monthGeometry';
 import {
   type CalendarSystem,
   calendarDateFromFields,
   calendarDayOfMonth,
 } from '../utils/calendarSystem';
-import type {ISODateString} from '../utils/dateTypes';
+import type {ISODateString, PlainDate} from '../utils/dateTypes';
 import {plainDateAddDays, plainDateFromISO} from '../utils/plainDate';
 
 const host = globalThis as {Temporal?: unknown};
@@ -481,6 +482,35 @@ describe('the month model', () => {
     });
   });
 
+  it('pages the keyboard focus by calendar months, and by calendar years with Shift', () => {
+    const hebrew = createMonthModel('hebrew');
+    const page = (date: PlainDate, key: string, shiftKey = false) =>
+      monthGridKeyTarget({key, shiftKey} as React.KeyboardEvent, date, {
+        calendar: 'hebrew',
+        isRTL: false,
+        weekStartsOn: 0,
+      });
+    const at = (date: PlainDate | null) =>
+      hebrew.yearMonthAt(hebrew.indexOf(date!));
+    // A month back from 1 Nisan 5784 is Adar II: the leap year has Adar I too.
+    const nisan1 = calendarDateFromFields('hebrew', {
+      year: 5784,
+      monthCode: 'M07',
+      day: 1,
+    })!;
+    expect(at(page(nisan1, 'PageUp'))).toEqual({year: 5784, month: 7});
+    // A year back from Shevat 5785 is Shevat 5784, 13 months back across
+    // Adar I, not 12.
+    const shevat10 = calendarDateFromFields('hebrew', {
+      year: 5785,
+      monthCode: 'M05',
+      day: 10,
+    })!;
+    const yearBack = page(shevat10, 'PageUp', true);
+    expect(at(yearBack)).toEqual({year: 5784, month: 5});
+    expect(calendarDayOfMonth('hebrew', yearBack!)).toBe(10);
+  });
+
   it('moves a date by calendar months, keeping its day of the month', () => {
     const persian = createMonthModel('persian');
     const mehr = persian.indexOfYearMonth(1405, 7);