@eventcatalog/core 4.2.2 → 4.2.4

package/dist/docs/development/customization/08-custom-properties.md

@@ -0,0 +1,176 @@
+---
+sidebar_position: 6
+keywords:
+- EventCatalog custom properties
+- resource metadata
+- custom frontmatter
+sidebar_label: Resource custom properties
+title: Custom properties on resources
+description: Add organization-specific metadata to EventCatalog resources and render it in Markdown or custom components.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="4.2.3" />
+
+Custom properties let you add organization-specific metadata to a resource without changing EventCatalog's built-in resource model.
+
+Custom property names must:
+
+- be defined at the top level of the resource frontmatter
+- start with `x-`
+- contain at least one character after `x-`
+
+Their values can be strings, numbers, booleans, arrays, or nested objects.
+
+```markdown title="/services/PaymentAPI/index.mdx"
+---
+id: PaymentAPI
+name: Payment API
+version: 1.0.0
+summary: Authorizes and records payments.
+x-operational-tier: 1
+x-scrum-masters:
+  - David
+  - Andrew
+x-on-call:
+  schedule: payments-primary
+  escalation-channel: '#payments-incidents'
+---
+```
+
+You can add custom properties to domains, systems, services, agents, events, commands, queries, channels, flows, containers, entities, data products, diagrams, and ADRs.
+
+## Why use custom properties?
+
+EventCatalog provides first-class fields for common concepts such as owners, messages, relationships, schemas, and repositories. Custom properties are useful when your organization needs metadata that is specific to its own platform or processes.
+
+For example, you can use them to record:
+
+- operational tiers, recovery objectives, or on-call schedules
+- data classification, retention, or compliance requirements
+- internal cost centres or business capabilities
+- maturity scores or governance review dates
+- metadata consumed by generators, plugins, or custom components
+
+Custom properties are also useful when you want to introduce an internal convention gradually without requiring EventCatalog to understand or interpret the value.
+
+:::tip
+Use EventCatalog's built-in fields when they already describe the concept. Use custom properties for metadata that is specific to your organization.
+:::
+
+## Render all custom properties
+
+Add the `CustomProperties` component to the Markdown content of a resource to render every `x-*` property.
+
+`CustomProperties` and `CustomProperty` are built-in components, so you do not need to import them.
+
+```jsx title="/services/PaymentAPI/index.mdx"
+<CustomProperties />
+```
+
+By default, the component uses **Custom properties** as its heading. Use the `title` prop to change it.
+
+```jsx
+<CustomProperties title="Operational metadata" />
+```
+
+Property names are converted into readable labels. For example, `x-operational-tier` is displayed as **Operational Tier**. The original `x-*` name is available from the information icon beside the label.
+
+Arrays are rendered as lists and nested objects are rendered as grouped values.
+
+![Custom properties rendered on an architecture decision record](/img/docs/components/custom-properties.png)
+
+These component and JavaScript expression examples require an `.mdx` resource file. Plain `.md` files do not evaluate MDX components or expressions.
+
+## Render one custom property
+
+Use `CustomProperty` when you only want to show one value.
+
+```jsx title="/services/PaymentAPI/index.mdx"
+<CustomProperty name="x-operational-tier" />
+```
+
+You can override the generated label.
+
+```jsx
+<CustomProperty name="x-scrum-masters" label="Scrum masters" />
+```
+
+If the named property is not present on the resource, the component renders nothing.
+
+## Reference custom properties in Markdown
+
+Resource frontmatter is available through the `frontmatter` variable. Because custom property names contain hyphens, use JavaScript bracket notation.
+
+```jsx title="/services/PaymentAPI/index.mdx"
+## Operations
+
+Operational tier: {frontmatter['x-operational-tier']}
+```
+
+Dot notation does not work:
+
+```jsx
+{/* This is interpreted as subtraction and causes a runtime error. */}
+{frontmatter.x-operational-tier}
+```
+
+Render an array by mapping over its value.
+
+```jsx
+<ul>
+  {frontmatter['x-scrum-masters']?.map((name) => (
+    <li>{name}</li>
+  ))}
+</ul>
+```
+
+Nested object values can be referenced in the same way.
+
+```jsx
+On-call schedule: {frontmatter['x-on-call'].schedule}
+```
+
+## Pass custom properties to your own components
+
+Custom components do not receive resource frontmatter automatically. Pass the values they need as props.
+
+```jsx title="/services/PaymentAPI/index.mdx"
+import OperationalMetadata from '@catalog/components/operational-metadata.astro';
+
+<OperationalMetadata
+  tier={frontmatter['x-operational-tier']}
+  scrumMasters={frontmatter['x-scrum-masters']}
+/>
+```
+
+Read those props in your Astro component.
+
+```jsx title="/components/operational-metadata.astro"
+---
+interface Props {
+  tier: number;
+  scrumMasters?: string[];
+}
+
+const { tier, scrumMasters = [] } = Astro.props;
+---
+
+<section class="not-prose">
+  <p>Operational tier: {tier}</p>
+  <ul>
+    {scrumMasters.map((name) => <li>{name}</li>)}
+  </ul>
+</section>
+```
+
+Read [Pass data into components](/docs/development/components/custom-components/pass-data-into-components) to learn more about using resource frontmatter with your own components.
+
+## Naming and security guidance
+
+- Use stable, descriptive names such as `x-operational-tier` or `x-data-classification`.
+- Consider an organization namespace, such as `x-acme-cost-centre`, when properties may be shared across tools.
+- Keep the meaning and expected value type consistent across resources.
+- Do not store secrets, credentials, or private tokens in custom properties. Resource frontmatter is catalog content and may be included in generated output.
+- Custom properties are stored and rendered, but EventCatalog does not automatically use them for relationships, diagrams, search behavior, or validation beyond the `x-*` naming requirement.

package/dist/docs/development/customization/customize-visualizer/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Customize Visualizer",
-  "position": 8,
+  "position": 10,
   "collapsible": true,
   "collapsed": true,
   "link": {

package/dist/docs/development/deployment/build-ssr-mode.md

@@ -47,4 +47,12 @@ This will output one directory
 
 You will need to deploy your EventCatalog to a server that can run Node.js.
 
-The easiest way to do this is to use [a docker container](/docs/development/deployment/hosting-options#hosting-static-website-with-docker).
+The easiest way to do this is to use [a docker container](/docs/development/deployment/hosting-options#hosting-static-website-with-docker).
+
+## Loading indicator
+
+<AddedIn version="4.2.4" />
+
+Server-side rendering means a page's render time depends on your server, so navigations can occasionally take longer than a static build.
+
+EventCatalog shows a thin progress bar at the top of the page during navigations that take longer than 200ms, so the catalog never looks unresponsive. It works automatically and needs no configuration.

package/dist/docs/development/guides/domains/09-reference.md

@@ -515,3 +515,7 @@ The attachments can be a URL string or an object with additional properties.
 | `description` | `string` | No | The description of the attachment. |
 | `type` | `string` | No | The type of the attachment, used to group attachments in the UI. |
 | `icon` | `string` | No | The icon of the attachment. You can pick from the [lucide icons](https://lucide.dev/icons/) library. |
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

package/dist/docs/development/guides/resources/adrs/06-reference.md

@@ -245,3 +245,7 @@ appliesTo:
 ```
 
 Supported resource types include `agent`, `service`, `system`, `event`, `command`, `query`, `flow`, `channel`, `domain`, `user`, `team`, `container`, `entity`, `diagram`, and `data-product`.
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

package/dist/docs/development/guides/resources/agents/11-reference.md

@@ -236,3 +236,7 @@ tools:
     description: Retrieves order status and recent order events.
 ---
 ```
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

package/dist/docs/development/guides/resources/data/04-reference.md

@@ -209,3 +209,7 @@ badges:
     textColor: green
 ---
 ```
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

package/dist/docs/development/guides/resources/data-products/07-reference.md

@@ -199,3 +199,7 @@ outputs:
       type: avro
 ---
 ```
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

package/dist/docs/development/guides/resources/entities/06-reference.md

@@ -271,3 +271,7 @@ Use `<EntityPropertiesTable />` in the entity Markdown body to render the entity
 ```
 
 This is useful when you want the documentation page to show the same properties defined in frontmatter.
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

package/dist/docs/development/guides/resources/flows/06-reference.md

@@ -224,3 +224,7 @@ steps:
     next_step: submit-order
 ---
 ```
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

package/dist/docs/development/guides/resources/messages/04-connect-messages/02-shared-messages-across-boundaries.md

@@ -4,6 +4,7 @@ keywords:
 sidebar_label: Patterns for shared messages
 title: Patterns for shared messages
 description: Understand the patterns for shared messages in EventCatalog.
+sidebar_position: 3
 ---
 
 import ProjectTree from '@site/src/components/MDX/ProjectTree';

package/dist/docs/development/guides/resources/messages/04-connect-messages/04-map-commands-to-events.md

@@ -0,0 +1,95 @@
+---
+keywords:
+- EventCatalog command events
+- command outcomes
+- map commands to events
+sidebar_label: Map commands to events
+title: Map commands to events
+description: Document which events a command can trigger, including the events produced in different scenarios.
+sidebar_position: 2
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="4.2.0" />
+
+Commands often produce one of several events. For example, a `CreateOrder` command may produce `OrderCreated` when it succeeds or `OrderRejected` when it fails.
+
+EventCatalog lets you document these relationships so teams can see which events to expect from a command and which commands can produce a specific event.
+
+![Cancel Order command mapped to the Order Cancelled event through the Order Service](./imgs/cancel-order-command-to-event.png)
+
+## Connect a command to events
+
+Commands are `received` from particular resources in EventCatalog (e.g services). When you receive a command, you can also specify what events are triggered downstream, you do this by using the `triggers` property.
+
+In the example below, the `OrderService` receives the `CreateOrder` (command) and we also specify that htis command is linked to and triggers the `OrderCreated` and `OrderRejected` event.
+
+
+```md title="/services/OrderService/index.mdx"
+---
+id: OrderService
+version: 1.0.0
+name: Order service
+receives:
+  # receives the CreateOrder Command
+  - id: CreateOrder
+    version: 1.0.0
+    # Tell EventCatalog that the CreateOrderCommand
+    # in this context will trigger the OrderCreated and Rejeected events.
+    triggers:
+      - id: OrderCreated
+        version: 1.0.0
+      - id: OrderRejected
+        version: 1.0.0
+---
+```
+
+The command and every event it triggers must already exist in your catalog before EventCatalog can resolve the relationship.
+
+## Describe different scenarios
+
+Add an optional `condition` to explain the scenario in which an event is produced. Conditions are useful for success and failure outcomes, business-rule branches, or different paths that produce the same event.
+
+```md title="/services/OrderService/index.mdx"
+---
+id: OrderService
+version: 1.0.0
+name: Order service
+receives:
+  - id: CreateOrder
+    version: 1.0.0
+    triggers:
+      - id: OrderCreated
+        version: 1.0.0
+        # specify the scenario when this event would be triggered
+        condition: When payment is authorized and stock is available
+---
+```
+
+This lets you document common command-handling scenarios such as:
+
+- A command producing a success event or a failure event.
+- A command producing different events based on a business rule.
+- Multiple paths producing the same event for different reasons.
+- Different services producing different events from the same command.
+
+| Property | Type | Required | Description |
+| -------- | ---- | -------- | ----------- |
+| `id` | `string` | Yes | Id of the event produced by the command. |
+| `version` | `string` | No | Version or semver range of the event. Defaults to `latest`. |
+| `condition` | `string` | No | Scenario in which the command produces the event. |
+
+The `version` on the received command also defaults to `latest` when omitted.
+
+## Explore command and event relationships
+
+The command page lists its events under **Triggers**. Each event page lists the commands that can produce it under **Triggered by**. Message maps also show the command, the resource handling it, and the resulting events.
+
+The example below shows the `Cancel Order` command mapped to the `Order Cancelled` event through the `Order Service`, including the scenario in which the event is produced.
+
+![Cancel Order command mapped to the Order Cancelled event through the Order Service](./imgs/cancel-order-command-to-event.png)
+
+Select **Map commands to events** under **Architecture** to compare these relationships. EventCatalog draws each command-to-event path through the receiving service or domain and groups repeated paths into selectable scenarios.
+
+The **Map commands to events** link is only generated for messages that participate in at least one resolved relationship.

package/dist/docs/development/guides/resources/messages/04-message-channels/05-reference.md

@@ -175,3 +175,7 @@ Supported values are `at-most-once`, `at-least-once`, and `exactly-once`.
 deliveryGuarantee: at-least-once
 ---
 ```
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

package/dist/docs/development/guides/resources/messages/10-reference.md

@@ -437,3 +437,7 @@ schemas:
     format: jsonschema
 ---
 ```
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

package/dist/docs/development/guides/resources/services/08-reference.md

@@ -8,6 +8,8 @@ title: Services reference
 description: Frontmatter fields, paths, and routes for services in EventCatalog.
 ---
 
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
 This page lists the fields, paths, and routes supported by services.
 
 ## Paths
@@ -132,6 +134,12 @@ receives:
 ---
 ```
 
+#### Map commands to events
+
+<AddedIn version="4.2.0" />
+
+Each received command can declare the events it triggers. See [Map commands to events](/docs/development/guides/resources/messages/connect-messages/map-commands-to-events) for the supported fields, scenarios, and generated views.
+
 ### `entities` {#entities}
 
 - Type: `array`
@@ -293,3 +301,7 @@ flows:
 ```
 
 If `version` is omitted, EventCatalog uses the latest version.
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

package/dist/docs/development/guides/systems/06-reference.md

@@ -327,3 +327,7 @@ actors:
 | `name` | `string` | Display name shown in diagrams. Optional. |
 | `label` | `string` | Text shown on the actor relationship edge. Optional. |
 | `direction` | `inbound` or `outbound` | `inbound` means actor to system. `outbound` means system to actor. Defaults to `inbound`. |
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

package/dist/eventcatalog.cjs

@@ -144,7 +144,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "4.2.2";
+var version = "4.2.4";
 
 // src/constants.ts
 var VERSION = version;

package/dist/eventcatalog.js

@@ -1,6 +1,6 @@
 import {
   log_build_default
-} from "./chunk-HIQ22EHS.js";
+} from "./chunk-GCEFDCZB.js";
 import "./chunk-K2XIENVT.js";
 import {
   runMigrations
@@ -14,10 +14,10 @@ import {
 } from "./chunk-B7HCX5HM.js";
 import {
   generate
-} from "./chunk-JV33GNVZ.js";
+} from "./chunk-WVIOZDVK.js";
 import {
   logger
-} from "./chunk-Z2CMR4HM.js";
+} from "./chunk-5MIGBCON.js";
 import {
   resolve_catalog_dependencies_default
 } from "./chunk-LHR4G2UO.js";
@@ -27,7 +27,7 @@ import {
 import {
   watch
 } from "./chunk-CAJUIMDJ.js";
-import "./chunk-ZGQNCIRW.js";
+import "./chunk-BXEGST4Z.js";
 import {
   createAstroDevLineFilter,
   createAstroLineFilter
@@ -38,7 +38,7 @@ import {
 import "./chunk-W5JQON7Z.js";
 import {
   VERSION
-} from "./chunk-A5LDEHRI.js";
+} from "./chunk-J2MVHSKA.js";
 import {
   linkCoreNodeModules,
   resolveInstalledCoreNodeModules

package/dist/generate.cjs

@@ -108,7 +108,7 @@ var getEventCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "4.2.2";
+var version = "4.2.4";
 
 // src/constants.ts
 var VERSION = version;

package/dist/generate.js

@@ -1,8 +1,8 @@
 import {
   generate
-} from "./chunk-JV33GNVZ.js";
-import "./chunk-Z2CMR4HM.js";
-import "./chunk-A5LDEHRI.js";
+} from "./chunk-WVIOZDVK.js";
+import "./chunk-5MIGBCON.js";
+import "./chunk-J2MVHSKA.js";
 import "./chunk-6QENHZZP.js";
 export {
   generate

package/dist/utils/cli-logger.cjs

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(cli_logger_exports);
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "4.2.2";
+var version = "4.2.4";
 
 // src/constants.ts
 var VERSION = version;

package/dist/utils/cli-logger.js

@@ -1,7 +1,7 @@
 import {
   logger
-} from "../chunk-Z2CMR4HM.js";
-import "../chunk-A5LDEHRI.js";
+} from "../chunk-5MIGBCON.js";
+import "../chunk-J2MVHSKA.js";
 export {
   logger
 };

package/eventcatalog/src/components/MDX/CustomProperties/CustomProperties.astro

@@ -0,0 +1,39 @@
+---
+import CustomPropertyRow from './CustomPropertyRow.astro';
+import { getCustomProperties } from './custom-properties';
+
+interface Props {
+  title?: string;
+  data?: Record<string, unknown>;
+}
+
+const { title = 'Custom properties', data } = Astro.props;
+const properties = getCustomProperties(data);
+---
+
+{
+  properties.length > 0 && (
+    <section class="not-prose my-8">
+      {title && <h3 class="mb-4 text-xl font-semibold text-[rgb(var(--ec-page-text))]">{title}</h3>}
+      <div class="overflow-x-auto">
+        <table class="w-full border-collapse text-left text-sm text-[rgb(var(--ec-page-text-muted))]">
+          <thead>
+            <tr class="border-b border-[rgb(var(--ec-page-border))] text-[rgb(var(--ec-page-text))]">
+              <th scope="col" class="py-3 pr-6 font-semibold">
+                Property
+              </th>
+              <th scope="col" class="py-3 font-semibold">
+                Value
+              </th>
+            </tr>
+          </thead>
+          <tbody class="divide-y divide-[rgb(var(--ec-page-border))]">
+            {properties.map((property) => (
+              <CustomPropertyRow property={property} />
+            ))}
+          </tbody>
+        </table>
+      </div>
+    </section>
+  )
+}

package/eventcatalog/src/components/MDX/CustomProperties/CustomProperty.astro

@@ -0,0 +1,37 @@
+---
+import CustomPropertyRow from './CustomPropertyRow.astro';
+import { getCustomProperty } from './custom-properties';
+
+interface Props {
+  name: string;
+  label?: string;
+  data?: Record<string, unknown>;
+}
+
+const { name, label, data } = Astro.props;
+const property = getCustomProperty(data, name);
+
+if (property && label) property.label = label;
+---
+
+{
+  property && (
+    <div class="not-prose my-6 overflow-x-auto">
+      <table class="w-full border-collapse text-left text-sm text-[rgb(var(--ec-page-text-muted))]">
+        <thead>
+          <tr class="border-b border-[rgb(var(--ec-page-border))] text-[rgb(var(--ec-page-text))]">
+            <th scope="col" class="py-3 pr-6 font-semibold">
+              Property
+            </th>
+            <th scope="col" class="py-3 font-semibold">
+              Value
+            </th>
+          </tr>
+        </thead>
+        <tbody class="divide-y divide-[rgb(var(--ec-page-border))]">
+          <CustomPropertyRow property={property} />
+        </tbody>
+      </table>
+    </div>
+  )
+}

package/eventcatalog/src/components/MDX/CustomProperties/CustomPropertyRow.astro

@@ -0,0 +1,37 @@
+---
+import CustomPropertyValue from './CustomPropertyValue.astro';
+import type { CustomProperty } from './custom-properties';
+import { InformationCircleIcon } from '@heroicons/react/24/outline';
+
+interface Props {
+  property: CustomProperty;
+}
+
+const { property } = Astro.props;
+---
+
+<tr class="hover:bg-[rgb(var(--ec-content-hover))]">
+  <td class="w-1/3 min-w-48 py-4 pr-6 align-top font-medium text-[rgb(var(--ec-page-text))]">
+    <span class="inline-flex items-center gap-1.5">
+      {property.label}
+      <span class="group relative inline-flex">
+        <button
+          type="button"
+          class="inline-flex cursor-help text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] focus:outline-hidden focus:ring-2 focus:ring-[rgb(var(--ec-accent))] focus:ring-offset-2"
+          aria-label={`Frontmatter property: ${property.name}`}
+        >
+          <InformationCircleIcon className="h-4 w-4" aria-hidden="true" />
+        </button>
+        <span
+          role="tooltip"
+          class="pointer-events-none absolute left-full top-1/2 z-20 ml-2 -translate-y-1/2 whitespace-nowrap rounded-md bg-[rgb(var(--ec-page-text))] px-2.5 py-1.5 text-xs font-medium text-[rgb(var(--ec-page-bg))] opacity-0 shadow-lg transition-opacity group-hover:opacity-100 group-focus-within:opacity-100"
+        >
+          {property.name}
+        </span>
+      </span>
+    </span>
+  </td>
+  <td class="min-w-0 py-4 align-top text-sm">
+    <CustomPropertyValue value={property.value} />
+  </td>
+</tr>