@logicflow/core 2.2.1 → 2.2.3

package/dist/docs/tutorial/extension/minimap.en.md

@@ -0,0 +1,164 @@
+---
+nav: Guide
+group:
+  title: Plug-in functionality
+  order: 3
+title: MiniMap
+order: 4
+toc: content
+---
+
+<style>
+table td:first-of-type {
+  word-break: normal;
+}
+</style>
+
+LogicFlow's canvas MiniMap is a thumbnail view that helps users quickly navigate and locate different areas of large or complex diagrams.
+
+This article covers the latest syntax for version 2.0. For versions before 2.0, please visit the [old version](https://docs.logic-flow.cn/docs/#/zh/guide/extension/component-minimap).
+
+## Demonstration
+
+<code id="react-portal" src="@/src/tutorial/extension/mini-map"></code>
+
+## Usage
+
+### 1. Registration
+
+There are two registration methods: global registration and local registration. The difference is that global registration allows every `lf` instance to use it.
+
+```tsx | pure
+import LogicFlow from "@logicflow/core";
+import { MiniMap } from "@logicflow/extension";
+
+// Global registration
+LogicFlow.use(MiniMap);
+
+// Local registration
+const lf = new LogicFlow({
+  ...config,
+  plugins: [MiniMap]
+});
+```
+
+### 2. Configuration
+
+When initializing the `lf` instance, you can customize the MiniMap's capabilities through `pluginsOptions`.
+
+```tsx | pure
+const miniMapOptions: MiniMap.MiniMapOption = {
+  ...options
+}
+
+const lf = new LogicFlow({
+  ...config,
+  plugins: [MiniMap],
+  pluginsOptions: {
+    miniMap: miniMapOptions,
+  },
+});
+```
+
+The `miniMapOptions` configuration is as follows:
+
+| Property Name   | Type    | Default Value | Required | Description                                                                                           |
+| --------------- | ------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------- |
+| width           | number  | 150           | -        | The width of the canvas in the MiniMap                                                                |
+| height          | number  | 220           | -        | The height of the canvas in the MiniMap                                                               |
+| showEdge        | boolean | false         | -        | Whether to render edges in the MiniMap                                                                |
+| headerTitle     | string  | Navigation    | -        | The text content of the MiniMap's title bar; defaults to not showing                                  |
+| isShowHeader    | boolean | false         | -        | Whether to show the MiniMap's title bar                                                               |
+| isShowCloseIcon | boolean | false         | -        | Whether to show the close button                                                                      |
+| leftPosition    | number  | -             | -        | The left margin of the MiniMap from the canvas's left boundary; takes precedence over `rightPosition` |
+| rightPosition   | number  | 0             | -        | The right margin of the MiniMap from the canvas's right boundary; lower priority than `leftPosition`  |
+| topPosition     | number  | -             | -        | The top margin of the MiniMap from the canvas's top boundary; takes precedence over `bottomPosition`  |
+| bottomPosition  | number  | 0             | -        | The bottom margin of the MiniMap from the canvas's bottom boundary; lower priority than `topPosition` |
+
+## API
+
+### show
+
+By default, the MiniMap is not displayed after being included; you need to manually enable it.
+
+```tsx | pure
+lf.extension.miniMap.show(left?: number, top?: number): void
+```
+
+`show()` supports passing `left` and `top` style properties to determine the MiniMap's position relative to the top-left corner of the canvas. If not provided, it defaults to the bottom-right corner of the canvas.
+
+Providing only `left` and `top` values allows integration with the `lf.getPointByClient` API. For more flexible styling, you can directly set styles via class names:
+
+- `lf-mini-map` - MiniMap root element
+- `lf-mini-map-header` - MiniMap header element
+- `lf-mini-map-graph` - MiniMap canvas element
+- `lf-mini-map-close` - MiniMap close icon element
+
+:::warning
+`MiniMap.show()` must be called after `lf.render()`. Otherwise, the console will always show a warning.
+:::
+
+### hide
+
+Hide the MiniMap.
+
+```tsx | pure
+lf.extension.miniMap.hide(): void
+```
+
+### reset
+
+Reset the MiniMap's zoom and translation, essentially resetting the canvas's zoom and translation.
+
+```tsx | pure
+lf.extension.miniMap.reset(): void
+```
+
+Internal implementation:
+
+```tsx | pure
+lf.resetTranslate()
+lf.resetZoom()
+```
+
+### updatePosition
+
+Update the MiniMap's position on the canvas.
+
+```tsx | pure
+lf.extension.miniMap.updatePosition(MiniMapPosition): void
+```
+
+`MiniMapPosition` parameter is as follows:
+
+```tsx | pure
+export type AbsolutePosition = Partial<
+  Record<'left' | 'right' | 'top' | 'bottom', number>
+>
+
+export type MiniMapPosition =
+  | 'left-top' // Indicates the MiniMap is located at the top-left corner of the container
+  | 'right-top' // Indicates the MiniMap is located at the top-right corner of the container
+  | 'left-bottom' // Indicates the MiniMap is located at the bottom-left corner of the container
+  | 'right-bottom' // Indicates the MiniMap is located at the bottom-right corner of the container
+  | AbsolutePosition // Custom position of the MiniMap on the canvas
+```
+
+### setShowEdge
+
+Set whether the edges are displayed in the MiniMap's canvas.
+
+```tsx | pure
+lf.extension.miniMap.setShowEdge(showEdge: boolean): void
+```
+
+`showEdge`: `true` to display, `false` to hide.
+
+## Events
+
+MiniMap events.
+
+| Event Name    | Description    | Event Object |
+| ------------- | -------------- | ------------ |
+| miniMap:close | MiniMap hidden | {}           |
+

package/dist/docs/tutorial/extension/minimap.zh.md

@@ -0,0 +1,180 @@
+---
+nav: 指南
+group:
+  title: 插件功能
+  order: 3
+title: 小地图 (MiniMap)
+order: 4
+toc: content
+---
+
+<style>
+table td:first-of-type {
+  word-break: normal;
+}
+</style>
+
+LogicFlow 的画布小地图是一个缩略图视图，帮助用户快速导航和定位大型或复杂图表的不同区域。
+
+本文是 2.0 版本最新语法，2.0 版本以前请移步<a href="https://docs.logic-flow.cn/docs/#/zh/guide/extension/component-minimap" target="_blank">旧版</a>。
+
+## 演示
+
+<code id="react-portal" src="@/src/tutorial/extension/mini-map"></code>
+
+## 使用
+
+### 1. 注册
+
+两种注册方式，全局注册和局部注册，区别是全局注册每一个 `lf` 实例都可以使用。
+
+```tsx | pure
+import LogicFlow from "@logicflow/core";
+import { MiniMap } from "@logicflow/extension";
+
+// 全局注册
+LogicFlow.use(MiniMap);
+
+// 局部注册
+const lf = new LogicFlow({
+  ...config,
+  plugins: [MiniMap]
+});
+
+```
+
+### 2. 配置
+
+在初始化 `lf` 实例时可以通过 `pluginsOptions` 自定义配置 mini-map 的能力。
+
+```tsx | pure
+
+const miniMapOptions: MiniMap.MiniMapOption = {
+  ...options
+}
+
+const lf = new LogicFlow({
+  ...config,
+  plugins: [MiniMap],
+  pluginsOptions: {
+    miniMap: miniMapOptions,
+  },
+});
+
+```
+
+`miniMapOptions` 配置如下：
+
+| 属性名          | 类型    | 默认值 | 必填 | 描述                                                   |
+| --------------- | ------- | ------ | ---- | ------------------------------------------------------ |
+| width           | number  | 150    | -    | 小地图中画布的宽度                                     |
+| height          | number  | 220    | -    | 小地图中画布的高度                                     |
+| showEdge        | boolean | false  | -    | 在小地图的画布中是否渲染边                             |
+| headerTitle     | string  | 导航   | -    | 小地图标题栏的文本内容，默认不显示                     |
+| isShowHeader    | boolean | false  | -    | 是否显示小地图的标题栏                                 |
+| isShowCloseIcon | boolean | false  | -    | 是否显示关闭按钮                                       |
+| leftPosition    | number  | -      | -    | 小地图与画布左边界的左边距，优先级高于`rightPosition`  |
+| rightPosition   | number  | 0      | -    | 小地图与画布右边界的右边距，优先级低于`leftPosition`   |
+| topPosition     | number  | -      | -    | 小地图与画布上边界的上边距，优先级高于`bottomPosition` |
+| bottomPosition  | number  | 0      | -    | 小地图与画布下边界的下边距，优先级低于`topPosition`    |
+
+## API
+
+### show
+
+引入 mini-map 后默认不展示，需要手动开启显示。
+
+```tsx | pure
+
+lf.extension.miniMap.show(left?: number, top?: number): void
+
+```
+
+`show()` 支持传入样式属性 left 和 top 的值，用来确定 mini-map 在画布中相对于左上角的位置，不传默认显示在画布右下角。
+
+只提供 left 和 top 这两个值是因为可以与`lf.getPointByClient` API 配合使用，如果想实现更加灵活的样式，可以直接通过类名设置样式。
+
+- `lf-mini-map` - mini-map 根元素
+- `lf-mini-map-header` - mini-map 头部元素
+- `lf-mini-map-graph` - mini-map 画布元素
+- `lf-mini-map-close` - mini-map 关闭图标元素
+
+:::warning
+`MiniMap.show()`必须在`lf.render()`后调用。否则控制台会一直有警告
+:::
+
+### hide
+
+隐藏 mini-map。
+
+```tsx | pure
+
+lf.extension.miniMap.hide(): void
+
+```
+
+### reset
+
+重置 mini-map 的缩放和平移，本质是重置画布的缩放和平移。
+
+```tsx | pure
+
+lf.extension.miniMap.reset(): void
+
+```
+
+内部实现：
+
+```tsx | pure
+
+lf.resetTranslate()
+lf.resetZoom()
+
+```
+
+### updatePosition
+
+更新小地图在画布中的位置。
+
+```tsx | pure
+
+lf.extension.miniMap.updatePosition(MiniMapPosition): void
+
+```
+
+`MiniMapPosition` 参数如下：
+
+```tsx | pure
+
+export type AbsolutePosition = Partial<
+  Record<'left' | 'right' | 'top' | 'bottom', number>
+>
+
+export type MiniMapPosition =
+  | 'left-top' // 表示迷你地图位于容器的左上角
+  | 'right-top' // 表示迷你地图位于容器的右上角
+  | 'left-bottom' // 表示迷你地图位于容器的左下角
+  | 'right-bottom' // 表示迷你地图位于容器的右下角。
+  | AbsolutePosition // 自定义小地图在画布上的位置
+
+```
+
+### setShowEdge
+
+设置小地图的画布中是否显示边。
+
+```tsx | pure
+
+lf.extension.miniMap.setShowEdge(showEdge: boolean): void
+
+```
+
+`showEdge`: `true` 显示，`false` 隐藏。
+
+## 事件
+
+mini-map 事件。
+
+| 事件名        | 说明       | 事件对象 |
+| ------------- | ---------- | -------- |
+| miniMap:close | 小地图隐藏 | {}       |

package/dist/docs/tutorial/extension/node-resize.en.md

@@ -0,0 +1,199 @@
+---
+nav: Guide
+group:
+  title: Plug-in functionality
+  order: 3
+title: NodeResize
+order: 16
+toc: content
+tag: Deprecated
+---
+
+## Use
+
+LogicFlow provides `RectResize`, `EllipseResize`, `DiamondResize`, `HtmlResize` in the extension package, each node has `view` and `model` attributes. The scaling of nodes is also achieved by using LogicFlow's custom node mechanism, which allows developers to inherit from these 4 types of nodes that can be scaled to achieve node scaling.
+
+For example, if we need a rectangle that can be scaled, when we didn't support node scaling before, we customize the node in the following way:
+
+```tsx | pure
+import { RectNode, RectNodeModel } from '@logicflow/core'
+
+class CustomNode extends RectNode {
+}
+
+class CustomNodeModel extends RectNodeModel {
+}
+
+export default {
+  type: 'custom-node',
+  model: CustomNodeModel,
+  view: CustomNode,
+}
+```
+
+If we expect the custom node to be scaled, then change it to:
+
+```tsx | pure
+import { RectResize } from '@logicflow/extension'
+
+class CustomNode extends RectResize.view {
+}
+
+class CustomNodeModel extends RectResize.model {
+}
+
+export default {
+  type: 'custom-node',
+  model: CustomNodeModel,
+  view: CustomNode,
+}
+```
+
+### Setting shape attributes of a node
+
+LogicFlow calls the attributes of a node such as width, height, radius, etc. as [ShapeAttributes](../../api/runtime-model/nodeModel.en.md#shape-attributes), we can override the [initNodeData](../../api/runtime-model/nodeModel.en.md#initnodedata) or [ setAttributes](../../api/runtime-model/nodeModel.en.md#setattributes) methods to set the shape attributes of a node. But when the node can be scaled, we can't set the width and height in `setAttributes`, only in `initNodeData`.
+
+```tsx | pure
+class ResizableRectModel extends RectResize.model {
+  initNodeData(data) {
+    super.initNodeData(data);
+    this.width = 100;
+    this.height = 40;
+  }
+}
+```
+
+### Customizing the view of a node
+
+As mentioned in Customizing Nodes, for nodes with complex style attributes, we can override the `getShape` method in `view` to achieve the real rendered appearance of the custom node. However, since custom nodes need to populate the node's appearance with adjustment points for scaling, we need to override `getResizeShape`, not `getShape`, for the view of a custom scalable node.
+
+```tsx | pure
+import { RectResize } from "@logicflow/extension";
+
+class ResizableRectModel extends RectResize.model {
+  initNodeData(data) {
+    super.initNodeData(data);
+    this.width = 100;
+    this.height = 40;
+    this.text.draggable = true;
+  }
+}
+class ResizableRectView extends RectResize.view {
+  getResizeShape() {
+    const { model } = this.props;
+    const { x, y, width, height, radius, properties } = model;
+    const style = model.getNodeStyle();
+    return h("g", {}, [
+      h("rect", {
+        ...style,
+        x: x - width / 2,
+        y: y - height / 2,
+        rx: radius,
+        ry: radius,
+        width,
+        height,
+      }),
+    ]);
+  }
+}
+
+export default {
+  type: "resizable-rect",
+  view: ResizableRectView,
+  model: ResizableRectModel,
+};
+```
+
+:::info{title=tip}
+For nodes that inherit `HtmlResize`, customize `view` by continuing to use the `setHtml` method of the `view` of the custom HTML node.
+:::
+
+## Event `node:resize` is thrown after node resizing.
+
+Throw event `node:resize` after node resizing, the data include node position and node size before and after node resizing, the data is {preData, data}, the details are as follows.
+| Name      | Type   | Description                         |
+| :-------- | :----- | :---------------------------------- |
+| id        | string | Node id                             |
+| type      | string | Node type                           |
+| modelType | string | Node graph type, internally defined |
+| x         | number | Node center x-axis coordinates      |
+| y         | number | Node center y-axis coordinate       |
+| rx        | number | x-axis radius (ellipse, rhombus)    |
+| ry        | number | y-axis radius (ellipse, diamond)    |
+| width     | number | Node width (rectangle)              |
+| height    | number | Node height (rectangle)             |
+
+```tsx | pure
+lf.on("node:resize", ({ preData, data }) => {
+  console.log(preData, data);
+});
+```
+
+## Setting the maximum and minimum values for zoom-in and zoom-out
+
+After `v1.1.8`, the zoom-in/zoom-out of a node supports setting the maximum and minimum values.
+
+```tsx | pure
+class ResizableRectModel extends RectResize.model {
+  initNodeData(data) {
+    super.initNodeData(data);
+    this.width = 100;
+    this.height = 40;
+    this.maxWidth = 400;
+    this.maxHeight = 400;
+  }
+}
+```
+
+## Setting the adjustment default distance for zooming in and out
+
+After `v1.1.8`, it is supported to set the `girdSize` property of a node, which is used to control how much distance to move the mouse before starting to zoom the node.
+
+```tsx | pure
+class ResizableRectModel extends RectResize.model {
+  initNodeData(data) {
+    super.initNodeData(data);
+    this.gridSize = 400;
+  }
+}
+```
+:::info{title=gridSize on node scaling}
+In most cases, to keep the nodes `neat` and to facilitate top/bottom/right/left/right alignment between nodes. `logicflow` defaults to change the size of nodes when zooming in and out, only when the mouse movement distance reaches twice the `gridSize` passed to the initialization canvas. But this has the disadvantage of a laggy feeling when adjusting. You can set the `gridSize` of each node individually without changing the initialized `gridSize` to make zooming in and out smoother.
+:::
+
+## Settings to adjust the border style
+
+The resizable node displays a dashed box against the node when it is selected (the rectangle does not). Customizing its style can be achieved by overriding the `getResizeOutlineStyle` method.
+
+```tsx | pure
+class ResizableRectModel extends RectResize.model {
+  getResizeOutlineStyle() {
+    return {
+      stroke: "#000000",
+      strokeWidth: 1,
+      strokeDasharray: "3,3",
+    };
+  }
+}
+```
+
+## Setting the resize point style
+
+When the zoom-in/zoom-out node is selected, action points for resizing the node are generated at the four corners of the dashed box, which can be customized by overriding the `getControlPointStyle` method.
+
+```tsx | pure
+class ResizableRectModel extends RectResize.model {
+  getControlPointStyle() {
+    return {
+      width: 7,
+      height: 7,
+      fill: "#FFFFFF",
+      stroke: "#000000",
+    };
+  }
+}
+```
+
+address: [https://codesandbox.io/s/prod-resonance-ztpvtv](https://codesandbox.io/s/prod-resonance-ztpvtv?file=/step_26_nodeResize/index.js)
+
+<a href="https://codesandbox.io/embed/prod-resonance-ztpvtv?fontsize=14&hidenavigation=1&theme=dark&view=preview" target="_blank"> Go to CodeSandbox for examples </a>