@roku-sdk/components 0.0.0-stage → 2.18.0

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

@@ -0,0 +1,288 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IArrayGridProps, VertFocusAnimationStyle } from "./array-grid";
+import type { EventHandler, JSX, Uri, Vector2D } from "./types";
+
+/**
+ * A tuple of `[rowIndex, itemIndex]` identifying a specific item within a RowList.
+ */
+export type RowItemPosition = [number, number];
+
+/**
+ * Event handler for RowList item events, receiving the `[rowIndex, itemIndex]`
+ * of the item that triggered the event.
+ */
+export type RowListItemEventHandler = EventHandler<RowItemPosition>;
+
+/**
+ * Properties for the RowList node.
+ *
+ * RowList displays a vertical list of rows, where each row scrolls horizontally
+ * through its items. The content of each item is rendered by a compiled component
+ * specified via `itemComponentName`. Row titles can also be rendered by a compiled
+ * component via `rowTitleComponentName`.
+ *
+ * Each row's size, spacing, label visibility, and focus animation can be
+ * configured independently using per-row array fields.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/rowlist}
+ *
+ * @example
+ * ```tsx
+ * // Register compiled components by importing their XML files
+ * import "./compiled-components/MyRowItem.xml";
+ * import "./compiled-components/MyRowTitle.xml";
+ *
+ * <RowList
+ *     itemComponentName="MyRowItem"
+ *     rowTitleComponentName="MyRowTitle"
+ *     itemSize={[1920, 200]}
+ *     rowItemSize={[[300, 160]]}
+ *     numRows={4}
+ *     content={listContent}
+ *     onRowItemFocused={([row, col]) => setFocus(row, col)}
+ *     onRowItemSelected={([row, col]) => navigate(row, col)}
+ * />
+ * ```
+ */
+export interface IRowListProps extends IArrayGridProps {
+    // ─────────────────────────────────────────────────────────────────────────
+    // Content
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies the content for the RowList.
+     *
+     * The root `ContentNode` should have one child per row. Each row child should
+     * have one child `ContentNode` per item in that row.
+     *
+     * @see {@link https://developer.roku.com/dev/docs/rowlist | RowList content}
+     */
+    content: JSX.Element;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Item Components
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies the name of the compiled component used to render each row item.
+     *
+     * Register the compiled component by importing its XML file before use:
+     * ```ts
+     * import "./compiled-components/MyRowItem.xml";
+     * ```
+     *
+     * The compiled component may define interface fields that RowList will
+     * automatically update: `width`, `height`, `index`, `listHasFocus`,
+     * `itemContent`, `focusPercent`, and `itemHasFocus`.
+     *
+     * @example "MyRowItem"
+     * @see {@link https://developer.roku.com/dev/docs/rowlist | RowList itemComponentName}
+     */
+    itemComponentName?: string;
+
+    /**
+     * Specifies the name of the compiled component used to render row titles,
+     * replacing the default text row label.
+     *
+     * Register the compiled component by importing its XML file before use:
+     * ```ts
+     * import "./compiled-components/MyRowTitle.xml";
+     * ```
+     *
+     * @example "MyRowTitle"
+     */
+    rowTitleComponentName?: string;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Row Layout
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies the width and height of items in each row.
+     *
+     * Each element corresponds to a row. If the array has fewer elements than
+     * the number of rows, the last value is repeated for the remaining rows.
+     *
+     * @example [[300, 160], [200, 120]]
+     */
+    rowItemSize?: Vector2D[];
+
+    /**
+     * Specifies the horizontal spacing between items in each row.
+     *
+     * Each element corresponds to a row. If the array has fewer elements than
+     * the number of rows, the last value is repeated.
+     *
+     * @example [[20, 0]]
+     */
+    rowItemSpacing?: Vector2D[];
+
+    /**
+     * Specifies the X-offset from the left edge to the first fully visible item
+     * for each row when that row has focus.
+     *
+     * @example [40, 40]
+     */
+    focusXOffset?: number[];
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Row Labels
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies the offset of the row label for each row.
+     *
+     * The x-value is the horizontal offset; the y-value is the vertical spacing
+     * between the label and the row items.
+     *
+     * @default [[0, 0]]
+     */
+    rowLabelOffset?: Vector2D[];
+
+    /**
+     * Controls whether the left-edge row label is shown for each row.
+     *
+     * @example [true, false, true]
+     */
+    showRowLabel?: boolean[];
+
+    /**
+     * Controls whether the "item N of M" counter is shown for each row.
+     * The counter is only displayed on the focused row.
+     *
+     * @example [true, true]
+     */
+    showRowCounter?: boolean[];
+
+    /**
+     * When `true` for a row, appends "+" to the total item count in that row's
+     * counter, indicating the count may be indefinite.
+     *
+     * @example [false, true]
+     */
+    indefiniteRowItemCount?: boolean[];
+
+    /**
+     * When `true` for a row, enables variable-width items for that row.
+     * Only supported with `rowFocusAnimationStyle` set to `fixedFocusWrap`.
+     *
+     * Item widths are read from `SDItemWidth`, `HDItemWidth`, or `FHDItemWidth`
+     * attributes on each item's ContentNode.
+     *
+     * @example [false, true]
+     */
+    variableWidthItems?: boolean[];
+
+    /**
+     * Specifies the horizontal focus movement animation style for all rows.
+     *
+     * - `floatingFocus`: focus indicator moves with the focused item
+     * - `fixedFocusWrap`: focus stays fixed; items wrap around
+     * - `fixedFocus`: focus stays fixed; items scroll without wrapping
+     *
+     * @default "floatingFocus"
+     * @see {@link https://developer.roku.com/dev/docs/rowlist | RowList rowFocusAnimationStyle}
+     */
+    rowFocusAnimationStyle?: VertFocusAnimationStyle | `${VertFocusAnimationStyle}`;
+
+    /**
+     * Specifies the color of row and counter labels.
+     *
+     * @default "0xffffffff"
+     * @example "0xddddddff"
+     */
+    rowLabelColor?: string;
+
+    /**
+     * Specifies the font for row and counter labels.
+     *
+     * @default system default
+     */
+    rowLabelFont?: string;
+
+    /**
+     * Specifies the offset of the right edge of the row counter relative to the
+     * right edge of the clipping rectangle.
+     */
+    rowCounterRightOffset?: number;
+
+    /**
+     * When `false`, the row counter is hidden for rows where all items fit
+     * on screen at once.
+     *
+     * @default true
+     */
+    showRowCounterForShortRows?: boolean;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Bitmaps
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies the bitmap file to display as a placeholder where images would
+     * appear in empty rows.
+     *
+     * Only set to specify a custom bitmap that differs from the default.
+     *
+     * @example "pkg:/images/image-well.png"
+     */
+    imageWellBitmapUri?: Uri;
+
+    /**
+     * Specifies the bitmap file shown while a row item's image is loading.
+     *
+     * @example "pkg:/images/loading.png"
+     */
+    loadingBitmapUri?: Uri;
+
+    /**
+     * Specifies the opacity of the loading bitmap.
+     *
+     * @default 1.0
+     */
+    loadingBitmapOpacity?: number;
+
+    /**
+     * Specifies the bitmap file shown when a row item's image fails to load.
+     *
+     * @example "pkg:/images/error.png"
+     */
+    failedBitmapUri?: Uri;
+
+    /**
+     * Specifies the opacity of the failed bitmap.
+     *
+     * @default 1.0
+     */
+    failedBitmapOpacity?: number;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Navigation
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * When set to a valid `[rowIndex, itemIndex]`, immediately moves focus to
+     * the specified item without animation.
+     *
+     * @example [2, 0]
+     */
+    jumpToRowItem?: RowItemPosition;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Events
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Fired when a row item is selected (OK pressed).
+     * Receives `[rowIndex, itemIndex]` of the selected item.
+     */
+    onRowItemSelected?: RowListItemEventHandler;
+
+    /**
+     * Fired when a row item gains focus.
+     * Receives `[rowIndex, itemIndex]` of the newly focused item.
+     */
+    onRowItemFocused?: RowListItemEventHandler;
+}

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

@@ -0,0 +1,47 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IRowListProps } from "./row-list.props";
+import { Component } from "./types";
+export type { RowItemPosition, RowListItemEventHandler, IRowListProps } from "./row-list.props";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// RowList Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ─────────────────────────────────────────────────────────────────────────────
+// RowList Properties
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * RowList displays a vertical list of rows, where each row scrolls horizontally
+ * through its items. Item rendering is delegated to compiled components specified
+ * by `itemComponentName`.
+ *
+ * Each row can have independent size, spacing, label, counter, and focus behavior
+ * via per-row array fields. Row titles can be rendered by a separate compiled
+ * component via `rowTitleComponentName`.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/rowlist}
+ *
+ * @example
+ * ```tsx
+ * // Register compiled components by importing their XML files
+ * import "./compiled-components/MyRowItem.xml";
+ *
+ * <rowList
+ *     itemComponentName="MyRowItem"
+ *     itemSize={[1920, 200]}
+ *     rowItemSize={[[300, 160]]}
+ *     numRows={4}
+ *     showRowLabel={[true]}
+ *     rowLabelColor="0xffffffff"
+ *     content={listContent}
+ *     onRowItemFocused={([row, col]) => setFocus(row, col)}
+ *     onRowItemSelected={([row, col]) => navigate(row, col)}
+ * />
+ * ```
+ */
+export const RowList: Component<IRowListProps> = props => {
+    return <rowList {...props}></rowList>;
+};

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

