docs(docs-infra): Search results as HTML (angular#60394)

JeanMeche · thePunderWoman · commit 440b1ada9bc7 · 2025-04-02T11:32:58.000Z
fixes angular#60384 PR Close angular#60394
diff --git a/adev/shared-docs/components/search-dialog/search-dialog.component.html b/adev/shared-docs/components/search-dialog/search-dialog.component.html
@@ -3,15 +3,14 @@
     <docs-text-field
       [autofocus]="true"
       [hideIcon]="true"
-      [ngModel]="searchQuery()"
-      (ngModelChange)="updateSearchQuery($event)"
+      [(ngModel)]="searchQuery"
       class="docs-search-input"
       placeholder="Search docs"
     />
 
-    @if (searchResults() && searchResults()!.length > 0) {
+    @if (searchResults.hasValue() && searchResults.value().length > 0) {
       <ul class="docs-search-results docs-mini-scroll-track">
-        @for (result of searchResults(); track result.objectID) {
+        @for (result of searchResults.value(); track result.id) {
           <li docsSearchItem [item]="result">
             <a
               [routerLink]="'/' + result.url | relativeLink: 'pathname'"
@@ -22,45 +21,35 @@
                   <!-- Icon -->
                   <span class="docs-search-result-icon" aria-hidden="true">
                     <i role="presentation" class="material-symbols-outlined docs-icon-small">
-                      {{ result.hierarchy.lvl0 === 'Tutorials' ? 'code' : 'description'}}
+                      {{ result.type === 'code' ? 'code' : 'description'}}
                     </i>
                   </span>
                   <!-- Results type -->
-                  <span class="docs-search-results__type">
-                    @let snippet = result._snippetResult.hierarchy?.lvl1?.value ?? '';
-                    <ng-container
-                      [ngTemplateOutlet]="highlightSnippet"
-                      [ngTemplateOutletContext]="{snippet}"
-                    />
-                  </span>
+                  <span class="docs-search-results__type" [innerHtml]="result.labelHtml"></span>
                 </div>
 
-                @let content = result._snippetResult.content;
-                @let hierarchy = result._snippetResult.hierarchy;
-                @if (content || hierarchy?.lvl2 || hierarchy?.lvl3 || hierarchy?.lvl4) {
-                  <span class="docs-search-results__type docs-search-results__lvl2">
-                    @let snippet = getBestSnippetForMatch(result);
-                    <ng-container
-                      [ngTemplateOutlet]="highlightSnippet"
-                      [ngTemplateOutletContext]="{snippet}"
-                    />
+                @if (result.subLabelHtml) {
+                  <span
+                    class="docs-search-results__type docs-search-results__lvl2"
+                    [innerHtml]="result.subLabelHtml"
+                  >
                   </span>
                 }
               </div>
 
               <!-- Page title -->
-              <span class="docs-result-page-title">{{ result.hierarchy?.lvl0 }}</span>
+              <span class="docs-result-page-title">{{ result.category }}</span>
             </a>
           </li>
         }
       </ul>
     } @else {
       <div class="docs-search-results docs-mini-scroll-track">
-        @if (searchResults() === undefined) {
+        @if (!searchResults.hasValue()) {
           <div class="docs-search-results__start-typing">
             <span>Start typing to see results</span>
           </div>
-        } @else if (searchResults()?.length === 0) {
+        } @else if (searchResults.value().length === 0) {
           <div class="docs-search-results__no-results">
             <span>No results found</span>
           </div>
@@ -70,21 +59,13 @@
 
     <div class="docs-algolia">
       <span>Search by</span>
-      <a target="_blank" rel="noopener"
-         href="https://www.algolia.com/developers/?utm_source=angular.dev&utm_medium=referral&utm_content=powered_by&utm_campaign=docsearch">
+      <a
+        target="_blank"
+        rel="noopener"
+        href="https://www.algolia.com/developers/?utm_source=angular.dev&utm_medium=referral&utm_content=powered_by&utm_campaign=docsearch"
+      >
         <docs-algolia-icon />
       </a>
     </div>
   </div>
 </dialog>
-
-<ng-template #highlightSnippet let-snippet="snippet">
-  @let parts = splitMarkedText(snippet);
-  @for (part of parts; track $index) {
-    @if (part.highlight) {
-      <mark>{{part.text}}</mark>
-    } @else {
-      <span>{{part.text}}</span>
-    }
-  }
-</ng-template>
diff --git a/adev/shared-docs/components/search-dialog/search-dialog.component.scss b/adev/shared-docs/components/search-dialog/search-dialog.component.scss
@@ -51,12 +51,17 @@ dialog {
       padding-inline-end: 1rem;
       padding-block: 0.25rem;
 
-      mark {
-        background: #e62600;
-        background: var(--red-to-orange-horizontal-gradient);
-        background-clip: text;
-        -webkit-background-clip: text;
-        color: transparent;
+      /** 
+      * This rule needs ng-deep to be applied to elements that are created via a [innerHTML] binding
+      */ 
+      ::ng-deep {
+        mark {
+          background: #e62600;
+          background: var(--red-to-orange-horizontal-gradient);
+          background-clip: text;
+          -webkit-background-clip: text;
+          color: transparent;
+        }
       }
 
       a {
diff --git a/adev/shared-docs/components/search-dialog/search-dialog.component.spec.ts b/adev/shared-docs/components/search-dialog/search-dialog.component.spec.ts
@@ -9,54 +9,59 @@
 import {ComponentFixture, TestBed} from '@angular/core/testing';
 
 import {SearchDialog} from './search-dialog.component';
-import {WINDOW} from '../../providers';
-import {Search} from '../../services';
+import {ENVIRONMENT, WINDOW} from '../../providers';
+import {ALGOLIA_CLIENT, Search} from '../../services';
 import {FakeEventTarget} from '../../testing/index';
 import {By} from '@angular/platform-browser';
 import {AlgoliaIcon} from '../algolia-icon/algolia-icon.component';
 import {RouterTestingModule} from '@angular/router/testing';
 import {Router} from '@angular/router';
-import {provideExperimentalZonelessChangeDetection} from '@angular/core';
+import {
+  ApplicationRef,
+  provideExperimentalZonelessChangeDetection,
+  ResourceStatus,
+} from '@angular/core';
 import {SearchResult} from '../../interfaces';
 
 describe('SearchDialog', () => {
   let fixture: ComponentFixture<SearchDialog>;
 
-  const fakeSearch = {
-    searchQuery: jasmine.createSpy(),
-    searchResults: jasmine.createSpy(),
-  };
+  const searchResults = jasmine.createSpy();
+
   const fakeWindow = new FakeEventTarget();
 
+  let search: Search;
+
   beforeEach(async () => {
-    fakeSearch.searchResults.and.returnValue([]);
-    fakeSearch.searchQuery.and.returnValue('');
+    searchResults.and.returnValue([]);
 
-    await TestBed.configureTestingModule({
+    TestBed.configureTestingModule({
       imports: [SearchDialog, RouterTestingModule],
       providers: [
         provideExperimentalZonelessChangeDetection(),
-        {
-          provide: Search,
-          useValue: fakeSearch,
-        },
-        {
-          provide: WINDOW,
-          useValue: fakeWindow,
-        },
+        {provide: ENVIRONMENT, useValue: {algolia: {index: 'fakeIndex'}}},
+        {provide: ALGOLIA_CLIENT, useValue: {search: searchResults}},
+        {provide: WINDOW, useValue: fakeWindow},
       ],
-    }).compileComponents();
+    });
 
     fixture = TestBed.createComponent(SearchDialog);
     fixture.detectChanges();
+    search = TestBed.inject(Search);
   });
 
-  it('should navigate to active item when user pressed Enter', () => {
+  it('should navigate to active item when user pressed Enter', async () => {
     const router = TestBed.inject(Router);
     const navigateByUrlSpy = spyOn(router, 'navigateByUrl');
 
-    fakeSearch.searchResults.and.returnValue(fakeSearchResults);
-    fixture.detectChanges();
+    search.searchQuery.set('fakeQuery');
+    searchResults.and.returnValue(Promise.resolve({results: [{hits: fakeSearchResults}]}));
+
+    // Fire the request
+    TestBed.inject(ApplicationRef).tick();
+
+    // Wait for the resource to resolve
+    await TestBed.inject(ApplicationRef).whenStable();
 
     fakeWindow.dispatchEvent(
       new KeyboardEvent('keydown', {
@@ -78,9 +83,15 @@ describe('SearchDialog', () => {
     expect(algoliaIcon).toBeTruthy();
   });
 
-  it('should display `No results found` message when there are no results for provided query', () => {
-    fakeSearch.searchResults.and.returnValue([]);
-    fixture.detectChanges();
+  it('should display `No results found` message when there are no results for provided query', async () => {
+    search.searchQuery.set('fakeQuery');
+    searchResults.and.returnValue(Promise.resolve({results: [{hits: []}]}));
+
+    // Fire the request
+    TestBed.inject(ApplicationRef).tick();
+
+    // Wait for the resource to resolve
+    await TestBed.inject(ApplicationRef).whenStable();
 
     const noResultsContainer = fixture.debugElement.query(
       By.css('.docs-search-results__no-results'),
@@ -90,7 +101,7 @@ describe('SearchDialog', () => {
   });
 
   it('should display `Start typing to see results` message when there are no provided query', () => {
-    fakeSearch.searchResults.and.returnValue(undefined);
+    searchResults.and.returnValue(undefined);
     fixture.detectChanges();
 
     const startTypingContainer = fixture.debugElement.query(
@@ -100,9 +111,15 @@ describe('SearchDialog', () => {
     expect(startTypingContainer).toBeTruthy();
   });
 
-  it('should display list of the search results when results exist', () => {
-    fakeSearch.searchResults.and.returnValue(fakeSearchResults);
-    fixture.detectChanges();
+  it('should display list of the search results when results exist', async () => {
+    search.searchQuery.set('fakeQuery');
+    searchResults.and.returnValue(Promise.resolve({results: [{hits: fakeSearchResults}]}));
+
+    // Fire the request
+    TestBed.inject(ApplicationRef).tick();
+
+    // Wait for the resource to resolve
+    await TestBed.inject(ApplicationRef).whenStable();
 
     const resultListContainer = fixture.debugElement.query(By.css('ul.docs-search-results'));
     const resultItems = fixture.debugElement.queryAll(By.css('ul.docs-search-results li a'));
diff --git a/adev/shared-docs/components/search-dialog/search-dialog.component.ts b/adev/shared-docs/components/search-dialog/search-dialog.component.ts
@@ -12,15 +12,13 @@ import {
   ElementRef,
   Injector,
   OnDestroy,
-  Signal,
   afterNextRender,
   effect,
   inject,
   output,
   viewChild,
   viewChildren,
 } from '@angular/core';
-import {NgTemplateOutlet} from '@angular/common';
 
 import {WINDOW} from '../../providers/index';
 import {ClickOutside} from '../../directives/index';
@@ -32,10 +30,9 @@ import {ActiveDescendantKeyManager} from '@angular/cdk/a11y';
 import {SearchItem} from '../../directives/search-item/search-item.directive';
 import {takeUntilDestroyed} from '@angular/core/rxjs-interop';
 import {Router, RouterLink} from '@angular/router';
-import {filter, fromEvent} from 'rxjs';
+import {fromEvent} from 'rxjs';
 import {AlgoliaIcon} from '../algolia-icon/algolia-icon.component';
 import {RelativeLink} from '../../pipes/relative-link.pipe';
-import {SearchResult, SnippetResult} from '../../interfaces';
 
 @Component({
   selector: 'docs-search-dialog',
@@ -48,7 +45,6 @@ import {SearchResult, SnippetResult} from '../../interfaces';
     AlgoliaIcon,
     RelativeLink,
     RouterLink,
-    NgTemplateOutlet,
   ],
   templateUrl: './search-dialog.component.html',
   styleUrls: ['./search-dialog.component.scss'],
@@ -106,46 +102,6 @@ export class SearchDialog implements OnDestroy {
       });
   }
 
-  splitMarkedText(snippet: string): Array<{highlight: boolean; text: string}> {
-    const parts: Array<{highlight: boolean; text: string}> = [];
-    while (snippet.indexOf('<ɵ>') !== -1) {
-      const beforeMatch = snippet.substring(0, snippet.indexOf('<ɵ>'));
-      const match = snippet.substring(snippet.indexOf('<ɵ>') + 3, snippet.indexOf('</ɵ>'));
-      parts.push({highlight: false, text: beforeMatch});
-      parts.push({highlight: true, text: match});
-      snippet = snippet.substring(snippet.indexOf('</ɵ>') + 4);
-    }
-    parts.push({highlight: false, text: snippet});
-    return parts;
-  }
-
-  getBestSnippetForMatch(result: SearchResult): string {
-    // if there is content, return it
-    if (result._snippetResult.content !== undefined) {
-      return result._snippetResult.content.value;
-    }
-
-    const hierarchy = result._snippetResult.hierarchy;
-    if (hierarchy === undefined) {
-      return '';
-    }
-    function matched(snippet: SnippetResult | undefined) {
-      return snippet?.matchLevel !== undefined && snippet.matchLevel !== 'none';
-    }
-    // return the most specific subheader match
-    if (matched(hierarchy.lvl4)) {
-      return hierarchy.lvl4!.value;
-    }
-    if (matched(hierarchy.lvl3)) {
-      return hierarchy.lvl3!.value;
-    }
-    if (matched(hierarchy.lvl2)) {
-      return hierarchy.lvl2!.value;
-    }
-    // if no subheader matched the query, fall back to just returning the most specific one
-    return hierarchy.lvl3?.value ?? hierarchy.lvl2?.value ?? '';
-  }
-
   ngOnDestroy(): void {
     this.keyManager.destroy();
   }
@@ -155,10 +111,6 @@ export class SearchDialog implements OnDestroy {
     this.onClose.emit();
   }
 
-  updateSearchQuery(query: string) {
-    this.search.updateSearchQuery(query);
-  }
-
   private navigateToTheActiveItem(): void {
     const activeItemLink: string | undefined = this.keyManager.activeItem?.item?.url;
 
diff --git a/adev/shared-docs/directives/search-item/search-item.directive.ts b/adev/shared-docs/directives/search-item/search-item.directive.ts
@@ -8,7 +8,7 @@
 
 import {Directive, ElementRef, Input, inject, signal} from '@angular/core';
 import {Highlightable} from '@angular/cdk/a11y';
-import {SearchResult} from '../../interfaces/search-results';
+import {SearchResultItem} from '../../interfaces';
 
 @Directive({
   selector: '[docsSearchItem]',
@@ -17,7 +17,7 @@ import {SearchResult} from '../../interfaces/search-results';
   },
 })
 export class SearchItem implements Highlightable {
-  @Input() item?: SearchResult;
+  @Input() item?: SearchResultItem;
   @Input() disabled = false;
 
   private readonly elementRef = inject(ElementRef<HTMLLIElement>);
@@ -36,14 +36,6 @@ export class SearchItem implements Highlightable {
     this._isActive.set(false);
   }
 
-  getLabel(): string {
-    if (!this.item?.hierarchy) {
-      return '';
-    }
-    const {hierarchy} = this.item;
-    return `${hierarchy.lvl0}${hierarchy.lvl1}${hierarchy.lvl2}`;
-  }
-
   scrollIntoView(): void {
     this.elementRef?.nativeElement.scrollIntoView({block: 'nearest'});
   }
diff --git a/adev/shared-docs/interfaces/search-results.ts b/adev/shared-docs/interfaces/search-results.ts
@@ -54,3 +54,14 @@ export interface Hierarchy {
   lvl5: string | null;
   lvl6: string | null;
 }
+
+/** Parsed & Structured search results */
+export interface SearchResultItem {
+  type: 'doc' | 'code';
+  labelHtml: string | null;
+  subLabelHtml: string | null;
+  url: string;
+
+  id: string;
+  category: string | null;
+}
diff --git a/adev/shared-docs/services/search.service.ts b/adev/shared-docs/services/search.service.ts
diff --git a/adev/src/app/app.config.ts b/adev/src/app/app.config.ts
