@roku-sdk/components 0.0.0-stage → 2.19.0

package/src/sg-nodes/layout-group.tsx

@@ -0,0 +1,75 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { JSX } from "@roku-sdk/solid";
+
+import type { ILayoutGroupProps } from "./layout-group.props";
+export type { ILayoutGroupProps } from "./layout-group.props";
+
+// Re-export types for convenience
+export type { LayoutGroupHorizAlign, LayoutDirection, LayoutGroupVertAlign } from "./types";
+
+/**
+ * A container node that automatically positions its child nodes in either
+ * a horizontal row or vertical column layout with configurable alignment
+ * and spacing.
+ *
+ * LayoutGroup simplifies the task of positioning nodes by automatically
+ * calculating and applying the proper translation to each child node
+ * based on the `layoutDirection`, alignment settings, and `itemSpacings`.
+ *
+ * **Alignment and Translation**:
+ * The `horizAlignment` and `vertAlignment` properties align children relative
+ * to the LayoutGroup's `translation` point (default `[0, 0]`). To center
+ * the LayoutGroup and its content on screen, you must set the `translation`
+ * to the desired center point.
+ *
+ * For FHD (1920×1080) resolution:
+ * - Horizontal center: `1920 / 2 = 960`
+ * - Vertical center: `1080 / 2 = 540`
+ *
+ * @see https://developer.roku.com/dev/docs/layoutgroup
+ *
+ * @example
+ * // Vertical layout with left-aligned children (default)
+ * <layoutGroup
+ *     layoutDirection="vert"
+ *     itemSpacings={[20, 20, 20]}
+ * >
+ *     <label text="Item 1" />
+ *     <label text="Item 2" />
+ *     <label text="Item 3" />
+ * </layoutGroup>
+ *
+ * @example
+ * // Center a vertical layout on screen (FHD 1920×1080)
+ * // translation must be set to screen center for alignment to work as expected
+ * <layoutGroup
+ *     translation={[960, 540]}
+ *     layoutDirection="vert"
+ *     horizAlignment="center"
+ *     vertAlignment="center"
+ *     itemSpacings={[20, 20]}
+ * >
+ *     <label text="Centered Item 1" />
+ *     <label text="Centered Item 2" />
+ *     <label text="Centered Item 3" />
+ * </layoutGroup>
+ *
+ * @example
+ * // Horizontal layout centered at bottom of screen (FHD)
+ * <layoutGroup
+ *     translation={[960, 980]}
+ *     layoutDirection="horiz"
+ *     horizAlignment="center"
+ *     vertAlignment="bottom"
+ *     itemSpacings={[30, 30]}
+ * >
+ *     <poster width={100} height={100} />
+ *     <poster width={100} height={100} />
+ *     <poster width={100} height={100} />
+ * </layoutGroup>
+ */
+export function LayoutGroup(props: ILayoutGroupProps): JSX.Element {
+    return <layoutGroup {...props}></layoutGroup>;
+}

package/src/sg-nodes/list-panel.props.ts

