rotor-framework 0.3.2

package/src/source/base/BaseViewModel.bs

@@ -0,0 +1,124 @@
+namespace Rotor
+
+    ' =====================================================================
+    ' ViewModel (BaseViewModel) - Base class for ViewModels that extends Widget to provide view lifecycle management
+    '
+    ' ViewModels act as controllers for views, managing:
+    '   - props: Immutable properties passed from parent (read-only)
+    '   - viewModelState: Mutable local state (read-write)
+    '   - template: Declarative UI structure
+    '   - Lifecycle hooks: onCreateView, onMountView, onUpdateView, onDestroyView
+    '
+    ' Key Features:
+    '   - Scoped state: props and viewModelState shared across all child widgets
+    '   - Template system: template() returns widget tree configuration
+    '   - Lifecycle management: Hooks for view creation, mounting, updates, destruction
+    '   - No prop drilling: Children access parent ViewModel state directly
+    ' =====================================================================
+    class ViewModel extends Rotor.Widget
+
+        ' =============================================================
+        ' MEMBER VARIABLES
+        ' =============================================================
+
+        isViewModel = true              ' Identifies this as a ViewModel
+
+        viewModelState = {}             ' Mutable state shared across ViewModel's widgets
+        props = {}                      ' Immutable props shared across ViewModel's widgets
+
+        ' =============================================================
+        ' PROPS MANAGEMENT
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' setProps - Updates props and triggers view update
+        '
+        ' Merges new props into existing props and calls onUpdateView lifecycle hook.
+        '
+        ' @param {object} newProps - New properties to merge
+        '
+        sub setProps(newProps as object)
+            m.props.append(newProps)
+            m.onUpdateView()
+        end sub
+
+        ' =============================================================
+        ' LIFECYCLE HOOKS
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' onCreateView - Called when view is being created
+        '
+        ' Override to perform initialization tasks before template is generated.
+        ' Use this to set up initial viewModelState or props.
+        '
+        sub onCreateView()
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' onTemplateCreated - Called after template has been created
+        '
+        ' Override to access and modify the created template structure.
+        ' Useful for dynamic template manipulation.
+        '
+        ' @param {object} template - The created template object
+        '
+        sub onTemplateCreated(template as object)
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' onMountView - Called when view is mounted to SceneGraph
+        '
+        ' Override to perform post-mount operations like starting animations,
+        ' fetching data, or setting up observers.
+        '
+        sub onMountView()
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' onUpdateView - Called when view needs to update
+        '
+        ' Override to handle state or props changes.
+        ' Called automatically when setProps() is invoked.
+        '
+        sub onUpdateView()
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' onDestroyView - Called when view is being destroyed
+        '
+        ' Override to perform cleanup tasks like removing observers,
+        ' stopping timers, or clearing resources.
+        '
+        sub onDestroyView()
+        end sub
+
+        ' =============================================================
+        ' TEMPLATE
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' template - Returns view template structure
+        '
+        ' Override to define custom view structure using declarative widget config.
+        ' Return an object with widget configuration including children.
+        '
+        ' @returns {object} Widget tree configuration
+        '
+        ' Example:
+        '   function template() as object
+        '       return {
+        '           nodeType: "Group",
+        '           children: [
+        '               { id: "label", nodeType: "Label", fields: { text: m.props.title } }
+        '           ]
+        '       }
+        '   end function
+        '
+        function template() as object
+            return {}
+        end function
+
+    end class
+
+end namespace

package/src/source/base/BaseWidget.bs

