@roku-sdk/components 0.0.0-stage → 2.18.0

package/src/sg-nodes/time-grid.props.ts

@@ -0,0 +1,646 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IArrayGridProps } from "./array-grid";
+import type { EventHandler, FontValue, Uri } from "./types";
+
+/**
+ * A tuple of `[channelIndex, programIndex]` identifying a specific program within a TimeGrid.
+ */
+export type TimeGridItemPosition = [number, number];
+
+/**
+ * Event handler for TimeGrid item events, receiving the `[channelIndex, programIndex]`
+ * of the item that triggered the event.
+ */
+export type TimeGridItemEventHandler = EventHandler<TimeGridItemPosition>;
+
+/**
+ * General TimeGrid settings that configure the overall time range,
+ * scrollable extent, and overlay appearance.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/timegrid#general-timegrid-settings}
+ */
+export interface ITimeGridGeneralProps {
+    /**
+     * The earliest time (in epoch seconds) that the TimeGrid can be scrolled to.
+     * The scrollable range is defined by the sum of `contentStartTime` and `maxDays`.
+     *
+     * @default 0
+     */
+    contentStartTime?: number;
+
+    /**
+     * Width (in seconds) of the visible section of the time grid.
+     * For example, 10800 displays a 3-hour window (10,800 = 3 * 3,600).
+     *
+     * @default 9000
+     */
+    duration?: number;
+
+    /**
+     * The total width of the TimeGrid in days.
+     *
+     * @default 7
+     */
+    maxDays?: number;
+
+    /**
+     * Time (in seconds) before the TimeGrid is automatically hidden.
+     * Setting to 0 prevents auto-hiding.
+     *
+     * @default 0
+     */
+    autoDismissTime?: number;
+
+    /**
+     * When true, ignores fast forward, rewind, and instant replay key events.
+     * FF/RW normally page the grid up/down; instant replay jumps to the current time.
+     *
+     * @default false
+     */
+    ignoreTrickPlayKeys?: boolean;
+
+    /**
+     * Bitmap URI for an overlay drawn on top of the entire time grid.
+     * Used by default to make bottom rows appear to fade out.
+     * In most cases, use a 9-patch image that specifies expandable regions.
+     *
+     * The overlay is drawn at full grid width with its bottom aligned to the grid bottom.
+     * If `overlayHeight` is greater than 0, the image is stretched to that height.
+     */
+    overlayBitmapUri?: Uri;
+
+    /**
+     * Height of the overlay image. If 0, the overlay is drawn at its default height.
+     *
+     * @default 0
+     */
+    overlayHeight?: number;
+}
+
+/**
+ * Channel-level navigation, focus, and selection settings.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/timegrid#app-settings}
+ */
+export interface ITimeGridChannelProps {
+    /**
+     * When explicitly set, triggers a horizontal scrolling animation so that the
+     * specified time is displayed at the left edge of the program grid.
+     *
+     * Also set by the firmware in response to remote control key presses that
+     * cause horizontal scrolling.
+     */
+    leftEdgeTargetTime?: number;
+
+    /**
+     * Write-only. Jumps the grid so the row corresponding to the specified
+     * channel index is on screen. The program in that row at the current
+     * focus time will have focus.
+     *
+     * @writeonly
+     */
+    jumpToChannel?: number;
+
+    /**
+     * Write-only. Scrolls the grid with animation so the row corresponding
+     * to the specified channel index is on screen. When scrolling ends,
+     * the program in that row at the current focus time will have focus.
+     *
+     * @writeonly
+     */
+    animateToChannel?: number;
+
+    /**
+     * Write-only. Jumps the grid to the program at the specified time (in UTC format).
+     * After the jump, the time will be visible and the program on the currently
+     * focused channel will have focus.
+     *
+     * @writeonly
+     */
+    jumpToTime?: string;
+
+    /**
+     * Index of the selected channel (read-only, set on program selection).
+     *
+     * @readonly
+     */
+    channelSelected?: number;
+
+    /** Fired when a channel is selected. */
+    onChannelSelected?: EventHandler<number>;
+
+    /**
+     * Index of the focused channel when a program in the channel's row gains focus.
+     *
+     * @readonly
+     */
+    channelFocused?: number;
+
+    /** Fired when the focused channel changes. */
+    onChannelFocused?: EventHandler<number>;
+
+    /**
+     * Index of the focused channel when a program in the channel's row loses focus.
+     *
+     * @readonly
+     */
+    channelUnfocused?: number;
+
+    /** Fired when a channel loses focus. */
+    onChannelUnfocused?: EventHandler<number>;
+}
+
+/**
+ * Configuration for the channel information column displayed on the left
+ * (or right) side of the EPG that lists channel names/logos.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/timegrid#channel-information-column}
+ */
+export interface ITimeGridChannelInfoProps {
+    /**
+     * Name of the compiled component used to render each channel info cell.
+     * The component's `content` field receives channel data.
+     *
+     * If not specified, the default channel info is displayed (optional icon + label).
+     */
+    channelInfoComponentName?: string;
+
+    /**
+     * Name of the compiled component shown when a channel has no program data.
+     */
+    channelNoDataComponentName?: string;
+
+    /**
+     * Width of the channel info column, in pixels.
+     */
+    channelInfoWidth?: number;
+
+    /**
+     * Spacing between the channel information column and the main grid.
+     *
+     * @default 0
+     */
+    infoGridGap?: number;
+
+    /**
+     * Text used as a label for the header of the channel information column.
+     * If not specified, the label shows the day of the week at the left edge.
+     */
+    channelInfoColumnLabel?: string;
+
+    /**
+     * Text color for channel names when `channelInfoComponentName` is not specified.
+     */
+    channelInfoTextColor?: string;
+
+    /**
+     * Font for channel names when `channelInfoComponentName` is not specified.
+     */
+    channelInfoFont?: FontValue;
+
+    /**
+     * Bitmap file used as the background for channel names when
+     * `channelInfoComponentName` is not specified.
+     * In most cases, use a 9-patch image that specifies expandable regions.
+     */
+    channelInfoBackgroundBitmapUri?: Uri;
+
+    /**
+     * Controls the position of the channel info column.
+     *
+     * @default "left"
+     */
+    channelInfoAlignment?: "left" | "right";
+
+    /**
+     * Whether the user can move focus into the channel information column.
+     * If false, the column is non-interactive.
+     *
+     * @default false
+     */
+    channelInfoFocusable?: boolean;
+
+    /**
+     * Write-only. Jumps the grid to the channel info box of the specified
+     * channel index. Ignored if `channelInfoFocusable` is false.
+     *
+     * @writeonly
+     */
+    jumpToChannelInfo?: number;
+
+    /**
+     * Bitmap displayed behind the focused channel info item.
+     */
+    channelFocusedBitmapUri?: Uri;
+
+    /**
+     * Bitmap displayed behind unfocused channel info items.
+     */
+    channelUnFocusedBitmapUri?: Uri;
+
+    /**
+     * Index of the selected channel in the channel information column.
+     *
+     * @readonly
+     */
+    channelInfoSelected?: number;
+
+    /** Fired when a channel info item is selected. */
+    onChannelInfoSelected?: EventHandler<number>;
+
+    /**
+     * Index of the channel when a channel info item gains focus.
+     *
+     * @readonly
+     */
+    channelInfoFocused?: number;
+
+    /** Fired when a channel info item gains focus. */
+    onChannelInfoFocused?: EventHandler<number>;
+
+    /**
+     * Index of the channel when a channel info item loses focus.
+     *
+     * @readonly
+     */
+    channelInfoUnfocused?: number;
+
+    /** Fired when a channel info item loses focus. */
+    onChannelInfoUnfocused?: EventHandler<number>;
+}
+
+/**
+ * Focused details for a program in the TimeGrid, combining the channel
+ * index and program index into a single object.
+ */
+export interface ITimeGridProgramFocusedDetails {
+    focusChannelIndex: number;
+    focusIndex: number;
+}
+
+/**
+ * Configuration for program titles, cells, data loading, and program
+ * focus/selection events in the EPG grid.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/timegrid#program-grid}
+ */
+export interface ITimeGridProgramGridProps {
+    /**
+     * Name of the compiled component used to render focused program details.
+     */
+    programInfoComponentName?: string;
+
+    /**
+     * Text color for unfocused program titles.
+     *
+     * @example "0xFFFFFFFF"
+     */
+    programTitleColor?: string;
+
+    /**
+     * Text color for the focused program title.
+     *
+     * @example "0x000000FF"
+     */
+    programTitleFocusedColor?: string;
+
+    /**
+     * Font for program titles.
+     */
+    programTitleFont?: FontValue;
+
+    /**
+     * Bitmap file used as the background for program cells.
+     * In most cases, use a 9-patch image that specifies expandable regions.
+     */
+    programBackgroundBitmapUri?: Uri;
+
+    /**
+     * Width of the left and right margins of program cell text, in pixels.
+     *
+     * @default 14
+     */
+    programHorizMargin?: number;
+
+    /**
+     * When true, inserts a placeholder cell with the "No Data Available" label
+     * if there is a gap between a program's start time and the previous program's end time.
+     *
+     * @default false
+     */
+    fillProgramGaps?: boolean;
+
+    /**
+     * When true, the program data region is automatically replaced with the
+     * loading message whenever content has not been set or the user scrolls
+     * to a time where content has not yet been loaded.
+     *
+     * @default true
+     */
+    automaticLoadingDataFeedback?: boolean;
+
+    /**
+     * When true, replaces the program data region with the loading message.
+     * Enables explicit control over when the loading message is displayed.
+     * Ignored if `automaticLoadingDataFeedback` is true.
+     *
+     * @default false
+     */
+    showLoadingDataFeedback?: boolean;
+
+    /**
+     * Text displayed over the program grid when the loading message is shown.
+     *
+     * @default "Loading Data..."
+     */
+    loadingDataText?: string;
+
+    /**
+     * Text displayed on each channel row when no data exists for a specific time.
+     *
+     * @default "No Data Available"
+     */
+    channelNoDataText?: string;
+
+    /**
+     * Write-only. Jumps the grid to the program at the specified index
+     * for the currently focused row.
+     *
+     * @writeonly
+     */
+    jumpToProgram?: number;
+
+    /**
+     * Index of the selected program in the currently focused channel row (read-only, set on OK press).
+     *
+     * @readonly
+     */
+    programSelected?: number;
+
+    /** Fired when a program is selected. */
+    onProgramSelected?: EventHandler<number>;
+
+    /**
+     * Index of the focused program in the currently focused channel row.
+     *
+     * @readonly
+     */
+    programFocused?: number;
+
+    /** Fired when the focused program changes. */
+    onProgramFocused?: EventHandler<number>;
+
+    /**
+     * Index of the program in the currently focused channel row when it loses focus.
+     *
+     * @readonly
+     */
+    programUnfocused?: number;
+
+    /** Fired when a program loses focus. */
+    onProgramUnfocused?: EventHandler<number>;
+
+    /**
+     * Combined channel index and program index when a program gains focus.
+     * Provides the same values as `channelFocused` and `programFocused` in a single object.
+     *
+     * @readonly
+     */
+    programFocusedDetails?: ITimeGridProgramFocusedDetails;
+
+    /** Fired when program focused details change. */
+    onProgramFocusedDetails?: EventHandler<ITimeGridProgramFocusedDetails>;
+}
+
+/**
+ * Configuration for the solid color background drawn behind all programs
+ * airing before the current time.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/timegrid#past-time-screen}
+ */
+export interface ITimeGridPastTimeScreenProps {
+    /**
+     * When true, draws a solid color background behind all programs
+     * airing before the current time.
+     *
+     * @default true
+     */
+    showPastTimeScreen?: boolean;
+
+    /**
+     * Tints the past time screen by multiplying each pixel by this color.
+     * No blending is performed if set to the default value.
+     *
+     * @default "0xFFFFFFFF"
+     */
+    pastTimeScreenBlendColor?: string;
+
+    /**
+     * Bitmap file displayed in the background of the past time screen.
+     */
+    pastTimeScreenBitmapUri?: Uri;
+}
+
+/**
+ * Configuration for the time bar displayed horizontally above the program cells.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/timegrid#time-bar}
+ */
+export interface ITimeGridTimeBarProps {
+    /**
+     * Height of the time bar region above the channel grid, in pixels.
+     *
+     * @default 50
+     */
+    timeBarHeight?: number;
+
+    /**
+     * Background color for the time bar.
+     *
+     * @example "0x111111FF"
+     */
+    timeBarBackgroundColor?: string;
+
+    /**
+     * Bitmap file used as the background of the time bar.
+     * In most cases, use a 9-patch image that specifies expandable regions.
+     */
+    timeBarBitmapUri?: Uri;
+
+    /**
+     * Text color for the time labels displayed in the time bar.
+     *
+     * @default "0xffffff99"
+     */
+    timeLabelColor?: string;
+
+    /**
+     * Font for the time labels displayed in the time bar.
+     */
+    timeLabelFont?: FontValue;
+
+    /**
+     * Offset from the edge of the grid of the leftmost time label, in pixels.
+     *
+     * @default 14
+     */
+    timeLabelOffset?: number;
+}
+
+/**
+ * Configuration for the thin vertical bar displayed at the current time.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/timegrid#now-bar}
+ */
+export interface ITimeGridNowBarProps {
+    /**
+     * Width of the Now Bar, in pixels.
+     */
+    nowBarWidth?: number;
+
+    /**
+     * Height of the Now Bar, in pixels.
+     */
+    nowBarHeight?: number;
+
+    /**
+     * Bitmap file used for the Now Bar.
+     * In most cases, use a 9-patch image that specifies expandable regions.
+     */
+    nowBarBitmapUri?: Uri;
+
+    /**
+     * Tints the Now Bar by multiplying each pixel by this color.
+     * No blending is performed if set to the default value.
+     *
+     * @example "0x6600FFFF"
+     */
+    nowBarBlendColor?: string;
+
+    /**
+     * Number of pixels the left edge of the Now Bar is offset from the current time.
+     *
+     * @default 0
+     */
+    nowBarOffset?: number;
+
+    /**
+     * The nearest (in seconds) that the Now Bar can be to the left edge of the time grid.
+     * If the Now Bar advances to this value plus 30 minutes, the grid auto-scrolls right 30 minutes.
+     *
+     * @default 300
+     */
+    minimumNowBarOffset?: number;
+}
+
+/**
+ * Configuration for Now/Next mode, where the program grid only shows
+ * "Now" and "Next" columns listing current and subsequent programs.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/timegrid#nownext-mode}
+ */
+export interface ITimeGridNowNextModeProps {
+    /**
+     * When true, the time grid displays two vertical columns showing
+     * Now and Next programs for each channel.
+     *
+     * @default false
+     */
+    nowNextMode?: boolean;
+
+    /**
+     * Bitmap file displayed in the background of the Now column.
+     */
+    nowBackgroundBitmapUri?: Uri;
+
+    /**
+     * Bitmap file displayed in the background of the Next column.
+     */
+    nextBackgroundBitmapUri?: Uri;
+
+    /**
+     * When true, hides the AM/PM abbreviation next to times in Now/Next mode.
+     *
+     * @default false
+     */
+    nowNextHideAmPm?: boolean;
+
+    /**
+     * Text color for program times in Now/Next cells when unfocused.
+     *
+     * @default "0xffffff99"
+     */
+    programNowNextTimeColor?: string;
+
+    /**
+     * Text color for program times in Now/Next cells when focused.
+     *
+     * @default "0x000000FF"
+     */
+    programNowNextTimeFocusedColor?: string;
+
+    /**
+     * Width of the left and right margins of program cell text in Now/Next mode, in pixels.
+     *
+     * @default 14
+     */
+    programNowNextHorizMargin?: number;
+
+    /**
+     * Gap between the Now and Next entries, in pixels.
+     *
+     * @default 15
+     */
+    programNowNextTimeTitleGap?: number;
+}
+
+/**
+ * Properties for the TimeGrid node.
+ *
+ * TimeGrid is an EPG (Electronic Program Guide) component that displays a
+ * time-based grid of channels and programs. Each row represents a channel,
+ * and each cell within a row represents a program with its time slot.
+ *
+ * The content tree structure is:
+ * - Root `ContentNode`
+ *   - Channel `ContentNode` per row (with `title`, `hdPosterUrl` for logo)
+ *     - Program `ContentNode` per cell (with `title`, `description`, `playStart`, `playDuration`)
+ *
+ * Program nodes use `playStart` (epoch seconds) and `playDuration` (seconds)
+ * to determine their horizontal position and width in the grid.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/timegrid}
+ *
+ * @example Basic TimeGrid
+ * ```tsx
+ * <TimeGrid
+ *     numRows={7}
+ *     duration={7200}
+ *     contentStartTime={startTime}
+ *     leftEdgeTargetTime={now}
+ *     channelInfoComponentName={channelItem}
+ *     content={epgContent}
+ *     onProgramSelected={(index) => console.log(`Selected program: ${index}`)}
+ * />
+ * ```
+ */
+export interface ITimeGridProps
+    extends
+        IArrayGridProps,
+        ITimeGridGeneralProps,
+        ITimeGridChannelProps,
+        ITimeGridChannelInfoProps,
+        ITimeGridProgramGridProps,
+        ITimeGridPastTimeScreenProps,
+        ITimeGridTimeBarProps,
+        ITimeGridNowBarProps,
+        ITimeGridNowNextModeProps {
+    /**
+     * Speed of horizontal scrolling through the time axis.
+     *
+     * @default 3
+     */
+    scrollSpeed?: number;
+}