@eventcatalog/core 3.34.0 → 3.35.1

package/dist/docs/development/components/07-resource-references.md

@@ -0,0 +1,136 @@
+---
+sidebar_position: 2
+keywords:
+- resource references
+- links
+- cross-references
+sidebar_label: Resource references
+title: Resource references
+description: Create inline links to resources with hover tooltips
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.6.1" />
+
+Create inline references to resources in your documentation using wiki-style syntax. References render as styled links with interactive tooltips showing resource details.
+
+<div className="flex justify-center flex-col items-center gap-4">
+  <img src="/img/resource-link.png" alt="Resource link example" className="rounded-lg"  />
+  <a href="https://demo.eventcatalog.dev/docs/services/OrdersService/0.0.1" target="_blank" class="block text-xs w-full text-center">See in EventCatalog demo &rarr;</a>
+</div>
+
+## Basic syntax
+
+Use double square brackets to create a resource reference.
+
+```md
+[[type|ResourceName]]
+```
+
+The reference automatically links to the resource and displays a tooltip on hover showing key information like version, summary, and related resources.
+
+### Example
+
+```md
+---
+id: OrdersService
+name: Orders Service
+version: 0.0.1
+summary: |
+  Handles all order processing
+owners:
+  - dboyne
+  - msmith
+---
+
+The [[service|OrdersService]] handles all order processing and will publish the event [[event|OrderCreated]] when an order is created.
+```
+
+This creates a link to the OrdersService with a tooltip showing service details, published messages, API specifications, and owners.
+
+## Supported resource types
+
+Reference any resource type in your catalog.
+
+| Type | Syntax | Links to |
+|------|--------|----------|
+| Service | `[[service\|OrdersService]]` | Service documentation |
+| Event | `[[event\|OrderCreated]]` | Event documentation |
+| Command | `[[command\|CreateOrder]]` | Command documentation |
+| Query | `[[query\|GetOrderStatus]]` | Query documentation |
+| Domain | `[[domain\|E-Commerce]]` | Domain documentation |
+| Flow | `[[flow\|PaymentFlow]]` | Flow documentation |
+| Channel | `[[channel\|OrderChannel]]` | Channel documentation |
+| Entity | `[[entity\|Order]]` or `[[Order]]` | Entity documentation |
+| Diagram | `[[diagram\|target-architecture]]` | Diagram page |
+| Container | `[[container\|APIGateway]]` | Container documentation |
+| User | `[[user\|dboyne]]` | User profile |
+| Team | `[[team\|backend-team]]` | Team profile |
+| Custom doc | `[[doc\|guides/getting-started]]` | Custom documentation page |
+
+### Reference custom docs
+
+Link to pages in your [custom documentation](/docs/development/bring-your-own-documentation/custom-pages/introduction) using path-based identifiers.
+
+```md
+[[doc|guides/getting-started]]
+[[doc|operations-and-support/runbooks/payment-service-runbook]]
+```
+
+The path matches the file location inside your `docs/` directory, relative to the catalog root. Paths are case-insensitive and leading `/docs/custom/` prefixes are stripped automatically.
+
+Doc references do not support version pinning since custom documentation pages are not versioned.
+
+### Default to entity
+
+Reference entities without specifying the type.
+
+```md
+The [[Customer]] entity stores user information.
+```
+
+This defaults to entity type and is equivalent to `[[entity|Customer]]`.
+
+## Version pinning
+
+Reference a specific version of a resource.
+
+```md
+[[service|OrdersService@1.0.0]]
+```
+
+Without a version, the reference uses the latest version. Pin versions when documenting specific implementations or historical states.
+
+### Example
+
+```md
+Our legacy [[service|PaymentService@0.9.0]] is being replaced by [[service|PaymentGatewayService]].
+```
+
+## Interactive tooltips
+
+Hover over any reference to see detailed information without leaving the page.
+
+<div className="flex justify-center flex-col items-center gap-4">
+  <img src="/img/resource-link.png" alt="Resource link example" className="rounded-lg"  />
+  <a href="https://demo.eventcatalog.dev/docs/services/OrdersService/0.0.1" target="_blank" class="block text-xs w-full text-center">See in EventCatalog demo &rarr;</a>
+</div>
+
+Tooltips show different information based on resource type.
+
+### Combine with other components
+
+Mix references with other EventCatalog components.
+
+```md
+## Architecture
+
+The [[service|OrdersService]] coordinates between inventory and payment:
+
+<NodeGraph id="OrdersService" version="latest" type="service" />
+```
+
+### Review references regularly
+
+Regularly audit references to ensure they point to current resources and remove outdated links.

