@roku-sdk/components 0.0.0-stage → 2.18.0

package/src/sg-nodes/dialog.tsx

@@ -0,0 +1,36 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { Modal } from "../modal-dialog";
+import type { IDialogProps } from "./dialog.props";
+import { Component } from "./types";
+export type { IDialogProps } from "./dialog.props";
+
+/**
+ * Dialog is a modal pop-up used to present the user with information requiring their
+ * immediate attention. It supports a title, message, bullet text, graphic, and button
+ * regions. Dialogs intercept all key events except Home and are closed automatically
+ * by Back or Home.
+ *
+ * > **Note:** Consider using StandardDialog (Roku OS 10.0+) for new development, which
+ * > provides updated graphics and color palette support.
+ *
+ * @example
+ * ```tsx
+ * <Dialog
+ *     title="Confirm Action"
+ *     message="Are you sure you want to proceed?"
+ *     iconUri="pkg:/images/dialog-icon.png"
+ *     buttons={["OK", "Cancel"]}
+ *     close={false}
+ *     onButtonSelected={(index) => {
+ *         if (index === 0) handleConfirm();
+ *         else handleCancel();
+ *     }}
+ *     onWasClosed={() => console.log("Dialog closed")}
+ * />
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/dialog}
+ */
+export const Dialog: Component<IDialogProps> = props => <Modal dialog={<dialog {...props}></dialog>} />;

package/src/sg-nodes/dynamic-key-grid.props.ts

@@ -0,0 +1,22 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./group.props";
+import type { EventHandler } from "./types";
+
+/**
+ * Properties for the {@link DynamicKeyGrid} component.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/dynamic-key-grid}
+ */
+export interface IDynamicKeyGridProps extends IGroupProps {
+    /** URI of a packaged `.keyboard.json` Key Definition File. */
+    keyDefinitionUri?: string;
+    /** Active grid mode (must match a mode in the KDF). */
+    mode?: string;
+    /** Fired when the `keySelected` field changes after a key press. */
+    onKeySelected?: EventHandler<string>;
+    focusVisible?: boolean;
+    horizWrap?: boolean;
+    vertWrap?: boolean;
+}

package/src/sg-nodes/dynamic-key-grid.tsx

@@ -0,0 +1,16 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { retainAsset } from "../retain-asset";
+import KeyGridExtXML from "../xml-components/keyboards/KeyGridExt.xml";
+import type { IDynamicKeyGridProps } from "./dynamic-key-grid.props";
+import { Component } from "./types";
+export type { IDynamicKeyGridProps } from "./dynamic-key-grid.props";
+
+/**
+ * Standalone key grid driven by a Key Definition File (no text edit box).
+ */
+export const DynamicKeyGrid: Component<IDynamicKeyGridProps> = props => {
+    retainAsset(KeyGridExtXML);
+    return <keyGridExt {...props}></keyGridExt>;
+};

package/src/sg-nodes/dynamic-keyboard.props.ts

@@ -0,0 +1,30 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { KeyboardDomain } from "./custom-keyboard.props";
+import type { IGroupProps } from "./group.props";
+import type { EventHandler } from "./types";
+
+/**
+ * Properties for the {@link DynamicKeyboard} component.
+ *
+ * Voice-enabled full keyboard with a fixed OS key layout (email/password style).
+ *
+ * @see {@link https://developer.roku.com/dev/docs/dynamic-keyboard}
+ */
+export interface IDynamicKeyboardProps extends IGroupProps {
+    /** Current text in the internal VoiceTextEditBox. */
+    text?: string;
+    /** Fired when entered text changes. */
+    onText?: EventHandler<string>;
+    /** Speech-recognition domain for voice entry. */
+    domain?: KeyboardDomain;
+    /** Placeholder text shown when empty. */
+    hintText?: string;
+    /** Maximum number of characters that may be entered. */
+    maxTextLength?: number;
+    /** Shows underscore placeholders in the text edit box. */
+    showUnderscores?: boolean;
+    /** When true, entered characters are masked. */
+    secureMode?: boolean;
+}

package/src/sg-nodes/dynamic-keyboard.tsx

