huntabyte · hmnd · Apr 22, 2025
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
@@ -0,0 +1 @@
+
diff --git a/docs/src/routes/api/demos.json/stackblitz-files.json b/docs/src/routes/api/demos.json/stackblitz-files.json
@@ -0,0 +1 @@
+
diff --git a/packages/bits-ui/src/lib/bits/calendar/calendar.svelte.ts b/packages/bits-ui/src/lib/bits/calendar/calendar.svelte.ts
@@ -53,6 +53,7 @@ interface CalendarRootStateOpts
 		WritableBoxedValues<{
 			value: DateValue | undefined | DateValue[];
 			placeholder: DateValue;
+			months: Month<DateValue>[];
 		}>,
 		ReadableBoxedValues<{
 			preventDeselect: boolean;
@@ -94,7 +95,7 @@ export class CalendarRootState {
 	}
 
 	readonly opts: CalendarRootStateOpts;
-	readonly visibleMonths = $derived.by(() => this.months.map((month) => month.value));
+	readonly visibleMonths = $derived.by(() => this.#months.map((month) => month.value));
 	readonly formatter: Formatter;
 	readonly accessibleHeadingId = useId();
 	readonly domContext: DOMContext;
@@ -134,7 +135,7 @@ export class CalendarRootState {
 			this.announcer = getAnnouncer(this.domContext.getDocument());
 		});
 
-		this.months = createMonths({
+		this.opts.months.current = createMonths({
 			dateObj: this.opts.placeholder.current,
 			weekStartsOn: this.opts.weekStartsOn.current,
 			locale: this.opts.locale.current,
@@ -156,7 +157,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),
 		});
 
 		/**
@@ -217,8 +218,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;
 	}
 
 	/**
@@ -230,7 +247,7 @@ export class CalendarRootState {
 	 */
 	readonly weekdays = $derived.by(() => {
 		return getWeekdays({
-			months: this.months,
+			months: this.#months,
 			formatter: this.formatter,
 			weekdayFormat: this.opts.weekdayFormat.current,
 		});
@@ -293,7 +310,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,
 		});
 	}
 
@@ -309,7 +326,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,
 		});
 	}
 
@@ -332,15 +349,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,
 		});
 	});
@@ -367,7 +384,7 @@ export class CalendarRootState {
 		this.opts.monthFormat.current;
 		this.opts.yearFormat.current;
 		return getCalendarHeadingValue({
-			months: this.months,
+			months: this.#months,
 			formatter: this.formatter,
 			locale: this.opts.locale.current,
 		});
@@ -408,7 +425,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,
 		});
 	}
@@ -509,7 +526,7 @@ export class CalendarRootState {
 	}
 
 	readonly snippetProps = $derived.by(() => ({
-		months: this.months,
+		months: this.#months,
 		weekdays: this.weekdays,
 	}));
 

diff --git a/packages/bits-ui/src/lib/bits/calendar/components/calendar.svelte b/packages/bits-ui/src/lib/bits/calendar/components/calendar.svelte
@@ -8,6 +8,7 @@
 	import { noop } from "$lib/internal/noop.js";
 	import { getDefaultDate } from "$lib/internal/date-time/utils.js";
 	import { resolveLocaleProp } from "$lib/bits/utilities/config/prop-resolvers.js";
+	import type { Month } from "$lib/shared/index.js";
 
 	let {
 		child,
@@ -38,9 +39,12 @@
 		maxDays,
 		monthFormat = "long",
 		yearFormat = "numeric",
+		onVisibleMonthsChange = noop,
 		...restProps
 	}: CalendarRootProps = $props();
 
+	let months = $state<Month<DateValue>[]>([]);
+
 	const defaultPlaceholder = getDefaultDate({
 		defaultValue: value,
 	});
@@ -117,6 +121,13 @@
 		monthFormat: boxWith(() => monthFormat),
 		yearFormat: boxWith(() => yearFormat),
 		defaultPlaceholder,
