@nuraly/runtime 0.1.0

package/handlers/runtime-api/editor.ts

@@ -0,0 +1,29 @@
+/**
+ * Editor Functions
+ * 
+ * Functions for interacting with the editor UI.
+ */
+
+import { openEditorTab, setCurrentEditorTab } from '../../redux/actions/editor';
+import { traitCompoentFromSchema } from '../../utils/clipboard-utils';
+
+export function createEditorFunctions() {
+  return {
+    /**
+     * Opens an editor tab
+     */
+    openEditorTab,
+
+    /**
+     * Sets the current active editor tab
+     */
+    setCurrentEditorTab,
+
+    /**
+     * Creates components from schema text
+     */
+    TraitCompoentFromSchema: (text) => {
+      traitCompoentFromSchema(text);
+    },
+  };
+}

package/handlers/runtime-api/functions.ts

@@ -0,0 +1,42 @@
+/**
+ * Function Invocation
+ * 
+ * Invoke studio functions (backend functions).
+ */
+
+import { ExecuteInstance } from '../../state';
+import { loadFunctionsHandler, invokeFunctionHandler } from '../../redux/handlers/functions';
+
+export function createFunctionInvocationFunctions() {
+  return {
+    /**
+     * Invokes a studio function by name
+     * 
+     * @param name - Function name to invoke
+     * @param payload - Data to pass to the function
+     * @returns Function execution result
+     */
+    InvokeFunction: async (name: string, payload: any = {}) => {
+      if (!ExecuteInstance.Vars.studio_functions) {
+        const functions = await loadFunctionsHandler();
+        ExecuteInstance.VarsProxy.studio_functions = [...functions];
+      }
+      const targetFunction = (ExecuteInstance.Vars.studio_functions ?? []).find(_function => _function.label === name);
+      try {
+        const result = await invokeFunctionHandler(targetFunction.id, payload);
+
+        const contentType = result.headers?.get("Content-Type") || "";
+
+        if (contentType.includes("application/json")) {
+          const jsonData = await result.json();
+          return jsonData;
+        } else {
+          const textData = await result.text();
+          return textData;
+        }
+      } catch (error) {
+        console.error("Error in InvokeFunctionHandler:", error);
+      }
+    },
+  };
+}

package/handlers/runtime-api/index.ts

