@nuraly/runtime 0.1.7 → 0.1.9

package/handlers/handler-scope.ts

@@ -0,0 +1,398 @@
+/**
+ * @fileoverview Handler Scope - Transparent Variable Access with $ Prefix
+ * @module Runtime/Handlers/HandlerScope
+ *
+ * @description
+ * Creates a scope proxy that enables transparent reactive variable access in handlers.
+ * Variables prefixed with `$` are automatically routed to VarsProxy for reactivity.
+ *
+ * This provides clear visual distinction between:
+ * - `$username` → Reactive state (persisted in Vars, triggers updates)
+ * - `username` → Local variable (temporary, disappears after handler)
+ *
+ * @example User writes:
+ * ```javascript
+ * // Reactive variables (stored in Vars)
+ * $username = 'John'
+ * $count = $count + 1
+ *
+ * // Local variables (temporary)
+ * let temp = 'hello'
+ * const MAX = 100
+ * ```
+ *
+ * @example Which behaves like:
+ * ```javascript
+ * $username = 'John'
+ * $count = $count + 1
+ *
+ * let temp = 'hello'
+ * const MAX = 100
+ * ```
+ */
+
+/**
+ * Set of reserved parameter names that should NOT be routed to $
+ * These are the built-in handler parameters and global objects.
+ */
+const RESERVED_NAMES = new Set([
+  // Core runtime parameters
+  'eventHandler',
+  'Components',
+  'Editor',
+  'Event',
+  'Item',
+  'Current',
+  'currentPlatform',
+  'Values',
+  'Apps',
+  'Vars',
+  'Instance',
+
+  // Namespaced APIs (new clean API)
+  'Nav',
+  'UI',
+  'Component',
+  'Data',
+  'Page',
+  'App',
+  'Var',
+
+  // Variable functions
+  'SetVar',
+  'GetContextVar',
+  'GetVar',
+  'SetContextVar',
+
+  // Component functions
+  'GetComponent',
+  'GetComponents',
+  'AddComponent',
+  'DeleteComponentAction',
+  'CopyComponentToClipboard',
+  'PasteComponentFromClipboard',
+
+  // Application functions
+  'UpdateApplication',
+  'context',
+  'applications',
+
+  // Page functions
+  'AddPage',
+  'UpdatePage',
+  'deletePage',
+
+  // Navigation functions
+  'NavigateToUrl',
+  'NavigateToHash',
+  'NavigateToPage',
+
+  // Property update functions
+  'updateInput',
+  'updateName',
+  'updateEvent',
+  'updateStyle',
+  'updateStyleHandlers',
+
+  // Editor functions
+  'openEditorTab',
+  'setCurrentEditorTab',
+  'TraitCompoentFromSchema',
+
+  // Other functions
+  'InvokeFunction',
+  'Utils',
+  'console',
+  'UploadFile',
+  'BrowseFiles',
+  'EventData',
+
+  // Toast functions
+  'ShowToast',
+  'ShowSuccessToast',
+  'ShowErrorToast',
+  'ShowWarningToast',
+  'ShowInfoToast',
+  'HideToast',
+  'ClearAllToasts',
+
+  // JavaScript built-ins that must be preserved
+  'undefined',
+  'null',
+  'true',
+  'false',
+  'NaN',
+  'Infinity',
+  'globalThis',
+  'window',
+  'self',
+
+  // Common globals
+  'Math',
+  'JSON',
+  'Date',
+  'Array',
+  'Object',
+  'String',
+  'Number',
+  'Boolean',
+  'RegExp',
+  'Error',
+  'TypeError',
+  'ReferenceError',
+  'SyntaxError',
+  'Promise',
+  'Map',
+  'Set',
+  'WeakMap',
+  'WeakSet',
+  'Symbol',
+  'Proxy',
+  'Reflect',
+  'parseInt',
+  'parseFloat',
+  'isNaN',
+  'isFinite',
+  'encodeURI',
+  'decodeURI',
+  'encodeURIComponent',
+  'decodeURIComponent',
+  'setTimeout',
+  'setInterval',
+  'clearTimeout',
+  'clearInterval',
+  'fetch',
+  'Request',
+  'Response',
+  'Headers',
+  'URL',
+  'URLSearchParams',
+  'FormData',
+  'Blob',
+  'File',
+  'FileReader',
+  'atob',
+  'btoa',
+  'crypto',
+  'performance',
+  'queueMicrotask',
+  'requestAnimationFrame',
+  'cancelAnimationFrame',
+
+  // Control flow keywords (not variables but good to have)
+  'arguments',
+  'this',
+]);
+
+/**
+ * Configuration for creating a handler scope
+ */
+export interface HandlerScopeConfig {
+  /** The VarsProxy for reactive variable access */
+  VarsProxy: Record<string, any>;
+
+  /** All handler parameters as key-value pairs */
+  parameters: Record<string, any>;
+}
+
+/**
+ * Check if a property name is a reactive variable (starts with $)
+ */
+function isReactiveVar(prop: string): boolean {
+  return prop.startsWith('$') && prop.length > 1;
+}
+
+/**
+ * Strip the $ prefix from a reactive variable name
+ */
+function stripPrefix(prop: string): string {
+  return prop.slice(1);
+}
+
+/**
+ * Creates a handler execution scope that enables transparent variable access.
+ *
+ * The returned proxy intercepts all property access:
+ * - Reserved names (Current, Event, etc.) return their actual values
+ * - `$`-prefixed names are routed to VarsProxy for reactive get/set
+ * - Other names resolve normally (local variables, globals)
+ *
+ * This is used with JavaScript's `with` statement to create a scope
+ * where `$`-prefixed variables automatically become reactive.
+ *
+ * @param config - Configuration with VarsProxy and parameters
+ * @returns A Proxy that can be used with `with` statement
+ *
+ * @example
+ * ```typescript
+ * const scope = createHandlerScope({
+ *   VarsProxy: context.VarsProxy,
+ *   parameters: { Current, Event, Apps, ... }
+ * });
+ *
+ * // Execute code with transparent variable access
+ * with (scope) {
+ *   $username = 'John';  // Sets VarsProxy.username (reactive)
+ *   $count++;            // Increments VarsProxy.count (reactive)
+ *   let temp = 'local';  // Local variable (not reactive)
+ * }
+ * ```
+ */
+export function createHandlerScope(config: HandlerScopeConfig): any {
+  const { VarsProxy, parameters } = config;
+
+  return new Proxy(parameters, {
+    /**
+     * The `has` trap is critical for `with` statement behavior.
+     * We claim to have:
+     * - All reserved names (handler parameters)
+     * - All $-prefixed names (reactive variables)
+     */
+    has(target, prop) {
+      const propStr = String(prop);
+
+      // Always claim reserved names
+      if (RESERVED_NAMES.has(propStr)) {
+        return true;
+      }
+
+      // Claim $-prefixed names for reactive variable access
+      if (isReactiveVar(propStr)) {
+        return true;
+      }
+
+      // Check if it's a handler parameter
+      if (propStr in target) {
+        return true;
+      }
+
+      // For other names, let them resolve normally (local vars, globals)
+      // Returning false lets the `with` statement fall through to outer scope
+      return false;
+    },
+
+    /**
+     * Get property value.
+     * - Reserved names get their actual values
+     * - $-prefixed names get from VarsProxy (without the $ prefix)
+     * - Other names shouldn't reach here (has() returns false)
+     */
+    get(target, prop, receiver) {
+      const propStr = String(prop);
+
+      // Symbol properties go to target
+      if (typeof prop === 'symbol') {
+        return target[prop];
+      }
+
+      // $-prefixed: route to VarsProxy (strip the $ prefix)
+      if (isReactiveVar(propStr)) {
+        const varName = stripPrefix(propStr);
+        return VarsProxy[varName];
+      }
+
+      // Reserved names: return actual parameter value or global
+      if (RESERVED_NAMES.has(propStr)) {
+        if (propStr in target) {
+          return target[propStr];
+        }
+        // Try globalThis for built-ins
+        if (propStr in globalThis) {
+          const value = (globalThis as any)[propStr];
+          // Bind functions that need 'this' context (like fetch, setTimeout, etc.)
+          if (typeof value === 'function' && ['fetch', 'setTimeout', 'setInterval', 'clearTimeout', 'clearInterval', 'requestAnimationFrame', 'cancelAnimationFrame', 'queueMicrotask'].includes(propStr)) {
+            return value.bind(globalThis);
+          }
+          return value;
+        }
+        return undefined;
+      }
+
+      // Check if it's a handler parameter
+      if (propStr in target) {
+        return target[propStr];
+      }
+
+      // Fallback to undefined (shouldn't normally reach here)
+      return undefined;
+    },
+
+    /**
+     * Set property value.
+     * - $-prefixed names set to VarsProxy (without the $ prefix)
+     * - Reserved names update actual values
+     * - Other names shouldn't reach here
+     */
+    set(target, prop, value, receiver) {
+      const propStr = String(prop);
+
+      // Symbol properties go to target
+      if (typeof prop === 'symbol') {
+        target[prop] = value;
+        return true;
+      }
+
+      // $-prefixed: route to VarsProxy (strip the $ prefix)
+      if (isReactiveVar(propStr)) {
+        const varName = stripPrefix(propStr);
+        VarsProxy[varName] = value;
+        return true;
+      }
+
+      // Don't allow setting reserved globals
+      if (RESERVED_NAMES.has(propStr) && propStr in globalThis) {
+        // Allow setting if it's a handler parameter (like Instance)
+        if (propStr in target) {
+          target[propStr] = value;
+          return true;
+        }
+        // Ignore attempts to set globals
+        return true;
+      }
+
+      // Check if it's a handler parameter
+      if (propStr in target && RESERVED_NAMES.has(propStr)) {
+        target[propStr] = value;
+        return true;
+      }
+
+      // For non-$-prefixed, non-reserved: this shouldn't happen
+      // but if it does, store on target
+      target[propStr] = value;
+      return true;
+    },
+
+    /**
+     * Property descriptor for iteration support
+     */
+    getOwnPropertyDescriptor(target, prop) {
+      const propStr = String(prop);
+
+      // $-prefixed: describe from VarsProxy
+      if (isReactiveVar(propStr)) {
+        const varName = stripPrefix(propStr);
+        if (varName in VarsProxy) {
+          return {
+            configurable: true,
+            enumerable: true,
+            value: VarsProxy[varName],
+            writable: true,
+          };
+        }
+        // Return a descriptor anyway so the variable can be set
+        return {
+          configurable: true,
+          enumerable: true,
+          value: undefined,
+          writable: true,
+        };
+      }
+
+      if (propStr in target) {
+        return Object.getOwnPropertyDescriptor(target, propStr);
+      }
+
+      return undefined;
+    },
+  });
+}

