@roku-sdk/components 0.0.0-stage → 2.18.0

package/src/sg-nodes/animated-image.props.ts

@@ -0,0 +1,64 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./group.props";
+import type { LoadDisplayMode } from "./poster.props";
+import type { EventHandler, ResType, Uri } from "./types";
+
+/** Commands accepted by the AnimatedImage `control` field. */
+export type AnimatedImageControl = "loop" | "pause" | "play" | "rewind";
+
+/** Values reported by the AnimatedImage `state` field. */
+export type AnimatedImageState = "downloading" | "init" | "first" | "decode" | "stop" | "error";
+
+/**
+ * MIME types accepted by the Roku OS AnimatedImage decoder.
+ * Matching is exact and case-sensitive; any other value fails with an
+ * unsupported-format error. `"video/lottie+json"` covers both Lottie JSON
+ * and zipped `.lottie` files.
+ */
+export type AnimatedImageMimeType = "video/mp4" | "video/webp" | "image/webp" | "video/lottie+json";
+
+/** Properties for the native AnimatedImage node. */
+export interface IAnimatedImageProps extends IGroupProps {
+    /** Width in local coordinates, or the decoded media width when zero. */
+    width?: ResType<number>;
+    /** Height in local coordinates, or the decoded media height when zero. */
+    height?: ResType<number>;
+    /** Requested media decode width; decode-time scaling depends on the format. */
+    loadWidth?: ResType<number>;
+    /** Requested media decode height; decode-time scaling depends on the format. */
+    loadHeight?: ResType<number>;
+    /** Scales decoded media within this node's dimensions. */
+    loadDisplayMode?: LoadDisplayMode;
+    /**
+     * MIME type used to select the decoder. Optional: when omitted, the firmware
+     * detects the format from the file header, so prefer leaving it unset over
+     * guessing. A wrong value is a hard decode error.
+     */
+    mimeType?: AnimatedImageMimeType;
+    /** Playback command. `"stop"` is a reported state, not a command. */
+    control?: AnimatedImageControl;
+    /** Bitmap URI shown while media is downloading or initializing. */
+    loadingBitmapUri?: Uri;
+    /** Opacity for `loadingBitmapUri`. */
+    loadingBitmapOpacity?: number;
+    /** Bitmap URI shown when decoding fails. */
+    failedBitmapUri?: Uri;
+    /** Opacity for `failedBitmapUri`. */
+    failedBitmapOpacity?: number;
+    /** Text announced by the audio guide when this node has focus. */
+    audioGuideText?: string;
+    /** Fired when the read-only playback state changes. */
+    onState?: EventHandler<AnimatedImageState>;
+    /** Fired when the read-only error text changes. */
+    onError?: EventHandler<string>;
+    /** Fired when the decoded media width changes. */
+    onMediaWidth?: EventHandler<number>;
+    /** Fired when the decoded media height changes. */
+    onMediaHeight?: EventHandler<number>;
+    /**
+     * Media URI. Direct intrinsic users must set this after configuration and handlers.
+     */
+    uri?: Uri;
+}

package/src/sg-nodes/animated-image.tsx

@@ -0,0 +1,23 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IAnimatedImageProps } from "./animated-image.props";
+import { Component, splitProps } from "./types";
+
+export type {
+    AnimatedImageControl,
+    AnimatedImageMimeType,
+    AnimatedImageState,
+    IAnimatedImageProps
+} from "./animated-image.props";
+
+/**
+ * Thin binding for the native AnimatedImage node.
+ *
+ * Native qualification is pending; observe `onState` and `onError` for decode results.
+ * Installs configuration and handlers before `uri`, which starts loading.
+ */
+export const AnimatedImage: Component<IAnimatedImageProps> = props => {
+    const [local, rest] = splitProps(props, ["uri"]);
+    return <animatedImage {...rest} uri={local.uri}></animatedImage>;
+};

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

