@roku-sdk/components 0.0.0-stage → 2.19.0

package/src/sg-nodes/scrolling-label.props.ts

@@ -0,0 +1,106 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./group.props";
+import type { FontValue, HorizAlign, ResType, VertAlign } from "./types";
+
+/**
+ * Properties for the ScrollingLabel node.
+ *
+ * ScrollingLabel displays a string of text that automatically scrolls horizontally
+ * if the text length exceeds the specified maximum width.
+ *
+ * **Scrolling Behavior:**
+ * - If the text fits within `maxWidth`, it is simply drawn without scrolling
+ * - If the text exceeds `maxWidth`, it is initially drawn with an ellipsis (...),
+ *   then transitions to the full string and scrolls left to right, returning
+ *   to the ellipsized state after scrolling completes
+ *
+ * @extends Group
+ * @see {@link https://developer.roku.com/dev/docs/scrollinglabel}
+ */
+export interface IScrollingLabelProps extends IGroupProps {
+    /**
+     * Specifies the text string to be displayed.
+     *
+     * @default ""
+     */
+    text?: string;
+
+    /**
+     * Specifies the text color as a hex value (e.g., `0xRRGGBBAA`).
+     *
+     * @default 0xddddddff
+     */
+    color?: string;
+
+    /**
+     * Specifies the Font node to use for rendering the text.
+     * Can be a system font enum value or a custom font URI string.
+     *
+     * @example
+     * // Using system font
+     * font={SystemFont.Medium}
+     *
+     * @example
+     * // Using custom font URI
+     * font="pkg:/fonts/custom.ttf"
+     *
+     * @default system default font
+     */
+    font?: FontValue;
+
+    /**
+     * Specifies the maximum width of the rendered text in local coordinates.
+     * If the rendered text width exceeds this value, the scrolling behavior
+     * is automatically triggered.
+     *
+     * @default 500
+     */
+    maxWidth?: ResType<number>;
+
+    /**
+     * Specifies the height of the label in local coordinates.
+     * If set to 0, the actual height is determined by the font metrics.
+     *
+     * @default 0
+     */
+    height?: ResType<number>;
+
+    /**
+     * Specifies the horizontal scrolling speed in pixels per second.
+     *
+     * @default 100
+     */
+    scrollSpeed?: number;
+
+    /**
+     * Controls the scrolling repeat behavior:
+     * - `-1`: Scrolls continuously (default)
+     * - `0`: Text remains ellipsized and never scrolls
+     * - `> 0`: Scrolls the specified number of times, then shows ellipsis
+     *
+     * @default -1
+     */
+    repeatCount?: number;
+
+    /**
+     * Specifies the horizontal alignment of the text within the label bounds.
+     * - `"left"`: Left edge of the text is drawn at the 0 x-coordinate
+     * - `"center"`: Horizontal center of the text is drawn at half the computed width
+     * - `"right"`: Right edge of the text is drawn at the computed width
+     *
+     * @default "left"
+     */
+    horizAlign?: HorizAlign;
+
+    /**
+     * Specifies the vertical alignment of the text within the label bounds.
+     * - `"top"`: Top edge of the text is drawn at the 0 y-coordinate
+     * - `"center"`: Vertical center of the text is drawn at half the computed height
+     * - `"bottom"`: Bottom edge of the text is drawn at the computed height
+     *
+     * @default "top"
+     */
+    vertAlign?: VertAlign;
+}

package/src/sg-nodes/scrolling-label.tsx

@@ -0,0 +1,42 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IScrollingLabelProps } from "./scrolling-label.props";
+import { Component } from "./types";
+export type { IScrollingLabelProps } from "./scrolling-label.props";
+
+/**
+ * ScrollingLabel component for displaying horizontally scrolling text.
+ *
+ * Use ScrollingLabel when you need to display text that may exceed a fixed width
+ * and should scroll to reveal the full content. This is commonly used for titles,
+ * descriptions, or any text that may be truncated.
+ *
+ * @example
+ * ```tsx
+ * import { SystemFont } from "@roku-sdk/components";
+ *
+ * <scrollingLabel
+ *     text="This is a long text that will scroll if it exceeds maxWidth"
+ *     maxWidth={400}
+ *     scrollSpeed={80}
+ *     font={SystemFont.Medium}
+ *     color="0xFFFFFFFF"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Scroll only 3 times then show ellipsis
+ * <scrollingLabel
+ *     text="Limited scroll text"
+ *     maxWidth={200}
+ *     repeatCount={3}
+ * />
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/scrollinglabel}
+ */
+export const ScrollingLabel: Component<IScrollingLabelProps> = props => {
+    return <scrollingLabel {...props}></scrollingLabel>;
+};

