svelte-tweakpane-ui 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Eric Mika
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# svelte-tweakpane-ui
+
+## Overview
+
+🎛️ **_Svelte Tweakpane UI_** wraps user-interface elements from the excellent [Tweakpane](https://cocopon.github.io/tweakpane/) library in a collection of 31 idiomatic, reactive, type-safe, carefully-crafted [Svelte](https://svelte.dev) components.
+
+The library makes it easy to quickly and declaratively add knobs and dials to your projects using components that feel like they belong in the DOM. It also augments Tweakpane with a few [extra features](https://kitschpatrol.com/svelte-tweakpane-ui/docs/features) for your convenience and enjoyment.
+
+[The components](https://kitschpatrol.com/svelte-tweakpane-ui/docs#components) should be useful for integrating controls and value monitoring in parametrically driven artworks or simulations.
+
+## Documentation
+
+**_Please see the documentation site for much more information:_**  
+**[https://kitschpatrol.com/svelte-tweakpane-ui](https://kitschpatrol.com/svelte-tweakpane-ui)**
+
+## Quick start
+
+1. Add _Svelte Tweakpane UI_ to your Svelte project:
+
+```sh
+npm install svelte-tweakpane-ui
+```
+
+2. Import and use Tweakpane components in your `.svelte` files:
+
+```svelte
+<script lang="ts">
+  import { Button } from 'svelte-tweakpane-ui';
+</script>
+
+<Button on:click={() => alert('Hi from STUI')} />
+```
+
+---
+
+_Note: This library is not to be confused with Karl Moore's [`svelte-tweakpane`](https://github.com/pierogis/svelte-tweakpane)._

package/dist/control/ButtonGrid.svelte

@@ -0,0 +1,49 @@
+<script context="module"></script>
+
+<script>
+	import * as pluginModule from '@tweakpane/plugin-essentials';
+	import Blade from '../core/Blade.svelte';
+	import ClsPad from '../internal/ClsPad.svelte';
+	import { fillWith } from '../utils';
+	import { getGridDimensions } from '../utils.js';
+	import { BROWSER } from 'esm-env';
+	import { createEventDispatcher } from 'svelte';
+	export let columns = void 0;
+	export let rows = void 0;
+	export let buttons = [];
+	export let label = void 0;
+	const dispatch = createEventDispatcher();
+	let options;
+	let gridBlade;
+	let gridDimensions;
+	function cells(x, y) {
+		const index = y * gridDimensions.columns + x;
+		if (index >= 0 && index < buttons.length) {
+			return {
+				title: `${buttons[index]}`
+			};
+		}
+		return { title: '' };
+	}
+	$: gridDimensions = getGridDimensions(buttons.length, columns, rows);
+	$: options = {
+		cells,
+		label,
+		size: [gridDimensions.columns, gridDimensions.rows],
+		view: 'buttongrid'
+	};
+	$: gridBlade &&
+		gridBlade.on('click', (ev) => {
+			dispatch('click', {
+				cell: { x: ev.index[0], y: ev.index[1] },
+				index: ev.index[1] * gridDimensions.columns + ev.index[0],
+				label: ev.cell.title
+			});
+		});
+</script>
+
+<Blade bind:ref={gridBlade} {options} plugin={pluginModule} {...$$restProps} />
+{#if !BROWSER}
+	<ClsPad keysAdd={fillWith('containerUnitSize', gridDimensions.rows)} theme={$$props.theme} />
+	<ClsPad keysAdd={fillWith('containerVerticalPadding', 2)} theme={$$props.theme} />
+{/if}

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

@@ -0,0 +1,190 @@
+import { SvelteComponent } from 'svelte';
+export type ButtonGridClickEvent = CustomEvent<{
+	cell: {
+		x: number;
+		y: number;
+	};
+	index: number;
+	label: string;
+}>;
+import type { ButtonGridApi as ButtonGridRef } from '@tweakpane/plugin-essentials';
+import type { ButtonGridBladeParams as ButtonGridOptions } from '@tweakpane/plugin-essentials/dist/types/button-grid/plugin.d.ts';
+declare const __propDef: {
+	props: Omit<
+		{
+			/**
+			 * Blade configuration exposing Tweakpane's internal
+			 * [`BladeParams`](https://tweakpane.github.io/docs/api/interfaces/BaseBladeParams.html).
+			 *
+			 */
+			options: ButtonGridOptions;
+			/**
+			 * 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?: ButtonGridRef | 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'
+	> & {
+		/**
+		 * Array of names, each of which will become the title of a button in the grid.
+		 * */
+		buttons: string[];
+		/**
+		 * Number of columns to arrange the buttons into.
+		 *
+		 * Setting `columns` without setting `rows` will lock the column count and allow the row
+		 * count to change dynamically based on the number of buttons.
+		 * @default `undefined`  \
+		 * Dynamic based on quantity of `buttons`.
+		 * */
+		columns?: number | undefined;
+		/**
+		 * Text displayed next to the button grid.
+		 * @default `undefined`
+		 */
+		label?: string | undefined;
+		/**
+		 * Number of rows to arrange the buttons into.
+		 *
+		 * Setting `rows` without setting `columns` will lock the column count and allow the column
+		 * count to change dynamically based on the number of buttons.
+		 * @default `undefined`  \
+		 * Dynamic based on quantity of `buttons`.
+		 * */
+		rows?: number | undefined;
+	};
+	slots: {};
+	events: {
+		/**
+		 * Fires when a button is clicked.
+		 *
+		 * Note that the values described in the `ButtonGridClickEvent` type are available on the
+		 * `event.detail` parameter.
+		 * @event
+		 * */
+		click: ButtonGridClickEvent;
+	};
+};
+export type ButtonGridProps = typeof __propDef.props;
+export type ButtonGridEvents = typeof __propDef.events;
+export type ButtonGridSlots = typeof __propDef.slots;
+/**
+ * A grid of `<Button>` components.
+ *
+ * Integrates the [Button Grid](https://github.com/tweakpane/plugin-essentials#button-grid) control
+ * from Tweakpane-creator [Hiroki Kokubun's](https://cocopon.me)  [Essentials
+ * plugin](https://github.com/tweakpane/plugin-essentials).
+ *
+ * See `<RadioGrid>` for a radio-flavored variation.
+ *
+ * _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`.
+ *
+ * @emits {ButtonGridClickEvent} click - When a button in the grid is clicked.
+ *
+ * Usage outside of a `<Pane>` component will implicitly wrap the button grid in `<Pane
+ * position='inline'>`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ * import {
+ *   Button,
+ *   ButtonGrid,
+ *   type ButtonGridClickEvent,
+ *   Pane
+ * } from 'svelte-tweakpane-ui';
+ *
+ * const keyboard = [
+ *   ...Array.from({ length: 26 }, (_, i) => String.fromCharCode(65 + i)),
+ *   ',',
+ *   '.',
+ *   '!',
+ *   '⌫'
+ * ];
+ *
+ * let textBuffer = '';
+ *
+ * function handleClick(e: ButtonGridClickEvent) {
+ *   textBuffer =
+ *     e.detail.label === '⌫'
+ *       ? textBuffer.slice(0, -1)
+ *       : textBuffer + e.detail.label;
+ * }
+ * </script>
+ *
+ * <Pane position="inline" title="Austerity Keyboard">
+ * <ButtonGrid on:click={handleClick} buttons={keyboard} />
+ * <Button on:click={() => (textBuffer += '\u2002')} title=" " />
+ * </Pane>
+ *
+ * <div class="demo">
+ * <p>{textBuffer}</p>
+ * </div>
+ *
+ * <style>
+ * .demo {
+ *   aspect-ratio: 1;
+ *   width: 100%;
+ *   background: linear-gradient(45deg, orange, magenta);
+ * }
+ *
+ * .demo > p {
+ *   margin: 0;
+ *   padding: 0.5rem;
+ *   font-family: monospace;
+ *   font-size: 2rem;
+ *   line-height: 1.2;
+ *   color: white;
+ *   word-break: break-all;
+ *   white-space: pre-wrap;
+ * }
+ *
+ * .demo > p::after {
+ *   content: '_';
+ *   opacity: 0.5;
+ * }
+ * </style>
+ * ```
+ *
+ * @sourceLink
+ * [ButtonGrid.svelte](https://github.com/kitschpatrol/svelte-tweakpane-ui/blob/main/src/lib/control/ButtonGrid.svelte)
+ */
+export default class ButtonGrid extends SvelteComponent<
+	ButtonGridProps,
+	ButtonGridEvents,
+	ButtonGridSlots
+> {}
+export {};

package/dist/control/Checkbox.svelte

@@ -0,0 +1,6 @@
+<script>
+	import GenericInput from '../internal/GenericInput.svelte';
+	export let value;
+</script>
+
+<GenericInput bind:value {...$$restProps} />

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

@@ -0,0 +1,113 @@
+import { SvelteComponent } from 'svelte';
+declare const __propDef: {
+	props: 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/core').BaseInputParams | 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'
+		> & {
+			/**
+			 * The value to control.
+			 * @bindable
+			 */
+			value: boolean;
+		},
+		'options' | 'ref' | 'plugin'
+	>;
+	events: {
+		[evt: string]: CustomEvent<any>;
+	};
+	slots: {};
+};
+export type CheckboxProps = typeof __propDef.props;
+export type CheckboxEvents = typeof __propDef.events;
+export type CheckboxSlots = typeof __propDef.slots;
+/**
+ * A checkbox.
+ *
+ * Wraps Tweakpane's [boolean input binding](https://tweakpane.github.io/docs/input-bindings/#boolean).
+ *
+ * Usage outside of a `<Pane>` component will implicitly wrap the checkbox in `<Pane
+ * position='inline'>`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ * import { Checkbox } from 'svelte-tweakpane-ui';
+ *
+ * let reticulationEnabled: boolean = false;
+ * </script>
+ *
+ * <Checkbox bind:value={reticulationEnabled} label="Reticulation" />
+ * <pre>Enabled: {reticulationEnabled}</pre>
+ * ```
+ *
+ * @sourceLink
+ * [Checkbox.svelte](https://github.com/kitschpatrol/svelte-tweakpane-ui/blob/main/src/lib/control/Checkbox.svelte)
+ */
+export default class Checkbox extends SvelteComponent<
+	CheckboxProps,
+	CheckboxEvents,
+	CheckboxSlots
+> {}
+export {};

package/dist/control/Color.svelte

@@ -0,0 +1,79 @@
+<script context="module"></script>
+
+<script>
+	import { isColorObject, isObject, isRgbColorObject, isRgbaColorObject } from '@tweakpane/core';
+	import ClsPad from '../internal/ClsPad.svelte';
+	import GenericInputFolding from '../internal/GenericInputFolding.svelte';
+	import { objectToTuple, tupleToObject } from '../utils';
+	import { fillWith } from '../utils';
+	import { BROWSER } from 'esm-env';
+	export let value;
+	export let expanded = void 0;
+	export let type = void 0;
+	let internalValue;
+	let options;
+	let ref;
+	const buttonClass = 'tp-colswv_b';
+	function updateInternalValue() {
+		if (Array.isArray(value)) {
+			if (value.length === 4) {
+				internalValue = tupleToObject(value, ['r', 'g', 'b', 'a']);
+			} else if (value.length === 3) {
+				internalValue = tupleToObject(value, ['r', 'g', 'b']);
+			} else {
+				console.error('Unreachable');
+			}
+		} else {
+			internalValue = value;
+		}
+	}
+	function updateValue() {
+		if (Array.isArray(value) && isColorObject(internalValue)) {
+			if (isRgbaColorObject(internalValue)) {
+				value = objectToTuple(internalValue, ['r', 'g', 'b', 'a']);
+			} else if (isRgbColorObject(internalValue)) {
+				value = objectToTuple(internalValue, ['r', 'g', 'b']);
+			} else {
+				console.error('Unreachable');
+			}
+		} else if (typeof value === 'string') {
+			value = internalValue;
+		} else if (isObject(value)) {
+			value = internalValue;
+		} else {
+			console.error('Unreachable');
+		}
+	}
+	function addListeners() {
+		ref.on('change', () => {
+			ref.refresh();
+		});
+	}
+	$: value, updateInternalValue();
+	$: internalValue, updateValue();
+	$: ref !== void 0 && addListeners();
+	$: options = {
+		color: {
+			type
+		},
+		view: 'color'
+	};
+</script>
+
+<GenericInputFolding
+	bind:value={internalValue}
+	bind:expanded
+	bind:ref
+	{buttonClass}
+	{options}
+	{...$$restProps}
+/>
+{#if !BROWSER && expanded && $$props.picker === 'inline'}
+	<!-- Main swatch -->
+	<ClsPad keysAdd={fillWith('containerUnitSize', 6)} theme={$$props.theme} />
+	<ClsPad keysAdd={fillWith('containerUnitSpacing', 3)} theme={$$props.theme} />
+	{#if isRgbaColorObject(internalValue)}
+		<ClsPad keysAdd={fillWith('containerUnitSize', 1)} theme={$$props.theme} />
+		<ClsPad extra={2} keysAdd={fillWith('containerVerticalPadding', 2)} theme={$$props.theme} />
+	{/if}
+{/if}

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

@@ -0,0 +1,177 @@
+import { SvelteComponent } from 'svelte';
+import type {
+	RgbColorObject,
+	RgbaColorObject
+} from '@tweakpane/core/dist/input-binding/color/model/color.js';
+import type { Simplify } from '../utils';
+export type ColorValueRgbTuple = [r: number, g: number, b: number];
+export type ColorValueRgbaTuple = [r: number, g: number, b: number, a: number];
+export type ColorValueRgbObject = Simplify<RgbColorObject>;
+export type ColorValueRgbaObject = Simplify<RgbaColorObject>;
+export type ColorValueString = string;
+export type ColorValue = Simplify<
+	| ColorValueRgbObject
+	| ColorValueRgbTuple
+	| ColorValueRgbaObject
+	| ColorValueRgbaTuple
+	| ColorValueString
+>;
+import type { ColorInputParams as ColorOptions } from 'tweakpane';
+declare const __propDef: {
+	props: Omit<
+		Omit<
+			{
+				/**
+				 * The binding's target object with values to manipulate.
+				 * @bindable
+				 */
+				object: import('@tweakpane/core').Bindable & {
+					[x: string]: ColorValue;
+				};
+				/** 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?: ColorOptions | 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 color value to control.
+			 *
+			 * Use either a color-like string (e.g. #ff00ff), or an object with `r`, `b`, `g`, and
+			 * optional `a` keys.
+			 * @bindable
+			 */
+			value: ColorValue;
+		} & {
+			/**
+			 * 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 color value to control.
+		 *
+		 * Use either a color-like string (e.g. #ff00ff), or an object with `r`, `b`, `g`, and
+		 * optional `a` keys.
+		 * @bindable
+		 * */
+		value: ColorValue;
+		/**
+		 * Whether to treat values as floats from 0.0 to 1.0, or integers from 0 to 255.
+		 * @default `'int'`
+		 * */
+		type?: 'float' | 'int' | undefined;
+	};
+	events: {
+		[evt: string]: CustomEvent<any>;
+	};
+	slots: {};
+};
+export type ColorProps = typeof __propDef.props;
+export type ColorEvents = typeof __propDef.events;
+export type ColorSlots = typeof __propDef.slots;
+/**
+ * A color picker.
+ *
+ * Wraps Tweakpane's [color input binding](https://tweakpane.github.io/docs/input-bindings/#color).
+ *
+ * Usage outside of a `<Pane>` component will implicitly wrap the color picker in `<Pane
+ * position='inline'>`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ * import { Color } from 'svelte-tweakpane-ui';
+ *
+ * let startColor = '#fff000';
+ * let endColor = '#ff00ff';
+ * </script>
+ *
+ * <Color bind:value={startColor} label="Start Color" />
+ * <Color bind:value={endColor} label="End Color" />
+ *
+ * <div class="demo" style:--a={startColor} style:--b={endColor} />
+ *
+ * <style>
+ * .demo {
+ *   aspect-ratio: 1;
+ *   width: 100%;
+ *   background: linear-gradient(to top, var(--a), var(--b));
+ * }
+ * </style>
+ * ```
+ *
+ * @sourceLink
+ * [Color.svelte](https://github.com/kitschpatrol/svelte-tweakpane-ui/blob/main/src/lib/control/Color.svelte)
+ */
+export default class Color extends SvelteComponent<ColorProps, ColorEvents, ColorSlots> {}
+export {};