+		months: boxWith(
+			() => 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
@@ -34,6 +34,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
@@ -41,6 +41,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
@@ -11,6 +11,7 @@
 	import { FloatingLayer } from "$lib/bits/utilities/floating-layer/index.js";
 	import { getDefaultDate } from "$lib/internal/date-time/utils.js";
 	import { resolveLocaleProp } from "$lib/bits/utilities/config/prop-resolvers.js";
+	import type { Month } from "$lib/shared/index.js";
 
 	let {
 		open = $bindable(false),
@@ -48,8 +49,11 @@
 		children,
 		monthFormat = "long",
 		yearFormat = "numeric",
+		onVisibleMonthsChange = noop,
 	}: DatePickerRootProps = $props();
 
+	let months = $state<Month<DateValue>[]>([]);
+
 	const defaultPlaceholder = getDefaultDate({
 		granularity,
 		defaultValue: value,
@@ -125,6 +129,13 @@
 		numberOfMonths: boxWith(() => numberOfMonths),
 		initialFocus: boxWith(() => initialFocus),
 		onDateSelect: boxWith(() => onDateSelect),
+		months: boxWith(
+			() => months,
+			(v) => {
+				months = v;
+				onVisibleMonthsChange(v);
+			}
+		),
 		defaultPlaceholder,
 		monthFormat: boxWith(() => monthFormat),
 		yearFormat: boxWith(() => yearFormat),

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,7 +2,7 @@ import type { DateValue } from "@internationalized/date";
 import { Context } from "runed";
 import { type ReadableBoxedValues, type WritableBoxedValues } from "svelte-toolbelt";
 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";
 
 export const DatePickerRootContext = new Context<DatePickerRootState>("DatePicker.Root");
 
@@ -11,6 +11,7 @@ interface DatePickerRootStateOpts
 			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";
 import type { PortalProps } from "$lib/bits/utilities/portal/index.js";
 
 export type DatePickerRootPropsWithoutHTML = WithChildren<{
@@ -24,6 +24,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
@@ -42,6 +42,7 @@
 		value: dateRangePickerRootState.opts.value,
 		excludeDisabled: dateRangePickerRootState.opts.excludeDisabled,
 		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
@@ -9,7 +9,7 @@
 	import { DateRangeFieldRootState } 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 { resolveLocaleProp } from "$lib/bits/utilities/config/prop-resolvers.js";
 
@@ -47,6 +47,7 @@
 		closeOnRangeSelect = true,
 		onStartValueChange = noop,
 		onEndValueChange = noop,
+		onVisibleMonthsChange = noop,
 		validate = noop,
 		errorMessageId,
 		minDays,
@@ -61,6 +62,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;
@@ -159,6 +161,13 @@
 		numberOfMonths: boxWith(() => numberOfMonths),
 		excludeDisabled: boxWith(() => excludeDisabled),
 		onRangeSelect: boxWith(() => onRangeSelect),
+		months: boxWith(
+			() => months,
+			(v) => {
+				months = v;
+				onVisibleMonthsChange(v);
+			}
+		),
 		startValue: boxWith(
 			() => 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,7 +2,7 @@ import type { DateValue } from "@internationalized/date";
 import { type ReadableBoxedValues, type WritableBoxedValues } from "svelte-toolbelt";
 import { Context } from "runed";
 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";
 
 export const DateRangePickerRootContext = new Context<DateRangePickerRootState>(
 	"DateRangePicker.Root"
@@ -13,6 +13,7 @@ interface DateRangePickerRootStateOpts
 			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<{
 	/**
@@ -271,6 +271,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
@@ -8,6 +8,7 @@
 	import { createId } from "$lib/internal/create-id.js";
 	import { getDefaultDate } from "$lib/internal/date-time/utils.js";
 	import { resolveLocaleProp } from "$lib/bits/utilities/config/prop-resolvers.js";
+	import type { Month } from "$lib/shared/index.js";
 
 	const uid = $props.id();
 
@@ -42,11 +43,13 @@
 		excludeDisabled = false,
 		monthFormat = "long",
 		yearFormat = "numeric",
+		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,
@@ -120,6 +123,13 @@
 		minDays: boxWith(() => minDays),
 		maxDays: boxWith(() => maxDays),
 		excludeDisabled: boxWith(() => excludeDisabled),
+		months: boxWith(
+			() => months,
+			(v) => {
+				months = v;
+				onVisibleMonthsChange(v);
+			}
+		),
 		startValue: boxWith(
 			() => startValue,
 			(v) => {