@lavalogic/scoria 0.35.0 → 0.37.0

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

@@ -1,122 +1,72 @@
-<svelte:options runes />
-
-<script
-	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 { 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 tooltipContext = getContext<TooltipContext>(TooltipContext.identifier);
-
-	$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);
-		}
-	});
-</script>
-
-<button
-	class:selected
-	{disabled}
-	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);
-		}
-	}}
->
-	<div
-		class="bordered"
-		class:invalid={!isValid}
-	>
-		{#if option.iconLeft}
-			<Icon
-				{...option.iconLeft}
-				colour={Colour['$brand-primary']}
-			/>
-		{/if}
-		{index + 1}
-		{#if !isValid}
-			<Icon
-				name="error"
-				colour={Colour['$error-border']}
-				size={Size.Small}
-			/>
-		{:else if option.iconRight}
-			<Icon
-				colour={Colour['$brand-primary']}
-				size={Size.Small}
-				{...option.iconRight}
-			/>
-		{/if}
-	</div>
-</button>
-
+<svelte:options runes />
+
+<script
+	lang="ts"
+	generics="Args"
+>
+	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 Icon from './Icon.svelte';
+	import type { StepButtonProps } from './StepButtonProps.js';
+
+	const { option, selected, index }: StepButtonProps<Args> = $props();
+
+	const isValid = useAsyncFlag(() => option.isValid, true);
+	const disabled = useAsyncFlag(() => option.disabled, false);
+	const visible = useAsyncFlag(() => option.visible, true);
+
+	// 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.value}
+	onclick={() => {
+		option.onclick();
+	}}
+	type="button"
+	class="tab"
+	class:invalid={!isValid.value}
+	class:hidden={!visible.value}
+	onmouseenter={tt.onmouseenter}
+	onmouseleave={tt.onmouseleave}
+>
+	<div
+		class="bordered"
+		class:invalid={!isValid.value}
+	>
+		{#if option.iconLeft}
+			<Icon
+				{...option.iconLeft}
+				colour={Colour['$brand-primary']}
+			/>
+		{/if}
+		{index + 1}
+		{#if !isValid.value}
+			<Icon
+				name="error"
+				colour={Colour['$error-border']}
+				size={Size.Small}
+			/>
+		{:else if option.iconRight}
+			<Icon
+				colour={Colour['$brand-primary']}
+				size={Size.Small}
+				{...option.iconRight}
+			/>
+		{/if}
+	</div>
+</button>
+
 <style>button.tab.hidden {
   display: none !important;
 }
@@ -157,4 +107,4 @@
   color: #aa1414;
   border-color: #aa1414;
   background-color: #f9e9e9;
-}</style>
+}</style>

package/dist/Components/StepForm.svelte

@@ -1,110 +1,142 @@
-<svelte:options runes />
-
-<script
-	lang="ts"
-	generics="CommonDenominator"
->
-	import { ColourSet } from '../scss/colours.js';
-	import { Size } from '../Types/Internal/Size.js';
-	import { onMount, untrack } from 'svelte';
-	import Button from './Button.svelte';
-	import StepButton from './StepButton.svelte';
-	import type { StepFormProps } from './StepFormProps.js';
-
-	let { name, steps, currentStep, noscroll = false }: StepFormProps<CommonDenominator> = $props();
-
-	onMount(() => {
-		if (name) {
-			const tabName = sessionStorage.getItem(`${name}-active-tab`);
-			if (tabName) {
-				steps.find((it) => it.label === tabName)?.onclick();
-			}
-		}
-	});
-
-	const indexOfCurrent = $derived(currentStep ? steps.indexOf(currentStep) : -1);
-
-	const previous = $derived.by(() => {
-		for (let i = indexOfCurrent - 1; i > -1; i--) {
-			const next = steps.at(i);
-
-			if (next == null || !next.disabled || next.visible != false) {
-				return next ?? null;
-			}
-		}
-		return null;
-	});
-
-	const next = $derived.by(() => {
-		for (let i = indexOfCurrent + 1; i < steps.length; i++) {
-			const next = steps.at(i);
-
-			if (next == null || !next.disabled || next.visible != false) {
-				return next ?? null;
-			}
-		}
-		return null;
-	});
-
-	$effect(() => {
-		if (name && currentStep) {
-			untrack(() => {
-				sessionStorage.setItem(`${name}-active-tab`, currentStep.label);
-			});
-		}
-	});
-</script>
-
-<div
-	class:noscroll
-	class="wrapper"
->
-	<div class="tabs">
-		{#each steps as option, index (index)}
-			<StepButton
-				{option}
-				{index}
-				selected={currentStep?.label === option.label}
-			/>
-		{/each}
-		<div class="divider"></div>
-
-		<div class="steps">
-			<Button
-				size={Size.Small}
-				fullWidth
-				disabled={!previous}
-				onclick={() => {
-					previous?.onclick();
-				}}
-				colourSet={ColourSet.Secondary}>Previous</Button
-			>
-			<Button
-				size={Size.Small}
-				fullWidth
-				onclick={() => {
-					next?.onclick();
-				}}
-				disabled={!next}
-				colourSet={ColourSet.Primary}>Next</Button
-			>
-		</div>
-	</div>
-
-	<div
-		class:noscroll
-		class="content"
-	>
-		{#if currentStep}
-			{@render currentStep.content(currentStep.args)}
-		{:else}
-			<div class="wrapper bg">
-				<span class="red">No Step Selected</span>
-			</div>
-		{/if}
-	</div>
-</div>
-
+<svelte:options runes />
+
+<script
+	lang="ts"
+	generics="CommonDenominator"
+>
+	import { readJSON } from '../Helpers/Storage.js';
+	import { ColourSet } from '../scss/colours.js';
+	import { Size } from '../Types/Internal/Size.js';
+	import { onMount, untrack } from 'svelte';
+	import Button from './Button.svelte';
+	import StepButton from './StepButton.svelte';
+	import type { StepFormProps } from './StepFormProps.js';
+
+	const {
+		name,
+		steps,
+		currentStep,
+		noscroll = false,
+		noStepMessage = 'No Step Selected',
+	}: StepFormProps<CommonDenominator> = $props();
+
+	const isNonEmptyString = (raw: unknown): raw is string =>
+		typeof raw === 'string' && raw.length > 0;
+
+	const storageKey = (key: string): string => `scoria-step-form:${key}:active-step`;
+
+	onMount(() => {
+		if (name) {
+			const tabName = readJSON(sessionStorage, storageKey(name), isNonEmptyString, '');
+			if (tabName) {
+				steps.find((it) => it.label === tabName)?.onclick();
+			}
+		}
+	});
+
+	const indexOfCurrent = $derived(currentStep ? steps.indexOf(currentStep) : -1);
+
+	const isReachable = (step: { disabled?: unknown; visible?: unknown } | undefined): boolean => {
+		if (step == null) {
+			return true;
+		}
+		// disabled may be a Promise; treat anything non-strictly-true as "reachable"
+		const disabled = step.disabled;
+		const visible = step.visible;
+		const isDisabled = disabled === true;
+		const isHidden = visible === false;
+		return !isDisabled && !isHidden;
+	};
+
+	const previous = $derived.by(() => {
+		for (let i = indexOfCurrent - 1; i > -1; i--) {
+			const candidate = steps.at(i);
+			if (candidate == null) {
+				return null;
+			}
+			if (isReachable(candidate)) {
+				return candidate;
+			}
+		}
+		return null;
+	});
+
+	const next = $derived.by(() => {
+		for (let i = indexOfCurrent + 1; i < steps.length; i++) {
+			const candidate = steps.at(i);
+			if (candidate == null) {
+				return null;
+			}
+			if (isReachable(candidate)) {
+				return candidate;
+			}
+		}
+		return null;
+	});
+
+	$effect(() => {
+		if (name && currentStep) {
+			untrack(() => {
+				try {
+					sessionStorage.setItem(storageKey(name), JSON.stringify(currentStep.label));
+				} catch {
+					// storage unavailable (private browsing, quota); persistence is best-effort
+				}
+			});
+		}
+	});
+</script>
+
+<div
+	class:noscroll
+	class="wrapper"
+>
+	<div class="tabs">
+		{#each steps as option, index (option.label)}
+			<StepButton
+				{option}
+				{index}
+				selected={currentStep?.label === option.label}
+			/>
+		{/each}
+		<div class="divider"></div>
+
+		<div class="steps">
+			<Button
+				size={Size.Small}
+				fullWidth
+				disabled={!previous}
+				onclick={() => {
+					previous?.onclick();
+				}}
+				colourSet={ColourSet.Secondary}>Previous</Button
+			>
+			<Button
+				size={Size.Small}
+				fullWidth
+				onclick={() => {
+					next?.onclick();
+				}}
+				disabled={!next}
+				colourSet={ColourSet.Primary}>Next</Button
+			>
+		</div>
+	</div>
+
+	<div
+		class:noscroll
+		class="content"
+	>
+		{#if currentStep}
+			{@render currentStep.content(currentStep.args)}
+		{:else}
+			<div class="wrapper bg">
+				<span class="red">{noStepMessage}</span>
+			</div>
+		{/if}
+	</div>
+</div>
+
 <style>.bg {
   padding: 1.5rem;
   background-color: #f9e9e9;
@@ -118,10 +150,10 @@
 .steps {
   display: flex;
   flex-flow: row nowrap;
-  width: 252px;
-  padding: 4px;
+  width: 15.75rem;
+  padding: 0.375rem;
   justify-content: center;
-  gap: 1rem;
+  gap: 1.0005rem;
 }
 
 .wrapper {
@@ -140,49 +172,17 @@
   flex-flow: row nowrap;
   overflow-x: auto;
   max-width: 100%;
-  gap: 1rem;
+  gap: 1.0005rem;
   padding-top: 0.5rem;
   padding-bottom: 0.5rem;
-  padding-left: 1.25rem;
-  padding-right: 1.25rem;
-  flex-basis: 64px;
+  padding-left: 1.250625rem;
+  padding-right: 1.250625rem;
+  flex-basis: 4rem;
   flex-shrink: 0;
   background-color: #ffffff;
   border-bottom: solid 1px #cbd4da;
   border-top: solid 2px transparent;
 }
-.wrapper .tabs .tab {
-  color: #3a4952;
-  cursor: pointer;
-  font-size: 0.875rem;
-  padding: 0;
-  background-color: transparent;
-  border: none;
-}
-.wrapper .tabs .tab .bordered {
-  border-radius: 4px;
-  padding: 0.25rem 0.75rem;
-  margin-bottom: 0.25rem;
-  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;
-  white-space: nowrap;
-  display: flex;
-  flex-flow: row nowrap;
-  align-items: center;
-  gap: 0.5rem;
-}
-.wrapper .tabs .tab .bordered.invalid {
-  color: #aa1414;
-  background-color: #f9e9e9;
-}
-.wrapper .tabs .tab.selected {
-  border-bottom-color: #259fc7;
-}
-.wrapper .tabs .tab.selected.invalid {
-  border-bottom-color: #aa1414;
-}
-.wrapper .tabs .tab:hover .bordered, .wrapper .tabs .tab.selected:hover .bordered {
-  background-color: #f4f7f9;
-}
 .wrapper .content {
   background-color: #f4f7f9;
   flex-grow: 1;
@@ -192,4 +192,4 @@
 }
 .wrapper .content.noscroll {
   overflow: visible;
-}</style>
+}</style>

package/dist/Components/StepFormProps.d.ts

@@ -1,7 +1,21 @@
+import type { ScoriaStorageKey } from '../Types/Internal/Misc.js';
 import type { TabOption } from '../Types/Internal/TabOption.js';
+/**
+ * Props for StepForm, the multi-step navigator built on StepButton.
+ * Persists the current step under `scoria-step-form:${name}:active-step` in
+ * sessionStorage when `name` is set - namespaced so it cannot collide
+ * with `VerticalTabGroup` or any future tab consumer.
+ */
 export interface StepFormProps<CommonDenominator> {
-    steps: Array<TabOption<CommonDenominator>>;
+    /** The ordered list of steps. Keyed by `option.label`. */
+    steps: ReadonlyArray<TabOption<CommonDenominator>>;
+    /** The currently active step, matched by reference. */
     currentStep: TabOption<CommonDenominator> | undefined;
-    name?: string;
+    /** When set, persist the active step's label in sessionStorage and
+     *  restore on mount. */
+    name?: ScoriaStorageKey;
+    /** Disable internal scroll containers. */
     noscroll?: boolean;
+    /** Empty-state message shown when no step is selected. */
+    noStepMessage?: string;
 }