@lavalogic/scoria 0.36.0 → 0.37.0

package/dist/Components/SingleSelect.svelte

@@ -1,7 +1,11 @@
 <svelte:options runes />
 
-<script lang="ts" generics="V extends object, VP extends ValueProp<V>">
-	import { devCatch, generateShortUUID, vowels } from '../Helpers/Helpers.svelte.js';
+<script
+	lang="ts"
+	generics="V extends object, VP extends ValueProp<V>"
+>
+	import { devCatch, generateWeakId, vowels } from '../Helpers/Helpers.svelte.js';
+	import { attachDropdownPortal } from '../Helpers/dropdownPortal.js';
 	import { Colour, ColourSet } from '../scss/colours.js';
 	import type { ValueProp } from '../Types/Internal/Misc.js';
 	import { Size } from '../Types/Internal/Size.js';
@@ -32,74 +36,49 @@
 		borderless = false,
 		lazyDropdown = false,
 		forceUpwards = false,
-		inputId = generateShortUUID(),
+		inputId = generateWeakId(),
 		value: selectedValue,
 		onchange,
-		// onkeydown, // TODO
 		onfocus,
-		onCreateOption
+		onCreateOption,
 	}: SingleSelectProps<V, VP> = $props();
 
-	// FIXME this in combination with the effect may trigger a double assignment on mount. We will need to test it.
-
-	let currentValue = $derived(selectedValue);
+	// Single source of truth for the current value. The previous code mixed
+	// `$derived` and `$effect.pre`, which fired a redundant assignment on mount.
+	const currentValue = $derived(selectedValue);
 	let ref = $state<Svelecte | undefined>();
 	let wrapperRef: HTMLDivElement | undefined = $state();
 
-	$effect.pre(() => {
-		void options;
-		void selectedValue;
-		currentValue = selectedValue;
-	});
-
-	// WARN this is potentially duplicating existing logic
-	// $effect.pre(() => {
-	// 	if (selectedValue) {
-	// 		const found = options.find((opt) => opt[valueProp] === selectedValue[valueProp]);
-	// 		debugger;
-	// 		if (!found) {
-	// 			onCreateOption?.(selectedValue);
-	// 		} else {
-	// 			console.log(options);
-	// 		}
-	// 	}
-	// });
-
 	const an = $derived(name && vowels.has(name.at(0)?.toLocaleLowerCase() ?? '') ? 'an' : 'a');
 
 	const isInvalid = $derived((required && !currentValue) || invalid);
 
 	let hasAutoFocused = $state(false);
-	const dropdownBottom = $derived(wrapperRef ? wrapperRef.getBoundingClientRect().height : 0);
+
+	// ResizeObserver-driven height. Replaces the layout-forcing
+	// `getBoundingClientRect()` call that used to run inside a `$derived`.
+	let dropdownBottom = $state(0);
+	$effect(() => {
+		if (!wrapperRef) {
+			return;
+		}
+		const ro = new ResizeObserver((entries) => {
+			const entry = entries[0];
+			dropdownBottom = entry.borderBoxSize[0].blockSize;
+		});
+		ro.observe(wrapperRef);
+		return () => {
+			ro.disconnect();
+		};
+	});
 
 	function forceShowDropdown(input: HTMLInputElement) {
 		if (focusOnLoad && !hasAutoFocused) {
 			hasAutoFocused = true;
-
 			input.click();
-
-			// HACK. the default selectOnTab functionality selects the highlighted element,
-			// this selects the first element on the list
-			// please decide which one we'll be using and be consistent
-			// input.addEventListener('keydown', (e) => {
-			// 	onkeydown(e)
-			// if (e.key === 'Tab') {
-			// 	const inputElement = e.target as HTMLInputElement | undefined;
-			// 	if (inputElement && inputElement.value.trim()) {
-			// 		(
-			// 			inputElement?.parentElement?.parentElement?.parentElement?.parentElement?.querySelector(
-			// 				'[data-pos="0"]' //first element from dropdown
-			// 			) as HTMLElement | undefined
-			// 		)?.click();
-			// 	} else if (optional) {
-			// 		dispatch('change', null);
-			// 	}
-			// }
-			// });
 		}
 	}
 
