@design-edito/tools 0.5.4 → 0.5.6

package/components/Scrllgngn/index.js

@@ -1,12 +1,14 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { useState, useEffect } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { clss } from '../../agnostic/css/clss/index.js';
+import { randomHash } from '../../agnostic/random/uuid/index.js';
 import { IntersectionObserverComponent } from '../IntersectionObserver/index.js';
 import { Paginator } from '../Paginator/index.js';
 import { ResizeObserverComponent } from '../ResizeObserver/index.js';
+import { subscribe, unsubscribe } from '../ScrollListener/utils.js';
 import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
 import { scrllgngn as publicClassName } from '../public-classnames.js';
-import { consolidateStickyBlocks, lazyLoadedBlocks, toScreenCssProps } from './utils.js';
+import { blockDisplayZones, consolidateStickyBlocks, contextsAreEqual, lazyLoadedBlocks, measurePages, sameDiscretePart, scrollBlocksOf, scrollKey, stickyKey, toScreenCssProps, toTrackedBlockContext, toTrackedBlockCssProps, toTrackedBlockDataAttributes } from './utils.js';
 import cssModule from './styles.module.css';
 /**
  * Scrollytelling engine component. Orchestrates layered sticky blocks (`back`
@@ -50,13 +52,40 @@ import cssModule from './styles.module.css';
  * - An inline `z-index` derived from the block's position in the sorted stack
  * (overridden by {@link PropsStickyBlock.zIndex} if provided).
  *
+ * ### Scroll block elements
+ * Each scroll block sits in its own wrapper, whatever it does — a block that isn't
+ * tracked still gets one, so the DOM keeps the same shape either way.
+ *
+ * ### Tracked block elements
+ * A block declaring {@link PropsCommonBlock.onScrolled} also carries its
+ * {@link TrackedBlockContext} on its wrapper, for scrollytelling driven in CSS
+ * alone. Written straight to the element on the frames they change, so they never
+ * re-render the sequence.
+ *
+ * Progressions, as unitless `0`–`1` ratios:
+ * - `--lm-scrllgngn-block-current-page-progression-ratio`
+ * - `--lm-scrllgngn-block-display-zone-progression-ratio`
+ * - `--lm-scrllgngn-block-contiguous-display-zone-progression-ratio`
+ *
+ * Position, which only moves with the page:
+ * - `data-current-page`
+ * - `data-display-zone` — comma-separated page positions.
+ * - `data-index-of-current-page-in-display-zone`
+ * - `data-contiguous-display-zone`
+ * - `data-index-of-current-page-in-contiguous-display-zone`
+ *
  * @param props - Component properties.
  * @see {@link Props}
  * @returns A div wrapping the full scrollytelling structure: top-bound sentinel,
  * back-blocks layer, front-blocks layer, paginated scrolling content, and
  * bottom-bound sentinel.
+ *
+ * @remarks
+ * Tracking costs nothing until a block asks for it: with no `onScrolled` anywhere,
+ * the component never joins the shared scroll listener. Once it does, each frame
+ * measures only the pages the displayed tracked blocks span, not the whole sequence.
  */
