@roku-sdk/components 0.0.0-stage → 2.19.0

package/src/focusable-group.tsx

@@ -0,0 +1,17 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IFocusableGroupProps } from "./focusable-group.props";
+import { Component } from "./index";
+import { retainAsset } from "./retain-asset";
+import FocusableGroupXML from "./xml-components/focus/focusable-group.xml";
+export type { IFocusableGroupProps } from "./focusable-group.props";
+
+export const FocusableGroup: Component<IFocusableGroupProps> = props => {
+    retainAsset(FocusableGroupXML);
+    return (
+        <focusable-group focusable={true} {...props}>
+            {props.children}
+        </focusable-group>
+    );
+};

package/src/focusable.props.ts

@@ -0,0 +1,14 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./sg-nodes/group.props";
+
+export interface IFocusableProps extends IGroupProps {
+    nextFocusRight?: string;
+    nextFocusLeft?: string;
+    nextFocusUp?: string;
+    nextFocusDown?: string;
+    nextFocusBack?: string;
+    nextFocusOk?: string;
+    hasPreferredFocus?: boolean;
+}

package/src/focusable.tsx

@@ -0,0 +1,17 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IFocusableProps } from "./focusable.props";
+import { retainAsset } from "./retain-asset";
+import { Component } from "./types";
+import FocusableXML from "./xml-components/focus/focusable.xml";
+export type { IFocusableProps } from "./focusable.props";
+
+export const Focusable: Component<IFocusableProps> = props => {
+    retainAsset(FocusableXML);
+    return (
+        <focusable focusable={true} {...props}>
+            {props.children}
+        </focusable>
+    );
+};

package/src/glyphs.ts