package/dist/docs/development/components/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "Components & Diagrams",
+  "position": 6,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "components",
+    "title": "Components & Diagrams",
+    "description": "Use MDX components, diagram syntax, and external embeds in EventCatalog documentation."
+  }
+}

package/dist/docs/development/components/components/01-accordian.md

@@ -0,0 +1,41 @@
+---
+sidebar_position: 2
+keywords:
+- components
+sidebar_label: Accordion
+title: Accordion
+description: Component for EventCatalog
+---
+
+The accordion component renders collapsable section in EventCatalog.
+
+```jsx /events/OrderAmended/index.mdx
+<Accordion title="Learn how to raise this event">
+    This will be rendered as a child inside a collapsible section.
+</Accordion>
+```
+**Example with code as child**
+
+```jsx /events/OrderAmended/index.mdx
+<Accordion title="Learn how to raise this event">
+  You can run the following command to raise this event.
+
+  ```sh
+  bin/kafka-topics.sh --create --topic OrderAmended --bootstrap-server localhost:9092 --partitions 1 --replication-factor 1
+  ``
+</Accordion>
+```
+
+### Output
+
+![Example output](./img/accordian.png)
+
+### Props
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `title` (required)                 | `string`  | (empty)           | Title to render in your accordion block                              |
+| `children`             | `string`  | (empty)           | Content that goes inside your accordion|
+
+### Support
+
+The `<Accordion/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.

package/dist/docs/development/components/components/02-accordian-group.md

@@ -0,0 +1,57 @@
+---
+sidebar_position: 2
+keywords:
+- components
+sidebar_label: AccordionGroup
+title: AccordionGroup
+description: Component for EventCatalog
+---
+
+The accordion group component renders a collection of accordions.
+
+**Basic Example**
+
+```jsx /events/OrderAmended/index.mdx
+<AccordionGroup>
+  <Accordion title="Example 1">Hello</Accordion>
+  <Accordion title="Example 2">Hello this is an example</Accordion>
+  <Accordion title="Example 3">Another example</Accordion>
+  <Accordion title="Example 4">Final example</Accordion>
+</AccordionGroup>
+```
+
+**Code example**
+
+Add code inside the Accordion to render code snippets.
+
+```jsx /events/OrderAmended/index.mdx
+<AccordionGroup>
+  <Accordion title="Code snippet 1">
+    ```js
+    console.log('My code here');
+    ``
+  </Accordion>
+  <Accordion title="Code snippet 2">
+  ```js
+    console.log('My other code snippet');
+  ``
+  </Accordion>
+  <Accordion title="Schema example">
+  ```json
+  { "test": true}
+  ``
+  </Accordion>
+</AccordionGroup>
+```
+
+### Output
+![Example output](./img/accordiangroup.png)
+
+### Props
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `children`             | `Accordion`  | (empty)           | Accordion components that are contained within the group|
+
+### Support
+
+The `<AccordionGroup/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.

package/dist/docs/development/components/components/03-admonitions.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 2
+keywords:
+- components
+sidebar_label: Admonitions
+title: Admonitions
+description: Component for EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.16.6"/>
+
+The admonitions syntax is used to render a block of text with a specific style. You can use it to highlight important information, warnings, or other types of content.
+
+**Basic Example**
+
+```md /events/OrderAmended/index.mdx
+:::note
+Some content with _Markdown_ syntax. Check [this api](https://eventcatalog.dev/).
+:::
+
+:::tip
+Some content with _Markdown_ syntax. Check [this api](https://eventcatalog.dev/).
+:::
+
+:::warning
+Some content with _Markdown_ syntax. Check [this api](https://eventcatalog.dev/).
+:::
+
+:::danger
+Some content with _Markdown_ syntax. Check [this api](https://eventcatalog.dev/).
+:::
+
+```
+
+
+### Output
+![Example output](./img/admonitions.png)
+
+### Support
+
+The markdown syntax is supported in all pages in EventCatalog.

