@roku-sdk/components 0.0.0-stage → 2.18.0

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

@@ -0,0 +1,45 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IPosterGridProps } from "./poster-grid.props";
+import { Component } from "./types";
+export type { CaptionVertAlignment, IPosterGridProps } from "./poster-grid.props";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Caption Vertical Alignment Type
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PosterGrid Properties
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PosterGrid Component
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 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.
+ *
+ * @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 const PosterGrid: Component<IPosterGridProps> = props => {
+    return <posterGrid {...props}></posterGrid>;
+};

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

@@ -0,0 +1,125 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./group.props";
+import type { EventHandler, JSX, ResType, Uri } from "./types";
+
+export type PosterDisplayMode = "noScale" | "scaleToFit" | "scaleToFill" | "scaleToZoom";
+
+export type LoadDisplayMode = PosterDisplayMode | "limitSize";
+
+export type PosterLoadStatus = "none" | "loading" | "ready" | "failed";
+
+export interface BitmapMargins {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+
+/**
+ * Properties for the Poster node.
+ *
+ * Poster is a renderable node that displays bitmap images. It is one of the most widely used nodes
+ * in SceneGraph applications for displaying images, thumbnails, and graphics with support for scaling,
+ * loading states, and fallback images.
+ *
+ * Images can be imported directly in TypeScript, which provides automatic resolution handling and
+ * dimension information. See the Static Image Management documentation for details.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/poster}
+ * @see **Static Image Management** at documentation/guides/images/static-image-management.md for image import details
+ *
+ * @example
+ * // Import image with resolution substitutes
+ * import { uri as logo } from "./images/logo-*.png";
+ * <Poster width={200} height={100} uri={logo} />
+ *
+ * @example
+ * // Use static URI path
+ * <Poster width={1920} height={1080} uri="pkg:/images/background.jpg" />
+ */
+export interface IPosterProps extends IGroupProps {
+    /**
+     * Specifies the width of the poster bitmap in local coordinates.
+     * If set to 0.0, the width of the bitmap from the image file is used.
+     * If set to a value greater than 0.0, the bitmap is scaled to that width.
+     */
+    width?: ResType<number>;
+    /**
+     * Specifies the height of the poster bitmap in local coordinates.
+     * If set to 0.0, the height of the bitmap from the image file is used.
+     * If set to a value greater than 0.0, the bitmap is scaled to that height.
+     */
+    height?: ResType<number>;
+    /**
+     * Controls whether the image is loaded synchronously or asynchronously.
+     * If true and the uri specifies a local file (pkg:/images), the image loads synchronously and appears immediately.
+     * If false, or if the uri specifies a remote URL (http/https), the image loads asynchronously in a background thread.
+     * Be careful when setting to true as it might cause brief glitches in rendering.
+     */
+    loadSync?: boolean;
+    /** Specifies the width of the bitmap to be loaded. Used for scaling during load. */
+    loadWidth?: ResType<number>;
+    /** Specifies the height of the bitmap to be loaded. Used for scaling during load. */
+    loadHeight?: ResType<number>;
+    /**
+     * Specifies how the bitmap should be scaled to fit the poster dimensions.
+     * - "noScale": Bitmap loaded at original resolution. If Poster's width/height differ, it will be scaled to fill (aspect ratio not preserved)
+     * - "scaleToFit": Scale to fit within dimensions, preserving aspect ratio with letterboxing/pillarboxing
+     * - "scaleToFill": Stretch to fill dimensions, distorting if aspect ratios differ
+     * - "scaleToZoom": Scale to fill dimensions, preserving aspect ratio but cropping parts of the image
+     * - "limitSize": Scale while loading so max width/height doesn't exceed loadWidth/loadHeight, preserving aspect ratio
+     */
+    loadDisplayMode?: LoadDisplayMode;
+    /** Color value to blend with the bitmap. */
+    blendColor?: string;
+    /** URI of the bitmap to display while the main image is loading. */
+    loadingBitmapUri?: Uri;
+    /** Opacity of the loading bitmap (0.0 to 1.0). */
+    loadingBitmapOpacity?: number;
+    /** URI of the bitmap to display if the main image fails to load. */
+    failedBitmapUri?: Uri;
+    /** Opacity of the failed bitmap (0.0 to 1.0). */
+    failedBitmapOpacity?: number;
+    /** Text to be spoken by the audio guide for accessibility. */
+    audioGuideText?: string;
+    /**
+     * Event handler called when the load status changes.
+     * - "none": No load operation in progress
+     * - "loading": Image is currently loading
+     * - "ready": Image loaded successfully
+     * - "failed": Image failed to load
+     */
+    onLoadStatus?: EventHandler<PosterLoadStatus>;
+    /** Event handler called when the bitmap width is determined. Provides the actual width of the loaded bitmap. */
+    onBitmapWidth?: EventHandler<number>;
+    /** Event handler called when the bitmap height is determined. Provides the actual height of the loaded bitmap. */
+    onBitmapHeight?: EventHandler<number>;
+    /** Event handler called when bitmap margins are determined. Provides margin information for 9-patch images. */
+    onBitmapMargins?: EventHandler<BitmapMargins>;
+    /**
+     * Specifies the URI of the bitmap image file to be displayed.
+     * Can use static paths (e.g., "pkg:/images/icon.png") or imported URIs from TypeScript.
+     * Images included as part of the application package can be referenced using the pkg:/images prefix.
+     *
+     * **Important**: Set `uri` as the last property in your JSX to avoid timing issues. If the image is
+     * already cached or loads quickly from local storage, it may render before other properties
+     * (such as `loadDisplayMode` or event handlers) are applied. Placing `uri` last ensures all
+     * configuration properties are set before the image loading process begins.
+     */
+    uri?: Uri;
+    /**
+     * An Effect node to apply shader-based rendering (rounded corners, borders, gradients).
+     * On platforms that do not support effects, this is silently ignored.
+     */
+    effect?: JSX.Element;
+    /**
+     * If true, requests that the bitmap is loaded in a format that can be used with shaders, which
+     * includes any poster that will have an Effect node attached.
+     * Note that setting this to false does not guarantee that the resulting poster cannot be used
+     * with Effects.
+     * @default false
+     */
+    shaderCompatible?: boolean;
+}

package/src/sg-nodes/poster.tsx

@@ -0,0 +1,44 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IPosterProps } from "./poster.props";
+import { Component } from "./types";
+export type { PosterDisplayMode, LoadDisplayMode, PosterLoadStatus, BitmapMargins, IPosterProps } from "./poster.props";
+
+/**
+ * Poster is a renderable node that displays bitmap images. It is one of the most widely used nodes
+ * in SceneGraph applications for displaying images, thumbnails, and graphics with support for scaling,
+ * loading states, and fallback images.
+ *
+ * Images can be imported directly in TypeScript, which provides automatic resolution handling and
+ * dimension information. See the Static Image Management documentation for details.
+ *
+ * **Attribute ordering pitfall:** When using `<poster>` as a JSX intrinsic,
+ * write event handlers (`onLoadStatus`, etc.) **before** `uri` and other props that trigger
+ * synchronous events on assignment. If `uri` is set first and the image is already cached,
+ * the load event fires before your handler is registered and is silently dropped.
+ * Writing handlers first is good practice regardless.
+ *
+ * ```tsx
+ * // Wrong: onLoadStatus may be missed if image is cached
+ * <poster uri={src} onLoadStatus={handleLoad} />
+ *
+ * // Correct: handler registered before the prop that fires it
+ * <poster onLoadStatus={handleLoad} uri={src} />
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/poster}
+ * @see **Static Image Management** at documentation/guides/images/static-image-management.md for image import details
+ *
+ * @example
+ * // Import image with resolution substitutes - note uri is last
+ * import { uri as logo } from "./images/logo-*.png";
+ * <poster width={200} height={100} uri={logo} />
+ *
+ * @example
+ * // Use static URI path - note uri is last
+ * <poster width={1920} height={1080} uri="pkg:/images/background.jpg" />
+ */
+export const Poster: Component<IPosterProps> = props => {
+    return <poster {...props}></poster>;
+};

