@roku-sdk/components 0.0.0-stage → 2.18.0

package/src/sg-nodes/standard-pinpad-dialog.props.ts

@@ -0,0 +1,64 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IStandardDialogProps } from "./standard-dialog.props";
+import type { EventHandler } from "./types";
+
+/**
+ * Properties for the {@link StandardPinPadDialog} component.
+ *
+ * Extends {@link IStandardDialogProps} with PIN pad-specific fields for numeric entry.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/standard-pinpad-dialog}
+ */
+export interface IStandardPinPadDialogProps extends IStandardDialogProps {
+    /**
+     * The title displayed at the top of the dialog.
+     * @default ""
+     */
+    title?: string;
+    /**
+     * One or more blocks of text describing the data to be entered.
+     * Each string in the array is displayed as a separate block of text.
+     * Minimize message length to avoid automatic scrollbar.
+     * @default []
+     */
+    message?: string[];
+    /**
+     * List of button labels to display in the button area at the bottom of the dialog.
+     * Minimize the number of buttons to ensure visibility without scrolling.
+     * @default []
+     */
+    buttons?: string[];
+    /**
+     * The entered PIN value displayed in the text edit box.
+     * Updated with the currently entered value as the user enters each digit.
+     * @default ""
+     */
+    pin?: string;
+    /**
+     * Fired whenever the PIN in the text edit box changes (on each digit entry).
+     * The handler receives the full current PIN string entered by the user.
+     *
+     * Use this to react to live input — for example to validate the PIN length
+     * or enable/disable action buttons based on what the user has entered so far.
+     *
+     * @example
+     * ```tsx
+     * const [pin, setPin] = createSignal("");
+     *
+     * <StandardPinPadDialog
+     *     title="Enter PIN"
+     *     pin={pin()}
+     *     onPin={(value) => {
+     *         // Called on every digit entry with the full current PIN
+     *         setPin(value);
+     *         console.log("User is entering PIN:", value);
+     *     }}
+     *     buttons={["Submit", "Cancel"]}
+     *     onButtonSelected={(index) => console.log("Button:", index)}
+     * />
+     * ```
+     */
+    onPin?: EventHandler<string>;
+}

package/src/sg-nodes/standard-pinpad-dialog.tsx

@@ -0,0 +1,46 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { Modal, modalPropKeys } from "../modal-dialog";
+import { retainAsset } from "../retain-asset";
+import StandardPinPadDialogExtXML from "../xml-components/modal/StandardPinPadDialogExt.xml";
+import type { IStandardPinPadDialogProps } from "./standard-pinpad-dialog.props";
+import { Component, splitProps } from "./types";
+export type { IStandardPinPadDialogProps } from "./standard-pinpad-dialog.props";
+
+/**
+ * Displays a PIN pad dialog for text and voice entry of numeric PIN codes.
+ *
+ * `StandardPinPadDialog` is a pre-built dialog similar to the legacy PinDialog node,
+ * but includes voice entry of numeric digits through its internal DynamicPinPad and
+ * VoiceTextEditBox nodes.
+ *
+ * @example
+ * ```tsx
+ * const [showPinPad, setShowPinPad] = createSignal(false);
+ * const [pin, setPin] = createSignal("");
+ *
+ * {showPinPad() && (
+ *     <StandardPinPadDialog
+ *         title="Enter PIN"
+ *         message={["Please enter your 4-digit PIN:"]}
+ *         pin={pin()}
+ *         buttons={["Submit", "Cancel"]}
+ *         onButtonSelected={(index) => {
+ *             if (index === 0) {
+ *                 console.log("PIN entered:", pin());
+ *             }
+ *             setShowPinPad(false);
+ *         }}
+ *         onWasClosed={() => setShowPinPad(false)}
+ *     />
+ * )}
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/standard-pinpad-dialog}
+ */
+export const StandardPinPadDialog: Component<IStandardPinPadDialogProps> = props => {
+    retainAsset(StandardPinPadDialogExtXML);
+    const [local, rest] = splitProps(props, modalPropKeys);
+    return <Modal {...local} dialog={<standardPinPadDialogExt {...rest} />} />;
+};

package/src/sg-nodes/standard-progress-dialog.props.ts