@@ -0,0 +1,18 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { retainAsset } from "../retain-asset";
+import KeyboardExtXML from "../xml-components/keyboards/KeyboardExt.xml";
+import type { IDynamicKeyboardProps } from "./dynamic-keyboard.props";
+import { Component } from "./types";
+export type { IDynamicKeyboardProps } from "./dynamic-keyboard.props";
+
+/**
+ * Standalone {@link DynamicKeyboard} with built-in key layout and voice entry.
+ *
+ * Voice is always enabled on this fixed OS layout; there is no `voiceEnabled` prop.
+ */
+export const DynamicKeyboard: Component<IDynamicKeyboardProps> = props => {
+    retainAsset(KeyboardExtXML);
+    return <keyboardExt {...props}></keyboardExt>;
+};

package/src/sg-nodes/dynamic-mini-keyboard.props.ts

@@ -0,0 +1,22 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { KeyboardDomain } from "./custom-keyboard.props";
+import type { IGroupProps } from "./group.props";
+import type { EventHandler } from "./types";
+
+/**
+ * Properties for the {@link DynamicMiniKeyboard} component.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/dynamic-mini-keyboard}
+ */
+export interface IDynamicMiniKeyboardProps extends IGroupProps {
+    text?: string;
+    onText?: EventHandler<string>;
+    /** Speech-recognition domain for voice entry. */
+    domain?: KeyboardDomain;
+    /** Placeholder text shown when empty. */
+    hintText?: string;
+    /** Maximum number of characters that may be entered. */
+    maxTextLength?: number;
+}

package/src/sg-nodes/dynamic-mini-keyboard.tsx

@@ -0,0 +1,18 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { retainAsset } from "../retain-asset";
+import MiniKeyboardExtXML from "../xml-components/keyboards/MiniKeyboardExt.xml";
+import type { IDynamicMiniKeyboardProps } from "./dynamic-mini-keyboard.props";
+import { Component } from "./types";
+export type { IDynamicMiniKeyboardProps } from "./dynamic-mini-keyboard.props";
+
+/**
+ * Standalone search-style mini keyboard (A–Z, 0–9) with voice entry.
+ *
+ * Voice is always enabled on this fixed OS layout; there is no `voiceEnabled` prop.
+ */
+export const DynamicMiniKeyboard: Component<IDynamicMiniKeyboardProps> = props => {
+    retainAsset(MiniKeyboardExtXML);
+    return <miniKeyboardExt {...props}></miniKeyboardExt>;
+};

package/src/sg-nodes/dynamic-pinpad.props.ts

@@ -0,0 +1,57 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./group.props";
+import type { EventHandler } from "./types";
+
+/**
+ * Properties for the {@link DynamicPinPad} component.
+ *
+ * DynamicPinPad is similar to the legacy PinPad node but adds voice entry functionality.
+ * It enables text and voice entry of numeric characters and is typically used for short
+ * PIN codes. The key layout is fixed based on the node's pre-built Key Definition File.
+ *
+ * This wrapper extends the native DynamicPinPad node via PinPadExt, forwarding text-edit-box
+ * styling fields to the internal VoiceTextEditBox.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/dynamic-pinpad}
+ * @see {@link https://developer.roku.com/dev/docs/dynamic-keyboard-base}
+ *
+ * @example
+ * ```tsx
+ * <DynamicPinPad
+ *   id="pinpad"
+ *   text={pin()}
+ *   hintText="Enter PIN"
+ *   maxTextLength={4}
+ *   secureMode
+ *   onText={setPin}
+ *   translation={[80, 200]}
+ * />
+ * ```
+ */
+export interface IDynamicPinPadProps extends IGroupProps {
+    /** Current PIN/text value. */
+    text?: string;
+    /** Fired when the entered text changes. */
+    onText?: EventHandler<string>;
+    /** When true, entered characters are masked. */
+    secureMode?: boolean;
+    /** Placeholder text shown when empty. */
+    hintText?: string;
+    /**
+     * Maximum number of characters that may be entered.
+     * @default 4
+     */
+    maxTextLength?: number;
+    /** Disables voice underscore control in the internal text edit box. */
+    disableVoiceUnderscoreControl?: boolean;
+    /** Shows underscore placeholders for each digit position. */
+    showUnderscores?: boolean;
+    /** Centers underscore placeholders within the text box. */
+    centerUnderscores?: boolean;
+    /** Color of the hint text. */
+    hintTextColor?: string;
+    /** Color of the entered text. */
+    textColor?: string;
+}

package/src/sg-nodes/dynamic-pinpad.tsx

