@design-edito/tools 0.5.1 → 0.5.3

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>;

package/components/Scrllgngn/utils.js

@@ -0,0 +1,102 @@
+import { randomHash } from '../../agnostic/random/uuid/index.js';
+/**
+ * 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 function consolidateStickyBlocks(pages) {
+    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]
+                });
+        }
+    }
+    return new Map(Array
+        .from(consolidatedBlocks)
+        .filter((e) => {
+        const block = e[1];
+        return block.depth === 'back'
+            || block.depth === 'front';
+    }));
+}
+/**
+ * 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 function lazyLoadedBlocks(blocks, depth, currentPagePos, lazyLoadDistance) {
+    return Array
+        .from(blocks)
+        .map(([, block]) => block)
+        .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));
+}
+/**
+ * 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 function toScreenCssProps(rect) {
+    const publicProps = rect === undefined
+        ? {}
+        : {
+            '--lm-scrllgngn-screen-left': `${rect.left}px`,
+            '--lm-scrllgngn-screen-left-raw': `${rect.left}`,
+            '--lm-scrllgngn-screen-right': `${rect.right}px`,
+            '--lm-scrllgngn-screen-right-raw': `${rect.right}`,
+            '--lm-scrllgngn-screen-width': `${rect.width}px`,
+            '--lm-scrllgngn-screen-width-raw': `${rect.width}`,
+            '--lm-scrllgngn-screen-height': `${rect.height}px`,
+            '--lm-scrllgngn-screen-height-raw': `${rect.height}`
+        };
+    return {
+        ...publicProps,
+        '--PRIVATE-left': toPrivateLength(rect?.left),
+        '--PRIVATE-right': toPrivateLength(rect?.right),
+        '--PRIVATE-width': toPrivateLength(rect?.width),
+        '--PRIVATE-height': toPrivateLength(rect?.height)
+    };
+}
+function toPrivateLength(value) {
+    return value === undefined ? 'initial' : `${value}px`;
+}

package/components/ScrollListener/index.d.ts

@@ -2,46 +2,61 @@ import { type FunctionComponent, type PropsWithChildren } from 'react';
 import type { WithClassName } from '../utils/types.js';
 import { type ScrollState } from './utils.js';
 /**
- * Props for the ScrollListener component.
+ * Props for the {@link ScrollListener} component.
  *
- * @property startOnVisible - When `true`, scroll tracking starts only when the component
- * becomes visible in the viewport. Visibility is detected using an IntersectionObserver.
- * @property stopOnHidden - When `true`, scroll tracking stops when the component leaves
- * the viewport.
- * @property stateHandlers - Optional callbacks invoked when internal state changes.
- * @property stateHandlers.scrollDataChanged - Called whenever the computed scroll data
- * changes. Receives the current {@link ScrollState} or `undefined`.
- * @property stateHandlers.visibilityChanged - Called when the visibility state of the
- * component changes. Receives `true` when the component is intersecting the viewport,
- * otherwise `false`.
+ * @property startOnVisible - When `true`, scroll tracking only starts once the
+ * component enters the viewport, instead of on mount.
+ * @property stopOnHidden - When `true`, scroll tracking stops when the component
+ * leaves the viewport.
+ * @property onScrollStateChanged - Called after the measured {@link ScrollState}
+ * changed. Receives `undefined` until the first measurement lands.
+ * @property onVisibilityChanged - Called on every intersection change, with
+ * `true` when the component intersects the viewport.
  * @property className - Optional additional class name(s) applied to the root element.
  * @property children - React nodes rendered inside the scroll listener container.
  */
 export type Props = PropsWithChildren<WithClassName<{
-    stopOnHidden?: boolean;
     startOnVisible?: boolean;
-    stateHandlers?: {
-        scrollDataChanged?: (scrollData?: ScrollState) => void;
-        visibilityChanged?: (isVisible: boolean) => void;
-    };
+    stopOnHidden?: boolean;
+    onScrollStateChanged?: (scrollState?: ScrollState) => void;
+    onVisibilityChanged?: (isVisible: boolean) => void;
 }>>;
 /**
- * Component that listens to global scroll events and exposes scroll-related data
- * through CSS custom properties and optional state callbacks.
+ * Exposes scroll metrics — both the document's and its own — as CSS custom
+ * properties on its root element, so scroll-driven styling needs no JavaScript
+ * of its own.
  *
- * The component measures both global scroll metrics (window size, document size,
- * scroll offsets) and local metrics relative to the component (dimensions and
- * position within the document).
+ * ### CSS custom properties on the root element
+ * Each measurement comes as a `px` length under its bare name, and as a `-raw`
+ * twin holding the plain number:
+ * - `--lm-scroll-listener-window-width`, `--lm-scroll-listener-window-height`
+ * - `--lm-scroll-listener-html-width`, `--lm-scroll-listener-html-height`
+ * - `--lm-scroll-listener-scroll-x`, `--lm-scroll-listener-scroll-y`
+ * - `--lm-scroll-listener-width`, `--lm-scroll-listener-height`
+ * - `--lm-scroll-listener-offset-x`, `--lm-scroll-listener-offset-y`
  *
- * Computed values are exposed as CSS variables on the root element, enabling
- * scroll-driven styling without additional JavaScript.
- *
- * Scroll observation can optionally start only when the component becomes visible
- * and stop when it leaves the viewport.
+ * Ratios are unitless and have no twin:
+ * - `--lm-scroll-listener-window-scrolled-x-ratio`,
+ *   `--lm-scroll-listener-window-scrolled-y-ratio` — how far the document is
+ *   scrolled.
+ * - `--lm-scroll-listener-self-inner-scrolled-x-ratio`,
+ *   `--lm-scroll-listener-self-inner-scrolled-y-ratio` — `0` when the element's
+ *   start edge meets the viewport's start edge, `1` when its end edge meets the
+ *   viewport's end edge. The span where it is fully visible.
+ * - `--lm-scroll-listener-self-outer-scrolled-x-ratio`,
+ *   `--lm-scroll-listener-self-outer-scrolled-y-ratio` — `0` when the element is
+ *   about to enter the viewport, `1` once it has fully left it. The span where it
+ *   overlaps the viewport at all.
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A container element exposing scroll metrics through CSS variables and
- * wrapping its children inside an IntersectionObserver boundary.
+ * @returns A container exposing the metrics, wrapping its children inside an
+ * {@link IntersectionObserverComponent}.
+ *
+ * @remarks
+ * All mounted instances share a single pair of `scroll` / `resize` listeners and
+ * a single measurement pass per animation frame — the document is measured once
+ * for everyone, each element only for itself. The listeners exist only while at
+ * least one instance is tracking.
  */
 export declare const ScrollListener: FunctionComponent<Props>;

