MagicScrollDirective

Complete facade directive coordinating anchor scrolling, two-tier route synchronization, user-intent cancellation, data readiness restoration, and layout/data position preservation.

Remarks

Architectural Pillars:

1. Two-Tier Anchor State Model:
   • liveAnchor: Immediate per-scroll evaluation representing the visible section currently in view. Used as the source of truth for immediate data and layout realignments.
   • fragment / activeAnchor: Debounced (default 500ms) URL router synchronization preventing browser history thrashing during continuous scrolling.
2. User Intent Detection & Cancellation:
   • Captures manual user gestures (wheel, touchstart, touchmove, navigation keydown) occurring prior to asynchronous scrollSource readiness.
   • Invalidates pending delayed initial restorations so conscious user navigation is never overridden.
   • Safely excludes editable form controls (<input>, <textarea>, contenteditable).
3. Reactive Render Pipeline & Lifecycle Coordination:
   • Sequenced afterRenderEffect execution blocks guarantee sticky header measurement and ResizeObserver monitoring are active before initial fragment restoration and data preservation execute.
4. Preservation & Realignment Engine:
   • Automatic realignments (preserve()) on data updates and container/header resizes based on the live active section.
5. Container & Anchor Scoping:
   • Automatic scroll container resolution (window vs scrollable element) and hierarchical anchor ownership isolation.

Example

<div magicScroll #scroll="magicScroll" [scrollSource]="projects">
  <section id="project-1">...</section>
  <section id="project-2">...</section>
</div>
<button (click)="scroll.scrollTo('project-2')">Go to Project 2</button>

Constructors

Constructor

new MagicScrollDirective(): MagicScrollDirective

Returns

MagicScrollDirective

Properties

activeAnchor

readonly activeAnchor: Signal<string | null | undefined>

Current URL anchor, suitable for active-navigation highlighting.

---

headerHeight

readonly headerHeight: Signal<number>

Measured header height, useful for sticky companion panels.

---

offset

readonly offset: Signal<number>

Complete effective top offset, including header height and configured gap.

---

scrollOptions

readonly scrollOptions: InputSignal<MagicScrollOptions>

Configuration overrides merged with global provideMagicScroll options.

---

scrollSource

readonly scrollSource: InputSignalWithTransform<ScrollSource | typeof NO_SCROLL_SOURCE, ScrollSource>

Asynchronous data source or signal determining scroll readiness.

• When omitted (NO_SCROLL_SOURCE), initial restoration executes on the initial rendered DOM.
• When provided, initial restoration waits until readScrollSource(source).ready === true. Subsequent ready data updates trigger automatic position preservation when restoreOnDataChange is enabled.

Methods

scrollTo()

scrollTo(anchor, options?): boolean

Explicitly scrolls the viewport to the target anchor identifier.

Parameters

anchor

string

Target anchor ID (with or without leading #).

options?

MagicScrollToOptions = {}

Per-call scroll overrides (behavior, top offset, ignoreWhenInView, focus).

Returns

boolean

true if the target anchor was found and scrolling initiated; false otherwise.

Remarks

Successful execution immediately synchronizes both liveAnchor and the router fragment with the target anchor, overriding any in-flight debounce delays.

When options.focus is true, DOM focus is transferred to the resolved anchor element using preventScroll: true without triggering secondary browser scrolling. For non-focusable containers, a temporary tabindex="-1" is applied and removed upon blur or directive destruction.