@box3lab/react-ui 0.0.1

package/README.md

@@ -0,0 +1,89 @@
+## 神岛 React（实验版）
+
+提供一个适用于 **神岛 Arena 客户端 UI** 的 React 渲染器（实验版）。
+
+- 基于官方 `react` 实现
+- 使用 JSX 描述 UI，通过自定义渲染器映射到神岛 UI
+
+React 中文官网：https://zh-hans.react.dev/
+
+### 安装
+
+```sh
+npm install @box3lab/react-ui
+```
+
+`@box3lab/react-ui` 导出结构：
+
+- `@box3lab/react-ui`：内置 UI 元素组件（`Box`、`Text`、`Image`...）
+- `@box3lab/react-ui/dom`：渲染入口（`createRoot` 等）
+
+### 基本用法
+
+```tsx
+import React, { useState } from 'react';
+import { Box, Text } from '@box3lab/react-ui';
+import { createRoot } from '@box3lab/react-ui/dom';
+
+function App() {
+  const [count, setCount] = useState(0);
+
+  return (
+    <Box
+      style={{
+        backgroundOpacity: 0.6,
+        position: {
+          offset: Vec2.create({ x: 0, y: 0 }),
+          size: Vec2.create({ x: 0, y: 0 }),
+        },
+      }}
+      onClick={() => setCount((c: number) => c + 1)}
+    >
+      <Text>你好，React！你点我了 {count} 次</Text>
+    </Box>
+  );
+}
+
+// ui 由宿主环境（神岛 Arena）提供，对应根 UI 节点
+const root = createRoot(ui);
+root.render(<App />);
+```
+
+### 内置元素组件（Intrinsic Elements）
+
+这些组件会通过自定义渲染器映射到对应的 Box3 UI 元素：
+
+- `Box`：基础容器
+- `Text`：文本显示，`children` 会自动映射到 `textContent`
+- `Image`：图片元素，支持 `onLoad` 等事件
+- `Input`：输入框，支持 `onFocus` / `onBlur` 等事件
+- `ScrollBox`：滚动容器
+
+示例：
+
+```tsx
+import { Box, Text, Image, Input, ScrollBox } from '@box3lab/react-ui';
+```
+
+### TypeScript 支持
+
+该包基于 TypeScript 编写，并提供完整的类型信息：
+
+- 组件 props 里会自动推导底层 `UiBox` / `UiText` / `UiInput` / `UiImage` / `UiScrollBox` 类型
+- 事件参数类型为 `UiEvent<T>`，可以获得更好的开发体验
+
+在你的项目中开启 JSX 支持（以 React JSX 为例）：
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "jsx": "react",
+  },
+}
+```
+
+### 注意事项
+
+- 本项目目前为 **实验版**，API 可能在后续版本中发生变动
+- 仅适用于神岛 Arena 提供的 UI 运行环境，无法在普通浏览器中直接使用

package/dist/client/src/elements.d.ts

@@ -0,0 +1,100 @@
+import React from 'react';
+/**
+ * 通用 UI 元素属性定义，抽象出所有控件共享的基础能力
+ */
+type CommonElementProps<T> = {
+    name?: string;
+    style?: Omit<Partial<T>, 'position' | 'size'> & {
+        /** 位置配置 */
+        position?: {
+            /** X/Y偏移量 */
+            offset?: Vec2;
+            /** 宽高缩放比例 */
+            size?: Vec2;
+        };
+        /** 尺寸配置 */
+        size?: {
+            /** 尺寸偏移量 */
+            offset?: Vec2;
+            /** 尺寸缩放比例 */
+            size?: Vec2;
+        };
+    };
+    /** 点击事件处理器 */
+    onClick?: (event: UiEvent<T>) => void;
+    /** 鼠标按下事件处理器 */
+    onMouseDown?: (event: UiEvent<T>) => void;
+    /** 鼠标释放事件处理器 */
+    onMouseUp?: (event: UiEvent<T>) => void;
+    /** 元素挂载完成回调 */
+    onMount?: (element: T) => void;
+    /** 元素卸载前回调 */
+    onUnmount?: (element: T) => void;
+    /** 元素引用，获取底层DOM实例 */
+    ref?: ((element: T) => void) | {
+        current: T | null;
+    };
+};
+/**
+ * 组件 props = UiX 自身的可选属性 + 公共 CommonElementProps<T> 属性
+ */
+type BaseUiProps<T> = React.PropsWithChildren<CommonElementProps<T>>;
+/**
+ * Input 组件专用 props，基于基础 UI 属性扩展输入框相关事件
+ */
+type InputProps = BaseUiProps<UiInput> & {
+    /** 获得焦点事件处理器 */
+    onFocus?: (event: UiEvent<UiInput>) => void;
+    /** 失去焦点事件处理器 */
+    onBlur?: (event: UiEvent<UiInput>) => void;
+};
+/**
+ * Image 组件专用 props，基于基础 UI 属性扩展图片相关事件
+ */
+type ImageProps = BaseUiProps<UiImage> & {
+    /** 图片加载完成事件处理器 */
+    onLoad?: (event: UiEvent<UiImage>) => void;
+};
+/**
+ * Box：基础容器组件，对应底层 UiBox
+ */
+export declare function Box(props: BaseUiProps<UiBox>): React.ReactElement<CommonElementProps<UiBox> & {
+    children?: React.ReactNode | undefined;
+}, string | React.JSXElementConstructor<any>>;
+/**
+ * Text：文本组件，对应底层 UiText
+ * 会把 children 转成 textContent 传给宿主环境
+ */
+export declare function Text(props: BaseUiProps<UiText>): React.ReactElement<CommonElementProps<UiText> & {
+    children?: React.ReactNode | undefined;
+} & {
+    textContent?: string;
+    size?: Coord2;
+}, string | React.JSXElementConstructor<any>>;
+/**
+ * Image：图片组件，对应底层 UiImage
+ */
+export declare function Image(props: ImageProps): React.ReactElement<CommonElementProps<UiImage> & {
+    children?: React.ReactNode | undefined;
+} & {
+    /** 图片加载完成事件处理器 */
+    onLoad?: (event: UiEvent<UiImage>) => void;
+}, string | React.JSXElementConstructor<any>>;
+/**
+ * Input：输入框组件，对应底层 UiInput
+ */
+export declare function Input(props: InputProps): React.ReactElement<CommonElementProps<UiInput> & {
+    children?: React.ReactNode | undefined;
+} & {
+    /** 获得焦点事件处理器 */
+    onFocus?: (event: UiEvent<UiInput>) => void;
+    /** 失去焦点事件处理器 */
+    onBlur?: (event: UiEvent<UiInput>) => void;
+}, string | React.JSXElementConstructor<any>>;
+/**
+ * ScrollBox：可滚动容器组件，对应底层 UiScrollBox
+ */
+export declare function ScrollBox(props: BaseUiProps<UiScrollBox>): React.ReactElement<CommonElementProps<UiScrollBox> & {
+    children?: React.ReactNode | undefined;
+}, string | React.JSXElementConstructor<any>>;
+export {};

package/dist/client/src/elements.js

@@ -0,0 +1,39 @@
+import React from 'react';
+/**
+ * Box：基础容器组件，对应底层 UiBox
+ */
+export function Box(props) {
+    return React.createElement('Box', props);
+}
+/**
+ * Text：文本组件，对应底层 UiText
+ * 会把 children 转成 textContent 传给宿主环境
+ */
+export function Text(props) {
+    const { children, ...rest } = props;
+    const nextProps = {
+        ...rest,
+    };
+    if (children) {
+        nextProps.textContent = children.toString();
+    }
+    return React.createElement('Text', nextProps);
+}
+/**
+ * Image：图片组件，对应底层 UiImage
+ */
+export function Image(props) {
+    return React.createElement('Image', props);
+}
+/**
+ * Input：输入框组件，对应底层 UiInput
+ */
+export function Input(props) {
+    return React.createElement('Input', props);
+}
+/**
+ * ScrollBox：可滚动容器组件，对应底层 UiScrollBox
+ */
+export function ScrollBox(props) {
+    return React.createElement('ScrollBox', props);
+}

package/dist/client/src/hostConfig.d.ts

@@ -0,0 +1,45 @@
+type Type = 'Box' | 'Text' | 'Image' | 'Input' | 'ScrollBox';
+type Props = Record<string, unknown>;
+type Container = UiScreen;
+type Instance = UiElement;
+type TextInstance = never;
+type PublicInstance = Instance;
+type HostContext = object;
+type UpdatePayload = Record<string, unknown> | null;
+declare const hostConfig: {
+    now: () => number;
+    supportsMutation: boolean;
+    supportsPersistence: boolean;
+    supportsHydration: boolean;
+    scheduleTimeout: typeof setTimeout;
+    cancelTimeout: typeof clearTimeout;
+    noTimeout: number;
+    isPrimaryRenderer: boolean;
+    warnsIfNotActing: boolean;
+    supportsMicrotasks: boolean;
+    scheduleMicrotask: (callback: () => void) => void;
+    getRootHostContext(): HostContext;
+    getChildHostContext(parentHostContext: HostContext): HostContext;
+    shouldSetTextContent(): boolean;
+    createInstance(type: Type, props: Props): Instance;
+    createTextInstance(): TextInstance;
+    appendInitialChild(parentInstance: Instance, child: Instance): void;
+    finalizeInitialChildren(): boolean;
+    prepareUpdate(instance: Instance, type: Type, oldProps: Props, newProps: Props): UpdatePayload;
+    commitUpdate(instance: Instance, updatePayload: UpdatePayload, _type: Type, oldProps: Props, newProps: Props): void;
+    appendChild(parentInstance: Instance, child: Instance): void;
+    appendChildToContainer(container: Container, child: Instance): void;
+    removeChild(parentInstance: Instance, child: Instance): void;
+    removeChildFromContainer(container: Container, child: Instance): void;
+    clearContainer(): void;
+    prepareForCommit(): unknown;
+    resetAfterCommit(): void;
+    getPublicInstance(instance: Instance): PublicInstance;
+    commitTextUpdate(): void;
+    resetTextContent(): void;
+    hideInstance(): void;
+    hideTextInstance(): void;
+    unhideInstance(): void;
+    unhideTextInstance(): void;
+};
+export default hostConfig;

package/dist/client/src/hostConfig.js

@@ -0,0 +1,296 @@
+// 保存每个节点的生命周期回调
+const nodeLifecycleCallbacks = new WeakMap();
+// 记录已经触发过 onMount 的节点，避免重复调用
+const mountedNodes = new WeakSet();
+// 辅助：处理 Coord2（position / size）
+function applyCoordProperty(nodeCoord, styleCoord) {
+    if (!styleCoord) {
+        return;
+    }
+    // 处理偏移
+    if (styleCoord.offset) {
+        if (typeof styleCoord.offset.copy === 'function') {
+            nodeCoord.offset.copy(styleCoord.offset);
+        }
+        else if (typeof styleCoord.offset === 'object') {
+            nodeCoord.offset.x = styleCoord.offset.x ?? nodeCoord.offset.x;
+            nodeCoord.offset.y = styleCoord.offset.y ?? nodeCoord.offset.y;
+        }
+    }
+    // 处理缩放
+    if (styleCoord.scale) {
+        if (typeof styleCoord.scale.copy === 'function') {
+            nodeCoord.scale.copy(styleCoord.scale);
+        }
+        else if (typeof styleCoord.scale === 'object') {
+            nodeCoord.scale.x = styleCoord.scale.x ?? nodeCoord.scale.x;
+            nodeCoord.scale.y = styleCoord.scale.y ?? nodeCoord.scale.y;
+        }
+    }
+}
+// 事件处理器缓存：用于在更新时解绑旧的监听器
+const nodeEventHandlers = new WeakMap();
+// React 风格事件名到底层 UI 事件名的映射
+const eventNameMap = {
+    onClick: 'pointerdown',
+    onMouseDown: 'pointerdown',
+    onMouseUp: 'pointerup',
+    onFocus: 'focus',
+    onBlur: 'blur',
+    onLoad: 'load',
+};
+// 辅助：处理颜色 Vec3（xxxColor）
+function applyColorProperty(nodeColor, styleColor) {
+    if (!styleColor) {
+        return;
+    }
+    if (typeof styleColor.copy === 'function') {
+        nodeColor.copy(styleColor);
+    }
+    else if (typeof styleColor === 'object' &&
+        'r' in styleColor &&
+        'g' in styleColor &&
+        'b' in styleColor) {
+        nodeColor.r = styleColor.r;
+        nodeColor.g = styleColor.g;
+        nodeColor.b = styleColor.b;
+    }
+}
+function applyProps(instance, _oldProps, newProps) {
+    const target = instance;
+    // 1. 先单独处理 style
+    const styleProp = newProps.style;
+    if (styleProp && typeof styleProp === 'object') {
+        const style = styleProp;
+        // 先处理 position / size 这类复合属性
+        if (style.position && 'position' in instance) {
+            applyCoordProperty(instance.position, style.position);
+        }
+        if (style.size && 'size' in instance) {
+            applyCoordProperty(instance.size, style.size);
+        }
+        // 处理其余样式字段
+        for (const styleKey in style) {
+            const styleValue = style[styleKey];
+            // 已在上面单独处理
+            if (styleKey === 'position' || styleKey === 'size') {
+                continue;
+            }
+            // 如果实例上没有这个字段，跳过
+            if (!(styleKey in target)) {
+                continue;
+            }
+            const targetField = target[styleKey];
+            if (styleValue && typeof styleValue === 'object') {
+                // 颜色属性：xxxColor
+                if (styleKey.toLowerCase().includes('color') &&
+                    typeof targetField === 'object') {
+                    applyColorProperty(targetField, styleValue);
+                }
+                else if (targetField &&
+                    typeof targetField === 'object' &&
+                    typeof targetField.copy === 'function') {
+                    // 具有 copy 方法的对象（Vec2 / Vec3 等）
+                    targetField.copy(styleValue);
+                }
+                else if (targetField && typeof targetField === 'object') {
+                    // 其他对象，做浅合并
+                    Object.assign(targetField, styleValue);
+                }
+                else {
+                    // 否则直接赋值
+                    target[styleKey] = styleValue;
+                }
+            }
+            else {
+                // 简单类型直接赋值
+                target[styleKey] = styleValue;
+            }
+        }
+    }
+    // 2. 再处理除 style 以外的普通 props
+    for (const key in newProps) {
+        if (key === 'style' || key === 'children' || key === 'ref') {
+            continue;
+        }
+        if (key.startsWith('on')) {
+            continue;
+        }
+        const value = newProps[key];
+        if (key in target) {
+            target[key] = value;
+        }
+    }
+    // 3. 处理事件 props（onClick / onMouseDown / onMouseUp）
+    const node = instance;
+    const eventsHost = node.events;
+    if (eventsHost && typeof eventsHost === 'object') {
+        // 先解绑旧的事件监听器
+        const prevHandlers = nodeEventHandlers.get(node);
+        if (prevHandlers) {
+            for (const [eventName, handler] of Object.entries(prevHandlers)) {
+                if (typeof eventsHost.off === 'function') {
+                    eventsHost.off(eventName, handler);
+                }
+                else if (typeof eventsHost.remove === 'function') {
+                    eventsHost.remove(eventName, handler);
+                }
+            }
+        }
+        const nextHandlers = {};
+        for (const key in newProps) {
+            if (!key.startsWith('on')) {
+                continue;
+            }
+            const handler = newProps[key];
+            if (typeof handler !== 'function') {
+                continue;
+            }
+            const eventName = eventNameMap[key] || key.toLowerCase().substring(2);
+            if (typeof eventsHost.on === 'function') {
+                eventsHost.on(eventName, handler);
+                nextHandlers[eventName] = handler;
+            }
+        }
+        if (Object.keys(nextHandlers).length > 0) {
+            nodeEventHandlers.set(node, nextHandlers);
+        }
+        else {
+            nodeEventHandlers.delete(node);
+        }
+    }
+    // 4. 处理生命周期回调（onMount / onUnmount）
+    const lifecycle = nodeLifecycleCallbacks.get(node) ?? {};
+    if (typeof newProps.onMount === 'function') {
+        lifecycle.onMount = newProps.onMount;
+    }
+    if (typeof newProps.onUnmount === 'function') {
+        lifecycle.onUnmount = newProps.onUnmount;
+    }
+    if (lifecycle.onMount || lifecycle.onUnmount) {
+        nodeLifecycleCallbacks.set(node, lifecycle);
+    }
+    // 首次挂载后异步触发 onMount，避免在尚未完全挂载时执行用户回调
+    if (!mountedNodes.has(node) && lifecycle.onMount) {
+        mountedNodes.add(node);
+        const { onMount } = lifecycle;
+        setTimeout(() => {
+            // 确保节点仍然挂在树上再调用回调
+            if (node.parent && onMount) {
+                onMount(node);
+            }
+        }, 0);
+    }
+}
+// 辅助：执行 onUnmount 并清理生命周期相关状态
+function callUnmountLifecycle(node) {
+    const lifecycle = nodeLifecycleCallbacks.get(node);
+    if (lifecycle?.onUnmount) {
+        lifecycle.onUnmount(node);
+    }
+    nodeLifecycleCallbacks.delete(node);
+    mountedNodes.delete(node);
+    nodeEventHandlers.delete(node);
+}
+// HostConfig 仅在运行时被 react-reconciler 使用，这里让 TS 按对象字面量推断类型，避免显式 any
+const hostConfig = {
+    // 时间相关能力，给 React 调度使用
+    now: Date.now,
+    // 采用 mutation 模式（直接修改现有节点）
+    supportsMutation: true,
+    // 不使用持久化 / Hydration，这里显式关闭
+    supportsPersistence: false,
+    supportsHydration: false,
+    // 定时器调度：React 18 在某些场景会调用这些方法
+    scheduleTimeout: setTimeout,
+    cancelTimeout: clearTimeout,
+    noTimeout: -1,
+    // 其它运行时能力标志
+    isPrimaryRenderer: true,
+    warnsIfNotActing: false,
+    supportsMicrotasks: true,
+    scheduleMicrotask: (callback) => {
+        // 使用 Promise 模拟 microtask 队列
+        Promise.resolve().then(callback);
+    },
+    getRootHostContext() {
+        return {};
+    },
+    getChildHostContext(parentHostContext) {
+        return parentHostContext;
+    },
+    shouldSetTextContent() {
+        return false;
+    },
+    createInstance(type, props) {
+        let node;
+        switch (type) {
+            case 'Box':
+                node = UiBox.create();
+                break;
+            case 'Text':
+                node = UiText.create();
+                break;
+            case 'Image':
+                node = UiImage.create();
+                break;
+            case 'Input':
+                node = UiInput.create();
+                break;
+            case 'ScrollBox':
+                node = UiScrollBox.create();
+                break;
+            default:
+                throw new Error(`Unknown type: ${type}`);
+        }
+        applyProps(node, {}, props);
+        return node;
+    },
+    createTextInstance() {
+        throw new Error('Text nodes are not supported; use <Text> component instead.');
+    },
+    appendInitialChild(parentInstance, child) {
+        child.parent = parentInstance;
+    },
+    finalizeInitialChildren() {
+        return false;
+    },
+    prepareUpdate(instance, type, oldProps, newProps) {
+        return newProps;
+    },
+    commitUpdate(instance, updatePayload, _type, oldProps, newProps) {
+        if (!updatePayload) {
+            return;
+        }
+        applyProps(instance, oldProps, newProps);
+    },
+    appendChild(parentInstance, child) {
+        child.parent = parentInstance;
+    },
+    appendChildToContainer(container, child) {
+        child.parent = container;
+    },
+    removeChild(parentInstance, child) {
+        callUnmountLifecycle(child);
+        child.parent = undefined;
+    },
+    removeChildFromContainer(container, child) {
+        callUnmountLifecycle(child);
+        child.parent = undefined;
+    },
+    clearContainer() { },
+    prepareForCommit() {
+        return null;
+    },
+    resetAfterCommit() { },
+    getPublicInstance(instance) {
+        return instance;
+    },
+    commitTextUpdate() { },
+    resetTextContent() { },
+    hideInstance() { },
+    hideTextInstance() { },
+    unhideInstance() { },
+    unhideTextInstance() { },
+};
+export default hostConfig;

package/dist/client/src/reconciler.d.ts

@@ -0,0 +1,3 @@
+import ReactReconciler from 'react-reconciler';
+declare const reconciler: ReactReconciler.Reconciler<unknown, unknown, unknown, unknown, unknown, unknown>;
+export default reconciler;

package/dist/client/src/reconciler.js

@@ -0,0 +1,4 @@
+import ReactReconciler from 'react-reconciler';
+import hostConfig from './hostConfig';
+const reconciler = ReactReconciler(hostConfig);
+export default reconciler;

package/dist/client/src/renderer.d.ts

@@ -0,0 +1,13 @@
+import type React from 'react';
+/**
+ * createRoot：在指定的 UI 节点上创建一个 React 根容器
+ */
+export declare function createRoot(container: UiNode): {
+    render(element: React.ReactNode): void;
+};
+/**
+ * render：一个简单的快捷方法，等价于 createRoot(container).render(element)
+ */
+export declare function render(element: React.ReactNode, container: UiNode): {
+    render(element: React.ReactNode): void;
+};

package/dist/client/src/renderer.js

@@ -0,0 +1,23 @@
+import reconciler from './reconciler';
+/**
+ * createRoot：在指定的 UI 节点上创建一个 React 根容器
+ */
+export function createRoot(container) {
+    const createContainer = reconciler.createContainer;
+    const root = createContainer(container, 0, null, false, null, '', () => null, null);
+    // 返回一个带有 render 方法的对象，兼容 React 18 的 root API
+    return {
+        // 调用时会触发一次完整的协调与渲染
+        render(element) {
+            reconciler.updateContainer(element, root, null, () => null);
+        },
+    };
+}
+/**
+ * render：一个简单的快捷方法，等价于 createRoot(container).render(element)
+ */
+export function render(element, container) {
+    const root = createRoot(container);
+    root.render(element);
+    return root;
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@box3lab/react-ui",
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "dev": "npm-run-all -p dev:*",
+    "build": "npm-run-all build:*",
+    "tsc": "npm-run-all -p tsc:*",
+    "tsc:check": "npm-run-all tsc:check:*",
+    "eslint:fix": "eslint --fix",
+    "prettier:write": "prettier . --write",
+    "tsc:client": "tsc -p client/tsconfig.json",
+    "tsc:server": "tsc -p server/tsconfig.json",
+    "tsc:check:client": "tsc -noEmit -p client/tsconfig.json",
+    "tsc:check:server": "tsc -noEmit -p server/tsconfig.json",
+    "dev:server": "cross-env VITE_BUILD_TARGET=server vite build --mode development --watch",
+    "dev:client": "cross-env  VITE_BUILD_TARGET=client vite build --mode development --watch",
+    "build:server": "cross-env VITE_BUILD_TARGET=server vite build --mode production",
+    "build:client": "cross-env  VITE_BUILD_TARGET=client vite build --mode production",
+    "debug:server": "cross-env VITE_BUILD_TARGET=server vite build --mode debug",
+    "debug:client": "cross-env VITE_BUILD_TARGET=client vite build --mode debug",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.2",
+    "@types/react": "^19.2.7",
+    "@types/react-reconciler": "^0.32.3",
+    "cross-env": "^10.1.0",
+    "eslint": "^9.39.2",
+    "husky": "^9.1.7",
+    "npm-run-all": "^4.1.5",
+    "prettier": "^3.7.4",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.49.0",
+    "vite": "^5.4.21",
+    "vite-plugin-arenapro-script": "^0.2.8",
+    "vite-plugin-checker": "^0.11.0",
+    "vite-tsconfig-paths": "^5.1.4"
+  },
+  "dependencies": {
+    "react": "18.3.1",
+    "react-reconciler": "^0.29.2"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/client/src/elements.js",
+      "types": "./dist/client/src/elements.d.ts"
+    },
+    "./dom": {
+      "import": "./dist/client/src/renderer.js",
+      "types": "./dist/client/src/renderer.d.ts"
+    }
+  },
+  "files": [
+    "dist/**/*"
+  ]
+}