@@ -0,0 +1,221 @@
+/**
+ * @fileoverview Runtime API - Global Functions for Handler Code
+ * @module Runtime/Handlers/RuntimeAPI
+ * 
+ * @description
+ * Main entry point that aggregates all runtime API functions available to handler code.
+ * 
+ * The Runtime API provides a rich set of global functions that handler code can use
+ * to interact with the Nuraly system. These functions are automatically injected into
+ * the execution context of every handler.
+ * 
+ * **API Categories:**
+ * 
+ * 1. **Variable Management** (`variables.ts`)
+ *    - `GetVar`, `SetVar` - Global variables
+ *    - `GetContextVar`, `SetContextVar` - App-scoped variables
+ * 
+ * 2. **Component Management** (`components.ts`)
+ *    - `GetComponent`, `GetComponents` - Component queries
+ *    - `AddComponent`, `DeleteComponentAction` - Component CRUD
+ *    - `CopyComponentToClipboard`, `PasteComponentFromClipboard` - Clipboard ops
+ * 
+ * 3. **Component Properties** (`component-properties.ts`)
+ *    - `updateName`, `updateInput`, `updateStyle`, `updateEvent` - Property updates
+ *    - `updateInputHandlers`, `updateStyleHandlers` - Handler updates
+ * 
+ * 4. **Page Management** (`pages.ts`)
+ *    - `AddPage`, `UpdatePage`, `deletePage` - Page CRUD
+ * 
+ * 5. **Application Management** (`applications.ts`)
+ *    - `UpdateApplication` - Application updates
+ * 
+ * 6. **Navigation** (`navigation.ts`)
+ *    - `NavigateToUrl`, `NavigateToHash`, `NavigateToPage` - Navigation functions
+ * 
+ * 7. **Storage** (`storage.ts`)
+ *    - `UploadFile`, `BrowseFiles` - File storage operations
+ * 
+ * 8. **Backend Functions** (`functions.ts`)
+ *    - `InvokeFunction` - Call studio backend functions
+ * 
+ * 9. **Editor** (`editor.ts`)
+ *    - `openEditorTab`, `setCurrentEditorTab` - Editor UI
+ *    - `TraitCompoentFromSchema` - Schema imports
+ *
+ * 10. **Toast Notifications** (`toast.ts`)
+ *    - `ShowToast`, `ShowSuccessToast`, `ShowErrorToast` - Toast notifications
+ *    - `ShowWarningToast`, `ShowInfoToast` - Toast variants
+ *    - `HideToast`, `ClearAllToasts` - Toast control
+ *
+ * **Usage in Handler Code:**
+ * All these functions are available directly in handler code without imports:
+ * 
+ * ```javascript
+ * // Handler code (no imports needed)
+ * const username = GetVar('username');
+ * SetVar('count', GetVar('count') + 1);
+ * NavigateToPage('Dashboard');
+ * updateInput(Current, 'text', 'static', 'Hello');
+ * ```
+ * 
+ * **Function Injection:**
+ * These functions are injected into handlers via the `HANDLER_PARAMETERS` array
+ * in `compiler.ts`. Each function is passed as a parameter when executing the
+ * compiled handler function.
+ * 
+ * @example Using Runtime API in Handlers
+ * ```javascript
+ * // Example handler code that uses multiple API functions:
+ * 
+ * // Variable management
+ * const count = GetVar('clickCount') || 0;
+ * SetVar('clickCount', count + 1);
+ * 
+ * // Component management
+ * const button = GetComponent('button-id', Current.application_id);
+ * updateStyle(button, 'backgroundColor', '#3b82f6');
+ * 
+ * // Navigation
+ * if (count + 1 >= 10) {
+ *   NavigateToPage('Congratulations');
+ * }
+ * 
+ * // Backend function call
+ * const result = await InvokeFunction('recordClick', { count: count + 1 });
+ * 
+ * // Update current component
+ * updateInput(Current, 'label', 'static', `Clicked ${count + 1} times`);
+ * ```
+ * 
+ * @example Creating and Using Global Functions
+ * ```typescript
+ * import { createGlobalHandlerFunctions } from './runtime-api';
+ * 
+ * const runtimeContext = {
+ *   context: { global: {} },
+ *   applications: {},
+ *   Apps: {},
+ *   // ... other context
+ * };
+ * 
+ * // Create all global functions
+ * const globalFunctions = createGlobalHandlerFunctions(runtimeContext);
+ * 
+ * // Now you can call them
+ * globalFunctions.SetVar('username', 'John');
+ * const username = globalFunctions.GetVar('username');
+ * ```
+ * 
+ * @see {@link ./variables.ts} for variable management functions
+ * @see {@link ./components.ts} for component management functions
+ * @see {@link ./navigation.ts} for navigation functions
+ * @see {@link ../compiler.ts} for HANDLER_PARAMETERS
+ */
+
+import { ExecuteInstance } from '../../state';
+import { createVariableFunctions } from './variables';
+import { createComponentFunctions } from './components';
+import { createComponentPropertyFunctions } from './component-properties';
+import { createPageFunctions } from './pages';
+import { createApplicationFunctions } from './applications';
+import { createNavigationFunctions } from './navigation';
+import { createStorageFunctions } from './storage';
+import { createFunctionInvocationFunctions } from './functions';
+import { createEditorFunctions } from './editor';
+import { createToastFunctions } from './toast';
+
+/**
+ * Creates all global functions available to handler code.
+ * 
+ * @description
+ * Aggregates all runtime API function creators into a single object.
+ * These functions are injected into the handler execution context and
+ * become available as global functions in handler code.
+ * 
+ * **Function Categories Created:**
+ * - Variable functions (GetVar, SetVar, GetContextVar, SetContextVar)
+ * - Component functions (GetComponent, AddComponent, DeleteComponentAction, etc.)
+ * - Component property functions (updateInput, updateStyle, updateEvent, etc.)
+ * - Page functions (AddPage, UpdatePage, deletePage)
+ * - Application functions (UpdateApplication)
+ * - Navigation functions (NavigateToPage, NavigateToUrl, NavigateToHash)
+ * - Storage functions (UploadFile, BrowseFiles)
+ * - Function invocation (InvokeFunction)
+ * - Editor functions (openEditorTab, setCurrentEditorTab, TraitCompoentFromSchema)
+ * - Toast notification functions (ShowToast, ShowSuccessToast, ShowErrorToast, etc.)
+ *
+ * **Why Create Functions This Way:**
+ * 1. **Closure over runtime context**: Functions have access to current context
+ * 2. **Modularity**: Each category in separate file for maintainability
+ * 3. **Testability**: Can create functions with mock context for testing
+ * 4. **Consistency**: All functions created with same pattern
+ * 
+ * @param {any} runtimeContext - The runtime context object containing:
+ *   - context: Global and app-scoped variables
+ *   - applications: Applications registry by ID
+ *   - Apps: Applications registry by name
+ *   - Values: Component values
+ *   - Current: Currently executing component
+ *   - Event: Current event data
+ *   - ... other runtime state
+ * 
+ * @returns {Object} Object containing all global handler functions
+ *   The returned object has ~50+ functions available to handler code
+ * 
+ * @example Creating Global Functions
+ * ```typescript
+ * import { createGlobalHandlerFunctions } from './runtime-api';
+ * import { extractRuntimeContext } from '../context-setup';
+ * 
+ * // Extract current runtime context
+ * const runtimeContext = extractRuntimeContext();
+ * 
+ * // Create all global functions with this context
+ * const globalFunctions = createGlobalHandlerFunctions(runtimeContext);
+ * 
+ * // Functions now have closure over the runtime context
+ * console.log(Object.keys(globalFunctions));
+ * // ['GetVar', 'SetVar', 'GetComponent', 'NavigateToPage', ...]
+ * ```
+ * 
+ * @example Using Created Functions
+ * ```typescript
+ * const globalFunctions = createGlobalHandlerFunctions(runtimeContext);
+ * 
+ * // Set a variable
+ * globalFunctions.SetVar('username', 'John Doe');
+ * 
+ * // Get a variable
+ * const username = globalFunctions.GetVar('username');
+ * console.log(username); // "John Doe"
+ * 
+ * // Navigate
+ * globalFunctions.NavigateToPage('Dashboard');
+ * 
+ * // Get component
+ * const component = globalFunctions.GetComponent('comp-123', 'app-1');
+ * 
+ * // Update component
+ * globalFunctions.updateInput(component, 'text', 'static', 'Hello');
+ * ```
+ * 
+ * @see {@link createVariableFunctions} for variable management
+ * @see {@link createComponentFunctions} for component management
+ * @see {@link createNavigationFunctions} for navigation
+ */
+export function createGlobalHandlerFunctions(runtimeContext: any) {
+  return {
+    ...createVariableFunctions(runtimeContext),
+    ...createComponentFunctions(runtimeContext),
+    ...createComponentPropertyFunctions(),
+    ...createPageFunctions(),
+    ...createApplicationFunctions(),
+    ...createNavigationFunctions(),
+    ...createStorageFunctions(),
+    ...createFunctionInvocationFunctions(),
+    ...createEditorFunctions(),
+    ...createToastFunctions(),
+  };
+}
+

