feat: split Ordo designer into library monorepo

Extract ordo-designer-vue package with shadcn UI and context-based state; add playground app, library-api docs, and README.

Co-authored-by: Cursor <cursoragent@cursor.com>

apps/playground/env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

apps/playground/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" href="/favicon.ico" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Ordo Designer Playground</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

apps/playground/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "playground",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "run-p type-check \"build-only {@}\" --",
+    "preview": "vite preview",
+    "build-only": "vite build",
+    "type-check": "vue-tsc --build"
+  },
+  "dependencies": {
+    "ordo-designer-vue": "workspace:*",
+    "vue": "^3.5.40",
+    "vue-router": "^5.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "@tsconfig/node24": "^24.0.4",
+    "@tailwindcss/vite": "^4.3.3",
+    "@vitejs/plugin-vue": "^6.0.8",
+    "@vue/tsconfig": "^0.9.1",
+    "npm-run-all2": "^9.0.2",
+    "tailwindcss": "^4.3.3",
+    "typescript": "~6.0.0",
+    "vite": "^8.1.5",
+    "vite-plugin-vue-devtools": "^8.1.5",
+    "vue-tsc": "^3.3.7"
+  }
+}

apps/playground/src/App.vue

@@ -0,0 +1,5 @@
+<script setup lang="ts"></script>
+
+<template>
+  <router-view />
+</template>

apps/playground/src/api/createOrdoClient.ts

@@ -0,0 +1,64 @@
+import type { CatalogItem, OrdoClient, PageResponse, ProcessDefinitionDocument } from 'ordo-designer-vue'
+
+async function request<T>(baseUrl: string, url: string, init?: RequestInit): Promise<T> {
+  const res = await fetch(`${baseUrl}${url}`, {
+    ...init,
+    headers: {
+      'Content-Type': 'application/json',
+      ...(init?.headers ?? {}),
+    },
+  })
+  if (!res.ok) {
+    let message = res.statusText
+    try {
+      const body = (await res.json()) as { message?: string }
+      if (body.message) {
+        message = body.message
+      }
+    } catch {
+      /* ignore */
+    }
+    throw new Error(message)
+  }
+  if (res.status === 204) {
+    return undefined as T
+  }
+  return (await res.json()) as T
+}
+
+export function createOrdoClient(baseUrl = '/ordo'): OrdoClient {
+  return {
+    listConditions: () => request<CatalogItem[]>(baseUrl, '/catalog/conditions'),
+    listActions: () => request<CatalogItem[]>(baseUrl, '/catalog/actions'),
+    listAssignees: () => request<CatalogItem[]>(baseUrl, '/catalog/assignees'),
+    getDefinition: (id) => request<ProcessDefinitionDocument>(baseUrl, `/definitions/${encodeURIComponent(id)}`),
+    getDefinitionVersion: (id, version) =>
+      request<ProcessDefinitionDocument>(baseUrl, `/definitions/${encodeURIComponent(id)}/versions/${version}`),
+    parseDefinition: (doc) =>
+      request<ProcessDefinitionDocument>(baseUrl, '/definitions/parse', {
+        method: 'POST',
+        body: JSON.stringify(doc),
+      }),
+    publishDefinition: (doc) =>
+      request<ProcessDefinitionDocument>(baseUrl, '/definitions', {
+        method: 'POST',
+        body: JSON.stringify(doc),
+      }),
+  }
+}
+
+export function listDefinitions(baseUrl: string, page = 0, size = 50) {
+  return request<PageResponse<ProcessDefinitionDocument>>(
+    baseUrl,
+    `/definitions?page=${page}&size=${size}`,
+  )
+}
+
+export function listDefinitionVersions(baseUrl: string, id: string, page = 0, size = 50) {
+  return request<PageResponse<ProcessDefinitionDocument>>(
+    baseUrl,
+    `/definitions/${encodeURIComponent(id)}/versions?page=${page}&size=${size}`,
+  )
+}
+
+export type { PageResponse, ProcessDefinitionDocument }

apps/playground/src/composables/useAsync.ts