@@ -0,0 +1,116 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+/**
+ * Named character constants for symbols that are awkward or impossible to type
+ * directly in source.
+ *
+ * The constants are grouped by the property that actually matters at runtime:
+ * which font has to supply the character.
+ *
+ * 1. RokuFont01 characters (the private-use area, plus ● ★ ☆). RokuFont01 is
+ *    the system-wide fallback font in firmware, so these render under a system
+ *    font AND under a custom app-supplied font.
+ * 2. RokuUI-Regular symbols. RokuUI-Regular is the default UI font but is not
+ *    in the fallback chain, so these render under a system font but become tofu
+ *    under a custom app-supplied font unless that font supplies them itself.
+ *
+ * The practical consequence, verified on device against firmware 15.3.5: if
+ * your app ships a custom font, the group that needs care is (2), not (1).
+ *
+ * A custom font that defines a codepoint itself always wins — no fallback
+ * occurs. A font carrying its own U+E0xx private-use glyphs will render those
+ * rather than the Roku icons.
+ *
+ * @packageDocumentation
+ */
+
+// -----------------------------------------------------------------------------
+// RokuFont01 — private-use area glyphs
+//
+// Supplied by the firmware fallback font, so these survive a custom app font.
+// -----------------------------------------------------------------------------
+
+export const OPTIONS_GLYPH = "\uE000";
+export const OK_BUTTON_GLYPH = "\uE001";
+export const OPTIONS_BUTTON_GLYPH = "\uE002";
+export const MICROPHONE_GLYPH = "\uE003";
+export const PLAY_PAUSE_BUTTON_GLYPH = "\uE004";
+export const PLAY_PAUSE_GLYPH = "\uE005";
+/**
+ * Baseline-aligned dot, sized and positioned to line up with the other icon
+ * glyphs in this block. Use {@link BLACK_CIRCLE} for a dot inside a run of
+ * text — that one is raised to text centre.
+ */
+export const DOT_GLYPH = "\uE006";
+export const HOME_GLYPH = "\uE007";
+export const SEARCH_GLYPH = "\uE008";
+export const REMOTE_GLYPH = "\uE009";
+export const REPLAY_GLYPH = "\uE010";
+export const MICROPHONE_BUTTON_GLYPH = "\uE011";
+export const SEARCH_BUTTON_GLYPH = "\uE012";
+export const FAST_FORWARD_GLYPH = "\uE013";
+export const REWIND_GLYPH = "\uE014";
+export const SHORTCUT_ONE_BUTTON_GLYPH = "\uE015";
+export const SHORTCUT_TWO_BUTTON_GLYPH = "\uE016";
+export const CLOSED_CAPTIONS_GLYPH = "\uE017";
+export const LIVE_TV_GLYPH = "\uE018";
+export const SLEEP_TIMER_GLYPH = "\uE019";
+export const GENERAL_APP_GLYPH = "\uE020";
+export const BACK_BUTTON_GLYPH = "\uE021";
+export const HOME_BUTTON_GLYPH = "\uE022";
+export const QUICK_LAUNCH_BUTTON_GLYPH = "\uE023";
+export const DOWN_BUTTON_GLYPH = "\uE024";
+export const LEFT_BUTTON_GLYPH = "\uE025";
+export const RIGHT_BUTTON_GLYPH = "\uE026";
+export const KIDS_PROFILE_GLYPH = "\uE027";
+export const UP_BUTTON_GLYPH = "\uE028";
+export const POWER_BUTTON_GLYPH = "\uE029";
+export const THUMBS_UP_GLYPH = "\uE030";
+export const THUMBS_DOWN_GLYPH = "\uE031";
+
+// -----------------------------------------------------------------------------
+// RokuFont01 — standard Unicode symbols
+//
+// These are real Unicode codepoints, but RokuUI-Regular does not contain them:
+// they resolve through the RokuFont01 fallback, exactly like the private-use
+// glyphs above. That fallback applies under a custom app font too, so these are
+// the safe shapes to use in custom-font text.
+// -----------------------------------------------------------------------------
+
+/** ● U+25CF BLACK CIRCLE — raised to text centre, for a dot inside a text run. */
+export const BLACK_CIRCLE = "\u25CF";
+/** ★ U+2605 BLACK STAR — filled star, e.g. a filled rating position. */
+export const BLACK_STAR = "\u2605";
+/** ☆ U+2606 WHITE STAR — outlined star, e.g. an empty rating position. */
+export const WHITE_STAR = "\u2606";
+
+// -----------------------------------------------------------------------------
+// RokuUI-Regular symbols
+//
+// Present in the default UI font, so no fallback is needed under a system font.
+// Under a custom app font there is no RokuFont01 backstop for these either — a
+// custom font that lacks them renders tofu. These are the constants to watch if
+// your app ships its own font.
+// -----------------------------------------------------------------------------
+
+/** • U+2022 BULLET */
+export const BULLET = "\u2022";
+/** … U+2026 HORIZONTAL ELLIPSIS */
+export const ELLIPSIS = "\u2026";
+/** – U+2013 EN DASH */
+export const EN_DASH = "\u2013";
+/** — U+2014 EM DASH */
+export const EM_DASH = "\u2014";
+/** ← U+2190 LEFTWARDS ARROW */
+export const LEFT_ARROW = "\u2190";
+/** ↑ U+2191 UPWARDS ARROW */
+export const UP_ARROW = "\u2191";
+/** → U+2192 RIGHTWARDS ARROW */
+export const RIGHT_ARROW = "\u2192";
+/** ↓ U+2193 DOWNWARDS ARROW */
+export const DOWN_ARROW = "\u2193";
+/** ✓ U+2713 CHECK MARK */
+export const CHECK_MARK = "\u2713";
+/** ✗ U+2717 BALLOT X */
+export const BALLOT_X = "\u2717";

package/src/helpers/index.tsx

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+export * from "./resolution-context";
+export * from "./scale-for-device-resolution";

package/src/helpers/resolution-context.tsx

