@devzwo/ngx-magic-scroll 1.0.0 → 1.1.1

package/docs/recipes/rx-resource.md

@@ -0,0 +1,87 @@
+---
+title: Angular rxResource
+description: Restore anchors after Observable data loads through rxResource.
+---
+
+## Goal
+
+Open a URL such as `/projects#project-2` before the projects have loaded, then restore the section once its DOM exists.
+
+## Solution
+
+Import `MagicScrollDirective` and pass the `rxResource` itself to `scrollSource`. This self-contained example simulates an Observable API request; replace `of(...).pipe(delay(...))` with your service's Observable.
+
+<!-- recipe-check: rx-resource-0.ts -->
+
+```ts
+import { Component } from '@angular/core';
+import { rxResource } from '@angular/core/rxjs-interop';
+import { delay, of } from 'rxjs';
+import { MagicScrollDirective } from '@devzwo/ngx-magic-scroll';
+
+@Component({
+  selector: 'app-resource-projects',
+  imports: [MagicScrollDirective],
+  template: `
+    <button (click)="projects.reload()">Reload</button>
+    <div magicScroll [scrollSource]="projects">
+      @if (projects.isLoading()) {
+        <p role="status">Loading projects…</p>
+      }
+      @if (projects.error()) {
+        <p role="alert">Could not load projects. Try reloading.</p>
+      }
+      @if (projects.hasValue()) {
+        @if (projects.value().length === 0) {
+          <p>No projects.</p>
+        }
+        @for (project of projects.value(); track project.id) {
+          <section [id]="'project-' + project.id">
+            <h2>{{ project.name }}</h2>
+          </section>
+        }
+      }
+    </div>
+  `,
+  styles: `
+    section {
+      min-height: 70vh;
+    }
+  `,
+})
+export class ResourceProjectsComponent {
+  readonly projects = rxResource({
+    stream: () =>
+      of([
+        { id: 1, name: 'Planning' },
+        { id: 2, name: 'Delivery' },
+        { id: 3, name: 'Review' },
+      ]).pipe(delay(300)),
+  });
+}
+```
+
+The library reads the resource's loading and value state and restores the initial fragment after the first ready render. Passing `projects.value()` instead would discard the resource's loading information. Guard template calls to `value()` with `hasValue()` because reading an errored resource without a value can throw.
+
+An empty array is a successful, ready result; an error without a value is not. Your application owns requests, retries and error presentation. Angular `resource` can be passed directly in the same way.
+
+### Preserve position on later updates
+
+Reloading or changing resource parameters can replace the content. After initialization, ready source changes preserve the **current** fragment with an instant correction when the anchor's top edge is no longer visible. They do not repeatedly restore the original fragment.
+
+If that behavior does not fit your page, disable it for the region:
+
+```html
+<div magicScroll [scrollSource]="projects" [scrollOptions]="{ restoreOnDataChange: false }">
+  <!-- Render projects here. -->
+</div>
+```
+
+## Scope and related recipes
+
+This recipe covers one resource and an unpaginated list. It does not retrieve missing pages or choose a new anchor when a filtered item disappears.
+
+- [Return to a list](./return-to-list.md) adds detail navigation and return links.
+- [Paginated lists](./paginated-lists.md) coordinates initial loading with a saved data range.
+- [NgRx Signal Store](./ngrx-signal-store.md) adapts existing store state.
+- [TanStack Query](./tanstack-query.md) uses a query result directly.

package/docs/recipes/scroll-to-anchor.md

