svelte-tweakpane-ui 1.0.0

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

@@ -0,0 +1,265 @@
+import { SvelteComponent } from 'svelte';
+import type { ProfilerBladeMeasureHandler } from '@0b5vr/tweakpane-plugin-profiler';
+import type { Simplify } from '../utils';
+export type ProfilerCalcMode = 'frame' | 'mean' | 'median';
+export type ProfilerChangeEvent = CustomEvent<number>;
+export type ProfilerMeasure = (name: string, fn: () => void) => void;
+export type ProfilerMeasureAsync = (name: string, fn: () => Promise<void>) => Promise<void>;
+export type ProfilerMeasureHandler = Simplify<ProfilerBladeMeasureHandler>;
+import type { ProfilerBladeApi as ProfilerRef } from '@0b5vr/tweakpane-plugin-profiler/dist/types/ProfilerBladeApi.js';
+import type { ProfilerBladePluginParams as ProfilerOptions } from '@0b5vr/tweakpane-plugin-profiler/dist/types/ProfilerBladePluginParams.js';
+declare const __propDef: {
+	props: {
+		/**
+		 * Function handle that wraps another function to measure its execution duration.
+		 *
+		 *  If you want to measure something other than execution duration, customize
+		 * `ProfilerBladeDefaultMeasureHandler`.
+		 *
+		 * @example `measure('Hard Work', () => { ... })`;
+		 * @bindable
+		 * @readonly
+		 * @default `undefined`
+		 */
+		measure?: ProfilerMeasure | undefined;
+		/**
+		 * Async variation of function handle that wraps another function to measure its execution
+		 * duration.
+		 *
+		 * @example `measureAsync('Hard Work', async () => { ... })`;
+		 * @bindable
+		 * @async
+		 * @readonly
+		 * @default `undefined`
+		 */
+		measureAsync?: ProfilerMeasureAsync | undefined;
+	} & Omit<
+		{
+			/**
+			 * Blade configuration exposing Tweakpane's internal
+			 * [`BladeParams`](https://tweakpane.github.io/docs/api/interfaces/BaseBladeParams.html).
+			 *
+			 */
+			options: ProfilerOptions;
+			/**
+			 * 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?: ProfilerRef | 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'
+	> & {
+			/**
+			 * Number of duration samples from which to calculate the delta value when `calcMode` is
+			 * `'mean'` or `'median'`.
+			 * @default `30`
+			 */
+			bufferSize?: number | undefined;
+			/**
+			 * How to calculate the delta value.
+			 *
+			 * `'frame'` takes only the latest sample into account, while `'mean'` and `'median'` are
+			 * calculated from the samples in the buffer.
+			 * @default `'mean'`
+			 */
+			calcMode?: ProfilerCalcMode | undefined;
+			/**
+			 * Label suffix for the delta values shown in the control.
+			 *
+			 * Possibly useful if you're using a custom `ProfilerBladeDefaultMeasureHandler` and are
+			 * measuring something other than time.
+			 * @default `'ms'`
+			 * */
+			deltaUnit?: string | undefined;
+			/**
+			 * Precision of the delta values shown in the control.
+			 * @default `2`
+			 */
+			fractionDigits?: number | undefined;
+			/**
+			 * Milliseconds between updates to the profiler visualization and delta label text.
+			 *
+			 * Note that this does not affect the internal sampling rate of the profiler itself, which
+			 * is determined by your calls to the bound `measure` function.
+			 * @default `500`
+			 */
+			interval?: number | undefined;
+			/**
+			 * Text displayed next to the profiler visualization.
+			 * @default `undefined`
+			 * */
+			label?: string | undefined;
+			/**
+			 * Function handle that wraps another function to measure its execution duration.
+			 *
+			 *  If you want to measure something other than execution duration, customize
+			 * `ProfilerBladeDefaultMeasureHandler`.
+			 *
+			 * @example `measure('Hard Work', () => { ... })`;
+			 *
+			 * @bindable
+			 * @readonly
+			 * @default `undefined`
+			 */
+			measure?: ProfilerMeasure | undefined;
+			/**
+			 * Async variation of function handle that wraps another function to measure its execution
+			 * duration.
+			 *
+			 * @example `measureAsync('Hard Work', async () => { ... })`;
+			 *
+			 * @bindable
+			 * @async
+			 * @readonly
+			 * @default `undefined`
+			 */
+			measureAsync?: ProfilerMeasureAsync | undefined;
+			/**
+			 * Function wrapping the `measure` function.
+			 *
+			 * The default is fine for most cases when you want to measure a temporal duration.
+			 * @default [`new
+			 * ProfilerBladeDefaultMeasureHandler()`](https://github.com/0b5vr/tweakpane-plugin-profiler/blob/dev/src/ProfilerBladeDefaultMeasureHandler.ts)
+			 */
+			measureHandler?:
+				| {
+						measureStart: () => () => number | Promise<number>;
+				  }
+				| undefined;
+			/**
+			 * Determines the horizontal scale and color mapping of the profiler visualization bars.
+			 * @default `16.67`  \
+			 * 60fps.
+			 */
+			targetDelta?: number | undefined;
+		};
+	slots: {};
+	events: {
+		/**
+		 * Fires when the overall delta value changes, passing the latest measurement.
+		 *
+		 * Note that the values described in the `ProfilerChangeEvent` type are available on the
+		 * `event.detail` parameter.
+		 * @event
+		 * */
+		change: ProfilerChangeEvent;
+	};
+};
+export type ProfilerProps = typeof __propDef.props;
+export type ProfilerEvents = typeof __propDef.events;
+export type ProfilerSlots = typeof __propDef.slots;
+/**
+ * Measure and visualize multiple quantities over time.
+ *
+ * Configured to measure a function's execution duration by default, but can be customized to measure
+ * anything.
+ *
+ * Integrates [0b5vr's](https://0b5vr.com)
+ * [tweakpane-plugin-profiler](https://github.com/0b5vr/tweakpane-plugin-profiler).
+ *
+ * See `<FpsGraph>` for a simpler alternative optimized for framerate visualization.
+ *
+ * Usage outside of a `<Pane>` component will implicitly wrap the profiler in `<Pane
+ * position='inline'>`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ * import { onMount } from 'svelte';
+ * import { Profiler, type ProfilerMeasure, Slider } from 'svelte-tweakpane-ui';
+ *
+ * // this is a readonly function handle assigned by Profiler component
+ * // first used in onMount since it is not bound until then
+ * let measure: ProfilerMeasure;
+ *
+ * let loopExponent = 1;
+ *
+ * // helper to test Math functions
+ * function hardWork(fn: (n: number) => number, exponent: number): void {
+ *   measure(fn.name, () => {
+ *     for (let sum = 0; sum < Number('1e' + exponent); sum++) {
+ *       fn(sum);
+ *     }
+ *   });
+ * }
+ *
+ * onMount(() => {
+ *   (function tick() {
+ *     // Nesting measurements creates a hierarchy
+ *     // in the Profile visualization
+ *     measure('Tick', () => {
+ *       measure('Trigonometry', () => {
+ *         hardWork(Math.sin, loopExponent);
+ *         hardWork(Math.cos, loopExponent);
+ *         hardWork(Math.tan, loopExponent);
+ *         hardWork(Math.atan, loopExponent);
+ *         hardWork(Math.acos, loopExponent);
+ *         hardWork(Math.acosh, loopExponent);
+ *       });
+ *       measure('Logarithms', () => {
+ *         hardWork(Math.log, loopExponent);
+ *         hardWork(Math.log10, loopExponent);
+ *         hardWork(Math.log1p, loopExponent);
+ *         hardWork(Math.log2, loopExponent);
+ *       });
+ *       measure('Rounding', () => {
+ *         hardWork(Math.round, loopExponent);
+ *         hardWork(Math.floor, loopExponent);
+ *         hardWork(Math.ceil, loopExponent);
+ *         hardWork(Math.fround, loopExponent);
+ *       });
+ *     });
+ *
+ *     requestAnimationFrame(tick);
+ *   })();
+ * });
+ * </script>
+ *
+ * <Profiler bind:measure label="Profiler" />
+ * <Slider
+ * bind:value={loopExponent}
+ * min={1}
+ * max={5}
+ * label="Loop Exponent (Careful)"
+ * step={1}
+ * />
+ * ```
+ *
+ * @sourceLink
+ * [Profiler.svelte](https://github.com/kitschpatrol/svelte-tweakpane-ui/blob/main/src/lib/monitor/Profiler.svelte)
+ */
+export default class Profiler extends SvelteComponent<
+	ProfilerProps,
+	ProfilerEvents,
+	ProfilerSlots
+> {
+	get measure(): ProfilerMeasure;
+	get measureAsync(): ProfilerMeasureAsync;
+}
+export {};