@@ -0,0 +1,21 @@
+import { ref } from 'vue'
+
+export function useAsync() {
+  const loading = ref(false)
+  const error = ref<string | null>(null)
+
+  async function run<T>(fn: () => Promise<T>): Promise<T> {
+    loading.value = true
+    error.value = null
+    try {
+      return await fn()
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : 'Request failed'
+      throw e
+    } finally {
+      loading.value = false
+    }
+  }
+
+  return { loading, error, run }
+}

apps/playground/src/main.ts

@@ -0,0 +1,8 @@
+import { createApp } from 'vue'
+import 'ordo-designer-vue/style.css'
+import './styles/main.css'
+
+import App from './App.vue'
+import router from './router'
+
+createApp(App).use(router).mount('#app')

apps/playground/src/router/index.ts

@@ -0,0 +1,13 @@
+import { createRouter, createWebHistory } from 'vue-router'
+import DefinitionListView from '@/views/DefinitionListView.vue'
+import DesignerPage from '@/views/DesignerPage.vue'
+
+const router = createRouter({
+  history: createWebHistory(import.meta.env.BASE_URL),
+  routes: [
+    { path: '/', name: 'definitions', component: DefinitionListView },
+    { path: '/designer/:definitionId?', name: 'designer', component: DesignerPage },
+  ],
+})
+
+export default router

apps/playground/src/stores/drafts.ts

@@ -0,0 +1,73 @@
+import { ref, type Ref } from 'vue'
+import type { DesignerDraft, DraftStorage } from 'ordo-designer-vue'
+import { layoutFromNodes } from 'ordo-designer-vue'
+import type { DesignerEdge, DesignerNode, ProcessDefinitionDocument } from 'ordo-designer-vue'
+
+const STORAGE_KEY = 'ordo-designer-drafts'
+
+function readAll(): Record<string, DesignerDraft> {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY)
+    if (!raw) {
+      return {}
+    }
+    return JSON.parse(raw) as Record<string, DesignerDraft>
+  } catch {
+    return {}
+  }
+}
+
+function writeAll(drafts: Record<string, DesignerDraft>) {
+  localStorage.setItem(STORAGE_KEY, JSON.stringify(drafts))
+}
+
+export function createDraftStorage(): DraftStorage {
+  const revision = ref(0)
+
+  return {
+    revision,
+    get(id: string) {
+      return readAll()[id]
+    },
+    save(params: {
+      id: string
+      name: string
+      startStepId: string
+      nodes: DesignerNode[]
+      edges: DesignerEdge[]
+    }) {
+      const drafts = readAll()
+      drafts[params.id] = {
+        id: params.id,
+        name: params.name,
+        startStepId: params.startStepId,
+        nodes: params.nodes,
+        edges: params.edges,
+        layout: layoutFromNodes(params.nodes),
+        updatedAt: Date.now(),
+      }
+      writeAll(drafts)
+      revision.value += 1
+    },
+    remove(id: string) {
+      const drafts = readAll()
+      delete drafts[id]
+      writeAll(drafts)
+      revision.value += 1
+    },
+  }
+}
+
+const shared = createDraftStorage()
+
+export function useDraftStorage(): DraftStorage {
+  return shared
+}
+
+export function listLocalDrafts(): DesignerDraft[] {
+  return Object.values(readAll()).sort((a, b) => b.updatedAt - a.updatedAt)
+}
+
+export function fromPublished(doc: ProcessDefinitionDocument): DesignerDraft | undefined {
+  return shared.get(doc.id)
+}

apps/playground/src/styles/main.css

@@ -0,0 +1,8 @@
+@import "tailwindcss";
+
+html,
+body,
+#app {
+  height: 100%;
+  margin: 0;
+}

apps/playground/src/views/DefinitionListView.vue

