@roku-sdk/components 0.0.0-stage → 2.19.0

package/src/sg-nodes/time-grid.tsx

@@ -0,0 +1,87 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { ITimeGridProps } from "./time-grid.props";
+import { Component } from "./types";
+export type {
+    TimeGridItemPosition,
+    TimeGridItemEventHandler,
+    ITimeGridGeneralProps,
+    ITimeGridChannelProps,
+    ITimeGridChannelInfoProps,
+    ITimeGridProgramFocusedDetails,
+    ITimeGridProgramGridProps,
+    ITimeGridPastTimeScreenProps,
+    ITimeGridTimeBarProps,
+    ITimeGridNowBarProps,
+    ITimeGridNowNextModeProps,
+    ITimeGridProps
+} from "./time-grid.props";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TimeGrid Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TimeGrid Sub-Interface: General Settings
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TimeGrid Sub-Interface: Channel Navigation / Focus / Selection
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TimeGrid Sub-Interface: Channel Information Column
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TimeGrid Sub-Interface: Program Grid
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TimeGrid Sub-Interface: Past Time Screen
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TimeGrid Sub-Interface: Time Bar
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TimeGrid Sub-Interface: Now Bar
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TimeGrid Sub-Interface: Now/Next Mode
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TimeGrid Composed Properties
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * TimeGrid is an EPG (Electronic Program Guide) component that displays a
+ * scrollable, time-based grid of TV channels and their programs.
+ *
+ * Each row represents a channel with a customizable info column on the left.
+ * Programs are laid out horizontally according to their `playStart` and
+ * `playDuration` content metadata. A time bar and optional "now" indicator
+ * provide temporal context.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/timegrid}
+ *
+ * @example
+ * ```tsx
+ * <timeGrid
+ *     numRows={7}
+ *     duration={7200}
+ *     contentStartTime={startTime}
+ *     leftEdgeTargetTime={now}
+ *     channelInfoComponentName={channelItem}
+ *     content={epgContent}
+ *     onProgramSelected={(index) => handleSelection(index)}
+ * />
+ * ```
+ */
+export const TimeGrid: Component<ITimeGridProps> = props => {
+    return <timeGrid {...props}></timeGrid>;
+};

package/src/sg-nodes/tween.props.ts

