@xsolla/xui-calendar 0.227.0 → 0.228.0

package/README.md

@@ -208,6 +208,7 @@ export default function DualRange() {
 - Each panel navigates on its own. The arrows and the month/year dropdowns of one panel do not move the other panel.
 - A chip, or a `month` value that neither panel shows, re-pairs the panels: the left panel shows that month and the right panel shows the next month.
 - With a complete range, a click in the right panel changes only the end date. A click on a day before the start date, or any click in the left panel, starts a new range.
+- Keyboard focus in a panel's day grid stays inside that panel's visible month; use the panel's arrows or month/year menus to change month.
 
 ### CalendarChips
 
@@ -229,20 +230,21 @@ interface CalendarChipOption {
 
 ### CalendarGrid
 
-| Prop           | Type                   | Default  | Description                   |
-| :------------- | :--------------------- | :------- | :---------------------------- |
-| currentMonth   | `Date`                 | required | The month to render.          |
-| locale         | `string`               | `"enUS"` | Date-fns locale identifier.   |
-| firstDayOfWeek | `number`               | `0`      | First day of week.            |
-| selectsRange   | `boolean`              | `false`  | Enable range mode.            |
-| minDate        | `Date \| null`         | -        | Minimum selectable date.      |
-| maxDate        | `Date \| null`         | -        | Maximum selectable date.      |
-| startDate      | `Date \| null`         | -        | Range start date.             |
-| endDate        | `Date \| null`         | -        | Range end date.               |
-| selectedDate   | `Date \| null`         | -        | Selected date (single mode).  |
-| selectingRange | `Date \| null`         | -        | Intermediate range selection. |
-| onDayPress     | `(date: Date) => void` | -        | Day press callback.           |
-| testID         | `string`               | -        | Test identifier.              |
+| Prop           | Type                    | Default  | Description                                                                                                                  |
+| :------------- | :---------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------- |
+| currentMonth   | `Date`                  | required | The month to render.                                                                                                         |
+| locale         | `string`                | `"enUS"` | Date-fns locale identifier.                                                                                                  |
+| firstDayOfWeek | `number`                | `0`      | First day of week.                                                                                                           |
+| selectsRange   | `boolean`               | `false`  | Enable range mode.                                                                                                           |
+| minDate        | `Date \| null`          | -        | Minimum selectable date.                                                                                                     |
+| maxDate        | `Date \| null`          | -        | Maximum selectable date.                                                                                                     |
+| startDate      | `Date \| null`          | -        | Range start date.                                                                                                            |
+| endDate        | `Date \| null`          | -        | Range end date.                                                                                                              |
+| selectedDate   | `Date \| null`          | -        | Selected date (single mode).                                                                                                 |
+| selectingRange | `Date \| null`          | -        | Intermediate range selection.                                                                                                |
+| onDayPress     | `(date: Date) => void`  | -        | Day press callback. Also fired by Enter / Space on the focused day.                                                          |
+| onMonthChange  | `(month: Date) => void` | -        | Called with the first day of a month when keyboard focus moves past the visible month. Without it, focus stays in the month. |
+| testID         | `string`                | -        | Test identifier.                                                                                                             |
 
 ## Platform Support
 
@@ -256,6 +258,21 @@ This package works on both **web** and **React Native**. All components use cros
 ## Accessibility
 
 - Navigation buttons have aria-labels ("Previous month", "Next month")
-- Month and year selectors are accessible via Select component
-- Day cells support keyboard navigation
+- Month and year selectors are Select components: each is a tab stop and opens, navigates and selects with the keyboard (see the Select docs)
+- The day grid has `role="grid"`, week rows `role="row"`, weekday labels `role="columnheader"` and days `role="gridcell"`
+- Each day in the visible month has an `aria-label` with the full date (e.g. "Thursday, 15 January 2026"), plus `aria-selected`, `aria-disabled` for days outside `minDate` / `maxDate`, and `aria-current="date"` for today
 - Chip selection follows radio-group pattern (single active item)
+
+### Keyboard (web)
+
+Tab order: Previous month → month menu → year menu → Next month → day grid. The day grid is a single tab stop (roving `tabIndex`): the selected day (or the range start), else today, else the first day of the month.
+
+| Key | Action |
+| :-- | :----- |
+| ← / → | Previous / next day |
+| ↑ / ↓ | Same day, previous / next week |
+| Home / End | First / last day of the week |
+| PageUp / PageDown | Same day, previous / next month |
+| Enter / Space | Selects the focused day (no effect on a disabled day) |
+
+When focus moves past the visible month, Calendar switches to that month. In DualCalendar, focus stays inside each panel's month.

package/native/index.d.mts

@@ -40,6 +40,12 @@ interface CalendarGridProps extends ThemeOverrideProps {
     selectedDate?: Date | null;
     selectingRange?: Date | null;
     onDayPress?: (date: Date) => void;
+    /**
+     * Called with the first day of a month when keyboard navigation moves past
+     * the visible month (arrow keys, PageUp/PageDown). Without it, keyboard
+     * focus stays inside the visible month.
+     */
+    onMonthChange?: (month: Date) => void;
     testID?: string;
 }
 interface CalendarHeaderProps extends ThemeOverrideProps {

package/native/index.d.ts

@@ -40,6 +40,12 @@ interface CalendarGridProps extends ThemeOverrideProps {
     selectedDate?: Date | null;
     selectingRange?: Date | null;
     onDayPress?: (date: Date) => void;
+    /**
+     * Called with the first day of a month when keyboard navigation moves past
+     * the visible month (arrow keys, PageUp/PageDown). Without it, keyboard
+     * focus stays inside the visible month.
+     */
+    onMonthChange?: (month: Date) => void;
     testID?: string;
 }
 interface CalendarHeaderProps extends ThemeOverrideProps {

package/native/index.js

@@ -348,6 +348,9 @@ var Text = ({
   );
 };
 
+// ../../foundation/primitives-native/src/index.tsx
+var isWeb = false;
+
 // src/Calendar.tsx
 var import_xui_core3 = require("@xsolla/xui-core");
 var import_date_fns3 = require("date-fns");
@@ -509,6 +512,7 @@ var locales2 = __toESM(require("date-fns/locale"));
 var import_jsx_runtime4 = require("react/jsx-runtime");
 var DAY_CELL_WIDTH = 40;
 var GRID_WIDTH = DAY_CELL_WIDTH * 7;
+var dayKeyOf = (date) => (0, import_date_fns2.format)(date, "yyyy-MM-dd");
 var CalendarGrid = ({
   currentMonth,
   locale = "enUS",
@@ -521,6 +525,7 @@ var CalendarGrid = ({
   selectedDate,
   selectingRange,
   onDayPress,
+  onMonthChange,
   testID,
   themeMode,
   themeProductContext
@@ -569,33 +574,122 @@ var CalendarGrid = ({
     },
     [selectsRange, startDate, endDate, selectingRange]
   );
-  return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(Box, { testID, children: [
+  const [focusedDate, setFocusedDate] = (0, import_react2.useState)(null);
+  const dayRefs = (0, import_react2.useRef)(/* @__PURE__ */ new Map());
+  const shouldMoveFocus = (0, import_react2.useRef)(false);
+  const tabStopDate = (0, import_react2.useMemo)(() => {
+    if (focusedDate && (0, import_date_fns2.isSameMonth)(focusedDate, currentMonth)) {
+      return focusedDate;
+    }
+    const preferred = selectsRange ? startDate : selectedDate;
+    if (preferred && (0, import_date_fns2.isSameMonth)(preferred, currentMonth)) return preferred;
+    const today = /* @__PURE__ */ new Date();
+    if ((0, import_date_fns2.isSameMonth)(today, currentMonth)) return today;
+    return monthStart;
+  }, [
+    focusedDate,
+    currentMonth,
+    selectsRange,
+    startDate,
+    selectedDate,
+    monthStart
+  ]);
+  const tabStopKey = dayKeyOf(tabStopDate);
+  (0, import_react2.useEffect)(() => {
+    if (!shouldMoveFocus.current) return;
+    shouldMoveFocus.current = false;
+    dayRefs.current.get(tabStopKey)?.focus();
+  }, [tabStopKey, currentMonth]);
+  const moveFocus = (0, import_react2.useCallback)(
+    (target) => {
+      if (!(0, import_date_fns2.isSameMonth)(target, currentMonth)) {
+        if (!onMonthChange) return;
+        onMonthChange((0, import_date_fns2.startOfMonth)(target));
+      }
+      shouldMoveFocus.current = true;
+      setFocusedDate(target);
+    },
+    [currentMonth, onMonthChange]
+  );
+  const handleDayKeyDown = (0, import_react2.useCallback)(
+    (event, day) => {
+      let target = null;
+      switch (event.key) {
+        case "ArrowLeft":
+          target = (0, import_date_fns2.addDays)(day, -1);
+          break;
+        case "ArrowRight":
+          target = (0, import_date_fns2.addDays)(day, 1);
+          break;
+        case "ArrowUp":
+          target = (0, import_date_fns2.addDays)(day, -7);
+          break;
+        case "ArrowDown":
+          target = (0, import_date_fns2.addDays)(day, 7);
+          break;
+        case "Home":
+          target = (0, import_date_fns2.startOfWeek)(day, { weekStartsOn });
+          break;
+        case "End":
+          target = (0, import_date_fns2.endOfWeek)(day, { weekStartsOn });
+          break;
+        case "PageUp":
+          target = (0, import_date_fns2.addMonths)(day, -1);
+          break;
+        case "PageDown":
+          target = (0, import_date_fns2.addMonths)(day, 1);
+          break;
+        case "Enter":
+        case " ":
+          event.preventDefault();
+          if (!isDateDisabled(day)) onDayPress?.(day);
+          return;
+        default:
+          return;
+      }
+      event.preventDefault();
+      moveFocus(target);
+    },
+    [isDateDisabled, moveFocus, onDayPress, weekStartsOn]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(Box, { testID, role: "grid", children: [
     /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
       Box,
       {
+        role: "row",
         flexDirection: "row",
         justifyContent: "flex-start",
         width: GRID_WIDTH,
         marginBottom: 8,
-        children: weekDays.map((day, i) => /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(Box, { width: DAY_CELL_WIDTH, alignItems: "center", children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
-          Text,
+        children: weekDays.map((day, i) => /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+          Box,
           {
-            fontSize: 12,
-            fontWeight: "600",
-            color: theme.colors.content.tertiary,
-            children: day.toUpperCase()
-          }
-        ) }, i))
+            role: "columnheader",
+            width: DAY_CELL_WIDTH,
+            alignItems: "center",
+            children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+              Text,
+              {
+                fontSize: 12,
+                fontWeight: "600",
+                color: theme.colors.content.tertiary,
+                children: day.toUpperCase()
+              }
+            )
+          },
+          i
+        ))
       }
     ),
     /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(Box, { gap: 2, children: weeks.map((week, i) => /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
       Box,
       {
+        role: "row",
         flexDirection: "row",
         justifyContent: "flex-start",
         width: GRID_WIDTH,
         children: week.map((day, j) => {
-          const dayKey = (0, import_date_fns2.format)(day, "yyyy-MM-dd");
+          const dayKey = dayKeyOf(day);
           const isOutsideMonth = !(0, import_date_fns2.isSameMonth)(day, currentMonth);
           const isSelected = !selectsRange && selectedDate && (0, import_date_fns2.isSameDay)(day, selectedDate) || selectsRange && startDate && endDate && (0, import_date_fns2.isSameDay)(day, startDate) && (0, import_date_fns2.isSameDay)(day, endDate);
           const isRangeStart = selectsRange && startDate && (0, import_date_fns2.isSameDay)(day, startDate);
@@ -605,6 +699,7 @@ var CalendarGrid = ({
           const disabled = isDateDisabled(day);
           const isHoverable = !disabled && !isOutsideMonth && !isSelected && !isRangeStart && !isRangeEnd;
           const isHovered = isHoverable && hoveredKey === dayKey;
+          const isTabStop = !isOutsideMonth && dayKey === tabStopKey;
           let bgColor = "transparent";
           let textColor = theme.colors.content.primary;
           if (isSelected || isRangeStart || isRangeEnd || inRange) {
@@ -616,9 +711,23 @@ var CalendarGrid = ({
           } else if (isOutsideMonth || disabled) {
             textColor = theme.colors.control.text.disable;
           }
+          const keyboardProps = isWeb && !isOutsideMonth ? {
+            ref: (node) => {
+              if (node) dayRefs.current.set(dayKey, node);
+              else dayRefs.current.delete(dayKey);
+            },
+            tabIndex: isTabStop ? 0 : -1,
+            onKeyDown: (event) => handleDayKeyDown(event, day)
+          } : {};
           return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
             Box,
             {
+              ...keyboardProps,
+              role: "gridcell",
+              "aria-label": isOutsideMonth ? void 0 : (0, import_date_fns2.format)(day, "EEEE, d MMMM yyyy", { locale: localeObj }),
+              "aria-selected": isOutsideMonth ? void 0 : Boolean(isSelected || isRangeStart || isRangeEnd),
+              "aria-disabled": disabled || isOutsideMonth || void 0,
+              "aria-current": today ? "date" : void 0,
               width: DAY_CELL_WIDTH,
               height: 32,
               alignItems: "center",
@@ -629,7 +738,11 @@ var CalendarGrid = ({
               borderBottomRightRadius: isSelected || isRangeEnd ? 4 : 0,
               backgroundColor: bgColor,
               cursor: disabled || isOutsideMonth ? "default" : "pointer",
-              onPress: () => !disabled && !isOutsideMonth && onDayPress?.(day),
+              onPress: () => {
+                if (disabled || isOutsideMonth) return;
+                setFocusedDate(day);
+                onDayPress?.(day);
+              },
               onMouseEnter: () => isHoverable && setHoveredKey(dayKey),
               onMouseLeave: () => setHoveredKey(
                 (current) => current === dayKey ? null : current
@@ -897,6 +1010,7 @@ var Calendar = (0, import_react3.forwardRef)(
               selectedDate: locSelectedDate,
               selectingRange,
               onDayPress: handleChange,
+              onMonthChange: setCurrentMonth,
               themeMode,
               themeProductContext
             }