@eventcatalog/core 5.7.2 → 5.7.5

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/changelog/_ChangelogPage.astro

@@ -0,0 +1,297 @@
+---
+import Footer from '@layouts/Footer.astro';
+import { getChangeLogs } from '@utils/collections/changelogs';
+import { render, getEntry } from 'astro:content';
+import mdxComponents from '@components/MDX/components';
+import 'diff2html/bundles/css/diff2html.min.css';
+import { getDiffDarkStyles } from '@components/SchemaExplorer/diff-dark-styles';
+
+import { buildUrl } from '@utils/url-builder';
+import { getPreviousVersion, getResourceNoun } from '@utils/collections/util';
+import { getDiffsForCurrentAndPreviousVersion } from '@utils/file-diffs';
+import { isIconPath, resolveIconUrl } from '@utils/icon';
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import Badge from '@components/Badge.astro';
+import { ClientRouter } from 'astro:transitions';
+import { HistoryIcon } from 'lucide-react';
+
+interface Props {
+  changelogOwner: any;
+}
+
+const props = Astro.props.changelogOwner;
+
+let collectionItem = props;
+const logs = await getChangeLogs(props);
+
+const { data } = props;
+const latestVersion = data.latestVersion;
+
+const renderedLogs = logs.map(async (log) => {
+  const logEntry = await getEntry('changelogs', log.id);
+  const { Content } = await render(logEntry as any);
+  return {
+    Content,
+    ...log,
+  };
+});
+
+const logsToRender = await Promise.all(renderedLogs);
+
+const logListPromise = logsToRender.map(async (log) => {
+  const currentLogVersion = log.data.version;
+  const previousLogVersion = log.data.version ? getPreviousVersion(log.data.version, data.versions || []) : '';
+  return {
+    id: log.id,
+    // Anchor for the version, linked from the "Versions" list on the right
+    anchor: `v${log.data.version}`,
+    url: buildUrl(`/docs/${props.collection}/${props.data.id}/${log.data.version}`),
+    isLatest: log.data.version === latestVersion,
+    version: log.data.version,
+    previousVersion: previousLogVersion,
+    createdAt: log.data.createdAt,
+    badges: log.data.badges || [],
+    Content: log.Content,
+    diffs:
+      currentLogVersion && previousLogVersion
+        ? await getDiffsForCurrentAndPreviousVersion(
+            currentLogVersion,
+            previousLogVersion,
+            collectionItem.data.id,
+            props.allCollectionItems
+          )
+        : [],
+  };
+});
+
+const logList = await Promise.all(logListPromise);
+
+const friendlyCollectionName = getResourceNoun(props.collection);
+const headerIconSrc = isIconPath(props.data.styles?.icon) ? resolveIconUrl(props.data.styles!.icon!) : null;
+
+const formatDate = (date?: Date) =>
+  date?.toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric', timeZone: 'UTC' });
+
+const releaseCount = `${logList.length} ${logList.length === 1 ? 'release' : 'releases'}`;
+---
+
+<VerticalSideBarLayout title={`${props.data.name} | Changelog`} description={props.data.summary}>
+  <main class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]">
+    <div class="flex docs-layout w-full">
+      <div class="w-full min-w-0 lg:mr-2 xl:pr-12 py-8 bg-[rgb(var(--ec-page-bg))]">
+        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-3 pt-4">
+          <div class="flex flex-col gap-4">
+            <span class="text-xs md:text-sm font-semibold text-[rgb(var(--ec-accent))]">Changelog</span>
+            <div class="flex items-center gap-3">
+              {
+                headerIconSrc && (
+                  <img src={headerIconSrc} alt={props.data.name} class="w-8 h-8 md:w-10 md:h-10 object-contain rounded-md shrink-0" />
+                )
+              }
+              <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">
+                {props.data.name}
+              </h2>
+            </div>
+          </div>
+          <p class="text-base pt-4 text-[rgb(var(--ec-page-text-muted))] font-light">
+            What changed in each version of {props.data.name}, newest first.
+          </p>
+          <div class="flex flex-wrap items-center gap-x-3 gap-y-2 pt-5 text-xs text-[rgb(var(--ec-page-text-muted))]">
+            <span>{releaseCount}</span>
+            {
+              latestVersion && (
+                <>
+                  <span aria-hidden="true" class="h-3 w-px bg-[rgb(var(--ec-page-border))]" />
+                  <span>Latest v{latestVersion}</span>
+                </>
+              )
+            }
+          </div>
+        </div>
+
+        {
+          logList.length === 0 && (
+            <div class="mt-8 rounded-lg border border-dashed border-[rgb(var(--ec-page-border))] px-6 py-10 text-center">
+              <HistoryIcon className="mx-auto h-6 w-6 text-[rgb(var(--ec-icon-color))]" strokeWidth={1.5} />
+              <p class="mt-3 text-sm font-semibold text-[rgb(var(--ec-page-text))]">No changelogs yet</p>
+              <p class="mt-1 text-sm text-[rgb(var(--ec-page-text-muted))]">
+                Add a <code>changelog.mdx</code> file next to this {friendlyCollectionName} to record what changed.
+              </p>
+            </div>
+          )
+        }
+
+        <ol class="changelog-timeline pt-4">
+          {
+            logList.map((log, index) => (
+              <li id={log.anchor} class="changelog-release relative scroll-mt-20 pl-8 pt-8">
+                {index !== logList.length - 1 && (
+                  <span aria-hidden="true" class="absolute left-[5px] top-[2.9rem] -bottom-[2.6rem] w-px bg-[rgb(var(--ec-page-border))]" />
+                )}
+                <span
+                  aria-hidden="true"
+                  class={`absolute left-0 top-[2.6rem] h-[11px] w-[11px] rounded-full ring-4 ring-[rgb(var(--ec-page-bg))] ${
+                    log.isLatest ? 'bg-[rgb(var(--ec-accent))]' : 'bg-[rgb(var(--ec-page-border))]'
+                  }`}
+                />
+                <div class="flex flex-wrap items-center gap-x-3 gap-y-2">
+                  <a
+                    href={log.url}
+                    class="text-xl font-bold text-[rgb(var(--ec-page-text))] hover:text-[rgb(var(--ec-accent))] transition-colors"
+                  >
+                    v{log.version}
+                  </a>
+                  {log.isLatest && (
+                    <span class="rounded-full bg-[rgb(var(--ec-accent-subtle))] px-2 py-0.5 text-xs font-medium text-[rgb(var(--ec-accent))]">
+                      Latest
+                    </span>
+                  )}
+                  {log.createdAt && (
+                    <time datetime={log.createdAt.toISOString()} class="text-sm text-[rgb(var(--ec-page-text-muted))]">
+                      {formatDate(log.createdAt)}
+                    </time>
+                  )}
+                </div>
+                {log.badges.filter(Boolean).length > 0 && (
+                  <div class="flex flex-wrap gap-1.5 pt-3">
+                    {log.badges.filter(Boolean).map((badge: any) => (
+                      <Badge badge={badge} />
+                    ))}
+                  </div>
+                )}
+                <div class="prose prose-md pt-2 pb-4 w-full text-[15px]">
+                  <log.Content components={mdxComponents(props)} />
+                </div>
+                {log.diffs && log.diffs.length > 0 && (
+                  <details class="changelog-diffs group mb-4 rounded-lg border border-[rgb(var(--ec-page-border))] overflow-hidden">
+                    <summary class="flex cursor-pointer list-none items-center justify-between gap-3 bg-[rgb(var(--ec-content-hover))] px-4 py-2.5 text-sm">
+                      <span class="text-[rgb(var(--ec-page-text))]">
+                        <span class="font-semibold">v{log.previousVersion}</span>
+                        <span class="mx-2 text-[rgb(var(--ec-page-text-muted))]">&rarr;</span>
+                        <span class="font-semibold">v{log.version}</span>
+                      </span>
+                      <span class="text-xs text-[rgb(var(--ec-page-text-muted))]">
+                        {log.diffs.length} {log.diffs.length === 1 ? 'file changed' : 'files changed'}
+                        <span class="ml-1 inline-block transition-transform group-open:rotate-90">&rsaquo;</span>
+                      </span>
+                    </summary>
+                    <div class="space-y-4 border-t border-[rgb(var(--ec-page-border))] p-2">
+                      {log.diffs.map((diff) => (
+                        <div set:html={diff} />
+                      ))}
+                    </div>
+                  </details>
+                )}
+              </li>
+            ))
+          }
+        </ol>
+        <Footer />
+      </div>
+      {
+        logList.length > 0 && (
+          <aside class="hidden xl:block sticky top-[4rem] self-start w-[280px] max-h-[calc(100vh-4rem)] overflow-y-auto py-2 flex-shrink-0 pr-4 bg-[rgb(var(--ec-page-bg))]">
+            <div class="mt-8">
+              <h3 class="text-xs text-[rgb(var(--ec-page-text))] font-semibold capitalize flex items-center gap-2 mb-4">
+                <HistoryIcon className="w-4 h-4" />
+                Versions
+              </h3>
+              <nav id="changelog-versions" class="text-xs border-l border-[rgb(var(--ec-page-border))]">
+                {logList.map((log) => (
+                  <a
+                    href={`#${log.anchor}`}
+                    data-version-anchor={log.anchor}
+                    class="flex items-center justify-between gap-2 py-1.5 pl-3 pr-2.5 leading-5 text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] border-l-2 border-transparent -ml-px transition-all duration-200"
+                  >
+                    <span>
+                      v{log.version}
+                      {log.isLatest && <span class="ml-1 text-[rgb(var(--ec-page-text-muted))]">(latest)</span>}
+                    </span>
+                    {log.createdAt && (
+                      <span class="shrink-0 text-[11px] text-[rgb(var(--ec-page-text-muted))]">
+                        {log.createdAt.toISOString().split('T')[0]}
+                      </span>
+                    )}
+                  </a>
+                ))}
+              </nav>
+            </div>
+          </aside>
+        )
+      }
+    </div>
+
+    <style is:global set:html={getDiffDarkStyles(":root[data-theme='dark'] .changelog-diffs")} />
+    <style is:global>
+      .docs-layout .prose {
+        max-width: none;
+        overflow: auto;
+      }
+      .changelog-diffs summary::-webkit-details-marker {
+        display: none;
+      }
+      #changelog-versions a.is-active {
+        color: rgb(var(--ec-accent));
+        border-color: rgb(var(--ec-accent));
+        font-weight: 500;
+      }
+    </style>
+
+    <script>
+      declare global {
+        interface Window {
+          __changelogVersionsScroll?: (event: Event) => void;
+        }
+      }
+
+      // Highlight the version in view in the "Versions" list, like "On this page" does for headings.
+      function setupVersionList() {
+        if (window.__changelogVersionsScroll) {
+          document.removeEventListener('scroll', window.__changelogVersionsScroll, true);
+          window.__changelogVersionsScroll = undefined;
+        }
+
+        const nav = document.getElementById('changelog-versions');
+        if (!nav) return;
+
+        const links = Array.from(nav.querySelectorAll<HTMLAnchorElement>('a[data-version-anchor]'));
+        const setActive = (anchor: string) => {
+          links.forEach((link) => link.classList.toggle('is-active', link.dataset.versionAnchor === anchor));
+        };
+
+        let paused = false;
+        links.forEach((link) =>
+          link.addEventListener('click', () => {
+            setActive(link.dataset.versionAnchor!);
+            paused = true;
+            setTimeout(() => (paused = false), 800);
+          })
+        );
+
+        // Each release is one tall block, so pick the last one whose top has scrolled past the
+        // top third of the screen, or the last release once the page is scrolled to the bottom.
+        const releases = Array.from(document.querySelectorAll<HTMLElement>('.changelog-release'));
+        const onScroll = (event: Event) => {
+          // Ignore other scrolling areas, like the sidebar
+          if (paused || (event.target instanceof HTMLElement && !event.target.contains(releases[0]))) return;
+          const scroller =
+            event.target instanceof HTMLElement ? event.target : (document.scrollingElement as HTMLElement | null);
+          const atBottom = scroller && scroller.scrollTop + scroller.clientHeight >= scroller.scrollHeight - 4;
+          const current = atBottom
+            ? releases[releases.length - 1]
+            : releases.filter((release) => release.getBoundingClientRect().top <= window.innerHeight / 3).pop();
+          setActive((current ?? releases[0])?.id ?? '');
+        };
+
+        window.__changelogVersionsScroll = onScroll;
+        document.addEventListener('scroll', onScroll, { capture: true, passive: true });
+
+        setActive(decodeURIComponent(location.hash.slice(1)) || links[0]?.dataset.versionAnchor || '');
+      }
+
+      // The page uses the ClientRouter, so this fires on the first load and after every navigation.
+      document.addEventListener('astro:page-load', setupVersionList);
+    </script>
+  </main>
+  <ClientRouter />
+</VerticalSideBarLayout>

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/changelog/_index.data.spec.ts

