Skip to content

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

TypeScript
40.1 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file MonthScroller.tsx
 * @input A calendar's month model, month bounds, selected value, constraints,
 *   week start
 * @output Exports MonthScroller and MonthScrollerHandle
 * @position Internal component; consumed by TouchDateField.tsx
 *
 * The continuous surface: months stacked vertically in one scroller, each pane
 * exactly as tall as the scrollport and snapped to its start. Two consequences
 * fall out of that single geometric choice — the picker never changes height,
 * and there is no resting position that shows half of two months.
 *
 * Every pane is a fixed six-row grid, including the months that only need
 * four or five, because a pane whose height depended on its contents would
 * make snap offsets vary from month to month and the scroll position drift.
 *
 * The list is long (a century by default) but only a few panes are ever
 * mounted: a spacer holds the full scroll height and the visible panes are
 * positioned into it absolutely. Nothing is stitched or recycled during a
 * scroll, so snap offsets are constant and momentum is never interrupted —
 * which is the failure mode of the usual "append months at the edge" approach.
 *
 * SYNC: When modified, update:
 * - /packages/core/src/DateInput/TouchDateField.tsx
 * - /packages/core/src/DateTimeInput/TouchDateTimeField.tsx
 * - /packages/core/src/DateInput/DateInput.doc.mjs
 * - /packages/core/src/DateInput/DateInputTouch.test.tsx
 */

import {
  useCallback,
  useEffect,
  useImperativeHandle,
  useLayoutEffect,
  useRef,
  useMemo,
  useState,
} from 'react';
import {flushSync} from 'react-dom';
import * as stylex from '@stylexjs/stylex';
import {useCalendarDays} from '../Calendar/hooks/useCalendarDays';
import {useDirection} from '../i18n/useDirection';
import {useLocale} from '../i18n/useLocale';
import {
  colorVars,
  radiusVars,
  fontWeightVars,
  typeScaleVars,
  durationVars,
  borderVars,
} from '../theme/tokens.stylex';
import {focusOutlineStyles} from '../utils/focusOutline.stylex';
import type {DayOfWeek, ISODateString, PlainDate} from '../utils/dateTypes';
import {
  plainDateAddDays,
  plainDateDayOfWeek,
  plainDateFormatDayNumber,
  plainDateIsEqual,
  plainDateToISO,
  DATE_FORMAT_WITH_WEEKDAY,
} from '../utils/plainDate';
import {
  playReducedMotionDip,
  reducedMotionFade,
  type ReducedMotionDip,
} from '../motion/reducedMotion';
import {
  calendarYearMonthOf,
  formatCalendarDate,
  formatCalendarMonthLabel,
  isInCalendarMonth,
} from '../utils/calendarSystem';
import {dateInputTouchSizes, dateInputTouchGeometry} from './tokens.stylex';
import {useOwnScrollGesture} from './useOwnScrollGesture';
import {useScrollSettle, useScrollSteer} from './useScrollSettle';
import {
  type MonthModel,
  paneWindow,
  rowAtScrollOffset,
  rowsIn,
  scrollOffsetForRow,
} from './monthGeometry';

const DAY_SIZE = dateInputTouchSizes.daySize;

/**
 * Panes mounted on each side of the visible one. Sized against a fast fling:
 * the window widens once per animation frame, so it only fails if a single
 * frame travels further than this — three months, about 800px at the default
 * day size. Under `scroll-snap-type: mandatory`, landing on an unmounted pane
 * would not merely show a gap, it would re-snap to the nearest mounted one.
 */
const OVERSCAN = 3;

/** Every listener on the scroller is passive; one options object serves all. */
const PASSIVE: AddEventListenerOptions = {passive: true};

