@eventcatalog/core 2.65.0 → 3.0.0-beta.0

package/eventcatalog/src/components/SideNav/NestedSideBar/builders/service.ts

@@ -0,0 +1,147 @@
+import type { CollectionEntry } from 'astro:content';
+import { buildUrl } from '@utils/url-builder';
+import { getSpecificationsForService } from '@utils/collections/services';
+import type { NavNode, ChildRef } from './shared';
+import {
+  uniqueBy,
+  buildQuickReferenceSection,
+  buildOwnersSection,
+  shouldRenderSideBarSection,
+  buildResourceGroupSections,
+  buildRepositorySection,
+} from './shared';
+import { isVisualiserEnabled } from '@utils/feature';
+import { pluralizeMessageType } from '@utils/collections/messages';
+
+export const buildServiceNode = (service: CollectionEntry<'services'>, owners: any[], context: any): NavNode => {
+  const sendsMessages = service.data.sends || [];
+  const receivesMessages = service.data.receives || [];
+  const serviceEntities = service.data.entities || [];
+
+  const specifications = getSpecificationsForService(service);
+  const hasSpecifications = specifications.length > 0;
+  const openAPISpecifications = specifications.filter((specification) => specification.type === 'openapi');
+  const asyncAPISpecifications = specifications.filter((specification) => specification.type === 'asyncapi');
+  const graphQLSpecifications = specifications.filter((specification) => specification.type === 'graphql');
+
+  const dataStoresInService = uniqueBy([...(service.data.writesTo || []), ...(service.data.readsFrom || [])], 'id');
+
+  const serviceFlows = service.data.flows || [];
+  const hasFlows = serviceFlows.length > 0;
+
+  const hasDataStores = dataStoresInService.length > 0;
+  const resourceGroups = service.data.resourceGroups || [];
+  const hasResourceGroups = resourceGroups.length > 0;
+
+  const renderResourceGroups = hasResourceGroups && shouldRenderSideBarSection(service, 'resourceGroups');
+  const renderVisualiser = isVisualiserEnabled();
+  const renderMessages = shouldRenderSideBarSection(service, 'messages');
+  const renderSpecifications = hasSpecifications && shouldRenderSideBarSection(service, 'specifications');
+  const renderEntities = serviceEntities.length > 0 && shouldRenderSideBarSection(service, 'entities');
+  const renderOwners = owners.length > 0 && shouldRenderSideBarSection(service, 'owners');
+  const renderRepository = service.data.repository && shouldRenderSideBarSection(service, 'repository');
+
+  return {
+    type: 'item',
+    title: service.data.name,
+    badge: 'Service',
+    summary: service.data.summary,
+    pages: [
+      buildQuickReferenceSection([
+        { title: 'Overview', href: buildUrl(`/docs/services/${service.data.id}/${service.data.version}`) },
+      ]),
+      {
+        type: 'group',
+        title: 'Architecture & Design',
+        icon: 'Workflow',
+        pages: [
+          {
+            type: 'item',
+            title: 'Architecture Diagram',
+            href: buildUrl(`/architecture/services/${service.data.id}/${service.data.version}`),
+          },
+          renderVisualiser && {
+            type: 'item',
+            title: 'Interaction Map',
+            href: buildUrl(`/visualiser/services/${service.data.id}/${service.data.version}`),
+          },
+          renderVisualiser &&
+            hasDataStores && {
+              type: 'item',
+              title: 'Data Map',
+              href: buildUrl(`/visualiser/services/${service.data.id}/${service.data.version}/data`),
+            },
+        ],
+      },
+      renderSpecifications && {
+        type: 'group',
+        title: 'API & Contracts',
+        icon: 'FileCode',
+        pages: [
+          ...openAPISpecifications.map((specification) => ({
+            type: 'item',
+            title: `${specification.name} (OpenAPI)`,
+            href: buildUrl(
+              `/docs/services/${service.data.id}/${service.data.version}/spec/${specification.filenameWithoutExtension}`
+            ),
+          })),
+          ...asyncAPISpecifications.map((specification) => ({
+            type: 'item',
+            title: `${specification.name} (AsyncAPI)`,
+            href: buildUrl(
+              `/docs/services/${service.data.id}/${service.data.version}/asyncapi/${specification.filenameWithoutExtension}`
+            ),
+          })),
+          ...graphQLSpecifications.map((specification) => ({
+            type: 'item',
+            title: `${specification.name} (GraphQL)`,
+            href: buildUrl(
+              `/docs/services/${service.data.id}/${service.data.version}/graphql/${specification.filenameWithoutExtension}`
+            ),
+          })),
+        ],
+      },
+      renderResourceGroups && buildResourceGroupSections(resourceGroups, context),
+      hasDataStores && {
+        type: 'group',
+        title: 'State and Persistence',
+        icon: 'Database',
+        pages: dataStoresInService.map(
+          (dataStore) => `container:${(dataStore as any).data.id}:${(dataStore as any).data.version}`
+        ),
+      },
+      renderEntities && {
+        type: 'group',
+        title: 'Entities',
+        icon: 'Box',
+        pages: serviceEntities.map((entity) => `entity:${(entity as any).data.id}:${(entity as any).data.version}`),
+      },
+      sendsMessages.length > 0 &&
+        renderMessages && {
+          type: 'group',
+          title: 'Outbound Messages',
+          icon: 'Mail',
+          pages: sendsMessages.map(
+            (message) => `${pluralizeMessageType(message as any)}:${(message as any).data.id}:${(message as any).data.version}`
+          ),
+        },
+      receivesMessages.length > 0 &&
+        renderMessages && {
+          type: 'group',
+          title: 'Inbound Messages',
+          icon: 'Mail',
+          pages: receivesMessages.map(
+            (receive) => `${pluralizeMessageType(receive as any)}:${(receive as any).data.id}:${(receive as any).data.version}`
+          ),
+        },
+      hasFlows && {
+        type: 'group',
+        title: 'Flows',
+        icon: 'Waypoints',
+        pages: serviceFlows.map((flow) => `flow:${(flow as any).data.id}:${(flow as any).data.version}`),
+      },
+      renderOwners && buildOwnersSection(owners),
+      renderRepository && buildRepositorySection(service.data.repository as { url: string; language: string }),
+    ].filter(Boolean) as ChildRef[],
+  };
+};

