@eventcatalog/core 5.0.0-beta.5 → 5.0.0-beta.6

package/eventcatalog/src/features/studio/node-types.ts

@@ -0,0 +1,173 @@
+/**
+ * The kinds of node people (and agents) can put on a canvas, and what's in their data. Shared by the browser and
+ * the server, so it has no UI in it: the icons for each type are in components/icons.ts.
+ */
+
+export type NodeCategory = 'boundaries' | 'messages' | 'architecture' | 'other';
+
+export const NODE_CATEGORIES: { id: NodeCategory; label: string }[] = [
+  { id: 'boundaries', label: 'Boundaries' },
+  { id: 'messages', label: 'Messages' },
+  { id: 'architecture', label: 'Architecture' },
+  { id: 'other', label: 'Other' },
+];
+
+/** Domains and systems as containers: boxes other nodes sit in */
+export const GROUP_TYPES = { domain: 'domain-group', system: 'system-group' } as const;
+export const isGroupType = (type?: string) => type === GROUP_TYPES.domain || type === GROUP_TYPES.system;
+
+export type NodeDefinition = {
+  /** React Flow node type, matches the visualiser node component keys */
+  type: string;
+  label: string;
+  category: NodeCategory;
+  /** Not in the components list (still drawn, for canvases that have them) */
+  unlisted?: boolean;
+  /** Where the resource lives inside node.data (e.g. `service` for data.service). Undefined = data root */
+  resourceKey?: string;
+  /** Nodes that are sized on the canvas (containers, notes) start at this size */
+  defaultSize?: { width: number; height: number };
+  createData: () => Record<string, unknown>;
+};
+
+const resource = (name: string, summary: string) => ({ name, version: '0.0.1', summary, owners: [] });
+
+export const nodeDefinitions: NodeDefinition[] = [
+  {
+    type: GROUP_TYPES.domain,
+    label: 'Domain',
+    category: 'boundaries',
+    resourceKey: 'domain',
+    defaultSize: { width: 720, height: 460 },
+    createData: () => ({ domain: { name: 'New Domain', version: '0.0.1' } }),
+  },
+  {
+    type: GROUP_TYPES.system,
+    label: 'System',
+    category: 'boundaries',
+    resourceKey: 'system',
+    defaultSize: { width: 560, height: 360 },
+    createData: () => ({ system: { name: 'New System', version: '0.0.1' } }),
+  },
+  {
+    type: 'service',
+    category: 'architecture',
+    label: 'Service',
+    resourceKey: 'service',
+    createData: () => ({
+      mode: 'full',
+      service: { ...resource('New Service', 'Describe what this service does.'), sends: [], receives: [] },
+    }),
+  },
+  {
+    type: 'event',
+    category: 'messages',
+    label: 'Event',
+    resourceKey: 'message',
+    createData: () => ({ mode: 'full', message: resource('NewEvent', 'Something happened.') }),
+  },
+  {
+    type: 'command',
+    category: 'messages',
+    label: 'Command',
+    resourceKey: 'message',
+    createData: () => ({ mode: 'full', message: resource('NewCommand', 'Asks a service to do something.') }),
+  },
+  {
+    type: 'query',
+    category: 'messages',
+    label: 'Query',
+    resourceKey: 'message',
+    createData: () => ({ mode: 'full', message: resource('NewQuery', 'Asks for some information.') }),
+  },
+  {
+    type: 'channel',
+    category: 'architecture',
+    label: 'Channel',
+    resourceKey: 'channel',
+    createData: () => ({ mode: 'full', channel: { ...resource('new.channel', 'Where messages are routed.'), protocols: [] } }),
+  },
+  {
+    type: 'data',
+    category: 'architecture',
+    label: 'Data Store',
+    resourceKey: 'data',
+    createData: () => ({ mode: 'full', data: { ...resource('New Database', 'Stores data.'), container_type: 'database' } }),
+  },
+  {
+    type: 'view',
+    category: 'architecture',
+    label: 'View',
+    resourceKey: 'view',
+    createData: () => ({ mode: 'full', view: resource('New View', 'What the user sees.') }),
+  },
+  {
+    type: 'externalSystem',
+    category: 'architecture',
+    unlisted: true,
+    label: 'External System',
+    resourceKey: 'externalSystem',
+    createData: () => ({ mode: 'full', externalSystem: resource('External System', 'A third party system.') }),
+  },
+  {
+    type: 'agent',
+    category: 'architecture',
+    label: 'Agent',
+    resourceKey: 'agent',
+    createData: () => ({ mode: 'full', agent: { ...resource('New Agent', 'What this agent does.'), sends: [], receives: [] } }),
+  },
+  {
+    type: 'actor',
+    category: 'other',
+    label: 'Actor',
+    createData: () => ({ mode: 'full', name: 'Customer', summary: 'A person using the system.' }),
+  },
+  {
+    type: 'note',
+    category: 'other',
+    label: 'Sticky Note',
+    defaultSize: { width: 200, height: 160 },
+    createData: () => ({ text: 'Double-click to edit...', color: 'yellow' }),
+  },
+];
+
+/** The types people and agents can add (not the unlisted ones) */
+export const COMPONENT_TYPES = nodeDefinitions
+  .filter((definition) => !definition.unlisted)
+  .map((definition) => definition.type) as [string, ...string[]];
+
+const definitionsByType = new Map(nodeDefinitions.map((definition) => [definition.type, definition]));
+
+// Node types that only come from the catalog (not in the components list)
+const catalogNodeTypes: Record<string, { label: string; resourceKey: string }> = {
+  system: { label: 'System', resourceKey: 'system' },
+  'context-domain': { label: 'Domain', resourceKey: 'domain' },
+};
+
+export const getNodeDefinition = (type?: string) => (type ? definitionsByType.get(type) : undefined);
+
+export const getNodeLabel = (type?: string) => getNodeDefinition(type)?.label ?? catalogNodeTypes[type ?? '']?.label ?? 'Node';
+
+// About the size the visualiser's resource cards render at
+export const DEFAULT_NODE_SIZE = { width: 240, height: 112 };
+
+/** The size a new node of a type starts at (or, for cards, about the size it renders at) */
+export const getNodeSize = (type?: string) => getNodeDefinition(type)?.defaultSize ?? DEFAULT_NODE_SIZE;
+
+const getResourceKey = (type?: string) => getNodeDefinition(type)?.resourceKey ?? catalogNodeTypes[type ?? '']?.resourceKey;
+
+/** The resource object for a node (e.g. data.service), or the data itself for flat nodes */
+export const getResource = (type: string | undefined, data: Record<string, unknown>): Record<string, unknown> => {
+  const key = getResourceKey(type);
+  return key ? ((data[key] as Record<string, unknown>) ?? {}) : data;
+};
+
+/** Returns new node data with fields of the resource changed */
+export const updateResource = (type: string | undefined, data: Record<string, unknown>, fields: Record<string, unknown>) => {
+  const key = getResourceKey(type);
+  return key ? { ...data, [key]: { ...getResource(type, data), ...fields } } : { ...data, ...fields };
+};
+
+/** A node's name, as people and agents see it */
+export const getNodeName = (type: string | undefined, data: Record<string, unknown>, fallback = 'node') =>
+  String(getResource(type, data).name ?? data.text ?? fallback);

