Migration Guide: v0.0.1-rc.2 to v1.0.0

This guide details the major features, navigation automation, anchor selection modes, and recommended upgrade steps when moving @devzwo/ngx-magic-scroll from v0.0.1-rc.2 to v1.0.0.

Overview of Changes

Release v1.0.0 marks the first stable production release of @devzwo/ngx-magic-scroll. Key enhancements include:

• Automatic Subsequent Router Fragment Navigation: Subsequent Angular router navigation with URL fragments is handled automatically without manual router event subscriptions.
• Asynchronous Mutation Retry Queue: Pending scroll targets are queued and retried automatically via MutationObserver until matching DOM elements appear.
• Multi-Prefix Anchor Matching: anchorPrefixes accepts an array of string prefixes to match multiple naming schemes across complex views.
• Strict Explicit Anchor Mode: anchorSelection: 'explicit' mode restricts anchor discovery exclusively to elements marked with [scrollAnchor].
• Browser Popstate & History Restoration: Full coordination with browser back and forward navigation for restoring prior scroll positions.

---

1. Automatic Router Fragment Navigation & Retry Queues

Previous Behavior (v0.0.1-rc.2)

In v0.0.1-rc.2, the directive focused on initial URL fragment restoration on page load. Navigating between fragments on the same route often required manual event listening or custom imperative calls to scrollTo(). Furthermore, if an anchor was rendered asynchronously after a route transition, navigation could fail if the element wasn’t immediately present.

Updated Behavior (v1.0.0)

In v1.0.0, MagicScrollDirective automatically subscribes to Angular Router fragment changes throughout the component lifecycle. If the target element is not in the DOM immediately (e.g. while data is fetching or templates are rendering), the directive queues the navigation request and retries automatically via MutationObserver until the element is mounted.

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

@Component({
  selector: 'app-migration-rc2-router-nav',
  imports: [RouterLink, MagicScrollDirective, ScrollAnchorDirective],
  providers: [provideMagicScroll()],
  template: `
    <nav>
      <!-- Subsequent fragment clicks automatically scroll and update active anchor in v1.0.0 -->
      <a routerLink="." fragment="overview">Overview</a>
      <a routerLink="." fragment="pricing">Pricing</a>
      <a routerLink="." fragment="faq">FAQ</a>
    </nav>

    <div magicScroll>
      <section id="overview" scrollAnchor>
        <h2>Overview</h2>
      </section>
      <section id="pricing" scrollAnchor>
        <h2>Pricing</h2>
      </section>
      <section id="faq" scrollAnchor>
        <h2>FAQ</h2>
      </section>
    </div>
  `,
})
export class MigrationRc2RouterNavComponent {}

---

2. Multi-Prefix Anchor Matching

Previous Configuration (v0.0.1-rc.2)

In v0.0.1-rc.2, anchor discovery matched either all DOM IDs or elements starting with a single configured prefix.

Updated Configuration (v1.0.0)

v1.0.0 supports anchorPrefixes as an array of prefixes (string[]). Elements matching any of the prefixes are registered automatically as anchors.

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

@Component({
  selector: 'app-migration-rc2-prefixes-sample',
  imports: [MagicScrollDirective],
  providers: [
    provideMagicScroll({
      // Match anchors with either prefix across the application
      anchorPrefixes: ['section-', 'module-'],
    }),
  ],
  template: `
    <div magicScroll>
      <!-- Automatically registered via 'section-' prefix -->
      <section id="section-header">
        <h2>Header Section</h2>
      </section>

      <!-- Automatically registered via 'module-' prefix -->
      <section id="module-analytics">
        <h2>Analytics Module</h2>
      </section>

      <!-- Ignored by scroll-spy because prefix does not match -->
      <div id="unrelated-dom-id">
        <p>Regular container</p>
      </div>
    </div>
  `,
})
export class MigrationRc2PrefixesSampleComponent {}

---

3. Strict Explicit Anchor Selection Mode

Previous Configuration (v0.0.1-rc.2)

In v0.0.1-rc.2, all child elements with an id attribute were candidates for anchor navigation unless filtered by prefixes.

Updated Configuration (v1.0.0)

v1.0.0 introduces anchorSelection: 'explicit'. When enabled, only elements with the [scrollAnchor] or scrollAnchor directive are recognized, ignoring standard DOM IDs entirely:

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

@Component({
  selector: 'app-migration-rc2-explicit-sample',
  imports: [MagicScrollDirective, ScrollAnchorDirective],
  providers: [
    provideMagicScroll({
      // Only recognize elements explicitly tagged with scrollAnchor
      anchorSelection: 'explicit',
    }),
  ],
  template: `
    <div magicScroll>
      <!-- Explicit anchor directive included -->
      <section id="features" scrollAnchor>
        <h2>Features</h2>
      </section>

      <!-- Explicit anchor with dynamic input ID binding -->
      <section [scrollAnchor]="'reviews'">
        <h2>Reviews</h2>
      </section>

      <!-- Excluded from anchor tracking even though it has an ID -->
      <div id="internal-widget">
        <p>Widget content</p>
      </div>
    </div>
  `,
})
export class MigrationRc2ExplicitSampleComponent {}

---

4. Deprecations and Breaking Changes

• Breaking Changes: None. Upgrading to v1.0.0 preserves backwards compatibility with existing v0.0.1-rc.2 options.
• Deprecations: None.