@eventcatalog/core 5.0.0-beta.3 → 5.0.0-beta.30

package/eventcatalog/src/features/studio/components/StudioNotice.astro

@@ -0,0 +1,24 @@
+---
+/** A message in place of Studio (e.g. a deleted canvas, or Studio not being available), with a way back */
+type Props = { title: string; message: string; href?: string; linkText?: string };
+const { title, message, href, linkText } = Astro.props;
+---
+
+<div class="flex h-full items-center justify-center p-4">
+  <div
+    class="max-w-md space-y-2 rounded-xl border p-5 text-center shadow-xl bg-[rgb(var(--ec-card-bg))] border-[rgb(var(--ec-page-border))]"
+  >
+    <h1 class="text-base font-semibold text-[rgb(var(--ec-page-text))]">{title}</h1>
+    <p class="text-sm text-[rgb(var(--ec-page-text-muted))]">{message}</p>
+    {
+      href && linkText && (
+        <a
+          href={href}
+          class="mt-2 inline-flex rounded-lg px-4 py-2 text-sm font-medium bg-[rgb(var(--ec-button-bg))] text-[rgb(var(--ec-button-text))] hover:bg-[rgb(var(--ec-button-bg-hover))]"
+        >
+          {linkText}
+        </a>
+      )
+    }
+  </div>
+</div>

package/eventcatalog/src/features/studio/document-name.ts

@@ -0,0 +1,7 @@
+// Canvases' documents on the collaboration server are named `design:<canvasId>` (scripts and peers join by it)
+const DOCUMENT_PREFIX = 'design:';
+export const canvasDocumentName = (canvasId: string) => `${DOCUMENT_PREFIX}${canvasId}`;
+export const canvasIdFromDocumentName = (name: string) =>
+  name.startsWith(DOCUMENT_PREFIX) ? name.slice(DOCUMENT_PREFIX.length) : undefined;
+/** Why the collaboration server refuses a canvas that was deleted (told to anyone who still has it open) */
+export const CANVAS_DELETED_REASON = 'canvas-deleted';

package/eventcatalog/src/features/studio/from-visualiser.ts