package/dist/docs/development/components/components/04-attachments.md

@@ -0,0 +1,56 @@
+---
+sidebar_position: 1
+keywords:
+- attachments
+- documentation
+- ADR
+- diagrams
+sidebar_label: Attachments
+title: Attachments
+description: Learn how to add attachments to your EventCatalog resources
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.57.2" />
+
+The Attachments component allows you to link related documents, diagrams, and resources to any EventCatalog resource. This is perfect for connecting Architecture Decision Records (ADRs), design documents, external diagrams, or any other relevant documentation.
+
+Attachments can be a url (string) or an object with additional properties.
+
+Here we have a domain with two attachments, one is a simple url and the other is an object with additional properties.
+
+```md title="domains/E-Commerce/index.mdx"
+---
+id: E-Commerce
+name: E-Commerce Domain
+attachments:
+  - https://example.com/adr/001-microservices-architecture
+  - url: https://example.com/adr/001
+    title: ADR-001 - Use Kafka for asynchronous messaging
+    description: Learn more about why we chose Kafka for asynchronous messaging in this architecture decision record.
+    type: 'architecture-decisions'
+    icon: FileTextIcon
+---
+
+## Domain Overview
+
+This domain handles all e-commerce operations.
+
+<Attachments />
+
+```
+
+### Output
+
+![Example output](./img/attachments.png)
+
+### Props
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `title` (optional)                 | `string`  | (empty)           | Title to render in your attachments block                             |
+| `description` (optional)             | `string`  | (empty)           | Any additional description to render in your attachments block|
+
+## Support
+
+The `<Attachments />` component is supported in all EventCatalog resources, and custom documentation pages.

package/dist/docs/development/components/components/05-channel-information.md

