@roku-sdk/components 0.0.0-stage → 2.18.0

package/src/xml-components/keyhandler/KeyHandler.brs

@@ -0,0 +1,30 @@
+' Copyright (c) 2026 Roku, Inc.
+' SPDX-License-Identifier: MIT
+
+Sub init()
+  print "init keyhandler"
+  m.top.observeField("keys", "updateKeyMap")
+  updateKeyMap()
+end Sub
+
+function onKeyEvent(key as String, press as Boolean) as Boolean
+    ' print "Key Event: "; key; " Press: "; press
+
+    if m.top.handleAllKeys = true
+        m.top.SetField("keyEvent", {"key": key, "press": press})
+        return true
+    end if
+
+    if m.keyMap[key] <> true and m.top.bubbleUnhandledKeys = true
+        return false
+    end if
+    m.top.SetField("keyEvent", {"key": key, "press": press})
+    return true
+end function
+
+sub updateKeyMap()
+    m.keyMap = {}
+    for each key in m.top.keys
+        m.keyMap[key] = true
+    end for
+end sub

package/src/xml-components/keyhandler/KeyHandler.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+Copyright (c) 2026 Roku, Inc.
+SPDX-License-Identifier: MIT
+-->
+
+
+<component name="key-handler" extends="Group" focusable="true">
+    <script type="text/brightscript" uri="KeyHandler.brs" />
+    <interface>
+        <field id="bubbleUnhandledKeys" type="boolean" value="true" />
+        <field id="keyEvent" type="assocarray" />
+        <field id="keys" type="stringarray" />
+        <field id="handleAllKeys" type="boolean" />
+    </interface>
+</component>

package/src/xml-components/keyhandler/KeyHandler.xml.d.ts

@@ -0,0 +1,45 @@
+// Auto-generated TypeScript declarations for XML component import.
+// DO NOT EDIT — this file is regenerated during build.
+//
+// Source component: key-handler
+// Extends: Group
+
+import type { IGroupProps } from "@roku-sdk/components";
+import type { TypedXmlComponent } from "@roku-sdk/interfaces";
+
+interface keyHandlerFields {
+    /** @default "true" */
+    bubbleUnhandledKeys: boolean;
+    keyEvent: Record<string, unknown>;
+    keys: string[];
+    handleAllKeys: boolean;
+}
+
+export interface IkeyHandlerProps extends IGroupProps, Partial<keyHandlerFields> {}
+
+declare const _default: TypedXmlComponent<"key-handler", keyHandlerFields>;
+export default _default;
+
+declare module "@roku-sdk/solid" {
+    namespace JSX {
+        interface IntrinsicElements {
+            keyHandler: IkeyHandlerProps;
+        }
+    }
+}
+
+declare module "@roku-sdk/solid/jsx-runtime" {
+    namespace JSX {
+        interface IntrinsicElements {
+            keyHandler: IkeyHandlerProps;
+        }
+    }
+}
+
+declare module "solid-js" {
+    namespace JSX {
+        interface IntrinsicElements {
+            keyHandler: IkeyHandlerProps;
+        }
+    }
+}

package/src/xml-components/managed-list-panel/ManagedListPanel.brs

