onejs-react 0.1.19 → 0.1.21

package/package.json

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

package/src/__tests__/hooks.test.tsx

@@ -10,7 +10,7 @@
 
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest"
 import React from "react"
-import { useFrameSync, useFrameSyncWith, toArray } from "../hooks"
+import { useFrameSync, useFrameSyncWith, useEventSync, toArray } from "../hooks"
 import { render, unmount } from "../renderer"
 import { createMockContainer, flushMicrotasks } from "./mocks"
 
@@ -579,3 +579,435 @@ describe("useFrameSyncWith (deprecated)", () => {
         expect(capturedValue.x).toBe(10)
     })
 })
+
+// ===========================================================================
+// useEventSync
+// ===========================================================================
+
+/**
+ * Creates a mock C# object with event subscription support.
+ * Simulates the bootstrap's add_EventName / remove_EventName proxy mechanism.
+ */
+function createMockCSharpObject(initialValues: Record<string, unknown>) {
+    const listeners = new Map<string, Set<Function>>()
+    const values = { ...initialValues }
+
+    const proxy = new Proxy(values, {
+        get(target, prop) {
+            const propName = String(prop)
+            if (propName.startsWith("add_")) {
+                return (handler: Function) => {
+                    const eventName = propName.slice(4)
+                    if (!listeners.has(eventName)) listeners.set(eventName, new Set())
+                    listeners.get(eventName)!.add(handler)
+                }
+            }
+            if (propName.startsWith("remove_")) {
+                return (handler: Function) => {
+                    const eventName = propName.slice(7)
+                    listeners.get(eventName)?.delete(handler)
+                }
+            }
+            return target[propName]
+        },
+    })
+
+    return {
+        proxy,
+        fire(eventName: string) {
+            listeners.get(eventName)?.forEach(h => (h as any)())
+        },
+        set(prop: string, value: unknown) {
+            (values as any)[prop] = value
+        },
+        listenerCount(eventName: string) {
+            return listeners.get(eventName)?.size ?? 0
+        },
+    }
+}
+
+describe("useEventSync", () => {
+    // -- Convention form --
+
+    describe("convention form", () => {
+        it("reads initial value on mount", async () => {
+            const obj = createMockCSharpObject({ Health: 100 })
+            let capturedValue: unknown
+
+            function TestComponent() {
+                capturedValue = useEventSync(obj.proxy, "Health")
+                return null
+            }
+
+            const container = createMockContainer()
+            render(React.createElement(TestComponent), container)
+            await flushMicrotasks()
+
+            expect(capturedValue).toBe(100)
+        })
+
+        it("subscribes to OnPropertyChanged event", async () => {
+            const obj = createMockCSharpObject({ Health: 100 })
+
+            function TestComponent() {
+                useEventSync(obj.proxy, "Health")
+                return null
+            }
+
+            const container = createMockContainer()
+            render(React.createElement(TestComponent), container)
+            await flushMicrotasks()
+
+            expect(obj.listenerCount("OnHealthChanged")).toBe(1)
+        })
+
+        it("updates when event fires", async () => {
+            const obj = createMockCSharpObject({ Health: 100 })
+            let capturedValue: unknown
+
+            function TestComponent() {
+                capturedValue = useEventSync(obj.proxy, "Health")
+                return null
+            }
+
+            const container = createMockContainer()
+            render(React.createElement(TestComponent), container)
+            await flushMicrotasks()
+            expect(capturedValue).toBe(100)
+
+            obj.set("Health", 75)
+            obj.fire("OnHealthChanged")
+            await flushMicrotasks()
+            expect(capturedValue).toBe(75)
+        })
+
+        it("unsubscribes on unmount", async () => {
+            const obj = createMockCSharpObject({ Health: 100 })
+
+            function TestComponent() {
+                useEventSync(obj.proxy, "Health")
+                return null
+            }
+
+            const container = createMockContainer()
+            render(React.createElement(TestComponent), container)
+            await flushMicrotasks()
+            expect(obj.listenerCount("OnHealthChanged")).toBe(1)
+
+            unmount(container)
+            await flushMicrotasks()
+            expect(obj.listenerCount("OnHealthChanged")).toBe(0)
+        })
+
+        it("does not poll via RAF", async () => {
+            const obj = createMockCSharpObject({ Health: 100 })
+
+            function TestComponent() {
+                useEventSync(obj.proxy, "Health")
+                return null
+            }
+
+            const container = createMockContainer()
+            render(React.createElement(TestComponent), container)
+            await flushMicrotasks()
+
+            // RAF should not have been called by useEventSync
+            // (useFrameSync calls it, useEventSync should not)
+            const rafCallCount = (globalThis as any).requestAnimationFrame.mock.calls.length
+            // Advance several frames — count should not grow from useEventSync
+            await advanceFrame()
+            await advanceFrame()
+            await advanceFrame()
+            const rafCallCountAfter = (globalThis as any).requestAnimationFrame.mock.calls.length
+            expect(rafCallCountAfter).toBe(rafCallCount)
+        })
+
+        it("handles null source without crashing", async () => {
+            let capturedValue: unknown
+
+            function TestComponent() {
+                capturedValue = useEventSync(null as any, "Health")
+                return null
+            }
+
+            const container = createMockContainer()
+            render(React.createElement(TestComponent), container)
+            await flushMicrotasks()
+
+            expect(capturedValue).toBeUndefined()
+        })
+
+        it("re-subscribes when deps change", async () => {
+            const obj1 = createMockCSharpObject({ Health: 100 })
+            const obj2 = createMockCSharpObject({ Health: 200 })
+            let capturedValue: unknown
+            let currentSource = obj1
+
+            function TestComponent({ source }: { source: any }) {
+                capturedValue = useEventSync(source.proxy, "Health", [source.proxy])
+                return null
+            }
+
+            const container = createMockContainer()
+            render(React.createElement(TestComponent, { source: currentSource }), container)
+            await flushMicrotasks()
+            expect(capturedValue).toBe(100)
+            expect(obj1.listenerCount("OnHealthChanged")).toBe(1)
+
+            // Switch source
+            currentSource = obj2
+            render(React.createElement(TestComponent, { source: currentSource }), container)
+            await flushMicrotasks()
+            expect(capturedValue).toBe(200)
+            expect(obj1.listenerCount("OnHealthChanged")).toBe(0)
+            expect(obj2.listenerCount("OnHealthChanged")).toBe(1)
+        })
+
+        it("handles multiple rapid events correctly", async () => {
+            const obj = createMockCSharpObject({ Score: 0 })
+            let capturedValue: unknown
+
+            function TestComponent() {
+                capturedValue = useEventSync(obj.proxy, "Score")
+                return null
+            }
+
+            const container = createMockContainer()
+            render(React.createElement(TestComponent), container)
+            await flushMicrotasks()
+
+            obj.set("Score", 10)
+            obj.fire("OnScoreChanged")
+            obj.set("Score", 20)
+            obj.fire("OnScoreChanged")
+            obj.set("Score", 30)
+            obj.fire("OnScoreChanged")
+            await flushMicrotasks()
+
+            expect(capturedValue).toBe(30)
+        })
+    })
+
+    // -- Explicit form --
+
+    describe("explicit form", () => {
+        it("reads initial value from custom getter", async () => {
+            const obj = createMockCSharpObject({ Items: { Count: 5 } })
+            let capturedValue: unknown
+
+            function TestComponent() {
+                capturedValue = useEventSync(
+                    () => (obj.proxy as any).Items.Count,
+                    [[obj.proxy, "OnItemsChanged"]]
+                )
+                return null
+            }
+
+            const container = createMockContainer()
+            render(React.createElement(TestComponent), container)
+            await flushMicrotasks()
+
+            expect(capturedValue).toBe(5)
+        })
+
+        it("subscribes to multiple events", async () => {
+            const obj = createMockCSharpObject({ Count: 0 })
+
+            function TestComponent() {
+                useEventSync(
+                    () => (obj.proxy as any).Count,
+                    [[obj.proxy, "OnItemAdded"], [obj.proxy, "OnItemRemoved"]]
+                )
+                return null
+            }
+
+            const container = createMockContainer()
+            render(React.createElement(TestComponent), container)
+            await flushMicrotasks()
+
+            expect(obj.listenerCount("OnItemAdded")).toBe(1)
+            expect(obj.listenerCount("OnItemRemoved")).toBe(1)
+        })
+
+        it("updates on any subscribed event", async () => {
+            const obj = createMockCSharpObject({ Count: 0 })
+            let capturedValue: unknown
+
+            function TestComponent() {
+                capturedValue = useEventSync(
+                    () => (obj.proxy as any).Count,
+                    [[obj.proxy, "OnItemAdded"], [obj.proxy, "OnItemRemoved"]]
+                )
+                return null
+            }
+
+            const container = createMockContainer()
+            render(React.createElement(TestComponent), container)
+            await flushMicrotasks()
+            expect(capturedValue).toBe(0)
+
+            obj.set("Count", 3)
+            obj.fire("OnItemAdded")
+            await flushMicrotasks()
+            expect(capturedValue).toBe(3)
+
+            obj.set("Count", 2)
+            obj.fire("OnItemRemoved")
+            await flushMicrotasks()
+            expect(capturedValue).toBe(2)
+        })
+
+        it("unsubscribes all events on unmount", async () => {
+            const obj = createMockCSharpObject({ Count: 0 })
+
+            function TestComponent() {
+                useEventSync(
+                    () => (obj.proxy as any).Count,
+                    [[obj.proxy, "OnItemAdded"], [obj.proxy, "OnItemRemoved"]]
+                )
+                return null
+            }
+
+            const container = createMockContainer()
+            render(React.createElement(TestComponent), container)
+            await flushMicrotasks()
+            expect(obj.listenerCount("OnItemAdded")).toBe(1)
+            expect(obj.listenerCount("OnItemRemoved")).toBe(1)
+
+            unmount(container)
+            await flushMicrotasks()
+            expect(obj.listenerCount("OnItemAdded")).toBe(0)
+            expect(obj.listenerCount("OnItemRemoved")).toBe(0)
+        })
+
+        it("supports events from multiple sources", async () => {
+            const inventory = createMockCSharpObject({ Count: 5 })
+            const player = createMockCSharpObject({ Level: 1 })
+            let capturedValue: unknown
+
+            function TestComponent() {
+                capturedValue = useEventSync(
+                    () => (inventory.proxy as any).Count * (player.proxy as any).Level,
+                    [[inventory.proxy, "OnChanged"], [player.proxy, "OnLevelUp"]]
+                )
+                return null
+            }
+
+            const container = createMockContainer()
+            render(React.createElement(TestComponent), container)
+            await flushMicrotasks()
+            expect(capturedValue).toBe(5)
+
+            player.set("Level", 2)
+            player.fire("OnLevelUp")
+            await flushMicrotasks()
+            expect(capturedValue).toBe(10)
+
+            inventory.set("Count", 10)
+            inventory.fire("OnChanged")
+            await flushMicrotasks()
+            expect(capturedValue).toBe(20)
+        })
+
+        it("handles getter that throws", async () => {
+            let shouldThrow = false
+            let capturedValue: unknown
+
+            const obj = createMockCSharpObject({})
+
+            function TestComponent() {
+                capturedValue = useEventSync(
+                    () => {
+                        if (shouldThrow) throw new Error("destroyed")
+                        return 42
+                    },
+                    [[obj.proxy, "OnChanged"]]
+                )
+                return null
+            }
+
+            const container = createMockContainer()
+            render(React.createElement(TestComponent), container)
+            await flushMicrotasks()
+            expect(capturedValue).toBe(42)
+
+            shouldThrow = true
+            obj.fire("OnChanged")
+            await flushMicrotasks()
+            // Should not crash — value stays at last good value
+            expect(capturedValue).toBe(42)
+        })
+
+        it("works with static-like event sources", async () => {
+            const staticClass = createMockCSharpObject({ Score: 999 })
+            let capturedValue: unknown
+
+            function TestComponent() {
+                capturedValue = useEventSync(
+                    () => (staticClass.proxy as any).Score,
+                    [[staticClass.proxy, "OnScoreChanged"]]
+                )
+                return null
+            }
+
+            const container = createMockContainer()
+            render(React.createElement(TestComponent), container)
+            await flushMicrotasks()
+            expect(capturedValue).toBe(999)
+
+            staticClass.set("Score", 1500)
+            staticClass.fire("OnScoreChanged")
+            await flushMicrotasks()
+            expect(capturedValue).toBe(1500)
+        })
+
+        it("handler still fires when event passes arguments (ignored by design)", async () => {
+            const obj = createMockCSharpObject({ Health: 100 })
+            let capturedValue: unknown
+
+            function TestComponent() {
+                capturedValue = useEventSync(obj.proxy, "Health")
+                return null
+            }
+
+            const container = createMockContainer()
+            render(React.createElement(TestComponent), container)
+            await flushMicrotasks()
+            expect(capturedValue).toBe(100)
+
+            // C# event fires — handler re-reads getter, ignoring event args
+            obj.set("Health", 80)
+            obj.fire("OnHealthChanged")
+            await flushMicrotasks()
+            expect(capturedValue).toBe(80)
+        })
+
+        it("multiple components subscribe to the same event independently", async () => {
+            const obj = createMockCSharpObject({ Health: 100 })
+            let value1: unknown, value2: unknown
+
+            function Component1() { value1 = useEventSync(() => (obj.proxy as any).Health, [[obj.proxy, "OnHealthChanged"]]); return null }
+            function Component2() { value2 = useEventSync(() => (obj.proxy as any).Health, [[obj.proxy, "OnHealthChanged"]]); return null }
+
+            function Parent() {
+                return React.createElement(React.Fragment, null,
+                    React.createElement(Component1),
+                    React.createElement(Component2)
+                )
+            }
+
+            const container = createMockContainer()
+            render(React.createElement(Parent), container)
+            await flushMicrotasks()
+            expect(value1).toBe(100)
+            expect(value2).toBe(100)
+            expect(obj.listenerCount("OnHealthChanged")).toBe(2)
+
+            obj.set("Health", 50)
+            obj.fire("OnHealthChanged")
+            await flushMicrotasks()
+            expect(value1).toBe(50)
+            expect(value2).toBe(50)
+        })
+    })
+})

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

