docs: update api docs

apps/docs/src/zh/api/_meta.json

@@ -20,12 +20,12 @@
     "label": "Components"
   },
   {
-    "type": "services",
+    "type": "dir",
     "name": "services",
     "label": "Services"
   },
   {
-    "type": "utils",
+    "type": "dir",
     "name": "utils",
     "label": "Utils"
   }

apps/docs/src/zh/api/core/_meta.json

@@ -1,6 +1,8 @@
 [
   "flow-document",
-  "workflow-document",
   "flow-node-entity",
+  "workflow-document",
+  "workflow-lines-manager",
+  "workflow-line-entity",
   "playground"
 ]

apps/docs/src/zh/api/core/flow-document.mdx

@@ -1,2 +1,183 @@
 # FlowDocument
 
+流程数据文档 (固定布局), 存储流程的所有节点数据
+
+[> API Detail](https://coze-dev.github.io/flowgram.ai/auto-docs/document/classes/FlowDocument.html)
+
+```ts pure
+import { useClientContext } from '@flowgram.ai/fixed-layout-editor'
+
+const ctx = useClientContext();
+console.log(ctx.document)
+```
+
+:::danger
+对节点的操作最好通过 [ctx.operation](/api/services/flow-operation-service.html) 进行操作, 这样才能绑定到 redo/undo
+:::
+
+
+## root
+
+获取画布的根节点，所有节点都挂在根节点下边
+
+```ts pure
+console.log(ctx.document.root);
+```
+## getAllNodes
+
+获取所有节点数据
+
+```ts pure
+const nodes = ctx.document.getAllNodes();
+```
+
+## getNode
+
+通过指定 id 获取节点
+```ts pure
+ctx.document.getNode('start')
+```
+
+## getNodeRegistry
+
+获取节点的定义, 节点定义可以根据业务自己扩展配置项
+
+```ts pure
+const startNodeRegistry = ctx.document.getNodeRegistry<FlowNodeRegistry>('start')
+```
+
+## fromJSON/toJSON
+
+导入和导出数据
+
+```ts pure
+const json = ctx.document.toJSON();
+ctx.document.fromJSON(json);
+```
+
+## registerFlowNodes
+
+注册节点的配置项目, 支持继承
+
+```ts pure
+const node1: FlowNodeRegistry = {
+  type: 'node1',
+  meta: {}
+}
+
+const node2: FlowNodeRegistry = {
+  type: 'node2',
+  extend: 'node1' // 继承 node1 的配置
+}
+ctx.document.registerFlowNodes(node1, node2)
+```
+
+## addNode
+
+添加节点
+
+```ts pure
+ctx.document.addNode({
+  id: 'node1',
+  type: 'start',
+  meta: {},
+  data: {},
+  parent: ctx.document.root // 可以指定父节点
+});
+
+```
+
+## addFromNode
+
+添加到指定节点的后边
+
+```ts pure
+ctx.document.addFromNode(
+ ctx.document.getNode('start'),
+ { id: 'node1', type: 'custom', data: {} }
+);
+
+```
+
+## addBlock
+
+为指定节点添加分支节点
+
+```ts pure
+
+ctx.document.addBlock(ctx.document.getNode('condition'), { id: 'if_1', type: 'block', data: {} })
+```
+
+## removeNode
+
+删除节点
+
+```ts pure
+ctx.document.removeNode('node1');
+```
+
+## onNodeCreate/onNodeUpdate/onNodeDispose
+
+节点创建/更新/销毁事件, 返回事件的注销函数
+
+```tsx pure
+
+useEffect(() => {
+  const toDispose1 = ctx.document.onNodeCreate((node) => {
+    console.log('onNodeCreate', node);
+  });
+  const toDispose2 = ctx.document.onNodeUpdate((node) => {
+    console.log('onNodeUpdate', node);
+  });
+  const toDispose3 = ctx.document.onNodeDispose((node) => {
+    console.log('onNodeDispose', node);
+  });
+  return () => {
+    toDispose1.dispose()
+    toDispose2.dispose()
+    toDispose3.dispose()
+  }
+}, []);
+```
+## traverse
+
+从指定节点遍历所有子节点, 默认根节点
+
+```ts pure
+/**
+ *
+ * traverse all nodes, O(n)
+ *   R
+ *   |
+ *   +---1
+ *   |   |
+ *   |   +---1.1
+ *   |   |
+ *   |   +---1.2
+ *   |   |
+ *   |   +---1.3
+ *   |   |    |
+ *   |   |    +---1.3.1
+ *   |   |    |
+ *   |   |    +---1.3.2
+ *   |   |
+ *   |   +---1.4
+ *   |
+ *   +---2
+ *       |
+ *       +---2.1
+ *
+ *  sort: [1, 1.1, 1.2, 1.3, 1.3.1, 1.3.2, 1.4, 2, 2.1]
+ */
+ctx.document.traverse((node, depth, index) => {
+  console.log(node.id);
+}, ctx.document.root);
+```
+
+## toString
+
+返回节点结构的字符串快照
+
+```ts pure
+console.log(ctx.document.toString())
+```

apps/docs/src/zh/api/core/flow-node-entity.mdx

@@ -1 +1,98 @@
-# FlowNodeEntity
+# FlowNodeEntity/WorkflowNodeEntity
+
+节点实体，`WorkflowNodeEntity` 为节点别名用于自由布局节点, 节点实体采用 [ECS](/flowgram.ai/guide/concepts/ECS.html) 架构
+
+[> API Detail](https://coze-dev.github.io/flowgram.ai/auto-docs/document/classes/FlowNodeEntity-1.html)
+
+## Properties
+
+- id: `string` 节点 id
+- flowNodeType: `string` | `number` 节点类型
+- version `number` 节点版本，可以用于判断节点状态是否更新
+
+## Accessors
+
+- document: `FlowDocument | WorkflowDocument` 文档链接
+- bounds: `Rectangle` 获取节点的 x，y，width，height, 等价于 `transform.bounds`
+- blocks: `FlowNodeEntity[]` 获取子节点, 包含折叠的子节点, 等价于 `collapsedChildren`
+- collapsedChildren: `FlowNodeEntity[]` 获取子节点, 包含折叠的子节点
+- allCollapsedChildren: `FlowNodeEntity[]` 获取所有子节点，包括所有折叠的子节点
+- children: `FlowNodeEntity[]` 获取子节点, 不包含折叠的子节点
+- pre: `FlowNodeEntity | undefined` 获取上一个节点
+- next: `FlowNodeEntity | undefined` 获取下一个节点
+- parent: `FlowNodeEntity | undefined` 获取父节点
+- originParent: `FlowNodeEntity | undefined` 获取原始父节点, 这个用于固定布局分支的第一个节点(orderIcon) 找到整个虚拟分支
+- allChildren: `FlowNodeEntity[]` 获取所有子节点, 不包含折叠的子节点
+- transform: [FlowNodeTransformData](https://coze-dev.github.io/flowgram.ai/auto-docs/document/classes/FlowNodeTransformData.html) 获取节点的 transform 矩阵数据
+- renderData: [FlowNodeRenderData](https://coze-dev.github.io/flowgram.ai/auto-docs/document/classes/FlowNodeRenderData.html) 获取节点的渲染数据, 包含渲染状态等
+
+
+## Methods
+
+### getExtInfo
+
+获取节点的扩展信息, 可以通过 `updateExtInfo` 更新扩展信息
+
+```
+node.getExtInfo<{ test: string }>()
+```
+
+### updateExtInfo
+
+更新扩展数据, 更新不会记录到 `redo/undo`, 如果需要记录，请实现 [history](/flowgram.ai/guide/advanced/history.html) 服务
+
+```
+node.updateExtInfo<{ test: string }>({
+  test: 'test'
+})
+```
+
+### getNodeRegistry
+
+获取节点注册器, 等价于 `ctx.document.getNodeRegistry(node.flowNodeType)`
+```ts pure
+const nodeRegistry = node.getNodeRegistry<FlowNodeRegistry>()
+```
+
+### getData
+
+### addData
+
+### getService
+
+节点访问 [IOC](/flowgram.ai/guide/concepts/IOC.html) 服务
+
+```ts pure
+node.getService(SelectionService)
+```
+
+### dispose
+
+节点从画布中销毁
+
+### onDispose
+
+节点销毁事件
+
+```ts pure
+useEffect(() => {
+  const toDispose = node.onDispose(() => {
+    console.log('Dispose node')
+  })
+  return () => toDispose.dispose()
+}, [node])
+```
+
+### toJSON
+
+导出节点数据
+
+:::note 节点数据基本结构:
+
+- id: `string` 节点唯一标识, 必须保证唯一
+- meta: `object` 节点的 ui 配置信息，如自由布局的 `position` 信息放这里
+- type: `string | number` 节点类型，会和 `nodeRegistries` 中的 `type` 对应
+- data: `object` 节点表单数据, 业务可自定义
+- blocks: `array` 节点的分支, 采用 `block` 更贴近 `Gramming`
+
+:::

apps/docs/src/zh/api/core/workflow-document.mdx

@@ -1 +1,86 @@
-# WorkflowDocument
+# WorkflowDocument (free)
+
+自由布局文档数据，继承自 [FlowDocument](/flowgram.ai/api/core/flow-document.html)
+
+[> API Detail](https://coze-dev.github.io/flowgram.ai/auto-docs/free-layout-core/classes/WorkflowDocument.html)
+
+```ts pure
+import { useClientContext } from '@flowgram.ai/free-layout-editor'
+
+const ctx = useClientContext();
+console.log(ctx.document)
+```
+
+:::tip
+由于历史原因， 带 `Workflow` 前缀的都代表自由布局
+:::
+
+## linesManager
+
+自由布局线条管理，见 [WorkflowLinesManager](/api/core/workflow-lines-manager.html)
+
+## createWorkflowNodeByType
+
+根据节点类型创建自由布局节点
+
+```ts pure
+const node = ctx.document.createWorkflowNodeByType(
+ 'custom',
+  { x: 100, y: 100 },
+  {
+    id: 'xxxx',
+    data: {}
+  }
+)
+```
+
+## onContentChange
+
+监听自由布局画布数据变化
+
+```ts pure
+
+export enum WorkflowContentChangeType {
+  /**
+   * 添加节点
+   */
+  ADD_NODE = 'ADD_NODE',
+  /**
+   * 删除节点
+   */
+  DELETE_NODE = 'DELETE_NODE',
+  /**
+   * 移动节点
+   */
+  MOVE_NODE = 'MOVE_NODE',
+  /**
+   * 节点数据更新 （表单引擎数据 或者 extInfo 数据）
+   */
+  NODE_DATA_CHANGE = 'NODE_DATA_CHANGE',
+  /**
+   * 添加线条
+   */
+  ADD_LINE = 'ADD_LINE',
+  /**
+   * 删除线条
+   */
+  DELETE_LINE = 'DELETE_LINE',
+  /**
+   * 节点Meta信息变更
+   */
+  META_CHANGE = 'META_CHANGE',
+}
+
+export interface WorkflowContentChangeEvent {
+  type: WorkflowContentChangeType;
+  /**
+   * 当前触发的元素的json数据，toJSON 需要主动触发
+   */
+  toJSON: () => any;
+  /*
+   * 当前的事件的 entity
+   */
+  entity: WorkflowNodeEntity | WorkflowLineEntity;
+}
+
+``

apps/docs/src/zh/api/core/workflow-line-entity.mdx

@@ -0,0 +1 @@
+# WorkflowLineEntity (free)

apps/docs/src/zh/api/core/workflow-lines-manager.mdx

@@ -0,0 +1 @@
+# WorkflowLinesManager (free)

apps/docs/src/zh/api/hooks/use-document.mdx

@@ -1 +0,0 @@
-# useDocument

apps/docs/src/zh/api/hooks/use-node-render.mdx

@@ -0,0 +1 @@
+# useNodeRender

apps/docs/src/zh/api/services/flow-operation-service.mdx

@@ -0,0 +1,113 @@
+# FlowOperationService
+
+节点操作服务, 目前用于固定布局，自由布局现阶段可通过 WorkflowDocument 直接操作, 后续也会抽象出 operation
+
+[> API Detail](https://coze-dev.github.io/flowgram.ai/auto-docs/fixed-layout-editor/interfaces/FlowOperationService.html)
+
+```typescript pure
+const ctx = useClientContext();
+ctx.operation.addNode({ id: 'xxx', type: 'custom', data: {} })
+
+```
+
+## Interface
+
+```typescript pure
+
+export interface FlowOperationBaseService extends Disposable {
+  /**
+   * 执行操作
+   * @param operation 可序列化的操作
+   * @returns 操作返回
+   */
+  apply(operation: FlowOperation): any;
+
+  /**
+   * 添加节点，如果节点已经存在则不会重复创建
+   * @param nodeJSON 节点数据
+   * @param config 配置
+   * @returns 成功添加的节点
+   */
+  addNode(nodeJSON: FlowNodeJSON, config?: AddNodeConfig): FlowNodeEntity;
+
+  /**
+   * 基于某一个起始节点往后面添加
+   * @param fromNode 起始节点
+   * @param nodeJSON 添加的节点JSON
+   */
+  addFromNode(fromNode: FlowNodeEntityOrId, nodeJSON: FlowNodeJSON): FlowNodeEntity;
+
+  /**
+   * 删除节点
+   * @param node 节点
+   * @returns
+   */
+  deleteNode(node: FlowNodeEntityOrId): void;
+
+  /**
+   * 批量删除节点
+   * @param nodes
+   */
+  deleteNodes(nodes: FlowNodeEntityOrId[]): void;
+
+  /**
+   * 添加块（分支）
+   * @param target 目标
+   * @param blockJSON 块数据
+   * @param config 配置
+   * @returns
+   */
+  addBlock(
+    target: FlowNodeEntityOrId,
+    blockJSON: FlowNodeJSON,
+    config?: AddBlockConfig,
+  ): FlowNodeEntity;
+
+  /**
+   * 移动节点
+   * @param node 被移动的节点
+   * @param config 移动节点配置
+   */
+  moveNode(node: FlowNodeEntityOrId, config?: MoveNodeConfig): void;
+
+  /**
+   * 拖拽节点
+   * @param param0
+   * @returns
+   */
+  dragNodes({ dropNode, nodes }: { dropNode: FlowNodeEntity; nodes: FlowNodeEntity[] }): void;
+
+  /**
+   * 添加节点的回调
+   */
+  onNodeAdd: Event<OnNodeAddEvent>;
+}
+
+export interface FlowOperationService extends FlowOperationBaseService {
+  /**
+   * 创建分组
+   * @param nodes 节点列表
+   */
+  createGroup(nodes: FlowNodeEntity[]): FlowNodeEntity | undefined;
+  /**
+   * 取消分组
+   * @param groupNode
+   */
+  ungroup(groupNode: FlowNodeEntity): void;
+  /**
+   * 开始事务
+   */
+  startTransaction(): void;
+  /**
+   * 结束事务
+   */
+  endTransaction(): void;
+  /**
+   * 修改表单数据
+   * @param node 节点
+   * @param path 属性路径
+   * @param value 值
+   */
+  setFormValue(node: FlowNodeEntityOrId, path: string, value: unknown): void;
+}
+```

apps/docs/src/zh/api/utils/get-node-form.mdx

@@ -0,0 +1 @@
+# getNodeForm

apps/docs/src/zh/guide/advanced/_meta.json

@@ -1,14 +1,4 @@
 [
-  {
-    "type": "dir",
-    "name": "fixed-layout",
-    "label": "固定布局"
-  },
-  {
-    "type": "dir",
-    "name": "free-layout",
-    "label": "自由布局"
-  },
   "form",
   "variable",
   "history",

apps/docs/src/zh/guide/advanced/history.mdx

@@ -13,9 +13,9 @@ Undo/Redo 是 FlowGram.AI 的一个插件，在 @flowgram.ai/fixed-layout-editor
 export function useEditorProps() {
   return useMemo(
     () => ({
-      ...
       history: {
-        enable: true
+        enable: true,
+        enableChangeNode: true // Listen Node engine data change
       }
     })
   )

apps/docs/src/zh/guide/advanced/interactive/shortcuts.mdx

@@ -5,12 +5,13 @@
 ```ts pure
 // 添加到 EditorProps
 {
-  shortcuts(shorcutsRegistry: ShortcutsRegistry, ctx) {
+  shortcuts(shorcutsRegistry, ctx) {
       // 按住 cmmand + a，选中所有节点
       shorcutsRegistry.addHandlers({
         commandId: 'selectAll',
         shortcuts: ['meta a', 'ctrl a'],
-        execute() {
+        isEnabled: (...args) => true,
+        execute(...args) {
           const allNodes = ctx.document.getAllNodes();
           ctx.playground.selectionService.selection = allNodes;
         },
@@ -19,3 +20,13 @@
 }
 
 ```
+
+## 通过 CommandService 调用快捷键
+
+```ts pure
+const commandService = useService(CommandService)
+/**
+ * 调用命令服务, args 参数会透传给 execute 和 isEnabled
+ */
+commandService.executeCommand('selectAll', ...args)
+```

apps/docs/src/zh/guide/concepts/_meta.json

@@ -1,5 +1,7 @@
 [
   "canvas-engine",
   "node-engine",
-  "variable-engine"
+  "variable-engine",
+  "ECS",
+  "IOC"
 ]

apps/docs/src/zh/guide/concepts/ecs.mdx

@@ -0,0 +1 @@
+# ECS

apps/docs/src/zh/guide/concepts/ioc.mdx

@@ -0,0 +1 @@
+# IOC