@@ -0,0 +1,68 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+import { getAppInfo } from "@roku-sdk/runtime/app-info";
+import { useUiResolution } from "@roku-sdk/runtime/device-info-events";
+import type { Component, JSX } from "@roku-sdk/solid";
+import { createContext, createEffect, createSignal, useContext } from "@roku-sdk/solid";
+
+export enum Resolution {
+    HD = "hd",
+    FHD = "fhd",
+    // eslint-disable-next-line @typescript-eslint/no-duplicate-enum-values
+    hd = "hd",
+    // eslint-disable-next-line @typescript-eslint/no-duplicate-enum-values
+    fhd = "fhd"
+}
+export enum ResolutionScale {
+    HD = 1,
+    FHD = 1.5,
+    // eslint-disable-next-line @typescript-eslint/no-duplicate-enum-values
+    hd = 1,
+    // eslint-disable-next-line @typescript-eslint/no-duplicate-enum-values
+    fhd = 1.5
+}
+interface ResolutionContextValue {
+    isFHDOnly: boolean;
+    deviceResolution: () => Resolution | undefined;
+}
+
+export interface IResolutionContextProviderProps {
+    children: JSX.Element;
+}
+
+const ResolutionContext = createContext<ResolutionContextValue>();
+
+export const ResolutionProvider: Component<IResolutionContextProviderProps> = props => {
+    const appInfo = getAppInfo();
+    const resolutions = appInfo?.getManifestValue("ui_resolutions")?.split(",");
+    const isFHDOnly = resolutions?.includes("fhd") && !resolutions?.includes("hd");
+    const { uiResolution } = useUiResolution();
+
+    const [deviceResolution, setDeviceResolution] = createSignal<Resolution>();
+
+    createEffect(() => {
+        const resolution = uiResolution();
+
+        if (resolution && !deviceResolution()) {
+            setDeviceResolution(resolution.name.toLowerCase() as Resolution);
+        }
+    });
+
+    const value: ResolutionContextValue = {
+        isFHDOnly: isFHDOnly === undefined ? true : isFHDOnly,
+        deviceResolution
+    };
+
+    return <ResolutionContext.Provider value={value}>{props.children}</ResolutionContext.Provider>;
+};
+
+export function useResolutionContext() {
+    const context = useContext(ResolutionContext);
+    if (!context) {
+        return {
+            isFHDOnly: true,
+            deviceResolution: () => Resolution.FHD
+        } as ResolutionContextValue;
+    }
+    return context;
+}

package/src/helpers/scale-for-device-resolution.ts

@@ -0,0 +1,31 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+import { Accessor, createMemo } from "@roku-sdk/solid";
+
+import { Vector2D } from "../sg-nodes/types";
+import { useResolutionContext } from "./resolution-context";
+
+const scale = (value: number) => Math.floor((value * 2) / 3);
+
+/**
+ * Workaround to scale the size based on the device resolution.
+ * Used to fix the lack of autoscaling when the device resolution is not FHD.
+ * Resolution-related properties of some SceneGraph nodes do not autoscale
+ * when the resolution is not FHD, even when autoscaling is enabled
+ * (manifest has FHD resolution only).
+ *
+ * @important This workaround works only under ResolutionProvider.
+ *
+ * @param size - The size accessor to apply the workaround to.
+ * @returns The autoscaled size accessor.
+ */
+export const scaleForDeviceResolution = (size: Accessor<Vector2D>): Accessor<Vector2D> => {
+    const { deviceResolution } = useResolutionContext();
+    return createMemo<Vector2D>(() => {
+        const [width, height] = size();
+        if (deviceResolution() === "hd") {
+            return [scale(width), scale(height)];
+        }
+        return [width, height];
+    });
+};

package/src/index.tsx