package/eventcatalog/src/features/studio/pages/[id].astro

@@ -0,0 +1,38 @@
+---
+// Visualiser styles ship in the page head so ClientRouter navigations keep them (see NodeGraph.astro).
+import '@eventcatalog/visualiser/styles-core.css';
+import '../studio.css';
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import { buildUrl } from '@utils/url-builder';
+import StudioDesigner from '../components/StudioDesigner';
+import { getCatalogResources } from '../catalog-resources';
+import { STUDIO_SOCKET_PATH } from '../server/runtime';
+
+export const prerender = false;
+
+const { id } = Astro.params;
+
+if (!id || !/^[0-9a-f-]{36}$/i.test(id)) {
+  return Astro.redirect(buildUrl('/studio'));
+}
+
+const { resources, relations } = await getCatalogResources();
+---
+
+<VerticalSideBarLayout title="Studio - EventCatalog" showNestedSideBar={false}>
+  <main
+    class="min-h-0 overflow-hidden bg-[rgb(var(--ec-page-bg))]"
+    style="margin-left: calc(var(--ec-app-content-padding-left, 5rem) * -1); margin-right: calc(var(--ec-app-content-padding-right, 5rem) * -1); height: calc(100dvh - 60px);"
+  >
+    <StudioDesigner
+      client:only="react"
+      canvasId={id}
+      socketPath={buildUrl(STUDIO_SOCKET_PATH, true)}
+      newCanvasUrl={buildUrl('/studio')}
+      mcpUrl={buildUrl('/docs/mcp', true)}
+      relayScriptPath={buildUrl('/webmcp-relay/embed.js', true)}
+      resources={resources}
+      relations={relations}
+    />
+  </main>
+</VerticalSideBarLayout>

