npm package: @huanban/rulego-editor-react
Description: RuleGo 编辑器 React 适配层 - WorkflowList / WorkflowInfoPanel / RuleGoEditor 独立组件 + Hooks
Author: HuanBan Team
Latest version: 1.1.0

# @huanban/rulego-editor-react

> RuleGo 规则链编辑器 React 适配层 — 薄封装 `HuanbanRulegoEditor`，提供 React 组件 + Hooks

[![npm version](https://img.shields.io/npm/v/@huanban/rulego-editor-react.svg)](https://www.npmjs.com/package/@huanban/rulego-editor-react)
[![license](https://img.shields.io/npm/l/@huanban/rulego-editor-react.svg)](https://github.com/openclaw/rulego-editor/blob/main/LICENSE)

## 设计理念

**React 版是 `@huanban/rulego-editor-core` 的薄封装**，不重写任何编辑器逻辑。所有功能（工具栏、侧边栏、右键菜单、属性面板、小地图等）都由 core 包的 `HuanbanRulegoEditor` 提供，React 版只做：

1. 生命周期管理（挂载时创建实例、卸载时销毁）
2. React Hooks 封装（方便在函数组件中使用）
3. Props → Options 的桥接

## 📦 安装

```bash
npm install @huanban/rulego-editor-react
# 或
pnpm add @huanban/rulego-editor-react
```

> **自动安装的依赖：** `@huanban/rulego-editor-core`、`@logicflow/core`、`@logicflow/extension`
> **需要宿主项目提供：** `react >= 16.8`、`react-dom >= 16.8`

---

## 样式引入

**一行搞定所有样式**（logicflow 基础样式 + 扩展样式 + 编辑器组件样式）：

```tsx
import '@huanban/rulego-editor-react/style.css'
```

---

## 组件一览

| 组件 | 用途 | 说明 |
|------|------|------|
| `RuleGoEditor` | 规则链编辑器 | 完整的可视化编辑器（内置工具栏、侧边栏、属性面板等全部 UI）|
| `WorkflowList` | 工作流列表 | 展示所有规则链，支持搜索、创建、删除 |
| `WorkflowInfoPanel` | 工作流信息面板 | 展示单条链的详细信息和配置 |

---

## 一、RuleGoEditor — 规则链编辑器

完整的可视化规则链编辑器，**内置全部 UI**，只需传入 `apiBase` + `data` 即可。

### 基本用法

```tsx
import { RuleGoEditor } from '@huanban/rulego-editor-react'
import '@huanban/rulego-editor-react/style.css'

function EditorPage({ chainId }: { chainId: string }) {
  const [chainData, setChainData] = useState(null)

  useEffect(() => {
    fetch(`http://localhost:9090/api/v1/rule-chains/${chainId}`)
      .then(res => res.json())
      .then(data => setChainData(data))
  }, [chainId])

  return (
    <RuleGoEditor
      apiBase="http://localhost:9090/api/v1"
      data={chainData}
      height="100vh"
    />
  )
}
```

### 内置功能（无需额外配置）

| 功能 | 说明 |
|------|------|
| 工具栏 | 保存、撤销/重做、部署、运行、导入/导出、主题切换、语言切换 |
| 组件侧边栏 | 按分类展示节点组件，支持搜索（拼音搜索）和拖拽添加 |
| 右键菜单 | 节点/边/画布右键菜单（复制、删除、查看属性等）|
| 节点属性面板 | 点击节点弹出属性编辑 Drawer，含 CodeMirror 代码编辑器 |
| 边属性面板 | 点击连线弹出路由关系编辑 Drawer |
| 小地图 | 全局视图鸟瞰 |
| 键盘快捷键 | Ctrl+S 保存 / Ctrl+Z 撤销 / Ctrl+C/V 复制粘贴 |
| 调试面板 | WebSocket 实时日志 |

### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `data` | `RuleChainData \| null` | `null` | 规则链数据 |
| `apiBase` | `string` | - | 后端 API 地址（如 `http://localhost:9090/api/v1`）|
| `theme` | `string` | `'modern'` | 主题：`classic` / `dark` / `nature` / `elegant` / `tech` / `modern` |
| `lang` | `string` | `'zh-CN'` | 语言：`zh-CN` / `en-US` |
| `toolbarTitle` | `string` | - | 工具栏标题 |
| `showChainInfo` | `boolean` | `true` | 是否显示链信息头部 |
| `height` | `string \| number` | `'100%'` | 编辑器高度 |
| `width` | `string \| number` | `'100%'` | 编辑器宽度 |
| `className` | `string` | `''` | 自定义 className |
| `style` | `CSSProperties` | `{}` | 自定义样式 |
| `onReady` | `({ core, lf }) => void` | - | 编辑器就绪回调 |
| `onNodeClick` | `(node) => void` | - | 节点点击回调 |
| `onNodeDbClick` | `(node) => void` | - | 节点双击回调 |
| `onEdgeClick` | `(edge) => void` | - | 边点击回调 |
| `onSaveSuccess` | `(data) => void` | - | 保存成功回调 |
| `onDeploySuccess` | `() => void` | - | 部署成功回调 |

---

## 二、WorkflowList — 工作流列表

展示所有规则链，支持搜索、分页、创建、删除、编辑跳转。

### 基本用法

```tsx
import { WorkflowList } from '@huanban/rulego-editor-react'
import '@huanban/rulego-editor-react/style.css'

function WorkflowPage() {
  return (
    <WorkflowList
      apiBase="http://localhost:9090/api/v1"
      onEdit={(item) => {
        window.location.href = `/editor/${item.id}`
      }}
    />
  )
}
```

### Props

| 属性 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `apiBase` | `string` | ✅ | 后端 API 地址 |
| `onEdit` | `(item: WorkflowItem) => void` | ❌ | 点击"编辑"按钮的回调 |
| `customRoutes` | `RuleChainRoutes` | ❌ | 自定义 API 路由映射 |
| `customIcons` | `WorkflowListIcons` | ❌ | 自定义图标 |
| `theme` | `WorkflowTheme` | ❌ | 自定义主题色 |

---

## 三、WorkflowInfoPanel — 工作流信息面板

展示单条规则链的详细信息、配置参数、集成地址等。

### 基本用法

```tsx
import { WorkflowInfoPanel } from '@huanban/rulego-editor-react'
import '@huanban/rulego-editor-react/style.css'

function InfoPage({ workflowItem }) {
  return (
    <WorkflowInfoPanel
      apiBase="http://localhost:9090/api/v1"
      workflowItem={workflowItem}
      onRefresh={() => { /* 重新加载数据 */ }}
    />
  )
}
```

### Props

| 属性 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `apiBase` | `string` | ✅ | 后端 API 地址 |
| `workflowItem` | `WorkflowItem` | ✅ | 工作流数据 |
| `onRefresh` | `() => void` | ❌ | 刷新回调 |
| `extraTabs` | `ExtraTab[]` | ❌ | 自定义扩展 Tab |
| `customRoutes` | `RuleChainRoutes` | ❌ | 自定义 API 路由 |
| `customIcons` | `WorkflowInfoIcons` | ❌ | 自定义图标 |
| `theme` | `WorkflowTheme` | ❌ | 自定义主题色 |

---

## 四、完整项目示例

三个组件组合使用：

```tsx
import { useState, useEffect } from 'react'
import { WorkflowList, RuleGoEditor, WorkflowInfoPanel } from '@huanban/rulego-editor-react'
import '@huanban/rulego-editor-react/style.css'

const API_BASE = 'http://localhost:9090/api/v1'

function App() {
  const [view, setView] = useState<'list' | 'editor'>('list')
  const [chainId, setChainId] = useState('')
  const [chainData, setChainData] = useState(null)

  useEffect(() => {
    if (!chainId) return
    fetch(`${API_BASE}/rule-chains/${chainId}`)
      .then(res => res.json())
      .then(data => setChainData(data))
  }, [chainId])

  if (view === 'list') {
    return (
      <WorkflowList
        apiBase={API_BASE}
        onEdit={(item) => {
          setChainId(item.id)
          setView('editor')
        }}
      />
    )
  }

  return (
    <RuleGoEditor
      apiBase={API_BASE}
      data={chainData}
      height="100vh"
    />
  )
}
```

---

## 五、Hooks

适用于需要完全自定义 UI 的高级场景：

| Hook | 说明 |
|------|------|
| `useEditorCore` | 创建和管理 EditorCore 实例 |
| `useEditorTheme` | 主题切换 |
| `useEditorI18n` | 国际化切换 |
| `useKeyboardShortcuts` | 键盘快捷键绑定 |
| `useClipboard` | 节点复制/粘贴 |

---

## 六、Next.js 集成

### Pages Router

```tsx
import dynamic from 'next/dynamic'

const RuleGoEditor = dynamic(
  () => import('@huanban/rulego-editor-react').then(m => ({ default: m.RuleGoEditor })),
  { ssr: false }
)

export default function EditorPage() {
  return <RuleGoEditor apiBase={API_BASE} data={chainData} />
}
```

### App Router

```tsx
'use client'
import { RuleGoEditor } from '@huanban/rulego-editor-react'
import '@huanban/rulego-editor-react/style.css'

export default function EditorPage() {
  return <RuleGoEditor apiBase={API_BASE} data={chainData} />
}
```

---

## 版本说明

| 版本 | 变更 |
|------|------|
| 1.0.0 | 🎉 正式版。包名改为 `@huanban/rulego-editor-react`。架构重写为薄封装（直接使用 core 的 HuanbanRulegoEditor，不再重复实现 UI）。内置 apiBase 直接保存/部署。|
| 0.7.0 | 重写为薄封装 HuanbanRulegoEditor |
| 0.6.0 | 链信息头部、样式打包优化 |
| 0.5.0 | WorkflowList、WorkflowInfoPanel 组件 |

## License

Apache-2.0