pixelize-native-library 1.0.6 → 1.2.0

package/lib/module/modules/data-table/MODULE.md

@@ -0,0 +1,145 @@
+# data-table/ — a horizontally-scrollable, column-configured table
+
+`DataTable` renders column headers + rows for tabular data on a phone screen. Header and body live
+in ONE vertical `FlatList` (header as `ListHeaderComponent`, `stickyHeaderIndices={[0]}` for the
+pin) nested inside a single horizontal `ScrollView` — header and rows are always the same width and
+scroll sideways together with no hand-rolled scroll-offset syncing between two separate lists.
+
+Sort and selection are fully **controlled**, the same contract `Select` uses for `value`: DataTable
+never sorts `data` itself and never owns `selectedKeys` — it reports the next state via
+`onSortChange`/`onSelectionChange` and renders whatever the caller passes back in.
+
+## Files
+
+| File | Role |
+|------|------|
+| `DataTable.tsx` | The component. Header/row/skeleton/empty JSX built inline per render (Select's precedent), one `FlatList` wired with `stickyHeaderIndices`. |
+| `DataTable.variants.ts` | Pure resolvers (`resolveDataTableColors`, `nextSortDirection`, `resolveSortIcon`, `resolveSortAccessibilityLabel`, `toggleSelectionKey`, `resolveSelectAllState`, `resolveSelectAllSelection`, `resolveDefaultCellText`, `resolveRowBackground`, `resolveTotalWidth`) + themed structural resolvers. No React, no lucide. |
+| `index.ts` | Public surface: `DataTable`, `DataTableProps`, `DataTableColumn`, `DataTableAlign`, `DataTableSortDirection`. |
+| `__tests__/DataTable.test.ts` | Pure: WCAG contrast (all brands × modes) + sort/selection/formatting contracts. |
+| `__tests__/DataTable.render.test.tsx` | Render: headers/cells, header **position** in the rendered order (both `stickyHeader` values, empty and loading), the sticky pin, header-offset row layout, per-cell column naming, row press, sort cycling, select-all/row selection, loading, empty state. |
+| `__tests__/DataTable.perf.test.tsx` | Perf: mounted rows stay bounded for a 10k dataset; an unrelated outer `style` change mounts no extra rows. |
+| `__tests__/DataTable.dom.test.tsx` | Real DOM (`jest.web.config.js`): a non-sortable header renders `<h3>`; a sortable header renders `<h3>` AND its sort control keeps `role="button"`, nested inside it. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `columns` | `DataTableColumn<T>[]` | — | `{ key, header, width?, align?, render?, sortable? }`. `render`'s `ReactNode`, if textual, must be caller-wrapped in `<Text>` — same convention as `ListItem`'s `leading`/`trailing`. |
+| `data` | `T[]` | — | Required. |
+| `keyExtractor` | `(row, index) => string` | — | Required; also seeds each row's `testID`. |
+| `onRowPress` | `(row, index) => void` | — | Absent = rows are plain `View`s, not `Pressable`. |
+| `sortBy` / `sortDirection` | `string` / `asc \| desc` | — | Controlled, like `Select`'s `value`. |
+| `onSortChange` | `(key, direction) => void` | — | Fired on a sortable header press; DataTable never sorts `data` itself. |
+| `selectable` | `boolean` | `false` | Adds a leading `Checkbox` column (select-all in the header). |
+| `selectedKeys` / `onSelectionChange` | `string[]` / `(keys) => void` | — | Controlled, like `sortBy`. |
+| `loading` | `boolean` | `false` | Swaps rows for `DATA_TABLE_SKELETON_ROW_COUNT` (5) `Skeleton` rows; header still renders. |
+| `emptyMessage` | `string` | `"No data"` | Passed to `EmptyState`'s `title` when `data` is empty and not loading. |
+| `stickyHeader` | `boolean` | `true` | `stickyHeaderIndices={[0]}` on the list. Controls the **pin only** — the header is `ListHeaderComponent` either way, so it is always rendered before row 0. |
+| `rowHeight` | `number` | `48` | Short values get `hitSlop`, same technique as `Select`'s compact sizes. Also feeds `getItemLayout`. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
+| `testID` | `string` | — | Seeds `-header`, `-header-<key>` (the sort button on a sortable column, the heading `View` itself on a non-sortable one), `-header-<key>-heading` (the heading wrapper, sortable columns only), `-row-<i>`, `-row-<i>-select`, `-select-all`, `-skeleton-<i>`, `-empty`, `-scroll`, plus `-focus-ring` under a focused header cell or row. |
+
+## Accessibility contract (WCAG)
+
+- **1.4.3** — header text/icon and body cell text are measured ≥ 4.5:1 on every fill they can sit on
+  (header band, even row, odd/zebra row, pressed row) across all brands × both modes.
+- **1.4.11** — the header/body boundary is `border.interactive`, measured ≥ 3:1, not the decorative
+  `border.default` (a ~1.2:1 hairline on every brand — see `DataTable.test.ts`).
+- **1.3.3 / 4.1.2** — the sort glyph is a visual-only cue; a sortable header's accessible name embeds
+  the state in words ("Name, sorted ascending") so it isn't lost to a screen reader.
+- **1.3.1 — every column header keeps `accessibilityRole="header"`, sortable or not**, each with
+  `aria-level={3}` (`HEADING_LEVEL.subsection`, `core/heading`). A sortable column previously LOST
+  the header role entirely — the sort control (`role="button"`) replaced it on the same node instead
+  of sitting alongside it, so a fully-sortable table had no column headers in the accessibility tree
+  at all. Fixed by wrapping: an outer `HeadingView` (`accessibilityRole="header"`,
+  `testID={testID}-header-<key>-heading`) contains the inner sort `Pressable`
+  (`testID={testID}-header-<key>`, `accessibilityRole="button"`) — one node per role, not one node
+  fighting over two.
+- **2.5.8 / 2.5.5 target size** — the header row is a direct 44dp target (no slop needed); a narrow
+  sortable column or a compact `rowHeight` reaches 44dp via `hitSlop`, same `Select`/`Button` technique.
+- Selection reuses `Checkbox`'s own contract wholesale (tri-state `accessibilityState`, required
+  `accessibilityLabel` on every unlabelled box) — select-all announces `"Select all rows"`, a row
+  announces `"Select row <n>"`.
+- Loading and empty states inherit `Skeleton`'s (decorative, `accessibilityElementsHidden`) and
+  `EmptyState`'s own contracts unmodified.
+- **2.1.1 keyboard-reachable scroll region** — the outer horizontal `ScrollView` carries an explicit
+  `tabIndex={0}`. A plain display table (no `onRowPress`, no `sortable` column, `selectable={false}`)
+  has **no** focusable descendant at all, so its off-screen columns were unreachable by keyboard.
+  Explicit, rather than relying on Chrome/Firefox's auto-focusable-scroll-region behaviour, which
+  Safari and native RN do not have. Consequence: every table is one tab stop on web.
+- **2.4.7** — a sortable header cell and a pressable row each draw a `border.focus` ring
+  (`${testID}-header-<key>-focus-ring`, `${testID}-row-<i>-focus-ring`). Both are drawn **inside**
+  their own bounds: they are full-bleed inside two nested scroll containers, where the gap-outside
+  ring `Button`/`CopyButton` use is clipped on the very edges that carry it.
+- **2.4.11** — while `stickyHeader` is on, rows carry `scrollMarginTop: headerOffset` **on web
+  only**. A pinned header renders as `position: sticky`, and the browser scrolls a newly focused row
+  flush to the container's top edge — under the header, hiding the ring above. The margin reuses the
+  same `headerOffset` `getItemLayout` derives, so the two cannot drift.
+- **1.3.1 / 1.3.2 cell↔column association** — rows are read one cell at a time and the header is off
+  to the side or scrolled away, so a bare value is unattributable. Every default-formatted cell's
+  `Text` announces `"<column header>: <value>"`. The list itself inherits
+  `accessibilityRole="list"` from `core/list`.
+
+## Patterns copied from the reference modules
+
+1. **Structure vs colour split** — layout/padding/border-width via `createThemedVariants`; colour
+   resolved from `RoleColors` only, applied inline (`Select`/`Menu`/`Banner`).
+2. **Pure, testable resolvers** in `DataTable.variants.ts` — contrast, sort cycling, and selection
+   set maths are unit-tested directly, never eyeballed or exercised only through a render test.
+3. **Closed unions** — `align`, `sortDirection` are closed unions, never a free-form prop.
+4. **Fully controlled sort/selection** — mirrors `Select`'s `value`/`onValueChange` contract: the
+   component reports intent, the caller owns the state.
+
+## Design decisions specific to this module
+
+- **One `FlatList`, not two scroll views kept in sync.** The header is that FlatList's own
+  `ListHeaderComponent`, pinned via `stickyHeaderIndices={[0]}` — RN's built-in mechanism for
+  exactly this, so there is no manual `onScroll`/`scrollTo` offset-mirroring between a header list
+  and a body list.
+- **`stickyHeader` must never become a position.** When `core/list`'s `VirtualList` had no
+  `ListHeaderComponent` prop, "sticky" was re-expressed here as *where* the header rendered:
+  `stickyHeader={false}` moved it below the list, so a screen reader read all N rows and *then* the
+  column labels naming them (WCAG 1.3.2, meaningful sequence). The header is now always
+  `ListHeaderComponent`; `stickyHeader` toggles `stickyHeaderIndices` and nothing else. The render
+  test asserts the header's **position in the rendered order**, not its presence — presence is what
+  stayed green through the regression.
+- **The empty state is `ListEmptyComponent`**, not a sibling that replaces the list, so the column
+  header survives an empty result set.
+- **`getItemLayout` is passed directly, not derived from `itemHeight`.** Offsets are measured from
+  the top of the scroll content and the header cell sits above row 0, so every row's offset carries
+  a leading `DATA_TABLE_HEADER_HEIGHT + borderWidths.thin`; without it `scrollToIndex` lands one
+  header short.
+- **Needs a bounded ancestor for the sticky header / internal scroll to do anything** — the same
+  requirement RN's own docs state for `ScrollView` ("needs a bounded height… by setting height
+  directly, or by flex"). Place `DataTable` in a `style={{ flex: 1 }}` (or explicit height)
+  container; unbounded, it renders at full content height and the enclosing screen scrolls it —
+  never invisible, just not independently scrollable.
+- **Row press vs. the selection checkbox** — the checkbox is its own nested `Pressable`; RN's
+  responder system lets the innermost element claim a touch, so pressing the checkbox never also
+  fires `onRowPress` (the standard, well-established RN pattern for a checkbox-in-row).
+- **Default cell text** reads `row[column.key]` through a narrow, documented `unknown` escape —
+  `T` is intentionally unconstrained so any row shape works without a `render`.
+
+## Known gaps
+
+- No pagination, column resize, or column reorder — v1 is fixed column widths from `columns`.
+- Skeleton is a fixed 5 rows regardless of `rowHeight` or viewport size.
+- `EmptyState` renders inside the same `totalWidth`-bound scroll region as the columns, so a very
+  narrow table gives it a narrow box rather than full screen width.
+- A column with a custom `render` gets no `"<header>: <value>"` label — the cell's content is the
+  caller's `ReactNode` and its text is not knowable here. Such a column should carry its own
+  accessible name inside `render`.
+
+## Performance
+
+Wrapped in `React.memo`; since the component itself is generic (`<T>`), `memo`'s erased type is
+restored with a documented `as typeof DataTableInner` cast. Header/row/skeleton/empty JSX are built
+inline per render, matching `Select`'s own precedent (its `renderItem` isn't extracted or memoized
+either) — real windowing for large datasets still comes from `FlatList` itself.
+
+## Modernization (v1.0.7)
+
+- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
+- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
+- `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.

package/lib/module/modules/data-table/index.js

@@ -0,0 +1,10 @@
+"use strict";
+
+/**
+ * Public surface of `pixelize-native-library/data-table`. Value exports and type exports are split
+ * for `verbatimModuleSyntax`. The resolvers (`resolveDataTableColors`, `nextSortDirection`, …) stay
+ * internal — a consumer configures a DataTable through its props, never by importing its internals.
+ */
+
+export { DataTable } from "./DataTable.js";
+//# sourceMappingURL=index.js.map

package/lib/module/modules/date-picker/Calendar.js

@@ -0,0 +1,368 @@
+"use strict";
+
+/**
+ * Calendar — the inline month grid every other export in this module composes. All of its date
+ * arithmetic lives in `DatePicker.variants.ts` (pure, unit-tested); this file is layout, state and
+ * accessibility only.
+ *
+ * The header doubles as a quick-jump toggle: while it is open the grid shows the twelve months of
+ * the cursor's year and the ‹ › controls page YEARS instead of months — one panel covering both
+ * dimensions, instead of a separate year grid and month grid to navigate between. The ‹ › controls
+ * themselves are the library's own `Button` (icon-only, ghost/neutral) — composed, not
+ * reimplemented; only the toggle needs a custom `Pressable`, for the `aria-expanded` (WCAG 4.1.2)
+ * `Button`'s closed a11y contract can't express (see `resolveCalendarChromeColors`).
+ *
+ * Keyboard (web only, WCAG 2.1.1): the 42 day cells are ONE tab stop, not 42 — exactly one carries
+ * `tabIndex={0}` and the arrows/Home/End/PageUp/PageDown move which. The DOM half lives in
+ * `Calendar.keys.web.ts`, the date arithmetic in `resolveCalendarFocusMove`; Enter/Space are left
+ * to `react-native-web`'s own `role="button"` press handling.
+ */
+
+import { memo, useCallback, useMemo, useRef, useState } from "react";
+import { Pressable, Text, View } from "react-native";
+import { Icon } from "../../core/icon/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { Button } from "../button/index.js";
+import { useCalendarGridFocus, useCalendarGridKeys } from "./Calendar.keys";
+import { addMonths, atNoon, buildMonthGrid, calendarDayCellStructure, calendarGridStructure, calendarHeaderButtonStructure, calendarHeaderStructure, calendarStructure, calendarWeekRowStructure, calendarWeekdayCellStructure, canShowMonth, canShowYear, chunkIntoWeeks, clampToRange, DEFAULT_FIRST_DAY_OF_WEEK, DEFAULT_LOCALE, EMPTY_RANGE, dayOrdinal, formatMonthYear, formatYear, isDateDisabled, isSameDay, isWithinRange, monthCursorOf, monthShortNames, nextRangeSelection, quickJumpCellStructure, quickJumpGridStructure, resolveCalendarChromeColors, resolveCalendarDayAccessibility, resolveCalendarDayColors, resolveCalendarFocusMove, toDayKey, weekdayLabels } from "./DatePicker.variants.js";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+const ICON_STROKE = 2;
+const HEADER_ICON_SIZE = 18;
+const CalendarDayCell = /*#__PURE__*/memo(function CalendarDayCell({
+  date,
+  dayOfMonth,
+  adjacent,
+  selected,
+  inRange,
+  disabled,
+  today,
+  tabIndex,
+  locale,
+  theme,
+  onPress,
+  testID
+}) {
+  const a11y = useMemo(() => resolveCalendarDayAccessibility({
+    date,
+    selected,
+    disabled,
+    inRange,
+    today,
+    locale
+  }), [date, selected, disabled, inRange, today, locale]);
+  const resting = useMemo(() => resolveCalendarDayColors(theme.colors, {
+    selected,
+    inRange,
+    adjacent,
+    disabled,
+    today,
+    pressed: false
+  }), [theme.colors, selected, inRange, adjacent, disabled, today]);
+  const pressedBackground = useMemo(() => resolveCalendarDayColors(theme.colors, {
+    selected,
+    inRange,
+    adjacent,
+    disabled,
+    today,
+    pressed: true
+  }).background, [theme.colors, selected, inRange, adjacent, disabled, today]);
+  const cellStructure = useMemo(() => calendarDayCellStructure(theme), [theme]);
+  const labelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    fontSize: theme.fontSizes.sm,
+    color: resting.label
+  }], [theme, resting.label]);
+  const handlePress = useCallback(() => {
+    if (!disabled) onPress(date);
+  }, [disabled, onPress, date]);
+  const cellStyle = useCallback(({
+    pressed
+  }) => [cellStructure, {
+    backgroundColor: pressed ? pressedBackground : resting.background,
+    borderColor: resting.ring
+  }], [cellStructure, pressedBackground, resting.background, resting.ring]);
+  return /*#__PURE__*/_jsx(Pressable, {
+    testID: testID,
+    accessibilityRole: a11y.accessibilityRole,
+    accessibilityLabel: a11y.accessibilityLabel,
+    "aria-selected": a11y["aria-selected"],
+    "aria-disabled": a11y["aria-disabled"],
+    disabled: disabled,
+    tabIndex: tabIndex,
+    onPress: handlePress,
+    style: cellStyle,
+    children: /*#__PURE__*/_jsx(Text, {
+      style: labelStyle,
+      children: dayOfMonth
+    })
+  });
+});
+const QuickJumpCell = /*#__PURE__*/memo(function QuickJumpCell({
+  month,
+  name,
+  selected,
+  disabled,
+  theme,
+  onPress,
+  testID
+}) {
+  const resting = useMemo(() => resolveCalendarDayColors(theme.colors, {
+    selected,
+    inRange: false,
+    adjacent: false,
+    disabled,
+    today: false,
+    pressed: false
+  }), [theme.colors, selected, disabled]);
+  const pressedBackground = useMemo(() => resolveCalendarDayColors(theme.colors, {
+    selected,
+    inRange: false,
+    adjacent: false,
+    disabled,
+    today: false,
+    pressed: true
+  }).background, [theme.colors, selected, disabled]);
+  const cellStructure = useMemo(() => quickJumpCellStructure(theme), [theme]);
+  const labelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.medium), {
+    fontSize: theme.fontSizes.sm,
+    color: resting.label
+  }], [theme, resting.label]);
+  const handlePress = useCallback(() => {
+    if (!disabled) onPress(month);
+  }, [disabled, onPress, month]);
+  const cellStyle = useCallback(({
+    pressed
+  }) => [cellStructure, {
+    backgroundColor: pressed ? pressedBackground : resting.background
+  }], [cellStructure, pressedBackground, resting.background]);
+  return /*#__PURE__*/_jsx(Pressable, {
+    testID: testID,
+    accessibilityRole: "button",
+    accessibilityLabel: name,
+    "aria-selected": selected,
+    "aria-disabled": disabled,
+    disabled: disabled,
+    onPress: handlePress,
+    style: cellStyle,
+    children: /*#__PURE__*/_jsx(Text, {
+      style: labelStyle,
+      children: name
+    })
+  });
+});
+export const Calendar = /*#__PURE__*/memo(function Calendar({
+  value,
+  onChange,
+  onSelect,
+  mode = "single",
+  rangeValue,
+  onRangeChange,
+  minDate,
+  maxDate,
+  disabledDates,
+  firstDayOfWeek = DEFAULT_FIRST_DAY_OF_WEEK,
+  locale = DEFAULT_LOCALE,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const chrome = useMemo(() => resolveCalendarChromeColors(theme.colors), [theme.colors]);
+  const range = rangeValue ?? EMPTY_RANGE;
+  const anchor = mode === "range" ? range.start : value ?? null;
+  const [cursor, setCursor] = useState(() => monthCursorOf(clampToRange(anchor ?? new Date(), minDate, maxDate)));
+  const [lastAnchorOrdinal, setLastAnchorOrdinal] = useState(anchor === null ? null : dayOrdinal(anchor));
+  const [quickJumpOpen, setQuickJumpOpen] = useState(false);
+  const [focusedDate, setFocusedDate] = useState(() => clampToRange(anchor ?? new Date(), minDate, maxDate));
+  const gridRef = useRef(null);
+
+  // React's "adjust state while rendering" pattern — a new selection from the caller pulls the grid
+  // to its month without an effect (and without the extra committed frame one would cost).
+  if (anchor !== null && dayOrdinal(anchor) !== lastAnchorOrdinal) {
+    setLastAnchorOrdinal(dayOrdinal(anchor));
+    setCursor(monthCursorOf(anchor));
+  }
+  const today = useMemo(() => atNoon(new Date()), []);
+  const weeks = useMemo(() => chunkIntoWeeks(buildMonthGrid(cursor.year, cursor.month, firstDayOfWeek)), [cursor.year, cursor.month, firstDayOfWeek]);
+  const weekdays = useMemo(() => weekdayLabels(firstDayOfWeek, locale), [firstDayOfWeek, locale]);
+  const months = useMemo(() => monthShortNames(locale), [locale]);
+  const selectDay = onSelect ?? onChange;
+  const handleDayPress = useCallback(date => {
+    setFocusedDate(atNoon(date));
+    if (mode === "range") {
+      onRangeChange?.(nextRangeSelection(range, date));
+      return;
+    }
+    selectDay?.(atNoon(date));
+  }, [mode, selectDay, onRangeChange, range]);
+  const step = quickJumpOpen ? 12 : 1;
+  const previousCursor = addMonths(cursor, -step);
+  const nextCursor = addMonths(cursor, step);
+  const canGoBack = quickJumpOpen ? canShowYear(previousCursor.year, minDate, maxDate) : canShowMonth(previousCursor, minDate, maxDate);
+  const canGoForward = quickJumpOpen ? canShowYear(nextCursor.year, minDate, maxDate) : canShowMonth(nextCursor, minDate, maxDate);
+  const goBack = useCallback(() => setCursor(current => addMonths(current, -step)), [step]);
+  const goForward = useCallback(() => setCursor(current => addMonths(current, step)), [step]);
+  const toggleQuickJump = useCallback(() => setQuickJumpOpen(open => !open), []);
+  const selectMonth = useCallback(month => {
+    setCursor(current => ({
+      year: current.year,
+      month
+    }));
+    setQuickJumpOpen(false);
+  }, []);
+  const rootStyle = useMemo(() => [calendarStructure(theme), {
+    backgroundColor: chrome.surface
+  }, style], [theme, chrome.surface, style]);
+  const headerStructure = useMemo(() => calendarHeaderStructure(theme), [theme]);
+  const quickJumpGrid = useMemo(() => quickJumpGridStructure(theme), [theme]);
+  const gridStructure = useMemo(() => calendarGridStructure(theme), [theme]);
+  const weekRowStructure = useMemo(() => calendarWeekRowStructure(theme), [theme]);
+  const weekdayCellStructure = useMemo(() => calendarWeekdayCellStructure(theme), [theme]);
+  const weekdayLabelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.medium), {
+    fontSize: theme.fontSizes.xs,
+    color: chrome.weekdayLabel
+  }], [theme, chrome.weekdayLabel]);
+  const headerLabelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.medium), {
+    fontSize: theme.fontSizes.md,
+    color: chrome.headerLabel
+  }], [theme, chrome.headerLabel]);
+  const headerButtonBase = useMemo(() => calendarHeaderButtonStructure(theme), [theme]);
+  const headerButtonStyle = useCallback(({
+    pressed
+  }) => [headerButtonBase, pressed && {
+    backgroundColor: chrome.headerPressed
+  }], [headerButtonBase, chrome.headerPressed]);
+  const weekDescriptors = useMemo(() => weeks.map(week => week.map(day => {
+    const disabled = isDateDisabled(day.date, {
+      minDate,
+      maxDate,
+      disabledDates
+    });
+    const selected = mode === "range" ? isSameDay(day.date, range.start) || isSameDay(day.date, range.end) : isSameDay(day.date, value);
+    return {
+      key: toDayKey(day.date),
+      date: day.date,
+      dayOfMonth: day.dayOfMonth,
+      adjacent: !day.inCurrentMonth,
+      selected,
+      inRange: mode === "range" && isWithinRange(day.date, range.start, range.end),
+      disabled,
+      today: isSameDay(day.date, today)
+    };
+  })), [weeks, minDate, maxDate, disabledDates, mode, range.start, range.end, value, today]);
+
+  // The roving tab stop. Falling back to the first day of the displayed month matters: paging with
+  // ‹ › can leave `focusedDate` outside the six weeks on screen, and a grid with no `tabIndex={0}`
+  // cell would have no tab stop at all — strictly worse than the 42 it replaces.
+  const focusedKey = toDayKey(focusedDate);
+  const activeDay = useMemo(() => {
+    const flat = weekDescriptors.flat();
+    return flat.find(day => day.key === focusedKey) ?? flat.find(day => !day.adjacent) ?? flat[0];
+  }, [weekDescriptors, focusedKey]);
+  const activeKey = activeDay?.key;
+  const handleGridMove = useCallback(move => {
+    const from = activeDay?.date;
+    if (from === undefined) return;
+    const next = clampToRange(resolveCalendarFocusMove(move, from, firstDayOfWeek), minDate, maxDate);
+    setFocusedDate(next);
+    setCursor(current => current.year === next.getFullYear() && current.month === next.getMonth() ? current : monthCursorOf(next));
+  }, [activeDay, firstDayOfWeek, minDate, maxDate]);
+  useCalendarGridKeys(gridRef, !quickJumpOpen, handleGridMove);
+  useCalendarGridFocus(gridRef, activeKey ?? "", !quickJumpOpen);
+  const quickJumpDescriptors = useMemo(() => months.map((name, month) => ({
+    name,
+    month,
+    selected: month === cursor.month,
+    disabled: !canShowMonth({
+      year: cursor.year,
+      month
+    }, minDate, maxDate)
+  })), [months, cursor.month, cursor.year, minDate, maxDate]);
+  return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
+    style: rootStyle,
+    children: [/*#__PURE__*/_jsxs(View, {
+      style: headerStructure,
+      children: [/*#__PURE__*/_jsx(Button, {
+        icon: "chevron-left",
+        accessibilityLabel: `Previous ${quickJumpOpen ? "year" : "month"}`,
+        variant: "ghost",
+        tone: "neutral",
+        size: "sm",
+        disabled: !canGoBack,
+        onPress: goBack,
+        testID: testID ? `${testID}-previous` : undefined
+      }), /*#__PURE__*/_jsxs(Pressable, {
+        testID: testID ? `${testID}-header` : undefined,
+        accessibilityRole: "button",
+        accessibilityLabel: quickJumpOpen ? formatYear(cursor.year, locale) : formatMonthYear(cursor, locale),
+        "aria-expanded": quickJumpOpen,
+        onPress: toggleQuickJump,
+        style: headerButtonStyle,
+        children: [/*#__PURE__*/_jsx(Text, {
+          numberOfLines: 1,
+          style: headerLabelStyle,
+          children: quickJumpOpen ? formatYear(cursor.year, locale) : formatMonthYear(cursor, locale)
+        }), /*#__PURE__*/_jsx(Icon, {
+          name: quickJumpOpen ? "chevron-up" : "chevron-down",
+          size: HEADER_ICON_SIZE,
+          color: chrome.headerIcon,
+          strokeWidth: ICON_STROKE
+        })]
+      }), /*#__PURE__*/_jsx(Button, {
+        icon: "chevron-right",
+        accessibilityLabel: `Next ${quickJumpOpen ? "year" : "month"}`,
+        variant: "ghost",
+        tone: "neutral",
+        size: "sm",
+        disabled: !canGoForward,
+        onPress: goForward,
+        testID: testID ? `${testID}-next` : undefined
+      })]
+    }), quickJumpOpen ? /*#__PURE__*/_jsx(View, {
+      style: quickJumpGrid,
+      children: quickJumpDescriptors.map(month => /*#__PURE__*/_jsx(QuickJumpCell, {
+        month: month.month,
+        name: month.name,
+        selected: month.selected,
+        disabled: month.disabled,
+        theme: theme,
+        onPress: selectMonth,
+        testID: testID ? `${testID}-month-${month.month}` : undefined
+      }, month.name))
+    }) : /*#__PURE__*/_jsxs(_Fragment, {
+      children: [/*#__PURE__*/_jsx(View, {
+        style: weekRowStructure,
+        children: weekdays.map((weekday, index) => /*#__PURE__*/_jsx(View
+        // Two weekdays can share an abbreviation in some locales, so the slot index is the key.
+        , {
+          "aria-hidden": true,
+          style: weekdayCellStructure,
+          children: /*#__PURE__*/_jsx(Text, {
+            style: weekdayLabelStyle,
+            children: weekday
+          })
+        }, `weekday-${index}`))
+      }), /*#__PURE__*/_jsx(View, {
+        ref: gridRef,
+        style: gridStructure,
+        children: weekDescriptors.map(week => /*#__PURE__*/_jsx(View, {
+          style: weekRowStructure,
+          children: week.map(day => /*#__PURE__*/_jsx(CalendarDayCell, {
+            date: day.date,
+            dayOfMonth: day.dayOfMonth,
+            adjacent: day.adjacent,
+            selected: day.selected,
+            inRange: day.inRange,
+            disabled: day.disabled,
+            today: day.today,
+            tabIndex: day.key === activeKey ? 0 : -1,
+            locale: locale,
+            theme: theme,
+            onPress: handleDayPress,
+            testID: testID ? `${testID}-day-${day.key}` : undefined
+          }, day.key))
+        }, week[0]?.key ?? "week"))
+      })]
+    })]
+  });
+});
+//# sourceMappingURL=Calendar.js.map

package/lib/module/modules/date-picker/Calendar.keys.js

@@ -0,0 +1,23 @@
+"use strict";
+
+/**
+ * Native/default counterpart of `Calendar.keys.web.ts`. A physical keyboard driving a month grid is
+ * a web concern, so both hooks are no-ops here with identical signatures.
+ *
+ * Same `.ts` / `.web.ts` pair `core/a11y/keyboard.ts` and `../modal/renderWebPortal.ts` use: Metro
+ * resolves the `.web.ts` only for a web bundle, so no DOM code enters the native graph, and Jest
+ * (whose `react-native` preset has no `web` platform) always resolves THIS file — the web half is
+ * tested by importing it explicitly.
+ *
+ * These live in the module rather than in `core/a11y` on purpose: `useRovingKeys` models one flat
+ * list on one axis, and a month grid is 2-D over Dates (week wrapping, month paging). Forcing it
+ * into that helper would distort both.
+ */
+
+export function useCalendarGridKeys(_ref, _active, _onMove) {
+  return;
+}
+export function useCalendarGridFocus(_ref, _focusedKey, _active) {
+  return;
+}
+//# sourceMappingURL=Calendar.keys.js.map

package/lib/module/modules/date-picker/Calendar.keys.web.js

@@ -0,0 +1,83 @@
+"use strict";
+
+/**
+ * Web implementation of the Calendar day-grid's keyboard navigation. Metro only resolves this file
+ * for a web bundle (see `Calendar.keys.ts`), so it is the one place here that may assume a DOM.
+ *
+ * The DOM types are hand-written for the same reason `core/a11y/keyboard.web.ts` writes its own:
+ * `tsconfig.json` sets `"lib": ["ESNext"]`, `any` is lint-banned, and augmenting `react-native`'s
+ * types would ship through `lib/typescript/**`. A module-local structural surface plus
+ * `declare const document` erases entirely at emit.
+ *
+ * This file owns ONLY the DOM half — which key means which move, and moving real focus. Every date
+ * calculation lives in `resolveCalendarFocusMove` (`DatePicker.variants.ts`), pure and unit-tested.
+ *
+ * Enter and Space are deliberately unhandled: the day cells are `role="button"`, which
+ * `react-native-web`'s `PressResponder.isValidKeyPress` already presses on both keys. Handling them
+ * here too would select the day twice.
+ */
+
+import { useEffect, useRef } from "react";
+/** `typeof` rather than a null check: a bare `document` reference throws outside a browser. */
+function getDocument() {
+  return typeof document === "undefined" ? undefined : document;
+}
+
+/** `react-native-web` forwards a component's ref to the host element it renders — the same
+ *  "assume a DOM in the `.web` file only" cast `renderWebPortal.web.ts` established. */
+function domNode(ref) {
+  return ref.current ?? null;
+}
+const MOVE_BY_KEY = {
+  ArrowLeft: "prevDay",
+  ArrowRight: "nextDay",
+  ArrowUp: "prevWeek",
+  ArrowDown: "nextWeek",
+  Home: "weekStart",
+  End: "weekEnd",
+  PageUp: "prevMonth",
+  PageDown: "nextMonth"
+};
+
+/**
+ * Arrow/Home/End/PageUp/PageDown on the grid container. Listens on the CONTAINER (capture phase),
+ * never on `document`, so two calendars on one page never fight over the same arrow key, and so an
+ * arrow pressed on the ‹ › header buttons is left alone.
+ */
+export function useCalendarGridKeys(ref, active, onMove) {
+  const onMoveRef = useRef(onMove);
+  onMoveRef.current = onMove;
+  useEffect(() => {
+    if (!active) return;
+    const node = domNode(ref);
+    if (node === null) return;
+    const handleKeyDown = event => {
+      const move = MOVE_BY_KEY[event.key];
+      if (move === undefined) return;
+      event.preventDefault();
+      onMoveRef.current(move);
+    };
+    node.addEventListener("keydown", handleKeyDown, true);
+    return () => node.removeEventListener("keydown", handleKeyDown, true);
+  }, [ref, active]);
+}
+
+/**
+ * Moves real DOM focus onto whichever day cell currently owns `tabIndex={0}`, after `focusedKey`
+ * changed the roving index.
+ *
+ * The `contains` guard is the whole safety of this hook: it only ever moves focus that is ALREADY
+ * inside the grid. Without it, a caller's own selection (or the first mount) would rip focus out of
+ * the field that opened the picker.
+ */
+export function useCalendarGridFocus(ref, focusedKey, active) {
+  useEffect(() => {
+    if (!active) return;
+    const doc = getDocument();
+    const node = domNode(ref);
+    if (doc === undefined || node === null) return;
+    if (!node.contains(doc.activeElement)) return;
+    node.querySelector('[tabindex="0"]')?.focus();
+  }, [ref, focusedKey, active]);
+}
+//# sourceMappingURL=Calendar.keys.web.js.map