@eventcatalog/core 3.35.0 → 3.36.1

package/dist/docs/development/customization/06-customize-tables.md

@@ -0,0 +1,194 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog tables
+sidebar_label: Customize tables
+title: Customize tables
+description: Customize tables in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.63.0" />
+
+EventCatalog allows you to customize the columns and names on the [Explore page](https://demo.eventcatalog.dev/discover/events), [Teams](https://demo.eventcatalog.dev/directory/teams) and [Users](https://demo.eventcatalog.dev/directory/users) pages.
+
+![EventCatalog Custom Tables](./img/table-example.png)
+
+### How to customize tables
+
+You can customize the tables in EventCatalog by configuring them in your `eventcatalog.config.js` file.
+
+Example of how to customize the tables for the events table page:
+
+
+```js title="eventcatalog.config.js"
+events: {
+  tableConfiguration: {
+    columns: {
+      name: { visible: true, label: 'Name' },
+      summary: { visible: true, label: 'Summary' },
+      producers: { visible: true, label: 'Producers' },
+      consumers: { visible: true, label: 'Consumers' },
+      badges: { visible: true, label: 'Badges' },
+      actions: { visible: true, label: 'Actions' },
+    }
+  },
+},
+```
+### Configuration
+
+List of available configuration options for the table columns:
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `visible` | boolean | true | Whether the column is visible. |
+| `label` | string | - | The label to display for the column. |
+
+<details>
+  <summary>Events, Queries and Commands Table</summary>
+
+The key property is either `events`, `queries`, `commands`.
+
+In this example we set the **events** table configuration.
+
+```js title="eventcatalog.config.js"
+// ... other configuration ...
+// change property to `events`, `queries`, `commands`
+events: {
+  tableConfiguration: {
+    columns: {
+      name: { visible: true, label: 'Name' },
+      summary: { visible: true, label: 'Summary' },
+      producers: { visible: true, label: 'Producers' },
+      consumers: { visible: true, label: 'Consumers' },
+      badges: { visible: true, label: 'Badges' },
+      actions: { visible: true, label: 'Actions' },
+    },
+  },
+}
+// ... other configuration ...
+```
+</details>
+<details>
+  <summary>Services Table</summary>
+
+```js title="eventcatalog.config.js"
+// ... other configuration ...
+services: {
+  tableConfiguration: {
+    columns: {
+      name: { visible: true, label: 'Name' },
+      summary: { visible: true, label: 'Summary' },
+      receives: { visible: true, label: 'Receives' },
+      sends: { visible: true, label: 'Sends' },
+      badges: { visible: true, label: 'Badges' },
+      actions: { visible: true, label: 'Actions' },
+    }
+  },
+}
+// ... other configuration ...
+```
+</details>
+<details>
+  <summary>Domains Table</summary>
+
+```js title="eventcatalog.config.js"
+// ... other configuration ...
+domains: {
+  tableConfiguration: {
+    columns: {
+      name: { visible: true, label: 'Name' },
+      summary: { visible: true, label: 'Summary' },
+      services: { visible: true, label: 'Owners' },
+      badges: { visible: true, label: 'Badges' },
+      actions: { visible: true, label: 'Actions' },
+    }
+  },
+}
+// ... other configuration ...
+```
+</details>
+<details>
+  <summary>Data Table</summary>
+
+```js title="eventcatalog.config.js"
+// ... other configuration ...
+containers: {
+  tableConfiguration: {
+    columns: {
+      name: { visible: true, label: 'Name' },
+      summary: { visible: true, label: 'Summary' },
+      writes: { visible: true, label: 'Writes' },
+      reads: { visible: true, label: 'Reads' },
+      badges: { visible: true, label: 'Badges' },
+      actions: { visible: true, label: 'Actions' },
+    }
+  },
+}
+// ... other configuration ...
+```
+</details>
+<details>
+  <summary>Flows Table</summary>
+
+```js title="eventcatalog.config.js"
+// ... other configuration ...
+flows: {
+  tableConfiguration: {
+    columns: {
+      name: { visible: true, label: 'Name' },
+      version: { visible: true, label: 'Version' },
+      summary: { visible: true, label: 'Summary' },
+      badges: { visible: true, label: 'Badges' },
+      actions: { visible: true, label: 'Actions' },
+    }
+  },
+}
+// ... other configuration ...
+```
+</details>
+<details>
+  <summary>Users Table</summary>
+
+```js title="eventcatalog.config.js"
+// ... other configuration ...
+users: {
+  tableConfiguration: {
+    columns: {
+      name: { visible: true, label: 'Name' },
+      ownedEvents: { visible: true, label: 'Owned Events' },
+      ownedCommands: { visible: true, label: 'Owned Commands' },
+      ownedQueries: { visible: true, label: 'Owned Queries' },
+      ownedServices: { visible: true, label: 'Owned Services' },
+      teams: { visible: true, label: 'Teams' },
+      actions: { visible: true, label: 'Actions' },
+    }
+  },
+}
+// ... other configuration ...
+```
+</details>
+<details>
+  <summary>Teams Table</summary>
+
+```js title="eventcatalog.config.js"
+// ... other configuration ...
+teams: {
+  tableConfiguration: {
+    columns: {
+      name: { visible: true, label: 'Name' },]
+      ownedEvents: { visible: true, label: 'Owned Events' },
+      ownedCommands: { visible: true, label: 'Owned Commands' },
+      ownedQueries: { visible: true, label: 'Owned Queries' },
+      ownedServices: { visible: true, label: 'Owned Services' },
+      actions: { visible: true, label: 'Actions' },
+    }
+  },
+}
+// ... other configuration ...
+```
+</details>
+
+
+
+You can read the `eventcatalog.config.js` API reference for [more information on the table configuration](/docs/api/config#domains).

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

@@ -0,0 +1,12 @@
+{
+  "label": "Customization",
+  "position": 7,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "development/customization",
+    "title": "Customization Documentation",
+    "description": "Learn how to customize EventCatalog."
+  }
+}

package/dist/docs/development/customization/custom-components/00-what-is-mdx.md

@@ -0,0 +1,73 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog components
+sidebar_label: What is MDX?
+title: What is MDX?
+description: What is MDX?
+---
+
+EventCatalog uses [MDX](https://mdxjs.com/) file format for documentation.
+
+Markdown is what powers EventCatalog, we encourage and follow a [docs-as-code approach](https://www.writethedocs.org/guide/docs-as-code/). This lets you write documentation in your favorite IDE and version control system, review changes, merge and deploy them.
+
+Using MDX gives you powerful features like:
+
+- [Writing and adding custom components to your documentation](/docs/development/customization/custom-components/introduction)
+- [Referring your frontmatter (title, description, image, etc) in your documentation](#how-to-refer-to-frontmatter-in-your-documentation)
+- [Using variables in your documentation](#how-to-use-variables-in-your-documentation)
+- And much more.
+
+## How to refer to frontmatter in your documentation
+
+You can refer to your frontmatter in your documentation using the `frontmatter` variable.
+
+```md title="events/MyEvent/index.mdx"
+---
+id: MyEvent
+name: My Event
+version: 1.0.0
+summary: My Event Summary
+---
+
+<!-- This will render My Event -->
+# {frontmatter.name}
+
+<!-- This will render My Event Summary -->
+{frontmatter.summary}
+```
+
+## How to use variables in your documentation
+
+MDX supports using the `export` statements to add variables to your documentation.
+
+For example you can export a `title` field from an MDX page or component and use it as a heading.
+
+```md title="events/MyEvent/index.mdx"
+---
+id: MyEvent
+name: My Event
+version: 1.0.0
+summary: My Event Summary
+---
+
+<!-- This will export the variable title -->
+export const title = "My Event"
+
+<!-- This will render the title -->
+# {title}
+
+```
+
+
+
+
+
+
+
+
+
+
+
+
+

package/dist/docs/development/customization/custom-components/01-introduction.md

@@ -0,0 +1,28 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog components
+sidebar_label: What are custom components?
+title: Introduction
+description: Add custom components to your catalog
+---
+
+EventCatalog provides the ability to add custom components to your domains, services and messages within your catalog. These features include:
+
+- Adding reuseable content across all your resources
+- Styling components with [Tailwind CSS](https://tailwindcss.com/) 
+- Adding custom [JavaScript to your pages](https://docs.astro.build/en/guides/client-side-scripts/#using-script-in-astro)
+
+
+
+### Why create components?
+
+Components are a great way to customize your EventCatalog and write shared snippets of code or content you can reuse across your EventCatalog.
+
+Components can be either [markdown files (component.mdx) or astro files (component.astro)](/docs/development/customization/custom-components/adding-components#types-of-components).
+
+:::info Astro components
+Custom components are powered by [Astro Components](https://docs.astro.build/en/basics/astro-components/). Read the Astro documentation to learn more about what you can include in your components. Custom components can be very powerful and allow some great customization.
+:::
+
+

package/dist/docs/development/customization/custom-components/02-adding-components.md

@@ -0,0 +1,145 @@
+---
+keywords:
+- EventCatalog components
+sidebar_label: Adding components
+title: Adding components
+description: Adding custom components to your catalog
+---
+
+The **components** directory is where your custom components will be created and stored.
+
+:::tip Upgrading your catalog?
+    If you don't have a `components` directory, you will need to create one in the root of your catalog (e.g `/my-catalog/components`)
+:::
+
+## Types of components
+
+EventCatalog supports [astro components](https://docs.astro.build/en/basics/astro-components/#_top) and markdown components. 
+
+1. Astro components - Dynamic components **(recommended)**
+    - Example `/my-catalog/components/my-component.astro`
+1. Markdown components - Static markdown files 
+    - Example `/my-catalog/components/my-component.mdx`    
+
+## Astro components (.astro)
+
+### Component structure
+
+Astro components are split into two parts the script and the template.
+
+``` title="/components/my-component.astro"
+---
+// Component Script (JavaScript)
+---
+<!-- Component Template (HTML + JS Expressions) -->
+```
+
+- **Component script**: Define variables, data, import components and make API requests [(read more)](https://docs.astro.build/en/basics/astro-components/#the-component-script)
+- **Component template**: Determines the HTML output. Also supports style and script tags. [(read more)](https://docs.astro.build/en/basics/astro-components/#the-component-template)
+
+#### Example
+
+1. First define your component.
+
+```md title="/components/my-component.astro"
+---
+# Import data from your eventcatalog.config.js file
+import config from "@config"
+# Access passed-in component props, like `<MyComponent title="Hello, World" />`
+const { subtitle } = Astro.props;
+---
+
+<main>
+    <span>This catalog belongs to the company:{config.organizationName}</span>
+    <span>Data given to this component {subtitle}</span>
+</main>
+
+```
+
+2. Import your component inside your domain, service or message.
+```md title="/events/OrderAccepted/index.mdx"
+---
+id: OrderAccepted
+name: Order Accepted
+# ... other event data
+---
+
+<!-- Import the component into your page -->
+import MyComponent from '@catalog/components/my-component.astro"
+
+# Overview 
+
+This event represents when an order has been accepted on our system.
+
+<!-- Render the component and pass props into it -->
+<MyComponent subtitle="This is a component" />
+
+```
+
+Read the full [astro guide here](https://docs.astro.build/en/basics/astro-components/#the-component-script).
+
+### Define variables inside your resources
+
+EventCatalog allows you to define variables inside your domains, services and messages that can be used to pass through to your custom components.
+
+```md title="/events/OrderAccepted/index.mdx"
+---
+id: OrderAccepted
+name: Order Accepted
+# ... other event data
+---
+
+<!-- Define your custom variable to use on this page -->
+export const MyCustomVariable = "Hello world";
+
+<!-- Import the component into your page -->
+import MyComponent from '@catalog/components/my-component.astro"
+
+# Overview 
+
+This event represents when an order has been accepted on our system.
+
+<!-- Render the component and pass custom variable to it -->
+<MyComponent subtitle={MyCustomVariable} />
+
+```
+
+### Reference frontmatter data in your components
+
+If you want to reference your domain, service or message data, you can reference the frontmatter information.
+
+```md title="/events/OrderAccepted/index.mdx"
+---
+id: OrderAccepted
+name: Order Accepted
+# ... other event data
+---
+
+<!-- Import the component into your page -->
+import MyComponent from '@catalog/components/my-component.astro"
+
+# Overview 
+
+This event represents when an order has been accepted on our system.
+
+<!-- Reference the name defined in your frontmatter -->
+<MyComponent subtitle={frontmatter.name} />
+
+```
+
+### Reference eventcatalog.config.js data in your components
+
+If you want to reference your eventcatalog.config.js data you can import it within your component.
+
+```md title="/components/my-component.astro"
+---
+# Import data from your eventcatalog.config.js file
+import config from "@config"
+---
+
+<main>
+    <span>This catalog belongs to the company: {config.organizationName}</span>
+    <span>This catalog title is: {config.title}</span>
+</main>
+
+```

package/dist/docs/development/customization/custom-components/03-component-styling.md

@@ -0,0 +1,27 @@
+---
+keywords:
+- EventCatalog components
+sidebar_label: Component styling
+title: Component styling
+description: Adding custom components to your catalog
+---
+
+EventCatalog uses [Tailwind](https://tailwindcss.com/). This means your custom components can be styled with tailwind.
+
+```md title="/components/my-component.astro"
+---
+# Import data from your eventcatalog.config.js file
+import config from "@config"
+# Access passed-in component props, like `<MyComponent title="Hello, World" />`
+const { subtitle } = Astro.props;
+---
+
+<main class="flex justify-center">
+    <span class="block bg-red-500">This catalog belongs to the company:{config.organizationName}</span>
+    <span class="block bg-yellow-500">Data given to this component {subtitle}</span>
+</main>
+
+```
+
+Read the full [astro guide here](https://docs.astro.build/en/basics/astro-components/#the-component-script).
+

package/dist/docs/development/customization/custom-components/04-javascript-components.md

@@ -0,0 +1,32 @@
+---
+keywords:
+  - EventCatalog components
+sidebar_label: Client side scripts
+title: Client side scripts
+description: Adding client side scripts to EventCatalog components
+---
+
+EventCatalog allows you to add client side JavaScript to your components.
+
+```md title="/components/my-component.astro"
+---
+# component template scripts.
+---
+
+<button class="alert">Click me!</button>
+
+<!-- This script will get called in the browser -->
+<script>
+  // Find all buttons with the `alert` class on the page.
+  const buttons = document.querySelectorAll('button.alert');
+
+  // Handle clicks on each button.
+  buttons.forEach((button) => {
+    button.addEventListener('click', () => {
+      alert('Button was clicked!');
+    });
+  });
+</script>
+```
+
+Read the [astro documentation for more information](https://docs.astro.build/en/guides/client-side-scripts/#using-script-in-astro).

package/dist/docs/development/customization/custom-components/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Write your own components",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/custom-components",
+    "description": "A collection of guides to help your understand and build custom components inside your catalog."
+  }
+}

package/dist/docs/development/customization/customize-sidebars/00-application-sidebar.md

@@ -0,0 +1,45 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog application sidebar
+sidebar_label: Application Sidebar
+title: Application Sidebar
+description: Pick and customize the application sidebar.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+The application sidebar is the sidebar that is rendered on every page in EventCatalog.
+
+![Example](../../guides/img/custom-sidebars/application-sidebar.png)
+
+### Show/hide items in the application sidebar
+
+You can show or hide items in the application sidebar by using the `sidebar` property in your `eventcatalog.config.js` file.
+
+**By default, all items is the sidebar are shown.**
+
+```js title="eventcatalog.config.js"
+// rest of the config
+sidebar: [
+  {
+    id: '/schemas/explorer',
+    // This will hide the Schema Explorer
+    visible: false,
+  },
+]
+```
+
+Options for the `sidebar` property:
+
+- `id`: The id of the item to hide.
+- `visible`: Whether to show or hide the item.
+
+| ID | Description |
+| --- | --- |
+| `/` | The home page icon |
+| `/docs` | The documentation page icon |
+| `/discover` | The discover page icon |
+| `/directory` | The users directory page icon |
+| `/studio` | The EventCatalog Studio icon |
+| `/schemas/explorer` | The schema explorer page |