@@ -0,0 +1,137 @@
+' Copyright (c) 2026 Roku, Inc.
+' SPDX-License-Identifier: MIT
+
+sub Init()
+  ' The row the attached nextPanel was built for, and a select still waiting for its panel.
+  m.attachedIndex = -1
+  m.pendingSelectIndex = -1
+  m.forwardSuppressed = false
+  ' Read rather than assume the default, so this does not have to be kept in step with it.
+  m.savedSelectForward = m.top.selectButtonMovesPanelForward
+  m.observedList = invalid
+  m.top.observeField("change", "onChildrenChange")
+  handleChildren()
+end sub
+
+' The app supplies nextPanel asynchronously, a render-thread hop after the list focus
+' moves, so in between it still holds the previous row's panel. Stop the built-in
+' forward move for as long as that is true. Clearing nextPanel instead would be
+' destructive: a ListPanel does not re-host a next panel once the field has been set
+' invalid, leaving the slot permanently empty.
+sub suppressForward()
+    if m.forwardSuppressed then return
+    m.savedSelectForward = m.top.selectButtonMovesPanelForward
+    m.forwardSuppressed = true
+    m.top.selectButtonMovesPanelForward = false
+end sub
+
+sub restoreForward()
+    if not m.forwardSuppressed then return
+    m.forwardSuppressed = false
+    m.top.selectButtonMovesPanelForward = m.savedSelectForward
+end sub
+
+sub onListItemFocused()
+    if m.observedList = invalid then return
+    focused = m.observedList.itemFocused
+    ' Navigating away abandons a select that was still waiting for its panel.
+    if m.pendingSelectIndex >= 0 and focused <> m.pendingSelectIndex
+        m.pendingSelectIndex = -1
+    end if
+    if m.attachedIndex >= 0 and focused <> m.attachedIndex
+        if m.top.createNextPanelOnItemFocus
+            m.attachedIndex = -1
+            ' Focus-driven panels arrive per row; suppress until the matching child lands.
+            suppressForward()
+        else
+            ' Static next panel: one panel serves every row. Keep attachedIndex in sync so
+            ' Select is not blocked waiting for a per-row panel that never arrives.
+            m.attachedIndex = focused
+        end if
+    end if
+end sub
+
+' Select on a row whose panel has not landed yet. The forward move is suppressed, so
+' remember the press rather than lose it and replay it once the panel arrives.
+sub onListItemSelected()
+    if m.observedList = invalid then return
+    ' If the app-level setting already blocks forward, there is nothing to replay.
+    if not m.savedSelectForward then return
+    selected = m.observedList.itemSelected
+    if m.attachedIndex <> selected
+        ' Record the press only when we are in the suppression window (stale-panel swap in
+        ' progress) or when no panel exists yet (first panel still on its way). In both cases
+        ' the native Select cannot do the right thing; flushPendingSelect will replay it once
+        ' the correct panel arrives. For static panels with a valid nextPanel and no active
+        ' suppression, skip recording and let the native behaviour handle it.
+        if m.forwardSuppressed or m.top.nextPanel = invalid
+            m.pendingSelectIndex = selected
+        end if
+    end if
+end sub
+
+' Replay a remembered select. The panel cannot be focused where it sits: nextPanel holds
+' it outside the tree, so setFocus alone is a no-op. Appending it to the PanelSet is what
+' performs the forward slide, the same move the suppressed Select would have made.
+sub flushPendingSelect()
+    if m.pendingSelectIndex < 0 or m.pendingSelectIndex <> m.attachedIndex then return
+    ' Honour the app-level setting: if selectButtonMovesPanelForward was false before
+    ' suppression began, replaying the select must not slide the panel forward either.
+    if not m.savedSelectForward then return
+    np = m.top.nextPanel
+    if np = invalid then return
+    panelSet = m.top.getParent()
+    if panelSet = invalid or not panelSet.isSubtype("PanelSet") then return
+    m.pendingSelectIndex = -1
+    panelSet.appendChild(np)
+    np.setFocus(true)
+end sub
+
+' Handle changes to the children of the managed list panel
+sub onChildrenChange(msg as Object)
+    changeDta = msg.getData()
+    operation = changeDta.operation
+    handleChildren()
+end sub
+
+' Depends on the list child being declared before the panel child: only the ArrayGrid branch
+' sets m.observedList, and the Panel branch needs it to learn which row the panel belongs to.
+' A consumer that puts the panel first would leave m.attachedIndex unset on the first pass, so
+' the stale-panel guard below would never arm. ListPanel documents the required child order.
+sub handleChildren()
+    for c = 0 to m.top.getChildCount() - 1
+        child = m.top.getChild(c)
+        if child <> invalid
+            hasBeenAssigned = false
+            subtype = child.subtype()
+            if child.isSubtype("Panel")
+                m.top.nextPanel = child
+                m.top.removeChild(child)
+                if m.observedList <> invalid
+                    ' A list that has not resolved a focused item yet reports -1, and
+                    ' the first panel arrives in exactly that window. Storing -1 leaves
+                    ' onListItemFocused unable to arm on the very first row change (it
+                    ' skips while attachedIndex is negative), so the first Select after
+                    ' the first Down is neither suppressed nor replayed — it is lost.
+                    ' The panel that just arrived is row 0's: index 0 is what the app
+                    ' was asked to build before the list reported any focus.
+                    attachedRow = m.observedList.itemFocused
+                    if attachedRow < 0 then attachedRow = 0
+                    m.attachedIndex = attachedRow
+                    restoreForward()
+                    flushPendingSelect()
+                end if
+                hasBeenAssigned = true
+            else if child.isSubtype("ArrayGrid")
+                if not child.isSameNode(m.top.list)
+                  m.top.list = child
+                  m.observedList = child
+                  ' Scoped so the callbacks resolve in this component, not the list's.
+                  child.observeFieldScoped("itemFocused", "onListItemFocused")
+                  child.observeFieldScoped("itemSelected", "onListItemSelected")
+                  hasBeenAssigned = true
+                end if
+            end if
+        end if
+    end for
+end sub

