@roku-sdk/components 0.0.0-stage → 2.19.0

package/src/sg-nodes/__tests__/core-props.test.ts

@@ -0,0 +1,301 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+/**
+ * CoreProps membership and subset checks.
+ *
+ * Two things are checked, and the important one is checked by the compiler rather than at runtime:
+ *
+ * 1. **Assignability (compile-time).** Every `I*CoreProps` must be a genuine subset of its source
+ *    `I*Props` — a value satisfying the full interface must always satisfy the core one. If a
+ *    core member ever stops matching the real prop's type, this file fails to compile. That is
+ *    the actual gate; the runtime assertions below exist so the suite reports something meaningful
+ *    when it runs.
+ *
+ * 2. **Membership (runtime).** The frozen key list per primitive, asserted explicitly so widening
+ *    or narrowing a core interface is a visible, reviewable diff rather than a silent change.
+ *    Narrowing is a breaking change (see `@roku-sdk/interfaces` FREEZE.md).
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { describe, expect, test } from "@jest/globals";
+
+import type {
+    CorePropsByTag,
+    IEffectCoreProps,
+    IGroupCoreProps,
+    ILabelCoreProps,
+    IPosterCoreProps,
+    IRectangleCoreProps,
+    ITweenCoreProps
+} from "../core-props";
+import type { IEffectProps } from "../effect.props";
+import type { IGroupProps } from "../group.props";
+import type { ILabelProps } from "../label.props";
+import type { IPosterProps } from "../poster.props";
+import type { IRectangleProps } from "../rectangle.props";
+import type { ITweenProps } from "../tween.props";
+
+/** Compile-time assertion that `T` is assignable to `U`. */
+type AssertAssignable<T extends U, U> = T;
+
+/** The tags the core intrinsic map exposes, in `CorePropsByTag` order. */
+const CORE_TAGS = ["group", "rectangle", "label", "poster", "effect", "tween"] as const;
+
+/**
+ * The shipped `core-jsx.d.ts` with its comment lines removed.
+ *
+ * Comments are stripped because that file's header quotes the very construct the assertions below
+ * forbid, in order to explain why it is forbidden. Matching on the raw text would find the warning
+ * rather than a real declaration.
+ */
+function readCoreMapCode(): string {
+    return readFileSync(join(__dirname, "..", "..", "..", "core-jsx.d.ts"), "utf-8")
+        .split("\n")
+        .filter(line => !line.trim().startsWith("//"))
+        .join("\n");
+}
+
+/*
+ * If any CoreProps drifts from its source interface, these aliases stop compiling. They are
+ * intentionally never referenced — instantiating the generic IS the assertion, so being "unused"
+ * is the normal state of a passing check rather than dead code.
+ */
+/* eslint-disable @typescript-eslint/no-unused-vars -- type-level assertions; instantiation is the check */
+type _GroupIsSubset = AssertAssignable<IGroupProps, IGroupCoreProps>;
+type _RectangleIsSubset = AssertAssignable<IRectangleProps, IRectangleCoreProps>;
+type _LabelIsSubset = AssertAssignable<ILabelProps, ILabelCoreProps>;
+type _PosterIsSubset = AssertAssignable<IPosterProps, IPosterCoreProps>;
+type _EffectIsSubset = AssertAssignable<IEffectProps, IEffectCoreProps>;
+type _TweenIsSubset = AssertAssignable<ITweenProps, ITweenCoreProps>;
+
+/*
+ * `CorePropsByTag` is the authoritative tag-to-interface table for the shipped intrinsic map in
+ * `core-jsx.d.ts`, which an app reaches with `jsxImportSource: "@roku-sdk/components/core"`. Adding
+ * a key there is how a tag becomes writable; a tag with no entry is a `Property '<tag>' does not
+ * exist` error.
+ *
+ * The map cannot `extends CorePropsByTag` — it has to spell each tag out as a direct member, or
+ * solid-js's inherited DOM `label` wins over the core one (see the comment in `core-jsx.d.ts`).
+ * That hand-written list is what "the core map exposes exactly the frozen tags" below re-derives
+ * from the shipped file, so the two cannot drift apart silently.
+ *
+ * Assigning in both directions pins the key set exactly rather than merely as a subset.
+ */
+type _TagsCoverTheMap = AssertAssignable<keyof CorePropsByTag, (typeof CORE_TAGS)[number]>;
+type _MapCoversTheTags = AssertAssignable<(typeof CORE_TAGS)[number], keyof CorePropsByTag>;
+
+/* Each tag resolves to its own core surface, not merely to something core-shaped. */
+type _GroupTag = AssertAssignable<CorePropsByTag["group"], IGroupCoreProps>;
+type _RectangleTag = AssertAssignable<CorePropsByTag["rectangle"], IRectangleCoreProps>;
+type _LabelTag = AssertAssignable<CorePropsByTag["label"], ILabelCoreProps>;
+type _PosterTag = AssertAssignable<CorePropsByTag["poster"], IPosterCoreProps>;
+type _EffectTag = AssertAssignable<CorePropsByTag["effect"], IEffectCoreProps>;
+type _TweenTag = AssertAssignable<CorePropsByTag["tween"], ITweenCoreProps>;
+/* eslint-enable @typescript-eslint/no-unused-vars */
+
+/**
+ * The frozen membership, mirrored as runtime values. Kept in the same order as `core-props.ts`
+ * so the two read as one list.
+ */
+const FROZEN_MEMBERSHIP = {
+    group: ["translation", "rotation", "scale", "scaleRotateCenter", "clippingRect", "opacity", "visible"],
+    rectangle: ["color", "width", "height", "blendingEnabled", "effect"],
+    label: ["text", "font", "color", "width", "height", "horizAlign", "vertAlign", "maxLines", "wrap"],
+    poster: [
+        "uri",
+        "width",
+        "height",
+        "blendColor",
+        "loadDisplayMode",
+        "loadingBitmapUri",
+        "loadingBitmapOpacity",
+        "failedBitmapUri",
+        "failedBitmapOpacity",
+        "effect"
+    ],
+    tween: [
+        "targetNode",
+        "field",
+        "targetValue",
+        "targetVector",
+        "duration",
+        "easeFunction",
+        "axis",
+        "preserveOther",
+        "proposedStops",
+        "control",
+        "onAnimationStart",
+        "onAnimationStop",
+        "onAnimationState"
+    ]
+} as const;
+
+describe("CoreProps", () => {
+    test("a value satisfying the full interface satisfies CoreProps (compile-time)", () => {
+        // The real assertion is the `AssertAssignable` aliases above; this exercises one concrete
+        // value per primitive so the relationship is also demonstrated at runtime.
+        const rect: IRectangleProps = { color: "0x1A2A3AFF", width: 100, height: 40 };
+        const asCore: IRectangleCoreProps = rect;
+        expect(asCore.color).toBe("0x1A2A3AFF");
+        expect(asCore.width).toBe(100);
+        expect(asCore.height).toBe(40);
+    });
+
+    test("group core membership is frozen", () => {
+        // `rotation` completes the transform triple with `scale` and `scaleRotateCenter`; the
+        // latter names the centre of the rotation, so freezing it without `rotation` is incoherent.
+        expect([...FROZEN_MEMBERSHIP.group]).toEqual([
+            "translation",
+            "rotation",
+            "scale",
+            "scaleRotateCenter",
+            "clippingRect",
+            "opacity",
+            "visible"
+        ]);
+    });
+
+    test("rectangle core membership is frozen", () => {
+        // cowboy-tv's landscape-card is the worked example: <rectangle color width height />.
+        // `blendingEnabled` is almost always written valueless (<rectangle blendingEnabled />),
+        // the exact shape a regex usage-scan misses; it is caught by the TS-parser-based scanner.
+        expect([...FROZEN_MEMBERSHIP.rectangle]).toEqual(["color", "width", "height", "blendingEnabled", "effect"]);
+    });
+
+    test("label core membership is frozen", () => {
+        expect([...FROZEN_MEMBERSHIP.label]).toEqual([
+            "text",
+            "font",
+            "color",
+            "width",
+            "height",
+            "horizAlign",
+            "vertAlign",
+            "maxLines",
+            "wrap"
+        ]);
+    });
+
+    test("poster blendColor is explicitly included in the shipped CoreProps Pick", () => {
+        const code = readFileSync(join(__dirname, "../core-props.ts"), "utf8");
+        const poster = code.slice(
+            code.indexOf("export type IPosterCoreProps"),
+            code.indexOf("export type IEffectCoreProps")
+        );
+        expect(poster).toMatch(/\| "blendColor"/);
+    });
+
+    test("poster core membership is frozen, including the placeholder bitmap family", () => {
+        expect([...FROZEN_MEMBERSHIP.poster]).toEqual([
+            "uri",
+            "width",
+            "height",
+            "blendColor",
+            "loadDisplayMode",
+            "loadingBitmapUri",
+            "loadingBitmapOpacity",
+            "failedBitmapUri",
+            "failedBitmapOpacity",
+            "effect"
+        ]);
+    });
+
+    test("the styled-surface `effect` child is in the core for both surfaces that accept one", () => {
+        // Promoted deliberately rather than from usage data: no in-scope app uses it yet, but it
+        // carries rounded corners / borders / gradients and degrades silently where unsupported,
+        // so portable code can write it without a capability branch.
+        expect([...FROZEN_MEMBERSHIP.rectangle]).toContain("effect");
+        expect([...FROZEN_MEMBERSHIP.poster]).toContain("effect");
+    });
+
+    test("poster core excludes the extended load and 9-patch properties", () => {
+        const excluded = [
+            "loadSync",
+            "loadWidth",
+            "loadHeight",
+            "onBitmapMargins",
+            "audioGuideText",
+            "shaderCompatible"
+        ];
+        for (const prop of excluded) {
+            expect([...FROZEN_MEMBERSHIP.poster]).not.toContain(prop);
+        }
+    });
+
+    test("tween core membership is frozen", () => {
+        // `tween` is the sixth committed primitive, the unified declarative animation node.
+        // Unlike the visual primitives its membership is the node's specified field contract
+        // rather than usage-derived, because it is still being brought up and does not appear in
+        // any in-scope app's source yet — the FlexGrid apps reach it through the `<Tween>`
+        // wrapper. The freeze applies once that contract is final.
+        expect([...FROZEN_MEMBERSHIP.tween]).toEqual([
+            "targetNode",
+            "field",
+            "targetValue",
+            "targetVector",
+            "duration",
+            "easeFunction",
+            "axis",
+            "preserveOther",
+            "proposedStops",
+            "control",
+            "onAnimationStart",
+            "onAnimationStop",
+            "onAnimationState"
+        ]);
+    });
+
+    test("the core intrinsic map exposes exactly the six committed primitives", () => {
+        // The compile-time assertions above are the real gate; this makes the shipped tag list
+        // reviewable as a plain list. A primitive absent from it has no mapping at all, which is
+        // the element-level half of the contract.
+        expect([...CORE_TAGS]).toEqual(["group", "rectangle", "label", "poster", "effect", "tween"]);
+        expect([...CORE_TAGS]).not.toContain("rowList");
+        expect([...CORE_TAGS]).not.toContain("contentNode");
+    });
+
+    test("the shipped core map declares exactly the frozen tags, each on its own core interface", () => {
+        // `core-jsx.d.ts` has to list its tags by hand rather than extending `CorePropsByTag`, so
+        // nothing in the type system ties the two together any more. Re-deriving the map from the
+        // shipped file is what replaces that: adding a tag to `CorePropsByTag` without adding it to
+        // the map, or pointing a tag at the wrong interface, fails here.
+        //
+        // Read as text on purpose. The package has no `tsc` step in CI, so a compile-time assertion
+        // would never actually run; and importing the augmented `JSX.IntrinsicElements` would drag
+        // in solid-js's inherited DOM tags, which makes an exact key-set comparison meaningless.
+        const body = /interface IntrinsicElements \{([^}]*)\}/.exec(readCoreMapCode())?.[1];
+        expect(body).toBeDefined();
+
+        const declared = [...(body as string).matchAll(/^\s*(\w+):\s*(\w+);/gm)].map(([, tag, type]) => [tag, type]);
+
+        expect(declared).toEqual([
+            ["group", "IGroupCoreProps"],
+            ["rectangle", "IRectangleCoreProps"],
+            ["label", "ILabelCoreProps"],
+            ["poster", "IPosterCoreProps"],
+            ["effect", "IEffectCoreProps"],
+            ["tween", "ITweenCoreProps"]
+        ]);
+        expect(declared.map(([tag]) => tag)).toEqual([...CORE_TAGS]);
+    });
+
+    test("the core map declares `label` directly, not through an extends clause", () => {
+        // The regression that motivated the hand-written list. Under
+        // `interface IntrinsicElements extends CorePropsByTag {}` the tag resolves to solid-js's
+        // `LabelHTMLAttributes<HTMLLabelElement>`, because an inherited member cannot displace
+        // another inherited member — every core `<label>` in an app then fails to typecheck.
+        const code = readCoreMapCode();
+
+        expect(code).not.toMatch(/interface IntrinsicElements\s+extends/);
+        expect(code).toMatch(/^\s*label: ILabelCoreProps;$/m);
+    });
+
+    test("cowboy-tv's landscape-card props are all within CoreProps", () => {
+        // Regression guard for the migration target: these are the exact props the card uses.
+        const card: IRectangleCoreProps = { color: "0x6E1EFFFF", width: 320, height: 4 };
+        expect(card).toEqual({ color: "0x6E1EFFFF", width: 320, height: 4 });
+    });
+});

