@roku-sdk/components 0.0.0-stage → 2.18.0

package/src/sg-nodes/overhang.tsx

@@ -0,0 +1,29 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { Component } from "../types";
+import type { IOverhangProps } from "./overhang.props";
+export type { IOverhangProps } from "./overhang.props";
+
+/**
+ * The Overhang node provides an information bar that is displayed at the top of a screen
+ * in many Roku apps. The regions occupied by the overhang can be filled with either a
+ * solid color or a bitmap.
+ *
+ * The overhang typically includes a logo, title, clock, and options indicator, all of
+ * which can be customized or hidden as needed.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/overhang}
+ *
+ * @example
+ * <overhang
+ *     title="My Channel"
+ *     logoUri="pkg:/images/logo.png"
+ *     showClock={true}
+ *     showOptions={true}
+ *     optionsAvailable={true}
+ * />
+ */
+export const Overhang: Component<IOverhangProps> = props => {
+    return <overhang {...props}></overhang>;
+};

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

@@ -0,0 +1,71 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./group.props";
+import type { EventHandler } from "./types";
+
+/**
+ * Properties for the PanelSet component.
+ *
+ * PanelSet extends Group and provides the panel sliding behavior seen in the Roku home screen.
+ * It manages the position of child Panel nodes and implements left/right panel sliding behavior.
+ * When a Left or Back key is pressed, the panels slide to the right, back towards their original
+ * home position. When a Right key is pressed, the panels slide left, and panels that slide off
+ * the right side of the display are automatically removed from the PanelSet.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/panelset}
+ * @see {@link https://developer.roku.com/dev/docs/sliding-panels-nodes | Sliding Panels Overview}
+ *
+ * @example
+ * ```tsx
+ * import { PanelSet, Panel, Label } from "@roku-sdk/components";
+ *
+ * <PanelSet width={1280} height={605} slideDuration={500}>
+ *   <Panel panelSize="narrow" leftOnly={true}>
+ *     <Label text="Navigation Menu" translation={[50, 50]} />
+ *   </Panel>
+ *   <Panel panelSize="wide" isFullScreen={false}>
+ *     <Label text="Content Panel" translation={[50, 50]} />
+ *   </Panel>
+ * </PanelSet>
+ * ```
+ */
+export interface IPanelSetProps extends IGroupProps {
+    /**
+     * Specifies the width of the PanelSet node in local coordinates.
+     * In most cases, this should be set to the display width (e.g., 1280 for HD, 1920 for FHD).
+     *
+     * @default 1280
+     */
+    width?: number;
+
+    /**
+     * Specifies the height of the PanelSet node in local coordinates.
+     * In most cases, this should be set to the display height minus the overhang height.
+     *
+     * @default 605
+     */
+    height?: number;
+
+    /**
+     * Specifies the duration of the slide transition in milliseconds.
+     *
+     * @default 500
+     */
+    slideDuration?: number;
+
+    /**
+     * Fired when the `isGoingBack` field changes.
+     * The value is `true` when the PanelSet panels are sliding right, back towards the original
+     * home position, as a result of a Left or Back key press. The value is `false` otherwise.
+     *
+     * @see **ListPanel, GridPanel Best Practices** at the internal RSG SDK documentation (knowledge-base/list-grid-panel-best-practice.md) for handling slidingBack prop
+     */
+    onIsGoingBack?: EventHandler<boolean>;
+
+    /**
+     * Fired when the `numPanels` field changes.
+     * Contains the current number of Panel nodes that are children of the PanelSet node.
+     */
+    onNumPanels?: EventHandler<number>;
+}

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