@@ -0,0 +1,18 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { retainAsset } from "../retain-asset";
+import PinPadExtXML from "../xml-components/keyboards/PinPadExt.xml";
+import type { IDynamicPinPadProps } from "./dynamic-pinpad.props";
+import { Component } from "./types";
+export type { IDynamicPinPadProps } from "./dynamic-pinpad.props";
+
+/**
+ * Voice-enabled numeric PIN pad for standalone on-screen entry (not inside a dialog).
+ *
+ * @see {@link https://developer.roku.com/dev/docs/dynamic-pinpad}
+ */
+export const DynamicPinPad: Component<IDynamicPinPadProps> = props => {
+    retainAsset(PinPadExtXML);
+    return <pinPadExt {...props}></pinPadExt>;
+};

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

@@ -0,0 +1,116 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { INodeProps } from "./node";
+import type { Vector2D } from "./types";
+
+export type GradientStyle = "none" | "linear" | "radial";
+
+/**
+ * Properties for the Effect node.
+ *
+ * Effect applies GPU shader-based rendering to a Rectangle or Poster, enabling rounded corners,
+ * borders, and gradient fills. Attach an Effect node to a Rectangle or Poster via the `effect`
+ * prop.
+ *
+ * **Platform availability**: Effects require Roku OS 16.0 or later and the OpenGL graphics backend.
+ * Elsewhere the `effect` prop is ignored without an error and the content renders unstyled. To branch
+ * on it, read `getDeviceInfo()` from `@roku-sdk/rsg-ts/runtime` once:
+ * `Number(info.osVersion.major) >= 16 && info.graphicsPlatform === "opengl"`. The node's own `supported`
+ * field is set when the node is created and cannot be read from TypeScript, and effects disabled by
+ * device configuration are invisible to that check.
+ *
+ * Hoist the effect into a `const`. A signal read by the `effect={...}` expression itself builds a new
+ * effect node on every change; signals read by the effect's own fields update it in place.
+ *
+ * {@includeCode ../../../../examples/showcase/src/components/showcases/effect-showcase/shared-effect-showcase.tsx#docs:effect-shared}
+ *
+ * @example
+ * // Rounded border and linear gradient, each hoisted once.
+ * const framed = <effect borderRadius={16} borderWidth={2} borderColor="0xFF0000FF" />;
+ * <rectangle width={400} height={200} effect={framed} />;
+ * const fill = <effect gradientStyle="linear" gradientColors={["0xFF0000FF", "0x0000FFFF"]} />;
+ * <rectangle width={400} height={200} effect={fill} />;
+ *
+ * @since Roku OS 16.0
+ */
+export interface IEffectProps extends INodeProps {
+    /**
+     * Per-corner border radius in pixels.
+     * - A single number applies a uniform radius to all corners.
+     * - A four-element tuple sets each corner independently: `[topLeft, topRight, bottomRight, bottomLeft]`.
+     *   The tuple is one Vector4 field, so a `FloatFieldInterpolator` cannot animate it.
+     * @default 0
+     */
+    borderRadius?: number | [number, number, number, number];
+
+    /**
+     * Border stroke width in pixels. The border is drawn **outside** the content rect.
+     * @default 0
+     */
+    borderWidth?: number;
+
+    /**
+     * Padding in pixels between the border and the content rect. It changes nothing while
+     * `borderWidth` is 0, so it is not content padding.
+     * @default 0
+     */
+    borderPadding?: number;
+
+    /**
+     * Border stroke color as an RGBA hex string (e.g. `"0xFF0000FF"`).
+     * @default "0xFFFFFFFF"
+     */
+    borderColor?: string;
+
+    /**
+     * Gradient fill style applied over the content area. No gradient renders while this is `"none"`.
+     * @default "none"
+     */
+    gradientStyle?: GradientStyle;
+
+    /**
+     * Ordered list of RGBA color stops for the gradient (e.g. `["0xFF0000FF", "0x0000FFFF"]`).
+     * At least two colors are required for the gradient to render. Maximum of 8 colors.
+     */
+    gradientColors?: string[];
+
+    /**
+     * Normalized stop positions `[0, 1]` corresponding to each entry in `gradientColors`.
+     * If omitted, colors are distributed evenly across the gradient. A length mismatch is not reported.
+     */
+    gradientStops?: number[];
+
+    /**
+     * Rotation angle of a linear gradient in degrees.
+     * The gradient fills the available space from opposite corners.
+     * @default 0
+     */
+    gradientAngle?: number;
+
+    /**
+     * Center point of a radial gradient in normalized coordinates.
+     * `[0, 0]` = top-left, `[1, 1]` = bottom-right.
+     * @default [0.5, 0.5]
+     */
+    gradientCentre?: Vector2D;
+
+    /**
+     * Radii of the radial gradient ellipse in normalized coordinates.
+     * `1.0` equals the rectangle's width or height respectively.
+     * @default [0.5, 0.5]
+     */
+    gradientRadius?: Vector2D;
+
+    /**
+     * Whether the gradient fills the content area (inside the border).
+     * @default true
+     */
+    gradientFillContent?: boolean;
+
+    /**
+     * Whether the gradient fills the border area.
+     * @default false
+     */
+    gradientFillBorder?: boolean;
+}

