feat(router): implement scrolling restoration service (#20030)

For documentation, see `RouterModule.scrollPositionRestoration`

Fixes #13636 #10929 #7791 #6595

PR Close #20030

packages/router/test/bootstrap.spec.ts

@@ -6,13 +6,13 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {APP_BASE_HREF} from '@angular/common';
+import {APP_BASE_HREF, Location, ViewportScroller} from '@angular/common';
 import {ApplicationRef, CUSTOM_ELEMENTS_SCHEMA, Component, NgModule, destroyPlatform} from '@angular/core';
 import {inject} from '@angular/core/testing';
 import {BrowserModule, DOCUMENT, ɵgetDOM as getDOM} from '@angular/platform-browser';
 import {platformBrowserDynamic} from '@angular/platform-browser-dynamic';
-import {NavigationEnd, Resolve, Router, RouterModule} from '@angular/router';
-
+import {NavigationEnd, NavigationStart, Resolve, Router, RouterModule} from '@angular/router';
+import {filter, first} from 'rxjs/operators';
 
 describe('bootstrap', () => {
   if (isNode) return;
@@ -86,7 +86,7 @@ describe('bootstrap', () => {
       expect(log).toEqual([
         'TestModule', 'NavigationStart', 'RoutesRecognized', 'GuardsCheckStart',
         'ChildActivationStart', 'ActivationStart', 'GuardsCheckEnd', 'ResolveStart', 'ResolveEnd',
-        'RootCmp', 'ActivationEnd', 'ChildActivationEnd', 'NavigationEnd'
+        'RootCmp', 'ActivationEnd', 'ChildActivationEnd', 'NavigationEnd', 'Scroll'
       ]);
       done();
     });
@@ -248,4 +248,78 @@ describe('bootstrap', () => {
          appRef.components[0].destroy();
        });
      });
+
+
+  it('should restore the scrolling position', async(done) => {
+    @Component({
+      selector: 'component-a',
+      template: `
+           <div style="height: 3000px;"></div>
+           <div id="marker1"></div>
+           <div style="height: 3000px;"></div>
+           <div id="marker2"></div>
+           <div style="height: 3000px;"></div>
+           <a name="marker3"></a>
+           <div style="height: 3000px;"></div>
+      `
+    })
+    class TallComponent {
+    }
+    @NgModule({
+      imports: [
+        BrowserModule,
+        RouterModule.forRoot(
+            [
+              {path: '', pathMatch: 'full', redirectTo: '/aa'},
+              {path: 'aa', component: TallComponent}, {path: 'bb', component: TallComponent},
+              {path: 'cc', component: TallComponent},
+              {path: 'fail', component: TallComponent, canActivate: ['returnFalse']}
+            ],
+            {
+              useHash: true,
+              scrollPositionRestoration: 'enabled',
+              anchorScrolling: 'enabled',
+              scrollOffset: [0, 100],
+              onSameUrlNavigation: 'reload'
+            })
+      ],
+      declarations: [TallComponent, RootCmp],
+      bootstrap: [RootCmp],
+      providers: [...testProviders, {provide: 'returnFalse', useValue: () => false}],
+      schemas: [CUSTOM_ELEMENTS_SCHEMA]
+    })
+    class TestModule {
+    }
+
+    const res = await platformBrowserDynamic([]).bootstrapModule(TestModule);
+    const router = res.injector.get(Router);
+    const location: Location = res.injector.get(Location);
+
+    await router.navigateByUrl('/aa');
+    window.scrollTo(0, 5000);
+
+    await router.navigateByUrl('/fail');
+    expect(window.scrollY).toEqual(5000);
+
+    await router.navigateByUrl('/bb');
+    window.scrollTo(0, 3000);
+
+    expect(window.scrollY).toEqual(3000);
+
+    await router.navigateByUrl('/cc');
+    expect(window.scrollY).toEqual(0);
+
+    await router.navigateByUrl('/aa#marker2');
+    expect(window.scrollY >= 5900).toBe(true);
+    expect(window.scrollY < 6000).toBe(true);  // offset
+
+    await router.navigateByUrl('/aa#marker3');
+    expect(window.scrollY >= 8900).toBe(true);
+    expect(window.scrollY < 9000).toBe(true);
+    done();
+  });
+
+  function waitForNavigationToComplete(router: Router): Promise<any> {
+    return router.events.pipe(filter((e: any) => e instanceof NavigationEnd), first()).toPromise();
+  }
 });

