@design-edito/tools 0.5.2 → 0.5.3

package/components/ListLoader/index.d.ts

@@ -22,12 +22,12 @@ import { type Props as ControlledProps } from './index.controlled.js';
  * from the DOM. Applies to load-button activations only, never to retries or
  * stale reloads. Ignored when `pages` is provided.
  * @property fetch - Fetches one page's items. Rejections are reported through
- * `onFetchError` and retried according to `fetchRetriesNb`.
+ * `onPageFetchFailed` and retried according to `fetchRetriesNb`.
  * @property staleAfterMs - Delay after which a loaded page is refetched, counted
  * from its own last successful load. When omitted, pages are never refreshed.
- * @property onFetchSuccess - Called after a page's items have been stored. Not
+ * @property onPageFetched - Called after a page's items have been stored. Not
  * called for a page dropped while its request was in flight.
- * @property onFetchError - Called on every failed attempt, not only once retries
+ * @property onPageFetchFailed - Called on every failed attempt, not only once retries
  * are exhausted. When omitted, failures are logged with `console.warn`.
  * @property fetchRetriesNb - Number of retries after a failed fetch. Defaults to
  * `Infinity`, so a page keeps retrying until it succeeds.
@@ -40,30 +40,30 @@ export type Props<T> = Omit<ControlledProps<T>, 'itemsPages' | 'loadingPages' |
     dropPagesFurtherThan?: number;
     fetch: (page: number) => Promise<T[]>;
     staleAfterMs?: number;
-    onFetchSuccess?: (pagePos: number, items: T[]) => void;
-    onFetchError?: (pagePos: number, error: Error) => void;
+    onPageFetched?: (pagePos: number, items: T[]) => void;
+    onPageFetchFailed?: (pagePos: number, error: Error) => void;
     fetchRetriesNb?: number;
     fetchRetriesDelayMs?: number;
 };
 /**
  * Paginated list abstraction. Fetches the pages it is asked for, keeps them
- * fresh, and drives a {@link ListLoaderControlled} with the result.
+ * fresh, and drives a {@link ControlledListLoader} with the result.
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @see {@link ListLoaderControlled} for the rendered markup and CSS elements.
- * @returns A {@link ListLoaderControlled} fed with the loaded pages.
+ * @see {@link ControlledListLoader} for the rendered markup and CSS elements.
+ * @returns A {@link ControlledListLoader} fed with the loaded pages.
  *
  * @remarks
  * - In controlled mode (`pages` defined), the page set is entirely driven by the
  *   parent. `fillGaps` and `dropPagesFurtherThan` are inert, and load buttons only
- *   report through `onLoadPageClick`.
+ *   report through `onLoadPageClicked`.
  * - In uncontrolled mode, internal state is initialized from `defaultPage` and load
- *   buttons extend the set themselves. `onLoadPageClick` still fires, after the
+ *   buttons extend the set themselves. `onLoadPageClicked` still fires, after the
  *   internal state has been updated.
  * - A page removed from the effective set is dropped from memory, and a request
  *   still in flight for it is discarded on arrival rather than re-inserted.
  * - No page outside `firstPagePos`–`lastPagePos` is ever fetched, whichever mode
  *   is in use.
  */
-export declare const ListLoader: <T>({ className, pages, defaultPage, fillGaps, dropPagesFurtherThan, autoLoadPrevWhenVisible, autoLoadNextWhenVisible, firstPagePos, lastPagePos, fetch, filter, display, getIdentifier, onLoadPageClick, staleAfterMs, onFetchSuccess, onFetchError, fetchRetriesNb, fetchRetriesDelayMs }: Props<T>) => ReactNode;
+export declare const ListLoader: <T>({ className, pages, defaultPage, fillGaps, dropPagesFurtherThan, autoLoadPrevWhenVisible, autoLoadNextWhenVisible, firstPagePos, lastPagePos, fetch, filter, display, getIdentifier, onLoadPageClicked, staleAfterMs, onPageFetched, onPageFetchFailed, fetchRetriesNb, fetchRetriesDelayMs }: Props<T>) => ReactNode;

package/components/ListLoader/index.js

@@ -2,30 +2,30 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { toError } from '../../agnostic/misc/cast/index.js';
 import { clamp } from '../../agnostic/numbers/clamp/index.js';
