svelte-tweakpane-ui 1.0.0

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

@@ -0,0 +1,374 @@
+import { SvelteComponent } from 'svelte';
+import type { Simplify } from '../utils';
+import type { Point2dInputParams, Point3dInputParams, Point4dInputParams } from 'tweakpane';
+export type PointValue2dObject = {
+	x: number;
+	y: number;
+};
+export type PointValue2dTuple = [x: number, y: number];
+export type PointValue2d = Simplify<PointValue2dObject | PointValue2dTuple>;
+export type PointValue3dObject = {
+	x: number;
+	y: number;
+	z: number;
+};
+export type PointValue3dTuple = [x: number, y: number, z: number];
+export type PointValue3d = Simplify<PointValue3dObject | PointValue3dTuple>;
+export type PointValue4dObject = {
+	x: number;
+	y: number;
+	z: number;
+	w: number;
+};
+export type PointValue4dTuple = [x: number, y: number, z: number, w: number];
+export type PointValue4d = Simplify<PointValue4dObject | PointValue4dTuple>;
+/**
+ * TODO docs
+ */
+export type PointOptions<
+	Dimensions extends '2' | '3' | '4',
+	Axis extends 'w' | 'x' | 'y' | 'z'
+> = Dimensions extends '4'
+	? Point4dInputParams[Axis]
+	: Dimensions extends '3'
+	  ? Point3dInputParams[Axis]
+	  : Dimensions extends '2'
+	    ? Point2dInputParams[Axis]
+	    : never;
+declare class __sveltets_Render<T extends PointValue2d | PointValue3d | PointValue4d> {
+	props(): Omit<
+		Omit<
+			{
+				/**
+				 * The binding's target object with values to manipulate.
+				 * @bindable
+				 */
+				object: import('@tweakpane/core').Bindable & {
+					[x: string]: T;
+				};
+				/** 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?:
+					| (T extends PointValue4d
+							? Point4dInputParams
+							: T extends PointValue3d
+							  ? Point3dInputParams
+							  : T extends PointValue2d
+							    ? Point2dInputParams
+							    : unknown)
+					| 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').TpPluginBundle | undefined;
+			},
+			'object' | 'key'
+		> & {
+			/**
+			 * A 2D, 3D, or 4D point object to control.
+			 *
+			 * Takes a tuple with a `number` value for each dimension, or an object with at least `x`
+			 * and `y` values, and optionally `z` and `w` values for additional dimensions.
+			 *
+			 * The type of this value will determine the availability of axis-specific option props.
+			 * @bindable
+			 */
+			value: T;
+		} & {
+			/**
+			 * 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'
+	> & {
+		/**
+		 * A 2D, 3D, or 4D point object to control.
+		 *
+		 * Takes a tuple with a `number` value for each dimension, or an object with at least `x`
+		 * and `y` values, and optionally `z` and `w` values for additional dimensions.
+		 *
+		 * The type of this value will determine the availability of axis-specific option props.
+		 * @bindable
+		 * */
+		value: T;
+		/**
+		 * The minimum value for all dimensions.
+		 * @default `undefined`  \
+		 * No minimum.
+		 * */
+		min?: number | undefined;
+		/**
+		 * The maximum value for all dimensions.
+		 * @default `undefined`  \
+		 * No maximum.
+		 * */
+		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 for all dimensions.
+		 * @default `undefined`  \
+		 * No step constraint.
+		 * */
+		step?: number | undefined;
+	} & (T extends PointValue2d | PointValue3d | PointValue4d
+			? {
+					/**
+					 * Input parameters specific to the X dimension.
+					 *
+					 * Renamed from `x` in Tweakpane API to clarify that it is an object of options, not
+					 * a value.
+					 * @default `undefined`
+					 * */
+					optionsX?:
+						| (T extends infer T_1
+								? T_1 extends T
+									? T_1 extends PointValue4d
+										? Point4dInputParams
+										: T_1 extends PointValue3d
+										  ? Point3dInputParams
+										  : T_1 extends PointValue2d
+										    ? Point2dInputParams
+										    : unknown
+									: never
+								: never)['x']
+						| undefined;
+					/**
+					 * Input parameters specific to the Y dimension.
+					 *
+					 * For 2D point values, the object also includes the `inverted` key, which inverts
+					 * the Y axis.
+					 *
+					 * Renamed from `y` in Tweakpane API to clarify that it is an object of options, not
+					 * a value.
+					 * @default `undefined`  \
+					 * `inverted` is `false`
+					 * */
+					optionsY?:
+						| (T extends infer T_2
+								? T_2 extends T
+									? T_2 extends PointValue4d
+										? Point4dInputParams
+										: T_2 extends PointValue3d
+										  ? Point3dInputParams
+										  : T_2 extends PointValue2d
+										    ? Point2dInputParams
+										    : unknown
+									: never
+								: never)['y']
+						| undefined;
+			  }
+			: unknown) &
+		(T extends PointValue3d | PointValue4d
+			? {
+					/**
+					 * Input parameters specific to the Z dimension.
+					 *
+					 * Renamed from `z` in Tweakpane API to clarify that it is an object of options,
+					 * not a value.
+					 * @default `undefined`
+					 * */
+					optionsZ?:
+						| (T extends infer T_3
+								? T_3 extends T
+									? T_3 extends PointValue4d
+										? Point4dInputParams
+										: T_3 extends PointValue3d
+										  ? Point3dInputParams
+										  : T_3 extends PointValue2d
+										    ? Point2dInputParams
+										    : unknown
+									: never
+								: never)['z']
+						| undefined;
+			  }
+			: unknown) &
+		(T extends PointValue4d
+			? {
+					/**
+					 * Input parameters specific to the W dimension.
+					 *
+					 * Renamed from `w` in Tweakpane API to clarify that it is an object of options,
+					 * not a value.
+					 * @default `undefined`
+					 * */
+					optionsW?:
+						| (T extends infer T_4
+								? T_4 extends T
+									? T_4 extends PointValue4d
+										? Point4dInputParams
+										: T_4 extends PointValue3d
+										  ? Point3dInputParams
+										  : T_4 extends PointValue2d
+										    ? Point2dInputParams
+										    : unknown
+									: never
+								: never)['w']
+						| undefined;
+			  }
+			: unknown);
+	events(): {} & {
+		[evt: string]: CustomEvent<any>;
+	};
+	slots(): {};
+}
+export type PointProps<T extends PointValue2d | PointValue3d | PointValue4d> = ReturnType<
+	__sveltets_Render<T>['props']
+>;
+export type PointEvents<T extends PointValue2d | PointValue3d | PointValue4d> = ReturnType<
+	__sveltets_Render<T>['events']
+>;
+export type PointSlots<T extends PointValue2d | PointValue3d | PointValue4d> = ReturnType<
+	__sveltets_Render<T>['slots']
+>;
+/**
+ * Wraps the Tweakpane [point bindings](https://tweakpane.github.io/docs/input-bindings/#point).
+ *
+ * Provides a nice cartesian picker for 2D points, and numeric input fields for 3D and 4D points. See
+ * the `<RotationEuler>` and `<RotationQuaternion>` components for higher-dimension graphical pickers.
+ *
+ * Extends the vanilla JS Tweakpane APIs to also support tuple values. (Useful when working with
+ * frameworks like [three.js](https://threejs.org) / [threlte](https://threlte.xyz).)
+ *
+ * `<Point>` is a dynamic component, and the availability of the `optionsZ` and `optionsW` props will
+ * change depending on the number of dimensions in the `value`.
+ *
+ * Usage outside of a `<Pane>` component will implicitly wrap the point picker in a `<Pane
+ * position='inline'>` component.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ * import {
+ *   Point,
+ *   type PointOptions,
+ *   type PointValue2d,
+ *   type PointValue3d,
+ *   type PointValue4d
+ * } from 'svelte-tweakpane-ui';
+ *
+ * let point2d: PointValue2d = { x: 0, y: 0 };
+ *
+ * // tuples are also fine
+ * let point3d: PointValue3d = [0, 0, 0];
+ *
+ * // dimension-specific option type needs to know the type of the point value
+ * let point3dXOptions: PointOptions<'3', 'x'> = { min: -100, max: 100 };
+ *
+ * let point4d: PointValue4d = { x: 0, y: 0, z: 0, w: 0 };
+ * </script>
+ *
+ * <Point
+ * bind:value={point2d}
+ * expanded={true}
+ * label="2D Point Picker"
+ * picker="inline"
+ * userExpandable={false}
+ * />
+ * <Point
+ * bind:value={point3d}
+ * label="3D Point Picker"
+ * optionsX={point3dXOptions}
+ * />
+ * <Point bind:value={point4d} min={0} max={100} label="4D Point Picker" />
+ *
+ * <pre>
+ * 2D Value:
+ * {JSON.stringify(point2d, null, 2)}
+ *
+ * 3D Value:
+ * {JSON.stringify(point3d, null, 2)}
+ *
+ * 4D Value:
+ * {JSON.stringify(point4d, null, 2)}
+ * </pre>
+ * ```
+ *
+ * @sourceLink
+ * [Point.svelte](https://github.com/kitschpatrol/svelte-tweakpane-ui/blob/main/src/lib/control/Point.svelte)
+ */
+export default class Point<
+	T extends PointValue2d | PointValue3d | PointValue4d
+> extends SvelteComponent<PointProps<T>, PointEvents<T>, PointSlots<T>> {}
+export {};

