@ek-aiot/2d-editor-react

React 壳层包。本包已提供可订阅的 editor controller + hooks、CanvasHost stage bridge、顶部 toolbar、window hotkeys、JSON/PNG 导入导出、MaterialPanel、RightSidebar 和节点属性面板， 用于把 @ek-aiot/2d-editor-core 的 headless state/actions 接入 React 渲染生命周期。

安装与使用

本包为 ESM-only library，依赖 Vite library build 产物。真正发布到 npm 前会在后续发布单元做 registry preflight。

1) 完整 React 壳层入口

import { ReactEditorShell } from "@ek-aiot/2d-editor-react";
import "@ek-aiot/2d-editor-react/style.css";

export function App() {
  return <ReactEditorShell style={{ width: 800, height: 600 }} hotkeys />;
}

ReactEditorShell 会创建 controller/provider，渲染 toolbar + CanvasHost，并在内部持有 StageHandle ref。编辑动作走 controller action；zoom/reset/fit 和 PNG 导出走 stage handle。

编辑模式默认渲染 full layout：左侧物料、中央画布、右侧属性。display 模式默认 canvas-only；如果宿主显式传入 layout={EditorLayout.FULL}，侧栏只读展示，所有写入 handler 仍会 no-op。

内置物料目录只包含基础形状/文本，不把资产写入 core 或导出文档。宿主可通过 materials 传入运行时物料，并通过 materialMergeStrategy="append" | "replace" 控制合并方式。

本仓库内置 React playground，可直接验证完整壳层：

pnpm dev:react

apps/react-playground 直接消费 workspace source 和本包源 CSS，不需要先构建 dist。默认 pnpm dev 仍然启动 Vue playground。

2) controller + hooks（自定义 UI 的唯一读写入口）

import React from "react";
import {
  EditorControllerProvider,
  createEditorController,
  useEditorController,
  useEditorSnapshot,
} from "@ek-aiot/2d-editor-react";

const controller = createEditorController();

function Toolbar() {
  const snapshot = useEditorSnapshot();
  const controller = useEditorController();

  return (
    <button onClick={() => controller.actions.undo()} disabled={!snapshot.capabilities.canUndo}>
      Undo
    </button>
  );
}

export function App() {
  return (
    <EditorControllerProvider controller={controller}>
      <Toolbar />
    </EditorControllerProvider>
  );
}

当前能力

• 提供包名/exports/peerDependencies/build/typecheck/test 的完整 scaffold
• 提供可订阅的 createEditorController（snapshot + subscribe + actions）
• 提供 React 侧注入与订阅：EditorControllerProvider、useEditorController、useEditorSnapshot
• 提供 CanvasHost，把 controller snapshot 同步到 core StageHandle
• 提供 ReactEditorShell、EditorToolbar 和 useEditorHotkeys
• Toolbar 覆盖工具切换、undo/redo、内部 clipboard、delete、JSON 导入导出、PNG 导出和视图控制
• MaterialPanel 覆盖 React-local 基础物料、宿主物料合并和 material drag payload
• RightSidebar 覆盖画布/snapping、节点外观/几何、图层、多选、管道样式、设备/数据绑定和运行态规则
• draft 输入遵循 focus/input/blur/Enter/Escape 行为，并在选择或只读态变化时同步回 snapshot
• 提供稳定的 CSS 出口：@ek-aiot/2d-editor-react/style.css
• 提供 apps/react-playground 作为本地浏览器验证面，覆盖 mode/layout/hotkeys/bindingValues/materials/materialMergeStrategy/sample reset

行为边界

• Clipboard 是 headless 内部内存 clipboard，不对接系统 clipboard。
• Hotkeys 默认在 window 上监听；hotkeys={false} 可关闭。
• display / preview 等非 edit mode 会禁用编辑 toolbar 与编辑 hotkeys，但保留 zoom/reset/fit/PNG。
• 面板写入只通过 controller actions 进入 core；React 组件不导入 Vue store、Pinia action 或 core 私有 mutator。
• editable=false 时控件 disabled，事件 handler 同样 guard，避免测试或脚本触发写入。
• JSON import 使用 core schema parser 校验，并在覆盖前调用 window.confirm。
• PNG 导出错误会透传 core/stage Error.message，常见 CORS/画布尺寸错误由 core 生成。
• download、filename、messages 等工具保持包内私有，不作为 public API。

非目标

• 不提供浏览器截图/GIF 自动回归或发布流水线校验
• 不把 material catalog、运行态状态或 UI messages 写入 EditorDocument
• 不公开面板内部 draft hooks；自定义 UI 应继续通过 controller + hooks 读写
• 不依赖 vue / pinia，也不依赖 @ek-aiot/2d-editor（Vue 壳层）

依赖边界

• react / react-dom / konva：peerDependencies（由宿主应用提供）
• @ek-aiot/2d-editor-agent：dependency（共享 Agent 客户端与工具端口契约）
• @ek-aiot/2d-editor-core：dependency（随包安装）