@real-router/angular 0.10.0 → 0.11.0

package/dist/types/real-router-angular.d.ts

@@ -35,6 +35,65 @@ interface ScrollRestorationOptions {
     storageKey?: string | undefined;
 }
 
+/**
+ * Router-coordinated scroll spy (#575).
+ *
+ * On `IntersectionObserver` notifications the utility picks the topmost
+ * visible anchor inside the configured scroll container and emits a forced
+ * same-route transition with `{ hash, replace: true, force: true, hashChange:
+ * true }` through `router.navigate(...)`. The URL plugin
+ * (`@real-router/browser-plugin` or `@real-router/navigation-plugin`) updates
+ * `state.context.url.hash` so sibling hash-aware `<Link hash>` re-highlights
+ * via the standard `createActiveRouteSource` pipeline.
+ *
+ * **Anti-flicker gates** (RFC §5.2):
+ * 1. `getTransitionSource(router).getSnapshot().isTransitioning` — skip emits
+ *    while a transition is in-flight (re-entrant lock).
+ * 2. `coolingDown` — set on a user-driven hash transition (e.g. `<Link hash>`
+ *    click + smooth `scrollIntoView`). Cleared on `scrollend` or after a
+ *    500ms safety timeout. Spy's own emits are excluded via the synchronous
+ *    `selfEmitting` flag — required so the spy doesn't rate-limit itself.
+ *
+ * **Self-healing** (RFC §7.3): if the initial URL contains a hash without a
+ * matching `id` (e.g. `/page#nonexistent`), the first IO event emitted right
+ * after observe()-ing picks the topmost real anchor and corrects the URL.
+ *
+ * **Hash-only transition pipeline cost** (RFC §5.3): for same-route same-
+ * params hash-only navigations, `getTransitionPath` returns empty
+ * `toDeactivate` / `toActivate` arrays, so `runGuards` is a no-op. The only
+ * work is the URL plugin's `onTransitionSuccess` write and the
+ * `getTransitionSource` flip — cheap.
+ *
+ * **Architecture**: decomposed into 4 private subsystem closure factories
+ * (`createUrlPluginDetector`, `createCooldown`, `createDebouncer`,
+ * `createObserverPair`). The main `createScrollSpy` wires them together
+ * around the shared `silenced` / `destroyed` / `selfEmitting` flags and the
+ * `flush()` emit logic. Each subsystem owns its state + cleanup; `destroy()`
+ * delegates to each. See section banners below.
+ *
+ * @returns A `ScrollSpy` handle whose `destroy()` is idempotent.
+ */
+interface ScrollSpyOptions {
+    /**
+     * CSS selector for anchor candidates. Empty string `""` or `undefined`
+     * disables the spy (returns a NOOP handle). Common values:
+     * `"[id]"`, `"[id]:is(h1,h2,h3)"`, `"section[id]"`.
+     */
+    selector: string;
+    /**
+     * `IntersectionObserver` `rootMargin`. Default
+     * `"-20% 0px -60% 0px"` — an anchor is considered "active" once it crosses
+     * into the top 20 % of the viewport (or scroll container).
+     */
+    rootMargin?: string | undefined;
+    /**
+     * Lazy getter for the scrollable container. Resolved on every event.
+     * `null` (or missing getter) falls back to the window viewport
+     * (`root: null` on the `IntersectionObserver`).
+     */
+    scrollContainer?: (() => HTMLElement | null) | undefined;
+}
+
 interface RouteSignals<P extends Params = Params> {
     readonly routeState: Signal<RouteSnapshot<P>>;
     readonly navigator: Navigator;
@@ -49,6 +108,7 @@ declare const NAVIGATOR: InjectionToken<Navigator>;
 declare const ROUTE: InjectionToken<RouteSignals<_real_router_types.Params>>;
 interface RealRouterOptions {
     scrollRestoration?: ScrollRestorationOptions;
+    scrollSpy?: ScrollSpyOptions;
     viewTransitions?: boolean;
 }
 declare function provideRealRouter(router: Router, options?: RealRouterOptions): EnvironmentProviders;
@@ -119,6 +179,8 @@ interface RealRouterFactoryOptions<TDeps extends DefaultDependencies = DefaultDe
     deps?: RequestDepsFactory<TDeps>;
     /** Optional scroll restoration — same semantics as `provideRealRouter`. */
     scrollRestoration?: ScrollRestorationOptions;
+    /** Optional scroll spy — same semantics as `provideRealRouter`. */
+    scrollSpy?: ScrollSpyOptions;
     /** Optional view transitions — same semantics as `provideRealRouter`. */
     viewTransitions?: boolean;
 }