@@ -0,0 +1,138 @@
+import type { Edge, Node } from '@xyflow/react';
+import type { VisualiserSnapshot } from '@eventcatalog/visualiser';
+import { getNodeCatalogResource } from '@utils/node-graphs/node-resource';
+import type { DiagramLevelsSpec, NewCanvasEdges, NodeSpecs } from './canvas-actions';
+import { DEFAULT_NODE_SIZE, isCatalogCollection, isGroupType } from '@eventcatalog/visualiser/studio';
+
+/**
+ * A canvas started from a diagram (the visualiser's "Open in Studio"): the catalog resources and actors it shows,
+ * where they are on it (the same top-left corners), in the domains and systems they're shown in, and the
+ * connections between them, drawn along the same routes. Other nodes (e.g. flow steps, users, entities) are left
+ * out, with their connections. Its levels 1 and 2 come as the diagram shows them, for Studio to show them the same.
+ */
+
+// Actors (people and roles) aren't catalog resources: they go on the canvas as Studio's actors, by the name shown
+const ACTOR_TYPES = new Set(['context-actor', 'actor']);
+const actorNameOf = (node: VisualiserSnapshot['nodes'][number]) =>
+  node.type && ACTOR_TYPES.has(node.type) && typeof node.data.name === 'string' ? node.data.name : undefined;
+
+export const canvasFromVisualiser = (
+  snapshot: VisualiserSnapshot
+): { nodes: NodeSpecs; edges: NewCanvasEdges; levels: DiagramLevelsSpec } => {
+  const byId = new Map(snapshot.nodes.map((node) => [node.id, node]));
+  const depthOf = (node: VisualiserSnapshot['nodes'][number]): number => {
+    const parent = node.parentId ? byId.get(node.parentId) : undefined;
+    return parent ? 1 + depthOf(parent) : 0;
+  };
+
+  const containers = new Set<string>();
+  const parentOf = new Map<string, string>();
+  const nodes = [...snapshot.nodes]
+    // Containers before what's in them (specs refer to containers given before them)
+    .sort((a, b) => depthOf(a) - depthOf(b))
+    .flatMap((node) => {
+      const resource = getNodeCatalogResource(node);
+      const fromCatalog =
+        resource && isCatalogCollection(resource.collection) ? { collection: resource.collection, id: resource.id } : undefined;
+      const actorName = actorNameOf(node);
+      if (!fromCatalog && !actorName) return [];
+      // Domains and systems shown as boxes are containers on the canvas
+      const container = isGroupType(node.type);
+      // In the innermost container shown that's on the canvas
+      let inside: string | undefined;
+      for (let parent = node.parentId; parent && !inside; parent = byId.get(parent)?.parentId) {
+        if (containers.has(parent)) inside = parent;
+      }
+      if (container) containers.add(node.id);
+      if (inside) parentOf.set(node.id, inside);
+      // Where it is: its top-left corner, as cards are put by their centre at the size they're created at (and
+      // render at the size they need from there), and containers at their size
+      const left = node.center.x - node.width / 2;
+      const top = node.center.y - node.height / 2;
+      return [
+        {
+          ref: node.id,
+          ...(fromCatalog ? { resource: fromCatalog } : { type: 'actor', name: actorName }),
+          ...(container
+            ? { x: node.center.x, y: node.center.y, container: true, width: node.width, height: node.height }
+            : { x: left + DEFAULT_NODE_SIZE.width / 2, y: top + DEFAULT_NODE_SIZE.height / 2 }),
+          ...(inside && { inside }),
+        },
+      ];
+    });
+
+  // Connections between nodes on the canvas, not between a container and what's in it (it holds it instead)
+  const onCanvas = new Set(nodes.map((node) => node.ref));
+  const isInside = (nodeId: string, containerId: string) => {
+    for (let parent = parentOf.get(nodeId); parent; parent = parentOf.get(parent)) if (parent === containerId) return true;
+    return false;
+  };
+  const edges = snapshot.edges
+    .filter(({ source, target }) => onCanvas.has(source) && onCanvas.has(target) && source !== target)
+    .filter(({ source, target }) => !isInside(source, target) && !isInside(target, source))
+    .map(({ source, target, label, route }) => ({ from: source, to: target, ...(label && { label }), ...(route && { route }) }));
+
+  const levels = {
+    ...(snapshot.levels[1] && { 1: levelFromVisualiser(snapshot.levels[1], nodes) }),
+    ...(snapshot.levels[2] && { 2: levelFromVisualiser(snapshot.levels[2], nodes) }),
+    ...(Object.keys(snapshot.unavailableLevels).length > 0 && { unavailable: snapshot.unavailableLevels }),
+  };
+  return { nodes, edges, levels };
+};
+
+const sameResource = (a?: { collection: string; id: string }, b?: { collection: string; id: string }) =>
+  !!a && !!b && a.collection === b.collection && a.id === b.id;
+const sizeOf = (node: Node) => ({
+  width: typeof node.style?.width === 'number' ? node.style.width : (node.width ?? node.measured?.width),
+  height: typeof node.style?.height === 'number' ? node.style.height : (node.height ?? node.measured?.height),
+});
+
+/**
+ * One of the diagram's levels, as it shows it: each node stands for the canvas node with the same id (on level 3),
+ * or the same catalog resource (e.g. a system shown as a card on level 1 and as a container on level 3), so moving
+ * between levels glides from one to the other. Nodes only on the level keep their own id.
+ */
+const levelFromVisualiser = (level: { nodes: Node[]; edges: Edge[] }, specs: NodeSpecs) => {
+  const used = new Set<string>();
+  const refs = new Map<string, string>();
+  for (const node of level.nodes) {
+    const resource = getNodeCatalogResource(node);
+    const ref = [
+      specs.find((spec) => spec.ref === node.id)?.ref,
+      specs.find((spec) => sameResource(spec.resource, resource))?.ref,
+    ].find((candidate) => candidate && !used.has(candidate));
+    refs.set(node.id, ref ?? node.id);
+    used.add(ref ?? node.id);
+  }
+  return {
+    nodes: level.nodes.map((node) => {
+      const { width, height } = sizeOf(node);
+      // The diagram marks the resource whose page it's on ("Viewing"): a canvas isn't on one
+      const { isFocused: _, ...data } = node.data as Record<string, unknown>;
+      return {
+        ref: refs.get(node.id)!,
+        type: node.type ?? 'default',
+        data,
+        ...(node.parentId && refs.has(node.parentId) && { parent: refs.get(node.parentId) }),
+        x: node.position.x,
+        y: node.position.y,
+        ...(isGroupType(node.type) && width && height && { width, height }),
+      };
+    }),
+    edges: level.edges.flatMap((edge) => {
+      const [from, to] = [refs.get(edge.source), refs.get(edge.target)];
+      if (!from || !to) return [];
+      return [
+        {
+          from,
+          to,
+          ...(typeof edge.label === 'string' && { label: edge.label }),
+          ...(edge.type && { type: edge.type }),
+          ...(edge.style && { style: edge.style as Record<string, unknown> }),
+          ...(edge.markerEnd && { markerEnd: edge.markerEnd }),
+          ...(edge.data && { data: edge.data }),
+        },
+      ];
+    }),
+  };
+};

