@lupinum/board-core 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/agent/pages/docs/reference/connections.md

@@ -0,0 +1,531 @@
+---
+title: "@lupinum/board-connections"
+description: "Edge and connection management plugin with routing, anchors, and an SVG connection layer."
+url: "https://nuxt-board.lupinum.com/docs/reference/connections"
+route: "/docs/reference/connections"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# @lupinum/board-connections
+
+> Edge and connection management plugin with routing, anchors, and an SVG connection layer.
+
+## Install
+
+<code-group>
+```bash [pnpm]
+pnpm add @lupinum/board-connections @lupinum/board-core @lupinum/vue-board
+```
+
+```bash [npm]
+npm install @lupinum/board-connections @lupinum/board-core @lupinum/vue-board
+```
+</code-group>
+
+## connectionsPlugin
+
+Creates the connections plugin. Install it during engine creation via `createBoardEngine({ plugins })`.
+
+```ts
+const plugin = connectionsPlugin({ routing: 'bezier' })
+```
+
+### Options
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `routing` | `ConnectionRouting` | `'bezier'` | Default edge routing style. |
+| `endpointMode` | `'auto' \| 'manual'` | `'auto'` | Whether UI-created endpoints adapt or lock to side anchors. |
+| `defaultArrow` | `'none' \| 'start' \| 'end' \| 'both'` | `'end'` | Default arrowhead placement. |
+
+```ts
+import { createBoardEngine } from '@lupinum/board-core'
+import { connectionsPlugin } from '@lupinum/board-connections'
+
+const engine = createBoardEngine({
+  plugins: [connectionsPlugin({ routing: 'bezier' })],
+})
+```
+
+---
+
+## Plugin API
+
+After installing the plugin, the connections API is available on `engine.plugins.connections`.
+
+### createEdge
+
+Creates a new edge between two nodes. Returns the created edge.
+
+```ts
+createEdge<T>(input: {
+  id?: EdgeId
+  from: NodeId
+  to: NodeId
+  fromAnchor?: AnchorPosition
+  toAnchor?: AnchorPosition
+  fromEnd?: EdgeEnd
+  toEnd?: EdgeEnd
+  label?: string
+  color?: string
+  data: T
+  zIndex?: number
+}): BoardEdge<T>
+```
+
+```ts
+const edge = engine.plugins.connections.createEdge({
+  from: nodeA,
+  to: nodeB,
+  label: 'depends on',
+  color: '#0f766e',
+  data: {},
+})
+```
+
+### deleteEdge
+
+Removes an edge by ID.
+
+```ts
+deleteEdge(id: EdgeId): void
+```
+
+### updateEdge
+
+Updates an existing edge in place. This is the API used by endpoint reconnect interactions.
+
+```ts
+updateEdge<T>(id: EdgeId, patch: BoardEdgePatch<T>): BoardEdge<T>
+```
+
+```ts
+engine.plugins.connections.updateEdge(edge.id, {
+  to: anotherNodeId,
+  toAnchor: undefined,
+})
+```
+
+### getEdge
+
+Returns a single edge by ID.
+
+```ts
+getEdge(id: EdgeId): BoardEdge | undefined
+```
+
+### getEdges
+
+Returns all edges.
+
+```ts
+getEdges(): BoardEdge[]
+```
+
+### getEdgesFrom
+
+Returns all edges originating from a node.
+
+```ts
+getEdgesFrom(id: NodeId): BoardEdge[]
+```
+
+### getEdgesTo
+
+Returns all edges pointing to a node.
+
+```ts
+getEdgesTo(id: NodeId): BoardEdge[]
+```
+
+### getEdgesBetween
+
+Returns all directed edges from `from` to `to`.
+
+```ts
+getEdgesBetween(from: NodeId, to: NodeId): BoardEdge[]
+```
+
+---
+
+## BoardConnectionLayer
+
+A Vue component that renders edges as SVG paths inside a `BoardRoot`.
+
+```ts
+import { BoardConnectionLayer } from '@lupinum/board-connections/vue'
+```
+
+### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `routing` | `ConnectionRouting \| undefined` | plugin default | Routing style for all edges. |
+| `endpointMode` | `ConnectionEndpointMode \| undefined` | plugin default | UI endpoint behavior: auto side resolution or manual side locking. |
+| `createNodeForConnection` | `(ctx: CreateNodeForConnectionContext) => BoardNode \| null` | `null` | Optional host policy for creating a node when a new connection is dropped on empty space. |
+
+### Slots
+
+#### edge
+
+Custom edge rendering. If not provided, edges render as SVG `<path>` elements.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `edge` | `BoardEdge` | The edge data. |
+| `source` | `ResolvedConnectionEndpoint` | Resolved source endpoint metadata. |
+| `target` | `ResolvedConnectionEndpoint` | Resolved target endpoint metadata. |
+| `route` | `ConnectionRoute` | Routed geometry, bounds, label point, and path string. |
+
+```vue
+<BoardConnectionLayer routing="smooth-step">
+  <template #edge="{ edge, route }">
+    <path :d="route.path" stroke="blue" stroke-width="2" fill="none" />
+    <text :x="route.labelPoint.x" :y="route.labelPoint.y">{{ edge.label }}</text>
+  </template>
+</BoardConnectionLayer>
+```
+
+### Usage
+
+Render `BoardConnectionLayer` under `BoardRoot`. It teleports the SVG layer to the board root and applies the camera transform itself:
+
+```vue
+<BoardRoot :engine="engine">
+  <BoardConnectionLayer />
+</BoardRoot>
+```
+
+`BoardConnectionLayer` handles both connection creation and reconnect. Hover a card edge to reveal a filled midpoint handle and drag it to another card to create a new edge. Hover or select an existing edge to reveal reconnect handles; dragging either end previews the route live and commits via `updateEdge()` when dropped on another node. Dropping a new connection on empty space cancels unless `createNodeForConnection` returns a node for the layer to connect.
+
+By default, UI-created edges use `endpointMode: 'auto'`: they do not store `fromAnchor` or `toAnchor`, so each endpoint resolves to the best node side as nodes move. Dragging an existing endpoint onto a node side stores that endpoint as `{ side, offset }`, where `offset` is the exact point under the pointer. Use `endpointMode: 'manual'` when newly created edges should also lock to the dragged side offsets. Selected manual edges expose reset actions that clear one or both anchors back to auto.
+
+---
+
+## Utility functions
+
+### resolveAnchorPoint
+
+Resolves an anchor position to a world-space point on a node.
+
+```ts
+function resolveAnchorPoint(
+  node: Pick<BoardNode, 'x' | 'y' | 'width' | 'height'>,
+  anchor: AnchorPosition,
+): Point
+```
+
+### resolveAutoAnchorSide
+
+Chooses the best side for an auto-routed endpoint and uses a deadband to reduce flicker near diagonals. Auto-routed endpoints then attach at the center of that side.
+
+```ts
+function resolveAutoAnchorSide(
+  source: Pick<BoardNode, 'x' | 'y' | 'width' | 'height'>,
+  target: Pick<BoardNode, 'x' | 'y' | 'width' | 'height'>,
+  role: 'source' | 'target',
+  previousSide?: AnchorSide,
+): AnchorSide
+```
+
+### resolveConnectionEndpoint
+
+Resolves one edge endpoint to a node side, normalized side offset, and world-space point. Explicit anchors are preserved; automatic endpoints choose the best side from the paired node.
+
+```ts
+function resolveConnectionEndpoint(
+  edge: BoardEdge,
+  node: Pick<BoardNode, 'id' | 'x' | 'y' | 'width' | 'height'>,
+  otherNode: Pick<BoardNode, 'id' | 'x' | 'y' | 'width' | 'height'>,
+  role: 'source' | 'target',
+  previousSide?: AnchorSide,
+): ResolvedConnectionEndpoint
+```
+
+### buildConnectionRoute
+
+Builds a routed connection path from fully resolved source and target endpoints.
+
+```ts
+function buildConnectionRoute(input: {
+  source: ResolvedConnectionEndpoint
+  target: ResolvedConnectionEndpoint
+  routing?: ConnectionRouting
+}): ConnectionRoute
+```
+
+| Routing | Description |
+| --- | --- |
+| `'bezier'` | Smooth cubic bezier curve (default). |
+| `'smooth-step'` | Rounded orthogonal connector. |
+| `'step'` | Right-angle stepped path. |
+| `'straight'` | Direct straight line. |
+| `'arc'` | Curved arc route. |
+
+### buildArcRoute
+
+Builds a curved arc route for hand-drawn or sketch-style edge rendering.
+
+```ts
+function buildArcRoute(
+  source: ResolvedConnectionEndpoint,
+  target: ResolvedConnectionEndpoint,
+  options?: ArcOptions,
+): ConnectionRoute
+```
+
+### Edge color helpers
+
+The package exports preset helpers for edge UI:
+
+```ts
+import {
+  EDGE_COLOR_PRESETS,
+  colorForPreset,
+  presetForColor,
+  resolvePresetColor,
+} from '@lupinum/board-connections'
+```
+
+Use these helpers when a toolbar stores edge colors as presets but the renderer needs a CSS color string.
+
+### resolveFloatingEndpoint
+
+Builds a temporary endpoint around a free pointer position for reconnect previews.
+
+```ts
+function resolveFloatingEndpoint(
+  point: Point,
+  otherPoint: Point,
+  role: 'source' | 'target',
+  previousSide?: AnchorSide,
+): ResolvedConnectionEndpoint
+```
+
+### resolveEdgeRenderState
+
+Resolves source/target endpoints and the routed path in one step.
+
+```ts
+function resolveEdgeRenderState(
+  edge: BoardEdge,
+  sourceNode: Pick<BoardNode, 'id' | 'x' | 'y' | 'width' | 'height'>,
+  targetNode: Pick<BoardNode, 'id' | 'x' | 'y' | 'width' | 'height'>,
+  options?: {
+    routing?: ConnectionRouting
+    previousSourceSide?: AnchorSide
+    previousTargetSide?: AnchorSide
+  },
+): {
+  source: ResolvedConnectionEndpoint
+  target: ResolvedConnectionEndpoint
+  route: ConnectionRoute
+}
+```
+
+### getVisibleEdges
+
+Returns edges whose routed path bounds intersect the given viewport bounds.
+
+```ts
+function getVisibleEdges(
+  engine: BoardEngine,
+  bounds: Bounds,
+  routing?: ConnectionRouting,
+): BoardEdge[]
+```
+
+---
+
+## Types
+
+### BoardEdge
+
+```ts
+interface BoardEdge<T = Record<string, unknown>> {
+  id: EdgeId
+  from: NodeId
+  to: NodeId
+  fromAnchor?: AnchorPosition // where the edge attaches on the source node
+  toAnchor?: AnchorPosition // where the edge attaches on the target node
+  fromEnd?: EdgeEnd
+  toEnd?: EdgeEnd
+  label?: string
+  color?: string
+  data: T // custom edge payload
+  zIndex: number
+}
+```
+
+### BoardEdgePatch
+
+```ts
+interface BoardEdgePatch<T = Record<string, unknown>> {
+  from?: NodeId
+  to?: NodeId
+  fromAnchor?: AnchorPosition
+  toAnchor?: AnchorPosition
+  fromEnd?: EdgeEnd
+  toEnd?: EdgeEnd
+  label?: string
+  color?: string
+  data?: T
+}
+```
+
+### AnchorPosition
+
+```ts
+interface AnchorPosition {
+  side: AnchorSide // 'top' | 'right' | 'bottom' | 'left'
+  offset: number // 0–1 position along the side (0.5 = center)
+}
+```
+
+When `fromAnchor` / `toAnchor` are omitted, the connection layer resolves the side automatically and uses `offset = 0.5`.
+
+Set an anchor to `undefined` with `updateEdge()` to reset that endpoint to automatic side resolution:
+
+```ts
+engine.plugins.connections.updateEdge(edgeId, {
+  fromAnchor: undefined,
+})
+```
+
+### AnchorSide
+
+```ts
+type AnchorSide = 'top' | 'right' | 'bottom' | 'left'
+```
+
+### ConnectionRouting
+
+```ts
+type ConnectionRouting = 'bezier' | 'smooth-step' | 'step' | 'straight' | 'arc'
+```
+
+### ConnectionEndpointMode
+
+```ts
+type ConnectionEndpointMode = 'auto' | 'manual'
+```
+
+### EdgeEnd
+
+```ts
+type EdgeEnd = 'none' | 'arrow'
+```
+
+### ConnectionConfig
+
+Resolved defaults installed by `connectionsPlugin()` and returned by `engine.plugins.connections.getConfig()`.
+
+```ts
+interface ConnectionConfig {
+  routing: ConnectionRouting
+  endpointMode: ConnectionEndpointMode
+  defaultArrow: 'none' | 'start' | 'end' | 'both'
+}
+```
+
+### CreateNodeForConnectionContext
+
+Context passed to `BoardConnectionLayer` when a host opts into creating a node from an empty connection drop.
+
+```ts
+interface CreateNodeForConnectionContext {
+  sourceNodeId: NodeId
+  sourceSide: AnchorSide
+  pointerWorld: Point
+  candidateAnchor: AnchorPosition | null
+}
+```
+
+### ResolvedConnectionEndpoint
+
+```ts
+interface ResolvedConnectionEndpoint {
+  nodeId: NodeId
+  node: Pick<BoardNode, 'id' | 'x' | 'y' | 'width' | 'height'>
+  side: AnchorSide
+  offset: number
+  point: Point
+  kind: 'explicit' | 'auto'
+}
+```
+
+### ConnectionRoute
+
+```ts
+interface ConnectionRoute {
+  routing: ConnectionRouting
+  path: string
+  labelPoint: Point
+  bounds: Bounds
+  waypoints: Point[]
+  segments: ConnectionRouteSegment[]
+}
+```
+
+### ConnectionRouteSegment
+
+A routed connection is made of path segments used by custom edge renderers.
+
+```ts
+type ConnectionRouteSegment =
+  | { type: 'line'; from: Point; to: Point }
+  | {
+      type: 'cubic'
+      from: Point
+      control1: Point
+      control2: Point
+      to: Point
+    }
+```
+
+### ConnectionsApi
+
+Installed by `connectionsPlugin()` on `engine.plugins.connections`.
+
+```ts
+interface ConnectionsApi {
+  createEdge<T>(input: CreateEdgeInput<T>): BoardEdge<T>
+  updateEdge<T>(id: EdgeId, patch: BoardEdgePatch<T>): BoardEdge<T>
+  deleteEdge(id: EdgeId): void
+  getEdge(id: EdgeId): BoardEdge | undefined
+  getEdges(): BoardEdge[]
+  getEdgesFrom(id: NodeId): BoardEdge[]
+  getEdgesTo(id: NodeId): BoardEdge[]
+  getEdgesBetween(from: NodeId, to: NodeId): BoardEdge[]
+  getConfig(): ConnectionConfig
+}
+```
+
+---
+
+## Events
+
+The connections plugin adds these events to `BoardEventMap`:
+
+| Event | Handler | Description |
+| --- | --- | --- |
+| `edge:created` | `(edge: BoardEdge) => void` | An edge was created. |
+| `edge:updated` | `(edge: BoardEdge, prev: BoardEdge) => void` | An edge was updated or reconnected. |
+| `edge:deleted` | `(edgeId: EdgeId) => void` | An edge was removed. |
+
+```ts
+engine.on('edge:created', (edge) => {
+  console.log('New edge:', edge.from, '->', edge.to)
+})
+
+engine.on('edge:updated', (edge, prev) => {
+  console.log('Moved edge:', prev.id, prev.to, '->', edge.to)
+})
+```
+
+Edges are automatically deleted when either endpoint node is deleted.
+
+---

