@eventcatalog/core 3.34.0 → 3.35.1

package/dist/docs/development/components/components/18-schema.md

@@ -0,0 +1,44 @@
+---
+sidebar_position: 5
+keywords:
+- components
+sidebar_label: Schema
+title: Schema
+description: Component for EventCatalog
+---
+
+The schema component renders a given schema into the page. 
+
+**Schemas can be any file format (.avro, .json etc).**
+
+:::tip
+**The `<Schema/>` component renders any schema format.**
+
+If you need to render JSON Schema, you can also use the [\<SchemaViewer/\> component](/docs/development/components/components/schema-viewer).
+
+:::
+
+### Usage
+
+1. Add your schema file to your folder.
+    - e.g `/events/MyEvent/schema.avro`
+
+**Example**
+
+```jsx /events/MyEvent/index.mdx
+<Schema file="schema.avro" />
+```
+
+### Output
+![Example output](./img/schema.png)
+
+### Props
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `file` (required)             | `string`  | (empty)           | The file to load into the schema block. Path is resolved by EventCatalog.                              |
+| `title` (optional)                 | `string`  | (empty)           | Title to render in your schema block                              |
+| `lang` (optional)             | `string`  | `json`           | The code language of the schema. Defaults to `json`. Over 100 languages are supported. [List of options can be found here.](https://github.com/shikijs/textmate-grammars-themes/blob/main/packages/tm-grammars/README.md)                             |
+
+### Support
+
+The `<Schema/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.

package/dist/docs/development/components/components/19-schema-viewer.md

@@ -0,0 +1,69 @@
+---
+sidebar_position: 6
+keywords:
+- components
+sidebar_label: SchemaViewer
+title: SchemaViewer
+description: Render JSON schema in EventCatalog
+---
+
+A Schema Viewer component for EventCatalog that supports JSON schemas and Avro schemas.
+
+Renders the given schema (.json, .yaml, .avro, .avsc) into the page.
+
+:::tip
+**The `<SchemaViewer/>` component only works with JSON Schema and Avro schemas.**
+
+If you need to render other schema formats, please use the [\<Schema/\> component](/docs/development/components/components/schema).
+
+_Avro support was added in 2.64.0. Please upgrade to the latest version of EventCatalog to use this component._
+:::
+
+### Usage
+
+1. Add a JSON or Avro schema file to your folder.
+    - e.g `/events/MyEvent/schema.json`
+    - e.g `/events/MyEvent/schema.avro`
+
+**Example**
+
+```jsx /events/MyEvent/index.mdx
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" search="true" expand="true" />
+
+<SchemaViewer file="schema.avro" title="Avro Schema" maxHeight="500" />
+
+<SchemaViewer file="schema.yaml" title="YAML Schema" maxHeight="500" />
+```
+
+### Output
+![Example output](./img/schemaviewer.png)
+
+### Props
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `title` (optional)                 | `string`  | (empty)           | Title to render above your schema                               |
+| `file` (required)             | `string`  | (empty)           | The file to load into the schema block. Path is resolved by EventCatalog.                              |
+| `maxHeight` (optional)             | `string`  | "500"           | Max height of the JSON Schema viewer (in pixels).                              |
+| `search` (optional)             | `boolean`  | false           | Renders a search input in the viewer                             |
+| `expand` (optional)             | `boolean`  | false           | Expands all properties by default                             |
+| `showRequired` (optional)             | `boolean`  | false           | **Avro Schemas only**: Will show which fields are required. Fields are required if they don't have a default value or null as their type. As documented in the [Avro Specification](https://avro.apache.org/docs/++version++/specification/)                           |
+
+
+## Rendering multiple schemas
+
+You can use the SchemaViewer multiple times in your page.
+
+**Example**
+
+```md /events/MyEvents.index.mdx
+The Inventory Adjusted event is triggered whenever there is a change in the inventory levels of a product. 
+This could occur due to various reasons such as receiving new stock, sales, returns, or manual adjustments by the inventory management team.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" id="json-schema" />
+<SchemaViewer file="old-schema.json" title="Another Version" maxHeight="500" id="json-schema2" />
+<SchemaViewer file="new-schema.yml" title="Another Version" maxHeight="500" id="yaml-schema" />
+```
+
+### Support
+
+The `<SchemaViewer/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.

package/dist/docs/development/components/components/20-steps.md

@@ -0,0 +1,83 @@
+---
+sidebar_position: 6
+keywords:
+  - components
+sidebar_label: Steps
+title: Steps
+description: Render steps into EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.7.14"/>
+
+The Steps component is a powerful tool for creating structured, sequential guides in EventCatalog. It's ideal for presenting step-by-step instructions, tutorials, or workflows, particularly when explaining processes, API integrations, or code implementations.
+
+### Key Features:
+
+- Automatic Numbering: Steps are automatically numbered, providing clear sequence and structure.
+- Flexible Content: Supports various content types including text, code snippets, and embedded components.
+
+### Use Cases:
+
+- Walking users through setup procedures
+- Explaining complex workflows
+- Presenting API integration steps
+- Showcasing code examples with explanations
+
+**Example**
+
+```jsx /services/MyService/index.mdx
+<Steps title="How to connect to Inventory Service">
+  <Step title="Obtain API credentials">
+    Request API credentials from the Inventory Service team.
+  </Step>
+  <Step title="Install the SDK">
+    Run the following command in your project directory:
+    ```bash
+      npm install inventory-service-sdk
+    ```_
+  </Step>
+  <Step title="Initialize the client">
+  Use the following code to initialize the Inventory Service client:
+  ```js
+    const InventoryService = require('inventory-service-sdk');
+    const client = new InventoryService.Client({
+      clientId: 'YOUR_CLIENT_ID',
+      clientSecret: 'YOUR_CLIENT_SECRET',
+      apiUrl: 'https://api.inventoryservice.com/v1'
+    });
+  ```_
+  </Step>
+  <Step title="Make API calls">
+  
+  You can now use the client to make API calls. For example, to get all products:
+  ```js
+  client.getProducts()
+    .then(products => console.log(products))
+    .catch(error => console.error(error));
+  ```_
+  </Step>
+</Steps>
+```
+
+### Output
+![Example output](./img/steps.png)
+
+See example in the [demo EventCatalog application](https://demo.eventcatalog.dev/docs/services/InventoryService/0.0.2).
+
+### Props (`<Steps>`)
+
+| Name               | Type     | Default | Description                             |
+| ------------------ | -------- | ------- | --------------------------------------- |
+| `title` (optional) | `string` | (empty) | Title that gets renders above the steps |
+
+### Props (`<Step>`)
+
+| Name                     | Type      | Default | Description                                                                                                                                                |
+| ------------------------ | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title` (required)       | `string`  | (empty) | Title for the step                                                                                                                                         |
+
+### Support
+
+The `<Steps/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.

package/dist/docs/development/components/components/21-tabs.md

@@ -0,0 +1,55 @@
+---
+sidebar_position: 6
+keywords:
+  - components
+sidebar_label: Tabs
+title: Tabs
+description: Render tabs in your EventCatalog pages
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.16.5"/>
+
+The `<Tabs />` component is a EventCatalog component that will render a tabs into your markdown page.
+
+Add Tabs and TabItems into your markdown file.
+
+**Example**
+
+```jsx /services/MyService/index.mdx
+<Tabs>
+  <TabItem title="Tab 1">
+    This is the content for tab 1
+  </TabItem>
+  <TabItem title="Tab 2">
+    This is the content for tab 2
+  </TabItem>
+</Tabs>
+```
+
+**Example with code as child**
+
+```jsx /services/MyService/index.mdx
+<Tabs>
+  <TabItem title="Tab 1">
+    ``sh
+    This is the content for tab 1
+    ``
+  </TabItem>
+  <TabItem title="Tab 2">
+    ``js
+    console.log('This is the content for tab 2');
+    ``
+  </TabItem>
+</Tabs>
+```
+
+### Output
+![Example output](./img/tabs.png)
+
+See example in the [demo EventCatalog application](https://demo.eventcatalog.dev/docs/events/InventoryAdjusted/1.0.1).
+
+### Support
+
+The `<Tabs/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.

package/dist/docs/development/components/components/22-tiles.md

@@ -0,0 +1,53 @@
+---
+sidebar_position: 6
+keywords:
+  - components
+sidebar_label: Tiles
+title: Tiles
+description: Render tiles into EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.7.12"/>
+
+Renders Tiles in EventCatalog, can be great for internal and external links.
+
+Tile icons are from [hero icons](https://heroicons.com/), you can find a [list of them here](https://unpkg.com/browse/@heroicons/react@2.1.5/24/outline/).
+
+**Example**
+
+```jsx /services/MyService/index.mdx
+<Tiles columns={2}>
+  <Tile icon="DocumentIcon" href="/docs" title="View the docs" description="Dive deeper and view our docs" />
+  <Tile icon="DocumentIcon" href="/visualiser" title="View the visualiser" description="Explore your architecture" />
+  <Tile icon="UserGroupIcon" href="https://eventcatalog.dev" openWindow="true" title="Contact EventCatalog" description="Any questions? Visit our website!" />
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} messages`} description="This service receives messages from downstream consumers" />
+</Tiles>
+```
+
+### Output
+![Example output](./img/tiles.png)
+
+See example in the [demo EventCatalog application](https://demo.eventcatalog.dev/docs/services/InventoryService/0.0.2).
+
+### Props (`<Tiles>`)
+
+| Name               | Type     | Default | Description                             |
+| ------------------ | -------- | ------- | --------------------------------------- |
+| `title` (optional) | `string` | (empty) | Title that gets renders above the tiles |
+| `columns` (optional) | `number` | 2 | Number of columns to render the tiles in |
+### Props (`<Tile>`)
+
+| Name                     | Type      | Default | Description                                                                                                                                                |
+| ------------------------ | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title` (optional)       | `string`  | (empty) | Title for the tile                                                                                                                                         |
+| `description` (optional) | `string`  | (empty) | Description for the tile                                                                                                                                   |
+| `icon` (optional)        | `string`  | (empty) | Icon to show in the tile. Iconss are [HeroIcons](https://heroicons.com/). [Find a list here](https://unpkg.com/browse/@heroicons/react@2.1.5/24/outline/). |
+| `iconColor` (optional)   | `string`  | `text-purple-500` | The color of the icon, using tailwind classes.                                                                                |
+| `href` (optional)        | `string`  | (empty) | URL for the tile                                                                                                                                           |
+| `openWindow` (optional)  | `boolean` | (empty) | Open the URL in a new window                                                                                                                               |
+
+### Support
+
+The `<Tiles/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.

package/dist/docs/development/components/components/23-visibility.md

@@ -0,0 +1,61 @@
+---
+sidebar_position: 19
+keywords:
+  - components
+  - visibility
+  - agents
+  - ai
+  - llm
+sidebar_label: Visibility
+title: Visibility
+description: Gate content by audience — humans in the UI, agents in raw markdown
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.33.0" />
+
+`<Visibility>` lets you write a single MDX file that serves two audiences: human readers in the browser and AI agents or LLMs consuming raw markdown. Wrap content in the appropriate block and EventCatalog handles the rest — no content forking required.
+
+**Example**
+
+```jsx /queries/GetInventoryList/index.mdx
+<Visibility for="humans">
+  Use the **Schema** and **Visualiser** actions on this page to inspect the
+  inventory query contract and its relationships.
+</Visibility>
+
+<Visibility for="agents">
+  When reasoning about this query, treat `GET /inventory` as a read-only
+  inventory lookup. Prefer linking this query to inventory reporting, order
+  placement, and stock reservation workflows.
+</Visibility>
+```
+
+### How it works
+
+In the browser UI, only `for="humans"` blocks render. The `for="agents"` block returns nothing and is never visible to human readers.
+
+When an AI agent or LLM fetches the raw markdown for a resource — via the `.md` / `.mdx` endpoints, the `/docs/llm/llms-full.txt` feed, custom docs, team/user pages, language pages, or diagram pages — the `for="humans"` blocks are stripped and only `for="agents"` content remains.
+
+This means the same file can give a human reader UI-oriented guidance ("click the Schema tab") while giving an agent structured, machine-actionable context ("treat this as a read-only lookup") without any duplication.
+
+### Props
+
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `for` | `"agents"` \| `"humans"` | Yes | The target audience for the wrapped content. |
+
+### Write effective agent content
+
+Use `for="agents"` blocks to provide context that helps AI tools reason about your architecture. Good agent content includes:
+
+- The intent and constraints of the resource ("read-only", "idempotent", "fires on every state change")
+- How the resource relates to other services or workflows
+- Edge cases or business rules that are not obvious from the schema
+
+Use `for="humans"` blocks for UI-oriented guidance: links to tabs, interactive tools, visual walkthroughs, or anything that only makes sense in a browser context.
+
+### Support
+
+`<Visibility>` is supported in domains, services, all messages, changelogs, custom documentation pages, team pages, user pages, language pages, and diagram pages.

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

@@ -0,0 +1,12 @@
+{
+  "label": "Components",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "components/list",
+    "title": "Components",
+    "description": "Reference for EventCatalog MDX components."
+  }
+}

package/dist/docs/development/components/diagram-syntax/01-mermaid.md

@@ -0,0 +1,218 @@
+---
+sidebar_position: 1
+keywords:
+- mermaid
+sidebar_label: Mermaid
+title: Using mermaid
+description: Understanding how to use mermaid with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<!-- 2.56.4 -->
+
+EventCatalog supports [mermaid](https://www.npmjs.com/package/mermaid) (v11.x) in all your markdown files.
+
+This let's you create [Class Diagrams](https://mermaid.js.org/syntax/classDiagram.html), [Sequence Diagrams](https://mermaid.js.org/syntax/sequenceDiagram.html), [Entity Relationship Diagrams](https://mermaid.js.org/syntax/entityRelationshipDiagram.html), [Architecture Diagrams](https://mermaid.js.org/syntax/architecture.html) and much more.
+
+## Using mermaid in EventCatalog
+
+There are two ways to use mermaid in EventCatalog.
+
+1. [Using the `mermaid` code block in any markdown file.](#using-the-mermaid-code-block-in-any-markdown-file)
+2. [Using Mermaid files `.mmd` and `.mermaid` files and loading them into your EventCatalog page.](#loading-mermaid-files-into-your-eventcatalog-page)
+    - _Added in EventCatalog 2.56.4_
+
+:::tip Diagrams not rendering?
+If you have large diagrams that fail to render, increase the `maxTextSize` configuration value. [Learn more about maxTextSize configuration](/docs/api/config#mermaid).
+:::
+
+### Using the `mermaid` code block in any markdown file.
+
+To use mermaid you need to use the `mermaid` code block in any markdown file.
+
+#### Example
+
+```markdown
+```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
+```_
+```
+
+This example will output the following in the markdown file.
+
+![Example output of mermaid](../img/mermaid.png)
+
+### Loading Mermaid files into your EventCatalog page.
+
+<AddedIn version="2.56.4" />
+
+You can load Mermaid files using the [`<MermaidFileLoader />`](/docs/development/components/components/mermaid-file-loader) component, if you prefer to use a file instead of a code block.
+
+Add your .mmd or .mermaid file to your folder (e.g `/events/MyEvent/mermaid.mmd`)
+
+```md /events/MyEvent/index.mdx
+---
+#event frontmatter
+---
+
+<!-- Using the .mmd file extension -->
+<MermaidFileLoader file="mermaid.mmd" />
+
+<!-- Using the .mermaid file extension -->
+<MermaidFileLoader file="my-second-mermaid-file.mermaid" />
+```
+
+This example will load a mermaid file (.mmd or .mermaid) into your EventCatalog page.
+
+**The file must be in the same directory as the markdown file.**
+
+---
+
+## Architecture diagrams with mermaid
+
+<AddedIn version="2.18.0" />
+
+Mermaid 11 introduced the [ability to create architecture diagrams](https://mermaid.js.org/syntax/architecture.html).
+
+You can use these diagrams to document your architecture.
+
+#### Example
+
+```markdown
+```mermaid
+architecture-beta
+    group api(cloud)[API]
+
+    service db(database)[Database] in api
+    service disk1(disk)[Storage] in api
+    service disk2(disk)[Storage] in api
+    service server(server)[Server] in api
+
+    db:L -- R:server
+    disk1:T -- B:server
+    disk2:T -- B:db
+
+```_
+```
+
+This example will output the following in the markdown file.
+
+<img src="/img/mermaid/mermaid-architecture.png" alt="Example output of mermaid" style={{width: "30%"}}/>
+
+## Architecture diagrams with icons
+
+<AddedIn version="2.18.0" />
+
+EventCatalog supports over **200,000 icons** from [icones.js.org](https://icones.js.org/collection/logos).
+
+To add icon support you need to add the icon pack into your `eventcatalog.config.js` file.
+
+```js
+// eventcatalog.config.js
+mermaid: {
+  iconPacks: ['logos'] // will load https://icones.js.org/collection/logos into eventcatalog
+}
+```
+
+In this example above we import the icon pack [logos](https://icones.js.org/collection/logos) from [icones.js.org](https://icones.js.org/collection/logos), but you can import any icon pack you like from [icones.js.org](https://icones.js.org/collection/logos).
+
+To use the icons in your mermaid diagrams you need to prefix the icon name with pack name. 
+
+In this example we are using the `logos` pack, so we prefix the icon name with `logos:`.
+
+```markdown
+```mermaid
+architecture-beta
+    group api(logos:aws-lambda)[API]
+
+    service db(logos:aws-aurora)[Database] in api
+    service disk1(logos:aws-glacier)[Storage] in api
+    service disk2(logos:aws-s3)[Storage] in api
+    service server(logos:aws-ec2)[Server] in api
+
+    db:L -- R:server
+    disk1:T -- B:server
+    disk2:T -- B:db
+```_
+```
+
+EventCatalog will then import the icons from the icon pack and render them in the diagram.
+
+<img src="/img/mermaid/mermaid-custom-icons.png" alt="Example output of mermaid" style={{width: "30%"}}/>
+
+## Mermaid with ELK (Eclipse Layout Kernel) layout algorithm
+
+<AddedIn version="2.61.2" />
+
+EventCatalog supports the [ELK (Eclipse Layout Kernel)](https://eclipse.dev/elk/) layout algorithm for mermaid diagrams.
+
+To add support for the ELK layout algorithm you need to add the following to your `eventcatalog.config.js` file.
+
+```js
+// eventcatalog.config.js
+mermaid: {
+  // default value is false
+  enableSupportForElkLayout: true
+}
+```
+
+After you set the value, mermaid will be configured to use the ELK layout algorithm.
+
+## Interactive controls
+
+<AddedIn version="3.4.1" />
+
+All Mermaid diagrams include interactive controls for better viewing and exploration.
+
+![Example output of mermaid](../img/interactive.png)
+
+### Zoom and pan
+
+Click and drag to pan around the diagram, or use the zoom controls in the bottom-left corner to zoom in and out. Double-click the diagram to zoom in quickly.
+
+### Presentation mode
+
+Click the presentation button in the top-left corner to view the diagram in fullscreen. In presentation mode, mouse wheel zooming is enabled for precise control.
+
+Press `Escape` to exit presentation mode.
+
+### Copy diagram code
+
+Click the copy button in the top-right corner to copy the diagram code to your clipboard. 
+
+Useful for copying diagrams into LLM prompts.
+
+## Export NodeGraphs as Mermaid
+
+<AddedIn version="3.9.0" />
+
+EventCatalog can export any NodeGraph visualization as Mermaid diagram code.
+
+Click the view switcher dropdown in any NodeGraph and select "Copy as Mermaid" to copy the diagram to your clipboard. The exported diagram preserves all nodes, edges, labels, and styling.
+
+You can then paste the Mermaid code into:
+- LLM prompts for architecture discussions
+- Other documentation tools
+- [mermaid.live](https://mermaid.live) for further editing
+- Mermaid code blocks in EventCatalog pages
+
+[Read more about NodeGraph controls](/docs/development/components/components/nodegraph#interactive-controls)
+
+### More resources
+
+- [Mermaid documentation](https://mermaid.js.org) - Learn more about mermaid and how to use it
+- [Icon packs](https://icones.js.org/) - Explore over 200,000 icons from iconify