@eventcatalog/core 4.1.3 → 4.1.4

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 9
 keywords:
 - components
 sidebar_label: Flow

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 10
 keywords:
 - components
 sidebar_label: Link

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 15
+sidebar_position: 11
 keywords:
 - components
 - remote schema

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 12
 keywords:
 - components
 sidebar_label: MessageTable

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 13
 keywords:
 - components
 sidebar_label: NodeGraph

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 14
 keywords:
 - components
 sidebar_label: OpenAPI
@@ -9,10 +9,10 @@ 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).
+This component is now deprecated. Please read the frontmatter API documentation [here](/docs/development/guides/resources/schemas/add-specifications-to-services/add-openapi-specifications).
 :::
 
-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).
+You can add specifications to any service in EventCatalog using the specifications frontmatter API. You can read more about it [here](/docs/development/guides/resources/schemas/add-specifications-to-services/add-openapi-specifications).
 
 If you are interested in automating your EventCatalog with OpenAPI files, you can use the [OpenAPI plugin](/docs/plugins/openapi/intro).
 

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 18
+sidebar_position: 15
 keywords:
   - components
   - prompt
@@ -15,7 +15,7 @@ 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 expand the card to inspect the prompt, copy it to their clipboard, or open it straight in Cursor with one click.
+`<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.
 
@@ -58,10 +58,6 @@ Use `actions={["copy"]}` (the default) when you only need clipboard support. Add
 
 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.
 
-### Inspect the prompt
-
-Every prompt card includes a **Show prompt** control. Expanding the card reveals the exact prompt text that will be copied or sent to Cursor.
-
 ### 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.

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 15
+sidebar_position: 16
 keywords:
 - components
 - remote schema
@@ -10,7 +10,7 @@ title: RemoteSchema
 description: Component for fetching and rendering remote schemas in EventCatalog
 ---
 
-import EventCatalogPro from '@site/src/components/MDX/EventCatalogPro';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
 import AddedIn from '@site/src/components/MDX/AddedIn';
 
 <AddedIn version="2.52.0" />
@@ -47,7 +47,9 @@ The `<RemoteSchema/>` component only works in Server-Side Rendering (SSR) mode.
 />
 ```
 
-**Fetching from Private APIs** <EventCatalogPro />
+### Fetching from Private APIs
+
+<PlanBanner plan="Scale" />
 
 For private APIs requiring authentication, you can provide headers:
 

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 17
 keywords:
 - components
 sidebar_label: ResourceGroupTable

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 18
 keywords:
 - components
 sidebar_label: ResourceLink

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 19
 keywords:
 - components
 sidebar_label: Schema

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 20
 keywords:
 - components
 sidebar_label: SchemaViewer

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 21
 keywords:
   - components
 sidebar_label: Steps

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 22
 keywords:
   - components
 sidebar_label: Tabs

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 23
 keywords:
   - components
 sidebar_label: Tiles

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 19
+sidebar_position: 24
 keywords:
   - components
   - visibility

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

