@roku-sdk/components 0.0.0-stage → 2.19.0

package/src/__tests__/tween.test.tsx

@@ -0,0 +1,195 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+// ---------------------------------------------------------------------------
+// Tween renders one `<tween>`: the native node when firmware reports the "tween" feature,
+// otherwise the compat shim. It sends the native node only the fields it has.
+// ---------------------------------------------------------------------------
+
+import "@roku-sdk/compat";
+
+import { afterEach, beforeEach, describe, expect, jest, test } from "@jest/globals";
+import type { AnimationState, Vector2D } from "@roku-sdk/components";
+import type { DomNode } from "@roku-sdk/interfaces";
+import { hasFeature } from "@roku-sdk/runtime/has-feature";
+import { batch, createSignal, type JSX, tmTransaction } from "@roku-sdk/solid";
+
+import { commitEarly, createAnchorNode, installSolidTestRenderer } from "../test-helpers/tween-test-setup";
+import { Tween } from "../tween";
+
+jest.mock("@roku-sdk/runtime/has-feature", () => ({
+    // The side-effect compat import loads this factory before the imported jest binding.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    hasFeature: require("@jest/globals").jest.fn()
+}));
+
+describe("Tween", () => {
+    let render: ReturnType<typeof installSolidTestRenderer>;
+    let setProperty: jest.SpiedFunction<typeof tmTransaction.setProperty>;
+    let createElement: jest.SpiedFunction<typeof tmTransaction.createElement>;
+    let dispose: (() => void) | undefined;
+
+    beforeEach(() => {
+        render = installSolidTestRenderer();
+        setProperty = jest.spyOn(tmTransaction, "setProperty");
+        createElement = jest.spyOn(tmTransaction, "createElement");
+    });
+
+    afterEach(() => {
+        dispose?.();
+        dispose = undefined;
+        jest.mocked(hasFeature).mockReset();
+        setProperty.mockRestore();
+        createElement.mockRestore();
+    });
+
+    const createdTypes = (): string[] => createElement.mock.results.map(r => (r.value as DomNode).t);
+
+    const mount = (native: boolean, renderTween: (target: () => DomNode | undefined) => JSX.Element): DomNode => {
+        jest.mocked(hasFeature).mockReturnValue(native);
+        let target: DomNode | undefined;
+        dispose = render(
+            () => (
+                <group>
+                    <rectangle ref={(el: unknown) => (target = el as DomNode)} />
+                    {renderTween(() => target)}
+                </group>
+            ),
+            createAnchorNode()
+        );
+        commitEarly();
+        const index = createElement.mock.calls.findIndex(([tag]) => tag === "tween");
+        return createElement.mock.results[index].value as DomNode;
+    };
+    const writes = (node: DomNode, name: string): unknown[] =>
+        setProperty.mock.calls.filter(([n, field]) => n === node && field === name).map(([, , value]) => value);
+
+    describe("node selection", () => {
+        test("creates the native node alone when the firmware reports the feature", () => {
+            const tween = mount(true, target => <Tween targetRef={target} axis="x" targetValue={100} />);
+
+            expect(tween.t).toBe("tween");
+            expect(createdTypes()).toEqual(["group", "rectangle", "tween"]);
+        });
+
+        test("creates the compat shim alone when the firmware does not report the feature", () => {
+            const tween = mount(false, target => <Tween targetRef={target} axis="x" targetValue={100} />);
+
+            expect(tween.t).toBe("RsgTweenShim");
+            expect(createdTypes()).toEqual(["group", "rectangle", "RsgTweenShim"]);
+        });
+    });
+
+    describe("native field contract", () => {
+        test('sends an axis="all" targetVector as given and writes no targetValue', () => {
+            const tween = mount(true, target => <Tween targetRef={target} axis="all" targetVector={[40, 90]} />);
+
+            expect(writes(tween, "targetVector")).toContainEqual([40, 90]);
+            expect(writes(tween, "targetValue").filter(v => v !== undefined)).toHaveLength(0);
+        });
+
+        test("sends the target immediately", () => {
+            const tween = mount(true, target => <Tween targetRef={target} axis="x" targetValue={100} />);
+
+            expect(writes(tween, "targetValue")).toContain(100);
+        });
+
+        test.each([true, false])("omits the state observer without a callback (native=%s)", native => {
+            const tween = mount(native, target => <Tween targetRef={target} targetValue={100} />);
+
+            expect(writes(tween, "onAnimationState").filter(value => value !== undefined)).toHaveLength(0);
+        });
+
+        test("reactively installs, replaces and removes the state callback", () => {
+            type Handler = NonNullable<Parameters<typeof Tween>[0]["onAnimationState"]>;
+            const [callback, setCallback] = createSignal<Handler | undefined>();
+            const first = jest.fn<Handler>();
+            const second = jest.fn<Handler>();
+            const tween = mount(true, target => <Tween targetRef={target} onAnimationState={callback()} />);
+            expect(writes(tween, "onAnimationState").filter(value => value !== undefined)).toHaveLength(0);
+
+            setCallback(() => first);
+            commitEarly();
+            const adapter = writes(tween, "onAnimationState").at(-1) as (t: [AnimationState, Vector2D]) => void;
+            expect(typeof adapter).toBe("function");
+            adapter(["running", [10, 20]]);
+            expect(first).toHaveBeenCalledWith("running", [10, 20]);
+
+            setCallback(() => second);
+            commitEarly();
+            adapter(["stopped", [30, 40]]);
+            expect(second).toHaveBeenCalledWith("stopped", [30, 40]);
+            expect(first).toHaveBeenCalledTimes(1);
+
+            setCallback(undefined);
+            commitEarly();
+            expect(writes(tween, "onAnimationState").at(-1)).toBeUndefined();
+        });
+
+        test("forwards onAnimationState as (state, value)", () => {
+            const onAnimationState = jest.fn();
+            const tween = mount(true, target => (
+                <Tween targetRef={target} axis="x" targetValue={100} onAnimationState={onAnimationState} />
+            ));
+
+            const handler = writes(tween, "onAnimationState")[0] as (t: [AnimationState, Vector2D]) => void;
+            handler(["running", [10, 20]]);
+
+            expect(onAnimationState).toHaveBeenCalledWith("running", [10, 20]);
+        });
+    });
+
+    test("targetNode takes precedence over the deprecated targetRef alias", () => {
+        const legacy = { t: "rectangle", r: { id: 999 }, c: [] } as unknown as DomNode;
+        const tween = mount(true, target => <Tween targetNode={target} targetRef={legacy} targetValue={100} />);
+        const targets = writes(tween, "targetNode");
+        expect(targets).toHaveLength(1);
+        expect(targets[0]).not.toBe(legacy);
+    });
+
+    describe("target switch", () => {
+        test.each([
+            ["value first", true],
+            ["target first", false]
+        ])("writes the new targetNode before the trigger that goes with it (%s)", (_, valueFirst) => {
+            jest.mocked(hasFeature).mockReturnValue(true);
+            const nodes: Record<string, DomNode> = {};
+            const [onB, setOnB] = createSignal(false);
+            const [to, setTo] = createSignal(100);
+            dispose = render(
+                () => (
+                    <group>
+                        <rectangle ref={(el: unknown) => (nodes.a = el as DomNode)} />
+                        <rectangle ref={(el: unknown) => (nodes.b = el as DomNode)} />
+                        <Tween targetNode={() => (onB() ? nodes.b : nodes.a)} axis="x" targetValue={to()} />
+                    </group>
+                ),
+                createAnchorNode()
+            );
+            commitEarly();
+            const tween = createElement.mock.results[createElement.mock.calls.findIndex(([t]) => t === "tween")]
+                .value as DomNode;
+            setProperty.mockClear();
+
+            batch(() => {
+                if (valueFirst) setTo(300);
+                setOnB(true);
+                if (!valueFirst) setTo(300);
+            });
+            commitEarly();
+
+            const order = setProperty.mock.calls
+                .filter(([n, field]) => n === tween && (field === "targetNode" || field === "targetValue"))
+                .map(([, field, value]) => (field === "targetNode" ? (value === nodes.b ? "B" : "?") : value));
+            expect(order).toEqual(["B", 300]);
+        });
+    });
+
+    describe("shim field contract", () => {
+        test("writes no animationNode", () => {
+            const tween = mount(false, target => <Tween targetRef={target} axis="x" targetValue={100} />);
+
+            expect(writes(tween, "animationNode")).toHaveLength(0);
+        });
+    });
+});

