selva-shared 0.8.1

package/src/lib/utils/file-download.ts

@@ -0,0 +1,88 @@
+/**
+ * Wrapper utilities for file downloads from Grasshopper outputs
+ * Uses the core package implementation for file handling
+ */
+
+import { downloadFileData, type FileData } from 'selva-compute';
+
+/**
+ * Download file(s) from Grasshopper outputs
+ * Single files are downloaded directly, multiple files are packaged as ZIP
+ */
+export async function downloadFiles(
+	fileData: FileData | FileData[],
+	fileName: string = 'grasshopper-output'
+): Promise<void> {
+	try {
+		const filesArray = Array.isArray(fileData) ? fileData : [fileData];
+
+		if (filesArray.length === 0) {
+			console.warn('[FileDownload] No files to download');
+			return;
+		}
+
+		if (filesArray.length === 1) {
+			// Single file - download directly
+			await downloadSingleFile(filesArray[0]);
+		} else {
+			// Multiple files - use core's ZIP functionality
+			await downloadFileData(filesArray, fileName);
+		}
+	} catch (error) {
+		console.error('[FileDownload] Error downloading files:', error);
+		throw error;
+	}
+}
+
+/**
+ * Download a single file directly
+ */
+async function downloadSingleFile(fileData: FileData): Promise<void> {
+	try {
+		await downloadFileData([fileData], fileData.fileName.replace(/\.[^.]*$/, ''));
+	} catch (error) {
+		console.error('[FileDownload] Error downloading single file:', error);
+		throw error;
+	}
+}
+
+/**
+ * Check if data is FileData
+ */
+export function isFileData(data: unknown): data is FileData {
+	return (
+		typeof data === 'object' &&
+		data !== null &&
+		'fileName' in data &&
+		'data' in data &&
+		'isBase64Encoded' in data
+	);
+}
+
+/**
+ * Check if data is FileData array
+ */
+export function isFileDataArray(data: unknown): data is FileData[] {
+	return Array.isArray(data) && data.length > 0 && isFileData(data[0]);
+}
+
+/**
+ * Format file size for display
+ */
+export function formatFileSize(bytes: number): string {
+	if (bytes === 0) return '0 Bytes';
+
+	const k = 1024;
+	const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+	const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+	return Math.round((bytes / Math.pow(k, i)) * 100) / 100 + ' ' + sizes[i];
+}
+
+/**
+ * Get approximate file size from base64 string
+ */
+export function getBase64FileSize(base64: string): number {
+	// Base64 encoded string is approximately 33% larger than original
+	return Math.ceil((base64.length * 3) / 4);
+}

package/src/lib/utils/loadScript.ts

@@ -0,0 +1,52 @@
+/**
+ * Load an external script from a CDN with automatic deduplication.
+ * All calls to load the same script will share a single promise,
+ * preventing duplicate script tags and race conditions.
+ *
+ * @param src The script URL
+ * @param options Script attributes (crossOrigin, async, etc.)
+ * @returns Promise that resolves when script is loaded
+ */
+
+const scriptLoaders = new Map<string, Promise<void>>();
+
+export function loadScript(
+	src: string,
+	options?: {
+		crossOrigin?: string;
+		async?: boolean;
+		defer?: boolean;
+	}
+): Promise<void> {
+	// Return existing promise if already loading/loaded
+	if (scriptLoaders.has(src)) {
+		return scriptLoaders.get(src)!;
+	}
+
+	// Check if script already exists in DOM
+	if (document.querySelector(`script[src="${src}"]`)) {
+		const resolved = Promise.resolve();
+		scriptLoaders.set(src, resolved);
+		return resolved;
+	}
+
+	// Create and load script
+	const promise = new Promise<void>((resolve, reject) => {
+		const script = document.createElement('script');
+		script.src = src;
+		if (options?.crossOrigin) script.crossOrigin = options.crossOrigin;
+		if (options?.async !== undefined) script.async = options.async;
+		if (options?.defer !== undefined) script.defer = options.defer;
+
+		script.onload = () => resolve();
+		script.onerror = () => {
+			scriptLoaders.delete(src);
+			reject(new Error(`Failed to load script: ${src}`));
+		};
+
+		document.head.appendChild(script);
+	});
+
+	scriptLoaders.set(src, promise);
+	return promise;
+}

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

