@roku-sdk/components 0.0.0-stage → 2.19.0

package/src/xml-components/focus/focusable-group.brs

@@ -0,0 +1,251 @@
+' Copyright (c) 2026 Roku, Inc.
+' SPDX-License-Identifier: MIT
+
+sub init()
+    m.top.observeField("change", "onChange")
+    m.top.observeField("focusedChild", "onFocusedChild")
+    m.focusableNodes = []
+    m.lastFocusedNode = invalid
+    m.focusablesParentNode = invalid
+    m.firstChangeEvent = true
+end sub
+
+' Handle node change events to manage focusable nodes
+' Init is invoked when node is created but children are not appended yet.
+' Children are added later, so we need to observe the change event
+sub onChange(msg as Object)
+    data = msg.getData()
+    node = msg.getRoSGNode()
+
+    if data.Operation = "add"
+        handleAddOperation(msg, data)
+    else
+        handleNonAddOperation(node)
+    end if
+
+    ' print "Focusable Group event:"; data.Operation
+    ' print "Node: "; node.id
+    ' print "Focusable Nodes: "; m.focusableNodes.count()
+    setupParentNodeObserver()
+    m.firstChangeEvent = false
+end sub
+
+' Handle when nodes are added to the group
+sub handleAddOperation(msg as Object, data as Object)
+    child = msg.getRoSGNode().getChild(data.Index1)
+    if child <> invalid
+        addFocusableNode(child)
+    end if
+end sub
+
+' Handle operations other than 'add' (rebuild focusable nodes list)
+' TODO: This can be expensive. Look at the operation field and optimize
+sub handleNonAddOperation(node as Object)
+    m.focusableNodes = []
+    m.lastFocusedNode = invalid
+    if node <> invalid and node.getChildCount() > 0
+        for each child in node.getChildren(node.getChildCount(), 0)
+            addFocusableNode(child)
+        end for
+    end if
+end sub
+
+' Setup observer for parent node if needed
+sub setupParentNodeObserver()
+    if m.firstChangeEvent = true and m.focusablesParentNode <> invalid 
+        m.focusablesParentNode.observeField("change", "onChange")
+    end if
+end sub
+
+' Add a focusable node to the collection or search its children
+sub addFocusableNode(node as Object)
+    if node = invalid
+        return
+    end if
+
+    if isFocusableNode(node)
+        addToFocusableCollection(node)
+    else
+        findFocusableNodes(node)
+    end if
+end sub
+
+' Add node to focusable collection and track its parent
+sub addToFocusableCollection(node as Object)
+    m.focusableNodes.push(node)
+
+    if node.getParent() <> invalid and node.getParent().subtype() <> "focusable-group" and m.firstChangeEvent = true
+        if m.focusablesParentNode <> invalid and m.focusablesParentNode.id <> node.getParent().id
+            print "Warning: Each Focusable node has a different parent. This may lead to unexpected behavior."
+        end if
+
+        ' Can each focusable be wrapped in different parent?
+        ' If so, may be app should create a focusable group for each focusable node
+        m.focusablesParentNode = node.getParent()
+    end if
+end sub
+
+' Recursively search for focusable nodes in children
+sub findFocusableNodes(node as Object)
+    if node = invalid or node.getChildCount() = 0
+        return
+    end if
+
+    for each child in node.getChildren(node.getChildCount(), 0)
+        addFocusableNode(child)
+    end for
+end sub
+
+function isFocusableNode(node as Object) as Boolean
+    return node.subtype() = "focusable"
+end function
+
+function onKeyEvent(key as String, press as Boolean) as Boolean
+    ' When key is pressed, get the focused child
+    ' look for the nextFocusDirection on the node
+    ' if present, focus that node
+    handled = false
+    if press
+        inPathFocusables = getFocusableNodes(true) ' Should be only one focusable node in focus chain
+        if inPathFocusables.count() = 0 then return handled ' No focusable nodes in focus chain yet — bail early
+        item = inPathFocusables[0]
+        if item = invalid then return handled ' Safety guard against invalid array element
+        nextNodeId = item["nextFocus" + key] ' case insensitive
+        ' print "Next NodeId: "; nextNodeId
+        if nextNodeId <> invalid and nextNodeId <> "" then
+            focusables = getFocusableNodes(false) 
+            for i = 0 to focusables.count() - 1
+                searchResult = findClosestFocusableGroup(focusables[i], nextNodeId, invalid)
+                if searchResult <> invalid and searchResult.focusableGroup <> invalid and searchResult.focusableGroup.id = nextNodeId
+                    handled = searchResult.focusableGroup.callfunc("pickFocus")
+                    return handled
+                end if
+                if searchResult.nodeFound
+                    if searchResult.focusableGroup <> invalid
+                        handled = searchResult.focusableGroup.callfunc("assignFocus", nextNodeId, false)
+                    else 
+                        ' Moving focus within same focusable group
+                        handled = assignFocus(nextNodeId, true)
+                    end if
+                    ' print "Handled: "; handled
+                    return handled
+                end if
+            end for 
+        end if
+    end if
+    return handled
+end function
+
+function getFocusableNodes(isInFocusChain as Boolean) as Object
+    focusables = []
+    for i = 0 to m.focusableNodes.count() - 1
+        item = m.focusableNodes[i]
+        if item.isInFocusChain() = isInFocusChain
+            focusables.push(item)
+        end if
+    end for
+    return focusables
+end function
+
+' DFS to find the focus path for a given nodeId and closest focusable group
+function findClosestFocusableGroup(rootNode as Object, nodeId as String, parentFocusableGroup as Object) as Object
+    result = {
+        nodeFound: false,
+        focusableGroup: invalid
+    }
+    
+    if rootNode <> invalid
+        ' Update current focusable group if this node is one
+        currentFocusableGroup = parentFocusableGroup
+        if rootNode.subtype() = "focusable-group"
+            currentFocusableGroup = rootNode
+        end if
+        
+        ' Check if current node is the target
+        if rootNode.id = nodeId
+            result.nodeFound = true
+            result.focusableGroup = currentFocusableGroup
+            return result
+        end if
+        
+        ' Search children
+        for i = 0 to rootNode.getChildCount() - 1
+            child = rootNode.getChild(i)
+            if child <> invalid
+                childResult = findClosestFocusableGroup(child, nodeId, currentFocusableGroup)
+                if childResult.nodeFound
+                    return childResult
+                end if
+            end if
+        end for
+    end if
+    
+    return result
+end function
+
+' Assign focus to a node by its ID
+function assignFocus(nodeId as String, withInSameFocusableGroup as Boolean) as Object
+    if m.lastFocusedNode <> invalid and m.top.rememberLastFocus and withInSameFocusableGroup = false then
+        ' print "Setting Focus to last focused node: "; m.lastFocusedNode.id
+        m.lastFocusedNode.setFocus(true)
+    end if
+
+    foundNode = m.top.findNode(nodeId)
+    if foundNode <> invalid then
+        ' print "Setting focus to: "; foundNode.id
+        foundNode.setFocus(true)
+        m.lastFocusedNode = foundNode
+        return true
+    end if
+    return false
+end function
+
+' Pick the first focusable node in the focusable group
+function pickFocus() as Object
+    if m.lastFocusedNode <> invalid and m.top.rememberLastFocus
+        ' print "Setting focus to last focused node: "; m.lastFocusedNode.id
+        m.lastFocusedNode.setFocus(true)
+        return true
+    end if
+
+    firstFocusable = invalid
+    if m.focusableNodes.count() > 0
+        for each focusable in m.focusableNodes
+            if focusable.hasPreferredFocus = true
+                ' print "Setting initial focus to preferred focusable: "; focusable.getChild(0).id
+                firstFocusable = focusable
+                exit for
+            end if
+        end for
+        if firstFocusable = invalid
+            firstFocusable = m.focusableNodes[0]
+        end if
+
+        if firstFocusable <> invalid
+           firstFocusableChild = firstFocusable.getChild(0)
+        end if
+
+        if firstFocusableChild <> invalid
+            if firstFocusableChild.subtype() = "focusable-group"
+                return firstFocusableChild.callfunc("pickFocus")
+            else
+                ' print "Setting focus to first child of first focusable group: "; firstFocusableChild.id
+                firstFocusableChild.setFocus(true)
+                ' print "Setting initial focus to: "; firstFocusableChild.id
+                m.lastFocusedNode = firstFocusableChild
+                return true
+            end if
+        end if
+   end if
+   return false
+end function
+
+sub onFocusedChild(msg as Object)
+    data = msg.getData()
+
+    if m.top.isSameNode(data) ' this is the case when focus is set to this group
+       pickFocus()
+    end if    
+end sub
+
+