@@ -0,0 +1,70 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+export * from "./sg-nodes/animation";
+export * from "./sg-nodes/animated-image";
+export * from "./sg-nodes/array-grid";
+export * from "./bounding-tracker";
+export * from "./blended-busy-spinner";
+export { BusySpinner } from "./sg-nodes/busy-spinner";
+export * from "./sg-nodes/button";
+export * from "./sg-nodes/button-group";
+export * from "./channel-store";
+export * from "./container";
+export * from "./sg-nodes/content-node";
+export * from "./sg-nodes/custom-keyboard";
+export * from "./sg-nodes/dialog";
+export * from "./sg-nodes/dynamic-key-grid";
+export * from "./sg-nodes/dynamic-keyboard";
+export * from "./sg-nodes/dynamic-mini-keyboard";
+export * from "./sg-nodes/dynamic-pinpad";
+export * from "./sg-nodes/effect";
+export * from "./focusable";
+export * from "./focusable-group";
+export * from "./sg-nodes/font";
+export * from "./sg-nodes/group";
+export * from "./key-handler";
+export * from "./sg-nodes/label";
+export * from "./sg-nodes/label-list";
+export * from "./sg-nodes/check-list";
+export * from "./sg-nodes/layout-group";
+export * from "./sg-nodes/list-panel";
+export * from "./sg-nodes/markup-list";
+export * from "./sg-nodes/mask-group";
+// Implementation lives in @roku-sdk/navigation. Re-exported here so
+// existing `import { ModalBoundary, useModal } from "@roku-sdk/components"` keeps working.
+export { ModalBoundary, type IModalBoundaryProps, useModal, type UseModalResult } from "@roku-sdk/navigation";
+export * from "./sg-nodes/node";
+export * from "./sg-nodes/overhang";
+export * from "./sg-nodes/panel";
+export * from "./sg-nodes/panel-set";
+export * from "./sg-nodes/poster";
+export * from "./sg-nodes/poster-grid";
+export * from "./sg-nodes/radio-button-list";
+export * from "./sg-nodes/rectangle";
+export * from "./sg-nodes/row-list";
+export * from "./sg-nodes/time-grid";
+export * from "./sg-nodes/zoom-row-list";
+export * from "./sg-nodes/scene";
+export * from "./sg-nodes/scrolling-label";
+export * from "./sg-nodes/scrollable-text";
+export * from "./sg-nodes/simple-label";
+export * from "./sg-nodes/standard-dialog";
+export * from "./sg-nodes/standard-message-dialog";
+export * from "./sg-nodes/standard-keyboard-dialog";
+export * from "./sg-nodes/standard-pinpad-dialog";
+export * from "./sg-nodes/standard-progress-dialog";
+export * from "./sg-nodes/target-set";
+export * from "./sg-nodes/target-group";
+export * from "./sg-nodes/target-list";
+export * from "./types";
+export * from "./sg-nodes/video";
+export * from "./sg-nodes/voice-text-edit-box";
+export * from "./sg-nodes/audio";
+export * from "./sg-nodes/sound-effect";
+export * from "./button-row";
+export * from "./sg-nodes/markup-grid";
+
+export { Tween } from "./tween";
+export type { TweenProps } from "./tween";
+export type { ITweenProps } from "./sg-nodes/tween.props";

package/src/jsx-props.ts

