@roku-sdk/components 0.0.0-stage → 2.19.0

package/src/__tests__/container.test.tsx

@@ -0,0 +1,150 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Transaction semantics of the imperative `ContainerRef` API.
+ *
+ * `insertNode` / `removeNode` are called from outside the Solid renderer, so
+ * unlike every renderer-driven mutation they have to open the transaction
+ * themselves. The mocks below record native tree-manipulation calls and
+ * transaction boundaries into one ordered log so a call that escapes its
+ * transaction is visible.
+ *
+ * Imports use relative module paths (not the @roku-sdk/components barrel) so
+ * Jest only transforms this feature's dependency subtree, per the monorepo's
+ * OOM-avoidance guidance.
+ */
+import { beforeEach, describe, expect, jest, test } from "@jest/globals";
+import { registerInternStringApi } from "@roku-sdk/common/string-interner";
+import { registerTransactionApi, transactionManager } from "@roku-sdk/common/transaction";
+import { DomNode, InternStringApi, StructuredDataApi, TmNodeRef, TreeManipulationApi } from "@roku-sdk/interfaces";
+import { makeSolidRenderer, Renderer } from "@roku-sdk/solid";
+
+import { Container, ContainerRef } from "../container";
+
+describe("Container imperative API", () => {
+    const commitEarly = transactionManager.commitEarly;
+
+    let render: Renderer<DomNode>["render"];
+    let mockTmApi: TreeManipulationApi;
+    /** Ordered log of transaction boundaries and native tree mutations. */
+    let calls: string[];
+
+    beforeEach(() => {
+        calls = [];
+        let nodeRef = 0;
+        let internRef = 0;
+
+        mockTmApi = {
+            createNode: jest.fn().mockImplementation((): object => ({ id: ++nodeRef })),
+            appendNode: jest.fn().mockImplementation(() => {
+                calls.push("appendNode");
+            }),
+            insertNodeBefore: jest.fn(),
+            removeNode: jest.fn().mockImplementation(() => {
+                calls.push("removeNode");
+            }),
+            setNodePropNull: jest.fn(),
+            setNodePropBool: jest.fn(),
+            setNodePropInt: jest.fn(),
+            setNodePropFloat: jest.fn(),
+            setNodePropString: jest.fn(),
+            setNodePropObject: jest.fn(),
+            setNodePropArray: jest.fn(),
+            setNodePropNodeRef: jest.fn(),
+            registerFieldChangeHandler: jest.fn(),
+            unregisterFieldHandler: jest.fn(),
+            setFocus: jest.fn()
+        } as unknown as TreeManipulationApi;
+
+        const internMap = new Map<string, object>();
+        const mockIntern: InternStringApi = {
+            internString: (str: string): object => {
+                const interned = internMap.get(str);
+                if (interned) {
+                    return interned;
+                }
+                const ref = { id: ++internRef };
+                internMap.set(str, ref);
+                return ref;
+            }
+        };
+        registerInternStringApi(mockIntern);
+
+        registerTransactionApi({
+            start: () => calls.push("tx:start"),
+            end: () => calls.push("tx:end")
+        });
+
+        const mockStructuredDataApi = {
+            createArray: jest.fn().mockImplementation(() => ({})),
+            appendInt: jest.fn(),
+            createObject: jest.fn().mockImplementation(() => ({})),
+            insertInt: jest.fn(),
+            insertArray: jest.fn()
+        } as unknown as StructuredDataApi;
+
+        const solidRenderer = makeSolidRenderer(mockTmApi, mockStructuredDataApi, mockStructuredDataApi);
+        ({ render } = solidRenderer.renderer);
+    });
+
+    /** Renders a Container holding one child and returns handles to both. */
+    function renderContainer(): { containerRef: ContainerRef; child: DomNode; dispose: () => void } {
+        let containerRef!: ContainerRef;
+        let child!: DomNode;
+
+        const dispose = render(
+            () => (
+                <Container
+                    ref={(el: ContainerRef) => {
+                        containerRef = el;
+                    }}
+                >
+                    <group
+                        ref={(el: DomNode) => {
+                            child = el;
+                        }}
+                    />
+                </Container>
+            ),
+            { r: {} as TmNodeRef, c: [] }
+        );
+        commitEarly();
+        calls.length = 0;
+
+        return { containerRef, child, dispose };
+    }
+
+    test("removeNode detaches the child inside a transaction", () => {
+        const { containerRef, child, dispose } = renderContainer();
+
+        containerRef.removeNode(child);
+        // The detach is queued, not applied — it lands in the pre-commit hook,
+        // which only runs because removeNode opened a transaction.
+        expect(calls).toEqual(["tx:start"]);
+
+        commitEarly();
+        expect(calls).toEqual(["tx:start", "removeNode", "tx:end"]);
+        expect(child.parent).toBeUndefined();
+
+        dispose();
+    });
+
+    test("insertNode re-attaches the child inside a transaction", () => {
+        const { containerRef, child, dispose } = renderContainer();
+
+        containerRef.removeNode(child);
+        commitEarly();
+        calls.length = 0;
+
+        containerRef.insertNode(child);
+        // appendNode reaches native synchronously, so the transaction has to be
+        // open before it — on firmware 15.2.x an append outside a transaction
+        // raises a render-thread exception and the child is never attached.
+        expect(calls).toEqual(["tx:start", "appendNode"]);
+
+        commitEarly();
+        expect(calls).toEqual(["tx:start", "appendNode", "tx:end"]);
+
+        dispose();
+    });
+});

