onejs-react 0.1.24 → 0.1.26

package/README.md

@@ -112,6 +112,27 @@ RenderContainer         (minimal: __csHandle, __csType)
         └── ScrollViewElement (+ scrollOffset, ScrollTo)
 ```
 
+### 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.
+
+```tsx
+import { createPortal, View } from "onejs-react"
+
+function Modal({ children }) {
+    return createPortal(
+        <View style={{ position: "absolute", top: 0, left: 0, right: 0, bottom: 0 }}>
+            {children}
+        </View>,
+        __root
+    )
+}
+```
+
+> Use the `createPortal` exported from `onejs-react`, not the one from `react-dom` - the latter targets the browser DOM and will not work here.
+
 ## Key Concepts
 
 - **Element types**: Use `ojs-` prefix internally (e.g., `ojs-view`, `ojs-button`) to avoid conflicts with HTML types
@@ -136,7 +157,7 @@ Test suite uses Vitest with mocked Unity CS globals. Tests are in `src/__tests__
 | File | Coverage |
 |------|----------|
 | `host-config.test.ts` | Instance creation, style/className management, events, children |
-| `renderer.test.tsx` | Integration tests: render(), unmount(), React state, effects |
+| `renderer.test.tsx` | Integration tests: render(), unmount(), createPortal(), React state, effects |
 | `components.test.tsx` | Component wrappers, prop passing, event mapping |
 | `mocks.ts` | Mock implementations of Unity UI Toolkit classes |
 | `setup.ts` | Global test setup for CS, __eventAPI |

package/package.json

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

package/src/__tests__/host-config.test.ts

@@ -138,6 +138,16 @@ describe('host-config', () => {
             const instance = createInstance('ojs-view', {});
             expect(getMockElement(instance).enabledSelf).toBe(true);
         });