@@ -0,0 +1,115 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { DomNode } from "@roku-sdk/interfaces";
+
+import type { AnimationControl, AnimationState, EaseFunction } from "./animation.props";
+import type { INodeProps } from "./node";
+import type { Vector2D } from "./types";
+
+/**
+ * Properties for the Tween node — the unified declarative animation primitive.
+ *
+ * A `<tween>` animates a single field on a target node. On Roku it is a native node, which
+ * supersedes the earlier BrightScript/XML tween components and takes the interpreter out of the
+ * animation hot path. Application source writes `<tween>` and gets render-thread animation without
+ * branching on where it runs.
+ *
+ * The portable subset of the fields below — the properties every renderer honours, and the ones
+ * portable code may rely on — is frozen as {@link ITweenCoreProps} in `core-props.ts`. This
+ * interface is the full SceneGraph surface and is a superset of that base.
+ *
+ * @example
+ * // Slide a node to x=480 over the default duration
+ * <tween targetNode={ref} field="translation" targetVector={[480, 0]} />
+ */
+export interface ITweenProps extends INodeProps {
+    /**
+     * The node whose field is animated. If you render `<tween>` directly, clear `targetNode`
+     * before removing it: a shim removed while idle or paused otherwise leaves its Animation in the
+     * parent. The `Tween` wrapper does this for you.
+     */
+    targetNode?: DomNode;
+
+    /**
+     * Field on {@link targetNode} to animate.
+     * @default "translation"
+     */
+    field?: string;
+
+    /**
+     * Float target. Writing it starts the animation. A scalar written against a vector2d field
+     * auto-expands to `[v, v]` on `axis="all"`; documented sugar for a uniform scale, not the
+     * canonical form. There is no separate Y target, so use {@link targetVector} for an
+     * `[x, y]` move; a vector target on a vector field is the plain way to say "all".
+     * @see [Tween value-shape contract](../../../../documentation/core-concepts/tween.md)
+     */
+    targetValue?: number;
+
+    /**
+     * Vector2d target `[x, y]`. Writing it starts the animation.
+     *
+     * @see [Tween value-shape contract](../../../../documentation/core-concepts/tween.md)
+     */
+    targetVector?: [number, number];
+
+    /**
+     * Duration in seconds. `0` is an instant snap with no animation artifacts.
+     * @default 0.333
+     */
+    duration?: number;
+
+    /**
+     * Named easing function.
+     * @default "linear"
+     */
+    easeFunction?: EaseFunction;
+
+    /**
+     * For vector fields, which axis to animate. `"x"` and `"y"` animate one component and hold
+     * the other at {@link preserveOther} to avoid stale mid-flight reads; `"all"` animates the
+     * whole vector.
+     *
+     * @default "all"
+     * @see [Tween value-shape contract](../../../../documentation/core-concepts/tween.md)
+     */
+    axis?: "x" | "y" | "all";
+
+    /** Value held on the non-animated axis for single-axis vector animation. */
+    preserveOther?: number;
+
+    /**
+     * Candidate snap positions for velocity-preserving settle. Empty means no settle.
+     * Float fields and single-axis vector motion take scalar candidates; whole-vector motion
+     * takes `[x, y]` pairs. Wrong-shaped entries are skipped and logged, and reported indices
+     * refer to the original list. A list with no usable candidates does not settle.
+     * @see [Tween value-shape contract](../../../../documentation/core-concepts/tween.md)
+     */
+    proposedStops?: number[] | [number, number][];
+
+    /** Optional explicit playback control (`start`/`stop`/`pause`/`resume`/`finish`). */
+    control?: AnimationControl;
+
+    /** Output: `[second, millisecond]` render-thread timestamp at animation start. */
+    onAnimationStart?: (t: [second: number, millisecond: number]) => void;
+
+    /**
+     * Output: `[index, position, [second, millisecond]]` after a settle re-arm — which
+     * `proposedStops` candidate was chosen, the coordinate it settles to, and the render-thread
+     * timestamp the settle is expected to finish at. On a vector field `position` is a scalar:
+     * the owned coordinate under `"x"`/`"y"`, and under `"all"` the coordinate of the chosen
+     * point that travels further. Read the full point from `proposedStops[index]`.
+     *
+     * Note this is NOT the plain `<animation>` node's `[second, millisecond]` stop timestamp.
+     * A tween's stop event is only interesting for what it settled on, so the chosen index and
+     * position lead and the timestamp is nested last.
+     */
+    onAnimationStop?: (t: [index: number, position: number, stopTime: [second: number, millisecond: number]]) => void;
+
+    /**
+     * Output: `[state, value]` on each animation state transition, where `value` is the target
+     * field's current value: a `number` for a float field, a `Vector2D` (`[x, y]`) for a vector2d field such as
+     * the default `translation`. Delivered as one array, like the other outputs.
+     */
+    onAnimationState?: (t: [state: AnimationState, value: number | Vector2D]) => void;
+}

package/src/sg-nodes/types.ts