package/dist/control/RadioGrid.svelte

@@ -0,0 +1,42 @@
+<script generics="T extends number | string | boolean">
+	import * as pluginModule from '@tweakpane/plugin-essentials';
+	import ClsPad from '../internal/ClsPad.svelte';
+	import GenericInput from '../internal/GenericInput.svelte';
+	import { fillWith } from '../utils';
+	import { getGridDimensions } from '../utils.js';
+	import { BROWSER } from 'esm-env';
+	import { nanoid } from 'nanoid';
+	const defaultGroupName = nanoid();
+	export let groupName = void 0;
+	export let values;
+	export let value = values[0];
+	export let columns = void 0;
+	export let rows = void 0;
+	export let suffix = void 0;
+	export let prefix = void 0;
+	let gridDimensions;
+	let options;
+	function cells(x, y) {
+		const index = y * gridDimensions.columns + x;
+		if (index >= 0 && index < values.length) {
+			return {
+				value: values[index],
+				title: `${prefix ?? ''}${values[index]}${suffix ?? ''}`
+			};
+		}
+		return { value: values[0], title: '' };
+	}
+	$: gridDimensions = getGridDimensions(values.length, columns, rows);
+	$: options = {
+		cells,
+		groupName: groupName ?? defaultGroupName,
+		size: [gridDimensions.columns, gridDimensions.rows],
+		view: 'radiogrid'
+	};
+</script>
+
+<GenericInput bind:value {options} plugin={pluginModule} {...$$restProps} />
+{#if !BROWSER}
+	<ClsPad keysAdd={fillWith('containerUnitSize', gridDimensions.rows - 1)} theme={$$props.theme} />
+	<div style:height={`${2 * (gridDimensions.rows - 1)}px`} />
+{/if}

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

@@ -0,0 +1,231 @@
+import { SvelteComponent } from 'svelte';
+declare class __sveltets_Render<T extends number | string | boolean> {
+	props(): Omit<
+		Omit<
+			{
+				/**
+				 * The binding's target object with values to manipulate.
+				 * @bindable
+				 */
+				object: import('@tweakpane/core').Bindable & {
+					[x: string]: T;
+				};
+				/** 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 & {
+							cells: (
+								x: number,
+								y: number
+							) => {
+								value: T;
+								title: string;
+							};
+							groupName: string;
+							size: [number, number];
+							view: 'radiogrid';
+					  })
+					| 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').TpPluginBundle | undefined;
+			},
+			'object' | 'key'
+		> & {
+			/**
+			 * Value of selected radio button.
+			 *
+			 * Bind to this prop to receive updates when the user clicks a radio button.
+			 * @bindable
+			 * @default `undefined` If undefined, the first value in the `values` array is assigned.
+			 */
+			value: T;
+		},
+		'options' | 'ref' | 'plugin'
+	> & {
+		/**
+		 * Value of selected radio button.
+		 *
+		 * Bind to this prop to receive updates when the user clicks a radio button.
+		 * @bindable
+		 * @default `undefined` If undefined, the first value in the `values` array is assigned.
+		 *  */
+		value?: T | undefined;
+		/**
+		 * Number of columns to arrange the radio buttons into.
+		 * @default `undefined`
+		 * */
+		columns?: number | undefined;
+		/**
+		 * Name allowing multiple radio groups to share mutually exclusive selection state.
+		 *
+		 * Allows spanning exclusive selection state across multiple independent `<RadioGrid>`
+		 * components, but should remain `undefined` for most use cases to keep exclusivity scoped
+		 * to a single `<RadioGrid>`.
+		 * @default `undefined`  \
+		 * Uses a dynamically generated globally unique id internally.
+		 */
+		groupName?: string | undefined;
+		/**
+		 * Text to show in the radio button label before the value.
+		 * @default `undefined`
+		 * */
+		prefix?: string | undefined;
+		/**
+		 * Number of rows to arrange the radio buttons into.
+		 * @default `undefined`
+		 * */
+		rows?: number | undefined;
+		/**
+		 * Text to show in the radio button label after the value.
+		 * @default `undefined`
+		 * */
+		suffix?: string | undefined;
+		/**
+		 * Array of `number`, `string` or `boolean` values, each of which will become a button in
+		 * the radio grid.
+		 * */
+		values: T[];
+	};
+	events(): {} & {
+		[evt: string]: CustomEvent<any>;
+	};
+	slots(): {};
+}
+export type RadioGridProps<T extends number | string | boolean> = ReturnType<
+	__sveltets_Render<T>['props']
+>;
+export type RadioGridEvents<T extends number | string | boolean> = ReturnType<
+	__sveltets_Render<T>['events']
+>;
+export type RadioGridSlots<T extends number | string | boolean> = ReturnType<
+	__sveltets_Render<T>['slots']
+>;
+/**
+ * A grid of radio buttons.
+ *
+ * Integrates the [Radio Grid](https://github.com/tweakpane/plugin-essentials#radio-grid) control from
+ * Tweakpane-creator [Hiroki Kokubun's](https://cocopon.me)  [Essentials
+ * plugin](https://github.com/tweakpane/plugin-essentials).
+ *
+ * See `<ButtonGrid>` for a button-flavored variation.
+ *
+ * Unlike the vanilla Tweakpane API, _Svelte Tweakpane UI_ provides a unique `groupname` for each
+ * instance of RadioGrid by default for consistency with expectations around component isolation. You
+ * may still assign the `groupname` prop manually to create cross-component groups that share selection
+ * exclusivity.
+ *
+ * _Svelte Tweakpane UI_ also includes some additional logic to manage default grid dimensions:
+ *
+ *   - If no `rows` or `columns` props are provided, it will create a grid with the squarest possible aspect ratio for the given quantity of `values`.
+ *
+ *   - If a single `rows` or `columns` prop is provided, it lets the undefined axis grow / shrink as needed to accommodate the quantity of `values`.
+ *
+ *   - If both `rows` _and_ `columns` props area provided, then buttons may be clipped if `rows * columns < values.length`.
+ *
+ *
+ * Usage outside of a `<Pane>` component will implicitly wrap the radio grid in `<Pane
+ * position='inline'>`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ * import { RadioGrid } from 'svelte-tweakpane-ui';
+ *
+ * // Svelte transition works around CSS gradient
+ * // transition limitations
+ * import { fade } from 'svelte/transition';
+ *
+ * const radioValues = [
+ *   ['magenta', 'orange'],
+ *   ['yellow', 'red'],
+ *   ['violet', 'gold'],
+ *   ['red', 'rebeccapurple']
+ * ];
+ *
+ * let value = 1;
+ *
+ * $: [start, end] = radioValues[value - 1];
+ * </script>
+ *
+ * <RadioGrid bind:value prefix="Color Scheme " values={[1, 2, 3, 4]} />
+ *
+ * <div class="demo">
+ * {#key value}
+ *   <div class="swatch" style:--e={end} style:--s={start} transition:fade></div>
+ * {/key}
+ * </div>
+ *
+ * <style>
+ * div.demo {
+ *   position: relative;
+ *   aspect-ratio: 1;
+ *   width: 100%;
+ *   background: white;
+ * }
+ *
+ * div.swatch {
+ *   position: absolute;
+ *   width: 100%;
+ *   height: 100%;
+ *   background: linear-gradient(45deg, var(--s), var(--e));
+ * }
+ * </style>
+ * ```
+ *
+ * @sourceLink
+ * [RadioGrid.svelte](https://github.com/kitschpatrol/svelte-tweakpane-ui/blob/main/src/lib/control/RadioGrid.svelte)
+ */
+export default class RadioGrid<T extends number | string | boolean> extends SvelteComponent<
+	RadioGridProps<T>,
+	RadioGridEvents<T>,
+	RadioGridSlots<T>
+> {}
+export {};

package/dist/control/Ring.svelte

@@ -0,0 +1,19 @@
+<script context="module"></script>
+
+<script>
+	import * as pluginModule from '@tweakpane/plugin-camerakit';
+	import GenericSlider from '../internal/GenericSlider.svelte';
+	export let value;
+	export let series = void 0;
+	export let unit = void 0;
+	export let wide = void 0;
+	let options;
+	$: options = {
+		series,
+		unit,
+		view: 'cameraring',
+		wide
+	};
+</script>
+
+<GenericSlider bind:value {options} plugin={pluginModule} {...$$restProps} />