@roku-sdk/components 0.0.0-stage → 2.18.0

package/src/sg-nodes/voice-text-edit-box.props.ts

@@ -0,0 +1,91 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./group.props";
+import type { EventHandler } from "./types";
+
+/**
+ * Properties for the legacy TextEditBox fields exposed by {@link VoiceTextEditBox}.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/texteditbox}
+ */
+export interface ITextEditBoxProps extends IGroupProps {
+    /** Current text displayed in the edit box. */
+    text: string;
+    /** Placeholder text shown when the edit box is empty. */
+    hintText: string;
+    /** Maximum number of characters that may be entered. */
+    maxTextLength: number;
+    /** Zero-based cursor position within the text string. */
+    cursorPosition: number;
+    /** When true, pressing Down clears the text field. */
+    clearOnDownKey: boolean;
+    /** When true, the edit box accepts focus and key input. */
+    active: boolean;
+    /** When true, entered characters are masked (for passwords/PINs). */
+    secureMode: boolean;
+    /** Color of the entered text. */
+    textColor: string | number;
+    /** Color of the hint text. */
+    hintTextColor: string | number;
+    /** Width of the voice-enabled text box. */
+    voiceTextBoxWidth: number;
+    /** Background image URI for the text box. */
+    backgroundUri: string;
+    /** When true, truncates long text with a leading ellipsis. */
+    leadingEllipsis: boolean;
+}
+
+/**
+ * Properties for the {@link VoiceTextEditBox} component.
+ *
+ * VoiceTextEditBox is similar to the legacy TextEditBox node but adds voice entry
+ * functionality. Only one voice-enabled VoiceTextEditBox may be on screen at a time.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/voice-text-edit-box}
+ *
+ * @example
+ * ```tsx
+ * <VoiceTextEditBox
+ *   id="search-input"
+ *   text={query()}
+ *   hintText="Search…"
+ *   maxTextLength={64}
+ *   cursorPosition={query().length}
+ *   clearOnDownKey={false}
+ *   active
+ *   secureMode={false}
+ *   textColor="0xFFFFFFFF"
+ *   hintTextColor="0x888888FF"
+ *   voiceTextBoxWidth={800}
+ *   backgroundUri=""
+ *   leadingEllipsis={false}
+ *   voiceEnabled
+ *   voiceEntryType="generic"
+ *   onText={setQuery}
+ * />
+ * ```
+ */
+export interface IVoiceTextEditBoxProps extends ITextEditBoxProps {
+    /**
+     * Enables voice entry for the text box (mic icon and voice hints).
+     * @default false
+     */
+    voiceEntryType?: string;
+    /** When true, voice entry is enabled. */
+    voiceEnabled?: boolean;
+    /**
+     * Maximum width of the voice hint tooltip.
+     * @default FHD: 321, HD: 214
+     */
+    voiceToolTipWidth?: number;
+    /** Fired when dictation starts or stops. */
+    onIsDictating?: EventHandler<boolean>;
+    /**
+     * Regex filter restricting characters entered via dictation.
+     * Write-only on the native node.
+     */
+    voiceInputRegexFilter?: string;
+    /** Fired when the text value changes. */
+    onText?: EventHandler<string>;
+}

package/src/sg-nodes/voice-text-edit-box.tsx

@@ -0,0 +1,15 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { Component } from "./types";
+import type { IVoiceTextEditBoxProps } from "./voice-text-edit-box.props";
+export type { ITextEditBoxProps, IVoiceTextEditBoxProps } from "./voice-text-edit-box.props";
+
+/**
+ * Voice-enabled text edit box for standalone text entry (not inside a dialog).
+ *
+ * @see {@link https://developer.roku.com/dev/docs/voice-text-edit-box}
+ */
+export const VoiceTextEditBox: Component<IVoiceTextEditBoxProps> = props => {
+    return <voiceTextEditBox {...props}></voiceTextEditBox>;
+};

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