@@ -0,0 +1,246 @@
+<script setup lang="ts">
+import { computed, onMounted, ref } from 'vue'
+import { useRouter } from 'vue-router'
+import {
+  comparableDocument,
+  toDocument,
+  DraftConflictModal,
+  Button,
+  Badge,
+  Alert,
+  DialogPanel,
+  type DesignerDraft,
+  type ProcessDefinitionDocument,
+} from 'ordo-designer-vue'
+import { createOrdoClient, listDefinitionVersions, listDefinitions } from '@/api/createOrdoClient'
+import { listLocalDrafts, useDraftStorage } from '@/stores/drafts'
+import { useAsync } from '@/composables/useAsync'
+
+const router = useRouter()
+const drafts = useDraftStorage()
+const listAsync = useAsync()
+const versionsAsync = useAsync()
+const loading = listAsync.loading
+const error = listAsync.error
+const published = ref<ProcessDefinitionDocument[]>([])
+const localDrafts = ref<DesignerDraft[]>([])
+const versionsShow = ref(false)
+const versions = ref<ProcessDefinitionDocument[]>([])
+const versionsTitle = ref('')
+const conflictShow = ref(false)
+const conflictDraft = ref<DesignerDraft | null>(null)
+const conflictPublished = ref<ProcessDefinitionDocument | null>(null)
+
+const publishedById = computed(() => {
+  const map = new Map<string, ProcessDefinitionDocument>()
+  for (const row of published.value) {
+    map.set(row.id, row)
+  }
+  return map
+})
+
+const conflictDraftText = computed(() => {
+  const draft = conflictDraft.value
+  if (!draft) {
+    return ''
+  }
+  return comparableDocument(toDocument(draft.id, draft.name, draft.startStepId, draft.nodes, draft.edges))
+})
+const conflictPublishedText = computed(() =>
+  conflictPublished.value ? comparableDocument(conflictPublished.value) : '',
+)
+
+function goDesigner(id: string, source?: 'draft' | 'published', version?: number) {
+  versionsShow.value = false
+  conflictShow.value = false
+  void router.push({
+    name: 'designer',
+    params: { definitionId: id },
+    query: {
+      ...(version != null ? { version: String(version) } : {}),
+      ...(source ? { source } : {}),
+    },
+  })
+}
+
+function openPublished(row: ProcessDefinitionDocument) {
+  const draft = drafts.get(row.id)
+  if (draft) {
+    conflictDraft.value = draft
+    conflictPublished.value = row
+    conflictShow.value = true
+    return
+  }
+  goDesigner(row.id)
+}
+
+function onOpenDraft() {
+  const draft = conflictDraft.value
+  if (!draft) {
+    return
+  }
+  goDesigner(draft.id, 'draft')
+}
+
+function onDiscardDraft() {
+  const publishedDoc = conflictPublished.value
+  const draft = conflictDraft.value
+  if (draft) {
+    drafts.remove(draft.id)
+    localDrafts.value = listLocalDrafts()
+  }
+  if (publishedDoc) {
+    goDesigner(publishedDoc.id, 'published')
+  }
+}
+
+function newProcess() {
+  void router.push({ name: 'designer' })
+}
+
+async function openVersions(id: string) {
+  versionsTitle.value = id
+  try {
+    const page = await versionsAsync.run(() => listDefinitionVersions('/ordo', id))
+    versions.value = page.content
+    versionsShow.value = true
+  } catch {
+    error.value = versionsAsync.error.value || 'Failed to load versions'
+  }
+}
+
+async function load() {
+  localDrafts.value = listLocalDrafts()
+  try {
+    const page = await listAsync.run(() => listDefinitions('/ordo'))
+    published.value = page.content
+  } catch {
+    published.value = []
+  }
+}
+
+onMounted(() => {
+  void load()
+})
+</script>
+
+<template>
+  <div class="ordo-designer min-h-screen bg-background p-6 text-foreground">
+    <div class="mx-auto flex max-w-5xl flex-col gap-4">
+      <div class="flex items-center justify-between">
+        <h1 class="text-lg font-semibold">Process definitions</h1>
+        <div class="flex gap-2">
+          <Button variant="outline" size="sm" @click="load">Refresh</Button>
+          <Button size="sm" @click="newProcess">New</Button>
+        </div>
+      </div>
+      <Alert v-if="error" variant="warning">{{ error }}</Alert>
+      <section class="rounded-lg border border-border bg-card p-4 text-card-foreground">
+        <h2 class="mb-3 text-sm font-semibold text-muted-foreground">Published</h2>
+        <p v-if="loading" class="text-sm text-muted-foreground">Loading…</p>
+        <table v-else class="w-full text-left text-sm">
+          <thead>
+            <tr class="border-b border-border text-muted-foreground">
+              <th class="py-2 pr-4 font-medium">id</th>
+              <th class="py-2 pr-4 font-medium">name</th>
+              <th class="py-2 pr-4 font-medium">version</th>
+              <th class="py-2 pr-4 font-medium">draft</th>
+              <th class="py-2 font-medium">actions</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr v-for="row in published" :key="row.id" class="border-b border-border">
+              <td class="py-2 pr-4 font-mono text-xs">{{ row.id }}</td>
+              <td class="py-2 pr-4">{{ row.name }}</td>
+              <td class="py-2 pr-4">{{ row.version ?? '—' }}</td>
+              <td class="py-2 pr-4">
+                <template v-if="drafts.get(row.id)">
+                  <Badge variant="warning" class="mr-2">Draft</Badge>
+                  <Button variant="ghost" size="xs" class="h-auto px-1 text-primary" @click="goDesigner(row.id, 'draft')">
+                    Open draft
+                  </Button>
+                </template>
+                <span v-else class="text-muted-foreground">—</span>
+              </td>
+              <td class="py-2">
+                <div class="flex flex-wrap gap-1">
+                  <Button variant="ghost" size="xs" class="h-auto px-1 text-primary" @click="openPublished(row)">Open</Button>
+                  <Button variant="ghost" size="xs" class="h-auto px-1 text-primary" @click="openVersions(row.id)">
+                    Versions
+                  </Button>
+                </div>
+              </td>
+            </tr>
+          </tbody>
+        </table>
+      </section>
+      <section class="rounded-lg border border-border bg-card p-4 text-card-foreground">
+        <h2 class="mb-3 text-sm font-semibold text-muted-foreground">Local drafts</h2>
+        <table class="w-full text-left text-sm">
+          <thead>
+            <tr class="border-b border-border text-muted-foreground">
+              <th class="py-2 pr-4 font-medium">id</th>
+              <th class="py-2 pr-4 font-medium">name</th>
+              <th class="py-2 pr-4 font-medium">updated</th>
+              <th class="py-2 pr-4 font-medium">published</th>
+              <th class="py-2 font-medium">actions</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr v-for="row in localDrafts" :key="row.id" class="border-b border-border">
+              <td class="py-2 pr-4 font-mono text-xs">{{ row.id }}</td>
+              <td class="py-2 pr-4">{{ row.name }}</td>
+              <td class="py-2 pr-4">{{ new Date(row.updatedAt).toLocaleString() }}</td>
+              <td class="py-2 pr-4">
+                {{
+                  publishedById.get(row.id)?.version != null
+                    ? `v${publishedById.get(row.id)!.version}`
+                    : '—'
+                }}
+              </td>
+              <td class="py-2">
+                <Button variant="ghost" size="xs" class="h-auto px-1 text-primary" @click="goDesigner(row.id, 'draft')">
+                  Open
+                </Button>
+              </td>
+            </tr>
+          </tbody>
+        </table>
+      </section>
+    </div>
+    <DialogPanel v-model:open="versionsShow" :title="`Versions · ${versionsTitle}`" class="max-w-lg">
+      <table class="w-full text-sm">
+        <thead>
+          <tr class="border-b border-border text-muted-foreground">
+            <th class="py-2 pr-4 font-medium">version</th>
+            <th class="py-2 pr-4 font-medium">name</th>
+            <th class="py-2 font-medium">actions</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr v-for="row in versions" :key="String(row.version)" class="border-b border-border">
+            <td class="py-2 pr-4">{{ row.version }}</td>
+            <td class="py-2 pr-4">{{ row.name }}</td>
+            <td class="py-2">
+              <Button
+                variant="ghost"
+                size="xs"
+                class="h-auto px-1 text-primary"
+                @click="goDesigner(versionsTitle, undefined, row.version)"
+              >
+                Open
+              </Button>
+            </td>
+          </tr>
+        </tbody>
+      </table>
+    </DialogPanel>
+    <DraftConflictModal
+      v-model:show="conflictShow"
+      :draft-text="conflictDraftText"
+      :published-text="conflictPublishedText"
+      @open-draft="onOpenDraft"
+      @discard="onDiscardDraft"
+    />
+  </div>
+</template>