@@ -0,0 +1,30 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IStandardDialogProps } from "./standard-dialog.props";
+
+/**
+ * Properties for the {@link StandardProgressDialog} component.
+ *
+ * Extends {@link IStandardDialogProps} (omitting button events since progress dialogs have no buttons)
+ * with fields for displaying a spinning progress indicator.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/standard-progress-dialog}
+ */
+export interface IStandardProgressDialogProps extends Omit<
+    IStandardDialogProps,
+    "onButtonSelected" | "onButtonFocused"
+> {
+    /**
+     * The title displayed at the top of the dialog.
+     * If empty, the dialog displays without a title area and uses minimum width.
+     * @default ""
+     */
+    title?: string;
+    /**
+     * A string displayed next to the spinning progress indicator.
+     * Typically tells the user why they are waiting. Minimize message length.
+     * @default ""
+     */
+    message?: string;
+}

package/src/sg-nodes/standard-progress-dialog.tsx

@@ -0,0 +1,43 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { Modal, modalPropKeys } from "../modal-dialog";
+import { retainAsset } from "../retain-asset";
+import StandardProgressDialogExtXML from "../xml-components/modal/StandardProgressDialogExt.xml";
+import type { IStandardProgressDialogProps } from "./standard-progress-dialog.props";
+import { Component, splitProps } from "./types";
+export type { IStandardProgressDialogProps } from "./standard-progress-dialog.props";
+
+/**
+ * Displays a progress dialog with a spinning indicator and message.
+ *
+ * `StandardProgressDialog` is a pre-built dialog similar to the legacy ProgressDialog node.
+ * It displays a spinning progress indicator for tasks with an indeterminate duration.
+ *
+ * Note: Unlike other standard dialogs, `StandardProgressDialog` has no buttons — it only
+ * displays a spinner with a message. Close the dialog programmatically by setting
+ * {@link IStandardProgressDialogProps.close | close} to `true` or by unmounting the component.
+ *
+ * @example
+ * ```tsx
+ * const [isLoading, setIsLoading] = createSignal(true);
+ *
+ * // Show progress dialog while loading
+ * {isLoading() && (
+ *     <StandardProgressDialog
+ *         title="Loading"
+ *         message="Please wait..."
+ *     />
+ * )}
+ *
+ * // When loading completes, hide the dialog
+ * setTimeout(() => setIsLoading(false), 3000);
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/standard-progress-dialog}
+ */
+export const StandardProgressDialog: Component<IStandardProgressDialogProps> = props => {
+    retainAsset(StandardProgressDialogExtXML);
+    const [local, rest] = splitProps(props, modalPropKeys);
+    return <Modal {...local} dialog={<standardProgressDialogExt {...rest} />} />;
+};

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

