@roku-sdk/components 0.0.0-stage → 2.19.0

package/src/sg-nodes/array-grid.ts

@@ -0,0 +1,602 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./group.props";
+import type { EventHandler, JSX, Rect2D, ResType, Uri, Vector2D } from "./types";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Focus Animation Style Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Horizontal focus animation style for grid items.
+ *
+ * Specifies how the focus indicator moves in a row of grid items
+ * in response to the remote direction pad Left and Right key presses.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/arraygrid}
+ */
+export enum HorizFocusAnimationStyle {
+    /**
+     * Causes the focus indicator to float left or right until it reaches the end of the row,
+     * at which point the focus indicator will stay fixed on the first or last item in the row,
+     * and the items will scroll left or right if there were items that were not visible.
+     */
+    FloatingFocus = "floatingFocus",
+    /**
+     * Causes the row to wrap around when the focus indicator reaches the first or last item
+     * in the row, as long as the row contains enough items to fill the row. If the row does
+     * not contain enough items to fill the row, the focus indicator will float left and right.
+     */
+    FixedFocusWrap = "fixedFocusWrap"
+}
+
+/**
+ * Vertical focus animation style for list or grid column items.
+ *
+ * Specifies how the focus indicator moves in a list or a column of grid items
+ * in response to the remote direction pad Up and Down key presses.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/arraygrid}
+ */
+export enum VertFocusAnimationStyle {
+    /**
+     * Causes the focus indicator to float up or down until it reaches the end of the list or
+     * grid column, at which point the focus indicator will stay fixed on the first or last item
+     * in the list or grid column, and the items will scroll up or down if there are items that
+     * were not visible. Note that when this style is set, section dividers are not rendered.
+     */
+    FloatingFocus = "floatingFocus",
+    /**
+     * Causes the column to wrap around when the focus indicator reaches the first or last item
+     * in the list or grid column, as long as the list or grid column contains enough items to
+     * fill the list or grid column. If the list or grid column does not contain enough items
+     * to fill the list or grid column, the focus indicator will float up and down.
+     */
+    FixedFocusWrap = "fixedFocusWrap",
+    /**
+     * Causes the focus to stay fixed on the upper leftmost item. As the user scrolls down,
+     * the row containing the previously selected item scrolls up off screen. Scrolling
+     * continues until the last row is reached.
+     */
+    FixedFocus = "fixedFocus"
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ArrayGrid Properties
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Properties for the ArrayGrid abstract node class.
+ *
+ * ArrayGrid is an abstract base class that provides functionality to the list and grid
+ * node classes that are extended from ArrayGrid. The field value settings and their effect
+ * in this abstract base class depend in many cases on whether a list, or a grid, node class
+ * is extended from ArrayGrid, and the specific type of list or grid.
+ *
+ * The following node classes extended from ArrayGrid derive their basic functionality
+ * from the ArrayGrid abstract node class:
+ *
+ * - {@link https://developer.roku.com/dev/docs/labellist LabelList}
+ * - {@link https://developer.roku.com/dev/docs/markuplist MarkupList}
+ * - {@link https://developer.roku.com/dev/docs/postergrid PosterGrid}
+ * - {@link https://developer.roku.com/dev/docs/markupgrid MarkupGrid}
+ * - {@link https://developer.roku.com/dev/docs/rowlist RowList}
+ *
+ * > **Note:** ArrayGrid is not meant to be instantiated directly by app code.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/arraygrid}
+ *
+ * @example Basic grid setup
+ * ```tsx
+ * <MarkupGrid
+ *     itemSize={[300, 200]}
+ *     itemSpacing={[20, 20]}
+ *     numRows={3}
+ *     numColumns={4}
+ *     drawFocusFeedback={true}
+ *     vertFocusAnimationStyle={VertFocusAnimationStyle.FloatingFocus}
+ *     content={gridContent}
+ *     onItemSelected={(event) => handleSelection(event)}
+ * />
+ * ```
+ */
+export interface IArrayGridProps extends IGroupProps {
+    // ─────────────────────────────────────────────────────────────────────────
+    // Content Data
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies the content meta-data for the list or grid.
+     *
+     * This field must be set with a ContentNode that specifies the content meta-data
+     * for the list or grid in order for the list or grid to be displayed.
+     *
+     * See the Data Bindings section of each list or grid reference description for
+     * details on the content meta-data that must be specified in the ContentNode.
+     *
+     * **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/content-metadata}
+     */
+    content?: JSX.Element;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Layout Configuration
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies the width and height of each item in the list or grid.
+     * For list or grid items that are posters, itemSize is the value of a
+     * basePosterSize field and any sub-elements included with the poster.
+     *
+     * @default [0, 0]
+     * @example [300, 200]
+     */
+    itemSize?: ResType<Vector2D>;
+
+    /**
+     * Specifies the horizontal and vertical spacing between the list or grid items.
+     * For lists, the vector2d Y-value specifies the vertical spacing between items
+     * in the list, and the vector2d X-value is ignored.
+     *
+     * @default [0, 0]
+     * @example [20, 10]
+     */
+    itemSpacing?: ResType<Vector2D>;
+
+    /**
+     * Specifies the number of visible rows displayed.
+     * Note that the actual number of rows may be more or less than the number
+     * specified depending on the number of items in the list or grid content.
+     *
+     * @default 0
+     */
+    numRows?: number;
+
+    /**
+     * Specifies the number of columns in a grid.
+     * This field is not used for lists.
+     *
+     * @default 0
+     */
+    numColumns?: number;
+
+    /**
+     * Specifies that a grid will have a layout of items of different widths
+     * configured by parameters included in a ContentNode for the grid.
+     * This field is not used by lists.
+     *
+     * @default false
+     */
+    fixedLayout?: boolean;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Focus Management
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies the row that will have fixed focus if the vertFocusAnimationStyle
+     * field value is set to fixedFocusWrap.
+     *
+     * @default 0
+     */
+    focusRow?: number;
+
+    /**
+     * Specifies the column that will have fixed focus for grids if the
+     * horizFocusAnimationStyle field value is set to fixedFocusWrap.
+     * This field is not used for lists.
+     *
+     * @default 0
+     */
+    focusColumn?: number;
+
+    /**
+     * Specifies how the focus indicator moves in a row of grid items in response
+     * to the remote direction pad Left and Right key presses.
+     * This field is not used for lists.
+     *
+     * @default "floatingFocus"
+     */
+    horizFocusAnimationStyle?: HorizFocusAnimationStyle | `${HorizFocusAnimationStyle}`;
+
+    /**
+     * Specifies how the focus indicator moves in a list or a column of grid items
+     * in response to the remote direction pad Up and Down key presses.
+     *
+     * @default "floatingFocus"
+     */
+    vertFocusAnimationStyle?: VertFocusAnimationStyle | `${VertFocusAnimationStyle}`;
+
+    /**
+     * Specifies whether changes in the focus item should be animated.
+     * If this field is set to true, any scrolling or repositioning/scaling of the
+     * focus indicator occurs without an animation. This causes fields reflecting
+     * the focus status (itemFocused, currFocusRow, currFocusColumn) to be updated
+     * instantly and not transition smoothly between old and new values.
+     *
+     * For example, currFocusRow will go directly from 3.0 to 4.0 instead of
+     * taking on values between 3.0 and 4.0.
+     *
+     * @default false
+     */
+    skipFocusAnimations?: boolean;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Focus Feedback
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Causes a specified bitmap to be drawn on list or grid items to indicate
+     * focus has moved to that item.
+     *
+     * @default true
+     */
+    drawFocusFeedback?: boolean;
+
+    /**
+     * If the drawFocusFeedback field value is set to true, specifies whether the
+     * specified focus indicator bitmap is drawn on top of the focused list or grid items.
+     * The default value draws the specified focus indicator bitmap below the focused
+     * list or grid item.
+     *
+     * @default false
+     */
+    drawFocusFeedbackOnTop?: boolean;
+
+    /**
+     * When set to true, the focus feedback indicator will quickly fade out when
+     * scrolling multiple items and fade back in when the scrolling ends.
+     * The focus feedback indicator will also fade in and out when using the
+     * FFW/Rewind keys to scroll a page at a time.
+     *
+     * @default false
+     */
+    fadeFocusFeedbackWhenAutoScrolling?: boolean;
+
+    /**
+     * If the drawFocusFeedback field value is set to true, specifies a custom bitmap
+     * to be drawn on list or grid items to indicate the focus has moved to that item.
+     * Only set this field to use a bitmap with a different appearance than the system default.
+     *
+     * In most cases, you will want to use a 9-patch PNG bitmap with both expandable
+     * regions as well as margins to fit around the item.
+     *
+     * @example "pkg:/images/focus.9.png"
+     */
+    focusBitmapUri?: Uri;
+
+    /**
+     * If the drawFocusFeedback field value is set to true, specifies a custom bitmap
+     * to be drawn on list or grid items to indicate focus on that item, when the list
+     * or grid itself does not have focus.
+     *
+     * In most cases, you will want to use a 9-patch PNG bitmap with both expandable
+     * regions as well as margins to fit around the item.
+     *
+     * @example "pkg:/images/focus-footprint.9.png"
+     */
+    focusFootprintBitmapUri?: Uri;
+
+    /**
+     * Blend the graphic image specified by focusBitmapUri with the specified color.
+     * If set to the default, 0xFFFFFFFF, no color blending will occur.
+     *
+     * @default "0xFFFFFFFF"
+     * @example "0x0066FFFF"
+     */
+    focusBitmapBlendColor?: string;
+
+    /**
+     * Blend the graphic image specified by focusFootprintBitmapUri with the specified color.
+     * If set to the default, 0xFFFFFFFF, no color blending will occur.
+     *
+     * @default "0xFFFFFFFF"
+     * @example "0x666666FF"
+     */
+    focusFootprintBlendColor?: string;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Wrap Divider
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * If the vertFocusAnimationStyle field value is set to fixedFocusWrap, specifies
+     * a custom bitmap to use as a visual divider between the last and first list or
+     * grid items, when the list or grid wraps.
+     *
+     * In most cases, you will want to use a 9-patch PNG bitmap with both expandable regions.
+     *
+     * @example "pkg:/images/wrap-divider.9.png"
+     */
+    wrapDividerBitmapUri?: Uri;
+
+    /**
+     * If the vertFocusAnimationStyle field value is set to fixedFocusWrap, specifies
+     * the width of a bitmap used as a visual divider between the last and first list
+     * or grid items when the list or grid wraps.
+     *
+     * @default 0
+     */
+    wrapDividerWidth?: number;
+
+    /**
+     * If the vertFocusAnimationStyle field value is set to fixedFocusWrap, specifies
+     * the height of a bitmap used as a visual divider between the last and first list
+     * or grid items, when the list or grid wraps.
+     *
+     * @default 36
+     */
+    wrapDividerHeight?: number;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Variable Row/Column Sizing
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies differing heights for each list or grid row, to allow the height
+     * of each row to vary from row to row.
+     *
+     * The specified values override the itemSize field vector2d Y-value for each
+     * list or grid row corresponding to its position in the array, in top to bottom order.
+     *
+     * @default []
+     * @example [100, 150, 100, 200]
+     */
+    rowHeights?: number[];
+
+    /**
+     * Specifies differing widths for each grid column, to allow the width of each
+     * column to vary from column to column.
+     * This field is not used by lists.
+     *
+     * @default []
+     * @example [200, 300, 200, 250]
+     */
+    columnWidths?: number[];
+
+    /**
+     * Specifies differing spaces between each list or grid row, to allow the spacing
+     * between rows to vary from row to row.
+     *
+     * @default []
+     * @example [10, 20, 10, 15]
+     */
+    rowSpacings?: number[];
+
+    /**
+     * Specifies differing spaces between each grid column, to allow the spacing between
+     * columns to vary from column to column.
+     * This field is not used by lists.
+     *
+     * @default []
+     * @example [10, 15, 10, 20]
+     */
+    columnSpacings?: number[];
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Section Divider
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * If the ContentNode specifies sections for a list or grid, specifies a custom
+     * bitmap to use as a visual divider between the sections of the list or grid.
+     *
+     * @example "pkg:/images/section-divider.9.png"
+     */
+    sectionDividerBitmapUri?: Uri;
+
+    /**
+     * If the ContentNode specifies sections for a list or grid, specifies a custom
+     * font to use for the section title text.
+     *
+     * @example "pkg:/fonts/SectionTitle.ttf"
+     */
+    sectionDividerFont?: string;
+
+    /**
+     * If the ContentNode specifies sections for a list or grid, specifies a custom
+     * color to use for the section title text.
+     *
+     * @example "0xFFFFFFFF"
+     */
+    sectionDividerTextColor?: string;
+
+    /**
+     * If the ContentNode specifies sections for a list or grid, specifies the
+     * spacing between the icon, label, and section divider bitmap.
+     *
+     * @default 0
+     */
+    sectionDividerSpacing?: number;
+
+    /**
+     * If the ContentNode specifies sections for a list or grid, specifies the
+     * width of the section divider bitmap.
+     *
+     * @default 0
+     */
+    sectionDividerWidth?: number;
+
+    /**
+     * If the ContentNode specifies sections for a list or grid, specifies the
+     * height of the section divider bitmap.
+     *
+     * @default 0
+     */
+    sectionDividerHeight?: number;
+
+    /**
+     * If the ContentNode specifies sections for a list or grid, specifies the
+     * minimum width of the section divider bitmap.
+     *
+     * @default 0
+     */
+    sectionDividerMinWidth?: number;
+
+    /**
+     * If the ContentNode specifies sections for a list or grid, specifies the
+     * left offset of the section divider from the list or grid.
+     *
+     * @default 0
+     */
+    sectionDividerLeftOffset?: number;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Rendering Configuration
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Specifies the number of rendering operations to display a complex list or grid.
+     *
+     * This allows you to achieve a performance increase by specifying that individual
+     * sub-elements of the list or grid items occur on sequential rendering operations.
+     *
+     * @default 1
+     */
+    numRenderPasses?: number;
+
+    /**
+     * Specifies a clipping region for the list or grid items.
+     *
+     * @default [0.0, 0.0, 0.0, 0.0]
+     */
+    itemClippingRect?: Rect2D;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Selection and Navigation
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * When set to a valid item index, causes the list or grid to immediately update
+     * so that the item at the specified index moves into focus.
+     *
+     * **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
+     * <LabelList
+     *     content={content}
+     *     jumpToItem={jumpToItem}
+     *     ...
+     * />
+     * ```
+     *
+     * @writeonly
+     * @default 0
+     */
+    jumpToItem?: number;
+
+    /**
+     * When set to a valid item index, causes the list or grid to quickly scroll
+     * so that the item at the specified index moves into focus.
+     *
+     * **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
+     * <LabelList
+     *     content={content}
+     *     animateToItem={animateToItem}
+     *     ...
+     * />
+     * ```
+     *
+     * @writeonly
+     * @default 0
+     */
+    animateToItem?: number;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Event Outputs (Read-Only)
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * When a list or grid item is selected, set to the index of the selected item.
+     *
+     * @readonly
+     * @default 0
+     */
+    itemSelected?: number;
+
+    /** Event fired when a list or grid item is selected. */
+    onItemSelected?: EventHandler<number>;
+
+    /**
+     * When focus moves to a list or grid item, set to the index of the focused item.
+     *
+     * @readonly
+     * @default 0
+     */
+    itemFocused?: number;
+
+    /** Event fired when focus moves to a list or grid item. */
+    onItemFocused?: EventHandler<number>;
+
+    /**
+     * When focus moves away from a list or grid item, set to the index of the unfocused item.
+     *
+     * @readonly
+     * @default 0
+     */
+    itemUnfocused?: number;
+
+    /** Event fired when focus moves away from a list or grid item. */
+    onItemUnfocused?: EventHandler<number>;
+
+    /**
+     * Current opacity of the focus feedback indicator (read-only).
+     *
+     * @readonly
+     * @default 0
+     */
+    currFocusFeedbackOpacity?: number;
+
+    /** Event fired when the current focus feedback opacity changes. */
+    onCurrFocusFeedbackOpacityChange?: EventHandler<number>;
+
+    /**
+     * Current opacity of the focus feedback indicator (writable).
+     *
+     * @default 0
+     */
+    itemcurrFocusFeedbackOpacity?: number;
+
+    /**
+     * Which row of a grid is in the focus position as the items scroll around.
+     * Example: `currFocusRow = 3.7` means item 3 occupies 30% and item 4 occupies 70%.
+     *
+     * @default 0.0
+     */
+    currFocusRow?: number;
+
+    /** Event fired when the current focus row changes. */
+    onCurrFocusRowChange?: EventHandler<number>;
+
+    /**
+     * Which column of a grid is in the focus position as the items scroll around.
+     *
+     * @default 0.0
+     */
+    currFocusColumn?: number;
+
+    /** Event fired when the current focus column changes. */
+    onCurrFocusColumnChange?: EventHandler<number>;
+
+    /**
+     * Which section of a grid is in the focus position as the items scroll around.
+     *
+     * @default 0.0
+     */
+    currFocusSection?: number;
+
+    /** Event fired when the current focus section changes. */
+    onCurrFocusSectionChange?: EventHandler<number>;
+}