@roku-sdk/components 0.0.0-stage → 2.19.0

package/src/sg-nodes/__tests__/imperative-methods.test.ts

@@ -0,0 +1,276 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+// Side-effect imports: loading these modules triggers their registerImperativeMethods calls.
+
+import "../video";
+import "../audio";
+import "../sound-effect";
+import "../animation";
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { beforeEach, describe, expect, it, jest } from "@jest/globals";
+import { TmNodeRef } from "@roku-sdk/interfaces";
+import { createDomNode, setSetPropertyHandler } from "@roku-sdk/solid/src/dom-node";
+
+describe("imperative methods", () => {
+    let mockSetProperty: jest.Mock;
+
+    beforeEach(() => {
+        mockSetProperty = jest.fn();
+        setSetPropertyHandler(mockSetProperty);
+    });
+
+    describe("video", () => {
+        it("should have play, pause, stop, resume, replay, prebuffer, skipcontent methods", () => {
+            const node = createDomNode("video", { id: 1 } as TmNodeRef) as any;
+
+            for (const method of ["play", "pause", "stop", "resume", "replay", "prebuffer", "skipcontent"]) {
+                expect(typeof node[method]).toBe("function");
+                node[method]();
+                expect(mockSetProperty).toHaveBeenLastCalledWith(node, "control", method);
+            }
+
+            expect(mockSetProperty).toHaveBeenCalledTimes(7);
+        });
+
+        it("should have seekTo method that sets seek property", () => {
+            const node = createDomNode("video", { id: 1 } as TmNodeRef) as any;
+
+            expect(typeof node.seekTo).toBe("function");
+            node.seekTo(120);
+            expect(mockSetProperty).toHaveBeenCalledWith(node, "seek", 120);
+        });
+
+        it("should have setNextContentIndex method that sets nextContentIndex property", () => {
+            const node = createDomNode("video", { id: 1 } as TmNodeRef) as any;
+
+            expect(typeof node.setNextContentIndex).toBe("function");
+            node.setNextContentIndex(3);
+            expect(mockSetProperty).toHaveBeenCalledWith(node, "nextContentIndex", 3);
+        });
+    });
+
+    describe("audio", () => {
+        it("should have play, pause, stop, resume, replay, prebuffer, skipcontent methods", () => {
+            const node = createDomNode("audio", { id: 1 } as TmNodeRef) as any;
+
+            for (const method of ["play", "pause", "stop", "resume", "replay", "prebuffer", "skipcontent"]) {
+                expect(typeof node[method]).toBe("function");
+                node[method]();
+                expect(mockSetProperty).toHaveBeenLastCalledWith(node, "control", method);
+            }
+
+            expect(mockSetProperty).toHaveBeenCalledTimes(7);
+        });
+
+        it("should have seekTo method that sets seek property", () => {
+            const node = createDomNode("audio", { id: 1 } as TmNodeRef) as any;
+
+            expect(typeof node.seekTo).toBe("function");
+            node.seekTo(60);
+            expect(mockSetProperty).toHaveBeenCalledWith(node, "seek", 60);
+        });
+
+        it("should have setNextContentIndex method that sets nextContentIndex property", () => {
+            const node = createDomNode("audio", { id: 1 } as TmNodeRef) as any;
+
+            expect(typeof node.setNextContentIndex).toBe("function");
+            node.setNextContentIndex(5);
+            expect(mockSetProperty).toHaveBeenCalledWith(node, "nextContentIndex", 5);
+        });
+    });
+
+    describe("soundEffect", () => {
+        it("should have play and stop methods", () => {
+            const node = createDomNode("soundEffect", { id: 1 } as TmNodeRef) as any;
+
+            for (const method of ["play", "stop"]) {
+                expect(typeof node[method]).toBe("function");
+                node[method]();
+                expect(mockSetProperty).toHaveBeenLastCalledWith(node, "control", method);
+            }
+
+            expect(mockSetProperty).toHaveBeenCalledTimes(2);
+        });
+
+        it("should not have pause or resume methods", () => {
+            const node = createDomNode("soundEffect", { id: 1 } as TmNodeRef) as any;
+
+            expect(node.pause).toBeUndefined();
+            expect(node.resume).toBeUndefined();
+        });
+    });
+
+    // `registerImperativeMethods` keys an exact-match Map by tag string, and the tag it is
+    // given is a plain string literal that no compiler check ties to the intrinsic the
+    // component renders. Renaming one and not the other type-checks, passes every other
+    // test, and silently drops the methods at runtime -- which is exactly what happened
+    // when `soundeffect` became `soundEffect`. These assert the registered tag against the
+    // tag actually rendered, so the two cannot drift apart again unnoticed.
+    describe("registered tags match the rendered intrinsics", () => {
+        it.each([
+            ["video", ["play", "pause", "stop", "resume", "replay", "prebuffer", "skipcontent"]],
+            ["audio", ["play", "pause", "stop", "resume"]],
+            ["soundEffect", ["play", "stop"]],
+            ["animation", ["start", "setDuration", "setEaseFunction"]],
+            ["sequentialAnimation", ["start", "setDuration", "setEaseFunction"]],
+            ["floatFieldInterpolator", ["setKeyValue", "setFieldToInterp"]],
+            ["colorFieldInterpolator", ["setKeyValue", "setFieldToInterp"]],
+            ["vector2dFieldInterpolator", ["setKeyValue", "setFieldToInterp"]]
+        ])("%s exposes its imperative methods", (tag, methods) => {
+            const node = createDomNode(tag as string, { id: 1 } as TmNodeRef) as any;
+
+            for (const method of methods as string[]) {
+                expect(typeof node[method]).toBe("function");
+            }
+        });
+
+        it("registers nothing under the pre-rename lowercase tags", () => {
+            for (const stale of ["soundeffect", "sequentialanimation"]) {
+                const node = createDomNode(stale, { id: 1 } as TmNodeRef) as any;
+
+                expect(node.play).toBeUndefined();
+                expect(node.start).toBeUndefined();
+            }
+        });
+    });
+
+    // Re-targeting a running animation needs duration, easeFunction and keyValue to reach
+    // the node before the surrounding stop/start. These setters exist so the caller can
+    // order those writes itself rather than inheriting the reactive props' deferral.
+    describe("animation re-target setters", () => {
+        it.each(["animation", "sequentialAnimation"])("%s setDuration writes duration", tag => {
+            const node = createDomNode(tag, { id: 1 } as TmNodeRef) as any;
+
+            node.setDuration(0.35);
+            expect(mockSetProperty).toHaveBeenCalledWith(node, "duration", 0.35);
+        });
+
+        it.each(["animation", "sequentialAnimation"])("%s setEaseFunction writes easeFunction", tag => {
+            const node = createDomNode(tag, { id: 1 } as TmNodeRef) as any;
+
+            node.setEaseFunction("linear");
+            expect(mockSetProperty).toHaveBeenCalledWith(node, "easeFunction", "linear");
+        });
+
+        it("floatFieldInterpolator setKeyValue writes keyValue", () => {
+            const node = createDomNode("floatFieldInterpolator", { id: 1 } as TmNodeRef) as any;
+
+            node.setKeyValue([1, 0]);
+            expect(mockSetProperty).toHaveBeenCalledWith(node, "keyValue", [1, 0]);
+        });
+
+        it("colorFieldInterpolator setKeyValue writes keyValue", () => {
+            const node = createDomNode("colorFieldInterpolator", { id: 1 } as TmNodeRef) as any;
+
+            node.setKeyValue(["0x000000FF", "0xFFFFFFFF"]);
+            expect(mockSetProperty).toHaveBeenCalledWith(node, "keyValue", ["0x000000FF", "0xFFFFFFFF"]);
+        });
+
+        it("vector2dFieldInterpolator setKeyValue writes keyValue", () => {
+            const node = createDomNode("vector2dFieldInterpolator", { id: 1 } as TmNodeRef) as any;
+
+            node.setKeyValue([
+                [0, 0],
+                [500, 200]
+            ]);
+            expect(mockSetProperty).toHaveBeenCalledWith(node, "keyValue", [
+                [0, 0],
+                [500, 200]
+            ]);
+        });
+
+        it.each(["floatFieldInterpolator", "colorFieldInterpolator", "vector2dFieldInterpolator"])(
+            "%s setFieldToInterp writes fieldToInterp",
+            tag => {
+                const node = createDomNode(tag, { id: 1 } as TmNodeRef) as any;
+
+                node.setFieldToInterp("42.translation");
+                expect(mockSetProperty).toHaveBeenCalledWith(node, "fieldToInterp", "42.translation");
+            }
+        );
+    });
+
+    describe("animation", () => {
+        it("should have start, stop, pause, resume, finish methods", () => {
+            const node = createDomNode("animation", { id: 1 } as TmNodeRef) as any;
+
+            for (const method of ["start", "stop", "pause", "resume", "finish"]) {
+                expect(typeof node[method]).toBe("function");
+                node[method]();
+                expect(mockSetProperty).toHaveBeenLastCalledWith(node, "control", method);
+            }
+
+            expect(mockSetProperty).toHaveBeenCalledTimes(5);
+        });
+    });
+
+    describe("sequentialAnimation", () => {
+        it("should have start, stop, pause, resume, finish methods", () => {
+            const node = createDomNode("sequentialAnimation", { id: 1 } as TmNodeRef) as any;
+
+            for (const method of ["start", "stop", "pause", "resume", "finish"]) {
+                expect(typeof node[method]).toBe("function");
+                node[method]();
+                expect(mockSetProperty).toHaveBeenLastCalledWith(node, "control", method);
+            }
+
+            expect(mockSetProperty).toHaveBeenCalledTimes(5);
+        });
+    });
+
+    // `registerImperativeMethods` only runs as a module side effect, and this package
+    // declares a `sideEffects` allowlist. A bundler that tree-shakes a registrar module
+    // out -- which it may do whenever a consumer reaches the tag through the intrinsic
+    // JSX rather than through the exported component -- leaves the tag proto with no
+    // methods, and every imperative call throws "is not a function" at runtime. Nothing
+    // else in this suite catches that, because Jest imports the modules directly.
+    describe("registrar modules are exempt from tree-shaking", () => {
+        const packageRoot = path.resolve(__dirname, "../../..");
+
+        function globToRegExp(pattern: string): RegExp {
+            const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+            const expanded = escaped
+                .replace(/\*\*\//g, "(?:.*/)?")
+                .replace(/\*\*/g, ".*")
+                .replace(/(?<!\.)\*/g, "[^/]*");
+            return new RegExp(`^${expanded}$`);
+        }
+
+        it("lists every module that calls registerImperativeMethods in sideEffects", () => {
+            const { sideEffects } = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")) as {
+                sideEffects: string[];
+            };
+            const patterns = sideEffects.map(globToRegExp);
+
+            const sgNodesDir = path.resolve(__dirname, "..");
+            const registrars = fs
+                .readdirSync(sgNodesDir)
+                .filter(name => name.endsWith(".tsx"))
+                .filter(name =>
+                    fs.readFileSync(path.join(sgNodesDir, name), "utf8").includes("registerImperativeMethods(")
+                )
+                .map(name => `src/sg-nodes/${name}`);
+
+            // Guards the scan itself: a refactor that moves the registrars elsewhere
+            // should fail loudly here rather than silently assert over an empty list.
+            expect(registrars.length).toBeGreaterThan(0);
+
+            const unlisted = registrars.filter(file => !patterns.some(pattern => pattern.test(file)));
+            expect(unlisted).toEqual([]);
+        });
+
+        it("lists effect.tsx in sideEffects so the gradient dev observer is not tree-shaken", () => {
+            const { sideEffects } = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")) as {
+                sideEffects: string[];
+            };
+            const patterns = sideEffects.map(globToRegExp);
+            expect(patterns.some(pattern => pattern.test("src/sg-nodes/effect.tsx"))).toBe(true);
+        });
+    });
+});