const styles = stylex.create({
  scroller: {
    position: 'relative',
    blockSize: dateInputTouchGeometry.paneBlockSize,
    // Stated, not inherited from the reset: the pane size, the snap offsets
    // and the virtualization all key off the measured box, so a consumer
    // without reset.css (or with a stray box-sizing rule — the reset's is
    // zero-specificity `:where`) must not be able to change what it means.
    boxSizing: 'border-box',
    overflowX: 'auto',
    overflowY: 'hidden',
    // The paging behaviour, now along the inline axis. Every snap area is a
    // full pane, so there is exactly one resting position per month.
    scrollSnapType: 'x mandatory',
    // Keeps a fling inside the picker rather than handing it to the page.
    overscrollBehavior: 'contain',
    scrollbarWidth: 'none',
    // pan-x, so the browser keeps horizontal pans here and hands VERTICAL
    // ones straight to the sheet. That is why this scroller no longer claims
    // the gesture the way the wheels do: with the axes separated there is
    // nothing to fight over, and a downward drag on the calendar can go back
    // to meaning swipe-to-dismiss.
    touchAction: 'pan-x',
  },
  spacer: {
    position: 'relative',
    blockSize: '100%',
  },
  pane: {
    position: 'absolute',
    insetBlock: 0,
    blockSize: dateInputTouchGeometry.paneBlockSize,
    scrollSnapAlign: 'start',
    // No `scroll-snap-stop: always`. It would cap every fling at one month,
    // which is tidy but stops the surface being continuous — "three months
    // ahead" should be one throw, not three flicks. Momentum carrying past
    // several panes is why OVERSCAN is what it is.
    display: 'grid',
    gridTemplateColumns: 'repeat(7, 1fr)',
    gridTemplateRows: dateInputTouchGeometry.paneRows,
  },
  row: {
    display: 'contents',
  },
  cell: {
    position: 'relative',
    display: 'flex',
    alignItems: 'center',
    justifyContent: 'center',
  },
  day: {
    display: 'flex',
    alignItems: 'center',
    justifyContent: 'center',
    inlineSize: '100%',
    blockSize: '100%',
    minInlineSize: DAY_SIZE,
    minBlockSize: DAY_SIZE,
    padding: 0,
    borderWidth: 0,
    borderStyle: 'none',
    backgroundColor: 'transparent',
    color: colorVars['--color-text-primary'],
    fontSize: typeScaleVars['--text-body-size'],
    fontWeight: fontWeightVars['--font-weight-normal'],
    cursor: {
      default: 'pointer',
      ':is(:disabled,[aria-disabled="true"])': 'default',
    },
    // A tap on a 44px target should not also select the number inside it.
    userSelect: 'none',
    WebkitTapHighlightColor: 'transparent',
  },
  /**
   * The circular hit/selection puck inside the tap target. Sizing the puck
   * rather than the button keeps the touch target at the full cell while the
   * visual stays a tidy circle.
   */
  puck: {
    display: 'flex',
    alignItems: 'center',
    justifyContent: 'center',
    inlineSize: `calc(${DAY_SIZE} - 8px)`,
    blockSize: `calc(${DAY_SIZE} - 8px)`,
    borderRadius: radiusVars['--radius-full'],
    borderWidth: borderVars['--border-width'],
    borderStyle: 'solid',
    borderColor: 'transparent',
    backgroundColor: 'transparent',
    transitionProperty: 'background-color, color, border-color',
    transitionDuration: durationVars['--duration-fast'],
  },
  puckHoverable: {
    // Two guards, for two different failure modes.
    //
    // `@media (hover: hover)`: on a touch screen a :hover tint sticks to the
    // last tapped day until something else is tapped.
    //
    // `:where(:not(:disabled,[aria-disabled="true"]))`: a browser suppresses a
    // disabled control's EVENTS, not its hover styling, so an unguarded
    // :hover tints a day you cannot pick. The day's disabled state lives on
    // the button (as `aria-disabled`, which keeps it focusable) and this puck
    // is the span inside it, so today the working mechanism is the JS gate at
    // the call site — this guard is what keeps the rule true if the styles
    // ever move onto the button itself.
    backgroundColor: {
      default: 'transparent',
      '@media (hover: hover)': {
        default: 'transparent',
        ':hover:where(:not(:disabled,[aria-disabled="true"]))':
          colorVars['--color-overlay-hover'],
      },
    },
  },
  puckToday: {
    borderColor: colorVars['--color-border-emphasized'],
    fontWeight: fontWeightVars['--font-weight-semibold'],
  },
  puckSelected: {
    backgroundColor: {
      default: colorVars['--color-accent'],
      // Holds the accent through hover, overriding puckHoverable's tint.
      // Same guarded selector, so the two have equal specificity and
      // application order decides — which is what puts this one on top.
      ':hover:where(:not(:disabled,[aria-disabled="true"]))':
        colorVars['--color-accent'],
    },
    borderColor: colorVars['--color-accent'],
    color: colorVars['--color-on-accent'],
    fontWeight: fontWeightVars['--font-weight-semibold'],
  },
  /**
   * A day belonging to the month either side of this pane. Muted the way
   * Calendar mutes its own, and unselectable for the same reason it is
   * there: it exists to show where the month ends, not to offer a date. A
   * pane is one month, and tapping out of it would move the calendar under
   * your thumb; the swipe or the arrow says "next month" without ambiguity.
   *
   * It needs no special handling for the roving tab order: `tabbableISO` is
   * resolved per pane and only ever names a date in THAT pane's own month,
   * so an outside cell can never match it. Which is the property that keeps
   * a date from having two tab stops — the pane that owns it, and the
   * neighbour that merely shows it.
   */
  dayOutside: {
    // Exactly what the desktop calendar does to its own spill days: the
    // secondary text colour AND half opacity, which is what makes them read
    // as background rather than as dimmer choices. (Calendar splits these
    // across two style objects — `dayOutside` in its theme layer carries the
    // colour, the one in its structural layer the opacity — so applying only
    // the colour, as this did at first, was half the treatment.)
    color: colorVars['--color-text-secondary'],
    opacity: 0.5,
  },
  dayDisabled: {
    // The desktop's disabled treatment, and deliberately not a disabled
    // COLOUR: it fades whatever colour the day already had (0.3), so an
    // in-month day and a spilled one stay a step apart while disabled, and
    // both land LIGHTER than an enabled spill day rather than darker.
    //
    // A flat `--color-text-disabled` is what this had, and it put an enabled
    // adjacent day at ~168 against a disabled in-month day at ~163 on white:
    // five levels apart, which is no difference at all. That is the whole
    // reason the two were hard to tell apart.
    opacity: 0.3,
    cursor: 'default',
  },
});

