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

package/dist/agent/pages/docs/solutions/workflow-builder.md

@@ -13,8 +13,441 @@ source: "ginko-content"
 
 > Render step-style cards with custom renderers, connections, and undo/redo.
 
-> Component omitted: `workflow-renderer-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/WorkflowRendererDemo.vue
+
+````vue
+<script setup lang="ts">
+import { computed, onBeforeUnmount, 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'
+import { historyPlugin } from '@lupinum/board-history'
+import WorkflowStepNode from './WorkflowStepNode.vue'
+
+type StepStatus = 'pending' | 'active' | 'done'
+interface WorkflowStep {
+  id: ReturnType<typeof asNodeId>
+  status: StepStatus
+  label: string
+  summary: string
+}
+
+const engine = createBoardEngine({
+  grid: { size: 24, majorEvery: 4, snap: true, pattern: 'line' },
+  plugins: [historyPlugin(), connectionsPlugin({ routing: 'step' })],
+})
+
+const CAPTURE_ID = asNodeId('capture')
+const QUALIFY_ID = asNodeId('qualify')
+const HANDOFF_ID = asNodeId('handoff')
+
+function createWorkflowSteps(): WorkflowStep[] {
+  return [
+    {
+      id: CAPTURE_ID,
+      status: 'done',
+      label: 'Capture lead',
+      summary: 'Collect the request and normalize inputs.',
+    },
+    {
+      id: QUALIFY_ID,
+      status: 'active',
+      label: 'Qualify',
+      summary: 'Score, tag, and route the lead.',
+    },
+    {
+      id: HANDOFF_ID,
+      status: 'pending',
+      label: 'Handoff',
+      summary: 'Create the downstream record and alert the owner.',
+    },
+  ]
+}
+
+const workflowSteps = ref<WorkflowStep[]>(createWorkflowSteps())
+const stepsByNodeId = computed(
+  () => new Map(workflowSteps.value.map((step) => [step.id, step])),
+)
+const historyState = ref(engine.plugins.history.getState())
+
+function syncHistoryState() {
+  historyState.value = engine.plugins.history.getState()
+}
+
+const unsubscribeHistory = [
+  engine.on('history:push', syncHistoryState),
+  engine.on('history:undo', syncHistoryState),
+  engine.on('history:redo', syncHistoryState),
+  engine.on('history:clear', syncHistoryState),
+]
+
+function seed() {
+  workflowSteps.value = createWorkflowSteps()
+
+  engine.loadDocument(
+    createDemoDocument({
+      camera: { x: -40, y: -30, z: 1 },
+      grid: engine.getGridSettings(),
+      selection: [],
+      nextZIndex: 4,
+      nodes: [
+        {
+          id: CAPTURE_ID,
+          type: 'text',
+          x: 40,
+          y: 110,
+          width: 220,
+          height: 130,
+          text: '',
+          zIndex: 1,
+          locked: false,
+          visible: true,
+        },
+        {
+          id: QUALIFY_ID,
+          type: 'text',
+          x: 340,
+          y: 110,
+          width: 220,
+          height: 130,
+          text: '',
+          zIndex: 2,
+          locked: false,
+          visible: true,
+        },
+        {
+          id: HANDOFF_ID,
+          type: 'text',
+          x: 640,
+          y: 110,
+          width: 220,
+          height: 130,
+          text: '',
+          zIndex: 3,
+          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: CAPTURE_ID,
+    to: QUALIFY_ID,
+    label: 'validated',
+    data: {},
+  })
+  engine.plugins.connections.createEdge({
+    from: QUALIFY_ID,
+    to: HANDOFF_ID,
+    label: 'approved',
+    data: {},
+  })
+  engine.plugins.history.clear()
+  syncHistoryState()
+}
+
+function nextStatus(current: StepStatus): StepStatus {
+  if (current === 'pending') return 'active'
+  if (current === 'active') return 'done'
+  return 'pending'
+}
+
+function advanceSelected() {
+  const target = engine.getSelection()[0] ?? QUALIFY_ID
+  workflowSteps.value = workflowSteps.value.map((step) =>
+    step.id === target ? { ...step, status: nextStatus(step.status) } : step,
+  )
+}
+
+onMounted(async () => {
+  seed()
+  await engine.zoomToFit(80, false)
+})
+
+onBeforeUnmount(() => {
+  for (const unsubscribe of unsubscribeHistory) {
+    unsubscribe()
+  }
+})
+</script>
+
+<template>
+  <div class="demo-frame">
+    <div class="demo-toolbar">
+      <button class="demo-danger" @click="seed">Reset</button>
+      <button class="demo-primary" @click="advanceSelected">
+        Cycle selected step
+      </button>
+      <button
+        :disabled="historyState.undoDepth === 0"
+        @click="engine.plugins.history.undo()"
+      >
+        Undo
+      </button>
+      <button
+        :disabled="historyState.redoDepth === 0"
+        @click="engine.plugins.history.redo()"
+      >
+        Redo
+      </button>
+      <span class="demo-history-badge ml-auto"
+        >{{ historyState.undoDepth }} undo /
+        {{ historyState.redoDepth }} redo</span
+      >
+    </div>
+
+    <BoardRoot :engine="engine" style="height: 400px">
+      <template #node:text="{ node, selected }">
+        <WorkflowStepNode
+          :step="stepsByNodeId.get(node.id)"
+          :selected="selected"
+        />
+      </template>
+      <BoardConnectionLayer routing="step" />
+    </BoardRoot>
+  </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/WorkflowStepNode.vue
+
+````vue
+<script setup lang="ts">
+import { computed } from 'vue'
+
+interface WorkflowStep {
+  status: 'pending' | 'active' | 'done'
+  label: string
+  summary: string
+}
+
+const props = defineProps<{
+  step?: WorkflowStep
+  selected: boolean
+}>()
+
+const data = computed(() => {
+  return (
+    props.step ?? {
+      status: 'pending',
+      label: 'Missing step',
+      summary: 'No workflow record matches this board node.',
+    }
+  )
+})
+const tone = computed(() => {
+  const status = data.value.status
+  if (status === 'done') {
+    return {
+      badge: 'bg-emerald-100 text-emerald-800 ring-1 ring-emerald-300/60',
+      border: '#10b981',
+      surface: `linear-gradient(135deg,
+        color-mix(in srgb, #10b981 14%, white),
+        color-mix(in srgb, #10b981 4%, white) 60%,
+        color-mix(in srgb, #10b981 10%, white))`,
+      glow: 'inset 0 1px 0 0 rgba(16,185,129,0.18), 0 18px 60px rgba(15,23,42,0.08), 0 1px 3px rgba(16,185,129,0.10)',
+    }
+  }
+  if (status === 'active') {
+    return {
+      badge: 'bg-sky-100 text-sky-800 ring-1 ring-sky-300/60',
+      border: '#0ea5e9',
+      surface: `linear-gradient(135deg,
+        color-mix(in srgb, #0ea5e9 14%, white),
+        color-mix(in srgb, #0ea5e9 4%, white) 60%,
+        color-mix(in srgb, #0ea5e9 10%, white))`,
+      glow: 'inset 0 1px 0 0 rgba(14,165,233,0.18), 0 18px 60px rgba(15,23,42,0.08), 0 1px 3px rgba(14,165,233,0.10)',
+    }
+  }
+  return {
+    badge: 'bg-slate-100 text-slate-600 ring-1 ring-slate-200',
+    border: '#94a3b8',
+    surface: `linear-gradient(135deg,
+      color-mix(in srgb, #94a3b8 8%, white),
+      white 60%,
+      color-mix(in srgb, #94a3b8 6%, white))`,
+    glow: 'inset 0 1px 0 0 rgba(148,163,184,0.14), 0 18px 60px rgba(15,23,42,0.06)',
+  }
+})
+</script>
+
+<template>
+  <div
+    class="h-full rounded-md border p-4"
+    :class="[selected ? 'ring-2 ring-primary' : 'border-default']"
+    :style="{
+      borderLeft: `5px solid ${tone.border}`,
+      background: tone.surface,
+      boxShadow: tone.glow,
+    }"
+  >
+    <div class="flex h-full flex-col justify-between gap-3">
+      <div class="flex items-center justify-between gap-3">
+        <span
+          class="flex items-center gap-1.5 text-[0.65rem] font-semibold uppercase tracking-[0.28em] text-dimmed"
+        >
+          <span
+            class="inline-block size-1.5 rounded-full"
+            :style="{ background: tone.border }"
+          ></span>
+          Step
+        </span>
+        <span
+          class="rounded-full px-2.5 py-1 text-[0.7rem] font-semibold tracking-wide"
+          :class="tone.badge"
+          >{{ data.status }}</span
+        >
+      </div>
+      <div>
+        <h3 class="text-lg font-semibold tracking-tight text-highlighted">
+          {{ data.label }}
+        </h3>
+        <p class="mt-2 text-sm leading-6 text-muted">
+          {{ data.summary }}
+        </p>
+      </div>
+    </div>
+  </div>
+</template>
+````
 
 ## What happens