svelte-tweakpane-ui
Version:
A Svelte component library wrapping UI elements from Tweakpane, plus some additional functionality for convenience and flexibility.
314 lines (313 loc) • 9.07 kB
TypeScript
import { SvelteComponent } from 'svelte'
import type { ProfilerBladeMeasureHandler } from '@kitschpatrol/tweakpane-plugin-profiler'
import type { Simplify } from '../utils.js'
export type ProfilerCalcMode = 'frame' | 'mean' | 'median'
export type ProfilerMeasure = (name: string, functionToMeasure: () => void) => void
export type ProfilerMeasureAsync = (
name: string,
functionToMeasure: () => Promise<void>,
) => Promise<void>
export type ProfilerMeasureHandler = Simplify<ProfilerBladeMeasureHandler>
export type ProfilerChangeEvent = CustomEvent<number>
import type { ProfilerBladeApi as ProfilerRef } from '@kitschpatrol/tweakpane-plugin-profiler/dist/types/ProfilerBladeApi.js'
import type { ProfilerBladePluginParams as ProfilerOptions } from '@kitschpatrol/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', () => { ... })`
* @default `undefined`
* @bindable
* @readonly
*/
measure?: ProfilerMeasure | undefined
/**
* Async variation of function handle that wraps another function to measure
* its execution duration.
*
* @async
* @example
* ;`measureAsync('Hard Work', async () => { ... })`
* @default `undefined`
* @bindable
* @readonly
*/
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
/**
* Custom color scheme.
*
* If undefined, inherits default Tweakpane theme equivalent to
* `ThemeUtils.presets.standard`, or the theme set with
* `setGlobalDefaultTheme()`.
*
* @default `undefined`
*/
theme?: import('..').Theme | undefined
/**
* Reference to internal Tweakpane
* [`BladeApi`](https://tweakpane.github.io/docs/api/classes/BladeApi.html)
* for this blade.
*
* This property is exposed for advanced use cases only, such as when
* implementing convenience components wrapping `<Blade>`'s functionality.
*
* Direct manipulation of Tweakpane's internals can break _Svelte Tweakpane
* UI_ abstractions.
*
* @bindable
* @readonly
*/
ref?: ProfilerRef | undefined
/**
* Imported Tweakpane `TpPluginBundle` (aliased as `Plugin`) module to
* automatically register in the `<Blade>`'s containing `<Pane>`.
*
* This property is exposed for advanced use cases only, such as when
* implementing convenience components wrapping `<Blade>`'s functionality in
* combination with a Tweakpane plugin.
*
* Direct manipulation of Tweakpane's internals can break _Svelte Tweakpane
* UI_ abstractions.
*
* @default `undefined`
*/
plugin?: import('../utils.js').Plugin | undefined
},
'ref' | 'options' | 'plugin'
> & {
/**
* Number of duration samples from which to calculate the delta value when
* `calcMode` is `'mean'` or `'median'`.
*
* @default `30`
*/
bufferSize?: number
/**
* 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
/**
* 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
/**
* Precision of the delta values shown in the control.
*
* @default `2`
*/
fractionDigits?: number
/**
* 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
/**
* Text displayed next to the profiler visualization.
*
* @default `undefined`
*/
label?: string
/**
* 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', () => { ... })`
*
* @default `undefined`
* @bindable
* @readonly
*/
measure?: ProfilerMeasure
/**
* Async variation of function handle that wraps another function to measure
* its execution duration.
*
* @async
* @example
* ;`measureAsync('Hard Work', async () => { ... })`
*
* @default `undefined`
* @bindable
* @readonly
*/
measureAsync?: ProfilerMeasureAsync
/**
* Function wrapping the `measure` function.
*
* The default is fine for most cases when you want to measure a temporal
* duration.
*
* @default
*/
measureHandler?: ProfilerMeasureHandler
/**
* Determines the horizontal scale and color mapping of the profiler
* visualization bars.
*
* @default `16.67` (60 FPS)
*/
targetDelta?: number
})
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">`.
*
* Note that _Svelte Tweakpane UI_ embeds a functionally identical [fork](https://github.com/kitschpatrol/tweakpane-plugin-profiler) of the plugin with build optimizations.
*
* @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(
* function_: (n: number) => number,
* exponent: number,
* ): void {
* measure(function_.name, () => {
* for (let sum = 0; sum < Number('1e' + exponent); sum++) {
* function_(sum)
* }
* })
* }
*
* onMount(() => {
* let animationFrameHandle: number
*
* // Nesting measurements creates a hierarchy
* // in the Profile visualization
* function tick() {
* 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)
* })
* })
*
* animationFrameHandle = requestAnimationFrame(tick)
* }
*
* tick()
*
* return () => {
* cancelAnimationFrame(animationFrameHandle)
* }
* })
* </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 {}