svelte-tweakpane-ui 1.0.0

package/dist/monitor/Monitor.svelte.d.ts

@@ -0,0 +1,526 @@
+import { SvelteComponent } from 'svelte';
+declare class __sveltets_Render<W extends number | string | boolean | unknown> {
+	props(): Omit<
+		Omit<
+			{
+				/**
+				 * The binding's target object with values to manipulate.
+				 * @bindable
+				 */
+				object: import('@tweakpane/core').Bindable & {
+					[x: string]: W;
+				};
+				/** 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?:
+					| (W extends string
+							? import('tweakpane').StringMonitorParams
+							: W extends boolean
+							  ? import('tweakpane').BooleanMonitorParams
+							  : W extends number
+							    ? import('tweakpane').NumberMonitorParams
+							    : import('@tweakpane/core').BaseMonitorParams)
+					| 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/GenericMonitor.svelte').GenericMonitorRef | 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 value to monitor.
+			 * @bindable
+			 */
+			value: W;
+		} & {
+			/**
+			 * Number of past states to retain.
+			 * @default `1`  \
+			 * Or `64` if value is `number` and `graph` is `true`.
+			 */
+			bufferSize?: number | undefined;
+			/**
+			 * Time between value samples in milliseconds.
+			 *
+			 * Useful when `graph` is true. Defaults to reactive value updates only (`interval={0}`).
+			 * @default `0`
+			 */
+			interval?: number | undefined;
+			/**
+			 * Number of visible rows of state history.
+			 *
+			 * If `bufferSize` is larger, then the value window will scroll once state history exceeds
+			 * row count.
+			 * @default `1`  \
+			 * Or `3` if value is `string` and `multiline` is `true`.
+			 */
+			rows?: number | undefined;
+		},
+		'options' | 'ref' | 'plugin'
+	> &
+		(W extends string
+			? 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').StringMonitorParams | 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/GenericMonitor.svelte').GenericMonitorRef | 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 value to monitor.
+						 * @bindable
+						 */
+						value: string;
+					} & {
+						/**
+						 * Number of past states to retain.
+						 * @default `1`  \
+						 * Or `64` if value is `number` and `graph` is `true`.
+						 */
+						bufferSize?: number | undefined;
+						/**
+						 * Time between value samples in milliseconds.
+						 *
+						 * Useful when `graph` is true. Defaults to reactive value updates only (`interval={0}`).
+						 * @default `0`
+						 */
+						interval?: number | undefined;
+						/**
+						 * Number of visible rows of state history.
+						 *
+						 * If `bufferSize` is larger, then the value window will scroll once state history exceeds
+						 * row count.
+						 * @default `1`  \
+						 * Or `3` if value is `string` and `multiline` is `true`.
+						 */
+						rows?: number | undefined;
+					},
+					'options' | 'ref' | 'plugin' | 'interval'
+			  > & {
+					/**
+					 * A value to monitor.
+					 * @bindable
+					 */
+					value: string;
+					/**
+					 * Display multiline strings.
+					 * @default `false`
+					 */
+					multiline?: boolean | undefined;
+			  }
+			: W extends boolean
+			  ? Omit<
+						Omit<
+							{
+								/**
+								 * The binding's target object with values to manipulate.
+								 * @bindable
+								 */
+								object: import('@tweakpane/core').Bindable & {
+									[x: string]: boolean;
+								};
+								/** 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').BooleanMonitorParams | 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/GenericMonitor.svelte').GenericMonitorRef | 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 value to monitor.
+							 * @bindable
+							 */
+							value: boolean;
+						} & {
+							/**
+							 * Number of past states to retain.
+							 * @default `1`  \
+							 * Or `64` if value is `number` and `graph` is `true`.
+							 */
+							bufferSize?: number | undefined;
+							/**
+							 * Time between value samples in milliseconds.
+							 *
+							 * Useful when `graph` is true. Defaults to reactive value updates only (`interval={0}`).
+							 * @default `0`
+							 */
+							interval?: number | undefined;
+							/**
+							 * Number of visible rows of state history.
+							 *
+							 * If `bufferSize` is larger, then the value window will scroll once state history exceeds
+							 * row count.
+							 * @default `1`  \
+							 * Or `3` if value is `string` and `multiline` is `true`.
+							 */
+							rows?: number | undefined;
+						},
+						'options' | 'ref' | 'plugin' | 'interval'
+			    > & {
+						/**
+						 * A value to monitor.
+						 * @bindable
+						 */
+						value: boolean;
+			    }
+			  : W extends number
+			    ? 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').NumberMonitorParams | 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/GenericMonitor.svelte').GenericMonitorRef | 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 value to monitor.
+								 * @bindable
+								 */
+								value: number;
+							} & {
+								/**
+								 * Number of past states to retain.
+								 * @default `1`  \
+								 * Or `64` if value is `number` and `graph` is `true`.
+								 */
+								bufferSize?: number | undefined;
+								/**
+								 * Time between value samples in milliseconds.
+								 *
+								 * Useful when `graph` is true. Defaults to reactive value updates only (`interval={0}`).
+								 * @default `0`
+								 */
+								interval?: number | undefined;
+								/**
+								 * Number of visible rows of state history.
+								 *
+								 * If `bufferSize` is larger, then the value window will scroll once state history exceeds
+								 * row count.
+								 * @default `1`  \
+								 * Or `3` if value is `string` and `multiline` is `true`.
+								 */
+								rows?: number | undefined;
+							},
+							'options' | 'ref' | 'plugin'
+			      > & {
+							/**
+							 * A value to monitor.
+							 * @bindable
+							 */
+							value: number;
+							/**
+							 * Minimum bound when `graph` is true.
+							 * @default `0`
+							 */
+							min?: number | undefined;
+							/**
+							 * Maximum bound when `graph` is true.
+							 * @default `100`
+							 */
+							max?: number | undefined;
+							/**
+							 * A function to customize the number's formatting (e.g. rounding, etc.).
+							 * @default `undefined`  \
+							 * Normal `.toString()` formatting.
+							 */
+							format?: ((value: number) => string) | undefined;
+							/**
+							 * Display a graph of the value's changes over time.
+							 * @default `false`
+							 */
+							graph?: boolean | undefined;
+			      }
+			    : {
+							/**
+							 * A value to monitor.
+							 * @bindable
+							 * */
+							value: string | number | boolean;
+			      });
+	events(): {} & {
+		[evt: string]: CustomEvent<any>;
+	};
+	slots(): {};
+}
+export type MonitorProps<W extends number | string | boolean | unknown> = ReturnType<
+	__sveltets_Render<W>['props']
+>;
+export type MonitorEvents<W extends number | string | boolean | unknown> = ReturnType<
+	__sveltets_Render<W>['events']
+>;
+export type MonitorSlots<W extends number | string | boolean | unknown> = ReturnType<
+	__sveltets_Render<W>['slots']
+>;
+/**
+ * Wraps the Tweakpane [monitor binding](https://tweakpane.github.io/docs/monitor-bindings/)
+ * functionality for `boolean`, `number`, and `string` values.
+ *
+ * Technically, any unbound value on a normal _Svelte Tweakpane UI_ component effectively acts as a
+ * monitor, but additional monitor-specific components are provided to expose additional view options
+ * (e.g. `rows`).
+ *
+ * `<Monitor>` is a dynamic component, and the availability of additional props will vary depending on
+ * the type of the defined `value`
+ *
+ * Note that `interval` is not exposed on `boolean` and `string` monitors because updates are driven by
+ * reactive changes in the `value`.
+ *
+ * However, `interval` _is_ exposed on `number` monitors Note to allow independent control over the
+ * reactive value's update rate and the graph's update rate.
+ *
+ * See also the `<Waveform>` component for a more advanced number visualization.
+ *
+ * Usage outside of a `<Pane>` component will implicitly wrap the monitor in a `<Pane
+ * position='inline'>` component.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ * import { Monitor } from 'svelte-tweakpane-ui';
+ *
+ * let booleanToMonitor = false;
+ * let stringToMonitor = 'Reticulating';
+ * let numberToMonitor = 85;
+ *
+ * setInterval(() => {
+ *   numberToMonitor = Math.random() * 100;
+ * }, 100);
+ *
+ * setInterval(() => {
+ *   booleanToMonitor = !booleanToMonitor;
+ *   stringToMonitor = stringToMonitor.split('').reverse().join('');
+ * }, 1000);
+ * </script>
+ *
+ * <Monitor value={numberToMonitor} graph={true} />
+ * <Monitor value={booleanToMonitor} label="Boolean Monitor" />
+ * <Monitor
+ * value={stringToMonitor}
+ * bufferSize={5}
+ * label="String Monitor"
+ * multiline={true}
+ * />
+ * ```
+ *
+ * @sourceLink
+ * [Monitor.svelte](https://github.com/kitschpatrol/svelte-tweakpane-ui/blob/main/src/lib/monitor/Monitor.svelte)
+ */
+export default class Monitor<W extends number | string | boolean | unknown> extends SvelteComponent<
+	MonitorProps<W>,
+	MonitorEvents<W>,
+	MonitorSlots<W>
+> {}
+export {};