-export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadDistance = 2, forceStickBlocks, onPageChanged, className }) => {
+export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadDistance = 2, forceStickBlocks, onPageChanged, onContentVisibilityChanged, className }) => {
     // State
     const [topVisible, setTopVis] = useState(false);
     const [contentVisible, setCntVis] = useState(false);
@@ -64,14 +93,125 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
     const [currentPagePos, setCurrentPagePos] = useState(0);
     const [stickyBlocks, setStickyBlocks] = useState(new Map());
     const [partialBoundingRect, setPartialBoundingRect] = useState();
+    // Scroll tracking. Everything the per-frame pass reads lives in a ref: it is
+    // registered once with the shared scroll listener, and writes straight to the DOM
+    // rather than through state, which would re-render the whole sequence per frame.
+    const rootRef = useRef(null);
+    const subscriptionIdRef = useRef(randomHash(8));
+    const pageElementsRef = useRef([]);
+    const trackedBlocksRef = useRef(new Map());
+    const trackedWrappersRef = useRef(new Map());
+    const lastContextsRef = useRef(new Map());
+    const currentPagePosRef = useRef(currentPagePos);
     // Sticky blocks calculations
     useEffect(() => {
         setStickyBlocks(consolidateStickyBlocks(pages));
     }, [pages]);
     const lazyLoadedBackBlocks = lazyLoadedBlocks(stickyBlocks, 'back', currentPagePos, stickyBlocksLazyLoadDistance);
     const lazyLoadedFrontBlocks = lazyLoadedBlocks(stickyBlocks, 'front', currentPagePos, stickyBlocksLazyLoadDistance);
+    // Tracked blocks, keyed the same way their wrappers are
+    const displayZones = blockDisplayZones(pages);
+    const trackedBlocks = new Map();
+    for (const [blockId, block] of stickyBlocks) {
+        if (block.onScrolled === undefined)
+            continue;
+        trackedBlocks.set(stickyKey(blockId), {
+            displayZone: block.id === undefined
+                ? block.displayOnPages
+                : displayZones.get(block.id) ?? block.displayOnPages,
+            onScrolled: block.onScrolled
+        });
+    }
+    pages?.forEach((page, pagePos) => {
+        scrollBlocksOf(page).forEach((block, blockPos) => {
+            if (block.onScrolled === undefined)
+                return;
+            trackedBlocks.set(scrollKey(pagePos, blockPos), {
+                displayZone: block.id === undefined
+                    ? [pagePos]
+                    : displayZones.get(block.id) ?? [pagePos],
+                onScrolled: block.onScrolled
+            });
+        });
+    });
+    const hasTrackedBlocks = trackedBlocks.size > 0;
+    // Fx. no dep. - Keep what the per-frame pass reads in sync with the last render
+    useEffect(() => {
+        trackedBlocksRef.current = trackedBlocks;
+        currentPagePosRef.current = currentPagePos;
+    });
+    // The per-frame pass: measure only the pages the displayed tracked blocks span,
+    // then hand each block its context — once, and only when something moved.
+    const handleScrolled = useCallback(() => {
+        const trackedBlocks = trackedBlocksRef.current;
+        const lastContexts = lastContextsRef.current;
+        const currentPage = currentPagePosRef.current;
+        const pending = [];
+        for (const [key, block] of trackedBlocks) {
+            if (block.displayZone.includes(currentPage))
+                pending.push([key, block, currentPage]);
+        }
+        // A block that just left the current page gets one last pass, on the page it was
+        // on: its progressions are clamped, so it lands on the edge it crossed instead of
+        // freezing part-way.
+        for (const [key, lastContext] of lastContexts) {
+            const block = trackedBlocks.get(key);
+            if (block === undefined) {
+                lastContexts.delete(key);
+                continue;
+            }
+            if (block.displayZone.includes(currentPage))
+                continue;
+            pending.push([key, block, lastContext.currentPage]);
+        }
+        if (pending.length === 0)
+            return;
+        const pagesToMeasure = new Set();
+        for (const [, block, page] of pending) {
+            pagesToMeasure.add(page);
+            for (const pagePos of block.displayZone)
+                pagesToMeasure.add(pagePos);
+        }
+        const metrics = measurePages(pageElementsRef.current, pagesToMeasure, thresholdOffsetPercent);
+        for (const [key, block, page] of pending) {
+            const context = toTrackedBlockContext(block.displayZone, page, metrics);
+            const lastContext = lastContexts.get(key);
+            if (contextsAreEqual(context, lastContext))
+                continue;
+            const wrapper = trackedWrappersRef.current.get(key);
+            if (wrapper !== undefined) {
+                for (const [name, value] of Object.entries(toTrackedBlockCssProps(context))) {
+                    wrapper.style.setProperty(name, value);
+                }
+                // Discrete values only move with the page, so they don't need a write per frame
+                if (!sameDiscretePart(context, lastContext)) {
+                    for (const [name, value] of Object.entries(toTrackedBlockDataAttributes(context))) {
+                        wrapper.setAttribute(name, value);
+                    }
+                }
+            }
+            block.onScrolled(context);
+            if (page === currentPage)
+                lastContexts.set(key, context);
+            else
+                lastContexts.delete(key);
+        }
+    }, [thresholdOffsetPercent]);
+    // Fx. dep. hasTrackedBlocks, handleScrolled - Join the shared scroll listener, and
+    // only then: no tracked block, no measurement pass at all.
+    useEffect(() => {
+        if (!hasTrackedBlocks)
+            return;
+        const subscriptionId = subscriptionIdRef.current;
+        subscribe(subscriptionId, {
+            rootRef,
+            onScrollStateChange: handleScrolled
+        });
+        return () => unsubscribe(subscriptionId);
+    }, [hasTrackedBlocks, handleScrolled]);
     // Handlers
     useChangeDispatch(currentPagePos, pagePos => onPageChanged?.(pagePos, pages?.[pagePos]));
+    useChangeDispatch(contentVisible, onContentVisibilityChanged);
     const handleTopBoundDetect = e => setTopVis(e.ioEntry?.isIntersecting ?? false);
     const handleCntDetect = e => setCntVis(e.ioEntry?.isIntersecting ?? false);
     const handleBtmBoundDetect = e => setBtmVis(e.ioEntry?.isIntersecting ?? false);
@@ -81,6 +221,17 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
             return;
         setCurrentPagePos(curPagePos);
     };