-	// let hidden = $state(false);
 	let isExpanded = $state(false);
 
 	onMount(() => {
@@ -112,15 +91,12 @@
 		}
 
 		const input = document.getElementById(inputId);
-		// input?.addEventListener('focus', () => {
-		// 	hidden = true;
-		// });
-		// input?.addEventListener('blur', () => {
-		// 	hidden = false;
-		// });
+		const svelecteRoot = input?.closest('div.svelecte') as HTMLElement | null;
+		const dropdownRef =
+			(svelecteRoot?.querySelector('.sv_dropdown') as HTMLElement | null) ?? undefined;
 
-		// HACK callback for is-open on/off
-		const dropdownRef = input?.closest('div.svelecte')?.querySelector('.sv_dropdown') ?? undefined;
+		// HACK callback for is-open on/off. Drives the chevron
+		// rotation / clear icon visibility below.
 		const observer = new MutationObserver((mutations: Array<MutationRecord>) => {
 			for (let i = mutations.length - 1; i > -1; i--) {
 				const mutation = mutations[i];
@@ -134,22 +110,26 @@
 			observer.observe(dropdownRef, { attributes: true });
 		}
 
+		// Teleport the dropdown to `document.body` while open so it
+		// escapes every ancestor `overflow` / `transform` / `z-index`
+		// stacking context (filter-panel groups, sticky table strips,
+		// modals, etc.). The portal helper also auto-flips upwards
+		// when there is not enough space below the trigger and
+		// repositions on scroll / resize. See
+		// `Helpers/dropdownPortal.ts` for the full rationale.
+		const detachPortal = attachDropdownPortal({
+			getTrigger: () => svelecteRoot,
+			getDropdown: () => dropdownRef,
+		});
+
 		return () => {
 			observer.disconnect();
+			detachPortal();
 		};
 	});
 
-	// function onChange(v: V | null) {
-	// 	if (clearable || v != null) {
-	// 		onchange(v ?? null);
-	// 	} else {
-	// 		currentValue = null;
-	// 		currentValue = selectedValue;
-	// 	}
-	// }
-
-	function isObject(value: SingleSelectProps<V, VP>['value']): value is V | null {
-		return typeof value == 'object';
+	function isObject(value: SingleSelectProps<V, VP>['value']): value is V {
+		return value !== null && typeof value === 'object';
 	}
 </script>
 
@@ -195,7 +175,18 @@
 		{lazyDropdown}
 		value={// eslint-disable-next-line @typescript-eslint/no-explicit-any
 		currentValue as Array<any>}
-		onChange={onchange}
+		onChange={(newValue: V | null) => {
+			// svelecte always emits the full option object regardless of
+			// `valueAsObject`. Map to the shape the discriminated variant
+			// promised: primitive for AsPrimitive, object for AsObject.
+			if (valueAsObject) {
+				void (onchange as (v: V | null) => void | Promise<void>)(newValue);
+			} else {
+				const primitive = newValue == null ? null : newValue[valueProp];
+				// eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
+				void (onchange as (v: V[VP] | null) => void | Promise<void>)(primitive);
+			}
+		}}
 		{searchable}
 		selectOnTab
 		keepSelectionInList
@@ -213,14 +204,14 @@
 								e.stopPropagation();
 							}
 
-							onchange(null);
+							void onchange(null);
 						}}
 						{disabled}
 						colourSet={ColourSet.Auxiliary}
 						size={Size.Small}
 						icon={{
 							name: 'close-menu-cross',
-							colour: Colour['$ui-blue-10']
+							colour: Colour['$ui-blue-10'],
 						}}
 					/>
 				{/if}