package/src/__tests__/effect-gradient-validation.test.tsx

@@ -0,0 +1,133 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+// ---------------------------------------------------------------------------
+// Effect warns in __DEV__ when gradientColors / gradientStops violate the firmware
+// constraints (2–8 colors, stops length and [0, 1] range) while gradientStyle is not
+// "none". Quiet for valid gradients and for style "none" with empty arrays (effects-lab
+// edit-demo). Each distinct problem is reported once per node; nothing without __DEV__.
+// ---------------------------------------------------------------------------
+
+import "@roku-sdk/compat";
+
+import { afterEach, beforeEach, describe, expect, jest, test } from "@jest/globals";
+import { createSignal, type JSX } from "@roku-sdk/solid";
+
+import { Effect, installEffectGradientDevValidation } from "../sg-nodes/effect";
+import { commitEarly, createAnchorNode, installSolidTestRenderer } from "../test-helpers/tween-test-setup";
+
+async function flushMicrotasks(): Promise<void> {
+    await Promise.resolve();
+    await Promise.resolve();
+}
+
+describe("Effect gradient prop 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;
+        installEffectGradientDevValidation();
+        render = installSolidTestRenderer();
+        warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        dispose?.();
+        dispose = undefined;
+        (globalThis as { __DEV__?: boolean }).__DEV__ = realDev;
+        warn.mockRestore();
+    });
+
+    const mount = (element: JSX.Element): void => {
+        dispose = render(() => <group>{element}</group>, createAnchorNode());
+        commitEarly();
+    };
+
+    const effectWarnings = (): string[] =>
+        warn.mock.calls.map(c => String(c[0])).filter(message => message.startsWith("Effect"));
+
+    test("warns when gradientColors has fewer than 2 entries", async () => {
+        mount(<effect gradientStyle="linear" gradientColors={["0xFF0000FF"]} />);
+        await flushMicrotasks();
+        expect(effectWarnings()).toEqual([
+            'Effect: gradientColors must have 2–8 entries when gradientStyle is "linear" (got 1).'
+        ]);
+    });
+
+    test("warns when gradientColors has more than 8 entries", async () => {
+        const colors = Array.from({ length: 9 }, (_, i) => `0xFF00000${i}`);
+        mount(<effect gradientStyle="radial" gradientColors={colors} />);
+        await flushMicrotasks();
+        expect(effectWarnings()).toEqual([
+            'Effect: gradientColors must have 2–8 entries when gradientStyle is "radial" (got 9).'
+        ]);
+    });
+
+    test("warns when gradientStops length does not match gradientColors", async () => {
+        mount(
+            <effect gradientStyle="linear" gradientColors={["0xFF0000FF", "0x0000FFFF"]} gradientStops={[0, 0.5, 1]} />
+        );
+        await flushMicrotasks();
+        expect(effectWarnings()).toEqual(["Effect: gradientStops length (3) must equal gradientColors length (2)."]);
+    });
+
+    test("warns when a gradientStops entry is outside [0, 1]", async () => {
+        mount(<effect gradientStyle="linear" gradientColors={["0xFF0000FF", "0x0000FFFF"]} gradientStops={[0, 1.5]} />);
+        await flushMicrotasks();
+        expect(effectWarnings()).toEqual(["Effect: gradientStops entries must be in [0, 1] (got 1.5 at index 1)."]);
+    });
+
+    test("includes id in the warning when the effect has one", async () => {
+        mount(<effect id="hero-fill" gradientStyle="linear" gradientColors={["0xFF0000FF"]} />);
+        await flushMicrotasks();
+        expect(effectWarnings()).toEqual([
+            'Effect[id=hero-fill]: gradientColors must have 2–8 entries when gradientStyle is "linear" (got 1).'
+        ]);
+    });
+
+    test("warns through the PascalCase Effect wrapper", async () => {
+        mount(<Effect gradientStyle="linear" gradientColors={["0xFF0000FF"]} />);
+        await flushMicrotasks();
+        expect(effectWarnings()).toEqual([
+            'Effect: gradientColors must have 2–8 entries when gradientStyle is "linear" (got 1).'
+        ]);
+    });
+
+    test("is silent for a valid gradient", async () => {
+        mount(<effect gradientStyle="linear" gradientColors={["0xFF0000FF", "0x0000FFFF"]} gradientStops={[0, 1]} />);
+        await flushMicrotasks();
+        expect(effectWarnings()).toEqual([]);
+    });
+
+    test("is silent for gradientStyle none with empty colors and stops (effects-lab edit-demo)", async () => {
+        mount(<effect gradientStyle="none" gradientColors={[]} gradientStops={[]} />);
+        await flushMicrotasks();
+        expect(effectWarnings()).toEqual([]);
+    });
+
+    test("reports each distinct problem once per node across updates", async () => {
+        const [colors, setColors] = createSignal<string[]>(["0xFF0000FF"]);
+        mount(<effect gradientStyle="linear" gradientColors={colors()} />);
+        await flushMicrotasks();
+        setColors(["0xFF0000FF"]);
+        commitEarly();
+        await flushMicrotasks();
+        setColors(Array.from({ length: 9 }, (_, i) => `0xFF00000${i}`));
+        commitEarly();
+        await flushMicrotasks();
+        // Same key "colors:count" — still one warning even though the count changed.
+        expect(effectWarnings()).toEqual([
+            'Effect: gradientColors must have 2–8 entries when gradientStyle is "linear" (got 1).'
+        ]);
+    });
+
+    test("is silent without __DEV__", async () => {
+        (globalThis as { __DEV__?: boolean }).__DEV__ = false;
+        mount(<effect gradientStyle="linear" gradientColors={["0xFF0000FF"]} />);
+        await flushMicrotasks();
+        expect(effectWarnings()).toEqual([]);
+    });
+});

