@roku-sdk/components 0.0.0-stage → 2.19.0

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

@@ -0,0 +1,302 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { ComponentRef } from "@roku-sdk/interfaces";
+
+import type { MediaControl, MediaState } from "../types";
+import type { IGroupProps } from "./group.props";
+import type { EventHandler, JSX } from "./types";
+
+/**
+ * Buffering progress information from the Audio node.
+ *
+ * Valid only while buffering is in progress, both at stream startup or when
+ * re-buffering is required.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/audio}
+ */
+export interface IAudioBufferingStatus {
+    /** Percent buffering complete as an integer. */
+    buffering: number;
+    /** Percent buffering complete as an integer. */
+    percent: number;
+}
+
+/** Alias for {@link MediaControl} used by the Audio node `control` field. */
+export type AudioControl = MediaControl;
+
+/** Alias for {@link MediaState} from the Audio node `state` field. */
+export type AudioState = MediaState;
+
+/**
+ * Audio codec format reported by the Audio node `audioFormat` field.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/audio}
+ */
+export type AudioFormat =
+    | ""
+    | "aac"
+    | "aac_adif"
+    | "aac_adts"
+    | "aac_latm"
+    | "ac3"
+    | "alac"
+    | "dts"
+    | "eac3"
+    | "flac"
+    | "mp2"
+    | "mp3"
+    | "none"
+    | "pcm"
+    | "unknown"
+    | "vorbis"
+    | "wma"
+    | "wmapro";
+
+/**
+ * HDR mode reported in `streamingSegment` data.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/audio}
+ */
+export type HDRmode = "invalid" | "unknown" | "none" | "hdr10" | "dolby_vision" | "hlg10" | "sl-hdr2";
+
+/**
+ * Information about the audio segment currently streaming (HLS/DASH).
+ *
+ * @see {@link https://developer.roku.com/dev/docs/audio}
+ */
+export interface IAudioStreamingSegment {
+    /** Bitrate of the segment in bits per second. */
+    segBitrateBps: number;
+    /** The sequence number of the segment in the audio. */
+    segSequence: number;
+    /** The start time of the segment from the start of the audio, in seconds. */
+    segStart: number;
+    /** URL of the segment. */
+    segUrl: string;
+    /** The type of data in the segment: "unknown", "mux", "audio", "video", or "captions". */
+    segTypeStr: string;
+    /** The HDR format of the content. */
+    hdrModeStr: HDRmode;
+}
+
+/**
+ * Information about the audio stream currently playing or buffering.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/audio}
+ */
+export interface IAudioStreamInfo {
+    /** If true, the stream was downloaded due to an underrun. */
+    isUnderrun: boolean;
+    /** If true, playback was resumed after trickplay. */
+    isResumed: boolean;
+    /** The measured bitrate (bps) of the network when the stream was selected. */
+    measuredBitrate: number;
+    /** The bitrate of the stream. */
+    streamBitrate: number;
+    /** The URL of the stream. */
+    streamUrl: string;
+}
+
+/**
+ * Properties for the Audio node.
+ *
+ * The Audio node plays streaming audio. It has no built-in visual UI, but you can build
+ * your own UI for the node, including trick play, or showing an album cover or similar
+ * graphical image for each song selected by a user.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/audio}
+ */
+export interface IAudioProps extends IGroupProps {
+    /**
+     * The ContentNode with the content metadata for the audio or audio playlist to be played.
+     * If an audio playlist is to be played, the ContentNode must include complete child
+     * ContentNodes for each audio in the playlist.
+     * @default null
+     */
+    content?: JSX.Element;
+    /**
+     * When true, enables audio playlists. The ContentNode set in `content` must have children
+     * ContentNodes for each audio in the playlist. All audios will be played in sequence.
+     * @default false
+     */
+    contentIsPlaylist?: boolean;
+    /**
+     * Sets the index of the next audio in the playlist to be played. Takes effect when the
+     * current audio is completed or skipped. Resets to -1 after the specified audio begins.
+     * @default -1
+     */
+    nextContentIndex?: number;
+    /**
+     * When true, the audio or audio playlist will be restarted from the beginning after
+     * the end is reached.
+     * @default false
+     */
+    loop?: boolean;
+    /**
+     * Fired when buffering progress or status changes. Valid only while buffering is in
+     * progress, both at stream startup or when re-buffering is required.
+     */
+    onBufferingStatus?: EventHandler<IAudioBufferingStatus>;
+    /**
+     * Sets the desired play state for the audio (e.g. "play", "pause", "stop", "prebuffer").
+     * To dynamically monitor the actual state, observe the `onState` event.
+     * @default "none"
+     */
+    control?: AudioControl;
+    /**
+     * The interval between position event notifications, in seconds.
+     * If 0, no notifications are delivered.
+     * @default 0.5
+     */
+    notificationInterval?: number;
+    /**
+     * If the audio stream contains timed metadata such as ID3 tags, any metadata with a
+     * key matching an entry in this array will be reported via `onTimedMetaData`. If any
+     * entry is "*", all timed metadata will be selected.
+     * @default []
+     */
+    timedMetaDataSelectionKeys?: string[];
+    /**
+     * Sets the current position in the audio in seconds from the beginning of the stream (write-only).
+     */
+    seek?: number;
+    /**
+     * Fired when the current playlist content index changes. Set to 0 for single audio
+     * when playlists are not enabled.
+     */
+    onContentIndex?: EventHandler<number>;
+    /**
+     * Fired when timed metadata (e.g. ID3 tags) matching {@link IAudioProps.timedMetaDataSelectionKeys}
+     * is decoded from the audio stream.
+     */
+    onTimedMetaData?: EventHandler<{ [key: string]: unknown }>;
+    /**
+     * Fired when the audio play state changes.
+     * Possible values: "none", "buffering", "playing", "paused", "stopped", "finished", "error".
+     */
+    onState?: EventHandler<AudioState>;
+    /** Fired on position updates at the interval specified by {@link IAudioProps.notificationInterval}. */
+    onPosition?: EventHandler<number>;
+    /**
+     * Fired when the audio duration is known or changes.
+     * Value is in seconds; becomes valid when playback begins.
+     */
+    onDuration?: EventHandler<number>;
+    /** Fired when an error code is set after the state changes to "error". */
+    onErrorCode?: EventHandler<number>;
+    /** Fired when an error message is set describing an audio play error. */
+    onErrorMsg?: EventHandler<string>;
+    /**
+     * Fired when the format of the currently playing audio changes.
+     * @see {@link AudioFormat}
+     */
+    onAudioFormat?: EventHandler<AudioFormat>;
+    /**
+     * Fired with information about the audio segment currently streaming.
+     * Only meaningful for segmented transports (DASH, HLS).
+     */
+    onStreamingSegment?: EventHandler<IAudioStreamingSegment>;
+    /**
+     * When false, disables auto-play after rebuffering following a seek.
+     * @default true
+     */
+    autoplayAfterSeek?: boolean;
+    /**
+     * Set to true to mute the audio currently playing. Set to false to restore audio.
+     * @default false
+     */
+    mute?: boolean;
+    /** Fired when stream info for the currently playing or buffering audio is updated. */
+    onStreamInfo?: EventHandler<IAudioStreamInfo>;
+    /**
+     * Fired when the time-to-start-streaming value is available. Value is the time in seconds
+     * from playback being started until audio actually began playing (minimum 0.001s).
+     * Only valid when state is "playing".
+     */
+    onTimeToStartStreaming?: EventHandler<number>;
+}
+
+/**
+ * Handle for imperative control of an {@link Audio} component, obtained via the `ref` prop.
+ *
+ * Extends {@link ComponentRef} with convenience methods that map to
+ * {@link AudioControl} values, so you can drive playback without manually
+ * setting the `control` prop.
+ *
+ * @example
+ * ```tsx
+ * import { Audio, AudioRef, Button } from "@roku-sdk/components";
+ *
+ * const MusicPlayer = () => {
+ *   let audioRef!: AudioRef;
+ *
+ *   return (
+ *     <>
+ *       <Button text="Play" onButtonSelected={() => audioRef.play()} />
+ *       <Audio
+ *         ref={audioRef}
+ *         content={<ContentNode url="https://example.com/song.mp3" streamFormat="mp3" />}
+ *       />
+ *     </>
+ *   );
+ * };
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/audio}
+ */
+export interface AudioRef extends ComponentRef<IAudioProps> {
+    /**
+     * Begin playback of the audio specified by `content`. Equivalent to setting
+     * `control="play"`. The node transitions through `buffering` to `playing`,
+     * which is observable via {@link IAudioProps.onState}.
+     */
+    play: () => void;
+    /**
+     * Pause playback while preserving the current position. Equivalent to setting
+     * `control="pause"`. Use {@link AudioRef.resume} to continue from where it
+     * paused. Has no effect when not currently `playing`.
+     */
+    pause: () => void;
+    /**
+     * Stop playback and release the audio stream. Equivalent to setting
+     * `control="stop"`. Position is reset; a subsequent {@link AudioRef.play}
+     * starts from the beginning.
+     */
+    stop: () => void;
+    /**
+     * Resume playback after a {@link AudioRef.pause}. Equivalent to setting
+     * `control="resume"`. Has no effect when the node is not in the `paused`
+     * state.
+     */
+    resume: () => void;
+    /**
+     * Restart the current audio (or playlist) from the beginning. Equivalent to
+     * setting `control="replay"`.
+     */
+    replay: () => void;
+    /**
+     * Pre-buffer the audio without starting playback. Equivalent to setting
+     * `control="prebuffer"`. Useful to reduce time-to-first-sample when playback
+     * is started later via {@link AudioRef.play}.
+     */
+    prebuffer: () => void;
+    /**
+     * Skip to the next item in a playlist. Equivalent to setting
+     * `control="skipcontent"`. Only meaningful when
+     * {@link IAudioProps.contentIsPlaylist} is true.
+     */
+    skipcontent: () => void;
+    /**
+     * Seek to a specific position in the current audio. Equivalent to setting
+     * the {@link IAudioProps.seek} prop.
+     *
+     * @param position Target position in seconds from the start of the stream.
+     */
+    seekTo: (position: number) => void;
+    /**
+     * Set the index of the next audio in the playlist to be played.
+     * @param index The index of the next audio in the playlist.
+     */
+    setNextContentIndex: (index: number) => void;
+}

