@roku-sdk/components 0.0.0-stage → 2.19.0

package/src/__tests__/native-modal.test.tsx

@@ -0,0 +1,224 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+import { describe, expect, it, jest } from "@jest/globals";
+import { createSignal, Show, tmTransaction } from "@roku-sdk/solid";
+import { render } from "@roku-sdk/testing-library";
+
+import { Modal } from "../modal-dialog";
+import { StandardDialog } from "../sg-nodes/standard-dialog";
+import { StandardKeyboardDialog } from "../sg-nodes/standard-keyboard-dialog";
+import { StandardMessageDialog } from "../sg-nodes/standard-message-dialog";
+import { StandardPinPadDialog } from "../sg-nodes/standard-pinpad-dialog";
+import { StandardProgressDialog } from "../sg-nodes/standard-progress-dialog";
+
+describe("native modal wrappers", () => {
+    it("retires handlers on cached dialog and fallback nodes when the modal unmounts", async () => {
+        const [visible, setVisible] = createSignal(true);
+        const selected = jest.fn();
+        const closed = jest.fn();
+        const view = await render(() => (
+            <Show when={visible()}>
+                <StandardDialog
+                    id="content"
+                    onButtonSelected={selected}
+                    onWasClosed={closed}
+                    fallback={<standardDialog id="fallback" onButtonSelected={selected} />}
+                />
+            </Show>
+        ));
+        try {
+            const modal = view.getByTag("modal");
+            const content = view.getByProp("id", "content");
+            const fallback = view.getByProp("id", "fallback");
+            await view.fireEvent(content, "onButtonSelected", 0);
+            expect(selected).toHaveBeenCalledTimes(1);
+            setVisible(false);
+            await view.transaction();
+            expect(view.queryByProp("id", "content")).toBeFalsy();
+            await view.fireEvent(content, "onButtonSelected", 0);
+            await view.fireEvent(fallback, "onButtonSelected", 0);
+            expect(selected).toHaveBeenCalledTimes(1);
+            await expect(view.fireEvent(modal, "onWasClosed", true)).rejects.toThrow("not registered");
+            expect(closed).not.toHaveBeenCalled();
+        } finally {
+            view.dispose();
+        }
+    });
+
+    it("prepares content and fallback in one modal and releases it on disposal", async () => {
+        const [readiness, setReadiness] = createSignal(0);
+        const view = await render(() => (
+            <StandardDialog
+                ready={readiness() > 0}
+                replaceExisting={false}
+                fallback={
+                    <standardDialog id="loading">
+                        <stdDlgContentArea>
+                            <stdDlgProgressItem text="Loading" />
+                        </stdDlgContentArea>
+                    </standardDialog>
+                }
+            >
+                <stdDlgContentArea>
+                    <stdDlgTextItem text="Prepared content" />
+                </stdDlgContentArea>
+            </StandardDialog>
+        ));
+        const modal = view.getByTag("modal");
+        try {
+            expect(view.getAllByTag("modal")).toHaveLength(1);
+            expect(modal.props).toMatchObject({ mounted: true, ready: false });
+            const dialog = view.getByTag("standardDialogExt");
+            const fallback = view.getByTag("standardDialog");
+            setReadiness(1);
+            await view.transaction();
+            expect(modal.props).toMatchObject({ ready: true });
+            expect(view.getByTag("standardDialogExt")).toBe(dialog);
+            expect(view.getByTag("standardDialog")).toBe(fallback);
+            setReadiness(2);
+            await view.transaction();
+            expect(view.getByTag("standardDialogExt")).toBe(dialog);
+            expect(view.getByTag("standardDialog")).toBe(fallback);
+        } finally {
+            view.dispose();
+        }
+        await view.transaction();
+        expect(modal.props).toMatchObject({ mounted: false });
+    });
+
+    it("updates existing content and still allows an intentional dialog replacement", async () => {
+        const [title, setTitle] = createSignal("First");
+        const [replacement, setReplacement] = createSignal(false);
+        const selected = jest.fn();
+        const view = await render(() => (
+            <Modal
+                dialog={
+                    replacement() ? (
+                        <standardDialog id="replacement" onButtonSelected={selected} />
+                    ) : (
+                        <standardDialog id="original" title={title()} onButtonSelected={selected} />
+                    )
+                }
+            />
+        ));
+        try {
+            const original = view.getByProp("id", "original");
+            setTitle("Updated");
+            await view.transaction();
+            expect(view.getByProp("id", "original")).toBe(original);
+            expect(original.props).toMatchObject({ title: "Updated" });
+            setReplacement(true);
+            await view.transaction();
+            expect(view.queryByProp("id", "original")).toBeFalsy();
+            expect(view.getByProp("id", "replacement")).not.toBe(original);
+            await view.fireEvent(original, "onButtonSelected", 0);
+            expect(selected).not.toHaveBeenCalled();
+            await view.fireEvent(view.getByProp("id", "replacement"), "onButtonSelected", 0);
+            expect(selected).toHaveBeenCalledTimes(1);
+        } finally {
+            view.dispose();
+        }
+    });
+
+    it("replaces the fallback without recreating content or retaining old handlers", async () => {
+        const [replacement, setReplacement] = createSignal(false);
+        const selected = jest.fn();
+        const view = await render(() => (
+            <Modal
+                dialog={<standardDialog id="content" />}
+                fallback={
+                    replacement() ? (
+                        <standardDialog id="new-fallback" />
+                    ) : (
+                        <standardDialog id="old-fallback" onButtonSelected={selected} />
+                    )
+                }
+            />
+        ));
+        try {
+            const content = view.getByProp("id", "content");
+            const fallback = view.getByProp("id", "old-fallback");
+            setReplacement(true);
+            await view.transaction();
+            expect(view.getByProp("id", "content")).toBe(content);
+            expect(view.queryByProp("id", "old-fallback")).toBeFalsy();
+            expect(view.getByProp("id", "new-fallback")).not.toBe(fallback);
+            await view.fireEvent(fallback, "onButtonSelected", 0);
+            expect(selected).not.toHaveBeenCalled();
+        } finally {
+            view.dispose();
+        }
+    });
+
+    it.each([
+        ["standardDialogExt", StandardDialog],
+        ["standardMessageDialogExt", StandardMessageDialog],
+        ["standardKeyboardDialogExt", StandardKeyboardDialog],
+        ["standardPinPadDialogExt", StandardPinPadDialog],
+        ["standardProgressDialogExt", StandardProgressDialog]
+    ] as const)("routes lifecycle props to Modal for %s", async (tag, Dialog) => {
+        const [open, setOpen] = createSignal(false);
+        const [close, setClose] = createSignal(false, { equals: false });
+        const opened = jest.fn();
+        const closed = jest.fn();
+        const blocked = jest.fn();
+        const view = await render(() => (
+            <Dialog
+                id="dialog"
+                title="Native title"
+                width={1154}
+                optionsDialog
+                open={open()}
+                close={close()}
+                replaceExisting={false}
+                initialFocusId="cancel"
+                onOpened={opened}
+                onWasClosed={closed}
+                onBlocked={blocked}
+            />
+        ));
+        const writes = jest.spyOn(tmTransaction, "setProperty");
+        try {
+            const modal = view.getByTag("modal");
+            const dialog = view.getByTag(tag);
+            expect(modal.props).toMatchObject({
+                mounted: true,
+                open: false,
+                replaceExisting: false,
+                initialFocusId: "cancel"
+            });
+            expect(dialog.props).toMatchObject({
+                title: "Native title",
+                width: 1154,
+                optionsDialog: true,
+                close: false
+            });
+            expect(modal.props).not.toHaveProperty("close");
+            for (const name of ["open", "replaceExisting", "initialFocusId", "onOpened", "onWasClosed", "onBlocked"])
+                expect(dialog.props).not.toHaveProperty(name);
+            expect(opened).not.toHaveBeenCalled();
+            setOpen(true);
+            await view.transaction();
+            expect(modal.props).toMatchObject({ open: true });
+            expect(view.getByTag(tag)).toBe(dialog);
+            writes.mockClear();
+            setClose(false);
+            await view.transaction();
+            expect(writes.mock.calls.filter(([, name]) => name === "close")).toEqual([]);
+            setClose(true);
+            await view.transaction();
+            expect(dialog.props).toMatchObject({ close: true });
+            expect(view.getByTag(tag)).toBe(dialog);
+            expect(modal.props).not.toHaveProperty("close");
+            await view.fireEvent(modal, "onOpened", true);
+            await view.fireEvent(modal, "onWasClosed", true);
+            await view.fireEvent(modal, "onBlocked", true);
+            expect(opened).toHaveBeenCalledTimes(1);
+            expect(closed).toHaveBeenCalledTimes(1);
+            expect(blocked).toHaveBeenCalledTimes(1);
+        } finally {
+            writes.mockRestore();
+            view.dispose();
+        }
+    });
+});

