feat(oc-docs): typo-tolerant endpoint search via Fuse.js (#131)

* feat(oc-docs): typo-tolerant endpoint search via Fuse.js

Replace the hand-rolled subsequence matcher with a Fuse.js (Bitap) index so
search tolerates typos (bikling matches billing) and matches whole words
contiguously instead of stitching characters across tokens (the "b" of baseUrl
no longer lit up when searching "billing").

- Narrow search fields to name, URL and folder chain (drop params and
  description); Fuse key weights name > url > folder.
- Tune threshold to 0.3 to keep real typos while dropping shared-prefix false
  positives (cursor no longer matches currencies).
- Bold the exact matched ranges Fuse reports in each field; the result name is
  no longer bold by default.
- Remove the now-unused fuzzyMatch utility and add fuse.js@^7.5.0.

* feat(oc-docs): tolerate adjacent-letter transpositions in search

Search also runs adjacent-swap variants of the query so a swap typo on a short
word (hotles matches hotels) resolves near-exact, without loosening the Fuse
threshold. Records introduced only by a variant are gated to near-exact scores,
so the expansion adds recall without reopening prefix-bleed false positives.

* test(oc-docs): update search empty-state copy assertion to 'folder'

* chore(oc-docs): add fuse.js to the lockfile

* refactor(oc-docs): address search review (e2e, types, 1-char UX, guards)

- Add e2e covering the new behaviours: a swap-typo correcting to its request,
  folder-chain text search (not just the filter dropdown), and a single-char
  query holding the initial prompt.
- Treat a query shorter than Fuse's minMatchCharLength as "not typing yet" so
  the first keystroke keeps the initial prompt instead of a no-results flash.
- Skip transposition expansion for long queries (likely pasted, not mistyped).
- Type collectMatches ranges as [number, number] tuples, not number[][].
- Drop em-dashes from the search comments and test titles.

* style(oc-docs): drop redundant comment in search result styles

* test(oc-docs): assert search highlight by bold tag, not class name

Author: sundram-bruno

package-lock.json

@@ -63,7 +63,7 @@ test.describe('Search palette', () => {
     await search.field.click();
 
     await expect(search.panel).toContainText('Search the collection');
-    await expect(search.panel).toContainText('Find any request by name, endpoint, or description.');
+    await expect(search.panel).toContainText('Find any request by name, endpoint, or folder.');
   });
 
   test('typing fuzzy-matches over request names', async ({ page, search }) => {
@@ -76,6 +76,36 @@ test.describe('Search palette', () => {
     await expect(search.panel).toContainText('Login');
   });
 
+  test('corrects a typo (adjacent letter swap) to the intended request', async ({ page, search }) => {
+    await page.setViewportSize(DESKTOP);
+    await page.goto(FIXTURE);
+    await search.field.click();
+    await search.field.fill('lgoin'); // "login" with the o/g swapped
+
+    await expect(search.results.first()).toBeVisible();
+    await expect(search.panel).toContainText('Login');
+  });
+
+  test('matches on the folder chain typed as text (not only the filter dropdown)', async ({ page, search }) => {
+    await page.setViewportSize(DESKTOP);
+    await page.goto(FIXTURE);
+    await search.field.click();
+    await search.field.fill('authentication'); // the folder Login lives under
+
+    await expect(search.results.first()).toBeVisible();
+    await expect(search.panel).toContainText('Login');
+  });
+
+  test('a single character keeps the initial prompt (below the match threshold)', async ({ page, search }) => {
+    await page.setViewportSize(DESKTOP);
+    await page.goto(FIXTURE);
+    await search.field.click();
+    await search.field.fill('l');
+
+    await expect(search.panel).toContainText('Search the collection');
+    await expect(search.resultsList).toHaveCount(0);
+  });
+
   test('selecting a result navigates and closes the panel', async ({ page, search }) => {
     await page.setViewportSize(DESKTOP);
     await page.goto(FIXTURE);

packages/oc-docs/e2e/tests/search/search.spec.ts

@@ -72,6 +72,7 @@
     "@types/prismjs": "^1.26.5",
     "ajv": "^8.12.0",
     "codemirror": "^6.0.2",
+    "fuse.js": "^7.5.0",
     "js-yaml": "^4.1.0",
     "jshint": "^2.13.6",
     "markdown-it": "^14.1.0",

packages/oc-docs/package.json

@@ -5,7 +5,9 @@ import {
   buildSearchRecords,
   collectTopLevelFolders,
   collectMethods,
-  searchRecords,
+  createSearchIndex,
+  searchHits,
+  type SearchHit,
   type SearchRecord,
 } from '../searchIndex';
 import { SearchIcon, CloseIcon } from '../../../assets/icons';
@@ -16,6 +18,11 @@ import { StyledWrapper } from './StyledWrapper';
 
 const RESULTS_ID = 'search-listbox';
 
+// A single character can't clear Fuse's `minMatchCharLength`, so treat a query
+// shorter than this as "not typing yet": keep the initial prompt rather than
+// flashing "no matching requests" after the first keystroke.
+const MIN_QUERY_LENGTH = 2;
+
 interface SearchBarProps {
   /** Open state, controlled by the shell so it is shared with the Topbar's
    *  below-desktop search row (one source of truth: icon, row and panel agree). */
@@ -33,9 +40,9 @@ interface SearchBarProps {
 }
 
 /**
- * Header-anchored endpoint search. Fuzzy text search over name/url/params/
- * description plus palette-local method + folder filters. Results render in the
- * palette itself and selecting one navigates via the slug route.
+ * Header-anchored endpoint search. Typo-tolerant (Fuse/Bitap) search over name,
+ * URL and folder chain plus palette-local method + folder filters. Results
+ * render in the palette itself and selecting one navigates via the slug route.
  *
  * Expands in place (a combobox whose listbox drops directly below the field)
  * rather than opening a centered modal. Open state is controlled so the Topbar
@@ -46,6 +53,7 @@ export const SearchBar: React.FC<SearchBarProps> = ({ open, onOpenChange, focusN
   const model = useNavModel();
 
   const records = useMemo(() => buildSearchRecords(model.ordered), [model]);
+  const fuse = useMemo(() => createSearchIndex(records), [records]);
   const folders = useMemo(() => collectTopLevelFolders(model.ordered), [model]);
   // One chip per method present in the collection (canonical order).
   const methodOptions = useMemo(() => collectMethods(model.ordered), [model]);
@@ -63,17 +71,21 @@ export const SearchBar: React.FC<SearchBarProps> = ({ open, onOpenChange, focusN
 
   const optionId = (i: number) => `${RESULTS_ID}-opt-${i}`;
 
-  const hasQuery = query.trim().length > 0;
+  const hasQuery = query.trim().length >= MIN_QUERY_LENGTH;
   const hasFilter = methods.size > 0 || folder !== null;
 
-  const results = useMemo(() => {
-    const base = hasQuery ? searchRecords(query, records) : hasFilter ? records : [];
+  const results = useMemo<SearchHit[]>(() => {
+    const base: SearchHit[] = hasQuery
+      ? searchHits(fuse, query)
+      : hasFilter
+        ? records.map((record) => ({ record, matches: {} }))
+        : [];
     return base.filter(
-      (r) =>
+      ({ record: r }) =>
         (methods.size === 0 || (r.method ? methods.has(r.method.toUpperCase()) : false)) &&
         (folder === null || r.ancestorSlugs.includes(folder)),
     );
-  }, [query, methods, folder, records, hasQuery, hasFilter]);
+  }, [query, methods, folder, records, fuse, hasQuery, hasFilter]);
 
   useEffect(() => setActiveIdx(-1), [results]);
 
@@ -165,10 +177,10 @@ export const SearchBar: React.FC<SearchBarProps> = ({ open, onOpenChange, focusN
     }
     if (e.key === 'Enter') {
       // Enter selects the highlighted row, or the first result if none navigated.
-      const rec = activeIdx >= 0 ? results[activeIdx] : results[0];
-      if (rec) {
+      const hit = activeIdx >= 0 ? results[activeIdx] : results[0];
+      if (hit) {
         e.preventDefault();
-        handleSelect(rec);
+        handleSelect(hit.record);
       }
     }
   };
@@ -230,7 +242,7 @@ export const SearchBar: React.FC<SearchBarProps> = ({ open, onOpenChange, focusN
                     <SearchIcon />
                   </span>
                   <p className="search-empty-title">Search the collection</p>
-                  <p className="search-empty-text">Find any request by name, endpoint, or description.</p>
+                  <p className="search-empty-text">Find any request by name, endpoint, or folder.</p>
                 </div>
               ) : results.length === 0 ? (
                 <div className="search-empty">
@@ -257,9 +269,9 @@ export const SearchBar: React.FC<SearchBarProps> = ({ open, onOpenChange, focusN
                   aria-label="Search results"
                   data-testid="search-results"
                 >
-                  {results.map((rec, i) => (
+                  {results.map((hit, i) => (
                     <li
-                      key={rec.id}
+                      key={hit.record.id}
                       id={optionId(i)}
                       role="option"
                       aria-selected={i === activeIdx}
@@ -269,7 +281,12 @@ export const SearchBar: React.FC<SearchBarProps> = ({ open, onOpenChange, focusN
                         if (e.movementX !== 0 || e.movementY !== 0) setActiveIdx(i);
                       }}
                     >
-                      <SearchResultItem record={rec} active={i === activeIdx} onSelect={handleSelect} />
+                      <SearchResultItem
+                        record={hit.record}
+                        matches={hit.matches}
+                        active={i === activeIdx}
+                        onSelect={handleSelect}
+                      />
                     </li>
                   ))}
                 </ul>

packages/oc-docs/src/components/Search/SearchBar/SearchBar.tsx

@@ -4,6 +4,11 @@ import { describe, it, expect } from 'vitest';
 import { SearchResultItem } from './SearchResultItem';
 import type { SearchRecord } from '../searchIndex';
 
+// Match "<text>" wrapped in a bold element, regardless of its attributes, so the
+// assertion keys off the tag (the highlight contract) and not a styling class.
+const boldElement = /<b(?:\s[^>]*)?>([^<]*)<\/b>/g;
+const boldedText = (html: string): string[] => [...html.matchAll(boldElement)].map((m) => m[1]);
+
 const record: SearchRecord = {
   id: 'u1',
   slug: 'hotels/get-all',
@@ -12,8 +17,6 @@ const record: SearchRecord = {
   breadcrumb: 'Hotels / Browse & search',
   ancestorSlugs: ['hotels'],
   url: '{{baseUrl}}/api/v1/hotels',
-  params: '',
-  description: '',
 };
 
 describe('SearchResultItem', () => {
@@ -29,4 +32,17 @@ describe('SearchResultItem', () => {
     const html = renderToStaticMarkup(<SearchResultItem record={{ ...record, url: '' }} onSelect={() => {}} />);
     expect(html).not.toContain('class="search-result-url"');
   });
+
+  it('wraps the matched ranges of a field in a bold element', () => {
+    // "Hotels" sits at indices 8-13 of "Get All Hotels".
+    const html = renderToStaticMarkup(
+      <SearchResultItem record={record} matches={{ name: [[8, 13]] }} onSelect={() => {}} />,
+    );
+    expect(boldedText(html)).toContain('Hotels');
+  });
+
+  it('renders plain text (no bold element) when a field has no matches', () => {
+    const html = renderToStaticMarkup(<SearchResultItem record={record} matches={{}} onSelect={() => {}} />);
+    expect(boldedText(html)).toHaveLength(0);
+  });
 });

packages/oc-docs/src/components/Search/SearchResultItem/SearchResultItem.spec.tsx

@@ -1,18 +1,44 @@
 import React from 'react';
 import { getMethodColorVar } from '../../../theme/methodColors';
 import { getShortMethod } from '../../../utils/request';
-import type { SearchRecord } from '../searchIndex';
+import type { SearchRecord, FieldMatches } from '../searchIndex';
 import { StyledWrapper } from './StyledWrapper';
 
 interface SearchResultItemProps {
   record: SearchRecord;
+  /** Matched character ranges per field, so each field bolds what matched. */
+  matches?: FieldMatches;
   /** Whether this row is the active (keyboard-highlighted) result. */
   active?: boolean;
   /** Navigate to this result (caller also closes the palette). */
   onSelect: (record: SearchRecord) => void;
   testId?: string;
 }
 
+/**
+ * Bold the `ranges` (inclusive [start, end] pairs from Fuse) inside `text`, so
+ * each field advertises the exact substring that matched. The mark keeps the
+ * field's own colour (weight is the only highlight signal). No ranges leaves
+ * the text plain.
+ */
+const highlightRanges = (text: string, ranges?: Array<[number, number]>): React.ReactNode => {
+  if (!ranges || ranges.length === 0) return text;
+  const sorted = [...ranges].sort((a, b) => a[0] - b[0]);
+  const nodes: React.ReactNode[] = [];
+  let cursor = 0;
+  sorted.forEach(([start, end], i) => {
+    if (start > cursor) nodes.push(text.slice(cursor, start));
+    nodes.push(
+      <b className="search-hl" key={i}>
+        {text.slice(start, end + 1)}
+      </b>
+    );
+    cursor = end + 1;
+  });
+  if (cursor < text.length) nodes.push(text.slice(cursor));
+  return nodes;
+};
+
 /**
  * One result row in the search palette. The method is rendered as a plain
  * colour-coded mono label (not the filled sidebar badge) while still sourcing
@@ -21,6 +47,7 @@ interface SearchResultItemProps {
  */
 export const SearchResultItem: React.FC<SearchResultItemProps> = ({
   record,
+  matches,
   active = false,
   onSelect,
   testId = 'search-result',
@@ -37,10 +64,12 @@ export const SearchResultItem: React.FC<SearchResultItemProps> = ({
     )}
     <span className="search-result-body">
       <span className="search-result-title-row">
-        <span className="search-result-name">{record.name}</span>
-        {record.breadcrumb && <span className="search-result-breadcrumb">{record.breadcrumb}</span>}
+        <span className="search-result-name">{highlightRanges(record.name, matches?.name)}</span>
+        {record.breadcrumb && (
+          <span className="search-result-breadcrumb">{highlightRanges(record.breadcrumb, matches?.breadcrumb)}</span>
+        )}
       </span>
-      {record.url && <span className="search-result-url">{record.url}</span>}
+      {record.url && <span className="search-result-url">{highlightRanges(record.url, matches?.url)}</span>}
     </span>
   </StyledWrapper>
 );

packages/oc-docs/src/components/Search/SearchResultItem/SearchResultItem.tsx

@@ -51,14 +51,18 @@ export const StyledWrapper = styled.button`
 
   .search-result-name {
     font-size: 13px;
-    font-weight: 600;
+    font-weight: 400;
     line-height: 1.3;
     color: var(--oc-text);
     white-space: nowrap;
     overflow: hidden;
     text-overflow: ellipsis;
   }
 
+  .search-hl {
+    font-weight: 700;
+  }
+
   .search-result-breadcrumb {
     font-size: 11px;
     line-height: 1.3;