feat: readonly startValue prop (#212)

Author: huntabyte

.changeset/forty-wasps-double.md

@@ -0,0 +1,5 @@
+---
+"bits-ui": patch
+---
+
+feat: readonly startValue prop

src/content/api-reference/date-range-picker.ts

@@ -204,7 +204,14 @@ const root: APISchema<DateRangePicker.Props> = {
 			description: "Override the focus when the popover is closed."
 		},
 		portal: { ...portalProp("popover") },
-
+		startValue: {
+			type: {
+				type: C.UNION,
+				definition: union("DateValue", "undefined")
+			},
+			description:
+				"The `start` value of the date range, which can exist prior to the true `value` being set, which is only set once a `start` and `end` value are selected. You can `bind:startValue` to a value to receive updates, but modifying this value outside the component will have no effect. To programmatically control the `start` value, use `bind:value` and update the `start` property of the `DateRange` object. This is provided as a convenience for use cases where you want to display the selected `start` value outside the component before the `value` is set."
+		},
 		asChild
 	},
 	slotProps: {

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

@@ -5,7 +5,8 @@ import {
 	attrsSlotProp,
 	weekdaysSlotProp,
 	enums,
-	monthsSlotProp
+	monthsSlotProp,
+	union
 } from "@/content/api-reference/helpers.js";
 import type * as RangeCalendar from "$lib/bits/range-calendar/_types.js";
 import { builderAndAttrsSlotProps } from "./helpers";
@@ -122,6 +123,30 @@ export const root: APISchema<RangeCalendar.Props> = {
 				"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
 		},
+		/**
+		 * The `start` value of the date range, which can exist prior
+		 * to the `value` being set. The `value` is only set once a `start`
+		 * and `end` value are selected.
+		 *
+		 * You can `bind:startValue` to a value to receive updates outside
+		 * this component when the user selects a `start` value.
+		 *
+		 * Modifying this value outside the component will have no effect.
+		 * To programmatically control the `start` value, use `bind:value`
+		 * and update the `start` property of the `DateRange` object.
+		 *
+		 * This is provided as a convenience for use cases where you want
+		 * to display the selected `start` value outside the component before
+		 * the `value` is set.
+		 */
+		startValue: {
+			type: {
+				type: C.UNION,
+				definition: union("DateValue", "undefined")
+			},
+			description:
+				"The `start` value of the date range, which can exist prior to the true `value` being set, which is only set once a `start` and `end` value are selected. You can `bind:startValue` to a value to receive updates, but modifying this value outside the component will have no effect. To programmatically control the `start` value, use `bind:value` and update the `start` property of the `DateRange` object. This is provided as a convenience for use cases where you want to display the selected `start` value outside the component before the `value` is set."
+		},
 		asChild
 	},
 	slotProps: {

src/lib/bits/date-range-picker/_types.ts

@@ -65,6 +65,24 @@ type Props = Expand<
 		 * This is used to apply the appropriate `aria-describedby` attribute to the input.
 		 */
 		descriptionId?: string;
+
+		/**
+		 * The `start` value of the date range, which can exist prior
+		 * to the `value` being set. The `value` is only set once a `start`
+		 * and `end` value are selected.
+		 *
+		 * You can `bind:startValue` to a value to receive updates outside
+		 * this component when the user selects a `start` value.
+		 *
+		 * Modifying this value outside the component will have no effect.
+		 * To programmatically control the `start` value, use `bind:value`
+		 * and update the `start` property of the `DateRange` object.
+		 *
+		 * This is provided as a convenience for use cases where you want
+		 * to display the selected `start` value outside the component before
+		 * the `value` is set.
+		 */
+		startValue?: DateValue | undefined;
 	} & AsChild
 >;
 

src/lib/bits/date-range-picker/components/date-range-picker.svelte

@@ -27,13 +27,14 @@
 	export let fixedWeeks: $$Props["fixedWeeks"] = undefined;
 	export let calendarLabel: $$Props["calendarLabel"] = undefined;
 	export let weekdayFormat: $$Props["weekdayFormat"] = undefined;
+	export let startValue: $$Props["startValue"] = undefined;
 
 	const {
 		states: {
 			value: localValue,
 			placeholder: localPlaceholder,
 			isInvalid: localIsInvalid,
-			startValue,
+			startValue: localStartValue,
 			endValue
 		},
 		updateOption,
@@ -182,6 +183,7 @@
 		ids.rangeField.field.description.set(descriptionId);
 	}
 
+	$: startValue = $localStartValue;
 	$: value !== undefined && localValue.set(value);
 	$: placeholder !== undefined && localPlaceholder.set(placeholder);
 
@@ -205,7 +207,7 @@
 	$: slotProps = {
 		isInvalid: $localIsInvalid,
 		ids: $idValues,
-		startValue: $startValue,
+		startValue: $localStartValue,
 		endValue: $endValue
 	};
 </script>

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

@@ -48,6 +48,7 @@ type Props = 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
@@ -56,6 +57,24 @@ type Props = Expand<
 		 * @default false
 		 */
 		initialFocus?: boolean;
+
+		/**
+		 * The `start` value of the date range, which can exist prior
+		 * to the `value` being set. The `value` is only set once a `start`
+		 * and `end` value are selected.
+		 *
+		 * You can `bind:startValue` to a value to receive updates outside
+		 * this component when the user selects a `start` value.
+		 *
+		 * Modifying this value outside the component will have no effect.
+		 * To programmatically control the `start` value, use `bind:value`
+		 * and update the `start` property of the `DateRange` object.
+		 *
+		 * This is provided as a convenience for use cases where you want
+		 * to display the selected `start` value outside the component before
+		 * the `value` is set.
+		 */
+		startValue?: DateValue | undefined;
 	} & AsChild
 >;
 

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

@@ -29,6 +29,7 @@
 	export let id: $$Props["id"] = undefined;
 	export let weekdayFormat: $$Props["weekdayFormat"] = undefined;
 	export let initialFocus: $$Props["initialFocus"] = false;
+	export let startValue: $$Props["startValue"] = undefined;
 
 	let el: HTMLElement | undefined = undefined;
 
@@ -44,7 +45,7 @@
 			placeholder: localPlaceholder,
 			months,
 			weekdays,
-			startValue,
+			startValue: localStartValue,
 			endValue
 		},
 		updateOption,
@@ -85,6 +86,8 @@
 		ids.calendar.set(id);
 	}
 
+	$: startValue = $localStartValue;
+
 	$: value !== undefined && localValue.set(value);
 	$: placeholder !== undefined && localPlaceholder.set(placeholder);
 
@@ -112,7 +115,7 @@
 		builder,
 		months: $months,
 		weekdays: $weekdays,
-		startValue: $startValue,
+		startValue: $localStartValue,
 		endValue: $endValue
 	};
 </script>