package/components/ScrollListener/index.js

@@ -1,100 +1,80 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useRef, useState, useCallback } 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 { mergeClassNames } from '../utils/index.js';
 import { IntersectionObserverComponent } from '../IntersectionObserver/index.js';
+import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
 import { scrollListener as publicClassName } from '../public-classnames.js';
-import { register, unregister } from './utils.js';
+import { subscribe, toScrollCssProps, unsubscribe } from './utils.js';
 import cssModule from './styles.module.css';
 /**
- * Component that listens to global scroll events and exposes scroll-related data
- * through CSS custom properties and optional state callbacks.
+ * Exposes scroll metrics — both the document's and its own — as CSS custom
+ * properties on its root element, so scroll-driven styling needs no JavaScript
+ * of its own.
  *
- * The component measures both global scroll metrics (window size, document size,
- * scroll offsets) and local metrics relative to the component (dimensions and
- * position within the document).
+ * ### CSS custom properties on the root element
+ * Each measurement comes as a `px` length under its bare name, and as a `-raw`
+ * twin holding the plain number:
+ * - `--lm-scroll-listener-window-width`, `--lm-scroll-listener-window-height`
+ * - `--lm-scroll-listener-html-width`, `--lm-scroll-listener-html-height`
+ * - `--lm-scroll-listener-scroll-x`, `--lm-scroll-listener-scroll-y`
+ * - `--lm-scroll-listener-width`, `--lm-scroll-listener-height`
+ * - `--lm-scroll-listener-offset-x`, `--lm-scroll-listener-offset-y`
  *
- * Computed values are exposed as CSS variables on the root element, enabling
- * scroll-driven styling without additional JavaScript.
- *
- * Scroll observation can optionally start only when the component becomes visible
- * and stop when it leaves the viewport.
+ * Ratios are unitless and have no twin:
+ * - `--lm-scroll-listener-window-scrolled-x-ratio`,
+ *   `--lm-scroll-listener-window-scrolled-y-ratio` — how far the document is
+ *   scrolled.
+ * - `--lm-scroll-listener-self-inner-scrolled-x-ratio`,
+ *   `--lm-scroll-listener-self-inner-scrolled-y-ratio` — `0` when the element's
+ *   start edge meets the viewport's start edge, `1` when its end edge meets the
+ *   viewport's end edge. The span where it is fully visible.
+ * - `--lm-scroll-listener-self-outer-scrolled-x-ratio`,
+ *   `--lm-scroll-listener-self-outer-scrolled-y-ratio` — `0` when the element is
+ *   about to enter the viewport, `1` once it has fully left it. The span where it
+ *   overlaps the viewport at all.
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A container element exposing scroll metrics through CSS variables and
- * wrapping its children inside an IntersectionObserver boundary.
+ * @returns A container exposing the metrics, wrapping its children inside an
+ * {@link IntersectionObserverComponent}.
+ *
+ * @remarks
+ * All mounted instances share a single pair of `scroll` / `resize` listeners and
+ * a single measurement pass per animation frame — the document is measured once
+ * for everyone, each element only for itself. The listeners exist only while at
+ * least one instance is tracking.
  */
