@eventcatalog/core 4.10.15 → 4.11.1

package/eventcatalog/src/components/SchemaExplorer/SchemaFlows.tsx

@@ -0,0 +1,76 @@
+import { useEffect, useState } from 'react';
+import { ArrowTopRightOnSquareIcon, ChevronDownIcon } from '@heroicons/react/24/outline';
+import SchemaGraph from './SchemaGraph';
+import type { FlowUsage, SchemaItem } from './types';
+import { getSchemaRelationshipHref } from './utils';
+
+interface SchemaFlowsProps {
+  message: SchemaItem;
+  flows: FlowUsage[];
+}
+
+const flowKey = (flow: FlowUsage) => `${flow.id}-${flow.version}`;
+
+/** The diagram of a flow the message appears in, with a picker when it appears in several. */
+export default function SchemaFlows({ message, flows }: SchemaFlowsProps) {
+  const [selectedKey, setSelectedKey] = useState(() => (flows[0] ? flowKey(flows[0]) : ''));
+  // Keep the selection valid when the message (and so the list of flows) changes.
+  useEffect(() => {
+    if (!flows.some((flow) => flowKey(flow) === selectedKey)) setSelectedKey(flows[0] ? flowKey(flows[0]) : '');
+  }, [flows, selectedKey]);
+
+  const selected = flows.find((flow) => flowKey(flow) === selectedKey) ?? flows[0];
+  if (!selected) return null;
+
+  return (
+    <div className="flex h-full flex-col overflow-auto pr-1">
+      <div className="mb-4 flex shrink-0 flex-wrap items-center gap-3">
+        {flows.length > 1 ? (
+          <label className="relative inline-flex items-center">
+            <span className="sr-only">Flow</span>
+            <select
+              value={flowKey(selected)}
+              onChange={(event) => setSelectedKey(event.target.value)}
+              className="appearance-none rounded-md border border-[rgb(var(--ec-input-border))] bg-[rgb(var(--ec-input-bg))] py-1.5 pl-3 pr-8 text-sm font-medium text-[rgb(var(--ec-input-text))] focus:outline-none focus:ring-2 focus:ring-[rgb(var(--ec-accent)/0.4)]"
+            >
+              {flows.map((flow) => (
+                <option key={flowKey(flow)} value={flowKey(flow)}>
+                  {flow.name || flow.id} (v{flow.version})
+                </option>
+              ))}
+            </select>
+            <ChevronDownIcon className="pointer-events-none absolute right-2 h-4 w-4 text-[rgb(var(--ec-icon-color))]" />
+          </label>
+        ) : (
+          <span className="text-sm font-semibold text-[rgb(var(--ec-page-text))]">
+            {selected.name || selected.id}
+            <span className="ml-2 font-mono text-[11px] font-normal text-[rgb(var(--ec-page-text-muted))]">
+              v{selected.version}
+            </span>
+          </span>
+        )}
+        <a
+          href={getSchemaRelationshipHref({ id: selected.id, version: selected.version, collection: 'flows' })}
+          className="inline-flex items-center gap-1 text-xs font-medium text-[rgb(var(--ec-accent))] hover:underline"
+        >
+          Open flow
+          <ArrowTopRightOnSquareIcon className="h-3.5 w-3.5" />
+        </a>
+        {selected.summary && <span className="basis-full text-xs text-[rgb(var(--ec-page-text-muted))]">{selected.summary}</span>}
+      </div>
+
+      {selected.graph ? (
+        <SchemaGraph
+          key={flowKey(selected)}
+          id={`schema-flow-${message.collection}-${message.data.id}-${message.data.version}-${flowKey(selected)}`}
+          graph={selected.graph}
+          showLegend={false}
+        />
+      ) : (
+        <p className="rounded-xl border border-dashed border-[rgb(var(--ec-page-border))] px-4 py-6 text-center text-xs text-[rgb(var(--ec-page-text-muted))]">
+          The diagram for this flow could not be built.
+        </p>
+      )}
+    </div>
+  );
+}

package/eventcatalog/src/components/SchemaExplorer/SchemaGraph.tsx