@@ -0,0 +1,87 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+// Types-only barrel for JSX intrinsic augmentations. Imported by jsx.d.ts / sg-jsx.d.ts.
+// Do not re-export from .tsx modules — that reintroduces consumer tsc circular errors.
+
+export type { IBlendedBusySpinnerProps } from "./blended-busy-spinner.props";
+export type { IBoundingTrackerProps } from "./bounding-tracker.props";
+export type { IChannelStoreProps } from "./channel-store.props";
+export type { IFocusableGroupProps } from "./focusable-group.props";
+export type { IFocusableProps } from "./focusable.props";
+export type { IKeyHandlerProps } from "./key-handler.props";
+export type { IModalProps } from "./modal-dialog.props";
+export type {
+    IAnimationBaseProps,
+    IAnimationProps,
+    IColorFieldInterpolatorProps,
+    IFloatFieldInterpolatorProps,
+    IVector2DFieldInterpolatorProps
+} from "./sg-nodes/animation.props";
+export type { IAnimatedImageProps } from "./sg-nodes/animated-image.props";
+export type { IAudioProps } from "./sg-nodes/audio.props";
+export type { IBusySpinnerProps } from "./sg-nodes/busy-spinner.props";
+export type { IButtonGroupProps } from "./sg-nodes/button-group.props";
+export type { IButtonProps } from "./sg-nodes/button.props";
+export type { ICheckListProps } from "./sg-nodes/check-list.props";
+export type { IContentNodeProps } from "./sg-nodes/content-node.props";
+export type { IKeyboardPropsWithVoice } from "./sg-nodes/custom-keyboard.props";
+export type { IDialogProps } from "./sg-nodes/dialog.props";
+export type { IDynamicKeyGridProps } from "./sg-nodes/dynamic-key-grid.props";
+export type { IDynamicKeyboardProps } from "./sg-nodes/dynamic-keyboard.props";
+export type { IDynamicMiniKeyboardProps } from "./sg-nodes/dynamic-mini-keyboard.props";
+export type { IDynamicPinPadProps } from "./sg-nodes/dynamic-pinpad.props";
+export type { IEffectProps } from "./sg-nodes/effect.props";
+export type { IFontProps } from "./sg-nodes/font.props";
+export type { IGroupProps } from "./sg-nodes/group.props";
+export type { ILabelListProps } from "./sg-nodes/label-list.props";
+export type { ILabelProps, IMultiStyleLabelProps } from "./sg-nodes/label.props";
+export type { ILayoutGroupProps } from "./sg-nodes/layout-group.props";
+export type { IFullPanelProps, IListPanelProps } from "./sg-nodes/list-panel.props";
+export type { IMarkupGridProps } from "./sg-nodes/markup-grid.props";
+export type { IMarkupListProps } from "./sg-nodes/markup-list.props";
+export type { IMaskGroupProps } from "./sg-nodes/mask-group.props";
+export type { IOverhangProps } from "./sg-nodes/overhang.props";
+export type { IPanelSetProps } from "./sg-nodes/panel-set.props";
+export type { IPanelProps } from "./sg-nodes/panel.props";
+export type { IPosterGridProps } from "./sg-nodes/poster-grid.props";
+export type { IPosterProps } from "./sg-nodes/poster.props";
+export type { IRadioButtonListProps } from "./sg-nodes/radio-button-list.props";
+export type { IRectangleProps } from "./sg-nodes/rectangle.props";
+export type { IRowListProps } from "./sg-nodes/row-list.props";
+export type { ISceneProps } from "./sg-nodes/scene.props";
+export type { IScrollableTextProps } from "./sg-nodes/scrollable-text.props";
+export type { IScrollingLabelProps } from "./sg-nodes/scrolling-label.props";
+export type { ISimpleLabelProps } from "./sg-nodes/simple-label.props";
+export type { ISoundEffectProps } from "./sg-nodes/sound-effect.props";
+export type {
+    IStandardDialogProps,
+    IStandardDialogRSGPaletteNodeProps,
+    IStdDlgActionCardItemProps,
+    IStdDlgBulletTextItemProps,
+    IStdDlgButtonAreaProps,
+    IStdDlgButtonProps,
+    IStdDlgContentAreaProps,
+    IStdDlgCustomItemProps,
+    IStdDlgDeterminateProgressItemProps,
+    IStdDlgGraphicItemProps,
+    IStdDlgItemGroupProps,
+    IStdDlgKeyboardItemProps,
+    IStdDlgMultiStyleTextItemProps,
+    IStdDlgProgressItemProps,
+    IStdDlgSideCardAreaProps,
+    IStdDlgTextItemProps,
+    IStdDlgTitleAreaProps
+} from "./sg-nodes/standard-dialog.props";
+export type { IStandardKeyboardDialogProps } from "./sg-nodes/standard-keyboard-dialog.props";
+export type { IStandardMessageDialogProps } from "./sg-nodes/standard-message-dialog.props";
+export type { IStandardPinPadDialogProps } from "./sg-nodes/standard-pinpad-dialog.props";
+export type { IStandardProgressDialogProps } from "./sg-nodes/standard-progress-dialog.props";
+export type { ITargetGroupProps } from "./sg-nodes/target-group.props";
+export type { ITargetListProps } from "./sg-nodes/target-list.props";
+export type { ITargetSetProps } from "./sg-nodes/target-set.props";
+export type { ITimeGridProps } from "./sg-nodes/time-grid.props";
+export type { ITweenProps } from "./sg-nodes/tween.props";
+export type { IBifDisplayProps, IProgressBarProps, ITrickPlayBarProps, IVideoProps } from "./sg-nodes/video.props";
+export type { IVoiceTextEditBoxProps } from "./sg-nodes/voice-text-edit-box.props";
+export type { IZoomRowListProps } from "./sg-nodes/zoom-row-list.props";

