onejs-react 0.1.25 → 0.1.27

package/README.md

@@ -114,24 +114,27 @@ RenderContainer         (minimal: __csHandle, __csType)
 
 ### Portals
 
-`createPortal(children, container, key?)` renders a subtree into a different `VisualElement`, outside the normal parent hierarchy - the OneJS equivalent of `react-dom`'s `createPortal`.
-
-UI Toolkit has no `z-index`: paint order follows the element hierarchy and a parent with `overflow: hidden` clips its children. Portaling overlays (modals, tooltips, dropdowns) into a top-level container like `__root` lets them escape clipping and paint above the rest of the UI.
+`<Portal>` renders children above the rest of the UI (modals, tooltips, dropdowns). UI Toolkit has no `z-index` and `overflow: hidden` clips children, so a deeply-nested overlay gets clipped and stuck below later siblings. `<Portal>` mounts into a shared overlay layer that onejs-react keeps as the last child of `__root`, so overlays always paint on top. Zero setup.
 
 ```tsx
-import { createPortal, View } from "onejs-react"
+import { Portal, View } from "onejs-react"
 
 function Modal({ children }) {
-    return createPortal(
-        <View style={{ position: "absolute", top: 0, left: 0, right: 0, bottom: 0 }}>
-            {children}
-        </View>,
-        __root
+    return (
+        <Portal>
+            <View style={{ position: "absolute", top: 0, left: 0, right: 0, bottom: 0 }}>
+                {children}
+            </View>
+        </Portal>
     )
 }
 ```
 
