@devzwo/ngx-magic-scroll 1.1.0 → 1.1.2

package/docs/migrations/v1.0-to-v1.1.md

@@ -0,0 +1,145 @@
+---
+title: 'Migration Guide: v1.0 to v1.1'
+description: 'Upgrade instructions and code transformations for updating @devzwo/ngx-magic-scroll from v1.0 to v1.1.'
+---
+
+This guide details the new features, behavioral improvements, and recommended configuration updates when upgrading `@devzwo/ngx-magic-scroll` from `1.0.x` to `1.1.0`.
+
+## Overview of Changes
+
+Release `v1.1.0` is backwards-compatible and introduces several opt-in enhancements:
+
+- **Layout Reflow Preservation**: New opt-in `preserveOnLayoutChange` setting to preserve reading positions during asynchronous DOM expansions (such as accordions, dynamic cards, or lazy images).
+- **Exact Displacement Tracking**: Section-relative scroll tracking now maintains intra-section pixel displacement (`displacement`) rather than resetting to the section top.
+- **Accessible Focus Management**: The `scrollTo()` method supports `{ focus: true }` to transfer keyboard focus safely to the scrolled target.
+
+---
+
+## 1. Enabling Layout Reflow Preservation
+
+### Previous Behavior (v1.0.0)
+
+In `v1.0.0`, position preservation was triggered when `scrollSource` data changed or on container window resize events. Asynchronous DOM reflows that did not alter `scrollSource` (e.g. collapsing/expanding an accordion or loading un-dimensioned images) could shift content away from the reader's viewport.
+
+### Updated Configuration (v1.1.0)
+
+Enable `preserveOnLayoutChange: true` in your global provider or directly on the `[magicScroll]` directive to automatically observe DOM layout shifts and maintain the reader's view.
+
+#### Before (v1.0.0)
+
+<!-- recipe-check: migration-v1-0-before.ts -->
+
+```ts
+import { Component } from '@angular/core';
+import {
+  MagicScrollDirective,
+  ScrollAnchorDirective,
+  provideMagicScroll,
+} from '@devzwo/ngx-magic-scroll';
+
+@Component({
+  selector: 'app-migration-sample-before',
+  imports: [MagicScrollDirective, ScrollAnchorDirective],
+  providers: [provideMagicScroll()],
+  template: `
+    <div magicScroll>
+      <section id="section-1" scrollAnchor>
+        <h2>Section 1</h2>
+      </section>
+      <section id="section-2" scrollAnchor>
+        <h2>Section 2</h2>
+      </section>
+    </div>
+  `,
+})
+export class MigrationSampleBeforeComponent {}
+```
+
+#### After (v1.1.0)
+
+<!-- recipe-check: migration-v1-1-after.ts -->
+
+```ts
+import { Component } from '@angular/core';
+import {
+  MagicScrollDirective,
+  ScrollAnchorDirective,
+  provideMagicScroll,
+} from '@devzwo/ngx-magic-scroll';
+
+@Component({
+  selector: 'app-migration-sample-after',
+  imports: [MagicScrollDirective, ScrollAnchorDirective],
+  providers: [
+    provideMagicScroll({
+      preserveOnLayoutChange: true,
+    }),
+  ],
+  template: `
+    <div magicScroll [scrollOptions]="{ preserveOnLayoutChange: true }">
+      <section id="section-1" scrollAnchor>
+        <h2>Section 1</h2>
+      </section>
+      <section id="section-2" scrollAnchor>
+        <h2>Section 2</h2>
+      </section>
+    </div>
+  `,
+})
+export class MigrationSampleAfterComponent {}
+```
+
+---
+
+## 2. Accessible Focus Navigation
+
+### Previous Implementation (v1.0.0)
+
+In `v1.0.0`, programmatic navigation via `scrollTo('section-id')` scrolled the viewport but did not alter keyboard DOM focus. Developers had to manually manage element focus and `tabindex` attributes.
+
+### Updated Implementation (v1.1.0)
+
+Pass `{ focus: true }` in `scrollTo()`. The directive automatically manages temporary `tabindex="-1"` attributes on non-focusable elements and waits for smooth scrolling to complete (`scrollend`) before transferring focus:
+
+<!-- recipe-check: migration-v1-1-focus.ts -->
+
+```ts
+import { Component, viewChild } from '@angular/core';
+import { MagicScrollDirective, provideMagicScroll } from '@devzwo/ngx-magic-scroll';
+
+@Component({
+  selector: 'app-migration-focus-sample',
+  imports: [MagicScrollDirective],
+  providers: [provideMagicScroll()],
+  template: `
+    <nav>
+      <button (click)="navigateToAnchor('section-2')">Jump to Section 2</button>
+    </nav>
+    <div magicScroll #scroll="magicScroll">
+      <section id="section-1">
+        <h2>Section 1</h2>
+      </section>
+      <section id="section-2">
+        <h2>Section 2</h2>
+      </section>
+    </div>
+  `,
+})
+export class MigrationFocusSampleComponent {
+  readonly scroll = viewChild.required<MagicScrollDirective>('scroll');
+
+  navigateToAnchor(targetId: string): void {
+    this.scroll().scrollTo(targetId, {
+      behavior: 'smooth',
+      focus: true,
+    });
+  }
+}
+```
+
+---
+
+## 3. Deprecations and Breaking Changes
+
+- **Breaking Changes**: None. All existing v1.0.0 configurations and APIs remain functional without modification.
+- **Deprecations**: None in this release.