const dynamic = stylex.create({
  spacer: (inlineSize: number) => ({
    inlineSize: `${inlineSize}px`,
  }),
  // insetInlineStart, not left: under RTL the panes have to lay out from the
  // right, and the scroll math mirrors with them (see scrollOffsetForRow).
  pane: (insetInlineStart: number, inlineSize: number) => ({
    insetInlineStart: `${insetInlineStart}px`,
    inlineSize: `${inlineSize}px`,
  }),
});

export interface MonthScrollerHandle {
  /** Bring a month to rest at the top of the scrollport. */
  scrollToMonth: (monthIndex: number, behavior?: ScrollBehavior) => void;
}

export interface MonthScrollerProps {
  /** Imperative handle for programmatic navigation (Today, the wheels). */
  handleRef?: React.RefObject<MonthScrollerHandle | null>;
  /** The calendar's months, by index. */
  monthModel: MonthModel;
  /** First reachable month, as a month index. */
  minMonthIndex: number;
  /** Last reachable month, as a month index. */
  maxMonthIndex: number;
  /** Month to rest on at mount. */
  initialMonthIndex: number;
  /** Fires as the scroller passes each month, settled or not. */
  onVisibleMonthChange: (monthIndex: number) => void;
  /** Currently selected date. */
  selectedDate: PlainDate | null;
  /**
   * Today, for the `aria-current` marker; `null` while it is not known yet
   * (server render, hydration).
   */
  today: PlainDate | null;
  /** Whether a date fails min/max or a custom constraint. */
  isDateDisabled: (date: PlainDate) => boolean;
  /** First column of the week. */
  weekStartsOn: DayOfWeek;
  /** Fired when a day is tapped. */
  onSelect: (value: ISODateString) => void;
}

/**
 * A vertically continuous, snap-paged run of month grids.
 */