package/src/sg-nodes/radio-button-list.props.ts

@@ -0,0 +1,59 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { ILabelListProps } from "./label-list.props";
+import type { JSX, Uri } from "./types";
+
+/**
+ * Properties for the RadioButtonList component.
+ *
+ * Extends {@link ILabelListProps} with single-selection radio button state
+ * management and custom radio icon options.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/radiobuttonlist}
+ */
+export interface IRadioButtonListProps extends ILabelListProps {
+    /**
+     * The data model for the list. Should be a ContentNode with child
+     * ContentNodes, one for each item in the list.
+     */
+    content: JSX.Element;
+
+    /**
+     * Specifies the index of the currently selected (checked) radio button item.
+     * Only one item can be selected at a time.
+     *
+     * Set to `-1` to indicate no item is selected.
+     *
+     * @default -1
+     */
+    checkedItem?: number;
+
+    /**
+     * Controls whether pressing OK automatically sets `checkedItem` to the
+     * focused item index.
+     *
+     * When `false`, developer must manage selection manually via `checkedItem`.
+     *
+     * @default true
+     */
+    checkOnSelect?: boolean;
+
+    /**
+     * URI for the radio button icon when item is selected and not focused.
+     * Typically shows a filled circle indicator.
+     * Only set to specify a custom bitmap different from default.
+     *
+     * @example "pkg:/images/radio-checked.png"
+     */
+    checkedIconUri?: Uri;
+
+    /**
+     * URI for the radio button icon when item is selected and has focus.
+     * Typically shows a filled circle indicator with focus highlight.
+     * Only set to specify a custom bitmap different from default.
+     *
+     * @example "pkg:/images/radio-checked-focused.png"
+     */
+    focusedCheckedIconUri?: Uri;
+}