package/src/sg-nodes/effect.tsx

@@ -0,0 +1,39 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IEffectProps } from "./effect.props";
+import { Component } from "./types";
+export type { GradientStyle, IEffectProps } from "./effect.props";
+
+/**
+ * Effect applies GPU shader-based rendering to a Rectangle or Poster.
+ *
+ * Hoist it into a `const` and pass that as the `effect` prop on a Rectangle or
+ * Poster to enable rounded corners, borders, and gradient fills. Set
+ * `shaderCompatible` on a Poster that takes one.
+ *
+ * Prefer the `<effect>` intrinsic for most uses. The `Effect` wrapper is a pure
+ * passthrough (`<effect {...props} />`) and exists for consistency with the component
+ * library.
+ *
+ * {@includeCode ../../../../examples/showcase/src/components/showcases/effect-showcase/shared-effect-showcase.tsx#docs:effect-shared}
+ *
+ * @example
+ * import { Effect } from "@roku-sdk/components";
+ * const framed = <Effect borderRadius={24} borderWidth={6} borderColor="0xF39C12FF" />;
+ * <rectangle width={300} height={140} effect={framed} />;
+ *
+ * @platformAvailability Effects require Roku OS 16.0 or later and the OpenGL graphics backend.
+ * Elsewhere the `effect` prop is ignored without an error and the content renders unstyled. To branch
+ * on it, read `getDeviceInfo()` from `@roku-sdk/rsg-ts/runtime` once:
+ * `Number(info.osVersion.major) >= 16 && info.graphicsPlatform === "opengl"`. The node's own `supported`
+ * field is set when the node is created and cannot be read from TypeScript, and effects disabled by
+ * device configuration are invisible to that check.
+ *
+ * @since Roku OS 16.0
+ *
+ * @intrinsic effect
+ */
+export const Effect: Component<IEffectProps> = props => {
+    return <effect {...props}></effect>;
+};

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

@@ -0,0 +1,45 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { INodeProps } from "./node";
+import type { Uri } from "./types";
+
+/**
+ * Properties for the Font node.
+ *
+ * Font specifies the font to be used by a Label node, or any other nodes that render text.
+ * The uri field can be set to any TrueType/OpenType font file included in the application package.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/font}
+ *
+ * @example
+ * // Using with a Label component
+ * <Label text="Hello World" font={<Font uri="pkg:/fonts/custom.ttf" size={24} />} />
+ */
+export interface IFontProps extends INodeProps {
+    /**
+     * Specifies a TrueType or OpenType font file.
+     * Currently only font files included in the application package can be specified.
+     * @default ""
+     */
+    uri?: Uri;
+
+    /**
+     * Specifies the size of the font in points.
+     * @default 1
+     */
+    size?: number;
+
+    /**
+     * String representation of a Unicode character to display when an unsupported glyph is encountered.
+     * For example, "u0020" would render a space for any unrenderable characters.
+     * @default ""
+     */
+    fallbackGlyph?: string;
+
+    /**
+     * If true, forces SceneGraph to update the component before it is rendered
+     * @default false
+     */
+    preUpdate?: boolean;
+}

package/src/sg-nodes/font.tsx

