rotor-framework 0.3.2

package/src/source/base/ListenerForDispatchers.bs

@@ -0,0 +1,246 @@
+' =====================================================================
+' Intent Interface - Standard interface for MVI intents
+'
+' Properties:
+'   - type: Intent type identifier (e.g., "FETCH_DATA", "UPDATE_USER")
+'   - payload: Optional data associated with intent
+'
+' Example:
+'   { type: "INCREMENT", payload: { amount: 1 } }
+' =====================================================================
+interface Intent
+    type as string
+    payload as object
+end interface
+
+namespace Rotor
+
+    ' =====================================================================
+    ' ListenerForDispatchers - Base class for dispatcher state change listener management
+    '
+    ' Provides listener registration, notification, and lifecycle management
+    ' for both internal and external dispatchers.
+    '
+    ' Listener Features:
+    '   - State mapping: mapStateToProps for updating widget props
+    '   - Conditional updates: shouldUpdate/allowUpdate for optimization
+    '   - Callbacks: callback (no args) or callbackWithState (receives state)
+    '   - One-time listeners: once flag for auto-removal after first trigger
+    '
+    ' Update Flow:
+    '   1. Check shouldUpdate/allowUpdate condition
+    '   2. If true: Map state to props (if configured)
+    '   3. Invoke callback functions
+    '   4. Remove 'once' listeners
+    ' =====================================================================
+    class ListenerForDispatchers
+
+        ' =============================================================
+        ' MEMBER VARIABLES
+        ' =============================================================
+
+        listeners = []                  ' Array of listener configurations
+
+        ' =============================================================
+        ' LISTENER NOTIFICATION
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' notifyListeners - Notifies all registered listeners of state change
+        '
+        ' Process flow:
+        '   1. For each listener, check shouldUpdate/allowUpdate condition
+        '   2. If condition passes:
+        '      - Map state to props (if mapStateToProps configured)
+        '      - Or deep extend props with state (default behavior)
+        '      - Invoke callback (if configured)
+        '      - Invoke callbackWithState (if configured)
+        '      - Remove listener if 'once' flag is true
+        '   3. Skip listener if condition fails
+        '
+        ' @param {object} state - New state to notify listeners about
+        '
+        sub notifyListeners(state as object)
+            listenerCount = m.listeners.Count()
+            listenerIndex = 0
+
+            ' Iterate through all listeners
+            while listenerIndex < listenerCount
+                listener = m.listeners[listenerIndex]
+                scope = listener.listenerScope
+
+                ' Determine if listener should be notified
+                if Rotor.Utils.isFunction(listener.shouldUpdate)
+                    ' Widget/ViewModel: Check shouldUpdate(props, state)
+                    shouldUpdate = Rotor.Utils.callbackScoped(listener.shouldUpdate, scope, scope.props, state)
+                else if Rotor.Utils.isFunction(listener.allowUpdate)
+                    ' Task thread: Check allowUpdate(state)
+                    shouldUpdate = Rotor.Utils.callbackScoped(listener.allowUpdate, scope, state)
+                else
+                    ' Default: always update
+                    shouldUpdate = true
+                end if
+
+                if shouldUpdate
+                    ' Map state to props
+                    if Rotor.Utils.isFunction(listener.mapStateToProps)
+                        ' Custom mapping: mapStateToProps(props, state)
+                        listener.mapStateToProps(scope.props, state)
+                    else if Rotor.Utils.isAssociativeArray(scope.props)
+                        ' Default: deep extend props with state
+                        Rotor.Utils.deepExtendAA(scope.props, state)
+                    end if
+
+                    ' Invoke callback without state
+                    callback = listener.callback
+                    if callback <> invalid
+                        Rotor.Utils.callbackScoped(callback, scope)
+                    end if
+
+                    ' Invoke callback with state
+                    callbackWithState = listener.callbackWithState
+                    if callbackWithState <> invalid
+                        Rotor.Utils.callbackScoped(callbackWithState, scope, state)
+                    end if
+
+                    ' Handle 'once' listeners (auto-remove after trigger)
+                    if listener?.once = true
+                        listener.listenerScope = invalid
+                        listener.callback = invalid
+                        m.listeners.Delete(listenerIndex)
+                        listenerCount--
+                    else
+                        listenerIndex++
+                    end if
+                else
+                    ' Skip this listener (condition not met)
+                    listenerIndex++
+                end if
+            end while
+        end sub
+
+        ' =============================================================
+        ' LISTENER REGISTRATION
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' addListener - Registers a new state change listener
+        '
+        ' Listener Configuration:
+        '   - listenerId: Identifier for grouping related listeners
+        '   - listenerScope: Scope (m) where callbacks are executed
+        '   - mapStateToProps: Optional function(props, state) for custom state mapping
+        '   - shouldUpdate: Optional function(props, state) for Widget/ViewModel update checks
+        '   - allowUpdate: Optional function(state) for task thread update checks
+        '   - callback: Optional function() invoked on state change
+        '   - callbackWithState: Optional function(state) invoked with new state
+        '   - once: Optional boolean (default false) - auto-remove after first trigger
+        '
+        ' @param {object} listenerConfig - Listener configuration object
+        ' @param {string} listenerId - Listener identifier for batch operations
+        ' @param {object} listenerScope - Scope where callbacks are executed
+        '
+        sub addListener(listenerConfig as object, listenerId as string, listenerScope as object)
+            ' Debug validation: ensure props exists when using widget-specific features
+            #if debug
+                hasPropsMapper = Rotor.Utils.isFunction(listenerConfig.mapStateToProps)
+                hasPropsUpdateChecker = Rotor.Utils.isFunction(listenerConfig.shouldUpdate)
+                isPropsAA = Rotor.Utils.isAssociativeArray(listenerScope.props)
+                if not isPropsAA and (hasPropsMapper or hasPropsUpdateChecker)
+                    throw { message: "props does not exist in caller scope. `mapStateToProps` and `shouldUpdate` only can be used in Widgets and ViewModels. Use allowUpdate instead." }
+                end if
+            #end if
+
+            ' Register listener
+            m.listeners.push({
+                listenerId: listenerId,
+                listenerScope: listenerScope,
+
+                mapStateToProps: listenerConfig?.mapStateToProps,
+                shouldUpdate: listenerConfig?.shouldUpdate,
+                allowUpdate: listenerConfig?.allowUpdate,
+                callback: listenerConfig?.callback,
+                callbackWithState: listenerConfig?.callbackWithState,
+                once: listenerConfig?.once ?? false
+            })
+        end sub
+
+        ' =============================================================
+        ' LISTENER REMOVAL
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' removeAllListenersByListenerId - Removes all listeners with matching ID
+        '
+        ' Iterates backwards through listener array for safe removal during iteration.
+        '
+        ' @param {string} listenerId - Listener identifier to remove
+        '
+        sub removeAllListenersByListenerId(listenerId as string)
+            listenerCount = m.listeners.Count()
+            listenerIndex = listenerCount - 1
+
+            ' Iterate backwards for safe removal
+            while listenerIndex >= 0 and listenerCount > 0
+                if m.listeners[listenerIndex].listenerId = listenerId
+                    ' Clear listener references
+                    m.listeners[listenerIndex].Clear()
+                    m.listeners.delete(listenerIndex)
+                    listenerCount--
+                end if
+                listenerIndex--
+            end while
+        end sub
+
+        ' =============================================================
+        ' STATE MAPPING HELPERS
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' runMapStateToProps - Executes mapStateToProps function with validation
+        '
+        ' This helper is used by getState() methods to apply optional state mapping.
+        ' Only works in render thread contexts where props exist.
+        '
+        ' @param {object} state - Current state
+        ' @param {dynamic} mapStateToProps - Optional mapping function(props, state)
+        ' @param {object} callerScope - Caller scope containing props
+        '
+        sub runMapStateToProps(state as object, mapStateToProps = invalid as dynamic, callerScope = invalid as object)
+            if Rotor.Utils.isFunction(mapStateToProps)
+                if Rotor.Utils.isAssociativeArray(callerScope?.props)
+                    ' Execute mapping: updates props in-place
+                    mapStateToProps(callerScope.props, state)
+                else
+                    ' Debug validation: props must exist for mapping
+                    #if debug
+                        throw { message: "Props does not exist in caller scope. `mapStateToProps` can only be used in Widgets and ViewModels (render thread). In task threads, use `getState()` without mapStateToProps and access state directly." }
+                    #end if
+                end if
+            end if
+        end sub
+
+        ' =============================================================
+        ' CLEANUP
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' destroy - Cleans up all listeners
+        '
+        ' Invalidates all listener references and clears listener array.
+        '
+        sub destroy()
+            ' Clear all listener references
+            if m.listeners.Count() > 0
+                for each listener in m.listeners
+                    listener.listenerScope = invalid
+                    listener.callback = invalid
+                end for
+            end if
+
+            m.listeners.Clear()
+        end sub
+
+    end class
+
+end namespace

