fix(DatePicker): remove controlled visibleMonth/onVisibleMonthChange, keep defaultVisibleMonth

Per review feedback, the controlled visibleMonth prop and its onVisibleMonthChange
callback are redundant with the existing onChange/onNext/onPrevious callbacks.
Consumers who need to track the rendered month (e.g. to re-anchor a comparison
picker) can rely on those instead. Keeps the uncontrolled defaultVisibleMonth
anchor, which covers the original comparison-range use case.

Author: rkdotxyz

.changeset/datepicker-visible-month.md

@@ -2,9 +2,9 @@
 '@razorpay/blade': minor
 ---
 
-feat(DatePicker): add `visibleMonth`/`defaultVisibleMonth` to control the rendered calendar month independently of `value`
+feat(DatePicker): add `defaultVisibleMonth` to anchor the rendered calendar month independently of `value`
 
-`DatePicker`/`DateRangePicker` now accept `visibleMonth` (controlled), `defaultVisibleMonth` (uncontrolled), and `onVisibleMonthChange` props. These let the calendar open on a specific month without pre-selecting a date — useful for a "comparison" range picker that should default to the period immediately preceding a primary range picker's selection, while leaving the comparison `value` empty for the user to pick.
+`DatePicker`/`DateRangePicker` now accept a `defaultVisibleMonth` prop. This lets the calendar open on a specific month without pre-selecting a date — useful for a "comparison" range picker that should default to the period immediately preceding a primary range picker's selection, while leaving the comparison `value` empty for the user to pick.
 
 ```tsx
 <DatePicker
@@ -14,4 +14,6 @@ feat(DatePicker): add `visibleMonth`/`defaultVisibleMonth` to control the render
 />
 ```
 
+`defaultVisibleMonth` only sets the initial anchor — subsequent calendar navigation is uncontrolled from that point on. Use the existing `onNext`/`onPrevious` callbacks to observe navigation, and `onChange` to observe date selection.
+
 Falls back to the existing behavior (first date of `value`/`defaultValue`, or today) when not set — fully backwards compatible.

packages/blade/src/components/DatePicker/BaseDatePicker.web.tsx

