@eventcatalog/core 5.0.0-beta.1 → 5.0.0-beta.11

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

@@ -0,0 +1,171 @@
+import type { Edge, Node } from '@xyflow/react';
+import type { CatalogRelation, CatalogResource } from './catalog-resources';
+import { buildNode } from './canvas-doc';
+import { createEdge } from './edges';
+import { layoutGraph, withGroupSizes } from './layout';
+import { GROUP_TYPES, isGroupType } from './node-types';
+
+/**
+ * Catalog resources on a canvas: the node for a resource, its connections to related resources already there,
+ * and domains and systems as containers with what they hold in the catalog.
+ */
+
+export type CatalogLink = { key: string; url: string; version: string };
+
+/** The node data for a resource, tagged with the catalog resource it came from */
+export const catalogNodeData = (resource: CatalogResource) => ({
+  ...resource.node.data,
+  catalog: { key: resource.key, url: resource.url, version: resource.version } satisfies CatalogLink,
+});
+
+export const getCatalogLink = (node: Pick<Node, 'data'>) => node.data?.catalog as CatalogLink | undefined;
+
+export const indexRelations = (relations: CatalogRelation[]) => {
+  const byKey = new Map<string, CatalogRelation[]>();
+  for (const relation of relations) {
+    for (const key of [relation.source, relation.target]) byKey.set(key, [...(byKey.get(key) ?? []), relation]);
+  }
+  return byKey;
+};
+
+/**
+ * Edges from a newly dropped resource to the related resources already on the canvas. A container doesn't get
+ * "contains" edges: what it contains sits inside it.
+ */
+export const getRelatedEdges = (
+  resource: CatalogResource,
+  nodeId: string,
+  existing: Node[],
+  relationsByKey: Map<string, CatalogRelation[]>,
+  nodeType = resource.node.type
+): Edge[] => {
+  const edges: Edge[] = [];
+  for (const relation of relationsByKey.get(resource.key) ?? []) {
+    const isSource = relation.source === resource.key;
+    const otherKey = isSource ? relation.target : relation.source;
+
+    for (const other of existing.filter((node) => getCatalogLink(node)?.key === otherKey)) {
+      if (relation.label === 'contains' && (isGroupType(nodeType) || isGroupType(other.type))) continue;
+      const [source, target] = isSource ? [{ id: nodeId, type: nodeType }, other] : [other, { id: nodeId, type: nodeType }];
+      const edge = createEdge(
+        { source: source.id, target: target.id, sourceHandle: null, targetHandle: null },
+        source.type,
+        target.type
+      );
+      edges.push(relation.label ? { ...edge, label: relation.label } : edge);
+    }
+  }
+  return edges;
+};
+
+// ---- Domains and systems as containers ----
+
+export const canBeContainer = (resource: CatalogResource) =>
+  resource.collection === 'domains' || resource.collection === 'systems';
+
+export const containerTypeFor = (resource: CatalogResource) =>
+  resource.collection === 'domains' ? GROUP_TYPES.domain : GROUP_TYPES.system;
+
+/** A container's data: the domain or system it stands for, and where it is in the catalog */
+export const catalogGroupData = (resource: CatalogResource) => ({
+  [resource.collection === 'domains' ? 'domain' : 'system']: {
+    id: resource.id,
+    name: resource.name,
+    version: resource.version,
+    summary: resource.summary,
+  },
+  catalog: { key: resource.key, url: resource.url, version: resource.version } satisfies CatalogLink,
+});
+
+/** What a domain or system contains in the catalog: a domain's systems and services, a system's services */
+export const getContents = (
+  resource: CatalogResource,
+  catalog: { resourcesByKey: Map<string, CatalogResource>; relationsByKey: Map<string, CatalogRelation[]> }
+) =>
+  (catalog.relationsByKey.get(resource.key) ?? [])
+    .filter((relation) => relation.source === resource.key && relation.label === 'contains')
+    .map((relation) => catalog.resourcesByKey.get(relation.target))
+    .filter((child): child is CatalogResource => !!child);
+
+/** A domain or system as an (empty) container, centred on a point */
+export const buildContainer = (resource: CatalogResource, center: { x: number; y: number }): Node =>
+  buildNode(containerTypeFor(resource), catalogGroupData(resource), center);
+
+/**
+ * A domain or system as a container with everything it holds in the catalog: its systems (as containers too)
+ * and services, and the messages and data stores of those services, so every level of detail (L1 to L3) has
+ * something to show. Laid out with the visualiser's layout and centred on a point, with the connections between
+ * them and to related resources already on the canvas. Resources already on the canvas aren't added again.
+ */
+export const buildContainerWithContents = async (
+  resource: CatalogResource,
+  center: { x: number; y: number },
+  catalog: { resourcesByKey: Map<string, CatalogResource>; relationsByKey: Map<string, CatalogRelation[]> },
+  existing: Node[]
+): Promise<{ nodes: Node[]; edges: Edge[] }> => {
+  const onCanvas = new Set(existing.map((node) => getCatalogLink(node)?.key).filter(Boolean));
+  const root = buildContainer(resource, { x: 0, y: 0 });
+  const nodes: Node[] = [root];
+  const added = (key: string) => onCanvas.has(key) || nodes.some((node) => getCatalogLink(node)?.key === key);
+  const services: { resource: CatalogResource; parentId: string }[] = [];
+
+  // Its systems (as containers, with their services) and services
+  const fill = (parent: CatalogResource, parentId: string) => {
+    for (const child of getContents(parent, catalog)) {
+      if (added(child.key)) continue;
+      if (canBeContainer(child)) {
+        const container = { ...buildContainer(child, { x: 0, y: 0 }), parentId };
+        nodes.push(container);
+        fill(child, container.id);
+      } else {
+        nodes.push({ ...buildNode(child.node.type, catalogNodeData(child), { x: 0, y: 0 }), parentId });
+        if (child.collection === 'services') services.push({ resource: child, parentId });
+      }
+    }
+  };
+  fill(resource, root.id);
+
+  // The messages its services send and receive (in the domain or system dropped), and their data stores (next to them)
+  for (const service of services) {
+    for (const relation of catalog.relationsByKey.get(service.resource.key) ?? []) {
+      if (relation.label === 'contains') continue;
+      const other = catalog.resourcesByKey.get(relation.source === service.resource.key ? relation.target : relation.source);
+      if (!other || added(other.key) || canBeContainer(other) || other.collection === 'services') continue;
+      const parentId = other.collection === 'containers' ? service.parentId : root.id;
+      nodes.push({ ...buildNode(other.node.type, catalogNodeData(other), { x: 0, y: 0 }), parentId });
+    }
+  }
+
+  if (nodes.length === 1) return { nodes: [buildContainer(resource, center)], edges: [] };
+
+  // Connections between them, and to related resources already on the canvas
+  const inside: Edge[] = [];
+  const outside: Edge[] = [];
+  const placed = [...existing];
+  for (const node of nodes) {
+    const link = getCatalogLink(node);
+    const related = link && catalog.resourcesByKey.get(link.key);
+    if (related) {
+      for (const edge of getRelatedEdges(related, node.id, placed, catalog.relationsByKey, node.type)) {
+        (existing.some((other) => other.id === edge.source || other.id === edge.target) ? outside : inside).push(edge);
+      }
+    }
+    placed.push(node);
+  }
+
+  // Laid out with its connections; containers are sized to fit what's in them
+  const laidOut = withGroupSizes((await layoutGraph(nodes, inside)).nodes);
+  const top = laidOut.find((node) => node.id === root.id)!;
+  const offset = { x: center.x - (top.width ?? 0) / 2 - top.position.x, y: center.y - (top.height ?? 0) / 2 - top.position.y };
+  return {
+    nodes: laidOut.map((node) => {
+      const original = nodes.find((candidate) => candidate.id === node.id)!;
+      return {
+        ...original,
+        position: node.parentId ? node.position : { x: node.position.x + offset.x, y: node.position.y + offset.y },
+        ...(isGroupType(node.type) && { width: node.width, height: node.height }),
+      };
+    }),
+    edges: [...inside, ...outside],
+  };
+};

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

