@eventcatalog/core 5.0.0-beta.2 → 5.0.0-beta.20

package/eventcatalog/src/components/SideNav/NestedSideBar/utils.ts

@@ -1,7 +1,130 @@
 // Shared utilities for NestedSideBar components
 
+import type { ChildRef, NavigationData, NavNode } from '@stores/sidebar-store/state';
+
 export const SIDEBAR_GROUP_COLLAPSE_THRESHOLD = 5;
 
+/**
+ * Strip the configured base path from a pathname so URL pattern matching works
+ * regardless of the base path setting (e.g. `/eventcatalog/docs/...` → `/docs/...`).
+ */
+export const stripBasePath = (pathname: string): string => {
+  const base = __EC_BASE__.replace(/\/$/, ''); // e.g. '/eventcatalog'
+  if (base && pathname.startsWith(base)) {
+    return pathname.slice(base.length) || '/';
+  }
+  return pathname;
+};
+
+export type NavigationLevel = {
+  key: string | null; // The key of the node that was drilled into (null for root)
+  entries: ChildRef[];
+  title: string;
+  badge?: string; // Category badge (e.g., "Domain", "Service")
+};
+
+export const rootLevel = (roots: ChildRef[]): NavigationLevel => ({ key: null, entries: roots, title: 'Documentation' });
+
+/** Resolve a child reference to a node, following unversioned aliases (string → key). */
+export const resolveNavRef = (nodes: NavigationData['nodes'], ref: ChildRef): NavNode | null => {
+  if (typeof ref !== 'string') return ref;
+  const node = nodes[ref];
+  if (!node) return null;
+  if (typeof node === 'string') return (nodes[node] as NavNode) ?? null;
+  return node;
+};
+
+/** Map of "type:id" → versioned node key, used to match URLs to nodes. */
+export const buildNodeLookup = (nodes: NavigationData['nodes']): Map<string, string> => {
+  const lookup = new Map<string, string>();
+
+  Object.entries(nodes).forEach(([key, value]) => {
+    // Skip keys that are references (string values pointing to other keys)
+    // These are unversioned aliases like "domain:E-Commerce" -> "domain:E-Commerce:1.0.0"
+    if (typeof value === 'string') return;
+
+    // Key formats:
+    // - "type:id:version" (e.g., "service:OrdersService:0.0.3")
+    // - "type:id" (e.g., "user:john", "team:backend") - non-versioned resources
+    // - "list:name" (e.g., "list:domains") - skip these
+    const parts = key.split(':');
+
+    // Skip list items
+    if (parts[0] === 'list') return;
+
+    if (parts.length >= 2) {
+      // Store as "type:id"
+      lookup.set(`${parts[0]}:${parts[1]}`, key);
+    }
+  });
+
+  return lookup;
+};
+
+/**
+ * What the sidebar shows for a URL before it knows the reader's saved drill-down path:
+ * the root level on the homepage or for pages without children, otherwise the matching
+ * resource's own level (the same "flattened" stack the client falls back to).
+ */
+export const getStackForUrl = (
+  url: string,
+  data: NavigationData,
+  nodeLookup: ReadonlyMap<string, string> = buildNodeLookup(data.nodes)
+): NavigationLevel[] => {
+  const root = rootLevel(data.roots);
+  if (url === '/' || url === '') return [root];
+
+  const targetKey = findNodeKeyByUrl(url, data.nodes, nodeLookup);
+  const target = targetKey ? resolveNavRef(data.nodes, targetKey) : null;
+  if (!targetKey || !target?.pages?.length) return [root];
+
+  return [root, { key: targetKey, entries: target.pages, title: target.title, badge: target.badge }];
+};
+
+/**
+ * Everything the sidebar needs to render one page's level, without the whole catalog: the
+ * stack for the URL and only the nodes that level shows (its items, and the contents of its
+ * groups). Rendered on the server so the sidebar appears with the HTML, and handed to the
+ * island so it keeps showing it until the full navigation data loads.
+ */
+export type SidebarSnapshot = {
+  url: string;
+  stack: NavigationLevel[];
+  data: NavigationData;
+};
+
+const nodeLookupCache = new WeakMap<NavigationData, Map<string, string>>();
+
+export const buildSidebarSnapshot = (data: NavigationData, url: string): SidebarSnapshot => {
+  let nodeLookup = nodeLookupCache.get(data);
+  if (!nodeLookup) {
+    nodeLookup = buildNodeLookup(data.nodes);
+    nodeLookupCache.set(data, nodeLookup);
+  }
+
+  const stack = getStackForUrl(url, data, nodeLookup);
+  const level = stack[stack.length - 1];
+  const nodes: NavigationData['nodes'] = {};
+
+  const include = (ref: ChildRef) => {
+    if (typeof ref === 'string') {
+      if (ref in nodes) return;
+      const value = data.nodes[ref];
+      if (value === undefined) return;
+      nodes[ref] = value;
+      if (typeof value === 'string' && data.nodes[value] !== undefined) nodes[value] = data.nodes[value];
+    }
+    const node = resolveNavRef(data.nodes, ref);
+    // Groups render their children inline; items with children only need their own node
+    if (node?.type === 'group') node.pages?.forEach(include);
+  };
+
+  if (level.key) include(level.key);
+  level.entries.forEach(include);
+
+  return { url, stack, data: { roots: data.roots, nodes } };
+};
+
 /**
  * The user's overrides of each group's default collapse state, keyed by group id.
  * A group is in at most one set; absence means "use the group's default".
@@ -67,6 +190,14 @@ export const toggleGroupCollapsed = (
  * Finds the sidebar node represented by a resource URL.
  * The URL must have its configured base path removed before it is passed in.
  */