-export const ScrollListener = ({ startOnVisible, stopOnHidden, stateHandlers, className, children }) => {
-    const [privateId] = useState(randomHash(6));
-    const [scrollData, setScrollData] = useState();
+export const ScrollListener = ({ startOnVisible, stopOnHidden, onScrollStateChanged, onVisibilityChanged, className, children }) => {
+    // State & refs
+    const [subscriberId] = useState(() => randomHash(6));
+    const [scrollState, setScrollState] = useState();
     const rootRef = useRef(null);
-    // Fx. dep. `scrollData` - State dispatcher
-    useEffect(() => {
-        stateHandlers?.scrollDataChanged?.(scrollData);
-    }, [scrollData]);
-    // Fx. no dep. - register / unregister to scroll listeners
+    // State dispatch
+    useChangeDispatch(scrollState, onScrollStateChanged);
+    // Fx. no dep. - track from mount, unless waiting for the component to show up.
+    // The cleanup runs whichever way the subscription was opened.
     useEffect(() => {
-        register({ id: privateId, rootRef, setData: setScrollData });
-        return () => { unregister(privateId); };
+        if (startOnVisible !== true) {
+            subscribe(subscriberId, { rootRef, onScrollStateChange: setScrollState });
+        }
+        return () => unsubscribe(subscriberId);
     }, []);
-    const handleIntersection = useCallback(({ ioEntry, observer }) => {
-        stateHandlers?.visibilityChanged?.(ioEntry?.isIntersecting ?? false);
-        if (startOnVisible !== true && stopOnHidden !== true)
-            return;
-        if (ioEntry?.isIntersecting === true && startOnVisible === true)
-            register({ id: privateId, rootRef, setData: setScrollData });
-        if (ioEntry?.isIntersecting !== true && stopOnHidden === true)
-            unregister(privateId);
-    }, [startOnVisible, stopOnHidden]);
-    // Rendering
-    const customProps = Object
-        .entries(scrollData !== undefined
-        ? {
-            // Global
-            [`--${publicClassName}-window-width`]: scrollData.global.win.width,
-            [`--${publicClassName}-window-height`]: scrollData.global.win.height,
-            [`--${publicClassName}-html-width`]: scrollData.global.html.width,
-            [`--${publicClassName}-html-height`]: scrollData.global.html.height,
-            [`--${publicClassName}-scroll-x`]: scrollData.global.scroll.x,
-            [`--${publicClassName}-scroll-y`]: scrollData.global.scroll.y,
-            // Local
-            [`--${publicClassName}-width`]: scrollData.local.width,
-            [`--${publicClassName}-height`]: scrollData.local.height,
-            [`--${publicClassName}-offset-x`]: scrollData.local.offsetX,
-            [`--${publicClassName}-offset-y`]: scrollData.local.offsetY
+    // User action handlers
+    const handleIntersection = useCallback(({ ioEntry }) => {
+        const isVisible = ioEntry?.isIntersecting ?? false;
+        onVisibilityChanged?.(isVisible);
+        if (isVisible && startOnVisible === true) {
+            subscribe(subscriberId, { rootRef, onScrollStateChange: setScrollState });
         }
-        : {}).reduce((acc, [key, val]) => ({
-        ...acc,
-        [key]: val,
-        [`${key}-px`]: `${val}px`
-    }), {});
-    if (scrollData !== undefined) {
-        customProps[`--${publicClassName}-window-scrolled-x-ratio`] = (scrollData.global.scroll.x) / Math.max((scrollData.global.html.width - scrollData.global.win.width), 1);
-        customProps[`--${publicClassName}-window-scrolled-y-ratio`] = (scrollData.global.scroll.y) / Math.max((scrollData.global.html.height - scrollData.global.win.height), 1);
-        const topTouchesTop = scrollData.local.offsetY;
-        const topTouchesBottom = scrollData.local.offsetY - scrollData.global.win.height;
-        const bottomTouchesTop = scrollData.local.offsetY + scrollData.local.height;
-        const bottomTouchesBottom = (scrollData.local.offsetY + scrollData.local.height) - scrollData.global.win.height;
-        const leftTouchesLeft = scrollData.local.offsetX;
-        const leftTouchesRight = scrollData.local.offsetX - scrollData.global.win.width;
-        const rightTouchesLeft = scrollData.local.offsetX + scrollData.local.width;
-        const rightTouchesRight = (scrollData.local.offsetX + scrollData.local.width) - scrollData.global.win.width;
-        const innerYRange = [bottomTouchesBottom, topTouchesTop];
-        const outerYRange = [topTouchesBottom, bottomTouchesTop];
-        const innerXRange = [rightTouchesRight, leftTouchesLeft];
-        const outerXRange = [leftTouchesRight, rightTouchesLeft];
-        const innerScrollYRatio = (scrollData.global.scroll.y - innerYRange[0]) / Math.max((innerYRange[1] - innerYRange[0]), 1);
-        const outerScrollYRatio = (scrollData.global.scroll.y - outerYRange[0]) / Math.max((outerYRange[1] - outerYRange[0]), 1);
-        const innerScrollXRatio = (scrollData.global.scroll.x - innerXRange[0]) / Math.max((innerXRange[1] - innerXRange[0]), 1);
-        const outerScrollXRatio = (scrollData.global.scroll.x - outerXRange[0]) / Math.max((outerXRange[1] - outerXRange[0]), 1);
-        customProps[`--${publicClassName}-self-inner-scrolled-y-ratio`] = innerScrollYRatio;
-        customProps[`--${publicClassName}-self-outer-scrolled-y-ratio`] = outerScrollYRatio;
-        customProps[`--${publicClassName}-self-inner-scrolled-x-ratio`] = innerScrollXRatio;
-        customProps[`--${publicClassName}-self-outer-scrolled-x-ratio`] = outerScrollXRatio;
-    }
+        if (!isVisible && stopOnHidden === true)
+            unsubscribe(subscriberId);
+    }, [startOnVisible, stopOnHidden, onVisibilityChanged]);
+    // Rendering
     const c = clss(publicClassName, { cssModule });
     const rootClss = mergeClassNames(c(), className);
+    const customProps = scrollState === undefined
+        ? {}
+        : toScrollCssProps(scrollState);
     return _jsx("div", { className: rootClss, ref: rootRef, style: { ...customProps }, children: _jsx(IntersectionObserverComponent, { onIntersected: handleIntersection, children: children }) });
 };