svelte-tweakpane-ui 1.0.0

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

@@ -0,0 +1,276 @@
+import { SvelteComponent } from 'svelte';
+import type { PointDimensionParams } from '@tweakpane/core';
+import type { Simplify } from '../utils';
+export type RotationQuaternionOptions = Simplify<PointDimensionParams>;
+export type RotationQuaternionValueObject = {
+	x: number;
+	y: number;
+	z: number;
+	w: number;
+};
+export type RotationQuaternionValueTuple = [x: number, y: number, z: number, w: number];
+export type RotationQuaternionValue = Simplify<
+	RotationQuaternionValueObject | RotationQuaternionValueTuple
+>;
+import type { RotationInputPluginQuaternionParams as RotationQuaternionOptionsInternal } from '@0b5vr/tweakpane-plugin-rotation/dist/types/RotationInputPluginQuaternionParams';
+declare const __propDef: {
+	props: Omit<
+		Omit<
+			{
+				/**
+				 * The binding's target object with values to manipulate.
+				 * @bindable
+				 */
+				object: import('@tweakpane/core').Bindable & {
+					[x: string]: RotationQuaternionValue;
+				};
+				/** The key for the value in the target `object` that the control should manipulate. */
+				key: string | number;
+				/**
+				 * Prevent interactivity and gray out the control.
+				 * @default `false`
+				 */
+				disabled?: boolean | undefined;
+				/**
+				 * 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?: RotationQuaternionOptionsInternal | 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 is primarily for internal use, when implementing convenience components wrapping
+				 * Binding's functionality.
+				 * @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 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;
+			},
+			'object' | 'key'
+		> & {
+			/**
+			 * The quaternion value to control.
+			 *
+			 * Tuple values are a convenience added by _Svelte Tweakpane UI_, and is not part of the
+			 * original TweakpaneRotationPlugin API.
+			 * @bindable
+			 */
+			value: RotationQuaternionValue;
+		} & {
+			/**
+			 * DOM class name of the button used to expand and collapse the input's picker.
+			 * @default `undefined`
+			 */
+			buttonClass?: string | undefined;
+			/**
+			 * Expand or collapse the input's picker.
+			 * @default `false`
+			 * @bindable
+			 */
+			expanded?: boolean | undefined;
+			/**
+			 * The style of value "picker" to use in the input.
+			 * @default `'popup'`
+			 */
+			picker?: 'inline' | 'popup' | undefined;
+			/**
+			 * Allow users to interactively expand / contract the picker.
+			 * @default `true`
+			 */
+			userExpandable?: boolean | undefined;
+		},
+		'options' | 'ref' | 'plugin' | 'buttonClass'
+	> & {
+		/**
+		 * The quaternion value to control.
+		 *
+		 * Tuple values are a convenience added by _Svelte Tweakpane UI_, and is not part of the
+		 * original TweakpaneRotationPlugin API.
+		 * @bindable
+		 * */
+		value: RotationQuaternionValue;
+		/**
+		 * Input parameters specific to the X dimension.
+		 *
+		 * Renamed from `x` in TweakpaneRotationPlugin API to clarify that it is an object of
+		 * options, not a value.
+		 * @default `undefined`
+		 * */
+		optionsX?:
+			| {
+					format?: import('@tweakpane/core').Formatter<number> | undefined;
+					keyScale?: number | undefined;
+					max?: number | undefined;
+					min?: number | undefined;
+					pointerScale?: number | undefined;
+					step?: number | undefined;
+			  }
+			| undefined;
+		/**
+		 * Input parameters specific to the Y dimension.
+		 *
+		 * Renamed from `y` in TweakpaneRotationPlugin API to clarify that it is an object of
+		 * options, not a value.
+		 * @default `undefined`
+		 * */
+		optionsY?:
+			| {
+					format?: import('@tweakpane/core').Formatter<number> | undefined;
+					keyScale?: number | undefined;
+					max?: number | undefined;
+					min?: number | undefined;
+					pointerScale?: number | undefined;
+					step?: number | undefined;
+			  }
+			| undefined;
+		/**
+		 * Input parameters specific to the Z dimension.
+		 *
+		 * Renamed from `z` in TweakpaneRotationPlugin API to clarify that it is an object of
+		 * options, not a value.
+		 * @default `undefined`
+		 * */
+		optionsZ?:
+			| {
+					format?: import('@tweakpane/core').Formatter<number> | undefined;
+					keyScale?: number | undefined;
+					max?: number | undefined;
+					min?: number | undefined;
+					pointerScale?: number | undefined;
+					step?: number | undefined;
+			  }
+			| undefined;
+		/**
+		 * Input parameters specific to the W dimension.
+		 *
+		 * Renamed from `w` in TweakpaneRotationPlugin API to clarify that it is an object of
+		 * options, not a value.
+		 * @default `undefined`
+		 * */
+		optionsW?:
+			| {
+					format?: import('@tweakpane/core').Formatter<number> | undefined;
+					keyScale?: number | undefined;
+					max?: number | undefined;
+					min?: number | undefined;
+					pointerScale?: number | undefined;
+					step?: number | undefined;
+			  }
+			| undefined;
+	};
+	events: {
+		[evt: string]: CustomEvent<any>;
+	};
+	slots: {};
+};
+export type RotationQuaternionProps = typeof __propDef.props;
+export type RotationQuaternionEvents = typeof __propDef.events;
+export type RotationQuaternionSlots = typeof __propDef.slots;
+/**
+ * Integrates the [quaternion
+ * rotation](https://github.com/0b5vr/tweakpane-plugin-rotation/blob/dev/src/RotationInputPluginQuaternion.ts)
+ * control from [0b5vr's](https://0b5vr.com)
+ * [tweakpane-plugin-rotation](https://github.com/0b5vr/tweakpane-plugin-rotation).
+ *
+ * _Svelte Tweakpane UI_ extends the original API to support tuple values in addition to object values.
+ * (Useful when working with frameworks like [three.js](https://threejs.org) /
+ * [threlte](https://threlte.xyz).)
+ *
+ * A utility function `Utils.quaternionToCssTransform()` is also provided to easily convert a euler
+ * rotation value object or tuple into a CSS transform string.
+ *
+ * See also <RotationEuler> if you're not into the whole `w` thing.
+ *
+ * Usage outside of a `<Pane>` component will implicitly wrap the profiler in `<Pane
+ * position='inline'>`.
+ *
+ *
+ *
+ *
+ *
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ * import {
+ *   Button,
+ *   RotationQuaternion,
+ *   type RotationQuaternionValue,
+ *   Utils
+ * } from 'svelte-tweakpane-ui';
+ *
+ * // Value could also be an object
+ * // e.g. {x: 0, y: 0, z: 0, w: 0}
+ * let value: RotationQuaternionValue = [0, 0, 0, 0];
+ *
+ * $: transform = Utils.quaternionToCssTransform(value);
+ * $: valueRows = Array.isArray(value)
+ *   ? value.map((v) => `${v >= 0 ? '+' : ''}${v.toFixed(6)}`).join('\n')
+ *   : '';
+ * </script>
+ *
+ * <RotationQuaternion
+ * bind:value
+ * expanded={true}
+ * label="CSS Rotation"
+ * picker={'inline'}
+ * />
+ * <Button on:click={() => (value = [0, 0, 0, 0])} title="Reset" />
+ *
+ * <div class="billboard" style:transform>
+ * <pre>{valueRows}</pre>
+ * </div>
+ *
+ * <style>
+ * div.billboard {
+ *   display: flex;
+ *   align-items: center;
+ *   justify-content: center;
+ *   aspect-ratio: 1;
+ *   width: 100%;
+ *   background: linear-gradient(45deg, magenta, orange);
+ * }
+ * </style>
+ * ```
+ *
+ * @sourceLink
+ * [RotationQuaternion.svelte](https://github.com/kitschpatrol/svelte-tweakpane-ui/blob/main/src/lib/control/RotationQuaternion.svelte)
+ */
+export default class RotationQuaternion extends SvelteComponent<
+	RotationQuaternionProps,
+	RotationQuaternionEvents,
+	RotationQuaternionSlots
+> {}
+export {};