@@ -0,0 +1,47 @@
+import { useEffect, useState } from 'react';
+import AstroNodeGraph from '@components/MDX/NodeGraph/AstroNodeGraph';
+import type { MessageUsageGraph } from '@utils/schema-usage-graph';
+
+interface SchemaGraphProps {
+  /** Unique on the page: it names the portal element the visualiser mounts into. */
+  id: string;
+  graph: MessageUsageGraph;
+  /** CSS height of the graph box. Omit to fill the remaining height of a flex column parent. */
+  height?: string;
+  showLegend?: boolean;
+}
+
+/**
+ * A visualiser node graph inside the schema panel. The visualiser is browser-only, so the
+ * graph mounts after hydration into the portal element rendered here; the box keeps its
+ * height meanwhile so the tab does not jump.
+ */
+export default function SchemaGraph({ id, graph, height, showLegend = true }: SchemaGraphProps) {
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+  const portalId = `${id}-portal`;
+
+  return (
+    <>
+      <div
+        id={portalId}
+        className={`not-prose relative w-full overflow-hidden rounded-xl border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-card-bg))] ${height ? '' : 'min-h-[20em] flex-1'}`}
+        style={height ? { height } : undefined}
+      />
+      {mounted && (
+        <AstroNodeGraph
+          id={id}
+          nodes={graph.nodes}
+          edges={graph.edges}
+          mode="simple"
+          linkTo="docs"
+          showSearch={false}
+          includeKey={showLegend}
+          zoomOnScroll={false}
+          portalId={portalId}
+          disableMessageAnimation={true}
+        />
+      )}
+    </>
+  );
+}

package/eventcatalog/src/components/SchemaExplorer/SchemaPageViewer.tsx

@@ -1,3 +1,4 @@
+import type { ReactNode } from 'react';
 import SchemaDetailsPanel from './SchemaDetailsPanel';
 import type { SchemaItem } from './types';
 
