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

package/dist/agent/pages/docs/build-features/save-and-load.md

@@ -15,8 +15,270 @@ source: "ginko-content"
 
 Save and load boards as JSON Canvas documents. Runtime snapshots are for rendering and tests; persisted documents go through `engine.exportDocument()` and `engine.loadDocument()`.
 
-> Component omitted: `json-import-export-demo`.
-> This page contains an interactive or site-specific block that has no agent markdown serializer yet.
+## 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/JsonImportExportDemo.vue
+
+````vue
+<script setup lang="ts">
+import { onMounted, ref } from 'vue'
+import { asNodeId, createBoardEngine } from '@lupinum/board-core'
+import { createDemoDocument } from '../../utils/demoDocument'
+import { connectionsPlugin } from '@lupinum/board-connections'
+import { BoardConnectionLayer } from '@lupinum/board-connections/vue'
+
+const engine = createBoardEngine({
+  grid: { size: 18, majorEvery: 6, snap: true, pattern: 'line' },
+  plugins: [connectionsPlugin()],
+})
+
+const payload = ref('')
+const formatMode = ref<'pretty' | 'compact'>('pretty')
+const SOURCE_ID = asNodeId('source')
+const TARGET_ID = asNodeId('target')
+
+function exportDocument() {
+  const raw = engine.exportDocument()
+  if (formatMode.value === 'compact') {
+    return JSON.stringify(raw)
+  }
+  return JSON.stringify(raw, null, 2)
+}
+
+function seed() {
+  engine.loadDocument(
+    createDemoDocument({
+      camera: { x: 0, y: 0, z: 1 },
+      grid: engine.getGridSettings(),
+      selection: [],
+      nextZIndex: 3,
+      nodes: [
+        {
+          id: SOURCE_ID,
+          type: 'text',
+          x: 80,
+          y: 110,
+          width: 220,
+          height: 100,
+          text: 'Export me\nto JSON Canvas',
+          zIndex: 1,
+          locked: false,
+          visible: true,
+        },
+        {
+          id: TARGET_ID,
+          type: 'text',
+          x: 420,
+          y: 110,
+          width: 220,
+          height: 100,
+          text: 'Edit the JSON\nthen import back',
+          zIndex: 2,
+          locked: false,
+          visible: true,
+        },
+      ],
+    }),
+    { mode: 'replace' },
+  )
+  for (const edge of engine.plugins.connections.getEdges()) {
+    engine.plugins.connections.deleteEdge(edge.id)
+  }
+  engine.plugins.connections.createEdge({
+    from: SOURCE_ID,
+    to: TARGET_ID,
+    label: 'json-canvas',
+    data: {},
+  })
+  payload.value = exportDocument()
+}
+
+function exportBoard() {
+  payload.value = exportDocument()
+}
+
+function setFormatMode(nextMode: 'pretty' | 'compact') {
+  formatMode.value = nextMode
+  exportBoard()
+}
+
+function importBoard() {
+  if (!payload.value.trim()) return
+  engine.loadDocument(JSON.parse(payload.value), { mode: 'replace' })
+}
+
+onMounted(async () => {
+  seed()
+  await engine.zoomToFit(72, false)
+})
+</script>
+
+<template>
+  <div class="demo-frame">
+    <div class="demo-toolbar">
+      <button class="demo-danger" @click="seed">Reset</button>
+      <button class="demo-primary" @click="exportBoard">
+        Export JSON Canvas
+      </button>
+      <button @click="importBoard">Import payload</button>
+      <span class="demo-toggle-group">
+        <button
+          :class="{ active: formatMode === 'pretty' }"
+          @click="setFormatMode('pretty')"
+        >
+          Pretty
+        </button>
+        <button
+          :class="{ active: formatMode === 'compact' }"
+          @click="setFormatMode('compact')"
+        >
+          Compact
+        </button>
+      </span>
+    </div>
+
+    <div class="grid gap-0 md:grid-cols-[minmax(0,1.2fr)_minmax(0,0.8fr)]">
+      <BoardRoot :engine="engine" style="height: 360px">
+        <BoardConnectionLayer />
+      </BoardRoot>
+      <textarea
+        v-model="payload"
+        class="min-h-[360px] resize-none border-0 border-l border-default bg-inverted p-4 font-mono text-xs leading-6 text-primary outline-none"
+        spellcheck="false"
+      />
+    </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)]),
+      ),
+    },
+  }
+}
+````
 
 ## What to persist
 

