rotor-framework 0.3.2

package/src/source/engine/builder/Tree.bs

@@ -0,0 +1,278 @@
+import "TreeBase.bs"
+
+namespace Rotor.ViewBuilder
+
+    ' =====================================================================
+    ' TreeRoot - Root node of the widget tree
+    '
+    ' Provides minimal API for rendering and erasing at the root level.
+    ' =====================================================================
+    class TreeRoot
+
+        node as object
+
+        children = {}
+
+        viewModelState = {}
+
+        id = ""
+        HID = "0"
+        vmHID = "0"
+        parentHID = invalid
+        isViewModel = true
+        childrenHIDhash = {}
+
+        function getFrameworkInstance() as object
+            return GetGlobalAA().rotor_framework_helper.frameworkInstance
+        end function
+
+        sub render(payloads as dynamic, params = {} as object)
+            for each payload in Rotor.Utils.ensureArray(payloads)
+                if payload.DoesExist("id") = false and payload.DoesExist("HID") = false
+                    payload.id = m.id
+                    payload.HID = m.HID
+                end if
+            end for
+            if Rotor.Utils.isValid(params.callback) then params.callbackScope = m
+            m.getFrameworkInstance().builder.render(payloads, params)
+        end sub
+
+        sub erase(payloads as dynamic, shouldSkipNodePool)
+            m.getFrameworkInstance().builder.erase(payloads, m.parentHID, shouldSkipNodePool)
+        end sub
+
+        sub destroy()
+            m.node = invalid
+        end sub
+
+    end class
+
+    ' =====================================================================
+    ' WidgetTree - Main widget tree implementation extending WidgetTreeBase
+    '
+    ' Manages widget hierarchy, parent-child relationships,
+    ' and ViewModel scope propagation through the tree.
+    ' =====================================================================
+    class WidgetTree extends Rotor.ViewBuilder.WidgetTreeBase
+
+        ' sub new()
+        ' end sub
+
+        ' ---------------------------------------------------------------------
+        ' init - Initializes the widget tree
+        '
+        sub init()
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' destroy - Destroys the widget tree and cleans up resources
+        '
+        sub destroy()
+            m.tree.destroy()
+            m.tree_HIDHash.stack.Clear()
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' add - Adds a widget to the tree and returns the widget instance
+        '
+        ' @param {object} config - Widget configuration with id and parentHID
+        ' @param {object} ViewModelClass - Optional ViewModel class constructor (default: invalid)
+        ' @returns {object} Created widget instance with generated HID
+        '
+        function add(config as object, ViewModelClass = invalid) as object
+
+            if Rotor.Utils.isFunction(ViewModelClass as function) ' Custom View extends Widget
+                ' bs:disable-next-line
+                widget = new ViewModelClass()
+            else
+                widget = new Rotor.Widget() ' Standard Widget
+            end if
+
+            id = config.id
+
+            ' Parse config properties
+            widget.id = id
+            widget.childrenHIDhash = {} ' prepare local HID cache
+            widget.isRootChild = config.parentHID = "0" ' detect root
+            widget.children = {} ' default
+
+            ' Check if has parent widget
+            if widget.isRootChild
+                parent = m.tree
+            else
+                parent = m.get(config.parentHID)
+            end if
+            widget.parentHID = config.parentHID
+            HID = m.generateHID(parent)
+
+            ' register as child by readable id
+            parent.children[LCase(id)] = widget
+
+            ' register as child by readable HID (Hierarchical Identifier)
+            parent.childrenHIDhash[HID] = true ' local cache for HID
+
+            widget.HID = HID
+            widget.parent = parent ' link parent widget
+
+            if widget?.isViewModel = true
+                widget.vmHID = widget.HID ' start new VM reference in hierarchy
+            else
+                widget.vmHID = parent.vmHID ' populate down the current VM reference in hierarchy
+                VM = m.getByHID(parent.vmHID)
+                widget.props = VM.props ' reference to ancestor's viewModel's props (sharing props across descendant widgets)
+                widget.viewModelState = VM.viewModelState ' reference to ancestor ViewModel's viewModelState
+            end if
+
+
+            ' Build virtual widget tree
+            m.tree_HIDHash.set(HID, widget)
+
+            return widget
+        end function
+
+        ' ---------------------------------------------------------------------
+        ' getChildrenWidgets - Gets child widgets of a parent in SceneGraph node order
+        '
+        ' @param {object} parentWidget - Parent widget to get children from
+        ' @param {string} matchingPattern - Optional glob pattern to filter children (default: "")
+        ' @returns {object} Array of child widgets in node order
+        '
+        function getChildrenWidgets(parentWidget as object, matchingPattern = "" as string) as object
+
+            if parentWidget = invalid then return invalid
+
+            ' Get all children in node order
+            childrenWidgets = parentWidget.children.items()
+
+            childrenWidgetsCount = childrenWidgets.Count()
+            childrenNodes = parentWidget.node.getChildren(-1, 0)
+
+            orderedWidgets = []
+            for each node in childrenNodes
+                isFound = false
+                itemIndex = 0
+                while isFound = false and itemIndex < childrenWidgetsCount
+                    widget = childrenWidgets[itemIndex].value
+                    if widget.node.isSameNode(node)
+                        ' Apply ID filtering if pattern is provided
+                        if matchingPattern = "" or m.matchesPattern(LCase(widget.id), LCase(matchingPattern))
+                            orderedWidgets.push(widget)
+                        end if
+                        isFound = true
+                    else
+                        itemIndex++
+                    end if
+                end while
+            end for
+
+            return orderedWidgets
+        end function
+
+        ' ---------------------------------------------------------------------
+        ' remove - Removes a widget from the tree by HID
+        '
+        ' @param {string} HID - Hierarchical ID of widget to remove
+        '
+        sub remove (HID as string)
+            widget = m.getByHID(HID)
+            ' if widget = invalid then return
+
+            ' remove from parent
+            parent = widget.parent
+            parent.children.Delete(widget.id)
+
+            parent.childrenHIDhash.Delete(widget.HID)
+
+            m.tree_HIDHash.remove(HID)
+
+            ' remove animators
+            if widget.animators <> invalid and widget.animators.Count() > 0
+                for each animatorId in widget.animators
+                    widget.animator(animatorId).destroy()
+                end for
+            end if
+
+            if widget.isViewModel = true
+                widget.props.Clear()
+                widget.viewModelState.Clear()
+            end if
+
+            widget.Clear()
+
+        end sub
+
+        ' ===== HELPER METHODS =====
+
+        ' ---------------------------------------------------------------------
+        ' isBranchOfRemove - Checks if widget is a top-level branch marked for removal
+        '
+        ' @param {object} widget - Widget to check
+        ' @returns {boolean} True if widget is removal branch root
+        '
+        function isBranchOfRemove(widget as object) as boolean
+            if false = widget.DoesExist("markedToRemove") then return false
+            if widget.isRootChild = true
+                return true
+            end if
+
+            return widget.parent.DoesExist("markedToRemove") ? false : true
+        end function
+
+        ' ---------------------------------------------------------------------
+        ' isBranchOfAppend - Checks if widget is a top-level branch marked for append
+        '
+        ' @param {object} widget - Widget to check
+        ' @returns {boolean} True if widget is append branch root
+        '
+        function isBranchOfAppend(widget as object) as boolean
+            if false = widget.DoesExist("markedToAppend") then return false
+            if widget.isRootChild = true
+                return true
+            end if
+            return widget.parent.DoesExist("markedToAppend") ? false : true
+        end function
+
+        ' ---------------------------------------------------------------------
+        ' getTreeItem - Gets tree item by HID or returns root if HID is empty
+        '
+        ' @param {string} HID - Hierarchical ID to lookup
+        ' @returns {object} Widget at HID or tree root
+        '
+        function getTreeItem(HID)
+            return HID = "" ? m.tree : m.getByHID(HID)
+        end function
+
+        ' Deprecated
+        ' function checkRegexIncluded(part as string) as object
+        '     if Left(part, 6) = "regex:"
+        '         return {
+        '             isRegex: true,
+        '             regex: CreateObject("roRegex", Right(part, Len(part) - 6), "i")
+        '         }
+        '     else
+        '         return {
+        '             isRegex: false
+        '         }
+        '     end if
+        ' end function
+
+        ' ---------------------------------------------------------------------
+        ' setRootNode - Sets the SceneGraph node for the tree root
+        '
+        ' @param {object} node - SceneGraph node to set as root
+        '
+        sub setRootNode (node as object)
+            m.tree.node = node
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' getRootNode - Gets the root SceneGraph node
+        '
+        ' @returns {object} Root SceneGraph node
+        '
+        function getRootNode() as object
+            return m.tree.node
+        end function
+    end class
+
+end namespace