package/src/xml-components/managed-list-panel/ManagedListPanel.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+Copyright (c) 2026 Roku, Inc.
+SPDX-License-Identifier: MIT
+-->
+
+
+<component name="managedListPanel" extends="ListPanel">
+    <script type="text/brightscript" uri="ManagedListPanel.brs" />
+</component>

package/src/xml-components/managed-list-panel/ManagedListPanel.xml.d.ts

@@ -0,0 +1,37 @@
+// Auto-generated TypeScript declarations for XML component import.
+// DO NOT EDIT — this file is regenerated during build.
+//
+// Source component: managedListPanel
+// Extends: ListPanel
+
+import type { IListPanelProps } from "@roku-sdk/components";
+import type { TypedXmlComponent } from "@roku-sdk/interfaces";
+
+export interface ImanagedListPanelProps extends IListPanelProps {}
+
+declare const _default: TypedXmlComponent<"managedListPanel", Record<string, never>>;
+export default _default;
+
+declare module "@roku-sdk/solid" {
+    namespace JSX {
+        interface IntrinsicElements {
+            managedListPanel: ImanagedListPanelProps;
+        }
+    }
+}
+
+declare module "@roku-sdk/solid/jsx-runtime" {
+    namespace JSX {
+        interface IntrinsicElements {
+            managedListPanel: ImanagedListPanelProps;
+        }
+    }
+}
+
+declare module "solid-js" {
+    namespace JSX {
+        interface IntrinsicElements {
+            managedListPanel: ImanagedListPanelProps;
+        }
+    }
+}

package/src/xml-components/modal/Modal.brs