+
+        it('forwards the name prop to the element (USS #id selectors / Debugger)', () => {
+            const instance = createInstance('ojs-view', { name: 'my-panel' } as TestProps);
+            expect(getMockElement(instance).name).toBe('my-panel');
+        });
+
+        it('leaves name empty by default when the prop is omitted', () => {
+            const instance = createInstance('ojs-view', {});
+            expect(getMockElement(instance).name).toBe('');
+        });
     });
 
     describe('style application', () => {
@@ -372,6 +382,22 @@ describe('host-config', () => {
             commitUpdate(instance, 'ojs-button', { disabled: true } as TestProps, {} as TestProps);
             expect(getMockElement(instance).enabledSelf).toBe(true);
         });
+
+        it('updates name when the prop changes', () => {
+            const instance = createInstance('ojs-view', { name: 'first' } as TestProps);
+            expect(getMockElement(instance).name).toBe('first');
+
+            commitUpdate(instance, 'ojs-view', { name: 'first' } as TestProps, { name: 'second' } as TestProps);
+            expect(getMockElement(instance).name).toBe('second');
+        });
+
+        it('resets name to empty string when the prop is removed', () => {
+            const instance = createInstance('ojs-view', { name: 'first' } as TestProps);
+            expect(getMockElement(instance).name).toBe('first');
+
+            commitUpdate(instance, 'ojs-view', { name: 'first' } as TestProps, {} as TestProps);
+            expect(getMockElement(instance).name).toBe('');
+        });
     });
 
     describe('className management', () => {

package/src/__tests__/mocks.ts

@@ -68,6 +68,7 @@ export class MockVisualElement {
     private _classList: Set<string> = new Set();
 
     // Common properties
+    name = '';
     text = '';
     value: unknown = undefined;
     label = '';

package/src/__tests__/renderer.test.tsx

@@ -10,7 +10,7 @@
 
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import React, { useState, useEffect } from 'react';
-import { render, unmount, getRoot } from '../renderer';
+import { render, unmount, createPortal, getRoot } from '../renderer';
 import { View, Label, Button } from '../components';
 import { MockVisualElement, MockLength, MockColor, createMockContainer, flushMicrotasks, getEventAPI } from './mocks';
 
@@ -140,6 +140,110 @@ describe('renderer', () => {
         });
     });
 
+    describe('createPortal()', () => {
+        it('renders portal children into the target, not the host container', async () => {
+            const host = createMockContainer();
+            const portalTarget = createMockContainer();
+
+            function App() {
+                return (
+                    <ojs-view>
+                        <ojs-label text="in-tree" />
+                        {createPortal(<ojs-button text="in-portal" />, portalTarget as any)}
+                    </ojs-view>
+                );
+            }
+
+            render(<App />, host as any);
+            await flushMicrotasks();
+
+            // Host tree contains only the view + its label child, not the portal child
+            const view = host.children[0] as MockVisualElement;
+            expect(view.childCount).toBe(1);
+            expect(view.children[0].__csType).toBe('UnityEngine.UIElements.Label');
+
+            // Portal target received the button
+            expect(portalTarget.childCount).toBe(1);
+            expect(portalTarget.children[0].__csType).toBe('UnityEngine.UIElements.Button');
+        });
+
+        it('appends into an existing target without clearing it', async () => {
+            const host = createMockContainer();
+            const portalTarget = createMockContainer();
+            const existing = new MockVisualElement();
+            portalTarget.Add(existing);
+
+            render(
+                <ojs-view>{createPortal(<ojs-label text="overlay" />, portalTarget as any)}</ojs-view>,
+                host as any
+            );
+            await flushMicrotasks();
+
+            expect(portalTarget.childCount).toBe(2);
+            expect(portalTarget.children).toContain(existing);
+        });
+
+        it('updates portal children when state changes', async () => {
+            const host = createMockContainer();
+            const portalTarget = createMockContainer();
+            let setText: (s: string) => void;
+
+            function App() {
+                const [text, _setText] = useState('a');
+                setText = _setText;
+                return <ojs-view>{createPortal(<ojs-label text={text} />, portalTarget as any)}</ojs-view>;
+            }
+
+            render(<App />, host as any);
+            await flushMicrotasks();
+            expect((portalTarget.children[0] as MockVisualElement).text).toBe('a');
+
+            setText!('b');
+            await flushMicrotasks();
+            expect((portalTarget.children[0] as MockVisualElement).text).toBe('b');
+        });
+
+        it('removes portal content from the target on unmount', async () => {
+            const host = createMockContainer();
+            const portalTarget = createMockContainer();
+
+            render(
+                <ojs-view>{createPortal(<ojs-label text="x" />, portalTarget as any)}</ojs-view>,
+                host as any
+            );
+            await flushMicrotasks();
+            expect(portalTarget.childCount).toBe(1);
+
+            unmount(host as any);
+            await flushMicrotasks();
+            expect(portalTarget.childCount).toBe(0);
+        });
+
+        it('removes portal content when conditionally unmounted', async () => {
+            const host = createMockContainer();
+            const portalTarget = createMockContainer();
+            let setShow: (b: boolean) => void;
+
+            function App() {
+                const [show, _setShow] = useState(true);
+                setShow = _setShow;
+                return (
+                    <ojs-view>
+                        {show && createPortal(<ojs-label text="modal" />, portalTarget as any)}
+                    </ojs-view>
+                );
+            }
+
+            render(<App />, host as any);
+            await flushMicrotasks();
+            expect(portalTarget.childCount).toBe(1);
+
+            setShow!(false);
+            await flushMicrotasks();
+            expect(portalTarget.childCount).toBe(0);
+        });
+    });
+
     describe('component wrappers', () => {
         it('renders View component', async () => {
             const container = createMockContainer();

package/src/host-config.ts

@@ -847,7 +847,7 @@ function applyListViewProps(element: CSListView, props: Record<string, unknown>,
 
 // Props handled by the reconciler infrastructure - not forwarded to C# elements
 const RESERVED_PROPS = new Set([
-    'children', 'key', 'ref', 'style', 'className', 'pickingMode', 'focusable', 'disabled',
+    'children', 'key', 'ref', 'style', 'className', 'name', 'pickingMode', 'focusable', 'disabled',
     'onGenerateVisualContent',
     ...Object.keys(EVENT_PROPS),
 ]);
@@ -918,6 +918,13 @@ function createInstance(type: string, props: BaseProps): Instance {
     applyVisualContentCallback(instance, props);
     applyComponentProps(element, type, props as Record<string, unknown>);
 
+    // Apply name (VisualElement.name). Drives USS #id selectors and the label
+    // shown in the UI Toolkit Debugger. Universal to every VisualElement, so
+    // it lives here rather than in the per-type prop handlers.
+    if (props.name !== undefined) {
+        element.name = props.name;
+    }
+
     // Apply pickingMode
     if (props.pickingMode !== undefined) {
         element.pickingMode = CS.UnityEngine.UIElements.PickingMode[props.pickingMode];
@@ -962,6 +969,12 @@ function updateInstance(instance: Instance, oldProps: BaseProps, newProps: BaseP
     // Update component-specific props - pass oldProps to skip unchanged values
     applyComponentProps(element, instance.type, newProps as Record<string, unknown>, oldProps as Record<string, unknown>);
 
+    // Update name. Unity defaults VisualElement.name to "", so removing the prop
+    // resets it to empty rather than leaving the stale value behind.
+    if (oldProps.name !== newProps.name) {
+        element.name = newProps.name ?? '';
+    }
+
     // Update pickingMode
     if (oldProps.pickingMode !== newProps.pickingMode) {
         if (newProps.pickingMode !== undefined) {

package/src/index.ts

@@ -19,7 +19,7 @@ export {
 export { registerElement } from './host-config';
 
 // Renderer
-export { render, unmount, flushSync, batchedUpdates, getDebugInfo } from './renderer';
+export { render, unmount, createPortal, flushSync, batchedUpdates, getDebugInfo } from './renderer';
 
 // Error Handling
 export { ErrorBoundary, formatError } from './error-boundary';

package/src/renderer.ts

@@ -1,5 +1,5 @@
 import Reconciler from 'react-reconciler';
-import type { ReactNode } from 'react';
+import type { ReactNode, ReactPortal } from 'react';
 import { hostConfig, type Container } from './host-config';
 import type { RenderContainer, VisualElement } from './types';
 
@@ -58,6 +58,39 @@ export function unmount(container: RenderContainer): void {
   }
 }
 
+/**
+ * Render `children` into a different container, outside the normal parent
+ * hierarchy. The returned node must be included in a render tree (i.e. returned
+ * from a component) to take effect.
+ *
+ * Unlike the DOM, UI Toolkit has no `z-index`: paint order follows the element
+ * hierarchy (later siblings draw on top) and a parent with `overflow: hidden`
+ * clips its descendants. Portaling a subtree into a top-level container such as
+ * `__root` lets modals, tooltips, and other overlays escape clipping and paint
+ * above the rest of the UI.
+ *
+ * @param children  React nodes to render into `container`.
+ * @param container Target VisualElement, e.g. `__root` or a ref'd element.
+ * @param key       Optional React key for the portal.
+ *
+ * @example
+ * function Modal({ children }: { children: ReactNode }) {
+ *     return createPortal(
+ *         <View style={{ position: "absolute", top: 0, left: 0, right: 0, bottom: 0 }}>
+ *             {children}
+ *         </View>,
+ *         __root
+ *     )
+ * }
+ */
+export function createPortal(children: ReactNode, container: RenderContainer, key: string | null = null): ReactPortal {
+  // `react-reconciler`'s ReactPortal type ({ containerInfo, implementation, ... })
+  // is structurally different from `react`'s ReactPortal (extends ReactElement with
+  // type/props). The runtime value is a valid portal either way; bridge the known
+  // @types discrepancy so consumers get `react`'s ReactPortal, matching react-dom.
+  return reconciler.createPortal(children, container as Container, null, key) as unknown as ReactPortal;
+}
+
 /**
  * Execute a callback synchronously, flushing all updates before returning.
  * Useful for tests or when you need immediate UI updates.

package/src/types.ts

@@ -409,6 +409,21 @@ export interface BaseProps {
   style?: ViewStyle;
   className?: string;
 
+  /**
+   * Element name. Maps directly to `VisualElement.name` in Unity UI Toolkit.
+   *
+   * Useful for:
+   * - **USS `#id` selectors**: a rule like `#my-panel { ... }` targets the
+   *   element whose `name` is `my-panel` (analogous to a CSS ID selector).
+   * - **Debugging**: the UI Toolkit Debugger window shows the name instead of
+   *   the bare type (e.g. `VisualElement#my-panel`).
+   *
+   * Names need not be unique, but since `#` selectors match by name, prefer
+   * unique names for elements you intend to select on. Removing the prop resets
+   * the name to an empty string (Unity's default).
+   */
+  name?: string;
+
   // Click
   onClick?: PointerEventHandler;