package/src/xml-components/focus/focusable-group.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+Copyright (c) 2026 Roku, Inc.
+SPDX-License-Identifier: MIT
+-->
+
+
+<component name="focusable-group" extends="Group">
+    <script type="text/brightscript" uri="focusable-group.brs" />
+    <interface>
+        <field id="rememberLastFocus" type="boolean" default="true" />
+        <function name="assignFocus" />
+        <function name="pickFocus" />
+    </interface>
+</component>

package/src/xml-components/focus/focusable-group.xml.d.ts

@@ -0,0 +1,42 @@
+// Auto-generated TypeScript declarations for XML component import.
+// DO NOT EDIT — this file is regenerated during build.
+//
+// Source component: focusable-group
+// Extends: Group
+
+import type { IGroupProps } from "@roku-sdk/components";
+import type { TypedXmlComponent } from "@roku-sdk/interfaces";
+
+interface focusableGroupFields {
+    /** @default "true" */
+    rememberLastFocus: boolean;
+}
+
+export interface IfocusableGroupProps extends IGroupProps, Partial<focusableGroupFields> {}
+
+declare const _default: TypedXmlComponent<"focusable-group", focusableGroupFields>;
+export default _default;
+
+declare module "@roku-sdk/solid" {
+    namespace JSX {
+        interface IntrinsicElements {
+            focusableGroup: IfocusableGroupProps;
+        }
+    }
+}
+
+declare module "@roku-sdk/solid/jsx-runtime" {
+    namespace JSX {
+        interface IntrinsicElements {
+            focusableGroup: IfocusableGroupProps;
+        }
+    }
+}
+
+declare module "solid-js" {
+    namespace JSX {
+        interface IntrinsicElements {
+            focusableGroup: IfocusableGroupProps;
+        }
+    }
+}