-> Use the `createPortal` exported from `onejs-react`, not the one from `react-dom` - the latter targets the browser DOM and will not work here.
+The layer ignores picking when empty, so a closed overlay never blocks the app.
+
+`<Portal>` is built on `createPortal(children, container, key?)` (the OneJS equivalent of `react-dom`'s `createPortal`), exported for when you need a specific target. With a custom target you own draw order, so prefer `<Portal>` for overlays.
+
+> Use the exports from `onejs-react`, not `react-dom` - the latter targets the browser DOM and will not work here.
 
 ## Key Concepts
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onejs-react",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "React 19 renderer for OneJS (Unity UI Toolkit)",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/__tests__/mocks.ts

@@ -73,6 +73,7 @@ export class MockVisualElement {
     value: unknown = undefined;
     label = '';
     enabledSelf = true;
+    pickingMode = 0;
 
     constructor(csType = 'UnityEngine.UIElements.VisualElement') {
         this.__csHandle = Math.floor(Math.random() * 1000000);

package/src/__tests__/portal.test.tsx

@@ -0,0 +1,85 @@
+/**
+ * Tests for the <Portal> component.
+ *
+ * Portal renders into a shared overlay layer that OneJS keeps as the last child
+ * of __root, so overlays paint on top of the app without per-call BringToFront.
+ */
+
+import { describe, it, expect } from 'vitest';
+import React from 'react';
+import { render } from '../renderer';
+import { Portal } from '../portal';
+import { View, Label, Button } from '../components';
+import { MockVisualElement, createMockContainer, flushMicrotasks } from './mocks';
+
+describe('Portal', () => {
+    it('mounts children into a shared overlay layer appended last under __root', async () => {
+        const root = createMockContainer();
+        (globalThis as any).__root = root;
+
+        render(<View><Portal><Label text="overlay" /></Portal></View>, root as any);
+        await flushMicrotasks();
+
+        // root children: [0] app view, [1] portal layer (added in an effect → last)
+        expect(root.childCount).toBe(2);
+        const layer = root.children[1] as MockVisualElement;
+        expect(layer.name).toBe('onejs-portal-root');
+        expect(layer.pickingMode).toBe((globalThis as any).CS.UnityEngine.UIElements.PickingMode.Ignore);
+
+        // portal content lives inside the layer, not the app view
+        expect(layer.childCount).toBe(1);
+        expect(layer.children[0].__csType).toBe('UnityEngine.UIElements.Label');
+        expect((root.children[0] as MockVisualElement).childCount).toBe(0);
+    });
+
+    it('shares one layer across multiple Portals', async () => {
+        const root = createMockContainer();
+        (globalThis as any).__root = root;
+
+        render(
+            <View>
+                <Portal><Label text="a" /></Portal>
+                <Portal><Button text="b" /></Portal>
+            </View>,
+            root as any
+        );
+        await flushMicrotasks();
+
+        // app + exactly one shared layer
+        expect(root.childCount).toBe(2);
+        const layer = root.children[1] as MockVisualElement;
+        expect(layer.childCount).toBe(2);
+    });
+
+    it('targets an explicit container without creating the shared layer', async () => {
+        const root = createMockContainer();
+        (globalThis as any).__root = root;
+        const target = createMockContainer();
+
+        render(<View><Portal container={target as any}><Label text="x" /></Portal></View>, root as any);
+        await flushMicrotasks();
+
+        expect(target.childCount).toBe(1);
+        expect(target.children[0].__csType).toBe('UnityEngine.UIElements.Label');
+        // shared layer not created: root has only the app view
+        expect(root.childCount).toBe(1);
+    });
+
+    it('removes portal content when unmounted', async () => {
+        const root = createMockContainer();
+        (globalThis as any).__root = root;
+
+        function App({ show }: { show: boolean }) {
+            return <View>{show && <Portal><Label text="m" /></Portal>}</View>;
+        }
+
+        render(<App show={true} />, root as any);
+        await flushMicrotasks();
+        const layer = root.children[1] as MockVisualElement;
+        expect(layer.childCount).toBe(1);
+
+        render(<App show={false} />, root as any);
+        await flushMicrotasks();
+        expect(layer.childCount).toBe(0);
+    });
+});

package/src/host-config.ts

@@ -86,6 +86,10 @@ declare const __eventAPI: {
     removeParent: (childHandle: number) => void;
 };
 
+// Panel root element, provided by the runtime. This is also the container apps
+// pass to render(), so it is the natural home for a shared overlay layer.
+declare const __root: CSObject;
+
 interface CSStyle {
     [key: string]: unknown;
 }
@@ -437,6 +441,34 @@ function applyStyle(element: CSObject, style: ViewStyle | undefined): Set<string
     return appliedKeys;
 }
 
+// Shared overlay layer for <Portal>. A full-screen, click-through element kept as
+// the LAST child of __root, so portaled content (modals, tooltips, dropdowns)
+// always paints above the app and escapes any `overflow: hidden` ancestor.
+//
+// It must be appended AFTER the app's root view exists, otherwise it lands before
+// the app and renders behind it. Callers create it from an effect (post-mount), by
+// which point the app root is already in __root, so Add() puts the layer last.
+//
+// Keyed by __root so a fresh root (e.g. after a domain reload) gets its own layer.
+const _portalLayers = new WeakMap<object, VisualElement>();
+
+export function getPortalLayer(): VisualElement {
+    const root = __root as unknown as object;
+    let layer = _portalLayers.get(root);
+    if (!layer) {
+        const el: CSObject = new CS.UnityEngine.UIElements.VisualElement();
+        el.name = "onejs-portal-root";
+        applyStyle(el, { position: "absolute", top: 0, left: 0, right: 0, bottom: 0 });
+        // The layer itself ignores picking so empty regions stay click-through; its
+        // children (modals, etc.) still receive input normally.
+        el.pickingMode = CS.UnityEngine.UIElements.PickingMode.Ignore;
+        __root.Add(el);
+        layer = el;
+        _portalLayers.set(root, layer);
+    }
+    return layer;
+}
+
 // Force-resolve CS path proxies (e.g. CS.UnityEngine.UIElements.Justify.Center)
 // to their underlying int value. parseEnumValue and parseLength's StyleKeyword
 // cases return path proxies whose .valueOf() reads the int via GetField. The

package/src/index.ts

@@ -21,6 +21,10 @@ export { registerElement } from './host-config';
 // Renderer
 export { render, unmount, createPortal, flushSync, batchedUpdates, getDebugInfo } from './renderer';
 
+// Portals
+export { Portal } from './portal';
+export type { PortalProps } from './portal';
+
 // Error Handling
 export { ErrorBoundary, formatError } from './error-boundary';
 export type { ErrorBoundaryProps } from './error-boundary';

package/src/portal.tsx

@@ -0,0 +1,51 @@
+import { useState, useEffect, type ReactNode } from "react"
+import { createPortal } from "./renderer"
+import { getPortalLayer } from "./host-config"
+import type { RenderContainer } from "./types"
+
+export interface PortalProps {
+    children: ReactNode
+    /** Target element. Defaults to OneJS's shared overlay layer (last child of `__root`). */
+    container?: RenderContainer
+}
+
+/**
+ * Render `children` above the rest of the UI, outside the normal hierarchy.
+ *
+ * Zero setup: portals into a shared overlay layer that OneJS keeps as the last
+ * child of `__root`, so modals, tooltips, and dropdowns always paint on top and
+ * escape any `overflow: hidden` ancestor. Pass `container` to target a specific
+ * element instead.
+ *
+ * Built on {@link createPortal}; reach for that directly only when you need a
+ * custom target and want to manage draw order yourself.
+ *
+ * @example
+ * function Modal({ onClose, children }) {
+ *     return (
+ *         <Portal>
+ *             <View
+ *                 style={{ position: "absolute", top: 0, left: 0, right: 0, bottom: 0,
+ *                          backgroundColor: "rgba(0,0,0,0.6)", alignItems: "center", justifyContent: "center" }}
+ *                 onClick={onClose}
+ *             >
+ *                 <View onClick={(e) => e.stopPropagation()}>{children}</View>
+ *             </View>
+ *         </Portal>
+ *     )
+ * }
+ */
+export function Portal({ children, container }: PortalProps) {
+    // The shared layer is appended to __root in an effect (after the app mounts) so
+    // it lands last. It is therefore unavailable on the first render; we resolve it
+    // post-mount, which adds one frame before the overlay appears. An explicit
+    // container is used immediately, with no delay.
+    const [layer, setLayer] = useState<RenderContainer | null>(container ?? null)
+
+    useEffect(() => {
+        if (!container) setLayer(getPortalLayer())
+    }, [container])
+
+    const target = container ?? layer
+    return target ? createPortal(children, target) : null
+}