@roku-sdk/components 0.0.0-stage → 2.19.0

package/src/sg-nodes/node.ts

@@ -0,0 +1,77 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { ComponentRef } from "@roku-sdk/interfaces";
+
+import { EventHandler, JSX } from "./types";
+
+/**
+ * Properties handled by the SolidJS framework layer.
+ * These are intercepted and never sent to SceneGraph as properties.
+ */
+export interface IFrameworkProps {
+    /**
+     * Reference to the component for imperative operations like focus()
+     *
+     * @example
+     * // Example from focusable-group-basic.tsx
+     * let buttonRef: ComponentRef<IButtonProps> | undefined;
+     *
+     * <Button ref={buttonRef} ... />
+     *
+     * // Later, imperatively call focus
+     * buttonRef?.focus();
+     */
+    ref?: ComponentRef<this> | ((ref: ComponentRef<this>) => void);
+
+    /** Declarative focus control - triggers focus on render */
+    gainFocus?: boolean;
+
+    /** Child elements - handled by renderer's tree manipulation, not sent as a property */
+    children?: JSX.Element;
+}
+
+export interface IBaseNodeProps {
+    /**
+     * Allows the node to be identified by SceneGraph. The value is also supplied as the parameter
+     * to certain event handlers (like onFocusedChild).
+     */
+    id?: string;
+
+    /** Provides a hint as to whether or not this node can take the key focus. */
+    focusable?: boolean;
+
+    /**
+     * Event handler called when a child node gains or loses focus.
+     * When focus is gained, the parameter is the child's `id`, or `""` if the child has no id.
+     * When focus is lost, the parameter is `null`.
+     *
+     * @param focusedChildId - The id of the child that gained focus, `""` if it has no id, or `null` when focus is lost
+     *
+     * @example
+     * const handleButtonFocused = (focusedChildId: string | null) => {
+     *     if (focusedChildId === null) {
+     *         console.log("Button lost focus");
+     *     } else if (focusedChildId === "") {
+     *         console.log("Unidentified child gained focus");
+     *     } else {
+     *         console.log(`Button Focused Id: ${focusedChildId}`);
+     *     }
+     * };
+     *
+     * <FocusableGroup onFocusedChild={handleButtonFocused}>
+     *     <Button id="button0" text="Button 0" />
+     * </FocusableGroup>
+     */
+    onFocusedChild?: EventHandler<string | null>;
+}
+
+/**
+ * Base properties for all SceneGraph nodes.
+ *
+ * Node is the abstract base class for all SceneGraph nodes. It provides fundamental properties
+ * and functionality that all nodes inherit, including identification, focus management, and event handling.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/node}
+ */
+export interface INodeProps extends IFrameworkProps, IBaseNodeProps {}

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

@@ -0,0 +1,169 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { Uri } from "../types";
+import type { IGroupProps } from "./group.props";
+
+/**
+ * Properties for the Overhang node.
+ *
+ * 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.
+ *
+ * @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 interface IOverhangProps extends IGroupProps {
+    /**
+     * Fills the overhang area with the specified color.
+     * If both `color` and `backgroundUri` are set, the last one set is used.
+     * @default 0x232323ff
+     */
+    color?: string;
+
+    /**
+     * Specifies the URI of a bitmap to be used to fill the overhang area.
+     * If both `color` and `backgroundUri` are set, the last one set is used.
+     * @default ""
+     */
+    backgroundUri?: Uri;
+
+    /**
+     * Specifies the URI of a bitmap to be drawn on the left side of the overhang area.
+     * If both `logoUri` and `title` are set, the logo will appear to the left of the
+     * title, with an optional divider bitmap between them.
+     * @default ""
+     */
+    logoUri?: Uri;
+
+    /**
+     * Specifies an adjustment to the vertical position of the logo to allow
+     * alignment of the logo relative to the baseline of the options prompt.
+     * @default 0
+     */
+    logoBaselineOffset?: number;
+
+    /**
+     * Specifies a text string to be displayed on the left side of the overhang area,
+     * to the right of the logo if `logoUri` is also specified.
+     * @default ""
+     */
+    title?: string;
+
+    /**
+     * Specifies the color of the title text.
+     * @default 0xddddddff
+     */
+    titleColor?: string;
+
+    /**
+     * Controls whether or not a clock is displayed on the right side of the overhang.
+     * The default value is based on the device clock format setting.
+     */
+    showClock?: boolean;
+
+    /**
+     * Specifies the color of the clock text.
+     * @default 0xddddddff
+     */
+    clockColor?: string;
+
+    /**
+     * Specifies an alternate string to be displayed in the location of the clock.
+     * If set to a non-empty string, the specified string is displayed in place of
+     * the clock. If set to an empty string, the clock is restored.
+     * @default ""
+     */
+    clockText?: string;
+
+    /**
+     * Controls whether or not the options prompt is displayed on the right side
+     * of the overhang. Note that `optionsAvailable` must also be set to true for
+     * the options prompt to be displayed.
+     * @default false
+     */
+    showOptions?: boolean;
+
+    /**
+     * Specifies the color of the options indicator when options are available.
+     * @default 0xddddddff
+     */
+    optionsColor?: string;
+
+    /**
+     * Specifies the color of the options indicator when options are not available.
+     * @default 0xdddddd44
+     */
+    optionsDimColor?: string;
+
+    /**
+     * Specifies the tint color to be applied to the options icon when options are available.
+     * @default 0xffffffff
+     */
+    optionsIconColor?: string;
+
+    /**
+     * Specifies the tint color to be applied to the options icon when options are not available.
+     * @default 0xffffffff
+     */
+    optionsIconDimColor?: string;
+
+    /**
+     * Specifies whether or not the Options remote key is currently available.
+     * When true and `showOptions` is also true, the options prompt is displayed.
+     * @default false
+     */
+    optionsAvailable?: boolean;
+
+    /**
+     * Specifies the text to be displayed next to the Options (*) symbol.
+     * @default ""
+     */
+    optionsText?: string;
+
+    /**
+     * Specifies the maximum width to which the `optionsText` text will be ellipsized.
+     * A value of 0.0 indicates no width restriction.
+     * @default 0.0
+     */
+    optionsMaxWidth?: number;
+
+    /**
+     * Specifies the URI of a bitmap to be used as a divider between the logo and the title.
+     * @default ""
+     */
+    leftDividerUri?: Uri;
+
+    /**
+     * Specifies the vertical offset of the left divider position.
+     * @default 0
+     */
+    leftDividerVertOffset?: number;
+
+    /**
+     * Specifies the URI of a bitmap to be used as a divider between the clock and options prompt.
+     * @default ""
+     */
+    rightDividerUri?: Uri;
+
+    /**
+     * Specifies the vertical offset of the right divider position.
+     * @default 0
+     */
+    rightDividerVertOffset?: number;
+
+    /**
+     * Specifies the height of the Overhang region.
+     * @default 115
+     */
+    height?: number;
+}

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 2.0 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>;
+};