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

package/dist/agent/pages/docs/build-features/custom-node-renderers.md

@@ -15,8 +15,372 @@ source: "ginko-content"
 
 Custom renderers make nodes look like your product, not the default text box. The board shell still handles positioning, selection, resize handles, and z-ordering — your renderer only draws content.
 
-> Component omitted: `renderer-board-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/RendererBoardDemo.vue
+
+````vue
+<script setup lang="ts">
+import { onMounted } from 'vue'
+import { createBoardEngine } from '@lupinum/board-core'
+import type { BoardRendererRegistry } from '@lupinum/vue-board'
+import { createDemoDocument } from '../../utils/demoDocument'
+import DocsInsightNode from './DocsInsightNode.vue'
+import DocsMetricNode from './DocsMetricNode.vue'
+
+const engine = createBoardEngine({
+  grid: { size: 24, majorEvery: 4, snap: true, pattern: 'cross' },
+})
+
+const renderers: BoardRendererRegistry = {
+  text: DocsInsightNode,
+  group: DocsMetricNode,
+}
+let insightCount = 0
+let metricCount = 0
+
+function seed() {
+  engine.loadDocument(
+    createDemoDocument({
+      camera: { x: 0, y: 0, z: 1 },
+      grid: engine.getGridSettings(),
+      selection: [],
+      nextZIndex: 4,
+      nodes: [
+        {
+          id: 'why',
+          type: 'text',
+          x: 80,
+          y: 80,
+          width: 250,
+          height: 160,
+          text: 'Why custom renderers\nSwap the default card view for a Vue component while keeping JSON Canvas node data explicit.',
+          zIndex: 1,
+          locked: false,
+          visible: true,
+        },
+        {
+          id: 'metric',
+          type: 'group',
+          x: 390,
+          y: 90,
+          width: 230,
+          height: 160,
+          label:
+            'Adoption\n83%\n+12%\nThe renderer can look nothing like the default text card.',
+          zIndex: 2,
+          locked: false,
+          visible: true,
+        },
+        {
+          id: 'flow',
+          type: 'text',
+          x: 660,
+          y: 130,
+          width: 230,
+          height: 100,
+          text: 'Default JSON Canvas\nRenderers are keyed by real node type.',
+          zIndex: 3,
+          locked: false,
+          visible: true,
+        },
+      ],
+    }),
+    { mode: 'replace' },
+  )
+}
+
+function addInsight() {
+  insightCount++
+  engine.createNode({
+    type: 'text',
+    x: 160 + (insightCount % 3) * 120,
+    y: 80 + (insightCount % 2) * 130,
+    width: 250,
+    height: 160,
+    text: 'New insight\nUse a text node with a renderer registered for the JSON Canvas text type.',
+  })
+}
+
+function addMetric() {
+  metricCount++
+  engine.createNode({
+    type: 'group',
+    x: 180 + (metricCount % 3) * 140,
+    y: 90 + (metricCount % 2) * 120,
+    width: 230,
+    height: 160,
+    label:
+      'Confidence\n91%\n+4%\nDifferent JSON Canvas node types can have their own layout.',
+  })
+}
+
+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="addInsight">Add insight</button>
+      <button @click="addMetric">Add metric</button>
+      <button @click="engine.zoomToFit(72, false)">Zoom to fit</button>
+    </div>
+
+    <BoardRoot :engine="engine" :renderers="renderers" style="height: 340px" />
+  </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)]),
+      ),
+    },
+  }
+}
+````
+
+### app/components/demos/DocsInsightNode.vue
+
+````vue
+<script setup lang="ts">
+import type { BoardNode } from '@lupinum/board-core'
+
+defineProps<{
+  node: BoardNode
+  selected: boolean
+}>()
+</script>
+
+<template>
+  <div
+    class="size-full rounded-[inherit] p-4 text-left"
+    :class="selected ? 'ring-2 ring-primary/60 ring-inset' : ''"
+    style="
+      background: linear-gradient(
+        135deg,
+        color-mix(in srgb, var(--ui-primary) 16%, transparent),
+        color-mix(in srgb, var(--ui-primary) 3%, white) 55%,
+        color-mix(in srgb, var(--ui-primary) 10%, transparent)
+      );
+      box-shadow:
+        inset 0 1px 0 0 color-mix(in srgb, var(--ui-primary) 16%, transparent),
+        inset 0 0 0 1px color-mix(in srgb, var(--ui-primary) 10%, transparent);
+    "
+  >
+    <div
+      class="text-[10px] font-mono uppercase tracking-[0.18em]"
+      style="color: var(--ui-primary)"
+    >
+      Insight node
+    </div>
+    <div class="mt-2 text-sm font-semibold text-highlighted">
+      {{ node.text?.split('\n')[0] ?? 'Untitled' }}
+    </div>
+    <div class="mt-2 text-xs leading-5 text-muted">
+      {{
+        node.text?.split('\n').slice(1).join('\n') ||
+        'Use custom renderers to swap the default card view for any Vue component.'
+      }}
+    </div>
+  </div>
+</template>
+````
+
+### app/components/demos/DocsMetricNode.vue
+
+````vue
+<script setup lang="ts">
+import { computed } from 'vue'
+import type { BoardNode } from '@lupinum/board-core'
+
+const props = defineProps<{
+  node: BoardNode
+  selected: boolean
+}>()
+
+const data = computed(() => {
+  const [label = 'Metric', value = '-', delta = '', caption = ''] =
+    props.node.label?.split('\n') ?? []
+  return { label, value, delta, caption }
+})
+const deltaPositive = computed(() => {
+  const d = String(data.value.delta ?? '')
+  return d.startsWith('+')
+})
+</script>
+
+<template>
+  <div
+    class="flex h-full flex-col justify-between rounded-md border p-4"
+    :class="[selected ? 'ring-2 ring-primary' : 'border-default']"
+    style="
+      background: linear-gradient(
+        160deg,
+        color-mix(in srgb, var(--ui-primary) 8%, white),
+        white 50%,
+        color-mix(in srgb, var(--ui-primary) 5%, white)
+      );
+      box-shadow:
+        inset 0 1px 0 0 color-mix(in srgb, var(--ui-primary) 12%, transparent),
+        0 12px 40px rgba(15, 23, 42, 0.07),
+        0 1px 3px rgba(15, 23, 42, 0.04);
+    "
+  >
+    <div class="flex items-center justify-between gap-3">
+      <span
+        class="text-[0.65rem] font-semibold uppercase tracking-[0.28em] text-dimmed"
+        >{{ data.label }}</span
+      >
+      <span
+        class="rounded-full px-2.5 py-1 text-[0.7rem] font-semibold tracking-wide ring-1"
+        :class="
+          deltaPositive
+            ? 'bg-emerald-50 text-emerald-700 ring-emerald-200/60'
+            : 'bg-amber-50 text-amber-700 ring-amber-200/60'
+        "
+      >
+        {{ data.delta }}
+      </span>
+    </div>
+    <div>
+      <p
+        class="text-3xl font-bold tracking-tight"
+        style="color: var(--ui-primary)"
+      >
+        {{ data.value }}
+      </p>
+      <p class="mt-2 text-sm leading-6 text-muted">
+        {{ data.caption }}
+      </p>
+    </div>
+  </div>
+</template>
+````
 
 ## Choose the data shape first
 

package/dist/agent/pages/docs/build-features/read-only-and-command-guards.md

@@ -31,8 +31,284 @@ This is not a third-party plugin surface. The supported consumer API is the
 package API exposed by each first-party package, such as `engine.plugins.history` and
 `engine.plugins.connections`.
 
-> Component omitted: `read-only-toggle-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/ReadOnlyToggleDemo.vue
+
+````vue
+<script setup lang="ts">
+import { onMounted, ref, watch } from 'vue'
+import { createBoardEngine } from '@lupinum/board-core'
+import { createDemoDocument } from '../../utils/demoDocument'
+
+const engine = createBoardEngine({
+  grid: { size: 20, majorEvery: 5, snap: true, pattern: 'dot' },
+})
+
+const isReadOnly = ref(true)
+const blockedCount = ref(0)
+let unsubscribeReadOnly: (() => void) | null = null
+
+const blockedCommands = new Set([
+  'beginNodeDrag',
+  'beginResize',
+  'beginTextEdit',
+  'createNode',
+  'updateNode',
+  'deleteNode',
+  'moveNode',
+  'resizeNode',
+  'deleteSelected',
+  'duplicateNodes',
+  'translateSelectedNodes',
+  'sendToBack',
+  'lockNode',
+  'unlockNode',
+  'commitTextEdit',
+  'copySelected',
+  'pasteClipboard',
+])
+
+function seed() {
+  engine.loadDocument(
+    createDemoDocument({
+      camera: { x: 0, y: 0, z: 1 },
+      grid: engine.getGridSettings(),
+      nodes: [
+        {
+          id: 'ro-a',
+          type: 'text',
+          x: 80,
+          y: 90,
+          width: 220,
+          height: 100,
+          text: 'Node',
+          zIndex: 1,
+          locked: false,
+          visible: true,
+        },
+        {
+          id: 'ro-b',
+          type: 'text',
+          x: 380,
+          y: 190,
+          width: 220,
+          height: 100,
+          text: 'Node',
+          zIndex: 2,
+          locked: false,
+          visible: true,
+        },
+      ],
+      selection: [],
+      nextZIndex: 3,
+    }),
+    { mode: 'replace' },
+  )
+}
+
+function applyReadOnly() {
+  unsubscribeReadOnly?.()
+  unsubscribeReadOnly = null
+
+  if (!isReadOnly.value) {
+    return
+  }
+
+  unsubscribeReadOnly = engine.addCommandGuard(({ name }) => {
+    if (blockedCommands.has(name)) {
+      blockedCount.value += 1
+      return 'Board is read-only.'
+    }
+    return true
+  })
+}
+
+watch(isReadOnly, applyReadOnly)
+
+onMounted(async () => {
+  seed()
+  applyReadOnly()
+  await engine.zoomToFit(60, false)
+})
+</script>
+
+<template>
+  <div class="demo-frame">
+    <div class="demo-toolbar">
+      <button class="demo-danger" @click="seed">Reset</button>
+      <button class="demo-primary" @click="isReadOnly = !isReadOnly">
+        {{ isReadOnly ? 'Switch to edit mode' : 'Switch to read-only' }}
+      </button>
+      <span class="demo-toolbar-note">
+        {{
+          isReadOnly
+            ? 'Mutations blocked — try dragging or deleting.'
+            : 'Mutations allowed.'
+        }}
+      </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"
+      >
+        <div
+          class="inline-flex rounded-full px-3 py-2 text-sm font-semibold"
+          :class="
+            isReadOnly
+              ? 'bg-amber-50 text-amber-700'
+              : 'bg-emerald-50 text-emerald-700'
+          "
+        >
+          {{ isReadOnly ? 'Read-only' : 'Editable' }}
+        </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"
+          >
+            Blocked attempts
+          </p>
+          <p class="mt-2 text-2xl font-bold tracking-tight text-highlighted">
+            {{ blockedCount }}
+          </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)]),
+      ),
+    },
+  }
+}
+````
 
 ## Command guards