packages/router/test/router_scroller.spec.ts

@@ -0,0 +1,168 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {fakeAsync, tick} from '@angular/core/testing';
+import {DefaultUrlSerializer, NavigationEnd, NavigationStart, RouterEvent} from '@angular/router';
+import {Subject} from 'rxjs';
+import {filter, switchMap} from 'rxjs/operators';
+
+import {Scroll} from '../src/events';
+import {RouterScroller} from '../src/router_scroller';
+
+describe('RouterScroller', () => {
+  describe('scroll to top', () => {
+    it('should scroll to the top', () => {
+      const {events, viewportScroller} =
+          createRouterScroller({scrollPositionRestoration: 'top', anchorScrolling: 'disabled'});
+
+      events.next(new NavigationStart(1, '/a'));
+      events.next(new NavigationEnd(1, '/a', '/a'));
+      expect(viewportScroller.scrollToPosition).toHaveBeenCalledWith([0, 0]);
+
+      events.next(new NavigationStart(2, '/a'));
+      events.next(new NavigationEnd(2, '/b', '/b'));
+      expect(viewportScroller.scrollToPosition).toHaveBeenCalledWith([0, 0]);
+
+      events.next(new NavigationStart(3, '/a', 'popstate'));
+      events.next(new NavigationEnd(3, '/a', '/a'));
+      expect(viewportScroller.scrollToPosition).toHaveBeenCalledWith([0, 0]);
+    });
+  });
+
+  describe('scroll to the stored position', () => {
+    it('should scroll to the stored position on popstate', () => {
+      const {events, viewportScroller} =
+          createRouterScroller({scrollPositionRestoration: 'enabled', anchorScrolling: 'disabled'});
+
+      events.next(new NavigationStart(1, '/a'));
+      events.next(new NavigationEnd(1, '/a', '/a'));
+      setScroll(viewportScroller, 10, 100);
+      expect(viewportScroller.scrollToPosition).toHaveBeenCalledWith([0, 0]);
+
+      events.next(new NavigationStart(2, '/b'));
+      events.next(new NavigationEnd(2, '/b', '/b'));
+      setScroll(viewportScroller, 20, 200);
+      expect(viewportScroller.scrollToPosition).toHaveBeenCalledWith([0, 0]);
+
+      events.next(new NavigationStart(3, '/a', 'popstate', {navigationId: 1}));
+      events.next(new NavigationEnd(3, '/a', '/a'));
+      expect(viewportScroller.scrollToPosition).toHaveBeenCalledWith([10, 100]);
+    });
+  });
+
+  describe('anchor scrolling', () => {
+    it('should work (scrollPositionRestoration is disabled)', () => {
+      const {events, viewportScroller} =
+          createRouterScroller({scrollPositionRestoration: 'disabled', anchorScrolling: 'enabled'});
+      events.next(new NavigationStart(1, '/a#anchor'));
+      events.next(new NavigationEnd(1, '/a#anchor', '/a#anchor'));
+      expect(viewportScroller.scrollToAnchor).toHaveBeenCalledWith('anchor');
+
+      events.next(new NavigationStart(2, '/a#anchor2'));
+      events.next(new NavigationEnd(2, '/a#anchor2', '/a#anchor2'));
+      expect(viewportScroller.scrollToAnchor).toHaveBeenCalledWith('anchor2');
+      viewportScroller.scrollToAnchor.calls.reset();
+
+      // we never scroll to anchor when navigating back.
+      events.next(new NavigationStart(3, '/a#anchor', 'popstate'));
+      events.next(new NavigationEnd(3, '/a#anchor', '/a#anchor'));
+      expect(viewportScroller.scrollToAnchor).not.toHaveBeenCalled();
+      expect(viewportScroller.scrollToPosition).not.toHaveBeenCalled();
+    });
+
+    it('should work (scrollPositionRestoration is enabled)', () => {
+      const {events, viewportScroller} =
+          createRouterScroller({scrollPositionRestoration: 'enabled', anchorScrolling: 'enabled'});
+      events.next(new NavigationStart(1, '/a#anchor'));
+      events.next(new NavigationEnd(1, '/a#anchor', '/a#anchor'));
+      expect(viewportScroller.scrollToAnchor).toHaveBeenCalledWith('anchor');
+
+      events.next(new NavigationStart(2, '/a#anchor2'));
+      events.next(new NavigationEnd(2, '/a#anchor2', '/a#anchor2'));
+      expect(viewportScroller.scrollToAnchor).toHaveBeenCalledWith('anchor2');
+      viewportScroller.scrollToAnchor.calls.reset();
+
+      // we never scroll to anchor when navigating back
+      events.next(new NavigationStart(3, '/a#anchor', 'popstate', {navigationId: 1}));
+      events.next(new NavigationEnd(3, '/a#anchor', '/a#anchor'));
+      expect(viewportScroller.scrollToAnchor).not.toHaveBeenCalled();
+      expect(viewportScroller.scrollToPosition).toHaveBeenCalledWith([0, 0]);
+    });
+  });
+
+  describe('extending a scroll service', () => {
+    it('work', fakeAsync(() => {
+         const {events, viewportScroller, router} = createRouterScroller(
+             {scrollPositionRestoration: 'disabled', anchorScrolling: 'disabled'});
+
+         router.events
+             .pipe(filter(e => e instanceof Scroll && !!e.position), switchMap(p => {
+                     // can be any delay (e.g., we can wait for NgRx store to emit an event)
+                     const r = new Subject<any>();
+                     setTimeout(() => {
+                       r.next(p);
+                       r.complete();
+                     }, 1000);
+                     return r;
+                   }))
+             .subscribe((e: Scroll) => { viewportScroller.scrollToPosition(e.position); });
+
+         events.next(new NavigationStart(1, '/a'));
+         events.next(new NavigationEnd(1, '/a', '/a'));
+         setScroll(viewportScroller, 10, 100);
+
+         events.next(new NavigationStart(2, '/b'));
+         events.next(new NavigationEnd(2, '/b', '/b'));
+         setScroll(viewportScroller, 20, 200);
+
+         events.next(new NavigationStart(3, '/c'));
+         events.next(new NavigationEnd(3, '/c', '/c'));
+         setScroll(viewportScroller, 30, 300);
+
+         events.next(new NavigationStart(4, '/a', 'popstate', {navigationId: 1}));
+         events.next(new NavigationEnd(4, '/a', '/a'));
+
+         tick(500);
+         expect(viewportScroller.scrollToPosition).not.toHaveBeenCalled();
+
+         events.next(new NavigationStart(5, '/a', 'popstate', {navigationId: 1}));
+         events.next(new NavigationEnd(5, '/a', '/a'));
+
+         tick(5000);
+         expect(viewportScroller.scrollToPosition).toHaveBeenCalledWith([10, 100]);
+       }));
+  });
+
+
+  function createRouterScroller({scrollPositionRestoration, anchorScrolling}: {
+    scrollPositionRestoration: 'disabled' | 'enabled' | 'top',
+    anchorScrolling: 'disabled' | 'enabled'
+  }) {
+    const events = new Subject<RouterEvent>();
+    const router = <any>{
+      events,
+      parseUrl: (url: any) => new DefaultUrlSerializer().parse(url),
+      triggerEvent: (e: any) => events.next(e)
+    };
+
+    const viewportScroller = jasmine.createSpyObj(
+        'viewportScroller',
+        ['getScrollPosition', 'scrollToPosition', 'scrollToAnchor', 'setHistoryScrollRestoration']);
+    setScroll(viewportScroller, 0, 0);
+
+    const scroller =
+        new RouterScroller(router, viewportScroller, {scrollPositionRestoration, anchorScrolling});
+    scroller.init();
+
+    return {events, viewportScroller, router};
+  }
+
+  function setScroll(viewportScroller: any, x: number, y: number) {
+    viewportScroller.getScrollPosition.and.returnValue([x, y]);
+  }
+});