rotor-framework 0.3.2

package/src/source/libs/animate/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Haystack TV Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/source/plugins/DispatcherProviderPlugin.bs

@@ -0,0 +1,127 @@
+import "../base/BasePlugin.bs"
+
+namespace Rotor
+
+    ' =====================================================================
+    ' DispatcherProviderPlugin - Manages MVI dispatcher integration with widgets
+    '
+    ' Rotor Framework plugin for managing MVI dispatcher integration with widgets.
+    '
+    ' Key Responsibilities:
+    '   - Provides dispatcher facades to widgets for state management
+    '   - Manages dispatcher lifecycle (creation, updates, cleanup)
+    '   - Integrates cross-thread MVI pattern with widget context
+    '   - Stores dispatcher references in viewModelState for easy access
+    '
+    ' Usage:
+    '   Widget config: dispatcher: "dispatcherId" or dispatcher: ["id1", "id2"]
+    '   Access: widget.viewModelState.dispatcher[dispatcherId]
+    '
+    ' =====================================================================
+    class DispatcherProviderPlugin extends Rotor.BasePlugin
+
+        ' =============================================================
+        ' CONSTRUCTOR
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' new - Initializes the DispatcherProviderPlugin instance
+        '
+        ' @param {string} key - Plugin identifier (default: "dispatcher")
+        '
+        sub new(key = "dispatcher" as string)
+            super(key)
+        end sub
+
+        ' =============================================================
+        ' LIFECYCLE HOOKS
+        ' =============================================================
+
+        hooks = {
+            ' ---------------------------------------------------------------------
+            ' beforeMount - Attaches dispatchers when widget is mounted
+            '
+            ' Creates dispatcher facades and stores them in viewModelState.
+            '
+            ' @param {object} scope - Plugin instance (m)
+            ' @param {object} widget - Widget being mounted
+            '
+            beforeMount: sub(scope as object, widget as object)
+                scope.setDispatcherOnContext(widget, scope.key)
+            end sub,
+
+            ' ---------------------------------------------------------------------
+            ' beforeUpdate - Updates dispatcher configuration
+            '
+            ' Extends existing dispatcher list with new IDs (prevents duplicates).
+            ' Creates facades for any newly added dispatchers.
+            '
+            ' @param {object} scope - Plugin instance (m)
+            ' @param {object} widget - Widget being updated
+            ' @param {dynamic} newValue - New dispatcher ID(s)
+            ' @param {dynamic} oldValue - Previous dispatcher ID(s)
+            '
+            beforeUpdate: sub(scope as object, widget as object, newValue, oldValue = [])
+                ' Merge old and new dispatcher IDs (no duplicates)
+                oldArrayOfDispatcherIds = Rotor.Utils.ensureArray(oldValue ?? [])
+                newArrayOfDispatcherIds = Rotor.Utils.ensureArray(newValue)
+                widget[scope.key] = Rotor.Utils.extendArrayOfStrings(oldArrayOfDispatcherIds, newArrayOfDispatcherIds)
+                scope.setDispatcherOnContext(widget, scope.key)
+            end sub,
+
+            ' ---------------------------------------------------------------------
+            ' beforeDestroy - Cleans up dispatchers before widget destruction
+            '
+            ' Destroys all dispatcher facades and clears references.
+            '
+            ' @param {object} scope - Plugin instance (m)
+            ' @param {object} widget - Widget being destroyed
+            '
+            beforeDestroy: sub(scope as object, widget as object)
+                dispatcherFacades = widget.viewModelState[scope.key]
+                if dispatcherFacades.Count() > 0
+                    for each dispatcherFacadeKey in dispatcherFacades
+                        dispatcherFacadeInstance = dispatcherFacades[dispatcherFacadeKey]
+                        dispatcherFacadeInstance.destroy()
+                        widget.viewModelState[scope.key][dispatcherFacadeKey] = invalid
+                    end for
+                end if
+            end sub
+        }
+
+        ' =============================================================
+        ' DISPATCHER MANAGEMENT
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' setDispatcherOnContext - Creates and stores dispatcher facades
+        '
+        ' For each dispatcher ID in the widget config:
+        '   1. Initializes viewModelState.dispatcher object if needed
+        '   2. Checks if facade already exists for this ID
+        '   3. Creates new facade via DispatcherProvider if not present
+        '   4. Stores facade in viewModelState.dispatcher[dispatcherId]
+        '
+        ' @param {object} widget - Widget instance
+        ' @param {string} scopeKey - Plugin key (typically "dispatcher")
+        '
+        sub setDispatcherOnContext(widget, scopeKey)
+            viewModelState = widget.viewModelState
+            config = widget[scopeKey]
+
+            for each dispatcherId in Rotor.Utils.ensureArray(config)
+                ' Initialize dispatcher storage in viewModelState
+                if viewModelState[m.key] = invalid then viewModelState[m.key] = {}
+
+                ' Create facade if it doesn't exist
+                if not viewModelState[m.key].DoesExist(dispatcherId)
+                    globalScope = GetGlobalAA()
+                    frameworkInstance = globalScope.rotor_framework_helper.frameworkInstance
+                    viewModelState[m.key][dispatcherId] = frameworkInstance.dispatcherProvider.getFacade(dispatcherId, widget)
+                end if
+            end for
+        end sub
+
+    end class
+
+end namespace

package/src/source/plugins/FieldsPlugin.bs