@@ -0,0 +1,150 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { Component, JSX } from "@roku-sdk/solid";
+import { children, mergeProps, splitProps } from "@roku-sdk/solid"; // NOTE: update this if we switch to different framework
+
+export type ResObject<T> = { hd: T; fhd: T };
+export type ResType<T> = T | ResObject<T>;
+export type IsResObjType = <T>(value: ResType<T> | undefined) => value is ResObject<T>;
+/**
+ * URI type for referencing resources in Roku SceneGraph.
+ * Can be a simple string or resolution-specific object with separate URIs for HD and FHD.
+ *
+ * Supported URI schemes:
+ * - `pkg:/`: Package resources (files within the application package)
+ * - `http://` or `https://`: Remote resources loaded from the internet
+ * - `theme:`: Theme-specific resources
+ *
+ * URIs can also be imported from TypeScript using the image import plugin, which automatically
+ * generates resolution-specific URIs and copies assets to the build output.
+ *
+ * @example
+ * // Simple string URI
+ * uri="pkg:/images/icon.png"
+ *
+ * @example
+ * // Resolution-specific URIs
+ * uri={{ hd: "pkg:/images/icon-hd.png", fhd: "pkg:/images/icon-fhd.png" }}
+ *
+ * @example
+ * // TypeScript import (generates resolution-specific URIs automatically)
+ * import { uri as logo } from "./images/roku-logo-*.png";
+ * <Poster uri={logo} />
+ */
+export type Uri = ResType<string>;
+
+export type Vector2D = [number, number];
+export type Rect2D = [number, number, number, number];
+export type HorizAlign = "left" | "center" | "right";
+export type VertAlign = "top" | "center" | "bottom";
+export type LayoutGroupHorizAlign = HorizAlign | "custom";
+export type LayoutGroupVertAlign = VertAlign | "custom";
+export type LayoutDirection = "vert" | "horiz";
+export type VideoMode = "hd" | "fhd";
+
+/**
+ * System font names available in RokuOS.
+ *
+ * System fonts are built-in fonts provided by the Roku platform that automatically
+ * adapt to the user's language and accessibility settings. They are referenced using
+ * the `font:` URI scheme and are case-sensitive.
+ *
+ * **Why use system fonts?**
+ * - Consistent appearance across all Roku devices
+ * - Automatic localization support for international characters
+ * - Respect user accessibility preferences (e.g., larger text settings)
+ * - No need to bundle font files in your application package
+ *
+ * @example
+ * // Using with Label component
+ * <Label text="Hello World" font={SystemFont.Medium} />
+ *
+ * @example
+ * // Using with custom font string for specific size
+ * <Label text="Custom" font="font:MediumSystemFont" />
+ */
+export enum SystemFont {
+    // ─────────────────────────────────────────────────────────────────────────
+    // Regular fonts (standard weight, size-based)
+    // ─────────────────────────────────────────────────────────────────────────
+    Largest = "font:LargestSystemFont",
+    UltraLarge = "font:UltraLargeSystemFont",
+    ExtraLarge = "font:ExtraLargeSystemFont",
+    Large = "font:LargeSystemFont",
+    Medium = "font:MediumSystemFont",
+    Small = "font:SmallSystemFont",
+    Smaller = "font:SmallerSystemFont",
+    Smallest = "font:SmallestSystemFont",
+    Tiny = "font:TinySystemFont",
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Bold fonts (bold weight, size-based)
+    // ─────────────────────────────────────────────────────────────────────────
+    UltraLargeBold = "font:UltraLargeBoldSystemFont",
+    ExtraLargeBold = "font:ExtraLargeBoldSystemFont",
+    LargeBold = "font:LargeBoldSystemFont",
+    MediumBold = "font:MediumBoldSystemFont",
+    SmallBold = "font:SmallBoldSystemFont",
+    SmallerBold = "font:SmallerBoldSystemFont",
+    SmallestBold = "font:SmallestBoldSystemFont",
+    TinyBold = "font:TinyBoldSystemFont",
+    /** Use for badge/pill UI elements (e.g., "NEW", "HD") */
+    Badge = "font:BadgeSystemFont",
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Semantic fonts for specific UI elements
+    // ─────────────────────────────────────────────────────────────────────────
+    /** Default font for label components */
+    DefaultLabel = "font:DefaultLabelFont",
+    /** Use for header/title text in sections */
+    Header = "font:HeaderFont",
+    /** Use for EPG (Electronic Program Guide) title text */
+    EPGInfoTitle = "font:EPGInfoTitleFont",
+    /** Use for overhang/top navigation titles */
+    OverhangTitle = "font:OverhangTitleFont",
+    /** Use for poster labels in settings screens */
+    SettingsPosterLabel = "font:SettingsPosterLabelFont",
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // OSD (On-Screen Display) fonts
+    // ─────────────────────────────────────────────────────────────────────────
+    /** Use for on-screen display buttons */
+    OSDButton = "font:OSDButtonFont",
+    /** Use for focused on-screen display buttons */
+    OSDFocusedButton = "font:OSDFocusedButtonFont",
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Specialized/system-specific fonts
+    // ─────────────────────────────────────────────────────────────────────────
+    /** Use for link panel player number display */
+    LinkPanelPlayerNumber = "font:LinkPanelPlayerNumberFont",
+    /** Use for TV input status indicators */
+    TvInputStatus = "font:TvInputStatusFont",
+    /** Use for relink screen headers */
+    RelinkHeader = "font:RelinkHeaderFont",
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Caption and accessibility fonts
+    // ─────────────────────────────────────────────────────────────────────────
+    /** Use for video captions/subtitles */
+    Caption = "font:CaptionFont",
+    /** Use for closed captioning (accessibility) */
+    ClosedCaption = "font:ClosedCaptionFont",
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Theme font
+    // ─────────────────────────────────────────────────────────────────────────
+    /** Theme-defined font that respects channel theming settings */
+    Theme = "font:ThemeFont"
+}
+
+/**
+ * Font value type that accepts system fonts or custom font strings.
+ * Use this for properties that accept a font specification.
+ */
+export type FontValue = SystemFont | `font:${string}` | JSX.Element;
+
+export { children, Component, JSX, mergeProps, splitProps };
+
+export type EventHandler<T> = (event: T) => void;