apps/playground/src/views/DesignerPage.vue

@@ -0,0 +1,56 @@
+<script setup lang="ts">
+import { computed, useTemplateRef } from 'vue'
+import { onBeforeRouteLeave, useRoute, useRouter } from 'vue-router'
+import { OrdoDesigner } from 'ordo-designer-vue'
+import { createOrdoClient } from '@/api/createOrdoClient'
+import { useDraftStorage } from '@/stores/drafts'
+
+const route = useRoute()
+const router = useRouter()
+const client = createOrdoClient()
+const drafts = useDraftStorage()
+const designerRef = useTemplateRef<InstanceType<typeof OrdoDesigner>>('designerRef')
+
+const definitionId = computed(() =>
+  typeof route.params.definitionId === 'string' ? route.params.definitionId : undefined,
+)
+const version = computed(() => {
+  const raw = route.query.version
+  if (typeof raw === 'string' && Number.isFinite(Number(raw))) {
+    return Number(raw)
+  }
+  return undefined
+})
+const source = computed(() => (typeof route.query.source === 'string' ? route.query.source : undefined))
+
+function onBack() {
+  void router.push({ name: 'definitions' })
+}
+
+function onNavigate(id: string) {
+  void router.replace({ name: 'designer', params: { definitionId: id } })
+}
+
+onBeforeRouteLeave(async () => {
+  designerRef.value?.flushAutosave?.()
+  if (designerRef.value?.confirmLeave) {
+    return designerRef.value.confirmLeave()
+  }
+  return true
+})
+</script>
+
+<template>
+  <div class="h-screen">
+    <OrdoDesigner
+      ref="designerRef"
+      :client="client"
+      :drafts="drafts"
+      :definition-id="definitionId"
+      :version="version"
+      :source="source"
+      @back="onBack"
+      @navigate="onNavigate"
+    />
+  </div>
+</template>

