@devzwo/ngx-magic-scroll 0.0.1-rc.2 → 1.1.0

package/README.md

@@ -45,23 +45,24 @@ Register defaults in `app.config.ts` or a component's providers:
 
 ```ts
 provideMagicScroll({
-  anchorPrefix: 'project-',
+  anchorPrefixes: ['project-', 'milestone-'],
+  anchorSelection: 'all',
   headerSelector: '.app-header',
   headerOffset: 16,
   behavior: { restoration: 'instant', interaction: 'smooth' },
 });
 ```
 
-The header's height is measured and observed automatically. `headerOffset` is an additional gap below it, or the full offset without a header. Defaults are an empty prefix and header selector, zero offset, a 500 ms scroll-spy debounce, instant restoration and smooth interaction.
+The header's height is measured and observed automatically. `headerOffset` is an additional gap below it, or the full offset without a header. Defaults are a single empty prefix in a list (`['']`, matching all descendant IDs), an empty header selector, zero offset, a 500 ms scroll-spy debounce, instant restoration and smooth interaction.
 
-Child providers inherit unspecified settings. Override an individual region with `[scrollOptions]="options"`; unspecified fields still inherit. Explicit `0`, `false` and `anchorPrefix: ''` override inherited values.
+Child providers inherit unspecified settings. Override an individual region with `[scrollOptions]="options"`; unspecified fields still inherit. Explicit `0`, `false`, `anchorPrefixes: ['']` (matches all descendant IDs), and `anchorPrefixes: []` (matches no prefix) override inherited values.
 
 ```html
 <div
   magicScroll
   #scroll="magicScroll"
   [scrollSource]="projects"
-  [scrollOptions]="{ headerOffset: 24 }"
+  [scrollOptions]="{ headerOffset: 24, anchorSelection: 'explicit' }"
 >
   ...
 </div>
@@ -72,9 +73,14 @@ Child providers inherit unspecified settings. Override an individual region with
 
 Navigation, reload and the first successful asynchronous load use `behavior.restoration`. Later data changes and resize/header corrections adjust instantly to stabilize the layout. `restoreOnDataChange: false` and `preserveOnResize: false` opt out of data corrections and resize/header corrections respectively. Visibility rules are: `none`, `top`, `full` and `always` (at least one edge visible).
 
-## Optional explicit anchors
+## Anchor selection and explicit anchors
 
-No marker is needed for normal IDs. An explicit anchor participates even outside the configured prefix:
+By default (`anchorSelection: 'all'`), all descendant IDs participate unless constrained by `anchorPrefixes`.
+
+You can also configure strict explicit selection or multiple prefixes:
+
+- **Multiple prefixes**: Pass `anchorPrefixes: ['item-', 'card-']` to include elements starting with any configured prefix.
+- **Strict explicit mode**: Set `anchorSelection: 'explicit'` to ignore all prefixes and admit only elements bearing the `[scrollAnchor]` or `scrollAnchor` marker. Generated component IDs (such as Angular Material input and form-field IDs) are completely excluded.
 
 ```html
 <section id="overview" scrollAnchor>...</section>

package/fesm2022/devzwo-ngx-magic-scroll.mjs

@@ -27,6 +27,8 @@ import * as i0 from "@angular/core";
 import { DestroyRef, Directive, ElementRef, Injectable, InjectionToken, afterNextRender, afterRenderEffect, computed, effect, inject, input, isSignal, linkedSignal, signal, untracked } from "@angular/core";
 import { ActivatedRoute, Router } from "@angular/router";
 import { toSignal } from "@angular/core/rxjs-interop";