package/handlers/index.ts

@@ -144,14 +144,17 @@ export {
 /**
  * Handler compilation utilities with automatic caching.
  * Compiles JavaScript code strings into executable functions.
- * 
+ *
  * @see {@link compiler.ts} for implementation details
  */
 export {
   compileHandlerFunction,
   clearHandlerCache,
   getHandlerCacheSize,
-  HANDLER_PARAMETERS
+  HANDLER_PARAMETERS,
+  setTransparentVarsEnabled,
+  isTransparentVarsEnabled,
+  createHandlerScope
 } from './compiler';
 
 // ============================================================================
@@ -182,3 +185,32 @@ export {
 export {
   createGlobalHandlerFunctions
 } from './runtime-api';
+
+// ============================================================================
+// Namespaced Handler API
+// ============================================================================
+
+/**
+ * Namespaced Handler API for clean, organized access to runtime functions.
+ * Provides Nav, UI, Component, Data, Page, App, Var namespaces.
+ *
+ * @see {@link handler-api.ts} for type definitions
+ * @see {@link handler-api-factory.ts} for factory implementation
+ */
+export {
+  createHandlerAPI,
+  extractLegacyParameters
+} from './handler-api-factory';
+
+export type {
+  HandlerAPI,
+  NavAPI,
+  UIAPI,
+  ComponentAPI,
+  DataAPI,
+  PageAPI,
+  AppAPI,
+  EditorAPI,
+  VarAPI,
+  ToastType
+} from './handler-api';

package/handlers/runtime-api/component-properties.ts

@@ -25,14 +25,6 @@ export function createComponentPropertyFunctions() {
       updateComponentAttributes(component.application_id, component.uuid, "input", eventData);
     },
 
-    /**
-     * Updates component input handlers
-     */
-    updateInputHandlers: (component: ComponentElement, inputName: string, value: any) => {
-      const eventData = { [inputName]: value };
-      updateComponentAttributes(component.application_id, component.uuid, "inputHandlers", eventData);
-    },
-
     /**
      * Updates component event handler
      */

package/handlers/runtime-api/index.ts

@@ -22,7 +22,7 @@
  * 
  * 3. **Component Properties** (`component-properties.ts`)
  *    - `updateName`, `updateInput`, `updateStyle`, `updateEvent` - Property updates
- *    - `updateInputHandlers`, `updateStyleHandlers` - Handler updates
+ *    - `updateStyleHandlers` - Style handler updates
  * 
  * 4. **Page Management** (`pages.ts`)
  *    - `AddPage`, `UpdatePage`, `deletePage` - Page CRUD

package/handlers/runtime-api/toast.ts

@@ -1,4 +1,4 @@
-import { showToast, hideToast, clearAllToasts } from '../../../../services/toast';
+import { showToast, hideToast, clearAllToasts } from '../../utils/toast';
 
 /**
  * Creates toast notification functions for the runtime API

package/index.ts

@@ -1,59 +1,3 @@
-/**
- * @module Runtime
- * @description Nuraly Runtime System - Core execution engine for the visual web application builder
- * 
- * The Runtime System is responsible for:
- * - **Handler Execution**: Compiling and executing JavaScript code from component properties
- * - **State Management**: Reactive state with proxy-based change detection
- * - **Component Lifecycle**: Managing component registration, hierarchy, and relationships
- * - **Runtime API**: Providing rich APIs for components to interact with the system
- * - **Editor Integration**: Connecting studio editor with runtime execution environment
- * 
- * @example Basic Usage
- * ```typescript
- * import { executeHandler, ExecuteInstance, Editor } from './';
- * 
- * // Execute a handler
- * const result = executeHandler(component, "GetVar('username')", { event: clickEvent });
- * 
- * // Access runtime state
- * ExecuteInstance.VarsProxy.username = 'John Doe';
- * const theme = ExecuteInstance.GetVar('theme');
- * 
- * // Check editor mode
- * if (Editor.getEditorMode()) {
- *   console.log('Running in editor mode');
- * }
- * ```
- * 
- * @example Advanced Usage - Creating Dynamic Applications
- * ```typescript
- * import { executeHandler, ExecuteInstance } from './';
- * 
- * // Handler code for dynamic component behavior
- * const handlerCode = `
- *   const count = GetVar('count') || 0;
- *   SetVar('count', count + 1);
- *   updateInput(Current, 'text', 'static', \`Clicked \${count + 1} times\`);
- * `;
- * 
- * // Execute handler when button is clicked
- * executeHandler(buttonComponent, handlerCode, { event: clickEvent });
- * ```
- * 
- * @see {@link ./README.md} for comprehensive documentation
- * @see {@link ./handlers/README.md} for handler execution details
- * @see {@link ./state/README.md} for state management details
- */
-
-// ============================================================================
-// Core Runtime Context and State Management
-// ============================================================================
-
-/**
- * RuntimeInstance - Main singleton instance of the RuntimeContext
- * @see {@link RuntimeContext} in ./state/runtime-context.ts
- */
 export {
   RuntimeInstance,
   ExecuteInstance,
@@ -61,16 +5,7 @@ export {
   RuntimeHelpers
 } from './state';
 
-// ============================================================================
-// Redux Store - Application State
-// ============================================================================
-
-/**
- * Redux store atoms for component, application, page, and environment state
- * @see {@link ./redux/store} for store definitions
- */
 export {
-  // Component Store
   $components,
   $applicationComponents,
   $selectedComponent,
@@ -99,12 +34,10 @@ export {
   fillApplicationComponents,
   extractChildresIds,
   extractAllChildrenIds,
-  // Application Store
   $applications,
   $currentApplication,
   $editorState,
   $resizing,
-  // Page Store
   $pages,
   $currentPage,
   $currentPageViewPort,
@@ -116,73 +49,39 @@ export {
   $pageSize,
   $applicationPages,
   refreshPageStoreVar,
-  // Context/Variables Store
   $context,
-  // Environment Store
   ViewMode,
   $environment,
-  // Toast Store
   $toasts,
-  // Debug Store
   $debug,
-  // Provider Store
   $providers,
-  // Component Types
   type ComponentElement,
   type PageElement
 } from './redux/store';
 
-// ============================================================================
-// Redux Actions
-// ============================================================================
-
-/**
- * Redux action creators for state mutations
- * @see {@link ./redux/actions} for action definitions
- */
 export * from './redux/actions';
-
-// ============================================================================
-// Redux Handlers
-// ============================================================================
-
-/**
- * Redux handlers for complex state transformations
- * @see {@link ./redux/handlers} for handler definitions
- */
 export * from './redux/handlers';
 
-// ============================================================================
-// Handler Execution System
-// ============================================================================
-
-/**
- * Handler execution utilities for compiling and running component handlers
- * @see {@link executeHandler} in ./handlers/handler-executor.ts
- * @see {@link compileHandlerFunction} in ./handlers/compiler.ts
- * @see {@link getContextFromComponent} in ./handlers/handler-executor.ts
- */
 export {
   executeHandler,
   getContextFromComponent,
   compileHandlerFunction
 } from './handlers';
 
-// ============================================================================
-// Utilities
-// ============================================================================
-
-/**
- * Utility functions for rendering, logging, validation, and more
- * @see {@link ./utils} for utility definitions
- */
 export * from './utils';
 
-// ============================================================================
-// Runtime Components
-// ============================================================================
+export {
+  ComponentRegistry,
+  registerComponent,
+  registerComponents,
+  type ComponentRegistrationOptions,
+  type ComponentTemplateFunction,
+  type ComponentRenderProps,
+  type RegisteredComponent
+} from './utils/component-registry';
 
-/**
- * Note: MicroApp component was removed from runtime exports to prevent circular dependencies.
- * Import MicroApp directly from '../../shared/ui/components/runtime/MicroApp/MicroApp' if needed.
- */
+export {
+  BaseElementBlock as BaseElement,
+  BaseElementBlock,
+  BaseElementCore
+} from './components/ui/components/base/BaseElement';