@@ -0,0 +1,105 @@
+' Copyright (c) 2026 Roku, Inc.
+' SPDX-License-Identifier: MIT
+
+sub init()
+    m.dialog = invalid
+    m.dismissed = false
+    m.presented = false
+    m.prepared = []
+end sub
+
+sub onDialogChange()
+    m.dismissed = false
+    updateDialog()
+end sub
+
+sub onOpenChange()
+    if m.top.open then m.dismissed = false
+    updateDialog()
+end sub
+
+function sameDialog(left as Dynamic, right as Dynamic) as Boolean
+    if left = invalid or right = invalid then return false
+    return left.isSameNode(right)
+end function
+
+sub updateDialog()
+    if not m.top.mounted then
+        closeSession(true)
+        m.prepared = []
+        return
+    end if
+    scene = m.top.getScene()
+    if scene = invalid then return
+    prepareDialogs(scene)
+    if not m.top.open or m.top.dialog = invalid then
+        m.dismissed = true
+        if sameDialog(scene.dialog, m.dialog) then
+            m.dialog.close = true
+        else
+            closeSession(false)
+        end if
+        return
+    end if
+    dialog = m.top.dialog
+    if not m.top.ready then dialog = m.top.fallback
+    if dialog = invalid then
+        releaseDialog(true)
+        return
+    end if
+    if m.dismissed or sameDialog(m.dialog, dialog) then return
+    if scene.dialog <> invalid and not sameDialog(scene.dialog, m.dialog) and not m.top.replaceExisting then
+        m.dismissed = true
+        closeSession(false)
+        m.top.blocked = true
+        return
+    end if
+    releaseDialog(false)
+    m.dialog = dialog
+    dialog.observeFieldScopedEx("wasClosed", "onNativeClosed")
+    scene.dialog = dialog
+    m.presented = true
+    if m.top.ready and m.top.initialFocusId <> "" then
+        target = dialog.findNode(m.top.initialFocusId)
+        if target <> invalid then target.setFocus(true)
+    end if
+    if m.top.ready then m.top.opened = true
+end sub
+
+sub prepareDialogs(scene as Object)
+    for each old in m.prepared
+        if old <> invalid and not sameDialog(old, m.top.dialog) and not sameDialog(old, m.top.fallback) then
+            if sameDialog(old.getParent(), m.top) then m.top.removeChild(old)
+        end if
+    end for
+    m.prepared = [m.top.dialog, m.top.fallback]
+    for each dialog in m.prepared
+        if dialog <> invalid and not sameDialog(scene.dialog, dialog) then
+            if not sameDialog(dialog.getParent(), m.top) then m.top.appendChild(dialog)
+        end if
+    end for
+end sub
+
+sub onNativeClosed(event as Object)
+    if not sameDialog(m.dialog, event.getRoSGNode()) then return
+    m.dismissed = true
+    closeSession(false)
+end sub
+
+sub closeSession(closeNative as Boolean)
+    releaseDialog(closeNative)
+    if not m.presented then return
+    m.presented = false
+    m.top.wasClosed = true
+end sub
+
+sub releaseDialog(closeNative as Boolean)
+    dialog = m.dialog
+    if dialog = invalid then return
+    m.dialog = invalid
+    dialog.unobserveFieldScoped("wasClosed")
+    scene = dialog.getScene()
+    if closeNative and scene <> invalid then
+        if sameDialog(scene.dialog, dialog) then dialog.close = true
+    end if
+end sub

package/src/xml-components/modal/Modal.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+Copyright (c) 2026 Roku, Inc.
+SPDX-License-Identifier: MIT
+-->
+
+
+<component name="modal" extends="Group">
+    <script type="text/brightscript" uri="Modal.brs" />
+    <interface>
+        <field id="dialog" type="node" onChange="onDialogChange" />
+        <field id="initialFocusId" type="string" />
+        <field id="open" type="boolean" value="true" onChange="onOpenChange" />
+        <field id="fallback" type="node" onChange="updateDialog" />
+        <field id="replaceExisting" type="boolean" value="true" />
+        <field id="ready" type="boolean" value="true" onChange="updateDialog" />
+        <field id="mounted" type="boolean" value="false" onChange="updateDialog" />
+        <field id="opened" type="boolean" alwaysNotify="true" />
+        <field id="wasClosed" type="boolean" alwaysNotify="true" />
+        <field id="blocked" type="boolean" alwaysNotify="true" />
+    </interface>
+</component>

package/src/xml-components/modal/Modal.xml.d.ts