package/eventcatalog/src/features/studio/hooks/presence-sender.ts

@@ -0,0 +1,63 @@
+import type { Awareness } from 'y-protocols/awareness';
+
+/** About 30 times a second, like Excalidraw and tldraw: smooth for others, without a message on every mousemove */
+export const PRESENCE_INTERVAL_MS = 33;
+/**
+ * Once a second when nobody else is on the canvas (people or agents), as tldraw does: nobody sees it, and the
+ * collaboration server sends every one back. Someone arriving gets what's waiting straight away.
+ */
+export const ALONE_INTERVAL_MS = 1000;
+
+export type PresenceSender = {
+  /** Share these fields of our presence: straight away if nothing was sent lately, otherwise with the next send */
+  send: (fields: Record<string, unknown>) => void;
+  /** Send anything waiting now (e.g. a node dropped, so the drop isn't behind the drag) */
+  flush: () => void;
+  destroy: () => void;
+};
+
+/**
+ * Our presence (pointer, nodes being dragged, selection, view), sent to everyone at most every interval. Awareness
+ * sends the whole state on every change, so fields changed together (the pointer and the node it drags) go in one
+ * message, and the latest value always goes out (the pointer stops where it really stopped).
+ */
+export function createPresenceSender(
+  awareness: Awareness,
+  intervalMs = PRESENCE_INTERVAL_MS,
+  aloneIntervalMs = ALONE_INTERVAL_MS
+): PresenceSender {
+  let pending: Record<string, unknown> | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let lastSent = -Infinity;
+  const alone = () => awareness.getStates().size <= 1;
+
+  const flush = () => {
+    clearTimeout(timer);
+    timer = undefined;
+    if (!pending) return;
+    const fields = pending;
+    pending = undefined;
+    lastSent = performance.now();
+    awareness.setLocalState({ ...awareness.getLocalState(), ...fields });
+  };
+  // Someone arrived: they get what's waiting now, not at the next (slower) send
+  const onChange = ({ added }: { added: number[] }) => {
+    if (pending && added.some((id) => id !== awareness.clientID)) flush();
+  };
+  awareness.on('change', onChange);
+
+  return {
+    send: (fields) => {
+      pending = { ...pending, ...fields };
+      if (timer) return;
+      const interval = alone() ? aloneIntervalMs : intervalMs;
+      timer = setTimeout(flush, Math.max(0, interval - (performance.now() - lastSent)));
+    },
+    flush,
+    destroy: () => {
+      clearTimeout(timer);
+      pending = undefined;
+      awareness.off('change', onChange);
+    },
+  };
+}

package/eventcatalog/src/features/studio/hooks/presence-store.ts

