@roku-sdk/components 0.0.0-stage → 2.18.0

package/src/tween.tsx

@@ -0,0 +1,173 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { type DomNode } from "@roku-sdk/interfaces";
+import { type Component, createEffect, onCleanup, tmTransaction, untrack } from "@roku-sdk/solid";
+
+import type { AnimationState } from "./sg-nodes/animation.props";
+import type { ITweenProps } from "./sg-nodes/tween.props";
+import type { Vector2D } from "./sg-nodes/types";
+
+declare const __DEV__: boolean;
+
+/**
+ * Unified `<tween>` primitive.
+ *
+ * Animate a target node using the unified native field contract.
+ *
+ * One component presenting the unified tween field contract, replacing the four earlier
+ * tween wrappers (`Tween`/GridTween, `TweenFloat`, `FloatTween`, `ScaleTween`). On device
+ * it renders a `<tween>` element, which is the firmware's native node when
+ * `roku.hasFeature("tween")` reports support. Otherwise `@roku-sdk/compat` aliases the tag
+ * to its `RsgTweenShim`; without compat creating it throws an error naming the missing feature. A renderer that
+ * provides its own tween implementation aliases this module to it at build time.
+ */
+export interface TweenProps extends Omit<ITweenProps, "targetNode" | "onAnimationState"> {
+    /** Node reference to animate, or a getter returning it. Takes precedence over targetRef. */
+    targetNode?: unknown | (() => unknown);
+    /** @deprecated Use targetNode. Retained for one minor release. */
+    targetRef?: unknown | (() => unknown);
+    /** Called with separate state and value arguments, unlike the intrinsic's tuple event. */
+    onAnimationState?: (state: AnimationState, value: number | Vector2D) => void;
+}
+
+let tweenIdCounter = 0;
+
+/** Fields the dev-only `proposedStops` shape check knows to be vector2d. */
+const VECTOR_FIELDS: ReadonlySet<string> = new Set(["translation", "scale", "scaleRotateCenter"]);
+/** Fields the dev-only `proposedStops` shape check knows to be float. */
+const FLOAT_FIELDS: ReadonlySet<string> = new Set(["opacity", "width", "height", "rotation"]);
+
+/**
+ * Dev-only: describe each way `proposedStops` (and `axis`) does not match the shape the field
+ * and axis call for. Returns `[key, message]` pairs, where `key` names the distinct problem so a
+ * caller can report each one once. A field outside the known lists is not checked.
+ *
+ * The expected shapes: float fields, and `axis` `"x"` / `"y"` on a vector field, take
+ * `number[]`; `axis` `"all"` (the default) on a vector field takes `[number, number][]`; `axis`
+ * is ignored on float fields.
+ */
+function proposedStopsShapeProblems(
+    field: string,
+    axis: string | undefined,
+    stops: readonly unknown[] | undefined
+): [key: string, message: string][] {
+    const problems: [string, string][] = [];
+    const list = Array.isArray(stops) ? stops : [];
+    if (VECTOR_FIELDS.has(field)) {
+        if (axis === "x" || axis === "y") {
+            if (list.some(stop => Array.isArray(stop))) {
+                problems.push([
+                    `${axis}:array`,
+                    `Tween: proposedStops on "${field}" with axis "${axis}" must be scalars (the ${axis} coordinate); got an array. Array entries are skipped.`
+                ]);
+            }
+        } else {
+            const shown = axis ?? "all";
+            if (list.some(stop => !Array.isArray(stop))) {
+                problems.push([
+                    "all:scalar",
+                    `Tween: proposedStops on "${field}" with axis "${shown}" must be [x, y] pairs; got a scalar. Scalar entries are skipped.`
+                ]);
+            }
+            const wrongLength = list.find(stop => Array.isArray(stop) && stop.length !== 2) as unknown[] | undefined;
+            if (wrongLength) {
+                problems.push([
+                    "all:length",
+                    `Tween: proposedStops on "${field}" with axis "${shown}" must be [x, y] pairs; got an array of length ${wrongLength.length}. Entries that are not pairs are skipped.`
+                ]);
+            }
+        }
+    } else if (FLOAT_FIELDS.has(field)) {
+        if (axis !== undefined) {
+            problems.push(["float:axis", `Tween: axis "${axis}" is ignored on float field "${field}"; remove it.`]);
+        }
+        if (list.some(stop => Array.isArray(stop))) {
+            problems.push([
+                "float:array",
+                `Tween: proposedStops on float field "${field}" must be numbers; got an array. Array entries are skipped.`
+            ]);
+        }
+    }
+    return problems;
+}
+
+const resolveTarget = (targetRef: unknown | (() => unknown)): unknown =>
+    typeof targetRef === "function" ? (targetRef as () => unknown)() : targetRef;
+
+export const Tween: Component<TweenProps> = props => {
+    const animationId = `tweenAnim_${props.id ?? ""}_${tweenIdCounter++}`;
+    const field = props.field ?? "translation";
+
+    let tweenRef: unknown;
+    let boundTarget: unknown;
+
+    const bindTarget = (target: unknown): void => {
+        if (tweenRef == null || target == null || target === boundTarget) return;
+        boundTarget = target;
+        tmTransaction.setProperty(tweenRef as DomNode, "targetNode", target as DomNode, undefined);
+    };
+
+    // A trigger fires on whatever node is bound when it lands, so a target switched in the
+    // same update as a trigger has to be written first, whichever effect runs first.
+    const withTarget = <V,>(value: V): V => {
+        bindTarget(untrack(() => resolveTarget(props.targetNode ?? props.targetRef)));
+        return value;
+    };
+
+    // Keep the node's targetNode bound to the current ref (parents may populate a ref after
+    // mount, and pooled nodes are recycled onto new cells).
+    createEffect(function syncTargetNodeEffect() {
+        bindTarget(resolveTarget(props.targetNode ?? props.targetRef));
+    });
+
+    // The node and its target reference each other on the render thread, so a disposed tween
+    // still holding the target keeps its whole subtree alive. `prev` stays undefined: a node
+    // passed as `prev` is queued for removal.
+    onCleanup(() => {
+        if (tweenRef == null) return;
+        tmTransaction.setProperty(tweenRef as DomNode, "targetNode", null as unknown as DomNode, undefined);
+        tweenRef = undefined;
+        boundTarget = undefined;
+    });
+
+    // Dev-only: warn when proposedStops (or axis) does not have the shape the field and axis
+    // call for, once per distinct problem per instance. DCE'd when __DEV__ is false.
+    if (typeof __DEV__ !== "undefined" && __DEV__) {
+        const warned = new Set<string>();
+        createEffect(function checkProposedStopsShapeEffect() {
+            for (const [key, message] of proposedStopsShapeProblems(field, props.axis, props.proposedStops)) {
+                if (warned.has(key)) continue;
+                warned.add(key);
+                console.warn(message);
+            }
+        });
+    }
+
+    const bindTween = (el: unknown): void => {
+        tweenRef = el;
+        bindTarget(resolveTarget(props.targetNode ?? props.targetRef));
+    };
+    const onAnimationState = ([state, value]: [AnimationState, number | Vector2D]): void => {
+        props.onAnimationState?.(state, value);
+    };
+
+    return (
+        <tween
+            ref={bindTween}
+            id={`tween-${animationId}`}
+            field={field}
+            duration={props.duration ?? 0.333}
+            easeFunction={props.easeFunction ?? "outCubic"}
+            axis={props.axis ?? "all"}
+            preserveOther={props.preserveOther ?? 0}
+            targetValue={withTarget(props.targetValue)}
+            targetVector={withTarget(props.targetVector)}
+            proposedStops={withTarget(props.proposedStops)}
+            control={withTarget(props.control)}
+            onAnimationStart={props.onAnimationStart}
+            onAnimationStop={props.onAnimationStop}
+            onAnimationState={props.onAnimationState ? onAnimationState : undefined}
+        />
+    );
+};