package/src/blended-busy-spinner.props.ts

@@ -0,0 +1,37 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IBusySpinnerProps } from "./sg-nodes/busy-spinner.props";
+
+/**
+ * Properties for the BlendedBusySpinner node.
+ *
+ * BlendedBusySpinner extends BusySpinner with blend color support, displaying an animated
+ * spinning indicator to show that content is loading or an operation is in progress.
+ *
+ * The spinner inherits all BusySpinner properties (control, clockwise, spinInterval, uri)
+ * and adds blend color customization.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/busyspinner}
+ *
+ * @example
+ * // Basic usage with default appearance
+ * <BlendedBusySpinner control="start" translation={[100, 100]} uri="pkg:/images/loader.png" />
+ *
+ * @example
+ * // Custom spinner with speed control and blend color
+ * <BlendedBusySpinner
+ *   control="start"
+ *   clockwise={false}
+ *   spinInterval={1}
+ *   uri="pkg:/images/custom-spinner.png"
+ *   blendColor="0xFF0000FF"
+ * />
+ */
+export interface IBlendedBusySpinnerProps extends IBusySpinnerProps {
+    /**
+     * Specifies the blend color for the spinner image.
+     * The blend color is applied to the spinner bitmap to modify its appearance.
+     */
+    blendColor?: string;
+}