package/src/sg-nodes/audio.tsx

@@ -0,0 +1,57 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { registerImperativeMethods } from "@roku-sdk/solid";
+
+import type { IAudioProps } from "./audio.props";
+export type {
+    IAudioBufferingStatus,
+    AudioControl,
+    AudioState,
+    AudioFormat,
+    HDRmode,
+    IAudioStreamingSegment,
+    IAudioStreamInfo,
+    IAudioProps,
+    AudioRef
+} from "./audio.props";
+
+import { mediaPlaybackMethods } from "./media-playback-methods";
+import { Component } from "./types";
+
+registerImperativeMethods("audio", mediaPlaybackMethods);
+
+/**
+ * Audio plays streaming audio content. It has no built-in visual UI, but you can build your
+ * own UI including trick play, album art, or any graphical elements for user interaction.
+ *
+ * Audio playlists are supported by setting `contentIsPlaylist` to true and providing a
+ * ContentNode with child ContentNodes for each audio in the playlist.
+ *
+ * @example
+ * ```tsx
+ * <Audio
+ *     content={<contentNode url="https://example.com/song.mp3" streamFormat="mp3" />}
+ *     control="play"
+ *     onState={(state) => console.log("Audio state:", state)}
+ *     onPosition={(pos) => console.log("Position:", pos)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Audio playlist
+ * <Audio
+ *     content={playlist}
+ *     contentIsPlaylist={true}
+ *     loop={true}
+ *     control="play"
+ *     onContentIndex={(idx) => console.log("Now playing track:", idx)}
+ * />
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/audio}
+ */
+export const Audio: Component<IAudioProps> = props => {
+    return <audio {...props}>{props.content}</audio>;
+};