package/src/sg-nodes/simple-label.props.ts

@@ -0,0 +1,156 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./group.props";
+import type { HorizAlign } from "./types";
+
+/**
+ * Horizontal origin options for SimpleLabel positioning.
+ * Controls the x=0 position of the SimpleLabel node's local coordinate system.
+ */
+export type HorizOrigin = HorizAlign;
+
+/**
+ * Vertical origin options for SimpleLabel positioning.
+ * Controls the y=0 position of the SimpleLabel node's local coordinate system.
+ *
+ * - `"top"`: Top edge of the text is at the 0 y-coordinate
+ * - `"center"`: Vertical center of the text is at the 0 y-coordinate
+ * - `"baseline"`: Baseline of the text is at the 0 y-coordinate
+ * - `"bottom"`: Bottom edge of the text is at the 0 y-coordinate
+ */
+export type VertOrigin = "top" | "center" | "baseline" | "bottom";
+
+/**
+ * Font URI options for SimpleLabel.
+ *
+ * Can be either:
+ * - A path to a TrueType or OpenType font file (e.g., `pkg:/fonts/MyFont.ttf`)
+ * - A built-in system font name using the `font:` prefix
+ *
+ * **Built-in System Fonts (Fixed Size):**
+ * - `font:SmallestSystemFont`
+ * - `font:SmallSystemFont`
+ * - `font:MediumSystemFont`
+ * - `font:LargeSystemFont`
+ * - `font:SmallestBoldSystemFont`
+ * - `font:SmallBoldSystemFont`
+ * - `font:MediumBoldSystemFont`
+ * - `font:LargeBoldSystemFont`
+ *
+ * **Built-in System Fonts (Variable Size - respects fontSize):**
+ * - `font:SystemFontFile`
+ * - `font:BoldSystemFontFile`
+ */
+export type SimpleLabelFontUri = string;
+
+/**
+ * Properties for the SimpleLabel node.
+ *
+ * SimpleLabel is a lightweight component for displaying a single line of text.
+ * It is more memory efficient than the Label node and supports simplified font
+ * style specification.
+ *
+ * **Features:**
+ * - Built-in system fonts or TrueType/OpenType font files
+ * - Customizable text color
+ * - Flexible horizontal and vertical origin positioning
+ * - Rotation support (center of rotation determined by origin point)
+ *
+ * @extends Group
+ * @see {@link https://developer.roku.com/dev/docs/simplelabel}
+ *
+ * @example
+ * <SimpleLabel
+ *     text="Hello World"
+ *     fontUri="font:MediumBoldSystemFont"
+ *     color="#FFFFFFFF"
+ *     horizOrigin="center"
+ *     vertOrigin="baseline"
+ * />
+ */
+export interface ISimpleLabelProps extends IGroupProps {
+    /**
+     * Specifies the text string to be displayed.
+     *
+     * @default ""
+     */
+    text?: string;
+
+    /**
+     * Specifies the text color as a hex value (e.g., `0xRRGGBBAA` or `#RRGGBBAA`).
+     *
+     * @default 0xddddddff
+     */
+    color?: string;
+
+    /**
+     * Specifies either a path to a TrueType/OpenType font file or a built-in
+     * system font name.
+     *
+     * For TrueType or OpenType font files, the file must be included with the
+     * application (e.g., `pkg:/fonts/SomeFontFile.ttf`). If no fontUri is
+     * specified, the System Default font is used.
+     *
+     * **Fixed Size System Fonts** (fontSize field is ignored):
+     * - `font:SmallestSystemFont`
+     * - `font:SmallSystemFont`
+     * - `font:MediumSystemFont`
+     * - `font:LargeSystemFont`
+     * - `font:SmallestBoldSystemFont`
+     * - `font:SmallBoldSystemFont`
+     * - `font:MediumBoldSystemFont`
+     * - `font:LargeBoldSystemFont`
+     *
+     * **Variable Size System Fonts** (fontSize field is respected):
+     * - `font:SystemFontFile`
+     * - `font:BoldSystemFontFile`
+     *
+     * @example
+     * // Using a built-in system font
+     * fontUri="font:MediumBoldSystemFont"
+     *
+     * @example
+     * // Using a custom TrueType font
+     * fontUri="pkg:/fonts/CustomFont.ttf"
+     *
+     * @default system default
+     */
+    fontUri?: SimpleLabelFontUri;
+
+    /**
+     * Specifies the size of the font in points.
+     *
+     * **Note:** This field is only respected when using variable size system fonts
+     * (`font:SystemFontFile` or `font:BoldSystemFontFile`) or custom font files.
+     * Fixed size system fonts ignore this value.
+     *
+     * @default system default
+     */
+    fontSize?: number;
+
+    /**
+     * Controls the horizontal origin (x=0 position) of the SimpleLabel's local
+     * coordinate system.
+     *
+     * - `"left"`: Left edge of text is at x=0
+     * - `"center"`: Horizontal center of text is at x=0
+     * - `"right"`: Right edge of text is at x=0
+     *
+     * @default "left"
+     */
+    horizOrigin?: HorizOrigin;
+
+    /**
+     * Controls the vertical origin (y=0 position) of the SimpleLabel's local
+     * coordinate system.
+     *
+     * - `"top"`: Top edge of text is at y=0
+     * - `"center"`: Vertical center of text is at y=0
+     * - `"baseline"`: Text baseline is at y=0
+     * - `"bottom"`: Bottom edge of text is at y=0
+     *
+     * @default "top"
+     */
+    vertOrigin?: VertOrigin;
+}

