@selvajs/ui 0.9.0

package/src/lib/compute/computeThrottle.svelte.ts

@@ -0,0 +1,97 @@
+/**
+ * Compute throttle utility for managing async compute requests.
+ *
+ * - Only one request in-flight at a time
+ * - Latest values always win (no queue)
+ * - AbortController support to cancel stale requests
+ * - Configurable timeout with automatic abort
+ */
+interface ComputeThrottleOptions {
+	timeout?: number;
+}
+
+/**
+ * Fallback per-solve abort timeout (ms) when the caller doesn't pass one.
+ * Used only by callers without a deployment-specific limit (e.g. builder-app
+ * over WebSocket); compute-app supplies `MAX_SOLVE_DURATION_MS` from its
+ * server config via `ComputeApp`'s `solveTimeoutMs` prop.
+ */
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+/**
+ * Creates a throttled compute handler that keeps only one request in-flight.
+ * If a new value arrives while one is running, it overwrites the single pending
+ * slot — older pending values are dropped. The pending value runs once the
+ * current request finishes (or aborts).
+ */
+export function createComputeThrottle<T>(
+	computeFn: (values: T, signal: AbortSignal) => Promise<void>,
+	options: ComputeThrottleOptions = {}
+): {
+	trigger: (values: T) => void;
+	readonly isComputing: boolean;
+	readonly hasPending: boolean;
+	cancel: () => void;
+} {
+	const { timeout = DEFAULT_TIMEOUT_MS } = options;
+
+	let isComputing = $state(false);
+	let pendingValues = $state<T | null>(null);
+	let currentAbortController: AbortController | null = null;
+
+	function abortCurrent() {
+		currentAbortController?.abort();
+		currentAbortController = null;
+	}
+
+	async function executeCompute(values: T) {
+		abortCurrent();
+
+		currentAbortController = new AbortController();
+		const { signal } = currentAbortController;
+		const timeoutId = setTimeout(() => currentAbortController?.abort(), timeout);
+
+		isComputing = true;
+		try {
+			await computeFn(values, signal);
+		} catch (err) {
+			if (!(err instanceof Error && err.name === 'AbortError')) {
+				throw err;
+			}
+		} finally {
+			clearTimeout(timeoutId);
+			isComputing = false;
+			currentAbortController = null;
+
+			if (pendingValues !== null) {
+				const next = pendingValues;
+				pendingValues = null;
+				executeCompute(next);
+			}
+		}
+	}
+
+	function trigger(values: T) {
+		if (isComputing) {
+			pendingValues = values;
+		} else {
+			executeCompute(values);
+		}
+	}
+
+	function cancel() {
+		pendingValues = null;
+		abortCurrent();
+	}
+
+	return {
+		trigger,
+		get isComputing() {
+			return isComputing;
+		},
+		get hasPending() {
+			return pendingValues !== null;
+		},
+		cancel
+	};
+}

package/src/lib/compute/solving.svelte.ts

@@ -0,0 +1,77 @@
+import { untrack } from 'svelte';
+import { APP_DEFAULTS } from '../constants';
+
+/**
+ * Creates an adaptive solving indicator that measures actual solve durations
+ * and adjusts its visibility delay accordingly.
+ *
+ * - Fast solves (<200ms avg): indicator never shown (avoids flicker)
+ * - Slow solves (>600ms avg): indicator shown immediately
+ * - In between: indicator shown after a proportional delay
+ * - First solve: shows immediately (no history yet)
+ */
+export function createSolvingIndicator(isSolving: () => boolean): { readonly show: boolean } {
+	const { FAST_THRESHOLD_MS, SLOW_THRESHOLD_MS, HISTORY_SIZE, ANIMATION_DELAY } =
+		APP_DEFAULTS.SOLVING_INDICATOR;
+
+	let show = $state(false);
+	let timeout: ReturnType<typeof setTimeout> | null = null;
+	let solveStartTime: number | null = null;
+	const solveHistory: number[] = [];
+
+	$effect(() => {
+		const solving = isSolving();
+
+		untrack(() => {
+			if (solving) {
+				solveStartTime = performance.now();
+
+				const avg =
+					solveHistory.length === 0
+						? Infinity
+						: solveHistory.reduce((a, b) => a + b, 0) / solveHistory.length;
+
+				if (solveHistory.length > 0 && avg < FAST_THRESHOLD_MS) return;
+
+				const delay =
+					avg === Infinity || avg >= SLOW_THRESHOLD_MS
+						? 0
+						: ((avg - FAST_THRESHOLD_MS) / (SLOW_THRESHOLD_MS - FAST_THRESHOLD_MS)) *
+							ANIMATION_DELAY;
+
+				if (!timeout) {
+					if (delay === 0) {
+						show = true;
+					} else {
+						timeout = setTimeout(() => {
+							show = true;
+							timeout = null;
+						}, delay);
+					}
+				}
+			} else {
+				if (solveStartTime !== null) {
+					solveHistory.push(performance.now() - solveStartTime);
+					if (solveHistory.length > HISTORY_SIZE) solveHistory.shift();
+					solveStartTime = null;
+				}
+
+				if (timeout) {
+					clearTimeout(timeout);
+					timeout = null;
+				}
+				show = false;
+			}
+		});
+
+		return () => {
+			if (timeout) clearTimeout(timeout);
+		};
+	});
+
+	return {
+		get show() {
+			return show;
+		}
+	};
+}