package/src/sg-nodes/radio-button-list.tsx

@@ -0,0 +1,68 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IRadioButtonListProps } from "./radio-button-list.props";
+import { Component } from "./types";
+export type { IRadioButtonListProps } from "./radio-button-list.props";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// RadioButtonList Properties
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * RadioButtonList displays a list of items with radio buttons for single selection.
+ *
+ * Each item shows a text string and a radio button icon positioned to the left.
+ * Unlike CheckList which allows multiple selections, RadioButtonList enforces
+ * single selection - selecting one item automatically deselects the previous.
+ *
+ * ## Data Binding
+ *
+ * The `content` field should be set to a ContentNode with one child ContentNode
+ * for each item. Each child ContentNode should have a `TITLE` attribute (string)
+ * that specifies the label text for that item.
+ *
+ * ```tsx
+ * <contentNode>
+ *     <contentNode title="Option A" />
+ *     <contentNode title="Option B" />
+ *     <contentNode title="Option C" />
+ * </contentNode>
+ * ```
+ *
+ * @example Basic usage
+ * ```tsx
+ * <radioButtonList
+ *     itemSize={[440, 48]}
+ *     checkedItem={0}
+ *     checkOnSelect={true}
+ *     content={
+ *         <contentNode>
+ *             <contentNode title="Low Quality" />
+ *             <contentNode title="Medium Quality" />
+ *             <contentNode title="High Quality" />
+ *         </contentNode>
+ *     }
+ * />
+ * ```
+ *
+ * @example With custom icons
+ * ```tsx
+ * <radioButtonList
+ *     itemSize={[440, 48]}
+ *     checkedIconUri="pkg:/images/radio-on.png"
+ *     focusedCheckedIconUri="pkg:/images/radio-on-focused.png"
+ *     content={
+ *         <contentNode>
+ *             <contentNode title="English" />
+ *             <contentNode title="Spanish" />
+ *         </contentNode>
+ *     }
+ * />
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/radiobuttonlist}
+ */
+export const RadioButtonList: Component<IRadioButtonListProps> = props => {
+    return <radioButtonList {...props}></radioButtonList>;
+};

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

@@ -0,0 +1,29 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./group.props";
+import type { JSX, ResType } from "./types";
+
+/**
+ * Properties for the Rectangle node.
+ *
+ * Rectangle is a renderable node that draws a solid colored rectangle. It is one of the three
+ * basic renderable nodes in SceneGraph and is commonly used for backgrounds, borders, and simple UI elements.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/rectangle}
+ */
+export interface IRectangleProps extends IGroupProps {
+    /** Specifies the width of the rectangle in local coordinates. @default 0.0 */
+    width?: ResType<number>;
+    /** Specifies the height of rectangle in local coordinates. @default 0.0 */
+    height?: ResType<number>;
+    /** Specifies the color of the rectangle (string containing hex value e.g. RGBA). @default "0xFFFFFFFF" */
+    color?: string;
+    /** Specifies if the rectangle should be alpha blended with the nodes that are behind it. @default true */
+    blendingEnabled?: boolean;
+    /**
+     * An Effect node to apply shader-based rendering (rounded corners, borders, gradients).
+     * On platforms that do not support effects, this is silently ignored.
+     */
+    effect?: JSX.Element;
+}

package/src/sg-nodes/rectangle.tsx

@@ -0,0 +1,27 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IRectangleProps } from "./rectangle.props";
+import { Component } from "./types";
+export type { IRectangleProps } from "./rectangle.props";
+
+/**
+ * Rectangle component for rendering solid colored rectangles.
+ *
+ * Rectangle is a renderable node that draws a solid colored rectangle. It is one of the three
+ * basic renderable nodes in SceneGraph and is commonly used for backgrounds, borders, and simple UI elements.
+ *
+ * @example
+ * ```tsx
+ * <rectangle
+ *     width={400}
+ *     height={200}
+ *     color="#FF0000FF"
+ * />
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/rectangle}
+ */
+export const Rectangle: Component<IRectangleProps> = props => {
+    return <rectangle {...props}></rectangle>;
+};