@@ -0,0 +1,292 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { ComponentRef } from "@roku-sdk/interfaces";
+
+import type { INodeProps } from "./node";
+import type { EventHandler, Vector2D } from "./types";
+
+/**
+ * Interpolator functions available for Animation easing.
+ *
+ * Controls how the animation progresses over time. Functions are divided into
+ * ease-in (beginning) and ease-out (end) portions. The `piecewise` option allows
+ * custom control over the ease-in/ease-out split via `easeInPercent` and `easeOutPercent`.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/animation}
+ */
+export type EaseFunction =
+    | "linear"
+    | "inQuad"
+    | "inCubic"
+    | "inQuartic"
+    | "inQuintic"
+    | "inExpo"
+    | "outQuad"
+    | "outCubic"
+    | "outQuartic"
+    | "outQuintic"
+    | "outExpo"
+    | "inOutQuad"
+    | "inOutCubic"
+    | "inOutQuartic"
+    | "inOutQuintic"
+    | "inOutExpo"
+    | "piecewise";
+
+/**
+ * Animation control commands.
+ *
+ * - `none`: Initial state with no associated action.
+ * - `start`: Always plays the animation from the beginning.
+ * - `stop`: Stops the animation in its current state.
+ * - `pause`: Pauses the animation in its current state.
+ * - `resume`: If paused, resumes from the current state; otherwise plays from the beginning.
+ * - `finish`: Jumps to the end of the animation, setting all fields to final values.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/animationbase}
+ */
+export type AnimationControl = "none" | "start" | "stop" | "pause" | "resume" | "finish";
+
+/**
+ * Animation state values reported by the `state` field.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/animationbase}
+ */
+export type AnimationState = "running" | "paused" | "stopped";
+
+/**
+ * Properties shared by Animation, SequentialAnimation, and ParallelAnimation.
+ *
+ * AnimationBase provides basic functionality for animating screen elements such as
+ * moving them across the display, fading them in and out, or changing their color.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/animationbase}
+ */
+export interface IAnimationBaseProps extends INodeProps {
+    /** Controls the animation. @default "none" */
+    control?: AnimationControl;
+    /** Controls whether the animation stops when it finishes (false) or repeats from the beginning (true). @default false */
+    repeat?: boolean;
+    /** Delays the start of the animation by the specified number of seconds. @default 0 */
+    delay?: number;
+    /** Fired when the animation state changes. Values: "running", "paused", "stopped". */
+    onState?: EventHandler<AnimationState>;
+}
+
+/**
+ * Properties for the Animation node.
+ *
+ * Animation provides animations of renderable nodes by applying interpolator functions
+ * to the values in specified renderable node fields. Requires child field interpolator nodes
+ * (FloatFieldInterpolator, Vector2DFieldInterpolator, ColorFieldInterpolator) for each
+ * animated field.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/animation}
+ */
+export interface IAnimationProps extends IAnimationBaseProps {
+    /** Duration of the animation in seconds. @default 0 */
+    duration?: number;
+    /** Interpolator function used for the animation. @default "outCubic" */
+    easeFunction?: EaseFunction;
+    /**
+     * If easeFunction is set to "piecewise", sets the percentage of the animation duration
+     * during which ease-in is applied. The sum of easeInPercent and easeOutPercent must be <= 1.
+     * Ignored for all other easeFunction values.
+     * @default 0.5
+     */
+    easeInPercent?: number;
+    /**
+     * If easeFunction is set to "piecewise", sets the percentage of the animation duration
+     * during which ease-out is applied. The sum of easeInPercent and easeOutPercent must be <= 1.
+     * Ignored for all other easeFunction values.
+     * @default 0.5
+     */
+    easeOutPercent?: number;
+    /**
+     * Set to true to skip animations on lower-performing Roku devices. When skipped,
+     * setting control to "start" causes state to transition running -> finished immediately,
+     * allowing any state observers to be properly called.
+     * @default false
+     */
+    optional?: boolean;
+    /** Fired when the willBeSkipped status changes. Indicates whether the animation will be skipped (rendered in its final state). */
+    onWillBeSkipped?: EventHandler<boolean>;
+}
+
+/**
+ * Properties shared by all field interpolator nodes.
+ *
+ * Field interpolators define keyframe animation sequences that are applied to
+ * specific fields of SceneGraph nodes. They are used as children of Animation nodes.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/floatfieldinterpolator}
+ */
+export interface IFieldInterpolatorPropsBase extends INodeProps {
+    /**
+     * Specifies the field to interpolate. The string should contain the ID of a node and
+     * the name of a field, separated by a dot (e.g. "myPoster.opacity").
+     * @default ""
+     */
+    fieldToInterp?: string;
+    /**
+     * Keyframe positions as an array of floats from 0 to 1 indicating the percentage of
+     * the animation where the corresponding keyValue should occur. Must match the length of keyValue.
+     * @default []
+     */
+    key?: number[];
+    /**
+     * Specifies the current interpolation progress (0 to 1) used to compute the field value.
+     * Typically driven by a parent Animation node.
+     * @default 0.0
+     */
+    fraction?: number;
+    /** Enables animation to be played in reverse. @default false */
+    reverse?: boolean;
+}
+
+/**
+ * Properties for the FloatFieldInterpolator node.
+ *
+ * Specifies a keyframe animation sequence to be applied to a floating point field
+ * of a node (such as opacity, width, or height).
+ *
+ * @see {@link https://developer.roku.com/dev/docs/floatfieldinterpolator}
+ */
+export interface IFloatFieldInterpolatorProps extends IFieldInterpolatorPropsBase {
+    /**
+     * Float values at each keyframe. Each value corresponds to a value in the key array.
+     * Must match the length of key.
+     * @default []
+     */
+    keyValue?: number[];
+}
+
+/**
+ * Properties for the ColorFieldInterpolator node.
+ *
+ * Specifies a keyframe animation sequence to be applied to a color field of a node.
+ * Interpolation is performed in HSV color space for visually pleasing results.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/colorfieldinterpolator}
+ */
+export interface IColorFieldInterpolatorProps extends IFieldInterpolatorPropsBase {
+    /**
+     * Color values at each keyframe (e.g. "0xFF0000FF" for red). Each value corresponds
+     * to a value in the key array. Must match the length of key.
+     * @default []
+     */
+    keyValue?: string[];
+}
+
+/**
+ * Properties for the Vector2DFieldInterpolator node.
+ *
+ * Specifies a keyframe animation sequence to be applied to a Vector2D field of a node,
+ * most commonly used to animate translation coordinates.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/vector2dfieldinterpolator}
+ */
+export interface IVector2DFieldInterpolatorProps extends IFieldInterpolatorPropsBase {
+    /**
+     * Vector2D values at each keyframe. Each value corresponds to a value in the key array.
+     * Must match the length of key.
+     * @default []
+     */
+    keyValue?: Vector2D[];
+}
+
+/**
+ * Handle for imperative control of an {@link Animation} or {@link SequentialAnimation}
+ * component, obtained via the `ref` prop.
+ *
+ * Extends {@link ComponentRef} with convenience methods that map to
+ * {@link AnimationControl} values, so you can drive animation playback without
+ * manually setting the `control` prop.
+ *
+ * Uses {@link IAnimationBaseProps} as the base so it works with both
+ * `Animation` and `SequentialAnimation`.
+ *
+ * @example
+ * ```tsx
+ * import { Animation, AnimationRef, FloatFieldInterpolator, Button } from "@roku-sdk/components";
+ *
+ * const FadeDemo = () => {
+ *   let animRef!: AnimationRef;
+ *
+ *   return (
+ *     <>
+ *       <Button text="Start" onButtonSelected={() => animRef.start()} />
+ *       <Button text="Pause" onButtonSelected={() => animRef.pause()} />
+ *       <Animation ref={animRef} duration={2} easeFunction="linear">
+ *         <FloatFieldInterpolator
+ *           key={[0, 1]}
+ *           keyValue={[1, 0]}
+ *           fieldToInterp="myPoster.opacity"
+ *         />
+ *       </Animation>
+ *     </>
+ *   );
+ * };
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/animationbase}
+ */
+export interface AnimationRef extends ComponentRef<IAnimationBaseProps> {
+    start: () => void;
+    stop: () => void;
+    pause: () => void;
+    resume: () => void;
+    finish: () => void;
+    /**
+     * Writes `duration` immediately instead of through the reactive `duration` prop.
+     *
+     * Re-targeting a running animation requires the new duration to reach the node
+     * before `stop()`. A reactive prop write is deferred to after the current effect
+     * body, so it would land after the following `start()` and the animation would
+     * run its first frames against the previous duration.
+     */
+    setDuration: (duration: number) => void;
+    /** Writes `easeFunction` immediately. See {@link AnimationRef.setDuration}. */
+    setEaseFunction: (easeFunction: EaseFunction) => void;
+}
+
+/**
+ * Handle for imperative control of a {@link FloatFieldInterpolator}, obtained via the `ref` prop.
+ *
+ * `setKeyValue` writes `keyValue` immediately instead of through the reactive prop.
+ * Re-targeting an animation requires `stop`, the new `keyValue`, and `start` to land
+ * in that order; a deferred prop write reorders it to `stop`, `start`, `keyValue`,
+ * leaving the restarted animation interpolating toward the previous target.
+ */
+export interface FloatFieldInterpolatorRef extends ComponentRef<IFloatFieldInterpolatorProps> {
+    setKeyValue: (keyValue: number[]) => void;
+    /**
+     * Writes `fieldToInterp` immediately. Needed when the interpolator is re-pointed at a
+     * new node in the same batch that starts the animation, since a zero-duration start
+     * applies the final `keyValue` to whichever node `fieldToInterp` names at that moment.
+     */
+    setFieldToInterp: (fieldToInterp: string) => void;
+}
+
+/**
+ * Handle for imperative control of a {@link ColorFieldInterpolator}, obtained via the `ref` prop.
+ *
+ * See {@link FloatFieldInterpolatorRef} for why `setKeyValue` bypasses the reactive prop.
+ */
+export interface ColorFieldInterpolatorRef extends ComponentRef<IColorFieldInterpolatorProps> {
+    setKeyValue: (keyValue: string[]) => void;
+    /** Writes `fieldToInterp` immediately. See {@link FloatFieldInterpolatorRef.setFieldToInterp}. */
+    setFieldToInterp: (fieldToInterp: string) => void;
+}
+
+/**
+ * Handle for imperative control of a {@link Vector2DFieldInterpolator}, obtained via the `ref` prop.
+ *
+ * See {@link FloatFieldInterpolatorRef} for why `setKeyValue` bypasses the reactive prop.
+ */
+export interface Vector2DFieldInterpolatorRef extends ComponentRef<IVector2DFieldInterpolatorProps> {
+    setKeyValue: (keyValue: Vector2D[]) => void;
+    /** Writes `fieldToInterp` immediately. See {@link FloatFieldInterpolatorRef.setFieldToInterp}. */
+    setFieldToInterp: (fieldToInterp: string) => void;
+}