+/**
+ * Whether an item in a group drops its default per-collection icon because the group heading
+ * already conveys its type: every item under a nested group, and items whose icon is the
+ * group's own (e.g. events listed under Events). Custom icons (`leftIcon`) always show.
+ */
+export const hidesDefaultItemIcon = (group: NavNode, item: NavNode, isNested: boolean): boolean =>
+  isNested || (!!group.icon && group.icon === item.icon);
+
 export const findNodeKeyByUrl = (
   url: string,
   nodes: Record<string, unknown>,

package/eventcatalog/src/components/SideNav/SideNav.astro

@@ -3,10 +3,18 @@ import type { HTMLAttributes } from 'astro/types';
 
 interface Props extends Omit<HTMLAttributes<'div'>, 'children'> {}
 import NestedSideBar from './NestedSideBar';
+import { buildSidebarSnapshot, stripBasePath } from './NestedSideBar/utils';
+import { getNestedSideBarData } from '@stores/sidebar-store/state';
 import { ClientRouter } from 'astro:transitions';
+
+// Render this page's sidebar level into the HTML so it shows before any JavaScript runs;
+// the full navigation still loads from /api/sidebar-data.json (see SearchDataLoader)
+const snapshot = buildSidebarSnapshot(await getNestedSideBarData(), stripBasePath(Astro.url.pathname));
 ---
 
 <div {...Astro.props}>
   <ClientRouter />
-  <NestedSideBar client:only="react" />
+  <NestedSideBar client:only="react" snapshot={snapshot}>
+    <NestedSideBar slot="fallback" snapshot={snapshot} />
+  </NestedSideBar>
 </div>

package/eventcatalog/src/components/Tables/Discover/DiscoverTable.tsx

@@ -11,7 +11,7 @@ import {
   type ColumnFiltersState,
   type SortingState,
 } from '@tanstack/react-table';
-import { ArrowDown, ArrowUp, ArrowUpDown, ChevronLeft, ChevronRight, SearchX, X, Search, Users } from 'lucide-react';
+import { ArrowDown, ArrowUp, ArrowUpDown, SearchX, X, Search, Users } from 'lucide-react';
 import { UserIcon } from '@heroicons/react/24/outline';
 import { useEffect, useMemo, useState } from 'react';
 import type { TableConfiguration } from '@types';
@@ -19,6 +19,7 @@ import { isSameVersion } from '@utils/collections/version-compare';
 import { resolveIconUrl } from '@utils/icon';
 import { FilterDropdown, CheckboxItem } from './FilterComponents';
 import { getDiscoverColumns } from './columns';
+import { TablePagination, useStoredPageSize } from '../TablePagination';
 import { formatAdrStatus, type AdrStatus } from '@utils/collections/adr-constants';
 import { buildDiscoverFilterSearch, filterKnownValues, parseDiscoverFilterSearch } from './url-filters';
 
@@ -243,18 +244,7 @@ export function DiscoverTable<T extends DiscoverTableData>({
   const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
   const [sorting, setSorting] = useState<SortingState>([]);
   const [tableFilter, setTableFilter] = useState(initialUrlFilters.q);
-  const PAGE_SIZE_OPTIONS = [10, 25, 50, 100];
-  const PAGE_SIZE_STORAGE_KEY = 'eventcatalog-discover-page-size';
-  const [pageSize, setPageSize] = useState<number>(() => {
-    if (typeof window === 'undefined') return 10;
-    const stored = Number(window.localStorage.getItem(PAGE_SIZE_STORAGE_KEY));
-    return PAGE_SIZE_OPTIONS.includes(stored) ? stored : 10;
-  });
-  useEffect(() => {
-    if (typeof window !== 'undefined') {
-      window.localStorage.setItem(PAGE_SIZE_STORAGE_KEY, String(pageSize));
-    }
-  }, [pageSize]);
+  const [pageSize, setPageSize] = useStoredPageSize('eventcatalog-discover-page-size');
   const [showOnlyLatest, setShowOnlyLatest] = useState(initialUrlFilters.showOnlyLatest);
   const [onlyShowDrafts, setOnlyShowDrafts] = useState(initialUrlFilters.onlyShowDrafts);
   const [selectedDomains, setSelectedDomains] = useState<string[]>(() =>
@@ -1287,55 +1277,7 @@ export function DiscoverTable<T extends DiscoverTableData>({
           </div>
         </div>
 
-        {/* Pagination */}
-        <div className="flex-shrink-0 flex items-center justify-between px-6 py-3 border-t border-[rgb(var(--ec-page-border))]">
-          <div className="flex items-center gap-3 text-xs text-[rgb(var(--ec-page-text-muted))]">
-            {totalResults > 0 && (
-              <span>
-                <span className="font-medium text-[rgb(var(--ec-page-text))]">{table.getRowModel().rows.length}</span> of{' '}
-                <span className="font-medium text-[rgb(var(--ec-page-text))]">{totalResults}</span> results
-              </span>
-            )}
-            {totalResults > 0 && <span aria-hidden className="h-3 w-px bg-[rgb(var(--ec-page-border))]" />}
-            <label className="flex items-center gap-1.5">
-              <span>Per page</span>
-              <select
-                value={pageSize}
-                onChange={(e) => setPageSize(Number(e.target.value))}
-                className="cursor-pointer rounded bg-transparent px-1 py-0.5 font-medium text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))] focus:bg-[rgb(var(--ec-content-hover))] focus:outline-none"
-              >
-                {PAGE_SIZE_OPTIONS.map((size) => (
-                  <option key={size} value={size}>
-                    {size}
-                  </option>
-                ))}
-              </select>
-            </label>
-          </div>
-          <div className="flex items-center gap-1.5">
-            <button
-              className="p-1.5 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] disabled:opacity-30 disabled:cursor-not-allowed transition-colors"
-              onClick={() => table.previousPage()}
-              disabled={!table.getCanPreviousPage()}
-              title="Previous page"
-            >
-              <ChevronLeft className="w-4 h-4" />
-            </button>
-            <span className="text-xs tabular-nums text-[rgb(var(--ec-page-text-muted))] min-w-[60px] text-center">
-              <span className="font-medium text-[rgb(var(--ec-page-text))]">{table.getState().pagination.pageIndex + 1}</span>
-              {' / '}
-              <span>{table.getPageCount() || 1}</span>
-            </span>
-            <button
-              className="p-1.5 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] disabled:opacity-30 disabled:cursor-not-allowed transition-colors"
-              onClick={() => table.nextPage()}
-              disabled={!table.getCanNextPage()}
-              title="Next page"
-            >
-              <ChevronRight className="w-4 h-4" />
-            </button>
-          </div>
-        </div>
+        <TablePagination table={table} pageSize={pageSize} onPageSizeChange={setPageSize} />
       </div>
     </div>
   );

package/eventcatalog/src/components/Tables/Discover/columns.tsx

@@ -1,25 +1,16 @@
 import { createColumnHelper } from '@tanstack/react-table';
-import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
-import { createPortal } from 'react-dom';
-import { DocumentTextIcon, MapIcon } from '@heroicons/react/24/solid';
-import {
-  ArrowDownIcon,
-  ArrowTopRightOnSquareIcon,
-  ArrowUpIcon,
-  EllipsisVerticalIcon,
-  StarIcon,
-} from '@heroicons/react/24/outline';
+import { useMemo, useState } from 'react';
+import { ArrowDownIcon, ArrowTopRightOnSquareIcon, ArrowUpIcon } from '@heroicons/react/24/outline';
 import { buildUrl } from '@utils/url-builder';
 import { getColorAndIconForCollection } from '@utils/collections/icons';
 import { getCollectionTextColorClass } from '@utils/collection-colors';
 import { getBadgeHref, getBadgeReactStyle } from '@utils/badge-styles';
 import { isIconPath, resolveIconUrl } from '@utils/icon';
-import { useStore } from '@nanostores/react';
-import { favoritesStore, toggleFavorite, type FavoriteItem } from '../../../stores/favorites-store';
 import type { DiscoverTableData, CollectionType } from './DiscoverTable';
 import type { TableConfiguration } from '@types';
 import { formatAdrDate, isAdrCollection } from '@utils/collections/adr-constants';
 import { CornerDownRight } from 'lucide-react';
+import { RowActionsMenu } from '../RowActionsMenu';
 
 const columnHelper = createColumnHelper<DiscoverTableData>();
 
@@ -167,147 +158,23 @@ const ResourceNameCell = ({ item }: { item: DiscoverTableData }) => {
   );
 };
 
-const MENU_WIDTH = 280;
-const MENU_GAP = 6;
-
-const RowActionsMenu = ({ item, collectionType }: { item: DiscoverTableData; collectionType: CollectionType }) => {
-  const [isOpen, setIsOpen] = useState(false);
-  const buttonRef = useRef<HTMLButtonElement>(null);
-  const menuRef = useRef<HTMLDivElement>(null);
-  const [menuPosition, setMenuPosition] = useState<{ top: number; left: number } | null>(null);
-  const favorites = useStore(favoritesStore);
-  const href = buildUrl(`/docs/${item.collection}/${item.data.id}/${item.data.version}`);
-  const visualiserHref = buildUrl(`/visualiser/${item.collection}/${item.data.id}/${item.data.version}`);
-  const hasVisualiser = !isAdrCollection(item.collection);
-  const nodeKey = `${item.collection}-${item.data.id}-${item.data.version}`;
-  const badgeLabel =
+// Discover keys favorites as `${collection}-${id}-${version}`; keep that so existing favorites still match.
+const DiscoverRowActions = ({ item, collectionType }: { item: DiscoverTableData; collectionType: CollectionType }) => {
+  const badge =
     collectionType === 'external-systems'
       ? 'External System'
       : collectionType.charAt(0).toUpperCase() + collectionType.slice(1, -1);
-  const isFavorite = favorites.some((fav) => fav.nodeKey === nodeKey);
-
-  // The table lives inside scrollable, overflow-hidden containers, so the menu is
-  // rendered in a portal with fixed positioning to avoid being clipped.
-  const updatePosition = () => {
-    const button = buttonRef.current;
-    if (!button) return;
-    const rect = button.getBoundingClientRect();
-    const menuHeight = menuRef.current?.offsetHeight ?? 0;
-    const spaceBelow = window.innerHeight - rect.bottom;
-
-    // Flip above the trigger when there isn't enough room below it.
-    const openUpwards = menuHeight > 0 && spaceBelow < menuHeight + MENU_GAP && rect.top > spaceBelow;
-    const top = openUpwards ? rect.top - menuHeight - MENU_GAP : rect.bottom + MENU_GAP;
-    const left = Math.max(MENU_GAP, rect.right - MENU_WIDTH);
-
-    setMenuPosition({ top, left });
-  };
-
-  useLayoutEffect(() => {
-    if (!isOpen) return;
-    updatePosition();
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [isOpen]);
-
-  useEffect(() => {
-    if (!isOpen) return;
-
-    const handlePointerDown = (event: MouseEvent) => {
-      const target = event.target as Node;
-      if (!menuRef.current?.contains(target) && !buttonRef.current?.contains(target)) {
-        setIsOpen(false);
-      }
-    };
-
-    const handleEscape = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') {
-        setIsOpen(false);
-      }
-    };
-
-    const handleReposition = () => updatePosition();
-
-    document.addEventListener('mousedown', handlePointerDown);
-    document.addEventListener('keydown', handleEscape);
-    window.addEventListener('resize', handleReposition);
-    window.addEventListener('scroll', handleReposition, true);
-
-    return () => {
-      document.removeEventListener('mousedown', handlePointerDown);
-      document.removeEventListener('keydown', handleEscape);
-      window.removeEventListener('resize', handleReposition);
-      window.removeEventListener('scroll', handleReposition, true);
-    };
-  }, [isOpen]);
-
-  const handleToggleFavorite = () => {
-    const favoriteItem: FavoriteItem = {
-      nodeKey,
-      path: [],
-      title: item.data.name,
-      badge: badgeLabel,
-      href,
-    };
-    toggleFavorite(favoriteItem);
-    setIsOpen(false);
-  };
-
   return (
-    <div className="relative flex justify-end">
-      <button
-        ref={buttonRef}
-        type="button"
-        aria-haspopup="menu"
-        aria-expanded={isOpen}
-        onClick={() => setIsOpen((prev) => !prev)}
-        className="rounded-md p-1.5 text-[rgb(var(--ec-icon-color))] transition-colors hover:bg-[rgb(var(--ec-content-hover)/0.5)] hover:text-[rgb(var(--ec-page-text))]"
-      >
-        <EllipsisVerticalIcon className="h-4 w-4" />
-      </button>
-
-      {isOpen &&
-        typeof document !== 'undefined' &&
-        createPortal(
-          <div
-            ref={menuRef}
-            role="menu"
-            style={{
-              position: 'fixed',
-              top: menuPosition?.top ?? -9999,
-              left: menuPosition?.left ?? -9999,
-              width: MENU_WIDTH,
-              visibility: menuPosition ? 'visible' : 'hidden',
-            }}
-            className="z-50 overflow-hidden rounded-xl border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-dropdown-bg))] shadow-xl"
-          >
-            <a
-              href={href}
-              className="flex items-center gap-2.5 px-3 py-2.5 text-xs font-medium text-[rgb(var(--ec-page-text))] transition-colors hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-accent))]"
-            >
-              <DocumentTextIcon className="h-3.5 w-3.5 text-[rgb(var(--ec-page-text-muted))]" />
-              View documentation
-            </a>
-            {hasVisualiser && (
-              <a
-                href={visualiserHref}
-                className="flex items-center gap-2.5 px-3 py-2.5 text-xs font-medium text-[rgb(var(--ec-page-text))] transition-colors hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-accent))]"
-              >
-                <MapIcon className="h-3.5 w-3.5 text-[rgb(var(--ec-page-text-muted))]" />
-                View in visualiser
-              </a>
-            )}
-            <button
-              type="button"
-              onClick={handleToggleFavorite}
-              className="flex w-full items-center gap-2.5 px-3 py-2.5 text-left text-xs font-medium text-[rgb(var(--ec-page-text))] transition-colors hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-accent))]"
-            >
-              <StarIcon className="h-3.5 w-3.5 text-[rgb(var(--ec-page-text-muted))]" />
-              {isFavorite ? 'Remove from favorites' : 'Add to favorites'}
-            </button>
-          </div>,
-          document.body
-        )}
-    </div>
+    <RowActionsMenu
+      title={item.data.name}
+      href={buildUrl(`/docs/${item.collection}/${item.data.id}/${item.data.version}`)}
+      visualiserHref={
+        isAdrCollection(item.collection)
+          ? undefined
+          : buildUrl(`/visualiser/${item.collection}/${item.data.id}/${item.data.version}`)
+      }
+      favorite={{ nodeKey: `${item.collection}-${item.data.id}-${item.data.version}`, badge }}
+    />
   );
 };
 
@@ -319,7 +186,7 @@ const createActionsColumn = (collectionType: CollectionType, tableConfiguration:
     enableSorting: false,
     cell: (info) => {
       const item = info.row.original;
-      return <RowActionsMenu item={item} collectionType={collectionType} />;
+      return <DiscoverRowActions item={item} collectionType={collectionType} />;
     },
     meta: {
       showFilter: false,