@@ -0,0 +1,242 @@
+import type {
+	UISchema,
+	ParameterPreset,
+	ParameterState,
+	ValidationIssueMessage,
+	GroupConfig
+} from '../types/generated';
+
+/**
+ * Generate a UUID v4 (with fallback for older environments)
+ */
+function generateUUID(): string {
+	if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+		return crypto.randomUUID();
+	}
+	// Fallback for older browsers/environments
+	return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+		const r = (Math.random() * 16) | 0;
+		const v = c === 'x' ? r : (r & 0x3) | 0x8;
+		return v.toString(16);
+	});
+}
+
+/**
+ * Create a saved state from current schema and values
+ */
+export function createSavedState(
+	schema: UISchema,
+	currentValues: Record<string, unknown>,
+	metadata: {
+		name: string;
+		description?: string;
+		author?: string;
+		tags?: string[];
+	}
+): ParameterPreset {
+	// Collect parameter states from schema
+	const parameters: ParameterState[] = [];
+
+	const processGroup = (group: GroupConfig) => {
+		for (const item of group.items || []) {
+			if (item.type === 'input') {
+				const value = currentValues[item.paramId];
+
+				// Find the input parameter definition for type info
+				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
+					});
+				}
+			}
+		}
+	};
+
+	if (schema.layout) {
+		if (schema.layout.type === 'tabbed') {
+			for (const tab of schema.layout.tabs) {
+				for (const group of tab.groups || []) {
+					processGroup(group);
+				}
+			}
+		} else if (schema.layout.type === 'flat') {
+			for (const group of schema.layout.groups || []) {
+				processGroup(group);
+			}
+		}
+	}
+
+	return {
+		id: generateUUID(),
+		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
+	};
+}
+
+/**
+ * Validate a saved state against the current schema
+ */
+export function validateSavedState(
+	savedState: ParameterPreset,
+	currentSchema: UISchema
+): {
+	isValid: boolean;
+	issues: ValidationIssueMessage[];
+	canLoad: boolean; // Can we load despite issues?
+} {
+	const issues: ValidationIssueMessage[] = [];
+
+	// Check document ID match
+	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
+			}
+		});
+	}
+
+	// Check schema ID match (warning only)
+	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
+			}
+		});
+	}
+
+	// Validate each parameter
+	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;
+		}
+
+		// Check nickname changed (warning)
+		if (inputDef.nickname !== paramState.nickname) {
+			issues.push({
+				paramId: paramState.paramId,
+				severity: 'warning',
+				message: `Parameter nickname changed`,
+				details: {
+					expected: paramState.nickname,
+					actual: inputDef.nickname
+				}
+			});
+		}
+	}
+
+	// Can load if no errors (warnings are ok)
+	const hasErrors = issues.some((i) => i.severity === 'error');
+	const canLoad = !hasErrors;
+
+	return {
+		isValid: issues.length === 0,
+		issues,
+		canLoad
+	};
+}
+
+/**
+ * Extract values from saved state that can be safely loaded
+ */
+export function extractLoadableValues(
+	savedState: ParameterPreset,
+	currentSchema: UISchema,
+	validation: ReturnType<typeof validateSavedState>
+): Record<string, unknown> {
+	const values: Record<string, unknown> = {};
+
+	// Get param IDs with errors
+	const errorParamIds = new Set(
+		validation.issues
+			.filter(
+				(i) => i.severity === 'error' && i.paramId !== '__document__' && i.paramId !== '__schema__'
+			)
+			.map((i) => i.paramId)
+	);
+
+	// Extract values for parameters without errors
+	for (const paramState of savedState.parameters) {
+		if (!errorParamIds.has(paramState.paramId)) {
+			// Verify parameter still exists
+			const inputDef = currentSchema.inputs.find((i) => i.id === paramState.paramId);
+			if (inputDef) {
+				values[paramState.paramId] = paramState.value;
+			}
+		}
+	}
+
+	return values;
+}
+
+/**
+ * Export state as .sps (Selva Param State) file
+ */
+export function exportStateAsJson(savedState: ParameterPreset): void {
+	const json = JSON.stringify(savedState, null, 2);
+	const blob = new Blob([json], { type: 'application/json' });
+	const url = URL.createObjectURL(blob);
+
+	// Use a more reliable method: add to DOM, trigger, then remove
+	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`;
+
+	// Ensure visibility for older browsers
+	link.style.display = 'none';
+	document.body.appendChild(link);
+
+	// Use setTimeout to ensure DOM is ready
+	setTimeout(() => {
+		link.click();
+		// Clean up after click
+		setTimeout(() => {
+			document.body.removeChild(link);
+			URL.revokeObjectURL(url);
+		}, 100);
+	}, 0);
+}
+
+/**
+ * Import state from .sps (Selva Param State) file
+ */
+export async function importStateFromJson(file: File): Promise<ParameterPreset> {
+	const text = await file.text();
+	const state = JSON.parse(text) as ParameterPreset;
+
+	// Basic validation
+	if (!state.id || !state.name || !state.documentId || !state.parameters) {
+		throw new Error('Invalid saved state file format');
+	}
+
+	return state;
+}

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

@@ -0,0 +1,100 @@
+import { untrack } from 'svelte';
+
+// How many solves to keep in history for averaging
+const HISTORY_SIZE = 3;
+// If expected solve time is below this, skip the indicator entirely
+const FAST_THRESHOLD_MS = 200;
+// If expected solve time is above this, show indicator immediately (no delay)
+const SLOW_THRESHOLD_MS = 600;
+
+/**
+ * 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) {
+	let show = $state(false);
+	let timeout: ReturnType<typeof setTimeout> | null = null;
+
+	// Solve duration history
+	const solveHistory: number[] = [];
+	let solveStartTime: number | null = null;
+	let hasHistory = false;
+
+	function getExpectedDuration(): number {
+		if (solveHistory.length === 0) return Infinity; // unknown → show immediately
+		return solveHistory.reduce((a, b) => a + b, 0) / solveHistory.length;
+	}
+
+	function recordSolveEnd() {
+		if (solveStartTime !== null) {
+			const duration = performance.now() - solveStartTime;
+			solveHistory.push(duration);
+			if (solveHistory.length > HISTORY_SIZE) {
+				solveHistory.shift();
+			}
+			solveStartTime = null;
+			hasHistory = true;
+		}
+	}
+
+	$effect(() => {
+		const solving = isSolving();
+
+		untrack(() => {
+			if (solving) {
+				solveStartTime = performance.now();
+
+				const expected = getExpectedDuration();
+
+				// Skip indicator entirely for consistently fast solves
+				if (hasHistory && expected < FAST_THRESHOLD_MS) {
+					return;
+				}
+
+				// Delay: 0 for slow/unknown, proportional for mid-range
+				const delay =
+					expected === Infinity || expected >= SLOW_THRESHOLD_MS
+						? 0
+						: Math.round(
+								((expected - FAST_THRESHOLD_MS) / (SLOW_THRESHOLD_MS - FAST_THRESHOLD_MS)) * 300
+							);
+
+				if (!timeout) {
+					if (delay === 0) {
+						show = true;
+					} else {
+						timeout = setTimeout(() => {
+							show = true;
+							timeout = null;
+						}, delay);
+					}
+				}
+			} else {
+				recordSolveEnd();
+
+				if (timeout) {
+					clearTimeout(timeout);
+					timeout = null;
+				}
+				show = false;
+			}
+		});
+
+		return () => {
+			if (timeout) {
+				clearTimeout(timeout);
+			}
+		};
+	});
+
+	return {
+		get show() {
+			return show;
+		}
+	};
+}

package/src/lib/utils/utils-shared.ts

@@ -0,0 +1,57 @@
+import type { UISchema } from '$lib/types/generated';
+
+/**
+ * Get default value for a parameter type
+ */
+export function getDefaultValue(paramType: string): unknown {
+	switch (paramType) {
+		case 'number':
+		case 'integer':
+			return 0;
+		case 'boolean':
+			return false;
+		case 'text':
+			return '';
+		default:
+			return null;
+	}
+}
+
+/**
+ * Ensure schema has proper layout defaults
+ */
+export function ensureSchemaLayoutDefaults(schema: UISchema | null): UISchema | null {
+	if (!schema) return null;
+
+	if (!schema.layout) {
+		schema.layout = {
+			type: 'tabbed',
+			gap: 16,
+			tabs: []
+		};
+	}
+
+	/**
+	 * @deprecated v1 schema migration
+	 * TODO(v2.0.0): Remove this block - all schemas should have layout.type
+	 */
+	if (schema.layout && !schema.layout.type) {
+		if ('tabs' in schema.layout) {
+			(schema.layout as any).type = 'tabbed';
+		} else if ('groups' in schema.layout) {
+			(schema.layout as any).type = 'flat';
+		} else {
+			(schema.layout as any).type = 'tabbed';
+		}
+	}
+
+	if (schema.layout.type === 'tabbed' && !schema.layout.tabs) {
+		schema.layout.tabs = [];
+	}
+	// Ensure instanceSolve has a default value
+	if (schema.instanceSolve === undefined) {
+		schema.instanceSolve = true;
+	}
+
+	return schema;
+}

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

@@ -0,0 +1,97 @@
+import type {
+	LayoutItem,
+	VisibilityRule,
+	VisibilityCondition,
+	GroupVisibilityCondition
+} from '$lib/types/generated';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface VisibilityResult {
+	visible: boolean;
+	disabled: boolean;
+	defaultValue?: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Rule operators
+// ---------------------------------------------------------------------------
+
+type RuleOperatorFn = (a: unknown, b: unknown, values?: unknown[]) => boolean;
+
+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;
+		}
+	}
+};
+
+// ---------------------------------------------------------------------------
+// Condition evaluation
+// ---------------------------------------------------------------------------
+
+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);
+}
+
+// ---------------------------------------------------------------------------
+// Item / group visibility
+// ---------------------------------------------------------------------------
+
+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;
+}

package/src/lib/utils.ts

@@ -0,0 +1,13 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs));
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type WithoutChild<T> = T extends { child?: any } ? Omit<T, 'child'> : T;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type WithoutChildren<T> = T extends { children?: any } ? Omit<T, 'children'> : T;
+export type WithoutChildrenOrChild<T> = WithoutChildren<WithoutChild<T>>;
+export type WithElementRef<T, U extends HTMLElement = HTMLElement> = T & { ref?: U | null };