@@ -0,0 +1,53 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IPanelSetProps } from "./panel-set.props";
+import { Component } from "./types";
+export type { IPanelSetProps } from "./panel-set.props";
+
+/**
+ * PanelSet is a Group node subclass that provides the panel sliding behavior seen in the Roku
+ * home screen. It manages child Panel nodes and implements left/right panel sliding behavior.
+ *
+ * In most cases, a PanelSet displays two Panel nodes: one on the left side (the "left panel")
+ * and one on the right side (the "right panel"). The panels slide left or right depending on
+ * user input, creating a navigation experience similar to the Roku OS.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/panelset}
+ * @see {@link https://developer.roku.com/dev/docs/sliding-panels-nodes | Sliding Panels Overview}
+ *
+ * @example
+ * Basic PanelSet with narrow and wide panels:
+ * ```tsx
+ * <panelSet width={1280} height={605}>
+ *   <panel panelSize="narrow" leftOnly={true}>
+ *     <label text="Menu" translation={[50, 50]} />
+ *   </panel>
+ *   <panel panelSize="wide">
+ *     <label text="Details" translation={[50, 50]} />
+ *   </panel>
+ * </panelSet>
+ * ```
+ *
+ * @example
+ * PanelSet with event handlers:
+ * ```tsx
+ * <panelSet
+ *   width={1920}
+ *   height={880}
+ *   slideDuration={300}
+ *   onIsGoingBack={(e) => console.log("Going back:", e.value)}
+ *   onNumPanels={(e) => console.log("Panel count:", e.value)}
+ * >
+ *   <panel panelSize="medium">
+ *     {/* Panel content *\/}
+ *   </panel>
+ *   <panel panelSize="medium">
+ *     {/* Panel content *\/}
+ *   </panel>
+ * </panelSet>
+ * ```
+ */
+export const PanelSet: Component<IPanelSetProps> = props => {
+    return <panelSet {...props}></panelSet>;
+};

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

@@ -0,0 +1,176 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./group.props";
+import type { EventHandler } from "./types";
+
+/**
+ * Panel size options for the Panel component.
+ * Controls the width and leftPosition of the panel when displayed in a PanelSet.
+ *
+ * | Value    | Meaning                                                                      |
+ * |----------|------------------------------------------------------------------------------|
+ * | `narrow` | Set the width and leftPosition fields to the values for a narrow Panel      |
+ * | `medium` | Set the width and leftPosition fields to the values for a medium width Panel|
+ * | `wide`   | Set the width and leftPosition fields to the values for a wide Panel        |
+ * | `full`   | Set the width and leftPosition fields to the values for a full width Panel  |
+ *
+ * Note: PanelSet usage mandates that whenever two Panels are visible, they should include
+ * either one narrow and one wide panel or two medium width panels. If one Panel is visible,
+ * its panelSize should be set to "full".
+ */
+export type PanelSize = "narrow" | "medium" | "wide" | "full";
+
+/**
+ * Properties for the Panel component.
+ *
+ * Panel extends Group and is used to create sliding panels for app UI,
+ * similar to those in the Roku OS home screen.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/panel}
+ * @see {@link https://developer.roku.com/dev/docs/sliding-panels-nodes Sliding Panels Overview}
+ *
+ * @example
+ * ```tsx
+ * import { Panel, PanelSet } from "@roku-sdk/components";
+ *
+ * <PanelSet>
+ *   <Panel panelSize="medium" leftOnly={true}>
+ *     <Label text="Panel Content" />
+ *   </Panel>
+ * </PanelSet>
+ * ```
+ */
+export interface IPanelProps extends IGroupProps {
+    /**
+     * Specifies one of the default panel sizes. Setting this field causes the width
+     * and leftPosition fields to be set to values that match the RSG preferred layout
+     * for a panel of the specified size.
+     *
+     * @default "narrow"
+     */
+    panelSize?: PanelSize;
+
+    /**
+     * Specifies the width of the panel in pixels. In most cases, this should be set
+     * by setting the panelSize field to one of the pre-configured settings.
+     *
+     * @default 388
+     */
+    width?: number;
+
+    /**
+     * Specifies the height of the panel in pixels. In most cases, this will be set
+     * by the PanelSet and should be treated as a read-only value.
+     *
+     * @default -1
+     */
+    height?: number;
+
+    /**
+     * Specifies the horizontal position of the panel relative to the left edge of the
+     * PanelSet (which is at the left edge of the display by default). In most cases,
+     * this should be set by setting the panelSize field to one of the pre-configured settings.
+     *
+     * @default 105
+     */
+    leftPosition?: number;
+
+    /**
+     * Provides information to the PanelSet that this Panel should never appear in the
+     * right position of the PanelSet. When the panels are sliding back towards the home
+     * position (as a result of a Left or Back key press), and the panel slides into the
+     * right position, the PanelSet initiates another slide in the same back direction
+     * so that the panel does not end up on the right.
+     *
+     * @default false
+     */
+    leftOnly?: boolean;
+
+    /**
+     * Provides information to the PanelSet as to whether or not this panel has another
+     * panel to its right. If set to true, the PanelSet's right arrow indicator is displayed
+     * and pressing the right arrow button on the remote triggers the PanelSet to move the
+     * focus one panel to the right, sliding the Panels as needed to make sure the panel
+     * that has the focus ends up onscreen. If set to false, the PanelSet's right arrow
+     * indicator is not displayed and the right arrow button does not trigger any change
+     * to the focused panel.
+     *
+     * @default false
+     */
+    hasNextPanel?: boolean;
+
+    /**
+     * Indicates that this panel should be the only panel displayed (i.e., it will take
+     * up both the left and right positions in the PanelSet).
+     *
+     * @default false
+     */
+    isFullScreen?: boolean;
+
+    /**
+     * Setting this field to a value greater than 1 causes the PanelSet to move the focus
+     * back that many panels when the user presses the left arrow button, sliding the
+     * Panels as needed to make sure the panel that has the focus ends up onscreen.
+     *
+     * @default 1
+     */
+    goBackCount?: number;
+
+    /**
+     * When set to true, pressing the OK/Select button on the remote control causes the
+     * PanelSet focus to move to the next panel.
+     *
+     * `ListPanel` may override this transiently. When its next panel is supplied
+     * asynchronously, the field is forced to false for the few milliseconds the previously
+     * built panel is still attached, then restored to the value it had when suppression
+     * began — so a change made to this prop during that window is not picked up.
+     *
+     * @default true
+     */
+    selectButtonMovesPanelForward?: boolean;
+
+    /**
+     * When the panel is used as part of the OverhangPanelSetScene, setting the overhangTitle
+     * field will cause that text to be displayed as the title in the overhang when the panel
+     * slides into the left position of the PanelSet.
+     *
+     * @default ""
+     */
+    overhangTitle?: string;
+
+    /**
+     * When the panel is used as part of the OverhangPanelSetScene, setting the clockText
+     * field will cause that text to be displayed instead of the clock in the overhang when
+     * the panel slides into the left position of the PanelSet.
+     *
+     * @default ""
+     */
+    clockText?: string;
+
+    /**
+     * When the panel is used as part of the OverhangPanelSetScene, setting optionsAvailable
+     * will enable/disable the options button handling when the panel slides into the left
+     * position of the PanelSet. The overhang's options prompt will change appearance to
+     * provide feedback to the user that the options button is enabled/disabled.
+     *
+     * @default false
+     */
+    optionsAvailable?: boolean;
+
+    /**
+     * Event handler called when the panel's offscreen left state changes.
+     * This field is set by the PanelSet to indicate that the panel is positioned offscreen
+     * of the left edge of the PanelSet. This field is often observed to cancel outstanding
+     * load requests for images that are displayed on the panel.
+     */
+    onIsOffscreenLeft?: EventHandler<boolean>;
+
+    /**
+     * Event handler called when the panel's left orientation changes.
+     * When the panel is used as part of the OverhangPanelSetScene, leftOrientation will be
+     * set to true when the panel moves into the left position of the PanelSet and set to
+     * false when the panel moves into the right position of the PanelSet.
+     */
+    onLeftOrientation?: EventHandler<boolean>;
+}