package/src/kdfs.d.ts

@@ -0,0 +1,14 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+/**
+ * Packaged Key Definition File URI exports (resolved to pkg:/components/... at build time).
+ *
+ * Keep this in sync with `kdfs.ts`: every export added there must be declared here.
+ */
+declare module "@roku-sdk/components/kdfs" {
+    export const CustomAddressKDF: string;
+    export const MOPPinPadCustomKDF: string;
+    export const PhonePadCustomKDF: string;
+    export const WifiCustomKDF: string;
+}

package/src/kdfs.ts

@@ -0,0 +1,15 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+/**
+ * Packaged Key Definition File URIs for standard keyboard layouts.
+ *
+ * Import only the layouts you use so unused KDF files tree-shake out of the build.
+ *
+ * When adding a new KDF export here, add a matching declaration to `kdfs.d.ts`
+ * (the published type surface for `@roku-sdk/components/kdfs`); the two must stay in sync.
+ */
+export { default as CustomAddressKDF } from "./xml-components/keyboards/CustomAddressKDF.keyboard.json";
+export { default as MOPPinPadCustomKDF } from "./xml-components/keyboards/MOPPinPadCustomKDF.keyboard.json";
+export { default as PhonePadCustomKDF } from "./xml-components/keyboards/PhonePadCustomKDF.keyboard.json";
+export { default as WifiCustomKDF } from "./xml-components/keyboards/WifiCustomKDF.keyboard.json";

package/src/key-handler.props.ts

@@ -0,0 +1,33 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { RemoteKeyName } from "@roku-sdk/interfaces";
+
+import type { IGroupProps } from "./sg-nodes/group.props";
+import type { EventHandler, JSX } from "./sg-nodes/types";
+
+export interface CommonKeyHandlerProps extends IGroupProps {
+    onKeyEvent: EventHandlerKey;
+    children?: JSX.Element;
+}
+
+export interface IKeyHandlerData {
+    key: RemoteKeyName;
+    press: boolean;
+}
+
+export type EventHandlerKey = EventHandler<IKeyHandlerData>;
+
+export interface ScopedKeyHandlerProps extends CommonKeyHandlerProps {
+    handleAllKeys?: false;
+    keys: RemoteKeyName[];
+    bubbleUnhandledKeys?: boolean;
+}
+
+export interface AllKeysKeyHandlerProps extends CommonKeyHandlerProps {
+    handleAllKeys: true;
+    keys?: never;
+    bubbleUnhandledKeys?: never;
+}
+
+export type IKeyHandlerProps = AllKeysKeyHandlerProps | ScopedKeyHandlerProps;

package/src/key-handler.tsx

@@ -0,0 +1,24 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IKeyHandlerProps } from "./key-handler.props";
+export type { CommonKeyHandlerProps } from "./key-handler.props";
+
+export type {
+    IKeyHandlerData,
+    EventHandlerKey,
+    ScopedKeyHandlerProps,
+    AllKeysKeyHandlerProps,
+    IKeyHandlerProps
+} from "./key-handler.props";
+
+import { retainAsset } from "./retain-asset";
+import { Component } from "./types";
+import KeyHandlerXML from "./xml-components/keyhandler/KeyHandler.xml";
+
+// Only allow either 'handleAllKeys' or ('keys' and 'bubbleUnhandledKeys'), not both
+
+export const KeyHandler: Component<IKeyHandlerProps> = props => {
+    retainAsset(KeyHandlerXML);
+    return <key-handler {...props}>{props.children}</key-handler>;
+};

package/src/modal-dialog.props.ts

