@eventcatalog/core 3.35.1 → 3.36.1

package/eventcatalog/src/components/Search/search-utils.spec.ts

@@ -1,5 +1,14 @@
 import { describe, expect, it, beforeEach } from 'vitest';
-import { getUrlForSearchItem } from './search-utils';
+import {
+  applyActiveFilter,
+  getIndexedResultRank,
+  getSearchFilters,
+  getUrlForSearchItem,
+  hasMeaningfulIndexedMatch,
+  highlightQuery,
+  mapPagefindResultsToSearchItems,
+  normalizeResultUrl,
+} from './search-utils';
 
 declare global {
   interface Window {
@@ -34,3 +43,131 @@ describe('getUrlForSearchItem', () => {
     expect(getUrlForSearchItem({}, 'unknown:Customer360:1.0.0')).toBeNull();
   });
 });
+
+describe('indexed search result helpers', () => {
+  it('filters weak single-character highlighted matches for longer queries', () => {
+    expect(
+      hasMeaningfulIndexedMatch({
+        query: 'random',
+        title: 'Orders Service',
+        content: 'Order Metadata in api service server logs',
+        excerpt: 'Order Metadata in api db L -- <mark>R</mark> server',
+      })
+    ).toBe(false);
+  });
+
+  it('keeps short but meaningful marked terms', () => {
+    expect(
+      hasMeaningfulIndexedMatch({
+        query: 'db',
+        title: 'Orders Service',
+        content: 'Order Metadata in api service server logs',
+        excerpt: 'Order Metadata in api <mark>db</mark>',
+      })
+    ).toBe(true);
+  });
+
+  it('keeps exact title or content matches even without marked excerpts', () => {
+    expect(
+      hasMeaningfulIndexedMatch({
+        query: 'payments',
+        title: 'Payments Database',
+        content: '',
+        excerpt: '',
+      })
+    ).toBe(true);
+
+    expect(
+      hasMeaningfulIndexedMatch({
+        query: 'idempotency',
+        title: 'Payments Database',
+        content: 'Always include an idempotency key in payment creation.',
+        excerpt: '',
+      })
+    ).toBe(true);
+  });
+
+  it('normalizes Pagefind URLs to root-relative paths', () => {
+    expect(normalizeResultUrl('docs/containers/payments-db/0.0.1')).toBe('/docs/containers/payments-db/0.0.1');
+    expect(normalizeResultUrl('/docs/containers/payments-db/0.0.1')).toBe('/docs/containers/payments-db/0.0.1');
+    expect(normalizeResultUrl('https://example.com/docs')).toBe('https://example.com/docs');
+  });
+
+  it('highlights title matches while escaping unsafe title text', () => {
+    expect(highlightQuery('Payment <Service>', 'payment')).toBe('<mark>Payment</mark> &lt;Service&gt;');
+  });
+
+  it('ranks title matches above id/url matches and content matches', () => {
+    const query = 'payment';
+    const contentRank = getIndexedResultRank({
+      query,
+      title: 'Orders Service',
+      url: '/docs/services/OrdersService/1.0.0',
+      content: 'Handles payment retries',
+    });
+    const urlRank = getIndexedResultRank({
+      query,
+      title: 'Orders Service',
+      url: '/docs/services/PaymentService/1.0.0',
+      content: 'Handles orders',
+    });
+    const titleRank = getIndexedResultRank({
+      query,
+      title: 'Payment Service',
+      url: '/docs/services/PaymentService/1.0.0',
+      content: 'Handles orders',
+    });
+
+    expect(titleRank).toBeGreaterThan(urlRank);
+    expect(urlRank).toBeGreaterThan(contentRank);
+  });
+
+  it('applies grouped search filters', () => {
+    const items = [{ type: 'Event' }, { type: 'Command' }, { type: 'Team' }, { type: 'User' }, { type: 'Service' }];
+
+    expect(applyActiveFilter(items, 'Message')).toEqual([{ type: 'Event' }, { type: 'Command' }]);
+    expect(applyActiveFilter(items, 'Team')).toEqual([{ type: 'Team' }, { type: 'User' }]);
+    expect(applyActiveFilter(items, 'Service')).toEqual([{ type: 'Service' }]);
+  });
+
+  it('builds filter metadata without encoding behavior in labels', () => {
+    expect(getSearchFilters({ items: [], query: 'missing' })).toEqual([{ id: 'all', name: 'All (0)', count: 0 }]);
+    expect(getSearchFilters({ items: [{ type: 'Event' }, { type: 'Service' }], query: 'order' })).toEqual([
+      { id: 'all', name: 'All (2)', count: 2 },
+      { id: 'Service', name: 'Services (1)', count: 1 },
+      { id: 'Message', name: 'Messages (1)', count: 1 },
+    ]);
+  });
+
+  it('maps Pagefind results into ranked search items', async () => {
+    const items = await mapPagefindResultsToSearchItems({
+      query: 'payment',
+      limit: 10,
+      results: [
+        {
+          id: 'content',
+          score: 10,
+          data: async () => ({
+            url: 'docs/services/OrdersService/1.0.0',
+            content: 'Handles payment retries',
+            excerpt: 'Handles <mark>payment</mark> retries',
+            meta: { title: 'Orders Service', type: 'Service', id: 'OrdersService' },
+          }),
+        },
+        {
+          id: 'title',
+          score: 1,
+          data: async () => ({
+            url: 'docs/services/PaymentService/1.0.0',
+            content: 'Handles orders',
+            excerpt: '<mark>Payment</mark> service',
+            meta: { title: 'Payment Service', type: 'Service', id: 'PaymentService' },
+          }),
+        },
+      ],
+    });
+
+    expect(items.map((item) => item.id)).toEqual(['title', 'content']);
+    expect(items[0].url).toBe('/docs/services/PaymentService/1.0.0');
+  });
+});

