@lupinum/board-core 1.0.0-beta.3 → 1.0.0-beta.5

package/dist/agent/pages/docs/build-features/connections.md

@@ -0,0 +1,572 @@
+---
+title: "Connections"
+description: "Add edges between nodes with the connections plugin — anchors, routing styles, and the SVG connection layer."
+url: "https://nuxt-board.lupinum.com/docs/build-features/connections"
+route: "/docs/build-features/connections"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Connections
+
+> Add edges between nodes with the connections plugin — anchors, routing styles, and the SVG connection layer.
+
+Connections draw edges between nodes. Install the plugin, create edges, and the connection layer renders them as SVG paths with five routing styles.
+
+## Live example source
+
+Use the installation guide to register @lupinum/nuxt-board. These are the actual documentation demo files. Keep their paths under app/. The module auto-imports Board components; install the optional packages named in imports. For the local content components, use components: [{ path: "~/components/content", pathPrefix: false }, "~/components"] in nuxt.config.ts, as this site does, or import them explicitly. createDemoDocument is a local helper, not a package export. DocsLab and the inspector components provide presentation only.
+
+### app/components/demos/ConnectionsBoardDemo.vue
+
+````vue
+<script setup lang="ts">
+import { computed, onMounted, ref } from 'vue'
+import { asNodeId, createBoardEngine } from '@lupinum/board-core'
+import { createDemoDocument } from '../../utils/demoDocument'
+import {
+  connectionsPlugin,
+  type ConnectionRouting,
+} from '@lupinum/board-connections'
+import { BoardConnectionLayer } from '@lupinum/board-connections/vue'
+import { historyPlugin } from '@lupinum/board-history'
+import { BoardMinimap } from '@lupinum/vue-board/minimap'
+
+const engine = createBoardEngine({
+  grid: { size: 20, majorEvery: 5, snap: true, pattern: 'dot' },
+  plugins: [historyPlugin(), connectionsPlugin()],
+})
+
+const historyState = computed(() => engine.plugins.history.getState())
+const routing = ref<ConnectionRouting>('bezier')
+const INPUT_ID = asNodeId('input')
+const PARSE_ID = asNodeId('parse')
+const SCORE_ID = asNodeId('score')
+const OUTPUT_ID = asNodeId('output')
+let shuffleStep = 0
+
+function seed() {
+  engine.loadDocument(
+    createDemoDocument({
+      camera: { x: -80, y: -40, z: 1 },
+      grid: engine.getGridSettings(),
+      nodes: [
+        {
+          id: 'input',
+          type: 'text',
+          x: 80,
+          y: 150,
+          width: 180,
+          height: 96,
+          text: 'Collect input',
+          zIndex: 1,
+          locked: false,
+          visible: true,
+        },
+        {
+          id: 'parse',
+          type: 'text',
+          x: 340,
+          y: 80,
+          width: 200,
+          height: 96,
+          text: 'Normalize data',
+          zIndex: 2,
+          locked: false,
+          visible: true,
+        },
+        {
+          id: 'score',
+          type: 'text',
+          x: 340,
+          y: 240,
+          width: 200,
+          height: 96,
+          text: 'Score result',
+          zIndex: 3,
+          locked: false,
+          visible: true,
+        },
+        {
+          id: 'output',
+          type: 'text',
+          x: 650,
+          y: 150,
+          width: 180,
+          height: 96,
+          text: 'Publish output',
+          zIndex: 4,
+          locked: false,
+          visible: true,
+        },
+      ],
+      selection: [],
+      nextZIndex: 5,
+    }),
+    { mode: 'replace' },
+  )
+  const connections = engine.plugins.connections
+  for (const edge of connections.getEdges()) {
+    connections.deleteEdge(edge.id)
+  }
+  connections.createEdge({
+    from: INPUT_ID,
+    to: PARSE_ID,
+    label: 'clean',
+    data: {},
+  })
+  connections.createEdge({
+    from: INPUT_ID,
+    to: SCORE_ID,
+    label: 'rank',
+    data: {},
+  })
+  connections.createEdge({
+    from: PARSE_ID,
+    to: OUTPUT_ID,
+    label: 'emit',
+    data: {},
+  })
+  connections.createEdge({
+    from: SCORE_ID,
+    to: OUTPUT_ID,
+    label: 'merge',
+    data: {},
+  })
+}
+
+function shuffle() {
+  shuffleStep = (shuffleStep + 1) % 3
+  engine.updateNode(PARSE_ID, {
+    x: 320 + shuffleStep * 28,
+    y: 60 + shuffleStep * 22,
+  })
+  engine.updateNode(SCORE_ID, {
+    x: 360 - shuffleStep * 20,
+    y: 220 + shuffleStep * 18,
+  })
+  engine.updateNode(OUTPUT_ID, {
+    x: 620 + shuffleStep * 26,
+    y: 120 + shuffleStep * 24,
+  })
+}
+
+onMounted(async () => {
+  seed()
+  await engine.zoomToFit(84, false)
+})
+</script>
+
+<template>
+  <div class="demo-frame">
+    <div class="demo-toolbar">
+      <button class="demo-danger" @click="seed">Reset</button>
+      <button @click="shuffle">Shuffle</button>
+      <span class="demo-toggle-group">
+        <button
+          :class="{ active: routing === 'bezier' }"
+          @click="routing = 'bezier'"
+        >
+          Bezier
+        </button>
+        <button
+          :class="{ active: routing === 'smooth-step' }"
+          @click="routing = 'smooth-step'"
+        >
+          Smooth
+        </button>
+        <button
+          :class="{ active: routing === 'step' }"
+          @click="routing = 'step'"
+        >
+          Step
+        </button>
+        <button
+          :class="{ active: routing === 'straight' }"
+          @click="routing = 'straight'"
+        >
+          Straight
+        </button>
+      </span>
+      <button
+        :disabled="!engine.plugins.history.canUndo()"
+        @click="engine.plugins.history.undo()"
+      >
+        Undo
+      </button>
+      <button
+        :disabled="!engine.plugins.history.canRedo()"
+        @click="engine.plugins.history.redo()"
+      >
+        Redo
+      </button>
+      <span class="demo-history-badge ml-auto"
+        >{{ historyState.undoDepth }} undo /
+        {{ historyState.redoDepth }} redo</span
+      >
+    </div>
+
+    <div class="relative">
+      <BoardRoot :engine="engine" style="height: 360px">
+        <BoardConnectionLayer :routing="routing" />
+      </BoardRoot>
+      <div
+        class="absolute right-4 bottom-4 rounded-md border border-default bg-elevated/90 p-2 shadow-lg backdrop-blur"
+      >
+        <BoardMinimap :engine="engine" :width="180" :height="110" />
+      </div>
+    </div>
+  </div>
+</template>
+````
+
+### app/utils/demoDocument.ts
+
+````ts
+import type {
+  BoardNode,
+  BoardNodeMetadata,
+  Camera,
+  GridSettings,
+  JsonCanvasDocument,
+  JsonCanvasNode,
+  NodeId,
+} from '@lupinum/board-core'
+
+type DemoNode = Omit<
+  Pick<
+    BoardNode,
+    | 'id'
+    | 'type'
+    | 'x'
+    | 'y'
+    | 'width'
+    | 'height'
+    | 'color'
+    | 'text'
+    | 'file'
+    | 'subpath'
+    | 'url'
+    | 'label'
+    | 'background'
+    | 'backgroundStyle'
+    | 'zIndex'
+    | 'locked'
+    | 'visible'
+    | 'parentId'
+  >,
+  'id' | 'parentId'
+> & {
+  id: NodeId | string
+  parentId?: NodeId | string
+}
+
+export interface DemoDocumentInput {
+  nodes: readonly DemoNode[]
+  camera?: Camera
+  grid?: GridSettings
+  selection?: readonly (NodeId | string)[]
+  nextZIndex?: number
+}
+
+function toJsonCanvasNode(node: DemoNode): JsonCanvasNode {
+  const base = {
+    id: node.id as NodeId,
+    type: node.type,
+    x: node.x,
+    y: node.y,
+    width: node.width,
+    height: node.height,
+    ...(node.color ? { color: node.color } : {}),
+  }
+
+  switch (node.type) {
+    case 'file':
+      return {
+        ...base,
+        type: 'file',
+        file: node.file ?? '',
+        ...(node.subpath ? { subpath: node.subpath } : {}),
+      }
+    case 'link':
+      return {
+        ...base,
+        type: 'link',
+        url: node.url ?? '',
+      }
+    case 'group':
+      return {
+        ...base,
+        type: 'group',
+        ...((node.label ?? node.text)
+          ? { label: node.label ?? node.text }
+          : {}),
+        ...(node.background ? { background: node.background } : {}),
+        ...(node.backgroundStyle
+          ? { backgroundStyle: node.backgroundStyle }
+          : {}),
+      }
+    case 'text':
+    default:
+      return {
+        ...base,
+        type: 'text',
+        text: node.text ?? '',
+      }
+  }
+}
+
+function toNodeMetadata(node: DemoNode): BoardNodeMetadata {
+  return {
+    zIndex: node.zIndex,
+    locked: node.locked,
+    visible: node.visible,
+    ...(node.parentId ? { parentId: node.parentId as NodeId } : {}),
+  }
+}
+
+export function createDemoDocument(
+  input: DemoDocumentInput,
+): JsonCanvasDocument {
+  return {
+    nodes: input.nodes.map(toJsonCanvasNode),
+    'x-lupinum-board': {
+      ...(input.camera ? { camera: input.camera } : {}),
+      ...(input.grid ? { grid: input.grid } : {}),
+      ...(input.selection
+        ? { selection: input.selection.map((id) => id as NodeId) }
+        : {}),
+      nextZIndex:
+        input.nextZIndex ??
+        input.nodes.reduce((max, node) => Math.max(max, node.zIndex), 0) + 1,
+      nodes: Object.fromEntries(
+        input.nodes.map((node) => [node.id, toNodeMetadata(node)]),
+      ),
+    },
+  }
+}
+````
+
+## Setup
+
+Install the package when your board needs edges:
+
+```bash
+pnpm add @lupinum/board-connections
+```
+
+Then install the connections plugin during engine creation and render the SVG
+layer under `BoardRoot`:
+
+```ts
+import { createBoardEngine } from '@lupinum/board-core'
+import { connectionsPlugin } from '@lupinum/board-connections'
+import { BoardConnectionLayer } from '@lupinum/board-connections/vue'
+
+const engine = createBoardEngine({
+  plugins: [connectionsPlugin({ routing: 'bezier' })],
+})
+```
+
+```vue
+<template>
+  <BoardRoot :engine="engine" style="height: 100vh">
+    <BoardConnectionLayer />
+  </BoardRoot>
+</template>
+```
+
+Both pieces are required: the plugin owns edge state, and
+`BoardConnectionLayer` renders and edits that state.
+
+---
+
+## Creating edges
+
+Create edges after the endpoint nodes exist:
+
+```ts
+const edge = engine.plugins.connections.createEdge({
+  from: sourceNodeId,
+  to: targetNodeId,
+  label: 'depends on',
+  data: {},
+})
+```
+
+For a complete minimal scene:
+
+```ts
+const source = engine.createNode({
+  type: 'text',
+  x: 80,
+  y: 100,
+  text: 'Source',
+})
+
+const target = engine.createNode({
+  type: 'text',
+  x: 420,
+  y: 100,
+  text: 'Target',
+})
+
+engine.plugins.connections.createEdge({
+  from: source.id,
+  to: target.id,
+  label: 'depends on',
+  data: {},
+})
+```
+
+### With anchors
+
+Specify where the edge attaches on each node:
+
+```ts
+engine.plugins.connections.createEdge({
+  from: nodeA,
+  to: nodeB,
+  fromAnchor: { side: 'right', offset: 0.5 }, // middle of right edge
+  toAnchor: { side: 'left', offset: 0.5 }, // middle of left edge
+  data: {},
+})
+```
+
+Anchor `offset` is 0–1 along the side (0.5 = center). If omitted, the connection layer auto-picks the best side from node geometry, keeps it stable while nodes move, and attaches at the center of that side.
+
+Use non-center offsets for precise manual anchors:
+
+```ts
+engine.plugins.connections.createEdge({
+  from: nodeA,
+  to: nodeB,
+  fromAnchor: { side: 'bottom', offset: 0.2 },
+  toAnchor: { side: 'top', offset: 0.8 },
+  data: {},
+})
+```
+
+---
+
+## Querying edges
+
+```ts
+// All edges
+const edges = engine.plugins.connections.getEdges()
+
+// Edges from a specific node
+const outgoing = engine.plugins.connections.getEdgesFrom(nodeId)
+
+// Edges to a specific node
+const incoming = engine.plugins.connections.getEdgesTo(nodeId)
+
+// Edges between two nodes
+const between = engine.plugins.connections.getEdgesBetween(nodeA, nodeB)
+
+// A specific edge
+const edge = engine.plugins.connections.getEdge(edgeId)
+```
+
+---
+
+## Updating edges
+
+Reconnect or restyle an existing edge with `updateEdge()`:
+
+```ts
+engine.plugins.connections.updateEdge(edgeId, {
+  to: otherNodeId,
+  toAnchor: undefined, // clear explicit anchor so the new node side auto-resolves
+})
+```
+
+The connection layer uses the same API internally when you drag an endpoint handle to another node.
+
+---
+
+## Deleting edges
+
+```ts
+engine.plugins.connections.deleteEdge(edgeId)
+```
+
+<note>
+Edges are also automatically deleted when either endpoint node is removed.
+</note>
+
+---
+
+## Rendering with BoardConnectionLayer
+
+Render `BoardConnectionLayer` anywhere under `BoardRoot`. It uses the board context, teleports its SVG layer to the root element, and applies the camera transform itself:
+
+```vue
+<script setup lang="ts">
+import { BoardRoot } from '@lupinum/vue-board'
+import { BoardConnectionLayer } from '@lupinum/board-connections/vue'
+</script>
+
+<template>
+  <BoardRoot :engine="engine" style="height: 100vh">
+    <BoardConnectionLayer />
+  </BoardRoot>
+</template>
+```
+
+Hover a card edge to reveal a filled connection handle, then drag from it to another card to create a new edge. Dropping a new connection on empty space cancels by default; pass `createNodeForConnection` if your app wants empty-drop creation to create a node and connect it. The callback runs synchronously inside the same board batch as edge creation. A rejected edge rolls back node changes made through that engine; it cannot roll back external effects from the callback. A callback that returns `null` keeps its existing cancellation behavior. Hover an edge or select it to reveal draggable endpoint handles for reconnecting existing edges; dropping a reconnect on empty space cancels it.
+
+UI-created edges use automatic endpoints by default. The edge stores no `fromAnchor` or `toAnchor`, so the connection layer keeps choosing the best side as nodes move. Dragging an existing endpoint onto a node side locks that endpoint to the exact side offset under the pointer. Select the edge and use the reset anchor actions to clear manual anchors back to auto. Set `endpointMode="manual"` on `BoardConnectionLayer`, or `connectionsPlugin({ endpointMode: 'manual' })`, when newly created edges should also lock to the side points the user chose.
+
+### Routing styles
+
+Toggle the demo above to compare routing styles. Set the routing on `BoardConnectionLayer`:
+
+```vue
+<BoardConnectionLayer routing="step" />
+```
+
+| Style | Purpose |
+| --- | --- |
+| `bezier` (default) | Smooth cubic bezier curve. Best for organic-looking graphs. |
+| `smooth-step` | Rounded orthogonal connector. Clean and readable. |
+| `step` | Right-angle stepped path. Good for pipeline and workflow layouts. |
+| `straight` | Direct straight line. Simple and lightweight. |
+| `arc` | Curved arc route for sketch-style or hand-drawn edge rendering. |
+
+### Custom edge rendering
+
+Use the `edge` slot for full control over edge appearance:
+
+```vue
+<BoardConnectionLayer>
+  <template #edge="{ edge, route }">
+    <path :d="route.path" stroke="#3b82f6" stroke-width="2" fill="none" />
+    <text :x="route.labelPoint.x" :y="route.labelPoint.y" text-anchor="middle">
+      {{ edge.label }}
+    </text>
+  </template>
+</BoardConnectionLayer>
+```
+
+---
+
+## Events
+
+```ts
+engine.on('edge:created', (edge) => {
+  console.log('Edge created:', edge.from, '→', edge.to)
+})
+
+engine.on('edge:updated', (edge, prev) => {
+  console.log('Edge moved from', prev.to, 'to', edge.to)
+})
+
+engine.on('edge:deleted', (edgeId) => {
+  console.log('Edge deleted:', edgeId)
+})
+```
+
+---