package/src/sg-nodes/busy-spinner.props.ts

@@ -0,0 +1,59 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./group.props";
+
+/**
+ * Properties for the BusySpinner node.
+ *
+ * BusySpinner is a widget that displays a continuously rotating bitmap to indicate loading
+ * or processing state. It uses an internal Poster node instance to display the spinner bitmap.
+ *
+ * **Note:** Not all Roku Player hardware versions support arbitrary rotations. Some hardware
+ * versions only support 90-degree rotation increments. In those cases, the icon will step through
+ * 90°, 180°, 270°, and back to 0° rotations rather than spin smoothly.
+ *
+ * @extends Group
+ * @see {@link https://developer.roku.com/dev/docs/busyspinner}
+ */
+export interface IBusySpinnerProps extends IGroupProps {
+    /**
+     * Sets the URI field of the internal Poster node to select the bitmap for the busy spinner.
+     * The Poster node instance is created internally and can be accessed to set the spinner image.
+     *
+     * @example
+     * // Using a theme resource
+     * uri="theme:ActionHudSpinner"
+     *
+     * @example
+     * // Using a package resource
+     * uri="pkg:/images/spinner.png"
+     */
+    uri?: string;
+
+    /**
+     * Sets the operational state of the busy spinner.
+     *
+     * - `"none"`: No operational state set. The busy spinner will run if not set to "stop"
+     * - `"start"`: Starts the busy spinner if not running
+     * - `"stop"`: Stops the busy spinner if running
+     *
+     * @default "none"
+     */
+    control?: "none" | "start" | "stop";
+
+    /**
+     * Specifies whether the bitmap rotates in a clockwise or counterclockwise direction.
+     *
+     * @default true
+     */
+    clockwise?: boolean;
+
+    /**
+     * The number of seconds to complete a 360-degree rotation of the spinner image.
+     * A value of 0 will cause the spinner to remain stationary and not spin.
+     *
+     * @default 2
+     */
+    spinInterval?: number;
+}