@@ -0,0 +1,65 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./group.props";
+import type { EventHandler, JSX, Uri } from "./types";
+
+/**
+ * Represents the current design resolution of the scene.
+ */
+export interface DesignResolution {
+    /** The width of the design resolution in pixels. */
+    width: number;
+    /** The height of the design resolution in pixels. */
+    height: number;
+    /** The resolution mode. */
+    resolution: "HD" | "FHD" | "SD";
+}
+
+/**
+ * Properties for the Scene node.
+ *
+ * Scene is the root node of a SceneGraph application. Every roSGScreen object must have
+ * exactly one Scene node as its root. The Scene node provides background rendering,
+ * dialog management, and design resolution information.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/scene}
+ */
+export interface ISceneProps extends IGroupProps {
+    /** Specifies a graphic image file to be used for the Scene node background. */
+    backgroundURI?: Uri;
+    /**
+     * If true, the backgroundURI image is limited to the current screen size after being loaded.
+     * If false, no scaling is applied.
+     * @default true
+     */
+    limitBackgroundToUIResolution?: boolean;
+    /**
+     * Specifies a background color for the scene as a hex string (e.g., "0x000000FF").
+     * Only used if backgroundURI is set to an empty string.
+     * @default "0x000000FF"
+     */
+    backgroundColor?: string;
+    /**
+     * If true, a Back key press causes the scene to exit.
+     * If false, Back key doesn't exit the scene.
+     * Requires focus to be set on the scene or a child node.
+     * @default true
+     */
+    backExitsScene?: boolean;
+    /**
+     * Setting this field to a node extended from Dialog causes the dialog to be displayed.
+     * Set to invalid to dismiss the dialog.
+     */
+    dialog?: JSX.Element;
+    /**
+     * Defines the default color palette used by nodes that have a palette field,
+     * such as standard dialogs and keyboards.
+     */
+    palette?: JSX.Element;
+    /**
+     * Event fired when the current design resolution changes.
+     * Returns the width, height, and resolution mode ("HD", "FHD", or "SD").
+     */
+    onCurrentDesignResolution?: EventHandler<DesignResolution>;
+}

