@roku-sdk/components 0.0.0-stage → 2.18.0

package/src/button-row.tsx

@@ -0,0 +1,126 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+import {
+    Component,
+    EventHandler,
+    Focusable,
+    FocusableGroup,
+    IButtonDataProps,
+    ResType,
+    Uri,
+    Vector2D
+} from "@roku-sdk/components";
+import { createMemo, createSelector, For, Show } from "@roku-sdk/solid";
+
+interface ISingleButtonProps extends IButtonDataProps {
+    text?: string;
+}
+
+export type IButtonRecord = ISingleButtonProps | string;
+
+export interface IButtonRowProps extends IButtonDataProps {
+    buttons: IButtonRecord[];
+    translation?: ResType<Vector2D>;
+    onButtonFocused?: EventHandler<number>;
+    onButtonSelected?: EventHandler<number>;
+    opacity?: number;
+    focusIdx?: number;
+    itemSpacing?: number;
+    gainFocus?: boolean;
+}
+
+const buttonDataKeys: (keyof IButtonDataProps)[] = [
+    "textColor",
+    "focusedTextColor",
+    "textFont",
+    "focusedTextFont",
+    "focusFootprintBitmapUri",
+    "focusBitmapUri",
+    "iconUri",
+    "focusedIconUri",
+    "height",
+    "minWidth",
+    "maxWidth",
+    "showFocusFootprint"
+];
+
+const defaultButtonData: ISingleButtonProps = {
+    showFocusFootprint: true,
+    iconUri: "",
+    focusedIconUri: "",
+    textFont: "font:TinySystemFont",
+    focusedTextFont: "font:TinyBoldSystemFont"
+};
+
+const createButtonProps = (button: IButtonRecord, componentProps: IButtonDataProps): ISingleButtonProps => {
+    let buttonProps: ISingleButtonProps = buttonDataKeys.reduce(
+        (acc: ISingleButtonProps, key) => {
+            const componentValue = componentProps[key];
+            if (componentValue !== undefined) {
+                (acc[key] as number | boolean | Uri) = componentValue;
+            }
+            return acc;
+        },
+        { ...defaultButtonData }
+    );
+
+    if (typeof button === "string") {
+        buttonProps.text = button;
+    } else {
+        buttonProps = { ...buttonProps, ...button };
+    }
+    return buttonProps;
+};
+
+export const ButtonRow: Component<IButtonRowProps> = props => {
+    const focusIdx = () => props.focusIdx || 0;
+
+    const onButtonFocused: EventHandler<string | null> = (id: string | null) => {
+        if (props.onButtonFocused && id) {
+            props.onButtonFocused(parseInt(id.replace(props.id || "", "")));
+        }
+    };
+
+    const buttonsLength = createMemo(() => props.buttons.length);
+
+    // Create a stable array of button indices that only changes when length changes
+    const buttonIndices = createMemo(() => Array.from({ length: buttonsLength() }, (_, i) => i));
+    const isFocused = createSelector(focusIdx, (a, b) => (props.gainFocus === undefined || props.gainFocus) && a === b);
+
+    return (
+        <FocusableGroup id={props.id} rememberLastFocus={true} gainFocus={props.gainFocus} opacity={props.opacity}>
+            <Show when={buttonsLength() > 0}>
+                <layoutGroup
+                    layoutDirection="horiz"
+                    horizAlignment="left"
+                    translation={props.translation}
+                    itemSpacings={[props.itemSpacing || 32]}
+                >
+                    <For
+                        each={buttonIndices()}
+                        children={(index: number) => {
+                            const buttonAtIndex = (): IButtonRecord | undefined => props.buttons[index];
+                            const onButtonSelected: EventHandler<never> = () => props.onButtonSelected?.(index);
+                            return (
+                                <Show when={buttonAtIndex() !== undefined}>
+                                    <Focusable
+                                        nextFocusRight={`${props.id || ""}${index < buttonsLength() - 1 ? (index + 1).toString() : undefined}`}
+                                        nextFocusLeft={`${props.id || ""}${index > 0 ? (index - 1).toString() : undefined}`}
+                                    >
+                                        <button
+                                            gainFocus={isFocused(index)}
+                                            onFocusedChild={onButtonFocused}
+                                            onButtonSelected={onButtonSelected}
+                                            {...createButtonProps(buttonAtIndex()!, props)}
+                                            id={`${props.id || ""}${index.toString()}`}
+                                        />
+                                    </Focusable>
+                                </Show>
+                            );
+                        }}
+                    />
+                </layoutGroup>
+            </Show>
+        </FocusableGroup>
+    );
+};