package/docs/recipes/material-drawer.md

@@ -0,0 +1,99 @@
+---
+title: Angular Material Drawer
+description: Scroll within mat-drawer-content and preserve anchors across layout changes.
+---
+
+## Goal
+
+Place a section list inside Angular Material's drawer layout, with navigation in the drawer and scrolling confined to its content area.
+
+## Solution
+
+Use this in an application that already has Angular Material and its theme configured, and provides Angular Router. The library requires no Material-specific adapter.
+
+<!-- recipe-check: material-drawer-0.ts -->
+
+```ts
+import { Component } from '@angular/core';
+import { MatSidenavModule } from '@angular/material/sidenav';
+import { MagicScrollDirective } from '@devzwo/ngx-magic-scroll';
+
+@Component({
+  selector: 'app-drawer-projects',
+  imports: [MatSidenavModule, MagicScrollDirective],
+  template: `
+    <button (click)="drawer.toggle()">Toggle navigation</button>
+    <mat-drawer-container class="shell">
+      <mat-drawer #drawer mode="side" opened>
+        <nav aria-label="Projects">
+          @for (project of projects; track project.id) {
+            <button (click)="scroll.scrollTo('project-' + project.id)">
+              {{ project.name }}
+            </button>
+          }
+        </nav>
+      </mat-drawer>
+
+      <mat-drawer-content>
+        <div magicScroll #scroll="magicScroll">
+          @for (project of projects; track project.id) {
+            <section [id]="'project-' + project.id">
+              <h2>{{ project.name }}</h2>
+              <details>
+                <summary>Project description</summary>
+                <p>Additional content changes this section's height.</p>
+              </details>
+            </section>
+          }
+        </div>
+      </mat-drawer-content>
+    </mat-drawer-container>
+  `,
+  styles: `
+    .shell {
+      height: 70vh;
+    }
+    mat-drawer {
+      width: 180px;
+    }
+    mat-drawer-content {
+      overflow-anchor: none;
+    }
+    nav {
+      display: flex;
+      flex-direction: column;
+    }
+    section {
+      min-height: 50vh;
+      padding: 16px;
+    }
+  `,
+})
+export class DrawerProjectsComponent {
+  readonly projects = Array.from({ length: 8 }, (_, index) => ({
+    id: index + 1,
+    name: `Project ${index + 1}`,
+  }));
+}
+```
+
+The constrained container height makes Material's `mat-drawer-content` scrollable. The directive detects that ancestor automatically. For a plain HTML layout, the same principle is a constrained ancestor with `overflow-y: auto`, or a scrollable `magicScroll` host itself.
+
+The drawer's navigation is outside the anchor region. Nested `magicScroll` regions own their own descendant anchors; use unique IDs throughout the document. Regions share the page's single URL fragment, so independent containers do not have separate URL state.
+
+`overflow-anchor: none` disables native browser scroll anchoring in this content area so it does not compete with the library's anchor corrections.
+
+### Data and layout changes
+
+For an asynchronous list, add `[scrollSource]="projects"` to the region and render the source's values in both lists. Later ready data changes can preserve the current anchor with `restoreOnDataChange`; window resizing and measured header changes use `preserveOnResize`.
+
+The library does not observe every DOM size change. A drawer toggle or expanded section can change layout without a window resize or source update. If your application needs an explicit realignment after such an interaction, call `scroll.scrollTo(scroll.activeAnchor(), { behavior: 'instant' })` once the layout has settled, after checking that the anchor is non-null. Decide whether that movement fits the interaction before adding it.
+
+## Scope and related recipes
+
+This recipe isolates container layout. It does not implement filtering, pagination or data loading.
+
+- [Angular rxResource](./rx-resource.md) or [TanStack Query](./tanstack-query.md) supplies asynchronous cards, as in the drawer demo.
+- [Paginated lists](./paginated-lists.md) adds loading and restoration of additional pages.
+- [Return to a list](./return-to-list.md) adds detail routes and return links.
+- [Sticky master–detail](./sticky-master-detail.md) covers document scrolling and measured headers.