@@ -0,0 +1,38 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IGroupProps } from "./sg-nodes/group.props";
+import type { EventHandler, JSX } from "./sg-nodes/types";
+
+export interface IModalLifecycleProps {
+    /** Present the dialog. False prepares its children without taking focus. @default true */
+    open?: boolean;
+    /** Prepare the dialog while showing fallback, without granting it focus. @default true */
+    ready?: boolean;
+    /** Native dialog shown while ready=false; use a standardDialog intrinsic, not another Modal. */
+    fallback?: JSX.Element;
+    /** Allow replacing another native modal. False reports onBlocked instead. @default true */
+    replaceExisting?: boolean;
+    /** Fired after native attachment and initial focus, not after artwork has drawn. */
+    onOpened?: EventHandler<void>;
+    /** Fired at most once per presented lifetime while mounted, including native dismissal and open=false. */
+    onWasClosed?: EventHandler<void>;
+    /** Another native dialog prevented presentation. Toggle open to retry explicitly. */
+    onBlocked?: EventHandler<void>;
+    /** ID of the child that receives focus when the dialog opens. */
+    initialFocusId?: string;
+}
+
+/**
+ * Props for the custom Modal XML component.
+ *
+ * Intentionally does not derive from `JSX.IntrinsicElements["modal"]` — that tag is
+ * declared as `IModalProps` in jsx.d.ts, so referencing the intrinsic here would create
+ * a circular type.
+ */
+export interface IModalProps extends IGroupProps, IModalLifecycleProps {
+    dialog?: JSX.Element;
+}
+
+/** @deprecated Use {@link IModalProps}. Kept for call-site casts onto the native modal tag. */
+export type ModalIntrinsicProps = IModalProps;

package/src/modal-dialog.tsx

@@ -0,0 +1,41 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { DomNode } from "@roku-sdk/interfaces";
+import { createMemo, onCleanup, onMount, setProp, splitProps } from "@roku-sdk/solid";
+
+import type { IModalProps } from "./modal-dialog.props";
+import { retainAsset } from "./retain-asset";
+import { Component } from "./types";
+import ModalXML from "./xml-components/modal/Modal.xml";
+export type { ModalIntrinsicProps, IModalProps, IModalLifecycleProps } from "./modal-dialog.props";
+
+export const modalPropKeys = [
+    "initialFocusId",
+    "open",
+    "ready",
+    "fallback",
+    "replaceExisting",
+    "onOpened",
+    "onWasClosed",
+    "onBlocked"
+] as const;
+
+export const Modal: Component<IModalProps> = (props: IModalProps) => {
+    retainAsset(ModalXML);
+    // JSX node getters must not reconstruct their subtrees when lifecycle props change.
+    const [content, rest] = splitProps(props, ["dialog", "fallback"]);
+    const dialog = createMemo(() => content.dialog);
+    const fallback = createMemo(() => content.fallback);
+    const element = <modal {...rest} dialog={dialog()} fallback={fallback()} visible={false} />;
+    const node = element as unknown as DomNode;
+    // Present only after the wrapper and all node-valued children have been attached.
+    onMount(() => setProp(node, "mounted", true));
+    onCleanup(() => {
+        setProp(node, "mounted", false);
+        // Node-valued props are not ordinary children; retire their observers explicitly.
+        setProp(node, "dialog", null, dialog());
+        setProp(node, "fallback", null, fallback());
+    });
+    return element;
+};

package/src/retain-asset.ts

@@ -0,0 +1,24 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+/**
+ * Keeps an imported asset live when its component survives tree-shaking.
+ *
+ * The asset import plugin uses esbuild's metafile to copy only assets referenced
+ * by bundled modules. This function is a no-op at runtime; its only job is to
+ * create a reference esbuild can see so TypeScript/esbuild does not elide the
+ * asset's import binding as unused.
+ *
+ * Call this inside the component function, not at module scope. Placement matters
+ * when a module exports more than one component: a module-scope reference keeps
+ * the asset alive whenever the module is loaded, even if the specific component
+ * export is dead-code-eliminated. Keeping the reference in the component body
+ * ties the asset to that export, so the two are removed together.
+ *
+ * Do NOT place this inside `createEffect`, `onMount`, or other lazy closures. The
+ * asset copies unconditionally once the module-scope import survives DCE, so a
+ * lazy call site would be misleading without changing packaging behavior.
+ */
+export function retainAsset(asset: unknown): void {
+    void asset;
+}