package/src/channel-store.props.ts

@@ -0,0 +1,425 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { EventHandler, ResObject } from "./sg-nodes/types";
+
+export interface IChannelStoreRequestStatusEvent {
+    command: string;
+    context: Record<string, string>;
+    requestid: number;
+    result: Record<string, string | number | boolean>;
+    status: number;
+    statusmessage: string;
+}
+
+/**
+ * Command strings supported by the ChannelStore node.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/channelstore}
+ */
+export type ChannelStoreCommand =
+    | "none"
+    | "getUserData"
+    | "getUserRegionData"
+    | "storeChannelCredData"
+    | "getChannelCred"
+    | "getCatalog"
+    | "doOrder"
+    | "getPurchases"
+    | "getAllPurchases"
+    | "requestPartnerOrder"
+    | "confirmPartnerOrder"
+    | "getDeviceAttestationToken";
+
+/** Context for the RFI (Request for Information) screen. */
+export type ChannelStoreUserDataContext = "signin" | "signup";
+
+/**
+ * Custom request object for advanced ChannelStore operations.
+ */
+export interface IChannelStoreRequest {
+    command?: string;
+    params?: ResObject<Record<string, string | number | boolean>>;
+    context?: ResObject<Record<string, string>>;
+}
+
+/**
+ * Roku customer account information returned by the `getUserData` command.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/channelstore | getUserData Command}
+ */
+export interface IUserData {
+    email?: string;
+    phone?: string;
+    firstName?: string;
+    lastName?: string;
+    street?: string;
+    city?: string;
+    state?: string;
+    zip?: string;
+    country?: string;
+    birth?: string;
+    gender?: string;
+}
+
+export type EventHandlerUserData = EventHandler<IUserData>;
+
+/**
+ * Region data returned by the `getUserRegionData` command.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/channelstore | getUserRegionData Command}
+ */
+export interface IUserRegionData {
+    state: string;
+    zip: string;
+    country: string;
+}
+
+export type EventHandlerUserRegionData = EventHandler<IUserRegionData>;
+
+/**
+ * Configuration for the RFI (Request for Information) screen.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/channelstore | requestedUserDataInfo Field}
+ */
+export interface IRequestedUserDataInfo {
+    /** Whether the RFI screen is for sign-up or sign-in. */
+    context?: ChannelStoreUserDataContext;
+    /**
+     * When true, the RFI signup screen displays the values of the requested customer
+     * information. Has no effect if context is "signin".
+     * @default false
+     */
+    forceShowData?: boolean;
+    [key: string]: unknown;
+}
+
+/**
+ * Status returned by the `storeChannelCredData` command.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/channelstore | storeChannelCredData Command}
+ */
+export interface IStoreChannelCredDataStatus {
+    /** JSON string with status, error, and error_detail fields. */
+    response: string;
+    /** Request status; 0 indicates success. */
+    status: number;
+}
+
+export type EventHandlerStoreChannelCredDataStatus = EventHandler<IStoreChannelCredDataStatus>;
+
+/**
+ * Channel credential data returned by the `getChannelCred` command.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/channelstore | getChannelCred Command}
+ */
+export interface IChannelCred {
+    /** The app ID (e.g., "2213" for Roku Media Player). */
+    channelId: string;
+    /** Error description; empty string on success. */
+    errorCode: string;
+    /** JSON string containing roku_pucid, token_type, channel_data, and error fields. */
+    json: string;
+    /** Unique identifier of the device. */
+    publisherDeviceId: string;
+    /** Request status; 0 indicates success. */
+    status: number;
+}
+
+export type EventHandlerChannelCred = EventHandler<IChannelCred>;
+
+/**
+ * Product information returned by the `getCatalog` command.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/channelstore | getCatalog Command}
+ */
+export interface IProduct {
+    /** Product identifier from the Developer Dashboard. */
+    code: string;
+    /** Item name / description. */
+    name: string;
+    /** Quantity (for consumable products). */
+    qty: number;
+    /** Product type (e.g., "MonthlySub"). */
+    productType: string;
+    /** Localized cost with currency symbol. */
+    cost: string;
+    /** Free trial length (e.g., 1 for 1-month, 7 for 7-day). */
+    freeTrialQuantity: number;
+    /** Free trial unit ("Days" or "Months"). */
+    freeTrialType: string;
+    /** Introductory pricing discounted price. */
+    trialCost: number;
+    /** Months of introductory pricing. */
+    trialQuantity: number;
+    /** Unit for introductory pricing ("months"). */
+    trialType: string;
+    /** Whether the product is "saved" or "approved for sale". */
+    status: string;
+    /** Subscription purchase date. */
+    purchaseDate: string;
+}
+
+export type EventHandlerCatalog = EventHandler<IProduct[]>;
+
+/**
+ * An item in an order for the `doOrder` command.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/channelstore | order Field}
+ */
+export interface IOrderItem {
+    /** Product identifier. */
+    code: string;
+    /** Quantity to purchase. */
+    qty: number;
+    /** Set to "Upgrade" or "Downgrade" for subscription plan changes. */
+    action?: string;
+}
+
+/**
+ * Status returned by the `doOrder` command.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/channelstore | doOrder Command}
+ */
+export interface IOrderStatus {
+    /** Completion status (1 = success, 2 = interrupted, 0 = network error, etc.). */
+    status: number;
+    /** Description of the completion status. */
+    statusMessage: string;
+}
+
+export type EventHandlerOrderStatus = EventHandler<IOrderStatus>;
+
+export type EventHandlerOrderItemsStatus = EventHandler<IPurchase[]>;
+
+/**
+ * Status returned by `getPurchases` / `getAllPurchases` commands.
+ */
+export interface IPurchasesStatus {
+    status: number;
+    statusMessage: string;
+}
+
+export type EventHandlerPurchasesStatus = EventHandler<IPurchasesStatus>;
+
+/**
+ * Purchase information returned by `getPurchases` or `getAllPurchases` commands.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/channelstore | getPurchases Command}
+ */
+export interface IPurchase {
+    /** Product identifier. */
+    code: string;
+    /** Localized cost with currency symbol. */
+    cost: string;
+    /** Subscription expiration date (ISO 8601). */
+    expirationDate: string;
+    /** Free trial length. */
+    freeTrialQuantity: number;
+    /** Free trial unit ("Days" or "Months"). */
+    freeTrialType: string;
+    /** Whether subscription is past due ("true" if in dunning state). */
+    inDunning: string;
+    /** Item name / description. */
+    name: string;
+    /** Product type (e.g., "MonthlySub"). */
+    productType: string;
+    /** Where the purchase was made ("web" or "device"). */
+    purchaseChannel: string;
+    /** How the purchase was made ("isu" or "iap"). */
+    purchaseContext: string;
+    /** Purchase date (ISO 8601). */
+    purchaseDate: string;
+    /** Transaction ID. */
+    purchaseId: string;
+    /** Quantity purchased. */
+    qty: number;
+    /** Subscription renewal date (ISO 8601). */
+    renewalDate: string;
+    /** "Valid" for current subscriptions, "Invalid" for canceled/expired. */
+    status: string;
+    /** Description of the status. */
+    statusMessage: string;
+    /** Introductory pricing discounted price. */
+    trialCost: number;
+    /** Months of introductory pricing. */
+    trialQuantity: number;
+    /** Unit for introductory pricing ("months"). */
+    trialType: string;
+}
+
+export type EventHandlerPurchases = EventHandler<IPurchase[]>;
+
+/**
+ * Partner order data for TVOD apps (`requestPartnerOrder` / `confirmPartnerOrder`).
+ *
+ * @see {@link https://developer.roku.com/dev/docs/channelstore | requestPartnerOrder Field}
+ */
+export interface IPartnerOrder {
+    /** Original price of the product (no currency symbol, e.g., "3.99"). */
+    priceDisplay: string;
+    /** Final price including discounts (no currency symbol). */
+    price: string;
+    /** Alphanumeric coupon code for discounted pricing. */
+    couponCode?: string;
+    /** Publisher-specific SKU or unique identifier. */
+    contentKey: string;
+    /** Product identifier. */
+    code: string;
+    /** Product description (e.g., movie title). */
+    title?: string;
+    /** Order ID returned by Roku (for confirmPartnerOrder). */
+    orderID?: string;
+    pin?: string;
+}
+
+export type EventHandlerPartnerOrder = EventHandler<IPartnerOrder>;
+
+/**
+ * Device attestation token returned by the `getDeviceAttestationToken` command.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/channelstore | getDeviceAttestationToken Command}
+ */
+export interface IDeviceAttestationToken {
+    /** Request status; 0 indicates success. */
+    status: number;
+    /** The nonce used to generate the token. */
+    nonce: string;
+    /** Signed JWT for device attestation verification. */
+    token: string;
+}
+
+export type EventHandlerDeviceAttestationToken = EventHandler<IDeviceAttestationToken>;
+
+/**
+ * Properties for the ChannelStore component.
+ *
+ * The ChannelStore component provides an interface to the Roku Streaming Store, enabling in-app purchases,
+ * user authentication, and data retrieval. It supports commands for fetching user data, managing orders,
+ * retrieving catalogs, and handling credentials. This component wraps the `<channelStoreExt>` XML element
+ * and exposes its fields as TypeScript props and event handlers.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/channelstore}
+ */
+export interface IChannelStoreProps {
+    id?: string;
+    /**
+     * Specifies the command to be executed (e.g., "getUserData", "getCatalog").
+     * @see {@link https://developer.roku.com/dev/docs/channelstore | ChannelStore Commands}
+     */
+    command?: ChannelStoreCommand;
+    /**
+     * Specifies the Roku customer account fields to be retrieved when the `getUserData` command
+     * is executed. Set to "all" for all available fields, or a comma-separated list of specific
+     * fields (e.g., "email,firstname,lastname").
+     * @default "all"
+     * @see {@link https://developer.roku.com/dev/docs/channelstore | requestedUserData Field}
+     */
+    requestedUserData?: string;
+    /**
+     * Configures whether the RFI screen is used for sign-ups or sign-ins.
+     * @see {@link https://developer.roku.com/dev/docs/channelstore | requestedUserDataInfo Field}
+     */
+    requestedUserDataInfoObject?: IRequestedUserDataInfo;
+    /**
+     * Fired when user data is retrieved from the `getUserData` command. Returns `invalid`
+     * if the user clicked Cancel on the RFI screen.
+     * @see {@link https://developer.roku.com/dev/docs/channelstore | userData Field}
+     */
+    onUserDataObject?: EventHandlerUserData;
+    /**
+     * Fired when user region data is retrieved from the `getUserRegionData` command.
+     * @see {@link https://developer.roku.com/dev/docs/channelstore | getUserRegionData Command}
+     */
+    onUserRegionDataObject?: EventHandlerUserRegionData;
+    /**
+     * Custom request object for advanced ChannelStore operations.
+     */
+    request?: IChannelStoreRequest;
+    /**
+     * Fired when a custom request completes.
+     */
+    onRequestStatus?: EventHandler<IChannelStoreRequestStatusEvent>;
+    /**
+     * Data to be stored securely for channel credentials via the `storeChannelCredData` command.
+     * @see {@link https://developer.roku.com/dev/docs/channelstore | channelCredData Field}
+     */
+    channelCredData?: string;
+    /**
+     * Fired when storing channel credential data completes.
+     * @see {@link https://developer.roku.com/dev/docs/channelstore | storeChannelCredData Command}
+     */
+    onStoreChannelCredDataStatusObject?: EventHandlerStoreChannelCredDataStatus;
+    /**
+     * Fired when channel credentials are retrieved via the `getChannelCred` command.
+     * @see {@link https://developer.roku.com/dev/docs/channelstore | getChannelCred Command}
+     */
+    onChannelCredObject?: EventHandlerChannelCred;
+    /**
+     * Fired when the catalog is retrieved from the `getCatalog` command.
+     * @see {@link https://developer.roku.com/dev/docs/channelstore | catalog Field}
+     */
+    onCatalogObject?: EventHandlerCatalog;
+    /**
+     * Contains the order to be filled when the `doOrder` command is executed.
+     * @see {@link https://developer.roku.com/dev/docs/channelstore | order Field}
+     */
+    orderObject?: IOrderItem[];
+    /**
+     * Enables incremental population of the order field. Each time this is set,
+     * the order is modified (use negative `qty` to remove items).
+     * @see {@link https://developer.roku.com/dev/docs/channelstore | deltaOrder Field}
+     */
+    deltaOrder?: IOrderItem;
+    /**
+     * Fired when the `doOrder` command completes with completion status.
+     * @see {@link https://developer.roku.com/dev/docs/channelstore | orderStatus Field}
+     */
+    onOrderStatusObject?: EventHandlerOrderStatus;
+    /**
+     * Fired when order items are processed (child nodes of orderStatus).
+     * @see {@link https://developer.roku.com/dev/docs/channelstore | doOrder Command}
+     */
+    onOrderItemsStatusObject?: EventHandlerOrderItemsStatus;
+    /**
+     * Fired when purchases are retrieved from `getPurchases` or `getAllPurchases` commands
+     * (completion status).
+     *
+     * Receives the command's status, not the purchase data: the backing field
+     * `purchasesStatusObject` is an `assocarray` holding the request node's own fields, and is
+     * `{}` when the request failed. The purchases themselves arrive on
+     * {@link IChannelStoreProps.onPurchasesObject}.
+     * @see {@link https://developer.roku.com/dev/docs/channelstore | purchases Field}
+     */
+    onPurchasesStatusObject?: EventHandlerPurchasesStatus;
+    /**
+     * Fired when purchase data is available from `getPurchases` or `getAllPurchases` commands.
+     * @see {@link https://developer.roku.com/dev/docs/channelstore | purchases Field}
+     */
+    onPurchasesObject?: EventHandlerPurchases;
+    /**
+     * Specifies the product to be ordered from a TVOD app.
+     * @see {@link https://developer.roku.com/dev/docs/channelstore | requestPartnerOrder Field}
+     */
+    requestPartnerOrderObject?: IPartnerOrder;
+    /**
+     * Fired when requesting a partner order completes.
+     * @see {@link https://developer.roku.com/dev/docs/channelstore | requestPartnerOrderStatus Field}
+     */
+    onRequestPartnerOrderStatusObject?: EventHandlerPartnerOrder;
+    /**
+     * Confirms the product being ordered from a TVOD app.
+     * @see {@link https://developer.roku.com/dev/docs/channelstore | confirmPartnerOrder Field}
+     */
+    confirmPartnerOrderObject?: IPartnerOrder;
+    /**
+     * Fired when confirming a partner order completes.
+     * @see {@link https://developer.roku.com/dev/docs/channelstore | confirmPartnerOrderStatus Field}
+     */
+    onConfirmPartnerOrderStatusObject?: EventHandlerPartnerOrder;
+    /**
+     * Fired when a device attestation token is generated via `getDeviceAttestationToken`.
+     * @see {@link https://developer.roku.com/dev/docs/channelstore | getDeviceAttestationToken Command}
+     */
+    onDeviceAttestationTokenObject?: EventHandlerDeviceAttestationToken;
+}

