@eventcatalog/core 0.1.12 → 0.1.13

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @eventcatalog/core
 
+## 0.1.13
+
+### Patch Changes
+
+- [`ca01bef`](https://github.com/boyney123/eventcatalog/commit/ca01bef1659b2c364210a86e0f9e916f6c1fbaa4) [#166](https://github.com/boyney123/eventcatalog/pull/166) Thanks [@thim81](https://github.com/thim81)! - feat: new nodegraph component to render services and events
+
 ## 0.1.12
 
 ### Patch Changes

package/components/Mdx/NodeGraph/GraphElements.ts

@@ -0,0 +1,183 @@
+import { ArrowHeadType, XYPosition, Node, Edge } from 'react-flow-renderer';
+import getConfig from 'next/config';
+import type { Event, Service } from '@eventcatalog/types';
+
+const { publicRuntimeConfig: { basePath = '' } = {} } = getConfig();
+
+const MIN_NODE_WIDTH = 150;
+const generateLink = (value, type) => (basePath !== '' ? `${basePath}/${type}/${value}` : `/${type}/${value}`);
+const calcWidth = (value) => (value.length * 7 > MIN_NODE_WIDTH ? value.length * 7 : MIN_NODE_WIDTH);
+
+const buildNodeEdge = ({ id, target, source, isAnimated = true }) => ({
+  id,
+  target,
+  source,
+  type: 'smoothstep',
+  arrowHeadType: ArrowHeadType.ArrowClosed,
+  animated: isAnimated,
+});
+
+const buildNodeData = ({ label, type, maxWidth }: { label: string; type: 'service' | 'event'; maxWidth?: number }) => {
+  const width = calcWidth(label);
+  const linkType = type === 'service' ? 'services' : 'events';
+  const link = generateLink(label, linkType);
+  return { label, link, width, maxWidth };
+};
+
+/**
+ * Builds a graph for a given event
+ * @param {Event} - event
+ * @param rootNodeColor - The color of the root node
+ * @param isAnimated - whether to animate the graph
+ */
+export const getEventElements = (
+  { name: eventName, producers: eventProducers, consumers: eventConsumers }: Event,
+  rootNodeColor = '#2563eb',
+  isAnimated = true
+) => {
+  const position: XYPosition = { x: 0, y: 0 };
+
+  const consumerColor = '#818cf8';
+  const producerColor = '#75d7b6';
+
+  const producersNames = eventProducers.map((s) => calcWidth(s));
+  const maxProducersWidth = Math.max(...producersNames);
+  const consumersNames = eventConsumers.map((s) => calcWidth(s));
+  const maxConsumersWidth = Math.max(...consumersNames);
+
+  const eventNameAsNodeID = `ev-${eventName.replace(/ /g, '_')}`;
+  const eventNodeWidth = calcWidth(eventName);
+
+  const producers = eventProducers.map((node) => ({ label: node, id: `pr-${node.replace(/ /g, '_')}` }));
+  const consumers = eventConsumers.map((node) => ({ label: node, id: `co-${node.replace(/ /g, '_')}` }));
+
+  // Transforms services & event into a graph model
+  const producersNodes: Node[] = producers.map(({ label, id }) => {
+    const nodeWidth = calcWidth(label);
+    const diff = maxProducersWidth - nodeWidth;
+    const nodeMaxWidth = diff !== 0 ? nodeWidth - diff : maxProducersWidth;
+    return {
+      id,
+      data: buildNodeData({ label, type: 'service', maxWidth: nodeMaxWidth }),
+      style: { border: `2px solid ${producerColor}`, width: nodeWidth },
+      type: 'input',
+      position,
+    };
+  });
+  const consumersNodes: Node[] = consumers.map(({ id, label }) => {
+    const width = calcWidth(label);
+    return {
+      id,
+      data: buildNodeData({ label, type: 'service', maxWidth: maxConsumersWidth }),
+      style: { border: `2px solid ${consumerColor}`, width },
+      type: 'output',
+      position,
+    };
+  });
+  const eventNode: Node = {
+    id: eventNameAsNodeID,
+    data: buildNodeData({ label: eventName, type: 'event', maxWidth: eventNodeWidth }),
+    style: {
+      border: `2px solid ${rootNodeColor}`,
+      width: eventNodeWidth,
+    },
+    position,
+  };
+
+  // Build connections
+  const producersEdges: Edge[] = producers.map(({ id, label }) =>
+    buildNodeEdge({ id: `epe-${label.replace(/ /g, '_')}`, source: id, target: eventNameAsNodeID, isAnimated })
+  );
+  const consumersEdges: Edge[] = consumers.map(({ id, label }) =>
+    buildNodeEdge({ id: `ece-${label.replace(/ /g, '_')}`, target: id, source: eventNameAsNodeID, isAnimated })
+  );
+
+  // Merge nodes in order
+  const elements: (Node | Edge)[] = [...producersNodes, eventNode, ...consumersNodes, ...producersEdges, ...consumersEdges];
+  return elements;
+};
+
+/**
+ * Builds a graph for a given service
+ * @param {Service} service
+ * @param {string} rootNodeColor of the root node
+ * @param isAnimated whether the graph should be animated
+ * @returns {string} Mermaid Graph
+ */
+export const getServiceElements = (
+  { publishes, subscribes, name: serviceName }: Service,
+  rootNodeColor = '#2563eb',
+  isAnimated = true
+) => {
+  const position: XYPosition = { x: 0, y: 0 };
+
+  const publishColor = '#818cf8';
+  const subscribeColor = '#75d7b6';
+
+  const publishesNames = publishes.map((e) => calcWidth(e.name));
+  const maxPublishesWidth = Math.max(...publishesNames);
+  const subscribesNames = subscribes.map((e) => calcWidth(e.name));
+  const maxSubscribesWidth = Math.max(...subscribesNames);
+
+  const serviceNameAsNodeID = `ser-${serviceName.replace(/ /g, '_')}`;
+
+  // Transforms services & event into a graph model
+  const publishesNodes: Node[] = publishes.map((node) => {
+    const nodeWidth = calcWidth(node.name);
+    return {
+      id: `pub-${node.name.replace(/ /g, '_')}`,
+      data: buildNodeData({ label: node.name, type: 'event', maxWidth: maxPublishesWidth }),
+      style: { border: `2px solid ${publishColor}`, width: nodeWidth },
+      type: 'output',
+      position,
+    };
+  });
+  const subscribesNodes: Node[] = subscribes.map((node) => {
+    const nodeWidth = calcWidth(node.name);
+    const diff = maxSubscribesWidth - nodeWidth;
+    const nodeMaxWidth = diff !== 0 ? nodeWidth - diff : maxSubscribesWidth;
+    return {
+      id: `sub-${node.name.replace(/ /g, '_')}`,
+      data: buildNodeData({ label: node.name, type: 'event', maxWidth: nodeMaxWidth }),
+      style: {
+        border: `2px solid ${subscribeColor}`,
+        width: nodeWidth,
+      },
+      type: 'input',
+      position,
+    };
+  });
+
+  const serviceNode: Node = {
+    id: serviceNameAsNodeID,
+    data: buildNodeData({ label: serviceName, type: 'service', maxWidth: calcWidth(serviceName) }),
+    style: {
+      border: `2px solid ${rootNodeColor}`,
+      width: calcWidth(serviceName),
+    },
+    position,
+  };
+
+  // Build connections
+  const publishesEdges: Edge[] = publishes.map((node) =>
+    buildNodeEdge({
+      id: `ecp-${node.name.replace(/ /g, '_')}`,
+      source: serviceNameAsNodeID,
+      target: `pub-${node.name.replace(/ /g, '_')}`,
+      isAnimated,
+    })
+  );
+
+  const subscribesEdges: Edge[] = subscribes.map((node) =>
+    buildNodeEdge({
+      id: `esc-${node.name.replace(/ /g, '_')}`,
+      target: serviceNameAsNodeID,
+      source: `sub-${node.name.replace(/ /g, '_')}`,
+      isAnimated,
+    })
+  );
+
+  // Merge nodes in order
+  const elements: (Node | Edge)[] = [...subscribesNodes, serviceNode, ...publishesNodes, ...publishesEdges, ...subscribesEdges];
+  return elements;
+};

package/components/Mdx/NodeGraph/GraphLayout.ts

@@ -0,0 +1,57 @@
+import { isNode, Elements, Position } from 'react-flow-renderer';
+import dagre from 'dagre';
+
+const nodeDefaultWidth = 150;
+const nodeDefaultHeight = 36;
+const offset = 48;
+const verticalOffset = offset / 1.5;
+
+export default function createGraphLayout(elements: Elements, isHorizontal: boolean): Elements {
+  const dagreGraph = new dagre.graphlib.Graph();
+
+  dagreGraph.setDefaultEdgeLabel(() => ({}));
+  dagreGraph.setGraph({ rankdir: 'LR', ranksep: offset * 2, nodesep: verticalOffset });
+
+  elements.forEach((element) => {
+    if (isNode(element)) {
+      // eslint-disable-next-line no-underscore-dangle
+      const nodeWidth = element.__rf?.width ? element.__rf?.width : element.data?.width;
+      dagreGraph.setNode(element.id, {
+        width: nodeWidth || nodeDefaultWidth,
+        // eslint-disable-next-line no-underscore-dangle
+        height: element.__rf?.height || nodeDefaultHeight,
+      });
+    } else {
+      dagreGraph.setEdge(element.source, element.target);
+    }
+  });
+
+  // Calculate the layout, to get the node positions with their widths and heights
+  dagre.layout(dagreGraph);
+
+  return elements.map((element) => {
+    if (isNode(element)) {
+      const node = dagreGraph.node(element.id);
+      element.targetPosition = isHorizontal ? Position.Left : Position.Top;
+      element.sourcePosition = isHorizontal ? Position.Right : Position.Bottom;
+      element.position = {
+        x: offset / 2 + node.x - (element?.data?.maxWidth || node.width) / 2,
+        y: node.y - node.height / 2,
+      };
+    }
+    return element;
+  });
+}
+
+// Helper - ReactFlow canvas height calculator
+export const calcCanvasHeight = (data, type): number => {
+  const minHeight = 300;
+  const nodeSpacing = nodeDefaultHeight + verticalOffset;
+  let nodesHeight = 0;
+  if (type === 'event') {
+    nodesHeight = Math.max(data.producers.length, data.consumers.length) * nodeSpacing;
+  } else {
+    nodesHeight = Math.max(data.publishes.length, data.subscribes.length) * nodeSpacing;
+  }
+  return Math.max(minHeight, nodesHeight);
+};

package/components/Mdx/NodeGraph/NodeGraph.tsx

@@ -0,0 +1,130 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import ReactFlow, { Controls, ReactFlowProvider, useStoreState } from 'react-flow-renderer';
+import { Event, Service } from '@eventcatalog/types';
+import { getEventElements, getServiceElements } from './GraphElements';
+import createGraphLayout, { calcCanvasHeight } from './GraphLayout';
+
+interface NodeGraphBuilderProps {
+  data: Event | Service;
+  source: 'event' | 'service';
+  rootNodeColor?: string;
+  maxZoom?: number;
+  fitView?: boolean;
+  zoomOnScroll?: boolean;
+  isAnimated?: boolean;
+  isDraggable?: boolean;
+  isHorizontal?: boolean;
+}
+
+interface NodeGraphProps extends NodeGraphBuilderProps {
+  maxHeight?: number;
+}
+
+// NodeGraphBuilder component wrapping ReactFlow
+function NodeGraphBuilder({
+  data,
+  source,
+  rootNodeColor,
+  maxZoom = 10,
+  isAnimated = true,
+  fitView = true,
+  zoomOnScroll = false,
+  isDraggable = false,
+  isHorizontal = true,
+}: NodeGraphBuilderProps) {
+  // Load event or service elements for graph
+  let initialElements;
+  if (source === 'event') {
+    initialElements = getEventElements(data as Event, rootNodeColor, isAnimated);
+  } else {
+    initialElements = getServiceElements(data as Service, rootNodeColor, isAnimated);
+  }
+
+  // Initialize graph layout
+  const isInitializedRef = useRef(false);
+  const nodes = useStoreState((state) => state.nodes);
+  const edges = useStoreState((state) => state.edges);
+
+  // Calculate initial element layout
+  const graphElements = createGraphLayout(initialElements, isHorizontal);
+  const [elements, setElements] = useState(graphElements);
+
+  // Rerender graph layout to get rendered width/height for nodes/edges
+  useEffect(() => {
+    if (
+      isInitializedRef.current === false &&
+      nodes.length > 0 &&
+      // eslint-disable-next-line no-underscore-dangle
+      nodes?.[0]?.__rf.width != null
+    ) {
+      // Calculate element layout
+      const updateElements = () => {
+        const updatedElements = createGraphLayout([...nodes, ...edges], isHorizontal);
+        setElements(updatedElements);
+        isInitializedRef.current = true;
+      };
+      updateElements();
+    }
+  }, [nodes, edges, isInitializedRef, isHorizontal]);
+
+  // ReactFlow operations
+  const onElementClick = (event, element) => window.open(element.data.link, '_self');
+  const onLoad = useCallback(
+    (reactFlowInstance) => {
+      if (fitView) {
+        reactFlowInstance.fitView();
+      }
+    },
+    [fitView]
+  );
+
+  return (
+    <ReactFlow
+      elements={elements}
+      onLoad={onLoad}
+      onElementClick={onElementClick}
+      nodesDraggable={isDraggable}
+      zoomOnScroll={zoomOnScroll}
+      maxZoom={maxZoom}
+    >
+      <Controls />
+    </ReactFlow>
+  );
+}
+
+// NodeGraph wrapping NodeGraphBuilder Component
+function NodeGraph({
+  data,
+  source,
+  rootNodeColor,
+  maxHeight,
+  maxZoom,
+  fitView,
+  zoomOnScroll,
+  isAnimated,
+  isDraggable,
+  isHorizontal,
+}: NodeGraphProps) {
+  // Set dynamic height of node graph
+  const dynamicHeight = maxHeight || calcCanvasHeight(data, source);
+
+  return (
+    <div className="node-graph w-full border-dashed border-2 border-slate-300" style={{ height: dynamicHeight }}>
+      <ReactFlowProvider>
+        <NodeGraphBuilder
+          source={source}
+          data={data}
+          rootNodeColor={rootNodeColor}
+          maxZoom={maxZoom}
+          fitView={fitView}
+          zoomOnScroll={zoomOnScroll}
+          isAnimated={isAnimated}
+          isDraggable={isDraggable}
+          isHorizontal={isHorizontal}
+        />
+      </ReactFlowProvider>
+    </div>
+  );
+}
+
+export default NodeGraph;

package/components/Mdx/NodeGraph/__tests__/GraphElements.spec.ts

@@ -0,0 +1,98 @@
+import { Event, Service } from '@eventcatalog/types';
+import { getEventElements, getServiceElements } from '../GraphElements';
+
+jest.mock('next/config', () => () => ({
+  publicRuntimeConfig: {
+    basePath: '/docs',
+  },
+}));
+
+describe('GraphElements', () => {
+  describe('getServiceElements', () => {
+    it('takes a given Service and returns the ReactFlow elements with relations the events it publishes and consumes', () => {
+      const event = { name: 'My Event', version: '0.0.1' };
+      const event2 = { name: 'My Event 2', version: '0.0.1' };
+      const rootNodeColor = '#2563eb';
+      const isAnimated = true;
+
+      const service = {
+        id: 'My Service',
+        name: 'My Service',
+        version: '0.0.1',
+        summary: 'Summary',
+        publishes: [event],
+        subscribes: [event2],
+      };
+
+      const result = getServiceElements(service as Service, rootNodeColor, isAnimated);
+
+      expect(result).toMatchSnapshot();
+    });
+
+    it('takes a given Service and returns the ReactFlow elements with multiple events & long names', () => {
+      const event = { name: 'My Event', version: '0.0.1' };
+      const event2 = { name: 'My Event 2', version: '0.0.1' };
+      const event3 = { name: 'My Event 3', version: '0.0.1' };
+      const event4 = { name: 'very.very.very.very.very.very.very.very.very.very.very.very.long.name.event.4', version: '0.0.1' };
+      const event5 = { name: 'very very very very very very very very very very very very long name event 5', version: '0.0.1' };
+      const event6 = { name: 'My Event 6', version: '0.0.1' };
+      const event7 = { name: 'My Event 7', version: '0.0.1' };
+      const event8 = { name: 'My Event 8', version: '0.0.1' };
+      const event9 = { name: 'My Event 9', version: '0.0.1' };
+      const rootNodeColor = '#2563eb';
+      const isAnimated = true;
+
+      const service = {
+        id: 'My Service',
+        name: 'My Service',
+        version: '0.0.1',
+        summary: 'Summary',
+        publishes: [event, event2, event3, event4],
+        subscribes: [event5, event6, event7, event8, event9],
+      };
+
+      const result = getServiceElements(service as Service, rootNodeColor, isAnimated);
+
+      expect(result).toMatchSnapshot();
+    });
+  });
+
+  describe('getEventElements', () => {
+    it('takes a given event and returns the ReactFlow elements with relations between the event and its consumers and producers', () => {
+      const event = {
+        name: 'My Event',
+        version: '0.0.1',
+        producers: ['Service 1'],
+        consumers: ['Service 2'],
+      };
+      const rootNodeColor = '#2563eb';
+      const isAnimated = true;
+
+      const result = getEventElements(event as Event, rootNodeColor, isAnimated);
+
+      expect(result).toMatchSnapshot();
+    });
+
+    it('takes a given event and returns the ReactFlow elements with multiple services & long names', () => {
+      const event = {
+        name: 'My Event',
+        version: '0.0.1',
+        producers: ['Service 1', 'Service 2', 'very very very very very very very very very very very very long name Service 3'],
+        consumers: [
+          'Service 4',
+          'Service 5',
+          'Service 6',
+          'Service 7',
+          'Service 8',
+          'very.very.very.very.very.very.very.very.very.very.very.very.long.name.event.8',
+        ],
+      };
+      const rootNodeColor = '#2563eb';
+      const isAnimated = true;
+
+      const result = getEventElements(event as Event, rootNodeColor, isAnimated);
+
+      expect(result).toMatchSnapshot();
+    });
+  });
+});

package/components/Mdx/NodeGraph/__tests__/GraphLayout.spec.ts

@@ -0,0 +1,104 @@
+import { Elements } from 'react-flow-renderer';
+import createGraphLayout, { calcCanvasHeight } from '../GraphLayout';
+
+describe('GraphLayout', () => {
+  describe('createGraphLayout', () => {
+    it('calculate a graph layout', () => {
+      const isHorizontal = true;
+      const elements = [
+        {
+          data: {
+            label: 'My Event 2',
+            link: '/docs/events/My Event 2',
+            maxWidth: 150,
+            width: 150,
+          },
+          id: 's-My_Event_2',
+          position: {
+            x: 0,
+            y: 0,
+          },
+          style: {
+            border: '2px solid #75d7b6',
+            width: 150,
+          },
+          type: 'input',
+        },
+        {
+          data: {
+            label: 'My Service',
+            link: '/docs/services/My Service',
+            maxWidth: 150,
+            width: 150,
+          },
+          id: 'c-My_Service',
+          position: {
+            x: 0,
+            y: 0,
+          },
+          style: {
+            border: '2px solid #2563eb',
+            width: 150,
+          },
+        },
+        {
+          data: {
+            label: 'My Event',
+            link: '/docs/events/My Event',
+            maxWidth: 150,
+            width: 150,
+          },
+          id: 'p-My_Event',
+          position: {
+            x: 0,
+            y: 0,
+          },
+          style: {
+            border: '2px solid #818cf8',
+            width: 150,
+          },
+          type: 'output',
+        },
+        {
+          animated: true,
+          arrowHeadType: 'arrowclosed',
+          id: 'ecp-My_Event',
+          source: 'c-My_Service',
+          target: 'p-My_Event',
+          type: 'smoothstep',
+        },
+        {
+          animated: true,
+          arrowHeadType: 'arrowclosed',
+          id: 'esc-My_Event_2',
+          source: 's-My_Event_2',
+          target: 'c-My_Service',
+          type: 'smoothstep',
+        },
+      ];
+
+      const result = createGraphLayout(elements as Elements, isHorizontal);
+      expect(result).toMatchSnapshot();
+    });
+  });
+
+  describe('calcCanvasHeight', () => {
+    it('takes all events and calculate the canvas height', () => {
+      const data = {
+        producers: [1, 2, 3, 4, 5, 6, 7, 8],
+        consumers: [1, 2, 3, 4, 5],
+      };
+      const result = calcCanvasHeight(data, 'event');
+      expect(result).toEqual(544);
+    });
+
+    it('takes all services and calculate the canvas height', () => {
+      const data = {
+        publishes: [1, 2, 3, 4, 5, 6, 7, 8, 9],
+        subscribes: [1, 2, 3, 4, 5],
+      };
+      const result = calcCanvasHeight(data, 'service');
+      expect(result).toEqual(612);
+    });
+  });
+});