rotor-framework 0.7.4 → 0.7.6

package/README.md

@@ -96,7 +96,7 @@ You can find [🌱](./docs/ai/readme.opt.yaml) symbols in all documentation page
 
 ## 📚 Learn More
 
-![Version](https://img.shields.io/badge/version-v0.7.4-blue?label=Documents%20TAG)
+![Version](https://img.shields.io/badge/version-v0.7.6-blue?label=Documents%20TAG)
 
 ### Framework Core
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rotor-framework",
-	"version": "0.7.4",
+	"version": "0.7.6",
 	"description": "Roku toolkit library providing a ViewBuilder, full UI lifecycle with focus handling and many core features, plus MVI-based state management.",
 	"author": "Balázs Molnár",
 	"license": "Apache-2.0",

package/src/source/RotorFramework.bs

@@ -4,7 +4,7 @@
 ' ▐▛▀▚▖▐▌ ▐▌ █ ▐▌ ▐▌▐▛▀▚▖    ▐▛▀▀▘▐▛▀▚▖▐▛▀▜▌▐▌  ▐▌▐▛▀▀▘▐▌ ▐▌▐▌ ▐▌▐▛▀▚▖▐▛▚▖
 ' ▐▌ ▐▌▝▚▄▞▘ █ ▝▚▄▞▘▐▌ ▐▌    ▐▌   ▐▌ ▐▌▐▌ ▐▌▐▌  ▐▌▐▙▄▄▖▐▙█▟▌▝▚▄▞▘▐▌ ▐▌▐▌ ▐▌
 ' Rotor Framework™
-' Version 0.7.4
+' Version 0.7.6
 ' © 2025 Balázs Molnár — Apache License 2.0
 ' =========================================================================
 
@@ -86,7 +86,7 @@ namespace Rotor
     class Framework
 
         name = "Rotor Framework"
-        version = "0.7.4"
+        version = "0.7.6"
 
         config = {
             tasks: invalid, ' @array    (optional)

package/src/source/RotorFrameworkTask.bs

@@ -4,7 +4,7 @@
 ' ▐▛▀▚▖▐▌ ▐▌ █ ▐▌ ▐▌▐▛▀▚▖    ▐▛▀▀▘▐▛▀▚▖▐▛▀▜▌▐▌  ▐▌▐▛▀▀▘▐▌ ▐▌▐▌ ▐▌▐▛▀▚▖▐▛▚▖
 ' ▐▌ ▐▌▝▚▄▞▘ █ ▝▚▄▞▘▐▌ ▐▌    ▐▌   ▐▌ ▐▌▐▌ ▐▌▐▌  ▐▌▐▙▄▄▖▐▙█▟▌▝▚▄▞▘▐▌ ▐▌▐▌ ▐▌
 ' Rotor Framework™
-' Version 0.7.4
+' Version 0.7.6
 ' © 2025 Balázs Molnár — Apache License 2.0
 ' =========================================================================
 
@@ -70,7 +70,7 @@ namespace Rotor
     class FrameworkTask
 
         name = "Rotor Framework"
-        version = "0.7.4"
+        version = "0.7.6"
 
         config = {
             tasks: invalid, ' optional

package/src/source/plugins/FocusPlugin.bs

@@ -121,6 +121,13 @@ namespace Rotor
     '   2. group.defaultFocusId [CONFIGURED]
     '   3. Deep search (if defaultFocusId not found immediately)
     '
+    ' RULE #11b: Deep Focus Tracking (trackDescendantFocus: true)
+    '   When a FocusGroup has trackDescendantFocus: true, it stores lastFocusedHID
+    '   for ANY descendant FocusItem (not just direct children).
+    '   - Immediate parent ALWAYS stores lastFocusedHID (default behavior)
+    '   - Ancestor groups with trackDescendantFocus: true ALSO store it
+    '   - Enables "deep focus memory" - returning to deeply nested items
+    '
     ' RULE #12: DefaultFocusId Targets
     '   - FocusItem node ID → Focus goes directly to it
     '   - Group node ID → Capturing continues on that group
@@ -636,6 +643,7 @@ namespace Rotor
                     ' Record the last focused item within its parent group for potential future use (e.g., returning focus)
                     lastFocusChainingGroups = m.findAncestorGroups(m.globalFocusHID)
                     if lastFocusChainingGroups.Count() > 0
+                        ' Always set on immediate parent (index 0)
                         parentGroupHID = lastFocusChainingGroups[0]
                         if parentGroupHID <> invalid and parentGroupHID <> ""
                             group = m.groupStack.get(parentGroupHID)
@@ -652,9 +660,20 @@ namespace Rotor
             for each groupHID in focusChainGroups
                 allAffectedGroups.unshift(groupHID) ' Add in reverse order (highest ancestor first)
             end for
-            for each groupHID in lastFocusChainingGroups
+            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) ' Add in reverse order if not already present
+                    allAffectedGroups.unshift(groupHID)
+                end if
+
+                ' Deep remember (skip index 0 - immediate parent is handled separately)
+                if i > 0 and lastFocused <> invalid
+                    ancestorGroup = m.groupStack.get(groupHID)
+                    if ancestorGroup <> invalid and ancestorGroup.trackDescendantFocus = true
+                        ancestorGroup.setLastFocusedHID(m.globalFocusHID)
+                    end if
                 end if
             end for
 
@@ -778,17 +797,12 @@ namespace Rotor
             if group = invalid then return ""
 
             ' Get fallback identifier for this group
-            newHID = group.getFallbackIdentifier()
+            ' (enableSpatialEnter groups return the spatially closest member here)
+            newHID = group.getFallbackIdentifier(m.globalFocusHID)
 
             ' Check if we found a FocusItem
             if m.focusItemStack.has(newHID)
-                ' Apply spatial enter feature if enabled
-                if group.enableSpatialEnter = true and direction <> ""
-                    focused = m.focusItemStack.get(m.globalFocusHID)
-                    newSpatialHID = m.spatialNavigation(focused, direction, group.getGroupMembersHIDs())
-                    if newSpatialHID <> "" then newHID = newSpatialHID
-                end if
-
+                ' noop — direct focusItem resolved
             else if newHID <> ""
                 ' Try to find as group first, then deep search
                 newHID = m.capturingFocus_recursively(newHID, direction, group.HID)
@@ -800,7 +814,8 @@ namespace Rotor
             end if
 
             ' Prevent capturing by fallback in the same group where original focus was
-            if newHID <> "" and m.globalFocusHID <> ""
+            ' Skip this guard for enableSpatialEnter groups (spatial enter explicitly targets a sibling group's member)
+            if not group.enableSpatialEnter and newHID <> "" and m.globalFocusHID <> ""
                 currentAncestors = m.findAncestorGroups(m.globalFocusHID)
                 newAncestors = m.findAncestorGroups(newHID)
                 if currentAncestors.Count() > 0 and newAncestors.Count() > 0
@@ -904,7 +919,6 @@ namespace Rotor
             end if
             ' Prevent any navigation if it is disabled
             #if debug
-                if m.enableFocusNavigation = false and press = true then print "[PLUGIN][FOCUS][INFO] Focus navigation is disabled. Call enableFocusNavigation(true) to make it enabled"
             #end if
             if m.enableFocusNavigation = false then return m.parseOnKeyEventResult(key, false, false)
             ' Execute action according to key press
@@ -1279,14 +1293,15 @@ namespace Rotor
                 m.defaultFocusId = config.defaultFocusId ?? ""
                 m.lastFocusedHID = config.lastFocusedHID ?? ""
                 m.enableSpatialEnter = config.enableSpatialEnter ?? false
+                m.trackDescendantFocus = config.trackDescendantFocus ?? false
             end sub
 
             defaultFocusId as string
             lastFocusedHID as string
             enableSpatialEnter as boolean
+            trackDescendantFocus as boolean
             focusItemsRef as object
             groupsRef as object
-
             isFocusItem = false
             isGroup = true
 
@@ -1347,34 +1362,66 @@ namespace Rotor
                 end if
             end function
 
-            function getFallbackIdentifier() as string
+            function getFallbackIdentifier(globalFocusHID = "" as string) as string
                 HID = ""
-                if m.lastFocusedHID <> ""
+                ' enableSpatialEnter takes priority over lastFocusedHID
+                ' (lastFocusedHID may be stale from slot recycling)
+                if not m.enableSpatialEnter and m.lastFocusedHID <> ""
                     return m.lastFocusedHID
-                else
-                    if Rotor.Utils.isFunction(m.defaultFocusId)
-                        defaultFocusId = Rotor.Utils.callbackScoped(m.defaultFocusId, m.widget) ?? ""
-                    else
-                        defaultFocusId = m.defaultFocusId
-                    end if
-
-                    if defaultFocusId <> ""
-                        focusItemsHIDlist = m.getGroupMembersHIDs()
-                        if focusItemsHIDlist.Count() > 0
+                end if
 
-                            ' Try find valid HID in focusItems by node id
-                            focusItemHID = m.findHIDinFocusItemsByNodeId(defaultFocusId, focusItemsHIDlist)
-                            if focusItemHID <> ""
-                                HID = focusItemHID
+                ' enableSpatialEnter: return the spatially closest member to the current focus
+                if m.enableSpatialEnter = true and globalFocusHID <> ""
+                    prevFocused = m.focusItemsRef.get(globalFocusHID)
+                    if prevFocused <> invalid
+                        prevFocused.refreshBounding()
+                        refPoint = prevFocused.metrics.middlePoint
+                        members = m.getGroupMembersHIDs()
+                        minDist = 2147483647
+                        closestHID = ""
+                        for each memberHID in members
+                            if memberHID <> globalFocusHID
+                                member = m.focusItemsRef.get(memberHID)
+                                if member <> invalid
+                                    member.refreshBounding()
+                                    dx = member.metrics.middlePoint.x - refPoint.x
+                                    dy = member.metrics.middlePoint.y - refPoint.y
+                                    dist = dx * dx + dy * dy
+                                    if dist < minDist
+                                        minDist = dist
+                                        closestHID = memberHID
+                                    end if
+                                end if
                             end if
+                        end for
+                        if closestHID <> ""
+                            return closestHID
+                        end if
+                    end if
+                end if
 
-                        else
+                ' Default: use defaultFocusId expression
+                if Rotor.Utils.isFunction(m.defaultFocusId)
+                    defaultFocusId = Rotor.Utils.callbackScoped(m.defaultFocusId, m.widget) ?? ""
+                else
+                    defaultFocusId = m.defaultFocusId
+                end if
 
-                            return defaultFocusId
+                if defaultFocusId <> ""
+                    focusItemsHIDlist = m.getGroupMembersHIDs()
+                    if focusItemsHIDlist.Count() > 0
 
+                        ' Try find valid HID in focusItems by node id
+                        focusItemHID = m.findHIDinFocusItemsByNodeId(defaultFocusId, focusItemsHIDlist)
+                        if focusItemHID <> ""
+                            HID = focusItemHID
                         end if
-                    end if
 
+                    else
+
+                        return defaultFocusId
+
+                    end if
                 end if
 
                 return HID