-import { ListLoaderControlled } from './index.controlled.js';
+import { ControlledListLoader } from './index.controlled.js';
 import { rangeBetween } from './utils.js';
 /**
  * Paginated list abstraction. Fetches the pages it is asked for, keeps them
- * fresh, and drives a {@link ListLoaderControlled} with the result.
+ * fresh, and drives a {@link ControlledListLoader} with the result.
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @see {@link ListLoaderControlled} for the rendered markup and CSS elements.
- * @returns A {@link ListLoaderControlled} fed with the loaded pages.
+ * @see {@link ControlledListLoader} for the rendered markup and CSS elements.
+ * @returns A {@link ControlledListLoader} fed with the loaded pages.
  *
  * @remarks
  * - In controlled mode (`pages` defined), the page set is entirely driven by the
  *   parent. `fillGaps` and `dropPagesFurtherThan` are inert, and load buttons only
- *   report through `onLoadPageClick`.
+ *   report through `onLoadPageClicked`.
  * - In uncontrolled mode, internal state is initialized from `defaultPage` and load
- *   buttons extend the set themselves. `onLoadPageClick` still fires, after the
+ *   buttons extend the set themselves. `onLoadPageClicked` still fires, after the
  *   internal state has been updated.
  * - A page removed from the effective set is dropped from memory, and a request
  *   still in flight for it is discarded on arrival rather than re-inserted.
  * - No page outside `firstPagePos`–`lastPagePos` is ever fetched, whichever mode
  *   is in use.
  */
