feat(Calendar): add onVisibleMonthsChange callback to calendars and date pickers

hmnd · hmnd · commit 2cedeba0d35c · 2025-05-15T19:54:12.000-07:00
diff --git a/.changeset/seven-dancers-admire.md b/.changeset/seven-dancers-admire.md
@@ -0,0 +1,5 @@
+---
+"bits-ui": minor
+---
+
+add onVisibleMonthsChange callback to calendars and date pickers
diff --git a/docs/src/routes/api/demos.json/demos.json b/docs/src/routes/api/demos.json/demos.json
diff --git a/docs/src/routes/api/demos.json/stackblitz-files.json b/docs/src/routes/api/demos.json/stackblitz-files.json
diff --git a/packages/bits-ui/src/lib/bits/calendar/calendar.svelte.ts b/packages/bits-ui/src/lib/bits/calendar/calendar.svelte.ts
@@ -50,6 +50,7 @@ type CalendarRootStateProps = WithRefProps<
 	WritableBoxedValues<{
 		value: DateValue | undefined | DateValue[];
 		placeholder: DateValue;
+		months: Month<DateValue>[];
 	}> &
 		ReadableBoxedValues<{
 			preventDeselect: boolean;
@@ -80,8 +81,7 @@ type CalendarRootStateProps = WithRefProps<
 >;
 
 export class CalendarRootState {
-	months: Month<DateValue>[] = $state([]);
-	visibleMonths = $derived.by(() => this.months.map((month) => month.value));
+	visibleMonths = $derived.by(() => this.#months.map((month) => month.value));
 	announcer: Announcer;
 	formatter: Formatter;
 	accessibleHeadingId = useId();
@@ -109,7 +109,7 @@ export class CalendarRootState {
 
 		useRefById(opts);
 
-		this.months = createMonths({
+		this.opts.months.current = createMonths({
 			dateObj: this.opts.placeholder.current,
 			weekStartsOn: this.opts.weekStartsOn.current,
 			locale: this.opts.locale.current,
@@ -154,7 +154,7 @@ export class CalendarRootState {
 			locale: this.opts.locale,
 			fixedWeeks: this.opts.fixedWeeks,
 			numberOfMonths: this.opts.numberOfMonths,
-			setMonths: (months: Month<DateValue>[]) => (this.months = months),
+			setMonths: (months: Month<DateValue>[]) => (this.opts.months.current = months),
 		});
 
 		/**
@@ -212,8 +212,24 @@ export class CalendarRootState {
 		});
 	}
 
+	/**
+	 * Currently displayed months, with default value fallback for SSR,
+	 * as boxes don't update server-side.
+	 */
+	get #months() {
+		return this.opts.months.current.length
+			? this.opts.months.current
+			: createMonths({
+					dateObj: this.opts.placeholder.current,
+					weekStartsOn: this.opts.weekStartsOn.current,
+					locale: this.opts.locale.current,
+					fixedWeeks: this.opts.fixedWeeks.current,
+					numberOfMonths: this.opts.numberOfMonths.current,
+				});
+	}
+
 	setMonths(months: Month<DateValue>[]) {
-		this.months = months;
+		this.opts.months.current = months;
 	}
 
 	/**
@@ -225,7 +241,7 @@ export class CalendarRootState {
 	 */
 	weekdays = $derived.by(() => {
 		return getWeekdays({
-			months: this.months,
+			months: this.#months,
 			formatter: this.formatter,
 			weekdayFormat: this.opts.weekdayFormat.current,
 		});
@@ -243,7 +259,7 @@ export class CalendarRootState {
 			setMonths: this.setMonths,
 			setPlaceholder: (date: DateValue) => (this.opts.placeholder.current = date),
 			weekStartsOn: this.opts.weekStartsOn.current,
-			months: this.months,
+			months: this.#months,
 		});
 	}
 
@@ -259,7 +275,7 @@ export class CalendarRootState {
 			setMonths: this.setMonths,
 			setPlaceholder: (date: DateValue) => (this.opts.placeholder.current = date),
 			weekStartsOn: this.opts.weekStartsOn.current,
-			months: this.months,
+			months: this.#months,
 		});
 	}
 
@@ -282,15 +298,15 @@ export class CalendarRootState {
 	isNextButtonDisabled = $derived.by(() => {
 		return getIsNextButtonDisabled({
 			maxValue: this.opts.maxValue.current,
-			months: this.months,
+			months: this.#months,
 			disabled: this.opts.disabled.current,
 		});
 	});
 
 	isPrevButtonDisabled = $derived.by(() => {
 		return getIsPrevButtonDisabled({
 			minValue: this.opts.minValue.current,
-			months: this.months,
+			months: this.#months,
 			disabled: this.opts.disabled.current,
 		});
 	});
@@ -315,7 +331,7 @@ export class CalendarRootState {
 
 	headingValue = $derived.by(() => {
 		return getCalendarHeadingValue({
-			months: this.months,
+			months: this.#months,
 			formatter: this.formatter,
 			locale: this.opts.locale.current,
 		});
@@ -356,7 +372,7 @@ export class CalendarRootState {
 			calendarNode: this.opts.ref.current,
 			isPrevButtonDisabled: this.isPrevButtonDisabled,
 			isNextButtonDisabled: this.isNextButtonDisabled,
-			months: this.months,
+			months: this.#months,
 			numberOfMonths: this.opts.numberOfMonths.current,
 		});
 	}
@@ -437,10 +453,12 @@ export class CalendarRootState {
 		});
 	}
 
-	snippetProps = $derived.by(() => ({
-		months: this.months,
-		weekdays: this.weekdays,
-	}));
+	snippetProps = $derived.by(() => {
+		return {
+			months: this.#months,
+			weekdays: this.weekdays,
+		};
+	});
 
 	getBitsAttr(part: CalendarParts) {
 		return `data-bits-calendar-${part}`;
diff --git a/packages/bits-ui/src/lib/bits/calendar/components/calendar.svelte b/packages/bits-ui/src/lib/bits/calendar/components/calendar.svelte
@@ -7,6 +7,7 @@
 	import { noop } from "$lib/internal/noop.js";
 	import { getDefaultDate } from "$lib/internal/date-time/utils.js";
 	import { watch } from "runed";
+	import type { Month } from "$lib/shared/index.js";
 
 	let {
 		child,
@@ -34,9 +35,12 @@
 		type,
 		disableDaysOutsideMonth = true,
 		initialFocus = false,
+		onVisibleMonthsChange = noop,
 		...restProps
 	}: CalendarRootProps = $props();
 
+	let months = $state<Month<DateValue>[]>([]);
+
 	const defaultPlaceholder = getDefaultDate({
 		defaultValue: value,
 	});
@@ -110,6 +114,13 @@
 		),
 		type: box.with(() => type),
 		defaultPlaceholder,
+		months: box.with(
+			() => months,
+			(v) => {
+				months = v;
+				onVisibleMonthsChange(v);
+			}
+		),
 	});
 
 	const mergedProps = $derived(mergeProps(restProps, rootState.props));
diff --git a/packages/bits-ui/src/lib/bits/calendar/types.ts b/packages/bits-ui/src/lib/bits/calendar/types.ts
@@ -33,6 +33,11 @@ type CalendarBaseRootPropsWithoutHTML = {
 	 */
 	onPlaceholderChange?: OnChangeFn<DateValue>;
 
+	/**
+	 * A callback function called when the currently displayed month(s) changes.
+	 */
+	onVisibleMonthsChange?: OnChangeFn<Month<DateValue>[]>;
+
 	/**
 	 * Whether or not users can deselect a date once selected
 	 * without selecting another date.
diff --git a/packages/bits-ui/src/lib/bits/date-picker/components/date-picker-calendar.svelte b/packages/bits-ui/src/lib/bits/date-picker/components/date-picker-calendar.svelte
@@ -39,6 +39,7 @@
 		minValue: datePickerRootState.opts.minValue,
 		placeholder: datePickerRootState.opts.placeholder,
 		value: datePickerRootState.opts.value,
+		months: datePickerRootState.opts.months,
 		onDateSelect: datePickerRootState.opts.onDateSelect,
 		initialFocus: datePickerRootState.opts.initialFocus,
 		defaultPlaceholder: datePickerRootState.opts.defaultPlaceholder,
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
@@ -10,6 +10,7 @@
 	import { FloatingLayer } from "$lib/bits/utilities/floating-layer/index.js";
 	import { getDefaultDate } from "$lib/internal/date-time/utils.js";
 	import { watch } from "runed";
+	import type { Month } from "$lib/shared/index.js";
 
 	let {
 		open = $bindable(false),
@@ -44,8 +45,11 @@
 		initialFocus = false,
 		errorMessageId,
 		children,
+		onVisibleMonthsChange = noop,
 	}: DatePickerRootProps = $props();
 
+	let months = $state<Month<DateValue>[]>([]);
+
 	const defaultPlaceholder = getDefaultDate({
 		granularity,
 		defaultValue: value,
@@ -121,6 +125,13 @@
 		numberOfMonths: box.with(() => numberOfMonths),
 		initialFocus: box.with(() => initialFocus),
 		onDateSelect: box.with(() => onDateSelect),
+		months: box.with(
+			() => months,
+			(v) => {
+				months = v;
+				onVisibleMonthsChange(v);
+			}
+		),
 		defaultPlaceholder,
 	});
 
diff --git a/packages/bits-ui/src/lib/bits/date-picker/date-picker.svelte.ts b/packages/bits-ui/src/lib/bits/date-picker/date-picker.svelte.ts
@@ -2,12 +2,13 @@ import type { DateValue } from "@internationalized/date";
 import { Context } from "runed";
 import type { ReadableBoxedValues, WritableBoxedValues } from "$lib/internal/box.svelte.js";
 import type { DateMatcher, SegmentPart } from "$lib/shared/index.js";
-import type { Granularity, HourCycle, WeekStartsOn } from "$lib/shared/date/types.js";
+import type { Granularity, HourCycle, Month, WeekStartsOn } from "$lib/shared/date/types.js";
 
 type DatePickerRootStateProps = WritableBoxedValues<{
 	value: DateValue | undefined;
 	open: boolean;
 	placeholder: DateValue;
+	months: Month<DateValue>[];
 }> &
 	ReadableBoxedValues<{
 		readonlySegments: SegmentPart[];
diff --git a/packages/bits-ui/src/lib/bits/date-picker/types.ts b/packages/bits-ui/src/lib/bits/date-picker/types.ts
@@ -8,7 +8,7 @@ import type {
 	DateValidator,
 	EditableSegmentPart,
 } from "$lib/shared/index.js";
-import type { Granularity, WeekStartsOn } from "$lib/shared/date/types.js";
+import type { Granularity, Month, WeekStartsOn } from "$lib/shared/date/types.js";
 
 export type DatePickerRootPropsWithoutHTML = WithChildren<{
 	/**
@@ -23,6 +23,11 @@ export type DatePickerRootPropsWithoutHTML = WithChildren<{
 	 */
 	onValueChange?: OnChangeFn<DateValue | undefined>;
 
+	/**
+	 * A callback function called when the currently displayed month(s) changes.
+	 */
+	onVisibleMonthsChange?: OnChangeFn<Month<DateValue>[]>;
+
 	/**
 	 * The placeholder value of the date field. This determines the format
 	 * and what date the field starts at when it is empty.
diff --git a/packages/bits-ui/src/lib/bits/date-range-picker/components/date-range-picker-calendar.svelte b/packages/bits-ui/src/lib/bits/date-range-picker/components/date-range-picker-calendar.svelte
@@ -39,6 +39,7 @@
 		placeholder: dateRangePickerRootState.opts.placeholder,
 		value: dateRangePickerRootState.opts.value,
 		onRangeSelect: dateRangePickerRootState.opts.onRangeSelect,
+		months: dateRangePickerRootState.opts.months,
 		startValue: dateRangePickerRootState.opts.startValue,
 		endValue: dateRangePickerRootState.opts.endValue,
 		defaultPlaceholder: dateRangePickerRootState.opts.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
@@ -8,7 +8,7 @@
 	import { useDateRangeFieldRoot } from "$lib/bits/date-range-field/date-range-field.svelte.js";
 	import FloatingLayer from "$lib/bits/utilities/floating-layer/components/floating-layer.svelte";
 	import { useId } from "$lib/internal/use-id.js";
-	import type { DateRange } from "$lib/shared/index.js";
+	import type { DateRange, Month } from "$lib/shared/index.js";
 	import { getDefaultDate } from "$lib/internal/date-time/utils.js";
 	import { watch } from "runed";
 
@@ -45,6 +45,7 @@
 		closeOnRangeSelect = true,
 		onStartValueChange = noop,
 		onEndValueChange = noop,
+		onVisibleMonthsChange = noop,
 		validate = noop,
 		errorMessageId,
 		child,
@@ -54,6 +55,7 @@
 
 	let startValue = $state<DateValue | undefined>(value?.start);
 	let endValue = $state<DateValue | undefined>(value?.end);
+	let months = $state.raw<Month<DateValue>[]>([]);
 
 	function handleDefaultValue() {
 		if (value !== undefined) return;
@@ -149,6 +151,13 @@
 		fixedWeeks: box.with(() => fixedWeeks),
 		numberOfMonths: box.with(() => numberOfMonths),
 		onRangeSelect: box.with(() => onRangeSelect),
+		months: box.with(
+			() => months,
+			(v) => {
+				months = v;
+				onVisibleMonthsChange(v);
+			}
+		),
 		startValue: box.with(
 			() => startValue,
 			(v) => {
diff --git a/packages/bits-ui/src/lib/bits/date-range-picker/date-range-picker.svelte.ts b/packages/bits-ui/src/lib/bits/date-range-picker/date-range-picker.svelte.ts
@@ -2,12 +2,13 @@ import type { DateValue } from "@internationalized/date";
 import { Context } from "runed";
 import type { ReadableBoxedValues, WritableBoxedValues } from "$lib/internal/box.svelte.js";
 import type { DateMatcher, DateRange, SegmentPart } from "$lib/shared/index.js";
-import type { Granularity, HourCycle, WeekStartsOn } from "$lib/shared/date/types.js";
+import type { Granularity, HourCycle, Month, WeekStartsOn } from "$lib/shared/date/types.js";
 
 type DateRangePickerRootStateProps = WritableBoxedValues<{
 	value: DateRange;
 	startValue: DateValue | undefined;
 	endValue: DateValue | undefined;
+	months: Month<DateValue>[];
 	open: boolean;
 	placeholder: DateValue;
 }> &
diff --git a/packages/bits-ui/src/lib/bits/date-range-picker/types.ts b/packages/bits-ui/src/lib/bits/date-range-picker/types.ts
@@ -9,7 +9,7 @@ import type {
 	EditableSegmentPart,
 } from "$lib/shared/index.js";
 import type { CalendarRootSnippetProps } from "$lib/types.js";
-import type { Granularity, WeekStartsOn } from "$lib/shared/date/types.js";
+import type { Granularity, Month, WeekStartsOn } from "$lib/shared/date/types.js";
 
 export type DateRangePickerRootPropsWithoutHTML = WithChild<{
 	/**
@@ -266,6 +266,11 @@ export type DateRangePickerRootPropsWithoutHTML = WithChild<{
 	 */
 	onEndValueChange?: OnChangeFn<DateValue | undefined>;
 
+	/**
+	 * A callback function called when the currently displayed month(s) changes.
+	 */
+	onVisibleMonthsChange?: OnChangeFn<Month<DateValue>[]>;
+
 	/**
 	 * The `id` of the element which contains the error messages for the date field when the
 	 * date is invalid.
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
@@ -7,6 +7,7 @@
 	import { useId } from "$lib/internal/use-id.js";
 	import { getDefaultDate } from "$lib/internal/date-time/utils.js";
 	import { watch } from "runed";
+	import type { Month } from "$lib/shared/index.js";
 
 	let {
 		children,
@@ -34,11 +35,13 @@
 		disableDaysOutsideMonth = true,
 		onStartValueChange = noop,
 		onEndValueChange = noop,
+		onVisibleMonthsChange = noop,
 		...restProps
 	}: RangeCalendarRootProps = $props();
 
 	let startValue = $state<DateValue | undefined>(value?.start);
 	let endValue = $state<DateValue | undefined>(value?.end);
+	let months = $state.raw<Month<DateValue>[]>([]);
 
 	const defaultPlaceholder = getDefaultDate({
 		defaultValue: value?.start,
@@ -109,6 +112,13 @@
 		calendarLabel: box.with(() => calendarLabel),
 		fixedWeeks: box.with(() => fixedWeeks),
 		disableDaysOutsideMonth: box.with(() => disableDaysOutsideMonth),
+		months: box.with(
+			() => months,
+			(v) => {
+				months = v;
+				onVisibleMonthsChange(v);
+			}
+		),
 		startValue: box.with(
 			() => startValue,
 			(v) => {
diff --git a/packages/bits-ui/src/lib/bits/range-calendar/range-calendar.svelte.ts b/packages/bits-ui/src/lib/bits/range-calendar/range-calendar.svelte.ts
diff --git a/packages/bits-ui/src/lib/bits/range-calendar/types.ts b/packages/bits-ui/src/lib/bits/range-calendar/types.ts
diff --git a/tests/src/tests/calendar/calendar.test.ts b/tests/src/tests/calendar/calendar.test.ts
diff --git a/tests/src/tests/range-calendar/range-calendar.test.ts b/tests/src/tests/range-calendar/range-calendar.test.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"bits-ui": minor
 +---
++
 +add onVisibleMonthsChange callback to calendars and date pickers