@@ -0,0 +1,119 @@
+import { useSyncExternalStore } from 'react';
+import type { XYPosition } from '@xyflow/react';
+import type { Awareness } from 'y-protocols/awareness';
+
+export type Peer = {
+  clientId: number;
+  name: string;
+  color: string;
+  /** A picture from their sign-in provider (SSO), shown over their initials */
+  picture?: string;
+  /** An AI agent (joined over MCP, or working through this tab with WebMCP), rather than a person */
+  agent?: boolean;
+  /** What an agent is doing, e.g. "Adding OrderService" */
+  activity?: string;
+  pointer: XYPosition | null;
+  selection: string[];
+  /** What they're looking at: the canvas position in the middle of their screen, and their zoom */
+  viewport?: { x: number; y: number; zoom: number };
+  /** Where a connection they're dragging starts (agents show theirs) */
+  connecting?: XYPosition | null;
+};
+
+type Listener = () => void;
+
+/**
+ * Who's on a canvas and what they're doing (pointers, selections, views), from Yjs awareness, kept out of React
+ * state: only the components that draw presence subscribe, so a pointer moving doesn't re-render the canvas.
+ * Our own pointer, selection and view are sent to others but don't notify here (nothing here draws them).
+ */
+export type PresenceStore = {
+  subscribe: (listener: Listener) => () => void;
+  /** Everyone, including us and an agent working through this tab. Changes whenever anyone does anything. */
+  getPeers: () => Peer[];
+  /**
+   * Everyone, for lists of who's here: changes only when people join, leave or rename, or agents change what
+   * they're doing (pointers and views in it may be out of date: read getPeers() for those)
+   */
+  getPeople: () => Peer[];
+  /** Show an agent working through this tab (WebMCP), which only this tab sees */
+  setLocalAgent: (agent: Peer | null) => void;
+  destroy: () => void;
+};
+
+const EMPTY: Peer[] = [];
+
+const toPeers = (awareness: Awareness): Peer[] => {
+  const peers: Peer[] = [];
+  awareness.getStates().forEach((state, clientId) => {
+    if (!state.user) return;
+    peers.push({
+      clientId,
+      ...state.user,
+      activity: state.activity,
+      pointer: state.pointer ?? null,
+      selection: state.selection ?? [],
+      viewport: state.viewport,
+      connecting: state.connecting,
+    });
+  });
+  return peers;
+};
+
+// What getPeople() changes on: who people are, what agents are doing, and whether they're on the canvas (a pointer)
+const identity = (peer: Peer) =>
+  [peer.clientId, peer.name, peer.color, peer.picture ?? '', peer.agent ? 1 : 0, peer.activity ?? '', peer.pointer ? 1 : 0].join(
+    '|'
+  );
+
+export function createPresenceStore(awareness: Awareness): PresenceStore {
+  const listeners = new Set<Listener>();
+  let remote = toPeers(awareness);
+  let localAgent: Peer | null = null;
+  let peers = remote;
+  let people = remote;
+  let ownUser = JSON.stringify(awareness.getLocalState()?.user ?? null);
+
+  const update = () => {
+    peers = localAgent ? [...remote, localAgent] : remote;
+    const nextPeople = peers.length ? peers : EMPTY;
+    if (nextPeople.map(identity).join() !== people.map(identity).join()) people = nextPeople;
+    listeners.forEach((listener) => listener());
+  };
+
+  const onChange = ({ added, updated, removed }: { added: number[]; updated: number[]; removed: number[] }) => {
+    const others = [...added, ...updated, ...removed].some((id) => id !== awareness.clientID);
+    const user = JSON.stringify(awareness.getLocalState()?.user ?? null);
+    // Only our own pointer, selection or view changed: nothing shown here changed
+    if (!others && user === ownUser) return;
+    ownUser = user;
+    remote = toPeers(awareness);
+    update();
+  };
+  awareness.on('change', onChange);
+
+  return {
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    getPeers: () => peers,
+    getPeople: () => people,
+    setLocalAgent: (agent) => {
+      localAgent = agent;
+      update();
+    },
+    destroy: () => {
+      awareness.off('change', onChange);
+      listeners.clear();
+    },
+  };
+}
+
+const noStore = { subscribe: () => () => {}, getPeers: () => EMPTY, getPeople: () => EMPTY };
+
+/** Everyone on the canvas, re-rendering only when people join, leave, rename or start or stop working */
+export const usePeople = (store: PresenceStore | null) => {
+  const source = store ?? noStore;
+  return useSyncExternalStore(source.subscribe, source.getPeople);
+};