@@ -0,0 +1,101 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { getLatestServiceChangelogPaths, Page, ServicePage } from './_index.data';
+
+const COLLECTIONS = ['agents', 'events', 'commands', 'queries', 'services', 'domains', 'systems', 'flows', 'containers'];
+
+const mocks = vi.hoisted(() => ({
+  isSSR: vi.fn(),
+  isChangelogEnabled: vi.fn(),
+  loaders: {} as Record<string, ReturnType<typeof vi.fn>>,
+  getServices: vi.fn(),
+}));
+
+vi.mock('@utils/feature', () => ({
+  isSSR: () => mocks.isSSR(),
+  isChangelogEnabled: () => mocks.isChangelogEnabled(),
+}));
+vi.mock('@utils/changelog-resource-badge', () => ({
+  changelogResourceCollections: ['agents', 'events', 'commands', 'queries', 'services', 'domains', 'systems', 'flows', 'containers'],
+}));
+vi.mock('@utils/collections/services', () => ({
+  getServices: () => mocks.getServices(),
+}));
+vi.mock('@utils/page-loaders/page-data-loader', () => ({
+  pageDataLoader: new Proxy({}, { get: (_target, type: string) => mocks.loaders[type] }),
+}));
+
+const item = (id: string, version: string) => ({ collection: 'any', data: { id, version } });
+
+describe('Changelog routes', () => {
+  beforeEach(() => {
+    mocks.isSSR.mockReset().mockReturnValue(false);
+    mocks.isChangelogEnabled.mockReset().mockReturnValue(true);
+    mocks.loaders = Object.fromEntries(COLLECTIONS.map((type) => [type, vi.fn().mockResolvedValue([item(`${type}-1`, '1.0.0')])]));
+  });
+
+  it('gives every type but services a path on the generic route', async () => {
+    const paths = await Page.getStaticPaths();
+
+    expect(paths.map(({ params }) => params.type)).toEqual(COLLECTIONS.filter((type) => type !== 'services'));
+    expect(paths[0].params).toEqual({ type: 'agents', id: 'agents-1', version: '1.0.0' });
+    expect(mocks.loaders.services).not.toHaveBeenCalled();
+  });
+
+  it('gives one path per service id and version on the service route', async () => {
+    const orders1 = item('Orders', '1.0.0');
+    mocks.loaders.services.mockResolvedValue([orders1, item('Orders', '2.0.0'), item('Billing', '1.0.0')]);
+
+    const paths = await ServicePage.getStaticPaths();
+
+    expect(paths.map(({ params }) => params)).toEqual([
+      { id: 'Orders', version: '1.0.0' },
+      { id: 'Orders', version: '2.0.0' },
+      { id: 'Billing', version: '1.0.0' },
+    ]);
+    expect(paths[0].props).toMatchObject({ type: 'services', ...orders1 });
+  });
+
+  it('has no static paths on a server', async () => {
+    mocks.isSSR.mockReturnValue(true);
+
+    expect(await Page.getStaticPaths()).toEqual([]);
+    expect(await ServicePage.getStaticPaths()).toEqual([]);
+  });
+
+  it('has no static paths when the changelog is disabled', async () => {
+    mocks.isChangelogEnabled.mockReturnValue(false);
+
+    expect(await Page.getStaticPaths()).toEqual([]);
+    expect(await ServicePage.getStaticPaths()).toEqual([]);
+  });
+
+  it('forces the services type when fetching on the service route', async () => {
+    mocks.loaders.services.mockResolvedValue([item('Orders', '1.0.0')]);
+
+    const data = await ServicePage.getData({ params: { id: 'Orders', version: '1.0.0', type: 'events' }, props: {} } as any);
+
+    expect(data).toMatchObject({ type: 'services', data: { id: 'Orders', version: '1.0.0' } });
+    expect(mocks.loaders.events).not.toHaveBeenCalled();
+  });
+
+  it('returns nothing for an unknown version or a disabled changelog', async () => {
+    mocks.loaders.services.mockResolvedValue([item('Orders', '1.0.0')]);
+
+    await expect(ServicePage.getData({ params: { id: 'Orders', version: '9.9.9' }, props: {} } as any)).resolves.toBeUndefined();
+
+    mocks.isChangelogEnabled.mockReturnValue(false);
+    await expect(ServicePage.getData({ params: { id: 'Orders', version: '1.0.0' }, props: {} } as any)).resolves.toBeUndefined();
+  });
+
+  it('gives the version-less service changelog alias a path for the latest version of each service', async () => {
+    mocks.loaders.services.mockResolvedValue([item('Orders', '1.0.0'), item('Orders', '2.0.0'), item('Billing', '1.0.0')]);
+    mocks.getServices.mockResolvedValue([item('Orders', '2.0.0'), item('Billing', '1.0.0')]);
+
+    const paths = await getLatestServiceChangelogPaths();
+
+    expect(paths.map(({ params, props }) => ({ params, redirectVersion: props?.redirectVersion }))).toEqual([
+      { params: { id: 'Orders' }, redirectVersion: '2.0.0' },
+      { params: { id: 'Billing' }, redirectVersion: '1.0.0' },
+    ]);
+  });
+});

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/changelog/_index.data.ts