@@ -0,0 +1,103 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { EventHandler, JSX } from "../types";
+import type { IPanelProps } from "./panel.props";
+
+/**
+ * Properties for the ListPanel component.
+ *
+ * ListPanel extends Panel to add a list of items that can be used to navigate
+ * to other panels using the Roku Sliding Panels pattern. The list can be a
+ * LabelList or MarkupList node, and supports the "Create Next Panel" mechanism
+ * for dynamic panel creation.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/listpanel | Roku ListPanel Documentation}
+ */
+export interface IListPanelProps extends IPanelProps {
+    /**
+     * A Label node to be displayed just above the upper-left corner of the list.
+     * Typically used to show a title or category name.
+     *
+     * @default Label node
+     */
+    leftLabel?: JSX.Element;
+
+    /**
+     * A Label node to be displayed just above the upper-right corner of the list.
+     * Typically used to show "N of M" item count information.
+     *
+     * @default Label node
+     */
+    rightLabel?: JSX.Element;
+
+    /**
+     * If set to true and the list is a MarkupList with sections, the section
+     * title for the currently focused section will be displayed as the `leftLabel`.
+     *
+     * @default false
+     */
+    showSectionLabels?: boolean;
+
+    /**
+     * Fired when the "Create Next Panel" mechanism is triggered. The event value
+     * contains the index of the list item that triggered the panel creation.
+     *
+     * This is the READ_ONLY `createNextPanelIndex` field from the SceneGraph ListPanel,
+     * exposed as an event handler for reactive usage.
+     *
+     * @see {@link https://developer.roku.com/dev/docs/listpanel#createNextPanelIndex | createNextPanelIndex Field}
+     */
+    onCreateNextPanelIndex?: EventHandler<number>;
+
+    /**
+     * A Panel node to be added to the parent PanelSet as the next panel.
+     * Setting this field adds the panel to the right of the current ListPanel.
+     *
+     * When using the managed `ListPanel` component, children extending Panel
+     * are automatically assigned to this field.
+     *
+     * @default false
+     */
+    nextPanel?: JSX.Element;
+
+    /**
+     * Controls whether the "Create Next Panel" mechanism is enabled.
+     * When true, navigating to a list item triggers the `onCreateNextPanelIndex` event.
+     * Set to false to disable dynamic panel creation.
+     *
+     * @default true
+     */
+    createNextPanelOnItemFocus?: boolean;
+}
+
+/**
+ * Properties for the raw `<listPanel>` SceneGraph element.
+ *
+ * These are the {@link IListPanelProps} plus the `list` and `nextPanel` node fields, which the
+ * managed `ListPanel` component fills in from its children. They type the lower-case
+ * `listPanel` JSX intrinsic and the generated SceneGraph declarations. Prefer the managed
+ * `ListPanel` component; use the raw element only when you set `list` and `nextPanel` yourself.
+ */
+export interface IFullPanelProps extends IListPanelProps {
+    /**
+     * A LabelList or MarkupList node to be displayed in the ListPanel.
+     * The list provides the navigation items for the panel.
+     *
+     * When using the managed `ListPanel` component, children extending ArrayGrid
+     * are automatically assigned to this field.
+     *
+     * @default null
+     */
+    list?: JSX.Element;
+    /**
+     * A Panel node to be added to the parent PanelSet as the next panel.
+     * Setting this field adds the panel to the right of the current ListPanel.
+     *
+     * When using the managed `ListPanel` component, children extending Panel
+     * are automatically assigned to this field.
+     *
+     * @default false
+     */
+    nextPanel?: JSX.Element;
+}

package/src/sg-nodes/list-panel.tsx

@@ -0,0 +1,49 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { retainAsset } from "../retain-asset";
+import { Component } from "../types";
+import ManagedListPanelXML from "../xml-components/managed-list-panel/ManagedListPanel.xml";
+import type { IListPanelProps } from "./list-panel.props";
+export type { IListPanelProps, IFullPanelProps } from "./list-panel.props";
+
+/**
+ * A panel component that displays a navigable list of items for the Roku
+ * Sliding Panels interface pattern.
+ *
+ * The `ListPanel` component creates a `managedListPanel` SceneGraph component
+ * that automatically handles `list` and `nextPanel` properties internally:
+ * - Children extending `ArrayGrid` (LabelList, MarkupList) are automatically assigned to `list`
+ * - Children extending `Panel` are automatically assigned to `nextPanel`
+ *
+ * Declare the list child before the panel child. The panel is matched to the row it was
+ * built for by consulting the list, so a panel declared first cannot be attributed to a row.
+ *
+ * While an asynchronously supplied `nextPanel` is still the previous row's, `ListPanel`
+ * transiently overrides {@link IFullPanelProps.selectButtonMovesPanelForward} to stop the
+ * platform opening the stale panel, restoring it once the correct panel arrives.
+ *
+ * This managed behavior simplifies the common pattern of defining a list and
+ * its associated next panel as JSX children rather than explicit property assignments.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/listpanel | Roku ListPanel Documentation}
+ * @see **ListPanel, GridPanel Best Practices** at the internal RSG 2.0 SDK documentation (knowledge-base/list-grid-panel-best-practice.md)
+ *
+ * @example
+ * ```tsx
+ * import { ListPanel } from "@roku-sdk/components";
+ *
+ * // Using managed child assignment
+ * <ListPanel
+ *   showSectionLabels={true}
+ *   onCreateNextPanelIndex={(index) => console.log(`Selected item: ${index}`)}
+ * >
+ *   <labelList content={items} /> // Automatically becomes list
+ *   <DetailPanel /> // Automatically becomes nextPanel
+ * </ListPanel>
+ * ```
+ */
+export const ListPanel: Component<IListPanelProps> = props => {
+    retainAsset(ManagedListPanelXML);
+    return <managedListPanel {...props} />;
+};

package/src/sg-nodes/markup-grid.props.ts