package/src/types.ts

@@ -0,0 +1,8 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+export * from "./sg-nodes/types";
+
+export type MediaControl = "none" | "play" | "pause" | "stop" | "resume" | "replay" | "prebuffer" | "skipcontent";
+
+export type MediaState = "none" | "buffering" | "playing" | "paused" | "stopping" | "stopped" | "finished" | "error";

package/src/xml-components/blended-busy-spinner/BlendedBusySpinner.brs

@@ -0,0 +1,13 @@
+Sub onUriChanged()
+    top = m.top
+    poster = top.poster
+
+    poster.uri = top.uri
+End Sub
+
+Sub onBlendColorChanged()
+    top = m.top
+    poster = top.poster
+
+    poster.blendColor = top.blendColor
+End Sub

package/src/xml-components/blended-busy-spinner/BlendedBusySpinner.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<component name="BlendedBusySpinner" extends="BusySpinner">
+    <script type="text/brightscript" uri="BlendedBusySpinner.brs" />
+    <interface>
+        <field id="uri" type="string" onChange="onUriChanged" />
+        <field id="blendColor" type="string" onChange="onBlendColorChanged" />
+    </interface>
+
+</component>

package/src/xml-components/blended-busy-spinner/BlendedBusySpinner.xml.d.ts

@@ -0,0 +1,42 @@
+// Auto-generated TypeScript declarations for XML component import.
+// DO NOT EDIT — this file is regenerated during build.
+//
+// Source component: BlendedBusySpinner
+// Extends: BusySpinner
+
+import type { IBusySpinnerProps } from "@roku-sdk/components";
+import type { TypedXmlComponent } from "@roku-sdk/interfaces";
+
+interface BlendedBusySpinnerFields {
+    uri: string;
+    blendColor: string;
+}
+
+export interface IBlendedBusySpinnerProps extends IBusySpinnerProps, Partial<BlendedBusySpinnerFields> {}
+
+declare const _default: TypedXmlComponent<"BlendedBusySpinner", BlendedBusySpinnerFields>;
+export default _default;
+
+declare module "@roku-sdk/solid" {
+    namespace JSX {
+        interface IntrinsicElements {
+            blendedBusySpinner: IBlendedBusySpinnerProps;
+        }
+    }
+}
+
+declare module "@roku-sdk/solid/jsx-runtime" {
+    namespace JSX {
+        interface IntrinsicElements {
+            blendedBusySpinner: IBlendedBusySpinnerProps;
+        }
+    }
+}
+
+declare module "solid-js" {
+    namespace JSX {
+        interface IntrinsicElements {
+            blendedBusySpinner: IBlendedBusySpinnerProps;
+        }
+    }
+}