@@ -232,24 +223,22 @@
 					{disabled}
 					icon={{
 						name: isExpanded ? 'chevron-up' : 'chevron-down',
-						colour: Colour['$ui-blue-10']
+						colour: Colour['$ui-blue-10'],
 					}}
 				/>
 			</div>
 		{/snippet}
 		{#snippet toggleIcon()}
 			<div class="nothing"></div>
-			<!-- <div class="icon-bg">
-				<Icon name="chevron-down" size={Size.MediumSmall} />
-			</div> -->
 		{/snippet}
 
 		{#snippet selection(/*_selectedOptions: Array<any>*/)}
-			<!-- <span class="selection">hello</span> -->
-
-			<span class="selection" class:invalid={isInvalid}>
+			<span
+				class="selection"
+				class:invalid={isInvalid}
+			>
 				{#if isObject(selectedValue)}
-					{selectedValue?.[labelProp]}
+					{selectedValue[labelProp]}
 				{:else}
 					{options.find((it) => it[valueProp] === selectedValue)?.[labelProp]}
 				{/if}
@@ -326,24 +315,13 @@
   max-height: 100%;
   box-sizing: border-box;
 }
-.select-wrapper :global(.sv-item--content) {
-  font-size: 0.875rem;
-}
-.select-wrapper :global(.sv-item--wrap.in-dropdown) {
-  cursor: pointer;
-  min-height: 40px;
-  align-items: center;
-}
-.select-wrapper :global(.sv-item--content) {
-  min-height: 1.2rem;
-}
 .select-wrapper :global(.sv-btn-indicator) {
   cursor: pointer;
 }
 .select-wrapper.no-border {
   --sv-border: none;
 }
-.select-wrapper .select-wrapper.force-upwards :global .sv_dropdown.is-open {
+.select-wrapper.force-upwards :global .sv_dropdown.is-open {
   bottom: var(--dropdown-bottom);
 }
 .select-wrapper :global .sv-control {
@@ -364,32 +342,18 @@
 .select-wrapper :global .svelecte.svelecte-control {
   cursor: pointer;
 }
-.select-wrapper :global .sv-item--wrap.in-dropdown {
-  cursor: pointer;
-  min-height: 40px;
-  align-items: center;
-}
-.select-wrapper :global .sv-item--content {
-  min-height: 1.2rem;
-}
 .select-wrapper :global span {
   transition: border-color ease-out 0.15s 0s, background-color ease-out 0.15s 0s, color ease-out 0.15s 0s, fill ease-out 0.15s 0s;
 }
 .select-wrapper :global .sv-control {
   transition: border-color ease-out 0.15s 0s, background-color ease-out 0.15s 0s, color ease-out 0.15s 0s, fill ease-out 0.15s 0s;
 }
-.select-wrapper :global div.sv_dropdown.is-open {
-  z-index: 99;
-}
 .select-wrapper div.nothing {
   height: 0;
   width: 0;
 }
-.select-wrapper .dropdown-item,
 .select-wrapper .selection {
   font-size: 0.875rem;
-}
-.select-wrapper .selection {
   padding-left: 0.5rem;
   white-space: nowrap;
   display: flex;
@@ -413,22 +377,36 @@ div.icons {
   box-sizing: border-box;
 }
 
-.dropdown-item {
+:global .sv-item--wrap.in-dropdown {
+  cursor: pointer;
+  min-height: 40px;
+  align-items: center;
+}
+:global .sv-item--content {
+  font-size: 0.875rem;
+  min-height: 1.2rem;
+}
+:global div.sv_dropdown.is-open {
+  z-index: 99;
+}
+
+:global(.dropdown-item) {
   display: flex;
   flex-flow: row nowrap;
   width: 100%;
   overflow: hidden;
   text-overflow: ellipsis;
   gap: 1rem;
+  font-size: 0.875rem;
   fill: #259fc7;
 }
-.dropdown-item .toggle-icon {
+:global(.dropdown-item) .toggle-icon {
   display: flex;
   align-items: center;
   justify-content: center;
   flex-flow: column nowrap;
   opacity: 0;
 }
-.dropdown-item .toggle-icon.yes {
+:global(.dropdown-item) .toggle-icon.yes {
   opacity: 1;
 }</style>

package/dist/Components/SingleSelectCommonProps.d.ts

@@ -1,27 +1,65 @@
-import type { NonNullableKey, ValueProp } from '../Types/Internal/Misc.js';
+import type { CssLength, NonNullableKey, ValueProp } from '../Types/Internal/Misc.js';
 export interface SingleSelectCommonProps<V extends object, VP extends ValueProp<V>> {
+    /** Options to display. */
     options: Array<V>;
+    /** Key of `V` whose value is the label string. */
     labelProp: NonNullableKey<V>;
+    /** Key of `V` whose value is the unique identifier. */
     valueProp: VP;
-    onchange: (newValue: V | null) => void;
+    /** Singular display name. */
     name?: string;
-    width?: string;
-    height?: string;
+    /**
+     * CSS width override. Interpolated into a CSS custom property.
+     *
+     * BREAKING (Phase 7.7): was `string`; now requires the `CssLength`
+     * brand. Use the `cssLength('...')` helper.
+     */
+    width?: CssLength;
+    /**
+     * CSS height override. Interpolated into a CSS custom property.
+     *
+     * BREAKING (Phase 7.7): was `string`; now requires the `CssLength`
+     * brand. Use the `cssLength('...')` helper.
+     */
+    height?: CssLength;
+    /** Top label. */
     label?: string;
-    minHeight?: string;
+    /**
+     * Minimum height for the wrapper.
+     *
+     * BREAKING (Phase 7.7): was `string`; now requires the `CssLength`
+     * brand. Use the `cssLength('...')` helper. Defaults to `'2rem'`
+     * inside the component when omitted.
+     */
+    minHeight?: CssLength;
+    /** Focus the input on mount. */
     focusOnLoad?: boolean;
+    /** Allow keyboard search. */
     searchable?: boolean;
+    /** Allow creating new options. */
     creatable?: boolean;
+    /** Called when the user creates a new option. */
     onCreateOption?: (option: V) => void;
+    /** When true, an "x" clears the selection. */
     clearable?: boolean;
+    /** Disable the input. */
     disabled?: boolean;
+    /** When true, render without a border. */
     borderless?: boolean;
+    /** Force the dropdown to render upwards. */
     forceUpwards?: boolean;
+    /** Delay dropdown DOM until first open. */
     lazyDropdown?: boolean;
+    /** Whether a selection is required. */
     required?: boolean;
+    /** Force the invalid visual state. */
     invalid?: boolean;
+    /** DOM id of the underlying input. */
     inputId?: string;
+    /** Filter for candidate user-created options. */
     createFilter?: (value: string) => boolean;
+    /** Keydown handler. Reserved. */
     onkeydown?: (e: KeyboardEvent) => void;
+    /** Focus handler invoked with the input element. */
     onfocus?: (target: HTMLInputElement) => void;
 }

package/dist/Components/SingleSelectPropsAsObject.d.ts

@@ -1,6 +1,13 @@
 import type { ValueProp } from '../Types/Internal/Misc.js';
 import type { SingleSelectCommonProps } from './SingleSelectCommonProps.js';
 export interface SingleSelectPropsAsObject<V extends object, VP extends ValueProp<V>> extends SingleSelectCommonProps<V, VP> {
+    /** Discriminator: when `true`, the bound `value` is the full option object. */
     valueAsObject: true;
+    /** Currently selected option, or null. */
     value: V | null;
+    /**
+     * Called when the selection changes. Receives the full option object
+     * (or null) because `valueAsObject` is `true`.
+     */
+    onchange: (newValue: V | null) => void | Promise<void>;
 }

package/dist/Components/SingleSelectPropsAsPrimitive.d.ts

@@ -1,6 +1,14 @@
 import type { ValueProp } from '../Types/Internal/Misc.js';
 import type { SingleSelectCommonProps } from './SingleSelectCommonProps.js';
 export interface SingleSelectPropsAsPrimitive<V extends object, VP extends ValueProp<V>> extends SingleSelectCommonProps<V, VP> {
+    /** Discriminator: when `false`, the bound `value` is `V[VP]`. */
     valueAsObject: false;
+    /** Currently selected primitive value, or null. */
     value: V[VP] | null;
+    /**
+     * Called when the selection changes. Receives the primitive key value
+     * (`V[VP]`) or null because `valueAsObject` is `false`. Do NOT read
+     * `.value` off the argument -- it is already the primitive.
+     */
+    onchange: (newValue: V[VP] | null) => void | Promise<void>;
 }

package/dist/Components/StepButton.svelte

@@ -4,95 +4,45 @@
 	lang="ts"
 	generics="Args"
 >
-	import { TooltipContext } from '../Contexts/TooltipContext.svelte.js';
-
-	import { Delay } from '../Delay/Delay.js';
-	import { devCatch } from '../Helpers/Helpers.svelte.js';
+	import { useAsyncFlag } from '../Helpers/AsyncFlag.svelte.js';
+	import { useTooltip } from '../Helpers/useTooltip.svelte.js';
 	import { Colour } from '../scss/colours.js';
 	import { Side } from '../Types/Internal/Side.js';
 	import { Size } from '../Types/Internal/Size.js';
-	import { getContext } from 'svelte';
 	import Icon from './Icon.svelte';
 	import type { StepButtonProps } from './StepButtonProps.js';
 
-	let { option, selected, index }: StepButtonProps<Args> = $props();
-
-	let disabled = $state(true);
-	let visible = $state(true);
-	let isValid = $state(true);
+	const { option, selected, index }: StepButtonProps<Args> = $props();
 
-	const tooltipContext = getContext<TooltipContext>(TooltipContext.identifier);
+	const isValid = useAsyncFlag(() => option.isValid, true);
+	const disabled = useAsyncFlag(() => option.disabled, false);
+	const visible = useAsyncFlag(() => option.visible, true);
 
-	$effect(() => {
-		if (typeof option.isValid === 'boolean') {
-			isValid = option.isValid;
-		} else {
-			option.isValid
-				?.then((v) => {
-					isValid = v;
-				})
-				.catch(devCatch);
-		}
-	});
-	$effect(() => {
-		if (typeof option.disabled === 'boolean') {
-			disabled = option.disabled;
-		} else if (option.disabled == undefined) {
-			disabled = false;
-		} else {
-			option.disabled
-				.then((v) => {
-					disabled = v;
-				})
-				.catch(devCatch);
-		}
-	});
-
-	$effect(() => {
-		if (typeof option.visible === 'boolean') {
-			visible = option.visible;
-		} else if (option.visible == undefined) {
-			visible = true;
-		} else {
-			option.visible
-				.then((v) => {
-					visible = v;
-				})
-				.catch(devCatch);
-		}
+	// Shared tooltip lifecycle: hover handlers plus unmount-time teardown
+	// (load-bearing because StepButton lives inside StepForm which
+	// re-renders the tab strip on every step change).
+	const tt = useTooltip({
+		text: () => option.label,
+		arrow: () => Side.Top,
 	});
 </script>
 
 <button
 	class:selected
-	{disabled}
+	disabled={disabled.value}
 	onclick={() => {
 		option.onclick();
 	}}
 	type="button"
 	class="tab"
-	class:invalid={!isValid}
-	class:hidden={!visible}
-	onmouseenter={(e) => {
-		if (option.label) {
-			const rect = (e.target as HTMLButtonElement).getBoundingClientRect();
-			tooltipContext.showTooltip({
-				text: option.label,
-				arrow: Side.Top,
-				delay: Delay.Default,
-				rect,
-			});
-		}
-	}}
-	onmouseleave={() => {
-		if (option.label) {
-			tooltipContext.hideTooltip(option.label);
-		}
-	}}
+	class:invalid={!isValid.value}
+	class:hidden={!visible.value}
+	onmouseenter={tt.onmouseenter}
+	onmouseleave={tt.onmouseleave}
 >
 	<div
 		class="bordered"
-		class:invalid={!isValid}
+		class:invalid={!isValid.value}
 	>
 		{#if option.iconLeft}
 			<Icon
@@ -101,7 +51,7 @@
 			/>
 		{/if}
 		{index + 1}
-		{#if !isValid}
+		{#if !isValid.value}
 			<Icon
 				name="error"
 				colour={Colour['$error-border']}