selva-shared 0.8.1

package/dist/types/generated/schema.d.ts

@@ -0,0 +1,451 @@
+/**
+ * This file was automatically generated from schemas/ui-schema.json.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSON Schema file,
+ * and run `npm run generate:ts` in the schemas directory to regenerate this file.
+ */
+export type GrasshopperParamType = 'number' | 'integer' | 'boolean' | 'text' | 'valueList' | 'file' | 'color' | 'generic';
+export type InputNumberLayoutItem = LayoutItemBase & {
+    type: 'input';
+    widgetType: 'number';
+    config?: NumberWidgetConfig;
+    [k: string]: unknown | undefined;
+};
+export type InputTextLayoutItem = LayoutItemBase & {
+    type: 'input';
+    widgetType: 'text';
+    config?: TextWidgetConfig;
+    [k: string]: unknown | undefined;
+};
+export type InputDropdownLayoutItem = LayoutItemBase & {
+    type: 'input';
+    widgetType: 'dropdown';
+    config: DropdownWidgetConfig;
+    [k: string]: unknown | undefined;
+};
+export type InputCheckboxLayoutItem = LayoutItemBase & {
+    type: 'input';
+    widgetType: 'checkbox';
+    config?: CheckboxWidgetConfig;
+    [k: string]: unknown | undefined;
+};
+export type InputFileLayoutItem = LayoutItemBase & {
+    type: 'input';
+    widgetType: 'file';
+    config?: FileInputWidgetConfig;
+    [k: string]: unknown | undefined;
+};
+export type InputColorLayoutItem = LayoutItemBase & {
+    type: 'input';
+    widgetType: 'color';
+    config?: ColorWidgetConfig;
+    [k: string]: unknown | undefined;
+};
+export type OutputTextLayoutItem = LayoutItemBase & {
+    type: 'output';
+    widgetType: 'text';
+    [k: string]: unknown | undefined;
+};
+export type OutputNumberLayoutItem = LayoutItemBase & {
+    type: 'output';
+    widgetType: 'number';
+    [k: string]: unknown | undefined;
+};
+export type OutputFileLayoutItem = LayoutItemBase & {
+    type: 'output';
+    widgetType: 'file';
+    config?: FileWidgetConfig;
+    [k: string]: unknown | undefined;
+};
+export type OutputChartLayoutItem = LayoutItemBase & {
+    type: 'output';
+    widgetType: 'chart';
+    config?: ChartWidgetConfig;
+    [k: string]: unknown | undefined;
+};
+export type LayoutItem = InputNumberLayoutItem | InputTextLayoutItem | InputDropdownLayoutItem | InputCheckboxLayoutItem | InputFileLayoutItem | InputColorLayoutItem | OutputTextLayoutItem | OutputNumberLayoutItem | OutputFileLayoutItem | OutputChartLayoutItem | LineBreakLayoutItem;
+export type LayoutConfig = TabbedLayoutConfig | FlatLayoutConfig;
+export type GrasshopperInputStructure = 'item' | 'list' | 'tree';
+/**
+ * Schema definitions for Selva UI configuration
+ */
+export interface SelvaUISchema {
+    [k: string]: unknown | undefined;
+}
+export interface VisibilityRule {
+    /**
+     * Parameter ID to watch for changes
+     */
+    paramId: string;
+    /**
+     * Comparison operator
+     */
+    operator: 'equals' | 'notEquals' | 'greaterThan' | 'lessThan' | 'greaterThanOrEqual' | 'lessThanOrEqual' | 'in' | 'notIn' | 'between' | 'matches';
+    /**
+     * Value to compare against (used for equals, notEquals, greaterThan, lessThan, greaterThanOrEqual, lessThanOrEqual)
+     */
+    value?: {
+        [k: string]: unknown | undefined;
+    };
+    /**
+     * Array of values (used for 'in', 'notIn' operators, or [min, max] for 'between')
+     */
+    values?: unknown[];
+}
+export interface VisibilityCondition {
+    /**
+     * Evaluation mode: 'all' = AND (all rules must pass), 'any' = OR (at least one rule must pass)
+     */
+    mode?: 'all' | 'any';
+    /**
+     * List of rules to evaluate
+     *
+     * @minItems 1
+     */
+    rules: [VisibilityRule, ...VisibilityRule[]];
+    /**
+     * Action to apply when condition is met: 'show' makes visible and enabled, 'hide' removes from view, 'disable' makes visible but greyed out and non-interactive
+     */
+    action?: 'show' | 'hide' | 'disable';
+    /**
+     * Default value to set for the parameter when condition is met. The value should be compatible with the parameter type (number, string, boolean, etc.)
+     */
+    defaultValue?: {
+        [k: string]: unknown | undefined;
+    };
+}
+export interface GroupVisibilityCondition {
+    /**
+     * Evaluation mode: 'all' = AND (all rules must pass), 'any' = OR (at least one rule must pass)
+     */
+    mode?: 'all' | 'any';
+    /**
+     * List of rules to evaluate
+     *
+     * @minItems 1
+     */
+    rules: [VisibilityRule, ...VisibilityRule[]];
+    /**
+     * Action to apply when condition is met: 'show' makes group visible, 'hide' removes group from view
+     */
+    action?: 'show' | 'hide';
+}
+export interface NumberWidgetConfig {
+    minimum?: number;
+    maximum?: number;
+    stepSize?: number;
+    placeholder?: string;
+    renderAsSlider?: boolean;
+}
+export interface TextWidgetConfig {
+    placeholder?: string;
+    required?: boolean;
+    /**
+     * Maximum character length for text input
+     */
+    maxLength?: number;
+    /**
+     * Regex pattern for validation (e.g., email, phone)
+     */
+    pattern?: string;
+    /**
+     * Custom error message shown when pattern validation fails
+     */
+    customErrorMessage?: string;
+}
+export interface DropdownWidgetConfig {
+    /**
+     * Key-value pairs for dropdown options
+     */
+    options: {
+        [k: string]: string | undefined;
+    };
+    required?: boolean;
+}
+export interface CheckboxWidgetConfig {
+}
+export interface FileWidgetConfig {
+    buttonLabel?: string;
+    /**
+     * File format hint (e.g., '3dm') for setting download extension
+     */
+    fileFormat?: string;
+}
+export interface FileInputWidgetConfig {
+    /**
+     * List of accepted file extensions (e.g., ['.3dm', '.step'])
+     */
+    acceptedFormats?: string[];
+    /**
+     * Which mode is active by default when both are allowed
+     */
+    defaultInputMode?: 'upload' | 'url';
+    /**
+     * Which input modes the end user can choose from. If omitted, both are allowed.
+     */
+    allowedInputModes?: ('upload' | 'url')[];
+}
+export interface ColorWidgetConfig {
+}
+export interface LayoutItemBase {
+    /**
+     * Unique identifier for this layout item in the UI tree (not the parameter ID)
+     */
+    id: string;
+    /**
+     * References the Grasshopper component InstanceGuid (Data Source)
+     */
+    paramId: string;
+    displayName?: string;
+    description?: string;
+    order?: number;
+    span?: number;
+    /**
+     * Base visibility (static). If false, item is always hidden regardless of conditions.
+     */
+    visible?: boolean;
+    visibilityCondition?: VisibilityCondition;
+    [k: string]: unknown | undefined;
+}
+export interface ChartWidgetConfig {
+}
+export interface LineBreakLayoutItem {
+    /**
+     * Unique identifier for this layout item in the UI tree
+     */
+    id: string;
+    type: 'linebreak';
+}
+export interface GroupConfig {
+    id: string;
+    label: string;
+    description?: string;
+    order?: number;
+    collapsed?: boolean;
+    columns?: number;
+    items: LayoutItem[];
+    visibilityCondition?: GroupVisibilityCondition;
+}
+export interface TabConfig {
+    id: string;
+    label: string;
+    icon?: string;
+    order?: number;
+    groups: GroupConfig[];
+    /**
+     * Horizontal region where this tab should be positioned in multi-column layouts
+     */
+    position?: 'left' | 'center' | 'right';
+}
+export interface TabbedLayoutConfig {
+    type: 'tabbed';
+    gap?: number;
+    tabs: TabConfig[];
+}
+export interface FlatLayoutConfig {
+    type: 'flat';
+    gap?: number;
+    groups: GroupConfig[];
+}
+export interface DiscoveredInput {
+    /**
+     * Grasshopper parameter instance GUID
+     */
+    id: string;
+    name: string;
+    nickname: string;
+    description: string;
+    type: GrasshopperParamType;
+    default?: unknown;
+    minimum?: number;
+    maximum?: number;
+    stepSize?: number;
+    atLeast?: number;
+    atMost?: number;
+    treeAccess?: boolean;
+    /**
+     * Key-value pairs for dropdown/selection options
+     */
+    options?: {
+        [k: string]: string | undefined;
+    };
+    [k: string]: unknown | undefined;
+}
+export interface DiscoveredOutput {
+    /**
+     * Grasshopper component instance GUID
+     */
+    id: string;
+    nickname: string;
+    description?: string;
+    /**
+     * Output display type in UI: 'text' for text/console output, 'number' for numeric output, 'file' for downloadable files, 'html' for rendered HTML (e.g. Plotly charts)
+     */
+    type: 'text' | 'number' | 'file' | 'chart';
+}
+export interface DiscoveredParameters {
+    sessionId: string;
+    timestamp: string;
+    /**
+     * List of input parameters available for UI building
+     */
+    inputs: DiscoveredInput[];
+    /**
+     * List of output components available for UI building
+     */
+    outputs: DiscoveredOutput[];
+    [k: string]: unknown | undefined;
+}
+export interface SchemaInput {
+    /**
+     * Grasshopper parameter instance GUID
+     */
+    id: string;
+    nickname: string;
+    paramType: GrasshopperParamType;
+    description?: string;
+    default?: unknown;
+    /**
+     * Grasshopper data access mode: 'item' = Item Access, 'list' = List Access, 'tree' = Tree Access. Defaults to 'item'.
+     */
+    inputStructure?: 'item' | 'list' | 'tree';
+}
+export interface SchemaOutput {
+    /**
+     * Grasshopper parameter instance GUID
+     */
+    id: string;
+    nickname: string;
+    description?: string;
+    /**
+     * Output display type
+     */
+    type: 'text' | 'number' | 'file' | 'chart';
+}
+export interface ViewerOptions {
+    /**
+     * If true, display mesh data is sent to the web preview for local rendering
+     */
+    enableLocal?: boolean;
+    /**
+     * If true, enables remote rendering via Rhino Compute
+     */
+    enableRemote?: boolean;
+    /**
+     * Background color for the 3D viewer as hex string (e.g., '#ffffff')
+     */
+    backgroundColor?: string;
+}
+export interface UISchema {
+    id: string;
+    name: string;
+    description?: string;
+    /**
+     * Grasshopper document file name (e.g., 'myfile.gh')
+     */
+    projectFileName?: string;
+    /**
+     * Grasshopper document unique identifier (GUID)
+     */
+    documentId?: string;
+    /**
+     * Version of Selva plugin that created/last modified this schema
+     */
+    pluginVersion?: string;
+    /**
+     * User-defined tags for organizing schemas (e.g., ['architecture', 'facade'])
+     */
+    tags?: string[];
+    /**
+     * Category for organizing schemas (e.g., 'architecture', 'structural', 'mechanical')
+     */
+    category?: string;
+    /**
+     * User or organization who created the schema
+     */
+    author?: string;
+    /**
+     * Organization/company name
+     */
+    organization?: string;
+    /**
+     * Semantic version of the schema format (MAJOR.MINOR.PATCH)
+     */
+    schemaVersion?: string;
+    /**
+     * Minimum plugin version required to load this schema
+     */
+    minPluginVersion?: string;
+    created?: string;
+    /**
+     * Last modification timestamp
+     */
+    lastModified?: string;
+    viewerOptions?: ViewerOptions1;
+    /**
+     * If true, changes trigger immediate solving. If false, user must press Calculate button.
+     */
+    instanceSolve?: boolean;
+    inputs: SchemaInput[];
+    /**
+     * All output components (print, bake, file download)
+     */
+    outputs: SchemaOutput[];
+    layout: LayoutConfig;
+}
+/**
+ * Configuration for the 3D viewer
+ */
+export interface ViewerOptions1 {
+    /**
+     * If true, display mesh data is sent to the web preview for local rendering
+     */
+    enableLocal?: boolean;
+    /**
+     * If true, enables remote rendering via Rhino Compute
+     */
+    enableRemote?: boolean;
+    /**
+     * Background color for the 3D viewer as hex string (e.g., '#ffffff')
+     */
+    backgroundColor?: string;
+}
+export interface SessionState {
+    sessionId: string;
+    active: boolean;
+    lastUpdate: string;
+    mode: 'builder' | 'preview';
+    [k: string]: unknown | undefined;
+}
+export interface RuntimeValues {
+    timestamp: string;
+    values: {
+        [k: string]: unknown | undefined;
+    };
+    [k: string]: unknown | undefined;
+}
+export interface ValidationIssueMessage {
+    paramId: string;
+    /**
+     * warning = can still load, error = cannot load
+     */
+    severity: 'warning' | 'error';
+    message: string;
+    details?: {
+        expected?: string;
+        actual?: string;
+        [k: string]: unknown | undefined;
+    };
+}
+export declare const ACCEPTED_FILE_FORMATS: readonly [".3dm", ".stp", ".step", ".fbx", ".obj", ".dxf", ".stl"];
+export declare function isInputLayoutItem(item: LayoutItem): item is InputNumberLayoutItem | InputTextLayoutItem | InputDropdownLayoutItem | InputCheckboxLayoutItem | InputFileLayoutItem | InputColorLayoutItem;
+export declare function isOutputLayoutItem(item: LayoutItem): item is OutputTextLayoutItem | OutputNumberLayoutItem | OutputFileLayoutItem | OutputChartLayoutItem;
+export declare function isLineBreakLayoutItem(item: LayoutItem): item is LineBreakLayoutItem;
+export declare function isNumberWidget(item: LayoutItem): item is InputNumberLayoutItem;
+export declare function isTextWidget(item: LayoutItem): item is InputTextLayoutItem;
+export declare function isDropdownWidget(item: LayoutItem): item is InputDropdownLayoutItem;
+export declare function isCheckboxWidget(item: LayoutItem): item is InputCheckboxLayoutItem;
+export declare function isFileWidget(item: LayoutItem): item is InputFileLayoutItem;
+export declare function isColorWidget(item: LayoutItem): item is InputColorLayoutItem;
+export type InputLayoutItem = InputNumberLayoutItem | InputTextLayoutItem | InputDropdownLayoutItem | InputCheckboxLayoutItem | InputFileLayoutItem | InputColorLayoutItem;
+export type OutputLayoutItem = OutputTextLayoutItem | OutputNumberLayoutItem | OutputFileLayoutItem | OutputChartLayoutItem;
+export type SupportedTypes = string | number | boolean;