package/src/channel-store.tsx

@@ -0,0 +1,76 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+// TODO: This component uses a custom XML extension (channelStoreExt) rather than a
+// native SG node, so it lives in src/ alongside other custom components (like modal-dialog)
+// instead of in sg-nodes/.
+
+import type { IChannelStoreProps } from "./channel-store.props";
+import { retainAsset } from "./retain-asset";
+import { Component } from "./sg-nodes/types";
+import ChannelStoreXML from "./xml-components/channel-store/channelStoreExt.xml";
+export type { IChannelStoreRequestStatusEvent } from "./channel-store.props";
+
+export type {
+    ChannelStoreCommand,
+    ChannelStoreUserDataContext,
+    IChannelStoreRequest,
+    IUserData,
+    EventHandlerUserData,
+    IUserRegionData,
+    EventHandlerUserRegionData,
+    IRequestedUserDataInfo,
+    IStoreChannelCredDataStatus,
+    EventHandlerStoreChannelCredDataStatus,
+    IChannelCred,
+    EventHandlerChannelCred,
+    IProduct,
+    EventHandlerCatalog,
+    IOrderItem,
+    IOrderStatus,
+    EventHandlerOrderStatus,
+    EventHandlerOrderItemsStatus,
+    IPurchasesStatus,
+    EventHandlerPurchasesStatus,
+    IPurchase,
+    EventHandlerPurchases,
+    IPartnerOrder,
+    EventHandlerPartnerOrder,
+    IDeviceAttestationToken,
+    EventHandlerDeviceAttestationToken,
+    IChannelStoreProps
+} from "./channel-store.props";
+
+/**
+ * ChannelStore provides an interface to the Roku Streaming Store for in-app purchases,
+ * user authentication, subscription management, and credential storage.
+ *
+ * Usage follows a command pattern: set required data fields, observe the result event,
+ * then set `command` to trigger execution. Results arrive asynchronously via event handlers.
+ *
+ * @example
+ * ```tsx
+ * // Retrieve user data for sign-in
+ * <ChannelStore
+ *     requestedUserData="email,firstname,lastname"
+ *     command="getUserData"
+ *     onUserDataObject={(data) => console.log("User data:", data)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Perform an in-app purchase
+ * <ChannelStore
+ *     orderObject={[{ code: "item1", qty: 1 }]}
+ *     command="doOrder"
+ *     onOrderStatusObject={(status) => console.log("Order status:", status)}
+ * />
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/channelstore}
+ */
+export const ChannelStore: Component<IChannelStoreProps> = props => {
+    retainAsset(ChannelStoreXML);
+    return <channelStoreExt {...props}></channelStoreExt>;
+};