package/eventcatalog/src/features/studio/pages/index.astro

@@ -0,0 +1,8 @@
+---
+import { buildUrl } from '@utils/url-builder';
+
+export const prerender = false;
+
+// EventCatalog Studio: each visit starts a new canvas
+return Astro.redirect(buildUrl(`/studio/${crypto.randomUUID()}`));
+---

package/eventcatalog/src/features/studio/pages/webmcp-relay.ts

@@ -0,0 +1,27 @@
+import type { APIRoute } from 'astro';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+/**
+ * Serves the WebMCP local relay's browser files (embed.js loads widget.html next to it), so the canvas page
+ * can hand its WebMCP tools to desktop MCP clients (Claude Code, Cursor...) running
+ * `npx -y @mcp-b/webmcp-local-relay@5.1.0`. Served from the installed package, so the version is pinned.
+ */
+const FILES: Record<string, string> = {
+  'embed.js': 'text/javascript',
+  'widget.html': 'text/html',
+  'widget.js': 'text/javascript',
+};
+
+const browserDirectory = path.join(path.dirname(createRequire(import.meta.url).resolve('@mcp-b/webmcp-local-relay')), 'browser');
+
+export const GET: APIRoute = async ({ params }) => {
+  const file = params.file ?? '';
+  const contentType = FILES[file];
+  if (!contentType) return new Response('Not found', { status: 404 });
+  const body = await fs.readFile(path.join(browserDirectory, file), 'utf-8');
+  return new Response(body, { headers: { 'Content-Type': contentType, 'Cache-Control': 'no-cache' } });
+};
+
+export const prerender = false;

package/eventcatalog/src/features/studio/placement.ts