package/src/lib/constants.ts

@@ -0,0 +1,35 @@
+export const APP_DEFAULTS = {
+	// File upload limits
+	FILE_UPLOAD: {
+		MAX_SIZE_MB: 150,
+		MAX_SIZE_BYTES: 150 * 1024 * 1024
+	},
+
+	// Timing & performance thresholds
+	TIMEOUTS: {
+		/** Duration to show solving state (ms) */
+		SOLVE_STATE_DURATION: 3500,
+		/** Parameter export callback delay (ms) */
+		PARAM_EXPORT_DELAY: 100,
+		/** Viewer initialization delay (ms) */
+		VIEWER_INIT_DELAY: 350
+	},
+
+	// Solving indicator adaptive thresholds
+	SOLVING_INDICATOR: {
+		/** If solve is faster than this, don't show indicator (ms) */
+		FAST_THRESHOLD_MS: 200,
+		/** If solve is slower than this, show indicator immediately (ms) */
+		SLOW_THRESHOLD_MS: 600,
+		/** Animation delay for solve indicator (ms) */
+		ANIMATION_DELAY: 300,
+		/** Number of solve durations to keep in history for averaging */
+		HISTORY_SIZE: 3
+	},
+
+	// File size formatting
+	FILE_SIZE: {
+		/** Bytes per kilobyte */
+		BYTES_PER_KB: 1024
+	}
+};

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

@@ -0,0 +1,54 @@
+import { getContext, setContext } from 'svelte';
+import { SvelteMap } from 'svelte/reactivity';
+
+export interface FooterItem {
+	id: string;
+	component: any;
+	/** Called on every render — return reactive state to keep footer in sync */
+	getProps: () => Record<string, any>;
+	position: 'left' | 'right';
+	priority: number;
+	onClick?: () => void;
+}
+
+export interface FooterStore {
+	items: SvelteMap<string, FooterItem>;
+	register(
+		id: string,
+		component: any,
+		getProps: () => Record<string, any>,
+		position?: 'left' | 'right',
+		priority?: number,
+		onClick?: () => void
+	): void;
+	unregister(id: string): void;
+}
+
+export const FOOTER_CONTEXT_KEY = Symbol('footer-context');
+
+export function initializeFooterContext(): FooterStore {
+	const items = new SvelteMap<string, FooterItem>();
+
+	const store: FooterStore = {
+		items,
+		register(id, component, getProps, position = 'left', priority = 0, onClick) {
+			items.set(id, { id, component, getProps, position, priority, onClick });
+		},
+		unregister(id) {
+			items.delete(id);
+		}
+	};
+
+	setContext(FOOTER_CONTEXT_KEY, store);
+	return store;
+}
+
+export function useFooter(): FooterStore {
+	const store = getContext<FooterStore | undefined>(FOOTER_CONTEXT_KEY);
+	if (!store) {
+		throw new Error(
+			'useFooter must be called within a component that is a descendant of the root layout'
+		);
+	}
+	return store;
+}

package/src/lib/index.ts

