@selvajs/ui 4.2.0 → 4.4.0

package/src/lib/compute/solve-session-core.ts

@@ -0,0 +1,102 @@
+// Pure, framework-free transition logic for a Solve Session (see CONTEXT.md).
+//
+// This module holds the value/lifecycle state machine with no Svelte runes and no
+// transport: how values are seeded (including client-sourced hydration), when a value
+// change should dispatch a solve vs. defer it, and what a reported solve result does to
+// the flags. The reactive wrapper in createSolveSession.svelte.ts is a thin shell over
+// these functions; everything testable lives here.
+
+import type { UISchema } from '@selvajs/schemas';
+import { getDefaultValue } from '../schema/defaults';
+import { getExternalInputs, type ExternalValueRef } from '../external/storage';
+import type { SolveResult } from '../types/solveFn';
+
+export interface SolveSessionState {
+	values: Record<string, unknown>;
+	error: string;
+	computeErrors: string[];
+	computeWarnings: string[];
+	meshes: unknown[];
+	/** Values changed since the last solve, in manual (instanceSolve === false) mode. */
+	pendingValues: Record<string, unknown>;
+	hasPendingChanges: boolean;
+	hasNeverSolved: boolean;
+}
+
+/** Reads a previously produced client-sourced value, or undefined if absent. */
+export type ExternalReader = (ref: ExternalValueRef) => unknown | undefined;
+
+/**
+ * Builds the initial `values` map for a schema. Non-client inputs get their declared
+ * default (falling back to the paramType default); client-sourced inputs are hydrated
+ * from `read` and left absent when no stored value exists so the missing-inputs panel
+ * can detect them. Outputs are seeded to null.
+ */
+export function buildInitialValues(
+	schema: UISchema,
+	scopeKey: string,
+	read: ExternalReader
+): Record<string, unknown> {
+	const clientSet = new Set(getExternalInputs(schema).map((e) => e.paramId));
+	const values: Record<string, unknown> = {};
+	for (const input of schema.inputs) {
+		if (clientSet.has(input.id)) {
+			const stored = read({ scopeKey, inputId: input.id });
+			if (stored !== undefined) values[input.id] = stored;
+			continue;
+		}
+		values[input.id] = input.default ?? getDefaultValue(input.paramType);
+	}
+	for (const output of schema.outputs) {
+		values[output.id] = null;
+	}
+	return values;
+}
+
+/**
+ * Initial lifecycle flags. Manual-solve schemas (instanceSolve === false) start dirty
+ * so the user must explicitly calculate; auto-solve schemas start clean.
+ */
+export function makeInitialFlags(instanceSolve: boolean | undefined): {
+	hasPendingChanges: boolean;
+	hasNeverSolved: boolean;
+} {
+	const manual = instanceSolve === false;
+	return { hasPendingChanges: manual, hasNeverSolved: manual };
+}
+
+/**
+ * Records a single value change and decides whether it should dispatch a solve now.
+ * Auto-solve mode dispatches immediately; manual mode defers (records the pending value
+ * and raises the dirty flag) and never dispatches.
+ */
+export function applyValueChange(
+	state: SolveSessionState,
+	id: string,
+	value: unknown,
+	instanceSolve: boolean | undefined
+): { state: SolveSessionState; shouldSolve: boolean } {
+	state.values[id] = value;
+	if (instanceSolve === false) {
+		state.pendingValues[id] = value;
+		state.hasPendingChanges = true;
+		return { state, shouldSolve: false };
+	}
+	return { state, shouldSolve: true };
+}
+
+/**
+ * Merges a reported solve result into the state and clears the post-solve lifecycle
+ * flags. Missing result arrays are treated as empty.
+ */
+export function applySolveResult(state: SolveSessionState, result: SolveResult): SolveSessionState {
+	state.error = '';
+	state.computeErrors = result.errors ?? [];
+	state.computeWarnings = result.warnings ?? [];
+	state.meshes = result.meshes ?? [];
+	Object.assign(state.values, result.outputs);
+	state.pendingValues = {};
+	state.hasPendingChanges = false;
+	state.hasNeverSolved = false;
+	return state;
+}

package/src/lib/constants.ts