package/dist/monitor/Profiler.svelte

@@ -0,0 +1,72 @@
+<script context="module"></script>
+
+<script>
+	import * as pluginModule from '@0b5vr/tweakpane-plugin-profiler';
+	import Blade from '../core/Blade.svelte';
+	import ClsPad from '../internal/ClsPad.svelte';
+	import { fillWith } from '../utils';
+	import { BROWSER } from 'esm-env';
+	import { createEventDispatcher, onDestroy } from 'svelte';
+	function _measure(name, fn) {
+		profilerBlade?.measure(name, fn);
+	}
+	async function _measureAsync(name, fn) {
+		profilerBlade?.measureAsync(name, fn);
+	}
+	export let label = void 0;
+	export let bufferSize = void 0;
+	export let calcMode = void 0;
+	export let deltaUnit = void 0;
+	export let fractionDigits = void 0;
+	export let measureHandler = void 0;
+	export const measure = _measure;
+	export const measureAsync = _measureAsync;
+	export let interval = void 0;
+	export let targetDelta = void 0;
+	let profilerBlade;
+	let options;
+	let observer = void 0;
+	const dispatch = createEventDispatcher();
+	onDestroy(() => {
+		stopObservingMeasuredValue();
+	});
+	function startObservingMeasuredValue() {
+		stopObservingMeasuredValue();
+		const targetNode = profilerBlade.controller.view.valueElement;
+		if (!targetNode || !targetNode.innerHTML) return;
+		observer = new MutationObserver((mutations) => {
+			for (const mutation of mutations) {
+				if (mutation.type === 'characterData' || mutation.type === 'childList') {
+					const delta = parseFloat(mutation.target.innerText);
+					!isNaN(delta) && dispatch('change', delta);
+				}
+			}
+		});
+		observer.observe(targetNode, { characterData: true, childList: true, subtree: true });
+	}
+	function stopObservingMeasuredValue() {
+		if (observer) {
+			observer.disconnect();
+			observer = void 0;
+		}
+	}
+	$: profilerBlade && startObservingMeasuredValue();
+	$: options = {
+		bufferSize,
+		calcMode,
+		deltaUnit,
+		fractionDigits,
+		interval,
+		label,
+		measureHandler,
+		targetDelta,
+		view: 'profiler'
+	};
+</script>
+
+<Blade bind:ref={profilerBlade} {options} plugin={pluginModule} {...$$restProps} />
+{#if !BROWSER}
+	<ClsPad keysAdd={fillWith('containerUnitSize', 2)} theme={$$props.theme} />
+	<!-- TODO Magic number for label... -->
+	<ClsPad extra={14.287} keysAdd={fillWith('containerVerticalPadding', 1)} theme={$$props.theme} />
+{/if}