@@ -0,0 +1,278 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./group.props";
+import type { EventHandler, JSX } from "./types";
+
+/**
+ * Properties for the TargetGroup node.
+ *
+ * TargetGroup associates a set of rectangular target regions (defined by a
+ * {@link ITargetSetProps | TargetSet}) with child items rendered by a compiled
+ * XML component. It is typically used to create scrolling lists where the
+ * focused item occupies more space than unfocused items, with smooth
+ * animations between states.
+ *
+ * **How it works:**
+ * 1. Define target rectangles via a TargetSet — one rectangle per visible
+ *    slot, including off-screen slots for smooth entry/exit.
+ * 2. Specify an XML component via `itemComponentName` to render each item.
+ *    The TargetGroup creates instances on demand and updates their fields
+ *    (`currTarget`, `currRect`, `index`, `groupHasFocus`, `itemContent`,
+ *    `focusPercent`, `itemHasFocus`) as items animate.
+ * 3. Navigate by setting `animateToItem` or `jumpToItem` to move the
+ *    content so that the specified index occupies the focus region.
+ * 4. Animate between layouts by setting `animateToTargetSet` to smoothly
+ *    transition all items from one set of target rectangles to another.
+ *
+ * @extends IGroupProps
+ * @see {@link https://developer.roku.com/dev/docs/targetgroup}
+ *
+ * @example
+ * ```tsx
+ * import "./compiled-components/MyItem.xml";
+ *
+ * <TargetGroup
+ *     itemComponentName="MyItem"
+ *     targetSet={
+ *         <TargetSet
+ *             targetRects={[
+ *                 [0, -200, 1920, 200],
+ *                 [0, 20, 1920, 200],
+ *                 [0, 240, 1920, 400],
+ *                 [0, 660, 1920, 200],
+ *                 [0, 880, 1920, 200],
+ *             ]}
+ *             focusIndex={2}
+ *         />
+ *     }
+ *     content={contentNode}
+ *     onItemFocused={(index) => console.log("Focused:", index)}
+ *     onItemSelected={(index) => console.log("Selected:", index)}
+ * />
+ * ```
+ */
+export interface ITargetGroupProps extends IGroupProps {
+    // ─────────────────────────────────────────────────────────────────────────
+    // Item Rendering
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies the name of the XML component used to render each group item.
+     * An instance is created on demand for each visible target region.
+     *
+     * Register the compiled component by importing its XML file before use:
+     * ```ts
+     * import "./compiled-components/MyItem.xml";
+     * ```
+     *
+     * The XML component may define interface fields that TargetGroup will
+     * automatically update: `currTarget`, `currRect`, `index`,
+     * `groupHasFocus`, `itemContent`, `focusPercent`, and `itemHasFocus`.
+     *
+     * @example "MyItem"
+     * @see {@link https://developer.roku.com/dev/docs/targetgroup#targetgroup-xml-component | TargetGroup XML Component}
+     */
+    itemComponentName?: string;
+
+    /**
+     * Specifies the content for the group.
+     *
+     * Should be a single root `ContentNode` with one child `ContentNode` per
+     * item. Each child node should contain the data required by the XML
+     * component specified in `itemComponentName`.
+     *
+     * **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/targetgroup#data-bindings | Data Bindings}
+     */
+    content?: JSX.Element;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Target Configuration
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies the TargetSet to use to define the target regions of the
+     * items in the group. When set or modified, the target regions are
+     * immediately adjusted to use the new values.
+     *
+     * @see {@link https://developer.roku.com/dev/docs/targetgroup | TargetGroup targetSet}
+     */
+    targetSet?: JSX.Element;
+
+    /**
+     * For TargetSets that do not specify a `focusIndex`, this value will
+     * be used as the index of the target rectangle where the focused item
+     * is located. If a TargetSet specifies any value for `focusIndex`,
+     * that value will be used instead.
+     *
+     * @default 0
+     */
+    defaultTargetSetFocusIndex?: number;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Scrolling Behaviour
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies whether the content items wrap around at the end of the
+     * TargetGroup to fill all of the target rectangles.
+     *
+     * @default false
+     */
+    wrap?: boolean;
+
+    /**
+     * Forces the item index to be interpolated in a forward direction when
+     * animating between items. Only has an effect when `wrap` is `true`.
+     *
+     * For example, when the number of items is 10 and animating from item 9
+     * to item 0, enabling this causes the sequence `9 → 0` instead of
+     * `9 → 8 → 7 → … → 0`.
+     *
+     * @default false
+     */
+    advancing?: boolean;
+
+    /**
+     * Forces the item index to be interpolated in a reverse direction when
+     * animating between items. Only has an effect when `wrap` is `true`.
+     *
+     * For example, when the number of items is 10 and animating from item 0
+     * to item 9, enabling this causes the sequence `0 → 9` instead of
+     * `0 → 1 → … → 9`.
+     *
+     * @default false
+     */
+    reversing?: boolean;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Animation
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies the time, in seconds, to perform the animation when the
+     * `animateToItem` or `animateToTargetSet` fields are set.
+     *
+     * @default 0.3
+     */
+    duration?: number;
+
+    /**
+     * Specifies the interpolator function used in TargetGroup animations
+     * between items.
+     *
+     * @default "inOutCubic"
+     */
+    easeFunction?: string;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Debug
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * When `true`, the current target rectangles (as defined in the
+     * `currTargetSet`) are drawn using the color specified in the
+     * TargetSet's `color` field. Typically only set to `true` for
+     * debugging purposes.
+     *
+     * @default false
+     */
+    showTargetRects?: boolean;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Navigation (Write-Only)
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * When set to a valid item index, causes the group to immediately
+     * update so that the specified index moves to the target region
+     * specified by the TargetSet's `focusIndex`.
+     *
+     * **Important:** Set this property after `content` in the component order. When
+     * content is updated dynamically, update `jumpToItem` in the same transaction
+     * or after content has been updated.
+     *
+     * @example
+     * ```tsx
+     * <TargetGroup
+     *     content={contentNode}
+     *     jumpToItem={jumpToItem}
+     *     ...
+     * />
+     * ```
+     *
+     * @writeonly
+     * @default 0
+     */
+    jumpToItem?: number;
+
+    /**
+     * When set to a valid item index, causes the group to smoothly
+     * animate so that the specified index moves to the target region
+     * specified by the TargetSet's `focusIndex`.
+     *
+     * **Important:** Set this property after `content` in the component order. When
+     * content is updated dynamically, update `animateToItem` in the same transaction
+     * or after content has been updated.
+     *
+     * @example
+     * ```tsx
+     * <TargetGroup
+     *     content={contentNode}
+     *     animateToItem={animateToItem}
+     *     ...
+     * />
+     * ```
+     *
+     * @writeonly
+     * @default 0
+     */
+    animateToItem?: number;
+
+    /**
+     * When set to a valid TargetSet, causes the group to smoothly
+     * animate all items from the current target regions to the
+     * corresponding regions of the new TargetSet. If the two
+     * TargetSets have different `focusIndex` values, the focus
+     * index is also animated.
+     *
+     * @writeonly
+     */
+    animateToTargetSet?: JSX.Element;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Events (Read-Only)
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Fired when the current focus item index changes during animation.
+     * The value is a `float` — integer when the item occupies the focus
+     * target, fractional during animation (e.g., `5.7` means item 6
+     * occupies 70% and item 5 occupies 30%).
+     *
+     * @readonly
+     */
+    onCurrFocusItemIndexChange?: EventHandler<number>;
+
+    /**
+     * Fired when the current target set changes during an
+     * `animateToTargetSet` animation. Contains the interpolated
+     * TargetSet as the animation proceeds.
+     *
+     * @readonly
+     */
+    onCurrTargetSetChange?: EventHandler<JSX.Element>;
+
+    /** Fired when a group item is selected (e.g., OK button press). */
+    onItemSelected?: EventHandler<number>;
+
+    /** Fired when a group item gains the key focus. */
+    onItemFocused?: EventHandler<number>;
+
+    /** Fired when a group item loses the key focus. */
+    onItemUnfocused?: EventHandler<number>;
+}

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

@@ -0,0 +1,63 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { ITargetGroupProps } from "./target-group.props";
+import { Component } from "./types";
+export type { ITargetGroupProps } from "./target-group.props";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TargetGroup Properties
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * TargetGroup creates scrolling lists (or rows) of items where each item's
+ * size and position is defined by rectangular target regions in a
+ * {@link TargetSet}. The focused item typically occupies a larger region
+ * than unfocused items, with smooth animations between states.
+ *
+ * **Common use cases:**
+ * - A full-screen vertical list where the focused item is larger
+ * - A list that collapses when unfocused and expands when focused,
+ *   using two TargetSets animated via `animateToTargetSet`
+ * - A horizontal row with a floating focus region
+ * - A circular arrangement with fixed positions
+ *
+ * @see {@link https://developer.roku.com/dev/docs/targetgroup}
+ * @see {@link https://github.com/rokudev/samples/blob/master/ux%20components/screen%20elements/target_group/FloatingFocusWrap | FloatingFocusWrap Sample}
+ * @see {@link https://github.com/rokudev/samples/blob/master/ux%20components/screen%20elements/target_group/TwoRowFixedFocus | TwoRowFixedFocus Sample}
+ *
+ * @example
+ * ```tsx
+ * import "./compiled-components/MyItem.xml";
+ *
+ * <targetGroup
+ *     itemComponentName="MyItem"
+ *     targetSet={
+ *         <targetSet
+ *             targetRects={[
+ *                 [0, -200, 1920, 200],
+ *                 [0, 20, 1920, 200],
+ *                 [0, 240, 1920, 400],
+ *                 [0, 660, 1920, 200],
+ *                 [0, 880, 1920, 200],
+ *             ]}
+ *             focusIndex={2}
+ *         />
+ *     }
+ *     content={
+ *         <contentNode>
+ *             <contentNode title="Item 1" description="First item" />
+ *             <contentNode title="Item 2" description="Second item" />
+ *             <contentNode title="Item 3" description="Third item" />
+ *         </contentNode>
+ *     }
+ *     duration={0.4}
+ *     wrap={true}
+ *     onItemFocused={(index) => console.log("Focused:", index)}
+ *     onItemSelected={(index) => console.log("Selected:", index)}
+ * />
+ * ```
+ */
+export const TargetGroup: Component<ITargetGroupProps> = props => {
+    return <targetGroup {...props}></targetGroup>;
+};

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

@@ -0,0 +1,128 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { ITargetGroupProps } from "./target-group.props";
+import type { JSX } from "./types";
+
+/**
+ * Properties for the TargetList node.
+ *
+ * TargetList extends {@link ITargetGroupProps | TargetGroup} with built-in
+ * focused/unfocused transitions, focus management policies (fixed focus,
+ * floating focus), and default key handling for navigating the list or row.
+ *
+ * **Fixed focus:** Set `focusedTargetSet` to a single-element array containing
+ * one TargetSet. The focus stays fixed on the target rectangle at the
+ * TargetSet's `focusIndex`. Optionally set `unfocusedTargetSet` for a smooth
+ * transition when the list gains or loses focus.
+ *
+ * **Floating focus:** Set `focusedTargetSet` to an array of TargetSets — one
+ * per focus position — with incrementing `focusIndex` values. As the user
+ * navigates, the list advances through the array until the last element is
+ * reached, at which point items begin to scroll.
+ *
+ * @extends ITargetGroupProps
+ * @see {@link https://developer.roku.com/dev/docs/targetlist}
+ *
+ * @example Fixed focus
+ * ```tsx
+ * import { TargetList, TargetSet } from "@roku-sdk/components";
+ * import "./compiled-components/MyItem.xml";
+ *
+ * <TargetList
+ *     itemComponentName="MyItem"
+ *     focusedTargetSet={[
+ *         <TargetSet
+ *             targetRects={[
+ *                 [-178, -64, 240, 134],
+ *                 [72, -96, 360, 202],
+ *                 [442, -64, 240, 134],
+ *                 [692, -64, 240, 134],
+ *             ]}
+ *             focusIndex={1}
+ *         />,
+ *     ]}
+ *     unfocusedTargetSet={
+ *         <TargetSet
+ *             targetRects={[
+ *                 [-100, -64, 240, 134],
+ *                 [150, -64, 240, 134],
+ *                 [400, -64, 240, 134],
+ *                 [650, -64, 240, 134],
+ *             ]}
+ *         />
+ *     }
+ *     content={contentNode}
+ * />
+ * ```
+ *
+ * @example Floating focus
+ * ```tsx
+ * <TargetList
+ *     itemComponentName="MyItem"
+ *     advanceKey="right"
+ *     reverseKey="left"
+ *     focusedTargetSet={[
+ *         <TargetSet targetRects={rectsForFocus0} focusIndex={0} />,
+ *         <TargetSet targetRects={rectsForFocus1} focusIndex={1} />,
+ *         <TargetSet targetRects={rectsForFocus2} focusIndex={2} />,
+ *     ]}
+ *     content={contentNode}
+ * />
+ * ```
+ */
+export interface ITargetListProps extends ITargetGroupProps {
+    // ─────────────────────────────────────────────────────────────────────────
+    // Focus Configuration
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies one or more TargetSets to be used when the TargetList has
+     * the focus.
+     *
+     * - **Fixed focus**: provide a single-element array. Focus stays fixed on
+     *   the target rectangle corresponding to the TargetSet's `focusIndex`
+     *   (or the TargetGroup's `defaultTargetSetFocusIndex` if the TargetSet
+     *   does not specify one).
+     * - **Floating focus**: provide multiple TargetSets with incrementing
+     *   `focusIndex` values. As the user presses `advanceKey`, focus floats
+     *   from one TargetSet to the next until the last element is reached, at
+     *   which point items begin to scroll. Reversing works symmetrically.
+     *
+     * @default []
+     * @see {@link https://developer.roku.com/dev/docs/targetlist | TargetList Fields}
+     */
+    focusedTargetSet?: JSX.Element[];
+
+    /**
+     * Specifies the TargetSet to be used when the TargetList does **not**
+     * have the focus. Setting this enables a smooth transition between the
+     * focused and unfocused layouts when the list gains or loses focus.
+     *
+     * @default invalid
+     * @see {@link https://developer.roku.com/dev/docs/targetlist | TargetList Fields}
+     */
+    unfocusedTargetSet?: JSX.Element;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Key Handling
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies which remote button will move the focus forward. For vertical
+     * lists, this is typically `"down"`; for horizontal rows, `"right"`.
+     *
+     * @default "down"
+     * @see {@link https://developer.roku.com/dev/docs/targetlist | TargetList Fields}
+     */
+    advanceKey?: string;
+
+    /**
+     * Specifies which remote button will move the focus backward. For vertical
+     * lists, this is typically `"up"`; for horizontal rows, `"left"`.
+     *
+     * @default "up"
+     * @see {@link https://developer.roku.com/dev/docs/targetlist | TargetList Fields}
+     */
+    reverseKey?: string;
+}