export function MonthScroller({
  handleRef,
  monthModel,
  minMonthIndex,
  maxMonthIndex,
  initialMonthIndex,
  onVisibleMonthChange,
  selectedDate,
  today,
  isDateDisabled,
  weekStartsOn,
  onSelect,
}: MonthScrollerProps) {
  const scrollerRef = useRef<HTMLDivElement | null>(null);
  const rowCount = maxMonthIndex - minMonthIndex + 1;

  // Pane WIDTH is read from layout, never assumed: it is whatever the CSS
  // says the scrollport is, so the snap offsets and the virtualization follow
  // a resize (rotation, a split-screen change) without re-deriving anything.
  const [paneSize, setPaneSize] = useState(0);
  // Which way the inline axis runs. Under RTL the panes lay out from the
  // right and scrollLeft counts DOWN from 0, so every conversion between a
  // row and a scroll offset has to know.
  const isRTL = useDirection() === 'rtl';
  const [centerRow, setCenterRow] = useState(initialMonthIndex - minMonthIndex);
  // The visible row, mirrored so the scroll handler can tell "changed" from
  // "same" without reading state, and notify the parent OUTSIDE a state
  // updater — React runs updaters during render, where another component's
  // setState is illegal.
  const centerRowRef = useRef(centerRow);

  /**
   * Scroll snapping is off from a re-center until the frame after its
   * commit. WebKit keeps the position it snapped to as an index into the
   * container's snap offsets, and re-snaps to that index after a layout: a
   * re-center that unmounts panes before the snapped one shifts the index,
   * so the re-snap lands a month further on, and the scroll that makes
   * re-centers again. One stalled frame right after an arrow (300 ms,
   * measured) was enough to set the calendar paging on by itself, a month
   * every few frames. With snapping off across the commit nothing re-snaps,
   * and switching it back on a frame later snaps to the pane in place.
   *
   * Each pause counts itself, so a batch of re-centers that ends on the
   * center it began from, which commits no new center, still restores
   * snapping.
   *
   * Not while a finger drives the scroll, from its touch until the scroll it
   * started comes to rest: iOS tracks a snap target for the gesture, and
   * turning snapping off drops it, so the swipe coasted past the month for
   * about two seconds and was corrected late (iOS 26.2 simulator, where the
   * same swipe snaps in about 0.6 s with snapping left on).
   */
  const [snapPauses, setSnapPauses] = useState(0);
  const isFingerScrollRef = useRef(false);
  const recenter = useCallback((scroller: HTMLElement, row: number) => {
    if (!isFingerScrollRef.current) {
      scroller.style.scrollSnapType = 'none';
      setSnapPauses(count => count + 1);
    }
    setCenterRow(row);
  }, []);
  // Synchronizes the scroller's snapping with the browser's frame loop: it
  // comes back on in the frame after the pause's commit, and a restore still
  // pending at the next pause or at unmount is dropped.
  useLayoutEffect(() => {
    const scroller = scrollerRef.current;
    if (snapPauses === 0 || scroller == null) {
      return undefined;
    }
    const frame = requestAnimationFrame(() => {
      scroller.style.scrollSnapType = '';
    });
    return () => cancelAnimationFrame(frame);
  }, [snapPauses]);
  // A row to scroll to once its pane is mounted; see scrollToMonth.
  const pendingScrollRef = useRef<number | null>(null);

  /**
   * The row a programmatic scroll is heading for. Its own scroll events are
   * not reported back as if the user had gone there. The settle correction
   * finishes the steer instead of rounding it back. The steer ends once its
   * scroll has arrived, or once the user's own input reaches the scroller
   * (useScrollSettle).
   */
  const steer = useScrollSteer();

  // Keyboard focus moves by date, not by cell index, so it crosses month
  // boundaries the way a calendar should. Null until the user takes the grid
  // with the keyboard.
  const [focusedDate, setFocusedDate] = useState<PlainDate | null>(null);
  const shouldRestoreFocusRef = useRef(false);

  const onVisibleMonthChangeRef = useRef(onVisibleMonthChange);
  onVisibleMonthChangeRef.current = onVisibleMonthChange;

  useLayoutEffect(() => {
    const scroller = scrollerRef.current;
    if (scroller == null) {
      return;
    }
    const measure = () => {
      // Ignore zero: the picker can be mounted inside something not yet
      // displayed (a closed BottomSheet), and a zero width would unmount
      // every pane and lose the scroll position.
      const measured = scroller.clientWidth;
      if (measured > 0) {
        // eslint-disable-next-line @eslint-react/set-state-in-effect -- pane width is a measurement; layout is the only place it exists
        setPaneSize(measured);
      }
    };
    measure();
    const observer = new ResizeObserver(measure);
    observer.observe(scroller);
    return () => observer.disconnect();
  }, []);

  // Land on the initial month before the first paint. Runs once the height is
  // known; `hasPositioned` keeps a later resize from yanking the user back.
  const hasPositionedRef = useRef(false);
  useLayoutEffect(() => {
    const scroller = scrollerRef.current;
    if (scroller == null || paneSize === 0 || hasPositionedRef.current) {
      return;
    }
    hasPositionedRef.current = true;
    scroller.scrollLeft = scrollOffsetForRow(
      initialMonthIndex - minMonthIndex,
      paneSize,
      isRTL,
    );
  }, [paneSize, initialMonthIndex, minMonthIndex, isRTL]);

  // The Reduced Motion dip of a step on a touch screen, owned here so a
  // second step or the unmount clears it.
  const dipRef = useRef<ReducedMotionDip | null>(null);
  const stopDip = useCallback(() => {
    dipRef.current?.cancel();
    dipRef.current = null;
  }, []);
  // Synchronizes with the dip's animations: they do not outlive the scroller.
  useEffect(() => stopDip, [stopDip]);

  const scrollToMonth = useCallback(
    (monthIndex: number, behavior: ScrollBehavior = 'smooth') => {
      // Every step replaces a running dip, whichever way it moves. Otherwise
      // the dip's landing would undo a jump or an immediate step made after it.
      stopDip();
      const scroller = scrollerRef.current;
      if (scroller == null || paneSize === 0) {
        return;
      }
      const row = Math.min(
        rowCount - 1,
        Math.max(0, monthIndex - minMonthIndex),
      );
      if (Math.abs(row - centerRowRef.current) > OVERSCAN) {
        // Beyond the mounted window there is no pane at the target offset, and
        // `scroll-snap-type: mandatory` will not leave the scroller resting
        // where no snap area is — it re-snaps to the nearest mounted pane, so
        // a jump to another year lands one month away instead. Mount the
        // target first and scroll once it exists (see the layout effect
        // below); a jump that far is never worth animating either.
        pendingScrollRef.current = row;
        centerRowRef.current = row;
        // The jump is a steer too. Recording it replaces a steer left behind
        // by a scroll that moved nothing (the re-assert when the month and
        // year wheels close), which the settle would otherwise finish,
        // pulling the scroller back off the jump's month.
        steer.start(row);
        recenter(scroller, row);
        return;
      }
      const left = scrollOffsetForRow(row, paneSize, isRTL);
      // Under reduced motion the month changes without travel: at once on a fine
      // primary pointer, under an opacity dip on a coarse one (reducedMotionFade).
      const fade = behavior === 'smooth' ? reducedMotionFade(scroller) : null;
      if (fade != null) {
        // The window mounts around the target first, and the scroll lands in
        // the layout effect below, as a far jump does. So nothing moves the
        // window after the jump. If the window followed the jump, WebKit would
        // re-snap it one pane further on every frame. A scroll that lands on
        // the centre row reports nothing.
        const land = () => {
          // The landing is the newest steer. An earlier steer whose scroll
          // never arrived would otherwise hide every scroll after it, a
          // trackpad's included. Closing the wheels makes such a steer: it
          // re-asserts the month already in view.
          steer.end();
          if (row === centerRowRef.current) {
            scroller.scrollTo({left, behavior: 'auto'});
            return;
          }
          pendingScrollRef.current = row;
          centerRowRef.current = row;
          setCenterRow(row);
        };
        if (fade.duration === 0) {
          land();
          return;
        }
        // A newer step replaces this one: only its scroll lands.
        dipRef.current = playReducedMotionDip(scroller, fade, () => {
          dipRef.current = null;
          // The fade-in starts as soon as this returns. So render now: the
          // scroll lands in the layout effect, before the fade-in.
          // eslint-disable-next-line @eslint-react/dom-no-flush-sync -- the month must change before the dip's fade-in starts
          flushSync(land);
        });
        return;
      }
      steer.start(row);
      scroller.scrollTo({left, behavior});
    },
    [paneSize, minMonthIndex, rowCount, isRTL, recenter, stopDip, steer],
  );

  // Deliberately un-keyed: it runs after every render, costs a null check, and
  // must fire on whichever render finally mounts the pending row's pane.
  useLayoutEffect(() => {
    const row = pendingScrollRef.current;
    const scroller = scrollerRef.current;
    if (row == null || scroller == null || paneSize === 0) {
      return;
    }
    pendingScrollRef.current = null;
    scroller.scrollTo({
      left: scrollOffsetForRow(row, paneSize, isRTL),
      behavior: 'auto',
    });
  });

  useImperativeHandle(handleRef, () => ({scrollToMonth}), [scrollToMonth]);

  /**
   * Put the scroller back on a pane boundary once the gesture is over.
   *
   * `scroll-snap-type: mandatory` is supposed to make this unnecessary, and
   * on a static list it does. This list is virtualized: seven panes exist out
   * of twelve hundred, and the panes ARE the snap areas — so every month the
   * finger crosses mounts one and unmounts another, mid-fling.
   *
   * iOS scrolls off the main thread. It picks a landing place from the snap
   * points it knows about at the time, and a React re-render that lands after
   * that decision moves them; the scroller then comes to rest where no snap
   * point exists any more, and nothing re-snaps it. That is the calendar
   * sitting between two months with the weekday header still square — the
   * grid is not skewed, the scrollport is simply parked a couple of columns
   * into a pane. Chrome hides it by snapping again after the mutation.
   *
   * So the rest position is corrected here rather than trusted. It waits for
   * a true settle — touch released AND quiet, since iOS below 26 has no
   * `scrollend` and its momentum outlasts any naive timer (see
   * useScrollSettle) — and only moves when the offset is genuinely off, so a
   * scroller the browser snapped for itself is left alone.
   *
   * ## Why it re-checks that the scroller is still
   *
   * A quiet period is not proof of rest, and getting that wrong here does not
   * merely fail to fix the bug — it REVERSES the user's swipe. iOS runs its
   * own snap animation for ~150-300ms after the finger lifts, and the scroll
   * events it fires during that animation arrive irregularly; a gap longer
   * than the quiet period is routine in the slow tail. The settle then lands
   * mid-animation, reads a scrollLeft still travelling toward April, rounds
   * THAT to the nearest pane — which is still March, because the animation is
   * not yet halfway — and drags the calendar back where it came from. Swipe
   * forward, get pulled backward, which is what this looked like on a device.
   *
   * Two samples a frame apart settle it: if the offset moved, the scroller is
   * still going somewhere and its destination is not ours to guess. Skipping
   * costs nothing, because the animation's own scroll events re-arm the
   * settle, and the last of them gets a quiet period that ends at true rest.
   *
   * The threshold is a subpixel rather than exact equality. A scroller at rest
   * on a fractional-density viewport can report an offset that wobbles in the
   * last decimal place, and exact equality would read that as travel and never
   * correct at all — the failure mode being silent, which is the worst kind.
   * A tail crawling slower than half a pixel a frame has effectively arrived,
   * so treating it as arrived is right anyway.
   *
   * After the user's own scroll the correction goes to the nearest boundary,
   * at most half a pane away. After a steer it goes on to the steered month,
   * however early the browser cut the steer short. Either way its own scroll
   * settles onto the boundary it aimed at, where a steer counts as arrived, so
   * it cannot oscillate.
   */
  const settleFrameRef = useRef<number | undefined>(undefined);
  // Releases the settle frame on unmount.
  useEffect(
    () => () => {
      if (settleFrameRef.current != null) {
        cancelAnimationFrame(settleFrameRef.current);
      }
    },
    [],
  );

  const settleOnRest = (scroller: HTMLElement) => {
    // At rest, momentum included: the finger no longer drives the scroll.
    isFingerScrollRef.current = false;
    if (paneSize === 0) {
      return;
    }
    const offsetBefore = scroller.scrollLeft;
    if (settleFrameRef.current != null) {
      cancelAnimationFrame(settleFrameRef.current);
    }
    settleFrameRef.current = requestAnimationFrame(() => {
      settleFrameRef.current = undefined;
      // Still travelling — including a snap animation iOS has not finished.
      // Correcting toward the nearest pane from a position mid-flight would
      // undo the swipe rather than complete it.
      if (Math.abs(scroller.scrollLeft - offsetBefore) >= 0.5) {
        return;
      }
      // A steer the browser cut short is finished, not rounded back. WebKit
      // ends a smooth scroll that a second one retargeted once the first
      // one's time is up, firing `scrollend` part-way: an arrow tapped late
      // in the previous arrow's scroll stopped near that month, and rounding
      // to the nearest pane put the scroller back on it while the title named
      // the new one.
      const steered = steer.current();
      const row =
        steered ??
        rowAtScrollOffset(scroller.scrollLeft, paneSize, rowCount, isRTL);
      const target = scrollOffsetForRow(row, paneSize, isRTL);
      // Sub-pixel drift is the browser's own rounding, not a failed snap.
      if (Math.abs(scroller.scrollLeft - target) < 1) {
        // At rest on its target, a steer has arrived even if no scroll
        // crossed into its month.
        steer.end();
        return;
      }
      scroller.scrollTo({left: target, behavior: 'smooth'});
    });
  };
  useScrollSettle(scrollerRef, settleOnRest, true, undefined, steer);

  // Claim horizontal gestures, leave vertical ones to the sheet.
  //
  // `touch-action: pan-x` alone is NOT enough: it governs what the browser
  // pans natively, and the sheet's listener is JavaScript whose
  // preventDefault() cancels the scroll regardless. Measured — a swipe 9° off
  // horizontal had every touchmove cancelled by the sheet and the month never
  // changed. The axis lock is biased toward horizontal, because a thumb arcs
  // as it swipes; `onSwipe` then pages the diagonals the browser itself
  // declines to pan, so no angle is left doing nothing. See
  // useOwnScrollGesture.
  useOwnScrollGesture(scrollerRef, 'inline', {
    onSwipe: direction => {
      const scroller = scrollerRef.current;
      if (scroller == null || paneSize === 0) {
        return;
      }
      scroller.scrollBy({left: direction * paneSize, behavior: 'smooth'});
    },
  });

  // rAF-throttled: a touch scroll fires far more scroll events than frames,
  // and all this does is move a label and widen a window.
  const frameRef = useRef<number | undefined>(undefined);
  // Syncs scroll and touch listeners on the scroller with its measured
  // height.
  useEffect(() => {
    const scroller = scrollerRef.current;
    // Not before the height is known. A listener attached while it was zero
    // would close over that zero and report row 0 for any scroll — and the
    // scroll event fired by the initial positioning arrives just late enough
    // to be handled by that stale listener. Every pane then unmounts except
    // rows 0-2, and `scroll-snap-type: mandatory` yanks the scroller to the
    // nearest surviving snap area, a century away from where it just landed.
    if (scroller == null || paneSize === 0) {
      return;
    }
    // From a touch until its scroll comes to rest (the settle above), the
    // finger drives the scroll and a re-center leaves snapping on.
    const onTouchStart = () => {
      isFingerScrollRef.current = true;
    };

    const onScroll = () => {
      if (frameRef.current != null) {
        return;
      }
      frameRef.current = requestAnimationFrame(() => {
        frameRef.current = undefined;
        const row = rowAtScrollOffset(
          scroller.scrollLeft,
          paneSize,
          rowCount,
          isRTL,
        );
        if (row === centerRowRef.current) {
          return;
        }
        centerRowRef.current = row;
        recenter(scroller, row);
        // Report nothing while a steer is in flight. `scrollToMonth` is only
        // ever called by something that already knows the month — a wheel
        // commit, a header arrow, the re-assert when the wheels close — so
        // none of the scrolling it causes is news, including whatever the
        // scroller passes through on the way.
        //
        // Reporting it is a feedback cycle, and worse on iOS. A wheel commit
        // steers this scroller while it is hidden behind the wheels, and a
        // hidden scroller does not reliably stay where it was put: iOS
        // re-snaps it when the panel becomes visible again, firing scrolls at
        // the exact moment reports start being trusted again. The month drifted
        // on the way back to the calendar.
        //
        // Ended on arrival, or by the user's input (useScrollSettle). From then
        // the user owns the scroller, and every month it passes is worth
        // reporting.
        const steered = steer.current();
        if (steered != null) {
          if (steered === row) {
            steer.end();
          }
          return;
        }
        onVisibleMonthChangeRef.current(minMonthIndex + row);
      });
    };
    scroller.addEventListener('scroll', onScroll, PASSIVE);
    scroller.addEventListener('touchstart', onTouchStart, PASSIVE);
    return () => {
      scroller.removeEventListener('scroll', onScroll, PASSIVE);
      scroller.removeEventListener('touchstart', onTouchStart, PASSIVE);
      if (frameRef.current != null) {
        cancelAnimationFrame(frameRef.current);
        frameRef.current = undefined;
      }
    };
  }, [paneSize, rowCount, minMonthIndex, isRTL, recenter, steer]);

  // Move the keyboard focus by whole days and let the scroller follow. Paging
  // by month is PageUp/PageDown; everything else is the APG grid vocabulary.
  const moveFocus = useCallback(
    (from: PlainDate, deltaDays: number) => {
      const next = plainDateAddDays(from, deltaDays);
      const nextIndex = monthModel.indexOf(next);
      if (nextIndex < minMonthIndex || nextIndex > maxMonthIndex) {
        return;
      }
      shouldRestoreFocusRef.current = true;
      setFocusedDate(next);
      if (nextIndex !== monthModel.indexOf(from)) {
        scrollToMonth(nextIndex, 'smooth');
      }
    },
    [monthModel, minMonthIndex, maxMonthIndex, scrollToMonth],
  );

  const handleKeyDown = useCallback(
    (event: React.KeyboardEvent, date: PlainDate) => {
      // Column within the displayed week, which is what Home/End move to —
      // not the day of the month.
      const column = (plainDateDayOfWeek(date) - weekStartsOn + 7) % 7;
      // The horizontal arrows follow the reading direction (APG grid): under
      // RTL the next day sits to the left.
      const forward = isRTL ? 'ArrowLeft' : 'ArrowRight';
      const backward = isRTL ? 'ArrowRight' : 'ArrowLeft';
      switch (event.key) {
        case backward:
          event.preventDefault();
          moveFocus(date, -1);
          break;
        case forward:
          event.preventDefault();
          moveFocus(date, 1);
          break;
        case 'ArrowUp':
          event.preventDefault();
          moveFocus(date, -7);
          break;
        case 'ArrowDown':
          event.preventDefault();
          moveFocus(date, 7);
          break;
        case 'Home':
          event.preventDefault();
          moveFocus(date, -column);
          break;
        case 'End':
          event.preventDefault();
          moveFocus(date, 6 - column);
          break;
        default:
          break;
      }
    },
    [isRTL, moveFocus, weekStartsOn],
  );

  // The focused day may have been in an unmounted pane a frame ago; focus it
  // once it exists, and only in response to a key press so a scroll never
  // steals focus.
  const focusedISO = focusedDate == null ? null : plainDateToISO(focusedDate);
  useEffect(() => {
    if (!shouldRestoreFocusRef.current || focusedISO == null) {
      return;
    }
    // A date can be mounted twice: as a real day in its own pane and as a
    // dimmed, disabled spill copy at the edge of a neighbouring pane. Only
    // the real day may take focus, or Enter and Space would select nothing.
    const target = scrollerRef.current?.querySelector<HTMLElement>(
      `[data-date="${focusedISO}"]:not([data-outside])`,
    );
    if (target != null) {
      shouldRestoreFocusRef.current = false;
      // preventScroll: the scroller is already snapping to this month; a
      // browser scroll-into-view here would fight the snap and land between
      // two panes.
      target.focus({preventScroll: true});
    }
  }, [focusedISO]);

  const visibleRows = paneWindow(centerRow, rowCount, OVERSCAN);

  // A focus event fires for the programmatic focus above too; only take the
  // date when it is actually a different day.
  const handleDayFocus = useCallback((date: PlainDate) => {
    setFocusedDate(previous =>
      previous != null && plainDateIsEqual(previous, date) ? previous : date,
    );
  }, []);

  return (
    <div
      ref={scrollerRef}
      data-scroller="months"
      {...stylex.props(styles.scroller)}>
      <div
        {...stylex.props(styles.spacer, dynamic.spacer(rowCount * paneSize))}>
        {paneSize > 0 &&
          rowsIn(visibleRows).map(row => (
            <MonthPane
              key={row}
              monthModel={monthModel}
              monthIndex={minMonthIndex + row}
              insetInlineStart={row * paneSize}
              inlineSize={paneSize}
              selectedDate={selectedDate}
              focusedDate={focusedDate}
              today={today}
              isDateDisabled={isDateDisabled}
              weekStartsOn={weekStartsOn}
              onSelect={onSelect}
              onDayKeyDown={handleKeyDown}
              onDayFocus={handleDayFocus}
            />
          ))}
      </div>
    </div>
  );
}