package/src/sg-nodes/panel.tsx

@@ -0,0 +1,56 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IPanelProps } from "./panel.props";
+import { Component } from "./types";
+export type { PanelSize, IPanelProps } from "./panel.props";
+
+/**
+ * Panel is a Group node subclass used to create sliding panels for app UI,
+ * similar to those in the Roku OS home screen.
+ *
+ * Panels provide a standardized way to create multi-level navigation screens where users
+ * can drill down through content. When used within a PanelSet, panels automatically handle
+ * sliding animations and focus management.
+ *
+ * The Panel component supports various size presets through the `panelSize` prop, or
+ * custom dimensions through `width` and `height` props. Navigation behavior can be
+ * customized through props like `hasNextPanel`, `leftOnly`, and `goBackCount`.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/panel}
+ * @see {@link https://developer.roku.com/dev/docs/sliding-panels-nodes Sliding Panels Overview}
+ *
+ * @example
+ * Basic panel usage:
+ * ```tsx
+ * <panel panelSize="medium">
+ *   <label text="Hello Panel" translation={[50, 50]} />
+ * </panel>
+ * ```
+ *
+ * @example
+ * Panel with navigation control:
+ * ```tsx
+ * <panel
+ *   panelSize="wide"
+ *   leftOnly={true}
+ *   hasNextPanel={true}
+ *   onIsOffscreenLeft={(isOffscreen) => {
+ *     console.log("Panel offscreen:", isOffscreen);
+ *   }}
+ * >
+ *   <markupList id="menuList" />
+ * </panel>
+ * ```
+ *
+ * @example
+ * Full screen panel:
+ * ```tsx
+ * <panel isFullScreen={true} hasNextPanel={false}>
+ *   {/* Full screen content *\/}
+ * </panel>
+ * ```
+ */
+export const Panel: Component<IPanelProps> = props => {
+    return <panel {...props}></panel>;
+};

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

