nkk-flow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nkk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# nkk-flow
+
+Vue 3 + LogicFlow 审批流画布封装。核心入口是 `useFlow`，页面只需要提供容器、业务流程 JSON 和可选配置。
+
+## 安装
+
+```bash
+npm install nkk-flow @logicflow/core @logicflow/extension @vueuse/core vue
+```
+
+在应用入口引入样式：
+
+```ts
+import '@logicflow/core/dist/index.css'
+import '@logicflow/extension/lib/index.css'
+import 'nkk-flow/style.css'
+```
+
+## 基础用法
+
+```ts
+import { onBeforeUnmount, onMounted, ref } from 'vue'
+import { useFlow, type FlowProcessJson, type FlowOptions } from 'nkk-flow'
+
+const graphRef = ref<HTMLElement | null>(null)
+let flowApi: ReturnType<typeof useFlow> | null = null
+
+const options: FlowOptions = {
+  editable: true,
+  tools: ['MiniMap'],
+}
+
+onMounted(() => {
+  if (!graphRef.value) return
+  flowApi = useFlow(graphRef.value, flowJson as FlowProcessJson, options)
+})
+
+onBeforeUnmount(() => {
+  flowApi?.destroy()
+})
+```
+
+```vue
+<template>
+  <div ref="graphRef" style="height: 100%; width: 100%;" />
+</template>
+```
+
+## 主要配置
+
+`useFlow(element, flowJson, options?)`
+
+`editable`：是否允许编辑。默认 `true`。关闭后会隐藏删除、标题编辑、添加节点和添加分支入口。
+
+`tools`：内置工具，当前支持 `zoom`、`MiniMap`。
+
+`nodePicker.options`：控制点击连线 `+` 后可添加的节点类型。
+
+`nodePicker.nodeFactories`：自定义某个类型新增时生成的业务 JSON。
+
+`nodeDrawer.orgTree` / `nodeDrawer.people` / `nodeDrawer.roles`：**组织数据由宿主注入**，库本身不发任何 HTTP 请求。宿主侧自行从后端拉取后传入，审批人/部门/角色选择器才能显示数据。
+
+`nodeDrawer.nodeConfigs`：追加或覆盖节点配置抽屉表单。
+
+`events`：监听节点点击、删除、标题修改、插入、抽屉保存等事件。
+
+## 注入组织数据
+
+`useFlow` 是一个纯画布封装，不内置任何网络请求。审批节点配置抽屉需要的组织架构、人员列表、角色列表，由宿主侧拉取后通过 `options.nodeDrawer` 注入：
+
+```ts
+import { fetchDrawerOrgData } from './api/org' // 宿主侧自己的接口
+
+const { orgTree, people, roles } = await fetchDrawerOrgData()
+
+useFlow(container, flowJson, {
+  nodeDrawer: { orgTree, people, roles },
+})
+```
+
+条件分支节点需要的表单字段元数据，通过 `flowApi.setMetaFormFields()` 注入：
+
+```ts
+const flowApi = useFlow(container, flowJson, options)
+flowApi.setMetaFormFields(formFieldsFromBackend)
+```
+
+## 扩展节点配置抽屉
+
+每个节点配置表单独立成组件，组件接收 `payload` 和 `context`，并通过 `defineExpose` 暴露 `getPatch()`。
+
+```vue
+<script setup lang="ts">
+import type { FlowNodeConfigFormExpose, FlowNodeConfigFormProps } from 'nkk-flow'
+
+const props = defineProps<FlowNodeConfigFormProps>()
+
+function getPatch() {
+  return {
+    customValue: props.payload.title,
+  }
+}
+
+defineExpose<FlowNodeConfigFormExpose>({ getPatch })
+</script>
+```
+
+注册到 `useFlow`：
+
+```ts
+useFlow(container, flowJson, {
+  nodeDrawer: {
+    nodeConfigs: [
+      {
+        type: 2,
+        kind: 'cc',
+        title: '抄送节点',
+        description: '配置抄送人员',
+        component: CcNodeConfig,
+      },
+    ],
+  },
+})
+```
+
+## 自定义新增节点 JSON
+
+```ts
+useFlow(container, flowJson, {
+  nodePicker: {
+    options: [{ type: 2, label: '抄送节点', description: '通知相关人员。' }],
+    nodeFactories: {
+      2: ({ nextNode, createNodeKey }) => ({
+        nodeName: '抄送节点',
+        nodeKey: createNodeKey('cc'),
+        type: 2,
+        nodeAssigneeList: [],
+        childNode: nextNode ?? {},
+      }),
+    },
+  },
+})
+```
+
+## 当前内置节点类型
+
+`-1`：结束
+
+`0`：发起人
+
+`1`：审批节点
+
+`2`：抄送节点
+
+`3`：条件分支
+
+`4`：条件路由
+
+`5`：子流程
+
+`6`：延迟等待
+
+`7`：触发器
+
+`8`：并行路由
+
+`9`：包容路由
+
+`23`：路由分支
+
+`30`：自动通过
+
+`31`：自动拒绝
+
+## 开发脚本
+
+```bash
+npm run build
+npm run build:lib
+```