package/src/sg-nodes/simple-label.tsx

@@ -0,0 +1,59 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { ISimpleLabelProps } from "./simple-label.props";
+import { Component } from "./types";
+export type { HorizOrigin, VertOrigin, SimpleLabelFontUri, ISimpleLabelProps } from "./simple-label.props";
+
+/**
+ * SimpleLabel component for displaying a single line of text.
+ *
+ * SimpleLabel is a lightweight complement to the Label node. It supports simplified
+ * font style specification and is more memory efficient than the Label node.
+ *
+ * Use SimpleLabel when you need basic text rendering without the advanced features
+ * of the Label node (such as multi-line text, wrapping, or truncation).
+ *
+ * **Origin-based Positioning:**
+ * Unlike most nodes where translation moves the top-left corner, SimpleLabel uses
+ * origin-based positioning. The `horizOrigin` and `vertOrigin` fields determine
+ * which part of the text is positioned at the translation point.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with system font
+ * <simpleLabel
+ *     text="Hello World"
+ *     fontUri="font:MediumBoldSystemFont"
+ *     translation={[100, 100]}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Centered text at a specific position
+ * <simpleLabel
+ *     text="Centered Text"
+ *     fontUri="font:LargeSystemFont"
+ *     horizOrigin="center"
+ *     vertOrigin="center"
+ *     translation={[960, 540]}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom font with specific size
+ * <simpleLabel
+ *     text="Custom Font"
+ *     fontUri="font:SystemFontFile"
+ *     fontSize={24}
+ *     color="#FF6B6BFF"
+ * />
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/simplelabel}
+ */
+export const SimpleLabel: Component<ISimpleLabelProps> = props => {
+    return <simpleLabel {...props}></simpleLabel>;
+};

package/src/sg-nodes/sound-effect.props.ts

