@roku-sdk/components 0.0.0-stage → 2.18.0

package/src/sg-nodes/standard-dialog.props.ts

@@ -0,0 +1,520 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IModalLifecycleProps } from "../modal-dialog.props";
+import type { IGroupProps } from "./group.props";
+import type { EventHandler, JSX, ResType, Uri } from "./types";
+
+/** Keyboard layout type for {@link StdDlgKeyboardItem}. */
+export enum StdDlgKeyboardLayoutType {
+    /** No keyboard displayed. */
+    Unspecified = "unspecified",
+    /** Full DynamicKeyboard for alphanumeric/symbol entry. */
+    Keyboard = "keyboard",
+    /** DynamicPinPad for digit entry. */
+    PinPad = "pinpad"
+}
+
+interface PaletteColors {
+    /** Background color of the dialog. */
+    dialogBackgroundColor?: string;
+    /** Color of non-text items in the dialog. */
+    dialogItemColor?: string;
+    /** Primary text color in the dialog. */
+    dialogTextColor?: string;
+    /** Color of the focus indicator highlight. */
+    dialogFocusColor?: string;
+    /** Color of items within the focus indicator. */
+    dialogFocusItemColor?: string;
+    /** Secondary text color in the dialog. */
+    dialogSecondaryTextColor?: string;
+    /** Color of secondary items in the dialog. */
+    dialogSecondaryItemColor?: string;
+    /** Color of input fields such as text edit boxes. */
+    dialogInputFieldColor?: string;
+    /** Color of keyboard keys. */
+    dialogKeyboardColor?: string;
+    /** Color of footprint (background) areas such as action card backgrounds. */
+    dialogFootprintColor?: string;
+}
+
+export interface IStandardDialogRSGPaletteNodeProps {
+    /** Color palette values for the dialog. */
+    colors: PaletteColors;
+}
+
+/**
+ * Properties for the {@link StandardDialog} component.
+ *
+ * StandardDialog is the base dialog node for Roku's standard dialog framework. It can host
+ * pre-built dialogs (message, keyboard, pinpad, progress) or be used directly with custom
+ * dialog structures built from StdDlg* area and item nodes.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/standard-dialog}
+ */
+export interface IStandardDialogProps extends IGroupProps, IModalLifecycleProps {
+    /** Native dialog title, including the accessibility title. */
+    title?: string;
+    /** Also dismiss when the Options key is pressed. @default false */
+    optionsDialog?: boolean;
+    /**
+     * Sets the color palette for the dialog's background, text, buttons, and other elements.
+     * Pass an {@link RsgPalette} element to override the inherited palette.
+     * @default not set (inherited from ancestor nodes)
+     */
+    palette?: JSX.Element;
+    /**
+     * Width of the dialog in pixels. When set to 0, the system default is used
+     * (1038 FHD / 692 HD), and the dialog auto-expands for title/button text up to 1380 FHD / 920 HD.
+     * @default 0
+     */
+    width?: number;
+    /**
+     * Height of the dialog in pixels. If greater than 0 and the layout height is less than
+     * this value, the button area moves to the bottom with a blank region above it.
+     * @default 0
+     */
+    height?: number;
+    /**
+     * Fired when a button in the button area is selected. The handler receives the zero-based
+     * index of the selected button.
+     */
+    onButtonSelected?: EventHandler<number>;
+    /**
+     * Fired when a button in the button area gains focus. The handler receives the zero-based
+     * index of the focused button.
+     */
+    onButtonFocused?: EventHandler<number>;
+    /**
+     * Dismisses the dialog whenever set (regardless of the value). Setting this field to any value
+     * triggers the dialog to close.
+     * @default false
+     */
+    close?: boolean;
+}
+
+/**
+ * Base props shared by all dialog area nodes ({@link StdDlgTitleArea}, {@link StdDlgContentArea},
+ * {@link StdDlgButtonArea}). Extends {@link IGroupProps} with no additional fields.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/std-dlg-area-base}
+ */
+export type IStdDlgAreaBaseProps = IGroupProps;
+
+/**
+ * Properties for the {@link StdDlgTitleArea} component.
+ *
+ * Contains the dialog's title information, always displayed at the top of the dialog.
+ * May include optional primary and secondary icons alongside the title text.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/std-dlg-title-area}
+ */
+export interface IStdDlgTitleAreaProps extends IStdDlgAreaBaseProps {
+    /**
+     * Title text displayed in the dialog's title area.
+     * @default ""
+     */
+    primaryTitle?: string;
+    /**
+     * URI of a bitmap displayed at the left edge of the title area, to the left of the primary title.
+     * @default ""
+     */
+    primaryIcon?: Uri;
+    /**
+     * Vertical position adjustment of the primary icon relative to the title baseline.
+     * @default 0
+     */
+    primaryIconVertOffset?: number;
+    /**
+     * URI of a bitmap displayed at the right edge of the title area.
+     * @default ""
+     */
+    secondaryIcon?: Uri;
+    /**
+     * Vertical position adjustment of the secondary icon relative to the title baseline.
+     * @default 0
+     */
+    secondaryIconVertOffset?: number;
+}
+
+/**
+ * Properties for the {@link StdDlgContentArea} component.
+ *
+ * Contains the main body of the dialog, positioned between the title area and button area.
+ * Add zero or more StdDlgItemBase-derived child nodes, which are arranged vertically top-to-bottom.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/std-dlg-content-area}
+ */
+export type IStdDlgContentAreaProps = IStdDlgAreaBaseProps;
+
+/**
+ * Properties for the {@link StdDlgButtonArea} component.
+ *
+ * Always positioned at the bottom of the dialog. Contains zero or more {@link StdDlgButton}
+ * child nodes arranged vertically in listed order.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/std-dlg-button-area}
+ */
+export type IStdDlgButtonAreaProps = IStdDlgAreaBaseProps;
+
+/**
+ * Properties for the {@link StdDlgSideCardArea} component.
+ *
+ * A freeform area on the left or right side of the dialog for decorative images or
+ * annotative text. The side card area never gains key focus.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/std-dlg-side-card-area}
+ */
+export interface IStdDlgSideCardAreaProps extends IStdDlgAreaBaseProps {
+    /**
+     * Width of the side card area. When 0, defaults to the width of the content area's bounding rectangle.
+     * @default 0
+     */
+    width: number;
+    /**
+     * Whether the area extends to the dialog's background image edge (`true`) or respects
+     * 9-patch margins (`false`).
+     * @default true
+     */
+    extendToDialogEdge?: boolean;
+    /**
+     * Which side of the dialog the area appears on.
+     * @default "right"
+     */
+    horizAlign?: "left" | "right";
+    /**
+     * Whether a thin vertical divider line is displayed between the side card and the main content column.
+     * @default false
+     */
+    showDivider?: boolean;
+}
+
+/**
+ * Properties for the {@link StdDlgButton} component.
+ *
+ * Represents a single button in the dialog's button area. Buttons are displayed in listed
+ * order with size and layout controlled by the StandardDialog layout algorithm.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/std-dlg-button}
+ */
+export interface IStdDlgButtonProps extends IGroupProps {
+    /**
+     * Text displayed on the button.
+     * @default ""
+     */
+    text: string;
+    /**
+     * When `true`, the button has an inactive appearance and cannot receive focus.
+     * @default false
+     */
+    disabled?: boolean;
+}
+
+/**
+ * Base props shared by all content area item nodes. Extends {@link IGroupProps} with
+ * a `scrollable` property.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/std-dlg-item-base}
+ */
+export interface IStdDlgItemBaseProps extends IGroupProps {
+    /**
+     * Whether the item can be scrolled vertically. The layout algorithm reduces the height
+     * of scrollable items if the dialog content is too large to fit.
+     * @default false
+     */
+    scrollable?: boolean;
+}
+
+/**
+ * Properties for the {@link StdDlgItemGroup} component.
+ *
+ * Visually groups StdDlgItemBase child nodes with reduced vertical spacing. Enforces
+ * a radio-button "only 1 of N" rule for {@link StdDlgActionCardItem} children with
+ * `iconType="radiobutton"`.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/std-dlg-item-group}
+ */
+export interface IStdDlgItemGroupProps extends IStdDlgItemBaseProps {
+    /**
+     * Index of the currently selected child node. Updated when the user selects an
+     * ActionCardItem child. Enforces radio-button exclusivity.
+     * @default 0
+     */
+    selectedIndex?: number;
+}
+
+/** Icon type for {@link StdDlgActionCardItem}. */
+export type IStdDlgActionIconType = "none" | "more_info" | "checkbox" | "radiobutton";
+
+/**
+ * Properties for the {@link StdDlgActionCardItem} component.
+ *
+ * Highlights child items with optional icons (arrow, radio button, or checkbox).
+ * Drawn on top of a rectangular background tinted with the RSGPalette's DialogFootprintColor.
+ * Focusable — receives key events.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/std-dlg-action-card-item}
+ */
+export interface IStdDlgActionCardItemProps extends IStdDlgItemBaseProps {
+    /**
+     * Whether the action card is checked or unchecked when {@link iconType} is
+     * `"checkbox"` or `"radiobutton"`.
+     * @default false
+     */
+    iconStatus?: boolean;
+    /**
+     * Type of icon displayed on the action card.
+     * - `"none"`: no icon
+     * - `"more_info"`: right-pointing arrow
+     * - `"checkbox"`: checkmark / empty box
+     * - `"radiobutton"`: filled / empty circle
+     * @default "none"
+     */
+    iconType?: IStdDlgActionIconType;
+    /**
+     * Event fired when the action card item is selected. The handler receives the resulting
+     * {@link iconStatus} value (for `"checkbox"` and `"radiobutton"` icon types).
+     */
+    onSelected?: EventHandler<boolean>;
+}
+
+/** Bullet list delimiter type for {@link StdDlgBulletTextItem}. */
+export type IStdDialogBulletType = "bullet" | "numbered" | "lettered";
+
+/**
+ * Properties for the {@link StdDlgBulletTextItem} component.
+ *
+ * Displays a bulleted, numbered, or lettered list of text in the content area.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/std-dlg-bullet-text-item}
+ */
+export interface IStdDlgBulletTextItemProps extends IStdDlgItemBaseProps {
+    /**
+     * Array of strings displayed as a bulleted/numbered/lettered list.
+     * @default []
+     */
+    bulletText?: string[];
+    /**
+     * Type of list delimiter.
+     * - `"bullet"`: bullet point
+     * - `"numbered"`: 1, 2, 3…
+     * - `"lettered"`: a, b, c…
+     * @default "bullet"
+     */
+    bulletType?: IStdDialogBulletType;
+}
+
+/**
+ * Properties for the {@link StdDlgDeterminateProgressItem} component.
+ *
+ * Displays a percentage progress indicator for tasks with a known duration.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/std-dlg-determinate-progress-item}
+ */
+export interface IStdDlgDeterminateProgressItemProps extends IStdDlgItemBaseProps {
+    /**
+     * Current completion percentage (0–100). Clamped to the 0–100 range.
+     *
+     * > **Note:** The Roku documentation defines this as a `string`, but the SDK uses `number`
+     * > for a more ergonomic API. The value is converted automatically.
+     * @default 0
+     */
+    percent?: number;
+    /**
+     * Text displayed next to the progress graphic. Wraps if too wide.
+     * @default ""
+     */
+    text?: string;
+}
+
+/** Graphic/text alignment for {@link StdDlgGraphicItem}. */
+export type IStdDlgGraphicAlign = "left" | "right" | "center_below" | "center_above";
+
+/**
+ * Properties for the {@link StdDlgGraphicItem} component.
+ *
+ * Displays an image with an optional text label positioned to the left, right, above, or below.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/std-dlg-graphic-item}
+ */
+export interface IStdDlgGraphicItemProps extends IStdDlgItemBaseProps {
+    /**
+     * Text displayed next to the graphic. Wraps if too wide.
+     * @default ""
+     */
+    text?: string;
+    /**
+     * URI of the image to display.
+     * @default ""
+     */
+    graphicUri?: Uri;
+    /**
+     * Width override for the image (instead of its actual width).
+     * @default 0
+     */
+    graphicWidth?: number;
+    /**
+     * Height override for the image (instead of its actual height).
+     * @default 0
+     */
+    graphicHeight?: number;
+    /**
+     * Relative position of the graphic and text.
+     * - `"left"`: graphic left, text right
+     * - `"right"`: graphic right, text left
+     * - `"center_below"`: graphic below text, both centered
+     * - `"center_above"`: graphic above text, both centered
+     * @default "left"
+     */
+    graphicAlign?: IStdDlgGraphicAlign;
+}
+
+/**
+ * Properties for the {@link StdDlgKeyboardItem} component.
+ *
+ * Displays a keyboard or PIN pad in the content area for alphanumeric/symbol/digit entry.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/std-dlg-keyboard-item}
+ */
+export interface IStdDlgKeyboardItemProps extends IStdDlgItemBaseProps {
+    /**
+     * Type of keyboard to display.
+     * @default StdDlgKeyboardLayoutType.Unspecified
+     */
+    keyLayoutType?: StdDlgKeyboardLayoutType;
+    /**
+     * Default string in the text edit box. Updated as the user types.
+     * @default ""
+     */
+    text?: string;
+    /**
+     * Fired whenever the text in the keyboard's text edit box changes (on each keystroke).
+     * The handler receives the full current string entered by the user.
+     *
+     * Use this to react to live input — for example to validate input or enable/disable
+     * action buttons based on what the user has typed so far.
+     */
+    onText?: EventHandler<string>;
+    // textEditBox?: node;  TODO: Add support for textEditBox
+}
+
+/** Drawing style for a named text style in {@link StdDlgMultiStyleTextItem}. */
+export interface IStdDlgDrawingStyle {
+    /**
+     * Font size in points. Ignored when using system fonts.
+     */
+    fontSize?: ResType<number>;
+    /**
+     * TrueType/OpenType font file URI (e.g., `"pkg:/fonts/font.ttf"`) or a system font URI
+     * (e.g., `"font:MediumBoldSystemFont"`).
+     */
+    fontUri?: string;
+    /** Text color in hex format (e.g., `"0xFF0000FF"`). */
+    color?: string;
+}
+
+/**
+ * Properties for the {@link StdDlgMultiStyleTextItem} component.
+ *
+ * Enables text with multiple styles (fonts, colors, sizes) using markup tags that reference
+ * named drawing styles.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/std-dlg-multi-style-text-item}
+ */
+export interface IStdDlgMultiStyleTextItemProps extends IStdDlgItemBaseProps {
+    /**
+     * Text to display. Use markup tags referencing keys in {@link drawingStyles} to apply styles.
+     * @default ""
+     */
+    text?: string;
+    /**
+     * Named font styles. Each top-level key becomes a markup tag name usable in the `text` field.
+     *
+     * @example
+     * ```tsx
+     * drawingStyles={{
+     *     bold: { fontUri: "font:MediumBoldSystemFont", color: "0xFFFFFFFF" },
+     *     highlight: { fontSize: 24, color: "0xFFFF00FF" }
+     * }}
+     * // Then in text: "Normal <bold>bold text</bold> and <highlight>highlighted</highlight>"
+     * ```
+     */
+    drawingStyles: { [tag: string]: IStdDlgDrawingStyle };
+    /**
+     * String spoken by the screen reader instead of the `text` field value.
+     * @default ""
+     */
+    audioGuideText: string;
+}
+
+/**
+ * Properties for the {@link StdDlgProgressItem} component.
+ *
+ * Displays a spinning progress indicator for tasks with an indeterminate duration.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/std-dlg-progress-item}
+ */
+export interface IStdDlgProgressItemProps extends IStdDlgItemBaseProps {
+    /**
+     * Text displayed next to the spinning progress graphic. Wraps if too wide.
+     * @default ""
+     */
+    text: string;
+}
+
+/** Named text style for {@link StdDlgTextItem}. */
+export type INamedTextStyles = "normal" | "secondary" | "bold" | "custom_secondary" | "centered" | "errorcode";
+
+/**
+ * Properties for the {@link StdDlgTextItem} component.
+ *
+ * Displays a block of text in the content area. Use multiple StdDlgTextItem nodes to
+ * separate lines of text rather than newline characters.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/std-dlg-text-item}
+ */
+export interface IStdDlgTextItemProps extends IStdDlgItemBaseProps {
+    /**
+     * Text to display. Wraps if too wide for the content area.
+     * @default ""
+     */
+    text: string;
+    /**
+     * Named text style controlling font and color.
+     * - `"normal"`: DialogTextColor, SmallSystemFont
+     * - `"secondary"`: DialogSecondaryTextColor, SmallestSystemFont
+     * - `"bold"`: DialogTextColor, SmallBoldSystemFont
+     * - `"custom_secondary"`: custom secondary style
+     * - `"centered"`: centered text
+     * - `"errorcode"`: error code style
+     * @default "normal"
+     */
+    namedTextStyle?: INamedTextStyles;
+    /**
+     * String spoken by the screen reader instead of the `text` field value.
+     * @default ""
+     */
+    audioGuideText?: string;
+}
+
+/**
+ * Properties for the {@link StdDlgCustomItem} component.
+ *
+ * Free-form dialog item in the content area requiring custom layout. Set `focusable=true`
+ * on child nodes if they need to receive focus (e.g., custom keyboard).
+ *
+ * @see {@link https://developer.roku.com/dev/docs/std-dlg-custom-item}
+ */
+export interface IStdDlgCustomItemProps extends IStdDlgItemBaseProps {
+    /**
+     * Width of the custom item enforced by the content area's layout algorithm (read-only).
+     * @default 0
+     */
+    widthField?: number;
+    /**
+     * Desired width passed to the content area's layout algorithm. Typically used with
+     * DynamicCustomKeyboard nodes.
+     * @default 0
+     */
+    fixedWidthField?: number;
+}