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

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

@@ -0,0 +1,152 @@
+import { getDomains } from '@utils/collections/domains';
+import { getSystems } from '@utils/collections/systems';
+import { getServices } from '@utils/collections/services';
+import { getEvents } from '@utils/collections/events';
+import { getCommands } from '@utils/collections/commands';
+import { getQueries } from '@utils/collections/queries';
+import { getChannels } from '@utils/collections/channels';
+import { getContainers } from '@utils/collections/containers';
+import { buildUrl } from '@utils/url-builder';
+
+/** A catalog resource that can be dropped onto the canvas (latest version only) */
+export type CatalogResource = {
+  /** `${collection}:${id}`, stored on the canvas node so relationships can be found */
+  key: string;
+  collection: string;
+  id: string;
+  version: string;
+  name: string;
+  summary?: string;
+  url: string;
+  node: { type: string; data: Record<string, unknown> };
+};
+
+/** A relationship between two catalog resources, by key */
+export type CatalogRelation = { source: string; target: string; label?: string };
+
+const keyOf = (collection: string, id: string) => `${collection}:${id}`;
+
+/** The collection helpers hydrate references (e.g. a domain's services) into entries; their types describe references */
+type HydratedEntry = { data: { id: string } };
+const isHydratedEntry = (value: unknown): value is HydratedEntry => {
+  if (typeof value !== 'object' || value === null || !('data' in value)) return false;
+  const { data } = value;
+  return typeof data === 'object' && data !== null && 'id' in data && typeof data.id === 'string';
+};
+const entries = (value: unknown): HydratedEntry[] => (Array.isArray(value) ? value.filter(isHydratedEntry) : []);
+const idsOf = (value: unknown) => entries(value).map((entry) => entry.data.id);
+
+const toResource = (
+  collection: string,
+  entry: { data: { id: string; version: string; name?: string; summary?: string } },
+  node: CatalogResource['node']
+): CatalogResource => ({
+  key: keyOf(collection, entry.data.id),
+  collection,
+  id: entry.data.id,
+  version: entry.data.version,
+  name: entry.data.name ?? entry.data.id,
+  summary: entry.data.summary,
+  url: buildUrl(`/docs/${collection}/${entry.data.id}/${entry.data.version}`),
+  node,
+});
+
+// Visualiser node data needs plain fields (not collection entries)
+const basics = ({ data }: { data: { id: string; version: string; name?: string; summary?: string } }) => ({
+  id: data.id,
+  version: data.version,
+  name: data.name ?? data.id,
+  summary: data.summary ?? '',
+});
+
+export const getCatalogResources = async (): Promise<{ resources: CatalogResource[]; relations: CatalogRelation[] }> => {
+  const [domains, systems, services, events, commands, queries, channels, containers] = await Promise.all([
+    getDomains({ getAllVersions: false }),
+    getSystems({ getAllVersions: false }),
+    getServices({ getAllVersions: false }),
+    getEvents({ getAllVersions: false, hydrateServices: false }),
+    getCommands({ getAllVersions: false, hydrateServices: false }),
+    getQueries({ getAllVersions: false, hydrateServices: false }),
+    getChannels({ getAllVersions: false }),
+    getContainers({ getAllVersions: false }),
+  ]);
+
+  const messages = [
+    ...events.map((entry) => ({ entry, collection: 'events', type: 'event' })),
+    ...commands.map((entry) => ({ entry, collection: 'commands', type: 'command' })),
+    ...queries.map((entry) => ({ entry, collection: 'queries', type: 'query' })),
+  ];
+  const messageCollection = new Map(messages.map(({ entry, collection }) => [entry.data.id, collection]));
+
+  const resources: CatalogResource[] = [
+    ...domains.map((domain) =>
+      toResource('domains', domain, {
+        type: 'context-domain',
+        data: {
+          mode: 'full',
+          navigable: false,
+          domain: basics(domain),
+          systemsCount: idsOf(domain.data.systems).length,
+          servicesCount: idsOf(domain.data.services).length,
+          entitiesCount: idsOf(domain.data.entities).length,
+        },
+      })
+    ),
+    ...systems.map((system) =>
+      toResource('systems', system, {
+        type: 'system',
+        data: {
+          mode: 'full',
+          navigable: false,
+          system: { ...basics(system), scope: system.data.scope },
+          servicesCount: idsOf(system.data.services).length,
+          containersCount: idsOf(system.data.containers).length,
+        },
+      })
+    ),
+    ...services.map((service) =>
+      toResource('services', service, { type: 'service', data: { mode: 'full', service: basics(service) } })
+    ),
+    ...messages.map(({ entry, collection, type }) =>
+      toResource(collection, entry, { type, data: { mode: 'full', message: basics(entry) } })
+    ),
+    ...channels.map((channel) =>
+      toResource('channels', channel, {
+        type: 'channel',
+        data: { mode: 'full', channel: { ...basics(channel), protocols: channel.data.protocols ?? [] } },
+      })
+    ),
+    ...containers.map((container) =>
+      toResource('containers', container, {
+        type: 'data',
+        data: { mode: 'full', data: { ...basics(container), container_type: container.data.container_type } },
+      })
+    ),
+  ];
+
+  const relations: CatalogRelation[] = [];
+  const relate = (source: string, target: string, label?: string) => relations.push({ source, target, label });
+
+  for (const domain of domains) {
+    for (const id of idsOf(domain.data.systems)) relate(keyOf('domains', domain.data.id), keyOf('systems', id), 'contains');
+    for (const id of idsOf(domain.data.services)) relate(keyOf('domains', domain.data.id), keyOf('services', id), 'contains');
+  }
+  for (const system of systems) {
+    for (const id of idsOf(system.data.services)) relate(keyOf('systems', system.data.id), keyOf('services', id), 'contains');
+  }
+  for (const service of services) {
+    const serviceKey = keyOf('services', service.data.id);
+    for (const id of idsOf(service.data.sends)) {
+      const collection = messageCollection.get(id);
+      if (collection) relate(serviceKey, keyOf(collection, id));
+    }
+    for (const id of idsOf(service.data.receives)) {
+      const collection = messageCollection.get(id);
+      if (collection) relate(keyOf(collection, id), serviceKey);
+    }
+    for (const id of idsOf(service.data.writesTo)) relate(serviceKey, keyOf('containers', id));
+    for (const id of idsOf(service.data.readsFrom)) relate(keyOf('containers', id), serviceKey);
+  }
+
+  return { resources, relations };
+};

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/components/CanvasControls.tsx

@@ -0,0 +1,153 @@
+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={!editable || !canUndo}>
+          <Undo className="h-4 w-4" />
+        </ControlButton>
+        <ControlButton label="Redo (⇧⌘Z)" onClick={onRedo} disabled={!editable || !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>
+        <ControlButton label="Add sticky note" onClick={onAddNote} disabled={!editable}>
+          <StickyNote className="h-4 w-4 text-yellow-500" />
+        </ControlButton>
+      </div>
+    </div>
+  );
+});