package/eventcatalog/src/components/Search/search-utils.ts

@@ -1,5 +1,49 @@
 import { buildUrl } from '@utils/url-builder';
 
+export interface SearchNode {
+  key: string;
+  title: string;
+  badge?: string;
+  summary?: string;
+  href?: string;
+  icon?: string;
+  leftIcon?: string;
+}
+
+export interface SearchItem {
+  id: string;
+  name: string;
+  url: string;
+  type: string;
+  key?: string;
+  rawNode: {
+    title?: string;
+    badge?: string;
+    summary?: string;
+    icon?: string;
+    leftIcon?: string;
+    matchedExcerpt?: string;
+  };
+  isFavorite?: boolean;
+}
+
+export interface SearchFilter {
+  id: string;
+  name: string;
+  count: number;
+}
+
+interface PagefindResult {
+  id: string;
+  score?: number;
+  data: () => Promise<{
+    url: string;
+    excerpt?: string;
+    content?: string;
+    meta?: Record<string, any>;
+  }>;
+}
+
 const docsPathByType: Record<string, string> = {
   channel: 'channels',
   command: 'commands',
@@ -32,3 +76,230 @@ export const getUrlForSearchItem = (node: { href?: string }, key: string) => {
 
   return buildUrl(`/docs/${docsPath}/${id}/${version}`);
 };
+
+export const stripHtml = (value: string) =>
+  value
+    .replace(/<[^>]+>/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+const escapeHtml = (value: string) =>
+  value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+
+const escapeRegExp = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+const getSearchTerms = (query: string) => [...new Set(query.trim().toLowerCase().split(/\s+/).filter(Boolean))];
+
+const getMarkedTerms = (value: string) => {
+  return [...value.matchAll(/<mark>(.*?)<\/mark>/gi)].map((match) => stripHtml(match[1]).toLowerCase());
+};
+
+export const highlightQuery = (value: string, query: string) => {
+  const terms = getSearchTerms(query).sort((a, b) => b.length - a.length);
+
+  if (terms.length === 0) {
+    return escapeHtml(value);
+  }
+
+  const termLookup = new Set(terms);
+  const pattern = new RegExp(`(${terms.map(escapeRegExp).join('|')})`, 'gi');
+
+  return value
+    .split(pattern)
+    .map((part) => (termLookup.has(part.toLowerCase()) ? `<mark>${escapeHtml(part)}</mark>` : escapeHtml(part)))
+    .join('');
+};
+
+export const normalizeResultUrl = (url: string) => {
+  if (/^(https?:)?\/\//.test(url) || url.startsWith('/')) {
+    return url;
+  }
+
+  return `/${url}`;
+};
+
+export const hasMeaningfulIndexedMatch = ({
+  query,
+  title,
+  content,
+  excerpt,
+}: {
+  query: string;
+  title: string;
+  content?: string;
+  excerpt: string;
+}) => {
+  const terms = getSearchTerms(query);
+  if (terms.length === 0) {
+    return false;
+  }
+
+  const searchableText = `${title} ${content || ''}`.toLowerCase();
+  if (terms.some((term) => searchableText.includes(term))) {
+    return true;
+  }
+
+  const minimumMarkedLength = Math.min(3, Math.max(...terms.map((term) => term.length)));
+  return getMarkedTerms(excerpt).some((term) => term.length >= minimumMarkedLength);
+};
+
+export const getIndexedResultRank = ({
+  query,
+  title,
+  id,
+  url,
+  content,
+}: {
+  query: string;
+  title: string;
+  id?: string;
+  url: string;
+  content?: string;
+}) => {
+  const terms = getSearchTerms(query);
+  const titleText = title.toLowerCase();
+  const identityText = `${id || ''} ${url}`.toLowerCase();
+  const contentText = (content || '').toLowerCase();
+
+  if (terms.some((term) => titleText.includes(term))) return 3;
+  if (terms.some((term) => identityText.includes(term))) return 2;
+  if (terms.some((term) => contentText.includes(term))) return 1;
+  return 0;
+};
+
+export const applyActiveFilter = <T extends { type: string }>(items: T[], activeFilter: string) => {
+  if (activeFilter === 'all') {
+    return items;
+  }
+
+  if (activeFilter === 'Message') {
+    return items.filter((item) => ['Event', 'Command', 'Query'].includes(item.type));
+  }
+
+  if (activeFilter === 'Team') {
+    return items.filter((item) => ['Team', 'User'].includes(item.type));
+  }
+
+  return items.filter((item) => item.type === activeFilter);
+};
+
+export const getSearchFilters = ({ items, query }: { items: Array<{ type: string }>; query: string }): SearchFilter[] => {
+  if (!items.length && query !== '') {
+    return [{ id: 'all', name: 'All (0)', count: 0 }];
+  }
+
+  const counts: Record<string, number> = {
+    all: items.length,
+    Domain: 0,
+    Service: 0,
+    Message: 0,
+    Team: 0,
+    Container: 0,
+    Entity: 0,
+    Design: 0,
+    Channel: 0,
+    Flow: 0,
+    'Data Product': 0,
+    'Custom Doc': 0,
+    'Resource Doc': 0,
+    Changelog: 0,
+  };
+
+  items.forEach((item) => {
+    if (counts[item.type] !== undefined) {
+      counts[item.type]++;
+    }
+
+    if (['Event', 'Command', 'Query'].includes(item.type)) {
+      counts.Message++;
+    }
+
+    if (['Team', 'User'].includes(item.type)) {
+      counts.Team++;
+    }
+  });
+
+  const filters: SearchFilter[] = [{ id: 'all', name: `All (${counts.all})`, count: counts.all }];
+  const addFilter = (id: string, name: string) => {
+    if (counts[id] > 0) {
+      filters.push({ id, name: `${name} (${counts[id]})`, count: counts[id] });
+    }
+  };
+
+  addFilter('Domain', 'Domains');
+  addFilter('Service', 'Services');
+  addFilter('Message', 'Messages');
+  addFilter('Container', 'Data Stores');
+  addFilter('Entity', 'Entities');
+  addFilter('Channel', 'Channels');
+  addFilter('Flow', 'Flows');
+  addFilter('Data Product', 'Data Products');
+  addFilter('Custom Doc', 'Custom Docs');
+  addFilter('Resource Doc', 'Resource Docs');
+  addFilter('Changelog', 'Changelogs');
+  addFilter('Design', 'Designs');
+  addFilter('Team', 'Teams & Users');
+
+  return filters;
+};
+
+export const mapPagefindResultsToSearchItems = async ({
+  results,
+  query,
+  limit,
+}: {
+  results: PagefindResult[];
+  query: string;
+  limit: number;
+}): Promise<SearchItem[]> => {
+  const mappedResults = await Promise.all(
+    results.slice(0, limit).map(async (result, resultIndex) => {
+      const data = await result.data();
+      const meta = data.meta || {};
+      const type = meta.type || 'Page';
+      const title = meta.title || data.url || 'Untitled';
+      const summary = meta.summary || stripHtml(data.excerpt || '');
+      const url = normalizeResultUrl(data.url);
+
+      if (
+        !hasMeaningfulIndexedMatch({
+          query,
+          title,
+          content: data.content,
+          excerpt: data.excerpt || '',
+        })
+      ) {
+        return null;
+      }
+
+      return {
+        item: {
+          id: result.id,
+          name: title,
+          url,
+          type,
+          rawNode: {
+            title,
+            badge: type,
+            summary,
+            matchedExcerpt: data.excerpt || summary,
+          },
+        } satisfies SearchItem,
+        resultIndex,
+        rank: getIndexedResultRank({
+          query,
+          title,
+          id: meta.id,
+          url,
+          content: data.content,
+        }),
+        score: typeof result.score === 'number' ? result.score : 0,
+      };
+    })
+  );
+
+  return mappedResults
+    .filter((result): result is NonNullable<typeof result> => result !== null)
+    .sort((a, b) => b.rank - a.rank || b.score - a.score || a.resultIndex - b.resultIndex)
+    .map((result) => result.item);
+};

package/eventcatalog/src/env.d.ts

@@ -3,6 +3,7 @@
 
 declare const __EC_TRAILING_SLASH__: boolean;
 declare const __EC_BASE__: string;
+declare const __EC_SEARCH_TYPE__: 'resource' | 'indexed';
 
 interface EventCatalogConfig {
   mermaid?: {

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
-  "version": "3.35.1",
+  "version": "3.36.1",
   "publishConfig": {
     "access": "public"
   },
@@ -80,6 +80,7 @@
     "mdast-util-find-and-replace": "^3.0.2",
     "mermaid": "^11.12.3",
     "nanostores": "^1.1.0",
+    "pagefind": "^1.5.2",
     "pako": "^2.1.0",
     "picocolors": "^1.1.1",
     "react": "^18.3.1",
@@ -105,8 +106,8 @@
     "update-notifier": "^7.3.1",
     "uuid": "^10.0.0",
     "zod": "^4.3.6",
-    "@eventcatalog/linter": "1.0.22",
     "@eventcatalog/sdk": "2.21.0",
+    "@eventcatalog/linter": "1.0.22",
     "@eventcatalog/visualiser": "^3.20.0"
   },
   "devDependencies": {