package/src/__tests__/glyphs.test.ts

@@ -0,0 +1,202 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, test } from "@jest/globals";
+import { LEFT_BUTTON_GLYPH as SubpathGlyphSmoke } from "@roku-sdk/components/glyphs";
+
+import {
+    BACK_BUTTON_GLYPH,
+    BALLOT_X,
+    BLACK_CIRCLE,
+    BLACK_STAR,
+    BULLET,
+    CHECK_MARK,
+    CLOSED_CAPTIONS_GLYPH,
+    DOT_GLYPH,
+    DOWN_ARROW,
+    DOWN_BUTTON_GLYPH,
+    ELLIPSIS,
+    EM_DASH,
+    EN_DASH,
+    FAST_FORWARD_GLYPH,
+    GENERAL_APP_GLYPH,
+    HOME_BUTTON_GLYPH,
+    HOME_GLYPH,
+    KIDS_PROFILE_GLYPH,
+    LEFT_ARROW,
+    LEFT_BUTTON_GLYPH,
+    LIVE_TV_GLYPH,
+    MICROPHONE_BUTTON_GLYPH,
+    MICROPHONE_GLYPH,
+    OK_BUTTON_GLYPH,
+    OPTIONS_BUTTON_GLYPH,
+    OPTIONS_GLYPH,
+    PLAY_PAUSE_BUTTON_GLYPH,
+    PLAY_PAUSE_GLYPH,
+    POWER_BUTTON_GLYPH,
+    QUICK_LAUNCH_BUTTON_GLYPH,
+    REMOTE_GLYPH,
+    REPLAY_GLYPH,
+    REWIND_GLYPH,
+    RIGHT_ARROW,
+    RIGHT_BUTTON_GLYPH,
+    SEARCH_BUTTON_GLYPH,
+    SEARCH_GLYPH,
+    SHORTCUT_ONE_BUTTON_GLYPH,
+    SHORTCUT_TWO_BUTTON_GLYPH,
+    SLEEP_TIMER_GLYPH,
+    THUMBS_DOWN_GLYPH,
+    THUMBS_UP_GLYPH,
+    UP_ARROW,
+    UP_BUTTON_GLYPH,
+    WHITE_STAR
+} from "../glyphs";
+
+describe("RokuFont01 glyph constants", () => {
+    test("exports expected codepoints", () => {
+        const expectedGlyphs: Record<string, string> = {
+            OPTIONS_GLYPH: "\uE000",
+            OK_BUTTON_GLYPH: "\uE001",
+            OPTIONS_BUTTON_GLYPH: "\uE002",
+            MICROPHONE_GLYPH: "\uE003",
+            PLAY_PAUSE_BUTTON_GLYPH: "\uE004",
+            PLAY_PAUSE_GLYPH: "\uE005",
+            DOT_GLYPH: "\uE006",
+            HOME_GLYPH: "\uE007",
+            SEARCH_GLYPH: "\uE008",
+            REMOTE_GLYPH: "\uE009",
+            REPLAY_GLYPH: "\uE010",
+            MICROPHONE_BUTTON_GLYPH: "\uE011",
+            SEARCH_BUTTON_GLYPH: "\uE012",
+            FAST_FORWARD_GLYPH: "\uE013",
+            REWIND_GLYPH: "\uE014",
+            SHORTCUT_ONE_BUTTON_GLYPH: "\uE015",
+            SHORTCUT_TWO_BUTTON_GLYPH: "\uE016",
+            CLOSED_CAPTIONS_GLYPH: "\uE017",
+            LIVE_TV_GLYPH: "\uE018",
+            SLEEP_TIMER_GLYPH: "\uE019",
+            GENERAL_APP_GLYPH: "\uE020",
+            BACK_BUTTON_GLYPH: "\uE021",
+            HOME_BUTTON_GLYPH: "\uE022",
+            QUICK_LAUNCH_BUTTON_GLYPH: "\uE023",
+            DOWN_BUTTON_GLYPH: "\uE024",
+            LEFT_BUTTON_GLYPH: "\uE025",
+            RIGHT_BUTTON_GLYPH: "\uE026",
+            KIDS_PROFILE_GLYPH: "\uE027",
+            UP_BUTTON_GLYPH: "\uE028",
+            POWER_BUTTON_GLYPH: "\uE029",
+            THUMBS_UP_GLYPH: "\uE030",
+            THUMBS_DOWN_GLYPH: "\uE031"
+        };
+
+        const actualGlyphs: Record<string, string> = {
+            OPTIONS_GLYPH,
+            OK_BUTTON_GLYPH,
+            OPTIONS_BUTTON_GLYPH,
+            MICROPHONE_GLYPH,
+            PLAY_PAUSE_BUTTON_GLYPH,
+            PLAY_PAUSE_GLYPH,
+            DOT_GLYPH,
+            HOME_GLYPH,
+            SEARCH_GLYPH,
+            REMOTE_GLYPH,
+            REPLAY_GLYPH,
+            MICROPHONE_BUTTON_GLYPH,
+            SEARCH_BUTTON_GLYPH,
+            FAST_FORWARD_GLYPH,
+            REWIND_GLYPH,
+            SHORTCUT_ONE_BUTTON_GLYPH,
+            SHORTCUT_TWO_BUTTON_GLYPH,
+            CLOSED_CAPTIONS_GLYPH,
+            LIVE_TV_GLYPH,
+            SLEEP_TIMER_GLYPH,
+            GENERAL_APP_GLYPH,
+            BACK_BUTTON_GLYPH,
+            HOME_BUTTON_GLYPH,
+            QUICK_LAUNCH_BUTTON_GLYPH,
+            DOWN_BUTTON_GLYPH,
+            LEFT_BUTTON_GLYPH,
+            RIGHT_BUTTON_GLYPH,
+            KIDS_PROFILE_GLYPH,
+            UP_BUTTON_GLYPH,
+            POWER_BUTTON_GLYPH,
+            THUMBS_UP_GLYPH,
+            THUMBS_DOWN_GLYPH
+        };
+
+        expect(actualGlyphs).toEqual(expectedGlyphs);
+    });
+
+    test("supports importing a single constant from subpath", () => {
+        expect(SubpathGlyphSmoke).toBe("\uE025");
+    });
+});
+
+describe("RokuFont01 standard-Unicode symbol constants", () => {
+    test("exports expected codepoints", () => {
+        expect({
+            BLACK_CIRCLE,
+            BLACK_STAR,
+            WHITE_STAR
+        }).toEqual({
+            BLACK_CIRCLE: "\u25CF",
+            BLACK_STAR: "\u2605",
+            WHITE_STAR: "\u2606"
+        });
+    });
+
+    test("DOT_GLYPH and BLACK_CIRCLE are distinct alignment variants of the same dot", () => {
+        expect(DOT_GLYPH).not.toBe(BLACK_CIRCLE);
+    });
+});
+
+describe("RokuUI-Regular symbol constants", () => {
+    test("exports expected codepoints", () => {
+        expect({
+            BULLET,
+            ELLIPSIS,
+            EN_DASH,
+            EM_DASH,
+            LEFT_ARROW,
+            UP_ARROW,
+            RIGHT_ARROW,
+            DOWN_ARROW,
+            CHECK_MARK,
+            BALLOT_X
+        }).toEqual({
+            BULLET: "\u2022",
+            ELLIPSIS: "\u2026",
+            EN_DASH: "\u2013",
+            EM_DASH: "\u2014",
+            LEFT_ARROW: "\u2190",
+            UP_ARROW: "\u2191",
+            RIGHT_ARROW: "\u2192",
+            DOWN_ARROW: "\u2193",
+            CHECK_MARK: "\u2713",
+            BALLOT_X: "\u2717"
+        });
+    });
+
+    test("every exported constant is a single character", () => {
+        const all = [
+            BULLET,
+            ELLIPSIS,
+            EN_DASH,
+            EM_DASH,
+            LEFT_ARROW,
+            UP_ARROW,
+            RIGHT_ARROW,
+            DOWN_ARROW,
+            CHECK_MARK,
+            BALLOT_X,
+            BLACK_CIRCLE,
+            BLACK_STAR,
+            WHITE_STAR,
+            DOT_GLYPH
+        ];
+        for (const c of all) {
+            expect(c).toHaveLength(1);
+        }
+        expect(new Set(all).size).toBe(all.length);
+    });
+});

package/src/__tests__/modal-boundary-export.test.ts

@@ -0,0 +1,12 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, test } from "@jest/globals";
+import { ModalBoundary, useModal } from "@roku-sdk/components";
+
+describe("ModalBoundary partner export", () => {
+    test("re-exports ModalBoundary and useModal from @roku-sdk/components", () => {
+        expect(typeof ModalBoundary).toBe("function");
+        expect(typeof useModal).toBe("function");
+    });
+});