svelte-tweakpane-ui 1.3.3 → 1.5.0

package/dist/control/Color.svelte

@@ -3,10 +3,11 @@
 <script>
 	import ClsPad from '../internal/ClsPad.svelte';
 	import GenericInputFolding from '../internal/GenericInputFolding.svelte';
-	import { objectToTuple, tupleToObject } from '../utils';
+	import { objectToTuple } from '../utils';
 	import { fillWith } from '../utils';
-	import { isColorObject, isObject, isRgbaColorObject, isRgbColorObject } from '@tweakpane/core';
+	import { isColorObject, isRgbaColorObject, isRgbColorObject } from '@tweakpane/core';
 	import { BROWSER } from 'esm-env';
+	import { shallowEqual } from 'fast-equals';
 	export let value;
 	export let expanded = void 0;
 	export let type = void 0;
@@ -14,34 +15,53 @@
 	let options;
 	let ref;
 	const buttonClass = 'tp-colswv_b';
-	function updateInternalValue() {
-		if (Array.isArray(value)) {
-			if (value.length === 4) {
-				internalValue = tupleToObject(value, ['r', 'g', 'b', 'a']);
-			} else if (value.length === 3) {
-				internalValue = tupleToObject(value, ['r', 'g', 'b']);
-			} else {
+	function updateInternalValueFromValue() {
+		if (typeof value === 'string') {
+			if (internalValue !== value) {
+				internalValue = value;
+			}
+		} else if (isColorObject(value)) {
+			if (!shallowEqual(value, internalValue)) {
+				internalValue = { ...value };
+			}
+		} else if (Array.isArray(value)) {
+			let newInternalValue =
+				value.length === 4
+					? { r: value[0], g: value[1], b: value[2], a: value[3] }
+					: value.length === 3
+						? { r: value[0], g: value[1], b: value[2] }
+						: void 0;
+			if (newInternalValue === void 0) {
 				console.error('Unreachable');
+			} else if (!shallowEqual(newInternalValue, internalValue)) {
+				internalValue = newInternalValue;
 			}
 		} else {
-			internalValue = value;
+			console.error('Unreachable');
 		}
 	}
-	function updateValue() {
-		if (Array.isArray(value) && isColorObject(internalValue)) {
-			if (isRgbaColorObject(internalValue)) {
-				value = objectToTuple(internalValue, ['r', 'g', 'b', 'a']);
-			} else if (isRgbColorObject(internalValue)) {
-				value = objectToTuple(internalValue, ['r', 'g', 'b']);
-			} else {
-				console.error('Unreachable');
+	function updateValueFromInternalValue() {
+		if (typeof value === 'string' && typeof internalValue === 'string') {
+			if (internalValue !== value) {
+				value = internalValue;
+			}
+		} else if (Array.isArray(value) && isColorObject(internalValue)) {
+			const newValue = isRgbaColorObject(internalValue)
+				? objectToTuple(internalValue, ['r', 'g', 'b', 'a'])
+				: isRgbColorObject(internalValue)
+					? objectToTuple(internalValue, ['r', 'g', 'b'])
+					: void 0;
+			if (newValue === void 0) {
+				console.error('Unreachable color type mismatch');
+			} else if (!shallowEqual(newValue, value)) {
+				value = newValue;
+			}
+		} else if (isColorObject(value) && isColorObject(internalValue)) {
+			if (!shallowEqual(internalValue, value)) {
+				value = { ...internalValue };
 			}
-		} else if (typeof value === 'string') {
-			value = internalValue;
-		} else if (isObject(value)) {
-			value = internalValue;
 		} else {
-			console.error('Unreachable');
+			console.error('Unreachable color type mismatch');
 		}
 	}
 	function addListeners() {
@@ -49,8 +69,8 @@
 			ref.refresh();
 		});
 	}
-	$: value, updateInternalValue();
-	$: internalValue, updateValue();
+	$: value, updateInternalValueFromValue();
+	$: internalValue, updateValueFromInternalValue();
 	$: ref !== void 0 && addListeners();
 	$: options = {
 		color: {

package/dist/control/CubicBezier.svelte

@@ -82,10 +82,3 @@
 		<ClsPad keysAdd={fillWith('containerUnitSpacing', 2)} theme={$$props.theme} />
 	{/if}
 {/if}
-
-<style>
-	/* Fix overflow bug from the plugin TODO PR */
-	:global(div.svelte-tweakpane-ui div.tp-cbzv:not(tp-cbzv-expanded) div.tp-cbzv_p) {
-		overflow: hidden !important;
-	}
-</style>

package/dist/control/File.svelte

@@ -0,0 +1,55 @@
+<script context="module"></script>
+
+<script>
+	import ClsPad from '../internal/ClsPad.svelte';
+	import GenericInput from '../internal/GenericInput.svelte';
+	import { fillWith } from '../utils';
+	import * as pluginModule from '@kitschpatrol/tweakpane-plugin-file-import';
+	import { BROWSER } from 'esm-env';
+	import { shallowEqual } from 'fast-equals';
+	export let value = void 0;
+	export let rows = void 0;
+	export let invalidExtensionMessage = void 0;
+	export let extensions = void 0;
+	let internalValue;
+	function updateInternalValueFromValue() {
+		const newInternalValue = value ?? '';
+		if (!shallowEqual(internalValue, newInternalValue)) {
+			internalValue = newInternalValue;
+		}
+	}
+	function updateValueFromInternalValue() {
+		if (internalValue instanceof File) {
+			if (!shallowEqual(value, internalValue)) {
+				value = internalValue;
+			}
+		} else if (value !== void 0) {
+			value = void 0;
+		}
+	}
+	let options;
+	$: options = {
+		extensions,
+		filetypes: extensions,
+		invalidFiletypeMessage: invalidExtensionMessage,
+		lineCount: rows,
+		view: 'file-input'
+	};
+	$: value, updateInternalValueFromValue();
+	$: internalValue, updateValueFromInternalValue();
+</script>
+
+<GenericInput
+	bind:value={internalValue}
+	on:change
+	{options}
+	plugin={pluginModule}
+	{...$$restProps}
+/>
+{#if !BROWSER}
+	{#if rows}
+		<ClsPad keysAdd={fillWith('containerUnitSize', rows)} theme={$$props.theme} />
+	{:else}
+		<ClsPad keysAdd={fillWith('containerUnitSize', 3)} theme={$$props.theme} />
+	{/if}
+{/if}

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

@@ -0,0 +1,204 @@
+import { SvelteComponent } from 'svelte';
+import type { ValueChangeEvent } from '../utils.js';
+export type FileValue = File | undefined;
+export type FileChangeEvent = ValueChangeEvent<FileValue>;
+declare const __propDef: {
+	props: {
+		/**
+		 * File data, or `undefined` to clear the file input.
+		 * @default `undefined`
+		 * @bindable
+		 */
+		value?: FileValue;
+		/**
+		 * Array of valid file extensions.
+		 * @default Any file extension
+		 */
+		extensions?: string[] | undefined;
+		/**
+		 * String shown when the user tries to upload an invalid filetype.
+		 * @default `'Unaccepted file type.'`
+		 */
+		invalidExtensionMessage?: string | undefined;
+		/**
+		 * Height of the file input drop zone, in rows.
+		 * @default `3`
+		 */
+		rows?: number | undefined;
+	} & Omit<
+		{
+			/**
+			 * File data, or `undefined` to clear the file input.
+			 * @default `undefined`
+			 * @bindable
+			 */
+			value: string | File | null;
+		} & Omit<
+			{
+				/**
+				 * The binding's target object with values to manipulate.
+				 * @bindable
+				 */
+				object: import('@tweakpane/core').Bindable & Record<string, string | File | null>;
+				/** The key for the value in the target `object` that the control should manipulate. */
+				key: string;
+				/**
+				 * Prevent interactivity and gray out the control.
+				 * @default `false`
+				 */
+				disabled?: boolean;
+				/**
+				 * Text displayed next to control.
+				 * @default `undefined`
+				 */
+				label?: string | undefined;
+				/**
+				 * Tweakpane's internal options object.
+				 *
+				 * See [`BindingParams`](https://tweakpane.github.io/docs/api/types/BindingParams.html).
+				 *
+				 * Valid types are contingent on the type of the value `key` points to in `object`.
+				 *
+				 * This is intended internal use, when implementing convenience components wrapping Binding's
+				 * functionality. Options of interest are instead exposed as top-level props in _Svelte
+				 * Tweakpane UI_.
+				 * @default `undefined`
+				 */
+				options?: import('@tweakpane/core').BaseInputParams | undefined;
+				/**
+				 * Custom color scheme.
+				 *
+				 * @default `undefined`  \
+				 * Inherits default Tweakpane theme equivalent to `ThemeUtils.presets.standard`, or the theme
+				 * set with `setGlobalDefaultTheme()`.
+				 */
+				theme?: import('..').Theme | undefined;
+				/**
+				 * Reference to internal Tweakpane
+				 * [`BindingApi`](https://tweakpane.github.io/docs/api/classes/_internal_.BindingApi.html) for
+				 * this control.
+				 *
+				 * 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>`.
+				 *
+				 * 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.
+				 *
+				 * @default `undefined`
+				 */
+				plugin?: import('../utils.js').Plugin | undefined;
+			},
+			'object' | 'key'
+		>,
+		'ref' | 'plugin' | 'value'
+	>;
+	slots: {};
+	events: {
+		/**
+		 * 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: FileChangeEvent;
+	};
+};
+export type FileProps = typeof __propDef.props;
+export type FileEvents = typeof __propDef.events;
+export type FileSlots = typeof __propDef.slots;
+/**
+ * A file input control.
+ *
+ * _Important: This component has some rough edges, and should be considered experimental._
+ *
+ * Integrates the [File Input](https://github.com/LuchoTurtle/tweakpane-plugin-file-import/blob/main/src/plugin.ts) control from [LuchoTurtle's](https://github.com/LuchoTurtle) [tweakpane-plugin-file-import](https://github.com/LuchoTurtle/tweakpane-plugin-file-import) plugin. Some of the control's parameter names have been changed for consistency with the `<Image>` CompositionEvent.
+ *
+ * Use the `<Image>` control instead if you're working with images and want to see a thumbnail preview of the image.
+ *
+ * There is currently a known bug where change events' `origin` values are sometimes incorrect. (This issue is limited to this component.)
+ *
+ * Usage outside of a `<Pane>` component will implicitly wrap the image control in `<Pane position="inline">`.
+ *
+ * Note that _Svelte Tweakpane UI_ embeds a functionally identical [fork](https://github.com/kitschpatrol/tweakpane-plugin-file-import) of the plugin with build optimizations.
+ *
+ *
+ * @emits {FileChangeEvent} change - When `value` changes. (This event is provided for advanced use cases. Prefer binding to `value`.)
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *  import { File, type FileValue } from '..';
+ *
+ *  let file: FileValue;
+ *
+ *  async function getFileBase64(file: FileValue): Promise<string> {
+ *    if (file === undefined) return 'Your bytes here...';
+ *    return new Promise((resolve, reject) => {
+ *      const reader = new FileReader();
+ *      reader.addEventListener('load', () => {
+ *        const { result } = reader;
+ *        if (result && typeof result === 'string') resolve(result);
+ *        else reject(new Error('Empty result'));
+ *      });
+ *      reader.addEventListener('error', reject);
+ *      reader.readAsDataURL(file);
+ *    });
+ *  }
+ *
+ *  function truncate(text: string, length: number) {
+ *    return text.length > length ? text.slice(0, length - 1) + '...' : text;
+ *  }
+ * </script>
+ *
+ * <File bind:value={file} label="File" />
+ *
+ * <div class="demo">
+ *  <p>
+ *    {#await getFileBase64(file)}
+ *      Loading...
+ *    {:then value}
+ *      {truncate(value, 512)}
+ *    {/await}
+ *  </p>
+ * </div>
+ *
+ * <style>
+ *  .demo {
+ *    width: 100%;
+ *    background: linear-gradient(45deg, orange, magenta);
+ *  }
+ *
+ *  .demo > p {
+ *    margin: 0;
+ *    padding: 0.5rem;
+ *    font-family: monospace;
+ *    line-height: 1.2;
+ *    color: white;
+ *    word-break: break-all;
+ *    white-space: pre-wrap;
+ *  }
+ * </style>
+ * ```
+ *
+ * @sourceLink
+ * [File.svelte](https://github.com/kitschpatrol/svelte-tweakpane-ui/blob/main/src/lib/control/File.svelte)
+ */
+export default class File extends SvelteComponent<FileProps, FileEvents, FileSlots> {}
+export {};

package/dist/control/Image.svelte

@@ -6,18 +6,52 @@
 	import { fillWith } from '../utils';
 	import * as pluginModule from '@kitschpatrol/tweakpane-plugin-image';
 	import { BROWSER } from 'esm-env';
-	export let value = 'placeholder';
+	import { shallowEqual } from 'fast-equals';
+	export let value = void 0;
 	export let fit = void 0;
 	export let extensions = void 0;
+	let internalValue = 'placeholder';
+	function updateInternalValueFromValue() {
+		const newInternalValue = value ?? 'placeholder';
+		if (!shallowEqual(internalValue, newInternalValue)) {
+			internalValue = newInternalValue;
+		}
+	}
+	function updateValueFromInternalValue() {
+		if (internalValue === 'placeholder') {
+			if (value !== void 0) {
+				value = void 0;
+			}
+		} else if (internalValue instanceof HTMLImageElement) {
+			if (value !== internalValue.src) {
+				value = internalValue.src;
+			}
+		} else if (internalValue instanceof File) {
+			console.warn('Image control does not support File objects.');
+			if (value !== void 0) {
+				value = void 0;
+			}
+		} else if (value !== internalValue) {
+			value = internalValue;
+		}
+	}
 	let options;
 	$: options = {
 		extensions,
 		imageFit: fit,
 		view: 'input-image'
 	};
+	$: value, updateInternalValueFromValue();
+	$: internalValue, updateValueFromInternalValue();
 </script>
 
-<GenericInput bind:value on:change {options} plugin={pluginModule} {...$$restProps} />
+<GenericInput
+	bind:value={internalValue}
+	on:change
+	{options}
+	plugin={pluginModule}
+	{...$$restProps}
+/>
 {#if !BROWSER}
 	<ClsPad keysAdd={fillWith('containerVerticalPadding', 2)} theme={$$props.theme} />
 {/if}

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

@@ -1,12 +1,12 @@
 import { SvelteComponent } from 'svelte';
 import type { ValueChangeEvent } from '../utils.js';
-export type ImageValue = 'placeholder' | File | HTMLImageElement | string | undefined;
+export type ImageValue = string | undefined;
 export type ImageChangeEvent = ValueChangeEvent<ImageValue>;
 declare const __propDef: {
 	props: {
 		/**
-		 * Image data
-		 * @default `'placeholder'`
+		 * Image data as Base64-encoded string, or `undefined` to clear.
+		 * @default `'undefined'`
 		 * @bindable
 		 */
 		value?: ImageValue;
@@ -25,18 +25,19 @@ declare const __propDef: {
 	} & Omit<
 		{
 			/**
-			 * Image data
-			 * @default `'placeholder'`
+			 * Image data as Base64-encoded string, or `undefined` to clear.
+			 * @default `'undefined'`
 			 * @bindable
 			 */
-			value: ImageValue;
+			value: string | HTMLImageElement | File | undefined;
 		} & Omit<
 			{
 				/**
 				 * The binding's target object with values to manipulate.
 				 * @bindable
 				 */
-				object: import('@tweakpane/core').Bindable & Record<string, ImageValue>;
+				object: import('@tweakpane/core').Bindable &
+					Record<string, string | HTMLImageElement | File | undefined>;
 				/** The key for the value in the target `object` that the control should manipulate. */
 				key: string;
 				/**
@@ -130,6 +131,8 @@ export type ImageSlots = typeof __propDef.slots;
  * Dias](https://www.linkedin.com/in/matheusdbs/), [Palash Bansal](https://github.com/repalash), and
  * others.
  *
+ * Use the `<File>` control instead if you're working with other file types, or don't wish to display a thumbnail preview of an uploaded image.
+ *
  * There is currently a known bug where change events' `origin` values are sometimes incorrect. (This issue is limited to this component.)
  *
  * Usage outside of a `<Pane>` component will implicitly wrap the image control in `<Pane
@@ -142,15 +145,15 @@ export type ImageSlots = typeof __propDef.slots;
  * @example
  * ```svelte
  * <script lang="ts">
- * import { Button, Image } from 'svelte-tweakpane-ui';
+ * import { Button, Image, type ImageValue } from '..';
  *
- * let source = 'placeholder';
+ * let source: ImageValue;
  *
  * async function getRandomKittenUrl() {
- *   const { url } = await fetch(
- *     'https://source.unsplash.com/800x800/?kitten',
- *     { method: 'HEAD', redirect: 'follow' }
- *   );
+ *   const { url } = await fetch('https://loremflickr.com/800/800/kitten', {
+ *     method: 'HEAD',
+ *     redirect: 'follow'
+ *   });
  *   return url;
  * }
  * </script>
@@ -165,9 +168,9 @@ export type ImageSlots = typeof __propDef.slots;
  * />
  *
  * <div class="demo">
- * {#if source === 'placeholder'}
+ * {#if source === undefined}
  *   <p>Tap “No Image” above to load an image from disk.</p>
- * {:else}
+ * {:else if typeof source === 'string'}
  *   <img alt="" src={source} />
  * {/if}
  * </div>

package/dist/control/IntervalSlider.svelte

@@ -3,30 +3,34 @@
 <script>
 	import GenericSlider from '../internal/GenericSlider.svelte';
 	import * as pluginModule from '@kitschpatrol/tweakpane-plugin-essentials';
+	import { shallowEqual } from 'fast-equals';
 	export let value;
 	export let meanValue = void 0;
 	export let wide = void 0;
 	let internalValue;
-	function updateInternalValue() {
-		if (Array.isArray(value)) {
-			const [min, max] = value;
-			internalValue = { min, max };
-		} else {
-			internalValue = value;
+	function updateInternalValueFromValue() {
+		const newInternalValue = Array.isArray(value) ? { min: value[0], max: value[1] } : value;
+		if (!shallowEqual(internalValue, newInternalValue)) {
+			internalValue = { ...newInternalValue };
 		}
 	}
-	function updateValue() {
+	function updateValueFromInternalValue() {
 		if (Array.isArray(value)) {
-			const { min, max } = internalValue;
-			value = [min, max];
-		} else {
-			value = internalValue;
+			const newValue = [internalValue.min, internalValue.max];
+			if (!shallowEqual(value, newValue)) {
+				value = newValue;
+			}
+		} else if (!shallowEqual(value, internalValue)) {
+			value = { ...internalValue };
 		}
 	}
 	function updateValueFromMean() {
 		if (meanValue !== void 0) {
 			const r = internalValue.max - internalValue.min;
-			internalValue = { min: meanValue - r / 2, max: meanValue + r / 2 };
+			const valueFromMean = { min: meanValue - r / 2, max: meanValue + r / 2 };
+			if (!shallowEqual(valueFromMean, internalValue)) {
+				internalValue = valueFromMean;
+			}
 		}
 	}
 	let ref;
@@ -39,8 +43,8 @@
 		}
 	}
 	$: ref && wide !== void 0 && updateWide(wide);
-	$: value, updateInternalValue();
-	$: internalValue, updateValue();
+	$: value, updateInternalValueFromValue();
+	$: internalValue, updateValueFromInternalValue();
 	$: meanValue = (internalValue.min + internalValue.max) / 2;
 	$: meanValue, updateValueFromMean();
 </script>

package/dist/control/Point.svelte

@@ -5,6 +5,7 @@
 	import GenericInputFolding from '../internal/GenericInputFolding.svelte';
 	import { removeKeys } from '../utils';
 	import { BROWSER } from 'esm-env';
+	import { shallowEqual } from 'fast-equals';
 	export let value;
 	export let expanded = $$props.expanded ?? void 0;
 	let pointerScale = $$props['pointerScale'] ?? void 0;
@@ -20,40 +21,38 @@
 	let internalValue;
 	let options;
 	const buttonClass = 'tp-p2dv_b';
-	function updateInternalValue() {
+	function updateInternalValueFromValue() {
 		if (Array.isArray(value)) {
-			if (value.length === 4) {
-				const [x, y, z, w] = value;
-				internalValue = { x, y, z, w };
-			} else if (value.length === 3) {
-				const [x, y, z] = value;
-				internalValue = { x, y, z };
-			} else {
-				const [x, y] = value;
-				internalValue = { x, y };
+			const newInternalValue =
+				value.length === 4
+					? { x: value[0], y: value[1], z: value[2], w: value[3] }
+					: value.length === 3
+						? { x: value[0], y: value[1], z: value[2] }
+						: { x: value[0], y: value[1] };
+			if (!shallowEqual(internalValue, newInternalValue)) {
+				internalValue = newInternalValue;
 			}
-		} else {
-			internalValue = value;
+		} else if (!shallowEqual(internalValue, value)) {
+			internalValue = { ...value };
 		}
 	}
-	function updateValue() {
+	function updateValueFromInternalValue() {
 		if (Array.isArray(value)) {
-			if ('w' in internalValue) {
-				const { x, y, z, w } = internalValue;
-				value = [x, y, z, w];
-			} else if ('z' in internalValue) {
-				const { x, y, z } = internalValue;
-				value = [x, y, z];
-			} else {
-				const { x, y } = internalValue;
-				value = [x, y];
+			const newValue =
+				'w' in internalValue
+					? [internalValue.x, internalValue.y, internalValue.z, internalValue.w]
+					: 'z' in internalValue
+						? [internalValue.x, internalValue.y, internalValue.z]
+						: [internalValue.x, internalValue.y];
+			if (!shallowEqual(value, newValue)) {
+				value = newValue;
 			}
-		} else {
-			value = internalValue;
+		} else if (!shallowEqual(value, internalValue)) {
+			value = { ...internalValue };
 		}
 	}
-	$: value, updateInternalValue();
-	$: internalValue, updateValue();
+	$: value, updateInternalValueFromValue();
+	$: internalValue, updateValueFromInternalValue();
 	$: options = {
 		x: optionsX,
 		y: optionsY,