@logicflow/core 2.2.1 → 2.2.3

package/README.md

@@ -102,6 +102,38 @@ const lf = new LogicFlow({
 lf.render(data);
 ```
 
+## AI 编程支持
+
+LogicFlow 为 AI 编程工具提供了随 npm 包发布的本地文档。`@logicflow/core@2.2.2` 及以上版本会包含这些文档。安装或升级后，可以把下面这段提示词复制给你的 AI Agent，让它在实现 LogicFlow 功能前先查官方文档。
+
+更多说明请查看 [AI 编程支持](https://site.logic-flow.cn/tutorial/ai)。
+
+升级 `@logicflow/core` 后，请将最新版提示词再次提供给 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 -->
+```
+
 ## 文档
 
 [官方文档](https://docs.logic-flow.cn)

package/dist/docs/api/logicflow-constructor/index.en.md

@@ -0,0 +1,106 @@
+---
+nav: API
+group:
+  title: LogicFlow
+  order: 1
+title: Constructor
+toc: content
+order: 0
+---
+
+## Calling the constructor
+
+```tsx | pure
+import LogicFlow from '@logicflow/core'
+
+const options: LogicFlow.Options = {
+  // ...
+}
+new LogicFlow(options)
+```
+
+## Basic options
+
+| Option     | Type        | Required | Default | Description |
+| :--------- | :---------- | :------- | :------ | :---------- |
+| container  | `HTMLElement` | Yes    | -       | DOM container for the diagram. |
+| width      | number      | No       | -       | Canvas width in `px`; defaults to container width. |
+| height     | number      | No       | -       | Canvas height in `px`; defaults to container height. |
+| autoExpand | boolean     | No       | false   | Expand the canvas when nodes are dragged near the edge. |
+
+## Canvas options
+
+| Option           | Type | Required | Default | Description |
+| :--------------- | :--- | :------- | :------ | :---------- |
+| background       | false \| [`BackgroundConfig`](../type/MainTypes.en.md#backgroundconfig) | No | false | Background layer; `false` disables it. |
+| grid             | number / boolean / [`GridOptions`](../type/MainTypes.en.md#gridoptions) | No | false | Grid configuration. |
+| snapGrid         | boolean | No | false | Snap dragging to the grid. |
+| partial          | boolean | No | false | Enable partial rendering for large graphs. |
+| animation        | boolean \| `Partial<AnimationConfig>`（[`AnimationConfig`](../type/MainTypes.en.md#animationconfig)） | No | - | Animation toggles and per-kind settings. |
+| overlapMode      | [`OverlapMode`](../type/MainTypes.en.md#common) | No | - | Z-ordering when elements overlap. |
+| snapline         | boolean | No | true | Show snaplines while dragging nodes. |
+| stopScrollGraph  | boolean | No | false | Disable wheel panning. |
+| stopZoomGraph    | boolean | No | false | Disable zoom. |
+| stopMoveGraph    | boolean \| 'vertical' \| 'horizontal' \| [number, number, number, number] | No | false | Constrain or disable canvas panning. |
+
+## Edit control
+
+| Option                 | Type | Required | Default | Description |
+| :--------------------- | :--- | :------- | :------ | :---------- |
+| isSilentMode           | boolean | No | false | Read-only / presentation mode. |
+| guards                 | [`GuardsConfig`](../type/MainTypes.en.md#guardsconfig) | No | - | Guard callbacks (`beforeClone`, `beforeDelete`, …). |
+| disabledTools          | `string[]` | No | - | Built-in tools to disable. |
+| adjustEdge             | boolean | No | true | Allow edge adjustment. |
+| adjustEdgeStartAndEnd  | boolean | No | false | Allow dragging edge endpoints. |
+| adjustNodePosition     | boolean | No | true | Allow moving nodes. |
+| hideAnchors            | boolean | No | false | Hide node anchors. |
+| outline                | boolean | No | false | Outer selection box for nodes. |
+| hoverOutline           | boolean | No | true | Outline on hover. |
+| nodeSelectedOutline    | boolean | No | true | Outline when a node is selected. |
+| edgeSelectedOutline    | boolean | No | true | Outline when an edge is selected. |
+| nodeTextEdit           | boolean | No | true | Allow editing node text. |
+| edgeTextEdit           | boolean | No | true | Allow editing edge text. |
+| textEdit               | boolean | No | true | Master text-edit switch. |
+| nodeTextDraggable      | boolean | No | false | Allow dragging node text. |
+| edgeTextDraggable      | boolean | No | false | Allow dragging edge text. |
+| multipleSelectKey      | string | No | - | Multi-select modifier (`meta` / `shift` / `alt`). |
+| idGenerator            | function | No | - | Custom id generator for new nodes/edges. |
+| customTargetAnchor     | [`customTargetAnchorType`](../type/MainTypes.en.md#customtargetanchortype) | No | - | Custom anchor picking when connecting. |
+| edgeGenerator          | [`EdgeGeneratorType`](../type/MainTypes.en.md#edgegeneratortype) | No | - | Rule for edge type when connecting. |
+| customTrajectory       | function | No | - | Custom anchor line rendering. |
+
+## Keyboard
+
+| Option   | Type | Required | Default | Description |
+| :------- | :--- | :------- | :------ | :---------- |
+| keyboard | [`KeyboardDef`](../type/MainTypes.en.md#keyboarddef) | No | - | Keyboard shortcuts configuration. |
+
+Built-in shortcuts (when `keyboard.enabled = true`):
+
+- `cmd + c` / `ctrl + c`: copy
+- `cmd + v` / `ctrl + v`: paste
+- `cmd + z` / `ctrl + z`: undo
+- `cmd + y` / `ctrl + y`: redo
+- `backspace`: delete
+
+## Theme
+
+| Option    | Type | Required | Default | Description |
+| :-------- | :--- | :------- | :------ | :---------- |
+| style     | [`Theme`](../type/Theme.en.md#theme) | No | - | Visual theme for nodes, edges, text, anchors, etc. |
+| themeMode | string | No | - | Built-in presets: `default`, `dark`, `colorful`, `radius`. |
+| edgeType  | [`EdgeType`](../type/MainTypes.en.md#edgetype) | No | `polyline` | Default edge type created from the UI. |
+
+## Plugins
+
+| Option          | Type | Required | Default | Description |
+| :-------------- | :--- | :------- | :------ | :---------- |
+| disabledPlugins | `string[]` | No | - | Plugins not to load at init. |
+| plugins         | [`ExtensionConstructor`](../type/MainTypes.en.md#extensionconstructor)`[]` | No | - | Plugins for this instance; falls back to global list. |
+| pluginsOptions  | any | No | - | Options passed to plugins. |
+
+## History
+
+| Option  | Type | Required | Default | Description |
+| :------ | :--- | :------- | :------ | :---------- |
+| history | boolean | No | true | Enable undo/redo stack. |

package/dist/docs/api/logicflow-constructor/index.zh.md

@@ -0,0 +1,106 @@
+---
+nav: API
+group:
+  title: LogicFlow
+  order: 1
+title: 构造方法
+toc: content
+order: 0
+---
+
+## 构造方法调用
+
+```tsx | pure
+import LogicFlow from '@logicflow/core'
+
+const options: LogicFlow.Options = {
+  // ...
+}
+new LogicFlow(options)
+```
+
+## 基础配置
+
+| 选项 | 类型 | 必选 | 默认值 | 描述 |
+| :--- | :--- | :--- | :--- | :--- |
+| container | `HTMLElement` | ✅ | - | 图的 DOM 容器。 |
+| width | number | - | - | 指定画布宽度，单位为 `px`，默认使用容器宽度。 |
+| height | number | - | - | 指定画布高度，单位为 `px`，默认使用容器高度。 |
+| autoExpand | boolean | - | false | 节点拖动靠近画布边缘时是否自动扩充画布。 |
+
+## 画布配置
+
+| 选项 | 类型 | 必选 | 默认值 | 描述 |
+| :--- | :--- | :--- | :--- | :--- |
+| background | false \| [`BackgroundConfig`](../type/MainTypes.zh.md#backgroundconfig背景配置) | - | false | 画布背景，默认无背景，支持传入参数配置。 |
+| grid | number / boolean / [`GridOptions`](../type/MainTypes.zh.md#gridoptions网格配置) | - | false | 网格配置，支持关闭、默认点状网格或自定义参数。 |
+| snapGrid | boolean | - | false | 是否开启网格吸附。 |
+| partial | boolean | - | false | 是否开启局部渲染功能。 |
+| animation | boolean \| `Partial<AnimationConfig>`（[`AnimationConfig`](../type/MainTypes.zh.md#animationconfig动画配置)） | - | - | 是否开启动画功能，可统一开关和单独配置。 |
+| overlapMode | [`OverlapMode`](../type/MainTypes.zh.md#common实例基础配置项) | - | - | 元素重合堆叠模式。 |
+| snapline | boolean | - | true | 是否启用节点辅助对齐线。 |
+| stopScrollGraph | boolean | - | false | 禁止鼠标滚动移动画布。 |
+| stopZoomGraph | boolean | - | false | 禁止缩放画布。 |
+| stopMoveGraph | boolean \| 'vertical' \| 'horizontal' \| [number, number, number, number] | - | false | 禁止拖动画布。 |
+
+## 编辑控制
+
+| 选项 | 类型 | 必选 | 默认值 | 描述 |
+| :--- | :--- | :--- | :--- | :--- |
+| isSilentMode | boolean | - | false | 仅浏览不可编辑模式，默认不开启。 |
+| guards | [`GuardsConfig`](../type/MainTypes.zh.md#guardsconfig守卫函数类型) | - | - | 守卫函数配置（`beforeClone`、`beforeDelete`）。 |
+| disabledTools | `string[]` | - | - | 禁止启用的内置工具。 |
+| adjustEdge | boolean | - | true | 允许调整边。 |
+| adjustEdgeStartAndEnd | boolean | - | false | 是否允许拖动边端点调整连线。 |
+| adjustNodePosition | boolean | - | true | 是否允许拖动节点。 |
+| hideAnchors | boolean | - | false | 是否隐藏节点锚点。 |
+| outline | boolean | - | false | 节点选择外侧选框是否展示。 |
+| hoverOutline | boolean | - | true | 鼠标悬停时是否显示节点外框。 |
+| nodeSelectedOutline | boolean | - | true | 节点选中时是否显示节点外框。 |
+| edgeSelectedOutline | boolean | - | true | 边选中时是否显示边外框。 |
+| nodeTextEdit | boolean | - | true | 允许节点文本编辑。 |
+| edgeTextEdit | boolean | - | true | 允许边文本编辑。 |
+| textEdit | boolean | - | true | 是否开启文本编辑。 |
+| nodeTextDraggable | boolean | - | false | 允许节点文本拖拽。 |
+| edgeTextDraggable | boolean | - | false | 允许边文本拖拽。 |
+| multipleSelectKey | string | - | - | 多选按键（`meta` / `shift` / `alt`）。 |
+| idGenerator | function | - | - | 自定义创建节点、连线时的 ID 生成规则。 |
+| customTargetAnchor | [`customTargetAnchorType`](../type/MainTypes.zh.md#customtargetanchortype自定义锚点连接规则) | - | - | 自定义锚点连接规则。 |
+| edgeGenerator | [`EdgeGeneratorType`](../type/MainTypes.zh.md#edgegeneratortype自定义边生成函数) | - | - | 连接节点及移动边时边的生成规则。 |
+| customTrajectory | function | - | - | 自定义连线轨迹。 |
+
+## 快捷键配置
+
+| 选项 | 类型 | 必选 | 默认值 | 描述 |
+| :--- | :--- | :--- | :--- | :--- |
+| keyboard | [`KeyboardDef`](../type/MainTypes.zh.md#keyboarddef快捷键参数类型) | - | - | 自定义键盘相关配置。 |
+
+内置快捷键（启用 `keyboard.enabled = true` 后可用）：
+
+- `cmd + c` / `ctrl + c`：复制
+- `cmd + v` / `ctrl + v`：粘贴
+- `cmd + z` / `ctrl + z`：撤销
+- `cmd + y` / `ctrl + y`：重做
+- `backspace`：删除
+
+## 主题配置
+
+| 选项 | 类型 | 必选 | 默认值 | 描述 |
+| :--- | :--- | :--- | :--- | :--- |
+| style | [`Theme`](../type/Theme.zh.md#theme主题配置) | - | - | 样式配置，用于定义节点、边、文本、锚点等视觉效果。 |
+| themeMode | string | - | - | 主题类型，内置支持 `default` / `dark` / `colorful` / `radius`。 |
+| edgeType | [`EdgeType`](../type/MainTypes.zh.md#edgetype边类型) | - | `polyline` | 在图上编辑创建边的默认类型。 |
+
+## 插件控制
+
+| 选项 | 类型 | 必选 | 默认值 | 描述 |
+| :--- | :--- | :--- | :--- | :--- |
+| disabledPlugins | `string[]` | - | - | 初始化时禁用加载的插件。 |
+| plugins | [`ExtensionConstructor`](../type/MainTypes.zh.md#extensionconstructor插件构造函数)`[]` | - | - | 当前实例加载的插件，不传则采用全局插件。 |
+| pluginsOptions | any | - | - | 插件初始化选项。 |
+
+## 历史记录
+
+| 选项 | 类型 | 必选 | 默认值 | 描述 |
+| :--- | :--- | :--- | :--- | :--- |
+| history | boolean | - | true | 是否开启历史记录功能。 |

package/dist/docs/api/logicflow-constructor/use.en.md

@@ -0,0 +1,61 @@
+---
+nav: API
+group:
+  title: LogicFlow
+  order: 1
+title: LogicFlow.use
+toc: content
+order: 1
+---
+
+Register a plugin globally.
+
+```ts
+LogicFlow.use(
+  extension: ExtensionConstructor | ExtensionDefinition,
+  props?: Record<string, unknown>,
+): void
+```
+
+Parameters:
+
+| Name | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `extension` | [`ExtensionConstructor`](../type/MainTypes.en.md#extensionconstructor) \| [`ExtensionDefinition`](../type/MainTypes.en.md#extensiondefinition) | Yes | Plugin constructor or definition object. |
+| `props` | `Record<string, unknown>` | No | Options passed to the plugin at registration time. |
+
+Example:
+
+```ts
+import LogicFlow from '@logicflow/core'
+
+class CustomPlugin {
+  static pluginName = 'CustomPlugin'
+
+  constructor({ lf, LogicFlow, props }) {
+    this.lf = lf
+    this.LogicFlow = LogicFlow
+    this.props = props
+  }
+
+  render(lf, container) {
+    const el = document.createElement('div')
+    el.textContent = 'Custom plugin'
+    container.appendChild(el)
+  }
+
+  destroy() {
+    // Clean up listeners, timers, etc.
+  }
+}
+
+LogicFlow.use(CustomPlugin, {
+  featureFlag: true,
+})
+```
+
+Notes:
+
+- `use` is static: call `LogicFlow.use(...)`.
+- Plugins should expose a unique `pluginName` to avoid collisions.
+- Whether a plugin runs for a given instance also depends on instance options (for example disabled lists).

package/dist/docs/api/logicflow-constructor/use.zh.md

@@ -0,0 +1,61 @@
+---
+nav: API
+group:
+  title: LogicFlow
+  order: 1
+title: LogicFlow.use
+toc: content
+order: 1
+---
+
+全局注册插件。
+
+```ts
+LogicFlow.use(
+  extension: ExtensionConstructor | ExtensionDefinition,
+  props?: Record<string, unknown>,
+): void
+```
+
+参数说明：
+
+| 名称 | 类型 | 必传 | 描述 |
+| :--- | :--- | :--- | :--- |
+| `extension` | [`ExtensionConstructor`](../type/MainTypes.zh.md#extensionconstructor插件构造函数) \| [`ExtensionDefinition`](../type/MainTypes.zh.md#extensiondefinition插件定义) | 是 | 插件构造器或插件定义对象 |
+| `props` | `Record<string, unknown>` | 否 | 注册时传入的插件配置 |
+
+示例：
+
+```ts
+import LogicFlow from '@logicflow/core'
+
+class CustomPlugin {
+  static pluginName = 'CustomPlugin'
+
+  constructor({ lf, LogicFlow, props }) {
+    this.lf = lf
+    this.LogicFlow = LogicFlow
+    this.props = props
+  }
+
+  render(lf, container) {
+    const el = document.createElement('div')
+    el.textContent = 'Custom plugin'
+    container.appendChild(el)
+  }
+
+  destroy() {
+    // 清理监听、定时器等资源
+  }
+}
+
+LogicFlow.use(CustomPlugin, {
+  featureFlag: true,
+})
+```
+
+说明：
+
+- `use` 是静态方法，需通过 `LogicFlow.use(...)` 调用。
+- 插件应提供唯一的 `pluginName`，避免同名冲突。
+- 插件是否在某个实例内生效，还受实例配置（如禁用列表）影响。

package/dist/docs/api/logicflow-instance/canvas.en.md

@@ -0,0 +1,197 @@
+---
+nav: API
+group:
+  title: LogicFlow Instance
+  order: 2
+title: Canvas
+toc: content
+order: 8
+---
+
+This page documents instance APIs for canvas size, viewport transforms, coordinate conversion, and edge animation.
+
+### resize
+
+Resize the canvas; when omitted, width and height are recomputed from the container.
+
+**Signature**
+
+```ts
+resize(width?: number, height?: number): void
+```
+
+**Parameters**
+
+| Name | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `width` | `number` | No | Target width. |
+| `height` | `number` | No | Target height. |
+
+### focusOn
+
+Center the viewport on a node id or a canvas coordinate.
+
+**Signature**
+
+```ts
+focusOn(focusOnArgs: { id?: string; coordinate?: { x: number; y: number } }): void
+```
+
+**Parameters**
+
+| Name | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `focusOnArgs` | `object` | Yes | Provide either `id` or `coordinate`. |
+
+### zoom
+
+Zoom by step or explicit ratio, optionally around a point.
+
+**Signature**
+
+```ts
+zoom(zoomSize?: boolean | number, point?: [number, number]): string
+```
+
+**Returns**
+
+- `string`: current zoom as a percentage string.
+
+### resetZoom
+
+Reset zoom to `1`.
+
+**Signature**
+
+```ts
+resetZoom(): void
+```
+
+### setZoomMiniSize
+
+Set the minimum allowed zoom factor.
+
+**Signature**
+
+```ts
+setZoomMiniSize(size: number): void
+```
+
+### setZoomMaxSize
+
+Set the maximum allowed zoom factor.
+
+**Signature**
+
+```ts
+setZoomMaxSize(size: number): void
+```
+
+### getTransform
+
+Read the current transform (scale and translation).
+
+**Signature**
+
+```ts
+getTransform(): {
+  SCALE_X: number;
+  SCALE_Y: number;
+  TRANSLATE_X: number;
+  TRANSLATE_Y: number;
+}
+```
+
+### translate
+
+Translate the canvas by a relative offset.
+
+**Signature**
+
+```ts
+translate(x: number, y: number): void
+```
+
+### resetTranslate
+
+Reset translation to the initial state.
+
+**Signature**
+
+```ts
+resetTranslate(): void
+```
+
+### translateCenter
+
+Center the graph content inside the viewport.
+
+**Signature**
+
+```ts
+translateCenter(): void
+```
+
+### fitView
+
+Adjust zoom and translation so the graph fits the viewport.
+
+**Signature**
+
+```ts
+fitView(verticalOffset?: number, horizontalOffset?: number): void
+```
+
+### getPointByClient
+
+Convert page coordinates to overlay positions (DOM and canvas layers).
+
+**Signature**
+
+```ts
+getPointByClient(x: number, y: number): {
+  domOverlayPosition: { x: number; y: number };
+  canvasOverlayPosition: { x: number; y: number };
+}
+```
+
+### toFront
+
+Raise the z-order of a node or edge.
+
+**Signature**
+
+```ts
+toFront(id: string): void
+```
+
+### openEdgeAnimation
+
+Enable animation for an edge.
+
+**Signature**
+
+```ts
+openEdgeAnimation(edgeId: string): void
+```
+
+### closeEdgeAnimation
+
+Disable animation for an edge.
+
+**Signature**
+
+```ts
+closeEdgeAnimation(edgeId: string): void
+```
+
+### Common recipes
+
+```ts
+lf.resize();
+lf.translateCenter();
+lf.zoom(1.2);
+
+const point = lf.getPointByClient(300, 200);
+lf.focusOn({ coordinate: point.canvasOverlayPosition });
+```