package/handlers/runtime-api/navigation.ts

@@ -0,0 +1,52 @@
+/**
+ * Navigation Functions
+ * 
+ * Functions for navigating between pages and URLs.
+ */
+
+import { ExecuteInstance } from '../../state';
+
+export function createNavigationFunctions() {
+  return {
+    /**
+     * Navigates to a URL
+     */
+    NavigateToUrl: (url: string): void => {
+      window.location.href = url;
+      ExecuteInstance.Event?.preventDefault?.();
+      ExecuteInstance.Event?.stopPropagation?.();
+    },
+
+    /**
+     * Navigates to a hash anchor and scrolls to it
+     */
+    NavigateToHash: (hash: string): void => {
+      window.location.hash = hash;
+      if (hash) {
+        const element = document.querySelector(hash);
+        if (element) {
+          element.scrollIntoView({ behavior: 'smooth' });
+        }
+      }
+      ExecuteInstance.Event?.preventDefault?.();
+      ExecuteInstance.Event?.stopPropagation?.();
+    },
+
+    /**
+     * Navigates to a page by name within the current application
+     */
+    NavigateToPage: (pageName: string): void => {
+      ExecuteInstance.Event?.preventDefault?.();
+      ExecuteInstance.Event?.stopPropagation?.();
+      const currentEditingApplication = ExecuteInstance.GetVar("currentEditingApplication");
+      const appPages = ExecuteInstance.GetContextVar(
+        currentEditingApplication?.uuid + ".appPages",
+        currentEditingApplication?.uuid
+      );
+      const targetPage = appPages?.find((pageItem: any) => pageItem.name === pageName);
+      if (targetPage) {
+        ExecuteInstance.VarsProxy.currentPage = targetPage.uuid;
+      }
+    },
+  };
+}