@@ -0,0 +1,130 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { ComponentRef } from "@roku-sdk/interfaces";
+
+import type { INodeProps } from "./node";
+import type { EventHandler } from "./types";
+
+/**
+ * Control values for the SoundEffect `control` field.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/soundeffect}
+ */
+export enum SoundEffectControl {
+    None = "none",
+    Play = "play",
+    Stop = "stop"
+}
+
+/**
+ * Playback state values reported by the SoundEffect `state` field.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/soundeffect}
+ */
+export enum SoundEffectState {
+    None = "none",
+    Playing = "playing",
+    Stopped = "stopped",
+    Finished = "finished",
+    TooManySounds = "toomanysounds",
+    NotReady = "notready"
+}
+
+/**
+ * Load status values reported by the SoundEffect `loadStatus` field.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/soundeffect}
+ */
+export enum SoundEffectLoadStatus {
+    None = "none",
+    Loading = "loading",
+    Ready = "ready",
+    Failed = "failed",
+    Flushed = "flushed"
+}
+
+/**
+ * Properties for the SoundEffect node.
+ *
+ * The SoundEffect node plays short audio sound effects triggered from UI events.
+ * Up to four simultaneous sounds can play at any time, in addition to audio from
+ * streaming content and TextToSpeech audio. All files must be WAV (PCM) format.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/soundeffect}
+ */
+export interface ISoundEffectProps extends INodeProps {
+    /**
+     * Specifies the URI of the WAV file. Sounds included as part of the application
+     * package can be referenced using the `pkg:/sounds` prefix. This may also specify
+     * the location of a WAV file on a remote server.
+     * @see {@link https://developer.roku.com/dev/docs/soundeffect | SoundEffect Fields}
+     */
+    uri?: string;
+    /**
+     * Controls the audio playback. Getting the value returns the most recent value set,
+     * or `"none"` if no value has been set.
+     *
+     * - `"none"` -- No effect.
+     * - `"play"` -- Start playing the audio. Restarts if already playing. If `loadStatus`
+     *   is not `"ready"`, the sound will not play and `state` becomes `"notready"`.
+     * - `"stop"` -- Stop playing the audio if it is currently playing.
+     *
+     * @default "none"
+     * @see {@link https://developer.roku.com/dev/docs/soundeffect | SoundEffect Fields}
+     */
+    control?: SoundEffectControl;
+    /**
+     * The volume as a percentage of full volume (0--100). Use 50 for normal volume.
+     * @default 50
+     * @see {@link https://developer.roku.com/dev/docs/soundeffect | SoundEffect Fields}
+     */
+    volume?: number;
+    /**
+     * Fired when the playback state changes.
+     *
+     * Possible values: `"none"`, `"playing"`, `"stopped"`, `"finished"`,
+     * `"toomanysounds"`, `"notready"`.
+     */
+    onState?: EventHandler<SoundEffectState>;
+    /**
+     * Fired when the load status of the sound file changes.
+     *
+     * Possible values: `"none"`, `"loading"`, `"ready"`, `"failed"`, `"flushed"`.
+     */
+    onLoadStatus?: EventHandler<SoundEffectLoadStatus>;
+}
+
+/**
+ * Handle for imperative control of a {@link SoundEffect} component, obtained via the `ref` prop.
+ *
+ * Extends {@link ComponentRef} with convenience methods that map to
+ * {@link SoundEffectControl} values, so you can drive playback without manually
+ * setting the `control` prop.
+ *
+ * Unlike {@link import("./video").VideoRef | VideoRef} and
+ * {@link import("./audio").AudioRef | AudioRef}, SoundEffect only supports
+ * `play` and `stop` — there is no pause, resume, or skip.
+ *
+ * @example
+ * ```tsx
+ * import { SoundEffect, SoundEffectRef, Button } from "@roku-sdk/components";
+ *
+ * const ClickSound = () => {
+ *   let sfxRef!: SoundEffectRef;
+ *
+ *   return (
+ *     <>
+ *       <Button text="Play" onButtonSelected={() => sfxRef.play()} />
+ *       <SoundEffect ref={sfxRef} uri="pkg:/sounds/click.wav" volume={50} />
+ *     </>
+ *   );
+ * };
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/soundeffect}
+ */
+export interface SoundEffectRef extends ComponentRef<ISoundEffectProps> {
+    play: () => void;
+    stop: () => void;
+}

package/src/sg-nodes/sound-effect.tsx

@@ -0,0 +1,65 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { registerImperativeMethods, setPropMethod } from "@roku-sdk/solid";
+
+import type { ISoundEffectProps } from "./sound-effect.props";
+export { SoundEffectControl, SoundEffectState, SoundEffectLoadStatus } from "./sound-effect.props";
+
+export type { ISoundEffectProps, SoundEffectRef } from "./sound-effect.props";
+
+import { Component } from "./types";
+
+registerImperativeMethods("soundEffect", {
+    play: setPropMethod("control", "play"),
+    stop: setPropMethod("control", "stop")
+});
+
+/**
+ * SoundEffect plays short audio sound effects that can be triggered from UI events.
+ * Files can be installed locally as part of the package or dynamically downloaded from
+ * the network. All files must be WAV (PCM) format. Up to four simultaneous sounds can
+ * play at any time.
+ *
+ * For local files, the convention is to include WAV files in a directory named `sounds`.
+ * For downloaded files, a least-recently-used (LRU) mechanism keeps the most recently
+ * played sounds in temporary storage on the device.
+ *
+ * Playback can be controlled declaratively via the `control` prop or imperatively
+ * via a {@link SoundEffectRef} obtained through the `ref` prop.
+ *
+ * @example
+ * ```tsx
+ * // Declarative control via the control prop
+ * <soundEffect
+ *     uri="pkg:/sounds/click.wav"
+ *     control={SoundEffectControl.Play}
+ *     volume={50}
+ *     onState={(state) => console.log("SoundEffect state:", state)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Imperative control via ref
+ * let sfxRef!: SoundEffectRef;
+ * <soundEffect ref={sfxRef} uri="pkg:/sounds/click.wav" volume={50} />
+ * // Then trigger playback: sfxRef.play()
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Network-hosted sound with load status monitoring
+ * <soundEffect
+ *     uri="https://example.com/sounds/alert.wav"
+ *     onLoadStatus={(status) => {
+ *         if (status === SoundEffectLoadStatus.Ready) console.log("Sound ready to play");
+ *     }}
+ * />
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/soundeffect}
+ */
+export const SoundEffect: Component<ISoundEffectProps> = props => {
+    return <soundEffect {...props} />;
+};