package/dist/control/Slider.svelte

@@ -0,0 +1,6 @@
+<script>
+	import GenericSlider from '../internal/GenericSlider.svelte';
+	export let value;
+</script>
+
+<GenericSlider bind:value {...$$restProps} />

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

@@ -0,0 +1,165 @@
+import { SvelteComponent } from 'svelte';
+declare const __propDef: {
+	props: Omit<
+		Omit<
+			{
+				/**
+				 * The binding's target object with values to manipulate.
+				 * @bindable
+				 */
+				object: import('@tweakpane/core').Bindable & {
+					[x: string]: number;
+				};
+				/** The key for the value in the target `object` that the control should manipulate. */
+				key: string | number;
+				/**
+				 * Prevent interactivity and gray out the control.
+				 * @default `false`
+				 */
+				disabled?: boolean | undefined;
+				/**
+				 * 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').NumberInputParams | 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 is primarily for internal use, when implementing convenience components wrapping
+				 * Binding's functionality.
+				 * @bindable
+				 * @readonly
+				 */
+				ref?: import('tweakpane').SliderInputBindingApi | undefined;
+				/**
+				 * Imported Tweakpane `TpPluginBundle` (aliased as `Plugin`) module to automatically register in
+				 * the binding's containing `<Pane>`.
+				 *
+				 * 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;
+			},
+			'object' | 'key'
+		> & {
+			/**
+			 * A `number` value to control.
+			 * @bindable .
+			 */
+			value: number;
+		} & {
+			/**
+			 * Minimum value.
+			 *
+			 * Specifying both a `min` and a `max` prop turns the control into a slider.
+			 * @default `undefined`
+			 */
+			min?: number | undefined;
+			/**
+			 * Maximum value.
+			 *
+			 * Specifying both a `min` and a `max` prop turns the control into a slider.
+			 * @default `undefined`
+			 */
+			max?: number | undefined;
+			/**
+			 * A function to customize the point value's formatting (e.g. rounding, etc.).
+			 * @default `undefined`  \
+			 * Normal `.toString()` formatting.
+			 */
+			format?: ((value: number) => string) | undefined;
+			/**
+			 * The unit scale for key-based input for all dimensions (e.g. the up and down arrow keys).
+			 * @default `1`  \
+			 * Or `stepValue` if defined.
+			 */
+			keyScale?: number | undefined;
+			/**
+			 * The unit scale for pointer-based input for all dimensions.
+			 * @default `undefined`  \
+			 * [Dynamic based on magnitude of
+			 * `value`](https://github.com/cocopon/tweakpane/blob/66dfbea04bfe9b7f031673c955ceda1f92356e75/packages/core/src/common/number/util.ts#L54).
+			 */
+			pointerScale?: number | undefined;
+			/**
+			 * The minimum step interval.
+			 * @default `undefined`  \
+			 * No step constraint.
+			 */
+			step?: number | undefined;
+		},
+		'options' | 'ref' | 'plugin'
+	> & {
+		/**
+		 * A `number` value to control.
+		 * @bindable.
+		 * */
+		value: number;
+	};
+	events: {
+		[evt: string]: CustomEvent<any>;
+	};
+	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.
+ *
+ * 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.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ * import { Slider } from 'svelte-tweakpane-ui';
+ *
+ * let value = 0;
+ * </script>
+ *
+ * <Slider
+ * bind:value
+ * min={-1}
+ * max={1}
+ * format={(v) => v.toFixed(2)}
+ * label="Let it Slide"
+ * />
+ * <pre>Value: {value}</pre>
+ * ```
+ *
+ * @sourceLink
+ * [Slider.svelte](https://github.com/kitschpatrol/svelte-tweakpane-ui/blob/main/src/lib/control/Slider.svelte)
+ */
+export default class Slider extends SvelteComponent<SliderProps, SliderEvents, SliderSlots> {}
+export {};

package/dist/control/Text.svelte

@@ -0,0 +1,25 @@
+<script>
+	import GenericInput from '../internal/GenericInput.svelte';
+	import { onDestroy } from 'svelte';
+	export let value;
+	export let live = true;
+	let ref;
+	onDestroy(() => {
+		updateListeners(live ?? true, true);
+	});
+	function onInput(event) {
+		if (event.target) {
+			value = event.target.value;
+		}
+	}
+	function updateListeners(live2, destroy = false) {
+		let input = ref?.controller.valueController.view.element.getElementsByTagName('input')[0];
+		if (input) {
+			input.removeEventListener('input', onInput);
+			!destroy && live2 && input.addEventListener('input', onInput);
+		}
+	}
+	$: ref && live !== void 0 && updateListeners(live);
+</script>
+
+<GenericInput bind:value bind:ref {...$$restProps} />

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

@@ -0,0 +1,129 @@
+import { SvelteComponent } from 'svelte';
+import { type GenericInputRef } from '../internal/GenericInput.svelte';
+declare const __propDef: {
+	props: Omit<
+		Omit<
+			{
+				/**
+				 * The binding's target object with values to manipulate.
+				 * @bindable
+				 */
+				object: import('@tweakpane/core').Bindable & {
+					[x: string]: string;
+				};
+				/** The key for the value in the target `object` that the control should manipulate. */
+				key: string | number;
+				/**
+				 * Prevent interactivity and gray out the control.
+				 * @default `false`
+				 */
+				disabled?: boolean | undefined;
+				/**
+				 * 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 is primarily for internal use, when implementing convenience components wrapping
+				 * Binding's functionality.
+				 * @bindable
+				 * @readonly
+				 */
+				ref?: GenericInputRef | undefined;
+				/**
+				 * Imported Tweakpane `TpPluginBundle` (aliased as `Plugin`) module to automatically register in
+				 * the binding's containing `<Pane>`.
+				 *
+				 * 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;
+			},
+			'object' | 'key'
+		> & {
+			/**
+			 * A `string` value to control.
+			 * @bindable
+			 */
+			value: string;
+		},
+		'options' | 'ref' | 'plugin'
+	> & {
+		/**
+		 * A `string` value to control.
+		 * @bindable
+		 * */
+		value: string;
+		/**
+		 * Whether to provide live updates to the bound `value` on every keystroke.
+		 *
+		 * To match expectations around reactive components, the default here diverges from the
+		 * vanilla JS Tweakpane behavior, which only updates on blur.
+		 * @default `true`
+		 * */
+		live?: boolean | undefined;
+	};
+	events: {
+		[evt: string]: CustomEvent<any>;
+	};
+	slots: {};
+};
+export type TextProps = typeof __propDef.props;
+export type TextEvents = typeof __propDef.events;
+export type TextSlots = typeof __propDef.slots;
+/**
+ * A text field, in the spirit of the HTML `<input type="text">` element.
+ *
+ * Wraps Tweakpane's [string binding](https://tweakpane.github.io/docs/input-bindings/#string).
+ *
+ * Extends the vanilla JS Tweakpane API to update the bound value on every keystroke. (If you prefer
+ * Tweakpane's default behavior of only updating on blur, set `live={false}`.)
+ *
+ * See `<TextArea>` for a multi-line input variation.
+ *
+ * Usage outside of a `<Pane>` component will implicitly wrap the text field in `<Pane
+ * position='inline'>`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ * import { Text } from 'svelte-tweakpane-ui';
+ *
+ * let text = 'Cosmic Manifold';
+ * </script>
+ *
+ * <Text bind:value={text} label="The Message" />
+ * <pre>Message: {text}</pre>
+ * ```
+ *
+ * @sourceLink
+ * [Text.svelte](https://github.com/kitschpatrol/svelte-tweakpane-ui/blob/main/src/lib/control/Text.svelte)
+ */
+export default class Text extends SvelteComponent<TextProps, TextEvents, TextSlots> {}
+export {};

package/dist/control/Textarea.svelte

@@ -0,0 +1,47 @@
+<script>
+	import * as pluginModule from '@kitschpatrol/tweakpane-textarea-plugin';
+	import GenericInput from '../internal/GenericInput.svelte';
+	import { BROWSER } from 'esm-env';
+	import { onDestroy } from 'svelte';
+	export let value;
+	export let live = true;
+	export let rows = void 0;
+	export let placeholder = void 0;
+	let _value = value;
+	let ref;
+	let options;
+	onDestroy(() => {
+		updateListeners(live ?? true, true);
+	});
+	function onBlur(event) {
+		console.log('onblur');
+		value = event.target.value;
+	}
+	function onInput(event) {
+		console.log('input');
+		value = event.target.value;
+	}
+	function updateListeners(live2, destroy = false) {
+		var input = ref?.controller.valueController.view.element.getElementsByTagName('textarea')[0];
+		if (input) {
+			input.removeEventListener('blur', onBlur);
+			input.removeEventListener('input', onInput);
+			!destroy && live2 && input.addEventListener('input', onInput);
+			!destroy && !live2 && input.addEventListener('blur', onBlur);
+		}
+	}
+	$: _value = value;
+	$: ref && live !== void 0 && updateListeners(live);
+	$: options = {
+		placeholder,
+		rows,
+		view: 'textarea'
+	};
+</script>
+
+<GenericInput value={_value} bind:ref {options} plugin={pluginModule} {...$$restProps} />
+{#if !BROWSER}
+	<!-- TODO magic numbers -->
+	<div style:background="red" style:height={`calc(${16 * (rows ?? 3)}px - 14px)`} />
+	<!-- <ClsPad keysAdd={fillWith('containerUnitSize', 1)} theme={$$props.theme} /> -->
+{/if}