+const MAGIC_SCROLL_ORIGIN_KEY = "__ngx_magic_scroll_origin";
+const MAGIC_SCROLL_ORIGIN_SCROLL_SPY = "scroll-spy";
 function linkedRouteFragment() {
 	const route = inject(ActivatedRoute);
 	const router = inject(Router);
@@ -34,13 +36,20 @@ function linkedRouteFragment() {
 	const actualFragment = linkedSignal(() => fragment(), ...ngDevMode ? [{ debugName: "actualFragment" }] : /* istanbul ignore next */ []);
 	effect(() => {
 		const newFragment = actualFragment();
-		if (route.snapshot.fragment !== newFragment) {
+		if (fragment() !== newFragment) {
 			const tree = router.createUrlTree([], {
 				relativeTo: route,
 				fragment: newFragment ?? void 0,
 				queryParamsHandling: "preserve"
 			});
-			router.navigateByUrl(tree, { replaceUrl: true }).catch((error) => {
+			router.navigateByUrl(tree, {
+				replaceUrl: true,
+				state: {
+					...history.state,
+					[MAGIC_SCROLL_ORIGIN_KEY]: MAGIC_SCROLL_ORIGIN_SCROLL_SPY
+				},
+				info: { [MAGIC_SCROLL_ORIGIN_KEY]: MAGIC_SCROLL_ORIGIN_SCROLL_SPY }
+			}).catch((error) => {
 				console.log(`Cant set fragment ${newFragment}`, error);
 			});
 		}
@@ -130,8 +139,13 @@ var ScrollService = class ScrollService {
 		const isTopInView = rect.top >= containerTop + topOffset - 1 && rect.top < containerTop + viewportHeight;
 		const isBottomInView = rect.bottom <= containerTop + viewportHeight && rect.bottom > containerTop;
 		if (ignoreWhenInView == "top" && isTopInView || ignoreWhenInView == "full" && isTopInView && isBottomInView || ignoreWhenInView == "always" && (isTopInView || isBottomInView)) return false;
+		const displacement = options?.displacement ?? 0;
+		const delta = rect.top - containerTop - topOffset - displacement;
+		const maxScrollTop = scrollable.scrollHeight > 0 && viewportHeight > 0 ? Math.max(0, scrollable.scrollHeight - viewportHeight) : Infinity;
+		const targetScrollTop = Math.min(Math.max(scrollable.scrollTop + delta, 0), maxScrollTop);
+		if (Math.abs(targetScrollTop - scrollable.scrollTop) < 1) return true;
 		scrollable.scrollTo({
-			top: scrollable.scrollTop + rect.top - containerTop - topOffset,
+			top: targetScrollTop,
 			behavior
 		});
 		return true;
@@ -163,7 +177,8 @@ i0.ɵɵngDeclareClassMetadata({
 	}]
 });
 const defaults = {
-	anchorPrefix: "",
+	anchorPrefixes: [""],
+	anchorSelection: "all",
 	headerSelector: "",
 	headerOffset: 0,
 	bottomOffset: 0,
@@ -175,11 +190,13 @@ const defaults = {
 	debounceTime: 500,
 	ignoreWhenInView: "none",
 	restoreOnDataChange: true,
-	preserveOnResize: true
+	preserveOnResize: true,
+	preserveOnLayoutChange: false
 };
 function resolveMagicScrollOptions(parent, options) {
 	return {
-		anchorPrefix: options.anchorPrefix ?? parent.anchorPrefix,
+		anchorPrefixes: options.anchorPrefixes ?? parent.anchorPrefixes,
+		anchorSelection: options.anchorSelection ?? parent.anchorSelection,
 		headerSelector: options.headerSelector ?? parent.headerSelector,
 		headerOffset: options.headerOffset ?? parent.headerOffset,
 		bottomOffset: options.bottomOffset ?? parent.bottomOffset,
@@ -191,7 +208,8 @@ function resolveMagicScrollOptions(parent, options) {
 		debounceTime: options.debounceTime ?? parent.debounceTime,
 		ignoreWhenInView: options.ignoreWhenInView ?? parent.ignoreWhenInView,
 		restoreOnDataChange: options.restoreOnDataChange ?? parent.restoreOnDataChange,
-		preserveOnResize: options.preserveOnResize ?? parent.preserveOnResize
+		preserveOnResize: options.preserveOnResize ?? parent.preserveOnResize,
+		preserveOnLayoutChange: options.preserveOnLayoutChange ?? parent.preserveOnLayoutChange
 	};
 }
 const MAGIC_SCROLL_OPTIONS = new InjectionToken("Magic scroll defaults", {
@@ -244,6 +262,15 @@ const SCROLL_KEYS = /* @__PURE__ */ new Set([
 	"Spacebar",
 	"Space"
 ]);
+function isNaturallyFocusable(el) {
+	if (el.hasAttribute("tabindex")) return true;
+	const tag = el.tagName.toLowerCase();
+	if (tag === "button" || tag === "select" || tag === "textarea") return !el.disabled;
+	if (tag === "input") return el.type !== "hidden" && !el.disabled;
+	if (tag === "a" || tag === "area") return el.hasAttribute("href");
+	if (tag === "iframe") return true;
+	return false;
+}
 function isEditableTarget(target) {
 	if (!target || !(target instanceof Element)) return false;
 	const tagName = target.tagName.toLowerCase();
@@ -263,6 +290,7 @@ var MagicScrollDirective = class MagicScrollDirective {
 	host = inject(ElementRef).nativeElement;
 	service = inject(ScrollService);
 	nearest = inject(NearestAnchorProvider);
+	router = inject(Router, { optional: true });
 	fragment = linkedRouteFragment();
 	initialAnchor = inject(ActivatedRoute).snapshot.fragment;
 	measuredHeaderHeight = signal(0, ...ngDevMode ? [{ debugName: "measuredHeaderHeight" }] : /* istanbul ignore next */ []);
@@ -273,8 +301,25 @@ var MagicScrollDirective = class MagicScrollDirective {
 	scrollRevision = signal(0, ...ngDevMode ? [{ debugName: "scrollRevision" }] : /* istanbul ignore next */ []);
 	initialized = false;
 	userInterrupted = false;
+	savedDisplacement = 0;
+	pendingDestination = this.initialAnchor ?? null;
+	lastProcessedFragment = void 0;
 	target;
 	timer;
+	retryObserver;
+	retryTimeoutTimer;
+	layoutCorrectionFrameId;
+	temporaryTabindexCleanups = /* @__PURE__ */ new Set();
+	pendingFocusTarget;
+	scrollEndHandler;
+	scrollEndTarget;
+	focusTimeoutTimer;
+	focusInitiator;
+	isSmoothNavigating = false;
+	pendingLayoutPreservation = false;
+	smoothNavEndHandler;
+	smoothNavTarget;
+	smoothNavTimeoutTimer;
 	constructor() {
 		const destroyRef = inject(DestroyRef);
 		afterNextRender(() => {
@@ -285,6 +330,13 @@ var MagicScrollDirective = class MagicScrollDirective {
 			this.detachListeners();
 			this.document.defaultView?.removeEventListener("resize", this.onResize);
 			clearTimeout(this.timer);
+			this.cancelDestinationRetry();
+			this.cancelScheduledFocus();
+			this.cancelLayoutPreservation();
+			this.cancelSmoothNavigation();
+			for (const cleanup of this.temporaryTabindexCleanups) cleanup();
+			this.temporaryTabindexCleanups.clear();
+			this.pendingDestination = null;
 		});
 		afterRenderEffect((onCleanup) => {
 			const selector = this.options().headerSelector;
@@ -303,21 +355,106 @@ var MagicScrollDirective = class MagicScrollDirective {
 				onCleanup(() => observer.disconnect());
 			}
 		});
+		afterRenderEffect((onCleanup) => {
+			this.scrollSource();
+			if (this.options().preserveOnLayoutChange && typeof ResizeObserver !== "undefined" && typeof window !== "undefined") {
+				const observedDimensions = /* @__PURE__ */ new Map();
+				const measureAndStore = (el) => {
+					const rect = el.getBoundingClientRect();
+					const dims = {
+						width: rect.width,
+						height: rect.height
+					};
+					observedDimensions.set(el, dims);
+					return dims;
+				};
+				const observer = new ResizeObserver((entries) => {
+					let hasRealChange = false;
+					if (!entries || !Array.isArray(entries) || entries.length === 0) hasRealChange = true;
+					else for (const entry of entries) {
+						const target = entry.target;
+						const prev = observedDimensions.get(target);
+						const rect = target.getBoundingClientRect?.();
+						const width = entry.contentRect?.width ?? rect?.width ?? 0;
+						const height = entry.contentRect?.height ?? rect?.height ?? 0;
+						if (!prev) observedDimensions.set(target, {
+							width,
+							height
+						});
+						else if (prev.width !== width || prev.height !== height) {
+							observedDimensions.set(target, {
+								width,
+								height
+							});
+							hasRealChange = true;
+						}
+					}
+					if (hasRealChange) this.scheduleLayoutPreservation();
+				});
+				measureAndStore(this.host);
+				observer.observe(this.host);
+				for (const anchor of this.anchors()) {
+					measureAndStore(anchor);
+					observer.observe(anchor);
+				}
+				onCleanup(() => {
+					observer.disconnect();
+					observedDimensions.clear();
+					this.cancelLayoutPreservation();
+				});
+			}
+		});
 		afterRenderEffect(() => {
 			const source = this.scrollSource();
 			if (!readScrollSource(source).ready) return;
 			untracked(() => {
 				if (!this.initialized) {
 					this.initialized = true;
-					if (!this.userInterrupted) this.execute(this.initialAnchor, { behavior: this.options().behavior.restoration });
-					else this.liveAnchor.set(this.calculateNearestAnchor() ?? null);
-				} else if (source !== NO_SCROLL_SOURCE && this.options().restoreOnDataChange) this.preserve("top");
+					if (!this.userInterrupted) {
+						if (!this.tryExecutePendingDestination(this.options().behavior.restoration)) {
+							if (this.pendingDestination) this.scheduleDestinationRetry();
+						}
+					} else {
+						const nearest = this.calculateNearestAnchor() ?? null;
+						this.liveAnchor.set(nearest);
+						if (nearest) this.updateSavedDisplacement(nearest);
+						this.cancelDestinationRetry();
+					}
+				} else if (this.pendingDestination && !this.userInterrupted) {
+					if (!this.tryExecutePendingDestination(this.options().behavior.restoration)) this.scheduleDestinationRetry();
+				} else if (source !== NO_SCROLL_SOURCE && this.options().restoreOnDataChange) this.preserve();
 			});
 		});
 		effect(() => {
 			const frag = this.fragment();
 			untracked(() => {
+				const prev = this.lastProcessedFragment;
+				this.lastProcessedFragment = frag;
 				this.liveAnchor.set(frag);
+				if (prev === void 0) return;
+				if (frag) {
+					if (!this.isInternalNavigation()) {
+						this.cancelScheduledFocus();
+						this.cancelLayoutPreservation();
+						this.cancelSmoothNavigation();
+						this.pendingLayoutPreservation = false;
+						this.userInterrupted = false;
+						this.savedDisplacement = 0;
+						this.pendingDestination = frag;
+						const state = readScrollSource(this.scrollSource());
+						if (this.initialized && state.ready) {
+							if (!this.tryExecutePendingDestination(this.options().behavior.restoration)) this.scheduleDestinationRetry();
+						} else this.cancelDestinationRetry();
+					}
+				} else {
+					this.cancelScheduledFocus();
+					this.cancelLayoutPreservation();
+					this.cancelSmoothNavigation();
+					this.pendingLayoutPreservation = false;
+					this.savedDisplacement = 0;
+					this.pendingDestination = null;
+					this.cancelDestinationRetry();
+				}
 			});
 		});
 		effect(() => {
@@ -326,22 +463,87 @@ var MagicScrollDirective = class MagicScrollDirective {
 			if (anchor) this.fragment.set(anchor);
 		});
 	}
+	isInternalNavigation() {
+		const raw = typeof this.router?.getCurrentNavigation === "function" ? this.router.getCurrentNavigation() ?? this.router.lastSuccessfulNavigation : this.router?.lastSuccessfulNavigation;
+		const nav = typeof raw === "function" ? raw() : raw ?? null;
+		const stateOrigin = nav?.extras?.state?.[MAGIC_SCROLL_ORIGIN_KEY];
+		return nav?.extras?.info?.[MAGIC_SCROLL_ORIGIN_KEY] === "scroll-spy" || nav?.trigger !== "popstate" && stateOrigin === "scroll-spy";
+	}
 	scrollTo(anchor, options = {}) {
+		this.refreshTarget();
+		this.cancelScheduledFocus();
+		const clean = anchor.replace(/^#/, "");
+		const targetEl = this.anchors().find((el) => el.id === clean);
+		const willScroll = targetEl ? this.willScroll(targetEl, options) : false;
+		const behavior = options.behavior ?? this.options().behavior.interaction;
+		if (willScroll && this.hasSmoothScrollBehavior(behavior)) this.beginSmoothNavigation();
+		else this.cancelSmoothNavigation();
 		const executed = this.execute(anchor, {
 			behavior: this.options().behavior.interaction,
 			ignoreWhenInView: this.options().ignoreWhenInView,
-			...options
+			...options,
+			displacement: 0
 		});
 		if (executed) {
-			const clean = anchor.replace(/^#/, "");
 			this.liveAnchor.set(clean);
+			this.savedDisplacement = 0;
+			this.pendingDestination = null;
+			this.cancelDestinationRetry();
+			this.cancelLayoutPreservation();
 			this.fragment.set(clean);
 		}
+		if (options.focus && targetEl) {
+			if (executed && willScroll && this.hasSmoothScrollBehavior(behavior)) this.scheduleFocus(targetEl);
+			else this.applyFocus(targetEl);
+		}
 		return executed;
 	}
+	tryExecutePendingDestination(behavior) {
+		if (!this.pendingDestination) return false;
+		const clean = this.pendingDestination.replace(/^#/, "");
+		const targetEl = this.anchors().find((el) => el.id === clean);
+		if ((targetEl ? this.willScroll(targetEl, { behavior }) : false) && this.hasSmoothScrollBehavior(behavior)) this.beginSmoothNavigation();
+		if (this.execute(this.pendingDestination, {
+			behavior,
+			displacement: 0
+		})) {
+			this.savedDisplacement = 0;
+			this.pendingDestination = null;
+			this.cancelDestinationRetry();
+			return true;
+		}
+		return false;
+	}
+	scheduleDestinationRetry() {
+		if (!this.retryObserver) {
+			this.retryObserver = new MutationObserver(() => {
+				if (readScrollSource(this.scrollSource()).ready) this.tryExecutePendingDestination(this.options().behavior.restoration);
+			});
+			this.retryObserver.observe(this.host, {
+				childList: true,
+				subtree: true,
+				attributes: true,
+				attributeFilter: ["id", "data-scroll-anchor"]
+			});
+		}
+		clearTimeout(this.retryTimeoutTimer);
+		this.retryTimeoutTimer = setTimeout(() => this.cancelDestinationRetry(), 1e3);
+	}
+	cancelDestinationRetry() {
+		if (this.retryObserver) {
+			this.retryObserver.disconnect();
+			this.retryObserver = void 0;
+		}
+		clearTimeout(this.retryTimeoutTimer);
+		this.retryTimeoutTimer = void 0;
+	}
 	anchors() {
-		const prefix = this.options().anchorPrefix;
-		return Array.from(this.host.querySelectorAll("[id]")).filter((el) => !!el.id && (el.hasAttribute("data-scroll-anchor") || el.id.startsWith(prefix)) && el.closest("[magicScroll]") === this.host);
+		const { anchorSelection, anchorPrefixes } = this.options();
+		return Array.from(this.host.querySelectorAll("[id]")).filter((el) => {
+			if (!el.id || el.closest("[magicScroll]") !== this.host) return false;
+			if (anchorSelection === "explicit") return el.hasAttribute("data-scroll-anchor");
+			return el.hasAttribute("data-scroll-anchor") || anchorPrefixes.some((prefix) => el.id.startsWith(prefix));
+		});
 	}
 	scrollable() {
 		const overflow = getComputedStyle(this.host).overflowY;
@@ -366,12 +568,63 @@ var MagicScrollDirective = class MagicScrollDirective {
 			...options
 		});
 	}
-	preserve(ignoreWhenInView = "none") {
-		if (this.initialized) this.execute(this.liveAnchor(), {
-			behavior: "instant",
-			ignoreWhenInView
+	willScroll(targetEl, options) {
+		const scrollable = this.scrollable() ?? this.document.scrollingElement ?? this.document.documentElement;
+		const isDocument = scrollable === this.document.documentElement || scrollable === this.document.body;
+		const containerTop = isDocument ? 0 : scrollable.getBoundingClientRect().top;
+		const viewportHeight = isDocument ? this.document.documentElement.clientHeight : scrollable.clientHeight;
+		const topOffset = options.topOffset ?? this.offset();
+		const delta = targetEl.getBoundingClientRect().top - containerTop - topOffset;
+		const maxScrollTop = scrollable.scrollHeight > 0 && viewportHeight > 0 ? Math.max(0, scrollable.scrollHeight - viewportHeight) : Infinity;
+		const targetScrollTop = Math.min(Math.max(scrollable.scrollTop + delta, 0), maxScrollTop);
+		return Math.abs(targetScrollTop - scrollable.scrollTop) >= 1;
+	}
+	hasSmoothScrollBehavior(behavior) {
+		if (behavior === "smooth") return true;
+		if (behavior !== "auto") return false;
+		const scrollable = this.scrollable() ?? this.document.documentElement;
+		return this.document.defaultView?.getComputedStyle(scrollable).scrollBehavior === "smooth";
+	}
+	preserve() {
+		if (this.initialized) {
+			if (this.isSmoothNavigating) {
+				this.pendingLayoutPreservation = true;
+				return;
+			}
+			const anchor = this.liveAnchor();
+			if (!anchor) return;
+			this.execute(anchor, {
+				behavior: "instant",
+				displacement: this.savedDisplacement
+			});
+		}
+	}
+	scheduleLayoutPreservation() {
+		if (!this.initialized || typeof window === "undefined") return;
+		if (this.isSmoothNavigating) {
+			this.pendingLayoutPreservation = true;
+			return;
+		}
+		if (this.layoutCorrectionFrameId !== void 0) return;
+		this.layoutCorrectionFrameId = window.requestAnimationFrame(() => {
+			this.layoutCorrectionFrameId = void 0;
+			this.preserve();
 		});
 	}
+	cancelLayoutPreservation() {
+		if (this.layoutCorrectionFrameId !== void 0 && typeof window !== "undefined") {
+			window.cancelAnimationFrame(this.layoutCorrectionFrameId);
+			this.layoutCorrectionFrameId = void 0;
+		}
+	}
+	updateSavedDisplacement(anchorId) {
+		const clean = anchorId.replace(/^#/, "");
+		const anchorEl = this.anchors().find((el) => el.id === clean);
+		if (!anchorEl) return;
+		const scrollable = this.scrollable();
+		const topBoundary = (!scrollable || scrollable === this.document.documentElement || scrollable === this.document.body ? 0 : scrollable.getBoundingClientRect().top) + this.offset();
+		this.savedDisplacement = anchorEl.getBoundingClientRect().top - topBoundary;
+	}
 	refreshTarget() {
 		const target = this.scrollable() ?? this.document;
 		if (target !== this.target) {
@@ -388,8 +641,66 @@ var MagicScrollDirective = class MagicScrollDirective {
 		target.addEventListener("keydown", this.onKeyDown);
 		this.document.addEventListener("keydown", this.onKeyDown);
 	}
+	applyFocus(targetEl) {
+		if (!this.document.defaultView || typeof targetEl.focus !== "function" || !targetEl.isConnected || !this.anchors().includes(targetEl)) return;
+		const addedTabindex = !isNaturallyFocusable(targetEl);
+		let cleanup;
+		if (addedTabindex) {
+			targetEl.setAttribute("tabindex", "-1");
+			const onBlur = () => cleanupFn();
+			const cleanupFn = () => {
+				targetEl.removeEventListener("blur", onBlur);
+				if (targetEl.getAttribute("tabindex") === "-1") targetEl.removeAttribute("tabindex");
+				this.temporaryTabindexCleanups.delete(cleanupFn);
+			};
+			cleanup = cleanupFn;
+			this.temporaryTabindexCleanups.add(cleanupFn);
+			targetEl.addEventListener("blur", onBlur, { once: true });
+		}
+		targetEl.focus({ preventScroll: true });
+		if (this.document.activeElement !== targetEl && cleanup) cleanup();
+	}
+	scheduleFocus(targetEl) {
+		this.refreshTarget();
+		this.cancelScheduledFocus();
+		this.pendingFocusTarget = targetEl;
+		this.focusInitiator = this.document.activeElement;
+		this.document.addEventListener("focusin", this.onFocusIn);
+		this.document.addEventListener("keydown", this.onFocusTransferKeyDown);
+		this.document.addEventListener("pointerdown", this.onFocusTransferPointerDown, true);
+		this.document.addEventListener("wheel", this.onFocusScrollIntent, { passive: true });
+		this.document.addEventListener("touchstart", this.onFocusScrollIntent, { passive: true });
+		this.document.addEventListener("touchmove", this.onFocusScrollIntent, { passive: true });
+		const target = this.target;
+		this.scrollEndTarget = target;
+		this.scrollEndHandler = () => {
+			this.cancelScheduledFocus();
+			this.applyFocus(targetEl);
+		};
+		target.addEventListener("scrollend", this.scrollEndHandler, { once: true });
+		this.focusTimeoutTimer = setTimeout(() => this.cancelScheduledFocus(), 5e3);
+	}
+	cancelScheduledFocus() {
+		if (this.scrollEndHandler && this.scrollEndTarget) {
+			this.scrollEndTarget.removeEventListener("scrollend", this.scrollEndHandler);
+			this.scrollEndHandler = void 0;
+			this.scrollEndTarget = void 0;
+		}
+		clearTimeout(this.focusTimeoutTimer);
+		this.focusTimeoutTimer = void 0;
+		this.document.removeEventListener("focusin", this.onFocusIn);
+		this.document.removeEventListener("keydown", this.onFocusTransferKeyDown);
+		this.document.removeEventListener("pointerdown", this.onFocusTransferPointerDown, true);
+		this.document.removeEventListener("wheel", this.onFocusScrollIntent);
+		this.document.removeEventListener("touchstart", this.onFocusScrollIntent);
+		this.document.removeEventListener("touchmove", this.onFocusScrollIntent);
+		this.focusInitiator = void 0;
+		this.pendingFocusTarget = void 0;
+	}
 	detachListeners() {
 		if (!this.target) return;
+		this.cancelScheduledFocus();
+		this.cancelSmoothNavigation();
 		this.target.removeEventListener("scroll", this.onScroll);
 		this.target.removeEventListener("wheel", this.onUserIntent);
 		this.target.removeEventListener("touchstart", this.onUserIntent);
@@ -399,6 +710,12 @@ var MagicScrollDirective = class MagicScrollDirective {
 	}
 	onUserIntent = () => {
 		this.userInterrupted = true;
+		this.pendingDestination = null;
+		this.cancelDestinationRetry();
+		this.cancelScheduledFocus();
+		this.cancelLayoutPreservation();
+		this.cancelSmoothNavigation();
+		this.pendingLayoutPreservation = false;
 	};
 	onKeyDown = (event) => {
 		if (!(event instanceof KeyboardEvent)) return;
@@ -406,12 +723,44 @@ var MagicScrollDirective = class MagicScrollDirective {
 		if (!SCROLL_KEYS.has(event.key)) return;
 		const targetEl = event.target;
 		const scrollable = this.scrollable();
-		if (!targetEl || targetEl === this.document.body || targetEl === this.document.documentElement || (scrollable ? scrollable === targetEl || scrollable.contains(targetEl) : true)) this.userInterrupted = true;
+		if (!targetEl || targetEl === this.document.body || targetEl === this.document.documentElement || (scrollable ? scrollable === targetEl || scrollable.contains(targetEl) : true)) {
+			this.userInterrupted = true;
+			this.pendingDestination = null;
+			this.cancelDestinationRetry();
+			this.cancelScheduledFocus();
+			this.cancelLayoutPreservation();
+			this.cancelSmoothNavigation();
+			this.pendingLayoutPreservation = false;
+		}
+	};
+	onFocusScrollIntent = () => {
+		this.cancelScheduledFocus();
+	};
+	onFocusIn = (event) => {
+		if (this.pendingFocusTarget && event.target !== this.focusInitiator) this.cancelScheduledFocus();
+	};
+	onFocusTransferKeyDown = (event) => {
+		if (!(event instanceof KeyboardEvent)) return;
+		if (event.key === "Tab") {
+			this.cancelScheduledFocus();
+			return;
+		}
+		if (isEditableTarget(event.target)) return;
+		if (SCROLL_KEYS.has(event.key)) this.cancelScheduledFocus();
+	};
+	onFocusTransferPointerDown = (event) => {
+		const target = event.target;
+		if (this.pendingFocusTarget && target instanceof Node && target !== this.focusInitiator && !this.focusInitiator?.contains(target)) this.cancelScheduledFocus();
 	};
 	onScroll = () => {
 		if (!this.initialized) return;
-		const anchor = this.calculateNearestAnchor();
-		if (anchor) this.liveAnchor.set(anchor);
+		if (!this.isSmoothNavigating) {
+			const anchor = this.calculateNearestAnchor();
+			if (anchor) {
+				this.liveAnchor.set(anchor);
+				this.updateSavedDisplacement(anchor);
+			}
+		}
 		clearTimeout(this.timer);
 		this.timer = setTimeout(() => this.scrollRevision.update((revision) => revision + 1), this.options().debounceTime);
 	};
@@ -419,6 +768,42 @@ var MagicScrollDirective = class MagicScrollDirective {
 		this.refreshTarget();
 		if (this.options().preserveOnResize) this.preserve();
 	};
+	beginSmoothNavigation() {
+		this.cancelSmoothNavigation();
+		this.isSmoothNavigating = true;
+		this.refreshTarget();
+		const target = this.target;
+		this.smoothNavTarget = target;
+		this.smoothNavEndHandler = () => {
+			this.endSmoothNavigation();
+		};
+		target.addEventListener("scrollend", this.smoothNavEndHandler, { once: true });
+		this.smoothNavTimeoutTimer = setTimeout(() => {
+			this.endSmoothNavigation();
+		}, 3e3);
+	}
+	endSmoothNavigation() {
+		this.cancelSmoothNavigation();
+		const anchor = this.calculateNearestAnchor();
+		if (anchor) {
+			this.liveAnchor.set(anchor);
+			this.updateSavedDisplacement(anchor);
+		}
+		if (this.pendingLayoutPreservation) {
+			this.pendingLayoutPreservation = false;
+			this.scheduleLayoutPreservation();
+		}
+	}
+	cancelSmoothNavigation() {
+		if (this.smoothNavEndHandler && this.smoothNavTarget) {
+			this.smoothNavTarget.removeEventListener("scrollend", this.smoothNavEndHandler);
+			this.smoothNavEndHandler = void 0;
+			this.smoothNavTarget = void 0;
+		}
+		clearTimeout(this.smoothNavTimeoutTimer);
+		this.smoothNavTimeoutTimer = void 0;
+		this.isSmoothNavigating = false;
+	}
 	static ɵfac = i0.ɵɵngDeclareFactory({
 		minVersion: "12.0.0",
 		version: "22.2.1",