@@ -0,0 +1,104 @@
+namespace Rotor
+
+    ' =====================================================================
+    ' Widget (BaseWidget) - Base class for UI components in the Rotor framework
+    '
+    ' Widgets are the fundamental building blocks of the UI tree, providing:
+    '   - Lifecycle management (mount, update, destroy)
+    '   - Tree navigation methods
+    '   - State access (viewModelState, props)
+    '   - Rendering and updates
+    '   - Plugin integration
+    '
+    ' IMPORTANT: Many properties and methods are injected/decorated by the
+    ' framework builder and plugins during widget instantiation.
+    '
+    ' Widget Creation Flow:
+    '   1. builder.WidgetTreeBase.add() - Registers widget in tree
+    '   2. builder.processor.createWidget() - Decorates with methods
+    ' =====================================================================
+    class Widget
+
+        ' =============================================================
+        ' CORE PROPERTIES
+        ' =============================================================
+
+        id as string                    ' Widget identifier
+        children as object              ' Child widgets collection
+
+        ' =============================================================
+        ' RUNTIME-INJECTED PROPERTIES
+        ' =============================================================
+        ' These are populated by the builder during widget creation
+
+        node as object                  ' SceneGraph node reference
+        parent as object                ' Parent widget reference
+        plugins as object               ' Plugin methods and state
+
+        viewModelState as object        ' Mutable state shared across ViewModel's widgets
+        props as object                 ' Immutable props shared across ViewModel's widgets
+        nodeType as string              ' SceneGraph node type (e.g., "Group", "Label")
+        zIndex as integer               ' Z-order for rendering
+
+        ' =============================================================
+        ' LIFECYCLE CALLBACKS
+        ' =============================================================
+
+        onMountWidget as Function       ' Called after widget is mounted
+        onUpdateWidget as Function      ' Called before widget updates
+        onDestroyWidget as Function     ' Called before widget is destroyed
+
+        ' =============================================================
+        ' DECORATED METHODS
+        ' =============================================================
+        ' These methods are injected by WidgetCreate.bs
+
+        ' Tree Navigation
+        getWidget as Function           ' Find widget by ID or path (any depth)
+        findWidgets as Function         ' Find widgets by glob pattern
+        getChildrenWidgets as Function  ' Get direct children (optionally filtered)
+        getSiblingWidget as Function    ' Get sibling widget by ID
+        getSubtreeClone as Function     ' Clone widget subtree
+
+        ' ViewModel Access
+        getParentViewModel as Function  ' Get parent ViewModel
+        getViewModel as Function        ' Get owning ViewModel
+        getRootWidget as Function       ' Get root widget (HID "0")
+
+        ' Rendering
+        render as Function              ' Render widget updates
+        refresh as Function             ' Refresh specific properties by key paths
+        erase as Function               ' Remove widget(s) from tree
+
+        ' Framework Integration
+        getFrameworkInstance as Function ' Get framework instance
+        getDispatcher as Function       ' Get dispatcher facade by ID
+        createDispatcher as Function    ' Create dispatcher
+        animator as Function            ' Get animator factory
+
+        ' =============================================================
+        ' PLUGIN METHODS
+        ' =============================================================
+        ' These are optionally injected by plugins
+
+        ' Focus Plugin Methods (from FocusPlugin.bs)
+        optional enableFocusNavigation as function   ' Enable focus navigation
+        optional isFocusNavigationEnabled as function ' Check if focus enabled
+        optional setFocus as function                ' Set focus on widget
+        optional getFocusedWidget as function        ' Get currently focused widget
+        optional proceedLongPress as function        ' Trigger long press
+        optional isLongPressActive as function       ' Check if long press active
+
+        ' =============================================================
+        ' PRIVATE PROPERTIES (Engine Use Only)
+        ' =============================================================
+
+        private HID as string           ' Hierarchical ID (e.g., "0.header.logo")
+        private vmHID as string         ' Owning ViewModel's HID
+        private isRootChild as boolean  ' True if direct child of root
+        private childrenHIDhash as object ' Hash of child HIDs for fast lookup
+        private parentHID as string     ' Parent's HID
+
+    end class
+
+end namespace

package/src/source/base/DispatcherCreator.bs