@@ -0,0 +1,78 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IArrayGridProps } from "./array-grid";
+import type { JSX, Uri } from "./types";
+
+/**
+ * Properties for the MarkupGrid node.
+ *
+ * MarkupGrid is a generic grid class that displays a set of items arranged in a
+ * 2D grid. The content of each grid item is an instance of an XML component
+ * specified by the `itemComponentName` field.
+ *
+ * The number of columns in the MarkupGrid is fixed and the number of rows varies
+ * as items fill from left to right, then top to bottom. Layouts range from simple
+ * uniform item sizes to complex multi-row/column spanning with `fixedLayout`.
+ *
+ * Grid items may be organized into sections demarcated by labelled horizontal
+ * divider lines between sections.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/markupgrid}
+ *
+ * @example Basic MarkupGrid
+ * ```tsx
+ * <MarkupGrid
+ *     itemComponentName="SimpleGridItem"
+ *     itemSize={[240, 135]}
+ *     numColumns={4}
+ *     content={
+ *         <contentNode>
+ *             <contentNode HDPOSTERURL="pkg:/images/item1.jpg" title="Item 1" />
+ *             <contentNode HDPOSTERURL="pkg:/images/item2.jpg" title="Item 2" />
+ *         </contentNode>
+ *     }
+ *     onItemSelected={(index) => console.log(`Selected: ${index}`)}
+ * />
+ * ```
+ */
+export interface IMarkupGridProps extends IArrayGridProps {
+    /**
+     * Specifies the name of the compiled component used to render each grid item.
+     *
+     * Register the compiled component by importing its XML file before use:
+     * ```ts
+     * import "./compiled-components/MyGridItem.xml";
+     * ```
+     *
+     * The compiled component may define interface fields that MarkupGrid will
+     * automatically update: `width`, `height`, `index`, `itemContent`,
+     * `focusPercent`, and `itemHasFocus`.
+     *
+     * @example "MyGridItem"
+     * @see {@link https://developer.roku.com/dev/docs/markupgrid | MarkupGrid itemComponentName}
+     */
+    itemComponentName: string;
+
+    /**
+     * Specifies the content for the grid.
+     *
+     * Should be a single root `ContentNode` with one child `ContentNode` per item.
+     * If the data contains section markers (`CONTENTTYPE="SECTION"`), section dividers
+     * will be drawn between each section.
+     *
+     * @see {@link https://developer.roku.com/dev/docs/markupgrid#data-bindings | Data bindings}
+     */
+    content: JSX.Element;
+
+    /**
+     * Specifies the bitmap file to use to suggest where images would appear for
+     * empty grids and empty sections of grids.
+     *
+     * Only set this field to specify a custom bitmap that differs in appearance
+     * from the default bitmap.
+     *
+     * @example "pkg:/images/image-well.png"
+     */
+    imageWellBitmapUri?: Uri;
+}

package/src/sg-nodes/markup-grid.tsx