package/src/blended-busy-spinner.tsx

@@ -0,0 +1,13 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IBlendedBusySpinnerProps } from "./blended-busy-spinner.props";
+import { retainAsset } from "./retain-asset";
+import { Component } from "./sg-nodes/types";
+import BlendedBusySpinnerXML from "./xml-components/blended-busy-spinner/BlendedBusySpinner.xml";
+export type { IBlendedBusySpinnerProps } from "./blended-busy-spinner.props";
+
+export const BlendedBusySpinner: Component<IBlendedBusySpinnerProps> = props => {
+    retainAsset(BlendedBusySpinnerXML);
+    return <blendedBusySpinner {...props}></blendedBusySpinner>;
+};

package/src/bounding-tracker.props.ts

@@ -0,0 +1,18 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./sg-nodes/group.props";
+import type { EventHandler, JSX } from "./sg-nodes/types";
+
+export interface IBoundingRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+export interface IBoundingTrackerProps extends IGroupProps {
+    doMeasure?: boolean;
+    onBoundsChange?: EventHandler<IBoundingRect>;
+    children?: JSX.Element;
+}

package/src/bounding-tracker.tsx

@@ -0,0 +1,13 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IBoundingTrackerProps } from "./bounding-tracker.props";
+import { Component } from "./index";
+import { retainAsset } from "./retain-asset";
+import BoundingTrackerXML from "./xml-components/bounding-tracker/BoundingTracker.xml";
+export type { IBoundingRect, IBoundingTrackerProps } from "./bounding-tracker.props";
+
+export const BoundingTracker: Component<IBoundingTrackerProps> = props => {
+    retainAsset(BoundingTrackerXML);
+    return <bounding-tracker {...props}>{props.children}</bounding-tracker>;
+};

package/src/button-row.tsx