MonthScroller.displayName = 'MonthScroller';

interface MonthPaneProps {
  monthModel: MonthModel;
  monthIndex: number;
  insetInlineStart: number;
  inlineSize: number;
  selectedDate: PlainDate | null;
  focusedDate: PlainDate | null;
  /** Today, or `null` while it is not known yet (server render, hydration). */
  today: PlainDate | null;
  isDateDisabled: (date: PlainDate) => boolean;
  weekStartsOn: DayOfWeek;
  onSelect: (value: ISODateString) => void;
  onDayKeyDown: (event: React.KeyboardEvent, date: PlainDate) => void;
  onDayFocus: (date: PlainDate) => void;
}

/**
 * One month, as a six-row grid.
 *
 * There is no `role="columnheader"` row in here: the weekday names are a
 * single sticky row outside the scroller (they would otherwise scroll away),
 * so each day instead carries its weekday in its accessible name.
 */
function MonthPane({
  monthModel,
  monthIndex,
  insetInlineStart,
  inlineSize,
  selectedDate,
  focusedDate,
  today,
  isDateDisabled,
  weekStartsOn,
  onSelect,
  onDayKeyDown,
  onDayFocus,
}: MonthPaneProps) {
  const locale = useLocale();
  const {calendar} = monthModel;
  const month = useMemo(
    () => monthModel.monthAt(monthIndex),
    [monthModel, monthIndex],
  );
  const {weeks} = useCalendarDays({
    ...calendarYearMonthOf(calendar, month),
    calendar,
    weekStartsOn,
    // Always six rows: a variable grid would make pane heights differ, and
    // with them every snap offset below this month.
    hasVariableRowCount: false,
  });

  const monthLabel = formatCalendarMonthLabel(calendar, month, locale);

  // Exactly one day per pane is tab-reachable, so Tab moves through the
  // picker rather than through 42 buttons: the focused day if the keyboard
  // owns one, else the selection, else the first of the month.
  const tabbableISO = (() => {
    if (focusedDate != null && isInCalendarMonth(focusedDate, month)) {
      return plainDateToISO(focusedDate);
    }
    if (selectedDate != null && isInCalendarMonth(selectedDate, month)) {
      return plainDateToISO(selectedDate);
    }
    return plainDateToISO(month.start);
  })();

  return (
    <div
      role="grid"
      aria-label={monthLabel}
      data-month={monthLabel}
      {...stylex.props(
        styles.pane,
        dynamic.pane(insetInlineStart, inlineSize),
      )}>
      {weeks.map(week => (
        <div key={week[0].iso} role="row" {...stylex.props(styles.row)}>
          {week.map(day => {
            // A spilled day is context, not a choice. Calendar computes the
            // same thing as `effectivelyDisabled: isDisabled || isOutside`,
            // and guards today/selected on `!isOutside` beside it, so a date
            // borrowed from a neighbouring month never carries a ring or a
            // puck in the pane that is only showing it.
            const isDisabled = day.isOutside || isDateDisabled(day.date);
            const isSelected =
              !day.isOutside &&
              selectedDate != null &&
              plainDateIsEqual(day.date, selectedDate);
            const isToday =
              !day.isOutside &&
              today != null &&
              plainDateIsEqual(day.date, today);

            return (
              <div
                key={day.iso}
                role="gridcell"
                aria-selected={isSelected || undefined}
                {...stylex.props(styles.cell)}>
                <button
                  type="button"
                  data-date={day.iso}
                  data-outside={day.isOutside ? '' : undefined}
                  tabIndex={day.iso === tabbableISO ? 0 : -1}
                  aria-label={formatCalendarDate(
                    calendar,
                    day.date,
                    DATE_FORMAT_WITH_WEEKDAY,
                    locale,
                  )}
                  aria-disabled={isDisabled || undefined}
                  aria-current={isToday ? 'date' : undefined}
                  onClick={() => {
                    if (!isDisabled) {
                      onSelect(day.iso);
                    }
                  }}
                  onFocus={() => onDayFocus(day.date)}
                  onKeyDown={event => onDayKeyDown(event, day.date)}
                  {...stylex.props(
                    styles.day,
                    focusOutlineStyles.focusVisible,
                    // Outside FIRST, so disabled wins where both apply: a
                    // spilled day past the range is unselectable, and must
                    // not be painted more available than the in-month days
                    // beside it.
                    day.isOutside && styles.dayOutside,
                    isDisabled && styles.dayDisabled,
                  )}>
                  <span
                    {...stylex.props(
                      styles.puck,
                      !isDisabled && styles.puckHoverable,
                      isToday && styles.puckToday,
                      isSelected && styles.puckSelected,
                    )}>
                    {plainDateFormatDayNumber(day.dayNumber, locale)}
                  </span>
                </button>
              </div>
            );
          })}
        </div>
      ))}
    </div>
  );
}

MonthPane.displayName = 'MonthPane';