package/dist/types/generated/schema.js

@@ -0,0 +1,48 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated from schemas/ui-schema.json.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSON Schema file,
+ * and run `npm run generate:ts` in the schemas directory to regenerate this file.
+ */
+// ============================================================================
+// CONSTANTS (from schema)
+// ============================================================================
+export const ACCEPTED_FILE_FORMATS = [
+    ".3dm",
+    ".stp",
+    ".step",
+    ".fbx",
+    ".obj",
+    ".dxf",
+    ".stl"
+];
+// ============================================================================
+// TYPE GUARDS
+// ============================================================================
+export function isInputLayoutItem(item) {
+    return item.type === 'input';
+}
+export function isOutputLayoutItem(item) {
+    return item.type === 'output';
+}
+export function isLineBreakLayoutItem(item) {
+    return item.type === 'linebreak';
+}
+export function isNumberWidget(item) {
+    return item.type === 'input' && item.widgetType === 'number';
+}
+export function isTextWidget(item) {
+    return item.type === 'input' && item.widgetType === 'text';
+}
+export function isDropdownWidget(item) {
+    return item.type === 'input' && item.widgetType === 'dropdown';
+}
+export function isCheckboxWidget(item) {
+    return item.type === 'input' && item.widgetType === 'checkbox';
+}
+export function isFileWidget(item) {
+    return item.type === 'input' && item.widgetType === 'file';
+}
+export function isColorWidget(item) {
+    return item.type === 'input' && item.widgetType === 'color';
+}

