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

Author: hmnd

.changeset/seven-dancers-admire.md

@@ -0,0 +1,5 @@
+---
+"bits-ui": minor
+---
+
+add onVisibleMonthsChange callback to calendars and date pickers

docs/src/routes/api/demos.json/demos.json

@@ -0,0 +1 @@
+

docs/src/routes/api/demos.json/stackblitz-files.json

@@ -0,0 +1 @@
+

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,
 	}));
 

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));

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.

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,

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),

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[];

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.