@lupinum/vue-board

Install

pnpm add @lupinum/vue-board @lupinum/board-core

npm install @lupinum/vue-board @lupinum/board-core

BoardRoot

The root component that renders the board. It subscribes to the engine, handles all pointer/keyboard events, and provides context to child components and composables.

Props

Treat the engine instance as stable after mount. To replace board contents, keep the same engine and load the new document through engine commands such as loadDocument.

Emits

Slots

default

The default slot renders after the board viewport, on top of the canvas. It receives the engine, runtime state, and debug state.

<BoardRoot :engine="engine">
  <template #default="{ engine, state, debugState }">
    <MyToolbar :engine="engine" />
    <MyMinimap />
  </template>
</BoardRoot>

viewport

Renders inside the viewport transform layer (world-space). Use this for custom overlays that should move with the canvas.

<BoardRoot :engine="engine">
  <template #viewport>
    <MyWorldOverlay />
  </template>
</BoardRoot>

node

Fallback slot for node content when no type-specific slot or renderer matches.

<BoardRoot :engine="engine">
  <template #node="{ node, selected, editing, beginEdit, commitText }">
    <div>{{ node.text }}</div>
  </template>
</BoardRoot>

node:{type}

Type-specific named slot. Takes precedence over the node slot and renderer registry.

<BoardRoot :engine="engine">
  <template #node:file="{ node, selected }">
    <img :src="node.file" :alt="node.label" />
  </template>
  <template #node:text="{ node }">
    <p>{{ node.text }}</p>
  </template>
</BoardRoot>

handle

Custom resize handle slot. Rendered for each of the 8 compass handles when a node is selected.

<BoardRoot :engine="engine">
  <template #handle="{ node, handle }">
    <div class="my-handle" :data-resize="handle">●</div>
  </template>
</BoardRoot>

box-select

Custom box selection overlay.

<BoardRoot :engine="engine">
  <template #box-select="{ bounds }">
    <div class="my-box-select" :style="boxStyle(bounds)" />
  </template>
</BoardRoot>

CSS custom properties

Set these on .board-root to theme the entire board:

/* Dark theme example */
.board-root {
  --board-bg: #1e293b;
  --board-fg: #f1f5f9;
  --board-node-bg: #334155;
  --board-node-border: rgba(241, 245, 249, 0.15);
  --board-accent: #22d3ee;
}

Level of detail (LOD)

BoardRoot automatically adjusts rendering based on screen-space size:

Keyboard shortcuts

BoardRoot handles these keyboard shortcuts out of the box:

BoardSelectionToolbar

Floating toolbar rendered by BoardRoot for selected nodes. It is also exported for custom board shells.

The toolbar appears above the selected node bounds when the board is idle. It hides during node drag, resize, and text editing.

Built-in actions:

Palette options apply BoardColorPreset IDs, which are one supported form of BoardNode.color.

Node color helpers

@lupinum/vue-board exports the shared color helpers for custom renderers.

import {
  BOARD_COLOR_PRESETS,
  colorForPreset,
  resolveNodeColorStyle,
} from '@lupinum/vue-board'

Use resolveNodeColorStyle(node.color) when custom wrappers need the same CSS variables as the built-in renderer.

<template>
  <article class="task-card" :style="resolveNodeColorStyle(node.color)">
    {{ node.text }}
  </article>
</template>

resolveNodeColorStyle() returns an empty style object when the node has no color.

BoardViewport

Applies the camera transform (scale + translate) to child content. All children render in world-space coordinates. Used internally by BoardRoot.

CSS

.board-viewport {
  position: absolute;
  inset: 0;
  transform-origin: 0 0;
  will-change: transform;
}

BoardNode

Renders a single node with selection state, editing support, resize handles, and slot-based content.

Props

Slots

default

Custom node content. When provided, replaces the built-in text display.

handle

Custom resize handle. Rendered for each of the 8 compass directions when the node is selected and not editing or locked.

CSS classes

Built-in text editing

When no custom renderer is provided and the node type is 'text', BoardNode renders:

• A <textarea> when editing is true (auto-focused, auto-selected)
• A <div> with the content text when not editing

The textarea commits on blur, Cmd/Ctrl + Enter, and cancels on Escape.

BoardNodeHandle

Renders a single resize handle square at the appropriate position on a node.

Props

The default handle uses an 18px hit target and a 7px visible dot, both scaled by 1 / zoom. It uses data-resize attributes for pointer event detection.

BoardGrid

Renders the grid pattern as CSS background gradients. Supports dot, line, cross, and none patterns. Automatically adjusts opacity based on zoom level.

The grid fades at edges when fadeEdges is enabled (via CSS mask-image).

BoardBoxSelect

Renders the box selection rectangle during a box-select interaction. The default overlay uses a solid blue window style for contain-mode selection and a dashed teal crossing style for intersecting selection.

Slots

default

Custom box selection rendering.

BoardSnapGuides

Renders alignment snap guides during drag and resize operations. Converts world-space guide data to screen-space lines using the current camera transform.

• Vertical guides (x-axis) render as 1px wide lines in --board-snap-guide-color, falling back to --board-accent.
• Horizontal guides (y-axis) render as 1px tall lines in --board-snap-guide-color, falling back to --board-accent.

Types

BoardGridOptions

Presentation-only grid options passed to the grid prop on BoardRoot. Configure size, snapping, thresholds, and pattern through createBoardEngine({ grid }) or engine.updateGridSettings() so rendering and interaction use one canonical value.

interface BoardGridOptions {
  visible?: boolean // show/hide the grid (default: true)
  minorOpacity?: number // minor grid line opacity (default: 0.14)
  majorOpacity?: number // major grid line opacity (default: 0.18)
  fadeEdges?: boolean // fade grid at viewport edges (default: true)
}

BoardRendererRegistry

Maps supported JSON Canvas node types to Vue components.

type BoardRendererRegistry = Partial<Record<JsonCanvasNodeType, Component>>

import TextCard from './TextCard.vue'
import GroupCard from './GroupCard.vue'

const renderers: BoardRendererRegistry = {
  text: TextCard,
  group: GroupCard,
}