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

package/types/devzwo-ngx-magic-scroll.d.ts

@@ -26,6 +26,18 @@ interface ScrollOptions {
    * Defaults to 20 pixels.
    */
   topOffset?: number;
+  /**
+   * Target anchor-relative pixel displacement relative to the top offset boundary.
+   * Negative values position the element higher (scrolled into), positive values lower.
+   * Defaults to 0 (element top aligned to topOffset).
+   */
+  displacement?: number;
+  /**
+   * Whether to transfer DOM focus to the resolved anchor element.
+   * Uses `preventScroll: true` and temporary `tabindex="-1"` for non-focusable targets.
+   * Defaults to `false`.
+   */
+  focus?: boolean;
 }
 /**
  * Central service for scrolling to DOM elements and anchors.
@@ -60,10 +72,28 @@ declare class ScrollService {
   static ɵfac: i0.ɵɵFactoryDeclaration<ScrollService, never>;
   static ɵprov: i0.ɵɵInjectableDeclaration<any>;
 }
+/**
+ * Anchor selection strategy for a `magicScroll` region.
+ * - `'all'`: Default strategy. Descendant elements matching any configured `anchorPrefixes`
+ *   (or all non-empty IDs if no prefix is configured) as well as explicit `scrollAnchor` markers participate.
+ * - `'explicit'`: Strict explicit-only mode. Only elements marked with `[scrollAnchor]` or `scrollAnchor`
+ *   participate, regardless of their element ID or configured prefixes.
+ */
+type AnchorSelectionMode = 'all' | 'explicit';
 /** Defaults for an application or overrides for one `magicScroll` region. */
 interface MagicScrollOptions {
-  /** All descendant IDs participate when empty. Explicit `scrollAnchor`s also participate. */
-  anchorPrefix?: string;
+  /**
+   * Allowed anchor ID prefixes. Descendant elements matching any prefix participate.
+   * Explicit `scrollAnchor` markers also participate.
+   * Passing an empty array `[]` disables prefix matching so only explicit markers participate.
+   */
+  anchorPrefixes?: readonly string[] | string[];
+  /**
+   * Selection strategy for anchor discovery.
+   * - `'all'`: Selects elements matching prefixes or explicit markers (default).
+   * - `'explicit'`: Selects only elements with explicit `scrollAnchor` markers.
+   */
+  anchorSelection?: AnchorSelectionMode;
   /** Selector for a fixed/sticky header whose height is measured automatically. */
   headerSelector?: string;
   /** Gap below the header, or the complete top offset when no header is selected. */
@@ -83,9 +113,16 @@ interface MagicScrollOptions {
   restoreOnDataChange?: boolean;
   /** Preserve the current anchor on window resize and measured header-height changes. */
   preserveOnResize?: boolean;
+  /**
+   * Preserve anchor-relative reading position when region content reflows
+   * (e.g. image loads, form expansions, accordion toggles) without changing scrollSource.
+   * Defaults to false (explicit opt-in).
+   */
+  preserveOnLayoutChange?: boolean;
 }
 interface ResolvedMagicScrollOptions {
-  anchorPrefix: string;
+  anchorPrefixes: readonly string[];
+  anchorSelection: AnchorSelectionMode;
   headerSelector: string;
   headerOffset: number;
   bottomOffset: number;
@@ -98,6 +135,7 @@ interface ResolvedMagicScrollOptions {
   ignoreWhenInView: NonNullable<ScrollOptions['ignoreWhenInView']>;
   restoreOnDataChange: boolean;
   preserveOnResize: boolean;
+  preserveOnLayoutChange: boolean;
 }
 declare function resolveMagicScrollOptions(parent: ResolvedMagicScrollOptions, options: MagicScrollOptions): ResolvedMagicScrollOptions;
 declare const MAGIC_SCROLL_OPTIONS: InjectionToken<ResolvedMagicScrollOptions>;
@@ -106,7 +144,7 @@ declare const MAGIC_SCROLL_OPTIONS: InjectionToken<ResolvedMagicScrollOptions>;
  * Per-region `scrollOptions` and per-call `scrollTo` options take precedence.
  *
  * @example
- * provideMagicScroll({ anchorPrefix: 'project-', behavior: { interaction: 'smooth' } })
+ * provideMagicScroll({ anchorPrefixes: ['project-'], behavior: { interaction: 'smooth' } })
  */
 export declare function provideMagicScroll(options?: MagicScrollOptions): Provider;
 /** Reactive getters must read signals so loading and data changes are tracked.
@@ -140,7 +178,7 @@ declare function readScrollSource(source: ScrollSource | typeof NO_SCROLL_SOURCE
  * Per-action scroll options for programmatic navigation via {@link MagicScrollDirective.scrollTo}.
  * Top offsets and container scoping are resolved automatically by the directive facade.
  */
-type MagicScrollToOptions = Pick<ScrollOptions, 'behavior' | 'topOffset' | 'ignoreWhenInView'>;
+type MagicScrollToOptions = Pick<ScrollOptions, 'behavior' | 'topOffset' | 'ignoreWhenInView' | 'focus'>;
 /**
  * Complete facade directive coordinating anchor scrolling, two-tier route synchronization,
  * user-intent cancellation, data readiness restoration, and layout/data position preservation.
@@ -161,7 +199,7 @@ type MagicScrollToOptions = Pick<ScrollOptions, 'behavior' | 'topOffset' | 'igno
  *    - 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('top')`) on data updates and container/header resizes based on the live active section.
+ *    - 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.
  *
@@ -190,6 +228,7 @@ export declare class MagicScrollDirective {
   private readonly host;
   private readonly service;
   private readonly nearest;
+  private readonly router;
   /** Bidirectional route fragment synchronization signal (debounced URL writer and listener). */
   private readonly fragment;
   /** Initial route URL fragment snapshot captured upon directive instantiation. */
@@ -214,31 +253,118 @@ export declare class MagicScrollDirective {
   private initialized;
   /**
    * Flag indicating whether manual user interaction (wheel, touch, or navigation keys) occurred
-   * before asynchronous data loading became ready. When true, delayed initial restoration is skipped.
+   * before asynchronous data loading became ready. When true, delayed restoration is skipped.
    */
   private userInterrupted;
+  /**
+   * Region-local anchor-relative pixel displacement tracking the distance between
+   * the active section's top boundary and the visible activation reading boundary.
+   * Preserved during automatic reflows (data prepending, container/header resizing)
+   * to keep the reader's view stable without jumping back to section headings.
+   */
+  private savedDisplacement;
+  /** Pending destination anchor awaiting data readiness or DOM rendering. */
+  private pendingDestination;
+  /** Tracks the last fragment processed from route fragment synchronization. */
+  private lastProcessedFragment;
   private target?;
   private timer?;
+  /** Active DOM mutation observer used to retry pending scroll destinations once target anchor elements are inserted. */
+  private retryObserver?;
+  /** Timeout timer bounding the lifetime of destination retries to prevent memory leaks from non-existent anchors. */
+  private retryTimeoutTimer?;
+  /** Handle for the active coalesced requestAnimationFrame layout correction. */
+  private layoutCorrectionFrameId?;
+  /** Cleanups for elements given temporary tabindex="-1" to restore DOM state on blur or directive destruction. */
+  private readonly temporaryTabindexCleanups;
+  /** Target element pending focus transfer after smooth scroll completion. */
+  private pendingFocusTarget?;
+  /** Active scrollend event handler waiting for smooth scroll completion. */
+  private scrollEndHandler?;
+  /** Active EventTarget on which scrollEndHandler was registered. */
+  private scrollEndTarget?;
+  /** Safety timeout preventing a missed scrollend event from retaining a pending focus request. */
+  private focusTimeoutTimer?;
+  /** Element focused when the pending focus transfer was initiated. */
+  private focusInitiator?;
+  /** Flag indicating whether programmatic smooth scrolling animation is actively running. */
+  private isSmoothNavigating;
+  /** Flag indicating a deferred layout preservation request while smooth navigation was active. */
+  private pendingLayoutPreservation;
+  /** Active scrollend event handler for programmatic smooth navigation settlement. */
+  private smoothNavEndHandler?;
+  /** Event target on which smoothNavEndHandler was registered. */
+  private smoothNavTarget?;
+  /** Safety timeout timer preventing smooth navigation lock if scrollend does not fire. */
+  private smoothNavTimeoutTimer?;
   constructor();
+  /**
+   * Determines whether the active router navigation was initiated internally by scroll-spy.
+   */
+  private isInternalNavigation;
   /**
    * Explicitly scrolls the viewport to the target anchor identifier.
    *
    * @param anchor - Target anchor ID (with or without leading `#`).
-   * @param options - Per-call scroll overrides (behavior, top offset, ignoreWhenInView).
+   * @param options - Per-call scroll overrides (behavior, top offset, ignoreWhenInView, focus).
    * @returns `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.
    */
   scrollTo(anchor: string, options?: MagicScrollToOptions): boolean;
+  /**
+   * Attempts to execute navigation to the pending destination anchor.
+   *
+   * @param behavior - The scroll animation behavior to apply (`instant` or `smooth`).
+   * @returns `true` if the target anchor element was found in the DOM and scrolling was initiated; `false` otherwise.
+   *
+   * @remarks
+   * If execution succeeds, `pendingDestination` is cleared and active retry observers/timers are canceled.
+   * If target elements are not yet present in the DOM (e.g. data is ready before DOM elements render),
+   * `pendingDestination` remains queued so subsequent DOM updates can retry.
+   */
+  private tryExecutePendingDestination;
+  /**
+   * Schedules a bounded retry mechanism observing DOM additions and attribute modifications
+   * within the directive host to re-attempt scrolling when the target anchor element is rendered.
+   *
+   * @remarks
+   * Asynchronous rendering cycles (such as Angular `@for` loops, `@if` blocks, or asynchronous child components)
+   * often resolve data/signals (`scrollSource`) before child DOM anchor nodes are attached to the document.
+   *
+   * To prevent dropped navigations without polling or manual timeouts, a `MutationObserver` watches host mutations
+   * for child node insertions and anchor attribute modifications (`id`, `data-scroll-anchor`). When DOM mutations
+   * occur and the scroll source is ready, destination execution is re-attempted.
+   *
+   * A bounded 1000ms safety timeout safeguards against indefinite observation if a non-existent anchor ID was requested.
+   */
+  private scheduleDestinationRetry;
+  /**
+   * Disconnects the DOM mutation observer and clears active retry timers.
+   *
+   * @remarks
+   * Invoked whenever destination execution succeeds, a user interrupts navigation (via scroll, touch, or keyboard),
+   * an explicit navigation supersedes the pending target, or the directive is destroyed.
+   */
+  private cancelDestinationRetry;
   /**
    * Queries and returns all eligible scroll anchor elements belonging strictly to this directive instance.
    *
    * @remarks
-   * Anchors must possess a non-empty `id` and either match the configured `anchorPrefix` or contain
-   * the `data-scroll-anchor` attribute. The `closest('[magicScroll]') === this.host` check prevents
-   * nested or parent `magicScroll` directive instances from capturing child anchors across boundaries.
+   * Anchors must possess a non-empty `id` and satisfy the configured selection strategy:
+   * - In `'explicit'` mode: Only elements marked with the `data-scroll-anchor` attribute participate,
+   *   ignoring prefix rules and excluding generated component/form IDs.
+   * - In `'all'` mode (default): Elements matching any configured `anchorPrefixes` OR bearing
+   *   the `data-scroll-anchor` attribute participate.
+   *
+   * The `closest('[magicScroll]') === this.host` check guarantees that nested child regions
+   * retain strict isolation over their own anchors and do not leak across region boundaries.
    */
   private anchors;
   /**
@@ -257,15 +383,39 @@ export declare class MagicScrollDirective {
    */
   private execute;
   /**
-   * Realigns the viewport instantly to preserve position during asynchronous data updates
-   * or container / header dimension changes.
+   * Determines whether the requested navigation will change the scroll position after clamping.
+   */
+  private willScroll;
+  /**
+   * Resolves whether the browser will animate this request, including `auto` with smooth CSS behavior.
+   */
+  private hasSmoothScrollBehavior;
+  /**
+   * Realigns the viewport instantly to preserve anchor-relative reading position
+   * during asynchronous data updates, container resizes, or header dimension changes.
    *
    * @remarks
-   * Targets `liveAnchor` (the real-time visible section) rather than `fragment` (the debounced URL fragment)
-   * to ensure rapid data or layout shifts during continuous scrolling maintain the user's active view
-   * rather than jumping back to a stale URL anchor.
+   * Targets `liveAnchor` (the real-time visible section) and restores `savedDisplacement`
+   * (the pixel offset between the anchor's top and the container's top boundary).
+   * If native browser scroll anchoring (`overflow-anchor`) has already adjusted scroll position,
+   * delta computes to 0, inherently avoiding double-compensation.
+   * If the active anchor element is no longer present in the DOM, realignment is skipped deterministically.
    */
   private preserve;
+  /**
+   * Schedules a coalesced layout realignment via requestAnimationFrame.
+   * Batches multiple synchronous or rapid descendant reflows into a single correction per frame.
+   */
+  private scheduleLayoutPreservation;
+  /**
+   * Cancels any pending requestAnimationFrame layout realignment.
+   */
+  private cancelLayoutPreservation;
+  /**
+   * Captures and stores the pixel displacement between the active anchor's top edge
+   * and the visible activation reading boundary (`containerTop + topOffset`).
+   */
+  private updateSavedDisplacement;
   /**
    * Updates target container references and re-binds passive event listeners whenever
    * the scroll container shifts dynamically.
@@ -275,21 +425,39 @@ export declare class MagicScrollDirective {
    * Attaches passive scroll, gesture, and keyboard listeners to track user intent and scroll motion.
    */
   private attachListeners;
+  /**
+   * Applies DOM focus safely to the target anchor element using `preventScroll: true`.
+   * Automatically assigns a temporary `tabindex="-1"` to non-focusable landmark containers
+   * and registers a one-time blur listener to cleanly remove it when focus shifts away.
+   */
+  private applyFocus;
+  /**
+   * Schedules focus transfer to execute upon smooth scroll completion (`scrollend`).
+   */
+  private scheduleFocus;
+  /**
+   * Cancels any pending scheduled focus transfer and unregisters the `scrollend` listener.
+   */
+  private cancelScheduledFocus;
   /**
    * Detaches all registered event listeners to ensure clean teardown without memory leaks.
    */
   private detachListeners;
   /**
    * Intercepts manual user gestures (`wheel`, `touchstart`, `touchmove`) to flag user interaction
-   * and cancel delayed initial restorations prior to data readiness.
+   * and cancel delayed restorations prior to data readiness.
    */
   private readonly onUserIntent;
   /**
    * Intercepts navigation keyboard events (`ArrowUp`, `ArrowDown`, `PageUp`, `PageDown`, `Home`, `End`, `Space`).
-   * Cancels pending initial restoration when navigation occurs within the relevant scroll context
+   * Cancels pending restoration when navigation occurs within the relevant scroll context
    * while safely ignoring interactions on editable input elements.
    */
   private readonly onKeyDown;
+  private readonly onFocusScrollIntent;
+  private readonly onFocusIn;
+  private readonly onFocusTransferKeyDown;
+  private readonly onFocusTransferPointerDown;
   /**
    * Handles scroll events by immediately updating `liveAnchor` for position preservation,
    * while debouncing `scrollRevision` increments to update the browser URL fragment without thrashing history.
@@ -299,6 +467,20 @@ export declare class MagicScrollDirective {
    * Handles window resize events by re-evaluating targets and optionally realigning the active anchor.
    */
   private readonly onResize;
+  /**
+   * Initiates smooth programmatic navigation protection, deferring layout realignments
+   * and intermediate anchor snapping until scrolling completes (`scrollend`) or times out.
+   */
+  private beginSmoothNavigation;
+  /**
+   * Concludes smooth programmatic navigation, updating the reading position
+   * at the settled destination and processing any deferred layout preservation requests.
+   */
+  private endSmoothNavigation;
+  /**
+   * Cancels active smooth navigation tracking and clears timeout timers and scrollend listeners.
+   */
+  private cancelSmoothNavigation;
   static ɵfac: i0.ɵɵFactoryDeclaration<MagicScrollDirective, never>;
   static ɵdir: i0.ɵɵDirectiveDeclaration<MagicScrollDirective, "[magicScroll]", ["magicScroll"], {
     "scrollSource": {
@@ -330,4 +512,4 @@ export declare class ScrollAnchorDirective {
     };
   }, {}, never, never, true, never>;
 }
-export type { MagicScrollOptions, MagicScrollToOptions, ScrollDataSource, ScrollResource, ScrollSource };
+export type { AnchorSelectionMode, MagicScrollOptions, MagicScrollToOptions, ScrollDataSource, ScrollResource, ScrollSource };