package/src/xml-components/focus/focusable.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+Copyright (c) 2026 Roku, Inc.
+SPDX-License-Identifier: MIT
+-->
+
+
+<component name="focusable" extends="Group">
+    <interface>
+        <field id="nextFocusUp" type="string" />
+        <field id="nextFocusDown" type="string" />
+        <field id="nextFocusLeft" type="string" />
+        <field id="nextFocusRight" type="string" />
+        <field id="nextFocusBack" type="string" />
+        <field id="nextFocusOk" type="string" />
+        <field id="hasPreferredFocus" type="boolean" default="false" />
+    </interface>
+</component>

package/src/xml-components/focus/focusable.xml.d.ts

@@ -0,0 +1,48 @@
+// Auto-generated TypeScript declarations for XML component import.
+// DO NOT EDIT — this file is regenerated during build.
+//
+// Source component: focusable
+// Extends: Group
+
+import type { IGroupProps } from "@roku-sdk/components";
+import type { TypedXmlComponent } from "@roku-sdk/interfaces";
+
+interface focusableFields {
+    nextFocusUp: string;
+    nextFocusDown: string;
+    nextFocusLeft: string;
+    nextFocusRight: string;
+    nextFocusBack: string;
+    nextFocusOk: string;
+    /** @default "false" */
+    hasPreferredFocus: boolean;
+}
+
+export interface IfocusableProps extends IGroupProps, Partial<focusableFields> {}
+
+declare const _default: TypedXmlComponent<"focusable", focusableFields>;
+export default _default;
+
+declare module "@roku-sdk/solid" {
+    namespace JSX {
+        interface IntrinsicElements {
+            focusable: IfocusableProps;
+        }
+    }
+}
+
+declare module "@roku-sdk/solid/jsx-runtime" {
+    namespace JSX {
+        interface IntrinsicElements {
+            focusable: IfocusableProps;
+        }
+    }
+}
+
+declare module "solid-js" {
+    namespace JSX {
+        interface IntrinsicElements {
+            focusable: IfocusableProps;
+        }
+    }
+}