feat: initialFocus prop for calendar components (#207)

.changeset/thick-guests-brush.md

@@ -0,0 +1,5 @@
+---
+"bits-ui": patch
+---
+
+Calendar & Range Calendar: add `initialFocus` prop to autofocus dates on mount

src/content/api-reference/calendar.ts

@@ -117,6 +117,12 @@ export const root: APISchema<Calendar.Props> = {
 			description: "Whether or not the calendar is readonly.",
 			default: C.FALSE
 		},
+		initialFocus: {
+			type: C.BOOLEAN,
+			description:
+				"If `true`, the calendar will focus the selected day, today, or the first day of the month in that order depending on what is visible when the calendar is mounted.",
+			default: C.FALSE
+		},
 		asChild
 	},
 	slotProps: {

src/content/api-reference/range-calendar.ts

@@ -116,6 +116,12 @@ export const root: APISchema<RangeCalendar.Props> = {
 			description: "Whether or not the calendar is readonly.",
 			default: C.FALSE
 		},
+		initialFocus: {
+			type: C.BOOLEAN,
+			description:
+				"If `true`, the calendar will focus the selected day, today, or the first day of the month in that order depending on what is visible when the calendar is mounted.",
+			default: C.FALSE
+		},
 		asChild
 	},
 	slotProps: {

src/lib/bits/calendar/_types.ts

@@ -49,6 +49,15 @@ type Props<Multiple extends boolean = false> = Expand<
 		 * A callback function called when the placeholder changes.
 		 */
 		onPlaceholderChange?: OnChangeFn<DateValue>;
+
+		/**
+		 * If `true`, the calendar will focus the selected day,
+		 * today, or the first day of the month in that order depending
+		 * on what is visible when the calendar is mounted.
+		 *
+		 * @default false
+		 */
+		initialFocus?: boolean;
 	} & AsChild
 >;
 

src/lib/bits/calendar/components/calendar.svelte

@@ -1,7 +1,8 @@
 <script lang="ts">
+	import { handleCalendarInitialFocus } from "$lib/internal/focus.js";
 	import { createDispatcher } from "$lib/internal/events.js";
-
 	import { melt } from "@melt-ui/svelte";
+	import { onMount } from "svelte";
 	import { setCtx, getAttrs } from "../ctx.js";
 	import type { Props } from "../types.js";
 
@@ -29,6 +30,14 @@
 	export let asChild: $$Props["asChild"] = false;
 	export let id: $$Props["id"] = undefined;
 	export let numberOfMonths: $$Props["numberOfMonths"] = undefined;
+	export let initialFocus: $$Props["initialFocus"] = false;
+
+	let el: HTMLElement | undefined = undefined;
+
+	onMount(() => {
+		if (!initialFocus || !el) return;
+		handleCalendarInitialFocus(el);
+	});
 
 	const {
 		elements: { calendar },
@@ -112,7 +121,12 @@
 {#if asChild}
 	<slot {...slotProps} />
 {:else}
-	<div use:melt={builder} {...$$restProps} on:m-keydown={dispatch}>
+	<div
+		use:melt={builder}
+		{...$$restProps}
+		on:m-keydown={dispatch}
+		bind:this={el}
+	>
 		<slot {...slotProps} />
 	</div>
 {/if}

src/lib/bits/range-calendar/_types.ts

@@ -20,10 +20,42 @@ type Props = Expand<
 		| "onValueChange"
 		| "ids"
 	> & {
-		placeholder?: DateValue;
+		/**
+		 * The selected date range. This updates as the user selects
+		 * date ranges in the calendar.
+		 *
+		 * You can bind this to a value to programmatically control the
+		 * value state.
+		 */
 		value?: DateRange;
-		onPlaceholderChange?: OnChangeFn<DateValue>;
+
+		/**
+		 * A callback function called when the value changes.
+		 */
 		onValueChange?: OnChangeFn<DateRange>;
+
+		/**
+		 * The placeholder date, used to display the calendar when no
+		 * date is selected. This updates as the user navigates
+		 * the calendar.
+		 *
+		 * You can bind this to a value to programmatically control the
+		 * placeholder state.
+		 */
+		placeholder?: DateValue;
+
+		/**
+		 * A callback function called when the placeholder changes.
+		 */
+		onPlaceholderChange?: OnChangeFn<DateValue>;
+		/**
+		 * If `true`, the calendar will focus the selected day,
+		 * today, or the first day of the month in that order depending
+		 * on what is visible when the calendar is mounted.
+		 *
+		 * @default false
+		 */
+		initialFocus?: boolean;
 	} & AsChild
 >;
 

src/lib/bits/range-calendar/components/range-calendar.svelte

@@ -3,6 +3,8 @@
 	import { setCtx, getAttrs } from "../ctx.js";
 	import type { Events, Props } from "../types.js";
 	import { createDispatcher } from "$lib/internal/events.js";
+	import { onMount } from "svelte";
+	import { handleCalendarInitialFocus } from "$lib/internal/focus.js";
 
 	type $$Props = Props;
 	type $$Events = Events;
@@ -26,6 +28,14 @@
 	export let asChild: $$Props["asChild"] = false;
 	export let id: $$Props["id"] = undefined;
 	export let weekdayFormat: $$Props["weekdayFormat"] = undefined;
+	export let initialFocus: $$Props["initialFocus"] = false;
+
+	let el: HTMLElement | undefined = undefined;
+
+	onMount(() => {
+		if (!initialFocus || !el) return;
+		handleCalendarInitialFocus(el);
+	});
 
 	const {
 		elements: { calendar },
@@ -106,7 +116,12 @@
 {#if asChild}
 	<slot {...slotProps} />
 {:else}
-	<div use:melt={builder} {...$$restProps} on:m-keydown={dispatch}>
+	<div
+		use:melt={builder}
+		{...$$restProps}
+		on:m-keydown={dispatch}
+		bind:this={el}
+	>
 		<slot {...slotProps} />
 	</div>
 {/if}

src/lib/internal/focus.ts

@@ -0,0 +1,26 @@
+import { isBrowser } from ".";
+
+/**
+ * Handles `initialFocus` prop behavior for the
+ * Calendar & RangeCalendar components.
+ */
+export function handleCalendarInitialFocus(calendar: HTMLElement) {
+	if (!isBrowser) return;
+	const selectedDay = calendar.querySelector<HTMLElement>("[data-selected]");
+	if (selectedDay) return focusWithoutScroll(selectedDay);
+
+	const today = calendar.querySelector<HTMLElement>("[data-today]");
+	if (today) return focusWithoutScroll(today);
+
+	const firstDay = calendar.querySelector<HTMLElement>("[data-calendar-date]");
+	if (firstDay) return focusWithoutScroll(firstDay);
+}
+
+export function focusWithoutScroll(element: HTMLElement) {
+	const scrollPosition = {
+		x: window.pageXOffset || document.documentElement.scrollLeft,
+		y: window.pageYOffset || document.documentElement.scrollTop
+	};
+	element.focus();
+	window.scrollTo(scrollPosition.x, scrollPosition.y);
+}

src/lib/internal/index.ts

@@ -8,3 +8,4 @@ export * from "./sleep.js";
 export * from "./style.js";
 export * from "./types.js";
 export * from "./updater.js";
+export * from "./focus.js";