package/src/xml-components/bounding-tracker/BoundingTracker.brs

@@ -0,0 +1,26 @@
+' Copyright (c) 2026 Roku, Inc.
+' SPDX-License-Identifier: MIT
+
+sub init()
+    m.top.BoundsChange = m.top.boundingRect()
+    m.top.observeField("change", "onChange")
+    m.top.observeField("doMeasure", "doMeasure")
+end sub
+
+sub onChange()
+    setBoundingRect()
+end sub
+
+sub doMeasure(msg as Object)
+    data = msg.getData()
+    if data = true
+        setBoundingRect()
+    end if
+end sub
+
+sub setBoundingRect()
+    rect = m.top.boundingRect()
+    if rect.x <> m.top.BoundsChange.x or rect.y <> m.top.BoundsChange.y or rect.width <> m.top.BoundsChange.width or rect.height <> m.top.BoundsChange.height then
+        m.top.BoundsChange = rect
+    end if
+end sub

package/src/xml-components/bounding-tracker/BoundingTracker.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+Copyright (c) 2026 Roku, Inc.
+SPDX-License-Identifier: MIT
+-->
+
+
+<component name="bounding-tracker" extends="Group" focusable="true">
+    <script type="text/brightscript" uri="BoundingTracker.brs" />
+    <interface>
+        <field id="BoundsChange" type="assocarray" />
+        <field id="doMeasure" type="bool" />
+    </interface>
+</component>

package/src/xml-components/bounding-tracker/BoundingTracker.xml.d.ts

@@ -0,0 +1,42 @@
+// Auto-generated TypeScript declarations for XML component import.
+// DO NOT EDIT — this file is regenerated during build.
+//
+// Source component: bounding-tracker
+// Extends: Group
+
+import type { IGroupProps } from "@roku-sdk/components";
+import type { TypedXmlComponent } from "@roku-sdk/interfaces";
+
+interface boundingTrackerFields {
+    BoundsChange: Record<string, unknown>;
+    doMeasure: boolean;
+}
+
+export interface IboundingTrackerProps extends IGroupProps, Partial<boundingTrackerFields> {}
+
+declare const _default: TypedXmlComponent<"bounding-tracker", boundingTrackerFields>;
+export default _default;
+
+declare module "@roku-sdk/solid" {
+    namespace JSX {
+        interface IntrinsicElements {
+            boundingTracker: IboundingTrackerProps;
+        }
+    }
+}
+
+declare module "@roku-sdk/solid/jsx-runtime" {
+    namespace JSX {
+        interface IntrinsicElements {
+            boundingTracker: IboundingTrackerProps;
+        }
+    }
+}
+
+declare module "solid-js" {
+    namespace JSX {
+        interface IntrinsicElements {
+            boundingTracker: IboundingTrackerProps;
+        }
+    }
+}

package/src/xml-components/channel-store/channelStoreExt.brs

