@roku-sdk/solid 0.0.0-stage → 2.18.0

package/src/focus.ts

@@ -0,0 +1,142 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+/**
+ * SG focus requested through the `gainFocus` prop or a node's `focus()` / `blur()` methods.
+ *
+ * Only those two APIs feed this module. Focus moved any other way (BrightScript, firmware,
+ * a native component handling keys) is not seen here, so `focused` can be stale after it.
+ * An app that uses neither API never sets `focused`, and removals and commits pass through
+ * without sending any focus call.
+ *
+ * `FocusBoundary` (`@roku-sdk/navigation`) doesn't use either API. Its focus is virtual and
+ * lives in TS, while SG focus stays on the anchor node (a `FocusBoundaryBase`) the whole
+ * time, which routes every key to TS. An app whose focus is managed entirely by
+ * `FocusBoundary` never reaches this module. It matters when SG focus has to leave the anchor
+ * for a real node, e.g. a native component that handles its own keys, and the restore below
+ * is what hands focus back to the anchor afterwards.
+ */
+
+import type { logger } from "@roku-sdk/common";
+import { AnchorNode, AnNodeRef, DomNode, TreeManipulationApi } from "@roku-sdk/interfaces";
+
+type Logger = ReturnType<typeof logger.getLogger>;
+
+let tmApi: TreeManipulationApi;
+let focusLogger: Logger;
+// The placeholder anchor ref solid.ts passes on every tree call.
+let NO_ANCHOR: AnNodeRef;
+
+// The node the SDK last gave SG focus to. SceneGraph has one focused node per scene,
+// so one slot covers every anchor node. This is the only focus state that persists across
+// transactions and is shared by all anchor nodes; everything below is cleared in commitFocus.
+let focused: DomNode | undefined;
+
+// Local to the transaction.
+let pending: DomNode | undefined;
+let requestCount = 0;
+// Set when the focused node is released or removed; preCommit moves SG focus here
+// unless another node requests focus in the same transaction.
+let restoreAnchor: AnchorNode | undefined;
+
+/**
+ * The anchor node a node is rendered under: the root of its parent chain, which is the
+ * AnchorNode passed to `render`. `undefined` for a node not attached under an anchor.
+ */
+function findOwningAnchor(node: DomNode | undefined): AnchorNode | undefined {
+    let current = node;
+    while (current?.parent) {
+        current = current.parent;
+    }
+    return current && current.t === undefined ? (current as AnchorNode) : undefined;
+}
+
+export function initFocus(api: TreeManipulationApi, log: Logger, noAnchor: AnNodeRef): void {
+    tmApi = api;
+    focusLogger = log;
+    NO_ANCHOR = noAnchor;
+}
+
+/** `gainFocus=true` and `focus()`. Applied in `commitFocus`; the last request wins. */
+export function requestFocus(node: DomNode): void {
+    pending = node;
+    requestCount++;
+}
+
+/** `gainFocus=false` and `blur()`. */
+export function releaseFocus(node: DomNode): void {
+    if (pending === node) {
+        pending = undefined;
+        requestCount = Math.max(0, requestCount - 1);
+    }
+    tmApi.setFocus(NO_ANCHOR, node.r, false);
+    if (focused === node) {
+        restoreAnchor = findOwningAnchor(node);
+        focused = undefined;
+    }
+}
+
+/**
+ * Called for every node of a removed subtree, before its parent pointer is cleared.
+ * `attachParent` is the parent the subtree was removed from.
+ */
+export function focusNodeRemoved(node: DomNode, attachParent: DomNode | undefined): void {
+    if (node === focused) {
+        restoreAnchor = findOwningAnchor(attachParent);
+        focused = undefined;
+    }
+    if (node === pending) {
+        pending = undefined;
+        requestCount = Math.max(0, requestCount - 1);
+    }
+}
+
+/**
+ * Drops every reference into a destroyed anchor node's tree. Called once the anchor's render
+ * root is disposed, before the transaction commits: a cleanup that released focus during
+ * dispose must not re-anchor to the dead anchor, and `focused` must not keep its tree alive.
+ */
+export function forgetAnchor(anchor: AnchorNode): void {
+    if (restoreAnchor === anchor) {
+        restoreAnchor = undefined;
+    }
+    if (focused && findOwningAnchor(focused) === anchor) {
+        focused = undefined;
+    }
+    if (pending && findOwningAnchor(pending) === anchor) {
+        pending = undefined;
+        requestCount = Math.max(0, requestCount - 1);
+    }
+}
+
+/** Sends the transaction's focus change. Runs in preCommit after removals and appends. */
+export function commitFocus(): void {
+    if (requestCount > 1) {
+        const count = requestCount;
+        focusLogger.warn(
+            () => `Multiple nodes (${count}) requested focus in one transaction. Only last one will receive focus.`
+        );
+    }
+    const node = pending;
+    const anchor = restoreAnchor;
+    pending = undefined;
+    restoreAnchor = undefined;
+    requestCount = 0;
+
+    if (node) {
+        tmApi.setFocus(NO_ANCHOR, node.r, true);
+        focused = node;
+        focusLogger.trace(() => `setFocus: ${node.t}`);
+    } else if (anchor?.canReceiveFocus) {
+        tmApi.setFocus(NO_ANCHOR, anchor.r, true);
+        focusLogger.trace(() => `setFocus re-anchored to anchor node`);
+    }
+}
+
+// Invoked only from unit tests
+export function resetFocus(): void {
+    focused = undefined;
+    pending = undefined;
+    restoreAnchor = undefined;
+    requestCount = 0;
+}

package/src/index.dev.ts

@@ -0,0 +1,6 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+globalThis.__DEV__ = true;
+globalThis.__SIGNAL__ = true;
+export * from "./index.ts";
+export { createSignal, createMemo, createEffect } from "./dev-wrappers";

package/src/index.ts

@@ -0,0 +1,6 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+export * from "./solid";
+export { registerImperativeMethods, setPropMethod } from "./dom-node";
+export { forgetAnchor } from "./focus";

package/src/jsx-runtime.ts

@@ -0,0 +1,5 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+// Re-export solid-js JSX runtime for @roku-sdk/solid
+// This allows TypeScript to use jsxImportSource: "@roku-sdk/solid"
+export * from "solid-js/jsx-runtime";