package/src/source/engine/Constants.bs

@@ -0,0 +1,74 @@
+' =====================================================================
+' Constants - Framework-wide constant definitions and enumerations
+'
+' Defines direction types, segment types, lifecycle hook types,
+' hook priority types, and thread synchronization types.
+' =====================================================================
+
+namespace Rotor
+
+    namespace Const
+
+        const GROUP_CONFIG_KEY = "group"
+
+        enum Direction
+            UP = "up"
+            RIGHT = "right"
+            DOWN = "down"
+            LEFT = "left"
+            BACK = "back"
+        end enum
+
+        enum Segment
+            TOP = "top"
+            RIGHT = "right"
+            BOTTOM = "bottom"
+            LEFT = "left"
+        end enum
+
+        enum PluginLifeCycleHookType
+            BEFORE_MOUNT = "beforeMount"
+            AFTER_MOUNTED = "afterMounted"
+            BEFORE_UPDATE = "beforeUpdate"
+            AFTER_UPDATED = "afterUpdated"
+            BEFORE_DESTROY = "beforeDestroy"
+        end enum
+
+        enum LifeCycleHookType
+            APPEND_CHILD = "appendChild"
+            REINDEX_CHILD = "reindexChild"
+            BEFORE_MOUNT = "beforeMount"
+            MOUNTED = "mounted"
+            AFTER_MOUNTED = "afterMounted"
+            BEFORE_UPDATE = "beforeUpdate"
+            UPDATED = "updated"
+            VIEWMODEL_STATE_UPDATE = "VIEWMODEL_STATE_UPDATE"
+            AFTER_UPDATED = "afterUpdated"
+            BEFORE_DESTROY = "beforeDestroy"
+            REMOVE_CHILD = "removeChild"
+            DELETE_WIDGET = "deleteWidget"
+        end enum
+
+
+        enum HookPriorityTypes
+            ROOT = "rootBuffer"
+            DEFAULT = "defaultBuffer"
+        end enum
+
+        enum ThreadSyncType
+            TASK_SYNCING = "taskSyncing"
+            REGISTER_EXTERNAL_DISPATCHER = "registerExternalDispatcher"
+            DESTROY = "destroy"
+            TASK_SYNCED = "taskSynced"
+            SYNC_COMPLETED = "sync_completed"
+            DISPATCH = "dispatch"
+        end enum
+
+        enum ThreadType
+            RENDER = "render"
+            TASK = "task"
+        end enum
+
+    end namespace
+
+end namespace