@@ -0,0 +1,148 @@
+---
+title: Anchor navigation
+description: Scroll to sections, choose anchors and highlight your navigation.
+---
+
+## Goal
+
+Build a small section navigation that scrolls on click and highlights the current section as the user scrolls.
+
+## Solution
+
+Start with an Angular application that provides Router, as described in [Getting started](../getting-started.md). This complete component uses static content:
+
+<!-- recipe-check: scroll-to-anchor-0.ts -->
+
+```ts
+import { Component } from '@angular/core';
+import {
+  MagicScrollDirective,
+  ScrollAnchorDirective,
+  provideMagicScroll,
+} from '@devzwo/ngx-magic-scroll';
+
+@Component({
+  selector: 'app-project-sections',
+  imports: [MagicScrollDirective, ScrollAnchorDirective],
+  providers: [provideMagicScroll({ anchorPrefixes: ['project-'] })],
+  template: `
+    <nav aria-label="Project sections">
+      @for (id of sections; track id) {
+        <button
+          [attr.aria-current]="scroll.activeAnchor() === id ? 'location' : null"
+          (click)="scroll.scrollTo(id)"
+        >
+          {{ id }}
+        </button>
+      }
+    </nav>
+
+    <div magicScroll #scroll="magicScroll">
+      <section id="overview" scrollAnchor>
+        <h2>Overview</h2>
+      </section>
+      <section id="project-planning">
+        <h2>Planning</h2>
+        <h3 id="planning-notes">Notes</h3>
+      </section>
+      <section [scrollAnchor]="'project-delivery'">
+        <h2>Delivery</h2>
+      </section>
+    </div>
+  `,
+  styles: `
+    section {
+      min-height: 70vh;
+    }
+    button[aria-current='location'] {
+      font-weight: bold;
+    }
+  `,
+})
+export class ProjectSectionsComponent {
+  readonly sections = ['overview', 'project-planning', 'project-delivery'];
+}
+```
+
+`anchorPrefixes` includes the project sections and excludes unrelated IDs such as `planning-notes`. The explicit `scrollAnchor` includes `overview` despite its different prefix; the bound form also assigns the element's ID. Without a prefix, all descendant IDs participate and the markers are optional.
+
+`scrollTo()` scrolls smoothly by default and synchronizes the fragment. `activeAnchor()` exposes that fragment; scroll-spy updates use a 500 ms debounce by default. IDs must be unique in the document and remain stable across renders.
+
+### Override one interaction
+
+For a particular button, pass per-call options:
+
+```html
+<button
+  (click)="scroll.scrollTo('project-delivery', {
+    behavior: 'instant',
+    ignoreWhenInView: 'full'
+  })"
+>
+  Show delivery if it is not fully visible
+</button>
+```
+
+`scrollTo()` returns `false` when the target is unavailable, outside this region, excluded by anchor selection or skipped by the visibility rule. Each anchor belongs to its closest `magicScroll` region, so a parent cannot scroll to a nested region's anchors.
+
+### Accessible focus transfer
+
+When navigating via keyboard shortcuts, skip links, or error notifications, transferring DOM focus to the target element is critical for accessibility. Pass `{ focus: true }` to `scrollTo()` to transfer keyboard focus without secondary layout shifts:
+
+```html
+<button
+  (click)="scroll.scrollTo('project-delivery', {
+    behavior: 'smooth',
+    focus: true
+  })"
+>
+  Jump to delivery and shift focus
+</button>
+```
+
+- **Safe Focus**: Invocations use `focus({ preventScroll: true })` so browser-native focus scrolling does not conflict with calculated header offsets.
+- **Temporary Tabindex Management**: Naturally focusable elements (links, buttons, inputs) and elements with existing `tabindex` receive focus directly. Non-focusable container elements (e.g. `<section>`, `<div>`) receive a temporary `tabindex="-1"`, which is removed if focus fails, on `blur`, or when the directive is destroyed. Consumer changes to `tabindex` are preserved.
+- **Smooth Scroll Coordination & Cancellation**: For effective smooth scrolling (including `behavior: 'auto'` when CSS `scroll-behavior` is smooth), focus is applied upon scroll completion (`scrollend`). No-movement requests focus immediately. A newer navigation, user scroll, Tab key, focus change, or pointer handoff cancels stale pending focus.
+- **Target validation**: The target must still be connected and eligible in this region when focus is applied. Pending focus is canceled if scrolling does not complete within five seconds.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User as User / Trigger
+    participant Directive as MagicScrollDirective
+    participant Service as ScrollService
+    participant Target as Anchor Element
+
+    User->>Directive: scrollTo('section-id', { focus: true, behavior: 'smooth' })
+    Directive->>Service: scroll('section-id', options)
+    alt Target resolved, but scroll is skipped or has no movement
+        Directive->>Directive: applyFocus(target)
+    else Target missing or excluded
+        Directive->>Directive: no focus transfer
+    else Scrolling Initiated
+        Service-->>Directive: returns true
+        alt Effective behavior is smooth
+            Directive->>Directive: scheduleFocus(target)
+            Note over Directive: Cancelled on newer navigation or user handoff
+            Directive->>Directive: on scrollend -> applyFocus(target)
+        else Instant behavior
+            Directive->>Directive: applyFocus(target)
+        end
+    end
+
+    opt Non-focusable Target (no tabindex)
+        Directive->>Target: setAttribute('tabindex', '-1')
+        Directive->>Target: addEventListener('blur', removeTabindex, { once: true })
+    end
+    Directive->>Target: target.focus({ preventScroll: true })
+    Directive-->>User: returns boolean
+```
+
+## Scope and related recipes
+
+The target must already be rendered; this recipe does not load data or missing sections.
+
+- [Return to a list](./return-to-list.md) adds navigation between routed pages.
+- [Angular rxResource](./rx-resource.md) waits for asynchronously rendered anchors.
+- [Sticky master–detail](./sticky-master-detail.md) adds header offsets and sticky navigation.
+- [Angular Material Drawer](./material-drawer.md) moves scrolling into a nested container.

package/docs/recipes/sticky-master-detail.md

@@ -0,0 +1,138 @@
+---
+title: Sticky master–detail
+description: Combine document scrolling, a measured header and sticky section navigation.
+---
+
+## Goal
+
+Build a portfolio page with a sticky header, an independently scrollable project index and details that scroll with the document. Keep navigation and offsets aligned when the header changes height.
+
+## Solution
+
+This compact version of the master–detail demo uses static projects so the layout is easy to see. Angular Router must be provided by the application.
+
+<!-- recipe-check: sticky-master-detail-0.ts -->
+
+```ts
+import { Component, signal } from '@angular/core';
+import { MagicScrollDirective, provideMagicScroll } from '@devzwo/ngx-magic-scroll';
+
+@Component({
+  selector: 'app-portfolio',
+  imports: [MagicScrollDirective],
+  providers: [
+    provideMagicScroll({
+      anchorPrefixes: ['project-'],
+      headerSelector: '.portfolio-header',
+      headerOffset: 16,
+    }),
+  ],
+  template: `
+    <header class="portfolio-header">
+      <strong>Portfolio</strong>
+      <button (click)="expanded.set(!expanded())">Toggle toolbar</button>
+      @if (expanded()) {
+        <p>Additional project tools</p>
+      }
+    </header>
+
+    <div class="layout" [style.--scroll-offset]="scroll.offset() + 'px'">
+      <aside class="master">
+        <nav aria-label="Projects">
+          @for (project of projects; track project.id) {
+            <button
+              [attr.aria-current]="
+                scroll.activeAnchor() === 'project-' + project.id ? 'location' : null
+              "
+              (click)="scroll.scrollTo('project-' + project.id)"
+            >
+              {{ project.name }}
+            </button>
+          }
+        </nav>
+      </aside>
+
+      <div class="details" magicScroll #scroll="magicScroll">
+        @for (project of projects; track project.id) {
+          <section [id]="'project-' + project.id">
+            <h2>{{ project.name }}</h2>
+            <p>Planning, milestones and project details.</p>
+          </section>
+        }
+      </div>
+    </div>
+  `,
+  styles: `
+    :host {
+      display: block;
+    }
+    .portfolio-header {
+      position: sticky;
+      top: 0;
+      z-index: 10;
+      padding: 16px;
+      background: white;
+    }
+    .layout {
+      display: grid;
+      grid-template-columns: minmax(120px, 200px) minmax(0, 1fr);
+      align-items: start;
+      gap: 24px;
+    }
+    .master {
+      position: sticky;
+      top: var(--scroll-offset);
+      max-height: calc(100dvh - var(--scroll-offset) - 16px);
+      overflow-y: auto;
+    }
+    nav {
+      display: flex;
+      flex-direction: column;
+    }
+    button[aria-current='location'] {
+      font-weight: bold;
+    }
+    .details {
+      min-width: 0;
+    }
+    section {
+      min-height: 70vh;
+    }
+  `,
+})
+export class PortfolioComponent {
+  readonly expanded = signal(false);
+  readonly projects = Array.from({ length: 12 }, (_, index) => ({
+    id: index + 1,
+    name: `Project ${index + 1}`,
+  }));
+}
+```
+
+The detail region has no constrained height or scrolling overflow, so it uses document scrolling. The sidebar scrolls independently and sits outside the region; its elements are not detail anchors.
+
+`headerSelector` measures the matching header and observes height changes. `headerOffset` adds a gap below it. `scroll.offset()` exposes the sum, which positions the sidebar and limits its height. Use a selector identifying the intended header uniquely.
+
+Resize and header-height corrections are enabled by default and adjust the current anchor instantly. Set `preserveOnResize: false` in `scrollOptions` if those corrections are unwanted; the measured offset still remains available.
+
+### Add asynchronously loaded details
+
+Replace the static collection with your data source and bind it to the detail region. For a resource:
+
+```html
+<div class="details" magicScroll #scroll="magicScroll" [scrollSource]="projects">
+  @if (projects.hasValue()) { @for (project of projects.value(); track project.id) {
+  <section [id]="'project-' + project.id">{{ project.name }}</section>
+  } }
+</div>
+```
+
+Update the sidebar to render the same loaded collection. Initial restoration then waits for the data rather than consuming the fragment before the detail anchors exist.
+
+## Scope and related recipes
+
+The layout follows the zwoPRO-inspired demo, but leaves application forms and store architecture out of the example. It uses the document for detail scrolling; CSS still determines whether an ancestor becomes the scroll container.
+
+- [Angular rxResource](./rx-resource.md), [NgRx Signal Store](./ngrx-signal-store.md) and [TanStack Query](./tanstack-query.md) implement the corresponding data sources.
+- [Anchor navigation](./scroll-to-anchor.md) explains explicit anchor selection and per-click overrides.
+- [Angular Material Drawer](./material-drawer.md) uses a constrained content container instead of document scrolling.

package/docs/recipes/tanstack-query.md

@@ -0,0 +1,96 @@
+---
+title: TanStack Query
+description: Bind a TanStack Angular Query result directly to scrollSource.
+---
+
+## Goal
+
+Restore an anchor after a query loads and keep the current section aligned when cached data is refreshed.
+
+## Solution
+
+If your application uses `@tanstack/angular-query-experimental`, its reactive `data()` and `isLoading()` getters already match `ScrollDataSource`. Pass the query result directly; the library does not depend on TanStack.
+
+Register the query client alongside your existing Angular Router providers in `app.config.ts`:
+
+<!-- recipe-check: tanstack-query-0.ts -->
+
+```ts
+import { ApplicationConfig } from '@angular/core';
+import { provideRouter } from '@angular/router';
+import { provideTanStackQuery, QueryClient } from '@tanstack/angular-query-experimental';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideRouter([]), provideTanStackQuery(new QueryClient())],
+};
+```
+
+Use your actual routes in place of `[]`. Then render a query in your component:
+
+<!-- recipe-check: tanstack-query-1.ts -->
+
+```ts
+import { Component } from '@angular/core';
+import { injectQuery } from '@tanstack/angular-query-experimental';
+import { MagicScrollDirective } from '@devzwo/ngx-magic-scroll';
+
+interface Project {
+  id: number;
+  name: string;
+}
+
+@Component({
+  selector: 'app-query-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>
+      }
+      @if (projects.data()?.length === 0) {
+        <p>No projects.</p>
+      }
+      @for (project of projects.data(); track project.id) {
+        <section [id]="'project-' + project.id">
+          <h2>{{ project.name }}</h2>
+        </section>
+      }
+    </div>
+  `,
+  styles: `
+    section {
+      min-height: 70vh;
+    }
+  `,
+})
+export class QueryProjectsComponent {
+  readonly projects = injectQuery(() => ({
+    queryKey: ['projects'],
+    queryFn: async (): Promise<Project[]> => {
+      const response = await fetch('/api/projects');
+      if (!response.ok) throw new Error('Could not load projects.');
+      return response.json();
+    },
+  }));
+}
+```
+
+The application endpoint `/api/projects` returns a project array. A failed response throws so TanStack can expose its error state. The query retains responsibility for retries, caching and refetching.
+
+The library waits while the query is initially loading or `data()` is undefined. Cached data can be ready immediately. Keep the rendered list in place during a background fetch: `isFetching()` also includes background activity, whereas `isLoading()` describes the initial fetch without data. A disabled query without data still waits because its data is undefined.
+
+When ready data changes after initialization, `restoreOnDataChange` preserves the current anchor by default. This is separate from cache policy and does not cause a request.
+
+## Scope and related recipes
+
+This recipe uses one ordinary query. It does not retrieve extra pages, restore filter state or force a refetch before initial restoration.
+
+- [Paginated lists](./paginated-lists.md#tanstack-infinite-query) adds an Infinite Query and a saved loading range, following the application-list pattern in the HNE frontend.
+- [Return to a list](./return-to-list.md) adds detail navigation.
+- [Angular Material Drawer](./material-drawer.md) places the same query-backed list inside a scrollable drawer layout.
+
+See the official [TanStack Angular quick start](https://tanstack.com/query/latest/docs/framework/angular/quick-start) and [query guide](https://tanstack.com/query/latest/docs/framework/angular/guides/queries) for setup and query behavior. The Angular package is experimental; use the APIs provided by your installed version.