@lavalogic/scoria 0.35.0 → 0.37.0

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

@@ -1,186 +1,172 @@
-<svelte:options runes />
-
-<script lang="ts">
-	import { InputVariant } from '../Types/Internal/InputVariant.js';
-	import type { Centimetres } from '../Types/Internal/Misc.js';
-	import type { DimensionInputProps } from './DimensionInputProps.js';
-
-	const min = 0;
-	let {
-		id,
-		x = $bindable(null),
-		y = $bindable(null),
-		z = $bindable(null),
-
-		// labelTop,
-		// rightIcon,
-		// onLeftIconClick,
-		// onRightIconClick,
-
-		max,
-		placeholder,
-		required = false,
-		variant = InputVariant.Default,
-		decimal = false,
-		invalid = false,
-		showErrorColours = false,
-		disabled,
-
-		leftIcon,
-
-		onblur,
-		onfocus,
-		onkeydown,
-		oninput,
-
-		inputRef = $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 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;
-			},
-		};
-	}
-	// ^
-
-	let isInvalid = $derived(
-		showErrorColours &&
-			((required &&
-				(x == null ||
-					x.toString().trim() === '' ||
-					y == null ||
-					y.toString().trim() === '' ||
-					z == null ||
-					z.toString().trim() === '')) ||
-				invalid)
-	);
-</script>
-
-<div
-	class="error-wrapper"
-	class:for-modal={variant == InputVariant.Modal}
-	class:for-table={variant == InputVariant.Table}
->
-	<span
-		class="top-label"
-		class:for-default={variant === InputVariant.Default}
-		class:invalid={isInvalid}>Dimensions - <span class="optional">optional</span></span
-	>
-	{#if variant === InputVariant.Default}
-		<span class="border">Dimensions - <span class="optional">optional</span></span>
-	{/if}
-	<!-- style="--background-colour: {leftIcon?.backgroundColour ?? rightIcon?.backgroundColour};" -->
-	<div
-		class="icon-container"
-		class:for-modal={variant == InputVariant.Modal}
-	>
-		<input
-			{id}
-			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}
-			{onblur}
-			{onfocus}
-			{onkeydown}
-			{oninput}
-			bind:this={inputRef}
-			{placeholder}
-			{required}
-			{disabled}
-			{min}
-			{max}
-			step={decimal ? 0.01 : 1}
-		/>
-		<input
-			{id}
-			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}
-			{onblur}
-			{onfocus}
-			{onkeydown}
-			{oninput}
-			bind:this={inputRef}
-			{placeholder}
-			{required}
-			{disabled}
-			{min}
-			{max}
-			step={decimal ? 0.01 : 1}
-		/>
-		<input
-			{id}
-			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}
-			{onblur}
-			{onfocus}
-			{onkeydown}
-			{oninput}
-			bind:this={inputRef}
-			{placeholder}
-			{required}
-			{disabled}
-			{min}
-			{max}
-			step={decimal ? 0.01 : 1}
-		/>
-		<div class="spacer"></div>
-		<span
-			class="right-label inset"
-			class:for-modal={variant == InputVariant.Modal}>cm</span
-		>
-	</div>
-</div>
-
+<svelte:options runes />
+
+<script lang="ts">
+	import { InputVariant } from '../Types/Internal/InputVariant.js';
+	import type { Centimetres } from '../Types/Internal/Misc.js';
+	import type { DimensionInputProps } from './DimensionInputProps.js';
+
+	const min = 0;
+	let {
+		id,
+		x = $bindable(null),
+		y = $bindable(null),
+		z = $bindable(null),
+
+		max,
+		labelTop = 'Dimensions',
+		optional = true,
+		placeholder,
+		required = false,
+		variant = InputVariant.Default,
+		decimal = false,
+		invalid = false,
+		showErrorColours = false,
+		disabled,
+
+		leftIcon,
+
+		onblur,
+		onfocus,
+		onkeydown,
+		// oninput intentionally not forwarded; per-axis handleInput wires it.
+		onchange,
+
+		inputRefs = $bindable({}),
+		'data-type': dataType,
+	}: DimensionInputProps = $props();
+
+	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 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);
+		};
+	}
+
+	const isInvalid = $derived(
+		showErrorColours &&
+			((required &&
+				(x == null ||
+					x.toString().trim() === '' ||
+					y == null ||
+					y.toString().trim() === '' ||
+					z == null ||
+					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
+	class="error-wrapper"
+	class:for-modal={variant == InputVariant.Modal}
+	class:for-table={variant == InputVariant.Table}
+>
+	<span
+		class="top-label"
+		class:for-default={variant === InputVariant.Default}
+		class:invalid={isInvalid}
+		>{labelTop}{#if optional}
+			- <span class="optional">optional</span>{/if}</span
+	>
+	{#if variant === InputVariant.Default}
+		<span class="border"
+			>{labelTop}{#if optional}
+				- <span class="optional">optional</span>{/if}</span
+		>
+	{/if}
+	<div
+		class="icon-container"
+		class:for-modal={variant == InputVariant.Modal}
+	>
+		<input
+			id={xId}
+			class:for-default={variant === InputVariant.Default}
+			data-type={dataType}
+			class:left-pad={leftIcon != undefined}
+			class:for-modal={variant == InputVariant.Modal}
+			type="number"
+			value={x ?? ''}
+			oninput={handleInput('x')}
+			{onblur}
+			{onfocus}
+			{onkeydown}
+			bind:this={inputRefs.x}
+			{placeholder}
+			{required}
+			{disabled}
+			{min}
+			{max}
+			step={decimal ? 0.01 : 1}
+		/>
+		<input
+			id={yId}
+			class:for-default={variant === InputVariant.Default}
+			data-type={dataType}
+			class:left-pad={leftIcon != undefined}
+			class:for-modal={variant == InputVariant.Modal}
+			type="number"
+			value={y ?? ''}
+			oninput={handleInput('y')}
+			{onblur}
+			{onfocus}
+			{onkeydown}
+			bind:this={inputRefs.y}
+			{placeholder}
+			{required}
+			{disabled}
+			{min}
+			{max}
+			step={decimal ? 0.01 : 1}
+		/>
+		<input
+			id={zId}
+			class:for-default={variant === InputVariant.Default}
+			data-type={dataType}
+			class:left-pad={leftIcon != undefined}
+			class:for-modal={variant == InputVariant.Modal}
+			type="number"
+			value={z ?? ''}
+			oninput={handleInput('z')}
+			{onblur}
+			{onfocus}
+			{onkeydown}
+			bind:this={inputRefs.z}
+			{placeholder}
+			{required}
+			{disabled}
+			{min}
+			{max}
+			step={decimal ? 0.01 : 1}
+		/>
+		<div class="spacer"></div>
+		<span
+			class="right-label inset"
+			class:for-modal={variant == InputVariant.Modal}>cm</span
+		>
+	</div>
+</div>
+
 <style>input {
   box-sizing: border-box;
   height: 100%;
@@ -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 {
@@ -459,4 +445,4 @@ div.spacer {
 .icon-container input:last-of-type {
   border-radius: 0;
   border-left-color: transparent;
-}</style>
+}</style>

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;
 }