@@ -1,6 +1,6 @@
 {
   "label": "Components",
-  "position": 3,
+  "position": 2,
   "collapsible": true,
   "collapsed": true,
   "link": {

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

@@ -0,0 +1,74 @@
+---
+sidebar_position: 1
+sidebar_label: Introduction
+title: Write your own components
+description: Learn when and why to create custom components in EventCatalog.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+EventCatalog is powered by [Astro](https://docs.astro.build/en/basics/astro-components/). This means you can create your own components and use them inside your catalog pages.
+
+Custom components are useful when you want to reuse the same block of UI or logic across services, events, domains, teams, and custom documentation pages.
+
+For example, you can create components for:
+
+- service health cards
+- ownership summaries
+- links to runbooks or dashboards
+- API status panels
+- scorecards
+- custom diagrams
+- metadata from another system
+
+## What you will create
+
+In this section, we will create a small component, render it in a service page, pass catalog data into it, fetch data from another system, and add simple browser behavior.
+
+By the end, you will have the main patterns you need to build your own reusable components.
+
+## Component types
+
+EventCatalog supports two types of custom component:
+
+- `.astro` components for reusable UI, JavaScript, data fetching, and dynamic rendering
+- `.mdx` components for reusable Markdown content
+
+Most custom components should be `.astro` files. They give you the most flexibility and match how EventCatalog renders built-in components.
+
+## Where components live
+
+Create custom components in the `components` directory at the root of your catalog.
+
+<ProjectTree
+  items={[
+    {
+      name: 'my-catalog',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'components',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'service-summary.astro', highlight: true }],
+        },
+        { name: 'services', type: 'folder' },
+        { name: 'events', type: 'folder' },
+        { name: 'eventcatalog.config.js' },
+      ],
+    },
+  ]}
+/>
+
+You can import these components into any MDX page using the `@catalog/components` alias.
+
+```tsx title="/services/OrderService/index.mdx"
+import ServiceSummary from '@catalog/components/service-summary.astro';
+
+<ServiceSummary />
+```
+
+:::tip
+Astro has its own component model. If you want to go deeper, read the [Astro components documentation](https://docs.astro.build/en/basics/astro-components/).
+:::

package/dist/docs/development/components/custom-components/02-create-your-first-component.md

@@ -0,0 +1,71 @@
+---
+sidebar_position: 2
+sidebar_label: Create your first component
+title: Create your first component
+description: Create a small reusable component and render it in a catalog page.
+---
+
+In this guide, we will create a simple component and add it to a service page.
+
+## Create the component
+
+Create a new file in your catalog.
+
+```txt title="File"
+/components/service-note.astro
+```
+
+Add the component markup.
+
+```jsx title="/components/service-note.astro"
+---
+const { title = 'Service note' } = Astro.props;
+---
+
+<aside class="not-prose rounded-lg border border-gray-200 bg-gray-50 p-4 dark:border-gray-800 dark:bg-gray-900">
+  <p class="m-0 text-sm font-semibold text-gray-900 dark:text-gray-100">{title}</p>
+  <p class="mb-0 mt-2 text-sm text-gray-600 dark:text-gray-300">
+    This note is rendered from a custom EventCatalog component.
+  </p>
+</aside>
+```
+
+The `not-prose` class keeps the documentation page typography from changing the spacing and styles inside your component.
+
+## Add it to a page
+
+Open one of your service pages and import the component.
+
+```markdown title="/services/OrderService/index.mdx"
+---
+id: OrderService
+name: Order Service
+version: 0.0.1
+summary: Handles customer orders.
+---
+
+import ServiceNote from '@catalog/components/service-note.astro';
+
+# Order Service
+
+<ServiceNote title="About this service" />
+```
+
+## Check the page
+
+Start your catalog and open the service page.
+
+```bash
+npm run dev
+```
+
+You should see the custom note rendered inside the service documentation.
+
+<div className="not-prose my-8 flex flex-col items-center gap-2">
+  <img src="/img/docs/custom-components/first-component.png" alt="Custom service note component rendered in EventCatalog" className="rounded-lg border border-gray-200 shadow-sm dark:border-gray-800" />
+  <span className="text-center text-sm italic text-gray-500 dark:text-gray-400">A custom component rendered inside an EventCatalog service page.</span>
+</div>
+
+:::tip
+Start small. Once you can render one component, the same pattern works for richer cards, tables, status panels, and diagrams.
+:::

package/dist/docs/development/components/custom-components/03-pass-data-into-components.md

@@ -0,0 +1,86 @@
+---
+sidebar_position: 3
+sidebar_label: Pass data into components
+title: Pass data into components
+description: Pass props, frontmatter, variables, and config data into custom components.
+---
+
+Components become more useful when they can render data from the page they are used on.
+
+## Use props
+
+Props are values passed into the component when you render it.
+
+```jsx title="/components/service-owner.astro"
+---
+const { team } = Astro.props;
+---
+
+<p class="not-prose text-sm">
+  Owned by <strong>{team}</strong>
+</p>
+```
+
+Render the component from a catalog page.
+
+```tsx title="/services/OrderService/index.mdx"
+import ServiceOwner from '@catalog/components/service-owner.astro';
+
+<ServiceOwner team="Commerce Platform" />
+```
+
+## Use frontmatter
+
+Every EventCatalog resource page has frontmatter. You can pass that data into your component.
+
+```markdown title="/services/OrderService/index.mdx"
+---
+id: OrderService
+name: Order Service
+version: 0.0.1
+summary: Handles customer orders.
+---
+
+import ServiceSummary from '@catalog/components/service-summary.astro';
+
+<ServiceSummary name={frontmatter.name} summary={frontmatter.summary} />
+```
+
+Then read those props in your component.
+
+```jsx title="/components/service-summary.astro"
+---
+const { name, summary } = Astro.props;
+---
+
+<section class="not-prose rounded-lg border border-gray-200 p-4 dark:border-gray-800">
+  <h2 class="m-0 text-lg font-semibold">{name}</h2>
+  <p class="mb-0 mt-2 text-sm text-gray-600 dark:text-gray-300">{summary}</p>
+</section>
+```
+
+## Use page variables
+
+You can export variables from an MDX page and pass them into a component.
+
+```tsx title="/services/OrderService/index.mdx"
+import ServiceStatus from '@catalog/components/service-status.astro';
+
+export const status = 'Stable';
+
+<ServiceStatus status={status} />
+```
+
+## Use catalog config
+
+You can import values from `eventcatalog.config.js` using `@config`.
+
+```jsx title="/components/catalog-name.astro"
+---
+import config from '@config';
+---
+
+<span>{config.title}</span>
+```
+
+Use this when a component needs shared catalog settings, organization names, or other global values.

package/dist/docs/development/components/custom-components/04-fetch-data-in-components.md

@@ -0,0 +1,191 @@
+---
+sidebar_position: 4
+sidebar_label: Fetch data
+title: Fetch data in components
+description: Fetch build-time, runtime, or browser data from custom EventCatalog components.
+---
+
+Custom components can fetch data from other systems. This is useful when your documentation needs to show information from tools such as internal platforms, service catalogs, monitoring systems, observability platforms, on-call tools, custom registries, schema registries, or deployment platforms.
+
+Astro components can use `await fetch()` in the component frontmatter. EventCatalog is powered by Astro, so the same pattern works in custom EventCatalog components.
+
+## Fetch and render data
+
+This example fetches a random user and renders their name and location.
+
+```jsx title="/components/random-user.astro"
+---
+const response = await fetch('https://randomuser.me/api/');
+const data = await response.json();
+const randomUser = data.results[0];
+---
+
+<article class="not-prose rounded-lg border border-gray-200 p-4 dark:border-gray-800">
+  <p class="m-0 text-sm font-semibold text-gray-900 dark:text-gray-100">
+    {randomUser.name.first} {randomUser.name.last}
+  </p>
+  <p class="mb-0 mt-2 text-sm text-gray-600 dark:text-gray-300">
+    {randomUser.location.city}, {randomUser.location.country}
+  </p>
+</article>
+```
+
+Use the component in a catalog page.
+
+```tsx title="/services/OrderService/index.mdx"
+import RandomUser from '@catalog/components/random-user.astro';
+
+<RandomUser />
+```
+
+The same pattern can be used to render data from systems your team already uses.
+
+For example, you might fetch:
+
+- a service owner from an internal platform API
+- a support rotation from an on-call tool
+- a maturity score from a scorecard system
+- repository metadata from GitHub
+- deployment metadata from your platform
+
+## Static builds
+
+By default, EventCatalog builds a static website.
+
+In a static build, `fetch()` calls in Astro component frontmatter run when the catalog is built. The fetched data is written into the generated HTML.
+
+This means:
+
+- the data is captured at build time
+- the page will not refetch that data for every viewer
+- the page updates when you rebuild and redeploy the catalog
+- a failed API request can fail the build unless you handle the error
+
+Static fetching works well for documentation data that does not need to change every time someone opens the page.
+
+```jsx title="/components/service-score.astro"
+---
+const { service } = Astro.props;
+
+let score = 'Unknown';
+
+try {
+  const response = await fetch(`https://platform.example.com/services/${service}/score`);
+  const data = await response.json();
+  score = data.score;
+} catch {
+  score = 'Unavailable';
+}
+---
+
+<span class="not-prose rounded-md border border-gray-200 px-2 py-1 text-sm dark:border-gray-800">
+  Score: {score}
+</span>
+```
+
+Use this pattern when the data can be slightly stale and tied to your documentation release process.
+
+## SSR builds
+
+EventCatalog can also run in [SSR mode](/docs/development/deployment/build-ssr-mode).
+
+In SSR mode, pages are rendered by a server. Astro frontmatter fetches run at runtime instead of only during the static build.
+
+This means:
+
+- the data can be fresher
+- the request can use server-side environment variables
+- the catalog needs a running server
+- slow APIs can slow down the page unless you cache or handle failures
+
+SSR mode is a better fit when the component needs private or frequently changing data.
+
+You can enable server output in `eventcatalog.config.js`.
+
+```js title="/eventcatalog.config.js"
+export default {
+  output: 'server',
+};
+```
+
+Read more about [EventCatalog static and server output](/docs/development/getting-started/develop-and-build#eventcatalog-static-vs-server-output).
+
+## Private APIs and API keys
+
+If the API requires a token, keep the token on the server.
+
+For static builds, the token can be available in your build environment. The fetch runs during the build, and only the rendered result is included in the generated HTML. You can store secrets in your `.env` file or deployment environment variables. Read more about [configuring environment variables](/docs/development/getting-started/configuration-overview#configuring-environment-variables).
+
+```jsx title="/components/internal-service-score.astro"
+---
+const { service } = Astro.props;
+
+const response = await fetch(`https://platform.example.com/services/${service}/score`, {
+  headers: {
+    Authorization: `Bearer ${process.env.PLATFORM_API_TOKEN}`,
+  },
+});
+
+const data = await response.json();
+---
+
+<span class="not-prose rounded-md border border-gray-200 px-2 py-1 text-sm dark:border-gray-800">
+  Score: {data.score}
+</span>
+```
+
+For SSR builds, the token is read by the server at runtime.
+
+:::caution
+Do not render API keys into the page, pass them to client-side scripts, or expose them through props that end up in HTML.
+:::
+
+If the request must happen in the browser, do not call private APIs directly with a secret. Use a server-side endpoint, proxy, or SSR component that keeps the token on the server.
+
+## Browser fetching
+
+Use browser fetching when the data should update after the page loads and does not require a private secret.
+
+```jsx title="/components/live-status.astro"
+---
+const { endpoint } = Astro.props;
+---
+
+<div data-service-status data-endpoint={endpoint} class="not-prose rounded-lg border border-gray-200 p-4 text-sm dark:border-gray-800">
+  Loading status...
+</div>
+
+<script>
+  const elements = document.querySelectorAll('[data-service-status]');
+
+  elements.forEach(async (element) => {
+    const endpoint = element.getAttribute('data-endpoint');
+
+    try {
+      const response = await fetch(endpoint);
+      const data = await response.json();
+      element.textContent = `Status: ${data.status}`;
+    } catch {
+      element.textContent = 'Status unavailable';
+    }
+  });
+</script>
+```
+
+Use the component in a page.
+
+```tsx title="/services/OrderService/index.mdx"
+import LiveStatus from '@catalog/components/live-status.astro';
+
+<LiveStatus endpoint="https://status.example.com/order-service.json" />
+```
+
+## Which pattern should you use?
+
+Use static build fetching when the data can be part of the generated documentation.
+
+Use SSR fetching when the data should be fresh at request time or needs private server-side credentials.
+
+Use browser fetching when the data is public and should update after the page loads.
+
+For more examples, read the [Astro data fetching documentation](https://docs.astro.build/en/guides/data-fetching/).

package/dist/docs/development/components/custom-components/05-style-components.md

@@ -0,0 +1,60 @@
+---
+sidebar_position: 5
+sidebar_label: Style components
+title: Style components
+description: Style custom EventCatalog components with Tailwind CSS.
+---
+
+EventCatalog includes Tailwind CSS. You can use Tailwind classes inside your custom components.
+
+```jsx title="/components/service-card.astro"
+---
+const { name, summary } = Astro.props;
+---
+
+<article class="not-prose rounded-lg border border-gray-200 bg-white p-4 shadow-sm dark:border-gray-800 dark:bg-gray-950">
+  <h2 class="m-0 text-base font-semibold text-gray-900 dark:text-gray-100">{name}</h2>
+  <p class="mb-0 mt-2 text-sm leading-6 text-gray-600 dark:text-gray-300">{summary}</p>
+</article>
+```
+
+Use the component from a catalog page.
+
+```tsx title="/services/OrderService/index.mdx"
+import ServiceCard from '@catalog/components/service-card.astro';
+
+<ServiceCard name={frontmatter.name} summary={frontmatter.summary} />
+```
+
+## Keep components readable
+
+Custom components usually sit inside documentation pages, so keep them simple.
+
+- Use small, focused components.
+- Prefer readable text over dense layouts.
+- Support light and dark mode.
+- Avoid large custom layouts unless the component needs them.
+
+## Use local styles when needed
+
+Astro components can include a `<style>` block.
+
+```jsx title="/components/status-pill.astro"
+---
+const { status } = Astro.props;
+---
+
+<span class="not-prose status-pill">{status}</span>
+
+<style>
+  .status-pill {
+    border: 1px solid var(--ifm-color-emphasis-300);
+    border-radius: 999px;
+    display: inline-flex;
+    font-size: 0.875rem;
+    padding: 0.125rem 0.5rem;
+  }
+</style>
+```
+
+Use Tailwind for most styling, and local CSS when a component needs a small custom rule.