package/src/sg-nodes/scene.tsx

@@ -0,0 +1,15 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { ISceneProps } from "./scene.props";
+import { Component } from "./types";
+export type { DesignResolution, ISceneProps } from "./scene.props";
+
+/**
+ * Scene component - the root node of a SceneGraph application.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/scene}
+ */
+export const Scene: Component<ISceneProps> = props => {
+    return <scene {...props}></scene>;
+};

package/src/sg-nodes/scrollable-text.props.ts

@@ -0,0 +1,133 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./group.props";
+import type { FontValue, HorizAlign, Uri, VertAlign } from "./types";
+
+/**
+ * Properties for the ScrollableText node.
+ *
+ * ScrollableText provides an interactive, vertically scrolling pane of text.
+ * This is typically used to display several paragraphs of text that are too
+ * long to fit onto the display, such as license agreements or detailed descriptions.
+ *
+ * **Key Features:**
+ * - Automatic scrollbar when text exceeds the specified height
+ * - User can scroll using remote's up/down arrow keys
+ * - Customizable scrollbar appearance
+ * - Text alignment control (horizontal and vertical)
+ *
+ * @extends Group
+ * @see {@link https://developer.roku.com/dev/docs/scrollabletext}
+ *
+ * @example
+ * <ScrollableText
+ *     text="Long text content here..."
+ *     width={800}
+ *     height={400}
+ *     font={SystemFont.Medium}
+ * />
+ */
+export interface IScrollableTextProps extends IGroupProps {
+    /**
+     * Specifies the text to be displayed.
+     *
+     * @default ""
+     */
+    text?: string;
+
+    /**
+     * Specifies the text color as a hex value (e.g., `0xRRGGBBAA` or `#RRGGBBAA`).
+     *
+     * @default 0xddddddff
+     */
+    color?: string;
+
+    /**
+     * Specifies the Font node to be used for rendering the text.
+     * Can be a system font enum value or a custom font URI string.
+     *
+     * @example
+     * // Using system font
+     * font={SystemFont.Medium}
+     *
+     * @example
+     * // Using custom font URI
+     * font="pkg:/fonts/custom.ttf"
+     *
+     * @default system default font
+     */
+    font?: FontValue;
+
+    /**
+     * Specifies the width of the node in local coordinates.
+     * This includes both the area where the text is rendered and the
+     * scrollbar on the right.
+     *
+     * @default 0.0
+     */
+    width?: number;
+
+    /**
+     * Specifies the height of the node in local coordinates.
+     * If the text to be displayed is larger than this height, a scrollbar
+     * is automatically added on the right, allowing users to scroll up and
+     * down using the remote's arrow keys.
+     *
+     * @default 0.0
+     */
+    height?: number;
+
+    /**
+     * If the text is displayed on more than one line, specifies the amount
+     * of additional space added between lines (in pixels).
+     *
+     * @default 8
+     */
+    lineSpacing?: number;
+
+    /**
+     * Specifies the horizontal alignment of the text within the computed width.
+     * The computed width is the `width` field value minus the scrollbar width.
+     *
+     * - `"left"`: Left edge of text is drawn at x=0
+     * - `"center"`: Horizontal center of each line is at half the computed width
+     * - `"right"`: Right edge of each line is at the computed width
+     *
+     * In most cases, this should remain set to `"left"`.
+     *
+     * @default "left"
+     */
+    horizAlign?: HorizAlign;
+
+    /**
+     * Specifies the vertical alignment of the text within the specified height.
+     *
+     * - `"top"`: Top edge of text is drawn at y=0
+     * - `"center"`: Vertical center of text is at half the height
+     * - `"bottom"`: Bottom edge of text is at the height
+     *
+     * In most cases, this should remain set to `"top"`.
+     *
+     * @default "top"
+     */
+    vertAlign?: VertAlign;
+
+    /**
+     * Specifies the URI of an image file to replace the default scrollbar track.
+     * This should be a 9-patch image so that it can be stretched to the
+     * appropriate height specified by the `height` field.
+     *
+     * @default ""
+     */
+    scrollbarTrackBitmapUri?: Uri;
+
+    /**
+     * Specifies the URI of an image file to replace the default scrollbar thumb.
+     * This should be a 9-patch image so that it can be stretched to the
+     * appropriate size based on content length.
+     *
+     * @default ""
+     */
+    scrollbarThumbBitmapUri?: Uri;
+}