package/handlers/runtime-api/pages.ts

@@ -0,0 +1,45 @@
+/**
+ * Page Management Functions
+ * 
+ * Operations for creating, updating, and deleting pages.
+ */
+
+import { addPageHandler, updatePageHandler } from '../../redux/handlers/pages/handler';
+import { deletePageAction } from '../../redux/actions/page/deletePageAction';
+import type { PageElement } from '../../redux/handlers/pages/page.interface';
+
+export function createPageFunctions() {
+  return {
+    /**
+     * Adds a new page
+     */
+    AddPage: (page: any): Promise<any> => {
+      return new Promise((resolve) => {
+        addPageHandler(page, (page: any) => {
+          resolve(page);
+        });
+      });
+    },
+
+    /**
+     * Updates an existing page
+     */
+    UpdatePage: (page: any): Promise<any> => {
+      return new Promise((resolve) => {
+        updatePageHandler(page, (page) => {
+          resolve(page);
+        });
+      });
+    },
+
+    /**
+     * Deletes a page with confirmation
+     */
+    deletePage: (page: PageElement) => {
+      const userInput = confirm("Are you sure you want to delete this page?");
+      if (userInput) {
+        deletePageAction(page);
+      }
+    },
+  };
+}

package/handlers/runtime-api/storage.ts

@@ -0,0 +1,95 @@
+/**
+ * File Storage Functions
+ * 
+ * Functions for uploading and browsing files in storage.
+ */
+
+import Editor from '../../state/editor';
+
+export function createStorageFunctions() {
+  return {
+    /**
+     * Uploads one or more files to storage
+     * 
+     * @param files - Single file or array of files to upload
+     * @param folderPath - Destination folder path
+     * @returns Upload result(s)
+     */
+    UploadFile: async (files: File | File[], folderPath: string = "my-folder"): Promise<any> => {
+      // Normalize to array
+      const fileArray = Array.isArray(files) ? files : [files];
+      
+      const results = [];
+      for (const file of fileArray) {
+        const formData = new FormData();
+        formData.append("file", file);
+        formData.append("fileName", file.name);
+        formData.append("contentType", file.type || "");
+        
+        try {
+          const response = await fetch(`/api/v1/storage/files/${folderPath}`, {
+            method: "POST",
+            body: formData,
+          });
+          
+          if (!response.ok) {
+            throw new Error(`Upload failed with status ${response.status}`);
+          }
+          
+          const result = await response.json();
+          Editor.Console.log({ message: "Upload success", data: result });
+          results.push(result);
+        } catch (err) {
+          Editor.Console.error({ message: "Upload failed", error: err });
+          throw err;
+        }
+      }
+      
+      // Return single result if single file, array if multiple
+      return results.length === 1 ? results[0] : results;
+    },
+
+    /**
+     * Browses files in a folder with pagination support
+     * 
+     * @param folderPath - Folder path to browse
+     * @param options - Browse options (continuation token, limit)
+     * @returns List of files and continuation token
+     */
+    BrowseFiles: async (
+      folderPath: string = "my-folder",
+      options: { continuation?: string | null; limit?: number } = {}
+    ): Promise<any> => {
+      try {
+        const { continuation = null, limit = 100 } = options;
+        let url = `/api/v1/storage/browse/${folderPath}`;
+        
+        const params = new URLSearchParams();
+        if (continuation) params.append("continuation", continuation);
+        if (limit) params.append("limit", limit.toString());
+        
+        if (params.toString()) {
+          url += `?${params.toString()}`;
+        }
+        
+        const response = await fetch(url, {
+          method: "GET",
+          headers: {
+            "accept": "*/*"
+          }
+        });
+        
+        if (!response.ok) {
+          throw new Error(`Browse failed with status ${response.status}`);
+        }
+        
+        const result = await response.json();
+        Editor.Console.log({ message: "Browse success", data: result });
+        return result;
+      } catch (err) {
+        Editor.Console.error({ message: "Browse failed", error: err });
+        throw err;
+      }
+    },
+  };
+}