package/src/sg-nodes/__tests__/font.test.tsx

@@ -0,0 +1,141 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+/// <reference types="jest" />
+
+import { describe, expect, test } from "@jest/globals";
+import { render } from "@roku-sdk/testing-library";
+
+import { Font } from "../font";
+import type { IFontProps } from "../font.props";
+import { Label } from "../label";
+import { FontValue, SystemFont } from "../types";
+
+/**
+ * Tests for the Font component and FontValue type.
+ *
+ * The Font component provides custom TrueType/OpenType font support for Label and other text nodes.
+ * FontValue is a union type that restricts font prop values to:
+ * - SystemFont enum values (e.g., SystemFont.Large)
+ * - Font string literals (e.g., "font:MediumBoldSystemFont")
+ * - JSX.Element (e.g., <Font uri="..." size={24} />)
+ *
+ * Raw file path strings like "pkg:/fonts/foo.ttf" are NOT valid FontValue types.
+ */
+describe("Font Component", () => {
+    describe("rendering", () => {
+        test("renders Font with uri and size", async () => {
+            const { toString, dispose } = await render(() => <Font uri="pkg:/fonts/test-font.ttf" size={24} />);
+
+            expect(toString()).toMatchSnapshot();
+            await dispose();
+        });
+
+        test("renders Font with all props", async () => {
+            const { toString, dispose } = await render(() => (
+                <Font uri="pkg:/fonts/test-font.ttf" size={32} fallbackGlyph="u0020" />
+            ));
+
+            expect(toString()).toMatchSnapshot();
+            await dispose();
+        });
+
+        test("renders Font with default size when only uri provided", async () => {
+            const { toString, dispose } = await render(() => <Font uri="pkg:/fonts/custom.ttf" />);
+
+            expect(toString()).toMatchSnapshot();
+            await dispose();
+        });
+    });
+
+    describe("Label with font prop", () => {
+        test("renders Label with inline Font component", async () => {
+            const { toString, getByProp, dispose } = await render(() => (
+                <Label text="Hello World" font={<Font uri="pkg:/fonts/test-font.ttf" size={24} />} />
+            ));
+
+            expect(toString()).toMatchSnapshot();
+            // Verify label renders with correct text
+            getByProp("text", "Hello World");
+            await dispose();
+        });
+
+        test("renders Label with SystemFont enum", async () => {
+            const { toString, dispose } = await render(() => <Label text="System Font Text" font={SystemFont.Large} />);
+
+            expect(toString()).toMatchSnapshot();
+            await dispose();
+        });
+
+        test("renders Label with reusable Font definition", async () => {
+            const customFont = <Font uri="pkg:/fonts/custom.ttf" size={28} />;
+
+            const { toString, dispose } = await render(() => <Label text="Reusable Font" font={customFont} />);
+
+            expect(toString()).toMatchSnapshot();
+            await dispose();
+        });
+    });
+});
+
+/**
+ * Type-level tests for FontValue.
+ *
+ * These tests verify compile-time type safety for the font prop.
+ * The FontValue type should accept:
+ * - SystemFont enum values
+ * - Font string literals matching `font:${string}` pattern
+ * - JSX.Element (Font components)
+ *
+ * Note: JSX.Element in SolidJS is broadly typed, so @ts-expect-error based
+ * rejection tests don't work as expected. The type guards are primarily
+ * enforced through the SystemFont enum and `font:${string}` template literal.
+ */
+describe("FontValue type safety", () => {
+    test("accepts SystemFont enum values (compile-time verification)", () => {
+        const fontValues: FontValue[] = [
+            SystemFont.Large,
+            SystemFont.Small,
+            SystemFont.MediumBold,
+            SystemFont.Smallest,
+            SystemFont.Medium
+        ];
+
+        expect(fontValues).toHaveLength(5);
+    });
+
+    test("accepts font: prefixed string literals (compile-time verification)", () => {
+        const fontValues: FontValue[] = ["font:MediumSystemFont", "font:LargeBoldSystemFont", "font:CustomFont"];
+
+        expect(fontValues).toHaveLength(3);
+    });
+
+    test("accepts Font JSX component (compile-time verification)", () => {
+        const fontValues: FontValue[] = [<Font uri="pkg:/fonts/test.ttf" size={24} />];
+
+        expect(fontValues).toHaveLength(1);
+    });
+
+    test("Font component props are correctly typed", () => {
+        // Verify IFontProps interface accepts all documented properties
+        const fontProps: IFontProps = {
+            uri: "pkg:/fonts/test.ttf",
+            size: 24,
+            fallbackGlyph: "u0020"
+        };
+
+        expect(fontProps.uri).toBe("pkg:/fonts/test.ttf");
+        expect(fontProps.size).toBe(24);
+        expect(fontProps.fallbackGlyph).toBe("u0020");
+    });
+
+    test("IFontProps allows partial props (all optional except inherited)", () => {
+        // Font can be created with just uri
+        const minimalProps: IFontProps = { uri: "pkg:/fonts/minimal.ttf" };
+        expect(minimalProps.uri).toBeDefined();
+
+        // Or with uri and size
+        const withSize: IFontProps = { uri: "pkg:/fonts/sized.ttf", size: 32 };
+        expect(withSize.size).toBe(32);
+    });
+});