package/docs/recipes/ngrx-signal-store.md

@@ -0,0 +1,132 @@
+---
+title: NgRx Signal Store
+description: Adapt NgRx store signals into a scroll data source.
+---
+
+## Goal
+
+Use the data and loading state of an existing `@ngrx/signals` store for anchor restoration, without moving data fetching into the component.
+
+## Solution
+
+This follows the portfolio-store pattern used in zwoPRO: the store owns projects, loading and errors. Install `@ngrx/signals` in your application if you do not already use it. The library itself has no NgRx dependency.
+
+A minimal `projects.store.ts` distinguishes data that has not loaded yet from a successful empty result:
+
+<!-- recipe-check: projects.store.ts -->
+
+```ts
+import { patchState, signalStore, withMethods, withState } from '@ngrx/signals';
+
+interface Project {
+  id: number;
+  name: string;
+}
+
+interface ProjectsState {
+  projects: Project[] | undefined;
+  loading: boolean;
+  error: string | null;
+}
+
+const initialState: ProjectsState = {
+  projects: undefined,
+  loading: false,
+  error: null,
+};
+
+export const ProjectsStore = signalStore(
+  withState(initialState),
+  withMethods((store) => ({
+    async load() {
+      patchState(store, { loading: true, error: null });
+      try {
+        const response = await fetch('/api/projects');
+        if (!response.ok) throw new Error('Could not load projects.');
+        const projects: Project[] = await response.json();
+        patchState(store, { projects, loading: false });
+      } catch {
+        patchState(store, { loading: false, error: 'Could not load projects.' });
+      }
+    },
+  })),
+);
+```
+
+Use your existing API service or `rxMethod` implementation instead of `fetch` if the store already handles requests. Here `/api/projects` is an application endpoint returning a project array.
+
+In `store-projects.component.ts`, provide the store and map its signals to the neutral `ScrollDataSource` contract:
+
+<!-- recipe-check: store-projects.component.ts -->
+
+```ts
+import { Component, inject } from '@angular/core';
+import { MagicScrollDirective, ScrollDataSource } from '@devzwo/ngx-magic-scroll';
+import { ProjectsStore } from './projects.store';
+
+@Component({
+  selector: 'app-store-projects',
+  imports: [MagicScrollDirective],
+  providers: [ProjectsStore],
+  template: `
+    <button [disabled]="store.loading()" (click)="store.load()">Reload</button>
+    <div magicScroll [scrollSource]="scrollSource">
+      @if (store.loading()) {
+        <p role="status">Loading projects…</p>
+      }
+      @if (store.error()) {
+        <p role="alert">{{ store.error() }}</p>
+      }
+      @if (store.projects()?.length === 0) {
+        <p>No projects.</p>
+      }
+      @for (project of store.projects(); track project.id) {
+        <section [id]="'project-' + project.id">
+          <h2>{{ project.name }}</h2>
+        </section>
+      }
+    </div>
+  `,
+  styles: `
+    section {
+      min-height: 70vh;
+    }
+  `,
+})
+export class StoreProjectsComponent {
+  readonly store = inject(ProjectsStore);
+  readonly scrollSource: ScrollDataSource = {
+    data: () => this.store.projects(),
+    isLoading: () => this.store.loading(),
+  };
+
+  constructor() {
+    void this.store.load();
+  }
+}
+```
+
+The getters must read signals so changes are tracked. Adapt the names to your store; for a filtered view, `data()` should return the collection actually rendered by the template. An NgRx store with fields called `projects` and `loading` does not automatically satisfy the `data()`/`isLoading()` contract.
+
+### If your store starts with an empty array
+
+`[]` is a ready value. If the store initially contains `projects: []` and `loading: false`, add a `loaded` signal that becomes true only after a successful request. Gate the source's data:
+
+```ts
+readonly scrollSource: ScrollDataSource = {
+  data: () => this.store.loaded() ? this.store.projects() : undefined,
+  isLoading: () => this.store.loading(),
+};
+```
+
+This is an alternative for an existing store; it requires that store to expose `loaded`. It prevents an idle or failed first request from consuming initial restoration. Do not use array length to detect successful loading, because an empty response is valid.
+
+## Scope and related recipes
+
+This recipe demonstrates the adapter and initial readiness. Store lifetime, caching, concurrency and filtering remain application responsibilities; use an existing root-provided store without adding a second component provider if you want to retain its state between pages.
+
+- [Return to a list](./return-to-list.md) covers route fragments and detail navigation.
+- [Sticky master–detail](./sticky-master-detail.md) combines the source with a portfolio layout.
+- [Paginated lists](./paginated-lists.md) explains saved load ranges and later data corrections.
+
+See the [NgRx Signal Store guide](https://ngrx.io/guide/signals/signal-store) for store design and additional features.

package/docs/recipes/paginated-lists.md

@@ -0,0 +1,206 @@
+---
+title: Paginated lists
+description: Restore the loaded range before restoring an anchor, with rxResource or TanStack Infinite Query.
+---
+
+## Goal
+
+Let users load more items, open a detail page and return to an item beyond the first page. Restore both the loaded range and the anchor after browser Back or reload.
+
+## Solution: restore data before scrolling
+
+The fragment identifies the item; a query parameter records how much data must be available. For example, `/projects?count=16#project-12` means that the application loads the first 16 items before the directive attempts initial restoration.
+
+This compact version of the drawer demo simulates a server that returns the requested range:
+
+<!-- recipe-check: paginated-lists-0.ts -->
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { rxResource } from '@angular/core/rxjs-interop';
+import { ActivatedRoute, Router } from '@angular/router';
+import { delay, of } from 'rxjs';
+import { MagicScrollDirective } from '@devzwo/ngx-magic-scroll';
+
+@Component({
+  selector: 'app-paginated-projects',
+  imports: [MagicScrollDirective],
+  template: `
+    <button [disabled]="projects.isLoading() || count() >= 100" (click)="loadMore()">
+      Load more
+    </button>
+    <div magicScroll [scrollSource]="projects">
+      @if (projects.isLoading()) {
+        <p role="status">Loading projects…</p>
+      }
+      @if (projects.error()) {
+        <p role="alert">Could not load projects.</p>
+        <button (click)="projects.reload()">Retry</button>
+      }
+      @if (projects.hasValue()) {
+        @for (project of projects.value(); track project.id) {
+          <section [id]="'project-' + project.id">
+            <h2>{{ project.name }}</h2>
+          </section>
+        }
+      }
+    </div>
+  `,
+  styles: `
+    section {
+      min-height: 50vh;
+    }
+  `,
+})
+export class PaginatedProjectsComponent {
+  private readonly route = inject(ActivatedRoute);
+  private readonly router = inject(Router);
+  readonly count = signal(
+    Math.max(8, Math.min(100, Number(this.route.snapshot.queryParamMap.get('count')) || 8)),
+  );
+  readonly projects = rxResource({
+    params: () => this.count(),
+    stream: ({ params: count }) =>
+      of(
+        Array.from({ length: count }, (_, index) => ({
+          id: index + 1,
+          name: `Project ${index + 1}`,
+        })),
+      ).pipe(delay(300)),
+  });
+
+  async loadMore() {
+    this.count.update((count) => Math.min(100, count + 8));
+    await this.router.navigate([], {
+      relativeTo: this.route,
+      queryParams: { count: this.count() },
+      queryParamsHandling: 'merge',
+      preserveFragment: true,
+      replaceUrl: true,
+    });
+  }
+}
+```
+
+Replace the simulated request with an Observable API call that returns the first `count` items. If your backend only exposes individual pages, load the required initial pages in the application's data layer and expose the combined result as ready **after all those pages have loaded**.
+
+The source is initially loading, so the initial fragment is not consumed by a partial first page. On subsequent updates, `restoreOnDataChange` keeps the current anchor's top edge visible when needed. Stable item IDs are essential: inserting items above an anchor should not change that anchor's ID.
+
+Use `preserveFragment: true` when persisting the loading range. `replaceUrl: true` avoids adding a history entry for each load-more operation. Preserve the count parameter on detail links and return links, as described in [Return to a list](./return-to-list.md).
+
+### Choose the correction policy
+
+The default preserves the current anchor after ready data changes. To let the user's viewport move naturally instead, disable data corrections for the region:
+
+```html
+<div magicScroll [scrollSource]="projects" [scrollOptions]="{ restoreOnDataChange: false }">
+  <!-- Render the loaded collection here. -->
+</div>
+```
+
+Appending items does not automatically scroll to the newly added item. If you want that interaction, wait for its DOM to render and then call `scrollTo()` deliberately. The source's readiness is used for automatic restoration; it does not queue explicit calls to missing targets.
+
+## TanStack Infinite Query
+
+For `@tanstack/angular-query-experimental`, keep the same URL contract and pass the Infinite Query directly. Configure the query client as shown in [TanStack Query](./tanstack-query.md).
+
+This component expects an endpoint accepting `offset` and `limit` and returning a project array. It requests the saved range in the first fetch, then adds eight items per subsequent page:
+
+<!-- recipe-check: paginated-lists-1.ts -->
+
+```ts
+import { Component, computed, inject } from '@angular/core';
+import { ActivatedRoute, Router } from '@angular/router';
+import { injectInfiniteQuery } from '@tanstack/angular-query-experimental';
+import { MagicScrollDirective } from '@devzwo/ngx-magic-scroll';
+
+interface Project {
+  id: number;
+  name: string;
+}
+
+@Component({
+  selector: 'app-infinite-projects',
+  imports: [MagicScrollDirective],
+  template: `
+    <div magicScroll [scrollSource]="projects">
+      @if (projects.isLoading()) {
+        <p role="status">Loading projects…</p>
+      }
+      @if (projects.isError()) {
+        <p role="alert">Could not load projects.</p>
+        <button (click)="projects.refetch()">Retry</button>
+      }
+      @for (project of items(); track project.id) {
+        <section [id]="'project-' + project.id">
+          <h2>{{ project.name }}</h2>
+        </section>
+      }
+    </div>
+    <button [disabled]="!projects.hasNextPage() || projects.isFetching()" (click)="loadMore()">
+      {{ projects.isFetchingNextPage() ? 'Loading…' : 'Load more' }}
+    </button>
+  `,
+  styles: `
+    section {
+      min-height: 50vh;
+    }
+  `,
+})
+export class InfiniteProjectsComponent {
+  private readonly route = inject(ActivatedRoute);
+  private readonly router = inject(Router);
+  private readonly pageSize = 8;
+  private readonly initialCount = Math.max(
+    this.pageSize,
+    Math.min(100, Number(this.route.snapshot.queryParamMap.get('count')) || this.pageSize),
+  );
+  readonly projects = injectInfiniteQuery(() => ({
+    queryKey: ['projects', 'infinite', this.initialCount],
+    initialPageParam: 0,
+    queryFn: async ({ pageParam }): Promise<Project[]> => {
+      const limit = pageParam === 0 ? this.initialCount : Math.min(this.pageSize, 100 - pageParam);
+      const response = await fetch(`/api/projects?offset=${pageParam}&limit=${limit}`);
+      if (!response.ok) throw new Error('Could not load projects.');
+      return response.json();
+    },
+    getNextPageParam: (lastPage, pages, lastOffset) => {
+      const requested =
+        lastOffset === 0 ? this.initialCount : Math.min(this.pageSize, 100 - lastOffset);
+      const total = pages.reduce((count, page) => count + page.length, 0);
+      return lastPage.length === requested && total < 100 ? total : undefined;
+    },
+  }));
+  readonly items = computed(() => this.projects.data()?.pages.flat() ?? []);
+
+  async loadMore() {
+    if (!this.projects.hasNextPage() || this.projects.isFetching()) return;
+    const result = await this.projects.fetchNextPage();
+    if (result.isError) return;
+    const count = result.data?.pages.reduce((total, page) => total + page.length, 0);
+    if (count === undefined) return;
+    await this.router.navigate([], {
+      relativeTo: this.route,
+      queryParams: { count },
+      queryParamsHandling: 'merge',
+      preserveFragment: true,
+      replaceUrl: true,
+    });
+  }
+}
+```
+
+The source returns the query's page structure; the template renders the flattened collection. Both read the same reactive query data. `initialCount` is captured once so persisting a new count does not change the running query's cache key and restart it. It belongs in the cache key because it changes the initial request's size.
+
+This mirrors the HNE frontend's strategy of requesting the previously loaded range first. The example assumes deterministic ordering, an offset-based API and a short response indicating the end of the list. This example caps the loaded range at 100 items; adapt that limit and the backend contract to your application. Cursor APIs need a different restoration strategy, and cached or removed pages must still contain the target before initial readiness.
+
+See [TanStack's Infinite Queries guide](https://tanstack.com/query/latest/docs/framework/angular/guides/infinite-queries) for page state and fetching APIs.
+
+## Scope and related recipes
+
+The library does not fetch missing pages, persist filters or virtualize the list. A target missing from the first ready render is not automatically searched for in later pages. Restore filters and the necessary data range before declaring the source ready; choose an application fallback when an item has been deleted or filtered out.
+
+- [Return to a list](./return-to-list.md) covers the detail-navigation round trip.
+- [Angular rxResource](./rx-resource.md) and [TanStack Query](./tanstack-query.md) explain the source contracts and error presentation.
+- [NgRx Signal Store](./ngrx-signal-store.md) adapts a store that already owns pagination.
+- [Angular Material Drawer](./material-drawer.md) adds the container layout used by the demo.

package/docs/recipes/return-to-list.md

@@ -0,0 +1,110 @@
+---
+title: Return to a list
+description: Restore a list section after detail navigation or a reload.
+---
+
+## Goal
+
+Open an item's detail page and return to the same list section, using either browser Back or an explicit link.
+
+## Solution
+
+Provide these routes through your application's existing `provideRouter(routes)` configuration:
+
+<!-- recipe-check: app.routes.ts -->
+
+```ts
+import { Routes } from '@angular/router';
+import { ProjectsComponent } from './projects.component';
+import { ProjectDetailsComponent } from './project-details.component';
+
+export const routes: Routes = [
+  { path: 'projects', component: ProjectsComponent },
+  { path: 'projects/:id', component: ProjectDetailsComponent },
+];
+```
+
+In `projects.component.ts`, use stable IDs and capture the selected item before leaving the list:
+
+<!-- recipe-check: projects.component.ts -->
+
+```ts
+import { Component, inject } from '@angular/core';
+import { ActivatedRoute, Router } from '@angular/router';
+import { MagicScrollDirective } from '@devzwo/ngx-magic-scroll';
+
+@Component({
+  selector: 'app-projects',
+  imports: [MagicScrollDirective],
+  template: `
+    <div magicScroll>
+      @for (project of projects; track project.id) {
+        <section [id]="'project-' + project.id">
+          <h2>{{ project.name }}</h2>
+          <button (click)="openDetails(project.id)">Open details</button>
+        </section>
+      }
+    </div>
+  `,
+  styles: `
+    section {
+      min-height: 70vh;
+    }
+  `,
+})
+export class ProjectsComponent {
+  private readonly router = inject(Router);
+  private readonly route = inject(ActivatedRoute);
+  readonly projects = [
+    { id: 1, name: 'Planning' },
+    { id: 2, name: 'Delivery' },
+    { id: 3, name: 'Review' },
+  ];
+
+  async openDetails(id: number) {
+    const recorded = await this.router.navigate([], {
+      relativeTo: this.route,
+      fragment: 'project-' + id,
+      queryParamsHandling: 'preserve',
+      replaceUrl: true,
+    });
+    if (!recorded) return;
+    await this.router.navigate(['/projects', id], { queryParamsHandling: 'preserve' });
+  }
+}
+```
+
+`openDetails()` first records the clicked item's fragment in the list's current history entry, then waits for that URL update before navigating to the detail page. This avoids relying on the scroll-spy debounce or racing two navigations. Both this update and scroll-spy updates replace the current entry; detail navigation creates the next entry.
+
+In `project-details.component.ts`, use the route ID for an explicit return link:
+
+<!-- recipe-check: project-details.component.ts -->
+
+```ts
+import { Component, inject } from '@angular/core';
+import { ActivatedRoute, RouterLink } from '@angular/router';
+
+@Component({
+  selector: 'app-project-details',
+  imports: [RouterLink],
+  template: `
+    <h1>Project {{ id }}</h1>
+    <a routerLink="/projects" [fragment]="'project-' + id" queryParamsHandling="preserve">
+      Back to this project
+    </a>
+  `,
+})
+export class ProjectDetailsComponent {
+  readonly id = inject(ActivatedRoute).snapshot.paramMap.get('id');
+}
+```
+
+Browser Back restores the fragment in the previous list entry. The explicit link also works when the detail page was opened directly. Query parameters are preserved so list settings can survive the round trip. Opening or reloading `/projects#project-2` restores the section after the list renders.
+
+## Scope and related recipes
+
+This example recreates a static list. Initial restoration runs once per `magicScroll` instance; a missing target at the first ready render is not retried automatically. It restores an anchor position rather than an exact pixel offset.
+
+- [Angular rxResource](./rx-resource.md), [NgRx Signal Store](./ngrx-signal-store.md) and [TanStack Query](./tanstack-query.md) supply asynchronous readiness.
+- [Paginated lists](./paginated-lists.md) restores the loaded data range before scrolling.
+- [Anchor navigation](./scroll-to-anchor.md) covers interaction options and navigation highlighting.