package/src/source/engine/builder/TreeBase.bs

@@ -0,0 +1,313 @@
+namespace Rotor.ViewBuilder
+
+    ' =====================================================================
+    ' WidgetTreeBase - Base class for widget tree management with HID generation and search capabilities
+    '
+    ' Provides core functionality for hierarchical widget organization,
+    ' lookup operations, and glob pattern matching.
+    ' =====================================================================
+    class WidgetTreeBase
+
+        tree = new TreeRoot()
+        tree_HIDHash = new Rotor.BaseStack()
+
+        ' sub new()
+        '     super()
+        ' end sub
+
+        ' ---------------------------------------------------------------------
+        ' generateHID - Generates a unique Hierarchical ID for a widget under a parent
+        '
+        ' @param {object} parent - Parent widget object
+        ' @returns {string} Unique HID string
+        '
+        function generateHID(parent) as string
+            tryCounter = 32
+            newHID = ""
+            ' Performance way
+            while tryCounter > 0 and newHID = ""
+                newHID = parent.HID + Rotor.Utils.getUUIDHex(3)
+                if parent.childrenHIDhash.DoesExist(newHID) = true
+                    newHID = ""
+                end if
+                tryCounter--
+            end while
+            ' Ok, then try another way (very rare scenario)
+            if newHID = ""
+                for decValue = 0 to 4095
+                    hexValue = stri(decValue, 16)
+                    newHID = parent.HID + hexValue
+                    if parent.childrenHIDhash.DoesExist(newHID) = true
+                        newHID = ""
+                        exit for
+                    end if
+                end for
+            end if
+            return newHID
+        end function
+
+        ' ---------------------------------------------------------------------
+        ' get - Gets a single widget by search pattern
+        '
+        ' @param {string} searchPattern - HID or glob pattern to search for
+        ' @param {string} HID - Starting context HID (default: "0")
+        ' @returns {object} First matching widget or invalid if not found
+        '
+        function get(searchPattern as string, HID = "0" as string) as object
+            untilFirstItem = true
+            results = m.find(searchPattern, HID, untilFirstItem)
+            if results = invalid
+                return invalid
+            else
+                return results.shift()
+            end if
+        end function
+
+        ' ---------------------------------------------------------------------
+        ' getByHID - Gets a widget directly by its HID
+        '
+        ' @param {string} HID - Hierarchical ID to look up
+        ' @returns {object} Widget at the specified HID or invalid if not found
+        '
+        function getByHID(HID as string) as object
+            return HID = "0" ? m.tree : m.tree_HIDHash.get(HID)
+        end function
+
+        ' ---------------------------------------------------------------------
+        ' hasByHID - Checks if a widget exists at the specified HID
+        '
+        ' @param {string} HID - Hierarchical ID to check
+        ' @returns {boolean} True if widget exists, false otherwise
+        '
+        function hasByHID(HID as string) as boolean
+            return m.tree_HIDHash.has(HID)
+        end function
+
+        ' ---------------------------------------------------------------------
+        ' find - Searches the widget tree using a path-like glob pattern or direct HID
+        '
+        ' Supports:
+        ' - Direct lookup by HID
+        ' - Relative path resolution (./ and .. operators)
+        ' - Glob patterns: *, ** and normalization (e.g. multiple slashes, stars)
+        '
+        ' @param {string} searchPattern - The lookup expression
+        ' @param {string} HID - Optional starting node (default: root)
+        ' @param {boolean} untilFirstItem - If true, stops after first match (default: false)
+        ' @returns {object} Array of matching widgets, or invalid if none found
+        '
+        function find(searchPattern as string, HID = "0" as string, untilFirstItem = false as boolean) as object
+            ' TODO: In the future, this could use a well-designed ID-based cache to improve performance
+
+            ' Direct lookup: if the search pattern is an HID
+            if m.hasByHID(searchPattern) = true
+                return [m.getByHID(searchPattern)]
+            end if
+
+            ' Check if the pattern begins with "./" (relative to root)
+            prefix = Left(searchPattern, 2)
+            if prefix = "./"
+                searchPattern = Right(searchPattern, Len(searchPattern) - 2)
+                HID = "0" ' Reset to root if explicitly referencing from top
+            end if
+
+            ' Normalize search pattern
+            searchPattern = /^\/*/.ReplaceAll(searchPattern, "") ' Remove leading slashes
+            searchPattern = /\/{2,}/.ReplaceAll(searchPattern, "/") ' Replace multiple slashes with one
+            searchPattern = /\*{3,}/.ReplaceAll(searchPattern, "**") ' Replace 3+ stars with **
+            searchPattern = /\*\*$/.ReplaceAll(searchPattern, "*") ' Convert trailing ** to *
+            searchPattern = /(\*\*\/){2,}/.ReplaceAll(searchPattern, "**/")' Collapse multiple **/** into one
+
+            searchPattern = LCase(searchPattern)
+            parts = /\//.Split(searchPattern)
+
+            startNode = HID = "0" ? m.tree : m.getByHID(HID)
+
+            ' Resolve ".." (parent) operators
+            while parts[0] = ".." and startNode.HID <> "0"
+                parts.shift()
+                startNode = m.getByHID(startNode.parentHID)
+            end while
+
+            results = []
+
+            ' If parts is empty after resolving "..", return the startNode itself
+            if parts.Count() = 0
+                return [startNode]
+            end if
+
+            ' Add leading "**" if pattern doesn't start with ** or *
+            ' This enables deep search when user provides just an ID like "menuItem2"
+            if parts[0] <> "**" and parts[0] <> "*"
+                parts.unshift("**")
+            end if
+
+            lastPart = parts[parts.Count() - 1]
+            if startNode.HID <> "0" and LCase(startNode.id) = lastPart
+                results.unshift(startNode)
+            end if
+
+            ' Begin recursive search
+            m.recursionFind(results, parts, untilFirstItem, startNode.children)
+
+            if results.Count() = 0 then return invalid
+
+            return results
+        end function
+
+        ' ---------------------------------------------------------------------
+        ' matchesPattern - Check if a string matches a wildcard pattern
+        '
+        ' Supports:
+        ' - "*" matches everything
+        ' - "prefix*" matches strings starting with prefix
+        ' - "*suffix" matches strings ending with suffix
+        ' - "prefix*suffix" matches strings starting with prefix and ending with suffix
+        '
+        ' @param {string} str - The string to check
+        ' @param {string} pattern - The pattern with optional wildcards
+        ' @returns {boolean} True if matches, false otherwise
+        '
+        function matchesPattern(str as string, pattern as string) as boolean
+            if pattern = "*" then return true
+            if pattern.Instr("*") < 0 then return str = pattern ' No wildcard, exact match
+
+            ' Split pattern by *
+            parts = pattern.Split("*")
+            partsCount = parts.Count()
+
+            ' Check prefix (before first *)
+            if parts[0] <> "" and str.Left(parts[0].Len()) <> parts[0]
+                return false
+            end if
+
+            ' Check suffix (after last *)
+            if parts[partsCount - 1] <> "" and str.Right(parts[partsCount - 1].Len()) <> parts[partsCount - 1]
+                return false
+            end if
+
+            ' For patterns like "prefix*suffix", check both prefix and suffix
+            if partsCount = 2 and parts[0] <> "" and parts[1] <> ""
+                ' Check if string is long enough
+                if str.Len() < parts[0].Len() + parts[1].Len()
+                    return false
+                end if
+            end if
+
+            return true
+        end function
+
+        ' ---------------------------------------------------------------------
+        ' recursionFind - Recursively finds widgets in a tree structure based on glob-like patterns
+        '
+        ' Supports:
+        ' - "*" to match any key at one level
+        ' - "**" to match any number of nested levels
+        '
+        ' @param {object} results - Array to collect matching widgets
+        ' @param {object} parts - Pattern parts split by "/"
+        ' @param {boolean} untilFirstItem - If true, stops after the first match
+        ' @param {object} children - The widget tree branch to search (default: {})
+        ' @param {integer} index - Current position in the pattern (default: 0)
+        ' @returns {object} Array of matching widgets
+        '
+        function recursionFind(results as object, parts as object, untilFirstItem as boolean, children = {} as object, index = 0 as integer) as object
+            currentPart = parts[index]
+            partsCount = parts.Count()
+            isLastPart = (partsCount - 1 = index)
+            nextPart = isLastPart ? "" : parts[index + 1]
+
+            if children.Count() > 0
+                for each key in children
+                    widget = children[key]
+                    ' Note: key is already lowercase because widgets are stored with LCase(id) as key in tree.bs:85
+
+                    if isLastPart = true
+                        ' Check if current part matches the key (supports wildcards like "menuItem*")
+                        if m.matchesPattern(key, currentPart)
+                            results.push(widget)
+                            if untilFirstItem = true then return results
+                        end if
+                    else
+                        nextChildren = {}
+                        matchedParent = false
+
+                        if currentPart = "**"
+                            ' Deep search: check if next part matches current key
+                            if m.matchesPattern(key, nextPart)
+                                matchedParent = true
+                                nextChildren = children ' Stay at same level, exit ** mode
+                            else
+                                nextChildren = widget.children
+                            end if
+                        else if m.matchesPattern(key, currentPart)
+                            ' Matched current level, move to next level
+                            matchedParent = true
+                            nextChildren = widget.children
+                        end if
+
+                        newIndex = matchedParent = true ? index + 1 : index
+
+                        if nextChildren.Count() > 0 and newIndex < partsCount
+                            m.recursionFind(results, parts, untilFirstItem, nextChildren, newIndex)
+                        end if
+                    end if
+                end for
+            end if
+
+            return results
+        end function
+
+        ' ---------------------------------------------------------------------
+        ' getSubtreeClone - Creates a cloned subtree from a widget by search pattern
+        '
+        ' @param {string} searchPattern - Pattern to find the root widget
+        ' @param {object} keyPathList - List of key paths to include in clone (default: [])
+        ' @param {string} parentHID - Parent HID context (default: "0")
+        ' @returns {object} Cloned subtree structure or invalid if not found
+        '
+        function getSubtreeClone(searchPattern as string, keyPathList = [] as object, parentHID = "0" as string) as object
+            subTree = m.get(searchPattern, parentHID)
+            if subTree = invalid then return invalid
+
+            ' keyPathList.push("id")
+            keyPathList.push("HID")
+            ' keyPathList.push("parentHID")
+
+            subTreeClone = {}
+            m.recursion_getSubtreeClone(subTree, subTreeClone, keyPathList)
+
+            return subTreeClone
+        end function
+
+        ' ---------------------------------------------------------------------
+        ' recursion_getSubtreeClone - Recursively clones a widget subtree by specified key paths
+        '
+        ' Note: Tree uses AA for children but clone uses Array for updates.
+        '
+        ' @param {object} subTree - Source subtree to clone
+        ' @param {object} subTreeClone - Target clone object to populate
+        ' @param {object} keyPathList - List of key paths to include in clone
+        '
+        sub recursion_getSubtreeClone(subTree as object, subTreeClone as object, keyPathList as object)
+            ' Note that
+            for each keyPath in keyPathList
+                clonedValue = Rotor.Utils.getCloneByKeyPath(subTree, keyPath)
+                if clonedValue <> invalid
+                    Rotor.Utils.deepExtendAA(subTreeClone, clonedValue)
+                end if
+            end for
+            if subTree.children <> invalid and subTree.children.Count() > 0
+                subTreeClone.children = []
+                childIndex = 0
+                for each id in subTree.children
+                    subTreeClone.children.push({ id: id })
+                    m.recursion_getSubtreeClone(subTree.children[id], subTreeClone.children[childIndex], keyPathList)
+                    childIndex++
+                end for
+            end if
+        end sub
+
+    end class
+
+end namespace