package/src/source/engine/animator/Animator.bs

@@ -0,0 +1,334 @@
+
+import "../../libs/animate/Animate.bs" ' https://github.com/haystacknews/animate
+
+
+namespace Rotor
+
+    ' ---------------------------------------------------------------------
+    ' animatorParamsIntegrationHelper - Helper function to parse and normalize animator parameters
+    '
+    ' @param {object} params - Animator parameters with target or targets field
+    ' @returns {object} Parsed parameters with normalized targets array
+    ' @throws {object} Error if no targets are specified
+    '
+    function animatorParamsIntegrationHelper(params) as object
+        if params.target <> invalid
+            targets = params.target
+            params.delete("target")
+        else if params.targets <> invalid
+            targets = params.targets
+            params.delete("targets")
+        else
+            throw { message: "[ANIMATOR][ERROR] Animator params don't specify targets." }
+        end if
+        parsedTargets = []
+        for each target in Rotor.Utils.ensureArray(targets)
+            if Rotor.Utils.isAssociativeArray(target) and target.doesExist("node")
+                node = target.node
+                node.id = `${target.id}-${target.HID}`
+                parsedTargets.push(node)
+            else
+                parsedTargets.push(target)
+            end if
+        end for
+
+        params.targets = parsedTargets
+
+        return params
+    end function
+
+    ' ---------------------------------------------------------------------
+    ' animationStateObserver - Sets up state observation for animator nodes
+    '
+    ' @param {object} params - Observer configuration parameters
+    '
+    sub animationStateObserver(params = {} as object)
+
+        globalScope = GetGlobalAA()
+        animatorObservber = globalScope.rotor_framework_helper.frameworkInstance.animatorProvider.animatorObservber
+        animatorObservber.detach(m.animNode)
+
+        observerParams = {
+            fieldId: "state",
+            infoFields: [],
+            callback: sub(state)
+                print "[WARNING] You have not specified callback for animation stateObserver"
+            end sub,
+            parsePayload: function(payload)
+                return payload.state
+            end function
+        }
+        observerParams.append(params)
+        ' mandatory field
+        observerParams.infoFields.unshift("isRotorAnimatorNode")
+
+        animatorObservber.attach(m.animNode, observerParams, m.scope)
+
+    end sub
+
+    ' =====================================================================
+    ' Animator - Manages animation instances and provides factory methods
+    '
+    ' Manages animation instances and provides factory methods for creating
+    ' single animations and timelines. Integrates with the Animate library
+    ' and provides state observation capabilities for animations.
+    ' =====================================================================
+    class Animator
+
+        animatorObservber as Rotor.ObserverPlugin
+
+        ' ---------------------------------------------------------------------
+        ' new - Initializes the animator with observer plugin
+        '
+        sub new()
+            m.animatorObservber = new Rotor.ObserverPlugin("rotorAnimatorObserver")
+            m.animatorObservber.init()
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' getFactory - Creates an animator factory instance for the given ID and scope
+        '
+        ' @param {string} animatorId - Unique identifier for the animator
+        ' @param {object} scope - Optional scope object for the animator (default: invalid)
+        ' @returns {object} Animator factory instance with control methods
+        '
+        function getFactory(animatorId as string, scope = invalid as object) as object
+
+            ' Get Animator by animatorScopedId
+            animatorInstance = {
+
+                animatorId: animatorId,
+                scope: scope,
+
+                ' ---------------------------------------------------------------------
+                ' create - Creates a single animation instance
+                '
+                ' @param {object} params - Animation parameters (target, duration, easing, etc.)
+                ' @returns {object} Animation control object with play method
+                '
+                create: function(params)
+
+                    ' destroy before create
+                    if m.scope?.animators?[m.animatorId] <> invalid
+                        ' unobserve
+                        animNode = m.scope.animators[m.animatorId].animNode
+                        globalScope = GetGlobalAA()
+                        animatorObservber = globalScope.rotor_framework_helper.frameworkInstance.animatorProvider.animatorObservber
+                        animatorObservber.detach(animNode)
+                        ' remove
+                        m.scope.animators[m.animatorId].animNode = invalid
+                        m.scope.animators.delete(m.animatorId)
+                    end if
+
+                    m.scope.animators = {}
+                    m.scope.animators[m.animatorId] = {}
+
+                    parsedParams = Rotor.animatorParamsIntegrationHelper(params)
+                    animNode = animate.create(parsedParams)
+
+                    m.scope.animators[m.animatorId].animNode = animNode
+                    m.scope.animators[m.animatorId].animNode.addField("isRotorAnimatorNode", "boolean", false) ' may use by observer
+                    m.scope.animators[m.animatorId].animNode.isRotorAnimatorNode = true
+                    m.scope.animators[m.animatorId].animNode.addField("animatorType", "string", false)
+                    m.scope.animators[m.animatorId].animNode.animatorType = "singleAnimation"
+
+                    return {
+
+                        scope: m.scope,
+                        animatorId: m.animatorId,
+
+                        play: function()
+                            animNode = m.scope?.animators?[m.animatorId]?.animNode
+                            animNode.control = "start"
+                            return {
+                                scope: m.scope,
+                                animNode: animNode,
+                                observeState: Rotor.animationStateObserver
+                            }
+                        end function
+
+                    }
+
+                end function,
+
+                ' ---------------------------------------------------------------------
+                ' timeline - Creates a timeline for multiple sequential/parallel animations
+                '
+                ' @param {object} params - Timeline parameters
+                ' @returns {object} Timeline control object with add, getAnimation, and play methods
+                '
+                timeline: function(params)
+
+                    ' destroy before create
+                    if m.scope?.animators?[m.animatorId] <> invalid
+                        ' unobserve
+                        animNode = m.scope.animators[m.animatorId].animNode
+                        globalScope = GetGlobalAA()
+                        animatorObservber = globalScope.rotor_framework_helper.frameworkInstance.animatorProvider.animatorObservber
+                        animatorObservber.detach(animNode)
+                        ' remove
+                        m.scope.animators[m.animatorId].animNode = invalid
+                        m.scope.animators.delete(m.animatorId)
+                    end if
+
+                    m.scope.animators = {}
+                    m.scope.animators[m.animatorId] = {}
+
+                    return {
+
+                        scope: m.scope,
+                        animatorId: m.animatorId,
+
+                        timeline: animate.timeline(params),
+
+                        add: function(params)
+
+                            parsedParams = Rotor.animatorParamsIntegrationHelper(params)
+                            m.timeline.add(parsedParams)
+
+                            return m
+                        end function,
+
+                        getAnimation: function()
+                            m.scope.animators[m.animatorId].animNode = m.timeline.getAnimation()
+                            m.scope.animators[m.animatorId].animNode.addField("isRotorAnimatorNode", "boolean", false) ' may use by observer
+                            m.scope.animators[m.animatorId].animNode.isRotorAnimatorNode = true
+                            m.scope.animators[m.animatorId].animNode.addField("animatorType", "string", false)
+                            m.scope.animators[m.animatorId].animNode.animatorType = "parallelAnimation"
+
+                            return m
+                        end function,
+
+                        play: function()
+                            animNode = m.scope?.animators?[m.animatorId]?.animNode
+                            ' Auto getAnimation and then play
+                            if animNode = invalid
+                                m.getAnimation()
+                            end if
+                            animNode = m.scope?.animators?[m.animatorId]?.animNode
+                            animNode.control = "start"
+                            return {
+                                scope: m.scope,
+                                animNode: animNode,
+                                observeState: Rotor.animationStateObserver
+                            }
+                        end function
+
+                    }
+                end function
+
+            }
+
+            return {
+                animatorInstance: animatorInstance,
+                animatorId: animatorId,
+                scope: scope,
+
+                getState: function()
+                    return m.scope?.animators?[m.animatorId]?.animNode?.state
+                end function,
+
+                isRunning: function()
+                    return m.getState() = "running"
+                end function,
+
+                isStopped: function()
+                    return m.getState() = "stopped"
+                end function,
+
+                isPaused: function()
+                    return m.getState() = "paused"
+                end function,
+
+                play: function()
+                    animNode = m.scope?.animators?[m.animatorId]?.animNode
+                    ' Auto getAnimation and then play
+                    if animNode = invalid
+                        m.getAnimation()
+                    end if
+                    animNode = m.scope?.animators?[m.animatorId]?.animNode
+                    if animNode <> invalid
+                        animNode.control = "start"
+                    end if
+                    return {
+                        scope: m.scope,
+                        animNode: animNode,
+                        observeState: Rotor.animationStateObserver
+                    }
+                end function,
+
+                stop: sub()
+                    animNode = m.scope?.animators?[m.animatorId]?.animNode
+                    if animNode <> invalid
+                        m.scope.animators[m.animatorId].animNode.control = "stop"
+                    end if
+                end sub,
+
+                pause: sub()
+                    animNode = m.scope?.animators?[m.animatorId]?.animNode
+                    if animNode <> invalid
+                        m.scope.animators[m.animatorId].animNode.control = "pause"
+                    end if
+                end sub,
+
+                finish: sub()
+                    animNode = m.scope?.animators?[m.animatorId]?.animNode
+                    if animNode <> invalid
+                        animNode.control = "finish"
+                    end if
+                end sub,
+
+                getAnimNode: function()
+                    animNode = m.scope?.animators?[m.animatorId]?.animNode
+                    return animNode
+                end function,
+
+                getInterpolators: function()
+                    animNode = m.scope?.animators?[m.animatorId]?.animNode
+                    if animNode <> invalid
+                        if m.scope.animators[m.animatorId].animNode.animatorType = "parallelAnimation"
+                            interpolators = []
+                            for each subAnim in animNode.getChildCount()
+                                interpolators.push(subAnim.getChildren(-1, 0))
+                            end for
+                        else ' singleAnimator
+                            interpolators = animNode.getChildren(-1, 0)
+                        end if
+                        return interpolators
+                    else
+                        return invalid
+                    end if
+                end function,
+
+                destroy: sub()
+                    if m.scope?.animators?[m.animatorId] <> invalid
+                        m.unobserveState()
+                        m.scope.animators[m.animatorId].animNode = invalid
+                        m.scope.animators.delete(m.animatorId)
+                    end if
+                end sub,
+
+                unobserveState: sub()
+                    animNode = m.scope.animators[m.animatorId].animNode
+                    globalScope = GetGlobalAA()
+                    animatorObservber = globalScope.rotor_framework_helper.frameworkInstance.animatorProvider.animatorObservber
+                    animatorObservber.detach(animNode)
+                end sub,
+
+                ' Create with self destroy
+                create: function(params) as object
+                    return m.animatorInstance.create(params)
+                end function,
+
+                ' Cerate timeline with self destroy
+                timeline: function(params) as object
+                    return m.animatorInstance.timeline(params)
+                end function
+            }
+
+
+        end function
+
+    end class
+
+end namespace