docs(docs-infra): Add query as an url query param to the api reference (angular#57062)

add an url query param to perform a search on api references directly via the url PR Close angular#57062

Author: mvdluit

adev/src/app/app-scroller.ts

@@ -41,6 +41,13 @@ export class AppScroller {
  this._lastScrollEvent = e;
  }),
  filter(() => !this.disableScrolling),
+ filter(() => {
+ const info = this.router.lastSuccessfulNavigation?.extras.info as Record<
+ 'disableScrolling',
+ boolean
+ >;
+ return !info?.['disableScrolling'];
+ }),
  switchMap((e) => {
  return firstValueFrom(
  this.appRef.isStable.pipe(

adev/src/app/features/references/api-items-section/api-items-section.component.html

@@ -3,7 +3,7 @@ <h3 [attr.id]="group.id">
  @if (group.isFeatured) {
  <docs-icon aria-hidden>star</docs-icon>
  }
- <a routerLink="/api" [fragment]="group.id" class="adev-api-anchor" tabindex="-1">{{ group.title }}</a>
+ <a routerLink="/api" [fragment]="group.id" queryParamsHandling="preserve" class="adev-api-anchor" tabindex="-1">{{ group.title }}</a>
  </h3>
 </header>
 

adev/src/app/features/references/api-reference-list/api-reference-list.component.spec.ts

@@ -14,6 +14,7 @@ import {signal} from '@angular/core';
 import {ApiItemType} from '../interfaces/api-item-type';
 import {RouterTestingHarness} from '@angular/router/testing';
 import {provideRouter} from '@angular/router';
+import {Location} from '@angular/common';
 
 describe('ApiReferenceList', () => {
  let component: ApiReferenceList;
@@ -117,4 +118,30 @@ describe('ApiReferenceList', () => {
  harness.navigateByUrl(`/api`);
  expect(component.type()).toBe(ALL_STATUSES_KEY);
  });
+
+ it('should set the value of the queryParam equal to the query value', async () => {
+ const location = TestBed.inject(Location);
+ component.query.set('item1');
+ await fixture.whenStable();
+ expect(location.path()).toBe(`?query=item1&type=All`);
+ });
+
+ it('should keep the values of existing queryParams and set new queryParam equal to the type', async () => {
+ const location = TestBed.inject(Location);
+
+ component.query.set('item1');
+ await fixture.whenStable();
+ expect(location.path()).toBe(`?query=item1&type=All`);
+
+ component.filterByItemType(ApiItemType.BLOCK);
+ await fixture.whenStable();
+ expect(location.path()).toBe(`?query=item1&type=${ApiItemType.BLOCK}`);
+ });
+
+ it('should display all items when query and type are undefined', async () => {
+ component.query.set(undefined);
+ component.type.set(undefined);
+ await fixture.whenStable();
+ expect(component.filteredGroups()![0].items).toEqual([fakeItem1, fakeItem2]);
+ });
 });

adev/src/app/features/references/api-reference-list/api-reference-list.component.ts

@@ -23,6 +23,7 @@ import ApiItemsSection from '../api-items-section/api-items-section.component';
 import {FormsModule} from '@angular/forms';
 import {SlideToggle, TextField} from '@angular/docs';
 import {NgFor, NgIf} from '@angular/common';
+import {Params, Router} from '@angular/router';
 import {ApiItemType} from '../interfaces/api-item-type';
 import {ApiReferenceManager} from './api-reference-manager.service';
 import ApiItemLabel from '../api-item-label/api-item-label.component';
@@ -50,6 +51,7 @@ export const ALL_STATUSES_KEY = 'All';
 })
 export default class ApiReferenceList {
  private readonly apiReferenceManager = inject(ApiReferenceManager);
+ private readonly router = inject(Router);
  filterInput = viewChild.required(TextField, {read: ElementRef});
  private readonly injector = inject(EnvironmentInjector);
 
@@ -71,9 +73,28 @@ export default class ApiReferenceList {
  {injector: this.injector},
  );
  });
+
+ effect(
+ () => {
+ const params: Params = {
+ 'query': this.query() ? this.query() : null,
+ 'type': this.type() ? this.type() : null,
+ };
+
+ this.router.navigate([], {
+ queryParams: params,
+ replaceUrl: true,
+ preserveFragment: true,
+ info: {
+ disableScrolling: true,
+ },
+ });
+ },
+ {allowSignalWrites: true},
+ );
  }
 
- query = signal('');
+ query = model<string | undefined>('');
  includeDeprecated = signal(false);
 
  type = model<string | undefined>(ALL_STATUSES_KEY);
@@ -87,8 +108,10 @@ export default class ApiReferenceList {
  id: group.id,
  items: group.items.filter((apiItem) => {
  return (
- (this.query()
- ? apiItem.title.toLocaleLowerCase().includes(this.query().toLocaleLowerCase())
+ (this.query() !== undefined
+ ? apiItem.title
+ .toLocaleLowerCase()
+ .includes((this.query() as string).toLocaleLowerCase())
  : true) &&
  (this.includeDeprecated() ? true : apiItem.isDeprecated === this.includeDeprecated()) &&
  (this.type() === undefined ||