package/dist/agent/pages/docs/build-features/selection-and-keyboard.md

@@ -15,8 +15,263 @@ source: "ginko-content"
 
 Selection and interaction are how users communicate with the board. Select nodes to act on them, drag to move, resize from handles, and box-select on empty canvas.
 
-> Component omitted: `interaction-state-viz`.
-> This page contains an interactive or site-specific block that has no agent markdown serializer yet.
+## 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/InteractionStateViz.vue
+
+````vue
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref } from 'vue'
+import { createBoardEngine } from '@lupinum/board-core'
+import { createDemoDocument } from '../../utils/demoDocument'
+
+const engine = createBoardEngine({
+  grid: { size: 20, majorEvery: 5, snap: true, pattern: 'cross' },
+})
+
+const mode = ref(engine.$interaction.get().mode)
+const selection = ref(engine.getSelection())
+let unsubscribeInteraction: (() => void) | null = null
+let unsubscribeSelection: (() => void) | null = null
+
+const statusTone = computed(() => {
+  if (mode.value === 'idle') return 'bg-accented text-default'
+  if (mode.value.includes('drag') || mode.value.includes('resize'))
+    return 'bg-sky-50 text-sky-700'
+  if (mode.value.includes('pan')) return 'bg-amber-50 text-amber-700'
+  return 'bg-emerald-50 text-emerald-700'
+})
+
+function seed() {
+  engine.loadDocument(
+    createDemoDocument({
+      camera: { x: 0, y: 0, z: 1 },
+      grid: engine.getGridSettings(),
+      nodes: [
+        {
+          id: 'state-a',
+          type: 'text',
+          x: 70,
+          y: 80,
+          width: 220,
+          height: 100,
+          text: 'Node',
+          zIndex: 1,
+          locked: false,
+          visible: true,
+        },
+        {
+          id: 'state-b',
+          type: 'text',
+          x: 360,
+          y: 180,
+          width: 220,
+          height: 100,
+          text: 'Node',
+          zIndex: 2,
+          locked: false,
+          visible: true,
+        },
+      ],
+      selection: [],
+      nextZIndex: 3,
+    }),
+    { mode: 'replace' },
+  )
+}
+
+async function reset() {
+  seed()
+  selection.value = []
+  await engine.zoomToFit(60, false)
+}
+
+onMounted(() => {
+  unsubscribeInteraction = engine.$interaction.subscribe((interaction) => {
+    mode.value = interaction.mode
+  })
+  unsubscribeSelection = engine.on('selection:change', (next) => {
+    selection.value = next
+  })
+  void reset()
+})
+
+onBeforeUnmount(() => {
+  unsubscribeInteraction?.()
+  unsubscribeSelection?.()
+})
+</script>
+
+<template>
+  <div class="demo-frame">
+    <div class="demo-toolbar">
+      <button class="demo-danger" @click="reset">Reset</button>
+      <span class="demo-toolbar-note"
+        >Interact with the board and watch the mode change in the sidebar.</span
+      >
+    </div>
+
+    <div class="grid gap-0 lg:grid-cols-[minmax(0,1fr)_280px]">
+      <BoardRoot :engine="engine" style="height: 360px" />
+
+      <div
+        class="border-t border-default bg-elevated p-4 lg:border-t-0 lg:border-l"
+      >
+        <p class="text-sm font-semibold text-highlighted">
+          Current interaction
+        </p>
+        <div
+          class="mt-4 inline-flex rounded-full px-3 py-2 text-sm font-semibold"
+          :class="statusTone"
+        >
+          {{ mode }}
+        </div>
+        <div class="mt-5 rounded-md border border-default bg-default p-4">
+          <p
+            class="text-xs font-semibold uppercase tracking-[0.28em] text-dimmed"
+          >
+            Selection
+          </p>
+          <p class="mt-2 text-sm text-default">
+            {{
+              selection.length ? selection.join(', ') : 'Nothing selected yet.'
+            }}
+          </p>
+        </div>
+      </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)]),
+      ),
+    },
+  }
+}
+````
 
 ## Selecting nodes