apps/playground/tsconfig.app.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@vue/tsconfig/tsconfig.dom.json",
+  "include": ["env.d.ts", "src/**/*", "src/**/*.vue"],
+  "compilerOptions": {
+    "noUncheckedIndexedAccess": true,
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo"
+  }
+}

apps/playground/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "files": [],
+  "references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" }]
+}

apps/playground/tsconfig.node.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@tsconfig/node24/tsconfig.json",
+  "include": ["vite.config.ts"],
+  "compilerOptions": {
+    "noEmit": true,
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo"
+  }
+}

apps/playground/vite.config.ts

@@ -0,0 +1,29 @@
+import path from 'node:path'
+import { fileURLToPath, URL } from 'node:url'
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import vueDevTools from 'vite-plugin-vue-devtools'
+import tailwindcss from '@tailwindcss/vite'
+
+const pkgDist = fileURLToPath(new URL('../../packages/ordo-designer-vue/dist/ordo-designer-vue.js', import.meta.url))
+const pkgStyle = fileURLToPath(new URL('../../packages/ordo-designer-vue/dist/style.css', import.meta.url))
+
+export default defineConfig({
+  plugins: [vue(), vueDevTools(), tailwindcss()],
+  resolve: {
+    alias: [
+      { find: '@', replacement: fileURLToPath(new URL('./src', import.meta.url)) },
+      { find: 'ordo-designer-vue/style.css', replacement: pkgStyle },
+      // Exact entry only — avoid breaking `ordo-designer-vue/style.css` subpath.
+      { find: /^ordo-designer-vue$/, replacement: pkgDist },
+    ],
+  },
+  server: {
+    proxy: {
+      '/ordo': {
+        target: 'http://localhost:8080',
+        changeOrigin: true,
+      },
+    },
+  },
+})