package/eventcatalog/src/components/SideNav/NestedSideBar/builders/shared.ts

@@ -0,0 +1,146 @@
+import type { ResourceGroup } from '@eventcatalog/sdk';
+import type { CollectionEntry } from 'astro:content';
+import { getLatestVersionInCollectionById } from '@utils/collections/util';
+import { buildUrl } from '@utils/url-builder';
+
+/**
+ * A child reference can be:
+ * - A string key (resolved from nodes map)
+ * - An inline node definition
+ */
+export type ChildRef = string | NavNode;
+
+/**
+ * A navigation node (can be section or item)
+ */
+export type NavNode = {
+  type: 'group' | 'item';
+  title: string;
+  icon?: string; // Lucide icon name
+  href?: string; // URL (for leaf items)
+  external?: boolean; // If true, the item will open in a new tab
+  pages?: ChildRef[]; // Can mix keys and inline nodes
+  visible?: boolean; // If false, hide this node (default: true)
+  badge?: string; // Category badge shown in header (e.g., "Domain", "Service", "Message")
+  summary?: string; // Short description of the item
+};
+
+/**
+ * The flat navigation data structure
+ */
+export type NavigationData = {
+  roots: ChildRef[]; // What to show at top level
+  nodes: Record<string, NavNode>; // Flat map of all nodes by key
+};
+
+export const uniqueBy = <T>(array: T[], key: keyof T): T[] => {
+  const seen = new Set();
+  return array.filter((item) => {
+    const value = item[key];
+    if (seen.has(value)) {
+      return false;
+    }
+    seen.add(value);
+    return true;
+  });
+};
+
+export type ResourceGroupContext = {
+  services: CollectionEntry<'services'>[];
+  domains: CollectionEntry<'domains'>[];
+  events: CollectionEntry<'events'>[];
+  commands: CollectionEntry<'commands'>[];
+  queries: CollectionEntry<'queries'>[];
+  flows: CollectionEntry<'flows'>[];
+  containers: CollectionEntry<'containers'>[];
+};
+
+export const buildQuickReferenceSection = (items: { title: string; href: string }[]): NavNode => ({
+  type: 'group',
+  title: 'Quick Reference',
+  icon: 'BookOpen',
+  pages: items.map((item) => ({
+    type: 'item',
+    title: item.title,
+    href: item.href,
+  })),
+});
+
+export const buildOwnersSection = (owners: any[]): NavNode | null => {
+  if (owners.length === 0) return null;
+  return {
+    type: 'group',
+    title: 'Owners',
+    icon: 'Users',
+    pages: owners.map((owner) => ({
+      type: 'item',
+      title: owner?.data.name ?? '',
+      href: buildUrl(`/docs/${owner?.collection}/${owner?.data.id}`),
+    })),
+    visible: true,
+  };
+};
+
+export const buildRepositorySection = (repository: { url: string; language: string }): NavNode | null => {
+  if (!repository) return null;
+  return {
+    type: 'group',
+    title: 'Code',
+    icon: 'Code',
+    pages: [
+      {
+        type: 'item',
+        title: repository.url,
+        href: repository.url,
+      },
+    ],
+  };
+};
+
+export const buildResourceGroupSections = (resourceGroups: ResourceGroup[], context: ResourceGroupContext) => {
+  return resourceGroups.map((resourceGroup) => buildResourceGroupSection(resourceGroup, context));
+};
+
+const buildResourceGroupSection = (resourceGroup: ResourceGroup, context: ResourceGroupContext) => {
+  // Only render resource groups that have a type
+  const resourcesWithTypes = resourceGroup.items.filter((item) => item.type !== undefined);
+
+  if (resourcesWithTypes.length === 0) {
+    return null;
+  }
+
+  // If no version is provided, we need to get the latest version
+  const resourcesWithVersions = resourcesWithTypes.map((item) => {
+    let collection: any[] = [];
+
+    if (item.type === 'service') collection = context.services;
+    else if (item.type === 'domain') collection = context.domains;
+    else if (item.type === 'event') collection = context.events;
+    else if (item.type === 'command') collection = context.commands;
+    else if (item.type === 'query') collection = context.queries;
+    else if (item.type === 'flow') collection = context.flows;
+    else if (item.type === 'container') collection = context.containers;
+
+    if (item.version === undefined || item.version === 'latest') {
+      return { ...item, version: getLatestVersionInCollectionById(collection, item.id as string) };
+    }
+    return item;
+  });
+
+  return {
+    type: 'group',
+    title: resourceGroup.title,
+    icon: 'Box',
+    pages: resourcesWithVersions.map((item) => {
+      const type = ['event', 'command', 'query'].includes(item.type as string) ? 'message' : item.type;
+      return `${type}:${item.id}:${item.version}`;
+    }),
+  };
+};
+
+export const shouldRenderSideBarSection = (resource: any, section: string) => {
+  if (!resource.data.detailsPanel) {
+    return true;
+  }
+  return resource.data.detailsPanel[section]?.visible ?? true;
+};