package/src/__tests__/tween-release.test.tsx

@@ -0,0 +1,125 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+// ---------------------------------------------------------------------------
+// Tween nulls its target ref on dispose.
+//
+// The tween node and the node it animates reference each other on the render thread, so a
+// tween left holding its target keeps a disposed grid alive. Each case disposes one tween and
+// checks the last write to `targetNode` is null, on the native node and on the compat shim.
+// ---------------------------------------------------------------------------
+
+import "@roku-sdk/compat";
+
+import { afterEach, beforeEach, describe, expect, jest, test } from "@jest/globals";
+import type { DomNode } from "@roku-sdk/interfaces";
+import { hasFeature } from "@roku-sdk/runtime/has-feature";
+import { createSignal, type JSX, Show, 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()
+}));
+
+type Case = [name: string, render: (target: () => DomNode | undefined) => JSX.Element];
+
+const cases: Case[] = [
+    ["float field", target => <Tween targetRef={target} field="width" targetValue={100} />],
+    ["vector field", target => <Tween targetNode={target} axis="y" targetValue={100} />]
+];
+
+const modes: [mode: string, native: boolean, nodeType: string][] = [
+    ["compat shim", false, "RsgTweenShim"],
+    ["native", true, "tween"]
+];
+
+describe("Tween releases its target ref", () => {
+    let render: ReturnType<typeof installSolidTestRenderer>;
+    let setProperty: jest.SpiedFunction<typeof tmTransaction.setProperty>;
+    let createElement: jest.SpiedFunction<typeof tmTransaction.createElement>;
+
+    beforeEach(() => {
+        render = installSolidTestRenderer();
+        setProperty = jest.spyOn(tmTransaction, "setProperty");
+        createElement = jest.spyOn(tmTransaction, "createElement");
+    });
+
+    afterEach(() => {
+        jest.mocked(hasFeature).mockReset();
+        setProperty.mockRestore();
+        createElement.mockRestore();
+    });
+
+    const created = (nodeType: string): DomNode[] =>
+        createElement.mock.results.map(r => r.value as DomNode).filter(node => node.t === nodeType);
+    const lastWrite = (node: DomNode, name: string) => {
+        const writes = setProperty.mock.calls.filter(([n, field]) => n === node && field === name);
+        return writes[writes.length - 1];
+    };
+
+    describe.each(modes)("%s", (_mode, native, nodeType) => {
+        test.each(cases)("%s: nulls targetNode on dispose", (_name, renderTween) => {
+            jest.mocked(hasFeature).mockReturnValue(native);
+            let target: DomNode | undefined;
+            const dispose = render(
+                () => (
+                    <group>
+                        <rectangle id="target" ref={(el: unknown) => (target = el as DomNode)} />
+                        {renderTween(() => target)}
+                    </group>
+                ),
+                createAnchorNode()
+            );
+            commitEarly();
+
+            const [tween] = created(nodeType);
+            expect(created(nodeType)).toHaveLength(1);
+            expect(lastWrite(tween, "targetNode")?.[2]).toBe(target);
+
+            dispose();
+            commitEarly();
+
+            expect(lastWrite(tween, "targetNode")).toStrictEqual([tween, "targetNode", null, undefined]);
+        });
+    });
+
+    // The shim releases its Animation when targetNode is cleared, so the clear has to be issued
+    // before the tween node is taken out of the tree, not after.
+    test("clears targetNode before the unmounted tween is removed", () => {
+        jest.mocked(hasFeature).mockReturnValue(false);
+        const removeNode = jest.spyOn(tmTransaction, "removeNode");
+        const [shown, setShown] = createSignal(true);
+        let target: DomNode | undefined;
+        render(
+            () => (
+                <group>
+                    <rectangle id="target" ref={(el: unknown) => (target = el as DomNode)} />
+                    <Show when={shown()}>
+                        <Tween targetNode={() => target} field="width" targetValue={100} />
+                    </Show>
+                </group>
+            ),
+            createAnchorNode()
+        );
+        commitEarly();
+        const [tween] = created("RsgTweenShim");
+        expect(lastWrite(tween, "targetNode")?.[2]).toBe(target);
+
+        setShown(false);
+        commitEarly();
+
+        const clearAt = setProperty.mock.calls.findIndex(
+            ([n, field, value]) => n === tween && field === "targetNode" && value === null
+        );
+        expect(clearAt).toBeGreaterThanOrEqual(0);
+        const removed = removeNode.mock.calls.findIndex(([, child]) => child === tween);
+        expect(removed).toBeGreaterThanOrEqual(0);
+        expect(setProperty.mock.invocationCallOrder[clearAt]).toBeLessThan(
+            removeNode.mock.invocationCallOrder[removed]
+        );
+        removeNode.mockRestore();
+    });
+});