@@ -0,0 +1,193 @@
+import "ListenerForDispatchers.bs"
+
+namespace Rotor
+
+    ' =====================================================================
+    ' createDispatcher - Factory function for creating dispatchers
+    '
+    ' Creates a dispatcher instance and returns its facade for external use.
+    '
+    ' @param {string} customDispatcherId - Dispatcher identifier
+    ' @param {Model} modelInstance - Model holding state
+    ' @param {Reducer} reducerInstance - Reducer for state transitions
+    ' @returns {Dispatcher} Dispatcher facade instance
+    ' =====================================================================
+    sub createDispatcher(customDispatcherId as string, modelInstance as Model, reducerInstance as Reducer)
+        m.dispatcherInstance = new Rotor.DispatcherCreator(customDispatcherId, modelInstance, reducerInstance)
+    end sub
+
+    ' =====================================================================
+    ' DispatcherCreator - Internal dispatcher implementation for MVI pattern state management
+    '
+    ' Responsibilities:
+    '   - Dispatches intents to reducer
+    '   - Manages state updates via Model
+    '   - Notifies listeners of state changes
+    '   - Handles dispatch queue to prevent reentrancy
+    '   - Exposes state to render thread via task node field
+    '
+    ' MVI Flow:
+    '   dispatch(intent) → reducer.reduce() → update state → notify listeners
+    ' =====================================================================
+    class DispatcherCreator extends ListenerForDispatchers
+
+        ' =============================================================
+        ' MEMBER VARIABLES
+        ' =============================================================
+
+        middlewares = []                ' Middleware array (unused, handled by Reducer)
+        isExternal = false              ' False for internal dispatchers
+        isDispatchingInProgress = false ' Prevents reentrant dispatch
+        dispatchQueue = []              ' Queue for intents during active dispatch
+        dispatcherId as string          ' Dispatcher identifier
+        taskNode as object              ' Task node for cross-thread state exposure
+        reducerInstance as object       ' Reducer instance
+        modelInstance as object         ' Model instance holding state
+        listeners = []                  ' State change listeners
+
+        ' =============================================================
+        ' CONSTRUCTOR
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' Constructor - Initializes dispatcher and registers with provider
+        '
+        ' @param {string} dispatcherId - Dispatcher identifier (auto-generated if empty)
+        ' @param {object} modelInstance - Model instance
+        ' @param {object} reducerInstance - Reducer instance
+        '
+        sub new(dispatcherId = "" as string, modelInstance = invalid as object, reducerInstance = invalid as object)
+            super()
+            if dispatcherId = "" then dispatcherId = Rotor.Utils.getUUIDHex()
+            m.dispatcherId = dispatcherId
+
+            globalScope = GetGlobalAA()
+            m.taskNode = globalScope.top
+
+            ' Link reducer to this dispatcher
+            m.reducerInstance = reducerInstance
+            m.reducerInstance.ownerDispatcher = m
+            m.reducerInstance.ownerDispatcherId = dispatcherId
+            m.modelInstance = modelInstance
+
+            ' Create field on task node for render thread communication
+            m.taskNode.addField(m.dispatcherId, "node", true)
+
+            ' Expose initial state
+            m.exposeState()
+
+            ' Register with dispatcher provider
+            dispatcherProvider = globalScope.rotor_framework_helper.frameworkInstance.dispatcherProvider
+            dispatcherProvider.registerDispatcher(m, dispatcherId)
+        end sub
+
+        ' =============================================================
+        ' STATE MANAGEMENT
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' exposeState - Exposes current state to render thread via task node field
+        '
+        ' Creates a ContentNode with state fields and sets it on task node.
+        ' This allows render thread to observe state changes.
+        '
+        sub exposeState()
+            newState = CreateObject("roSGNode", "ContentNode")
+            newState.addFields(m.modelInstance.state)
+            m.taskNode.setField(m.dispatcherId, newState)
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' getState - Returns current state (optionally mapped)
+        '
+        ' @param {dynamic} mapStateToProps - Optional mapping function
+        ' @param {object} callerScope - Caller scope for mapping function
+        ' @returns {object} Current state
+        '
+        function getState(mapStateToProps = invalid as Dynamic, callerScope = invalid as object) as object
+            state = m.modelInstance.state
+            m.runMapStateToProps(state, mapStateToProps, callerScope)
+            return state
+        end function
+
+        ' =============================================================
+        ' DISPATCH
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' dispatch - Dispatches intent to reducer and updates state
+        '
+        ' Process flow:
+        '   1. Validate intent payload
+        '   2. If not dispatching, execute reducer and notify listeners
+        '   3. If dispatching, queue intent for later processing
+        '   4. Process queued intents after completion
+        '
+        ' @param {Intent} intent - Intent object to dispatch
+        '
+        sub dispatch(intent as Intent)
+            if intent?.payload <> invalid and intent.payload.Count() > 1 and intent.payload = invalid
+                throw "[WARNING] Intent payload is invalid."
+            end if
+
+            if m.isDispatchingInProgress = false
+                ' Execute reducer
+                currentState = m.modelInstance.state
+                newState = m.reducerInstance.reduce(currentState, intent)
+
+                ' Middleware cancelled intent
+                if newState = invalid then return
+
+                ' Update state and notify
+                m.exposeState()
+                m.notifyListeners(newState)
+
+                ' Process queued intents
+                if m.dispatchQueue.Count() > 0
+                    intent = m.dispatchQueue.shift()
+                    m.dispatch(intent)
+                end if
+            else
+                ' Queue intent to prevent reentrancy
+                m.dispatchQueue.push(intent)
+            end if
+        end sub
+
+        ' =============================================================
+        ' ASYNC CALLBACK
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' asyncReducerCallback - Routes async callback to reducer
+        '
+        ' @param {object} msg - Message from async operation
+        '
+        sub asyncReducerCallback(msg)
+            m.reducerInstance.asyncReducerCallback(msg)
+        end sub
+
+        ' =============================================================
+        ' CLEANUP
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' destroy - Cleans up dispatcher resources
+        '
+        ' Deregisters from provider and clears all references.
+        '
+        override sub destroy()
+            super.destroy()
+
+            m.dispatchQueue.clear()
+
+            frameworkInstance = GetGlobalAA().rotor_framework_helper.frameworkInstance
+            frameworkInstance.dispatcherProvider.deregisterDispatcher(m.dispatcherId)
+
+            m.taskNode = invalid
+            m.modelInstance = invalid
+            m.reducerInstance = invalid
+        end sub
+
+    end class
+
+end namespace