package/handlers/runtime-api/toast.ts

@@ -0,0 +1,108 @@
+import { showToast, hideToast, clearAllToasts } from '../../../../services/toast';
+
+/**
+ * Creates toast notification functions for the runtime API
+ * These functions are available globally in all handler code (studio + micro-apps)
+ */
+export function createToastFunctions() {
+  return {
+    /**
+     * Shows a toast notification
+     * @param message - The message to display
+     * @param type - Toast type: 'success', 'error', 'warning', 'info' (default: 'info')
+     * @param options - Additional options (duration, closable)
+     * @returns Toast ID for programmatic control
+     *
+     * @example
+     * ShowToast('File saved successfully!', 'success');
+     * ShowToast('Error occurred', 'error', { duration: 5000 });
+     * ShowToast('Processing...', 'info', { duration: 0 }); // No auto-hide
+     */
+    ShowToast: (
+      message: string,
+      type: 'success' | 'error' | 'warning' | 'info' = 'info',
+      options?: { duration?: number; closable?: boolean }
+    ): string => {
+      return showToast({
+        message,
+        type,
+        ...options
+      });
+    },
+
+    /**
+     * Shows a success toast (convenience function)
+     * @param message - Success message
+     * @param duration - Display duration in milliseconds (default: 3000)
+     * @returns Toast ID
+     *
+     * @example
+     * ShowSuccessToast('Operation completed!');
+     */
+    ShowSuccessToast: (message: string, duration = 3000): string => {
+      return showToast({ message, type: 'success', duration });
+    },
+
+    /**
+     * Shows an error toast (convenience function)
+     * @param message - Error message
+     * @param duration - Display duration in milliseconds (default: 5000)
+     * @returns Toast ID
+     *
+     * @example
+     * ShowErrorToast('Failed to save file');
+     */
+    ShowErrorToast: (message: string, duration = 5000): string => {
+      return showToast({ message, type: 'error', duration });
+    },
+
+    /**
+     * Shows a warning toast (convenience function)
+     * @param message - Warning message
+     * @param duration - Display duration in milliseconds (default: 4000)
+     * @returns Toast ID
+     *
+     * @example
+     * ShowWarningToast('This action cannot be undone');
+     */
+    ShowWarningToast: (message: string, duration = 4000): string => {
+      return showToast({ message, type: 'warning', duration });
+    },
+
+    /**
+     * Shows an info toast (convenience function)
+     * @param message - Info message
+     * @param duration - Display duration in milliseconds (default: 3000)
+     * @returns Toast ID
+     *
+     * @example
+     * ShowInfoToast('Loading data...');
+     */
+    ShowInfoToast: (message: string, duration = 3000): string => {
+      return showToast({ message, type: 'info', duration });
+    },
+
+    /**
+     * Hides a specific toast by ID
+     * @param id - Toast ID returned from ShowToast
+     *
+     * @example
+     * const toastId = ShowToast('Processing...', 'info', { duration: 0 });
+     * // ... later
+     * HideToast(toastId);
+     */
+    HideToast: (id: string): void => {
+      hideToast(id);
+    },
+
+    /**
+     * Clears all active toasts
+     *
+     * @example
+     * ClearAllToasts();
+     */
+    ClearAllToasts: (): void => {
+      clearAllToasts();
+    }
+  };
+}