package/src/__tests__/tween-stops-shape.test.tsx

@@ -0,0 +1,165 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+// ---------------------------------------------------------------------------
+// Tween warns in dev builds when proposedStops does not have the shape its field and axis call
+// for: number[] on a float field or on a vector field under axis "x" / "y", [x, y][] under axis
+// "all" (the default) on a vector field, and no axis on a float field. Each distinct problem is
+// reported once per instance; unknown fields are not checked; nothing is reported without __DEV__.
+// ---------------------------------------------------------------------------
+
+import "@roku-sdk/compat";
+
+import { afterEach, beforeEach, describe, expect, jest, test } from "@jest/globals";
+import type { DomNode } from "@roku-sdk/interfaces";
+import { hasFeature } from "@roku-sdk/runtime/has-feature";
+import { createSignal, type JSX } 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()
+}));
+
+type Stops = number[] | [number, number][];
+
+describe("Tween proposedStops shape warning (dev only)", () => {
+    let render: ReturnType<typeof installSolidTestRenderer>;
+    let warn: jest.SpiedFunction<typeof console.warn>;
+    let realDev: boolean | undefined;
+    let dispose: (() => void) | undefined;
+
+    beforeEach(() => {
+        realDev = (globalThis as { __DEV__?: boolean }).__DEV__;
+        (globalThis as { __DEV__?: boolean }).__DEV__ = true;
+        jest.mocked(hasFeature).mockReturnValue(true);
+        render = installSolidTestRenderer();
+        warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        dispose?.();
+        dispose = undefined;
+        (globalThis as { __DEV__?: boolean }).__DEV__ = realDev;
+        jest.mocked(hasFeature).mockReset();
+        warn.mockRestore();
+    });
+
+    const mount = (renderTween: (target: () => DomNode | undefined) => JSX.Element): void => {
+        let target: DomNode | undefined;
+        dispose = render(
+            () => (
+                <group>
+                    <rectangle ref={(el: unknown) => (target = el as DomNode)} />
+                    {renderTween(() => target)}
+                </group>
+            ),
+            createAnchorNode()
+        );
+        commitEarly();
+    };
+
+    const tweenWarnings = (): string[] =>
+        warn.mock.calls.map(c => String(c[0])).filter(message => message.startsWith("Tween:"));
+
+    test("warns once when a vector field under axis x / y gets an array stop", () => {
+        mount(target => (
+            <Tween
+                targetRef={target}
+                axis="x"
+                targetValue={100}
+                proposedStops={[[300, 0], 200] as unknown as number[]}
+            />
+        ));
+        expect(tweenWarnings()).toEqual([
+            'Tween: proposedStops on "translation" with axis "x" must be scalars (the x coordinate); got an array. Array entries are skipped.'
+        ]);
+    });
+
+    test("warns when a vector field under axis all gets a scalar stop", () => {
+        mount(target => <Tween targetRef={target} axis="all" targetVector={[100, 100]} proposedStops={[400, 300]} />);
+        expect(tweenWarnings()).toEqual([
+            'Tween: proposedStops on "translation" with axis "all" must be [x, y] pairs; got a scalar. Scalar entries are skipped.'
+        ]);
+    });
+
+    test("treats an unset axis on a vector field as all, and checks pair length", () => {
+        mount(target => (
+            <Tween
+                targetRef={target}
+                field="scale"
+                targetVector={[1, 1]}
+                proposedStops={[[1, 2, 3]] as unknown as [number, number][]}
+            />
+        ));
+        expect(tweenWarnings()).toEqual([
+            'Tween: proposedStops on "scale" with axis "all" must be [x, y] pairs; got an array of length 3. Entries that are not pairs are skipped.'
+        ]);
+    });
+
+    test("warns when a float field is given an axis", () => {
+        mount(target => <Tween targetRef={target} field="opacity" axis="x" targetValue={0.5} proposedStops={[0.2]} />);
+        expect(tweenWarnings()).toEqual(['Tween: axis "x" is ignored on float field "opacity"; remove it.']);
+    });
+
+    test("warns when a float field gets an array stop", () => {
+        mount(target => (
+            <Tween
+                targetRef={target}
+                field="width"
+                targetValue={100}
+                proposedStops={[[50, 50]] as [number, number][]}
+            />
+        ));
+        expect(tweenWarnings()).toEqual([
+            'Tween: proposedStops on float field "width" must be numbers; got an array. Array entries are skipped.'
+        ]);
+    });
+
+    test("reports each distinct problem once per instance, across stop updates", () => {
+        const [stops, setStops] = createSignal<Stops>([400, 300]);
+        mount(target => <Tween targetRef={target} targetVector={[100, 100]} proposedStops={stops()} />);
+        setStops([500]);
+        commitEarly();
+        setStops([[1, 2, 3]] as unknown as [number, number][]);
+        commitEarly();
+        setStops([600]);
+        commitEarly();
+        expect(tweenWarnings()).toHaveLength(2);
+        expect(tweenWarnings()[0]).toContain("got a scalar");
+        expect(tweenWarnings()[1]).toContain("got an array of length 3");
+    });
+
+    test("does not warn when every stop has the right shape", () => {
+        mount(target => (
+            <>
+                <Tween targetRef={target} axis="y" targetValue={100} proposedStops={[100, 200]} />
+                <Tween targetRef={target} targetVector={[1, 2]} proposedStops={[[1, 2]]} />
+                <Tween targetRef={target} field="rotation" targetValue={1} proposedStops={[0.5, 1]} />
+                <Tween targetRef={target} field="opacity" targetValue={1} />
+            </>
+        ));
+        expect(tweenWarnings()).toEqual([]);
+    });
+
+    test("does not check a field it does not know", () => {
+        mount(target => (
+            <Tween
+                targetRef={target}
+                field="customField"
+                axis="all"
+                targetValue={1}
+                proposedStops={[1, [1, 2, 3]] as unknown as number[]}
+            />
+        ));
+        expect(tweenWarnings()).toEqual([]);
+    });
+
+    test("is silent without __DEV__", () => {
+        (globalThis as { __DEV__?: boolean }).__DEV__ = false;
+        mount(target => <Tween targetRef={target} axis="all" targetVector={[100, 100]} proposedStops={[400, 300]} />);
+        expect(tweenWarnings()).toEqual([]);
+    });
+});