package/dist/monitor/WaveformMonitor.svelte

@@ -0,0 +1,26 @@
+<script context="module"></script>
+
+<script>
+	import ClsPad from '../internal/ClsPad.svelte';
+	import GenericMonitor from '../internal/GenericMonitor.svelte';
+	import { fillWith } from '../utils';
+	import { BROWSER } from 'esm-env';
+	import * as pluginModule from 'tweakpane-plugin-waveform';
+	export let value;
+	export let max = void 0;
+	export let min = void 0;
+	export let lineStyle = void 0;
+	let options;
+	$: options = {
+		min,
+		max,
+		lineStyle,
+		readonly: true,
+		view: 'waveform'
+	};
+</script>
+
+<GenericMonitor {value} {options} plugin={pluginModule} {...$$restProps} />
+{#if !BROWSER}
+	<ClsPad keysAdd={fillWith('containerUnitSize', 2)} theme={$$props.theme} />
+{/if}

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

@@ -0,0 +1,176 @@
+import { SvelteComponent } from 'svelte';
+export type WaveformMonitorValue = Uint8Array | Uint16Array | Uint32Array | number[];
+import type { WaveformStyles as WaveformMonitorLineStyle } from 'tweakpane-plugin-waveform/dist/types/view/waveform.js';
+declare const __propDef: {
+	props: Omit<
+		Omit<
+			{
+				/**
+				 * The binding's target object with values to manipulate.
+				 * @bindable
+				 */
+				object: import('@tweakpane/core').Bindable & {
+					[x: string]: WaveformMonitorValue;
+				};
+				/** 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').BaseMonitorParams & {
+							min?: number | undefined;
+							max?: number | undefined;
+							lineStyle?: WaveformMonitorLineStyle | undefined;
+					  })
+					| 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'
+		> & {
+			/**
+			 * Waveform values.
+			 * @bindable
+			 */
+			value: WaveformMonitorValue;
+		} & {
+			/**
+			 * 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 /**
+			 * Waveform values.
+			 * @bindable
+			 * */;
+		},
+		'options' | 'ref' | 'plugin'
+	> & {
+		/**
+		 * Waveform values.
+		 * @bindable
+		 * */
+		value: WaveformMonitorValue;
+		/**
+		 * Minimum graph bound.
+		 * @default `0`
+		 * */
+		min?: number | undefined;
+		/**
+		 * Maximum graph bound.
+		 * @default `100`
+		 * */
+		max?: number | undefined;
+		/**
+		 * Line style.
+		 * @default `'linear''`
+		 * */
+		lineStyle?: 'linear' | 'bezier' | undefined;
+	};
+	events: {
+		[evt: string]: CustomEvent<any>;
+	};
+	slots: {};
+};
+export type WaveformMonitorProps = typeof __propDef.props;
+export type WaveformMonitorEvents = typeof __propDef.events;
+export type WaveformMonitorSlots = typeof __propDef.slots;
+/**
+ * Visualize multiple numeric values as a waveform.
+ *
+ * Integrates [Simon Schödler's](https://shoedler.github.io)
+ * [tweakpane-plugin-waveform](https://github.com/shoedler/tweakpane-plugin-waveform).
+ *
+ * See `<Monitor>` component if you want to graph a single value's change over time.
+ *
+ * Usage outside of a `<Pane>` component will implicitly wrap the waveform monitor in `<Pane
+ * position='inline'>`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ * import { WaveformMonitor } from 'svelte-tweakpane-ui';
+ *
+ * let waveData = [5, 6, 7, 8, 9, 3, 9, 8, 7, 6, 5];
+ *
+ * setInterval(() => {
+ *   waveData = waveData.map((v) =>
+ *     Math.max(0, Math.min(10, v + (Math.random() * 2 - 1) * 0.5))
+ *   );
+ * }, 10);
+ * </script>
+ *
+ * <WaveformMonitor value={waveData} min={-1} max={11} lineStyle={'bezier'} />
+ * ```
+ *
+ * @sourceLink
+ * [WaveformMonitor.svelte](https://github.com/kitschpatrol/svelte-tweakpane-ui/blob/main/src/lib/monitor/WaveformMonitor.svelte)
+ */
+export default class WaveformMonitor extends SvelteComponent<
+	WaveformMonitorProps,
+	WaveformMonitorEvents,
+	WaveformMonitorSlots
+> {}
+export {};

package/dist/theme.d.ts

@@ -0,0 +1,91 @@
+import { type RgbColorObject, type RgbaColorObject } from '@tweakpane/core';
+import type { Simplify } from './utils';
+export type ThemeColorValue = Simplify<RgbColorObject | RgbaColorObject | string>;
+export type Theme = ThemeKeys & CustomThemeKeys;
+type ThemeKeys = {
+	baseBackgroundColor?: ThemeColorValue;
+	baseBorderRadius?: string;
+	baseFontFamily?: string;
+	baseShadowColor?: ThemeColorValue;
+	bladeBorderRadius?: string;
+	bladeHorizontalPadding?: string;
+	bladeValueWidth?: string;
+	buttonBackgroundColor?: ThemeColorValue;
+	buttonBackgroundColorActive?: ThemeColorValue;
+	buttonBackgroundColorFocus?: ThemeColorValue;
+	buttonBackgroundColorHover?: ThemeColorValue;
+	buttonForegroundColor?: ThemeColorValue;
+	containerBackgroundColor?: ThemeColorValue;
+	containerBackgroundColorActive?: ThemeColorValue;
+	containerBackgroundColorFocus?: ThemeColorValue;
+	containerBackgroundColorHover?: ThemeColorValue;
+	containerForegroundColor?: ThemeColorValue;
+	containerHorizontalPadding?: string;
+	containerUnitSize?: string;
+	containerUnitSpacing?: string;
+	containerVerticalPadding?: string;
+	grooveForegroundColor?: ThemeColorValue;
+	inputBackgroundColor?: ThemeColorValue;
+	inputBackgroundColorActive?: ThemeColorValue;
+	inputBackgroundColorFocus?: ThemeColorValue;
+	inputBackgroundColorHover?: ThemeColorValue;
+	inputForegroundColor?: ThemeColorValue;
+	labelForegroundColor?: ThemeColorValue;
+	monitorBackgroundColor?: ThemeColorValue;
+	monitorForegroundColor?: ThemeColorValue;
+	pluginImageDraggingColor?: ThemeColorValue;
+};
+type CustomThemeKeys = {
+	[key: string]: ThemeColorValue;
+};
+export declare const keys: Record<string, string>;
+export declare const presets: {
+	/** Dark blue theme. */
+	iceberg: Theme;
+	/** Extra dark theme. */
+	jetblack: Theme;
+	/** Standard Tweakpane light theme. */
+	light: Theme;
+	/** Light theme with CRT vibes. */
+	retro: Theme;
+	/** Standard Tweakpane dark theme. This is the default theme. */
+	standard: Theme;
+	/** Dark translucent theme. */
+	translucent: Theme;
+	/** Red theme. */
+	vivid: Theme;
+};
+/**
+ * Used during SSR to calculate metrics Returns CSS string.
+ */
+export declare function getValueOrFallback(theme: Theme | undefined, key: keyof ThemeKeys): string;
+export declare function applyTheme(element: HTMLElement, theme: Theme | undefined): void;
+/**
+ * Sets a default theme for all Tweakpane components on the page. Useful if you have a light / dark
+ * mode toggle.
+ */
+export declare function setGlobalDefaultTheme(theme: Theme | undefined): void;
+declare const _default: {
+	/**
+	 * A collection of default theme color schemes, matching those provided in the Tweakpane
+	 * [Panebuilder presets](https://tweakpane.github.io/docs/theming/#builder).
+	 * */
+	presets: {
+		/** Dark blue theme. */
+		iceberg: Theme;
+		/** Extra dark theme. */
+		jetblack: Theme;
+		/** Standard Tweakpane light theme. */
+		light: Theme;
+		/** Light theme with CRT vibes. */
+		retro: Theme;
+		/** Standard Tweakpane dark theme. This is the default theme. */
+		standard: Theme;
+		/** Dark translucent theme. */
+		translucent: Theme;
+		/** Red theme. */
+		vivid: Theme;
+	};
+	setGlobalDefaultTheme: typeof setGlobalDefaultTheme;
+};
+export default _default;