@@ -0,0 +1,180 @@
+import "../base/BasePlugin.bs"
+
+namespace Rotor
+
+    ' =====================================================================
+    ' FieldsPlugin - Handles dynamic field expressions and interpolation
+    '
+    ' Rotor Framework plugin for handling dynamic field expressions and interpolation.
+    '
+    ' Key Features:
+    '   - Evaluates function-based field values
+    '   - Interpolates @-prefixed expressions (e.g., @viewModelState.value)
+    '   - Supports dynamic field resolution from widget context
+    '   - Automatically updates fields on widget lifecycle changes
+    '
+    ' Expression Syntax:
+    '   @key.path - Resolves from widget.viewModelState
+    '
+    ' =====================================================================
+    class FieldsPlugin extends Rotor.BasePlugin
+
+        ' =============================================================
+        ' MEMBER VARIABLES
+        ' =============================================================
+
+        ' Regex pattern for matching @-prefixed expressions
+        ' Matches: @ followed by any characters except space, @, or comma
+        configRegex = /(\@)([^\s\@\,]*)/i
+
+        ' =============================================================
+        ' CONSTRUCTOR
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' new - Initializes the FieldsPlugin instance
+        '
+        ' @param {string} key - Plugin identifier (default: "fields")
+        ' @param {object} params - Additional parameters (unused)
+        '
+        sub new(key = "fields" as string, params = invalid as object)
+            super(key)
+        end sub
+
+        ' =============================================================
+        ' LIFECYCLE HOOKS
+        ' =============================================================
+
+        hooks = {
+            ' ---------------------------------------------------------------------
+            ' beforeMount - Sets custom fields when widget is mounted
+            '
+            ' Evaluates and applies all field expressions after widget creation.
+            '
+            ' @param {object} scope - Plugin instance (m)
+            ' @param {object} widget - Widget being mounted
+            '
+            beforeMount: sub(scope as object, widget as object)
+                value = widget[scope.key]
+                scope.setCustomFields(widget, value)
+            end sub,
+
+            ' ---------------------------------------------------------------------
+            ' beforeUpdate - Updates custom fields when widget config changes
+            '
+            ' Merges new field config with existing config and re-evaluates all fields.
+            '
+            ' @param {object} scope - Plugin instance (m)
+            ' @param {object} widget - Widget being updated
+            ' @param {object} newValue - New field configuration
+            ' @param {object} oldValue - Previous field configuration
+            '
+            beforeUpdate: sub(scope as object, widget as object, newValue = {}, oldValue = {})
+                ' Extend old config with new values
+                Rotor.Utils.deepExtendAA(widget[scope.key], newValue)
+                scope.setCustomFields(widget, newValue)
+            end sub,
+
+            ' ---------------------------------------------------------------------
+            ' beforeDestroy - Clears field configuration on destruction
+            '
+            ' @param {object} scope - Plugin instance (m)
+            ' @param {object} widget - Widget being destroyed
+            '
+            beforeDestroy: sub(scope as object, widget as object)
+                widget[scope.key].Clear()
+            end sub
+        }
+
+        ' =============================================================
+        ' FIELD PROCESSING
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' setCustomFields - Evaluates and applies fields to widget node
+        '
+        ' Parses field expressions and sets the resolved values on the widget's SceneGraph node.
+        '
+        ' @param {object} widget - Widget instance
+        ' @param {object} fields - Field configuration object
+        '
+        sub setCustomFields(widget as object, fields)
+            parsedFields = m.parseFields(widget, fields)
+            node = widget.node
+            Rotor.Utils.setCustomFields(node, parsedFields, true)
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' parseFields - Parses and resolves field expressions
+        '
+        ' Processes field values through multiple resolution strategies:
+        '   1. Function values - Executes function in widget scope
+        '   2. String interpolation - Resolves @-prefixed expressions
+        '   3. Direct values - Passes through unchanged
+        '
+        ' Expression Resolution:
+        '   - @key.path resolves from widget.viewModelState
+        '   - If result is string, performs string interpolation
+        '   - If result is non-string, replaces entire value
+        '
+        ' @param {object} widget - Widget instance providing context
+        ' @param {object} fields - Field configuration to parse
+        ' @returns {object} Parsed fields with resolved values
+        '
+        function parseFields(widget as object, fields as object) as object
+            parsedFields = {}
+
+            for each fieldId in fields
+                value = fields[fieldId]
+
+                ' Step 1: Resolve function-based values
+                if Rotor.Utils.isFunction(value)
+                    parsedFields[fieldId] = Rotor.Utils.callbackScoped(value, widget)
+                    value = parsedFields[fieldId]
+                end if
+
+                ' Step 2: Process string interpolation
+                if Rotor.Utils.isString(value)
+                    results = m.configRegex.MatchAll(value)
+
+                    if results.Count() > 0
+                        for each result in results
+                            matchKey = result[2]        ' The key path after @
+                            sourceTypeOperator = result[1]  ' The @ symbol
+
+                            ' Determine source based on operator
+                            if sourceTypeOperator = "@"
+                                source = widget.viewModelState
+                            else
+                                source = widget
+                            end if
+
+                            ' Resolve value from key path
+                            asset = Rotor.Utils.getValueByKeyPath(source, matchKey)
+
+                            ' Handle string vs non-string results
+                            if Rotor.Utils.isString(asset)
+                                ' String interpolation - replace in original string
+                                replaceRegex = CreateObject("roRegex", sourceTypeOperator + matchKey, "ig")
+                                value = replaceRegex.ReplaceAll(value, asset)
+                            else
+                                ' Non-string value - replace entire field value
+                                value = asset
+                                exit for
+                            end if
+                        end for
+                    end if
+
+                    parsedFields[fieldId] = value
+                else
+                    ' Step 3: Direct value assignment
+                    parsedFields[fieldId] = value
+                end if
+            end for
+
+            return parsedFields
+        end function
+
+    end class
+
+end namespace