@@ -0,0 +1,159 @@
+' Copyright (c) 2026 Roku, Inc.
+' SPDX-License-Identifier: MIT
+
+Sub init()
+  m.top.observeField("userData", "updateUserData")
+  m.top.observeField("userRegionData", "updateUserRegionData")
+  m.top.observeField("requestedUserDataInfoObject", "updateRequestedUserDataInfo")
+  m.top.observeField("storeChannelCredDataStatus", "updateChannelCredDataStatus")
+  m.top.observeField("channelCred", "updateChannelCred")
+  m.top.observeField("catalog", "updateCatalog")
+  m.top.observeField("order", "updateOrder")
+  m.top.observeField("orderStatus", "updateOrderStatus")
+  m.top.observeField("purchases", "updatePurchases")
+  m.top.observeField("requestPartnerOrderObject", "updateRequestPartnerOrder")
+  m.top.observeField("requestPartnerOrderStatus", "updateRequestPartnerOrderStatus")
+  m.top.observeField("confirmPartnerOrderObject", "updateConfirmPartnerOrder")
+  m.top.observeField("confirmPartnerOrderStatus", "updateConfirmPartnerOrderStatus")
+  m.top.observeField("deviceAttestationToken", "updateDeviceAttestationToken")
+end Sub
+
+sub updateUserData()
+    userData = m.top.userData
+    if userData <> invalid
+        m.top.userDataObject = m.top.userData.getFields()
+    else
+        m.top.userDataObject = {}
+    end if
+end sub
+
+sub updateUserRegionData()
+    userRegionData = m.top.userRegionData
+    if userRegionData <> invalid
+        m.top.userRegionDataObject = m.top.userRegionData.getFields()
+    else
+        m.top.userRegionDataObject = {}
+    end if
+end sub
+
+sub updateRequestedUserDataInfo()
+    cn = CreateObject("roSGNode","ContentNode")
+    cn.Update(m.top.requestedUserDataInfoObject, true)
+    m.top.requestedUserDataInfo = cn
+end sub
+
+sub updateChannelCredDataStatus()
+    storeChannelCredDataStatus = m.top.storeChannelCredDataStatus
+    if storeChannelCredDataStatus <> invalid
+        m.top.storeChannelCredDataStatusObject = m.top.storeChannelCredDataStatus.getFields()
+    else
+        m.top.storeChannelCredDataStatusObject = {}
+    end if
+end sub
+
+sub updateChannelCred()
+    channelCred = m.top.channelCred
+    if channelCred <> invalid
+        m.top.channelCredObject = m.top.channelCred.getFields()
+    else
+        m.top.channelCredObject = {}
+    end if
+end sub
+
+sub updateCatalog()
+    catalog = m.top.catalog
+    if catalog <> invalid
+        result = []
+        products = catalog.getChildren(-1, 0)
+        for each product in products
+            result.push(product.getFields())
+        end for
+        m.top.catalogObject = result
+    else
+        m.top.catalogObject = []
+    end if
+end sub
+
+sub updateOrder()
+    order = m.top.orderObject
+    cn = CreateObject("roSGNode","ContentNode")
+    for each item in order
+        itemCn = cn.appendChild("ContentNode")
+        itemCn.Update(item, true)
+    end for
+    m.top.order = cn
+end sub
+
+sub updateOrderStatus()
+    orderStatus = m.top.orderStatus
+    if orderStatus <> invalid
+        m.top.orderStatusObject = orderStatus.getFields()
+
+        orderItems = []
+        items = orderStatus.getChildren(-1, 0)
+        for each item in items
+            orderItems.push(item.getFields())
+        end for
+        m.top.orderItemsStatusObject = orderItems
+    else
+        m.top.orderItemsStatusObject = []
+    end if
+end sub
+
+sub updatePurchases()
+    purchases = m.top.purchases
+    if purchases <> invalid
+        m.top.purchasesStatusObject = purchases.getFields()
+
+        purchaseItems = []
+        items = purchases.getChildren(-1, 0)
+        for each item in items
+            purchaseItems.push(item.getFields())
+        end for
+        m.top.purchasesObject = purchaseItems
+    else
+        m.top.purchasesStatusObject = {}
+        m.top.purchasesObject = []
+    end if
+end sub
+
+sub updateRequestPartnerOrder()
+    partnerOrder = m.top.requestPartnerOrderObject
+    cn = CreateObject("roSGNode","ContentNode")
+    cn.Update(partnerOrder, true)
+    m.top.requestPartnerOrder = cn
+end sub
+
+sub updateRequestPartnerOrderStatus()
+    partnerOrderStatus = m.top.requestPartnerOrderStatus
+    if partnerOrderStatus <> invalid
+        m.top.requestPartnerOrderStatusObject = partnerOrderStatus.getFields()
+    else
+        m.top.requestPartnerOrderStatusObject = {}
+    end if
+end sub
+
+sub updateConfirmPartnerOrder()
+    partnerOrder = m.top.confirmPartnerOrderObject
+    cn = CreateObject("roSGNode","ContentNode")
+    cn.Update(partnerOrder, true)
+    m.top.confirmPartnerOrder = cn
+end sub
+
+sub updateConfirmPartnerOrderStatus()
+    partnerOrderStatus = m.top.confirmPartnerOrderStatus
+    if partnerOrderStatus <> invalid
+        m.top.confirmPartnerOrderStatusObject = partnerOrderStatus.getFields()
+    else
+        m.top.confirmPartnerOrderStatusObject = {}
+    end if
+end sub
+
+sub updateDeviceAttestationToken()
+    deviceAttestationToken = m.top.deviceAttestationToken
+    if deviceAttestationToken <> invalid
+        m.top.deviceAttestationTokenObject = deviceAttestationToken.getFields()
+    else
+        m.top.deviceAttestationTokenObject = {}
+    end if
+end sub