@@ -0,0 +1,38 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IMarkupGridProps } from "./markup-grid.props";
+import { Component } from "./types";
+export type { IMarkupGridProps } from "./markup-grid.props";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MarkupGrid Properties
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * MarkupGrid is a generic grid class that can be used to display a set of items
+ * arranged in a 2D grid. The content of each grid item is an instance of an XML
+ * component specified by the `itemComponentName` field.
+ *
+ * The grid supports flexible layouts: simple uniform items, rows/columns with
+ * varying heights/widths, and fixed multi-cell spanning items. Items can be
+ * organized into labeled sections with horizontal dividers.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/markupgrid}
+ * @see {@link https://github.com/rokudev/samples/blob/master/ux%20components/lists%20and%20grids/SimpleMarkupList | SimpleMarkupList Sample App}
+ *
+ * @example
+ * ```tsx
+ * <markupGrid
+ *     itemComponentName="MyGridItem"
+ *     itemSize={[300, 200]}
+ *     numColumns={3}
+ *     content={gridContent}
+ *     onItemFocused={(index) => setFocusedIndex(index)}
+ *     onItemSelected={(index) => navigateToDetail(index)}
+ * />
+ * ```
+ */
+export const MarkupGrid: Component<IMarkupGridProps> = props => {
+    return <markupGrid {...props}></markupGrid>;
+};

package/src/sg-nodes/markup-list.props.ts

@@ -0,0 +1,66 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IArrayGridProps } from "./array-grid";
+import type { JSX } from "./types";
+
+/**
+ * Properties for the MarkupList node.
+ *
+ * MarkupList is a generic list class that displays a vertical list of items,
+ * where each item's appearance is defined by an XML component specified via
+ * `itemComponentName`. Item appearance as it enters/exits focus can be
+ * customized using BrightScript scripting in the item XML component.
+ *
+ * List items can be organized into sections demarcated by labelled horizontal
+ * divider lines between them.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/markuplist}
+ *
+ * @example Basic MarkupList
+ * ```tsx
+ * <MarkupList
+ *     itemComponentName="SimpleListItem"
+ *     itemSize={[440, 72]}
+ *     numRows={8}
+ *     content={
+ *         <contentNode>
+ *             <contentNode title="Drama" HDPOSTERURL="pkg:/images/drama.jpg" />
+ *             <contentNode title="Action" HDPOSTERURL="pkg:/images/action.jpg" />
+ *         </contentNode>
+ *     }
+ *     onItemSelected={(index) => console.log(`Selected: ${index}`)}
+ * />
+ * ```
+ */
+export interface IMarkupListProps extends IArrayGridProps {
+    /**
+     * Specifies the name of the compiled component used to render each list item.
+     *
+     * Register the compiled component by importing its XML file before use:
+     * ```ts
+     * import "./compiled-components/MyListItem.xml";
+     * ```
+     *
+     * The compiled component may define interface fields that MarkupList will
+     * automatically update: `width`, `height`, `index`, `listHasFocus`,
+     * `itemContent`, `focusPercent`, and `itemHasFocus`.
+     *
+     * @example "MyListItem"
+     * @see {@link https://developer.roku.com/dev/docs/markuplist | MarkupList itemComponentName}
+     */
+    itemComponentName: string;
+
+    /**
+     * Specifies the content for the list.
+     *
+     * Should be a single root ContentNode with one child ContentNode per item. If the data contains section markers (`CONTENTTYPE="SECTION"`), section dividers will be drawn between each section, optionally with an icon and/or label.
+     *
+     * **Important:** Place `content` before `jumpToItem` and `animateToItem` in the
+     * component. When content is updated dynamically, update `jumpToItem`/`animateToItem`
+     * in the same transaction or after content has been updated.
+     *
+     * @see {@link https://developer.roku.com/dev/docs/markuplist#data-bindings | Data bindings}
+     */
+    content?: JSX.Element;
+}

package/src/sg-nodes/markup-list.tsx