package/dist/types/real-router-angular.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"real-router-angular.d.ts","sources":["../../src/dom-utils/scroll-restore.ts","../../src/types.ts","../../src/providers.ts","../../src/providersFactory.ts","../../src/sourceToSignal.ts","../../src/functions/injectRouter.ts","../../src/functions/injectNavigator.ts","../../src/functions/injectRoute.ts","../../src/functions/injectRouteNode.ts","../../src/functions/injectRouteUtils.ts","../../src/functions/injectRouterTransition.ts","../../src/functions/injectIsActiveRoute.ts","../../src/functions/injectRouteExit.ts","../../src/functions/injectRouteEnter.ts","../../src/directives/RouteMatch.ts","../../src/directives/RouteNotFound.ts","../../src/directives/RouteSelf.ts","../../src/components/RouteView.ts","../../src/components/RouterErrorBoundary.ts","../../src/components/NavigationAnnouncer.ts","../../src/directives/RealLink.ts","../../src/directives/RealLinkActive.ts"],"mappings":"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","names":[]}
+{"version":3,"file":"real-router-angular.d.ts","sources":["../../src/dom-utils/scroll-restore.ts","../../src/dom-utils/scroll-spy.ts","../../src/types.ts","../../src/providers.ts","../../src/providersFactory.ts","../../src/sourceToSignal.ts","../../src/functions/injectRouter.ts","../../src/functions/injectNavigator.ts","../../src/functions/injectRoute.ts","../../src/functions/injectRouteNode.ts","../../src/functions/injectRouteUtils.ts","../../src/functions/injectRouterTransition.ts","../../src/functions/injectIsActiveRoute.ts","../../src/functions/injectRouteExit.ts","../../src/functions/injectRouteEnter.ts","../../src/directives/RouteMatch.ts","../../src/directives/RouteNotFound.ts","../../src/directives/RouteSelf.ts","../../src/components/RouteView.ts","../../src/components/RouterErrorBoundary.ts","../../src/components/NavigationAnnouncer.ts","../../src/directives/RealLink.ts","../../src/directives/RealLinkActive.ts"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/angular",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "commonjs",
   "description": "Angular 21 integration for Real-Router",
   "exports": {
@@ -41,7 +41,7 @@
   "license": "MIT",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.54.1",
+    "@real-router/core": "^0.54.6",
     "@real-router/route-utils": "^0.2.2",
     "@real-router/sources": "^0.8.3"
   },

package/src/dom-utils/index.ts

@@ -4,6 +4,8 @@ export { createRouteAnnouncer } from "./route-announcer";
 
 export { createScrollRestoration } from "./scroll-restore";
 
+export { createScrollSpy } from "./scroll-spy";
+
 export { createViewTransitions } from "./view-transitions";
 
 export {
@@ -22,6 +24,8 @@ export type {
   ScrollRestorationMode,
 } from "./scroll-restore";
 
+export type { ScrollSpy, ScrollSpyOptions } from "./scroll-spy";
+
 export type { DirectionTracker } from "./direction-tracker";
 
 export type { ViewTransitions } from "./view-transitions";

package/src/dom-utils/scroll-restore.ts

@@ -2,6 +2,14 @@ import type { Router, State } from "@real-router/core";
 
 const DEFAULT_STORAGE_KEY = "real-router:scroll";
 
+// Bounded retry budget for resolving a late-mounting scroll container on the
+// restore path. A per-route container (e.g. an `overflow:auto` div rendered
+// only on one route) can be committed to the DOM a few frames after the
+// navigation settles — heavier routes paint later than the subscribe's rAF.
+// ~10 frames (≈160ms at 60fps) comfortably covers a React commit of a large
+// route without being perceptible. See the doc-block on `restorePos`.
+const RESTORE_RETRY_FRAMES = 10;
+
 const NOOP_INSTANCE: { destroy: () => void } = Object.freeze({
   destroy: () => {
     /* no-op */
@@ -135,6 +143,74 @@ export function createScrollRestoration(
     }
   };
 
+  // Restore path (back / traverse / reload). Unlike `writePos`, this tolerates a
+  // scroll container that both MOUNTS and LAYS OUT a few frames AFTER the
+  // navigation settles.
+  //
+  // The capture-side `readPos` always runs against an already-mounted DOM (the
+  // route being left). On restore the target route — and its container — is
+  // still being committed by the view layer. The subscribe callback schedules a
+  // single rAF; for a heavy route (e.g. a long virtual list) the framework's
+  // commit can land AFTER that frame. Two distinct failures follow, each losing
+  // the saved position (Scenario 6 e2e, reproduced under CI's slower runner):
+  //
+  //   1. Container not mounted yet → `getContainer()` is `null`, the scroll
+  //      silently falls back to `window`, which on a container-only route has
+  //      nothing to scroll.
+  //   2. Container mounted but its content not laid out yet → `scrollHeight`
+  //      is still small, so a single `scrollTo({ top })` clamps short of the
+  //      saved position and never re-applies once layout grows.
+  //
+  // With no `scrollContainer` getter the target is always `window`, present
+  // from the first frame — restore in a single shot (unchanged behaviour). When
+  // a getter is configured we cannot tell "this route legitimately uses window"
+  // from "the container is still mounting", so re-apply the scroll on every
+  // frame for a bounded budget: window as a fallback while the container is
+  // absent (harmless clamp on container routes), the container itself once it
+  // appears. For instant restores we stop early the moment the position sticks;
+  // smooth restores animate asynchronously, so they run the full budget. The
+  // frame budget is the hard backstop against an unreachable target (saved
+  // position taller than the restored content).
+  const restorePos = (top: number): void => {
+    if (!getContainer) {
+      globalThis.scrollTo({ top, left: 0, behavior });
+
+      return;
+    }
+
+    let frames = 0;
+
+    const attempt = (): void => {
+      if (destroyed) {
+        return;
+      }
+
+      const element = getContainer();
+
+      if (element) {
+        element.scrollTo({ top, left: 0, behavior });
+
+        // Instant restore landed within rounding tolerance → done; no point
+        // re-applying. Smooth restore never matches synchronously, so let it
+        // ride the budget.
+        if (behavior !== "smooth" && Math.abs(element.scrollTop - top) <= 1) {
+          return;
+        }
+      } else {
+        globalThis.scrollTo({ top, left: 0, behavior });
+      }
+
+      if (frames >= RESTORE_RETRY_FRAMES) {
+        return;
+      }
+
+      frames += 1;
+      requestAnimationFrame(attempt);
+    };
+
+    attempt();
+  };
+
   const scrollToHashOrTop = (route: State): void => {
     // URL plugin path (#532): `state.context.url.hash` is the source of truth
     // when one of the URL plugins (browser-plugin / navigation-plugin) is
@@ -240,20 +316,26 @@ export function createScrollRestoration(
         return;
       }
 
-      if (route.transition.replace || nav?.navigationType === "replace") {
-        return;
-      }
-
-      // Both arms are required: `transition.reload` only fires for programmatic
-      // `router.navigate({reload:true})`. F5 under navigation-plugin primes
-      // `nav.navigationType === "reload"` via #531 getActivationType but leaves
-      // opts.reload undefined, so dropping the plugin arm would regress F5
-      // scroll-restore. Same belt-and-suspenders pattern is used for replace
-      // above. Browser-plugin's F5 is not covered (no priming, out of scope).
+      // Restore branches (reload, back/traverse) MUST be evaluated before the
+      // replace-skip below. Since #657 lifted `replace` into TransitionMeta, a
+      // history TRAVERSAL (back/forward) under navigation-plugin carries
+      // `transition.replace === true` — a traversal reuses an existing history
+      // entry, which is replace-shaped at the history level. If the replace-skip
+      // ran first it would swallow every back/forward navigation and restore
+      // would never fire (the Scenario 6 e2e regression). Genuine in-place
+      // replaces (`router.navigate({ replace: true })`, navigateToNotFound) are
+      // not traversals and fall through to the skip below.
+      //
+      // Both arms of each check are required: `transition.reload` only fires for
+      // programmatic `router.navigate({reload:true})`. F5 under navigation-plugin
+      // primes `nav.navigationType === "reload"` via #531 getActivationType but
+      // leaves opts.reload undefined, so dropping the plugin arm would regress F5
+      // scroll-restore. Browser-plugin's F5 is not covered (no priming, out of
+      // scope).
       if (route.transition.reload || nav?.navigationType === "reload") {
         const key = safeKeyOf(route);
 
-        writePos(key === null ? 0 : (loadStore()[key] ?? 0));
+        restorePos(key === null ? 0 : (loadStore()[key] ?? 0));
 
         return;
       }
@@ -261,11 +343,16 @@ export function createScrollRestoration(
       if (nav?.direction === "back" || nav?.navigationType === "traverse") {
         const key = safeKeyOf(route);
 
-        writePos(key === null ? 0 : (loadStore()[key] ?? 0));
+        restorePos(key === null ? 0 : (loadStore()[key] ?? 0));
 
         return;
       }
 
+      // Genuine in-place replace (not a traversal) — leave scroll untouched.
+      if (route.transition.replace || nav?.navigationType === "replace") {
+        return;
+      }
+
       scrollToHashOrTop(route);
     });
   });