@@ -0,0 +1,97 @@
+import type { Edge, Node, XYPosition } from '@xyflow/react';
+import { shortId, toSharedNode } from './canvas-doc';
+import { findGroupAtPoint, getAbsolutePosition, sizeOf, sortByHierarchy, withDescendants } from './grouping';
+import { canGoInContainer } from './node-types';
+
+/**
+ * Copying and pasting nodes, within a canvas or between canvases (through the system clipboard). What's copied is
+ * the selected nodes, everything inside selected containers, and the connections between them. Comments aren't.
+ */
+
+/** The clipboard type Studio reads first (other apps get a plain text list of what was copied) */
+export const CLIPBOARD_TYPE = 'application/x-eventcatalog-studio+json';
+const MARKER = 'eventcatalog-studio/nodes@1';
+
+export type ClipboardContent = { marker: typeof MARKER; nodes: Node[]; edges: Edge[] };
+
+/** What's copied when these nodes are selected, or null if there's nothing to copy */
+export const copyNodes = (nodes: Node[], edges: Edge[], selectedIds: string[]): ClipboardContent | null => {
+  if (selectedIds.length === 0) return null;
+  const lookup = new Map(nodes.map((node) => [node.id, node]));
+  const ids = withDescendants(selectedIds, nodes);
+  const copied = sortByHierarchy(nodes.filter((node) => ids.has(node.id))).map((node) => {
+    const shared = toSharedNode(node);
+    // Copied without its container: where it is on the canvas
+    if (shared.parentId && !ids.has(shared.parentId)) {
+      const { parentId: _, ...rest } = shared;
+      return { ...rest, position: getAbsolutePosition(node, lookup) };
+    }
+    return shared;
+  });
+  return {
+    marker: MARKER,
+    nodes: copied,
+    edges: edges.filter((edge) => ids.has(edge.source) && ids.has(edge.target)).map(({ selected: _, ...edge }) => edge),
+  };
+};
+
+/** Copied content read back from the clipboard, if it's Studio's */
+export const readClipboard = (text: string | undefined): ClipboardContent | null => {
+  if (!text) return null;
+  try {
+    const content = JSON.parse(text) as Partial<ClipboardContent>;
+    return content.marker === MARKER && Array.isArray(content.nodes) && Array.isArray(content.edges)
+      ? (content as ClipboardContent)
+      : null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Copies of the content to add to the canvas, with new ids: centred on a point (e.g. the pointer), or moved by an
+ * offset from where they were copied. Copies that land in a container on the canvas go inside it.
+ */
+export const pasteNodes = (
+  content: ClipboardContent,
+  existing: Node[],
+  place: { at: XYPosition } | { offset: XYPosition }
+): { nodes: Node[]; edges: Edge[] } => {
+  const ids = new Map(content.nodes.map((node) => [node.id, `${node.type ?? 'node'}-${shortId()}`]));
+  const roots = content.nodes.filter((node) => !node.parentId);
+  const offset = 'offset' in place ? place.offset : offsetToCentre(roots, place.at);
+
+  const lookup = new Map(existing.map((node) => [node.id, node]));
+  const nodes = content.nodes.map((node): Node => {
+    const id = ids.get(node.id)!;
+    if (node.parentId) return { ...node, id, parentId: ids.get(node.parentId) };
+    const position = { x: node.position.x + offset.x, y: node.position.y + offset.y };
+    const { width, height } = sizeOf(node);
+    const container = canGoInContainer(node.type)
+      ? findGroupAtPoint({ x: position.x + width / 2, y: position.y + height / 2 }, existing)
+      : undefined;
+    if (!container) return { ...node, id, position };
+    const origin = getAbsolutePosition(container, lookup);
+    return { ...node, id, parentId: container.id, position: { x: position.x - origin.x, y: position.y - origin.y } };
+  });
+
+  return {
+    nodes,
+    edges: content.edges.map((edge) => ({
+      ...edge,
+      id: `edge-${shortId()}`,
+      source: ids.get(edge.source)!,
+      target: ids.get(edge.target)!,
+    })),
+  };
+};
+
+/** How far to move nodes so the middle of them is at a point */
+const offsetToCentre = (roots: Node[], at: XYPosition): XYPosition => {
+  if (roots.length === 0) return { x: 0, y: 0 };
+  const left = Math.min(...roots.map((node) => node.position.x));
+  const top = Math.min(...roots.map((node) => node.position.y));
+  const right = Math.max(...roots.map((node) => node.position.x + sizeOf(node).width));
+  const bottom = Math.max(...roots.map((node) => node.position.y + sizeOf(node).height));
+  return { x: at.x - (left + right) / 2, y: at.y - (top + bottom) / 2 };
+};

package/eventcatalog/src/features/studio/components/CanvasControls.tsx

@@ -0,0 +1,154 @@
+import { memo, type ReactNode } from 'react';
+import { useReactFlow, useStore } from '@xyflow/react';
+import { Maximize, MessageCircle, Redo, SendToBack, StickyNote, Undo, ZoomIn, ZoomOut } from 'lucide-react';
+import { LEVELS, type Level } from '../levels';
+
+// The canvas's bottom bar: layout, view, levels of detail, undo, comments and notes
+
+export const FIT_VIEW_OPTIONS = { padding: { top: '80px', right: '60px', bottom: '100px', left: '60px' } } as const;
+
+function ControlButton({
+  label,
+  onClick,
+  disabled,
+  active,
+  children,
+}: {
+  label: string;
+  onClick: () => void;
+  disabled?: boolean;
+  active?: boolean;
+  children: ReactNode;
+}) {
+  return (
+    <button
+      title={label}
+      aria-label={label}
+      onClick={onClick}
+      disabled={disabled}
+      className={`rounded-full p-2 transition-colors ${
+        disabled
+          ? 'cursor-not-allowed opacity-40'
+          : active
+            ? 'bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-accent))]'
+            : 'text-[rgb(var(--ec-icon-color))] hover:bg-[rgb(var(--ec-page-border)/0.5)] hover:text-[rgb(var(--ec-icon-hover))]'
+      }`}
+    >
+      {children}
+    </button>
+  );
+}
+
+/** Isolated, so the bar only re-renders when the zoom changes (not on every pan) */
+function ZoomLevel() {
+  const zoom = useStore((state) => Math.round(state.transform[2] * 100));
+  return <div className="w-12 text-center text-xs font-medium tabular-nums text-[rgb(var(--ec-page-text-muted))]">{zoom}%</div>;
+}
+
+const Divider = () => <div className="mx-1 h-6 w-px bg-[rgb(var(--ec-page-border))]" />;
+
+function LevelSwitch({
+  level,
+  onChange,
+  unavailable,
+}: {
+  level: Level;
+  onChange: (level: Level) => void;
+  unavailable: Partial<Record<Level, string | undefined>>;
+}) {
+  return (
+    <div role="group" aria-label="Level of detail" className="flex items-center gap-0.5">
+      {LEVELS.map(({ level: value, description }) => {
+        const reason = unavailable[value];
+        const active = value === level;
+        return (
+          <button
+            key={value}
+            title={`Level ${value}: ${description}${reason ? `. ${reason}` : ''}`}
+            // Stays focusable when unavailable, so its title can say why
+            aria-disabled={!!reason}
+            aria-pressed={active}
+            onClick={() => !reason && onChange(value)}
+            className={`h-8 min-w-8 rounded-full px-2 text-xs font-semibold tabular-nums transition-colors ${
+              reason
+                ? 'cursor-not-allowed opacity-40'
+                : active
+                  ? 'bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-accent))]'
+                  : 'text-[rgb(var(--ec-page-text-muted))] hover:bg-[rgb(var(--ec-page-border)/0.5)]'
+            }`}
+          >
+            L{value}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+export default memo(function CanvasControls({
+  level,
+  onLevelChange,
+  unavailableLevels,
+  editable,
+  onReorder,
+  canUndo,
+  canRedo,
+  onUndo,
+  onRedo,
+  commentMode,
+  onToggleCommentMode,
+  onAddNote,
+}: {
+  level: Level;
+  onLevelChange: (level: Level) => void;
+  unavailableLevels: Partial<Record<Level, string | undefined>>;
+  /** L1 and L2 are read only views of the canvas */
+  editable: boolean;
+  onReorder: () => void;
+  canUndo: boolean;
+  canRedo: boolean;
+  onUndo: () => void;
+  onRedo: () => void;
+  commentMode: boolean;
+  onToggleCommentMode: () => void;
+  onAddNote: () => void;
+}) {
+  const { fitView, zoomIn, zoomOut } = useReactFlow();
+
+  return (
+    <div className="absolute bottom-4 left-1/2 z-10 -translate-x-1/2">
+      <div className="flex items-center gap-1 rounded-full border px-2 py-1 shadow-lg bg-[rgb(var(--ec-card-bg))] border-[rgb(var(--ec-page-border))]">
+        <ControlButton label="Reorder diagram (the visualiser's layout)" onClick={onReorder} disabled={!editable}>
+          <SendToBack className="h-4 w-4" />
+        </ControlButton>
+        <ControlButton label="Fit view" onClick={() => void fitView({ ...FIT_VIEW_OPTIONS, duration: 500 })}>
+          <Maximize className="h-4 w-4" />
+        </ControlButton>
+        <ControlButton label="Zoom out" onClick={() => void zoomOut({ duration: 200 })}>
+          <ZoomOut className="h-4 w-4" />
+        </ControlButton>
+        <ZoomLevel />
+        <ControlButton label="Zoom in" onClick={() => void zoomIn({ duration: 200 })}>
+          <ZoomIn className="h-4 w-4" />
+        </ControlButton>
+        <Divider />
+        <LevelSwitch level={level} onChange={onLevelChange} unavailable={unavailableLevels} />
+        <Divider />
+        <ControlButton label="Undo (⌘Z)" onClick={onUndo} disabled={!canUndo}>
+          <Undo className="h-4 w-4" />
+        </ControlButton>
+        <ControlButton label="Redo (⇧⌘Z)" onClick={onRedo} disabled={!canRedo}>
+          <Redo className="h-4 w-4" />
+        </ControlButton>
+        <Divider />
+        <ControlButton label="Comment (C)" onClick={onToggleCommentMode} active={commentMode} disabled={!editable}>
+          <MessageCircle className="h-4 w-4" />
+        </ControlButton>
+        {/* Notes can be added on every level, and are shown on the level they're added on */}
+        <ControlButton label={editable ? 'Add sticky note' : `Add sticky note to L${level}`} onClick={onAddNote}>
+          <StickyNote className="h-4 w-4 text-yellow-500" />
+        </ControlButton>
+      </div>
+    </div>
+  );
+});