package/dist/utils/computeThrottle.svelte.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Compute throttle utility for managing async compute requests.
+ *
+ * Features:
+ * - Only one request in-flight at a time
+ * - Latest values always sent (no queue, just "latest wins")
+ * - AbortController support to cancel stale requests
+ * - Configurable timeout with automatic abort
+ *
+ * Flow:
+ * 1. User changes value → request sent immediately
+ * 2. User changes value while request in-flight → current request aborted, new one starts
+ * 3. Result: server never overwhelmed, always processing latest values
+ */
+export interface ComputeThrottleOptions {
+    /** Timeout in milliseconds. Default: 60000 (60 seconds) */
+    timeout?: number;
+}
+export declare function createComputeThrottle<T>(computeFn: (values: T, signal: AbortSignal) => Promise<void>, options?: ComputeThrottleOptions): {
+    /** Trigger a compute with the given values */
+    trigger: (values: T) => void;
+    /** Whether a compute is currently in progress */
+    readonly isComputing: boolean;
+    /** Whether there are pending values waiting to be sent */
+    readonly hasPending: boolean;
+    /** Cancel any in-flight request */
+    cancel: () => void;
+};

package/dist/utils/computeThrottle.svelte.js

@@ -0,0 +1,93 @@
+/**
+ * Compute throttle utility for managing async compute requests.
+ *
+ * Features:
+ * - Only one request in-flight at a time
+ * - Latest values always sent (no queue, just "latest wins")
+ * - AbortController support to cancel stale requests
+ * - Configurable timeout with automatic abort
+ *
+ * Flow:
+ * 1. User changes value → request sent immediately
+ * 2. User changes value while request in-flight → current request aborted, new one starts
+ * 3. Result: server never overwhelmed, always processing latest values
+ */
+export function createComputeThrottle(computeFn, options = {}) {
+    const { timeout = 60000 } = options;
+    let isComputing = $state(false);
+    let pendingValues = $state(null);
+    let currentAbortController = null;
+    function abortCurrent() {
+        if (currentAbortController) {
+            currentAbortController.abort();
+            currentAbortController = null;
+        }
+    }
+    async function executeCompute(values) {
+        // Abort any existing request
+        abortCurrent();
+        // Create new abort controller with timeout
+        currentAbortController = new AbortController();
+        const signal = currentAbortController.signal;
+        // Set up timeout
+        const timeoutId = setTimeout(() => {
+            if (currentAbortController) {
+                currentAbortController.abort(new Error(`Request timed out after ${timeout}ms`));
+            }
+        }, timeout);
+        isComputing = true;
+        try {
+            await computeFn(values, signal);
+        }
+        catch (err) {
+            // Re-throw unless it's an abort (which we handle silently for cancellation)
+            if (err instanceof Error && err.name === 'AbortError') {
+                // Check if there are pending values - if so, this was intentional cancellation
+                if (pendingValues === null) {
+                    // Timeout or manual cancel without pending values - rethrow
+                    throw err;
+                }
+                // Otherwise, silently ignore - we're about to process pending values
+            }
+            else {
+                throw err;
+            }
+        }
+        finally {
+            clearTimeout(timeoutId);
+            isComputing = false;
+            currentAbortController = null;
+            // If values changed while we were computing, send the latest
+            if (pendingValues !== null) {
+                const next = pendingValues;
+                pendingValues = null;
+                executeCompute(next);
+            }
+        }
+    }
+    function trigger(values) {
+        if (isComputing) {
+            // Store latest values and abort current request
+            pendingValues = values;
+            abortCurrent();
+        }
+        else {
+            // No request in-flight, send immediately
+            executeCompute(values);
+        }
+    }
+    function cancel() {
+        pendingValues = null;
+        abortCurrent();
+    }
+    return {
+        trigger,
+        get isComputing() {
+            return isComputing;
+        },
+        get hasPending() {
+            return pendingValues !== null;
+        },
+        cancel
+    };
+}

