@roku-sdk/components 0.0.0-stage → 2.19.0

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

@@ -0,0 +1,66 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { ITargetListProps } from "./target-list.props";
+import { Component } from "./types";
+export type { ITargetListProps } from "./target-list.props";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TargetList Properties
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * TargetList extends {@link TargetGroup} with built-in focused/unfocused
+ * transitions and focus management policies, making it easy to create
+ * scrollable lists and rows with minimal scripting.
+ *
+ * It supports two focus modes:
+ * - **Fixed focus**: the focused item stays in one position while items
+ *   scroll beneath it.
+ * - **Floating focus**: the focus moves across several positions before
+ *   items begin to scroll.
+ *
+ * Both modes can include an `unfocusedTargetSet` for a smooth layout
+ * transition when the list gains or loses focus.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/targetlist}
+ * @see {@link https://github.com/rokudev/samples/tree/master/ux%20components/screen%20elements/target_group/TwoRowFixedFocus | TwoRowFixedFocus Sample}
+ *
+ * @example
+ * ```tsx
+ * import "./compiled-components/MyItem.xml";
+ *
+ * <targetList
+ *     itemComponentName="MyItem"
+ *     focusedTargetSet={[
+ *         <targetSet
+ *             targetRects={[
+ *                 [0, -200, 1920, 200],
+ *                 [0, 20, 1920, 200],
+ *                 [0, 240, 1920, 400],
+ *                 [0, 660, 1920, 200],
+ *                 [0, 880, 1920, 200],
+ *             ]}
+ *             focusIndex={2}
+ *         />,
+ *     ]}
+ *     unfocusedTargetSet={
+ *         <targetSet
+ *             targetRects={[
+ *                 [0, 0, 1920, 200],
+ *                 [0, 210, 1920, 200],
+ *                 [0, 420, 1920, 200],
+ *                 [0, 630, 1920, 200],
+ *                 [0, 840, 1920, 200],
+ *             ]}
+ *         />
+ *     }
+ *     content={contentNode}
+ *     onItemFocused={(index) => console.log("Focused:", index)}
+ *     onItemSelected={(index) => console.log("Selected:", index)}
+ * />
+ * ```
+ */
+export const TargetList: Component<ITargetListProps> = props => {
+    return <targetList {...props}></targetList>;
+};

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

@@ -0,0 +1,63 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { INodeProps } from "./node";
+import type { Rect2D } from "./types";
+
+/**
+ * Properties for the TargetSet node.
+ *
+ * TargetSet defines a set of rectangular target regions used by a
+ * {@link ITargetGroupProps | TargetGroup} node to position its items.
+ * Each rectangle specifies the location and size of a region that will
+ * be occupied by an item in the TargetGroup.
+ *
+ * @extends INodeProps
+ * @see {@link https://developer.roku.com/dev/docs/targetset}
+ *
+ * @example
+ * ```tsx
+ * <targetSet
+ *     targetRects={[
+ *         [0, 0, 400, 300],
+ *         [0, 320, 400, 200],
+ *         [0, 540, 400, 200],
+ *     ]}
+ *     focusIndex={0}
+ * />
+ * ```
+ */
+export interface ITargetSetProps extends INodeProps {
+    /**
+     * Specifies an array of rectangles that define the target regions used
+     * by a TargetGroup node. Each rectangle is specified as
+     * `[x, y, width, height]`.
+     *
+     * @default []
+     * @example [[10, 5, 200, 150], [10, 160, 200, 150]]
+     * @see {@link https://developer.roku.com/dev/docs/targetset | TargetSet targetRects}
+     */
+    targetRects?: Rect2D[];
+
+    /**
+     * Identifies the index of a `targetRects` element that will be treated
+     * as the region occupied by the focus item.
+     *
+     * A value of `-1` indicates that the TargetGroup's
+     * `defaultTargetSetFocusIndex` will be used instead.
+     *
+     * @default -1
+     * @see {@link https://developer.roku.com/dev/docs/targetset | TargetSet focusIndex}
+     */
+    focusIndex?: number;
+
+    /**
+     * If the TargetGroup using this TargetSet has its `showTargetRects`
+     * field set to `true`, the target rectangles will be drawn using this
+     * color. Typically only used for debugging.
+     *
+     * @default "0xFFFFFF80"
+     * @see {@link https://developer.roku.com/dev/docs/targetset | TargetSet color}
+     */
+    color?: string;
+}

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

@@ -0,0 +1,42 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { ITargetSetProps } from "./target-set.props";
+import { Component } from "./types";
+export type { ITargetSetProps } from "./target-set.props";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TargetSet Properties
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * TargetSet defines rectangular target regions for a {@link TargetGroup}.
+ *
+ * A TargetSet specifies an array of rectangles that define where items in a
+ * TargetGroup will be rendered, along with an optional focus index identifying
+ * which rectangle is treated as the focused region.
+ *
+ * Multiple TargetSets can be used to animate between different layouts
+ * (e.g., focused vs. unfocused states) via the TargetGroup's
+ * `animateToTargetSet` field.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/targetset}
+ *
+ * @example
+ * ```tsx
+ * <targetSet
+ *     targetRects={[
+ *         [0, -200, 1920, 200],   // off-screen above
+ *         [0, 20, 1920, 200],     // first visible
+ *         [0, 240, 1920, 200],    // second visible
+ *         [0, 460, 1920, 400],    // focused (larger)
+ *         [0, 880, 1920, 200],    // fourth visible
+ *         [0, 1100, 1920, 200],   // off-screen below
+ *     ]}
+ *     focusIndex={3}
+ * />
+ * ```
+ */
+export const TargetSet: Component<ITargetSetProps> = props => {
+    return <targetSet {...props}></targetSet>;
+};