@roku-sdk/components 0.0.0-stage → 2.18.0

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

@@ -0,0 +1,119 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./group.props";
+import type { EventHandler, Uri } from "./types";
+
+/**
+ * Properties shared across Button-like components (Button, ButtonGroup, ButtonRow).
+ *
+ * Provides the visual customization fields common to all button presentations,
+ * including text styling, icon bitmaps, and sizing constraints.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/button}
+ */
+export interface IButtonDataProps {
+    id?: string;
+    centerNoIcon?: boolean;
+    centerIconOnly?: boolean;
+    positionIconToRight?: boolean;
+    /**
+     * Specifies the color of the button label when the button does not have the key focus.
+     * @default 0xddddddff
+     */
+    textColor?: string;
+    /**
+     * Specifies the color of the button label when the button has the key focus.
+     * @default 0x262626ff
+     */
+    focusedTextColor?: string;
+    /**
+     * Specifies the font of the button label when the button does not have the key focus.
+     * @see {@link https://developer.roku.com/dev/docs/button | Button Fields}
+     */
+    textFont?: string;
+    /**
+     * Specifies the font of the button label when the button has the key focus.
+     * @see {@link https://developer.roku.com/dev/docs/button | Button Fields}
+     */
+    focusedTextFont?: string;
+    /**
+     * Specifies the button focus "footprint" bitmap file to display when the button does
+     * not have key focus. Only set this field to specify a custom bitmap that differs in
+     * appearance from the default bitmap. The footprint is only displayed when
+     * {@link IButtonDataProps.showFocusFootprint | showFocusFootprint} is `true`.
+     * @default ""
+     */
+    focusFootprintBitmapUri?: Uri;
+    /**
+     * Specifies the button background bitmap file to display when the button has the key focus.
+     * Only set this field to specify a custom bitmap that differs in appearance from the default bitmap.
+     * @default ""
+     */
+    focusBitmapUri?: Uri;
+    /**
+     * Specifies a bitmap file for the button icon when the button does not have the key focus.
+     * For a button with no icon, set this field to an empty string.
+     * @default ""
+     */
+    iconUri?: Uri;
+    /**
+     * Specifies a bitmap file for the button icon when the button has the key focus.
+     * For a button with no icon, set this field to an empty string.
+     * @default ""
+     */
+    focusedIconUri?: Uri;
+    /**
+     * Specifies the height of the button.
+     * @default 64
+     */
+    height?: number;
+    /**
+     * Specifies the minimum width of the button. Must be less than or equal to
+     * {@link IButtonDataProps.maxWidth | maxWidth}.
+     * @default 0
+     */
+    minWidth?: number;
+    /**
+     * Specifies the maximum width of the button. Must be greater than or equal to
+     * {@link IButtonDataProps.minWidth | minWidth}.
+     * @default 32767
+     */
+    maxWidth?: number;
+    width?: number;
+    /**
+     * Controls whether the focus "footprint" bitmap is displayed when the button does not
+     * have the key focus. When a Button node is not a child of a ButtonGroup, typically this
+     * should be set to `true` so the button always displays a background image.
+     * @default false
+     */
+    showFocusFootprint?: boolean;
+}
+
+/**
+ * Properties for the Button node.
+ *
+ * The Button node is a simple widget that generates a `buttonSelected` event when the user
+ * selects it. The button can display a label and/or an icon, as well as a background image.
+ * Fields are provided to customize the label text and color depending on whether or not the
+ * button has the key focus. Similarly, the bitmaps used for the icon and background can be
+ * specified for both focused and unfocused button states.
+ *
+ * By default, the background of the button is only shown when the button has the key focus.
+ * Buttons are typically used in a ButtonGroup node that manages which button in the group
+ * will have the key focus when the ButtonGroup node receives the focus.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/button}
+ */
+export interface IButtonProps extends IButtonDataProps, IGroupProps {
+    /**
+     * Specifies the text to be displayed as the button label.
+     * @default ""
+     */
+    text?: string;
+    /**
+     * Fired when the button is selected by the user (e.g., pressing the OK remote button
+     * while the button has key focus).
+     */
+    onButtonSelected?: EventHandler<never>;
+}

package/src/sg-nodes/button.tsx

