svelte-tweakpane-ui 1.0.0

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

@@ -0,0 +1,196 @@
+import { SvelteComponent } from 'svelte';
+import type { Simplify } from '../utils';
+export type IntervalSliderValueTuple = [min: number, max: number];
+export type IntervalSliderValueObject = {
+	min: number;
+	max: number;
+};
+export type IntervalSliderValue = Simplify<IntervalSliderValueObject | IntervalSliderValueTuple>;
+declare const __propDef: {
+	props: Omit<
+		Omit<
+			{
+				/**
+				 * The binding's target object with values to manipulate.
+				 * @bindable
+				 */
+				object: import('@tweakpane/core').Bindable & {
+					[x: string]: IntervalSliderValue;
+				};
+				/** 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'
+		> & {
+			/**
+			 * Interval value to control.
+			 *
+			 * Tuples are a convenience addition to the vanilla JS Tweakpane API.
+			 * @bindable
+			 */
+			value: IntervalSliderValue;
+		} & {
+			/**
+			 * 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'
+	> & {
+		/**
+		 * Interval value to control.
+		 *
+		 * Tuples are a convenience addition to the vanilla JS Tweakpane API.
+		 * @bindable
+		 */
+		value: IntervalSliderValue;
+		/**
+		 * Midpoint of the interval range value.
+		 * @bindable
+		 * */
+		meanValue?: number | undefined;
+	};
+	events: {
+		[evt: string]: CustomEvent<any>;
+	};
+	slots: {};
+};
+export type IntervalSliderProps = typeof __propDef.props;
+export type IntervalSliderEvents = typeof __propDef.events;
+export type IntervalSliderSlots = typeof __propDef.slots;
+/**
+ * A twin-handled slider control for specifying range values.
+ *
+ * Integrates the [Interval](https://github.com/tweakpane/plugin-essentials#interval) control from
+ * Tweakpane-creator [Hiroki Kokubun's](https://cocopon.me)  [Essentials
+ * plugin](https://github.com/tweakpane/plugin-essentials).
+ *
+ * _Svelte Tweakpane UI_ extends the original implementation to by supporting tuple values in addition
+ * to object values. It also exposes a `meanValue` prop for reading or setting the midpoint of the
+ * interval range value.
+ *
+ * Usage outside of a `<Pane>` component will implicitly wrap the interval slider in `<Pane
+ * position='inline'>`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ * import { IntervalSlider } from 'svelte-tweakpane-ui';
+ *
+ * // Could specify convenience type IntervalSliderValueTuple here, or
+ * // use the object {start: number, end: number} instead of a tuple
+ * let value: [number, number] = [25, 75];
+ * </script>
+ *
+ * <IntervalSlider
+ * bind:value
+ * min={0}
+ * max={100}
+ * format={(v) => `${v.toFixed(0)}%`}
+ * />
+ * <div class="demo" style:--e="{value[1]}%" style:--s="{value[0]}%" />
+ *
+ * <style>
+ * div.demo {
+ *   aspect-ratio: 1;
+ *   width: 100%;
+ *   background: linear-gradient(45deg, magenta var(--s), orange var(--e));
+ * }
+ * </style>
+ * ```
+ *
+ * @sourceLink
+ * [IntervalSlider.svelte](https://github.com/kitschpatrol/svelte-tweakpane-ui/blob/main/src/lib/control/IntervalSlider.svelte)
+ */
+export default class IntervalSlider extends SvelteComponent<
+	IntervalSliderProps,
+	IntervalSliderEvents,
+	IntervalSliderSlots
+> {}
+export {};

package/dist/control/List.svelte

