Migration Guide: v1.0 to v1.1

This guide details the new features, behavioral improvements, and recommended configuration updates when upgrading @devzwo/ngx-magic-scroll from 1.0.x to 1.1.0.

Overview of Changes

Release v1.1.0 is backwards-compatible and introduces several opt-in enhancements:

• Layout Reflow Preservation: New opt-in preserveOnLayoutChange setting to preserve reading positions during asynchronous DOM expansions (such as accordions, dynamic cards, or lazy images).
• Exact Displacement Tracking: Section-relative scroll tracking now maintains intra-section pixel displacement (displacement) rather than resetting to the section top.
• Accessible Focus Management: The scrollTo() method supports { focus: true } to transfer keyboard focus safely to the scrolled target.

---

1. Enabling Layout Reflow Preservation

Previous Behavior (v1.0.0)

In v1.0.0, position preservation was triggered when scrollSource data changed or on container window resize events. Asynchronous DOM reflows that did not alter scrollSource (e.g. collapsing/expanding an accordion or loading un-dimensioned images) could shift content away from the reader’s viewport.

Updated Configuration (v1.1.0)

Enable preserveOnLayoutChange: true in your global provider or directly on the [magicScroll] directive to automatically observe DOM layout shifts and maintain the reader’s view.

Before (v1.0.0)

import { Component } from '@angular/core';
import {
  MagicScrollDirective,
  ScrollAnchorDirective,
  provideMagicScroll,
} from '@devzwo/ngx-magic-scroll';

@Component({
  selector: 'app-migration-sample-before',
  imports: [MagicScrollDirective, ScrollAnchorDirective],
  providers: [provideMagicScroll()],
  template: `
    <div magicScroll>
      <section id="section-1" scrollAnchor>
        <h2>Section 1</h2>
      </section>
      <section id="section-2" scrollAnchor>
        <h2>Section 2</h2>
      </section>
    </div>
  `,
})
export class MigrationSampleBeforeComponent {}

After (v1.1.0)

import { Component } from '@angular/core';
import {
  MagicScrollDirective,
  ScrollAnchorDirective,
  provideMagicScroll,
} from '@devzwo/ngx-magic-scroll';

@Component({
  selector: 'app-migration-sample-after',
  imports: [MagicScrollDirective, ScrollAnchorDirective],
  providers: [
    provideMagicScroll({
      preserveOnLayoutChange: true,
    }),
  ],
  template: `
    <div magicScroll [scrollOptions]="{ preserveOnLayoutChange: true }">
      <section id="section-1" scrollAnchor>
        <h2>Section 1</h2>
      </section>
      <section id="section-2" scrollAnchor>
        <h2>Section 2</h2>
      </section>
    </div>
  `,
})
export class MigrationSampleAfterComponent {}

---

2. Accessible Focus Navigation

Previous Implementation (v1.0.0)

In v1.0.0, programmatic navigation via scrollTo('section-id') scrolled the viewport but did not alter keyboard DOM focus. Developers had to manually manage element focus and tabindex attributes.

Updated Implementation (v1.1.0)

Pass { focus: true } in scrollTo(). The directive automatically manages temporary tabindex="-1" attributes on non-focusable elements and waits for smooth scrolling to complete (scrollend) before transferring focus:

import { Component, viewChild } from '@angular/core';
import { MagicScrollDirective, provideMagicScroll } from '@devzwo/ngx-magic-scroll';

@Component({
  selector: 'app-migration-focus-sample',
  imports: [MagicScrollDirective],
  providers: [provideMagicScroll()],
  template: `
    <nav>
      <button (click)="navigateToAnchor('section-2')">Jump to Section 2</button>
    </nav>
    <div magicScroll #scroll="magicScroll">
      <section id="section-1">
        <h2>Section 1</h2>
      </section>
      <section id="section-2">
        <h2>Section 2</h2>
      </section>
    </div>
  `,
})
export class MigrationFocusSampleComponent {
  readonly scroll = viewChild.required<MagicScrollDirective>('scroll');

  navigateToAnchor(targetId: string): void {
    this.scroll().scrollTo(targetId, {
      behavior: 'smooth',
      focus: true,
    });
  }
}

---

3. Deprecations and Breaking Changes

• Breaking Changes: None. All existing v1.0.0 configurations and APIs remain functional without modification.
• Deprecations: None in this release.