package/src/sg-nodes/animation.tsx

@@ -0,0 +1,190 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { registerImperativeMethods, setPropMethod } from "@roku-sdk/solid";
+
+import type {
+    IAnimationBaseProps,
+    IAnimationProps,
+    IColorFieldInterpolatorProps,
+    IFloatFieldInterpolatorProps,
+    IVector2DFieldInterpolatorProps
+} from "./animation.props";
+export type {
+    EaseFunction,
+    AnimationControl,
+    AnimationState,
+    IAnimationBaseProps,
+    IAnimationProps,
+    IFieldInterpolatorPropsBase,
+    IFloatFieldInterpolatorProps,
+    IColorFieldInterpolatorProps,
+    IVector2DFieldInterpolatorProps,
+    AnimationRef,
+    FloatFieldInterpolatorRef,
+    ColorFieldInterpolatorRef,
+    Vector2DFieldInterpolatorRef
+} from "./animation.props";
+
+import { Component } from "./types";
+
+const animationMethods = {
+    start: setPropMethod("control", "start"),
+    stop: setPropMethod("control", "stop"),
+    pause: setPropMethod("control", "pause"),
+    resume: setPropMethod("control", "resume"),
+    finish: setPropMethod("control", "finish"),
+    setDuration: setPropMethod("duration"),
+    setEaseFunction: setPropMethod("easeFunction")
+};
+
+// Re-targeting a running animation has to deliver duration, easeFunction and keyValue
+// alongside the surrounding stop/start in a single batch, in that order. Reactive prop
+// writes are deferred to after the current effect body, which reorders them after the
+// trailing start.
+//
+// `fieldToInterp` needs the same treatment whenever the interpolator is re-pointed at a
+// different node in the same batch that starts the animation: a zero-duration start
+// applies the final keyValue to whatever `fieldToInterp` currently names, so a deferred
+// write would snap the previous target instead of the new one.
+const fieldInterpolatorMethods = {
+    setKeyValue: setPropMethod("keyValue"),
+    setFieldToInterp: setPropMethod("fieldToInterp")
+};
+
+registerImperativeMethods("animation", animationMethods);
+registerImperativeMethods("sequentialAnimation", animationMethods);
+registerImperativeMethods("floatFieldInterpolator", fieldInterpolatorMethods);
+registerImperativeMethods("colorFieldInterpolator", fieldInterpolatorMethods);
+registerImperativeMethods("vector2dFieldInterpolator", fieldInterpolatorMethods);
+
+/**
+ * Animation component for animating renderable node fields using interpolator functions.
+ *
+ * Requires child field interpolator nodes (FloatFieldInterpolator, Vector2DFieldInterpolator,
+ * ColorFieldInterpolator) to define which fields to animate. Supports various easing functions
+ * to control the animation's speed curve.
+ *
+ * Playback can be controlled declaratively via the `control` prop or imperatively
+ * via an {@link AnimationRef} obtained through the `ref` prop.
+ *
+ * @example
+ * ```tsx
+ * <animation duration={1} repeat={true} easeFunction="linear" control="start">
+ *     <vector2dFieldInterpolator
+ *         key={[0.0, 0.5, 1.0]}
+ *         keyValue={[[0, 0], [500, 0], [500, 200]]}
+ *         fieldToInterp="myPoster.translation"
+ *     />
+ * </animation>
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/animation}
+ */
+export const Animation: Component<IAnimationProps> = props => {
+    return <animation {...props}></animation>;
+};
+
+/**
+ * FloatFieldInterpolator animates a floating point field of a node through a series of keyframes.
+ *
+ * Typically used as a child of an Animation node to animate fields like opacity, width, or height.
+ *
+ * @example
+ * ```tsx
+ * <animation duration={10} repeat={true} control="start" easeFunction="linear">
+ *     <floatFieldInterpolator
+ *         key={[0.0, 0.5, 1.0]}
+ *         keyValue={[1.0, 0.0, 1.0]}
+ *         fieldToInterp="myPoster.opacity"
+ *     />
+ * </animation>
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/floatfieldinterpolator}
+ */
+export const FloatFieldInterpolator: Component<IFloatFieldInterpolatorProps> = props => {
+    return <floatFieldInterpolator {...props}></floatFieldInterpolator>;
+};
+
+/**
+ * ColorFieldInterpolator animates a color field of a node through a series of keyframes.
+ *
+ * Interpolation is performed in HSV color space for visually pleasing transitions.
+ * Typically used as a child of an Animation node.
+ *
+ * @example
+ * ```tsx
+ * <animation duration={10} repeat={true} control="start" easeFunction="linear">
+ *     <colorFieldInterpolator
+ *         key={[0.0, 0.5, 1.0]}
+ *         keyValue={["0x0000CCFF", "0x00000FFF", "0x0000CCFF"]}
+ *         fieldToInterp="myRectangle.color"
+ *     />
+ * </animation>
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/colorfieldinterpolator}
+ */
+export const ColorFieldInterpolator: Component<IColorFieldInterpolatorProps> = props => {
+    return <colorFieldInterpolator {...props}></colorFieldInterpolator>;
+};
+
+/**
+ * Vector2DFieldInterpolator animates a Vector2D field of a node through a series of keyframes.
+ *
+ * Most commonly used to animate translation coordinates for moving nodes across the screen.
+ * Typically used as a child of an Animation node.
+ *
+ * @example
+ * ```tsx
+ * <animation duration={10} repeat={true} control="start" easeFunction="linear">
+ *     <vector2dFieldInterpolator
+ *         key={[0.0, 0.5, 1.0]}
+ *         keyValue={[[318, 8], [656, 8], [318, 8]]}
+ *         fieldToInterp="myLabel.translation"
+ *     />
+ * </animation>
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/vector2dfieldinterpolator}
+ */
+export const Vector2DFieldInterpolator: Component<IVector2DFieldInterpolatorProps> = props => {
+    return <vector2dFieldInterpolator {...props}></vector2dFieldInterpolator>;
+};
+
+/**
+ * SequentialAnimation runs a set of child animations one after another.
+ *
+ * The state field is set to "running" while any child animation is in progress.
+ * Once all children have completed, the state becomes "stopped". Child animation
+ * `delay` fields can be used to add gaps between sequential animations.
+ *
+ * Playback can be controlled declaratively via the `control` prop or imperatively
+ * via an {@link AnimationRef} obtained through the `ref` prop.
+ *
+ * @example
+ * ```tsx
+ * <sequentialAnimation repeat={true} control="start">
+ *     <animation duration={2} easeFunction="linear">
+ *         <floatFieldInterpolator
+ *             key={[0, 0.5, 1]}
+ *             keyValue={[0.2, 1, 0.2]}
+ *             fieldToInterp="rect1.opacity"
+ *         />
+ *     </animation>
+ *     <animation duration={2} easeFunction="linear">
+ *         <floatFieldInterpolator
+ *             key={[0, 0.5, 1]}
+ *             keyValue={[0.2, 1, 0.2]}
+ *             fieldToInterp="rect2.opacity"
+ *         />
+ *     </animation>
+ * </sequentialAnimation>
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/sequentialanimation}
+ */
+export const SequentialAnimation: Component<IAnimationBaseProps> = props => {
+    return <sequentialAnimation {...props}></sequentialAnimation>;
+};