@logicflow/core 2.2.0 → 2.2.2

package/dist/docs/tutorial/advanced/snapline.en.md

@@ -0,0 +1,54 @@
+---
+nav: Guide
+group:
+  title: Intermediate
+  order: 2
+title: Snapline
+order: 2
+toc: content
+---
+
+Snap-lines assist in positional adjustment by comparing the position of a moving node with the
+position of other nodes in the canvas as the node moves. The position comparison is done in two
+ways.
+
+- The center of the node
+- The border of the node
+
+## Alignment Line Usage
+
+Alignment lines are turned on by default in normal editing mode, and can also be turned off by
+configuration.
+In [silent mode](silent-mode.en.md#silent-mode), it is not possible to move the node, so the
+alignment line function is turned off and cannot be turned on by configuration.
+
+```tsx | pure
+const lf = new LogicFlow({
+  snapline: false,
+});
+```
+
+## Alignment Line Style Settings
+
+The style of the alignment line includes color and width, which can be modified by setting the
+theme.
+
+```tsx | pure
+// default configuration
+// {
+//   stroke: '#1E90FF',
+//   strokeWidth: 1,
+// }
+
+// Modify the alignment line style
+lf.setTheme({
+  snapline: {
+    stroke: '#1E90FF',
+    strokeWidth: 1,
+  },
+})
+```
+
+<example :height="400" ></example>
+
+For more modifications to the styles see [Theme](../basic/theme.en.md)

package/dist/docs/tutorial/advanced/vue.en.md

@@ -0,0 +1,249 @@
+---
+nav: Guide
+group:
+  title: Intermediate
+  order: 2
+title: Vue Node Registry
+order:  7
+toc: content
+tag: New
+---
+
+:::info{title=New-Features-Introduction}
+* How to use Vue components to register node content
+* How to synchronize node content updates when properties change
+  :::
+
+## Rendering Vue Components as Node Content
+
+Similar to React, we provide a separate package `@logicflow/vue-node-registry` for rendering nodes with Vue components.
+
+### Vue 3
+
+Here's an example of how to use Vue 3:
+
+```html
+<template>
+  <div ref="containerRef" id="graph" class="viewport"></div>
+  <TeleportContainer :flow-id="flowId"/>
+</template>
+
+<script setup lang="ts">
+  import { onMounted, ref } from 'vue'
+  import { has } from 'lodash-es'
+  import LogicFlow from '@logicflow/core'
+  import { register, getTeleport } from '@logicflow/vue-node-registry'
+  import '@logicflow/core/es/index.css'
+
+  import ProgressNode from '@/components/LFElements/ProgressNode.vue'
+
+  const lfRef = ref<LogicFlow | null>(null)
+  const containerRef = ref<HTMLDivElement | null>(null)
+  const TeleportContainer = getTeleport()
+  const flowId = ref('')
+
+  onMounted(() => {
+    if (containerRef.value) {
+      const lf = new LogicFlow({
+        container: containerRef.value,
+        grid: true,
+      })
+
+      // 注册自定义 vue 节点
+      register({
+        type: 'custom-vue-node',
+        component: ProgressNode
+      }, lf)
+
+      lf.on('graph:rendered', ({ graphModel }) => {
+        flowId.value = graphModel.flowId!
+      })
+
+      // 注册事件
+      lf.render({})
+
+      const node1 = lf.addNode({
+        id: 'vue-node-1',
+        type: 'custom-vue-node',
+        x: 80,
+        y: 80,
+        properties: {
+          progress: 60,
+          width: 80,
+          height: 80
+        }
+      })
+      console.log('node1 --->>>', node1)
+
+      const node2 = lf.addNode({
+        id: 'vue-node-2',
+        type: 'custom-vue-node',
+        x: 360,
+        y: 80,
+        properties: {
+          progress: 60,
+          width: 80,
+          height: 80
+        }
+      })
+
+      setInterval(() => {
+        const { properties } = node2.getData()
+        console.log('properties.progress --->>>', properties?.progress)
+        if (has(properties, 'progress')) {
+          const progress = properties?.progress
+          node2.setProperty('progress', (progress + 10) % 100)
+        }
+      }, 2000)
+    }
+  })
+</script>
+```
+
+Node component content is as follows:
+
+```html
+<template>
+    <el-progress type="dashboard" :percentage="percentage" :width="80">
+        <template #default="{ percentage }">
+            <span class="percentage-value">{{ percentage }}%</span>
+        </template>
+    </el-progress>
+</template>
+
+<script lang="ts">
+    import {
+        defineComponent
+    } from 'vue'
+    import {
+        EventType
+    } from '@logicflow/core'
+    import {
+        vueNodesMap
+    } from '@logicflow/vue-node-registry'
+
+    export default defineComponent({
+        name: 'ProgressNode',
+        inject: ['getNode', 'getGraph'],
+        data() {
+            return {
+                percentage: 80
+            }
+        },
+        mounted() {
+            const node = (this as any).getNode()
+            const graph = (this as any).getGraph()
+            graph.eventCenter.on(EventType.NODE_PROPERTIES_CHANGE, (eventData: any) => {
+                const keys = eventData.keys as string[]
+                const content = vueNodesMap[node.type]
+                if (content && eventData.id === node.id) {
+                    const {
+                        effect
+                    } = content
+
+                    // If effect is not defined, default to updating; if effect is defined, only update when properties in effect change
+                    if (!effect || keys.some((key) => effect.includes(key))) {
+                        console.log('eventData --->>>', eventData)
+                        this.percentage = eventData.properties?.progress || 0
+                    }
+                }
+            })
+        }
+    })
+</script>
+```
+
+Below is an animated image showing the effect. To experience the functionality, you can start the `examples/vue3-app` project.
+<img src="/vue3-app.gif">
+
+## Updating Nodes
+
+Similar to `HTMLNode`, when users update node properties using `setProperties` or `setProperty`, we need to listen to the `node:properties-change` event inside the component and update the component's state based on the properties value, as demonstrated in the example above.
+
+## Using Vue 2
+
+In the example above, we used teleport, a feature of Vue 3. How can this be done in Vue 2?
+
+```html
+<template>
+    <div id="app">
+        <div ref="containerRef" id="graph"></div>
+    </div>
+</template>
+
+<script>
+    import LogicFlow from '@logicflow/core'
+    import {
+        register
+    } from '@logicflow/vue-node-registry'
+
+    import ProgressNode from '@/components/ProgressNode'
+    import '@logicflow/core/dist/index.css'
+
+    export default {
+        name: 'App',
+        data() {
+            return {
+                lf: null,
+            }
+        },
+        mounted() {
+            this.lf = new LogicFlow({
+                container: this.$refs.containerRef,
+                grid: true,
+            })
+            register({
+                    type: 'progress',
+                    component: ProgressNode,
+                },
+                this.lf,
+            )
+
+            this.lf.render({})
+
+            const node1 = this.lf.addNode({
+                id: 'vue-node-1',
+                type: 'progress',
+                x: 80,
+                y: 80,
+                properties: {
+                    progress: 60,
+                    width: 80,
+                    height: 80,
+                },
+            })
+            console.log('node1 --->>>', node1)
+        },
+    }
+</script>
+
+<style>
+    #graph {
+        height: 100vh;
+    }
+</style>
+```
+
+Node component content is as follows:
+
+```html
+<template>
+    <div>vue2 node</div>
+</template>
+
+<script>
+    export default {
+        name: 'ProgressNode',
+        inject: ['getNode', 'getGraph'],
+        data() {
+            return {
+                percentage: 80,
+            }
+        },
+    }
+</script>
+```
+
+:::warning{title=Note}
+Currently, there are some limitations with node component content in Vue 2, such as the inability to use Vuex, i18n, element-ui, etc. If you need these features, you can try using `vue2-teleport` to enhance the capabilities, and we welcome PRs (we will also gradually enhance this functionality in the future).
+:::

package/dist/docs/tutorial/advanced/vue.zh.md

@@ -0,0 +1,248 @@
+---
+nav: 指南
+group:
+  title: 进阶
+  order: 2
+title: Vue 节点
+order: 7
+toc: content
+tag: 新特性
+---
+
+:::info{title=我们带来了新特性，本节内容主要介绍}
+- 如何使用 Vue 组件来注册节点内容
+- properties 更新后如何同步更新节点内容
+::::
+
+::::info{title=阅读提示}
+- 适合已经理解 [节点](../basic/node.zh.md) 的 Vue 项目用户
+- 当前推荐优先使用 `@logicflow/vue-node-registry`
+- Vue3 和 Vue2 的使用方式不同，建议按自己的技术栈跳读，不要混在一起理解
+- 本页不展开连接规则、锚点和边能力；这些内容请回到 [进阶节点](node.zh.md)
+- 相关 API：[`nodeModel`](../../api/runtime-model/nodeModel.zh.md)、[`graphModel`](../../api/runtime-model/graphModel.zh.md)、[`事件`](../../api/logicflow-instance/event.zh.md)
+::::
+
+## 渲染 Vue 组件为节点内容
+同 React 一样我们提供了一个独立的包 `@logicflow/vue-node-registry` 来使用 Vue 组件渲染节点。
+
+### Vue3
+在 Vue3 中使用示例如下：
+
+```html
+<template>
+  <div ref="containerRef" id="graph" class="viewport"></div>
+  <TeleportContainer :flow-id="flowId"/>
+</template>
+
+<script setup lang="ts">
+  import { onMounted, ref } from 'vue'
+  import { has } from 'lodash-es'
+  import LogicFlow from '@logicflow/core'
+  import { register, getTeleport } from '@logicflow/vue-node-registry'
+  import '@logicflow/core/es/index.css'
+
+  import ProgressNode from '@/components/LFElements/ProgressNode.vue'
+
+  const lfRef = ref<LogicFlow | null>(null)
+  const containerRef = ref<HTMLDivElement | null>(null)
+  const TeleportContainer = getTeleport()
+  const flowId = ref('')
+
+  onMounted(() => {
+    if (containerRef.value) {
+      const lf = new LogicFlow({
+        container: containerRef.value,
+        grid: true,
+      })
+
+      // 注册自定义 vue 节点
+      register({
+        type: 'custom-vue-node',
+        component: ProgressNode
+      }, lf)
+
+      lf.on('graph:rendered', ({ graphModel }) => {
+        flowId.value = graphModel.flowId!
+      })
+
+      // 注册事件
+      lf.render({})
+
+      const node1 = lf.addNode({
+        id: 'vue-node-1',
+        type: 'custom-vue-node',
+        x: 80,
+        y: 80,
+        properties: {
+          progress: 60,
+          width: 80,
+          height: 80
+        }
+      })
+      console.log('node1 --->>>', node1)
+
+      const node2 = lf.addNode({
+        id: 'vue-node-2',
+        type: 'custom-vue-node',
+        x: 360,
+        y: 80,
+        properties: {
+          progress: 60,
+          width: 80,
+          height: 80
+        }
+      })
+
+      setInterval(() => {
+        const { properties } = node2.getData()
+        console.log('properties.progress --->>>', properties?.progress)
+        if (has(properties, 'progress')) {
+          const progress = properties?.progress
+          node2.setProperty('progress', (progress + 10) % 100)
+        }
+      }, 2000)
+    }
+  })
+</script>
+
+```
+
+节点组件内容如下：
+```html
+<template>
+  <el-progress type="dashboard" :percentage="percentage" :width="80">
+    <template #default="{ percentage }">
+      <span class="percentage-value">{{ percentage }}%</span>
+    </template>
+  </el-progress>
+</template>
+
+<script lang="ts">
+import { defineComponent } from 'vue'
+import { EventType } from '@logicflow/core'
+import { vueNodesMap } from '@logicflow/vue-node-registry'
+
+export default defineComponent({
+  name: 'ProgressNode',
+  inject: ['getNode', 'getGraph'],
+  data() {
+    return {
+      percentage: 80
+    }
+  },
+  mounted() {
+    const node = (this as any).getNode()
+    const graph = (this as any).getGraph()
+    graph.eventCenter.on(EventType.NODE_PROPERTIES_CHANGE, (eventData: any) => {
+      const keys = eventData.keys as string[]
+      const content = vueNodesMap[node.type]
+      if (content && eventData.id === node.id) {
+        const { effect } = content
+
+        // 如果没有定义 effect，则默认更新；如果定义了 effect，则只有在 effect 中的属性发生变化时才更新
+        if (!effect || keys.some((key) => effect.includes(key))) {
+          console.log('eventData --->>>', eventData)
+          this.percentage = eventData.properties?.progress || 0
+        }
+      }
+    })
+  }
+})
+</script>
+
+```
+
+下面插入一张动图展示效果。如果想体验具体功能可以通过启动：examples/vue3-app 项目查看。
+<img src="/vue3-app.gif">
+
+## 更新节点
+跟 `HTMLNode` 一样，当用户通过 `setProperties` 或 `setProperty` 等更新节点 properties 时，
+我们需要在组件内部监听 `node:properties-change` 事件，根据 properties 值更新组件状态。如上面 Demo 所示。
+
+## Vue2 使用
+上面我们使用到了 teleport，它是 Vue3 中的特性，如果在 Vue2 中，如何使用呢？
+
+```html
+<template>
+  <div id="app">
+    <div ref="containerRef" id="graph"></div>
+  </div>
+</template>
+
+<script>
+  import LogicFlow from '@logicflow/core'
+  import { register } from '@logicflow/vue-node-registry'
+
+  import ProgressNode from '@/components/ProgressNode'
+  import '@logicflow/core/dist/index.css'
+
+  export default {
+    name: 'App',
+    data() {
+      return {
+        lf: null,
+      }
+    },
+    mounted() {
+      this.lf = new LogicFlow({
+        container: this.$refs.containerRef,
+        grid: true,
+      })
+      register(
+        {
+          type: 'progress',
+          component: ProgressNode,
+        },
+        this.lf,
+      )
+
+      this.lf.render({})
+
+      const node1 = this.lf.addNode({
+        id: 'vue-node-1',
+        type: 'progress',
+        x: 80,
+        y: 80,
+        properties: {
+          progress: 60,
+          width: 80,
+          height: 80,
+        },
+      })
+      console.log('node1 --->>>', node1)
+    },
+  }
+</script>
+
+<style>
+  #graph {
+    height: 100vh;
+  }
+</style>
+```
+
+节点组件内容如下：
+```html
+<template>
+  <div>vue2 node</div>
+</template>
+
+<script>
+export default {
+  name: 'ProgressNode',
+  inject: ['getNode', 'getGraph'],
+  data() {
+    return {
+      percentage: 80,
+    }
+  },
+}
+</script>
+
+```
+
+:::warning{title=注意}
+目前在 Vue2 中，节点组件内容有一些限制，比如无法使用 Vuex、i18n、element-ui 等。如果需要使用这些功能，可以尝试
+使用 vue2-teleport 来增强能力，欢迎给我们提 PR（我们后面也会逐步增强该功能）。
+:::
+

package/dist/docs/tutorial/ai.en.md

@@ -0,0 +1,64 @@
+---
+nav: Guide
+group:
+  title: Introduction
+title: AI Programming Support
+order: 2
+toc: content
+---
+
+Starting from `@logicflow/core@2.3.0`, LogicFlow ships tutorial and API docs with the npm package. Copy the prompt on this page to your AI Agent so it can read local docs in your project instead of implementing LogicFlow features from general knowledge alone.
+
+## When to Copy the Prompt
+
+Copy the prompt in these situations:
+
+1. After installing `@logicflow/core` for the first time
+2. After upgrading `@logicflow/core`
+3. Before asking an Agent to implement LogicFlow features
+
+If your Agent already has an older prompt but still misses official plugin or layout capabilities, copy the latest prompt below again.
+
+## What the Agent Should Know
+
+LogicFlow is organized around three main packages:
+
+- `@logicflow/core`: the core graph editor runtime, including canvas, nodes, edges, models, events, rendering, themes, and basic interactions.
+- `@logicflow/extension`: the official extension package for common product features.
+- `@logicflow/layout`: the official layout plugin package for automatic graph layout.
+
+The docs for these packages are shipped under `node_modules/@logicflow/core/dist/docs/`. The docs for `@logicflow/extension` and `@logicflow/layout` mainly live under `tutorial/extension/`.
+
+## Prompt to Copy
+
+Copy the whole block below to your AI Agent:
+
+```md
+<!-- BEGIN:logicflow-agent-rules -->
+# LogicFlow Agent Rules
+
+LogicFlow documentation is available at:
+
+- `node_modules/@logicflow/core/dist/docs/`
+
+Package roles:
+
+- `@logicflow/core`: core graph editor runtime, including canvas, nodes, edges, models, events, rendering, themes, and basic interactions.
+- `@logicflow/extension`: official plugins for common product features.
+- `@logicflow/layout`: official layout plugins for automatic graph layout.
+
+The docs for `@logicflow/extension` and `@logicflow/layout` are included under:
+
+- `node_modules/@logicflow/core/dist/docs/tutorial/extension/`
+
+Before implementing any LogicFlow feature, check the local docs first to see whether LogicFlow already provides a built-in, extension, or layout capability. If it does, prefer the documented official capability instead of reimplementing it from scratch.
+
+If an official package is needed but not installed, ask the user before installing it.
+<!-- END:logicflow-agent-rules -->
+```
+
+## Next Reading
+
+- New to LogicFlow: read [Getting Started](get-started.en.md)
+- Need plugins or layout: read [Plugin Introduction](extension/intro.en.md)
+- Need exact API options: read [API Guide](../api/logicflow-instance/index.en.md)

package/dist/docs/tutorial/ai.zh.md

@@ -0,0 +1,64 @@
+---
+nav: 指南
+group:
+  title: 介绍
+title: AI 编程支持
+order: 2
+toc: content
+---
+
+LogicFlow 会从 `@logicflow/core@2.3.0` 开始，把教程和 API 文档随 npm 包一起发布。你可以把本页的提示词复制给 AI Agent，让它在你的项目里直接读取本地文档，而不是只凭通用经验实现功能。
+
+## 什么时候复制给 Agent
+
+建议在这些场景复制：
+
+1. 首次安装 `@logicflow/core` 后
+2. 升级 `@logicflow/core` 后
+3. 准备让 Agent 实现 LogicFlow 相关功能前
+
+如果 Agent 已经拿到旧提示词，但仍然没有按官方插件或布局能力实现功能，也可以重新复制下面的最新提示词。
+
+## Agent 需要知道什么
+
+LogicFlow 主要由三个包组成：
+
+- `@logicflow/core`：核心画布运行时，包含画布、节点、边、模型、事件、渲染、主题和基础交互能力。
+- `@logicflow/extension`：官方插件包，用于常见产品功能。
+- `@logicflow/layout`：官方布局插件包，用于自动布局。
+
+这些包的使用文档都发布在 `node_modules/@logicflow/core/dist/docs/` 中。其中 `@logicflow/extension` 和 `@logicflow/layout` 的文档主要在 `tutorial/extension/` 目录下。
+
+## 复制给 Agent 的提示词
+
+将下面整段内容复制给你的 AI Agent：
+
+```md
+<!-- BEGIN:logicflow-agent-rules -->
+# LogicFlow Agent Rules
+
+LogicFlow documentation is available at:
+
+- `node_modules/@logicflow/core/dist/docs/`
+
+Package roles:
+
+- `@logicflow/core`: core graph editor runtime, including canvas, nodes, edges, models, events, rendering, themes, and basic interactions.
+- `@logicflow/extension`: official plugins for common product features.
+- `@logicflow/layout`: official layout plugins for automatic graph layout.
+
+The docs for `@logicflow/extension` and `@logicflow/layout` are included under:
+
+- `node_modules/@logicflow/core/dist/docs/tutorial/extension/`
+
+Before implementing any LogicFlow feature, check the local docs first to see whether LogicFlow already provides a built-in, extension, or layout capability. If it does, prefer the documented official capability instead of reimplementing it from scratch.
+
+If an official package is needed but not installed, ask the user before installing it.
+<!-- END:logicflow-agent-rules -->
+```
+
+## 下一步阅读
+
+- 第一次接入 LogicFlow：阅读 [快速上手](get-started.zh.md)
+- 需要插件或布局能力：阅读 [插件简介](extension/intro.zh.md)
+- 需要精确 API 参数：阅读 [API 导览](../api/logicflow-instance/index.zh.md)