package/src/sg-nodes/busy-spinner.tsx

@@ -0,0 +1,84 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IBusySpinnerProps } from "./busy-spinner.props";
+import { Component, ResObject } from "./types";
+export type { IBusySpinnerProps } from "./busy-spinner.props";
+
+/**
+ * Standard dimensions for the default BusySpinner (theme:ActionHudSpinner).
+ * These dimensions are resolution-aware and scale appropriately for HD and FHD displays.
+ *
+ * @example
+ * ```tsx
+ * import { getBusySpinnerWidth, getBusySpinnerHeight } from "@roku-sdk/components";
+ * import { useDeviceInfoEvents } from "@roku-sdk/rsg-ts/runtime";
+ *
+ * // Get current resolution and select appropriate dimension
+ * const { uiResolution } = useDeviceInfoEvents();
+ * const width = getBusySpinnerWidth(uiResolution()?.res);
+ * const height = getBusySpinnerHeight(uiResolution()?.res);
+ * ```
+ */
+export const BUSY_SPINNER_DIMENSIONS = {
+    /** Width of ActionHudSpinner: 80px in HD, 120px in FHD */
+    width: { hd: 80, fhd: 120 } as ResObject<number>,
+    /** Height of ActionHudSpinner: 80px in HD, 120px in FHD */
+    height: { hd: 80, fhd: 120 } as ResObject<number>
+};
+
+/**
+ * Get the width of the BusySpinner for the given UI resolution.
+ * Defaults to FHD (120px) if resolution is not provided.
+ *
+ * @param res - The resolution key ("hd", "fhd" or undefined)
+ * @returns Width in pixels (80 for HD, 120 for FHD)
+ */
+export function getBusySpinnerWidth(res?: "hd" | "fhd"): number {
+    return BUSY_SPINNER_DIMENSIONS.width[res ?? "fhd"];
+}
+
+/**
+ * Get the height of the BusySpinner for the given UI resolution.
+ * Defaults to FHD (120px) if resolution is not provided.
+ *
+ * @param res - The resolution key ("hd", "fhd" or undefined)
+ * @returns Height in pixels (80 for HD, 120 for FHD)
+ */
+export function getBusySpinnerHeight(res?: "hd" | "fhd"): number {
+    return BUSY_SPINNER_DIMENSIONS.height[res ?? "fhd"];
+}
+
+/**
+ * BusySpinner component - displays an animated spinning indicator.
+ *
+ * The BusySpinner is commonly used to provide visual feedback during loading operations
+ * or to indicate that processing is in progress.
+ *
+ * @example
+ * ```tsx
+ * <busySpinner
+ *   uri="theme:ActionHudSpinner"
+ *   control="start"
+ *   clockwise={true}
+ *   spinInterval={2}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Controlling the spinner with state
+ * const [isLoading, setIsLoading] = createSignal(true);
+ *
+ * <busySpinner
+ *   uri="pkg:/images/custom-spinner.png"
+ *   control={isLoading() ? "start" : "stop"}
+ *   visible={isLoading()}
+ * />
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/busyspinner}
+ */
+export const BusySpinner: Component<IBusySpinnerProps> = (props: IBusySpinnerProps) => {
+    return <busySpinner {...props}></busySpinner>;
+};

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