@@ -0,0 +1,38 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IMarkupListProps } from "./markup-list.props";
+import { Component } from "./types";
+export type { IMarkupListProps } from "./markup-list.props";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MarkupList Properties
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * MarkupList is a generic list class that displays a vertical list of items,
+ * where the visual content of each item is an instance of an XML component
+ * specified by the `itemComponentName` field.
+ *
+ * The item XML component receives injected fields (`width`, `height`, `index`,
+ * `listHasFocus`, `itemContent`, `focusPercent`, `itemHasFocus`) from the
+ * MarkupList, allowing BrightScript to customize item appearance as focus moves.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/markuplist}
+ * @see {@link https://github.com/rokudev/samples/tree/master/ux%20components/lists%20and%20grids | SimpleMarkupList Sample App}
+ *
+ * @example
+ * ```tsx
+ * <markupList
+ *     itemComponentName="MyListItem"
+ *     itemSize={[440, 72]}
+ *     numRows={8}
+ *     content={listContent}
+ *     onItemFocused={(index) => setFocusedIndex(index)}
+ *     onItemSelected={(index) => navigateToDetail(index)}
+ * />
+ * ```
+ */
+export const MarkupList: Component<IMarkupListProps> = props => {
+    return <markupList {...props}></markupList>;
+};

package/src/sg-nodes/mask-group.props.ts

@@ -0,0 +1,78 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./group.props";
+import type { EventHandler, Uri, Vector2D } from "./types";
+
+/**
+ * Properties for the MaskGroup node.
+ *
+ * MaskGroup allows an alpha mask bitmap to be applied to the rendering of its children.
+ * This enables effects such as having content fade out at edges.
+ *
+ * **Important Notes:**
+ * - MaskGroup only works on Roku players that support OpenGL
+ * - On non-OpenGL players, children render without the mask effect
+ * - Should only be used for decorative purposes (fading effects, etc.)
+ * - Does NOT work with 9-patch images
+ * - If mask size doesn't match group bounds, edge rows/columns are repeated
+ *
+ * @extends Group
+ * @see {@link https://developer.roku.com/dev/docs/maskgroup}
+ *
+ * @example
+ * <MaskGroup maskUri="pkg:/images/fade-mask.png">
+ *     <Poster uri="pkg:/images/content.jpg" width={400} height={300} />
+ * </MaskGroup>
+ */
+export interface IMaskGroupProps extends IGroupProps {
+    /**
+     * Specifies the bitmap to use for the group alpha mask.
+     *
+     * The alpha value of each pixel rendered in the group is multiplied by the
+     * corresponding pixel value in the alpha mask. The mapping from pixel
+     * coordinates in the group to mask pixel coordinates is controlled by
+     * the `maskSize` and `maskOffset` field values.
+     *
+     * @default ""
+     */
+    maskUri?: Uri;
+
+    /**
+     * Specifies a scaling factor of the alpha mask coordinate system relative
+     * to the group coordinate system.
+     *
+     * If either element doesn't match the corresponding mask bitmap size
+     * (reported via `onMaskBitmapWidth` / `onMaskBitmapHeight`), the mask
+     * is scaled to the specified size in that dimension.
+     *
+     * Setting either element to `0` causes the mask bitmap to be used at its
+     * actual size in that dimension.
+     *
+     * @default [0, 0]
+     */
+    maskSize?: Vector2D;
+
+    /**
+     * Specifies an offset of the mask coordinate system relative to the group
+     * coordinate system.
+     *
+     * For example, if set to `[100, 0]`, then mask pixel [0, 0] is used as
+     * the alpha value for pixels rendered at group coordinate [100, 0].
+     *
+     * @default [0, 0]
+     */
+    maskOffset?: Vector2D;
+
+    /**
+     * Invoked when the mask bitmap loads, with the actual width in pixels.
+     * Use this to size child content to match the mask bitmap dimensions.
+     */
+    onMaskBitmapWidth?: EventHandler<number>;
+
+    /**
+     * Invoked when the mask bitmap loads, with the actual height in pixels.
+     * Use this to size child content to match the mask bitmap dimensions.
+     */
+    onMaskBitmapHeight?: EventHandler<number>;
+}

package/src/sg-nodes/mask-group.tsx

@@ -0,0 +1,59 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IMaskGroupProps } from "./mask-group.props";
+import { Component } from "./types";
+export type { IMaskGroupProps } from "./mask-group.props";
+
+/**
+ * MaskGroup component for applying alpha masks to child content.
+ *
+ * Use MaskGroup to create decorative effects like fading content at edges,
+ * vignette effects, or shaped reveals. The mask bitmap's alpha channel
+ * determines the opacity of the rendered children.
+ *
+ * **How Masking Works:**
+ * - Each pixel's alpha is multiplied by the corresponding mask pixel value
+ * - White (255) in the mask = fully visible
+ * - Black (0) in the mask = fully transparent
+ * - Gray values = partial transparency
+ *
+ * **Limitations:**
+ * - Only works on OpenGL-capable Roku devices
+ * - On other devices, children render normally without the mask
+ * - Not suitable for critical UI elements due to device variability
+ * - Does not support 9-patch images
+ *
+ * @example
+ * ```tsx
+ * // Basic fade effect at bottom
+ * <maskGroup maskUri="pkg:/images/bottom-fade.png">
+ *     <poster uri="pkg:/images/hero.jpg" width={1920} height={1080} />
+ * </maskGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Scaled and offset mask
+ * <maskGroup
+ *     maskUri="pkg:/images/vignette.png"
+ *     maskSize={[800, 600]}
+ *     maskOffset={[100, 50]}
+ * >
+ *     <rectangle width={1000} height={700} color="#FF0000FF" />
+ * </maskGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Circular reveal effect
+ * <maskGroup maskUri="pkg:/images/circle-mask.png">
+ *     <poster uri={thumbnailUri} width={200} height={200} />
+ * </maskGroup>
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/maskgroup}
+ */
+export const MaskGroup: Component<IMaskGroupProps> = props => {
+    return <maskGroup {...props}></maskGroup>;
+};

package/src/sg-nodes/media-playback-methods.ts

@@ -0,0 +1,20 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { setPropMethod } from "@roku-sdk/solid";
+
+/**
+ * Shared imperative method descriptors for media playback nodes (Video, Audio).
+ * Both tags expose the same control surface for playback management.
+ */
+export const mediaPlaybackMethods = {
+    play: setPropMethod("control", "play"),
+    pause: setPropMethod("control", "pause"),
+    stop: setPropMethod("control", "stop"),
+    resume: setPropMethod("control", "resume"),
+    replay: setPropMethod("control", "replay"),
+    prebuffer: setPropMethod("control", "prebuffer"),
+    skipcontent: setPropMethod("control", "skipcontent"),
+    seekTo: setPropMethod("seek"),
+    setNextContentIndex: setPropMethod("nextContentIndex")
+};