svelte-tweakpane-ui 1.0.0

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

@@ -0,0 +1,220 @@
+import { SvelteComponent } from 'svelte';
+import type { RingSeries } from '@tweakpane/plugin-camerakit/dist/types/util.js';
+type RingUnit = {
+	/**
+	 * The value for the unit.
+	 *
+	 * This sets the interval between each `value` labeled on the ring. For example a `value` of
+	 * `20` will show value labels 0, 20, 40... etc. spaced according to the `pixels` value.
+	 */
+	value: number;
+	/**
+	 * The number of pixels per unit.
+	 *
+	 * This is the amount of space in pixels between each `value` labeled on the ring. For
+	 * example, if `pixels` is 100 and `value` is 10, you will see a value label on the ring in
+	 * the form of 10...(100 pixels)...20...(100 pixels)...30... etc.
+	 */
+	pixels: number;
+	/**
+	 * The number of vertical tick marks between each `value` label on the ring.
+	 *
+	 * For example, if `pixels` is `100`, `value` is `10, and `ticks` is `10`, you will have a
+	 * vertical tick mark every 10 pixels, and a value label every 100 pixels.
+	 */
+	ticks: number;
+};
+export type { RingSeries, RingUnit };
+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;
+		/**
+		 * Style variations.
+		 * @default `0`
+		 * */
+		series?: RingSeries | undefined;
+		/**
+		 * Density and value mapping of the ring's tick marks.
+		 * @default `{ ticks: 5, pixels: 40, value: 10 }`
+		 * */
+		unit?: RingUnit | undefined;
+		/**
+		 * When `true`, expand the width of the ring control at the expense of the numerical input
+		 * field.
+		 * @default `false`
+		 * */
+		wide?: boolean | undefined;
+	};
+	events: {
+		[evt: string]: CustomEvent<any>;
+	};
+	slots: {};
+};
+export type RingProps = typeof __propDef.props;
+export type RingEvents = typeof __propDef.events;
+export type RingSlots = typeof __propDef.slots;
+/**
+ * A control evoking the focus ring on a proper camera lens.
+ *
+ * Similar in functionality to a `<Slider>`.
+ *
+ * Integrates the [Ring](https://github.com/tweakpane/plugin-camerakit/blob/main/src/plugin-ring.ts)
+ * control from Tweakpane-creator [Hiroki Kokubun's](https://cocopon.me) [Camerakit
+ * plugin](https://github.com/tweakpane/plugin-camerakit).
+ *
+ * Usage outside of a `<Pane>` component will implicitly wrap the ring in `<Pane position='inline'>`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ * import { Ring, type RingUnit } from 'svelte-tweakpane-ui';
+ *
+ * let unitConfig: RingUnit = {
+ *   value: 20,
+ *   pixels: 40,
+ *   ticks: 5
+ * };
+ *
+ * let angle = 45;
+ * </script>
+ *
+ * <Ring
+ * bind:value={angle}
+ * format={(v) => `${(Math.abs(v) % 360).toFixed(0)}°`}
+ * pointerScale={-2.5}
+ * unit={unitConfig}
+ * wide={true}
+ * />
+ *
+ * <div class="demo" style:--a="{angle}deg" />
+ *
+ * <style>
+ * div.demo {
+ *   aspect-ratio: 1;
+ *   width: 100%;
+ *   background: linear-gradient(var(--a), magenta, orange);
+ * }
+ * </style>
+ * ```
+ *
+ * @sourceLink
+ * [Ring.svelte](https://github.com/kitschpatrol/svelte-tweakpane-ui/blob/main/src/lib/control/Ring.svelte)
+ */
+export default class Ring extends SvelteComponent<RingProps, RingEvents, RingSlots> {}

package/dist/control/RotationEuler.svelte

