ScrollSpy design RFC

[maxokorokov]

Hey,

I've been playing with the ScrollSpy a little recently with implementation based on the IntersectionObserver. Here is the RFC for the API I came up with.

1. ScrollSpy service

It can be started/stopped on any element or on the whole document. You can add/remove fragments to watch and be notified when a particular fragment becomes active.

You can configure rootMargin for the IntersectionObserver and pass a ChangeDetectorRef that will be marked for check when active fragment changes.

It also allows to scroll to a particular fragment manually.

interface NgbScrollSpyOptions extends Pick<IntersectionObserverInit, 'rootMargin'> {
  changeDetectorRef?: ChangeDetectorRef;
}

@Injectable({ providedIn: 'root' })
class NgbScrollSpyService {

  get active(): string;               // currently active fragment
  get active$(): Observable<string>;  // active fragment

  start(element: HTMLElement | Document, options: NgbScrollSpyOptions = {}); // starts intersection observer
  stop();                             // stops intersection observer

  addFragment(id: string);            // adds a new element to watch for
  removeFragment(id: string);         // removes the element from watching

  scrollTo(id: string);               // scrolls to a fragment
}

Example 1 - Service usage

const scrollSpy = inject(NgbScrollSpyService);
const changeDetectorRef = inject(ChangeDetectorRef); // optional of course

scrollSpy.start(document, { rootMargin: '24px', changeDetectorRef });

scrollSpy.addFragment('one');

scrollSpy.active; // 'one' or ''
scrollSpy.active$.subscribe(active => {});


scrollSpy.addFragment('two');

scrollSpy.scrollTo('two');

2. ScrollSpy directive

Allows to setup the NgbScrollSpy service on a particular element.

@Directive({
  selector: '[ngbScrollSpy]',
  exportAs: 'ngbScrollSpy'
})
class NgbScrollSpy {

  @Input() rootMargin: string;
  @Output() activeChange: EventEmitter<string>;

  get active(): string;
  get active$(): Observable<string>;

  scrollTo(id: string);
}


@Directive({
  selector: '[ngbScrollSpyFragment]'
})
class NgbScrollSpyFragment {

  @Input('ngbScrollSpyFragment') id: string;
}

Example 2 - Directive usage

<div ngbScrollSpy #s="ngbScrollSpy" (activeChange)="..." rootMargin="...">
  <h2 ngbScrollSpyFragment="one"></h2>
  <h2 ngbScrollSpyFragment="two"></h2>
</div>

<button (click)="s.scrollTo('one')">Scroll to</button>
<span [class.active]="s.active === 'two'">Second active</span>

3. Helper menu directives

NgbScrollSpyItem and NgbScrollSpyNav allow to handle .active class changes and build hierarchical menus.

@Directive({
  selector: '[ngbScrollSpyItem]',
  exportAs: 'ngbScrollSpyItem'
})
class NgbScrollSpyItem {

  @Input('ngbScrollSpyItem') scrollSpy: NgbScrollSpy; // optional scrollspy
  @Input() fragment: string;  // references a fragment to scroll to
  @Input() parent: string;    // references a parent item in case of hierarchical highlighting

  isActive(): boolean;        // `true`, if current item is  active
  scrollTo();                 // scrolls to a current item
}

@Directive({
  selector: '[ngbScrollSpyNav]'
})
class NgbScrollSpyNav {
  @Input('ngbScrollNav') scrollSpy: NgbScrollSpy; // optional scrollspy
}

Example 3.1 - Simple menu items

These will handle click and scrolling.

<button ngbScrollSpyItem fragment="one">One</button>       <!-- service instance got via DI -->
<button [ngbScrollSpyItem]="s" fragment="one">One</button> <!-- scrollSpy referenced directly -->
<button [ngbScrollSpyItem]="[s, 'one']">One</button>       <!-- shortcut syntax -->

<div ngbScrollSpy #s="ngbScrollSpy">
  <h2 ngbScrollSpyFragment="one"></h2>
</div>

Example 3.2 - Simple menu links

These will not handle clicks and won't scroll, usually this will be done by the router.

<a ngbScrollSpyItem routerLink="." fragment="one">One</a>  <!-- service instance got via DI -->
<a [ngbScrollSpyItem]="s" fragment="one">One</a>           <!-- scrollSpy referenced directly -->

<div ngbScrollSpy #s="ngbScrollSpy">
  <h2 ngbScrollSpyFragment="one"></h2>
</div>

Example 3.3 - Using items

Any individual item can be referenced

<button ngbScrollSpyItem #item="ngbScrollSpyItem" fragment="one">One</button>

<button (click)="item.scrollTo()">Scroll to</button>
<span [class.active]="item.isActive()">First is active</span>

Example 3.4 - Complex menus

These will allow to build hierarchical highlighting. Can be applied to an arbitrary markup and bound either to a service via DI or to a particular instance of a ScrollSpy directive.

In this case parent-child relationships have to be esablished manually via the parent link and ngbScrollSpyNav group.

<nav [ngbScrollSpyNav]="s"> <!-- can also get an instance via DI -->
  <nav class="nav nav-pills flex-column">
    <a class="nav-link" [ngbScrollSpyItem]="s" fragment="p1"> Parent 1</a>
      <nav class="nav nav-pills flex-column">
        <a class="nav-link ms-3 my-1" ngbScrollSpyItem fragment="one" parent="p1">Item 1</a>
        <a class="nav-link ms-3 my-1" [ngbScrollSpyItem]="[s, 'two', 'p1']">Item 2</a>
      </nav>
  </nav>
</nav>

<div ngbScrollSpy #s="ngbScrollSpy">
  <h1 ngbScrollSpyFragment="p1"></h1>
  <h2 ngbScrollSpyFragment="one"></h2>
  <h2 ngbScrollSpyFragment="two"></h2>
</div>

cc @jnizet, @ExFlo, @divdavem, @fbasso