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

# @huanban/editor-react

RuleGo 规则链编辑器 React 适配层。提供开箱即用的编辑器、工作流列表、信息面板等组件。

## 安装

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

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

---

## 样式引入

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

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

---

## 组件一览

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

---

## 一、WorkflowList — 工作流列表

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

### 基本用法

```tsx
import { WorkflowList } from '@huanban/editor-react'
import '@huanban/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 地址，如 `http://localhost:9090/api/v1` |
| `onEdit` | `(item: WorkflowItem) => void` | ❌ | 点击"编辑"按钮的回调 |
| `customRoutes` | `RuleChainRoutes` | ❌ | 自定义 API 路由映射 |
| `customIcons` | `WorkflowListIcons` | ❌ | 自定义图标 |
| `theme` | `WorkflowTheme` | ❌ | 自定义主题色 |

---

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

完整的可视化规则链编辑器，支持拖拽节点、连线、属性编辑、撤销/重做。

### 基本用法

```tsx
import { RuleGoEditor } from '@huanban/editor-react'
import '@huanban/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])

  const handleSave = (data) => {
    fetch(`http://localhost:9090/api/v1/rule-chains/${chainId}`, {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data),
    })
  }

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

### 链信息头部

编辑器顶部自动展示：
- **链名称** — 当前规则链的 name
- **主链/子链标签** — 根据 `ruleChain.root` 字段判断
- **已停用标签** — 当 `ruleChain.disabled` 为 true 时显示
- **Endpoint 列表** — 如果有 `metadata.endpoints` 则显示类型标签（如 HTTP、MQTT）

可通过 `showChainInfo={false}` 隐藏。

### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `data` | `RuleChainData \| null` | `null` | 规则链数据 |
| `options` | `Partial<EditorOptions>` | `{}` | 编辑器配置 |
| `onSave` | `(data) => void` | - | 保存回调 |
| `onReady` | `({ core, lf }) => void` | - | 编辑器就绪回调 |
| `showChainInfo` | `boolean` | `true` | 是否显示链信息头部 |
| `builtinUi` | `boolean` | `true` | 是否使用内置 UI |
| `height` | `string \| number` | `'100%'` | 编辑器高度 |
| `width` | `string \| number` | `'100%'` | 编辑器宽度 |
| `className` | `string` | `''` | 自定义 className |
| `style` | `CSSProperties` | `{}` | 自定义样式 |
| `onNodeClick` | `(node) => void` | - | 节点点击回调 |
| `onNodeDbClick` | `(node) => void` | - | 节点双击回调 |
| `onEdgeClick` | `(edge) => void` | - | 边点击回调 |
| `renderSidebar` | `({ groups, core }) => ReactNode` | - | 自定义侧边栏 |
| `renderToolbar` | `({ canUndo, canRedo, core }) => ReactNode` | - | 自定义工具栏 |
| `renderPanel` | `({ nodeView, nodeModel, core }) => ReactNode` | - | 自定义属性面板 |

---

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

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

### 基本用法

```tsx
import { WorkflowInfoPanel } from '@huanban/editor-react'
import '@huanban/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/editor-react'
import '@huanban/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])

  // 保存
  const handleSave = (data) => {
    fetch(`${API_BASE}/rule-chains/${chainId}`, {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data),
    })
  }

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

  return (
    <div style={{ display: 'flex', height: '100vh' }}>
      <div style={{ flex: 1 }}>
        <RuleGoEditor
          data={chainData}
          onSave={handleSave}
        />
      </div>
    </div>
  )
}
```

---

## 五、Hooks

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

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

```tsx
import { useEditorCore, useEditorTheme } from '@huanban/editor-react'

function MyCustomEditor() {
  const { core, isReady, componentGroups } = useEditorCore({
    url: 'http://localhost:9090/api/v1',
  })
  const { setTheme } = useEditorTheme(core)

  return (
    <div>
      <button onClick={() => setTheme('dark')}>暗色</button>
      {/* 自定义的编辑器 UI */}
    </div>
  )
}
```

---

## 六、Next.js 集成

### Pages Router

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

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

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

### App Router

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

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

---

## 版本说明

| 版本 | 变更 |
|------|------|
| 0.6.0 | 编辑器顶部新增链信息头部（名称 + 主链/子链 + endpoint）；样式打包优化（一个 style.css 包含所有样式）；依赖锁定 logicflow 2.1.11 |
| 0.5.0 | WorkflowList、WorkflowInfoPanel 组件 |
| 0.4.0 | 初始版本 |

## License

Apache-2.0