+    const handlePageElementsChanged = elements => {
+        pageElementsRef.current = elements;
+    };
+    // Registers a block wrapper under the key its context is tracked by. Blocks come
+    // and go with lazy loading, so the map is kept clean on unmount rather than grown.
+    const registerWrapper = (key) => (element) => {
+        if (element === null)
+            trackedWrappersRef.current.delete(key);
+        else
+            trackedWrappersRef.current.set(key, element);
+    };
     const handleResize = ({ boundingClientRect }) => {
         if (partialBoundingRect === undefined
             || boundingClientRect.left !== partialBoundingRect.left
@@ -100,24 +251,21 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
         'force-stick-blocks-both': forceStickBlocks === 'both'
     }), className);
     const customCssProps = toScreenCssProps(partialBoundingRect);
-    return _jsx("div", { className: rootClss, "data-current-page-pos": currentPagePos, "data-current-page-id": pages?.[currentPagePos]?.id, style: { ...customCssProps }, children: _jsxs(ResizeObserverComponent, { onResized: handleResize, children: [_jsx("div", { className: c('top-bound'), children: _jsx(IntersectionObserverComponent, { onIntersected: handleTopBoundDetect }) }), _jsx("div", { className: c('back-blocks'), children: lazyLoadedBackBlocks.map((block, blockPos) => {
+    return _jsx("div", { ref: rootRef, className: rootClss, "data-current-page-pos": currentPagePos, "data-current-page-id": pages?.[currentPagePos]?.id, style: { ...customCssProps }, children: _jsxs(ResizeObserverComponent, { onResized: handleResize, children: [_jsx("div", { className: c('top-bound'), children: _jsx(IntersectionObserverComponent, { onIntersected: handleTopBoundDetect }) }), _jsx("div", { className: c('back-blocks'), children: lazyLoadedBackBlocks.map(([blockId, block], blockPos) => {
                         const isActive = block.displayOnPages.includes(currentPagePos);
                         const blockClss = c('back-block', {
                             active: isActive,
                             'lazy-loaded': !isActive
                         });
-                        return _jsx("div", { className: blockClss, style: { zIndex: blockPos }, children: block.children });
-                    }) }), _jsx("div", { className: c('front-blocks'), children: lazyLoadedFrontBlocks.map((block, blockPos) => {
+                        return _jsx("div", { ref: registerWrapper(stickyKey(blockId)), className: blockClss, style: { zIndex: blockPos }, children: block.children }, blockId);
+                    }) }), _jsx("div", { className: c('front-blocks'), children: lazyLoadedFrontBlocks.map(([blockId, block], blockPos) => {
                         const isActive = block.displayOnPages.includes(currentPagePos);
                         const blockClss = c('front-block', {
                             active: isActive,
                             'lazy-loaded': !isActive
                         });
-                        return _jsx("div", { className: blockClss, style: { zIndex: blockPos }, children: block.children });
-                    }) }), _jsx("div", { className: c('scrolling-content'), children: _jsx(IntersectionObserverComponent, { onIntersected: handleCntDetect, children: _jsx(Paginator, { thresholdOffsetPercent: thresholdOffsetPercent, onPagesChanged: handlePagesChanged, children: pages?.map(page => {
-                                const scrollBlocks = page.blocks
-                                    ?.filter(b => b.depth === 'scroll' || b.depth === undefined) ?? [];
-                                // eslint-disable-next-line @typescript-eslint/promise-function-async
-                                return _jsx(_Fragment, { children: scrollBlocks.map(b => b.children) });
+                        return _jsx("div", { ref: registerWrapper(stickyKey(blockId)), className: blockClss, style: { zIndex: blockPos }, children: block.children }, blockId);
+                    }) }), _jsx("div", { className: c('scrolling-content'), children: _jsx(IntersectionObserverComponent, { onIntersected: handleCntDetect, children: _jsx(Paginator, { thresholdOffsetPercent: thresholdOffsetPercent, onPagesChanged: handlePagesChanged, onPageElementsChanged: handlePageElementsChanged, children: pages?.map((page, pagePos) => {
+                                return _jsx(_Fragment, { children: scrollBlocksOf(page).map((block, blockPos) => _jsx("div", { ref: registerWrapper(scrollKey(pagePos, blockPos)), className: c('scroll-block'), children: block.children }, blockPos)) });
                             }) }) }) }), _jsx("div", { className: c('bottom-bound'), children: _jsx(IntersectionObserverComponent, { onIntersected: handleBtmBoundDetect }) })] }) });
 };

package/components/Scrllgngn/utils.d.ts

@@ -1,4 +1,4 @@
-import type { PropsPage, PropsStickyBlock } from './index.js';
+import type { PropsBlock, PropsPage, PropsStickyBlock } from './index.js';
 /** The subset of a bounding rect a {@link Scrllgngn} tracks and exposes. */
 export type ScreenRect = {
     left: number;
@@ -33,9 +33,11 @@ export declare function consolidateStickyBlocks(pages?: PropsPage[]): Map<string
  * @param currentPagePos - Zero-based position of the page in view.
  * @param lazyLoadDistance - How many pages around the current one still mount
  * their blocks.
- * @returns The blocks to render, stacked by ascending `zIndex`.
+ * @returns The blocks to render with the id they were consolidated under, stacked
+ * by ascending `zIndex`. The id comes along because it is what identifies the block
+ * across renders — its own `id` is optional, a consolidation key never is.
  */
-export declare function lazyLoadedBlocks(blocks: Map<string, ConsolidatedStickyBlock>, depth: 'back' | 'front', currentPagePos: number, lazyLoadDistance: number): ConsolidatedStickyBlock[];
+export declare function lazyLoadedBlocks(blocks: Map<string, ConsolidatedStickyBlock>, depth: 'back' | 'front', currentPagePos: number, lazyLoadDistance: number): Array<[string, ConsolidatedStickyBlock]>;
 /**
  * Builds the CSS custom properties exposed on a {@link Scrllgngn} root.
  *
@@ -50,3 +52,136 @@ export declare function lazyLoadedBlocks(blocks: Map<string, ConsolidatedStickyB
  * @returns The custom properties, keyed by their full name.
  */
 export declare function toScreenCssProps(rect?: ScreenRect): Record<string, string>;
+/**
+ * Where one tracked block stands in the scroll, as handed to its `onScrolled`.
+ *
+ * Every progression is a `0`–`1` ratio measured against the threshold line, and
+ * weighted **by pixel height**: a zone of unequal pages is not the same as
+ * `(indexOfCurrentPage + currentPageProgression) / displayZone.length`.
+ *
+ * @property currentPage - Zero-based position of the page in view.
+ * @property currentPageProgression - `0` when the current page's top meets the
+ * threshold, `1` when its bottom does.
+ * @property displayZone - Every page the block's `id` appears on. A block without
+ * an `id` shows on one page, so its zone holds that page alone and its three
+ * progressions are equal.
+ * @property indexOfCurrentPageInDisplayZone - Where `currentPage` sits in
+ * `displayZone`.
+ * @property displayZoneProgression - Progression across the whole zone. On a zone
+ * like `[2, 3, 5]` it runs 0 → ~0.66 over pages 2–3, pauses while page 4 shows the
+ * block nowhere, then resumes to 1 on page 5.
+ * @property contiguousDisplayZone - The unbroken run of `displayZone` containing
+ * `currentPage` — `[2, 3]` for the zone above while on page 2 or 3.
+ * @property indexOfCurrentPageInContiguousDisplayZone - Where `currentPage` sits in
+ * `contiguousDisplayZone`.
+ * @property contiguousDisplayZoneProgression - Progression across that run alone,
+ * so it always spans a full 0 → 1.
+ */
+export type TrackedBlockContext = {
+    currentPage: number;
+    currentPageProgression: number;
+    displayZone: number[];
+    indexOfCurrentPageInDisplayZone: number;
+    displayZoneProgression: number;
+    contiguousDisplayZone: number[];
+    indexOfCurrentPageInContiguousDisplayZone: number;
+    contiguousDisplayZoneProgression: number;
+};
+/** How far the threshold line has travelled through one page, in pixels. */
+export type PageScrollMetrics = {
+    scrolled: number;
+    height: number;
+};
+/**
+ * Lists the pages each block id shows on.
+ *
+ * @param pages - The pages to walk, in order.
+ * @returns Zero-based page positions per id, ordered. Blocks without an `id` are
+ * left out: they show on their own page and nowhere else.
+ */
+export declare function blockDisplayZones(pages?: PropsPage[]): Map<string, number[]>;
+/**
+ * Isolates the unbroken run of pages around one page.
+ *
+ * @param zone - The pages a block shows on, in any order.
+ * @param page - The page the run must contain.
+ * @returns The run holding `page`, ascending, or an empty array when `zone` misses
+ * it entirely.
+ */
+export declare function contiguousRunContaining(zone: number[], page: number): number[];
+/**
+ * Measures how far the threshold line has travelled through each of the pages
+ * asked for.
+ *
+ * Only those pages are measured, not all of them: a long sequence would otherwise
+ * pay for a forced layout per page on every frame, where the tracked blocks rarely
+ * span more than a handful.
+ *
+ * @param pageElements - Every page slot, indexed by position.
+ * @param pagePositions - The positions worth measuring.
+ * @param thresholdOffsetPercent - The same offset the internal `Paginator` uses,
+ * as a percentage of the viewport height.
+ * @returns The metrics of each measurable page, keyed by position.
+ */
+export declare function measurePages(pageElements: HTMLElement[], pagePositions: Iterable<number>, thresholdOffsetPercent?: number): Map<number, PageScrollMetrics>;
+/**
+ * Assembles what one tracked block is told about the scroll.
+ *
+ * @param displayZone - The pages the block shows on.
+ * @param currentPage - Zero-based position of the page in view.
+ * @param metrics - Measurements covering at least `displayZone`.
+ * @returns The context to hand to `onScrolled`.
+ */
+export declare function toTrackedBlockContext(displayZone: number[], currentPage: number, metrics: Map<number, PageScrollMetrics>): TrackedBlockContext;
+/** Whether two contexts hold the same discrete fields, ignoring the progressions. */
+export declare function sameDiscretePart(a: TrackedBlockContext, b?: TrackedBlockContext): boolean;
+/** Whether two contexts are equal down to the progressions. */
+export declare function contextsAreEqual(a: TrackedBlockContext, b?: TrackedBlockContext): boolean;
+/**
+ * Builds the CSS custom properties carrying a tracked block's progressions.
+ *
+ * Only the continuous fields land here — the discrete ones are `data-` attributes,
+ * written by {@link toTrackedBlockDataAttributes}.
+ *
+ * @param context - The block's current context.
+ * @returns The custom properties, keyed by their full name.
+ */
+export declare function toTrackedBlockCssProps(context: TrackedBlockContext): Record<string, string>;
+/**
+ * Builds the `data-` attributes carrying a tracked block's discrete position.
+ *
+ * @param context - The block's current context.
+ * @returns The attributes, keyed by their full name.
+ */
+export declare function toTrackedBlockDataAttributes(context: TrackedBlockContext): Record<string, string>;
+/** What the per-frame pass needs to know about one tracked block. */
+export type TrackedBlock = {
+    displayZone: number[];
+    onScrolled: (context: TrackedBlockContext) => void;
+};
+/**
+ * Keys a tracked sticky block.
+ *
+ * Sticky and scroll blocks share one map of wrappers, and a sticky block is one
+ * element for the whole sequence where a scroll block is one per page — hence two
+ * key shapes rather than a single ambiguous one.
+ *
+ * @param blockId - The id the block was consolidated under.
+ * @returns The key its wrapper is registered as.
+ */
+export declare function stickyKey(blockId: string): string;
+/**
+ * Keys a tracked scroll block.
+ *
+ * @param pagePos - Zero-based position of the page it belongs to.
+ * @param blockPos - Its position among that page's scroll blocks.
+ * @returns The key its wrapper is registered as.
+ */
+export declare function scrollKey(pagePos: number, blockPos: number): string;
+/**
+ * Picks the blocks of a page that scroll with the content.
+ *
+ * @param page - The page to read.
+ * @returns Its scroll blocks, in order. `depth` left out means `'scroll'`.
+ */
+export declare function scrollBlocksOf(page: PropsPage): PropsBlock[];

package/components/Scrllgngn/utils.js

@@ -1,3 +1,4 @@
+import { clamp } from '../../agnostic/numbers/clamp/index.js';
 import { randomHash } from '../../agnostic/random/uuid/index.js';
 /**
  * Merges the sticky blocks of every page into a single entry per block id.
@@ -50,18 +51,19 @@ export function consolidateStickyBlocks(pages) {
  * @param currentPagePos - Zero-based position of the page in view.
  * @param lazyLoadDistance - How many pages around the current one still mount
  * their blocks.
- * @returns The blocks to render, stacked by ascending `zIndex`.
+ * @returns The blocks to render with the id they were consolidated under, stacked
+ * by ascending `zIndex`. The id comes along because it is what identifies the block
+ * across renders — its own `id` is optional, a consolidation key never is.
  */
 export function lazyLoadedBlocks(blocks, depth, currentPagePos, lazyLoadDistance) {
     return Array
         .from(blocks)
-        .map(([, block]) => block)
-        .filter(block => block.depth === depth
+        .filter(([, block]) => block.depth === depth
         && block.displayOnPages.some(dispPage => {
             const absDiff = Math.abs(dispPage - currentPagePos);
             return absDiff <= lazyLoadDistance;
         }))
-        .sort((a, b) => (a.zIndex ?? -Infinity) - (b.zIndex ?? -Infinity));
+        .sort(([, a], [, b]) => (a.zIndex ?? -Infinity) - (b.zIndex ?? -Infinity));
 }
 /**
  * Builds the CSS custom properties exposed on a {@link Scrllgngn} root.
@@ -100,3 +102,194 @@ export function toScreenCssProps(rect) {
 function toPrivateLength(value) {
     return value === undefined ? 'initial' : `${value}px`;
 }
+/**
+ * Lists the pages each block id shows on.
+ *
+ * @param pages - The pages to walk, in order.
+ * @returns Zero-based page positions per id, ordered. Blocks without an `id` are
+ * left out: they show on their own page and nowhere else.
+ */
+export function blockDisplayZones(pages) {
+    const zones = new Map();
+    (pages ?? []).forEach((page, pagePos) => {
+        for (const block of page.blocks ?? []) {
+            if (block.id === undefined)
+                continue;
+            const zone = zones.get(block.id) ?? [];
+            if (!zone.includes(pagePos))
+                zone.push(pagePos);
+            zones.set(block.id, zone);
+        }
+    });
+    return zones;
+}
+/**
+ * Isolates the unbroken run of pages around one page.
+ *
+ * @param zone - The pages a block shows on, in any order.
+ * @param page - The page the run must contain.
+ * @returns The run holding `page`, ascending, or an empty array when `zone` misses
+ * it entirely.
+ */
+export function contiguousRunContaining(zone, page) {
+    const ascending = [...zone].sort((a, b) => a - b);
+    let run = [];
+    for (const pagePos of ascending) {
+        const previous = run[run.length - 1];
+        if (previous !== undefined && pagePos !== previous + 1) {
+            if (run.includes(page))
+                return run;
+            run = [];
+        }
+        run.push(pagePos);
+    }
+    return run.includes(page) ? run : [];
+}
+/**
+ * Measures how far the threshold line has travelled through each of the pages
+ * asked for.
+ *
+ * Only those pages are measured, not all of them: a long sequence would otherwise
+ * pay for a forced layout per page on every frame, where the tracked blocks rarely
+ * span more than a handful.
+ *
+ * @param pageElements - Every page slot, indexed by position.
+ * @param pagePositions - The positions worth measuring.
+ * @param thresholdOffsetPercent - The same offset the internal `Paginator` uses,
+ * as a percentage of the viewport height.
+ * @returns The metrics of each measurable page, keyed by position.
+ */
+export function measurePages(pageElements, pagePositions, thresholdOffsetPercent) {
+    const thresholdY = window.innerHeight * (thresholdOffsetPercent ?? 0) / 100;
+    const measured = new Map();
+    for (const pagePos of pagePositions) {
+        const element = pageElements[pagePos];
+        if (element === undefined)
+            continue;
+        const { top, height } = element.getBoundingClientRect();
+        measured.set(pagePos, {
+            scrolled: clamp(thresholdY - top, 0, height),
+            height
+        });
+    }
+    return measured;
+}
+/** Pixel-weighted progression across a set of pages, `0` when none is measured. */
+function zoneProgression(zone, metrics) {
+    let scrolled = 0;
+    let height = 0;
+    for (const pagePos of zone) {
+        const pageMetrics = metrics.get(pagePos);
+        if (pageMetrics === undefined)
+            continue;
+        scrolled += pageMetrics.scrolled;
+        height += pageMetrics.height;
+    }
+    return height === 0 ? 0 : scrolled / height;
+}
+/**
+ * Assembles what one tracked block is told about the scroll.
+ *
+ * @param displayZone - The pages the block shows on.
+ * @param currentPage - Zero-based position of the page in view.
+ * @param metrics - Measurements covering at least `displayZone`.
+ * @returns The context to hand to `onScrolled`.
+ */
+export function toTrackedBlockContext(displayZone, currentPage, metrics) {
+    const contiguousDisplayZone = contiguousRunContaining(displayZone, currentPage);
+    return {
+        currentPage,
+        currentPageProgression: zoneProgression([currentPage], metrics),
+        displayZone,
+        indexOfCurrentPageInDisplayZone: displayZone.indexOf(currentPage),
+        displayZoneProgression: zoneProgression(displayZone, metrics),
+        contiguousDisplayZone,
+        indexOfCurrentPageInContiguousDisplayZone: contiguousDisplayZone.indexOf(currentPage),
+        contiguousDisplayZoneProgression: zoneProgression(contiguousDisplayZone, metrics)
+    };
+}
+/** The fields that only move when the page does, so they can be written sparingly. */
+function discretePart(context) {
+    return [
+        context.currentPage,
+        context.indexOfCurrentPageInDisplayZone,
+        context.indexOfCurrentPageInContiguousDisplayZone,
+        context.displayZone.join(','),
+        context.contiguousDisplayZone.join(',')
+    ].join('|');
+}
+/** Whether two contexts hold the same discrete fields, ignoring the progressions. */
+export function sameDiscretePart(a, b) {
+    return b !== undefined && discretePart(a) === discretePart(b);
+}
+/** Whether two contexts are equal down to the progressions. */
+export function contextsAreEqual(a, b) {
+    return sameDiscretePart(a, b)
+        && b !== undefined
+        && a.currentPageProgression === b.currentPageProgression
+        && a.displayZoneProgression === b.displayZoneProgression
+        && a.contiguousDisplayZoneProgression === b.contiguousDisplayZoneProgression;
+}
+/**
+ * Builds the CSS custom properties carrying a tracked block's progressions.
+ *
+ * Only the continuous fields land here — the discrete ones are `data-` attributes,
+ * written by {@link toTrackedBlockDataAttributes}.
+ *
+ * @param context - The block's current context.
+ * @returns The custom properties, keyed by their full name.
+ */
+export function toTrackedBlockCssProps(context) {
+    return {
+        '--lm-scrllgngn-block-current-page-progression-ratio': `${context.currentPageProgression}`,
+        '--lm-scrllgngn-block-display-zone-progression-ratio': `${context.displayZoneProgression}`,
+        '--lm-scrllgngn-block-contiguous-display-zone-progression-ratio': `${context.contiguousDisplayZoneProgression}`
+    };
+}
+/**
+ * Builds the `data-` attributes carrying a tracked block's discrete position.
+ *
+ * @param context - The block's current context.
+ * @returns The attributes, keyed by their full name.
+ */
+export function toTrackedBlockDataAttributes(context) {
+    return {
+        'data-current-page': `${context.currentPage}`,
+        'data-display-zone': context.displayZone.join(','),
+        'data-index-of-current-page-in-display-zone': `${context.indexOfCurrentPageInDisplayZone}`,
+        'data-contiguous-display-zone': context.contiguousDisplayZone.join(','),
+        'data-index-of-current-page-in-contiguous-display-zone': `${context.indexOfCurrentPageInContiguousDisplayZone}`
+    };
+}
+/**
+ * Keys a tracked sticky block.
+ *
+ * Sticky and scroll blocks share one map of wrappers, and a sticky block is one
+ * element for the whole sequence where a scroll block is one per page — hence two
+ * key shapes rather than a single ambiguous one.
+ *
+ * @param blockId - The id the block was consolidated under.
+ * @returns The key its wrapper is registered as.
+ */
+export function stickyKey(blockId) {
+    return `sticky:${blockId}`;
+}
+/**
+ * Keys a tracked scroll block.
+ *
+ * @param pagePos - Zero-based position of the page it belongs to.
+ * @param blockPos - Its position among that page's scroll blocks.
+ * @returns The key its wrapper is registered as.
+ */
+export function scrollKey(pagePos, blockPos) {
+    return `scroll:${pagePos}:${blockPos}`;
+}
+/**
+ * Picks the blocks of a page that scroll with the content.
+ *
+ * @param page - The page to read.
+ * @returns Its scroll blocks, in order. `depth` left out means `'scroll'`.
+ */
+export function scrollBlocksOf(page) {
+    return page.blocks?.filter(block => block.depth === 'scroll' || block.depth === undefined) ?? [];
+}

package/components/ScrollListener/index.d.ts

@@ -12,6 +12,11 @@ import { type ScrollState } from './utils.js';
  * changed. Receives `undefined` until the first measurement lands.
  * @property onVisibilityChanged - Called on every intersection change, with
  * `true` when the component intersects the viewport.
+ * @property onScrollProgressChanged - Called after the element's vertical outer
+ * scroll progress changed: `0` when it is about to enter the viewport, `1` once
+ * it has fully left it. Never on mount.
+ * @property onScrollDirectionChanged - Called after the document scroll
+ * direction changed, with `'up'` or `'down'`. Never on mount.
  * @property className - Optional additional class name(s) applied to the root element.
  * @property children - React nodes rendered inside the scroll listener container.
  */
@@ -20,6 +25,8 @@ export type Props = PropsWithChildren<WithClassName<{
     stopOnHidden?: boolean;
     onScrollStateChanged?: (scrollState?: ScrollState) => void;
     onVisibilityChanged?: (isVisible: boolean) => void;
+    onScrollProgressChanged?: (progress: number) => void;
+    onScrollDirectionChanged?: (direction: 'up' | 'down') => void;
 }>>;
 /**
  * Exposes scroll metrics — both the document's and its own — as CSS custom