@@ -0,0 +1,80 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IFontProps } from "./font.props";
+import { Component } from "./types";
+export type { IFontProps } from "./font.props";
+
+/**
+ * Font specifies the font to be used by a Label node, or any other nodes that render text.
+ *
+ * The uri field can be set to any TrueType/OpenType font file. A default system font can also
+ * be specified using the `font:` prefix (e.g., `font:MediumBoldSystemFont`).
+ *
+ * **Components that support Font:**
+ * - `Label` / `MultiStyleLabel`: via `font` prop
+ * - `ScrollableText`: via `font` prop
+ * - `ScrollingLabel`: via `font` prop
+ * - `LabelList`: via `font` and `focusedFont` props
+ * - `PosterGrid`: via `caption1Font` and `caption2Font` props
+ *
+ * @see {@link https://developer.roku.com/dev/docs/font}
+ *
+ * @example
+ * ```tsx
+ * // Inline font prop with Label
+ * <label text="Custom styled text" font={<font uri="pkg:/fonts/orbitron-font.ttf" size={32} />} />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Reusable font definition (declared outside JSX return)
+ * const myFont = <font uri="pkg:/fonts/cookie-regular.ttf" size={28} />;
+ *
+ * // Then in return statement:
+ * return (
+ *     <group>
+ *         <label text="ABCDEFGHIJKLMNOPQRSTUVWXYZ" font={myFont} />
+ *         <label text="abcdefghijklmnopqrstuvwxyz" font={myFont} />
+ *     </group>
+ * );
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using with ScrollableText
+ * <scrollableText
+ *     text="Long scrollable content..."
+ *     width={800}
+ *     height={400}
+ *     font={<font uri="pkg:/fonts/readable.ttf" size={24} />}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using with LabelList
+ * <labelList
+ *     itemSize={[440, 48]}
+ *     font={<font uri="pkg:/fonts/menu.ttf" size={20} />}
+ *     focusedFont={<font uri="pkg:/fonts/menu-bold.ttf" size={22} />}
+ *     content={content}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using with PosterGrid captions
+ * <posterGrid
+ *     basePosterSize={[200, 300]}
+ *     caption1Font={<font uri="pkg:/fonts/title.ttf" size={18} />}
+ *     caption2Font={<font uri="pkg:/fonts/subtitle.ttf" size={14} />}
+ *     caption1NumLines={1}
+ *     caption2NumLines={1}
+ *     content={content}
+ * />
+ * ```
+ */
+export const Font: Component<IFontProps> = props => {
+    return <font {...props}></font>;
+};

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