@@ -0,0 +1,31 @@
+// Layout components (page chrome: shell, header, footer, nav)
+export * from './components/layout';
+
+// Compute app (schema + viewer + solve controls composed into a runnable app)
+export { default as AppLayout } from './components/compute/AppLayout.svelte';
+export { default as ComputeApp } from './components/compute/ComputeApp.svelte';
+
+// Error screen
+export { default as ErrorScreen } from './components/ErrorScreen.svelte';
+
+// Design-system primitives (shadcn-svelte + custom)
+export * from './components/primitives';
+export { default as StateDisplay } from './components/primitives/StateDisplay.svelte';
+
+// 3D viewer
+export { default as Viewer } from './components/viewer/Viewer.svelte';
+
+// Utilities
+export * from './schema/defaults';
+export * from './compute/solving.svelte';
+
+// Contexts & Composables
+export * from './contexts/footerContext.svelte';
+export * from './composables/useFooterItem.svelte';
+
+// Utils (cn function)
+export * from './utils';
+
+// UI-specific runtime types (not from schema)
+export type { ActionButton } from './types/actionButton';
+export type { SolveFn } from './types/solveFn';

package/src/lib/schema/defaults.ts

@@ -0,0 +1,13 @@
+export function getDefaultValue(paramType: string): unknown {
+	switch (paramType) {
+		case 'number':
+		case 'integer':
+			return 0;
+		case 'boolean':
+			return false;
+		case 'text':
+			return '';
+		default:
+			return null;
+	}
+}

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

@@ -0,0 +1,160 @@
+import { APP_DEFAULTS } from '../constants';
+import type {
+	UISchema,
+	ParameterPreset,
+	ParameterState,
+	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>,
+	metadata: {
+		name: string;
+		description?: string;
+		author?: string;
+		tags?: string[];
+	}
+): ParameterPreset {
+	const parameters: ParameterState[] = [];
+
+	for (const group of getGroups(schema)) {
+		for (const item of group.items ?? []) {
+			if (item.type !== 'input') continue;
+			const value = currentValues[item.paramId];
+			const inputDef = schema.inputs.find((i) => i.id === item.paramId);
+			if (value !== undefined && inputDef) {
+				parameters.push({
+					paramId: item.paramId,
+					nickname: inputDef.nickname,
+					displayName: item.displayName || inputDef.nickname,
+					paramType: inputDef.paramType,
+					value,
+					groupName: group.label
+				});
+			}
+		}
+	}
+
+	return {
+		id: crypto.randomUUID(),
+		name: metadata.name,
+		description: metadata.description,
+		timestamp: new Date().toISOString(),
+		schemaId: schema.id,
+		documentId: schema.documentId ?? '',
+		projectFileName: schema.projectFileName ?? '',
+		pluginVersion: schema.pluginVersion ?? '',
+		author: metadata.author,
+		tags: metadata.tags ?? [],
+		parameters
+	};
+}
+
+export function validateSavedState(
+	savedState: ParameterPreset,
+	currentSchema: UISchema
+): {
+	isValid: boolean;
+	issues: ValidationIssueMessage[];
+	canLoad: boolean;
+} {
+	const issues: ValidationIssueMessage[] = [];
+
+	if (savedState.documentId !== (currentSchema.documentId ?? '')) {
+		issues.push({
+			paramId: '__document__',
+			severity: 'error',
+			message: 'Document ID mismatch - this state was saved for a different document',
+			details: { expected: currentSchema.documentId ?? '', actual: savedState.documentId }
+		});
+	}
+
+	if (savedState.schemaId !== currentSchema.id) {
+		issues.push({
+			paramId: '__schema__',
+			severity: 'warning',
+			message: 'Schema has changed since this state was saved',
+			details: { expected: currentSchema.id, actual: savedState.schemaId }
+		});
+	}
+
+	for (const paramState of savedState.parameters) {
+		const inputDef = currentSchema.inputs.find((i) => i.id === paramState.paramId);
+
+		if (!inputDef) {
+			issues.push({
+				paramId: paramState.paramId,
+				severity: 'error',
+				message: `Parameter "${paramState.nickname}" no longer exists in the schema`
+			});
+			continue;
+		}
+
+		if (inputDef.nickname !== paramState.nickname) {
+			issues.push({
+				paramId: paramState.paramId,
+				severity: 'warning',
+				message: 'Parameter nickname changed',
+				details: { expected: paramState.nickname, actual: inputDef.nickname }
+			});
+		}
+	}
+
+	const hasErrors = issues.some((i) => i.severity === 'error');
+	return { isValid: issues.length === 0, issues, canLoad: !hasErrors };
+}
+
+export function extractLoadableValues(
+	savedState: ParameterPreset,
+	currentSchema: UISchema,
+	validation: ReturnType<typeof validateSavedState>
+): 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) {
+			values[paramState.paramId] = paramState.value;
+		}
+	}
+	return values;
+}
+
+export function exportStateAsJson(savedState: ParameterPreset): void {
+	const blob = new Blob([JSON.stringify(savedState, null, 2)], { type: 'application/json' });
+	const url = URL.createObjectURL(blob);
+	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);
+}
+
+export async function importStateFromJson(file: File): Promise<ParameterPreset> {
+	const state = JSON.parse(await file.text()) as ParameterPreset;
+	if (!state.id || !state.name || !state.documentId || !state.parameters) {
+		throw new Error('Invalid saved state file format');
+	}
+	return state;
+}