@@ -0,0 +1,69 @@
+<script context="module"></script>
+
+<script generics="T extends any">
+	import Blade from '../core/Blade.svelte';
+	import ClsPad from '../internal/ClsPad.svelte';
+	import { BROWSER } from 'esm-env';
+	export let value;
+	export let options;
+	export let label = void 0;
+	let listBlade;
+	let bladeOptions;
+	function addEvent() {
+		listBlade.on('change', (ev) => {
+			value = ev.value;
+		});
+	}
+	function getInitialValue() {
+		if (value === void 0) {
+			const internalOptions = getInternalOptions(options);
+			if (Array.isArray(internalOptions)) {
+				value = internalOptions[0].value;
+				return value;
+			} else {
+				value = internalOptions[Object.keys(internalOptions)[0]];
+				return value;
+			}
+		} else {
+			return value;
+		}
+	}
+	function isArrayStyleListOptions(obj) {
+		return (
+			Array.isArray(obj) &&
+			obj.every(
+				(item) => typeof item === 'object' && item !== null && 'text' in item && 'value' in item
+			)
+		);
+	}
+	function isObjectStyleListOptions(obj) {
+		return typeof obj === 'object' && obj !== null && !Array.isArray(obj);
+	}
+	function getInternalOptions(options2) {
+		if (isArrayStyleListOptions(options2)) {
+			return options2;
+		} else if (isObjectStyleListOptions(options2)) {
+			return options2;
+		} else {
+			return options2.map((value2) => {
+				return { value: value2, text: JSON.stringify(value2) };
+			});
+		}
+	}
+	function setValue() {
+		listBlade.value = value;
+	}
+	$: bladeOptions = {
+		value: getInitialValue(),
+		label,
+		options: getInternalOptions(options),
+		view: 'list'
+	};
+	$: listBlade && addEvent();
+	$: value, listBlade && setValue();
+</script>
+
+<Blade bind:ref={listBlade} options={bladeOptions} {...$$restProps} />
+{#if !BROWSER}
+	<ClsPad keysAdd={['containerUnitSize']} theme={$$props.theme} />
+{/if}

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

@@ -0,0 +1,122 @@
+import { SvelteComponent } from 'svelte';
+import type { Simplify } from '../utils';
+export type ListOptionsArray<T> = T[];
+export type ListOptionsObjectArray<T> = {
+	value: T;
+	text: string;
+}[];
+export type ListOptionsRecord<T> = {
+	[text: string]: T;
+};
+export type ListOptions<T> = Simplify<
+	ListOptionsArray<T> | ListOptionsObjectArray<T> | ListOptionsRecord<T>
+>;
+import type { ListBladeApi, ListBladeParams } from 'tweakpane';
+declare class __sveltets_Render<T extends any> {
+	props(): Omit<
+		{
+			/**
+			 * A collection of options to select from.
+			 *
+			 * The arbitrary array list type is a convenience addition to to the vanilla JS Tweakpane
+			 * API.
+			 */
+			options: ListBladeParams<T>;
+			/**
+			 * Prevent interactivity and gray out the control.
+			 * @default `false`
+			 */
+			disabled?: boolean | 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
+			 * [`BladeApi`](https://tweakpane.github.io/docs/api/classes/BladeApi.html) for this blade.
+			 *
+			 * This is primarily for internal use, when implementing convenience components wrapping Blade's
+			 * functionality.
+			 * @bindable
+			 * @readonly
+			 */
+			ref?: ListBladeApi<T> | undefined;
+			/**
+			 * Imported Tweakpane `TpPluginBundle` (Aliased as `Plugin`) module to register before creating
+			 * the blade.
+			 *
+			 * This is primarily for internal use, when implementing convenience components wrapping Blade's
+			 * functionality in combination with a Tweakpane plugin.
+			 * @default `undefined`
+			 */
+			plugin?: import('tweakpane').TpPluginBundle | undefined;
+		},
+		'options' | 'ref' | 'plugin'
+	> & {
+		/**
+		 * Value of the selected `options` item.
+		 * @bindable
+		 * */
+		value: T;
+		/**
+		 * Text displayed next to list.
+		 * @default `undefined`
+		 * */
+		label?: string | undefined;
+		/**
+		 * A collection of options to select from.
+		 *
+		 * The arbitrary array list type is a convenience addition to to the vanilla JS Tweakpane
+		 * API.
+		 * */
+		options: ListOptions<T>;
+	};
+	events(): {} & {
+		[evt: string]: CustomEvent<any>;
+	};
+	slots(): {};
+}
+export type ListProps<T extends any> = ReturnType<__sveltets_Render<T>['props']>;
+export type ListEvents<T extends any> = ReturnType<__sveltets_Render<T>['events']>;
+export type ListSlots<T extends any> = ReturnType<__sveltets_Render<T>['slots']>;
+/**
+ * An option list picker, similar to an HTML `<select>` element.
+ *
+ * Wraps Tweakpane's list blade. See Tweakpane's documentation for [list
+ * blades](https://tweakpane.github.io/docs/blades/#list).
+ *
+ * _Svelte Tweakpane UI_ extends Tweakpane's underlying implementation to allow for arbitrary arrays of
+ * values to be used as options. See the `ListOptions` type for details on how to provide specific
+ * labels to options.
+ *
+ * Tweakpane's `addBlade` list variations is used instead of the `addBinding` method to allow for
+ * additional value types. The `value` remains bindable via Svelte's reactivity.
+ *
+ * Usage outside of a `<Pane>` component will implicitly wrap the color picker in `<Pane
+ * position='inline'>`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ * import { List, type ListOptions } from 'svelte-tweakpane-ui';
+ *
+ * const options: ListOptions<number> = { b: 2, a: 1, c: 3 };
+ * let selection: number = 1;
+ * </script>
+ *
+ * <List bind:value={selection} label="Alphanumerics" {options} />
+ * <pre>Selected Option: {selection}</pre>
+ * ```
+ *
+ * @sourceLink
+ * [List.svelte](https://github.com/kitschpatrol/svelte-tweakpane-ui/blob/main/src/lib/control/List.svelte)
+ */
+export default class List<T extends any> extends SvelteComponent<
+	ListProps<T>,
+	ListEvents<T>,
+	ListSlots<T>
+> {}
+export {};

package/dist/control/Point.svelte

@@ -0,0 +1,100 @@
+<script context="module"></script>
+
+<script generics="T extends PointValue2d | PointValue3d | PointValue4d">
+	import ClsPad from '../internal/ClsPad.svelte';
+	import GenericInputFolding from '../internal/GenericInputFolding.svelte';
+	import { removeKeys } from '../utils';
+	import { BROWSER } from 'esm-env';
+	export let value;
+	export let expanded = $$props.expanded ?? void 0;
+	let pointerScale = $$props['pointerScale'] ?? void 0;
+	let keyScale = $$props['keyScale'] ?? void 0;
+	let min = $$props['min'] ?? void 0;
+	let max = $$props['max'] ?? void 0;
+	let step = $$props['step'] ?? void 0;
+	let optionsX = $$props['optionsX'] ?? void 0;
+	let optionsY = $$props['optionsY'] ?? void 0;
+	let optionsZ = $$props['optionsZ'] ?? void 0;
+	let optionsW = $$props['optionsW'] ?? void 0;
+	let format = $$props['format'] ?? void 0;
+	let internalValue;
+	let options;
+	const buttonClass = 'tp-p2dv_b';
+	function updateInternalValue() {
+		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 };
+			}
+		} else {
+			internalValue = value;
+		}
+	}
+	function updateValue() {
+		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];
+			}
+		} else {
+			value = internalValue;
+		}
+	}
+	$: value, updateInternalValue();
+	$: internalValue, updateValue();
+	$: options = {
+		x: optionsX,
+		y: optionsY,
+		z: optionsZ,
+		w: optionsW,
+		min,
+		max,
+		format,
+		keyScale,
+		pointerScale,
+		step
+	};
+</script>
+
+<GenericInputFolding
+	bind:value={internalValue}
+	bind:expanded
+	{buttonClass}
+	{options}
+	{...removeKeys(
+		$$restProps,
+		...Object.keys(options),
+		'optionsX',
+		'optionsY',
+		'optionsZ',
+		'optionsW'
+	)}
+/>
+{#if !BROWSER && !('z' in internalValue)}
+	<!-- 2D points only -->
+	{#if expanded && $$props.picker === 'inline'}
+		{#if $$props.label !== undefined}
+			<ClsPad
+				keysAdd={['bladeValueWidth']}
+				keysSubtract={[`containerUnitSize`]}
+				theme={$$props.theme}
+			/>
+		{:else}
+			<!-- Without a label, the grid takes the full width of the control -->
+			<!-- TODO remove magic number -->
+			<div style="aspect-ratio: 1; width: calc(100% - 28px);" />
+		{/if}
+	{/if}
+{/if}