package/dist/utils/debounce.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Debounce utility - delays function execution until after a specified wait time
+ * has elapsed since the last time it was invoked.
+ *
+ * Use this for text inputs, search boxes, etc. where you want to wait for user
+ * to finish typing before executing.
+ *
+ * For sliders, use throttle() instead to get immediate feedback with rate limiting.
+ *
+ * @param func The function to debounce
+ * @param wait The delay in milliseconds
+ * @returns A debounced version of the function
+ */
+export declare function debounce<T extends (...args: any[]) => any>(func: T, wait: number): (...args: Parameters<T>) => void;

package/dist/utils/debounce.js

@@ -0,0 +1,25 @@
+/**
+ * Debounce utility - delays function execution until after a specified wait time
+ * has elapsed since the last time it was invoked.
+ *
+ * Use this for text inputs, search boxes, etc. where you want to wait for user
+ * to finish typing before executing.
+ *
+ * For sliders, use throttle() instead to get immediate feedback with rate limiting.
+ *
+ * @param func The function to debounce
+ * @param wait The delay in milliseconds
+ * @returns A debounced version of the function
+ */
+export function debounce(func, wait) {
+    let timeout = null;
+    return function (...args) {
+        if (timeout !== null) {
+            clearTimeout(timeout);
+        }
+        timeout = setTimeout(() => {
+            func(...args);
+            timeout = null;
+        }, wait);
+    };
+}

package/dist/utils/file-download.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Wrapper utilities for file downloads from Grasshopper outputs
+ * Uses the core package implementation for file handling
+ */
+import { type FileData } from 'selva-compute';
+/**
+ * Download file(s) from Grasshopper outputs
+ * Single files are downloaded directly, multiple files are packaged as ZIP
+ */
+export declare function downloadFiles(fileData: FileData | FileData[], fileName?: string): Promise<void>;
+/**
+ * Check if data is FileData
+ */
+export declare function isFileData(data: unknown): data is FileData;
+/**
+ * Check if data is FileData array
+ */
+export declare function isFileDataArray(data: unknown): data is FileData[];
+/**
+ * Format file size for display
+ */
+export declare function formatFileSize(bytes: number): string;
+/**
+ * Get approximate file size from base64 string
+ */
+export declare function getBase64FileSize(base64: string): number;