-export const ListLoader = ({ className, pages, defaultPage, fillGaps = true, dropPagesFurtherThan, autoLoadPrevWhenVisible, autoLoadNextWhenVisible, firstPagePos, lastPagePos, fetch, filter, display, getIdentifier, onLoadPageClick, staleAfterMs, onFetchSuccess, onFetchError, fetchRetriesNb = Infinity, fetchRetriesDelayMs = 1000 }) => {
+export const ListLoader = ({ className, pages, defaultPage, fillGaps = true, dropPagesFurtherThan, autoLoadPrevWhenVisible, autoLoadNextWhenVisible, firstPagePos, lastPagePos, fetch, filter, display, getIdentifier, onLoadPageClicked, staleAfterMs, onPageFetched, onPageFetchFailed, fetchRetriesNb = Infinity, fetchRetriesDelayMs = 1000 }) => {
     const [itemsPages, setItemsPages] = useState(new Map());
     const [loadingPages, setLoadingPages] = useState(new Set());
     const [internalPages, setInternalPages] = useState([
@@ -45,7 +45,7 @@ export const ListLoader = ({ className, pages, defaultPage, fillGaps = true, dro
                 return kept.length === next.length ? next : kept;
             });
         }
-        onLoadPageClick?.(pagePos);
+        onLoadPageClicked?.(pagePos);
     };
     const storePage = (page, items) => setItemsPages(curr => {
         const next = new Map(curr);
@@ -62,8 +62,8 @@ export const ListLoader = ({ className, pages, defaultPage, fillGaps = true, dro
     });
     const reportFetchError = (page, err) => {
         const error = toError(err);
-        if (onFetchError !== undefined)
-            return onFetchError(page, error);
+        if (onPageFetchFailed !== undefined)
+            return onPageFetchFailed(page, error);
         // eslint-disable-next-line no-console
         console.warn(`ListLoader failed to fetch page ${page}`, error);
     };
@@ -78,7 +78,7 @@ export const ListLoader = ({ className, pages, defaultPage, fillGaps = true, dro
             if (!requestedPages.current.has(page))
                 return;
             storePage(page, items);
-            onFetchSuccess?.(page, items);
+            onPageFetched?.(page, items);
             setPageLoading(page, false);
         })
             .catch((err) => {
@@ -142,5 +142,5 @@ export const ListLoader = ({ className, pages, defaultPage, fillGaps = true, dro
     const controlledItemsPages = new Map(Array
         .from(itemsPages)
         .map(([page, { items }]) => [page, items]));
-    return _jsx(ListLoaderControlled, { className: className, pages: currentPages, firstPagePos: firstPagePos, lastPagePos: lastPagePos, itemsPages: controlledItemsPages, filter: filter, display: display, getIdentifier: getIdentifier, loadingPages: Array.from(loadingPages), onLoadPageClick: handleLoadClick, autoLoadPrevWhenVisible: autoLoadPrevWhenVisible, autoLoadNextWhenVisible: autoLoadNextWhenVisible });
+    return _jsx(ControlledListLoader, { className: className, pages: currentPages, firstPagePos: firstPagePos, lastPagePos: lastPagePos, itemsPages: controlledItemsPages, filter: filter, display: display, getIdentifier: getIdentifier, loadingPages: Array.from(loadingPages), onLoadPageClicked: handleLoadClick, autoLoadPrevWhenVisible: autoLoadPrevWhenVisible, autoLoadNextWhenVisible: autoLoadNextWhenVisible });
 };

package/components/Overlayer/index.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { clss } from '../../agnostic/css/clss/index.js';
 import { isFalsy } from '../../agnostic/booleans/is-falsy/index.js';
 import { mergeClassNames } from '../utils/index.js';
-import { overlayer as publicClassname } from '../public-classnames.js';
+import { overlayer as publicClassName } from '../public-classnames.js';
 import cssModule from './styles.module.css';
 /**
  * Absolute positioning overlay component. Renders a base content layer and
@@ -27,10 +27,10 @@ import cssModule from './styles.module.css';
  * @returns A root `<div>` containing the base layer and all positioned overlay elements.
  */
 export const Overlayer = ({ overlays, children, className }) => {
-    const c = clss(publicClassname, { cssModule });
+    const c = clss(publicClassName, { cssModule });
     const rootClss = mergeClassNames(c(), className);
     const baseClss = c('base');
-    return _jsxs("div", { className: rootClss, children: [_jsx("div", { className: baseClss, children: children }), overlays?.map(({ content, xPercent = 0, yPercent = 0, justify }) => {
+    return _jsxs("div", { className: rootClss, children: [_jsx("div", { className: baseClss, children: children }), overlays?.map(({ content, xPercent = 0, yPercent = 0, justify }, overlayPos) => {
                 const overlayClss = c('overlay');
                 let computedTranslateX;
                 if (typeof justify === 'number') {
@@ -55,6 +55,6 @@ export const Overlayer = ({ overlays, children, className }) => {
                 };
                 if (isFalsy(content))
                     return null;
-                return _jsx("div", { className: overlayClss, style: overlayCustomProps, children: content });
+                return _jsx("div", { className: overlayClss, style: overlayCustomProps, children: content }, overlayPos);
             })] });
 };

package/components/Paginator/index.d.ts

@@ -27,23 +27,18 @@ type DirectionState = 'forwards' | 'backwards' | null;
  * the {@link IntersectionObserver} root margin. Determines how far into the viewport
  * a page must be before it is considered `'curr'`. Defaults to `0`.
  *
- * @property stateHandlers - Callbacks called after the internal state changed
- * @property stateHandlers.directionChanged - Callback invoked when the scroll direction changes.
- * Receives the new {@link DirectionState}. Only fires when the direction actually
- * changes — repeated scrolls in the same direction do not trigger it again.
- *
- * @property stateHandlers.pageChanged - Callback invoked whenever any page's {@link PageState}
- * changes. Receives a flat array of all pages' states, ordered by position.
- *
+ * @property onDirectionChanged - Called after the scroll direction changed, with
+ * the new {@link DirectionState}. Repeated scrolls in the same direction do not
+ * trigger it again.
+ * @property onPagesChanged - Called after any page's {@link PageState} changed,
+ * with a flat array of every page's state, ordered by position.
  * @property className - Optional additional class name(s) applied to the root element.
  * @property children - Each direct child is treated as an individual page slot.
  */
 export type Props = PropsWithChildren<WithClassName<{
     thresholdOffsetPercent?: number;
-    stateHandlers?: {
-        directionChanged?: (direction: DirectionState) => void;
-        pageChanged?: (pages: PageState[]) => void;
-    };
+    onDirectionChanged?: (direction: DirectionState) => void;
+    onPagesChanged?: (pages: PageState[]) => void;
 }>>;
 /**
  * A scroll-driven pagination component that tracks which child page is currently

package/components/Paginator/index.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useRef, Children, useState } from 'react';
 import { clss } from '../../agnostic/css/clss/index.js';
-import { mergeClassNames } from '../utils/index.js';
+import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
 import { paginator as publicClassName } from '../public-classnames.js';
 import cssModule from './styles.module.css';
 /**
@@ -27,21 +27,17 @@ import cssModule from './styles.module.css';
  * - `currCount` on each {@link PageState} increments each time a page transitions
  *   into the `'curr'` position, making it useful as a re-entry counter.
  */
-export const Paginator = ({ thresholdOffsetPercent, stateHandlers, className, children }) => {
+export const Paginator = ({ thresholdOffsetPercent, onDirectionChanged, onPagesChanged, className, children }) => {
     // State, refs, effects
     const [pagesState, setPagesState] = useState(new Map());
     const [directionState, setDirectionState] = useState(null);
     const pagesRef = useRef(null);
     const directionRef = useRef(null);
-    // State change handlers
-    useEffect(() => {
-        stateHandlers?.pageChanged?.(Array
-            .from(pagesState)
-            .map(([, state]) => state));
-    }, [pagesState]);
-    useEffect(() => {
-        stateHandlers?.directionChanged?.(directionState);
-    }, [directionState]);
+    // State dispatch
+    useChangeDispatch(pagesState, pages => onPagesChanged?.(Array
+        .from(pages)
+        .map(([, pageState]) => pageState)));
+    useChangeDispatch(directionState, onDirectionChanged);
     // Catch scroll direction listening on scroll events
     useEffect(() => {
         let lastCall = 0;

package/components/ResizeObserver/index.d.ts

@@ -16,9 +16,20 @@ export type Props = PropsWithChildren<WithClassName<{
     onResized?: (entry: ROEntryWithBoundingRect) => void;
 }>>;
 /**
- * Component that observes its own size changes and exposes the dimensions.
- * Updates are exposed both via data attributes (e.g., `data-width`) and CSS custom properties
- * (e.g., `--<prefix>-width`, `--<prefix>-width-px`) for styling or scripting purposes.
+ * Component that observes its own size changes and exposes the measured content
+ * rect on its root element. Both sets stay absent until the first measurement
+ * lands.
+ *
+ * ### Data attributes
+ * `data-x`, `data-y`, `data-top`, `data-left`, `data-bottom`, `data-right`,
+ * `data-width` and `data-height` — the content rect, as plain numbers.
+ *
+ * ### CSS custom properties
+ * The same eight measurements, each exposed twice: `--lm-resize-observer-width`
+ * carries the ready-to-use `px` length, `--lm-resize-observer-width-raw` the
+ * plain number for `calc()`. Same pattern for `-x`, `-y`, `-top`, `-left`,
+ * `-bottom`, `-right` and `-height`.
+ *
  * @param props - Component properties
  * @see {@link Props}
  * @returns A div wrapping `children`, with resize observation applied.

package/components/ResizeObserver/index.js

@@ -3,11 +3,22 @@ import { useRef, useEffect, useState } from 'react';
 import { clss } from '../../agnostic/css/clss/index.js';
 import { mergeClassNames } from '../utils/index.js';
 import { resizeObserver as publicClassName } from '../public-classnames.js';
-import cssModule from './style.module.css';
+import cssModule from './styles.module.css';
 /**
- * Component that observes its own size changes and exposes the dimensions.
- * Updates are exposed both via data attributes (e.g., `data-width`) and CSS custom properties
- * (e.g., `--<prefix>-width`, `--<prefix>-width-px`) for styling or scripting purposes.
+ * Component that observes its own size changes and exposes the measured content
+ * rect on its root element. Both sets stay absent until the first measurement
+ * lands.
+ *
+ * ### Data attributes
+ * `data-x`, `data-y`, `data-top`, `data-left`, `data-bottom`, `data-right`,
+ * `data-width` and `data-height` — the content rect, as plain numbers.
+ *
+ * ### CSS custom properties
+ * The same eight measurements, each exposed twice: `--lm-resize-observer-width`
+ * carries the ready-to-use `px` length, `--lm-resize-observer-width-raw` the
+ * plain number for `calc()`. Same pattern for `-x`, `-y`, `-top`, `-left`,
+ * `-bottom`, `-right` and `-height`.
+ *
  * @param props - Component properties
  * @see {@link Props}
  * @returns A div wrapping `children`, with resize observation applied.
@@ -43,27 +54,41 @@ export const ResizeObserverComponent = ({ className, onResized, children }) => {
         return () => observerRef.current?.disconnect();
     }, [onResized]);
     // Data attributes, CSS custom props & Rendering
-    const { x, y, top, left, bottom, right, width, height } = roEntry?.entry.contentRect ?? {};
-    const contentRect = { x, y, top, left, bottom, right, width, height };
-    const dataAttributes = Object
-        .entries(contentRect)
-        .reduce((acc, [key, val]) => {
-        if (val === undefined)
-            return acc;
-        return { ...acc, [`data-${key}`]: val.toString() };
-    }, {});
-    const cssCustomProps = Object
-        .entries(contentRect)
-        .reduce((acc, [key, val]) => {
-        if (val === undefined)
-            return acc;
-        return {
-            ...acc,
-            [`--${publicClassName}-${key}`]: val.toString(),
-            [`--${publicClassName}-${key}-px`]: `${val.toString()}px`
+    const contentRect = roEntry?.entry.contentRect;
+    let dataAttributes = {};
+    let cssCustomProps = {};
+    if (contentRect !== undefined) {
+        const { x, y, top, left, bottom, right, width, height } = contentRect;
+        dataAttributes = {
+            'data-x': `${x}`,
+            'data-y': `${y}`,
+            'data-top': `${top}`,
+            'data-left': `${left}`,
+            'data-bottom': `${bottom}`,
+            'data-right': `${right}`,
+            'data-width': `${width}`,
+            'data-height': `${height}`
         };
-    }, {});
+        cssCustomProps = {
+            '--lm-resize-observer-x': `${x}px`,
+            '--lm-resize-observer-x-raw': `${x}`,
+            '--lm-resize-observer-y': `${y}px`,
+            '--lm-resize-observer-y-raw': `${y}`,
+            '--lm-resize-observer-top': `${top}px`,
+            '--lm-resize-observer-top-raw': `${top}`,
+            '--lm-resize-observer-left': `${left}px`,
+            '--lm-resize-observer-left-raw': `${left}`,
+            '--lm-resize-observer-bottom': `${bottom}px`,
+            '--lm-resize-observer-bottom-raw': `${bottom}`,
+            '--lm-resize-observer-right': `${right}px`,
+            '--lm-resize-observer-right-raw': `${right}`,
+            '--lm-resize-observer-width': `${width}px`,
+            '--lm-resize-observer-width-raw': `${width}`,
+            '--lm-resize-observer-height': `${height}px`,
+            '--lm-resize-observer-height-raw': `${height}`
+        };
+    }
     const c = clss(publicClassName, { cssModule });
-    const rootClss = mergeClassNames(c(null), className);
+    const rootClss = mergeClassNames(c(), className);
     return _jsx("div", { ...dataAttributes, className: rootClss, ref: rootRef, style: { ...cssCustomProps }, children: children });
 };

package/components/Scrllgngn/index.d.ts

@@ -71,10 +71,8 @@ export type PropsPage = {
  * - `'after'`  — forces blocks from pages after the current one.
  * - `'both'`   — forces blocks on both sides.
  * - `'none'`   — no forcing (default behaviour).
- * @property stateHandlers - Optional callbacks invoked in response to
- * component state changes.
- * @property stateHandlers.pageChanged - Called whenever the current page
- * changes. Receives the zero-based index of the current page and the
+ * @property onPageChanged - Called once the current page has changed, never on
+ * mount. Receives the zero-based index of the new current page and the
  * corresponding page definition, if available.
  * @property className - Optional additional class name(s) applied to the root
  * element.
@@ -84,9 +82,7 @@ export type Props = WithClassName<{
     thresholdOffsetPercent?: number;
     stickyBlocksLazyLoadDistance?: number;
     forceStickBlocks?: 'before' | 'after' | 'both' | 'none';
-    stateHandlers?: {
-        pageChanged?: (currentPagePos: number, pageData?: PropsPage) => void;
-    };
+    onPageChanged?: (currentPagePos: number, pageData?: PropsPage) => void;
 }>;
 /**
  * Scrollytelling engine component. Orchestrates layered sticky blocks (`back`
@@ -104,16 +100,24 @@ export type Props = WithClassName<{
  * - `--force-stick-blocks-both` — when `forceStickBlocks === 'both'`.
  *
  * ### Data attributes
- * - `data-current-page-pos` — zero-based index of the page currently in view,
- * updated on every page change reported by the internal {@link Paginator}.
+ * Both are updated on every page change reported by the internal
+ * {@link Paginator}.
+ * - `data-current-page-pos` — zero-based index of the page currently in view.
+ * - `data-current-page-id` — that page's {@link PropsPage.id}. Absent while the
+ * current page carries no id, since the id is optional.
  *
  * ### CSS custom properties
  * Exposed on the root element and updated on resize via the internal
  * {@link ResizeObserverComponent}:
- * - `--scrllgngn-screen-left` / `--PRIVATE-left` — left edge of the bounding rect (px).
- * - `--scrllgngn-screen-right` / `--PRIVATE-right` — right edge (px).
- * - `--scrllgngn-screen-width` / `--PRIVATE-width` — total width (px).
- * - `--scrllgngn-screen-height` / `--PRIVATE-height` — total height (px).
+ * - `--lm-scrllgngn-screen-left` / `--lm-scrllgngn-screen-left-raw` — left edge
+ * of the bounding rect.
+ * - `--lm-scrllgngn-screen-right` / `--lm-scrllgngn-screen-right-raw` — right edge.
+ * - `--lm-scrllgngn-screen-width` / `--lm-scrllgngn-screen-width-raw` — total width.
+ * - `--lm-scrllgngn-screen-height` / `--lm-scrllgngn-screen-height-raw` — total height.
+ *
+ * The same four measurements are also exposed as `--PRIVATE-left`, `-right`,
+ * `-width` and `-height` for the component's own stylesheet. They are internal:
+ * do not read or override them.
  *
  * ### Sticky block elements
  * Each lazy-loaded sticky block receives:

package/components/Scrllgngn/index.js

@@ -1,12 +1,12 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState, useEffect } 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 { mergeClassNames } from '../utils/index.js';
+import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
 import { scrllgngn as publicClassName } from '../public-classnames.js';
+import { consolidateStickyBlocks, lazyLoadedBlocks, toScreenCssProps } from './utils.js';
 import cssModule from './styles.module.css';
 /**
  * Scrollytelling engine component. Orchestrates layered sticky blocks (`back`
@@ -24,16 +24,24 @@ import cssModule from './styles.module.css';
  * - `--force-stick-blocks-both` — when `forceStickBlocks === 'both'`.
  *
  * ### Data attributes
- * - `data-current-page-pos` — zero-based index of the page currently in view,
- * updated on every page change reported by the internal {@link Paginator}.
+ * Both are updated on every page change reported by the internal
+ * {@link Paginator}.
+ * - `data-current-page-pos` — zero-based index of the page currently in view.
+ * - `data-current-page-id` — that page's {@link PropsPage.id}. Absent while the
+ * current page carries no id, since the id is optional.
  *
  * ### CSS custom properties
  * Exposed on the root element and updated on resize via the internal
  * {@link ResizeObserverComponent}:
- * - `--scrllgngn-screen-left` / `--PRIVATE-left` — left edge of the bounding rect (px).
- * - `--scrllgngn-screen-right` / `--PRIVATE-right` — right edge (px).
- * - `--scrllgngn-screen-width` / `--PRIVATE-width` — total width (px).
- * - `--scrllgngn-screen-height` / `--PRIVATE-height` — total height (px).
+ * - `--lm-scrllgngn-screen-left` / `--lm-scrllgngn-screen-left-raw` — left edge
+ * of the bounding rect.
+ * - `--lm-scrllgngn-screen-right` / `--lm-scrllgngn-screen-right-raw` — right edge.
+ * - `--lm-scrllgngn-screen-width` / `--lm-scrllgngn-screen-width-raw` — total width.
+ * - `--lm-scrllgngn-screen-height` / `--lm-scrllgngn-screen-height-raw` — total height.
+ *
+ * The same four measurements are also exposed as `--PRIVATE-left`, `-right`,
+ * `-width` and `-height` for the component's own stylesheet. They are internal:
+ * do not read or override them.
  *
  * ### Sticky block elements
  * Each lazy-loaded sticky block receives:
@@ -48,7 +56,7 @@ import cssModule from './styles.module.css';
  * back-blocks layer, front-blocks layer, paginated scrolling content, and
  * bottom-bound sentinel.
  */
-export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadDistance = 2, forceStickBlocks, stateHandlers, className }) => {
+export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadDistance = 2, forceStickBlocks, onPageChanged, className }) => {
     // State
     const [topVisible, setTopVis] = useState(false);
     const [contentVisible, setCntVis] = useState(false);
@@ -58,69 +66,20 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
     const [partialBoundingRect, setPartialBoundingRect] = useState();
     // Sticky blocks calculations
     useEffect(() => {
-        const consolidatedBlocks = new Map();
-        for (const page of pages ?? []) {
-            const pageIndex = pages?.indexOf(page) ?? -1;
-            for (const block of page.blocks ?? []) {
-                const blockId = block.id ?? randomHash(12);
-                const found = consolidatedBlocks.get(blockId);
-                if (found !== undefined)
-                    consolidatedBlocks.set(blockId, {
-                        ...found,
-                        ...block,
-                        displayOnPages: [
-                            ...found.displayOnPages,
-                            pageIndex
-                        ]
-                    });
-                else
-                    consolidatedBlocks.set(blockId, {
-                        ...block,
-                        displayOnPages: [pageIndex]
-                    });
-            }
-        }
-        const consolidatedStickyBlocks = new Map(Array
-            .from(consolidatedBlocks)
-            .filter((e) => {
-            const block = e[1];
-            return block.depth === 'back'
-                || block.depth === 'front';
-        }));
-        setStickyBlocks(consolidatedStickyBlocks);
+        setStickyBlocks(consolidateStickyBlocks(pages));
     }, [pages]);
-    const lazyLoadedBackBlocks = Array
-        .from(stickyBlocks)
-        .filter(([, block]) => block.depth === 'back'
-        && block.displayOnPages.some(dispPage => {
-            const absDiff = Math.abs(dispPage - currentPagePos);
-            return absDiff <= stickyBlocksLazyLoadDistance;
-        })).map(([, block]) => block)
-        .sort((a, b) => {
-        return (a.zIndex ?? -Infinity) - (b.zIndex ?? -Infinity);
-    });
-    const lazyLoadedFrontBlocks = Array
-        .from(stickyBlocks)
-        .filter(([, block]) => block.depth === 'front'
-        && block.displayOnPages.some(dispPage => {
-            const absDiff = Math.abs(dispPage - currentPagePos);
-            return absDiff <= stickyBlocksLazyLoadDistance;
-        })).map(([, block]) => block)
-        .sort((a, b) => {
-        return (a.zIndex ?? -Infinity) - (b.zIndex ?? -Infinity);
-    });
+    const lazyLoadedBackBlocks = lazyLoadedBlocks(stickyBlocks, 'back', currentPagePos, stickyBlocksLazyLoadDistance);
+    const lazyLoadedFrontBlocks = lazyLoadedBlocks(stickyBlocks, 'front', currentPagePos, stickyBlocksLazyLoadDistance);
     // Handlers
+    useChangeDispatch(currentPagePos, pagePos => onPageChanged?.(pagePos, pages?.[pagePos]));
     const handleTopBoundDetect = e => setTopVis(e.ioEntry?.isIntersecting ?? false);
     const handleCntDetect = e => setCntVis(e.ioEntry?.isIntersecting ?? false);
     const handleBtmBoundDetect = e => setBtmVis(e.ioEntry?.isIntersecting ?? false);
-    const handlePageChange = statePages => {
+    const handlePagesChanged = statePages => {
         const curPagePos = statePages.findIndex(page => page.position === 'curr');
         if (curPagePos === -1)
             return;
-        if (curPagePos === currentPagePos)
-            return;
         setCurrentPagePos(curPagePos);
-        stateHandlers?.pageChanged?.(curPagePos, pages?.[curPagePos]);
     };
     const handleResize = ({ boundingClientRect }) => {
         if (partialBoundingRect === undefined
@@ -140,24 +99,8 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
         'force-stick-blocks-after': forceStickBlocks === 'after',
         'force-stick-blocks-both': forceStickBlocks === 'both'
     }), className);
-    const customCssProps = {};
-    if (partialBoundingRect?.left !== undefined) {
-        customCssProps[`--${publicClassName}-screen-left`] = `${partialBoundingRect.left}px`;
-        customCssProps['--PRIVATE-left'] = `${partialBoundingRect.left}px`;
-    }
-    if (partialBoundingRect?.right !== undefined) {
-        customCssProps[`--${publicClassName}-screen-right`] = `${partialBoundingRect.right}px`;
-        customCssProps['--PRIVATE-right'] = `${partialBoundingRect.right}px`;
-    }
-    if (partialBoundingRect?.width !== undefined) {
-        customCssProps[`--${publicClassName}-screen-width`] = `${partialBoundingRect.width}px`;
-        customCssProps['--PRIVATE-width'] = `${partialBoundingRect.width}px`;
-    }
-    if (partialBoundingRect?.height !== undefined) {
-        customCssProps[`--${publicClassName}-screen-height`] = `${partialBoundingRect.height}px`;
-        customCssProps['--PRIVATE-height'] = `${partialBoundingRect.height}px`;
-    }
-    return _jsx("div", { className: rootClss, "data-current-page-pos": currentPagePos, 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) => {
+    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) => {
                         const isActive = block.displayOnPages.includes(currentPagePos);
                         const blockClss = c('back-block', {
                             active: isActive,
@@ -171,9 +114,7 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
                             '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, stateHandlers: {
-                                pageChanged: handlePageChange
-                            }, children: pages?.map(page => {
+                    }) }), _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

package/components/Scrllgngn/utils.d.ts

@@ -0,0 +1,52 @@
+import type { PropsPage, PropsStickyBlock } from './index.js';
+/** The subset of a bounding rect a {@link Scrllgngn} tracks and exposes. */
+export type ScreenRect = {
+    left: number;
+    right: number;
+    width: number;
+    height: number;
+};
+/** Zero-based positions of the pages a consolidated block is displayed on. */
+export type BlockConsolidatedData = {
+    displayOnPages: number[];
+};
+/** A sticky block, merged across every page it appears on. */
+export type ConsolidatedStickyBlock = PropsStickyBlock & BlockConsolidatedData;
+/**
+ * Merges the sticky blocks of every page into a single entry per block id.
+ *
+ * A block repeated across pages under the same `id` becomes one sticky block
+ * listing all the pages it shows on, so it stays mounted across them instead of
+ * being torn down and rebuilt at every page change. Blocks without an `id` get a
+ * random one and are therefore never merged.
+ *
+ * @param pages - The pages to walk, in order.
+ * @returns The sticky blocks, keyed by id. Scroll blocks are left out.
+ */
+export declare function consolidateStickyBlocks(pages?: PropsPage[]): Map<string, ConsolidatedStickyBlock>;
+/**
+ * Picks the sticky blocks of one layer close enough to the current page to be
+ * worth mounting.
+ *
+ * @param blocks - Every consolidated sticky block.
+ * @param depth - The layer to pick from.
+ * @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`.
+ */
+export declare function lazyLoadedBlocks(blocks: Map<string, ConsolidatedStickyBlock>, depth: 'back' | 'front', currentPagePos: number, lazyLoadDistance: number): ConsolidatedStickyBlock[];
+/**
+ * Builds the CSS custom properties exposed on a {@link Scrllgngn} root.
+ *
+ * The public `screen-*` set follows the usual convention and stays absent until
+ * the first measurement lands. The `--PRIVATE-*` set is what the component's own
+ * stylesheet positions its fixed layers with, and it is emitted from the very
+ * first render — as `initial`, the guaranteed-invalid value — so those layers can
+ * never inherit the same names from an ancestor component. `initial` leaves them
+ * behaving exactly as an unset variable would, without opening the hole.
+ *
+ * @param rect - The measured bounding rect, absent until the first resize lands.
+ * @returns The custom properties, keyed by their full name.
+ */
+export declare function toScreenCssProps(rect?: ScreenRect): Record<string, string>;