@eventcatalog/core 5.6.1 → 5.7.0

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

@@ -30,6 +30,7 @@ export default memo(function NodeDetails({
   connections,
   onOpenNode,
   containerRef,
+  nameEmpty,
   locked,
   onChange,
   onClose,
@@ -43,6 +44,8 @@ export default memo(function NodeDetails({
   onOpenNode: (id: string) => void;
   /** The canvas, to put the card next to the node */
   containerRef: RefObject<HTMLElement | null>;
+  /** Its name starts empty, to type it straight in (a node just made: it keeps its name if nothing's typed) */
+  nameEmpty?: boolean;
   locked: boolean;
   onChange: UpdateNodeData;
   onClose: () => void;
@@ -112,6 +115,7 @@ export default memo(function NodeDetails({
                 onSaved={showSaved}
                 placeholder={`Name this ${label.toLowerCase()}`}
                 className="ec-editable-title"
+                startEmpty={nameEmpty}
                 required
               />
             </Field>

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

@@ -98,6 +98,12 @@ import {
   type HotspotSeverity,
   type HotspotSpot,
   RemeasureHandles,
+  ConnectChooser,
+  isCardType,
+  newCardData,
+  notPlaceholder,
+  useConnectNew,
+  type NewLink,
 } from '@eventcatalog/visualiser/studio';
 import { X } from 'lucide-react';
 import type { CatalogRelation, CatalogResource } from '../catalog-resources';
@@ -625,11 +631,23 @@ function Canvas({
     centring.current.set(id, { level, size });
     flow.setLevelLayout(level, new Map([[id, centredOn(center, size)]]));
   };
-  /** A component (its type, or its key in the components list: the kinds of data store share a type) */
-  const addComponentAt = (component: string, point: XYPosition) => {
-    if (component === 'note') return addNoteAt(point);
+  /**
+   * A component (its type, or its key in the components list: the kinds of data store share a type), connected to
+   * the node a connection was dragged from when there is one
+   */
+  const addComponentAt = (component: string, point: XYPosition, link?: NewLink) => {
+    if (component === 'note') return void addNoteAt(point);
     const at = landingAt(point, getNodeDefinition(component)?.type ?? component);
-    keepOnLevel(at, flow.addNode(component, at.center, at.inside));
+    const id = flow.addNode(component, at.center, at.inside, link);
+    keepOnLevel(at, id);
+    return id;
+  };
+  /** A new domain or system as a card (the visualiser's, as Studio on the web makes them), connected to `link`'s node */
+  const addCardAt = (type: 'context-domain' | 'system', point: XYPosition, link: NewLink) => {
+    const at = landingAt(point, type);
+    const id = flow.insertNode(type, newCardData(type), at.center, undefined, at.inside, link);
+    keepOnLevel(at, id);
+    return id;
   };
 
   const addComponent = useStableCallback((type: string) => addComponentAt(type, canvasCenter()));
@@ -728,6 +746,21 @@ function Canvas({
     trackPointer(event);
   });
 
+  // ---- Connecting to something new: a connection let go of on empty canvas ----
+
+  // A placeholder where it was let go of, connected to the node it came from, until what it is is chosen beside it
+  const connect = useConnectNew({
+    canvasRef,
+    getNode: (id) => nodesRef.current.find((node) => node.id === id),
+    getLevel: () => levelRef.current,
+    locked,
+    onMake: (option, center, link) => {
+      const id = isCardType(option.type) ? addCardAt(option.type, center, link) : addComponentAt(option.key, center, link);
+      // Selected, and its details open to name it, once it's on the canvas
+      if (id) editOnceShown.current = id;
+    },
+  });
+
   // While the canvas is panned, zoomed or dragged, message edges stop animating (a class, not state, so nothing re-renders)
   const interactions = useRef({ moving: false, dragging: false });
   const setInteraction = useCallback((kind: 'moving' | 'dragging', on: boolean) => {
@@ -972,6 +1005,7 @@ function Canvas({
     setTool('select');
     setDraft(null);
     setOpenThreadId(null);
+    connect.cancel();
     // What's selected may not be on the next level (e.g. a note added on this one)
     flow.onNodesChange(selectedIds().map((id) => ({ type: 'select', id, selected: false })));
     setLevel(next);
@@ -1193,7 +1227,8 @@ function Canvas({
    * removes it from the canvas (the level is drawn from it); and moving or resizing something arranges the level,
    * kept when it's dropped.
    */
-  const onLevelNodesChange = useStableCallback((changes: NodeChange[]) => {
+  const onLevelNodesChange = useStableCallback((allChanges: NodeChange[]) => {
+    const changes = allChanges.filter(notPlaceholder);
     const level = levelRef.current;
     const current = levelGraphRef.current;
     if (level === 3 || !current) return;
@@ -1232,6 +1267,11 @@ function Canvas({
     });
     if (measured.length) flow.setLevelLayout(level, new Map(measured));
   });
+  /** Changes on the canvas (L3), apart from the placeholder's */
+  const onCanvasNodesChange = useStableCallback((allChanges: NodeChange[]) => {
+    const changes = allChanges.filter(notPlaceholder);
+    if (changes.length) flow.onNodesChange(changes);
+  });
   /** Connecting two things on L1 or L2 connects them on the canvas (e.g. a relationship between two systems) */
   const onLevelConnect = useStableCallback((connection: Connection) => {
     const onCanvas = new Set(nodesRef.current.map((node) => node.id));
@@ -1254,6 +1294,13 @@ function Canvas({
         : edge
     );
   }, [levelEdges, flow.edges, hovered]);
+  // With the placeholder, while a connection let go of on empty canvas is waiting to be told what it connects to
+  const { placeholder } = connect;
+  const flowNodes = useMemo(
+    () => (placeholder ? [...visibleNodes, placeholder.node] : visibleNodes),
+    [visibleNodes, placeholder]
+  );
+  const flowEdges = useMemo(() => (placeholder ? [...shownEdges, placeholder.edge] : shownEdges), [shownEdges, placeholder]);
   // A canvas opened from a diagram has the levels the diagram has (until what's on it changes)
   const unavailableLevels = useMemo(() => {
     const reason = (level: 1 | 2) => {
@@ -1654,6 +1701,20 @@ function Canvas({
   // The node whose details are being edited in its card: opened with the edit button over it, by double clicking it,
   // or "Edit details" in its menu (selecting a node doesn't open it). Notes are edited on the canvas.
   const [editingId, setEditingId] = useState<string | null>(null);
+  // Made at the end of a connection: selected and its details opened once it's on the canvas (looked for as what's on
+  // it changes, not as things move), its name empty to type it straight in. NodeDetails is keyed by the node, so its
+  // name starts empty when its card opens, and only then (the next card opened, even its own again, doesn't).
+  const editOnceShown = useRef<string | null>(null);
+  const [justMadeId, setJustMadeId] = useState<string | null>(null);
+  useEffect(() => {
+    const id = editOnceShown.current;
+    if (!id || !nodesRef.current.some((node) => node.id === id)) return;
+    editOnceShown.current = null;
+    select(new Set([id]));
+    setEditingId(id);
+    setJustMadeId(id);
+  }, [flow.structureKey]);
+  useEffect(() => setJustMadeId((id) => (id === editingId ? id : null)), [editingId]);
   const editing = editingId ? flow.nodes.find((node) => node.id === editingId && !isWrittenOnCanvas(node.type)) : undefined;
   // What the card shows (not the node's position, so dragging it doesn't re-render the card)
   const inspected = useMemo(
@@ -1706,8 +1767,8 @@ function Canvas({
                   onDoubleClick={onCanvasDoubleClick}
                 >
                   <ReactFlow
-                    nodes={visibleNodes}
-                    edges={shownEdges}
+                    nodes={flowNodes}
+                    edges={flowEdges}
                     onNodeMouseEnter={onNodeMouseEnter}
                     onNodeMouseLeave={onHoverEnd}
                     onEdgeMouseEnter={onEdgeMouseEnter}
@@ -1717,12 +1778,15 @@ function Canvas({
                     nodesDraggable={!locked && tool !== 'hand'}
                     nodesConnectable={!locked && tool !== 'hand'}
                     elementsSelectable={tool !== 'hand'}
-                    onNodesChange={editable ? flow.onNodesChange : onLevelNodesChange}
+                    onNodesChange={editable ? onCanvasNodesChange : onLevelNodesChange}
                     onEdgesChange={editable ? flow.onEdgesChange : undefined}
                     onConnect={editable ? flow.onConnect : onLevelConnect}
+                    onConnectEnd={connect.onConnectEnd}
                     // Drag either end of a connection to another node (dropped anywhere else, it stays where it was)
                     edgesReconnectable={editable && !locked}
                     onReconnect={editable ? flow.onReconnect : undefined}
+                    onReconnectStart={connect.onReconnectStart}
+                    onReconnectEnd={connect.onReconnectEnd}
                     reconnectRadius={RECONNECT_RADIUS}
                     onDragOver={locked ? undefined : onDragOver}
                     onMoveStart={onMoveStart}
@@ -2016,6 +2080,7 @@ function Canvas({
                       connections={inspectedConnections}
                       onOpenNode={openConnected}
                       containerRef={canvasRef}
+                      nameEmpty={inspected.id === justMadeId}
                       locked={locked}
                       onChange={flow.updateNodeData}
                       onClose={closePanel}
@@ -2023,6 +2088,7 @@ function Canvas({
                   )}
                 </div>
 
+                {connect.chooser && <ConnectChooser {...connect.chooser} />}
                 {chooser && (
                   <ContainerChooser
                     kind={chooser.resource.collection === 'domains' ? 'domain' : 'system'}

package/eventcatalog/src/features/studio/hooks/use-studio-flow.ts

@@ -55,6 +55,8 @@ import {
   canGoInContainer,
   getNodeDefinition,
   isGroupType,
+  linkConnection,
+  type NewLink,
   createHotspot as createHotspotInDoc,
   updateHotspot as updateHotspotInDoc,
   deleteHotspot as deleteHotspotInDoc,
@@ -599,7 +601,8 @@ export function useStudioFlow({
 
   /**
    * Add a node centred on a canvas position. `connect` gets the new node's id and the nodes already
-   * on the canvas, and returns edges to add with it (e.g. a catalog resource's relationships).
+   * on the canvas, and returns edges to add with it (e.g. a catalog resource's relationships). `link` connects it to
+   * the node a connection was dragged from (in the same change, so one undo takes both back).
    */
   const insertNode = useCallback(
     (
@@ -607,7 +610,8 @@ export function useStudioFlow({
       data: Record<string, unknown>,
       center: XYPosition,
       connect?: (id: string, existing: Node[]) => Edge[],
-      inside?: string
+      inside?: string,
+      link?: NewLink
     ) => {
       const built = buildNode(type, data, center);
       withDoc((doc) => {
@@ -618,6 +622,7 @@ export function useStudioFlow({
           ? { ...built, parentId: group.id, position: toRelativePosition(built.position, group.id, existing) }
           : built;
         addNodes(doc, [node], connect?.(node.id, existing) ?? []);
+        if (link) connectNodes(doc, linkConnection(node.id, link));
         if (group) fitGroupToChildren(doc, group.id, renderedSizes());
       });
       return built.id;
@@ -627,9 +632,9 @@ export function useStudioFlow({
 
   /** Add a node of a component (its type, or its key in the components list), centred on a canvas position (in a container, if asked) */
   const addNode = useCallback(
-    (component: string, center: XYPosition, inside?: string) => {
+    (component: string, center: XYPosition, inside?: string, link?: NewLink) => {
       const definition = getNodeDefinition(component);
-      return definition ? insertNode(definition.type, definition.createData(), center, undefined, inside) : undefined;
+      return definition ? insertNode(definition.type, definition.createData(), center, undefined, inside, link) : undefined;
     },
     [insertNode]
   );

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/index.astro

@@ -75,6 +75,7 @@ import {
   isArchitectureGraphEnabled,
 } from '@utils/feature';
 import { getMDXComponentsByName, parseMdxBooleanProp } from '@utils/markdown';
+import { isFlowGroupBy } from '@eventcatalog/visualiser';
 
 import type { CollectionTypes } from '@types';
 
@@ -349,6 +350,8 @@ let nodeGraphs =
       ...graph,
       search: parseMdxBooleanProp(nodeGraph.search, true),
       legend: parseMdxBooleanProp(nodeGraph.legend, true),
+      // Flows only: group the steps to start with (a string in MDX, so only a way they can be grouped)
+      lanes: isFlowGroupBy(nodeGraph.lanes) ? nodeGraph.lanes : undefined,
     };
   }) || [];
 const flowEmbeds = getMDXComponentsByName(props.body || '', 'Flow') || [];
@@ -649,6 +652,7 @@ if (!isAdrPage && !hasCurrentFlowEmbed && !hasCurrentPageNodeGraph) {
                     linksToVisualiser={true}
                     showSearch={nodeGraph.search ?? true}
                     showLegend={nodeGraph.legend ?? true}
+                    lanes={collection === 'flows' ? nodeGraph.lanes : undefined}
                     href={
                       isVisualiserEnabled()
                         ? {

package/eventcatalog/src/utils/node-graphs/compact-visualiser-graph.ts

@@ -37,6 +37,8 @@ const RESOURCE_DATA_KEYS = [
   // An entity's identifier, its primary key in the Mermaid export
   'identifier',
   'sidebar',
+  // `visualiser: false`: it has no diagram page, so a node's card doesn't link to one
+  'visualiser',
 ] as const;
 
 const RESOURCE_OBJECT_KEYS = new Set([
@@ -138,6 +140,18 @@ const compactVisualiserResourceData = (value: unknown): unknown => {
     out.services = value.services.map(compactDomainService);
   }
 
+  // A service's messages, by id only: a node's card uses them to tell which of a shared channel's messages it sends
+  // or receives (pointers, or hydrated messages)
+  for (const key of ['sends', 'receives'] as const) {
+    const list = value[key];
+    if (!Array.isArray(list)) continue;
+    out[key] = list.flatMap((pointer) => {
+      if (!isPlainObject(pointer)) return [];
+      const id = isPlainObject(pointer.data) ? pointer.data.id : pointer.id;
+      return id === undefined ? [] : [{ id }];
+    });
+  }
+
   return out;
 };
 

package/eventcatalog/src/utils/node-graphs/node-resource.ts

@@ -65,3 +65,29 @@ export const getNodeCatalogResource = (node: DiagramNode): { collection: string;
   if (!collection || typeof details?.id !== 'string') return undefined;
   return { collection, id: details.id, ...(typeof details.version === 'string' && { version: details.version }) };
 };
+
+// The collections with a diagram page (pages/visualiser/[type], and domains' and systems' own)
+const DIAGRAM_COLLECTIONS = new Set([
+  'services',
+  'agents',
+  'events',
+  'commands',
+  'queries',
+  'channels',
+  'flows',
+  'containers',
+  'data-products',
+  'domains',
+  'systems',
+]);
+
+/**
+ * The path of the diagram page of the resource a node shows (e.g. `/visualiser/services/OrderService/1.0.0`), if it
+ * has one: not for actors, users, entities and the like, or a resource with `visualiser: false`
+ */
+export const getNodeDiagramPath = (node: DiagramNode): string | undefined => {
+  const resource = getNodeCatalogResource(node);
+  if (!resource?.version || !DIAGRAM_COLLECTIONS.has(resource.collection)) return undefined;
+  if (getNodeResourceDetails(node)?.visualiser === false) return undefined;
+  return `/visualiser/${resource.collection}/${resource.id}/${resource.version}`;
+};

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "BUSL-1.1",
   "type": "module",
-  "version": "5.6.1",
+  "version": "5.7.0",
   "publishConfig": {
     "access": "public"
   },
@@ -75,14 +75,14 @@
     "@radix-ui/react-dropdown-menu": "^2.1.12",
     "@radix-ui/react-popover": "^1.1.15",
     "@radix-ui/react-tooltip": "^1.1.8",
-    "@scalar/api-reference-react": "^0.9.36",
+    "@scalar/api-reference-react": "^0.9.82",
     "@tailwindcss/typography": "^0.5.16",
     "@tailwindcss/vite": "^4.3.1",
     "@tanstack/react-table": "^8.17.3",
     "@xyflow/react": "^12.12.0",
     "ai": "^7.0.106",
     "astro": "7.3.8",
-    "astro-expressive-code": "^0.44.0",
+    "astro-expressive-code": "^0.44.3",
     "astro-seo": "^1.2.0",
     "boxen": "^8.0.1",
     "commander": "^12.1.0",
@@ -123,7 +123,7 @@
     "react-syntax-highlighter": "^16.1.1",
     "recast": "^0.23.11",
     "rehype-autolink-headings": "^7.1.0",
-    "rehype-expressive-code": "^0.44.0",
+    "rehype-expressive-code": "^0.44.3",
     "rehype-slug": "^6.0.0",
     "remark-comment": "^1.0.0",
     "remark-directive": "^3.0.0",
@@ -141,11 +141,11 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.33",
     "zod": "^4.6.6",
-    "@eventcatalog/exporters": "0.1.3",
     "@eventcatalog/fitness": "0.1.1",
-    "@eventcatalog/linter": "1.3.1",
     "@eventcatalog/sdk": "2.32.0",
-    "@eventcatalog/visualiser": "^5.1.2"
+    "@eventcatalog/visualiser": "^5.2.0",
+    "@eventcatalog/linter": "1.3.1",
+    "@eventcatalog/exporters": "0.1.4"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.10",