@@ -0,0 +1,126 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+import {
+    Component,
+    EventHandler,
+    Focusable,
+    FocusableGroup,
+    IButtonDataProps,
+    ResType,
+    Uri,
+    Vector2D
+} from "@roku-sdk/components";
+import { createMemo, createSelector, For, Show } from "@roku-sdk/solid";
+
+interface ISingleButtonProps extends IButtonDataProps {
+    text?: string;
+}
+
+export type IButtonRecord = ISingleButtonProps | string;
+
+export interface IButtonRowProps extends IButtonDataProps {
+    buttons: IButtonRecord[];
+    translation?: ResType<Vector2D>;
+    onButtonFocused?: EventHandler<number>;
+    onButtonSelected?: EventHandler<number>;
+    opacity?: number;
+    focusIdx?: number;
+    itemSpacing?: number;
+    gainFocus?: boolean;
+}
+
+const buttonDataKeys: (keyof IButtonDataProps)[] = [
+    "textColor",
+    "focusedTextColor",
+    "textFont",
+    "focusedTextFont",
+    "focusFootprintBitmapUri",
+    "focusBitmapUri",
+    "iconUri",
+    "focusedIconUri",
+    "height",
+    "minWidth",
+    "maxWidth",
+    "showFocusFootprint"
+];
+
+const defaultButtonData: ISingleButtonProps = {
+    showFocusFootprint: true,
+    iconUri: "",
+    focusedIconUri: "",
+    textFont: "font:TinySystemFont",
+    focusedTextFont: "font:TinyBoldSystemFont"
+};
+
+const createButtonProps = (button: IButtonRecord, componentProps: IButtonDataProps): ISingleButtonProps => {
+    let buttonProps: ISingleButtonProps = buttonDataKeys.reduce(
+        (acc: ISingleButtonProps, key) => {
+            const componentValue = componentProps[key];
+            if (componentValue !== undefined) {
+                (acc[key] as number | boolean | Uri) = componentValue;
+            }
+            return acc;
+        },
+        { ...defaultButtonData }
+    );
+
+    if (typeof button === "string") {
+        buttonProps.text = button;
+    } else {
+        buttonProps = { ...buttonProps, ...button };
+    }
+    return buttonProps;
+};
+
+export const ButtonRow: Component<IButtonRowProps> = props => {
+    const focusIdx = () => props.focusIdx || 0;
+
+    const onButtonFocused: EventHandler<string | null> = (id: string | null) => {
+        if (props.onButtonFocused && id) {
+            props.onButtonFocused(parseInt(id.replace(props.id || "", "")));
+        }
+    };
+
+    const buttonsLength = createMemo(() => props.buttons.length);
+
+    // Create a stable array of button indices that only changes when length changes
+    const buttonIndices = createMemo(() => Array.from({ length: buttonsLength() }, (_, i) => i));
+    const isFocused = createSelector(focusIdx, (a, b) => (props.gainFocus === undefined || props.gainFocus) && a === b);
+
+    return (
+        <FocusableGroup id={props.id} rememberLastFocus={true} gainFocus={props.gainFocus} opacity={props.opacity}>
+            <Show when={buttonsLength() > 0}>
+                <layoutGroup
+                    layoutDirection="horiz"
+                    horizAlignment="left"
+                    translation={props.translation}
+                    itemSpacings={[props.itemSpacing || 32]}
+                >
+                    <For
+                        each={buttonIndices()}
+                        children={(index: number) => {
+                            const buttonAtIndex = (): IButtonRecord | undefined => props.buttons[index];
+                            const onButtonSelected: EventHandler<never> = () => props.onButtonSelected?.(index);
+                            return (
+                                <Show when={buttonAtIndex() !== undefined}>
+                                    <Focusable
+                                        nextFocusRight={`${props.id || ""}${index < buttonsLength() - 1 ? (index + 1).toString() : undefined}`}
+                                        nextFocusLeft={`${props.id || ""}${index > 0 ? (index - 1).toString() : undefined}`}
+                                    >
+                                        <button
+                                            gainFocus={isFocused(index)}
+                                            onFocusedChild={onButtonFocused}
+                                            onButtonSelected={onButtonSelected}
+                                            {...createButtonProps(buttonAtIndex()!, props)}
+                                            id={`${props.id || ""}${index.toString()}`}
+                                        />
+                                    </Focusable>
+                                </Show>
+                            );
+                        }}
+                    />
+                </layoutGroup>
+            </Show>
+        </FocusableGroup>
+    );
+};