fix(DatePicker): align modelValue prop type with sibling pickers (#2657)

zernonia · web-flow · commit c3c3729d5e4b · 2026-05-22T17:14:03.000+08:00
Calendar, MonthPicker, and YearPicker accepted `DateValue | DateValue[] | undefined` while DatePicker, RangeCalendar, and the range pickers also accepted `null`. Add `| null` to bring the single/multi-select pickers in line with the range variants so consumers binding form state that uses `null` as the empty value get a consistent API. Refs #2600
diff --git a/packages/core/src/Calendar/CalendarRoot.vue b/packages/core/src/Calendar/CalendarRoot.vue
@@ -98,7 +98,7 @@ export interface CalendarRootProps extends PrimitiveProps {
   /** A function that returns the previous page of the calendar. It receives the current placeholder as an argument inside the component. */
   prevPage?: (placeholder: DateValue) => DateValue
   /** The controlled selected date value of the calendar. Can be bound as `v-model`. */
-  modelValue?: DateValue | DateValue[] | undefined
+  modelValue?: DateValue | DateValue[] | null
   /** Whether multiple dates can be selected */
   multiple?: boolean
   /** Whether or not to disable days outside the current view. */
diff --git a/packages/core/src/DateRangeField/DateRangeFieldRoot.vue b/packages/core/src/DateRangeField/DateRangeFieldRoot.vue
@@ -84,7 +84,7 @@ export interface DateRangeFieldRootProps extends PrimitiveProps, FormFieldProps
 
 export type DateRangeFieldRootEmits = {
   /** Event handler called whenever the model value changes */
-  'update:modelValue': [DateRange]
+  'update:modelValue': [date: DateRange]
   /** Event handler called whenever the placeholder value changes */
   'update:placeholder': [date: DateValue]
 }
diff --git a/packages/core/src/MonthPicker/MonthPicker.test.ts b/packages/core/src/MonthPicker/MonthPicker.test.ts
@@ -97,6 +97,20 @@ describe('month picker', async () => {
     expect(getByTestId('heading')).toHaveTextContent('1980')
   })
 
+  it('does not crash when modelValue is null', async () => {
+    const { picker, rerender } = setup({ pickerProps: { modelValue: null } })
+
+    expect(getSelectedMonths(picker)).toHaveLength(0)
+
+    await rerender({
+      pickerProps: {
+        modelValue: calendarDate,
+      },
+    })
+
+    expect(getSelectedMonth(picker)).toHaveTextContent('Jan')
+  })
+
   it('navigates to next year using next button', async () => {
     const { getByTestId, user } = setup({ pickerProps: { modelValue: calendarDate } })
 
diff --git a/packages/core/src/MonthPicker/MonthPickerRoot.vue b/packages/core/src/MonthPicker/MonthPickerRoot.vue
@@ -74,7 +74,7 @@ export interface MonthPickerRootProps extends PrimitiveProps {
   /** A function that returns the previous page of the month picker. Receives the current placeholder as an argument. */
   prevPage?: (placeholder: DateValue) => DateValue
   /** The controlled selected month value of the month picker. Can be bound as `v-model`. */
-  modelValue?: DateValue | DateValue[] | undefined
+  modelValue?: DateValue | DateValue[] | null
   /** Whether multiple months can be selected */
   multiple?: boolean
 }
diff --git a/packages/core/src/YearPicker/YearPicker.test.ts b/packages/core/src/YearPicker/YearPicker.test.ts
@@ -54,6 +54,20 @@ describe('year picker', async () => {
     expect(getByTestId('heading')).toHaveTextContent('1980 - 1991')
   })
 
+  it('does not crash when modelValue is null', async () => {
+    const { picker, rerender } = setup({ pickerProps: { modelValue: null } })
+
+    expect(getSelectedYears(picker)).toHaveLength(0)
+
+    await rerender({
+      pickerProps: {
+        modelValue: calendarDate,
+      },
+    })
+
+    expect(getSelectedYear(picker)).toHaveTextContent('1980')
+  })
+
   it('navigates to next decade using next button', async () => {
     const { getByTestId, user } = setup({ pickerProps: { modelValue: calendarDate } })
 
diff --git a/packages/core/src/YearPicker/YearPickerRoot.vue b/packages/core/src/YearPicker/YearPickerRoot.vue
@@ -75,7 +75,7 @@ export interface YearPickerRootProps extends PrimitiveProps {
   /** A function that returns the previous page of the year picker. Receives the current placeholder as an argument. */
   prevPage?: (placeholder: DateValue) => DateValue
   /** The controlled selected year value of the year picker. Can be bound as `v-model`. */
-  modelValue?: DateValue | DateValue[] | undefined
+  modelValue?: DateValue | DateValue[] | null
   /** Whether multiple years can be selected */
   multiple?: boolean
   /** Number of years to display per page */

Original file line number	Diff line number	Diff line change
`@@ -84,7 +84,7 @@ export interface DateRangeFieldRootProps extends PrimitiveProps, FormFieldProps`
`84`	`84`
`85`	`85`	`export type DateRangeFieldRootEmits = {`
`86`	`86`	`/** Event handler called whenever the model value changes */`
`87`		`- 'update:modelValue': [DateRange]`
	`87`	`+ 'update:modelValue': [date: DateRange]`
`88`	`88`	`/** Event handler called whenever the placeholder value changes */`
`89`	`89`	`'update:placeholder': [date: DateValue]`
`90`	`90`	`}`
Original file line number	Diff line number	Diff line change
`@@ -74,7 +74,7 @@ export interface MonthPickerRootProps extends PrimitiveProps {`
`74`	`74`	`/** A function that returns the previous page of the month picker. Receives the current placeholder as an argument. */`
`75`	`75`	`prevPage?: (placeholder: DateValue) => DateValue`
`76`	`76`	/** The controlled selected month value of the month picker. Can be bound as `v-model`. */
`77`		`- modelValue?: DateValue \| DateValue[] \| undefined`
	`77`	`+ modelValue?: DateValue \| DateValue[] \| null`
`78`	`78`	`/** Whether multiple months can be selected */`
`79`	`79`	`multiple?: boolean`
`80`	`80`	`}`