@@ -108,6 +108,36 @@ describe('host-config', () => {
                 createInstance('unknown-type', {});
             }).toThrow('Unknown element type: unknown-type');
         });
+
+        it('forwards the focusable prop to the element', () => {
+            const instance = createInstance('ojs-view', { focusable: true } as TestProps);
+            expect((instance.element as unknown as { focusable: boolean }).focusable).toBe(true);
+        });
+
+        it('forwards focusable=false explicitly', () => {
+            const instance = createInstance('ojs-button', { focusable: false } as TestProps);
+            expect((instance.element as unknown as { focusable: boolean }).focusable).toBe(false);
+        });
+
+        it('does not set focusable when prop is omitted', () => {
+            const instance = createInstance('ojs-view', {});
+            expect((instance.element as unknown as { focusable?: boolean }).focusable).toBeUndefined();
+        });
+
+        it('applies disabled=true by calling SetEnabled(false)', () => {
+            const instance = createInstance('ojs-button', { disabled: true } as TestProps);
+            expect(getMockElement(instance).enabledSelf).toBe(false);
+        });
+
+        it('applies disabled=false by calling SetEnabled(true)', () => {
+            const instance = createInstance('ojs-button', { disabled: false } as TestProps);
+            expect(getMockElement(instance).enabledSelf).toBe(true);
+        });
+
+        it('leaves element enabled by default when disabled prop is omitted', () => {
+            const instance = createInstance('ojs-view', {});
+            expect(getMockElement(instance).enabledSelf).toBe(true);
+        });
     });
 
     describe('style application', () => {
@@ -302,6 +332,46 @@ describe('host-config', () => {
             expect(instance.appliedStyleKeys.has('width')).toBe(false);
             expect(instance.appliedStyleKeys.has('height')).toBe(true);
         });
+
+        it('updates focusable when the prop changes', () => {
+            const instance = createInstance('ojs-view', { focusable: false } as TestProps);
+            expect((instance.element as unknown as { focusable: boolean }).focusable).toBe(false);
+
+            commitUpdate(instance, 'ojs-view', { focusable: false } as TestProps, { focusable: true } as TestProps);
+            expect((instance.element as unknown as { focusable: boolean }).focusable).toBe(true);
+        });
+
+        it('does not clobber focusable when the prop becomes undefined', () => {
+            // Removing the prop should leave the element's current state alone,
+            // so element-specific defaults (Button etc.) remain intact.
+            const instance = createInstance('ojs-button', { focusable: true } as TestProps);
+            expect((instance.element as unknown as { focusable: boolean }).focusable).toBe(true);
+
+            commitUpdate(instance, 'ojs-button', { focusable: true } as TestProps, {} as TestProps);
+            expect((instance.element as unknown as { focusable: boolean }).focusable).toBe(true);
+        });
+
+        it('updates disabled when the prop changes', () => {
+            const instance = createInstance('ojs-button', { disabled: false } as TestProps);
+            expect(getMockElement(instance).enabledSelf).toBe(true);
+
+            commitUpdate(instance, 'ojs-button', { disabled: false } as TestProps, { disabled: true } as TestProps);
+            expect(getMockElement(instance).enabledSelf).toBe(false);
+
+            commitUpdate(instance, 'ojs-button', { disabled: true } as TestProps, { disabled: false } as TestProps);
+            expect(getMockElement(instance).enabledSelf).toBe(true);
+        });
+
+        it('restores disabled to enabled when prop is removed', () => {
+            // Unlike focusable, every VisualElement starts enabled by default,
+            // so removing `disabled={true}` must call SetEnabled(true) to
+            // restore the element rather than leaving it stuck disabled.
+            const instance = createInstance('ojs-button', { disabled: true } as TestProps);
+            expect(getMockElement(instance).enabledSelf).toBe(false);
+
+            commitUpdate(instance, 'ojs-button', { disabled: true } as TestProps, {} as TestProps);
+            expect(getMockElement(instance).enabledSelf).toBe(true);
+        });
     });
 
     describe('className management', () => {

package/src/__tests__/mocks.ts

@@ -71,6 +71,7 @@ export class MockVisualElement {
     text = '';
     value: unknown = undefined;
     label = '';
+    enabledSelf = true;
 
     constructor(csType = 'UnityEngine.UIElements.VisualElement') {
         this.__csHandle = Math.floor(Math.random() * 1000000);
@@ -117,6 +118,11 @@ export class MockVisualElement {
         this._children = [];
     }
 
+    // Enabled state
+    SetEnabled(value: boolean): void {
+        this.enabledSelf = value;
+    }
+
     // Class list methods
     AddToClassList(className: string): void {
         this._classList.add(className);
@@ -262,6 +268,7 @@ export function createMockCS() {
                 Path: {
                     Combine: (...parts: string[]) => parts.join("/"),
                     GetDirectoryName: (p: string) => p.substring(0, p.lastIndexOf("/")),
+                    IsPathRooted: (p: string) => p.startsWith("/"),
                 },
                 File: {
                     Exists: (path: string) => mockFileSystem.has(path),

package/src/hooks.ts

@@ -376,3 +376,113 @@ export function toArray<T = unknown>(collection: unknown): T[] {
     }
     return result
 }
+
+/**
+ * Event source descriptor for useEventSync: [sourceObject, eventName].
+ * The eventName should NOT include the "add_" / "remove_" prefix.
+ */
+export type EventSource = [source: object, eventName: string]
+
+/**
+ * Syncs a value from C# to React state via event subscription instead of polling.
+ * Zero work when nothing changes — the getter is only called when an event fires.
+ *
+ * Use this instead of `useFrameSync` when C# fires events on state change.
+ * `useFrameSync` polls every frame (causing GC pressure); `useEventSync` does
+ * zero work between events.
+ *
+ * **Convention form**: Derives the getter and event name from a property name.
+ * `useEventSync(source, "Health")` subscribes to `source.add_OnHealthChanged`
+ * and reads `source.Health`. The C# side must have an event named `On{Prop}Changed`.
+ *
+ * **Explicit form**: User-provided getter and event descriptors.
+ * Supports multiple event sources, static events, and derived state.
+ *
+ * If the source object can be null or change over time, pass it in deps:
+ * `useEventSync(player, "Health", [player])`
+ *
+ * Events must fire on Unity's main thread (the normal case for MonoBehaviour methods).
+ *
+ * @example
+ * // Convention: subscribes to player.add_OnHealthChanged, reads player.Health
+ * const health = useEventSync(player, "Health")
+ *
+ * @example
+ * // Convention with deps (required if source can change or start null)
+ * const health = useEventSync(currentPlayer, "Health", [currentPlayer])
+ *
+ * @example
+ * // Explicit: custom getter, multiple events
+ * const itemCount = useEventSync(
+ *     () => inventory.Items.Count,
+ *     [[inventory, "OnItemAdded"], [inventory, "OnItemRemoved"]]
+ * )
+ *
+ * @example
+ * // Explicit: static events
+ * const state = useEventSync(
+ *     () => CS.GameManager.Score,
+ *     [[CS.GameManager, "OnScoreChanged"]]
+ * )
+ */
+export function useEventSync<T>(getter: () => T, events: EventSource[], deps?: readonly unknown[]): T
+export function useEventSync(source: object, propertyName: string, deps?: readonly unknown[]): unknown
+export function useEventSync<T>(
+    sourceOrGetter: object | (() => T),
+    propOrEvents: string | EventSource[],
+    depsOrNothing?: readonly unknown[]
+): T {
+    if (typeof sourceOrGetter === "function") {
+        return useEventSyncImpl(
+            sourceOrGetter as () => T,
+            propOrEvents as EventSource[],
+            depsOrNothing ?? []
+        )
+    }
+
+    const source = sourceOrGetter
+    const propName = propOrEvents as string
+    return useEventSyncImpl(
+        () => source ? (source as any)[propName] : undefined,
+        source ? [[source, `On${propName}Changed`]] : [],
+        depsOrNothing ?? []
+    )
+}
+
+function useEventSyncImpl<T>(
+    getter: () => T,
+    events: EventSource[],
+    deps: readonly unknown[]
+): T {
+    const [value, setValue] = useState<T>(() => {
+        try { return getter() } catch { return undefined as T }
+    })
+    const getterRef = useRef(getter)
+    getterRef.current = getter
+
+    useEffect(() => {
+        try { setValue(getterRef.current()) } catch {}
+
+        const handler = () => {
+            try { setValue(getterRef.current()) } catch {}
+        }
+
+        for (const [source, eventName] of events) {
+            try {
+                const addFn = (source as any)[`add_${eventName}`]
+                if (typeof addFn === "function") addFn(handler)
+            } catch {}
+        }
+
+        return () => {
+            for (const [source, eventName] of events) {
+                try {
+                    const removeFn = (source as any)[`remove_${eventName}`]
+                    if (typeof removeFn === "function") removeFn(handler)
+                } catch {}
+            }
+        }
+    }, deps)
+
+    return value
+}

package/src/host-config.ts

@@ -303,16 +303,21 @@ const CLASS_ESCAPE_MAP: [string, string][] = [
 ];
 
 /**
- * Escape special characters in a class name for USS compatibility
+ * Escape special characters in a class name for USS compatibility.
  * Tailwind class names like "hover:bg-red-500" become "hover_c_bg-red-500"
+ * Results are cached since the same class names are used repeatedly across renders.
  */
+const _escapeCache = new Map<string, string>();
 function escapeClassName(name: string): string {
+    const cached = _escapeCache.get(name);
+    if (cached !== undefined) return cached;
     let escaped = name;
     for (const [char, replacement] of CLASS_ESCAPE_MAP) {
         if (escaped.includes(char)) {
             escaped = escaped.split(char).join(replacement);
         }
     }
+    _escapeCache.set(name, escaped);
     return escaped;
 }
 
@@ -437,14 +442,20 @@ function clearRemovedStyles(element: CSObject, oldKeys: Set<string>, newKeys: Se
     }
 }
 
-// Parse className string into a Set of escaped class names
+// Parse className string into a Set of escaped class names.
+// Results are cached since the same className strings recur across renders.
+const _parseCache = new Map<string, Set<string>>();
 function parseClassNames(className: string | undefined): Set<string> {
     if (!className) return new Set();
-    return new Set(
+    const cached = _parseCache.get(className);
+    if (cached !== undefined) return cached;
+    const result = new Set(
         className.split(/\s+/)
             .filter(Boolean)
             .map(escapeClassName)
     );
+    _parseCache.set(className, result);
+    return result;
 }
 
 // Apply className(s) to element (with escaping for Tailwind/USS compatibility)
@@ -775,7 +786,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',
+    'children', 'key', 'ref', 'style', 'className', 'pickingMode', 'focusable', 'disabled',
     'onGenerateVisualContent',
     ...Object.keys(EVENT_PROPS),
 ]);
@@ -851,6 +862,16 @@ function createInstance(type: string, props: BaseProps): Instance {
         element.pickingMode = CS.UnityEngine.UIElements.PickingMode[props.pickingMode];
     }
 
+    // Apply focusable
+    if (props.focusable !== undefined) {
+        element.focusable = props.focusable;
+    }
+
+    // Apply disabled (inverted — SetEnabled(true) means "not disabled")
+    if (props.disabled !== undefined) {
+        element.SetEnabled(!props.disabled);
+    }
+
     return instance;
 }
 
@@ -890,6 +911,24 @@ function updateInstance(instance: Instance, oldProps: BaseProps, newProps: BaseP
         }
     }
 
+    // Update focusable - only set if explicitly provided, do not override
+    // element-specific defaults (Button is focusable by default, View is not)
+    // when the prop is removed.
+    if (oldProps.focusable !== newProps.focusable && newProps.focusable !== undefined) {
+        element.focusable = newProps.focusable;
+    }
+
+    // Update disabled - unlike focusable, every VisualElement starts enabled
+    // by default, so removing the prop after a previous `disabled={true}` is
+    // expected to restore the enabled state.
+    if (oldProps.disabled !== newProps.disabled) {
+        if (newProps.disabled !== undefined) {
+            element.SetEnabled(!newProps.disabled);
+        } else {
+            element.SetEnabled(true);
+        }
+    }
+
     instance.props = newProps;
 }
 

package/src/index.ts

@@ -45,7 +45,8 @@ export type {
 export { Transform2D, useVectorContent } from './vector';
 
 // Sync Hooks & C# Interop Utilities
-export { useFrameSync, useFrameSyncWith, useThrottledSync, toArray } from './hooks';
+export { useFrameSync, useFrameSyncWith, useThrottledSync, useEventSync, toArray } from './hooks';
+export type { EventSource } from './hooks';
 
 // Types
 export type {
@@ -60,6 +61,7 @@ export type {
   DragEventData,
   GeometryEventData,
   NavigationEventData,
+  NavigationDirection,
   TransitionEventData,
   // Event handler types
   PointerEventHandler,

package/src/style-parser.ts

@@ -14,7 +14,8 @@ declare const CS: {
         UIElements: {
             Length: new (value: number, unit?: number) => CSLength;
             LengthUnit: { Pixel: number; Percent: number };
-            StyleKeyword: { Auto: number; None: number; Initial: number };
+            StyleKeyword: { Auto: number; None: number; Initial: number; Null: number };
+            StyleMaterialDefinition: new (v: unknown) => unknown;
             Angle: { Degrees: (v: number) => any; Radians: (v: number) => any; Turns: (v: number) => any; Gradians: (v: number) => any };
             Translate: new (x: any, y: any) => any;
             Rotate: new (angle: any) => any;
@@ -499,6 +500,18 @@ function parseTransformOriginStyle(value: unknown): unknown {
  * @returns Parsed value suitable for Unity UI Toolkit
  */
 export function parseStyleValue(key: string, value: unknown): unknown {
+    // `unityMaterial` is special: it can legitimately be `null` (meaning
+    // "reset to the panel default") so we can't short-circuit like the
+    // length/color paths below. Wrap in StyleMaterialDefinition either way.
+    if (key === "unityMaterial") {
+        if (value === undefined) return undefined
+        const SMD = CS.UnityEngine.UIElements.StyleMaterialDefinition
+        if (value === null) {
+            return new SMD(CS.UnityEngine.UIElements.StyleKeyword.Null)
+        }
+        return new SMD(value as any)
+    }
+
     if (value === undefined || value === null) return value
 
     // Length properties

package/src/types.ts

@@ -163,6 +163,17 @@ export interface ViewStyle {
   /** Tint color applied to the background image */
   unityBackgroundImageTintColor?: StyleColor;
 
+  /**
+   * Override the shader / material used to render the element. Accepts a
+   * Unity `Material` (typical) or a `MaterialDefinition`; `null` clears the
+   * inline override so the element falls back to the panel default.
+   *
+   * Typed loosely as `object | null` because the React layer has no reason
+   * to pin the caller to a specific C# shape — the style parser constructs
+   * a `StyleMaterialDefinition` at assignment time.
+   */
+  unityMaterial?: object | null;
+
   // Slicing
   /** 9-slice top inset */
   unitySliceTop?: number;
@@ -262,9 +273,32 @@ export interface ChangeEventData<T = unknown> {
   value: T;
 }
 
+/**
+ * Shape of the synthetic event object passed to focus / blur handlers at
+ * runtime. Matches `QuickJSBootstrap.__dispatchEvent` (see
+ * `OneJS/Resources/OneJS/QuickJSBootstrap.js.txt:980-1031`) — every synthetic
+ * event carries `target` / `currentTarget` as integer C# handles plus the
+ * propagation-control surface, and the C# bridge's `OnFocusIn` / `OnFocusOut`
+ * dispatch an empty data object, so focus events add no fields beyond the
+ * base.
+ *
+ * `relatedTarget` is intentionally absent: the C# bridge serializes `{}` for
+ * focus events and never includes it. Any code that previously depended on
+ * `e.relatedTarget` at runtime has been silently receiving `undefined`.
+ *
+ * `target` / `currentTarget` are raw C# handles, not `VisualElement` proxies.
+ * Resolve them via `CS.QuickJSNative.GetObjectByHandle(handle)` when an
+ * element reference is needed, or compare them directly against
+ * `ref.current?.__csHandle` to check element identity.
+ */
 export interface FocusEventData {
   type: string;
-  relatedTarget?: unknown;
+  target: number;
+  currentTarget: number;
+  preventDefault(): void;
+  stopPropagation(): void;
+  defaultPrevented: boolean;
+  propagationStopped: boolean;
 }
 
 export interface DragEventData {
@@ -281,9 +315,26 @@ export interface GeometryEventData {
   newRect: { x: number; y: number; width: number; height: number };
 }
 
+/**
+ * Direction values dispatched by `NavigationMoveEvent`. Mirrors
+ * `UnityEngine.UIElements.NavigationMoveEvent.Direction`, serialized to
+ * lowercase strings by the C# bridge (see `QuickJSUIBridge.OnNavigationMove`
+ * and `QuickJSBootstrap.__NAV_DIRECTION_NAMES`). `NavigationSubmitEvent` /
+ * `NavigationCancelEvent` do not carry a direction — the field is only
+ * populated for navigation-move.
+ */
+export type NavigationDirection =
+  | 'none'
+  | 'left'
+  | 'up'
+  | 'right'
+  | 'down'
+  | 'next'
+  | 'previous';
+
 export interface NavigationEventData {
   type: string;
-  direction?: string;
+  direction?: NavigationDirection;
   modifiers?: number;
 }
 
@@ -430,6 +481,29 @@ export interface BaseProps {
    */
   pickingMode?: 'Position' | 'Ignore';
 
+  // Focus
+  /**
+   * Whether this element can receive focus.
+   * Maps directly to `VisualElement.focusable` in Unity UI Toolkit.
+   *
+   * Default is element-specific (e.g. Button is focusable by default, View is not).
+   * Setting this to `true` makes the element a focus target for keyboard/gamepad
+   * navigation and enables `NavigationMoveEvent`/`NavigationSubmitEvent` routing.
+   */
+  focusable?: boolean;
+
+  // Enabled state
+  /**
+   * Whether this element is disabled. When `true`, the reconciler calls
+   * `VisualElement.SetEnabled(false)` on the underlying C# element, which
+   * applies the `:disabled` USS pseudo-class, blocks pointer events, and
+   * prevents the element and its descendants from receiving focus.
+   *
+   * Removing the prop (or setting it to `false`) restores the element to
+   * `SetEnabled(true)`. Every VisualElement starts enabled by default.
+   */
+  disabled?: boolean;
+
   // Vector drawing
   /**
    * Callback for custom vector drawing via Unity's generateVisualContent.
@@ -572,6 +646,7 @@ export interface VisualElement extends RenderContainer {
   visible: boolean;
   enabledSelf: boolean;
   enabledInHierarchy: boolean;
+  SetEnabled: (value: boolean) => void;
 
   // Text content (for TextElement-derived types)
   text?: string;