@lavalogic/scoria 0.36.0 → 0.37.1

package/dist/Components/Dial.svelte

@@ -1,29 +1,60 @@
 <svelte:options runes />
 
-<script lang="ts" generics="T">
+<script
+	lang="ts"
+	module
+>
+	import { Sizing } from '../scss/sizing.js';
+
+	// Pixel height of each dial option. Sourced from `sizing.ts` so the
+	// SCSS partial and TS constant stay in sync (see comment at the top
+	// of `sizing.ts`).
+	const OPTION_HEIGHT: number = Sizing['$dial-option-height'];
+</script>
+
+<script
+	lang="ts"
+	generics="T"
+>
 	import { onMount } from 'svelte';
 	import type { DialProps } from './DialProps.js';
 
-	const optionHeight = 50;
-
 	let {
 		selected,
-		values,
-		labels,
+		entries,
 		type,
 		ref = $bindable(),
 		onsubmit,
 		onPrevious,
 		onNext,
-		onchange
+		onchange,
 	}: DialProps<T> = $props();
 
-	let position = $derived(selected != null ? -values.indexOf(selected) * optionHeight : 0);
-	let offset = 0;
-	let dragging = false;
+	// `position`, `offset`, `dragging` must all be `$state` so that the
+	// position-syncing `$effect` below re-runs when `dragging` flips back
+	// to `false` at the end of a drag. The previous `let` variables were
+	// invisible to Svelte's reactivity and made the `$effect`'s firing
+	// order depend on `selected` happening to change.
+	//
+	// `position` initialises to 0; the `$effect` below syncs it to the
+	// `selected`-derived position on first run. Reading `selected` /
+	// `values` directly in the initialiser would only capture their
+	// initial values (svelte warning `state_referenced_locally`), and
+	// since the effect already covers that path we keep the initialiser
+	// trivial.
+	let position = $state(0);
+	let offset = $state(0);
+	let dragging = $state(false);
 
 	let itemWrapper: HTMLUListElement | undefined = $state();
