next: rename onValueChangeEnd to onValueCommit (#774)

huntabyte · Oct 17, 2024 · ceea3e7 · ceea3e7
1 parent 44db2f1
commit ceea3e7
Show file tree

Hide file tree

Showing 6 changed files with 28 additions and 10 deletions.
diff --git a/.changeset/shaggy-waves-prove.md b/.changeset/shaggy-waves-prove.md
@@ -0,0 +1,5 @@
+---
+"bits-ui": patch
+---
+
+breaking: rename `onValueChangeEnd` to `onValueCommit`
diff --git a/packages/bits-ui/src/lib/bits/slider/components/slider.svelte b/packages/bits-ui/src/lib/bits/slider/components/slider.svelte
@@ -12,7 +12,7 @@
 		ref = $bindable(null),
 		value = $bindable([]),
 		onValueChange = noop,
-		onValueChangeEnd = noop,
+		onValueCommit = noop,
 		disabled = false,
 		min = 0,
 		max = 100,
@@ -41,7 +41,7 @@
 				}
 			}
 		),
-		onValueChangeEnd: box.with(() => onValueChangeEnd),
+		onValueCommit: box.with(() => onValueCommit),
 		disabled: box.with(() => disabled),
 		min: box.with(() => min),
 		max: box.with(() => max),

diff --git a/packages/bits-ui/src/lib/bits/slider/slider.svelte.ts b/packages/bits-ui/src/lib/bits/slider/slider.svelte.ts
@@ -36,7 +36,7 @@ type SliderRootStateProps = WithRefProps<
 		step: number;
 		dir: Direction;
 		autoSort: boolean;
-		onValueChangeEnd: OnChangeFn<number[]>;
+		onValueCommit: OnChangeFn<number[]>;
 	}> &
 		WritableBoxedValues<{
 			value: number[];
@@ -64,7 +64,7 @@ class SliderRootState {
 			return this.dir.current === "rtl" ? "tb" : "bt";
 		}
 	});
-	onValueChangeEnd: SliderRootStateProps["onValueChangeEnd"];
+	onValueCommit: SliderRootStateProps["onValueCommit"];
 
 	constructor(props: SliderRootStateProps) {
 		this.id = props.id;
@@ -77,7 +77,7 @@ class SliderRootState {
 		this.dir = props.dir;
 		this.autoSort = props.autoSort;
 		this.value = props.value;
-		this.onValueChangeEnd = props.onValueChangeEnd;
+		this.onValueCommit = props.onValueCommit;
 
 		useRefById({
 			id: this.id,
@@ -242,7 +242,7 @@ class SliderRootState {
 
 	handlePointerUp = () => {
 		if (this.isActive) {
-			this.onValueChangeEnd.current(untrack(() => this.value.current));
+			this.onValueCommit.current(untrack(() => this.value.current));
 		}
 		this.isActive = false;
 	};
@@ -587,7 +587,7 @@ class SliderThumbState {
 				}
 				break;
 		}
-		this.#root.onValueChangeEnd.current(this.#root.value.current);
+		this.#root.onValueCommit.current(this.#root.value.current);
 	};
 
 	props = $derived.by(

diff --git a/packages/bits-ui/src/lib/bits/slider/types.ts b/packages/bits-ui/src/lib/bits/slider/types.ts
@@ -22,9 +22,10 @@ export type SliderRootPropsWithoutHTML = WithChild<
 
 		/**
 		 * A callback function called when the user stops dragging the thumb,
-		 * which is useful for knowing when the user has finished interacting with the slider.
+		 * which is useful for knowing when the user has finished interacting with the
+		 * slider and _commits_ the value.
 		 */
-		onValueChangeEnd?: OnChangeFn<number[]>;
+		onValueCommit?: OnChangeFn<number[]>;
 
 		/**
 		 * Whether to automatically sort the values in the array when moving thumbs past

diff --git a/sites/docs/content/components/slider.md b/sites/docs/content/components/slider.md
@@ -160,6 +160,18 @@ For more in-depth information on controlled components and advanced state manage
 
 </Callout>
 
+## Value Commit
+
+You can use the `onValueCommit` prop to be notified when the user finishes dragging the thumb and the value changes. This is different than the `onValueChange` callback because it waits until the user stops dragging before calling the callback, where the `onValueChange` callback is called as the user dragging.
+
+```svelte
+<Slider.Root
+	onValueCommit={(v) => {
+		console.log("user is done sliding!", v);
+	}}
+/>
+```
+
 ## Multiple Thumbs and Ticks
 
 If the `value` prop has more than one value, the slider will render multiple thumbs. You can also use the `ticks` snippet prop to render ticks at specific intervals

diff --git a/sites/docs/src/lib/content/api-reference/slider.api.ts b/sites/docs/src/lib/content/api-reference/slider.api.ts
@@ -33,7 +33,7 @@ const root = createApiSchema<SliderRootPropsWithoutHTML>({
 			definition: SliderRootOnValueChangeProp,
 			description: "A callback function called when the value state of the slider changes.",
 		}),
-		onValueChangeEnd: createFunctionProp({
+		onValueCommit: createFunctionProp({
 			definition: SliderRootOnValueChangeProp,
 			description:
 				"A callback function called when the user finishes dragging the thumb and the value changes. This is different than the `onValueChange` callback because it waits until the user stops dragging before calling the callback, where the `onValueChange` callback is called immediately after the user starts dragging.",