@@ -0,0 +1,197 @@
+import type { Node, XYPosition } from '@xyflow/react';
+import { fitGroup, getAbsolutePosition, GROUP_PADDING, sizeOf } from './grouping';
+
+/**
+ * Where agents put what they add without a position, the way an architect would: next to what it connects to,
+ * following the flow left to right (what sends to it on its left, what it sends to on its right), lined up with
+ * it, and stacked around it when several things connect to the same node. Nothing already on the canvas moves.
+ * Things connected to nothing go in a row below what's there. Containers are filled first, so what goes around them
+ * leaves room for what they grow to hold.
+ */
+
+/** A connection between two nodes, from the one that sends to the one that receives */
+export type Link = { source: string; target: string };
+
+/** Between connected nodes side by side (room for the labels on their connections), and nodes stacked in a column */
+const GAP = { x: 200, y: 80 };
+/** The least room left around nodes */
+const CLEARANCE = { x: 120, y: 60 };
+/** Between what's on the canvas and things connected to nothing added below it */
+const BELOW_GAP = 120;
+/** Things connected to nothing go side by side (so connecting them later is easy), this many to a row */
+const ROW_LENGTH = 4;
+/** How far to look for free space before giving up and going below everything */
+const MAX_ROWS = 12;
+const MAX_COLUMNS = 8;
+
+type Rect = { x: number; y: number; width: number; height: number };
+type Anchor = { rect: Rect; centerY: number; upstream: boolean };
+
+const rectOf = (node: Node): Rect => ({ ...node.position, ...sizeOf(node) });
+
+const tooClose = (a: Rect, b: Rect) =>
+  a.x < b.x + b.width + CLEARANCE.x &&
+  b.x < a.x + a.width + CLEARANCE.x &&
+  a.y < b.y + b.height + CLEARANCE.y &&
+  b.y < a.y + a.height + CLEARANCE.y;
+
+const below = (rects: Rect[]): XYPosition => ({
+  x: Math.min(...rects.map((rect) => rect.x)),
+  y: Math.max(...rects.map((rect) => rect.y + rect.height)) + BELOW_GAP,
+});
+
+/** 0, 1, -1, 2, -2, …: rows below and above in turn, so things stacked around a node stay centred on it */
+const rowOffset = (row: number) => (row % 2 ? (row + 1) / 2 : -row / 2);
+
+/**
+ * Where the nodes to place go on the canvas (not relative to their containers: containers that grow to fit them
+ * move what's in them, but nothing moves on the canvas). They're among `nodes`, with their containers set.
+ * Everything else in `nodes` stays where it is.
+ */
+export const placeNodes = (nodes: Node[], toPlace: string[], links: Link[]): Map<string, XYPosition> => {
+  const working = new Map(nodes.map((node) => [node.id, node]));
+  const remaining = new Set(toPlace.filter((id) => working.has(id)));
+
+  const neighbours = new Map<string, { id: string; upstream: boolean }[]>();
+  const addNeighbour = (id: string, neighbour: { id: string; upstream: boolean }) =>
+    neighbours.set(id, [...(neighbours.get(id) ?? []), neighbour]);
+  for (const { source, target } of links) {
+    addNeighbour(source, { id: target, upstream: false });
+    addNeighbour(target, { id: source, upstream: true });
+  }
+
+  const depthOf = (id: string | undefined): number => {
+    const node = id ? working.get(id) : undefined;
+    return node ? 1 + depthOf(node.parentId) : 0;
+  };
+
+  /** The node, or the container it's in, that sits directly in a level (undefined for the canvas itself) */
+  const atLevel = (id: string, level: string | undefined) => {
+    let node = working.get(id);
+    while (node && node.parentId !== level) node = node.parentId ? working.get(node.parentId) : undefined;
+    return node;
+  };
+
+  /** The containers things are put in grow to fit them (innermost first), as they will on the canvas */
+  const growing = new Set<string>();
+  for (const id of remaining) {
+    for (let parentId = working.get(id)!.parentId; parentId; parentId = working.get(parentId)?.parentId) growing.add(parentId);
+  }
+  const fitContainers = () => {
+    const containers = [...growing].filter((id) => working.has(id)).sort((a, b) => depthOf(b) - depthOf(a));
+    for (const id of containers) {
+      const fit = fitGroup(
+        id,
+        [...working.values()].filter((node) => node.parentId !== id || !remaining.has(node.id))
+      );
+      if (!fit) continue;
+      const container = working.get(id)!;
+      // Growing up or left: what's in it moves the other way, so nothing moves on the canvas
+      if (fit.shift.x || fit.shift.y) {
+        for (const child of working.values()) {
+          if (child.parentId !== id) continue;
+          working.set(child.id, {
+            ...child,
+            position: { x: child.position.x + fit.shift.x, y: child.position.y + fit.shift.y },
+          });
+        }
+      }
+      working.set(id, {
+        ...container,
+        position: { x: container.position.x - fit.shift.x, y: container.position.y - fit.shift.y },
+        width: fit.width,
+        height: fit.height,
+      });
+    }
+  };
+
+  // Innermost containers first, then outwards to the canvas
+  const levels = [...new Set([...remaining].map((id) => working.get(id)!.parentId))].sort((a, b) => depthOf(b) - depthOf(a));
+
+  for (const level of levels) {
+    fitContainers();
+    const parent = level ? working.get(level) : undefined;
+    const origin = parent ? getAbsolutePosition(parent, working) : { x: 0, y: 0 };
+    // Inside a container: clear of its header, so it grows down rather than up
+    const start = parent ? { x: GROUP_PADDING.left, y: GROUP_PADDING.top } : { x: 0, y: 0 };
+    const todo = [...remaining].filter((id) => working.get(id)!.parentId === level);
+    // Things connected to nothing: a row below what was there, each to the right of what's been placed so far
+    let row: { y: number; length: number } | undefined;
+    const placedHere: Rect[] = [];
+    const obstacles = () =>
+      [...working.values()].filter((node) => node.parentId === level && !remaining.has(node.id)).map(rectOf);
+
+    /** What a node connects to that's already placed: the node itself, or the container it's in, at this level */
+    const anchorsOf = (id: string): Anchor[] =>
+      (neighbours.get(id) ?? []).flatMap(({ id: other, upstream }) => {
+        const shown = atLevel(other, level);
+        if (!shown || shown.id === id || remaining.has(shown.id)) return [];
+        const node = working.get(other)!;
+        // Lined up with the node itself, even when it's inside a container
+        const centerY = getAbsolutePosition(node, working).y + sizeOf(node).height / 2 - origin.y;
+        return [{ rect: rectOf(shown), centerY, upstream }];
+      });
+
+    /** Nothing placed to start from: the first one with nothing sending to it, so the flow grows left to right */
+    const startOf = (ids: string[]) =>
+      ids.find(
+        (id) =>
+          !(neighbours.get(id) ?? []).some(({ id: other, upstream }) => {
+            const shown = atLevel(other, level);
+            return upstream && shown && shown.id !== id && ids.includes(shown.id);
+          })
+      ) ?? ids[0];
+
+    const findSpot = (from: XYPosition, size: { width: number; height: number }, direction: 1 | -1): XYPosition => {
+      const rects = obstacles();
+      for (let column = 0; column < MAX_COLUMNS; column++) {
+        const x = from.x + direction * column * (size.width + GAP.x);
+        for (let row = 0; row < MAX_ROWS * 2; row++) {
+          const spot = { x, y: from.y + rowOffset(row) * (size.height + GAP.y) };
+          if (parent && spot.y < GROUP_PADDING.top) continue;
+          if (!rects.some((rect) => tooClose({ ...spot, ...size }, rect))) return spot;
+        }
+      }
+      return rects.length ? below(rects) : start;
+    };
+
+    while (todo.length > 0) {
+      const candidates = todo.map((id) => ({ id, anchors: anchorsOf(id) }));
+      const connected = candidates.reduce((best, candidate) =>
+        candidate.anchors.length > best.anchors.length ? candidate : best
+      );
+      const { id, anchors } = connected.anchors.length > 0 ? connected : { id: startOf(todo), anchors: [] };
+      const node = working.get(id)!;
+      const size = sizeOf(node);
+
+      let spot: XYPosition;
+      if (anchors.length > 0) {
+        const upstream = anchors.filter((anchor) => anchor.upstream);
+        const downstream = anchors.filter((anchor) => !anchor.upstream);
+        const x = upstream.length
+          ? Math.max(...upstream.map(({ rect }) => rect.x + rect.width)) + GAP.x
+          : Math.min(...downstream.map(({ rect }) => rect.x)) - GAP.x - size.width;
+        const centerY = anchors.reduce((sum, anchor) => sum + anchor.centerY, 0) / anchors.length;
+        spot = findSpot({ x, y: centerY - size.height / 2 }, size, upstream.length ? 1 : -1);
+      } else {
+        const rects = obstacles();
+        if (!row || row.length === ROW_LENGTH) {
+          spot = findSpot(rects.length ? below(rects) : start, size, 1);
+          row = { y: spot.y, length: 1 };
+        } else {
+          spot = findSpot({ x: Math.max(...placedHere.map((rect) => rect.x + rect.width)) + GAP.x, y: row.y }, size, 1);
+          row.length++;
+        }
+      }
+
+      const position = { x: Math.round(spot.x), y: Math.round(spot.y) };
+      working.set(id, { ...node, position });
+      placedHere.push({ ...position, ...size });
+      remaining.delete(id);
+      todo.splice(todo.indexOf(id), 1);
+    }
+  }
+
+  fitContainers();
+  return new Map(toPlace.filter((id) => working.has(id)).map((id) => [id, getAbsolutePosition(working.get(id)!, working)]));
+};