@@ -0,0 +1,54 @@
+// Auto-generated TypeScript declarations for XML component import.
+// DO NOT EDIT — this file is regenerated during build.
+//
+// Source component: modal
+// Extends: Group
+
+import type { IGroupProps } from "@roku-sdk/components";
+import type { TypedXmlComponent } from "@roku-sdk/interfaces";
+
+interface modalFields {
+    dialog: import("@roku-sdk/interfaces").DomNode;
+    initialFocusId: string;
+    /** @default "true" */
+    open: boolean;
+    fallback: import("@roku-sdk/interfaces").DomNode;
+    /** @default "true" */
+    replaceExisting: boolean;
+    /** @default "true" */
+    ready: boolean;
+    /** @default "false" */
+    mounted: boolean;
+    opened: boolean;
+    wasClosed: boolean;
+    blocked: boolean;
+}
+
+export interface ImodalProps extends IGroupProps, Partial<modalFields> {}
+
+declare const _default: TypedXmlComponent<"modal", modalFields>;
+export default _default;
+
+declare module "@roku-sdk/solid" {
+    namespace JSX {
+        interface IntrinsicElements {
+            modal: ImodalProps;
+        }
+    }
+}
+
+declare module "@roku-sdk/solid/jsx-runtime" {
+    namespace JSX {
+        interface IntrinsicElements {
+            modal: ImodalProps;
+        }
+    }
+}
+
+declare module "solid-js" {
+    namespace JSX {
+        interface IntrinsicElements {
+            modal: ImodalProps;
+        }
+    }
+}

package/src/xml-components/modal/StandardDialogExt.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+Copyright (c) 2026 Roku, Inc.
+SPDX-License-Identifier: MIT
+-->
+
+
+
+<component name="StandardDialogExt" extends="StandardDialog">
+</component>

package/src/xml-components/modal/StandardDialogExt.xml.d.ts

@@ -0,0 +1,37 @@
+// Auto-generated TypeScript declarations for XML component import.
+// DO NOT EDIT — this file is regenerated during build.
+//
+// Source component: StandardDialogExt
+// Extends: StandardDialog
+
+import type { IStandardDialogProps } from "@roku-sdk/components";
+import type { TypedXmlComponent } from "@roku-sdk/interfaces";
+
+export interface IStandardDialogExtProps extends IStandardDialogProps {}
+
+declare const _default: TypedXmlComponent<"StandardDialogExt", Record<string, never>>;
+export default _default;
+
+declare module "@roku-sdk/solid" {
+    namespace JSX {
+        interface IntrinsicElements {
+            standardDialogExt: IStandardDialogExtProps;
+        }
+    }
+}
+
+declare module "@roku-sdk/solid/jsx-runtime" {
+    namespace JSX {
+        interface IntrinsicElements {
+            standardDialogExt: IStandardDialogExtProps;
+        }
+    }
+}
+
+declare module "solid-js" {
+    namespace JSX {
+        interface IntrinsicElements {
+            standardDialogExt: IStandardDialogExtProps;
+        }
+    }
+}

package/src/xml-components/modal/StandardKeyboardDialogExt.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+Copyright (c) 2026 Roku, Inc.
+SPDX-License-Identifier: MIT
+-->
+
+
+
+<component name="StandardKeyboardDialogExt" extends="StandardKeyboardDialog">
+</component>

package/src/xml-components/modal/StandardKeyboardDialogExt.xml.d.ts

@@ -0,0 +1,37 @@
+// Auto-generated TypeScript declarations for XML component import.
+// DO NOT EDIT — this file is regenerated during build.
+//
+// Source component: StandardKeyboardDialogExt
+// Extends: StandardKeyboardDialog
+
+import type { IStandardKeyboardDialogProps } from "@roku-sdk/components";
+import type { TypedXmlComponent } from "@roku-sdk/interfaces";
+
+export interface IStandardKeyboardDialogExtProps extends IStandardKeyboardDialogProps {}
+
+declare const _default: TypedXmlComponent<"StandardKeyboardDialogExt", Record<string, never>>;
+export default _default;
+
+declare module "@roku-sdk/solid" {
+    namespace JSX {
+        interface IntrinsicElements {
+            standardKeyboardDialogExt: IStandardKeyboardDialogExtProps;
+        }
+    }
+}
+
+declare module "@roku-sdk/solid/jsx-runtime" {
+    namespace JSX {
+        interface IntrinsicElements {
+            standardKeyboardDialogExt: IStandardKeyboardDialogExtProps;
+        }
+    }
+}
+
+declare module "solid-js" {
+    namespace JSX {
+        interface IntrinsicElements {
+            standardKeyboardDialogExt: IStandardKeyboardDialogExtProps;
+        }
+    }
+}