@@ -0,0 +1,29 @@
+---
+sidebar_position: 6
+keywords:
+  - components
+sidebar_label: ChannelInformation
+title: ChannelInformation
+description: Render channel into EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.13.0"/>
+
+The ChannelInformation component is a EventCatalog component that will render a table into your markdown page that contains information about the Channel. 
+
+**Example**
+
+```jsx /services/MyService/index.mdx
+<ChannelInformation />
+```
+
+### Output
+![Example output](./img/channel.png)
+
+See example in the [demo EventCatalog application](https://demo.eventcatalog.dev/docs/channels/inventory.%7Benv%7D.events/1.0.0).
+
+### Support
+
+The `<ChannelInformation/>` component is supported in channels.

package/dist/docs/development/components/components/06-design.md

@@ -0,0 +1,66 @@
+---
+sidebar_position: 15
+keywords:
+- components
+- remote schema
+- fetch
+- runtime
+sidebar_label: Design
+title: Design
+description: Component for embedding EventCatalog Studio diagrams into your documentation
+---
+
+import EventCatalogPro from '@site/src/components/MDX/EventCatalogPro';
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.56.0" />
+
+The **Design** component is a EventCatalog component that will render a [EventCatalog Studio diagram](https://eventcatalog.studio) into your markdown page.
+
+## Interactive controls
+
+<AddedIn version="3.9.0" />
+
+Design visualizations include the same interactive controls as NodeGraph components.
+
+Switch between React Flow and Mermaid view modes, export as Mermaid diagram code, or share URLs with your team.
+
+[Read more about interactive controls](/docs/development/components/components/nodegraph#interactive-controls)
+
+Design visualizations also support [layout persistence](/docs/development/components/components/nodegraph#layout-persistence) in dev mode, allowing you to save custom node positions.
+
+### Usage
+
+**Basic Example**
+
+```jsx /events/MyEvent/index.mdx
+<Design file="event-stream-example" search={false} />
+```
+
+**With Custom Title and Height**
+
+```jsx /events/MyEvent/index.mdx
+<Design
+  file="event-stream-example"
+  title="Event Stream Example"
+  maxHeight="600"
+/>
+```
+
+### Output
+When you use the `<Design />` component, it will render the diagram in your EventCatalog page.
+
+![Example output](/img/embed-ec.png)
+
+### Props
+
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `file` (required)        | `string`  | (empty)           | The `.ecstudio` file to load into the diagram block. Path is resolved by EventCatalog. |
+| `title` (optional)      | `string`  | "Remote Schema"   | Title to display above the diagram                                 |
+| `maxHeight` (optional)  | `string`  | "400"             | Maximum height of the diagram in pixels                    |
+| `search` (optional)    | `boolean`  | `false`              | Show or hide the search bar in the diagram |
+
+### Support
+
+The `<Design/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.

package/dist/docs/development/components/components/07-entitymap.md

@@ -0,0 +1,71 @@
+---
+sidebar_position: 3
+keywords:
+- components
+sidebar_label: EntityMap
+title: EntityMap
+description: Component for EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.49.0" />
+
+A component to visually render a domain's entity map.
+
+The `<EntityMap/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.
+
+:::info
+To visualize entities [you need to create entities in EventCatalog](/docs/development/guides/domains/entities/introduction) and assign them to your services or domains.
+:::
+
+## Interactive controls
+
+<AddedIn version="3.9.0" />
+
+Entity map visualizations include the same interactive controls as NodeGraph components.
+
+Switch between React Flow and Mermaid view modes, export as Mermaid diagram code, or share URLs with your team.
+
+[Read more about interactive controls](/docs/development/components/components/nodegraph#interactive-controls)
+
+Entity maps also support [layout persistence](/docs/development/components/components/nodegraph#layout-persistence) in dev mode, allowing you to save custom node positions.
+
+## Usage
+
+**Example**
+
+```jsx /domains/OrdersDomain/index.mdx
+<EntityMap title="Orders Domain Entity Map" />
+```
+
+#### Output
+![Example output](./img/entity-map.png)
+
+#### Props
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `id` (optional)             | `string`  | -          | The id of the domain or service entity map to render. By default the component will use the id of the current page. If you want to embed this component into custom documentation pages, you can use the `id` prop to specify the id of the domain or service to render. |
+| `version` (optional)             | `string`  | -          | The version of the domain or service to render. By default the component will use the version of the current page. If you want to embed this component into custom documentation pages, you can use the `version` prop to specify the version of the domain or service to render. |
+| `title` (optional)             | `string`  | -          | The title of the entity map to render. |
+| `maxHeight` (optional)             | `string`  | 30           | Max height to set the nodegraph in your document. |
+| `includeKey` (optional)             | `boolean`  | true           | Show or hide the legend. |
+| `entities` (optional)             | `array`  | []           | Array of entities (ids or names) to filter in the map. Useful if you want to render a subset of the entities in the map. (Added in v2.51.1). [Read more about filtering](#filter-entities) |
+
+#### Filter Entities
+
+<AddedIn version="2.51.1" />
+
+The `<EntityMap/>` component will render all entities by default for a given domain.
+
+If you want to render a subset of the entities in the map, you can use the `entities` prop.
+
+**Example**
+
+```jsx /events/MyEvents/index.mdx
+<EntityMap id="OrdersDomain" title="Orders Domain Entity Map" entities={["Order", "Customer"]} />
+```
+
+In this example, only the `Order` and `Customer` entities will be chosen to be rendered in the map.
+
+If the `Order` or `Customer` entity references other entities, they will also be rendered in the map

package/dist/docs/development/components/components/08-flow.md

@@ -0,0 +1,46 @@
+---
+sidebar_position: 6
+keywords:
+- components
+sidebar_label: Flow
+title: Flow
+description: Render a Flow in any EventCatalog page
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Embed flows into your pages.
+
+**Example**
+
+```jsx /domains/MyDomain/index.mdx
+<Flow id="CancelSubscription" version="latest" includeKey={false} />
+```
+
+### Output
+![Example output](./img/flows.png)
+
+### Props
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `id` (required)                 | `string`  | (empty)           | Flow id to render in your page                               |
+| `version` (optional)             | `string`  | "latest"           | Version of the flow to render. Supports exact version and semver versions (e.g 1.0.x, ^1.3.5, latest)|
+| `includeKey` (optional)             | `boolean`  | true           | Renders the diagram key on the UI |
+| `search` (optional)             | `boolean`  | true           | Show or hide the search bar in the flow _(Added in v2.50.3)_ |
+| `mode` (optional)             | `string` ("simple" or "full")  | "simple"           | `simple` will render the flow in a simplfied view not rendering descriptions. Full will render the flow in a full view, rendering descriptions and other information _(Added in v2.50.3)_|
+
+## Interactive controls
+
+<AddedIn version="3.9.0" />
+
+Flow visualizations include the same interactive controls as NodeGraph components.
+
+Switch between React Flow and Mermaid view modes, export as Mermaid diagram code, or share URLs with your team.
+
+[Read more about interactive controls](/docs/development/components/components/nodegraph#interactive-controls)
+
+Flow visualizations also support [layout persistence](/docs/development/components/components/nodegraph#layout-persistence) in dev mode, allowing you to save custom node positions.
+
+### Support
+
+The `<Flow/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.

package/dist/docs/development/components/components/09-link.md

@@ -0,0 +1,32 @@
+---
+sidebar_position: 2
+keywords:
+- components
+sidebar_label: Link
+title: Link
+description: Create links in your documentation
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.32.3" />
+
+The `<Link/>` component renders a link to a resource in EventCatalog.
+
+EventCatalog handles links depending on your configuration file (e.g trailing slashes, etc), using this component creates links that are consistent with your EventCatalog configuration.
+
+**Basic Example**
+
+```jsx /domains/MyDomain/index.mdx
+<Link href="/my/awesome/page">My Awesome Page</Link>
+
+```
+
+### Props
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `href`             | `string`  | none           | The href of the link. |
+
+### Support
+
+The `<Link/>` component is supported on all EventCatalog pages.

package/dist/docs/development/components/components/10-mermaid-file-loader.md

@@ -0,0 +1,63 @@
+---
+sidebar_position: 15
+keywords:
+- components
+- remote schema
+- fetch
+- runtime
+sidebar_label: MermaidFileLoader
+title: MermaidFileLoader
+description: Component for embedding EventCatalog Studio diagrams into your documentation
+---
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<AddedIn version="2.56.4" />
+
+The **MermaidFileLoader** component is a EventCatalog component that will render a [Mermaid](https://mermaid.js.org/) file into your markdown page.
+
+**Basic Example**
+
+<Tabs>
+  <TabItem value="Markdown file" label="Markdown file" default>
+    
+```jsx /events/MyEvent/index.mdx
+<MermaidFileLoader file="mermaid.mmd" />
+```
+  </TabItem>
+  <TabItem value="Mermaid file (.mmd or .mermaid)" label="Mermaid file (.mmd or .mermaid)">
+    ```
+  sequenceDiagram
+      participant Customer
+      participant OrdersService
+      participant InventoryService
+      participant NotificationService
+
+      Customer->>OrdersService: Place Order
+      OrdersService->>InventoryService: Check Inventory
+      InventoryService-->>OrdersService: Inventory Available
+      OrdersService->>InventoryService: Reserve Inventory
+      OrdersService->>NotificationService: Send Order Confirmation
+      NotificationService-->>Customer: Order Confirmation
+      OrdersService->>Customer: Order Placed Successfully
+      OrdersService->>InventoryService: Update Inventory
+    ```
+  </TabItem>
+</Tabs>
+
+### Output
+When you use the `<MermaidFileLoader />` component, it will render the diagram in your EventCatalog page.
+
+![Example output](./img/mermaid.png)
+
+### Props
+
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `file` (required)        | `string`  | (empty)           | The `.mmd` or `.mermaid` file to load into the diagram block. Path is resolved by EventCatalog. |
+
+### Support
+
+The `<MermaidFileLoader/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.