-	let previousY: number;
+	let previousY = 0;
+
+	// AbortController used to register/clean up window-level
+	// `mousemove`/`mouseup`/`touchmove`/`touchend` listeners. Stored in a
+	// single ref so a stray `mousedown` cannot leak a second set, and so
+	// the cleanup `$effect` below can detach everything on unmount even
+	// if the user navigates away mid-drag.
+	let dragAbort: AbortController | undefined;
 
 	onMount(() => {
 		setPosition();
@@ -31,7 +62,8 @@
 
 	$effect(() => {
 		if (!dragging) {
-			const selectedPosition = selected != null ? -values.indexOf(selected) * optionHeight : 0;
+			const selectedPosition =
+				selected != null ? -entries.findIndex((e) => e.value === selected) * OPTION_HEIGHT : 0;
 			if (position !== selectedPosition) {
 				position = selectedPosition;
 				setPosition();
@@ -39,69 +71,88 @@
 		}
 	});
 
+	// Ensure any in-flight drag listeners are detached on unmount. The
+	// listeners would otherwise leak if the component unmounted between
+	// `onmousedown` and `onMouseUp` (rare, but possible if the parent
+	// modal closes mid-drag).
+	$effect(() => () => {
+		dragAbort?.abort();
+	});
+
 	function onChange(changedData: T) {
 		onchange({
 			type,
-			changedData
+			changedData,
 		});
 	}
 
 	function setPosition() {
-		const itemPosition = `
-		transition: transform ${Math.abs(offset) / 100 + 0.1}s;
-        transform: translateY(${position}px)
-      `;
-		if (itemWrapper) {
-			itemWrapper.style.cssText = itemPosition;
-		} else {
-			console.warn('item wrapper is undefined');
+		if (!itemWrapper) {
+			// Silently no-op if the wrapper has not yet mounted. The previous
+			// `console.warn` fired during the initial render of every dial
+			// and was noise in production logs.
+			return;
 		}
+
+		// Set transform / transition individually rather than rewriting the
+		// full `cssText`. The latter parses the entire declaration string
+		// per mousemove (~60 Hz); `setProperty` skips the parse and only
+		// updates the named declarations. The `transition-duration` scales
+		// with drag inertia, so we still need imperative updates rather
+		// than `style:transform={...}` for the dragging case.
+		const transitionDuration = `${Math.abs(offset) / 100 + 0.1}s`;
+		itemWrapper.style.setProperty('transition', `transform ${transitionDuration}`);
+		itemWrapper.style.setProperty('transform', `translateY(${position}px)`);
 	}
 
 	const onmousedown = (event: MouseEvent | TouchEvent) => {
 		previousY = 'touches' in event ? event.touches[0].clientY : event.clientY;
 		dragging = true;
 
-		window.addEventListener('mousemove', onMouseMove);
-		window.addEventListener('mouseup', onMouseUp);
-		window.addEventListener('touchmove', onMouseMove);
-		window.addEventListener('touchend', onMouseUp);
+		// One AbortController per drag. Attached to all four window
+		// listeners so a single `controller.abort()` detaches everything.
+		dragAbort?.abort();
+		dragAbort = new AbortController();
+		const { signal } = dragAbort;
+
+		window.addEventListener('mousemove', onMouseMove, { signal });
+		window.addEventListener('mouseup', onMouseUp, { signal });
+		window.addEventListener('touchmove', onMouseMove, { signal });
+		window.addEventListener('touchend', onMouseUp, { signal });
 	};
 
 	const onMouseMove = (event: MouseEvent | TouchEvent) => {
 		const clientY = 'touches' in event ? event.touches[0].clientY : event.clientY;
 		offset = clientY - previousY;
 
-		const maxPosition = -values.length * optionHeight;
+		const maxPosition = -entries.length * OPTION_HEIGHT;
 		const _position = position + offset;
-		position = Math.max(maxPosition, Math.min(optionHeight, _position));
+		position = Math.max(maxPosition, Math.min(OPTION_HEIGHT, _position));
 		previousY = 'touches' in event ? event.touches[0].clientY : event.clientY;
 		setPosition();
 	};
 
 	const onMouseUp = () => {
-		const maxPosition = -(values.length - 1) * optionHeight;
-		const rounderPosition = Math.round((position + offset * 5) / optionHeight) * optionHeight;
+		const maxPosition = -(entries.length - 1) * OPTION_HEIGHT;
+		const rounderPosition = Math.round((position + offset * 5) / OPTION_HEIGHT) * OPTION_HEIGHT;
 		const finalPosition = Math.max(maxPosition, Math.min(0, rounderPosition));
 
 		dragging = false;
 		position = finalPosition;
 
-		window.removeEventListener('mousemove', onMouseMove);
-		window.removeEventListener('mouseup', onMouseUp);
-		window.removeEventListener('touchmove', onMouseMove);
-		window.removeEventListener('touchend', onMouseUp);
+		dragAbort?.abort();
+		dragAbort = undefined;
 
 		setPosition();
-		onChange(values[-finalPosition / optionHeight]);
+		onChange(entries[-finalPosition / OPTION_HEIGHT].value);
 	};
 
 	const onwheel = (e: WheelEvent) => {
 		if (e.deltaY > 0) {
-			position = position - optionHeight;
+			position = position - OPTION_HEIGHT;
 		}
 		if (e.deltaY < 0) {
-			position = position + optionHeight;
+			position = position + OPTION_HEIGHT;
 		}
 		onMouseUp();
 	};
@@ -116,10 +167,10 @@
 			} else if (e.key === 'ArrowRight') {
 				onNext(type);
 			} else if (e.key === 'ArrowUp') {
-				position = position + optionHeight;
+				position = position + OPTION_HEIGHT;
 				onMouseUp();
 			} else if (e.key === 'ArrowDown') {
-				position = position - optionHeight;
+				position = position - OPTION_HEIGHT;
 				onMouseUp();
 			} else if (e.key === 'Enter') {
 				onsubmit();
@@ -129,7 +180,6 @@
 </script>
 
 <div
-	style="--option-height: {optionHeight}px"
 	class="select-wrapper"
 	role="listbox"
 	tabindex="0"
@@ -140,15 +190,19 @@
 	{onkeydown}
 >
 	<div class="selected-wrapper">
-		<ul bind:this={itemWrapper} class="touch-date-container">
-			{#each labels as item (item)}
-				<li>{item}</li>
+		<ul
+			bind:this={itemWrapper}
+			class="touch-date-container"
+		>
+			{#each entries as entry (entry.value)}
+				<li>{entry.label}</li>
 			{/each}
 		</ul>
 	</div>
 </div>
 
 <style>.select-wrapper {
+  --option-height: 50px;
   height: calc(var(--option-height));
   padding: 50px 0;
   margin: 10px 0;
@@ -172,6 +226,14 @@
   margin: 0;
   padding: 0;
 }
+@media (prefers-reduced-motion: reduce) {
+  .touch-date-container {
+    animation-duration: 0.001ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.001ms !important;
+    scroll-behavior: auto !important;
+  }
+}
 
 .selected-wrapper:before,
 .selected-wrapper:after {

package/dist/Components/DialProps.d.ts

@@ -1,13 +1,85 @@
 import type { DateChange } from '../Types/Internal/DateChange.js';
 import type { DatePickerType } from '../Types/Internal/DatePickerType.js';
+/**
+ * A single dial entry pairing the underlying value with its
+ * human-readable label. Replaces the previous parallel
+ * `values: Array<T>` / `labels: Array<string | number>` arrays whose
+ * index parity was a runtime invariant the type system could not
+ * enforce.
+ */
+export interface DialEntry<T> {
+    /** The underlying value selected when this entry is active. */
+    value: T;
+    /**
+     * The displayed label. `string | number` because both numeric
+     * ranges (days, years, hours) and named string lists (months) are
+     * valid label sources.
+     */
+    label: string | number;
+}
+/**
+ * Props for {@link Dial}.
+ *
+ * `Dial` is a touch/wheel-scroll value picker used by `DatePicker`.
+ * It renders a vertical scrolling list and reports the selected value
+ * via the `onchange` callback.
+ *
+ * @typeParam T - The underlying value type of each option (e.g. `number`
+ *                for days/years, `number` for month indices).
+ */
 export interface DialProps<T> {
+    /**
+     * The currently selected value. Must be the `value` of one of the
+     * `entries`.
+     */
     selected: T;
-    values: Array<T>;
-    labels: Array<unknown>;
+    /**
+     * Ordered list of `{ value, label }` entries. Replaces the prior
+     * parallel `values` + `labels` arrays.
+     *
+     * BREAKING (vNext): was `values: Array<T> + labels: Array<string |
+     * number>`. Migrate by zipping the two arrays into entry objects:
+     *
+     * ```ts
+     * // before
+     * <Dial values={[1,2,3]} labels={['Jan','Feb','Mar']} />
+     * // after
+     * <Dial entries={[
+     *   { value: 1, label: 'Jan' },
+     *   { value: 2, label: 'Feb' },
+     *   { value: 3, label: 'Mar' },
+     * ]} />
+     * ```
+     */
+    entries: ReadonlyArray<DialEntry<T>>;
+    /**
+     * Which date component this dial controls. Forwarded back through
+     * `onchange`, `onPrevious`, `onNext` so the parent `DatePicker` can
+     * dispatch the value to the correct field.
+     */
     type: DatePickerType;
+    /**
+     * Invoked when the user confirms the dial value (`Enter` keypress).
+     */
     onsubmit: () => void;
+    /**
+     * Invoked when the user requests focus on the previous dial
+     * (`ArrowLeft` keypress).
+     */
     onPrevious: (type: DatePickerType) => void;
+    /**
+     * Invoked when the user requests focus on the next dial
+     * (`ArrowRight` keypress).
+     */
     onNext: (type: DatePickerType) => void;
+    /**
+     * Invoked when the selected value changes (drag end, wheel scroll,
+     * or `ArrowUp`/`ArrowDown` keypress).
+     */
     onchange: (change: DateChange<T>) => void;
+    /**
+     * Two-way bindable reference to the outer wrapper element. Used by
+     * `DatePicker` to programmatically move focus between dials.
+     */
     ref?: HTMLDivElement | undefined;
 }

package/dist/Components/DimensionInput.svelte

@@ -12,12 +12,9 @@
 		y = $bindable(null),
 		z = $bindable(null),
 
-		// labelTop,
-		// rightIcon,
-		// onLeftIconClick,
-		// onRightIconClick,
-
 		max,
+		labelTop = 'Dimensions',
+		optional = true,
 		placeholder,
 		required = false,
 		variant = InputVariant.Default,
@@ -31,55 +28,39 @@
 		onblur,
 		onfocus,
 		onkeydown,
-		oninput,
+		// oninput intentionally not forwarded; per-axis handleInput wires it.
+		onchange,
 
-		inputRef = $bindable(),
+		inputRefs = $bindable({}),
 		'data-type': dataType,
 	}: DimensionInputProps = $props();
 
-	// NOTE unable to edit signature
-	function xNumberValidator(_node: HTMLInputElement, _newValue: number | null | undefined) {
-		// function xNumberValidator() {
-		return {
-			update(newValue: number) {
-				const underMinimum = min > newValue;
-				const overMaximum = max != undefined && max < newValue;
-
-				x = (
-					isNaN(newValue) ? 0 : underMinimum ? min : overMaximum ? max : newValue
-				) as Centimetres;
-			},
-		};
-	}
-	function yNumberValidator(_node: HTMLInputElement, _newValue: number | null | undefined) {
-		return {
-			update(newValue: number) {
-				const underMinimum = min > newValue;
-				const overMaximum = max != undefined && max < newValue;
-
-				y = (
-					isNaN(newValue) ? 0 : underMinimum ? min : overMaximum ? max : newValue
-				) as Centimetres;
-			},
-		};
+	function clamp(value: number): Centimetres {
+		if (isNaN(value)) {
+			return 0 as Centimetres;
+		}
+		const underMinimum = min > value;
+		const overMaximum = max != undefined && max < value;
+		return (underMinimum ? min : overMaximum ? max : value) as Centimetres;
 	}
 
-	function zNumberValidator(_node: HTMLInputElement, _newValue: number | null | undefined) {
-		// function zNumberValidator() {
-		return {
-			update(newValue: number) {
-				const underMinimum = min > newValue;
-				const overMaximum = max != undefined && max < newValue;
-
-				z = (
-					isNaN(newValue) ? 0 : underMinimum ? min : overMaximum ? max : newValue
-				) as Centimetres;
-			},
+	function handleInput(axis: 'x' | 'y' | 'z') {
+		return (e: Event) => {
+			const target = e.target as HTMLInputElement;
+			const raw = target.value;
+			const parsed = raw === '' ? null : clamp(Number(raw));
+			if (axis === 'x') {
+				x = parsed;
+			} else if (axis === 'y') {
+				y = parsed;
+			} else {
+				z = parsed;
+			}
+			onchange?.(axis, parsed);
 		};
 	}
-	// ^
 
-	let isInvalid = $derived(
+	const isInvalid = $derived(
 		showErrorColours &&
 			((required &&
 				(x == null ||
@@ -90,6 +71,10 @@
 					z.toString().trim() === '')) ||
 				invalid)
 	);
+
+	const xId = $derived(id ? `${id}-x` : undefined);
+	const yId = $derived(id ? `${id}-y` : undefined);
+	const zId = $derived(id ? `${id}-z` : undefined);
 </script>
 
 <div
@@ -100,30 +85,33 @@
 	<span
 		class="top-label"
 		class:for-default={variant === InputVariant.Default}
-		class:invalid={isInvalid}>Dimensions - <span class="optional">optional</span></span
+		class:invalid={isInvalid}
+		>{labelTop}{#if optional}
+			- <span class="optional">optional</span>{/if}</span
 	>
 	{#if variant === InputVariant.Default}
-		<span class="border">Dimensions - <span class="optional">optional</span></span>
+		<span class="border"
+			>{labelTop}{#if optional}
+				- <span class="optional">optional</span>{/if}</span
+		>
 	{/if}
-	<!-- style="--background-colour: {leftIcon?.backgroundColour ?? rightIcon?.backgroundColour};" -->
 	<div
 		class="icon-container"
 		class:for-modal={variant == InputVariant.Modal}
 	>
 		<input
-			{id}
+			id={xId}
 			class:for-default={variant === InputVariant.Default}
 			data-type={dataType}
-			use:xNumberValidator={x}
 			class:left-pad={leftIcon != undefined}
 			class:for-modal={variant == InputVariant.Modal}
 			type="number"
-			bind:value={x as number}
+			value={x ?? ''}
+			oninput={handleInput('x')}
 			{onblur}
 			{onfocus}
 			{onkeydown}
-			{oninput}
-			bind:this={inputRef}
+			bind:this={inputRefs.x}
 			{placeholder}
 			{required}
 			{disabled}
@@ -132,19 +120,18 @@
 			step={decimal ? 0.01 : 1}
 		/>
 		<input
-			{id}
+			id={yId}
 			class:for-default={variant === InputVariant.Default}
 			data-type={dataType}
-			use:yNumberValidator={y}
 			class:left-pad={leftIcon != undefined}
 			class:for-modal={variant == InputVariant.Modal}
 			type="number"
-			bind:value={y as number}
+			value={y ?? ''}
+			oninput={handleInput('y')}
 			{onblur}
 			{onfocus}
 			{onkeydown}
-			{oninput}
-			bind:this={inputRef}
+			bind:this={inputRefs.y}
 			{placeholder}
 			{required}
 			{disabled}
@@ -153,19 +140,18 @@
 			step={decimal ? 0.01 : 1}
 		/>
 		<input
-			{id}
+			id={zId}
 			class:for-default={variant === InputVariant.Default}
 			data-type={dataType}
-			use:zNumberValidator={z}
 			class:left-pad={leftIcon != undefined}
 			class:for-modal={variant == InputVariant.Modal}
 			type="number"
-			bind:value={z as number}
+			value={z ?? ''}
+			oninput={handleInput('z')}
 			{onblur}
 			{onfocus}
 			{onkeydown}
-			{oninput}
-			bind:this={inputRef}
+			bind:this={inputRefs.z}
 			{placeholder}
 			{required}
 			{disabled}
@@ -419,7 +405,7 @@ input[type=number] {
 input::-webkit-outer-spin-button,
 input::-webkit-inner-spin-button {
   -webkit-appearance: none;
-  margin: 0; /* <-- Apparently some margin are still there even though it's hidden */
+  margin: 0;
 }
 
 .error-wrapper {

package/dist/Components/DimensionInput.svelte.d.ts

@@ -1,4 +1,4 @@
 import type { DimensionInputProps } from './DimensionInputProps.js';
-declare const DimensionInput: import("svelte").Component<DimensionInputProps, {}, "x" | "y" | "z" | "inputRef">;
+declare const DimensionInput: import("svelte").Component<DimensionInputProps, {}, "x" | "z" | "y" | "inputRefs">;
 type DimensionInput = ReturnType<typeof DimensionInput>;
 export default DimensionInput;

package/dist/Components/DimensionInputProps.d.ts

@@ -1,29 +1,64 @@
 import type { InputVariant } from '../Types/Internal/InputVariant.js';
 import type { Centimetres } from '../Types/Internal/Misc.js';
-import type { FormEventHandler } from 'svelte/elements';
 import type { PartialIconProps } from './PartialIconProps.js';
+/**
+ * Per-axis refs to the three underlying number inputs. Each property is
+ * bindable independently so consumers can drive focus/showPicker on a
+ * specific axis. Replaces the previous single `inputRef` that exhibited
+ * a last-write-wins bug.
+ */
+export interface DimensionInputRefs {
+    x?: HTMLInputElement | undefined;
+    y?: HTMLInputElement | undefined;
+    z?: HTMLInputElement | undefined;
+}
 export interface DimensionInputProps {
+    /** Optional id prefix. The three inputs receive `${id}-x|-y|-z`. */
     id?: string | undefined;
+    /** Bindable centimetre value for the x axis. */
     x: Centimetres | null;
+    /** Bindable centimetre value for the y axis. */
     y: Centimetres | null;
+    /** Bindable centimetre value for the z axis. */
     z: Centimetres | null;
-    max?: number | undefined;
+    /** Inclusive maximum value, in centimetres. */
+    max?: Centimetres | undefined;
+    /** Visible top label. Defaults to "Dimensions". */
     labelTop?: string | undefined;
+    /** When true, the visible "- optional" suffix is rendered. */
+    optional?: boolean;
+    /** Placeholder forwarded to each underlying input. */
     placeholder?: string | undefined;
+    /** Whether the input is required for form submission. */
     required?: boolean;
+    /** Visual variant. */
     variant?: InputVariant;
+    /** Whether to permit decimal values (relaxes native step to 0.01). */
     decimal?: boolean;
+    /** Force the invalid visual state. */
     invalid?: boolean;
+    /** When true, error colours are shown for the invalid state. */
     showErrorColours?: boolean;
+    /** Whether the inputs are disabled. */
     disabled?: boolean | undefined;
+    /** Optional left-positioned icon. */
     leftIcon?: PartialIconProps | undefined;
+    /** Optional right-positioned icon. */
     rightIcon?: PartialIconProps | undefined;
+    /** Click handler for the left icon. */
     onLeftIconClick?: (() => void) | undefined;
+    /** Click handler for the right icon. */
     onRightIconClick?: (() => void) | undefined;
-    inputRef?: HTMLInputElement | undefined;
+    /** Per-axis bindable refs. Replaces single-input inputRef. */
+    inputRefs?: DimensionInputRefs;
+    /** Forwarded `data-type` attribute. */
     'data-type'?: string;
+    /** Blur handler. */
     onblur?: (e: FocusEvent) => void;
+    /** Focus handler. */
     onfocus?: (e: FocusEvent) => void;
+    /** Keydown handler forwarded to each input. */
     onkeydown?: (e: KeyboardEvent) => void;
-    oninput?: FormEventHandler<HTMLInputElement>;
+    /** Per-axis change callback. */
+    onchange?: (axis: 'x' | 'y' | 'z', value: Centimetres | null) => void;
 }