@@ -2,61 +2,90 @@ import { isSSR, isChangelogEnabled } from '@utils/feature';
 import { changelogResourceCollections } from '@utils/changelog-resource-badge';
 import { HybridPage } from '@utils/page-loaders/hybrid-page';
 import type { PageTypes } from '@types';
+import { getLatestServicePaths } from '../../../../services/_latest-version-route';
 
-export class Page extends HybridPage {
-  static get prerender(): boolean {
-    return !isSSR();
-  }
+// Services have their own route (pages/docs/services/[id]/[version]/changelog), because the
+// version-less alias /docs/services/[id]/[docType]/[docId] outranks this generic route and
+// would otherwise catch /docs/services/{id}/{version}/changelog.
+const GENERIC_ROUTE_TYPES = changelogResourceCollections.filter((type) => type !== 'services');
 
-  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
-    if (isSSR() || !isChangelogEnabled()) {
-      return [];
+type RouteParams = { type?: string; id?: string; version?: string };
+
+const createChangelogPage = ({
+  types,
+  toParams,
+  typeOf,
+}: {
+  types: PageTypes[];
+  toParams: (type: PageTypes, item: any) => RouteParams;
+  typeOf: (params: RouteParams) => string | undefined;
+}) =>
+  class extends HybridPage {
+    static get prerender(): boolean {
+      return !isSSR();
     }
 
-    const { pageDataLoader } = await import('@utils/page-loaders/page-data-loader');
-
-    const itemTypes: PageTypes[] = [...changelogResourceCollections];
-    const allItems = await Promise.all(itemTypes.map((type) => pageDataLoader[type]()));
-
-    return allItems.flatMap((items, index) =>
-      items.map((item) => ({
-        params: {
-          type: itemTypes[index],
-          id: item.data.id,
-          version: item.data.version,
-        },
-        props: {
-          type: itemTypes[index],
-          allCollectionItems: items,
-          ...item,
-        },
-      }))
-    );
-  }
-
-  protected static async fetchData(params: any) {
-    const { type, id, version } = params;
-
-    if (!type || !id || !version || !isChangelogEnabled()) {
-      return null;
+    static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
+      if (isSSR() || !isChangelogEnabled()) {
+        return [];
+      }
+
+      const { pageDataLoader } = await import('@utils/page-loaders/page-data-loader');
+
+      const allItems = await Promise.all(types.map((type) => pageDataLoader[type]()));
+
+      return allItems.flatMap((items, index) =>
+        items.map((item) => ({
+          params: toParams(types[index], item),
+          props: {
+            type: types[index],
+            allCollectionItems: items,
+            ...item,
+          },
+        }))
+      );
     }
 
-    const { pageDataLoader } = await import('@utils/page-loaders/page-data-loader');
+    protected static async fetchData(params: RouteParams) {
+      const type = typeOf(params);
+      const { id, version } = params;
 
-    // Get all items of the specified type
-    const items = await pageDataLoader[type as PageTypes]();
+      if (!type || !id || !version || !isChangelogEnabled()) {
+        return null;
+      }
 
-    // Find the specific item by id and version
-    const item = items.find((i) => i.data.id === id && i.data.version === version);
+      const { pageDataLoader } = await import('@utils/page-loaders/page-data-loader');
 
-    if (!item) {
-      return null;
+      const items = await pageDataLoader[type as PageTypes]();
+      const item = items.find((i) => i.data.id === id && i.data.version === version);
+
+      if (!item) {
+        return null;
+      }
+
+      return {
+        type,
+        allCollectionItems: items,
+        ...item,
+      };
     }
+  };
+
+export const Page = createChangelogPage({
+  types: GENERIC_ROUTE_TYPES as PageTypes[],
+  toParams: (type, item) => ({ type, id: item.data.id, version: item.data.version }),
+  typeOf: (params) => params.type,
+});
+
+export const ServicePage = createChangelogPage({
+  types: ['services'],
+  toParams: (_type, item) => ({ id: item.data.id, version: item.data.version }),
+  typeOf: () => 'services',
+});
 
-    return {
-      type,
-      allCollectionItems: items,
-      ...item,
-    };
-  }
-}
+// Static paths for the version-less /docs/services/[id]/changelog alias. The service route has no
+// [type] segment, so put it back for getLatestServicePaths, which only keeps services.
+export const getLatestServiceChangelogPaths = async () => {
+  const paths = await ServicePage.getStaticPaths();
+  return getLatestServicePaths(paths.map(({ params, props }) => ({ params: { ...params, type: 'services' }, props })));
+};