@@ -0,0 +1,277 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IArrayGridProps } from "./array-grid";
+import type { PosterDisplayMode } from "./poster.props";
+import type { FontValue, HorizAlign, JSX, Uri, Vector2D, VertAlign } from "./types";
+
+/**
+ * Vertical alignment options for PosterGrid captions.
+ *
+ * Extends the standard vertical alignment with additional positioning options
+ * specific to captions relative to the poster.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/postergrid}
+ */
+export type CaptionVertAlignment = VertAlign | "above" | "below";
+
+/**
+ * Properties for the PosterGrid node.
+ *
+ * PosterGrid is a simple grid class that can be used to display two-dimensional grids of posters.
+ * In addition to the poster, each item in the grid can include up to two lines of captions.
+ *
+ * The number of columns in the PosterGrid is fixed and the number of rows varies. The items in the
+ * grid fill each row from left to right, then top to bottom.
+ *
+ * The layout of rows and columns in the grid is very flexible. Possible layouts include:
+ * - A simple layout with all posters in the grid having the same size
+ * - A layout with posters in some rows having varying heights and/or columns having varying widths
+ * - A layout with varying width rows and columns and items that occupy one or more rows and columns
+ *
+ * The grid items can be organized into sections that are demarcated by labelled horizontal
+ * divider lines between the sections.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/postergrid}
+ *
+ * @example Simple PosterGrid setup
+ * ```tsx
+ * <PosterGrid
+ *     basePosterSize={[240, 240]}
+ *     itemSpacing={[32, 32]}
+ *     caption1NumLines={1}
+ *     caption2NumLines={1}
+ *     numColumns={4}
+ *     numRows={3}
+ *     content={gridContent}
+ *     onItemSelected={(index) => handleSelection(index)}
+ * />
+ * ```
+ */
+export interface IPosterGridProps extends IArrayGridProps {
+    // ─────────────────────────────────────────────────────────────────────────
+    // Content Data
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies the content for the grid.
+     *
+     * Should be a ContentNode with child nodes for each item in the grid.
+     * If the data contains section markers, section dividers will be drawn between each section.
+     * These section dividers may contain an icon and/or a string.
+     *
+     * @see {@link https://developer.roku.com/dev/docs/postergrid#data-bindings | Data Bindings}
+     */
+    content: JSX.Element;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Poster Configuration
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies the width and height of the posters in the grid.
+     *
+     * For simple layouts, set this to the dimensions of each poster image.
+     * Can be overridden per-row with `rowHeights` or per-column with `columnWidths`.
+     *
+     * @default [0, 0]
+     * @example [240, 240]
+     */
+    basePosterSize?: Vector2D;
+
+    /**
+     * Enables a performance optimization when most poster items have the same size.
+     *
+     * When true, uses a texture atlas that stores the posters in the grid, providing
+     * rendering performance benefits for grids where most posters match `basePosterSize`.
+     *
+     * Set to false for grids with:
+     * - Complicated layouts with several posters differing from `basePosterSize`
+     * - Only a few large posters (5-8, or about quarter screen height/width)
+     *
+     * @default true
+     */
+    useAtlas?: boolean;
+
+    /**
+     * Provides automatic scaling of posters when `useAtlas` is set to false.
+     *
+     * If loading very large images (larger than UI resolution), you must set a scaling
+     * option other than `noScale`, otherwise the image may fail to load.
+     *
+     * - `noScale`: No scaling applied
+     * - `scaleToFit`: Scale to fit, preserving aspect ratio (letterboxing/pillarboxing)
+     * - `scaleToFill`: Stretch to fill, distorting if aspect ratios differ
+     * - `scaleToZoom`: Scale to fill, preserving aspect ratio but cropping
+     *
+     * @default "noScale"
+     */
+    posterDisplayMode?: PosterDisplayMode;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Loading State Bitmaps
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * 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 from the default.
+     */
+    imageWellBitmapUri?: Uri;
+
+    /**
+     * Specifies a bitmap file to display while a grid item's poster is loading.
+     *
+     * To execute a seamless cross-fade transition between posters, set this
+     * to the URI of the currently displayed poster.
+     */
+    loadingBitmapUri?: Uri;
+
+    /**
+     * Specifies an opacity value used to render the loading bitmap.
+     *
+     * @default 1.0
+     */
+    loadingBitmapOpacity?: number;
+
+    /**
+     * Specifies a bitmap file to display when a grid item poster fails to load.
+     */
+    failedBitmapUri?: Uri;
+
+    /**
+     * Specifies an opacity value used to render the failed bitmap.
+     *
+     * @default 1.0
+     */
+    failedBitmapOpacity?: number;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Caption Configuration
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies the font for the grid item first caption.
+     * Can be a SystemFont enum, registry font string, or Font component.
+     *
+     * @default system default
+     * @example
+     * ```tsx
+     * // Using SystemFont enum (recommended)
+     * caption1Font={SystemFont.Medium}
+     *
+     * // Using registry font string
+     * caption1Font="font:MediumSystemFont"
+     *
+     * // Using Font component for custom size
+     * caption1Font={<Font uri="pkg:/fonts/caption.ttf" size={20} />}
+     * ```
+     */
+    caption1Font?: FontValue;
+
+    /**
+     * Specifies the color for the grid item first caption.
+     *
+     * @default "0xddddddff"
+     */
+    caption1Color?: string;
+
+    /**
+     * Specifies the number of lines to render for the grid item first caption.
+     *
+     * Set to 0 to hide the first caption.
+     *
+     * @default 0
+     */
+    caption1NumLines?: number;
+
+    /**
+     * Specifies the font for the grid item second caption.
+     * Can be a SystemFont enum, registry font string, or Font component.
+     *
+     * @default system default
+     * @example
+     * ```tsx
+     * // Using SystemFont enum (recommended)
+     * caption2Font={SystemFont.Small}
+     *
+     * // Using registry font string
+     * caption2Font="font:SmallSystemFont"
+     *
+     * // Using Font component for custom size
+     * caption2Font={<Font uri="pkg:/fonts/caption.ttf" size={18} />}
+     * ```
+     */
+    caption2Font?: FontValue;
+
+    /**
+     * Specifies the color for the grid item second caption.
+     *
+     * @default "0xddddddff"
+     */
+    caption2Color?: string;
+
+    /**
+     * Specifies the number of lines to render for the grid item second caption.
+     *
+     * Set to 0 to hide the second caption.
+     *
+     * @default 0
+     */
+    caption2NumLines?: number;
+
+    /**
+     * Specifies a bitmap file to render as a background for the grid item captions.
+     */
+    captionBackgroundBitmapUri?: Uri;
+
+    /**
+     * Specifies the horizontal positioning of the grid item captions.
+     *
+     * - `left`: Left-justify the caption relative to the grid item poster
+     * - `center`: Center-justify the caption relative to the grid item poster
+     * - `right`: Right-justify the caption relative to the grid item poster
+     *
+     * Set `enableCaptionScrolling` to false to use `captionHorizAlignment`.
+     *
+     * @default "center"
+     */
+    captionHorizAlignment?: HorizAlign;
+
+    /**
+     * Specifies the vertical positioning of the grid item captions.
+     *
+     * - `above`: Position caption so bottom lies just above the poster
+     * - `top`: Align top of caption with top edge of poster
+     * - `center`: Align vertical center of caption with center of poster
+     * - `bottom`: Align bottom of caption with bottom edge of poster
+     * - `below`: Position caption so top lies just below the poster
+     *
+     * @default "below"
+     */
+    captionVertAlignment?: CaptionVertAlignment;
+
+    /**
+     * Specifies the spacing in pixels between lines of the caption.
+     *
+     * @default 0
+     */
+    captionLineSpacing?: number;
+
+    /**
+     * If a caption background is specified, this field specifies whether or not
+     * to display the caption background when the caption text is empty.
+     *
+     * @default true
+     */
+    showBackgroundForEmptyCaptions?: boolean;
+
+    /**
+     * Specifies whether or not to scroll single line captions when it is necessary
+     * to ellipsize the caption because it is wider than the column containing the grid item.
+     *
+     * @default true
+     */
+    enableCaptionScrolling?: boolean;
+}