@@ -0,0 +1,31 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IButtonProps } from "./button.props";
+import { Component } from "./types";
+export type { IButtonDataProps, IButtonProps } from "./button.props";
+
+/**
+ * Button is a simple widget that generates a `buttonSelected` event when the user selects it.
+ * The button can display a label and/or an icon, as well as a background image. Fields are
+ * provided to customize the label text and color depending on whether or not the button has
+ * the key focus.
+ *
+ * By default, the background is only shown when the button has focus. Buttons are typically
+ * used in a ButtonGroup node. When a Button is not a child of a ButtonGroup, set
+ * `showFocusFootprint` to `true` so it always displays a background image.
+ *
+ * @example
+ * ```tsx
+ * <button
+ *     text="Play"
+ *     showFocusFootprint={true}
+ *     onButtonSelected={() => console.log("Button selected")}
+ * />
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/button}
+ */
+export const Button: Component<IButtonProps> = props => {
+    return <button {...props}></button>;
+};

package/src/sg-nodes/check-list.props.ts

@@ -0,0 +1,71 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { ILabelListProps } from "./label-list.props";
+import type { Uri } from "./types";
+
+/**
+ * Properties for the CheckList component.
+ *
+ * Extends {@link ILabelListProps} with checkbox state management and
+ * custom checkbox icon options.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/checklist}
+ */
+export interface ICheckListProps extends ILabelListProps {
+    /**
+     * Specifies the checked state of each item in the list.
+     * `true` indicates checked, `false` indicates unchecked.
+     *
+     * When reading, always includes one value per item.
+     * When writing with fewer values than items, unspecified items remain unchanged.
+     *
+     * @default all false
+     * @example [true, false, true]
+     */
+    checkedState?: boolean[];
+
+    /**
+     * Controls whether pressing OK toggles the checked state of the focused item.
+     * When `false`, developer must manage checked state manually via `checkedState`.
+     *
+     * @default true
+     */
+    checkOnSelect?: boolean;
+
+    /**
+     * URI for the checkbox icon when item is checked and not focused.
+     * Typically includes the outline of a box with a checkmark indicator inside.
+     * Only set to specify a custom bitmap different from default.
+     *
+     * @example "pkg:/images/checked.png"
+     */
+    checkedIconUri?: Uri;
+
+    /**
+     * URI for the checkbox icon when item is unchecked and not focused.
+     * Typically includes the outline of an empty box.
+     * Only set to specify a custom bitmap different from default.
+     *
+     * @example "pkg:/images/unchecked.png"
+     */
+    uncheckedIconUri?: Uri;
+
+    /**
+     * URI for the checkbox icon when item is checked and has focus.
+     * Typically includes the outline of a box with a checkmark indicator inside.
+     * Only set to specify a custom bitmap different from default.
+     *
+     * @example "pkg:/images/checked-focused.png"
+     */
+    focusedCheckedIconUri?: Uri;
+
+    /**
+     * URI for the checkbox icon when item is unchecked and has focus.
+     * Typically includes the outline of an empty box.
+     * Only set to specify a custom bitmap different from default.
+     *
+     * @example "pkg:/images/unchecked-focused.png"
+     */
+    focusedUncheckedIconUri?: Uri;
+}

package/src/sg-nodes/check-list.tsx

@@ -0,0 +1,55 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { ICheckListProps } from "./check-list.props";
+import { Component } from "./types";
+export type { ICheckListProps } from "./check-list.props";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CheckList Properties
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * CheckList displays a list of items with optional checkboxes for selection.
+ *
+ * Each item shows a text string and an optional checkbox icon positioned to the left.
+ * Checkboxes display as empty (unchecked) or with a checkmark (checked).
+ *
+ * Items can optionally hide their checkbox by setting HIDEICON attribute to false
+ * on the ContentNode, allowing mixed checkbox and regular list items.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <checkList
+ *     itemSize={[440, 48]}
+ *     checkedState={[true, false, false]}
+ *     checkOnSelect={true}
+ *     content={
+ *         <contentNode>
+ *             <contentNode title="Option 1" />
+ *             <contentNode title="Option 2" />
+ *             <contentNode title="Option 3" />
+ *         </contentNode>
+ *     }
+ * />
+ * ```
+ *
+ * @example With mixed items (checkbox and regular)
+ * ```tsx
+ * <checkList
+ *     itemSize={[440, 48]}
+ *     content={
+ *         <contentNode>
+ *             <contentNode title="Selectable Option" />
+ *             <contentNode title="Regular Item" HIDEICON={false} />
+ *         </contentNode>
+ *     }
+ * />
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/checklist}
+ * @see {@link https://github.com/rokudev/samples/tree/master/ux%20components/lists%20and%20grids/CheckListExample | Sample App}
+ */
+export const CheckList: Component<ICheckListProps> = props => {
+    return <checkList {...props}></checkList>;
+};