@@ -0,0 +1,105 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { INodeProps } from "./node";
+import type { EventHandler, Rect2D, ResType, Vector2D } from "./types";
+
+/**
+ * Properties for the Group node.
+ *
+ * Group is a layout container node that serves as the base class for organizing and positioning
+ * child nodes in the SceneGraph. It provides transformation, rendering, and clipping capabilities
+ * for managing visual hierarchies.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/group}
+ */
+export interface IGroupProps extends INodeProps {
+    /** If true, the node and its children are rendered. If false, the node and its children do not render. */
+    visible?: boolean;
+    /** Defines the origin of the node local coordinate system relative to its parent node. */
+    translation?: ResType<Vector2D>;
+    /**
+     * Sets the opacity of the node and its children. Opacity is the opposite of transparency.
+     * Opacity values range from 0.0 (fully transparent) to 1.0 (fully opaque). As the SceneGraph
+     * is traversed, the opacity values are combined by multiplying the current accumulated opacity
+     * with the node opacity, so that if the accumulated opacity of a node ancestors is 0.25 (75%
+     * transparent), the node will have opacity of 0.25 or less. This allows entire branches of the
+     * SceneGraph to fade in and out by animating the opacity of the node at the root of the branch.
+     */
+    opacity?: number;
+    /**
+     * Defines the rotation angle about the scaleRotateCenter point (in radians) of the node local
+     * coordinate system. Positive values specify a counterclockwise rotation, negative values specify
+     * a clockwise rotation. For some Roku Player hardware, specifically Roku Players without OpenGL
+     * graphics support, only rotations of 0, 90, 180 and 270 degrees (in equivalent radians) are supported.
+     */
+    rotation?: number;
+    /** Defines the scale factor to be applied to the node local coordinate. */
+    scale?: Vector2D;
+    /** Describes the location of a point in the node local coordinate that serves as the center of the scale and rotation operations. */
+    scaleRotateCenter?: ResType<Vector2D>;
+    /**
+     * Controls the rendering order of the node relative to its children.
+     * - "renderFirst": any drawing done by this node will be done before the node children are rendered
+     * - "renderLast": any drawing done by this node will be done after the node children are rendered (default)
+     */
+    childRenderOrder?: "renderFirst" | "renderLast";
+    /**
+     * If true, the node overall transformation is determined by combining the accumulated transformation
+     * matrix of all of its ancestors in the SceneGraph with the node local 2D transformation matrix
+     * described by its translation, rotation, scale and scaleRotateCenter fields. If false, the accumulated
+     * transformation of all of its ancestors in the SceneGraph is ignored and only the node local
+     * transformation matrix is used. This causes the node to be transformed relative to the root of the
+     * SceneGraph (that is, the Scene component).
+     */
+    inheritParentTransform?: boolean;
+    /**
+     * If true, the node opacity is determined by multiplying opacity attribute of the node by the opacity
+     * of the parent node, which may have been determined by multiplying the opacity of its ancestor nodes.
+     * If false, the node opacity is determined by the opacity attribute set for the node or the default
+     * opacity attribute value.
+     */
+    inheritParentOpacity?: boolean;
+    /**
+     * Specifies a rectangle in the node local coordinate system that is used to limit the region where
+     * this node and its children can render. If a non-empty rectangle is specified, then all drawing by
+     * this node and its children will be limited to that rectangular area.
+     * ClippingRects can be specified by the node or by any of its ancestors in the SceneGraph.
+     * ClippingRects are automatically set by some nodes such as lists and grids.
+     * ClippingRects are always clipped to the screen boundaries, so if a clippingRect is specified that
+     * is partially or completely offscreen, it will be clipped to the screen boundaries. With respect to
+     * render tracking, although the node could be completely within the bounds of the specified clippingRect,
+     * it's renderTracking field could be set to "none" if the portion of the clippingRect it occupies is
+     * completely offscreen.
+     */
+    clippingRect?: ResType<Rect2D>;
+    /**
+     * Used in combination with the numRenderPasses field of nodes extended from the ArrayGrid abstract
+     * node class, to optimize rendering of lists and grids. This should never be set to a non-zero value
+     * unless you are optimizing the performance of a list or grid rendering by specifying the sequence of
+     * rendering operations for sub-elements of the list or grid items, and have set the numRenderPasses
+     * field value for the list or grid to a value greater than 1. If the numRenderPasses field value for
+     * the list or grid is set to a value greater than 1, you must set this field to a value greater than 0
+     * for all sub-elements of the list or grid items, and not greater than the numRenderPasses field value.
+     * If the numRenderPasses field is set to a value greater than 1, and you set this field for a list or
+     * grid item sub-element to 0 (the default), or a value greater than the numRenderPasses field value,
+     * the list or grid item sub-element will not render.
+     */
+    renderPass?: number;
+    /** Set to true to suppress the default CVAA text to speech. This allows apps to provide their own custom implementation. */
+    muteAudioGuide?: boolean;
+    /** If true, renderTracking will be set to a string describing how much of the node is rendered on screen. */
+    enableRenderTracking?: boolean;
+    /**
+     * Event fired when the render tracking state changes. The value is set to "disabled" when enableRenderTracking
+     * is set to false. The following options are only available when enableRenderTracking is set to true:
+     * - "disabled": Set when enableRenderTracking is false.
+     * - "none": Set when the node's visible field is false, opacity is 0.0, the node is completely offscreen,
+     *   or lies completely outside the clippingRect's coordinates.
+     * - "partial": Set when the node is visible with opacity > 0.0 and is partially offscreen or lies partially
+     *   inside the clippingRect's coordinates.
+     * - "full": Set when the node is visible with opacity > 0.0 and is completely onscreen or lies completely
+     *   inside the clippingRect's coordinates.
+     */
+    onRenderTracking?: EventHandler<"disabled" | "none" | "partial" | "full">;
+}

package/src/sg-nodes/group.tsx

@@ -0,0 +1,30 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./group.props";
+import { Component } from "./types";
+export type { IGroupProps } from "./group.props";
+
+/**
+ * Group component - a layout container for organizing and positioning child nodes.
+ *
+ * Group is a layout container node that serves as the base class for organizing and positioning
+ * child nodes in the SceneGraph. It provides transformation, rendering, and clipping capabilities
+ * for managing visual hierarchies.
+ *
+ * @example
+ * ```tsx
+ * <group
+ *     translation={[100, 50]}
+ *     opacity={0.8}
+ * >
+ *     <rectangle width={200} height={100} color="#0000FFFF" />
+ *     <label text="Hello World" />
+ * </group>
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/group}
+ */
+export const Group: Component<IGroupProps> = (props: IGroupProps) => {
+    return <group {...props}></group>;
+};