svelte-tweakpane-ui 1.1.3 → 1.2.0

package/dist/control/RotationQuaternion.svelte.d.ts

@@ -1,6 +1,7 @@
 import { SvelteComponent } from 'svelte';
 import type { PointDimensionParams } from '@tweakpane/core';
 import type { Simplify } from '../utils';
+import type { ValueChangeEvent } from '../utils.js';
 export type RotationQuaternionOptions = Simplify<PointDimensionParams>;
 export type RotationQuaternionValueObject = {
 	x: number;
@@ -12,6 +13,7 @@ export type RotationQuaternionValueTuple = [x: number, y: number, z: number, w:
 export type RotationQuaternionValue = Simplify<
 	RotationQuaternionValueObject | RotationQuaternionValueTuple
 >;
+export type RotationQuaternionChangeEvent = ValueChangeEvent<RotationQuaternionValue>;
 import type { RotationInputPluginQuaternionParams as RotationQuaternionOptionsInternal } from '@0b5vr/tweakpane-plugin-rotation/dist/types/RotationInputPluginQuaternionParams';
 declare const __propDef: {
 	props: Omit<
@@ -60,18 +62,24 @@ declare const __propDef: {
 				 * [`BindingApi`](https://tweakpane.github.io/docs/api/classes/_internal_.BindingApi.html) for
 				 * this control.
 				 *
-				 * This is primarily for internal use, when implementing convenience components wrapping
-				 * Binding's functionality.
+				 * This property is exposed for advanced use cases only, such as when implementing convenience
+				 * components wrapping `<Binding>`'s functionality.
+				 *
+				 * Direct manipulation of Tweakpane's internals can break _Svelte Tweakpane UI_ abstractions.
+				 *
 				 * @bindable
 				 * @readonly
 				 */
 				ref?: import('../internal/GenericInput.svelte').GenericInputRef | undefined;
 				/**
 				 * Imported Tweakpane `TpPluginBundle` (aliased as `Plugin`) module to automatically register in
-				 * the binding's containing `<Pane>`.
+				 * the `<Binding>`'s containing `<Pane>`.
+				 *
+				 * This property is exposed for advanced use cases only, such as when implementing convenience
+				 * components wrapping `<Binding>`'s functionality in combination with a Tweakpane plugin.
+				 *
+				 * Direct manipulation of Tweakpane's internals can break _Svelte Tweakpane UI_ abstractions.
 				 *
-				 * This is primarily for internal use, when implementing convenience components wrapping
-				 * Binding's functionality in combination with a Tweakpane plugin.
 				 * @default `undefined`
 				 */
 				plugin?: import('@tweakpane/core').TpPluginBundle | undefined;
@@ -188,10 +196,21 @@ declare const __propDef: {
 			  }
 			| undefined;
 	};
+	slots: {};
 	events: {
-		[evt: string]: CustomEvent<any>;
+		/**
+		 * Fires when `value` changes.
+		 *
+		 * _This event is provided for advanced use cases. It's usually preferred to bind to the `value` prop instead._
+		 *
+		 * The `event.details` payload includes a copy of the value and an `origin` field to distinguish between user-interactive changes (`internal`)
+		 * and changes resulting from programmatic manipulation of the `value` (`external`).
+		 *
+		 * @extends ValueChangeEvent
+		 * @event
+		 * */
+		change: RotationQuaternionChangeEvent;
 	};
-	slots: {};
 };
 export type RotationQuaternionProps = typeof __propDef.props;
 export type RotationQuaternionEvents = typeof __propDef.events;
@@ -211,14 +230,11 @@ export type RotationQuaternionSlots = typeof __propDef.slots;
  *
  * See also <RotationEuler> if you're not into the whole `w` thing.
  *
+ * @emits {RotationQuaternionChangeEvent} change - When `value` changes. (This event is provided for advanced use cases. Prefer binding to `value`.)
+ *
  * Usage outside of a `<Pane>` component will implicitly wrap the profiler in `<Pane
  * position='inline'>`.
  *
- *
- *
- *
- *
- *
  * @example
  * ```svelte
  * <script lang="ts">

package/dist/control/Slider.svelte

@@ -1,6 +1,8 @@
+<script context="module"></script>
+
 <script>
 	import GenericSlider from '../internal/GenericSlider.svelte';
 	export let value;
 </script>
 
-<GenericSlider bind:value {...$$restProps} />
+<GenericSlider bind:value on:change {...$$restProps} />

package/dist/control/Slider.svelte.d.ts

@@ -1,4 +1,6 @@
 import { SvelteComponent } from 'svelte';
+import type { ValueChangeEvent } from '../utils.js';
+export type SliderChangeEvent = ValueChangeEvent<number>;
 declare const __propDef: {
 	props: Omit<
 		Omit<
@@ -46,18 +48,24 @@ declare const __propDef: {
 				 * [`BindingApi`](https://tweakpane.github.io/docs/api/classes/_internal_.BindingApi.html) for
 				 * this control.
 				 *
-				 * This is primarily for internal use, when implementing convenience components wrapping
-				 * Binding's functionality.
+				 * This property is exposed for advanced use cases only, such as when implementing convenience
+				 * components wrapping `<Binding>`'s functionality.
+				 *
+				 * Direct manipulation of Tweakpane's internals can break _Svelte Tweakpane UI_ abstractions.
+				 *
 				 * @bindable
 				 * @readonly
 				 */
 				ref?: import('tweakpane').SliderInputBindingApi | undefined;
 				/**
 				 * Imported Tweakpane `TpPluginBundle` (aliased as `Plugin`) module to automatically register in
-				 * the binding's containing `<Pane>`.
+				 * the `<Binding>`'s containing `<Pane>`.
+				 *
+				 * This property is exposed for advanced use cases only, such as when implementing convenience
+				 * components wrapping `<Binding>`'s functionality in combination with a Tweakpane plugin.
+				 *
+				 * Direct manipulation of Tweakpane's internals can break _Svelte Tweakpane UI_ abstractions.
 				 *
-				 * This is primarily for internal use, when implementing convenience components wrapping
-				 * Binding's functionality in combination with a Tweakpane plugin.
 				 * @default `undefined`
 				 */
 				plugin?: import('tweakpane').TpPluginBundle | undefined;
@@ -85,7 +93,7 @@ declare const __propDef: {
 			 */
 			max?: number | undefined;
 			/**
-			 * A function to customize the point value's formatting (e.g. rounding, etc.).
+			 * A function to customize the point value's string representation (e.g. rounding, etc.).
 			 * @default `undefined`  \
 			 * Normal `.toString()` formatting.
 			 */
@@ -118,26 +126,39 @@ declare const __propDef: {
 		 * */
 		value: number;
 	};
+	slots: {};
 	events: {
-		[evt: string]: CustomEvent<any>;
+		/**
+		 * Fires when `value` changes.
+		 *
+		 * _This event is provided for advanced use cases. It's usually preferred to bind to the `value` prop instead._
+		 *
+		 * The `event.details` payload includes a copy of the value and an `origin` field to distinguish between user-interactive changes (`internal`)
+		 * and changes resulting from programmatic manipulation of the `value` (`external`).
+		 *
+		 * @extends ValueChangeEvent
+		 * @event
+		 * */
+		change: SliderChangeEvent;
 	};
-	slots: {};
 };
 export type SliderProps = typeof __propDef.props;
 export type SliderEvents = typeof __propDef.events;
 export type SliderSlots = typeof __propDef.slots;
 /**
- * A slider component providing fine-grained control over numerical values.
+ * A slider component providing fine-grained control over numeric values.
  *
  * Wraps Tweakpane's [number bindings](https://tweakpane.github.io/docs/input-bindings/#number).
  *
  * Note that if `min` and `max` props are not defined, no linear slider widget will be provided and a
  * input field with a draggable handle will be used instead.
  *
- * Usage outside of a `<Pane>` component will implicitly wrap the slider in `<Pane position='inline'>`.
- *
  * See the `<Interval>` component for a multi-handle range-defining slider.
  *
+ * @emits {SliderChangeEvent} change - When `value` changes. (This event is provided for advanced use cases. Prefer binding to `value`.)
+ *
+ * Usage outside of a `<Pane>` component will implicitly wrap the slider in `<Pane position='inline'>`.
+ *
  * @example
  * ```svelte
  * <script lang="ts">

package/dist/control/Text.svelte

@@ -1,3 +1,5 @@
+<script context="module"></script>
+
 <script>
 	import GenericInput from '../internal/GenericInput.svelte';
 	import { onDestroy } from 'svelte';
@@ -8,18 +10,14 @@
 		updateListeners(live ?? true, true);
 	});
 	function onInput(event) {
-		if (event.target) {
-			value = event.target.value;
-		}
+		event.target?.dispatchEvent(new Event('change'));
 	}
 	function updateListeners(live2, destroy = false) {
-		let input = ref?.controller.valueController.view.element.querySelector('input');
-		if (input) {
-			input.removeEventListener('input', onInput);
-			!destroy && live2 && input.addEventListener('input', onInput);
-		}
+		const input = ref?.controller.valueController.view.element.querySelector('input');
+		input?.removeEventListener('input', onInput);
+		!destroy && live2 && input?.addEventListener('input', onInput);
 	}
 	$: ref && live !== void 0 && updateListeners(live);
 </script>
 
-<GenericInput bind:value bind:ref {...$$restProps} />
+<GenericInput bind:value bind:ref on:change {...$$restProps} />

package/dist/control/Text.svelte.d.ts

@@ -1,4 +1,6 @@
 import { SvelteComponent } from 'svelte';
+import type { ValueChangeEvent } from '../utils.js';
+export type TextChangeEvent = ValueChangeEvent<string>;
 import { type GenericInputRef } from '../internal/GenericInput.svelte';
 declare const __propDef: {
 	props: Omit<
@@ -47,18 +49,24 @@ declare const __propDef: {
 				 * [`BindingApi`](https://tweakpane.github.io/docs/api/classes/_internal_.BindingApi.html) for
 				 * this control.
 				 *
-				 * This is primarily for internal use, when implementing convenience components wrapping
-				 * Binding's functionality.
+				 * This property is exposed for advanced use cases only, such as when implementing convenience
+				 * components wrapping `<Binding>`'s functionality.
+				 *
+				 * Direct manipulation of Tweakpane's internals can break _Svelte Tweakpane UI_ abstractions.
+				 *
 				 * @bindable
 				 * @readonly
 				 */
 				ref?: GenericInputRef | undefined;
 				/**
 				 * Imported Tweakpane `TpPluginBundle` (aliased as `Plugin`) module to automatically register in
-				 * the binding's containing `<Pane>`.
+				 * the `<Binding>`'s containing `<Pane>`.
+				 *
+				 * This property is exposed for advanced use cases only, such as when implementing convenience
+				 * components wrapping `<Binding>`'s functionality in combination with a Tweakpane plugin.
+				 *
+				 * Direct manipulation of Tweakpane's internals can break _Svelte Tweakpane UI_ abstractions.
 				 *
-				 * This is primarily for internal use, when implementing convenience components wrapping
-				 * Binding's functionality in combination with a Tweakpane plugin.
 				 * @default `undefined`
 				 */
 				plugin?: import('tweakpane').TpPluginBundle | undefined;
@@ -87,10 +95,21 @@ declare const __propDef: {
 		 * */
 		live?: boolean | undefined;
 	};
+	slots: {};
 	events: {
-		[evt: string]: CustomEvent<any>;
+		/**
+		 * Fires when `value` changes.
+		 *
+		 * _This event is provided for advanced use cases. It's usually preferred to bind to the `value` prop instead._
+		 *
+		 * The `event.details` payload includes a copy of the value and an `origin` field to distinguish between user-interactive changes (`internal`)
+		 * and changes resulting from programmatic manipulation of the `value` (`external`).
+		 *
+		 * @extends ValueChangeEvent
+		 * @event
+		 * */
+		change: TextChangeEvent;
 	};
-	slots: {};
 };
 export type TextProps = typeof __propDef.props;
 export type TextEvents = typeof __propDef.events;
@@ -105,6 +124,8 @@ export type TextSlots = typeof __propDef.slots;
  *
  * See `<TextArea>` for a multi-line input variation.
  *
+ * @emits {TextChangeEvent} change - When `value` changes. (This event is provided for advanced use cases. Prefer binding to `value`.)
+ *
  * Usage outside of a `<Pane>` component will implicitly wrap the text field in `<Pane
  * position='inline'>`.
  *

package/dist/control/Textarea.svelte

@@ -1,12 +1,16 @@
+<script context="module"></script>
+
 <script>
 	import * as pluginModule from '@kitschpatrol/tweakpane-textarea-plugin';
 	import GenericInput from '../internal/GenericInput.svelte';
+	import {} from '../utils.js';
 	import { BROWSER } from 'esm-env';
-	import { onDestroy } from 'svelte';
+	import { createEventDispatcher, onDestroy } from 'svelte';
 	export let value;
 	export let live = true;
 	export let rows = void 0;
 	export let placeholder = void 0;
+	const dispatch = createEventDispatcher();
 	let _value = value;
 	let ref;
 	let options;
@@ -15,17 +19,26 @@
 	});
 	function onBlur(event) {
 		value = event.target.value;
+		lastText = value;
+		dispatch('change', { value, origin: 'internal' });
 	}
 	function onInput(event) {
 		value = event.target.value;
+		lastText = value;
+		dispatch('change', { value, origin: 'internal' });
 	}
 	function updateListeners(live2, destroy = false) {
 		const input = ref?.controller.valueController.view.element.querySelector('textarea');
-		if (input) {
-			input.removeEventListener('blur', onBlur);
-			input.removeEventListener('input', onInput);
-			!destroy && live2 && input.addEventListener('input', onInput);
-			!destroy && !live2 && input.addEventListener('blur', onBlur);
+		input?.removeEventListener('blur', onBlur);
+		input?.removeEventListener('input', onInput);
+		!destroy && live2 && input?.addEventListener('input', onInput);
+		!destroy && !live2 && input?.addEventListener('blur', onBlur);
+	}
+	let lastText = value;
+	function onBoundValueChange(text) {
+		if (text !== lastText) {
+			dispatch('change', { value: text, origin: 'external' });
+			lastText = text;
 		}
 	}
 	$: _value = value;
@@ -35,6 +48,7 @@
 		rows,
 		view: 'textarea'
 	};
+	$: ref && onBoundValueChange(_value);
 </script>
 
 <GenericInput value={_value} bind:ref {options} plugin={pluginModule} {...$$restProps} />

package/dist/control/Textarea.svelte.d.ts

@@ -1,4 +1,6 @@
 import { SvelteComponent } from 'svelte';
+import type { ValueChangeEvent } from '../utils.js';
+export type TextareaChangeEvent = ValueChangeEvent<string>;
 import type { TextareaPluginInputParams } from '@kitschpatrol/tweakpane-textarea-plugin/dist/types/plugin.js';
 import { type GenericInputRef } from '../internal/GenericInput.svelte';
 declare const __propDef: {
@@ -48,18 +50,24 @@ declare const __propDef: {
 				 * [`BindingApi`](https://tweakpane.github.io/docs/api/classes/_internal_.BindingApi.html) for
 				 * this control.
 				 *
-				 * This is primarily for internal use, when implementing convenience components wrapping
-				 * Binding's functionality.
+				 * This property is exposed for advanced use cases only, such as when implementing convenience
+				 * components wrapping `<Binding>`'s functionality.
+				 *
+				 * Direct manipulation of Tweakpane's internals can break _Svelte Tweakpane UI_ abstractions.
+				 *
 				 * @bindable
 				 * @readonly
 				 */
 				ref?: GenericInputRef | undefined;
 				/**
 				 * Imported Tweakpane `TpPluginBundle` (aliased as `Plugin`) module to automatically register in
-				 * the binding's containing `<Pane>`.
+				 * the `<Binding>`'s containing `<Pane>`.
+				 *
+				 * This property is exposed for advanced use cases only, such as when implementing convenience
+				 * components wrapping `<Binding>`'s functionality in combination with a Tweakpane plugin.
+				 *
+				 * Direct manipulation of Tweakpane's internals can break _Svelte Tweakpane UI_ abstractions.
 				 *
-				 * This is primarily for internal use, when implementing convenience components wrapping
-				 * Binding's functionality in combination with a Tweakpane plugin.
 				 * @default `undefined`
 				 */
 				plugin?: import('tweakpane').TpPluginBundle | undefined;
@@ -97,10 +105,21 @@ declare const __propDef: {
 		 */
 		rows?: number | undefined;
 	};
+	slots: {};
 	events: {
-		[evt: string]: CustomEvent<any>;
+		/**
+		 * Fires when `value` changes.
+		 *
+		 * _This event is provided for advanced use cases. It's usually preferred to bind to the `value` prop instead._
+		 *
+		 * The `event.details` payload includes a copy of the value and an `origin` field to distinguish between user-interactive changes (`internal`)
+		 * and changes resulting from programmatic manipulation of the `value` (`external`).
+		 *
+		 * @extends ValueChangeEvent
+		 * @event
+		 * */
+		change: TextareaChangeEvent;
 	};
-	slots: {};
 };
 export type TextareaProps = typeof __propDef.props;
 export type TextareaEvents = typeof __propDef.events;
@@ -121,6 +140,8 @@ export type TextareaSlots = typeof __propDef.slots;
  * [pull request](https://github.com/panGenerator/tweakpane-textarea-plugin/pull/4) with Tweakpane 4
  * support is merged.
  *
+ * @emits {TextareaChangeEvent} change - When `value` changes. (This event is provided for advanced use cases. Prefer binding to `value`.)
+ *
  * Usage outside of a `<Pane>` component will implicitly wrap the text area in `<Pane
  * position='inline'>`.
  *

package/dist/control/Wheel.svelte

@@ -1,3 +1,5 @@
+<script context="module"></script>
+
 <script>
 	import * as pluginModule from '@tweakpane/plugin-camerakit';
 	import GenericSlider from '../internal/GenericSlider.svelte';
@@ -12,4 +14,4 @@
 	};
 </script>
 
-<GenericSlider bind:value {options} plugin={pluginModule} {...$$restProps} />
+<GenericSlider bind:value on:change {options} plugin={pluginModule} {...$$restProps} />

package/dist/control/Wheel.svelte.d.ts

@@ -1,4 +1,6 @@
 import { SvelteComponent } from 'svelte';
+import type { ValueChangeEvent } from '../utils.js';
+export type WheelChangeEvent = ValueChangeEvent<number>;
 declare const __propDef: {
 	props: Omit<
 		Omit<
@@ -46,18 +48,24 @@ declare const __propDef: {
 				 * [`BindingApi`](https://tweakpane.github.io/docs/api/classes/_internal_.BindingApi.html) for
 				 * this control.
 				 *
-				 * This is primarily for internal use, when implementing convenience components wrapping
-				 * Binding's functionality.
+				 * This property is exposed for advanced use cases only, such as when implementing convenience
+				 * components wrapping `<Binding>`'s functionality.
+				 *
+				 * Direct manipulation of Tweakpane's internals can break _Svelte Tweakpane UI_ abstractions.
+				 *
 				 * @bindable
 				 * @readonly
 				 */
 				ref?: import('tweakpane').SliderInputBindingApi | undefined;
 				/**
 				 * Imported Tweakpane `TpPluginBundle` (aliased as `Plugin`) module to automatically register in
-				 * the binding's containing `<Pane>`.
+				 * the `<Binding>`'s containing `<Pane>`.
+				 *
+				 * This property is exposed for advanced use cases only, such as when implementing convenience
+				 * components wrapping `<Binding>`'s functionality in combination with a Tweakpane plugin.
+				 *
+				 * Direct manipulation of Tweakpane's internals can break _Svelte Tweakpane UI_ abstractions.
 				 *
-				 * This is primarily for internal use, when implementing convenience components wrapping
-				 * Binding's functionality in combination with a Tweakpane plugin.
 				 * @default `undefined`
 				 */
 				plugin?: import('tweakpane').TpPluginBundle | undefined;
@@ -85,7 +93,7 @@ declare const __propDef: {
 			 */
 			max?: number | undefined;
 			/**
-			 * A function to customize the point value's formatting (e.g. rounding, etc.).
+			 * A function to customize the point value's string representation (e.g. rounding, etc.).
 			 * @default `undefined`  \
 			 * Normal `.toString()` formatting.
 			 */
@@ -124,16 +132,27 @@ declare const __propDef: {
 		 */
 		amount?: number | undefined;
 		/**
-		 * When `true`, expand the width of the wheel control at the expense of the numerical input
+		 * When `true`, expand the width of the wheel control at the expense of the numeric input
 		 * field.
 		 * @default `false`
 		 * */
 		wide?: boolean | undefined;
 	};
+	slots: {};
 	events: {
-		[evt: string]: CustomEvent<any>;
+		/**
+		 * Fires when `value` changes.
+		 *
+		 * _This event is provided for advanced use cases. It's usually preferred to bind to the `value` prop instead._
+		 *
+		 * The `event.details` payload includes a copy of the value and an `origin` field to distinguish between user-interactive changes (`internal`)
+		 * and changes resulting from programmatic manipulation of the `value` (`external`).
+		 *
+		 * @extends ValueChangeEvent
+		 * @event
+		 * */
+		change: WheelChangeEvent;
 	};
-	slots: {};
 };
 export type WheelProps = typeof __propDef.props;
 export type WheelEvents = typeof __propDef.events;
@@ -147,6 +166,8 @@ export type WheelSlots = typeof __propDef.slots;
  * control from Tweakpane-creator [Hiroki Kokubun's](https://cocopon.me) [Camerakit
  * plugin](https://github.com/tweakpane/plugin-camerakit).
  *
+ * @emits {WheelChangeEvent} change - When `value` changes. (This event is provided for advanced use cases. Prefer binding to `value`.)
+ *
  * Usage outside of a `<Pane>` component will implicitly wrap the wheel in `<Pane position='inline'>`.
  *
  * @example

package/dist/core/Binding.svelte

@@ -5,7 +5,9 @@
 	import InternalPaneInline from '../internal/InternalPaneInline.svelte';
 	import { enforceReadonly, getElementIndex, isRootPane } from '../utils.js';
 	import { BROWSER, DEV } from 'esm-env';
-	import { getContext, onDestroy, onMount } from 'svelte';
+	import copy from 'fast-copy';
+	import { shallowEqual } from 'fast-equals';
+	import { createEventDispatcher, getContext, onDestroy, onMount } from 'svelte';
 	export let object;
 	export let key;
 	export let disabled = false;
@@ -30,11 +32,10 @@
 			label,
 			...options,
 			disabled
+			// Why last?
 		});
 		ref = _ref;
-		_ref.on('change', () => {
-			object = object;
-		});
+		_ref.on('change', onTweakpaneChange);
 	}
 	onMount(() => {
 		index = indexElement ? getElementIndex(indexElement) : 0;
@@ -42,13 +43,35 @@
 	onDestroy(() => {
 		_ref?.dispose();
 	});
+	const dispatch = createEventDispatcher();
+	let lastValue = copy(object[key]);
+	let internalChange = false;
+	function onBoundValueChange(object2) {
+		if (!shallowEqual(object2[key], lastValue)) {
+			lastValue = copy(object2[key]);
+			dispatch('change', {
+				value: copy(object2[key]),
+				origin: internalChange ? 'internal' : 'external'
+			});
+			if (!internalChange && _ref) {
+				_ref.off('change', onTweakpaneChange);
+				_ref.refresh();
+				_ref.on('change', onTweakpaneChange);
+			}
+		}
+		internalChange = false;
+	}
+	function onTweakpaneChange() {
+		internalChange = true;
+		object = object;
+	}
 	$: DEV && enforceReadonly(_ref, ref, 'Binding', 'ref', true);
 	$: options, $parentStore !== void 0 && index !== void 0 && create();
-	$: object, _ref !== void 0 && _ref.refresh();
 	$: _ref !== void 0 && (_ref.disabled = disabled);
 	$: _ref !== void 0 && (_ref.label = label);
+	$: $parentStore !== void 0 && onBoundValueChange(object);
 	$: theme &&
-		$parentStore &&
+		$parentStore !== void 0 &&
 		(userCreatedPane || !isRootPane($parentStore)) &&
 		console.warn(
 			'Set theme on the <Pane> component, not on its children! (Check nested <Binding> components for a theme prop.)'
@@ -63,6 +86,15 @@
 	{/if}
 {:else}
 	<InternalPaneInline {theme} userCreatedPane={false}>
-		<svelte:self bind:disabled bind:key bind:label bind:object bind:options bind:plugin bind:ref />
+		<svelte:self
+			bind:disabled
+			bind:key
+			bind:label
+			bind:object
+			bind:options
+			bind:plugin
+			bind:ref
+			on:change
+		/>
 	</InternalPaneInline>
 {/if}

package/dist/core/Binding.svelte.d.ts

@@ -1,8 +1,10 @@
 import { SvelteComponent } from 'svelte';
 import type { BindingApi, BindingParams } from '@tweakpane/core';
 import type { BindingObject } from '../utils';
+import type { ValueChangeEvent } from '../utils.js';
 export type BindingOptions = BindingParams;
 export type BindingRef = BindingApi;
+export type BindingChangeEvent = ValueChangeEvent<BindingObject>;
 import type { Theme } from '../theme.js';
 declare class __sveltets_Render<
 	T extends BindingObject,
@@ -47,22 +49,39 @@ declare class __sveltets_Render<
 		 * [`BindingApi`](https://tweakpane.github.io/docs/api/classes/_internal_.BindingApi.html) for
 		 * this control.
 		 *
-		 * This is primarily for internal use, when implementing convenience components wrapping
-		 * Binding's functionality.
+		 * This property is exposed for advanced use cases only, such as when implementing convenience
+		 * components wrapping `<Binding>`'s functionality.
+		 *
+		 * Direct manipulation of Tweakpane's internals can break _Svelte Tweakpane UI_ abstractions.
+		 *
 		 * @bindable
 		 * @readonly
 		 * */ ref?: V | undefined;
 		/**
 		 * Imported Tweakpane `TpPluginBundle` (aliased as `Plugin`) module to automatically register in
-		 * the binding's containing `<Pane>`.
+		 * the `<Binding>`'s containing `<Pane>`.
+		 *
+		 * This property is exposed for advanced use cases only, such as when implementing convenience
+		 * components wrapping `<Binding>`'s functionality in combination with a Tweakpane plugin.
+		 *
+		 * Direct manipulation of Tweakpane's internals can break _Svelte Tweakpane UI_ abstractions.
 		 *
-		 * This is primarily for internal use, when implementing convenience components wrapping
-		 * Binding's functionality in combination with a Tweakpane plugin.
 		 * @default `undefined`
 		 * */ plugin?: import('@tweakpane/core').TpPluginBundle | undefined;
 	};
-	events(): {} & {
-		[evt: string]: CustomEvent<any>;
+	events(): {
+		/**
+		 * Fires when the value of `object[key]` changes.
+		 *
+		 * _This event is provided for advanced use cases. It's usually preferred to bind to the `object` prop instead._
+		 *
+		 * The `event.details` payload includes a copy of the value and an `origin` field to distinguish between user-interactive changes (`internal`)
+		 * and changes resulting from programmatic manipulation of the `object` (`external`).
+		 *
+		 * @extends ValueChangeEvent
+		 * @event
+		 * */
+		change: BindingChangeEvent;
 	};
 	slots(): {};
 }
@@ -90,6 +109,8 @@ export type BindingSlots<
  * Please consider convenience components like `<Slider>`, `<Color>`, etc. etc. before using this
  * component directly.
  *
+ * @emits {BindingChangeEvent} change - When the value of `object[key]` changes. (This event is provided for advanced use cases. Prefer binding to `object`.)
+ *
  * Usage outside of a `<Pane>` component will implicitly wrap the component in `<Pane
  * position='inline'>`.
  *