@@ -9,8 +9,6 @@ export const APP_DEFAULTS = {
 	TIMEOUTS: {
 		/** Duration to show solving state (ms) */
 		SOLVE_STATE_DURATION: 3500,
-		/** Parameter export callback delay (ms) */
-		PARAM_EXPORT_DELAY: 100,
 		/** Drawer open/close animation duration (ms) — matches the CSS transition. */
 		DRAWER_ANIMATION_MS: 350
 	},

package/src/lib/contexts/clientSlotContext.svelte.ts

@@ -0,0 +1,33 @@
+import { getContext, setContext } from 'svelte';
+import type { Snippet } from 'svelte';
+
+// Carries the host app's slot renderer down to InputControl without threading a
+// prop through every layout layer (ComputeApp → AppLayout → TabLayout →
+// TabContent → Group → InputControl).
+//
+// An input with source.kind === 'client' and source.client.presentation === 'slot'
+// reserves its cell but renders nothing itself. Instead Selva invokes this snippet
+// so the host can render its own element (e.g. an "Edit JSON" button). Selva never
+// interprets what the host renders; `slotLabel` is passed through untouched.
+
+export interface ClientSlotArgs {
+	/** Grasshopper parameter instance GUID (LayoutItem.paramId / SchemaInput.id). */
+	inputId: string;
+	displayName: string;
+	/** Author-set label from the schema, passed through untouched. May be undefined. */
+	slotLabel?: string;
+	/** The current value held for this input (e.g. the prefilled JSON), if any. */
+	value: unknown;
+}
+
+export type ClientSlot = Snippet<[ClientSlotArgs]>;
+
+const CLIENT_SLOT_CONTEXT_KEY = Symbol('client-slot-context');
+
+export function setClientSlot(slot: ClientSlot | undefined): void {
+	setContext(CLIENT_SLOT_CONTEXT_KEY, slot);
+}
+
+export function getClientSlot(): ClientSlot | undefined {
+	return getContext<ClientSlot | undefined>(CLIENT_SLOT_CONTEXT_KEY);
+}

package/src/lib/contexts/footerContext.svelte.ts

@@ -1,11 +1,21 @@
-import { getContext, setContext } from 'svelte';
+import { getContext, setContext, type Component } from 'svelte';
 import { SvelteMap } from 'svelte/reactivity';
 
-export interface FooterItem {
+/**
+ * A footer item registered by a descendant of the root layout. `component` + `position`
+ * are fixed at registration; the renderer re-invokes `getProps` reactively, so return
+ * reactive state from it (e.g. `() => ({ status: myState.status })`) to keep the footer
+ * in sync.
+ *
+ * Generic over the component's props `P` so registration is type-checked at the call
+ * site. The store holds a heterogeneous mix of items, so its map widens `P` to
+ * `Record<string, unknown>` at the boundary.
+ */
+export interface FooterItem<P extends Record<string, unknown> = Record<string, unknown>> {
 	id: string;
-	component: any;
-	/** Called on every render — return reactive state to keep footer in sync */
-	getProps: () => Record<string, any>;
+	component: Component<P>;
+	/** Called on every render — return reactive state to keep footer in sync. */
+	getProps: () => P;
 	position: 'left' | 'right';
 	priority: number;
 	onClick?: () => void;
@@ -13,13 +23,10 @@ export interface FooterItem {
 
 export interface FooterStore {
 	items: SvelteMap<string, FooterItem>;
-	register(
-		id: string,
-		component: any,
-		getProps: () => Record<string, any>,
-		position?: 'left' | 'right',
-		priority?: number,
-		onClick?: () => void
+	/** Register (or replace) a footer item. `position`/`priority` default to 'left'/0. */
+	register<P extends Record<string, unknown>>(
+		item: Omit<FooterItem<P>, 'position' | 'priority'> &
+			Partial<Pick<FooterItem<P>, 'position' | 'priority'>>
 	): void;
 	unregister(id: string): void;
 }
@@ -31,8 +38,16 @@ export function initializeFooterContext(): FooterStore {
 
 	const store: FooterStore = {
 		items,
-		register(id, component, getProps, position = 'left', priority = 0, onClick) {
-			items.set(id, { id, component, getProps, position, priority, onClick });
+		register(item) {
+			const { id, component, getProps, position = 'left', priority = 0, onClick } = item;
+			items.set(id, {
+				id,
+				component: component as Component<Record<string, unknown>>,
+				getProps: getProps as () => Record<string, unknown>,
+				position,
+				priority,
+				onClick
+			});
 		},
 		unregister(id) {
 			items.delete(id);

package/src/lib/external/storage.test.ts

@@ -0,0 +1,99 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+	getExternalInputs,
+	writeExternalValue,
+	readExternalValue,
+	clearExternalValue
+} from './storage';
+import type { UISchema } from '@selvajs/schemas';
+
+// getExternalInputs is the gate the whole client-input feature hangs on: it decides
+// which inputs a producer route must fill. These pin the source.kind === 'client'
+// filter and the displayName fallback. The read/write helpers are also covered with a
+// sessionStorage stub, including the no-storage guard (SSR / node).
+
+const input = (paramId: string, opts: { displayName?: string; source?: { kind: string } } = {}) =>
+	({ type: 'input', paramId, ...opts }) as never;
+
+function schema(items: unknown[]): UISchema {
+	return {
+		layout: { type: 'flat', groups: [{ id: 'g', label: 'g', items }] }
+	} as unknown as UISchema;
+}
+
+describe('getExternalInputs', () => {
+	it('keeps only inputs with source.kind === client', () => {
+		const s = schema([
+			input('a', { source: { kind: 'client' } }),
+			input('b', { source: { kind: 'user' } }),
+			input('c') // no source
+		]);
+		expect(getExternalInputs(s).map((e) => e.paramId)).toEqual(['a']);
+	});
+
+	it('falls back to paramId when displayName is absent', () => {
+		const s = schema([input('a', { source: { kind: 'client' } })]);
+		expect(getExternalInputs(s)[0].displayName).toBe('a');
+	});
+
+	it('uses displayName when present', () => {
+		const s = schema([input('a', { displayName: 'Width', source: { kind: 'client' } })]);
+		expect(getExternalInputs(s)[0].displayName).toBe('Width');
+	});
+});
+
+describe('read/write/clear with a sessionStorage stub', () => {
+	afterEach(() => {
+		vi.unstubAllGlobals();
+	});
+
+	function stubStorage() {
+		const store = new Map<string, string>();
+		vi.stubGlobal('sessionStorage', {
+			getItem: (k: string) => store.get(k) ?? null,
+			setItem: (k: string, v: string) => store.set(k, v),
+			removeItem: (k: string) => store.delete(k)
+		});
+		return store;
+	}
+
+	it('round-trips a value scoped by (scopeKey, inputId)', () => {
+		const store = stubStorage();
+		writeExternalValue({ scopeKey: 's1', inputId: 'p1', value: { x: 1 } });
+		expect(readExternalValue({ scopeKey: 's1', inputId: 'p1' })).toEqual({ x: 1 });
+		expect(store.has('external:s1:p1')).toBe(true);
+	});
+
+	it('scopes values so they do not bleed across scopeKey', () => {
+		stubStorage();
+		writeExternalValue({ scopeKey: 's1', inputId: 'p1', value: 'a' });
+		expect(readExternalValue({ scopeKey: 's2', inputId: 'p1' })).toBeUndefined();
+	});
+
+	it('clear removes the value', () => {
+		stubStorage();
+		writeExternalValue({ scopeKey: 's1', inputId: 'p1', value: 'a' });
+		clearExternalValue({ scopeKey: 's1', inputId: 'p1' });
+		expect(readExternalValue({ scopeKey: 's1', inputId: 'p1' })).toBeUndefined();
+	});
+
+	it('returns undefined for malformed JSON', () => {
+		const store = stubStorage();
+		store.set('external:s1:p1', '{not json');
+		expect(readExternalValue({ scopeKey: 's1', inputId: 'p1' })).toBeUndefined();
+	});
+});
+
+describe('no-storage guard (SSR / node)', () => {
+	it('read returns undefined and write/clear no-op when sessionStorage is absent', () => {
+		// node env: sessionStorage is undefined by default
+		expect(readExternalValue({ scopeKey: 's1', inputId: 'p1' })).toBeUndefined();
+		expect(() => writeExternalValue({ scopeKey: 's1', inputId: 'p1', value: 1 })).not.toThrow();
+		expect(() => clearExternalValue({ scopeKey: 's1', inputId: 'p1' })).not.toThrow();
+	});
+
+	it('ignores empty scopeKey or inputId', () => {
+		expect(readExternalValue({ scopeKey: '', inputId: 'p1' })).toBeUndefined();
+		expect(readExternalValue({ scopeKey: 's1', inputId: '' })).toBeUndefined();
+	});
+});

package/src/lib/external/storage.ts

@@ -8,7 +8,8 @@
 //
 // inputId is the Grasshopper parameter instance GUID (LayoutItem.paramId / SchemaInput.id).
 
-import type { UISchema, LayoutItem, GroupConfig, InputSource } from '@selvajs/schemas';
+import type { UISchema } from '@selvajs/schemas';
+import { getInputItems } from '@selvajs/schemas';
 
 const STORAGE_PREFIX = 'external';
 
@@ -53,28 +54,11 @@ export interface ExternalInput {
 	displayName: string;
 }
 
-function* walkLayoutItems(schema: UISchema): Generator<LayoutItem> {
-	const groups: GroupConfig[] =
-		schema.layout.type === 'tabbed'
-			? schema.layout.tabs.flatMap((t) => t.groups)
-			: schema.layout.groups;
-	for (const group of groups) {
-		for (const item of group.items) {
-			yield item;
-		}
-	}
-}
-
 export function getExternalInputs(schema: UISchema): ExternalInput[] {
-	const result: ExternalInput[] = [];
-	for (const item of walkLayoutItems(schema)) {
-		if (item.type !== 'input') continue;
-		const source = (item as { source?: InputSource }).source;
-		if (source?.kind !== 'client') continue;
-		result.push({
+	return getInputItems(schema)
+		.filter((item) => item.source?.kind === 'client')
+		.map((item) => ({
 			paramId: item.paramId,
 			displayName: item.displayName ?? item.paramId
-		});
-	}
-	return result;
+		}));
 }

package/src/lib/index.ts

@@ -17,6 +17,7 @@ export { default as Viewer } from './components/viewer/Viewer.svelte';
 
 // Utilities
 export * from './schema/defaults';
+export * from './schema/traversal';
 export * from './compute/solving.svelte';
 
 // External-input transit storage (used by routes that wire pre-step producers)
@@ -24,6 +25,7 @@ export * from './external/storage';
 
 // Contexts & Composables
 export * from './contexts/footerContext.svelte';
+export * from './contexts/clientSlotContext.svelte';
 export * from './composables/useFooterItem.svelte';
 
 // Utils (cn function)

package/src/lib/schema/param-exporter.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from 'vitest';
+import { validateSavedState, extractLoadableValues, loadPreset } from './param-exporter';
+import type { UISchema, ParameterPreset } from '@selvajs/schemas';
+
+// These tests cover the load path a user hits when restoring a preset against a
+// schema that has drifted. The severity of each mismatch decides whether the
+// preset can load at all (error blocks, warning allows), so those are the cases
+// worth locking in — not the happy path.
+
+function schema(over: Partial<UISchema> = {}): UISchema {
+	return {
+		id: 'schema-1',
+		documentId: 'doc-1',
+		inputs: [
+			{ id: 'a', nickname: 'A', paramType: 'number' },
+			{ id: 'b', nickname: 'B', paramType: 'number' }
+		],
+		...over
+	} as unknown as UISchema;
+}
+
+function preset(over: Partial<ParameterPreset> = {}): ParameterPreset {
+	return {
+		id: 'p1',
+		name: 'My Preset',
+		schemaId: 'schema-1',
+		documentId: 'doc-1',
+		parameters: [
+			{ paramId: 'a', nickname: 'A', value: 1 },
+			{ paramId: 'b', nickname: 'B', value: 2 }
+		],
+		...over
+	} as unknown as ParameterPreset;
+}
+
+describe('validateSavedState', () => {
+	it('document-ID mismatch is a blocking error', () => {
+		const result = validateSavedState(preset({ documentId: 'other-doc' }), schema());
+		expect(result.canLoad).toBe(false);
+		expect(result.issues.some((i) => i.severity === 'error' && i.paramId === '__document__')).toBe(
+			true
+		);
+	});
+
+	it('schema-ID change is a warning that still allows loading', () => {
+		const result = validateSavedState(preset({ schemaId: 'old-schema' }), schema());
+		expect(result.canLoad).toBe(true);
+		expect(result.isValid).toBe(false);
+		expect(result.issues.some((i) => i.severity === 'warning' && i.paramId === '__schema__')).toBe(
+			true
+		);
+	});
+
+	it('a parameter missing from the schema is a blocking error', () => {
+		const p = preset({
+			parameters: [
+				{ paramId: 'a', nickname: 'A', value: 1 },
+				{ paramId: 'gone', nickname: 'Gone', value: 9 }
+			] as ParameterPreset['parameters']
+		});
+		const result = validateSavedState(p, schema());
+		expect(result.canLoad).toBe(false);
+		expect(result.issues.some((i) => i.severity === 'error' && i.paramId === 'gone')).toBe(true);
+	});
+
+	it('a renamed nickname is a warning, not a block', () => {
+		const renamed = schema({
+			inputs: [
+				{ id: 'a', nickname: 'A renamed', paramType: 'number' },
+				{ id: 'b', nickname: 'B', paramType: 'number' }
+			]
+		} as unknown as Partial<UISchema>);
+		const result = validateSavedState(preset(), renamed);
+		expect(result.canLoad).toBe(true);
+		expect(result.issues.some((i) => i.severity === 'warning' && i.paramId === 'a')).toBe(true);
+	});
+
+	it('a fully matching preset is valid with no issues', () => {
+		const result = validateSavedState(preset(), schema());
+		expect(result).toEqual({ isValid: true, issues: [], canLoad: true });
+	});
+});
+
+describe('extractLoadableValues', () => {
+	it('drops params that no longer exist in the schema, keeps the rest', () => {
+		const p = preset({
+			parameters: [
+				{ paramId: 'a', nickname: 'A', value: 1 },
+				{ paramId: 'gone', nickname: 'Gone', value: 9 } // not in schema
+			] as ParameterPreset['parameters']
+		});
+		expect(extractLoadableValues(p, schema())).toEqual({ a: 1 });
+	});
+
+	it('keeps a warned-but-valid param (nickname drift) on load', () => {
+		const renamed = schema({
+			inputs: [
+				{ id: 'a', nickname: 'A renamed', paramType: 'number' },
+				{ id: 'b', nickname: 'B', paramType: 'number' }
+			]
+		} as unknown as Partial<UISchema>);
+		expect(extractLoadableValues(preset(), renamed)).toEqual({ a: 1, b: 2 });
+	});
+});
+
+describe('loadPreset', () => {
+	it('fuses validation and extraction: valid preset loads cleanly', () => {
+		const result = loadPreset(preset(), schema());
+		expect(result.isValid).toBe(true);
+		expect(result.canLoad).toBe(true);
+		expect(result.issues).toEqual([]);
+		expect(result.values).toEqual({ a: 1, b: 2 });
+	});
+
+	it('blocks on a document mismatch but still returns loadable values', () => {
+		const result = loadPreset(preset({ documentId: 'other-doc' }), schema());
+		expect(result.canLoad).toBe(false);
+		expect(result.issues.some((i) => i.severity === 'error')).toBe(true);
+		// values are still computed (the caller decides whether to apply them)
+		expect(result.values).toEqual({ a: 1, b: 2 });
+	});
+
+	it('allows load with warnings (schema drift) and drops missing params', () => {
+		const p = preset({
+			parameters: [
+				{ paramId: 'a', nickname: 'A', value: 1 },
+				{ paramId: 'gone', nickname: 'Gone', value: 9 }
+			] as ParameterPreset['parameters'],
+			schemaId: 'old-schema'
+		});
+		const result = loadPreset(p, schema());
+		expect(result.isValid).toBe(false);
+		expect(result.canLoad).toBe(false); // missing param is an error
+		expect(result.values).toEqual({ a: 1 });
+	});
+});

package/src/lib/schema/param-exporter.ts

@@ -1,5 +1,5 @@
-import { APP_DEFAULTS } from '../constants';
 import { randomId } from '../utils/randomId';
+import { getGroups } from '@selvajs/schemas';
 import type {
 	UISchema,
 	ParameterPreset,
@@ -7,13 +7,6 @@ import type {
 	ValidationIssueMessage
 } from '@selvajs/schemas';
 
-function getGroups(schema: UISchema) {
-	if (!schema.layout) return [];
-	if (schema.layout.type === 'tabbed') return schema.layout.tabs.flatMap((t) => t.groups ?? []);
-	if (schema.layout.type === 'flat') return schema.layout.groups ?? [];
-	return [];
-}
-
 export function createSavedState(
 	schema: UISchema,
 	currentValues: Record<string, unknown>,
@@ -113,43 +106,64 @@ export function validateSavedState(
 	return { isValid: issues.length === 0, issues, canLoad: !hasErrors };
 }
 
+/**
+ * The subset of a preset's parameters that can safely be applied to the current schema:
+ * every param that still exists as an input. A param that no longer exists is dropped
+ * (it's the same condition `validateSavedState` flags as an error), so this derives its
+ * own "loadable" rule from the schema rather than re-reading validation issues — no
+ * coupling to how sentinel ids are encoded.
+ */
 export function extractLoadableValues(
 	savedState: ParameterPreset,
-	currentSchema: UISchema,
-	validation: ReturnType<typeof validateSavedState>
+	currentSchema: UISchema
 ): Record<string, unknown> {
-	const errorParamIds = new Set(
-		validation.issues
-			.filter((i) => i.severity === 'error' && !i.paramId.startsWith('__'))
-			.map((i) => i.paramId)
-	);
-
 	const values: Record<string, unknown> = {};
 	for (const paramState of savedState.parameters) {
 		const exists = currentSchema.inputs.some((i) => i.id === paramState.paramId);
-		if (!errorParamIds.has(paramState.paramId) && exists) {
+		if (exists) {
 			values[paramState.paramId] = paramState.value;
 		}
 	}
 	return values;
 }
 
+/** The full outcome of loading a preset: what to apply, plus the diagnostics to surface. */
+export interface PresetLoadResult {
+	/** Values safe to apply now (params that still exist). */
+	values: Record<string, unknown>;
+	/** All validation issues (errors + warnings) for the load dialog. */
+	issues: ValidationIssueMessage[];
+	/** No issues at all — load silently. */
+	isValid: boolean;
+	/** No blocking errors — load is allowed (warnings are fine). */
+	canLoad: boolean;
+}
+
+/**
+ * Single entry point for applying a preset: validates against the current schema and, in
+ * the same pass, computes the loadable values. Callers get one object instead of
+ * threading a validation result back into a separate extraction step.
+ */
+export function loadPreset(savedState: ParameterPreset, currentSchema: UISchema): PresetLoadResult {
+	const validation = validateSavedState(savedState, currentSchema);
+	return {
+		values: extractLoadableValues(savedState, currentSchema),
+		issues: validation.issues,
+		isValid: validation.isValid,
+		canLoad: validation.canLoad
+	};
+}
+
 export function exportStateAsJson(savedState: ParameterPreset): void {
 	const blob = new Blob([JSON.stringify(savedState, null, 2)], { type: 'application/json' });
-	const url = URL.createObjectURL(blob);
+	const safeName = savedState.name.replace(/[^a-z0-9]/gi, '_');
+	const date = savedState.timestamp.split('T')[0].replace(/-/g, '_');
+
 	const link = document.createElement('a');
-	link.href = url;
-	link.download = `${savedState.name.replace(/[^a-z0-9]/gi, '_')}_${savedState.timestamp.split('T')[0].replace(/-/g, '_')}.sps`;
-	link.style.display = 'none';
-	document.body.appendChild(link);
-
-	setTimeout(() => {
-		link.click();
-		setTimeout(() => {
-			document.body.removeChild(link);
-			URL.revokeObjectURL(url);
-		}, APP_DEFAULTS.TIMEOUTS.PARAM_EXPORT_DELAY);
-	}, 0);
+	link.href = URL.createObjectURL(blob);
+	link.download = `${safeName}_${date}.sps`;
+	link.click();
+	URL.revokeObjectURL(link.href);
 }
 
 export async function importStateFromJson(file: File): Promise<ParameterPreset> {