@@ -0,0 +1,67 @@
+<script context="module"></script>
+
+<script>
+	import * as pluginModule from '@0b5vr/tweakpane-plugin-rotation';
+	import ClsPad from '../internal/ClsPad.svelte';
+	import GenericInputFolding from '../internal/GenericInputFolding.svelte';
+	import { BROWSER } from 'esm-env';
+	export let value;
+	export let order = void 0;
+	export let unit = void 0;
+	export let optionsX = void 0;
+	export let optionsY = void 0;
+	export let optionsZ = void 0;
+	export let expanded = void 0;
+	let options;
+	let internalValue;
+	const buttonClass = 'tp-rotationswatchv_b';
+	function updateInternalValue() {
+		if (Array.isArray(value)) {
+			const [x, y, z] = value;
+			internalValue = { x, y, z };
+		} else {
+			internalValue = value;
+		}
+	}
+	function updateValue() {
+		if (Array.isArray(value)) {
+			const { x, y, z } = internalValue;
+			value = [x, y, z];
+		} else {
+			value = internalValue;
+		}
+	}
+	$: value, updateInternalValue();
+	$: internalValue, updateValue();
+	$: options = {
+		x: optionsX,
+		y: optionsY,
+		z: optionsZ,
+		order,
+		rotationMode: 'euler',
+		unit,
+		view: 'rotation'
+	};
+</script>
+
+<GenericInputFolding
+	bind:value={internalValue}
+	bind:expanded
+	{buttonClass}
+	{options}
+	plugin={pluginModule}
+	{...$$restProps}
+/>
+{#if !BROWSER && 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}

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

@@ -0,0 +1,273 @@
+import { SvelteComponent } from 'svelte';
+import type { EulerOrder } from '@0b5vr/tweakpane-plugin-rotation/dist/types/EulerOrder.js';
+import type { EulerUnit } from '@0b5vr/tweakpane-plugin-rotation/dist/types/EulerUnit.js';
+import type { PointDimensionParams } from '@tweakpane/core';
+import type { Simplify } from '../utils';
+export type RotationEulerOptions = Simplify<PointDimensionParams>;
+export type RotationEulerOrder = EulerOrder;
+export type RotationEulerUnit = EulerUnit;
+export type RotationEulerValueObject = {
+	x: number;
+	y: number;
+	z: number;
+};
+export type RotationEulerValueTuple = [x: number, y: number, z: number];
+export type RotationEulerValue = Simplify<RotationEulerValueObject | RotationEulerValueTuple>;
+import type { RotationInputPluginEulerParams as RotationEulerOptionsInternal } from '@0b5vr/tweakpane-plugin-rotation/dist/types/RotationInputPluginEulerParams';
+declare const __propDef: {
+	props: Omit<
+		Omit<
+			{
+				/**
+				 * The binding's target object with values to manipulate.
+				 * @bindable
+				 */
+				object: import('@tweakpane/core').Bindable & {
+					[x: string]: RotationEulerValue;
+				};
+				/** 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?: RotationEulerOptionsInternal | 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 rotation value to control.
+			 *
+			 * Tuple values are a convenience added by _Svelte Tweakpane UI_, and are not part of the
+			 * original TweakpaneRotationPlugin API.
+			 *
+			 * See the `order` prop to specify the sequence in which rotations are applied.
+			 * @bindable
+			 */
+			value: RotationEulerValue;
+		} & {
+			/**
+			 * 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 rotation value to control.
+		 *
+		 * Tuple values are a convenience added by _Svelte Tweakpane UI_, and are not part of the
+		 * original TweakpaneRotationPlugin API.
+		 *
+		 * See the `order` prop to specify the sequence in which rotations are applied.
+		 * @bindable
+		 * */
+		value: RotationEulerValue;
+		/**
+		 * Input parameters specific to the X dimension.
+		 *
+		 * Renamed from `x` in the original 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 the original 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 the original 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;
+		/**
+		 * Order of in which rotations are applied.
+		 *
+		 * Note that this is extrinsic rotations (used by Blender, Maya, and Unity). Three.js uses
+		 * intrinsic rotations, so you have to reverse the order if you want to match Three.js'
+		 * behavior.
+		 * @default `'XYZ'`
+		 * */
+		order?: EulerOrder | undefined;
+		/**
+		 * Units of rotation.
+		 * @default `'rad'`
+		 */
+		unit?: EulerUnit | undefined;
+	};
+	events: {
+		[evt: string]: CustomEvent<any>;
+	};
+	slots: {};
+};
+export type RotationEulerProps = typeof __propDef.props;
+export type RotationEulerEvents = typeof __propDef.events;
+export type RotationEulerSlots = typeof __propDef.slots;
+/**
+ * Integrates the [euler
+ * rotation](https://github.com/0b5vr/tweakpane-plugin-rotation/blob/dev/src/RotationInputPluginEuler.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.eulerToCssTransform()` is also provided to easily convert a quaternion
+ * value object or tuple into a CSS transform string.
+ *
+ * See also <RotationQuaternion> if you're feeling gimbal locked.
+ *
+ * Usage outside of a `<Pane>` component will implicitly wrap the profiler in `<Pane
+ * position='inline'>`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ * import {
+ *   Button,
+ *   RotationEuler,
+ *   type RotationEulerValueObject,
+ *   Utils
+ * } from 'svelte-tweakpane-ui';
+ *
+ * // Value could also be a tuple
+ * // e.g. [0, 0, 0]
+ * let value: RotationEulerValueObject = { x: 0, y: 0, z: 0 };
+ *
+ * $: transform = Utils.eulerToCssTransform(value);
+ * $: valueRows = Object.values(value)
+ *   .map((v) => `${v >= 0 ? '+' : ''}${v.toFixed(6)}`)
+ *   .join('\n');
+ * </script>
+ *
+ * <RotationEuler
+ * bind:value
+ * expanded={true}
+ * label="CSS Rotation"
+ * picker={'inline'}
+ * />
+ * <Button on:click={() => (value = { x: 0, y: 0, z: 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
+ * [RotationEuler.svelte](https://github.com/kitschpatrol/svelte-tweakpane-ui/blob/main/src/lib/control/RotationEuler.svelte)
+ */
+export default class RotationEuler extends SvelteComponent<
+	RotationEulerProps,
+	RotationEulerEvents,
+	RotationEulerSlots
+> {}
+export {};

package/dist/control/RotationQuaternion.svelte

@@ -0,0 +1,65 @@
+<script context="module"></script>
+
+<script>
+	import * as pluginModule from '@0b5vr/tweakpane-plugin-rotation';
+	import ClsPad from '../internal/ClsPad.svelte';
+	import GenericInputFolding from '../internal/GenericInputFolding.svelte';
+	import { BROWSER } from 'esm-env';
+	export let value;
+	export let optionsX = void 0;
+	export let optionsY = void 0;
+	export let optionsZ = void 0;
+	export let optionsW = void 0;
+	export let expanded = void 0;
+	let options;
+	let internalValue;
+	const buttonClass = 'tp-rotationswatchv_b';
+	function updateInternalValue() {
+		if (Array.isArray(value)) {
+			const [x, y, z, w] = value;
+			internalValue = { x, y, z, w };
+		} else {
+			internalValue = value;
+		}
+	}
+	function updateValue() {
+		if (Array.isArray(value)) {
+			const { x, y, z, w } = internalValue;
+			value = [x, y, z, w];
+		} else {
+			value = internalValue;
+		}
+	}
+	$: value, updateInternalValue();
+	$: internalValue, updateValue();
+	$: options = {
+		x: optionsX,
+		y: optionsY,
+		z: optionsZ,
+		w: optionsW,
+		rotationMode: 'quaternion',
+		view: 'rotation'
+	};
+</script>
+
+<GenericInputFolding
+	bind:value={internalValue}
+	bind:expanded
+	{buttonClass}
+	{options}
+	plugin={pluginModule}
+	{...$$restProps}
+/>
+{#if !BROWSER && 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}