package/src/xml-components/modal/StandardMessageDialogExt.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+Copyright (c) 2026 Roku, Inc.
+SPDX-License-Identifier: MIT
+-->
+
+
+
+<component name="StandardMessageDialogExt" extends="StandardMessageDialog">
+</component>

package/src/xml-components/modal/StandardMessageDialogExt.xml.d.ts

@@ -0,0 +1,37 @@
+// Auto-generated TypeScript declarations for XML component import.
+// DO NOT EDIT — this file is regenerated during build.
+//
+// Source component: StandardMessageDialogExt
+// Extends: StandardMessageDialog
+
+import type { IStandardMessageDialogProps } from "@roku-sdk/components";
+import type { TypedXmlComponent } from "@roku-sdk/interfaces";
+
+export interface IStandardMessageDialogExtProps extends IStandardMessageDialogProps {}
+
+declare const _default: TypedXmlComponent<"StandardMessageDialogExt", Record<string, never>>;
+export default _default;
+
+declare module "@roku-sdk/solid" {
+    namespace JSX {
+        interface IntrinsicElements {
+            standardMessageDialogExt: IStandardMessageDialogExtProps;
+        }
+    }
+}
+
+declare module "@roku-sdk/solid/jsx-runtime" {
+    namespace JSX {
+        interface IntrinsicElements {
+            standardMessageDialogExt: IStandardMessageDialogExtProps;
+        }
+    }
+}
+
+declare module "solid-js" {
+    namespace JSX {
+        interface IntrinsicElements {
+            standardMessageDialogExt: IStandardMessageDialogExtProps;
+        }
+    }
+}

package/src/xml-components/modal/StandardPinPadDialogExt.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+Copyright (c) 2026 Roku, Inc.
+SPDX-License-Identifier: MIT
+-->
+
+
+
+<component name="StandardPinPadDialogExt" extends="StandardPinPadDialog">
+</component>

package/src/xml-components/modal/StandardPinPadDialogExt.xml.d.ts

@@ -0,0 +1,37 @@
+// Auto-generated TypeScript declarations for XML component import.
+// DO NOT EDIT — this file is regenerated during build.
+//
+// Source component: StandardPinPadDialogExt
+// Extends: StandardPinPadDialog
+
+import type { IStandardPinPadDialogProps } from "@roku-sdk/components";
+import type { TypedXmlComponent } from "@roku-sdk/interfaces";
+
+export interface IStandardPinPadDialogExtProps extends IStandardPinPadDialogProps {}
+
+declare const _default: TypedXmlComponent<"StandardPinPadDialogExt", Record<string, never>>;
+export default _default;
+
+declare module "@roku-sdk/solid" {
+    namespace JSX {
+        interface IntrinsicElements {
+            standardPinPadDialogExt: IStandardPinPadDialogExtProps;
+        }
+    }
+}
+
+declare module "@roku-sdk/solid/jsx-runtime" {
+    namespace JSX {
+        interface IntrinsicElements {
+            standardPinPadDialogExt: IStandardPinPadDialogExtProps;
+        }
+    }
+}
+
+declare module "solid-js" {
+    namespace JSX {
+        interface IntrinsicElements {
+            standardPinPadDialogExt: IStandardPinPadDialogExtProps;
+        }
+    }
+}

package/src/xml-components/modal/StandardProgressDialogExt.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+Copyright (c) 2026 Roku, Inc.
+SPDX-License-Identifier: MIT
+-->
+
+
+
+<component name="StandardProgressDialogExt" extends="StandardProgressDialog">
+</component>