@@ -0,0 +1,141 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./group.props";
+import type { ILayoutGroupProps } from "./layout-group.props";
+import type { EventHandler, Uri } from "./types";
+
+/**
+ * Properties shared across ButtonGroup-like components.
+ *
+ * Provides the visual customization fields for button groups, including text styling,
+ * icon bitmaps, sizing, and button creation via string arrays.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/buttongroup}
+ */
+export interface IButtonGroupDataProps {
+    id?: string;
+    /**
+     * Specifies the button label color for all unfocused Button nodes in the group.
+     * Only set to override the system default.
+     * @default 0xffffffff
+     */
+    textColor?: string;
+    /**
+     * Specifies the button label color for the Button node that has focus, if any.
+     * Only set to override the system default.
+     * @default 0xffffffff
+     */
+    focusedTextColor?: string;
+    /**
+     * Specifies the font for all unfocused Button nodes in the group.
+     * Only set to override the system default.
+     * @default "font:MediumSystemFont"
+     */
+    textFont?: string;
+    /**
+     * Specifies the font for the Button node that has focus, if any.
+     * Only set to override the system default.
+     * @default "font:MediumBoldSystemFont"
+     */
+    focusedTextFont?: string;
+    /**
+     * Specifies the bitmap to be used as the focus footprint background when focus is not
+     * on the ButtonGroup node. The focus footprint is a visual indicator of the button that
+     * will take focus when focus moves back onto the ButtonGroup.
+     */
+    focusFootprintBitmapUri?: Uri;
+    /**
+     * Specifies the bitmap to be used as the background for the Button node that has focus.
+     * Only set to override the system default.
+     */
+    focusBitmapUri?: Uri;
+    /**
+     * Specifies the bitmap for the button icon for all unfocused Button nodes in the group.
+     * Only set to override the system default.
+     */
+    iconUri?: Uri;
+    /**
+     * Specifies the bitmap for the focused button icon.
+     * Only set to override the system default.
+     */
+    focusedIconUri?: Uri;
+    /**
+     * Specifies the height of each Button node in the group.
+     * Only set to override the system default.
+     * @default 0
+     */
+    height?: number;
+    /**
+     * Specifies the minimum width for the Button nodes in the group.
+     * Must be less than or equal to {@link IButtonGroupDataProps.maxWidth | maxWidth}.
+     * @default 0
+     */
+    minWidth?: number;
+    /**
+     * Specifies the maximum width for the Button nodes in the group.
+     * Must be greater than or equal to {@link IButtonGroupDataProps.minWidth | minWidth}.
+     * @default 32767
+     */
+    maxWidth?: number;
+    width?: number;
+    /**
+     * Controls whether the focus footprint bitmap is displayed when the ButtonGroup
+     * does not have the key focus.
+     * @default false
+     */
+    showFocusFootprint?: boolean;
+    /**
+     * Specifies the height of each Button node in the group.
+     * Only set to override the system default.
+     * @default 0
+     */
+    buttonHeight?: number;
+    /**
+     * Specifies whether the button labels and icons should be right- or left-justified.
+     * When right-justified and there is an icon, it appears to the right of the button label.
+     * @default false
+     */
+    rightJustify?: boolean;
+    /**
+     * Causes the button with the specified index to receive the focus when the ButtonGroup
+     * has the key focus. If the ButtonGroup does not have the key focus when set, the
+     * specified button will display the focus footprint as its background.
+     * @default 0
+     */
+    focusButton?: number;
+    /**
+     * Allows a set of Button nodes to be easily created by providing an array of button labels.
+     * Each string in the array results in a Button node added to the ButtonGroup, using the
+     * string as the button label.
+     * @default []
+     */
+    buttons?: string[];
+}
+
+/**
+ * Properties for the ButtonGroup node.
+ *
+ * ButtonGroup manages the layout, visual attributes, and focus management of a vertical
+ * list of Button nodes. When the ButtonGroup has focus, it sets the key focus on a single
+ * one of its child Button nodes.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/buttongroup}
+ */
+export interface IButtonGroupProps extends IButtonGroupDataProps, IGroupProps, ILayoutGroupProps {
+    /**
+     * Specifies the text for a single button. Typically `buttons` (string array) is preferred
+     * for creating multiple buttons at once.
+     */
+    text?: string;
+    /**
+     * Fired when a button in the group is selected by the user. The handler receives the
+     * zero-based index of the selected button.
+     */
+    onButtonSelected?: EventHandler<number>;
+    /**
+     * Fired when a button in the group receives the key focus. The handler receives the
+     * zero-based index of the focused button.
+     */
+    onButtonFocused?: EventHandler<number>;
+}

package/src/sg-nodes/button-group.tsx

@@ -0,0 +1,30 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IButtonGroupProps } from "./button-group.props";
+import { Component } from "./types";
+export type { IButtonGroupDataProps, IButtonGroupProps } from "./button-group.props";
+
+/**
+ * ButtonGroup manages the layout, visual attributes, and focus management of a vertical
+ * list of Button nodes. Buttons can be created by setting the `buttons` field to an array
+ * of label strings. A single observer on `onButtonSelected` can watch for any button in
+ * the group to be selected.
+ *
+ * By default, Button nodes added to the group will have the default button appearance.
+ * Several fields allow you to override the appearance of all buttons at once.
+ *
+ * @example
+ * ```tsx
+ * <buttonGroup
+ *     buttons={["Play", "Pause", "Stop"]}
+ *     onButtonSelected={(index) => console.log("Selected button:", index)}
+ *     onButtonFocused={(index) => console.log("Focused button:", index)}
+ * />
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/buttongroup}
+ */
+export const ButtonGroup: Component<IButtonGroupProps> = props => {
+    return <buttonGroup {...props}></buttonGroup>;
+};