package/dist/agent/pages/docs/reference/events-and-errors.md

@@ -0,0 +1,158 @@
+---
+title: "Events and subscriptions"
+description: "React to state changes with the event system and subscribables."
+url: "https://nuxt-board.lupinum.com/docs/reference/events-and-errors"
+route: "/docs/reference/events-and-errors"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Events and subscriptions
+
+> React to state changes with the event system and subscribables.
+
+Events tell you what happened. Subscribables tell you what state looks like now. Use events to react to discrete actions, use subscribables to keep your UI in sync.
+
+> Component omitted: `event-logger`.
+> This page contains an interactive or site-specific block that has no agent markdown serializer yet.
+
+## Events
+
+Register a listener with `engine.on()`. It returns an unsubscribe function:
+
+```ts
+const unsub = engine.on('node:created', (node) => {
+  console.log('Created', node.id)
+})
+
+// Later...
+unsub()
+```
+
+### Event catalog
+
+<accordion>
+<accordion-item title="Lifecycle">
+- `destroy` — engine destroyed
+</accordion-item>
+
+<accordion-item title="Node events">
+- `node:created(node)` — a node was added
+- `node:updated(node, previousNode)` — a node's data or geometry changed
+- `node:deleted(nodeId, previousNode)` — a node was removed
+- `node:moved(node, delta)` — a node's position changed
+- `node:resized(node, previousBounds)` — a node's dimensions changed
+</accordion-item>
+
+<accordion-item title="Selection and interaction">
+- `selection:change(selectedIds, previousIds)` — selection changed
+- `interaction:start(state)` — an interaction began (drag, resize, pan, etc.)
+- `interaction:update(state)` — ongoing interaction position updated (high-frequency)
+- `interaction:end(state)` — interaction finished
+</accordion-item>
+
+<accordion-item title="Camera">
+- `camera:change(camera, previousCamera)` — camera position or zoom changed (high-frequency during pan/zoom)
+- `viewport:change(size, previousSize)` — the measured board root size changed
+</accordion-item>
+
+<accordion-item title="Guarded commands">
+- `command:before(commandName, args, metadata)` — a validated command has succeeded and is publishing its lifecycle boundary
+- `command:after(commandName, args, duration, metadata)` — a command finished executing
+- `command:blocked(commandName, args, metadata)` — a command was blocked by a guard
+- `validation:failed(failure)` — commit validation rejected an invalid candidate state
+</accordion-item>
+
+<accordion-item title="Feature events">
+Internal features add their own namespaced events:
+
+- **Connections:** `edge:created(edge)`, `edge:updated(edge, prev)`, `edge:deleted(edgeId)`
+- **History:** `history:push(entry)`, `history:undo(entry | null)`, `history:redo(entry | null)`, `history:clear()`
+</accordion-item>
+</accordion>
+
+## Subscribables
+
+Six subscribables give you reactive access to engine state. Each fires independently — a camera change does not trigger a `$nodes` notification:
+
+<tabs>
+<tab label="$nodes" icon="i-lucide-square">
+```ts
+engine.$nodes.subscribe((nodes) => {
+  console.log('Node count:', nodes.size)
+})
+```
+
+Fires when any node is created, updated, moved, resized, or deleted.
+</tab>
+
+<tab label="$camera" icon="i-lucide-move">
+```ts
+engine.$camera.subscribe((camera) => {
+  console.log(`Zoom: ${camera.z.toFixed(2)}`)
+})
+```
+
+Fires on every pan and zoom change. High-frequency during interaction.
+</tab>
+
+<tab label="$selection" icon="i-lucide-check-square">
+```ts
+engine.$selection.subscribe((ids) => {
+  console.log('Selected:', ids.size)
+})
+```
+
+Fires when the selection set changes.
+</tab>
+
+<tab label="$grid" icon="i-lucide-grid-3x3">
+```ts
+engine.$grid.subscribe((grid) => {
+  console.log('Grid size:', grid.size)
+})
+```
+
+Fires when snapping or grid settings change.
+</tab>
+
+<tab label="$interaction" icon="i-lucide-hand">
+```ts
+engine.$interaction.subscribe((state) => {
+  console.log('Mode:', state.mode)
+})
+```
+
+Fires when the interaction state machine transitions.
+</tab>
+
+<tab label="$snapGuides" icon="i-lucide-ruler">
+```ts
+engine.$snapGuides.subscribe((guides) => {
+  console.log('Active guides:', guides.length)
+})
+```
+
+Fires when snap alignment guides appear or disappear.
+</tab>
+</tabs>
+
+<tip>
+In Vue, prefer the composables (`useBoardCamera()`, `useBoardNodes()`, `useBoardSelection()`) over raw subscribables. They handle reactivity automatically.
+</tip>
+
+<note>
+Inside `engine.batch()`, entity events and subscribable notifications publish only after the outer batch commits. Command lifecycle events describe the outer `batch` boundary. A blocked command and a validation failure remain observable failure telemetry.
+</note>
+
+## Error taxonomy
+
+- `BoardInputError`: malformed or invalid boundary input.
+- `BoardNotFoundError`: requested entity does not exist.
+- `BoardConflictError`: an ID, plugin name, or other unique identity conflicts.
+- `CommandBlockedError`: a command guard rejected the operation.
+- `BoardDestroyedError`: a command targeted a destroyed engine.
+
+Listener, subscriber, and finalized commit-effect errors are reported through `onUnhandledError` after commit. They do not reverse committed state.