package/src/source/base/DispatcherExternal.bs

@@ -0,0 +1,260 @@
+import "ListenerForDispatchers.bs"
+
+namespace Rotor
+
+    ' =====================================================================
+    ' DispatcherExternal - External dispatcher for cross-thread MVI state management
+    '
+    ' This dispatcher is used when accessing dispatchers from a different thread
+    ' than where they were created (render thread accessing task thread dispatcher
+    ' or vice versa).
+    '
+    ' Responsibilities:
+    '   - Dispatches intents across thread boundaries via rotorSync field
+    '   - Observes state changes on task node field
+    '   - Manages cross-thread listener notifications
+    '   - Lazy observer setup (only when listeners are added)
+    '   - Auto cleanup when last listener is removed
+    '
+    ' MVI Cross-Thread Flow:
+    '   Render Thread: dispatch(intent) → rotorSync field → Task Thread
+    '   Task Thread: reduce state → task node field → Render Thread observer callback
+    ' =====================================================================
+    class DispatcherExternal extends ListenerForDispatchers
+
+        ' =============================================================
+        ' MEMBER VARIABLES
+        ' =============================================================
+
+        dispatcherId as string          ' Dispatcher identifier
+        taskNode as object              ' Task node for cross-thread communication
+        threadType as string            ' Current thread type (RENDER or TASK)
+        isExternal = true               ' True for external dispatchers
+        isStateObserved = false         ' Tracks if observer is active
+
+        ' =============================================================
+        ' CONSTRUCTOR
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' Constructor - Initializes external dispatcher
+        '
+        ' @param {string} dispatcherId - Dispatcher identifier
+        ' @param {object} taskNode - Task node for cross-thread communication
+        ' @param {string} threadType - Current thread type (RENDER or TASK)
+        '
+        sub new(dispatcherId as string, taskNode as object, threadType as string)
+            super()
+
+            ' Store dispatcher configuration
+            m.dispatcherId = dispatcherId
+            m.taskNode = taskNode
+            m.threadType = threadType
+        end sub
+
+        ' =============================================================
+        ' DISPATCH
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' dispatch - Sends intent to internal dispatcher via cross-thread sync
+        '
+        ' Process flow:
+        '   1. Validate intent payload
+        '   2. Package intent with dispatcher ID
+        '   3. Set rotorSync field to trigger task thread processing
+        '
+        ' @param {Intent} intent - Intent object to dispatch
+        '
+        sub dispatch(intent as Intent)
+            ' Validate intent payload
+            if intent?.payload <> invalid and intent.payload.Count() > 1 and intent.payload = invalid
+                throw "[WARNING] Intent payload is invalid."
+            end if
+
+            ' Send intent to task thread via rotorSync field
+            m.taskNode.setField("rotorSync", {
+                type: Rotor.Const.ThreadSyncType.DISPATCH,
+                payload: {
+                    dispatcherId: m.dispatcherId,
+                    intent: intent
+                }
+            })
+        end sub
+
+        ' =============================================================
+        ' STATE ACCESS
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' getState - Returns current state from task node field (optionally mapped)
+        '
+        ' Reads state from task node field set by internal dispatcher.
+        '
+        ' @param {dynamic} mapStateToProps - Optional mapping function
+        ' @param {object} callerScope - Caller scope for mapping function
+        ' @returns {object} Current state
+        '
+        function getState(mapStateToProps = invalid as Dynamic, callerScope = invalid as object) as object
+            ' Read state from task node field
+            state = m.taskNode.getField(m.dispatcherId)
+
+            ' Apply optional state mapping
+            m.runMapStateToProps(state, mapStateToProps, callerScope)
+
+            return state
+        end function
+
+        ' =============================================================
+        ' LISTENER MANAGEMENT
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' addListener - Adds state change listener with lazy observer setup
+        '
+        ' Sets up observer on first listener registration (lazy initialization).
+        '
+        ' @param {object} listenerConfig - Listener configuration
+        ' @param {string} listenerId - Listener identifier
+        ' @param {object} listenerScope - Listener scope for callback
+        '
+        override sub addListener(listenerConfig as object, listenerId as string, listenerScope as object)
+            ' Setup observer on first listener (lazy initialization)
+            if m.isStateObserved = false
+                m.setupObserver()
+            end if
+
+            ' Register listener with parent class
+            super.addListener(listenerConfig, listenerId, listenerScope)
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' removeAllListenersByListenerId - Removes all listeners with given ID
+        '
+        ' Automatically removes observer when last listener is removed.
+        '
+        ' @param {string} listenerId - Listener identifier to remove
+        '
+        override sub removeAllListenersByListenerId(listenerId as string)
+            ' Remove listeners via parent class
+            super.removeAllListenersByListenerId(listenerId)
+
+            ' Auto cleanup: remove observer when no listeners remain
+            if m.isStateObserved = true and m.listeners.Count() = 0
+                m.removeObserver()
+            end if
+        end sub
+
+        ' =============================================================
+        ' OBSERVER MANAGEMENT
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' setupObserver - Sets up observer for state changes on task node field
+        '
+        ' Thread-specific observer setup:
+        '   - RENDER thread: Uses observeFieldScoped with callback name
+        '   - TASK thread: Uses framework's observer system
+        '
+        sub setupObserver()
+            if m.threadType = Rotor.Const.ThreadType.RENDER
+                ' Render thread: use native SceneGraph observer
+                m.taskNode.observeFieldScoped(m.dispatcherId, "Rotor_dispatcherStateCallback")
+            else
+                ' Task thread: use framework observer system
+                fieldId = m.dispatcherId
+                frameworkInstance = GetGlobalAA().rotor_framework_helper.frameworkInstance
+                frameworkInstance.addObserver(fieldId, m.taskNode)
+            end if
+
+            m.isStateObserved = true
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' removeObserver - Removes observer for state changes
+        '
+        ' Thread-specific observer cleanup matching setupObserver.
+        '
+        sub removeObserver()
+            if m.threadType = Rotor.Const.ThreadType.RENDER
+                ' Render thread: unobserve SceneGraph field
+                m.taskNode.unobserveFieldScoped(m.dispatcherId)
+            else
+                ' Task thread: remove framework observer
+                fieldId = m.dispatcherId
+                frameworkInstance = GetGlobalAA().rotor_framework_helper.frameworkInstance
+                frameworkInstance.removeObserver(fieldId, m.taskNode)
+            end if
+
+            m.isStateObserved = false
+        end sub
+
+        ' =============================================================
+        ' CLEANUP
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' destroy - Cleans up external dispatcher resources
+        '
+        ' Cleanup steps:
+        '   1. Call parent cleanup
+        '   2. Remove observer if active
+        '   3. Clear listeners
+        '   4. Deregister from dispatcher provider
+        '
+        override sub destroy()
+            super.destroy()
+
+            frameworkInstance = GetGlobalAA().rotor_framework_helper.frameworkInstance
+
+            ' Remove observer if active
+            if m.isStateObserved = true
+                if m.threadType = Rotor.Const.ThreadType.RENDER
+                    m.taskNode.unobserveFieldScoped(m.dispatcherId)
+                else
+                    fieldId = m.dispatcherId
+                    frameworkInstance.removeObserver(fieldId, m.taskNode)
+                end if
+            end if
+
+            ' Clear all references
+            m.listeners.Clear()
+            m.taskNode = invalid
+
+            ' Deregister from provider
+            frameworkInstance.dispatcherProvider.deregisterDispatcher(m.dispatcherId)
+        end sub
+
+    end class
+
+end namespace
+
+namespace Rotor
+
+    ' =====================================================================
+    ' dispatcherStateCallback - Global callback function for dispatcher state changes on render thread
+    '
+    ' This function is called by SceneGraph's observeFieldScoped when a dispatcher's
+    ' state field changes on the task node. It routes the state change to the
+    ' appropriate dispatcher instance for listener notification.
+    '
+    ' Process flow:
+    '   1. Extract dispatcher ID from message field
+    '   2. Extract new state from message data
+    '   3. Lookup dispatcher instance from provider
+    '   4. Notify all registered listeners with new state
+    '
+    ' @param {roSGNodeEvent} msg - SceneGraph observer message
+    ' =====================================================================
+    sub dispatcherStateCallback(msg)
+        ' Extract dispatcher ID and state from message
+        dispatcherId = msg.getField()
+        state = msg.getData()
+
+        ' Lookup dispatcher instance and notify listeners
+        frameworkInstance = GetGlobalAA().rotor_framework_helper.frameworkInstance
+        dispatcherInstance = frameworkInstance.dispatcherProvider.get(dispatcherId)
+        dispatcherInstance.notifyListeners(state)
+    end sub
+
+end namespace