fix: use minValue and maxValue to generate a defaultPlaceholder for date inputs (#1874)

zomchak-code · web-flow · commit 893271658b93 · 2025-11-09T22:18:53.000-05:00
diff --git a/.changeset/full-foxes-decide.md b/.changeset/full-foxes-decide.md
@@ -0,0 +1,5 @@
+---
+"bits-ui": patch
+---
+
+fix(Calendar, DateField, DatePicker, DateRangeField, DateRangePicker, RangeCalendar): Change default placeholder behaviour to choose the closest available value to current date, in case current date is outside of allowed range by minValue and maxValue.
diff --git a/docs/content/components/calendar.md b/docs/content/components/calendar.md
@@ -71,7 +71,7 @@ The `placeholder` prop for the `Calendar.Root` component determines what date ou
 
 As the user navigates through the calendar, the `placeholder` will be updated to reflect the currently focused date in that view.
 
-By default, the `placeholder` will be set to the current date, and be of type `CalendarDate`.
+By default, the `placeholder` will be set to the closed alowed (by `maxValue`, `minValue`) value to current date, and be of type `CalendarDate`.
 
 ## Managing Placeholder State
 
diff --git a/docs/content/components/date-field.md b/docs/content/components/date-field.md
@@ -103,7 +103,7 @@ Notice that in the `MyDateField` component we created, we're styling the `DateFi
 
 The `placeholder` prop for the `DateField.Root` component isn't what is displayed when the field is empty, but rather what date our field should start with when the user attempts to cycle through the segments. The placeholder can also be used to set a granularity for the date field, which will determine which type of `DateValue` object is used for the `value`.
 
-By default, the `placeholder` will be set to the current date, and be of type `CalendarDate`. However, if we wanted this date field to also allow for selecting a time, we could set the placeholder to a `CalendarDateTime` object.
+By default, the `placeholder` will be set to the closed alowed (by `maxValue`, `minValue`) value to current date, and be of type `CalendarDate`. However, if we wanted this date field to also allow for selecting a time, we could set the placeholder to a `CalendarDateTime` object.
 
 ```svelte
 <script lang="ts">
diff --git a/docs/src/routes/api/search.json/search.json b/docs/src/routes/api/search.json/search.json
diff --git a/packages/bits-ui/src/lib/bits/calendar/components/calendar.svelte b/packages/bits-ui/src/lib/bits/calendar/components/calendar.svelte
@@ -43,6 +43,8 @@
 
 	const defaultPlaceholder = getDefaultDate({
 		defaultValue: value,
+		minValue,
+		maxValue,
 	});
 
 	function handleDefaultPlaceholder() {
diff --git a/packages/bits-ui/src/lib/bits/date-field/components/date-field.svelte b/packages/bits-ui/src/lib/bits/date-field/components/date-field.svelte
@@ -34,6 +34,8 @@
 		const defaultPlaceholder = getDefaultDate({
 			granularity,
 			defaultValue: value,
+			minValue,
+			maxValue,
 		});
 
 		if (setPlaceholder) {
diff --git a/packages/bits-ui/src/lib/bits/date-picker/components/date-picker.svelte b/packages/bits-ui/src/lib/bits/date-picker/components/date-picker.svelte
@@ -53,6 +53,8 @@
 	const defaultPlaceholder = getDefaultDate({
 		granularity,
 		defaultValue: value,
+		minValue,
+		maxValue,
 	});
 
 	function handleDefaultPlaceholder() {
diff --git a/packages/bits-ui/src/lib/bits/date-range-field/components/date-range-field.svelte b/packages/bits-ui/src/lib/bits/date-range-field/components/date-range-field.svelte
@@ -44,7 +44,12 @@
 
 	function handleDefaultPlaceholder() {
 		if (placeholder !== undefined) return;
-		const defaultPlaceholder = getDefaultDate({ granularity, defaultValue: value?.start });
+		const defaultPlaceholder = getDefaultDate({
+			granularity,
+			defaultValue: value?.start,
+			minValue,
+			maxValue,
+		});
 		placeholder = defaultPlaceholder;
 	}
 
diff --git a/packages/bits-ui/src/lib/bits/date-range-picker/components/date-range-picker.svelte b/packages/bits-ui/src/lib/bits/date-range-picker/components/date-range-picker.svelte
@@ -85,6 +85,8 @@
 	const defaultPlaceholder = getDefaultDate({
 		granularity,
 		defaultValue: value?.start,
+		minValue,
+		maxValue,
 	});
 
 	function handleDefaultPlaceholder() {
diff --git a/packages/bits-ui/src/lib/bits/range-calendar/components/range-calendar.svelte b/packages/bits-ui/src/lib/bits/range-calendar/components/range-calendar.svelte
@@ -50,6 +50,8 @@
 
 	const defaultPlaceholder = getDefaultDate({
 		defaultValue: value?.start,
+		minValue,
+		maxValue,
 	});
 
 	function handleDefaultPlaceholder() {
diff --git a/packages/bits-ui/src/lib/internal/date-time/utils.ts b/packages/bits-ui/src/lib/internal/date-time/utils.ts
@@ -20,6 +20,8 @@ import type {
 
 type GetDefaultDateProps = {
 	defaultValue?: DateValue | DateValue[] | undefined;
+	minValue?: DateValue;
+	maxValue?: DateValue;
 	granularity?: Granularity;
 };
 
@@ -41,7 +43,7 @@ const defaultTimeDefaults = {
 /**
  * A helper function used throughout the various date builders
  * to generate a default `DateValue` using the `defaultValue`,
- * `defaultPlaceholder`, and `granularity` props.
+ * `defaultPlaceholder`, `minValue`, `maxValue`, and `granularity` props.
  *
  * It's important to match the `DateValue` type being used
  * elsewhere in the builder, so they behave according to the
@@ -50,7 +52,7 @@ const defaultTimeDefaults = {
  */
 export function getDefaultDate(opts: GetDefaultDateProps): DateValue {
 	const withDefaults = { ...defaultDateDefaults, ...opts };
-	const { defaultValue, granularity } = withDefaults;
+	const { defaultValue, granularity, minValue, maxValue } = withDefaults;
 
 	if (Array.isArray(defaultValue) && defaultValue.length) {
 		return defaultValue[defaultValue.length - 1]!;
@@ -59,7 +61,12 @@ export function getDefaultDate(opts: GetDefaultDateProps): DateValue {
 	if (defaultValue && !Array.isArray(defaultValue)) {
 		return defaultValue;
 	} else {
-		const date = new Date();
+		let date = new Date();
+		if (minValue && date < minValue.toDate(getLocalTimeZone())) {
+			date = minValue.toDate(getLocalTimeZone());
+		} else if (maxValue && date > maxValue.toDate(getLocalTimeZone())) {
+			date = maxValue.toDate(getLocalTimeZone());
+		}
 		const year = date.getFullYear();
 		const month = date.getMonth() + 1;
 		const day = date.getDate();
diff --git a/tests/src/tests/calendar/calendar.browser.test.ts b/tests/src/tests/calendar/calendar.browser.test.ts
@@ -301,6 +301,22 @@ describe("type='single'", () => {
 			await addMonthBtn.click();
 			await expect.element(heading).toHaveTextContent("May 1981");
 		});
+
+		it("should set default placeholder greater than `minValue`", async () => {
+			const currentYear = new Date().getFullYear();
+			const minValue = new CalendarDate(currentYear + 2, 2, 1);
+			setup({ minValue });
+			const heading = page.getByTestId("heading");
+			await expect.element(heading).toHaveTextContent(`February ${minValue.year}`);
+		});
+
+		it("should set default placeholder lower than `maxValue`", async () => {
+			const currentYear = new Date().getFullYear();
+			const maxValue = new CalendarDate(currentYear - 2, 11, 11);
+			setup({ maxValue });
+			const heading = page.getByTestId("heading");
+			await expect.element(heading).toHaveTextContent(`November ${maxValue.year}`);
+		});
 	});
 
 	describe("Selection and Deselection", () => {
diff --git a/tests/src/tests/date-picker/date-picker.browser.test.ts b/tests/src/tests/date-picker/date-picker.browser.test.ts
@@ -446,6 +446,22 @@ it("should not navigate before `minValue` (with keyboard)", async () => {
 	await expect.element(heading).toHaveTextContent("December 1979");
 });
 
+it("should set default placeholder greater than `minValue`", async () => {
+	const currentYear = new Date().getFullYear();
+	const minValue = new CalendarDate(currentYear + 2, 2, 1);
+	await open({minValue});
+	const heading = page.getByTestId("heading");
+	await expect.element(heading).toHaveTextContent(`February ${minValue.year}`);
+});
+
+it("should set default placeholder lower than `maxValue`", async () => {
+	const currentYear = new Date().getFullYear();
+	const maxValue = new CalendarDate(currentYear - 2, 11, 11);
+	await open({maxValue});
+	const heading = page.getByTestId("heading");
+	await expect.element(heading).toHaveTextContent(`November ${maxValue.year}`);
+});
+
 it("should handle unavailable dates appropriately", async () => {
 	await open({
 		placeholder: testDate,
diff --git a/tests/src/tests/date-range-picker/date-range-picker.browser.test.ts b/tests/src/tests/date-range-picker/date-range-picker.browser.test.ts
@@ -564,6 +564,23 @@ it("should not navigate before `minValue` (with keyboard)", async () => {
 	await expect.element(heading).toHaveTextContent("December 1979");
 });
 
+it("should set default placeholder greater than `minValue`", async () => {
+	const currentYear = new Date().getFullYear();
+	const minValue = new CalendarDate(currentYear + 2, 2, 1);
+	await open({minValue});
+	const heading = page.getByTestId("heading");
+	await expect.element(heading).toHaveTextContent(`February ${minValue.year}`);
+});
+
+it("should set default placeholder lower than `maxValue`", async () => {
+	const currentYear = new Date().getFullYear();
+	const maxValue = new CalendarDate(currentYear - 2, 11, 11);
+	await open({maxValue});
+	const heading = page.getByTestId("heading");
+	await expect.element(heading).toHaveTextContent(`November ${maxValue.year}`);
+});
+
+
 it("should handle unavailable dates appropriately", async () => {
 	await open({
 		placeholder: calendarDateRange.start,
diff --git a/tests/src/tests/range-calendar/range-calendar.browser.test.ts b/tests/src/tests/range-calendar/range-calendar.browser.test.ts
@@ -283,6 +283,23 @@ it("should not navigate before `minValue` (with keyboard)", async () => {
 	await expect.element(heading).toHaveTextContent("December 1979");
 });
 
+it("should set default placeholder greater than `minValue`", async () => {
+	const currentYear = new Date().getFullYear();
+	const minValue = new CalendarDate(currentYear + 2, 2, 1);
+	setup({ minValue });
+	const heading = page.getByTestId("heading");
+	await expect.element(heading).toHaveTextContent(`February ${minValue.year}`);
+});
+
+it("should set default placeholder lower than `maxValue`", async () => {
+	const currentYear = new Date().getFullYear();
+	const maxValue = new CalendarDate(currentYear - 2, 11, 11);
+	setup({ maxValue });
+	const heading = page.getByTestId("heading");
+	await expect.element(heading).toHaveTextContent(`November ${maxValue.year}`);
+});
+
+
 it("should handle unavailable dates appropriately", async () => {
 	setup({
 		placeholder: calendarDateRange.start,

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"bits-ui": patch
 +---
++
 +fix(Calendar, DateField, DatePicker, DateRangeField, DateRangePicker, RangeCalendar): Change default placeholder behaviour to choose the closest available value to current date, in case current date is outside of allowed range by minValue and maxValue.