@@ -0,0 +1,416 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./group.props";
+import type { RowItemPosition, RowListItemEventHandler } from "./row-list.props";
+import type { EventHandler, FontValue, JSX, Rect2D, Uri, Vector2D } from "./types";
+
+/**
+ * Controls whether rows above the focus row remain zoomed or unzoom as they scroll.
+ *
+ * - `focusIsAtTop`: when itemClippingRect top is 0, rows remain zoomed as they enter/exit from above
+ * - `never`: rows zoom up/down as they enter/exit the focus region from above
+ * - `always`: rows always remain zoomed as they enter/exit from above
+ *
+ * @default "focusIsAtTop"
+ */
+export type RemainZoomedAboveFocus = "focusIsAtTop" | "never" | "always";
+
+/**
+ * Controls whether rows above the focus row fade in/out as they scroll.
+ *
+ * - `focusIsAtTop`: when itemClippingRect top is 0, rows fade as they enter/exit from above
+ * - `never`: rows do not fade as they enter/exit from above
+ * - `always`: rows always fade as they enter/exit from above
+ *
+ * @default "focusIsAtTop"
+ */
+export type FadeOutAboveFocus = "focusIsAtTop" | "never" | "always";
+
+/**
+ * Properties for the ZoomRowList node.
+ *
+ * ZoomRowList allows a row of the Row-Row Grid to smoothly zoom up to a larger size when that row
+ * has focus. Rows are capable of gaining focus while scrolling and smoothly zooming by the specified
+ * amount. The amount to zoom can be specified on a per-row basis.
+ *
+ * ZoomRowList extends Group and uses the same data model as RowList: a root ContentNode with child
+ * ContentNodes for each row, each containing child ContentNodes for each item.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/zoomrowlist}
+ *
+ * @example
+ * ```tsx
+ * import "./compiled-components/MyRowItem.xml";
+ *
+ * <ZoomRowList
+ *     itemComponentName="MyRowItem"
+ *     rowWidth={1920}
+ *     rowHeight={[120, 120, 120]}
+ *     rowZoomHeight={[200, 200, 200]}
+ *     rowItemHeight={[100, 100, 100]}
+ *     rowItemZoomHeight={[180, 180, 180]}
+ *     rowItemAspectRatio={[1.777]}
+ *     content={listContent}
+ *     onRowItemFocused={([row, col]) => setFocus(row, col)}
+ *     onRowItemSelected={([row, col]) => navigate(row, col)}
+ * />
+ * ```
+ */
+export interface IZoomRowListProps extends IGroupProps {
+    // ─────────────────────────────────────────────────────────────────────────
+    // Content
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies the content for the ZoomRowList.
+     *
+     * 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/zoomrowlist#zoomrowlist-data-model}
+     */
+    content: JSX.Element;
+
+    /**
+     * Specifies the name of the compiled component used to render each row item.
+     *
+     * Register the compiled component by importing its XML file before use.
+     * The component may define: width, height, index, rowIndex, itemHasFocus,
+     * rowHasFocus, rowListHasFocus, itemContent, focusPercent, rowFocusPercent, rowHeightPercent.
+     *
+     * @example "MyRowItem"
+     */
+    itemComponentName?: string;
+
+    /**
+     * Specifies the name of an XML component to decorate each row.
+     * An instance is created for each visible row.
+     *
+     * @example "MyRowDecoration"
+     */
+    rowDecorationComponentName?: string[];
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Layout
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies the maximum width of items in each row before items wrap.
+     * Also used for Row Counter positioning.
+     *
+     * @default 0
+     */
+    rowWidth?: number;
+
+    /**
+     * Specifies the height of each ZoomRowItem when the row is not zoomed.
+     * At least one value must be specified.
+     *
+     * @example [120, 120, 120]
+     */
+    rowHeight?: number[];
+
+    /**
+     * Specifies the height of each ZoomRowItem when the row is zoomed.
+     * If not specified, rows do not zoom.
+     *
+     * @example [200, 200, 200]
+     */
+    rowZoomHeight?: number[];
+
+    /**
+     * Specifies the spacing between rows. Not scaled by zoom.
+     *
+     * @default 0
+     */
+    spacingAfterRow?: number;
+
+    /**
+     * Specifies a clipping region for the ZoomRowItem renders.
+     * For best performance, set to match what's visible onscreen.
+     *
+     * @default [0, 0, 0, 0]
+     */
+    itemClippingRect?: Rect2D;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Row Item Sizing
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Vertical position of the Row relative to the top of its ZoomRowItem when unfocused.
+     *
+     * @example [0, 0, 0]
+     */
+    rowItemYOffset?: number[];
+
+    /**
+     * Vertical position of the Row relative to the top of its ZoomRowItem when focused (zoomed).
+     *
+     * @example [10, 10, 10]
+     */
+    rowItemZoomYOffset?: number[];
+
+    /**
+     * Height of each Item in a Row when the row is unfocused.
+     *
+     * @example [100, 100, 100]
+     */
+    rowItemHeight?: number[];
+
+    /**
+     * Height of each Item in a Row when the row is focused (zoomed).
+     *
+     * @example [180, 180, 180]
+     */
+    rowItemZoomHeight?: number[];
+
+    /**
+     * Aspect ratio of Items in each Row (width/height).
+     * Used to compute item width from interpolated height.
+     * E.g. 16:9 = 1.7777778.
+     *
+     * @example [1.7777778]
+     */
+    rowItemAspectRatio?: number[];
+
+    /**
+     * Horizontal spacing between Items in each Row.
+     * Scales with zoom as the row gains focus.
+     *
+     * @example [20, 20, 20]
+     */
+    spacingAfterRowItem?: number[];
+
+    /**
+     * If true, use rowItemAspectRatio for all items. If false, use aspectRatio
+     * from each item's ContentNode when available.
+     *
+     * @example [true, true, true]
+     */
+    useDefaultAspectRatio?: boolean[];
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Row Title and Counter
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies whether the row title is displayed for each row.
+     *
+     * @example [true, true, true]
+     */
+    showRowTitle?: boolean[];
+
+    /**
+     * Offset of the Row Title for each row. [x, y] from left edge and top.
+     *
+     * @example [[0, 0], [0, 10]]
+     */
+    rowTitleOffset?: Vector2D[];
+
+    /**
+     * Font for the Row Title text.
+     */
+    rowTitleFont?: FontValue;
+
+    /**
+     * Color of the Row Title text for each row.
+     *
+     * @example ["0xffffffff"]
+     */
+    rowTitleColor?: string[];
+
+    /**
+     * Specifies whether each row's Row Counter is displayed.
+     *
+     * @example [true, true, true]
+     */
+    showRowCounter?: boolean[];
+
+    /**
+     * Offset of the Row Counter for each row. X is right edge position (right-aligned).
+     *
+     * @example [[1920, 0]]
+     */
+    rowCounterOffset?: Vector2D[];
+
+    /**
+     * Font for the Row Counter text.
+     */
+    rowCounterFont?: FontValue;
+
+    /**
+     * Color of the Row Counter text for each row.
+     *
+     * @example ["0xffffffff"]
+     */
+    rowCounterColor?: string[];
+
+    /**
+     * When true, Row Counter is shown for all rows. When false, not shown for
+     * rows where total zoomed width of items is less than rowWidth.
+     *
+     * @default true
+     */
+    showRowCounterForShortRows?: boolean;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Focus Feedback
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * If true, the focus feedback indicator is drawn.
+     *
+     * @default true
+     */
+    drawFocusFeedback?: boolean;
+
+    /**
+     * If true, the focus feedback indicator is drawn on top of the items.
+     *
+     * @default true
+     */
+    drawFocusFeedbackOnTop?: boolean;
+
+    /**
+     * If true, focus indicator fades out during long-press scrolling.
+     *
+     * @default true
+     */
+    fadeFocusFeedbackWhenLongPressScrolling?: boolean;
+
+    /**
+     * Bitmap file for the focus feedback indicator.
+     * Use 9-patch for expandable regions and margins.
+     */
+    focusBitmapUri?: Uri;
+
+    /**
+     * Blend color for the focus bitmap.
+     *
+     * @default "0xFFFFFFFF"
+     */
+    focusBitmapBlendColor?: string;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Wrap Divider
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * If true, items wrap from bottom to top.
+     *
+     * @default true
+     */
+    wrap?: boolean;
+
+    /**
+     * Bitmap file for the wrap divider between last and first items.
+     */
+    wrapDividerBitmapUri?: Uri;
+
+    /**
+     * Blend color for the wrap divider bitmap.
+     *
+     * @default "0xFFFFFFFF"
+     */
+    wrapDividerBitmapBlendColor?: string;
+
+    /**
+     * Height of the wrap divider bitmap.
+     *
+     * @default 0
+     */
+    wrapDividerHeight?: number;
+
+    /**
+     * Width of the wrap divider bitmap. Defaults to rowWidth if not specified.
+     *
+     * @default 0
+     */
+    wrapDividerWidth?: number;
+
+    /**
+     * Offset to adjust the wrap divider position from its default.
+     *
+     * @default [0, 0]
+     */
+    wrapDividerOffset?: Vector2D;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Zoom Behavior
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Controls whether rows above the focus row remain zoomed as they scroll.
+     *
+     * @default "focusIsAtTop"
+     */
+    remainZoomedAboveFocus?: RemainZoomedAboveFocus;
+
+    /**
+     * Controls whether rows above the focus row fade in/out as they scroll.
+     *
+     * @default "focusIsAtTop"
+     */
+    fadeOutAboveFocus?: FadeOutAboveFocus;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Navigation
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * When set to a valid row index, immediately moves focus to that row.
+     *
+     * @see {@link https://developer.roku.com/dev/docs/zoomrowlist}
+     */
+    jumpToRow?: number;
+
+    /**
+     * When set to a valid [rowIndex, itemIndex], immediately moves focus to that item.
+     *
+     * @example [2, 0]
+     */
+    jumpToRowItem?: RowItemPosition;
+
+    /**
+     * When set to a valid row index, scrolls to bring that row into focus.
+     *
+     * @see {@link https://developer.roku.com/dev/docs/zoomrowlist}
+     */
+    animateToRow?: number;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // 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;
+
+    /**
+     * Fired when a row is selected.
+     * Receives the index of the selected row.
+     */
+    onRowSelected?: EventHandler<number>;
+
+    /**
+     * Fired when a row gains focus.
+     * Receives the index of the focused row.
+     */
+    onRowFocused?: EventHandler<number>;
+
+    /**
+     * Fired when a row loses focus.
+     * Receives the index of the unfocused row.
+     */
+    onRowUnfocused?: EventHandler<number>;
+}

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

@@ -0,0 +1,42 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { Component } from "./types";
+import type { IZoomRowListProps } from "./zoom-row-list.props";
+export type { RemainZoomedAboveFocus, FadeOutAboveFocus, IZoomRowListProps } from "./zoom-row-list.props";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ZoomRowList Properties
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Re-export for consumers
+export type { RowItemPosition, RowListItemEventHandler } from "./row-list";
+
+/**
+ * ZoomRowList displays a vertically scrolling list of rows where the focused row
+ * smoothly zooms to a larger size. Each row scrolls horizontally through its items.
+ * Item rendering is delegated to compiled components specified by itemComponentName.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/zoomrowlist}
+ *
+ * @example
+ * ```tsx
+ * import "./compiled-components/MyRowItem.xml";
+ *
+ * <zoomRowList
+ *     itemComponentName="MyRowItem"
+ *     rowWidth={1920}
+ *     rowHeight={[120, 120, 120]}
+ *     rowZoomHeight={[200, 200, 200]}
+ *     rowItemHeight={[100, 100, 100]}
+ *     rowItemZoomHeight={[180, 180, 180]}
+ *     rowItemAspectRatio={[1.777]}
+ *     content={listContent}
+ *     onRowItemFocused={([row, col]) => setFocus(row, col)}
+ *     onRowItemSelected={([row, col]) => navigate(row, col)}
+ * />
+ * ```
+ */
+export const ZoomRowList: Component<IZoomRowListProps> = props => {
+    return <zoomRowList {...props}></zoomRowList>;
+};