package/src/xml-components/channel-store/channelStoreExt.xml

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+Copyright (c) 2026 Roku, Inc.
+SPDX-License-Identifier: MIT
+-->
+
+
+<component name="channelStoreExt" extends="ChannelStore" focusable="false">
+    <script type="text/brightscript" uri="channelStoreExt.brs" />
+    <interface>
+        <field id="userDataObject" type="assocarray" />
+        <field id="userRegionDataObject" type="assocarray" />
+        <field id="requestedUserDataInfoObject" type="assocarray" />
+        <field id="storeChannelCredDataStatusObject" type="assocarray" />
+        <field id="channelCredObject" type="assocarray" />
+        <field id="catalogObject" type="array" />
+        <field id="orderObject" type="array" />
+        <field id="deltaOrderObject" type="assocarray" />
+        <field id="orderStatusObject" type="assocarray" />
+        <field id="orderItemsStatusObject" type="array" />
+        <field id="purchasesStatusObject" type="assocarray" />
+        <field id="purchasesObject" type="array" />
+        <field id="requestPartnerOrderObject" type="assocarray" />
+        <field id="requestPartnerOrderStatusObject" type="assocarray" />
+        <field id="confirmPartnerOrderObject" type="assocarray" />
+        <field id="confirmPartnerOrderStatusObject" type="assocarray" />
+        <field id="deviceAttestationTokenObject" type="assocarray" />
+    </interface>
+</component>

package/src/xml-components/channel-store/channelStoreExt.xml.d.ts

@@ -0,0 +1,57 @@
+// Auto-generated TypeScript declarations for XML component import.
+// DO NOT EDIT — this file is regenerated during build.
+//
+// Source component: channelStoreExt
+// Extends: ChannelStore
+
+import type { IChannelStoreProps } from "@roku-sdk/components";
+import type { TypedXmlComponent } from "@roku-sdk/interfaces";
+
+interface channelStoreExtFields {
+    userDataObject: Record<string, unknown>;
+    userRegionDataObject: Record<string, unknown>;
+    requestedUserDataInfoObject: Record<string, unknown>;
+    storeChannelCredDataStatusObject: Record<string, unknown>;
+    channelCredObject: Record<string, unknown>;
+    catalogObject: unknown[];
+    orderObject: unknown[];
+    deltaOrderObject: Record<string, unknown>;
+    orderStatusObject: Record<string, unknown>;
+    orderItemsStatusObject: unknown[];
+    purchasesStatusObject: Record<string, unknown>;
+    purchasesObject: unknown[];
+    requestPartnerOrderObject: Record<string, unknown>;
+    requestPartnerOrderStatusObject: Record<string, unknown>;
+    confirmPartnerOrderObject: Record<string, unknown>;
+    confirmPartnerOrderStatusObject: Record<string, unknown>;
+    deviceAttestationTokenObject: Record<string, unknown>;
+}
+
+export interface IchannelStoreExtProps extends IChannelStoreProps, Partial<channelStoreExtFields> {}
+
+declare const _default: TypedXmlComponent<"channelStoreExt", channelStoreExtFields>;
+export default _default;
+
+declare module "@roku-sdk/solid" {
+    namespace JSX {
+        interface IntrinsicElements {
+            channelStoreExt: IchannelStoreExtProps;
+        }
+    }
+}
+
+declare module "@roku-sdk/solid/jsx-runtime" {
+    namespace JSX {
+        interface IntrinsicElements {
+            channelStoreExt: IchannelStoreExtProps;
+        }
+    }
+}
+
+declare module "solid-js" {
+    namespace JSX {
+        interface IntrinsicElements {
+            channelStoreExt: IchannelStoreExtProps;
+        }
+    }
+}