@@ -78,9 +78,7 @@ const BaseDatePicker = <Type extends DateSelectionType = 'single'>({
   defaultPicker = 'day',
   picker,
   onPickerChange,
-  visibleMonth,
   defaultVisibleMonth,
-  onVisibleMonthChange,
   zIndex = componentZIndices.popover,
   format = 'DD/MM/YYYY',
   inputPlaceHolder,
@@ -369,9 +367,7 @@ const BaseDatePicker = <Type extends DateSelectionType = 'single'>({
             {...props}
             selectionType={_selectionType}
             defaultValue={defaultValue}
-            visibleMonth={visibleMonth}
             defaultVisibleMonth={defaultVisibleMonth}
-            onVisibleMonthChange={onVisibleMonthChange}
             onMouseLeave={onRootMouseLeave}
             __onDayMouseEnter={(_event, date) => {
               onHoveredDateChange(date);

packages/blade/src/components/DatePicker/Calendar.web.tsx

@@ -26,9 +26,7 @@ const Calendar = <Type extends DateSelectionType>({
   date,
   defaultDate,
   onDateChange,
-  visibleMonth,
   defaultVisibleMonth,
-  onVisibleMonthChange,
   onNext,
   onPrevious,
   presets,
@@ -69,11 +67,7 @@ const Calendar = <Type extends DateSelectionType>({
   });
 
   const [_visibleMonth, setVisibleMonth] = useControllableState<Date | undefined>({
-    value: visibleMonth,
     defaultValue: defaultVisibleMonth,
-    onChange: (date) => {
-      if (date) onVisibleMonthChange?.(date);
-    },
   });
 
   const dateContext = useDatesContext();
@@ -97,8 +91,9 @@ const Calendar = <Type extends DateSelectionType>({
   const numberOfColumns = isMobile || !isRange ? 1 : 2;
   const columnsToScroll = numberOfColumns;
 
-  // Keeps the legacy `_date` state and the new `_visibleMonth` state in sync so that
-  // navigation keeps working regardless of which one is currently driving `currentDate`.
+  // Keeps the legacy `_date` state and `_visibleMonth` (the defaultVisibleMonth anchor)
+  // in sync so navigation keeps working regardless of which one is currently driving
+  // `currentDate`.
   // Note: Not wrapped in useCallback because `setDate` from mantine's `useUncontrolled`
   // is not memoized, so useCallback would provide no benefit.
   const updateCurrentDate = (nextDate: Date): void => {

packages/blade/src/components/DatePicker/DatePicker.native.tsx

@@ -382,16 +382,12 @@ function _DatePicker<Type extends DateSelectionType = 'single'>(
     picker,
     defaultPicker,
     onPickerChange,
-    visibleMonth: visibleMonthProp,
     defaultVisibleMonth,
-    onVisibleMonthChange,
   } = props as DatePickerNativeProps<DateSelectionType> & {
     picker?: unknown;
     defaultPicker?: unknown;
     onPickerChange?: unknown;
-    visibleMonth?: unknown;
     defaultVisibleMonth?: unknown;
-    onVisibleMonthChange?: unknown;
     successText?: unknown;
   };
 
@@ -401,9 +397,7 @@ function _DatePicker<Type extends DateSelectionType = 'single'>(
     if (picker !== undefined) unsupported.push('picker');
     if (defaultPicker !== undefined) unsupported.push('defaultPicker');
     if (onPickerChange !== undefined) unsupported.push('onPickerChange');
-    if (visibleMonthProp !== undefined) unsupported.push('visibleMonth');
     if (defaultVisibleMonth !== undefined) unsupported.push('defaultVisibleMonth');
-    if (onVisibleMonthChange !== undefined) unsupported.push('onVisibleMonthChange');
     if (unsupported.length > 0) {
       logger({
         type: 'warn',
@@ -413,14 +407,7 @@ function _DatePicker<Type extends DateSelectionType = 'single'>(
         )}.`,
       });
     }
-  }, [
-    picker,
-    defaultPicker,
-    onPickerChange,
-    visibleMonthProp,
-    defaultVisibleMonth,
-    onVisibleMonthChange,
-  ]);
+  }, [picker, defaultPicker, onPickerChange, defaultVisibleMonth]);
 
   const isError = validationState === 'error';
   const isSuccess = validationState === 'success';
@@ -732,8 +719,8 @@ function _DatePicker<Type extends DateSelectionType = 'single'>(
  * #### Not yet supported on native
  *
  * Month/year picker variants (`picker`, `defaultPicker`, `onPickerChange`),
- * `visibleMonth`/`defaultVisibleMonth`/`onVisibleMonthChange`, masked text
- * input, and the form-validation props (`validationState`, `helpText`,
+ * `defaultVisibleMonth`, masked text input, and the form-validation props
+ * (`validationState`, `helpText`,
  * `errorText`, `isRequired`, `necessityIndicator`, `labelPosition`). Passing
  * any of these emits a `__DEV__` warning and they are otherwise ignored at
  * runtime.

packages/blade/src/components/DatePicker/DatePicker.stories.tsx

@@ -47,9 +47,7 @@ export default {
     maxDate: baseProp,
     excludeDate: baseProp,
     picker: baseProp,
-    visibleMonth: baseProp,
     defaultVisibleMonth: baseProp,
-    onVisibleMonthChange: baseProp,
     onOpenChange: baseProp,
     allowSingleDateInRange: baseProp,
     defaultIsOpen: baseProp,
@@ -1370,11 +1368,14 @@ export const DatePickerComparisonRange: StoryFn<typeof DatePickerComponent> = ()
   return (
     <Box>
       <Text marginBottom="spacing.5">
-        Use <Code size="medium">visibleMonth</Code>/<Code size="medium">defaultVisibleMonth</Code>{' '}
-        to anchor a comparison <Code size="medium">DatePicker</Code> on the months immediately
-        preceding a primary range&apos;s selection — without pre-filling the comparison{' '}
-        <Code size="medium">value</Code>. Pick a primary range below, then open &quot;Compare
-        to&quot; and notice the calendar opens on the same-length period right before it.
+        Use <Code size="medium">defaultVisibleMonth</Code> to anchor a comparison{' '}
+        <Code size="medium">DatePicker</Code> on the months immediately preceding a primary
+        range&apos;s selection — without pre-filling the comparison{' '}
+        <Code size="medium">value</Code>. Since <Code size="medium">defaultVisibleMonth</Code>{' '}
+        only sets the initial anchor, remounting via a <Code size="medium">key</Code> re-anchors
+        the calendar whenever the computed comparison month changes. Pick a primary range below,
+        then open &quot;Compare to&quot; and notice the calendar opens on the same-length period
+        right before it.
       </Text>
       <Box display="flex" flexDirection="column" gap="spacing.5" maxWidth="400px">
         <DatePickerComponent
@@ -1384,18 +1385,18 @@ export const DatePickerComparisonRange: StoryFn<typeof DatePickerComponent> = ()
           onChange={(date) => setPrimaryRange(date)}
         />
         <DatePickerComponent
+          key={comparisonVisibleMonth?.toISOString()}
           label={{ start: 'Compare to' }}
           selectionType="range"
           value={comparisonRange}
-          visibleMonth={comparisonVisibleMonth}
-          onVisibleMonthChange={setComparisonVisibleMonth}
+          defaultVisibleMonth={comparisonVisibleMonth}
           onChange={(date) => setComparisonRange(date)}
         />
       </Box>
     </Box>
   );
 };
 
-DatePickerComparisonRange.storyName = 'Comparison Range (visibleMonth)';
+DatePickerComparisonRange.storyName = 'Comparison Range (defaultVisibleMonth)';
 
 DatePickerWithTimePickerInModal.storyName = 'DatePicker with TimePicker (Modal)';

packages/blade/src/components/DatePicker/__tests__/DatePicker.visibleMonth.web.test.tsx

@@ -27,7 +27,7 @@ describe('<DatePicker/> visibleMonth', () => {
     expect(getAllByText(dayjs(anchorMonth).format('MMMM YYYY')).length).toBeGreaterThan(0);
   });
 
-  it('gives visibleMonth priority over the first date of a controlled value', async () => {
+  it('gives defaultVisibleMonth priority over the first date of a controlled value', async () => {
     const anchorMonth = dayjs().subtract(6, 'month').toDate();
     const selectedRange = [dayjs().toDate(), dayjs().add(3, 'day').toDate()] as [Date, Date];
 
@@ -36,7 +36,7 @@ describe('<DatePicker/> visibleMonth', () => {
         selectionType="range"
         label={{ start: 'Compare to' }}
         value={selectedRange}
-        visibleMonth={anchorMonth}
+        defaultVisibleMonth={anchorMonth}
         onChange={() => undefined}
       />,
     );
@@ -49,16 +49,19 @@ describe('<DatePicker/> visibleMonth', () => {
     expect(getAllByText(dayjs(anchorMonth).format('MMMM YYYY')).length).toBeGreaterThan(0);
   });
 
-  it('fires onVisibleMonthChange when navigating to the next month in controlled mode', async () => {
+  it('fires onNext with the correct date when navigating to the next month', async () => {
+    // Consumers who need to track the rendered month (e.g. to re-anchor a
+    // comparison picker) should rely on the existing onNext/onPrevious
+    // callbacks rather than a dedicated visible-month callback.
     const anchorMonth = dayjs().subtract(4, 'month').toDate();
-    const onVisibleMonthChange = jest.fn();
+    const onNext = jest.fn();
 
     const { getByRole, queryByText } = renderWithTheme(
       <DatePickerComponent
         selectionType="range"
         label={{ start: 'Compare to' }}
-        visibleMonth={anchorMonth}
-        onVisibleMonthChange={onVisibleMonthChange}
+        defaultVisibleMonth={anchorMonth}
+        onNext={onNext}
       />,
     );
 
@@ -71,10 +74,11 @@ describe('<DatePicker/> visibleMonth', () => {
     const nextButton = getByRole('button', { name: /Next/i });
     await user.click(nextButton);
 
-    expect(onVisibleMonthChange).toHaveBeenCalledTimes(1);
-    const calledDate = onVisibleMonthChange.mock.calls[0][0] as Date;
+    expect(onNext).toHaveBeenCalledTimes(1);
+    const { date: calledDate, type } = onNext.mock.calls[0][0] as { date: Date; type: string };
     // Range picker on desktop shows 2 columns, so "Next" advances by 2 months
     const expectedDate = dayjs(anchorMonth).add(2, 'month').toDate();
+    expect(type).toBe('month');
     expect(dayjs(calledDate).isSame(expectedDate, 'month')).toBe(true);
   });
 

packages/blade/src/components/DatePicker/types.ts

@@ -60,34 +60,22 @@ type CalendarProps<SelectionType extends DateSelectionType> = Pick<
   onPickerChange?: (picker: PickerType) => void;
 
   /**
-   * Controlled month that the calendar renders, independent of the selected `value`.
+   * Sets the initial month the calendar renders, independent of the selected `value`.
    *
    * Useful when you want the calendar to open on a specific month without pre-selecting
    * a date — e.g. a "comparison" range picker that should default to the period
    * immediately preceding a primary range picker's selection.
    *
    * Falls back to the first date of `value`/`defaultValue` (or today) when not set.
-   *
-   * When `visibleMonth` is controlled, you must handle `onVisibleMonthChange` to keep
-   * the prop in sync — otherwise calendar navigation will not work.
+   * Only sets the initial anchor — subsequent calendar navigation (next/previous
+   * month, year, decade) is uncontrolled from that point on. Use `onChange` to
+   * observe date selection.
    *
    * @example
    * // Anchor a comparison picker to the month before the primary range's start
-   * <DatePicker selectionType="range" visibleMonth={dayjs(primaryStart).subtract(1, 'month').toDate()} />
-   */
-  visibleMonth?: Date;
-  /**
-   * Uncontrolled variant of `visibleMonth`. Sets the initial month the calendar renders,
-   * without pre-selecting a date.
+   * <DatePicker selectionType="range" defaultVisibleMonth={dayjs(primaryStart).subtract(1, 'month').toDate()} />
    */
   defaultVisibleMonth?: Date;
-  /**
-   * Callback which fires when the rendered month changes, either via calendar
-   * navigation (next/previous month, year, or decade) or when a date in a
-   * different month is selected. Does not fire when the `visibleMonth` prop
-   * is updated externally by the consumer.
-   */
-  onVisibleMonthChange?: (date: Date) => void;
 
   /**
    * Controlled isOpen state