package/src/sg-nodes/scrollable-text.tsx

@@ -0,0 +1,64 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IScrollableTextProps } from "./scrollable-text.props";
+import { Component } from "./types";
+export type { IScrollableTextProps } from "./scrollable-text.props";
+
+/**
+ * ScrollableText component for displaying vertically scrolling text content.
+ *
+ * Use ScrollableText when you need to display large amounts of text that may
+ * not fit within the visible area, such as:
+ * - License agreements
+ * - Terms of service
+ * - Long descriptions
+ * - Help documentation
+ *
+ * The component automatically shows a scrollbar when the text exceeds the
+ * specified height, and users can scroll using the remote's up/down arrow keys.
+ *
+ * @example
+ * ```tsx
+ * import { SystemFont } from "@roku-sdk/components";
+ *
+ * // Basic scrollable text panel
+ * <scrollableText
+ *     text="This is a very long piece of text that will scroll..."
+ *     width={800}
+ *     height={400}
+ *     font={SystemFont.Medium}
+ *     color="#FFFFFFFF"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom scrollbar appearance
+ * <scrollableText
+ *     text={licenseText}
+ *     width={1000}
+ *     height={500}
+ *     lineSpacing={12}
+ *     scrollbarTrackBitmapUri="pkg:/images/scrollbar-track.9.png"
+ *     scrollbarThumbBitmapUri="pkg:/images/scrollbar-thumb.9.png"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Centered text alignment
+ * <scrollableText
+ *     text="Centered scrollable content"
+ *     width={600}
+ *     height={300}
+ *     horizAlign="center"
+ *     vertAlign="top"
+ * />
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/scrollabletext}
+ */
+export const ScrollableText: Component<IScrollableTextProps> = props => {
+    return <scrollableText {...props}></scrollableText>;
+};