package/src/__tests__/tween-without-compat.test.tsx

@@ -0,0 +1,64 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+// ---------------------------------------------------------------------------
+// Without `@roku-sdk/compat`, a Tween on firmware with no native node refuses loudly instead of
+// asking SceneGraph for a node type it does not have. This file deliberately never imports
+// compat, so only the refusal alias is registered.
+// ---------------------------------------------------------------------------
+
+import "@roku-sdk/compat/refuse-gated-tags";
+
+import { afterEach, beforeEach, describe, expect, jest, test } from "@jest/globals";
+import type { DomNode } from "@roku-sdk/interfaces";
+import { hasFeature } from "@roku-sdk/runtime/has-feature";
+
+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 without @roku-sdk/compat", () => {
+    let render: ReturnType<typeof installSolidTestRenderer>;
+    let dispose: (() => void) | undefined;
+
+    beforeEach(() => {
+        render = installSolidTestRenderer();
+    });
+
+    afterEach(() => {
+        dispose?.();
+        dispose = undefined;
+        jest.mocked(hasFeature).mockReset();
+    });
+
+    const mount = (): void => {
+        let target: DomNode | undefined;
+        dispose = render(
+            () => (
+                <group>
+                    <rectangle ref={(el: unknown) => (target = el as DomNode)} />
+                    <Tween targetRef={() => target} axis="x" targetValue={100} />
+                </group>
+            ),
+            createAnchorNode()
+        );
+        commitEarly();
+    };
+
+    test("throws naming the missing firmware feature and compat when the firmware lacks the node", () => {
+        jest.mocked(hasFeature).mockReturnValue(false);
+
+        expect(mount).toThrow('<tween> requires the "tween" firmware feature or @roku-sdk/compat');
+    });
+
+    test("creates the native node when the firmware has it", () => {
+        jest.mocked(hasFeature).mockReturnValue(true);
+
+        expect(mount).not.toThrow();
+    });
+});