@@ -7,6 +8,11 @@ interface SchemaPageViewerProps {
   apiAccessEnabled?: boolean;
   showOwners?: boolean;
   showProducersConsumers?: boolean;
+  /** Tab requested in the URL, resolved on the server to avoid a flash of the default tab. */
+  initialTab?: string;
+  /** Examples rendered on the server through the MDX pipeline, passed as the `examples` slot. */
+  examples?: ReactNode;
+  hasRenderedExamples?: boolean;
 }
 
 export default function SchemaPageViewer({
@@ -15,6 +21,9 @@ export default function SchemaPageViewer({
   apiAccessEnabled = false,
   showOwners = true,
   showProducersConsumers = true,
+  initialTab,
+  examples,
+  hasRenderedExamples = false,
 }: SchemaPageViewerProps) {
   const handleVersionChange = (version: string) => {
     // Construct new URL
@@ -32,6 +41,8 @@ export default function SchemaPageViewer({
       apiAccessEnabled={apiAccessEnabled}
       showOwners={showOwners}
       showProducersConsumers={showProducersConsumers}
+      initialTab={initialTab}
+      renderedExamples={hasRenderedExamples ? examples : undefined}
     />
   );
 }

package/eventcatalog/src/components/SchemaExplorer/SchemaUsage.tsx

@@ -0,0 +1,17 @@
+import SchemaGraph from './SchemaGraph';
+import type { SchemaItem } from './types';
+
+/** Producers, consumers and channels of the message, drawn with the same node graph as the docs page. */
+export default function SchemaUsage({ message }: { message: SchemaItem }) {
+  return (
+    <div className="flex h-full flex-col overflow-auto pr-1">
+      {message.graph ? (
+        <SchemaGraph id={`schema-usage-${message.collection}-${message.data.id}-${message.data.version}`} graph={message.graph} />
+      ) : (
+        <p className="rounded-xl border border-dashed border-[rgb(var(--ec-page-border))] px-4 py-6 text-center text-xs text-[rgb(var(--ec-page-text-muted))]">
+          No producers or consumers declared for this message.
+        </p>
+      )}
+    </div>
+  );
+}

package/eventcatalog/src/components/SchemaExplorer/types.ts

@@ -1,15 +1,33 @@
 import type { CollectionMessageTypes } from '@types';
 import type { MessageExample } from '@utils/collections/examples';
+import type { MessageUsageGraph } from '@utils/schema-usage-graph';
 export type { MessageExample };
 
-export interface Producer {
+/** A resource related to a message: something that produces or consumes it, or a flow that includes it. */
+export type SchemaRelationshipCollection = 'services' | 'agents' | 'data-products' | 'flows';
+
+export interface SchemaRelationship {
   id: string;
   version: string;
+  /** Which kind of resource produces or consumes the message. Defaults to a service when unknown. */
+  collection?: SchemaRelationshipCollection;
+  name?: string;
+  summary?: string;
+}
+
+export type Producer = SchemaRelationship;
+export type Consumer = SchemaRelationship;
+
+export interface FlowUsage extends SchemaRelationship {
+  /** The flow's diagram, as rendered by the visualiser. */
+  graph?: MessageUsageGraph;
 }
 
-export interface Consumer {
+/** A channel the message is published to. */
+export interface MessageChannel {
   id: string;
   version: string;
+  name?: string;
 }
 
 export interface Owner {
@@ -19,6 +37,21 @@ export interface Owner {
   href: string;
 }
 
+/** Where a remote schema was resolved from. Absent for schema files stored in the catalog. */
+export interface SchemaSourceInfo {
+  provider: string;
+  /** Browsable link to the schema, when the source provides one. */
+  url?: string;
+  repository?: string;
+  path?: string;
+  ref?: string;
+  commit?: string;
+  /** ISO 8601 timestamp of when the schema was first created in the source. */
+  createdAt?: string;
+  /** ISO 8601 timestamp of when the schema was last updated in the source. */
+  updatedAt?: string;
+}
+
 export interface SchemaItem {
   collection: CollectionMessageTypes | 'services' | 'domains' | 'data-products';
   data: {
@@ -29,6 +62,10 @@ export interface SchemaItem {
     schemaPath?: string;
     producers?: Producer[];
     consumers?: Consumer[];
+    /** Flows with a step that sends or receives this message. */
+    flows?: FlowUsage[];
+    /** Channels the message is published to. */
+    channels?: MessageChannel[];
     producerName?: string;
     owners?: Owner[];
   };
@@ -36,6 +73,11 @@ export interface SchemaItem {
   /** Internal URL for loading this version's content without embedding it in the page. */
   contentUrl?: string;
   schemaExtension?: string;
+  /** The schema reference used by the message, for example `source://contracts/events/OrderPlaced.schema.json`. */
+  schemaRef?: string;
+  /** Display name of the schema entry itself, as declared on the message or reported by the source. */
+  schemaName?: string;
+  source?: SchemaSourceInfo;
   specType?: string;
   specName?: string;
   specFilenameWithoutExtension?: string;
@@ -45,12 +87,15 @@ export interface SchemaItem {
   dataProductVersion?: string;
   // Examples
   examples?: MessageExample[];
+  /** Producer → message → consumer graph for the Usage tab, as rendered by the visualiser. */
+  graph?: MessageUsageGraph;
 }
 
 export interface SchemaDetails {
   schemaContent: string;
   examples: MessageExample[];
-  data?: Pick<SchemaItem['data'], 'producers' | 'consumers'>;
+  graph?: MessageUsageGraph;
+  data?: Pick<SchemaItem['data'], 'producers' | 'consumers' | 'flows' | 'channels'>;
 }
 
 export interface VersionDiff {

package/eventcatalog/src/components/SchemaExplorer/utils.ts

@@ -1,3 +1,6 @@
+import type { SchemaRelationshipCollection } from './types';
+import { buildUrl } from '@utils/url-builder';
+
 // Schema types that should use SVG icons
 export const ICON_SPECS: Record<string, string> = {
   openapi: 'openapi',
@@ -45,14 +48,38 @@ export function extractServiceName(refId: string): string {
 export function getSchemaRelationshipReference(reference: {
   id: string;
   version?: string;
-  data?: { id: string; version: string };
+  collection?: string;
+  name?: string;
+  summary?: string;
+  data?: { id: string; version: string; name?: string; summary?: string };
 }) {
+  const collection = (
+    reference.collection === 'agents' || reference.collection === 'data-products' || reference.collection === 'flows'
+      ? reference.collection
+      : 'services'
+  ) as SchemaRelationshipCollection;
   return {
     id: reference.data?.id ?? reference.id,
     version: reference.data?.version ?? reference.version,
+    collection,
+    name: reference.data?.name ?? reference.name,
+    summary: reference.data?.summary ?? reference.summary,
   };
 }
 
+export const SCHEMA_RELATIONSHIP_LABELS: Record<SchemaRelationshipCollection, string> = {
+  services: 'Service',
+  agents: 'Agent',
+  'data-products': 'Data Product',
+  flows: 'Flow',
+};
+
+export const getSchemaRelationshipHref = (reference: {
+  id: string;
+  version?: string;
+  collection: SchemaRelationshipCollection;
+}) => buildUrl(`/docs/${reference.collection}/${reference.id}/${reference.version}`);
+
 export const getLanguageForHighlight = (extension?: string): string => {
   if (!extension) return 'json';
   const ext = extension.toLowerCase();

package/eventcatalog/src/content.config.ts

@@ -1193,6 +1193,10 @@ const schemas = defineCollection({
         url: z.string().optional(),
         ref: z.string().optional(),
         branch: z.string().optional(),
+        repository: z.string().optional(),
+        commit: z.string().optional(),
+        createdAt: z.string().optional(),
+        updatedAt: z.string().optional(),
       }),
       readOnly: z.boolean().optional(),
     })
@@ -1266,10 +1270,34 @@ const sidebars = defineCollection({
   schema: sidebarSchema,
 });
 
+/**
+ * Usage examples: Markdown or MDX files inside a message's `examples/` folder. Loaded as a
+ * collection so they render through the MDX pipeline with EventCatalog's custom components.
+ */
+const examples = defineCollection({
+  loader: globWithSafeWatcher({
+    pattern: withIgnoredBuildArtifacts([
+      '**/events/*/examples/**/*.(md|mdx)',
+      '**/events/*/versioned/*/examples/**/*.(md|mdx)',
+      '**/commands/*/examples/**/*.(md|mdx)',
+      '**/commands/*/versioned/*/examples/**/*.(md|mdx)',
+      '**/queries/*/examples/**/*.(md|mdx)',
+      '**/queries/*/versioned/*/examples/**/*.(md|mdx)',
+    ]),
+    base: projectDirBase,
+    generateId: ({ entry }) => entry,
+  }),
+  schema: z.object({
+    title: z.string().optional(),
+    summary: z.string().optional(),
+  }),
+});
+
 export const collections = {
   events,
   commands,
   queries,
+  examples,
   services,
   agents,
   adrs,

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

@@ -1,9 +1,12 @@
 ---
-import { Code } from 'astro-expressive-code/components';
+import { marked } from 'marked';
+import path from 'node:path';
+import { getCollection, render } from 'astro:content';
+import components from '@components/MDX/components';
+import { getExampleEntriesForMessage } from '@utils/collections/examples';
 import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
 import Footer from '@layouts/Footer.astro';
 import { Page } from './_[...filename].data';
-import { getLanguageForHighlight } from '@components/SchemaExplorer/utils';
 
 export const prerender = Page.prerender;
 export const getStaticPaths = Page.getStaticPaths;
@@ -12,7 +15,13 @@ const props = await Page.getData(Astro);
 const { collection, data, example } = props;
 
 const pageTitle = `${collection} | ${data.name} | ${example.title}`.replace(/^\w/, (c: string) => c.toUpperCase());
-const lang = getLanguageForHighlight(example.extension);
+// Prefer the MDX pipeline so EventCatalog components work; fall back to plain Markdown.
+const examplesDir = path.join(path.dirname(props.filePath ?? ''), 'examples');
+const exampleEntry = getExampleEntriesForMessage(await getCollection('examples'), props.filePath).find(
+  (entry) => path.relative(examplesDir, entry.filePath ?? '').replace(/\\/g, '/') === example.fileName
+);
+const Content = exampleEntry ? (await render(exampleEntry)).Content : undefined;
+const exampleHtml = !Content && example.renderMode === 'markdown' ? await marked.parse(example.content) : '';
 ---
 
 <VerticalSideBarLayout title={pageTitle} description={`Example: ${example.title} for ${data.name}`}>
@@ -24,14 +33,36 @@ const lang = getLanguageForHighlight(example.extension);
             {example.title}
           </h1>
           <h2 class="text-lg text-[rgb(var(--ec-page-text-muted))] font-medium mb-1">
-            Example for {data.name} <span class="text-[rgb(var(--ec-page-text-muted))]">(v{data.version})</span>
+            Example for {data.name}
+            <span class="text-[rgb(var(--ec-page-text-muted))]">(v{data.version})</span>
           </h2>
         </div>
 
         <div class="mt-6">
-          <div class="not-prose overflow-x-auto">
-            <Code code={example.content} title={example.fileName} lang={lang} />
-          </div>
+          {example.summary && <p class="mb-4 text-[rgb(var(--ec-page-text-muted))]">{example.summary}</p>}
+          {
+            Content ? (
+              <div class="prose prose-md max-w-none">
+                <Content components={components(props)} />
+              </div>
+            ) : example.renderMode === 'markdown' ? (
+              <div class="prose prose-md max-w-none" set:html={exampleHtml} />
+            ) : (
+              <pre class="overflow-auto rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-code-bg))] p-5 text-sm">
+                <code>{example.content}</code>
+              </pre>
+            )
+          }
+          {
+            example.usage && (
+              <section class="mt-6">
+                <h2 class="mb-2 text-sm font-semibold uppercase tracking-wider text-[rgb(var(--ec-page-text-muted))]">Usage</h2>
+                <pre class="overflow-auto rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-code-bg))] p-5 text-sm">
+                  <code>{example.usage}</code>
+                </pre>
+              </section>
+            )
+          }
         </div>
 
         <Footer />