package/src/lib/schema/visibility-rules.ts

@@ -0,0 +1,94 @@
+import type {
+	LayoutItem,
+	VisibilityRule,
+	VisibilityCondition,
+	GroupVisibilityCondition
+} from '@selvajs/schemas';
+
+export interface VisibilityResult {
+	visible: boolean;
+	disabled: boolean;
+	defaultValue?: unknown;
+}
+
+type RuleOperatorFn = (a: unknown, b: unknown, values?: unknown[]) => boolean;
+
+const toStringArray = (value: unknown): string[] => {
+	if (Array.isArray(value)) return value.map(String);
+	if (value === undefined || value === null || value === '') return [];
+	return [String(value)];
+};
+
+const RULE_OPERATORS: Record<string, RuleOperatorFn> = {
+	equals: (a, b) => a === b,
+	notEquals: (a, b) => a !== b,
+	greaterThan: (a, b) => Number(a) > Number(b),
+	lessThan: (a, b) => Number(a) < Number(b),
+	greaterThanOrEqual: (a, b) => Number(a) >= Number(b),
+	lessThanOrEqual: (a, b) => Number(a) <= Number(b),
+	between: (a, _, vals) =>
+		vals?.length === 2 && Number(a) >= Number(vals[0]) && Number(a) <= Number(vals[1]),
+	in: (a, _, vals) => vals?.includes(String(a)) ?? false,
+	notIn: (a, _, vals) => !(vals?.includes(String(a)) ?? false),
+	matches: (a, b) => {
+		try {
+			return new RegExp(String(b)).test(String(a));
+		} catch {
+			return false;
+		}
+	},
+	contains: (a, b) => toStringArray(a).includes(String(b)),
+	containsAny: (a, _, vals) => {
+		const arr = toStringArray(a);
+		return vals?.some((v) => arr.includes(String(v))) ?? false;
+	},
+	isEmpty: (a) => toStringArray(a).length === 0,
+	isNotEmpty: (a) => toStringArray(a).length > 0
+};
+
+export function evaluateRule(rule: VisibilityRule, values: Record<string, unknown>): boolean {
+	const fn = RULE_OPERATORS[rule.operator];
+	return fn ? fn(values[rule.paramId], rule.value, rule.values) : false;
+}
+
+export function evaluateCondition(
+	condition: VisibilityCondition | GroupVisibilityCondition,
+	values: Record<string, unknown>
+): boolean {
+	const results = condition.rules.map((rule) => evaluateRule(rule, values));
+	return condition.mode === 'any' ? results.some(Boolean) : results.every(Boolean);
+}
+
+type ActionFn = (met: boolean, defaultValue?: unknown) => VisibilityResult;
+
+const ACTIONS: Record<string, ActionFn> = {
+	show: (met) => ({ visible: met, disabled: false }),
+	hide: (met, dv) => ({ visible: !met, disabled: false, defaultValue: dv }),
+	disable: (met, dv) => ({ visible: true, disabled: met, defaultValue: met ? dv : undefined })
+};
+
+export function evaluateVisibility(
+	item: LayoutItem,
+	values: Record<string, unknown>
+): VisibilityResult {
+	if (item.type === 'linebreak') return { visible: true, disabled: false };
+	if (!item.visibilityCondition?.rules) return { visible: true, disabled: false };
+
+	const { action = 'show', defaultValue } = item.visibilityCondition;
+	const met = evaluateCondition(item.visibilityCondition, values);
+	const actionFn = ACTIONS[action] ?? ACTIONS.show;
+
+	return actionFn(met, defaultValue);
+}
+
+export function evaluateGroupVisibility(
+	group: { visibilityCondition?: GroupVisibilityCondition },
+	values: Record<string, unknown>
+): boolean {
+	if (!group.visibilityCondition?.rules) return true;
+
+	const { action = 'show' } = group.visibilityCondition;
+	const met = evaluateCondition(group.visibilityCondition, values);
+
+	return action === 'hide' ? !met : met;
+}