22325902662

Committed 23 Feb 2026 09:38PM UTC coverage: 90.089% (-0.06%) from 90.146%

Build # 22325902662

Build Type

push

github

Committed by

mobalazs

Commit Message

chore: bump version to 0.8.2

Run Details

2218 of 2462 relevant lines covered (90.09%)

1.26 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

84.18

/src/source/plugins/FocusPlugin.bs

' TODO: Future improvement: integrate deviceinfo TimeSinceLastKeypress() -> idle time
' TODO: Future improvement: key combo detector

namespace Rotor

    ' =====================================================================
    ' FocusPlugin - Handles focus logic, focus groups, and spatial navigation
    '
    ' A Brighterscript class for handling focus logic, focus groups,
    ' and spatial navigation within the Rotor framework.
    '
    ' ═══════════════════════════════════════════════════════════════
    ' CONCEPTUAL OVERVIEW: BUBBLING vs CAPTURING
    ' ═══════════════════════════════════════════════════════════════
    '
    ' This plugin implements two complementary focus resolution strategies:
    '
    ' 1. BUBBLING FOCUS (bubblingFocus) - "Upward Search"
    '    ┌─────────────────────────────────────────────────────────┐
    '    │ WHEN: User interaction (key press) cannot find target   │
    '    │ DIRECTION: Child → Parent → Grandparent (upward)        │
    '    │ PURPOSE: "I can't navigate further, ask my parents"     │
    '    └─────────────────────────────────────────────────────────┘
    '
    '    Example: User presses UP from a focused item, but there's
    '    no item above. The plugin "bubbles up" through ancestor
    '    groups to find an alternative navigation path defined at
    '    a higher level.
    '
    ' 2. CAPTURING FOCUS (capturingFocus_recursively) - "Downward Rescue"
    '    ┌─────────────────────────────────────────────────────────┐
    '    │ WHEN: Need to resolve abstract target to concrete item  │
    '    │ DIRECTION: Group → Nested Group → FocusItem (downward)  │
    '    │ PURPOSE: "Found a group/ID, find the actual item"       │
    '    └─────────────────────────────────────────────────────────┘
    '
    '    This is a "rescue operation" that converts:
    '    - Group reference → concrete FocusItem
    '    - ID string → actual widget with focus capability
    '
    '    Example: Bubbling found "menuGroup", but we need a specific
    '    focusable item. Capturing recursively descends through the
    '    group's defaultFocusId chain until it finds a real FocusItem.
    '
    '
    ' DEEP SEARCH ENHANCEMENT:
    '    The capturing process now searches deeply in hierarchies.
    '    If defaultFocusId doesn't match immediate children, it will:
    '    - Search all descendant FocusItems (any depth)
    '    - Search all nested Groups (any depth)
    '    - Apply fallback logic if a matching Group is found
    '
    '    This means defaultFocusId: "deepItem" will find "deepItem"
    '    even if it's 3+ levels deep in the hierarchy!
    '
    ' TOGETHER THEY WORK AS:
    '    User Action → Bubbling (↑ find alternative) → Capturing (↓ resolve target)
    '
    ' ═══════════════════════════════════════════════════════════════
    ' COMPLETE RULES REFERENCE
    ' ═══════════════════════════════════════════════════════════════
    '
    ' RULE #1: Widget Types
    '   - focus: { group: {...} } → Group (container)
    '   - focus: {...} (no group key) → FocusItem (focusable element)
    '   - No focus config → Not part of focus system
    '
    ' RULE #2: FocusItem Direction Values
    '   - String (Node ID): Static navigation to that element
    '   - Function: Dynamic, evaluated at runtime
    '   - false: Blocks the direction (nothing happens)
    '   - true/undefined/empty string: Spatial navigation attempts
    '
    ' RULE #3: Navigation Priority (Decreasing Order)
    '   1. FocusItem static direction (left: "button2")
    '   2. Spatial navigation (within group only)
    '   3. BubblingFocus (ask parent groups)
    '
    ' RULE #4: Spatial Navigation Scope
    '   - Works within parent group scope
    '   - Participants: FocusItems AND direct child Groups with enableSpatialNavigation: true
    '   - enableSpatialNavigation default is FALSE (opt-in)
    '   - When Group is selected via spatial nav, capturing focus starts into that group
    '   - Searches possibleFocusItems + Groups from group.getGroupMembersHIDs()
    '
    ' RULE #5: Group Direction Activation
    '   Group direction triggers ONLY when:
    '   - FocusItem has NO static direction
    '   - Spatial navigation found NOTHING
    '   - BubblingFocus reaches this group
    '
    ' RULE #6: Group Direction Values
    '   - String (Node ID): Navigate to that group/item (may EXIT group)
    '   - true: BLOCKS (stays on current element)
    '   - false/undefined: Continue bubbling to next ancestor
    '
    ' RULE #7: Group Direction Does NOT Block Spatial Navigation
    '   Setting group.right = true does NOT prevent spatial navigation
    '   INSIDE the group. It only blocks EXITING the group when spatial
    '   navigation finds nothing.
    '
    ' RULE #8: Exiting a Group - 3 Methods
    '   Method 1: FocusItem explicit direction
    '     focusItem.right = "otherGroupItem" → EXITS immediately
    '   Method 2: Group direction (via BubblingFocus)
    '     group.right = "otherGroup" → EXITS when spatial nav fails
    '   Method 3: Ancestor group direction
    '     parentGroup.right = "otherGroup" → EXITS when child groups pass
    '
    ' RULE #9: Blocking Group Exit
    '   To prevent exit: group.left = true, group.right = true
    '   Exception: FocusItem explicit directions still work!
    '
    ' RULE #10: BubblingFocus Flow
    '   FocusItem (no direction) → Spatial nav (nothing) → Group.direction?
    '     - "nodeId" → CapturingFocus(nodeId) [EXIT]
    '     - true → STOP (stay on current)
    '     - false/undefined → Continue to parent group
    '     - No more ancestors → Stay on current
    '
    ' RULE #11: CapturingFocus Priority
    '   1. group.lastFocusedHID (if exists) [AUTO-SAVED]
    '   2. group.defaultFocusId [CONFIGURED]
    '   3. Deep search (if defaultFocusId not found immediately)
    '
    ' RULE #12: DefaultFocusId Targets
    '   - FocusItem node ID → Focus goes directly to it
    '   - Group node ID → Capturing continues on that group
    '   - Non-existent ID → Deep search attempts
    '
    ' RULE #13: Deep Search Activation
    '   Triggers when:
    '   - CapturingFocus doesn't find defaultFocusId in immediate children
    '   - defaultFocusId is not empty
    '   Searches:
    '   1. All descendant FocusItems (any depth)
    '   2. All nested Groups (any depth, applies their fallback)
    '
    ' RULE #14: Spatial Enter
    '   When enableSpatialEnter = true on a group:
    '   - Entering the group uses spatial navigation from the direction
    '   - Finds geometrically closest item instead of defaultFocusId
    '   - Falls back to defaultFocusId if spatial finds nothing
    '
    ' RULE #15: Navigation Decision Tree Summary
    '   User presses direction key:
    '     1. FocusItem.direction exists? → Use it (may EXIT group)
    '     2. Spatial nav finds item? → Navigate (STAYS in group)
    '     3. BubblingFocus: Group.direction?
    '        - "nodeId" → EXIT to that target
    '        - true → BLOCK (stay)
    '        - undefined → Continue to ancestor
    '     4. No more ancestors? → STAY on current item
    '
    ' COMMON PATTERNS:
    '   Sidebar + Content:
    '     sidebar: { group: { right: true } }
    '     menuItem1: { right: "contentFirst" } [explicit exit]
    '
    '   Modal Dialog (locked):
    '     modal: { group: { left: true, right: true, up: true, down: true } }
    '
    '   Nested Navigation:
    '     innerGroup: { group: { down: undefined } } [no direction]
    '     outerGroup: { group: { down: "bottomBar" } } [catches bubbling]
    '
    ' =====================================================================

    const PRIMARY_FOCUS_PLUGIN_KEY = "focus"
    const GROUP_FOCUS_PLUGIN_KEY = "focusGroup"
    class FocusPlugin extends Rotor.BasePlugin

        pluginKey = PRIMARY_FOCUS_PLUGIN_KEY
        aliasPluginKey = GROUP_FOCUS_PLUGIN_KEY

        ' Framework lifecycle hooks
        hooks = {
            ' ---------------------------------------------------------------------
            ' beforeMount - Hook executed before a widget is mounted
            '
            ' Sets initial focus config.
            '
            ' @param {object} scope - The plugin scope (this instance)
            ' @param {object} widget - The widget being mounted
            '
            beforeMount: sub(scope as object, widget as object)
                ' Validation: widget cannot have both "focus" and GROUP_FOCUS_PLUGIN_KEY configs
                isFocusItem = widget.DoesExist(PRIMARY_FOCUS_PLUGIN_KEY) and widget.focus <> invalid
                isFocusGroup = widget.DoesExist(GROUP_FOCUS_PLUGIN_KEY) and widget.focusGroup <> invalid

                if isFocusItem and isFocusGroup
                    #if debug
                        ? "[FOCUS_PLUGIN][ERROR] Widget '" + widget.id + "' (HID: " + widget.HID + ") cannot have both 'focus' and 'focusGroup' configurations!"
                    #end if
                    return ' Skip setup for this widget
                end if

                config = widget[isFocusItem ? PRIMARY_FOCUS_PLUGIN_KEY : GROUP_FOCUS_PLUGIN_KEY]
                scope.setFocusConfig(widget, config)
            end sub,

            ' ---------------------------------------------------------------------
            ' beforeUpdate - Hook executed before a widget is updated
            '
            ' Removes old config, applies new.
            '
            ' @param {object} scope - The plugin scope (this instance)
            ' @param {object} widget - The widget being updated
            ' @param {dynamic} newValue - The new plugin configuration value
            ' @param {object} oldValue - The previous plugin configuration value (default: {})
            '
            beforeUpdate: sub(scope as object, widget as object, newValue, oldValue = {})
                ' Remove previous config before applying the update
                scope.removeFocusConfig(widget.HID)

                ' Determine whether this widget is a focus item or focus group
                targetKey = PRIMARY_FOCUS_PLUGIN_KEY
                if widget.DoesExist(PRIMARY_FOCUS_PLUGIN_KEY) and widget[PRIMARY_FOCUS_PLUGIN_KEY] <> invalid
                    targetKey = PRIMARY_FOCUS_PLUGIN_KEY
                else
                    targetKey = GROUP_FOCUS_PLUGIN_KEY
                end if

                ' Ensure target config exists
                if not Rotor.Utils.isAssociativeArray(widget[targetKey])
                    widget[targetKey] = {}
                end if

                ' Merge new config into existing widget config (or replace if non-AA)
                if Rotor.Utils.isAssociativeArray(newValue)
                    Rotor.Utils.deepExtendAA(widget[targetKey], newValue)
                else
                    widget[targetKey] = newValue
                end if

                scope.setFocusConfig(widget, widget[targetKey])
            end sub,

            ' ---------------------------------------------------------------------
            ' beforeDestroy - Hook executed before a widget is destroyed
            '
            ' Removes focus config. Clears global focus if this widget had it.
            '
            ' @param {object} scope - The plugin scope (this instance)
            ' @param {object} widget - The widget being destroyed
            '
            beforeDestroy: sub(scope as object, widget as object)
                hadFocus = scope.globalFocusHID = widget.HID
                scope.removeFocusConfig(widget.HID)
                if hadFocus
                    scope.storeGlobalFocusHID("", "")
                end if
            end sub
        }

        ' Widget methods - Injected into widgets managed by this plugin
        widgetMethods = {

            ' ---------------------------------------------------------------------
            ' enableFocusNavigation - Enables or disables focus navigation globally for this plugin
            '
            ' @param {boolean} enableFocusNavigation - True to enable, false to disable (default: true)
            '
            enableFocusNavigation: sub(enableFocusNavigation = true as boolean)
                m.getFrameworkInstance().plugins[PRIMARY_FOCUS_PLUGIN_KEY].enableFocusNavigation = enableFocusNavigation
            end sub,

            ' ---------------------------------------------------------------------
            ' isFocusNavigationEnabled - Checks if focus navigation is currently enabled globally
            '
            ' @returns {boolean} True if enabled, false otherwise
            '
            isFocusNavigationEnabled: function() as boolean
                return m.getFrameworkInstance().plugins[PRIMARY_FOCUS_PLUGIN_KEY].enableFocusNavigation
            end function,

            ' ---------------------------------------------------------------------
            ' setFocus - Sets focus to this widget or another specified widget
            '
            ' @param {dynamic} isFocused - Boolean to focus/blur current widget, or string ID/HID of widget to focus
            ' @param {boolean} enableNativeFocus - If true, allows setting native focus on the underlying node
            ' @returns {boolean} True if focus state was changed successfully, false otherwise
            '
            setFocus: function(command = true as dynamic, enableNativeFocus = false as boolean) as boolean
                plugin = m.getFrameworkInstance().plugins[PRIMARY_FOCUS_PLUGIN_KEY]
                HID = m.HID

                if Rotor.Utils.isString(command)
                    return plugin.setFocus(command, true, enableNativeFocus)
                else
                    return plugin.setFocus(HID, command, enableNativeFocus)
                end if
            end function,

            ' ---------------------------------------------------------------------
            ' getFocusedWidget - Retrieves the currently focused widget managed by this plugin
            '
            ' @returns {object} The widget instance that currently holds focus, or invalid
            '
            getFocusedWidget: function() as object
                return m.getFrameworkInstance().plugins[PRIMARY_FOCUS_PLUGIN_KEY].getFocusedWidget()
            end function,

            ' ---------------------------------------------------------------------
            ' proceedLongPress - Manually triggers the navigation action associated with the current long-press key
            '
            ' @returns {object} The result of the executed navigation action (see parseOnKeyEventResult)
            '
            proceedLongPress: function() as object
                return m.getFrameworkInstance().plugins[PRIMARY_FOCUS_PLUGIN_KEY].proceedLongPress()
            end function,

            ' ---------------------------------------------------------------------
            ' isLongPressActive - Checks if a long press action is currently active
            '
            ' @returns {boolean} True if a long press is active, false otherwise
            '
            isLongPressActive: function() as boolean
                return m.getFrameworkInstance().plugins[PRIMARY_FOCUS_PLUGIN_KEY].isLongPress
            end function,

            ' ---------------------------------------------------------------------
            ' triggerKeyPress - Simulate key press
            '
            ' @param {string} key - Pressed key
            ' @returns {object} The widget instance that currently holds focus, or invalid
            '
            triggerKeyPress: function(key) as object
                return m.getFrameworkInstance().plugins[PRIMARY_FOCUS_PLUGIN_KEY].onKeyEventHandler(key, true)
            end function,

            ' ---------------------------------------------------------------------
            ' setGroupLastFocusedId - Updates the lastFocusedHID of this widget's focus group
            '
            ' If called on a focusGroup widget, updates its own lastFocusedHID.
            ' If called on a focusItem widget, finds and updates the parent group's lastFocusedHID.
            '
            ' @param {string} id - The widget id to set as lastFocusedHID
            '
            setGroupLastFocusedId: sub(id as string)
                plugin = m.getFrameworkInstance().plugins[PRIMARY_FOCUS_PLUGIN_KEY]

                ' Determine ancestorHID for search context
                ' If this is a focus item, use parent group's HID to find siblings
                ancestorGroups = plugin.findAncestorGroups(m.HID)
                if ancestorGroups.count() > 0
                    ancestorHID = ancestorGroups[0]
                else
                    ancestorHID = m.HID
                end if

                ' Resolve id to HID - check focusItemStack first, then groupStack
                focusItem = plugin.focusItemStack.getByNodeId(id, ancestorHID)
                if focusItem <> invalid
                    resolvedHID = focusItem.HID
                else
                    group = plugin.groupStack.getByNodeId(id, ancestorHID)
                    if group <> invalid
                        resolvedHID = group.HID
                    else
                        return
                    end if
                end if

                ' Check if this widget is a group
                group = plugin.groupStack.get(m.HID)
                if group <> invalid
                    group.setLastFocusedHID(resolvedHID)
                    return
                end if

                ' This is a focus item - find parent group
                ancestorGroups = plugin.findAncestorGroups(m.HID)
                if ancestorGroups.count() > 0
                    parentGroupHID = ancestorGroups[0]
                    parentGroup = plugin.groupStack.get(parentGroupHID)
                    if parentGroup <> invalid
                        parentGroup.setLastFocusedHID(resolvedHID)
                    end if
                end if
            end sub,

            ' ---------------------------------------------------------------------
            ' isFocused - Checks if this widget currently has focus
            '
            ' For a FocusItem: returns whether this item is the focused element
            ' For a Group: returns whether any descendant within this group has focus (is in focus chain)
            ' For widgets without focus config: returns false
            '
            ' @returns {boolean} True if focused (or in focus chain for groups), false otherwise
            '
            isFocused: function() as boolean
                plugin = m.getFrameworkInstance().plugins[PRIMARY_FOCUS_PLUGIN_KEY]
                focusItem = plugin.focusItemStack.get(m.HID)
                if focusItem <> invalid
                    return focusItem.isFocused
                end if
                group = plugin.groupStack.get(m.HID)
                if group <> invalid
                    return group.isFocused
                end if
                return false
            end function

        }

        ' Configuration
        longPressDuration = 0.4
        enableLongPressFeature = true
        enableFocusNavigation = true

        ' State tracking
        globalFocusHID = ""
        globalFocusId = ""
        lastNavigationDirection = ""
        isLongPress = false
        longPressKey = ""

        ' References
        widgetTree as object
        frameworkInstance as Rotor.Framework

        ' Helper objects
        focusItemStack = new Rotor.FocusPluginHelper.FocusItemStack()
        groupStack = new Rotor.FocusPluginHelper.GroupStack()
        distanceCalculator = new Rotor.FocusPluginHelper.ClosestSegmentToPointCalculatorClass()
        longPressTimer = CreateObject("roSGNode", "Timer")

        ' Spatial navigation direction validators (reused across calls)
        spatialValidators = {
            "left": function(segments as object, refSegmentLeft as object, refSegmentRight as object) as object
                right = segments[Rotor.Const.Segment.RIGHT]
                return right.x2 <= refSegmentLeft.x1 ? { isValid: true, segment: right } : { isValid: false }
            end function,
            "up": function(segments as object, refSegmentTop as object, refSegmentBottom as object) as object
                bottom = segments[Rotor.Const.Segment.BOTTOM]
                return bottom.y2 <= refSegmentTop.y1 ? { isValid: true, segment: bottom } : { isValid: false }
            end function,
            "right": function(segments as object, refSegmentLeft as object, refSegmentRight as object) as object
                left = segments[Rotor.Const.Segment.LEFT]
                return left.x1 >= refSegmentRight.x2 ? { isValid: true, segment: left } : { isValid: false }
            end function,
            "down": function(segments as object, refSegmentTop as object, refSegmentBottom as object) as object
                top = segments[Rotor.Const.Segment.TOP]
                return top.y1 >= refSegmentBottom.y2 ? { isValid: true, segment: top } : { isValid: false }
            end function
        }

        ' ---------------------------------------------------------------------
        ' init - Initializes the plugin instance
        '
        ' Sets up internal state and helpers.
        '
        sub init ()
            m.widgetTree = m.frameworkInstance.builder.widgetTree ' Reference to the main widget tree
            m.longPressTimer.addField("pluginKey", "string", false)
            m.longPressTimer.setFields({
                "pluginKey": m.pluginKey,
                duration: m.longPressDuration
            })
            ' Observe timer fire event to handle long press callback
            m.longPressTimer.observeFieldScoped("fire", "Rotor_FocusPluginHelper_longPressObserverCallback", ["pluginKey"])
        end sub

        '
        ' storeGlobalFocusHID - Stores the globally focused widget's HID and ID
        '
        ' @param {string} HID - The Hierarchical ID of the focused widget
        ' @param {string} id - The regular ID of the focused widget
        '
        sub storeGlobalFocusHID(HID as string, id as string)
            ' Store focus reference within the plugin
            m.globalFocusHID = HID
            m.globalFocusId = id
        end sub

        '
        ' getFocusedWidget - Gets the widget instance that currently holds global focus
        '
        ' @returns {object} The focused widget object, or invalid if none
        '
        function getFocusedWidget() as object
            return m.getFocusedItem()?.widget
        end function

        '
        ' getFocusedItem - Gets the FocusItem instance corresponding to the globally focused widget
        '
        ' @returns {object} The FocusItem instance, or invalid if none
        '
        function getFocusedItem() as object
            return m.focusItemStack.get(m.globalFocusHID)
        end function

        '
        ' setFocusConfig - Configures focus properties (FocusItem and/or Group) for a widget
        '
        ' @param {object} widget - The widget to configure
        ' @param {object} pluginConfig - The focus configuration object from the widget's spec
        '
        sub setFocusConfig(widget as object, pluginConfig as object)

            if pluginConfig = invalid then return ' No config provided
            HID = widget.HID
            id = widget.id

            ' Make a copy to avoid modifying the original config
            config = Rotor.Utils.deepCopy(pluginConfig)

            ' Ensure essential identifiers are in the config
            config.id = id
            config.HID = widget.HID

            ' Handle group configuration if present
            if widget.DoesExist(PRIMARY_FOCUS_PLUGIN_KEY)
                ' Handle focus item configuration if applicable
                m.setupFocusItem(HID, config, widget)
            else
                ' Handle group configuration
                m.setupGroup(HID, config, widget)
            end if
        end sub

        '
        ' setupGroup - Creates and registers a new Focus Group based on configuration
        '
        ' @param {string} HID - The Hierarchical ID of the widget acting as the group root
        ' @param {object} config - The full focus configuration for the widget
        ' @param {object} widget - The widget instance itself
        '
        sub setupGroup(HID as string, config as object, widget as object)
            ' Copy essential info to the group-specific config
            config.id = config.id
            config.HID = config.HID
            config.widget = widget
            ' Create and configure the Group instance
            newGroup = new Rotor.FocusPluginHelper.GroupClass(config)
            newGroup.focusItemsRef = m.focusItemStack ' Provide reference to focus items
            newGroup.groupsRef = m.groupStack ' Provide reference to other groups
            m.groupStack.set(config.HID, newGroup) ' Register the new group
        end sub

        '
        ' setupFocusItem - Creates and registers a new Focus Item based on configuration
        '
        ' @param {string} HID - The Hierarchical ID of the focusItem widget
        ' @param {object} config - The full focus configuration for the widget
        ' @param {object} widget - The widget instance itself
        '
        sub setupFocusItem(HID as string, config as object, widget as object)
            config.widget = widget ' Ensure widget reference is in the config

            ' Create and register the FocusItem instance
            newFocusItem = new Rotor.FocusPluginHelper.FocusItemClass(config)
            m.focusItemStack.set(HID, newFocusItem)

            ' Restore focus state if this widget had global focus
            if m.globalFocusHID = HID
                newFocusItem.isFocused = true
            end if
        end sub

        '
        ' findAncestorGroups - Finds all ancestor groups for a given widget HID
        '
        ' @param {string} HID - The Hierarchical ID of the widget
        ' @returns {object} An roArray of ancestor group HIDs, sorted with the immediate parent first (descending HID length)
        '
        function findAncestorGroups(HID as string) as object
            allGroups = m.groupStack.getAll() ' Get all registered groups
            ancestorGroups = []
            ' Iterate through all groups to find ancestors
            for each groupHID in allGroups
                if Rotor.Utils.isAncestorHID(groupHID, HID)
                    ancestorGroups.push(groupHID)
                end if
            end for
            ' Sort by HID length descending (parent first)
            ancestorGroups.Sort("r")

            ' Note:
            ' - Parent group is at index 0
            ' - If HID is a focusItem, its direct parent group is included
            ' - If HID is a group, the group itself is NOT included
            return ancestorGroups
        end function

        '
        ' removeFocusConfig - Removes focus configuration (Group and/or FocusItem) for a widget
        '
        ' @param {string} HID - The Hierarchical ID of the widget whose config should be removed
        '
        sub removeFocusConfig(HID as string)
            ' Remove associated group, if it exists
            if m.groupStack.has(HID)
                m.groupStack.remove(HID)
            end if
            ' Remove associated focus item, if it exists
            if m.focusItemStack.has(HID)
                m.focusItemStack.remove(HID)
            end if
        end sub

        '
        ' setFocus - Sets or removes focus from a specific widget or group
        '
        ' Handles focus state changes, callbacks, and native focus interaction.
        '
        ' @param {dynamic} ref - The target: HID (string) of a FocusItem or Group, or Node ID (string) of a Group
        ' @param {boolean} isFocused - True to set focus, false to remove focus (default: true)
        ' @param {boolean} enableNativeFocus - If true, allows setting native focus on the underlying node (default: false)
        ' @returns {boolean} True if the focus state was successfully changed, false otherwise
        '
        function setFocus(ref as dynamic, isFocused = true as boolean, enableNativeFocus = false as boolean) as boolean

            ' Resolve reference (HID or ID) to a focusItem item.
            focusItem = invalid ' Initialize target focus item

            ' Exit if reference is empty or invalid.
            if ref = invalid or ref = "" then return false

            if m.focusItemStack.has(ref)
                ' Case 1: ref is a valid focusItem HID.
                focusItem = m.focusItemStack.get(ref)
            else
                ' Case 2: ref might be a focusItem node ID.
                focusItem = m.focusItemStack.getByNodeId(ref)

                if focusItem = invalid
                    ' Case 3: ref might be a group HID or group node ID.
                    ' Try finding group by HID first, then by Node ID.
                    group = m.groupStack.get(ref) ?? m.groupStack.getByNodeId(ref)
                    if group <> invalid
                        ' If group found, find its default/entry focus item recursively.
                        ' Use lastNavigationDirection so enableSpatialEnter groups can pick the right entry point
                        HID = m.capturingFocus_recursively(group.HID, m.lastNavigationDirection)
                        focusItem = m.focusItemStack.get(HID) ' May still be invalid if capture fails
                        ' else: ref is not a known FocusItem HID or Group identifier
                    end if
                end if
            end if

            ' Handle case where the target focus item could not be found or resolved.
            if focusItem = invalid
                focused = m.focusItemStack.get(m.globalFocusHID) ' Check current focus
                #if debug
                    ' Log warnings if focus target is not found
                    if focused = invalid
                        print `[PLUGIN][FOCUS][WARNING] Requested focus target ref: "${ref}" was not found or resolved to a valid FocusItem.`
                        if m.globalFocusHID = ""
                            ' If global focus is also lost, indicate potential issue.
                            print `[PLUGIN][FOCUS][WARNING] Focus lost issue likely. No current focus set. Ensure valid initial focus.`
                        else
                            print `[PLUGIN][FOCUS][WARNING] Current focus HID: "${m.globalFocusHID}". Ensure target "${ref}" is registered and reachable.`
                        end if
                    else
                        print `[PLUGIN][FOCUS][WARNING] Could not find focus target ref: "${ref}". Current focus remains on HID: "${m.globalFocusHID}", id"${m.globalFocusId}"".`
                    end if
                #end if
                return false ' Indicate focus change failed
            end if

            ' Found a valid focusItem to target
            HID = focusItem.HID

            ' Exit if already focused/blurred as requested (no change needed).
            if HID = m.globalFocusHID and isFocused = true then return false
            ' Note: Handling blur when already blurred might be needed depending on desired logic, currently allows blurring focused item.

            ' Cannot focus an invisible item.
            if focusItem.node.visible = false and isFocused = true then return false

            ' Determine if native focus should be enabled (request or item default)
            enableNativeFocus = enableNativeFocus or focusItem.enableNativeFocus = true

            ' Prevent focusing a disabled item.
            preventFocusOnDisabled = focusItem.isEnabled = false and isFocused = true
            if preventFocusOnDisabled
                return false ' Indicate focus change failed
            end if

            ' Prepare ancestor groups for notification (from highest ancestor to closest parent)
            focusChainGroups = m.findAncestorGroups(focusItem.HID) ' Groups containing the new focus

            lastFocusChainingGroups = []

            ' Handle blurring the previously focused item
            if m.globalFocusHID <> "" ' If something was focused before
                lastFocused = m.focusItemStack.get(m.globalFocusHID)
                if lastFocused <> invalid ' Check if the last focused widget hasn't been destroyed
                    ' Record the last focused item within its parent group for potential future use (e.g., returning focus)
                    lastFocusChainingGroups = m.findAncestorGroups(m.globalFocusHID)
                    for i = 0 to lastFocusChainingGroups.Count() - 1
                        ancestorGroupHID = lastFocusChainingGroups[i]
                        ancestorGroup = m.groupStack.get(ancestorGroupHID)
                        if ancestorGroup <> invalid
                            ' For immediate parent (index 0): set if enableLastFocusId is true (default)
                            ' For other ancestors: set if enableDeepLastFocusId is enabled
                            shouldSetLastFocusId = (i = 0 and ancestorGroup.enableLastFocusId) or (i > 0 and ancestorGroup.enableDeepLastFocusId)
                            if shouldSetLastFocusId
                                ancestorGroup.setLastFocusedHID(m.globalFocusHID)
                            end if
                        end if
                    end for
                end if
            end if

            ' Prepare notification list: all affected groups (unique)
            allAffectedGroups = []
            for each groupHID in focusChainGroups
                allAffectedGroups.unshift(groupHID) ' Add in reverse order (highest ancestor first)
            end for
            for i = 0 to lastFocusChainingGroups.Count() - 1
                groupHID = lastFocusChainingGroups[i]

                ' Add to allAffectedGroups if not present
                if -1 = Rotor.Utils.findInArray(allAffectedGroups, groupHID)
                    allAffectedGroups.unshift(groupHID)
                end if
            end for

            ' Notify all ancestor groups BEFORE applying focus (from highest ancestor to closest parent)
            m.notifyFocusAtAncestorGroups(focusItem.HID, allAffectedGroups)

            ' Blur the previously focused item (after notification)
            if m.globalFocusHID <> "" and lastFocused <> invalid
                lastFocused.applyFocus(false, enableNativeFocus)
            end if

            ' Apply focus state (focused/blurred) to the target item.
            focusItem.applyFocus(isFocused, enableNativeFocus)

            ' Update the globally tracked focused item.
            m.storeGlobalFocusHID(isFocused ? HID : "", isFocused ? focusItem.id : "")

            ' Ensure SceneGraph root has focus if native focus wasn't explicitly enabled on the item.
            if enableNativeFocus = false
                globalScope = GetGlobalAA()
                if globalScope.top.isInFocusChain() = false
                    globalScope.top.setFocus(true)
                end if
            end if

            return true

        end function

        '
        ' notifyFocusAtAncestorGroups - Applies the correct focus state (in focus chain or not) to a list of group HIDs
        '
        ' @param {string} HID - The HID of the item that ultimately received/lost focus
        ' @param {object} groupHIDs - An roArray of group HIDs to notify
        '
        sub notifyFocusAtAncestorGroups(HID as string, groupHIDs = [] as object)

            ' Notify all ancestor groups
            if groupHIDs.Count() > 0
                for each groupHID in groupHIDs

                    group = m.groupStack.get(groupHID)
                    isInFocusChain = Rotor.Utils.isAncestorHID(groupHID, HID)
                    group.applyFocus(isInFocusChain)

                end for
            end if
        end sub

        sub notifyLongPressAtAncestorGroups(isLongPress as boolean, key as string, HID as string, groupHIDs = [] as object)
            ' Notify all ancestor groups
            if groupHIDs.Count() > 0
                for each groupHID in groupHIDs
                    group = m.groupStack.get(groupHID)
                    handled = group.callLongPressHandler(isLongPress, key)
                    if handled then exit for
                end for
            end if
        end sub

        function delegateKeyPress(key as string) as boolean
            focused = m.getFocusedItem()
            if focused = invalid then return false

            ' Bubble through ancestor groups (focused item already checked by caller)
            focusChainGroups = m.findAncestorGroups(focused.HID)
            for each groupHID in focusChainGroups
                group = m.groupStack.get(groupHID)
                handled = group.callKeyPressHandler(key)
                if handled then return true
            end for

            return false
        end function

        sub delegateLongPressChanged(isLongPress as boolean, key as string)
            focused = m.getFocusedItem()
            handled = focused.callLongPressHandler(isLongPress, key)
            if handled then return

            focusChainGroups = m.findAncestorGroups(focused.HID)
            m.notifyLongPressAtAncestorGroups(isLongPress, key, focused.HID, focusChainGroups)
        end sub

        function spatialNavigation(focused as object, direction as string, focusItemsHIDlist as object, bypassFocusedCheck = false as boolean) as string
            ' Skip if focused item doesn't participate in spatial nav (unless bypassed for cross-group nav)
            if not bypassFocusedCheck and focused.enableSpatialNavigation = false then return ""
            if direction = Rotor.Const.Direction.BACK then return ""

            ' Remove current focused item from candidates
            index = Rotor.Utils.findInArray(focusItemsHIDlist, focused.HID)
            if index >= 0 then focusItemsHIDlist.delete(index)

            ' Find closest focusable item in direction
            focusedMetrics = focused.refreshBounding()
            segments = m.collectSegments(focusedMetrics, direction, focusItemsHIDlist, focused.HID)
            if segments.Count() > 0
                return m.findClosestSegment(segments, focusedMetrics.middlePoint)
            end if

            return ""
        end function

        function findClosestSegment(segments as object, middlePoint as object) as string
            distances = []

            ' Calculate distance from middle point to each segment
            for each HID in segments
                segment = segments[HID]
                distance = m.distanceCalculator.distToSegment(middlePoint, {
                    x: segment.x1,
                    y: segment.y1
                }, {
                    x: segment.x2,
                    y: segment.y2
                })

                distances.push({
                    HID: HID,
                    distance: distance
                })
            end for

            ' Find segment with minimum distance
            minDistItem = Rotor.Utils.checkArrayItemsByHandler(distances, "distance", function(a, b) as dynamic
                return a < b
            end function)

            return minDistItem.HID
        end function


        ' Waterfall of fallback's of groups (linked together with defaultFocusId)
        function capturingFocus_recursively(identifier as string, direction = "", ancestorHID = "0" as string) as string
            ' Resolve identifier to a group
            group = m.groupStack.get(identifier)
            if group = invalid then group = m.groupStack.getByNodeId(identifier, ancestorHID)
            if group = invalid then return ""

            newHID = ""

            ' enableSpatialEnter: use spatialNavigation to find closest member
            if group.isSpatialEnterEnabledForDirection(direction)
                if direction <> "" and m.globalFocusHID <> ""
                    focused = m.focusItemStack.get(m.globalFocusHID)
                    if focused <> invalid
                        ' Get group members and use spatial navigation to find closest
                        members = group.getGroupMembersHIDs()
                        if members.count() > 0
                            newHID = m.spatialNavigation(focused, direction, members, true)
                            ' If spatial nav found a group (not a focus item), recursively resolve it
                            if newHID <> "" and m.groupStack.has(newHID)
                                newHID = m.capturingFocus_recursively(newHID, direction, group.HID)
                            end if
                        end if
                    end if
                end if
            end if

            ' Fallback to getFallbackIdentifier if spatial enter didn't find anything
            if newHID = ""
                newHID = group.getFallbackIdentifier(m.globalFocusHID, direction)
            end if

            ' Check if we found a FocusItem
            if m.focusItemStack.has(newHID)
                ' noop — direct focusItem resolved
            else if newHID <> ""
                ' Try to find as group first, then deep search
                newHID = m.capturingFocus_recursively(newHID, direction, group.HID)

                ' If still not found, perform deep search in all descendants
                if newHID = ""
                    newHID = m.deepSearchFocusItemByNodeId(group.HID, group.getFallbackNodeId())
                end if
            end if

            ' Prevent capturing by fallback in the same group where original focus was
            ' Skip this guard for enableSpatialEnter groups (spatial enter explicitly targets a sibling group's member)
            if not group.isSpatialEnterEnabledForDirection(direction) and newHID <> "" and m.globalFocusHID <> ""
                currentAncestors = m.findAncestorGroups(m.globalFocusHID)
                newAncestors = m.findAncestorGroups(newHID)
                if currentAncestors.Count() > 0 and newAncestors.Count() > 0
                    if currentAncestors[0] = newAncestors[0] and newHID <> m.globalFocusHID then newHID = ""
                end if
            end if

            return newHID
        end function

        '
        ' deepSearchFocusItemByNodeId - Deep search for a FocusItem or Group by nodeId within a group hierarchy
        '
        ' @param {string} groupHID - The HID of the group to search within
        ' @param {string} nodeId - The node ID to search for
        ' @returns {string} The HID of the found FocusItem or Group, or empty string if not found
        '
        function deepSearchFocusItemByNodeId(groupHID as string, nodeId as string) as string
            if nodeId = "" then return ""

            ' Get all descendants of this group (both FocusItems and nested Groups)
            allFocusItems = m.focusItemStack.getAll()
            allGroups = m.groupStack.getAll()

            ' First, search in direct and nested FocusItems
            for each focusItemHID in allFocusItems
                if Rotor.Utils.isDescendantHID(focusItemHID, groupHID)
                    focusItem = m.focusItemStack.get(focusItemHID)
                    if focusItem <> invalid and focusItem.id = nodeId
                        return focusItemHID
                    end if
                end if
            end for

            ' Second, search in nested Groups (and if found, apply fallback logic on that group)
            for each nestedGroupHID in allGroups
                if Rotor.Utils.isDescendantHID(nestedGroupHID, groupHID) and nestedGroupHID <> groupHID
                    nestedGroup = m.groupStack.get(nestedGroupHID)
                    if nestedGroup <> invalid and nestedGroup.id = nodeId
                        ' Found a matching group - now apply fallback logic on it
                        fallbackHID = nestedGroup.getFallbackIdentifier()
                        if m.focusItemStack.has(fallbackHID)
                            return fallbackHID
                        else if fallbackHID <> ""
                            ' Recursively resolve the fallback
                            return m.capturingFocus_recursively(fallbackHID, "", nestedGroupHID)
                        end if
                    end if
                end if
            end for

            return ""
        end function

        function bubblingFocus(groupHID, direction = "" as string) as dynamic
            newHID = ""

            ' Build ancestor chain (current group + all ancestors)
            ancestorGroups = m.findAncestorGroups(groupHID)
            ancestorGroups.unshift(groupHID)
            ancestorGroupsCount = ancestorGroups.Count()
            ancestorIndex = 0

            ' Get currently focused item for spatial navigation
            focused = m.focusItemStack.get(m.globalFocusHID)

            ' Bubble up through ancestor groups until we find a target or reach the top
            while Rotor.Utils.isString(newHID) and newHID = "" and ancestorIndex < ancestorGroupsCount
                ' Get next ancestor group
                groupHID = ancestorGroups[ancestorIndex]
                group = m.groupStack.get(groupHID)

                ' Check group's direction configuration
                nodeId = group.getStaticNodeIdInDirection(direction)

                if Rotor.Utils.isBoolean(nodeId)
                    ' Boolean means focus is explicitly handled
                    if nodeId = true
                        newHID = true ' Block navigation (exit loop)
                    else
                        newHID = "" ' Continue bubbling
                    end if
                else
                    ' String nodeId - try to resolve target
                    if nodeId <> ""
                        otherGroup = m.groupStack.getByNodeId(nodeId)
                        if otherGroup <> invalid
                            newHID = m.capturingFocus_recursively(otherGroup.HID, direction)
                        end if
                    else
                        ' No explicit direction - try spatial navigation at this group level
                        ' This allows navigation between sibling child groups with enableSpatialNavigation
                        ' Skip during long press to allow bubbling up to parent carousel for continuous scrolling
                        ' Skip for "back" direction - spatial navigation doesn't apply
                        if focused <> invalid and m.isLongPress = false and direction <> Rotor.Const.Direction.BACK
                            groupMembers = group.getGroupMembersHIDs()
                            ' Check if this group has any child groups with spatial nav enabled
                            hasSpatialNavGroups = false
                            for each memberHID in groupMembers
                                if m.groupStack.has(memberHID)
                                    memberGroup = m.groupStack.get(memberHID)
                                    if memberGroup.enableSpatialNavigation = true
                                        hasSpatialNavGroups = true
                                        exit for
                                    end if
                                end if
                            end for
                            ' If there are spatial-nav-enabled child groups, try spatial navigation
                            ' Use bypassFocusedCheck=true since we're navigating between groups, not within
                            if hasSpatialNavGroups
                                newHID = m.spatialNavigation(focused, direction, groupMembers, true)
                                ' If spatial nav found a group, use capturing focus to enter it
                                if newHID <> "" and m.groupStack.has(newHID)
                                    newHID = m.capturingFocus_recursively(newHID, direction)
                                end if
                            end if
                        end if
                    end if
                end if

                ancestorIndex++
            end while

            return newHID
        end function

        ' * KEY EVENT HANDLER
        function onKeyEventHandler(key as string, press as boolean) as object
            ' Check long-press
            if m.enableLongPressFeature = true
                m.checkLongPressState(key, press)
            end if
            ' Prevent any navigation if it is disabled
            #if debug
            #end if
            if m.enableFocusNavigation = false then return m.parseOnKeyEventResult(key, false, false)
            ' Execute action according to key press
            return m.executeNavigationAction(key, press)
        end function

        function executeNavigationAction(key as string, press as boolean) as object

            if true = press

                ' keyPressHandler: local (no bubbling), fires for all keys before navigation
                focusedItem = m.focusItemStack.get(m.globalFocusHID)
                if focusedItem <> invalid and focusedItem.keyPressHandler <> invalid
                    if true = Rotor.Utils.callbackScoped(focusedItem.keyPressHandler, focusedItem.widget, key)
                        return m.parseOnKeyEventResult(key, true, false)
                    end if
                end if

                if -1 < Rotor.Utils.findInArray([
                        Rotor.Const.Direction.UP,
                        Rotor.Const.Direction.RIGHT,
                        Rotor.Const.Direction.DOWN,
                        Rotor.Const.Direction.LEFT,
                        Rotor.Const.Direction.BACK
                    ], key)

                    newHID = ""
                    direction = key
                    m.lastNavigationDirection = direction

                    ' (1) Pick up current focused item

                    focused = m.focusItemStack.get(m.globalFocusHID)

                    if focused = invalid
                        #if debug
                            print `[PLUGIN][FOCUS][WARNING] Focus lost issue detected. Last known focus id:\"${m.globalFocusHID}\". Please ensure valid focus.`
                        #end if
                        return m.parseOnKeyEventResult(key, false, false)
                    end if


                    ancestorGroups = m.findAncestorGroups(focused.HID)
                    ancestorGroupsCount = ancestorGroups.Count()

                    if ancestorGroupsCount = 0
                        allFocusItems = m.focusItemStack.getAll()
                        possibleFocusItems = allFocusItems.keys()
                        parentGroupHID = ""
                    else
                        parentGroupHID = ancestorGroups[0]
                        group = m.groupStack.get(parentGroupHID)
                        possibleFocusItems = group.getGroupMembersHIDs()
                    end if

                    ' (2) Try static direction, defined on the focusItem, among possible focusItems
                    nodeId = focused.getStaticNodeIdInDirection(direction) ' Note that this is a nodeId

                    if Rotor.Utils.isBoolean(nodeId) and nodeId = true
                        ' It means that focus is handled, and no need further action by plugin.
                        return m.parseOnKeyEventResult(key, true, false)
                    end if

                    if nodeId <> ""
                        newHID = m.focusItemStack.convertNodeIdToHID(nodeId, possibleFocusItems)
                    end if

                    if newHID = ""
                        ' (3) Try spatial navigation in direction, among possible focusItems
                        ' all = m.focusItemStack.getAll()
                        ' allKeys = all.Keys()
                        newHID = m.spatialNavigation(focused, direction, possibleFocusItems)
                    end if

                    ' (4) Check if found group. FocusItem can not point out of group.
                    if newHID = "" and ancestorGroupsCount > 0 ' (5/2) If this focused has parent group, lets try bubbling focus on ancestors (groups)
                        newHID = m.bubblingFocus(parentGroupHID, direction)
                        if Rotor.Utils.isBoolean(newHID)
                            if newHID = true
                                ' It means that focus is handled, and no need further action by plugin.
                                return m.parseOnKeyEventResult(key, true, false)
                            else
                                newHID = ""
                            end if
                        end if
                    end if

                    handled = m.setFocus(newHID)
                    return m.parseOnKeyEventResult(key, handled, false)

                else if key = "OK"

                    return m.parseOnKeyEventResult(key, true, true)

                end if

                ' Unhandled key (not direction, not OK) → bubble through ancestor groups
                if m.delegateKeyPress(key) then return m.parseOnKeyEventResult(key, true, false)
            end if

            return m.parseOnKeyEventResult(key, false, false)

        end function

        function parseOnKeyEventResult(key as string, handled as boolean, isSelected as boolean) as object
            result = {
                handled: handled,
                key: key
            }
            if m.globalFocusHID <> "" and handled = true
                focusItem = m.focusItemStack.get(m.globalFocusHID)
                widget = m.widgetTree.get(focusItem.HID)
                ' viewModelState = Rotor.Utils.deepCopy(widget.viewModelState)
                result.widget = widget
                if isSelected
                    result.isSelected = isSelected
                    focusItem.callOnSelectFnOnWidget()
                end if
            end if
            return result
        end function

        sub checkLongPressState(key as string, press as boolean)
            m.longPressTimer.control = "stop"
            if press = true
                if m.isLongPress = false
                    m.longPressKey = key
                    m.longPressTimer.control = "start"
                end if
            else
                wasLongPress = m.isLongPress = true
                lastKey = m.longPressKey
                m.isLongPress = false
                m.longPressKey = ""
                if wasLongPress
                    m.delegateLongPressChanged(false, lastKey)
                end if
            end if
        end sub

        function proceedLongPress() as object
            if m.enableFocusNavigation = false then return m.parseOnKeyEventResult(m.longPressKey, false, false)
            return m.executeNavigationAction(m.longPressKey, true)
        end function

        ' Find all the relevant(closest in direction) segments that are in the same group as the focused item.
        ' @param focusedMetrics - The metrics object from focused.refreshBounding()
        ' @param focusedHID - The HID of the focused item (to exclude from candidates)
        function collectSegments(focusedMetrics as object, direction as string, focusItemsHIDlist as object, focusedHID as string) as object
            refSegments = focusedMetrics.segments
            refSegmentTop = refSegments[Rotor.Const.Segment.TOP]
            refSegmentRight = refSegments[Rotor.Const.Segment.RIGHT]
            refSegmentLeft = refSegments[Rotor.Const.Segment.LEFT]
            refSegmentBottom = refSegments[Rotor.Const.Segment.BOTTOM]

            segments = {}
            validator = m.spatialValidators[direction]
            for each HID in focusItemsHIDlist
                if HID <> focusedHID
                    ' Try to get as FocusItem first, then as Group
                    candidate = m.focusItemStack.get(HID)
                    isGroup = false
                    if candidate = invalid
                        candidate = m.groupStack.get(HID)
                        isGroup = true
                    end if
                    if candidate = invalid then continue for

                    ' Skip disabled items - they should not be candidates for spatial navigation
                    if not isGroup and candidate.isEnabled = false then continue for

                    candidateMetrics = candidate.refreshBounding()
                    ' Pass appropriate reference segments based on direction
                    if direction = "left" or direction = "right"
                        result = validator(candidateMetrics.segments, refSegmentLeft, refSegmentRight)
                    else ' up or down
                        result = validator(candidateMetrics.segments, refSegmentTop, refSegmentBottom)
                    end if
                    if result.isValid
                        segments[HID] = result.segment
                    end if
                end if
            end for

            return segments
        end function

        sub destroy()
            ' Remove all groups
            for each HID in m.groupStack.getAll()
                m.groupStack.remove(HID)
            end for
            ' Remove all focus items
            for each HID in m.focusItemStack.getAll()
                m.focusItemStack.remove(HID)
            end for
            m.longPressTimer.unobserveFieldScoped("fire")
            m.longPressTimer = invalid
            m.widgetTree = invalid
        end sub

    end class

    namespace FocusPluginHelper

        class BaseEntryStack extends Rotor.BaseStack

            function getByNodeId(nodeId as string, ancestorHID = "0" as string) as object
                if ancestorHID <> "0"
                    filteredStack = {}
                    for each HID in m.stack
                        if Rotor.Utils.isDescendantHID(HID, ancestorHID)
                            filteredStack[HID] = m.get(HID)
                        end if
                    end for
                else
                    filteredStack = m.stack
                end if
                HID = Rotor.Utils.findInAArrayByKey(filteredStack, "id", nodeId)
                return HID <> "" ? m.get(HID) : invalid
            end function

            override sub remove(HID as string)
                item = m.get(HID)
                item.destroy()
                super.remove(HID)
            end sub

        end class

        class GroupStack extends BaseEntryStack

            function convertNodeIdToHID(nodeId as string, possibleGroups as object) as string
                foundHID = ""
                for each HID in possibleGroups
                    group = m.get(HID)
                    if group.id = nodeId
                        foundHID = group.HID
                        exit for
                    end if
                end for
                return foundHID
            end function

        end class


        class FocusItemStack extends BaseEntryStack

            function convertNodeIdToHID(nodeId as string, possibleFocusItems as object) as string
                foundHID = ""
                for each HID in possibleFocusItems
                    focusItem = m.get(HID)
                    if focusItem?.id = nodeId
                        foundHID = focusItem.HID
                        exit for
                    end if
                end for
                return foundHID
            end function

            function hasEnabled(HID as string) as boolean
                if m.has(HID)
                    focusItem = m.get(HID)
                    return focusItem.isEnabled
                else
                    return false
                end if
            end function

        end class

        class BaseFocusConfig

            staticDirection as object

            sub new (config as object)

                m.HID = config.HID
                m.id = config.id

                m.widget = config.widget
                m.node = m.widget.node
                m.isFocused = config.isFocused ?? false

                m.isEnabled = config.isEnabled ?? true
                m.enableSpatialNavigation = config.enableSpatialNavigation ?? false
                m.staticDirection = {}
                m.staticDirection[Rotor.Const.Direction.UP] = config.up ?? ""
                m.staticDirection[Rotor.Const.Direction.RIGHT] = config.right ?? ""
                m.staticDirection[Rotor.Const.Direction.DOWN] = config.down ?? ""
                m.staticDirection[Rotor.Const.Direction.LEFT] = config.left ?? ""
                m.staticDirection[Rotor.Const.Direction.BACK] = config.back ?? ""

                m.onFocusChanged = config.onFocusChanged
                m.longPressHandler = config.longPressHandler
                m.keyPressHandler = config.keyPressHandler
                m.onFocus = config.onFocus
                m.onBlur = config.onBlur

                Rotor.Utils.setCustomFields(m.node, { "isFocused": false }, true, true)

                if m.widget.isViewModel = true and not m.widget.viewModelState.DoesExist("isFocused")
                    m.widget.viewModelState.isFocused = false
                end if

            end sub


            HID as string
            id as string
            idByKeys as object
            isEnabled as boolean
            isFocused as boolean
            enableSpatialNavigation as boolean
            onFocusChanged as dynamic
            onFocus as dynamic
            onBlur as dynamic
            longPressHandler as dynamic
            keyPressHandler as dynamic
            node as object
            widget as object

            protected metrics = {
                segments: {}
            }

            function refreshBounding() as object
                b = m.node.sceneBoundingRect()
                rotation = m.node.rotation

                if rotation = 0
                    if b.y = 0 and b.x = 0
                        t = m.node.translation
                        b.x += t[0]
                        b.y += t[1]
                    end if

                    m.metrics.append(b)
                    m.metrics.segments[Rotor.Const.Segment.LEFT] = {
                        x1: b.x, y1: b.y,
                        x2: b.x, y2: b.y + b.height
                    }
                    m.metrics.segments[Rotor.Const.Segment.TOP] = {
                        x1: b.x, y1: b.y,
                        x2: b.x + b.width, y2: b.y
                    }
                    m.metrics.segments[Rotor.Const.Segment.RIGHT] = {
                        x1: b.x + b.width, y1: b.y,
                        x2: b.x + b.width, y2: b.y + b.height
                    }
                    m.metrics.segments[Rotor.Const.Segment.BOTTOM] = {
                        x1: b.x, y1: b.y + b.height,
                        x2: b.x + b.width, y2: b.y + b.height
                    }
                    m.metrics.middlePoint = {
                        x: b.x + b.width / 2,
                        y: b.y + b.height / 2
                    }
                end if

                return m.metrics
            end function

            function getStaticNodeIdInDirection(direction as dynamic) as dynamic
                direction = m.staticDirection[direction]
                if Rotor.Utils.isFunction(direction)
                    return Rotor.Utils.callbackScoped(direction, m.widget) ?? ""
                else
                    return direction ?? ""
                end if
            end function

            sub callOnFocusedFnOnWidget(isFocused as boolean)
                Rotor.Utils.callbackScoped(m.onFocusChanged, m.widget, isFocused)
                if true = isFocused
                    Rotor.Utils.callbackScoped(m.onFocus, m.widget)
                else
                    Rotor.Utils.callbackScoped(m.onBlur, m.widget)
                end if
            end sub

            function callLongPressHandler(isLongPress as boolean, key as string) as boolean
                if Rotor.Utils.isFunction(m.longPressHandler)
                    return Rotor.Utils.callbackScoped(m.longPressHandler, m.widget, isLongPress, key)
                else
                    return false
                end if
            end function

            function callKeyPressHandler(key as string) as boolean
                if Rotor.Utils.isFunction(m.keyPressHandler)
                    return Rotor.Utils.callbackScoped(m.keyPressHandler, m.widget, key)
                else
                    return false
                end if
            end function

            sub destroy()
                m.widget = invalid
                m.node = invalid
                m.onFocusChanged = invalid
                m.onFocus = invalid
                m.onBlur = invalid
                m.longPressHandler = invalid
                m.keyPressHandler = invalid
            end sub

        end class

        class GroupClass extends BaseFocusConfig
            ' Note: Spatial navigation is supported within group, there is no spatial navigation between groups
            ' If you want to focus out to another group, you need to config a direction prop.
            ' You can set a groupId or any focusItem widgetId.
            ' > Point to a groupId: focus will be set to defaultFocusId or lastFocusedHID if available
            ' > Point to a widgetId: focus will be set to widgetId (and relevant group will be activated)

            sub new (config as object)
                super(config)
                m.defaultFocusId = config.defaultFocusId ?? ""
                m.lastFocusedHID = config.lastFocusedHID ?? ""
                m.enableSpatialEnter = config.enableSpatialEnter ?? false
                m.enableLastFocusId = config.enableLastFocusId ?? true
                m.enableDeepLastFocusId = config.enableDeepLastFocusId ?? false
            end sub

            defaultFocusId as string
            lastFocusedHID as string
            enableSpatialEnter as dynamic ' boolean | { up?: boolean, down?: boolean, left?: boolean, right?: boolean }
            enableLastFocusId as boolean
            enableDeepLastFocusId as boolean

            '
            ' isSpatialEnterEnabledForDirection - Checks if spatial enter is enabled for a specific direction
            '
            ' @param {string} direction - The direction to check (up, down, left, right)
            ' @returns {boolean} True if spatial enter is enabled for the direction
            '
            function isSpatialEnterEnabledForDirection(direction as string) as boolean
                if Rotor.Utils.isBoolean(m.enableSpatialEnter)
                    return m.enableSpatialEnter
                else if Rotor.Utils.isAssociativeArray(m.enableSpatialEnter)
                    return m.enableSpatialEnter[direction] = true
                end if
                return false
            end function
            focusItemsRef as object
            groupsRef as object
            isFocusItem = false
            isGroup = true

            sub setLastFocusedHID(lastFocusedHID as string)
                m.lastFocusedHID = lastFocusedHID
            end sub

            function getGroupMembersHIDs()
                ' Collect all focusItems that are descendants of this group
                ' Exclude items that belong to nested sub-groups
                ' Also include direct child groups with enableSpatialNavigation: true
                focusItems = m.focusItemsRef.getAll()
                groups = m.groupsRef.getAll()
                HIDlen = Len(m.HID)
                collection = []
                groupsKeys = groups.keys()
                groupsCount = groups.Count()

                ' Collect focusItems (existing logic)
                for each focusItemHID in focusItems
                    ' Check if focusItem is a descendant of this group
                    isDescendant = Left(focusItemHID, HIDlen) = m.HID
                    if isDescendant
                        ' Check if focusItem belongs to a nested sub-group
                        shouldExclude = false
                        otherGroupIndex = 0
                        while shouldExclude = false and otherGroupIndex < groupsCount
                            otherGroupHID = groupsKeys[otherGroupIndex]
                            otherGroupHIDlen = Len(otherGroupHID)
                            ' Exclude if belongs to deeper nested group
                            shouldExclude = Left(focusItemHID, otherGroupHIDlen) = otherGroupHID and otherGroupHIDlen > HIDlen
                            otherGroupIndex++
                        end while

                        if not shouldExclude then collection.push(focusItemHID)
                    end if
                end for

                ' Collect direct child groups with enableSpatialNavigation: true
                for i = 0 to groupsCount - 1
                    childGroupHID = groupsKeys[i]
                    childGroupHIDlen = Len(childGroupHID)

                    ' Check if it's a descendant of this group (but not this group itself)
                    if childGroupHIDlen > HIDlen and Left(childGroupHID, HIDlen) = m.HID
                        childGroup = groups[childGroupHID]

                        ' Only include if enableSpatialNavigation is true
                        if childGroup.enableSpatialNavigation = true
                            ' Check if it's a DIRECT child (no intermediate groups)
                            isDirectChild = true
                            for j = 0 to groupsCount - 1
                                intermediateHID = groupsKeys[j]
                                intermediateLen = Len(intermediateHID)
                                ' Check if there's a group between this group and the child
                                if intermediateLen > HIDlen and intermediateLen < childGroupHIDlen
                                    if Left(childGroupHID, intermediateLen) = intermediateHID
                                        isDirectChild = false
                                        exit for
                                    end if
                                end if
                            end for

                            if isDirectChild then collection.push(childGroupHID)
                        end if
                    end if
                end for

                return collection
            end function

            '
            ' getFallbackNodeId - Returns the nodeId to use for fallback (defaultFocusId or lastFocusedHID)
            '
            ' @returns {string} The nodeId to use for fallback, or empty string if none
            '
            function getFallbackNodeId() as string
                if m.lastFocusedHID <> ""
                    ' Note: lastFocusedHID is already a HID, not a nodeId, so we need to get the nodeId
                    lastFocusedItem = m.focusItemsRef.get(m.lastFocusedHID)
                    if lastFocusedItem <> invalid
                        return lastFocusedItem.id
                    end if
                end if

                if Rotor.Utils.isFunction(m.defaultFocusId)
                    return Rotor.Utils.callbackScoped(m.defaultFocusId, m.widget) ?? ""
                else
                    return m.defaultFocusId
                end if
            end function

            function getFallbackIdentifier(globalFocusHID = "" as string, direction = "" as string) as string
                HID = ""
                ' enableSpatialEnter is handled by capturingFocus_recursively using spatialNavigation
                ' Here we only handle lastFocusedHID and defaultFocusId fallbacks

                ' Use lastFocusedHID if available AND still exists (check both focusItems and groups)
                if not m.isSpatialEnterEnabledForDirection(direction) and m.lastFocusedHID <> ""
                    if m.focusItemsRef.has(m.lastFocusedHID) or m.groupsRef.has(m.lastFocusedHID)
                        return m.lastFocusedHID
                    end if
                end if

                ' Default: use defaultFocusId expression
                if Rotor.Utils.isFunction(m.defaultFocusId)
                    defaultFocusId = Rotor.Utils.callbackScoped(m.defaultFocusId, m.widget) ?? ""
                else
                    defaultFocusId = m.defaultFocusId
                end if

                focusItemsHIDlist = m.getGroupMembersHIDs()

                if defaultFocusId <> ""
                    if focusItemsHIDlist.Count() > 0
                        ' Try find valid HID in focusItems by node id
                        focusItemHID = m.findHIDinFocusItemsByNodeId(defaultFocusId, focusItemsHIDlist)
                        if focusItemHID <> ""
                            return focusItemHID
                        end if
                    end if
                    ' If not found as focusItem, return defaultFocusId string
                    ' so capturingFocus_recursively can try to resolve it as a group
                    return defaultFocusId
                end if

                ' Last resort: pick the first available member of the group
                if focusItemsHIDlist.Count() > 0
                    return focusItemsHIDlist[0]
                end if

                return HID
            end function

            function findHIDinFocusItemsByNodeId(nodeId as string, focusItemsHIDlist as object) as string
                for each itemHID in focusItemsHIDlist
                    focusItem = m.focusItemsRef.get(itemHID)
                    if focusItem <> invalid and focusItem.id = nodeId
                        return focusItem.HID
                    end if
                end for
                return ""
            end function

            sub applyFocus(isFocused as boolean)
                if m.isFocused = isFocused then return

                m.isFocused = isFocused
                m.node.setField("isFocused", isFocused)
                if m.widget.isViewModel = true then m.widget.viewModelState.isFocused = isFocused
                m.callOnFocusedFnOnWidget(isFocused)
            end sub

            override sub destroy()
                super.destroy()
                m.focusItemsRef = invalid
                m.groupsRef = invalid
            end sub



        end class

        class FocusItemClass extends BaseFocusConfig

            sub new (config as object)
                super(config)

                m.onSelect = config.onSelect ?? config.ok ?? ""
                m.enableNativeFocus = config.enableNativeFocus ?? false
            end sub

            ' You can set a groupId or any focusItem widgetId.
            ' > Point to a groupId: focus will be set to defaultFocusId or lastFocusedHID if available
            ' > Point to a widgetId: focus will be set to widgetId (and relevant group will be activated)

            ' key as string
            isFocusItem = true
            isGroup = false
            enableNativeFocus as boolean
            onSelect as dynamic

            private bounding as object


            override function refreshBounding() as object
                b = m.node.sceneBoundingRect()
                rotation = m.node.rotation

                ' If both bounding x and y are zero, then we assume that inheritParentTransform = false
                ' That is why we can use translation without knowing the value of inheritParentTransform
                ' If bounding x or y are not zero, then bounding will include the node's translation
                if rotation = 0
                    if b.y = 0 and b.x = 0
                        t = m.node.translation
                        b.x += t[0]
                        b.y += t[1]
                    end if

                    m.metrics.append(b)
                    m.metrics.segments[Rotor.Const.Segment.LEFT] = {
                        x1: b.x, y1: b.y,
                        x2: b.x, y2: b.y + b.height
                    }
                    m.metrics.segments[Rotor.Const.Segment.TOP] = {
                        x1: b.x, y1: b.y,
                        x2: b.x + b.width, y2: b.y
                    }
                    m.metrics.segments[Rotor.Const.Segment.RIGHT] = {
                        x1: b.x + b.width, y1: b.y,
                        x2: b.x + b.width, y2: b.y + b.height
                    }
                    m.metrics.segments[Rotor.Const.Segment.BOTTOM] = {
                        x1: b.x, y1: b.y + b.height,
                        x2: b.x + b.width, y2: b.y + b.height
                    }
                    m.metrics.middlePoint = { x: b.x + b.width / 2, y: b.y + b.height / 2 }
                else
                    scaleRotateCenter = m.node.scaleRotateCenter
                    dims = m.node.localBoundingRect() ' We need this to get proper (rotated value of rotated x and y)
                    if b.y = 0 and b.x = 0
                        t = m.node.translation
                        b.x += t[0]
                        b.y += t[1]
                    end if
                    b.width = dims.width
                    b.height = dims.height
                    m.metrics.append(b)

                    ' Calculate rotated segments
                    segmentLEFT = { x1: b.x, y1: b.y, x2: b.x, y2: b.y + b.height }
                    rotatedSegment = Rotor.Utils.rotateSegment(segmentLEFT.x1, segmentLEFT.y1, segmentLEFT.x2, segmentLEFT.y2, rotation, scaleRotateCenter)
                    m.metrics.segments[Rotor.Const.Segment.LEFT] = rotatedSegment

                    segmentTOP = { x1: b.x, y1: b.y, x2: b.x + b.width, y2: b.y }
                    rotatedSegment = Rotor.Utils.rotateSegment(segmentTOP.x1, segmentTOP.y1, segmentTOP.x2, segmentTOP.y2, rotation, scaleRotateCenter)
                    m.metrics.segments[Rotor.Const.Segment.TOP] = rotatedSegment

                    segmentRIGHT = { x1: b.x + b.width, y1: b.y, x2: b.x + b.width, y2: b.y + b.height }
                    rotatedSegment = Rotor.Utils.rotateSegment(segmentRIGHT.x1, segmentRIGHT.y1, segmentRIGHT.x2, segmentRIGHT.y2, rotation, scaleRotateCenter)
                    m.metrics.segments[Rotor.Const.Segment.RIGHT] = rotatedSegment

                    segmentBOTTOM = { x1: b.x, y1: b.y + b.height, x2: b.x + b.width, y2: b.y + b.height }
                    rotatedSegment = Rotor.Utils.rotateSegment(segmentBOTTOM.x1, segmentBOTTOM.y1, segmentBOTTOM.x2, segmentBOTTOM.y2, rotation, scaleRotateCenter)
                    m.metrics.segments[Rotor.Const.Segment.BOTTOM] = rotatedSegment

                    ' Calculate rotated middle point
                    middlePoint = { x: b.x + b.width / 2, y: b.y + b.height / 2 }
                    rotatedMiddlePoint = Rotor.Utils.rotateSegment(middlePoint.x, middlePoint.y, 0, 0, rotation, scaleRotateCenter)
                    m.metrics.middlePoint = { x: rotatedMiddlePoint.x1, y: rotatedMiddlePoint.y1 }

                end if

                return m.metrics
            end function

            override sub destroy()
                m.onSelect = invalid
                m.metrics.segments.Clear()
                super.destroy()
            end sub

            sub applyFocus(isFocused as boolean, enableNativeFocus = false as boolean)
                if m.isFocused = isFocused then return

                m.isFocused = isFocused
                m.node.setField("isFocused", isFocused)
                if m.widget.isViewModel = true then m.widget.viewModelState.isFocused = isFocused

                if enableNativeFocus or m.enableNativeFocus
                    m.node.setFocus(isFocused)
                end if

                m.callOnFocusedFnOnWidget(isFocused)

            end sub

            sub callOnSelectFnOnWidget()
                Rotor.Utils.callbackScoped(m.onSelect, m.widget)
            end sub

        end class

        class ClosestSegmentToPointCalculatorClass

            ' Translated from js; source: https://stackoverflow.com/a/6853926/16164491 (author:Joshua)
            function pDistance(x, y, x1, y1, x2, y2)

                A = x - x1
                B = y - y1
                C = x2 - x1
                D = y2 - y1

                dot = A * C + B * D
                len_sq = C * C + D * D
                param = -1
                if len_sq <> 0
                    param = dot / len_sq
                end if

                xx = 0
                yy = 0

                if param < 0
                    xx = x1
                    yy = y1
                else if param > 1
                    xx = x2
                    yy = y2
                else
                    xx = x1 + param * C
                    yy = y1 + param * D
                end if

                dx = x - xx
                dy = y - yy
                return dx * dx + dy * dy
            end function

            function distToSegment(p as object, s1 as object, s2 as object)
                return m.pDistance(p.x, p.y, s1.x, s1.y, s2.x, s2.y)
            end function

        end class

    end namespace

    namespace FocusPluginHelper

        sub longPressObserverCallback(msg)
            extraInfo = msg.GetInfo()

            pluginKey = extraInfo["pluginKey"]

            globalScope = GetGlobalAA()
            frameworkInstance = globalScope.rotor_framework_helper.frameworkInstance
            plugin = frameworkInstance.plugins[pluginKey]
            plugin.isLongPress = true
            ' plugin.longPressStartHID = plugin.globalFocusHID
            plugin.delegateLongPressChanged(true, plugin.longPressKey)

        end sub

    end namespace

end namespace

mobalazs / rotor-framework / 22325902662

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous