@eventcatalog/core 3.35.0 → 3.35.1

package/dist/docs/development/components/components/11-message-table.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 2
+keywords:
+- components
+sidebar_label: MessageTable
+title: MessageTable
+description: Component for displaying messages for services and domains in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.26.0" />
+
+The `<MessageTable/>` component renders a table of messages for a service or domain in EventCatalog.
+
+The component renders a paginated table of messages, with the ability to filter by message type (event, command, query), and text search.
+
+### Use case
+
+- Display all the messages that a service sends and receives.
+- Display all the messages that a domain sends and receives.
+  - These are all messages that are sent and received in child services of the domain.
+
+**Basic Example**
+
+```jsx /domains/MyDomain/index.mdx
+<MessageTable limit={10} showChannels={true} />
+```
+### Output
+![Example output](./img/message-table.png)
+
+See the [demo](https://demo.eventcatalog.dev/docs/domains/Orders/0.0.3) for a full example.
+
+### Props
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `format`                  | `string`  | 'all'           | Which messages to render. `all` will render messages that are sent and received. `sends` will render messages that are sent and `receives` will render messages that are received.                               |
+| `limit`             | `number`  | 10           | The number of messages to render in the table. Results are paginated. |
+| `showChannels`             | `boolean`  | true           | Whether to show the channel information in the table for each message. |
+
+### Support
+
+The `<MessageTable/>` component is supported in domains and services.

package/dist/docs/development/components/components/12-nodegraph.md

@@ -0,0 +1,167 @@
+---
+sidebar_position: 3
+keywords:
+- components
+sidebar_label: NodeGraph
+title: NodeGraph
+description: Component for EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+A component to visually render your information.
+
+The `<NodeGraph/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.
+
+### Single NodeGraph
+
+**Example**
+
+```jsx /events/MyEvents/index.mdx
+<NodeGraph/>
+```
+
+#### Output
+![Example output](./img/nodegraph.png)
+
+#### Props
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `maxHeight` (optional)             | `string`  | 30           | Max height to set the nodegraph in your document|
+| `search` (optional)             | `boolean`  | true           | Show or hide the search bar in the nodegraph _(Added in v2.50.3)_ |
+| `legend` (optional)             | `boolean`  | true           | Show or hide the legend in the nodegraph _(Added in v2.50.3)_ |
+| `mode` (optional)             | `string` ("simple" or "full")  | "simple"           | `simple` will render the nodegraph in a simplfied view not rendering descriptions. Full will render the nodegraph in a full view, rendering descriptions and other information _(Added in v2.50.3)_|
+
+
+## Interactive controls
+
+<AddedIn version="3.9.0" />
+
+All NodeGraph visualizations include interactive controls for better viewing, exploration, and sharing.
+
+![NodeGraph interactive controls](./img/interactive-controls.png)
+
+### View modes
+
+Switch between two visualization modes using the view switcher dropdown.
+
+**React Flow** - Interactive node-based visualization with drag and pan controls.
+
+**Mermaid** - Standard Mermaid diagram view with automatic layout and pan/zoom controls.
+
+### Export as Mermaid
+
+Copy the NodeGraph as Mermaid diagram code to your clipboard. The diagram preserves all nodes, edges, and styling information.
+
+Useful for sharing architectures with LLMs, documentation tools, or pasting into Mermaid-compatible renderers like [mermaid.live](https://mermaid.live).
+
+:::tip Large diagram exports
+If you export large NodeGraphs and they fail to render as Mermaid diagrams, increase the `maxTextSize` configuration. [Learn more about maxTextSize](/docs/api/config#mermaid).
+:::
+
+### Share URL
+
+Copy the current page URL to share the visualization with your team.
+
+## Layout persistence
+
+<AddedIn version="3.11.0" />
+
+Save and restore custom node positions in the visualizer during development.
+
+When you drag nodes to arrange your visualization, a "Layout changed" indicator appears with a quick save button. Layouts are saved to `_data/visualizer-layouts/` as JSON files and can be committed to git to share with your team.
+
+:::info Dev mode only
+Layout persistence is only available when running EventCatalog in development mode (`npm run start`). This ensures saved layouts don't affect production builds.
+:::
+
+### Saving layouts
+
+Drag any node to reposition it. When changes are detected, the "Layout changed" indicator appears in the bottom-left corner with a quick save button.
+
+You can also save layouts from the dropdown menu:
+
+1. Click the menu icon (three dots) in the top-right corner
+2. Select **Layout** > **Save Layout**
+
+Layouts are saved to `_data/visualizer-layouts/{collection}/{id}/{version}.json` in your catalog directory.
+
+### Resetting layouts
+
+Reset a saved layout to return to auto-positioning:
+
+1. Click the menu icon (three dots) in the top-right corner
+2. Select **Layout** > **Reset Layout**
+3. Confirm the reset
+
+This deletes the saved layout file and reloads the page with auto-calculated positions.
+
+### Layout files
+
+Layout files are keyed by resource (collection/id/version), so the same layout is used whether viewing in the visualizer or embedded in documentation.
+
+Works across all visualizers including services, events, flows, domains, entity maps, and designs.
+
+**Example layout file structure:**
+
+```json
+{
+  "version": 1,
+  "savedAt": "2026-01-29T12:00:00.000Z",
+  "resourceKey": "services/OrderService/1.0.0",
+  "positions": {
+    "node-1": { "x": 100, "y": 200 },
+    "node-2": { "x": 300, "y": 400 }
+  }
+}
+```
+
+### Sharing layouts with your team
+
+Saved layouts can be committed to git and shared with your team. When team members pull the changes, they'll see the same node positions in their local development environment.
+
+Add the layout directory to your git repository:
+
+```bash
+git add _data/visualizer-layouts
+git commit -m "Add custom visualizer layouts"
+```
+
+
+### Multiple NodeGraphs
+
+<AddedIn version="2.37.3" />
+
+You can add multiple NodeGraphs to your document by using the `NodeGraph` component multiple times.
+
+Here is an example of how to add multiple NodeGraphs to your document:
+
+```jsx /events/MyEvents/index.mdx
+<!-- Without any properties, this will render the current pages NodeGraph like you see in the above example -->
+<NodeGraph/>
+
+<!--  -->
+<div class="grid grid-cols-2 gap-4 not-prose">
+  <!-- We tell EventCatalog to render the Orders Domain version 0.0.3 NodeGraph -->
+  <NodeGraph id="Orders" version="0.0.3" type="domain" />
+  <!-- We tell EventCatalog to render the Subscription Domain version 0.0.1 NodeGraph -->
+  <NodeGraph id="Subscription" version="0.0.1" type="domain" />
+</div>
+```
+
+#### Output
+![Example output](./img/multi-nodegraph.png)
+
+You can see a demo of this [here](https://demo.eventcatalog.dev/docs/domains/E-Commerce/1.0.0)
+
+#### Props
+
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `id`                    | `string`  | `undefined`       | The id of the NodeGraph to render. If not provided, the current page's NodeGraph will be rendered. |
+| `version`               | `string`  | `undefined`       | The version of the NodeGraph to render. If not provided, the current page's NodeGraph will be rendered. |
+| `type`                  | `string`  | `undefined`       | The type of the NodeGraph to render. If not provided, the current page's NodeGraph will be rendered. |
+
+
+
+

package/dist/docs/development/components/components/13-openapi.md

@@ -0,0 +1,55 @@
+---
+sidebar_position: 4
+keywords:
+- components
+sidebar_label: OpenAPI
+title: OpenAPI
+description: Component for EventCatalog
+---
+
+
+:::warning
+This component is now deprecated. Please read the frontmatter API documentation [here](/docs/development/guides/services/adding-to-services/openapi).
+:::
+
+You can add specifications to any service in EventCatalog using the specifications frontmatter API. You can read more about it [here](/docs/development/guides/services/adding-to-services/openapi).
+
+If you are interested in automating your EventCatalog with OpenAPI files, you can use the [OpenAPI plugin](/docs/plugins/openapi/intro).
+
+<!-- A component to render [OpenAPI specification files](https://swagger.io/specification/) into EventCatalog.
+
+:::tip
+ OpenAPI files can be great for your services. Remember you can version your services and all files that associate with it. This allows you to version your OpenAPI files with EventCatalog.
+:::
+
+### Usage
+
+1. Add your `openapi.yml` file to your folder
+    - e.g `/events/MyEvent/openapi.yml`
+
+When you include the component three things happen:
+
+- You get a section in your document with a link to the spec file
+- A button is rendered in the sidebar for the document
+- A new page is rendered loading the OpenAPI file.
+
+**Example**
+
+```jsx /events/MyEvents/index.mdx
+<OpenAPI/>
+```
+
+### Output
+![Example output](./img/openapi.png)
+
+**New page that is created for your OpenAPI spec**
+
+![Example openapi page](./img/openapi-page.png)
+
+### Props
+
+_No configuration required._ -->
+
+### Support
+
+The `<OpenAPI/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.

package/dist/docs/development/components/components/14-prompt.md

@@ -0,0 +1,69 @@
+---
+sidebar_position: 18
+keywords:
+  - components
+  - prompt
+  - ai
+  - cursor
+  - clipboard
+sidebar_label: Prompt
+title: Prompt
+description: Embed copyable AI prompts into resource documentation
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.32.2" />
+
+`<Prompt />` lets you embed ready-to-use AI prompts directly in your documentation pages. Readers can copy the prompt to their clipboard or open it straight in Cursor with one click.
+
+Place the prompt text as the slot content and configure the label and actions via props.
+
+**Copy only (default)**
+
+```jsx /events/OrderCreated/index.mdx
+<Prompt description="Generate test cases for this event">
+  You are a senior QA engineer. Review the OrderCreated event schema above and write
+  Jest test cases that cover the happy path and the top three failure modes.
+</Prompt>
+```
+
+**Copy and open in Cursor**
+
+```jsx /services/OrdersService/index.mdx
+<Prompt
+  description="Generate Gherkin scenarios for this service"
+  actions={["copy", "cursor"]}
+  icon="sparkles"
+>
+  You are a senior QA engineer. Read the attached service documentation and produce
+  Gherkin Given/When/Then scenarios covering the happy path and the top three failure modes.
+</Prompt>
+```
+
+### Output
+![Example output](./img/prompt.png)
+
+### Props
+
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `description` (required) | `string` | — | Short label shown to the reader, e.g. "Generate test cases for this event". |
+| `actions` (optional) | `('copy' \| 'cursor')[]` | `['copy']` | Buttons to render. `'copy'` adds a clipboard button; `'cursor'` adds an "Open in Cursor" deep-link button. |
+| `icon` (optional) | `string` | — | Lucide icon name to display beside the description. Accepts kebab-case, snake_case, or space-separated input (e.g. `"sparkles"`, `"bot-message-square"`). |
+
+### Understand the actions
+
+Use `actions={["copy"]}` (the default) when you only need clipboard support. Add `"cursor"` to the array when your team works in Cursor and you want a one-click "Open in Cursor" button that pre-fills the prompt.
+
+Both actions derive their text from the slot content. HTML tags are stripped automatically, so plain text is always passed to the clipboard and the Cursor deep-link.
+
+### Use the icon prop
+
+Pass any [Lucide](https://lucide.dev/icons/) icon name to the `icon` prop. The component normalises the value to PascalCase internally, so `"bot-message-square"`, `"bot_message_square"`, and `"Bot Message Square"` all resolve to the same icon.
+
+If the icon name is not found in the Lucide library, no icon is rendered and no error is thrown.
+
+### Support
+
+The `<Prompt />` component is supported in domains, services, all messages, changelogs, and custom documentation pages.

package/dist/docs/development/components/components/15-remote-schema.md

@@ -0,0 +1,174 @@
+---
+sidebar_position: 15
+keywords:
+- components
+- remote schema
+- fetch
+- runtime
+sidebar_label: RemoteSchema
+title: RemoteSchema
+description: Component for fetching and rendering remote schemas in EventCatalog
+---
+
+import EventCatalogPro from '@site/src/components/MDX/EventCatalogPro';
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.52.0" />
+
+The **RemoteSchema** component fetches and renders schemas from remote URLs at runtime, keeping your documentation automatically synchronized with external schema sources.
+
+**Schemas can be fetched from any accessible URL and support authentication headers for private APIs.**
+
+:::tip
+**The `<RemoteSchema/>` component fetches schemas at runtime.**
+
+This ensures your documentation stays up-to-date with the latest schema versions without manual updates.
+:::
+
+:::info SSR Mode Required
+The `<RemoteSchema/>` component only works in Server-Side Rendering (SSR) mode. Make sure your EventCatalog is configured to run in SSR mode to use this component. You can read more about how to configure your EventCatalog to run in SSR mode [here](/docs/development/deployment/build-ssr-mode).
+:::
+
+### Usage
+
+**Basic Example**
+
+```jsx /events/MyEvent/index.mdx
+<RemoteSchema url="https://api.example.com/schemas/user-registered.json" />
+```
+
+**With Custom Title and Height**
+
+```jsx /events/MyEvent/index.mdx
+<RemoteSchema
+  url="https://api.example.com/schemas/payment.json"
+  title="Payment Schema"
+  maxHeight="600"
+/>
+```
+
+**Fetching from Private APIs** <EventCatalogPro />
+
+For private APIs requiring authentication, you can provide headers:
+
+```jsx /events/MyEvent/index.mdx
+<RemoteSchema 
+  url="https://private-api.example.com/schemas/order.json"
+  headers={{
+    "Authorization": "Bearer ${API_TOKEN}",
+    "X-API-Key": "${API_KEY}"
+  }}
+  title="Order Schema"
+/>
+```
+
+:::tip Loading environment variables
+
+Add your environment variables to the `.env` file in the root of your EventCatalog project.
+
+The RemoteSchema component will automatically map the environment variables to the template string.
+:::
+
+**Using JSONPath to Extract Specific Schema Parts**
+
+When your API returns nested schemas, use JSONPath to extract specific parts:
+
+```jsx /events/MyEvent/index.mdx
+<RemoteSchema 
+  url="https://api.example.com/openapi.json"
+  jsonPath="$.components.schemas.UserEvent"
+  title="User Event Schema"
+/>
+```
+
+**Rendering as Raw JSON**
+
+Force rendering as raw JSON instead of the schema viewer:
+
+```jsx /events/MyEvent/index.mdx
+<RemoteSchema 
+  url="https://api.example.com/schemas/config.json"
+  renderAs="raw"
+  title="Configuration Schema"
+/>
+```
+
+### Output
+The component automatically detects JSON Schema format and renders an interactive [Schema Viewer](/docs/development/components/components/schema-viewer), or displays raw content for other formats.
+
+### Props
+
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `url` (required)        | `string`  | (empty)           | The URL to fetch the schema from. Supports environment variable templating with `${VAR_NAME}` syntax. |
+| `title` (optional)      | `string`  | "Remote Schema"   | Title to display above the schema                                 |
+| `maxHeight` (optional)  | `string`  | "400"             | Maximum height of the schema viewer in pixels                    |
+| `headers` (optional)    | `object`  | `{}`              | HTTP headers for authentication (requires EventCatalog Scale plan) |
+| `jsonPath` (optional)   | `string`  | (empty)           | [JSONPath expression](https://github.com/dchester/jsonpath) to extract specific parts of the response    |
+| `renderAs` (optional)   | `string`  | "auto"            | Rendering mode: "auto", "schema", or "raw"                      |
+
+### Environment Variable Support
+
+The `url` and `headers` props support environment variable templating using `${VARIABLE_NAME}` syntax:
+
+```md
+<RemoteSchema 
+  url="https://${API_HOST}/schemas/user.json"
+  headers={{
+    "Authorization": "Bearer ${API_TOKEN}"
+  }}
+/>
+```
+
+:::tip Loading environment variables
+Add your environment variables to the `.env` file in the root of your EventCatalog project.
+
+The RemoteSchema component will automatically map the environment variables to the template string.
+:::
+
+### JSONPath Examples
+
+Extract specific schema definitions from complex API responses using [JSONPath](https://github.com/dchester/jsonpath).
+
+```md
+<!-- Extract a specific component schema from OpenAPI -->
+<RemoteSchema 
+  url="https://api.example.com/openapi.json"
+  jsonPath="$.components.schemas.User"
+/>
+
+<!-- Extract from AsyncAPI -->
+<RemoteSchema 
+  url="https://api.example.com/asyncapi.json"
+  jsonPath="$.components.messages.UserCreated.payload"
+/>
+
+<!-- Extract from nested arrays -->
+<RemoteSchema 
+  url="https://api.example.com/schemas.json"
+  jsonPath="$.definitions[0].schema"
+/>
+```
+
+### Error Handling
+
+The component provides clear error messages for common issues:
+
+- **Network errors**: Connection timeouts, DNS resolution failures
+- **Authentication errors**: Invalid credentials or missing headers
+- **JSONPath errors**: Invalid JSONPath expressions
+- **Format errors**: Unsupported schema formats
+
+### Benefits for Teams
+
+- **Always up-to-date**: Schemas are fetched at runtime, ensuring documentation reflects the latest API changes
+- **Reduced maintenance**: No need to manually update schema files when APIs change
+- **Single source of truth**: Documentation pulls directly from your API definitions
+- **Private API support**: Secure access to internal schemas with authentication headers
+- **Flexible extraction**: Use JSONPath to document specific parts of large API specifications
+
+This component bridges the gap between your live APIs and documentation, ensuring your EventCatalog always reflects the current state of your systems.
+
+### Support
+
+The `<RemoteSchema/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.

package/dist/docs/development/components/components/16-resource-group-table.md

@@ -0,0 +1,86 @@
+---
+sidebar_position: 2
+keywords:
+- components
+sidebar_label: ResourceGroupTable
+title: ResourceGroupTable
+description: Component for displaying EventCatalog grouped resources in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.32.0" />
+
+The `<ResourceGroupTable/>` component renders a table of resources for your page in EventCtalog.
+
+The component renders a paginated table of (messages, services, domains, flows, channels), with the ability to filter by resource type, and text search.
+
+### Why use ResourceGroupTable?
+
+Sometimes in your catalog you may want to link related resources together or group them in particular ways that EventCatalog does not naturally support.
+
+Examples:
+
+- List a custom list of messages in a domain page
+- Create a "Related Resources" section on your docs for your documentation readers
+- Create a custom list of resources in your page and let people search them easily.
+
+### Usage
+
+The `<ResourceGroupTable/>` component requires **frontmatter** property called **resourceGroups** defined in your resource, and then the component itself.
+
+1. Adding `resourceGroup` property to your resource
+```md title="example /domains/Orders/index.mdx"
+---
+id: Orders
+name: Orders
+version: 0.0.3
+owners:
+  - dboyne
+  - full-stack
+# Here we define the resourceGroups, in this example we create a group called core resources
+# We create a list called `related-resources` and we group these services.
+# Remember you can define any group of information you want, and link to any catalog resource
+resourceGroups:
+  - id: related-resources
+    title: Core resources
+    items:
+      - id: InventoryService
+        type: service
+      - id: OrdersService
+        type: service
+      - id: NotificationService
+        type: service
+      - id: ShippingService
+        type: service
+---
+```
+
+
+**Basic Example**
+
+```md /domains/MyDomain/index.mdx
+---
+#domain frontmatter
+---
+
+<ResourceGroupTable id="related-resources" limit={4} showOwners={true} title="Core resources for the Orders domain" description="Resources that are related to the Orders domain, you may find them useful" />
+```
+### Output
+![Example output](./img/resource-group-table.png)
+
+You can see the demo of this in the [Orders domain page](https://demo.eventcatalog.dev/domains/Orders/0.0.3).
+
+### Props
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `id`             | `string`  | none           | Id of the resource group to render. |
+| `title`             | `string`  | 'Related Resources'           | The title shown above the table. |
+| `subtitle`             | `string`  | 'Resources'           | The title shown inside the table. |
+| `description`             | `string`  | 'Resources that are related to the current resource.'           | The description of the table. |
+| `limit`             | `number`  | 10           | The number of resources to render in the table. Results are paginated. |
+| `showOwners`             | `boolean`  | false           | Whether to show the owners of the resources in the table. |
+
+### Support
+
+The `<ResourceGroupTable/>` component is supported on all EventCatalog pages.

package/dist/docs/development/components/components/17-resource-link.md

@@ -0,0 +1,57 @@
+---
+sidebar_position: 2
+keywords:
+- components
+sidebar_label: ResourceLink
+title: ResourceLink
+description: Create links in your documentation to resources in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.32.3" />
+
+:::tip Prefer wiki-style syntax
+For most use cases, we recommend using the newer [resource references](/docs/development/components/resource-references) syntax instead:
+
+```md
+[[service|InventoryService]]
+```
+
+This provides interactive tooltips and a more natural writing experience. Use `<ResourceLink/>` only when you need custom link text or explicit component control.
+:::
+
+The `<ResourceLink/>` component renders a link to a resource in EventCatalog.
+
+**Basic Example**
+
+```jsx /domains/MyDomain/index.mdx
+<ResourceLink id="InventoryService" type="service" />
+
+<ResourceLink id="InventoryService" type="service" version="1.0.0" />
+
+<ResourceLink id="InventoryService" type="service">This is a custom link</ResourceLink>
+```
+
+### Props
+| Name                    | Type      | Default           | Required | Description                                                       |
+| ----------------------- | --------- | ----------------- | -------- | ----------------------------------------------------------------- |
+| `id`             | `string`  | none           | Yes      | Id of the resource group to render. |
+| `type`             | `string`  | none           | Yes      | The type of resource to render (service, event, query, command, channel, flow, domain, user, team) |
+| `version`             | `string`  | none           | Optional. The version of the resource to render, by default the latest version is used. | Version of the resource to link to.
+
+### Recommended alternative
+
+<AddedIn version="3.6.1" />
+
+For most documentation, prefer the wiki-style syntax which provides interactive tooltips:
+
+```md
+The [[service|InventoryService]] manages inventory.
+```
+
+See [Resource references](/docs/development/components/resource-references) for full documentation.
+
+### Support
+
+The `<ResourceLink/>` component is supported on all EventCatalog pages.