@roku-sdk/components 0.0.0-stage → 2.18.0

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;
+}