fix: reset monthSelectedIn when changeMonth is called in custom header

Fixes #3829

When using monthsShown >= 2 with a custom header, calling changeMonth()
would produce inconsistent results depending on which calendar panel
the user last selected a date in. This was because the monthSelectedIn
state (which tracks the offset for multi-month display) was not being
reset when changeMonth was explicitly called.

This fix:
- Adds onMonthSelectedInChange callback prop to Calendar component
- Resets monthSelectedIn to 0 when changeMonth is called, ensuring
  the target month always appears in the leftmost position
- Adds test to verify the fix

Author: martijnrusschen

src/calendar.tsx

@@ -180,6 +180,7 @@ type CalendarProps = React.PropsWithChildren<
       showPreviousMonths?: boolean;
       monthsShown?: number;
       monthSelectedIn?: number;
+      onMonthSelectedInChange?: (monthSelectedIn: number) => void;
       onSelect: (
         day: Date,
         event?:
@@ -455,7 +456,12 @@ export default class Calendar extends Component<CalendarProps, CalendarState> {
       ({ date }) => ({
         date: setMonth(date, Number(month)),
       }),
-      () => this.handleMonthChange(this.state.date),
+      () => {
+        this.handleMonthChange(this.state.date);
+        // Reset monthSelectedIn to 0 so the target month appears in the leftmost position
+        // This ensures consistent behavior when using changeMonth in custom headers
+        this.props.onMonthSelectedInChange?.(0);
+      },
     );
   };
 

src/index.tsx

@@ -1461,6 +1461,10 @@ export class DatePicker extends Component<DatePickerProps, DatePickerState> {
     }
   };
 
+  handleMonthSelectedInChange = (monthSelectedIn: number): void => {
+    this.setState({ monthSelectedIn });
+  };
+
   renderCalendar = () => {
     if (!this.props.inline && !this.isCalendarOpen()) {
       return null;
@@ -1492,6 +1496,7 @@ export class DatePicker extends Component<DatePickerProps, DatePickerState> {
         dropdownMode={
           this.props.dropdownMode ?? DatePicker.defaultProps.dropdownMode
         }
+        onMonthSelectedInChange={this.handleMonthSelectedInChange}
       >
         {this.props.children}
       </Calendar>

src/test/calendar_test.test.tsx

@@ -984,6 +984,47 @@ describe("Calendar", () => {
       expect(header).toHaveLength(1);
       expect(time).toHaveLength(1);
     });
+
+    it("should display the target month in the leftmost position when changeMonth is called with monthsShown >= 2", () => {
+      // This test verifies the fix for issue #3829
+      // When using changeMonth in a custom header with monthsShown >= 2,
+      // the target month should always appear in the leftmost position
+      // regardless of which calendar panel the user last selected a date in
+      const onMonthSelectedInChangeSpy = jest.fn();
+
+      const renderCustomHeaderWithMonthSelect = ({
+        changeMonth,
+      }: {
+        changeMonth: (month: number) => void;
+      }) => (
+        <div className="custom-header">
+          <select
+            className="month-select"
+            onChange={({ target: { value } }) => changeMonth(Number(value))}
+          >
+            {months.map((option, index) => (
+              <option key={option} value={index}>
+                {option}
+              </option>
+            ))}
+          </select>
+        </div>
+      );
+
+      const { calendar } = getCalendar({
+        renderCustomHeader: renderCustomHeaderWithMonthSelect,
+        monthsShown: 2,
+        onMonthSelectedInChange: onMonthSelectedInChangeSpy,
+      });
+
+      // Select June (month index 5) from the month dropdown
+      const monthSelect = safeQuerySelector(calendar, ".month-select");
+      fireEvent.change(monthSelect, { target: { value: 5 } });
+
+      // Verify that onMonthSelectedInChange was called with 0
+      // This ensures the target month appears in the leftmost position
+      expect(onMonthSelectedInChangeSpy).toHaveBeenCalledWith(0);
+    });
   });
 
   describe("when showDisabledMonthNavigation is enabled", () => {