@design-edito/tools 0.4.4 → 0.4.6

package/components/Scrllgngn/index.js

@@ -1,186 +1,179 @@
-import {
-  Paginator
-} from "../../chunks/chunk-AC4UMIWM.js";
-import {
-  randomHash
-} from "../../chunks/chunk-75BICI4L.js";
-import "../../chunks/chunk-OGBUSUE6.js";
-import {
-  ResizeObserverComponent
-} from "../../chunks/chunk-GG4EFNMU.js";
-import {
-  IntersectionObserverComponent
-} from "../../chunks/chunk-F2YJXIT7.js";
-import {
-  scrllgngn
-} from "../../chunks/chunk-IEZ3O5OF.js";
-import {
-  clss
-} from "../../chunks/chunk-TRFZSKNB.js";
-import {
-  mergeClassNames
-} from "../../chunks/chunk-OFCSIK6J.js";
-import "../../chunks/chunk-WSFCRVEQ.js";
-
-// src/components/Scrllgngn/index.tsx
-import {
-  useState,
-  useEffect
-} from "react";
-import cssModule from "./styles.module.css";
-import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-var Scrllgngn = ({
-  pages,
-  thresholdOffsetPercent,
-  stickyBlocksLazyLoadDistance = 2,
-  forceStickBlocks,
-  className
-}) => {
-  const [topVisible, setTopVis] = useState(false);
-  const [contentVisible, setCntVis] = useState(false);
-  const [bottomVisible, setBtmVis] = useState(false);
-  const [currentPagePos, setCurrentPagePos] = useState(0);
-  const [stickyBlocks, setStickyBlocks] = useState(/* @__PURE__ */ new Map());
-  const [partialBoundingRect, setPartialBoundingRect] = useState();
-  useEffect(() => {
-    const consolidatedBlocks = /* @__PURE__ */ 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 !== void 0) 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);
-  }, [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 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 = (pages2) => {
-    const curPagePos = pages2.findIndex((page) => page.position === "curr");
-    if (curPagePos === -1) return;
-    return setCurrentPagePos(curPagePos);
-  };
-  const handleResize = ({ boundingClientRect }) => {
-    if (partialBoundingRect === void 0 || boundingClientRect.left !== partialBoundingRect.left || boundingClientRect.right !== partialBoundingRect.right || boundingClientRect.height !== partialBoundingRect.height || boundingClientRect.width !== partialBoundingRect.width) setPartialBoundingRect(boundingClientRect);
-  };
-  const c = clss(scrllgngn, { cssModule });
-  const rootClss = mergeClassNames(
-    c(null, {
-      "top-visible": topVisible,
-      "content-visible": contentVisible,
-      "bottom-visible": bottomVisible,
-      "force-stick-blocks-before": forceStickBlocks === "before",
-      "force-stick-blocks-after": forceStickBlocks === "after",
-      "force-stick-blocks-both": forceStickBlocks === "both"
-    }),
-    className
-  );
-  const customCssProps = {};
-  if (partialBoundingRect?.left !== void 0) {
-    customCssProps[`--${scrllgngn}-screen-left`] = `${partialBoundingRect.left}px`;
-    customCssProps["--PRIVATE-left"] = `${partialBoundingRect.left}px`;
-  }
-  if (partialBoundingRect?.right !== void 0) {
-    customCssProps[`--${scrllgngn}-screen-right`] = `${partialBoundingRect.right}px`;
-    customCssProps["--PRIVATE-right"] = `${partialBoundingRect.right}px`;
-  }
-  if (partialBoundingRect?.width !== void 0) {
-    customCssProps[`--${scrllgngn}-screen-width`] = `${partialBoundingRect.width}px`;
-    customCssProps["--PRIVATE-width"] = `${partialBoundingRect.width}px`;
-  }
-  if (partialBoundingRect?.height !== void 0) {
-    customCssProps[`--${scrllgngn}-screen-height`] = `${partialBoundingRect.height}px`;
-    customCssProps["--PRIVATE-height"] = `${partialBoundingRect.height}px`;
-  }
-  return /* @__PURE__ */ jsx(
-    "div",
-    {
-      className: rootClss,
-      "data-current-page-pos": currentPagePos,
-      style: { ...customCssProps },
-      children: /* @__PURE__ */ jsxs(ResizeObserverComponent, { onResized: handleResize, children: [
-        /* @__PURE__ */ jsx("div", { className: c("top-bound"), children: /* @__PURE__ */ jsx(IntersectionObserverComponent, { onIntersected: handleTopBoundDetect }) }),
-        /* @__PURE__ */ jsx("div", { className: c("back-blocks"), children: lazyLoadedBackBlocks.map((block, blockPos) => {
-          const isActive = block.displayOnPages.includes(currentPagePos);
-          const blockClss = c("back-block", {
-            active: isActive,
-            "lazy-loaded": !isActive
-          });
-          return /* @__PURE__ */ jsx(
-            "div",
-            {
-              className: blockClss,
-              style: { zIndex: blockPos },
-              children: block.children
-            }
-          );
-        }) }),
-        /* @__PURE__ */ jsx("div", { className: c("front-blocks"), children: lazyLoadedFrontBlocks.map((block, blockPos) => {
-          const isActive = block.displayOnPages.includes(currentPagePos);
-          const blockClss = c("front-block", {
-            active: isActive,
-            "lazy-loaded": !isActive
-          });
-          return /* @__PURE__ */ jsx(
-            "div",
-            {
-              className: blockClss,
-              style: { zIndex: blockPos },
-              children: block.children
+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 { scrllgngn as publicClassName } from '../public-classnames.js';
+import cssModule from './styles.module.css';
+/**
+ * Scrollytelling engine component. Orchestrates layered sticky blocks (`back`
+ * and `front`) over a paginated scrolling content area, with lazy loading,
+ * viewport bound detection, and dimension tracking.
+ *
+ * ### Root element modifiers
+ * The root `<div>` receives the public class name defined by `scrllgngn` and
+ * the following BEM-style modifier classes when active:
+ * - `--top-visible` — the top boundary sentinel is intersecting the viewport.
+ * - `--content-visible` — the scrolling content area is intersecting the viewport.
+ * - `--bottom-visible` — the bottom boundary sentinel is intersecting the viewport.
+ * - `--force-stick-blocks-before` — when `forceStickBlocks === 'before'`.
+ * - `--force-stick-blocks-after` — when `forceStickBlocks === 'after'`.
+ * - `--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}.
+ *
+ * ### 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).
+ *
+ * ### Sticky block elements
+ * Each lazy-loaded sticky block receives:
+ * - `--active` modifier when the block's page range includes the current page.
+ * - `--lazy-loaded` modifier when the block is mounted but not on the current page.
+ * - An inline `z-index` derived from the block's position in the sorted stack
+ * (overridden by {@link PropsStickyBlock.zIndex} if provided).
+ *
+ * @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.
+ */
+export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadDistance = 2, forceStickBlocks, className }) => {
+    // State
+    const [topVisible, setTopVis] = useState(false);
+    const [contentVisible, setCntVis] = useState(false);
+    const [bottomVisible, setBtmVis] = useState(false);
+    const [currentPagePos, setCurrentPagePos] = useState(0);
+    const [stickyBlocks, setStickyBlocks] = useState(new Map());
+    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]
+                    });
             }
-          );
-        }) }),
-        /* @__PURE__ */ jsx("div", { className: c("scrolling-content"), children: /* @__PURE__ */ jsx(IntersectionObserverComponent, { onIntersected: handleCntDetect, children: /* @__PURE__ */ jsx(
-          Paginator,
-          {
-            thresholdOffsetPercent,
-            stateHandlers: {
-              pageChanged: handlePageChange
-            },
-            children: pages?.map((page) => {
-              const scrollBlocks = page.blocks?.filter((b) => b.depth === "scroll" || b.depth === void 0) ?? [];
-              return /* @__PURE__ */ jsx(Fragment, { children: scrollBlocks.map((b) => b.children) });
-            })
-          }
-        ) }) }),
-        /* @__PURE__ */ jsx("div", { className: c("bottom-bound"), children: /* @__PURE__ */ jsx(IntersectionObserverComponent, { onIntersected: handleBtmBoundDetect }) })
-      ] })
+        }
+        const consolidatedStickyBlocks = new Map(Array
+            .from(consolidatedBlocks)
+            .filter((e) => {
+            const block = e[1];
+            return block.depth === 'back'
+                || block.depth === 'front';
+        }));
+        setStickyBlocks(consolidatedStickyBlocks);
+    }, [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);
+    });
+    // Handlers
+    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 = pages => {
+        const curPagePos = pages.findIndex(page => page.position === 'curr');
+        if (curPagePos === -1)
+            return;
+        return setCurrentPagePos(curPagePos);
+    };
+    const handleResize = ({ boundingClientRect }) => {
+        if (partialBoundingRect === undefined
+            || boundingClientRect.left !== partialBoundingRect.left
+            || boundingClientRect.right !== partialBoundingRect.right
+            || boundingClientRect.height !== partialBoundingRect.height
+            || boundingClientRect.width !== partialBoundingRect.width)
+            setPartialBoundingRect(boundingClientRect);
+    };
+    // Rendering
+    const c = clss(publicClassName, { cssModule });
+    const rootClss = mergeClassNames(c(null, {
+        'top-visible': topVisible,
+        'content-visible': contentVisible,
+        'bottom-visible': bottomVisible,
+        'force-stick-blocks-before': forceStickBlocks === 'before',
+        '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`;
     }
-  );
-};
-export {
-  Scrllgngn
+    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 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) => {
+                        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, stateHandlers: {
+                                pageChanged: handlePageChange
+                            }, 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) });
+                            }) }) }) }), _jsx("div", { className: c('bottom-bound'), children: _jsx(IntersectionObserverComponent, { onIntersected: handleBtmBoundDetect }) })] }) });
 };

package/components/ScrollListener/index.js

@@ -1,174 +1,100 @@
-import {
-  randomHash
-} from "../../chunks/chunk-75BICI4L.js";
-import "../../chunks/chunk-OGBUSUE6.js";
-import {
-  IntersectionObserverComponent
-} from "../../chunks/chunk-F2YJXIT7.js";
-import {
-  scrollListener
-} from "../../chunks/chunk-IEZ3O5OF.js";
-import {
-  clss
-} from "../../chunks/chunk-TRFZSKNB.js";
-import {
-  mergeClassNames
-} from "../../chunks/chunk-OFCSIK6J.js";
-import "../../chunks/chunk-WSFCRVEQ.js";
-
-// src/components/ScrollListener/index.tsx
-import {
-  useEffect,
-  useRef,
-  useState,
-  useCallback
-} from "react";
-
-// src/components/ScrollListener/utils.tsx
-var globalDocumentScrollListener = () => {
-  const win = {
-    height: window.innerHeight,
-    width: window.innerWidth
-  };
-  const html = {
-    width: document.body.parentElement?.offsetWidth ?? 0,
-    height: document.body.parentElement?.offsetHeight ?? 0
-  };
-  const scroll = {
-    x: window.scrollX,
-    y: window.scrollY
-  };
-  const viewport = {
-    minX: scroll.x,
-    minY: scroll.y,
-    maxX: scroll.x + win.width,
-    maxY: scroll.y + win.height
-  };
-  return { win, html, scroll, viewport };
-};
-var localElementScrollListener = (div) => {
-  const offsetX = div.offsetLeft;
-  const offsetY = div.offsetTop;
-  const width = div.offsetWidth;
-  const height = div.offsetHeight;
-  return {
-    offsetX,
-    offsetY,
-    width,
-    height
-  };
-};
-window.addEventListener("scroll", () => {
-  const global = globalDocumentScrollListener();
-  Array.from(registeredIds).forEach(([, item]) => {
-    const { rootRef, setData } = item;
-    if (rootRef.current === null) return;
-    const local = localElementScrollListener(rootRef.current);
-    setData({ global, local });
-  });
-});
-var registeredIds = /* @__PURE__ */ new Map();
-var register = (props) => {
-  const { id, rootRef, setData } = props;
-  registeredIds.set(id, { id, rootRef, setData });
-};
-var unregister = (id) => {
-  registeredIds.delete(id);
-};
-
-// src/components/ScrollListener/index.tsx
-import cssModule from "./styles.module.css";
-import { jsx } from "react/jsx-runtime";
-var ScrollListener = ({
-  startOnVisible,
-  stopOnHidden,
-  stateHandlers,
-  className,
-  children
-}) => {
-  const [privateId] = useState(randomHash(6));
-  const [scrollData, setScrollData] = useState();
-  const rootRef = useRef(null);
-  useEffect(() => {
-    stateHandlers?.scrollDataChanged?.(scrollData);
-  }, [scrollData]);
-  useEffect(() => {
-    register({ id: privateId, rootRef, setData: setScrollData });
-    return () => {
-      unregister(privateId);
-    };
-  }, []);
-  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]);
-  const customProps = Object.entries(
-    scrollData !== void 0 ? {
-      // Global
-      [`--${scrollListener}-window-width`]: scrollData.global.win.width,
-      [`--${scrollListener}-window-height`]: scrollData.global.win.height,
-      [`--${scrollListener}-html-width`]: scrollData.global.html.width,
-      [`--${scrollListener}-html-height`]: scrollData.global.html.height,
-      [`--${scrollListener}-scroll-x`]: scrollData.global.scroll.x,
-      [`--${scrollListener}-scroll-y`]: scrollData.global.scroll.y,
-      // Local
-      [`--${scrollListener}-width`]: scrollData.local.width,
-      [`--${scrollListener}-height`]: scrollData.local.height,
-      [`--${scrollListener}-offset-x`]: scrollData.local.offsetX,
-      [`--${scrollListener}-offset-y`]: scrollData.local.offsetY
-    } : {}
-  ).reduce((acc, [key, val]) => ({
-    ...acc,
-    [key]: val,
-    [`${key}-px`]: `${val}px`
-  }), {});
-  if (scrollData !== void 0) {
-    customProps[`--${scrollListener}-window-scrolled-x-ratio`] = scrollData.global.scroll.x / Math.max(scrollData.global.html.width - scrollData.global.win.width, 1);
-    customProps[`--${scrollListener}-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[`--${scrollListener}-self-inner-scrolled-y-ratio`] = innerScrollYRatio;
-    customProps[`--${scrollListener}-self-outer-scrolled-y-ratio`] = outerScrollYRatio;
-    customProps[`--${scrollListener}-self-inner-scrolled-x-ratio`] = innerScrollXRatio;
-    customProps[`--${scrollListener}-self-outer-scrolled-x-ratio`] = outerScrollXRatio;
-  }
-  const c = clss(scrollListener, { cssModule });
-  const rootClss = mergeClassNames(
-    c(),
-    className
-  );
-  return /* @__PURE__ */ jsx(
-    "div",
-    {
-      className: rootClss,
-      ref: rootRef,
-      style: { ...customProps },
-      children: /* @__PURE__ */ jsx(
-        IntersectionObserverComponent,
-        {
-          onIntersected: handleIntersection,
-          children
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef, useState, useCallback } 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 { scrollListener as publicClassName } from '../public-classnames.js';
+import { register, unregister } 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.
+ *
+ * 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).
+ *
+ * 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.
+ *
+ * @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.
+ */
+export const ScrollListener = ({ startOnVisible, stopOnHidden, stateHandlers, className, children }) => {
+    const [privateId] = useState(randomHash(6));
+    const [scrollData, setScrollData] = useState();
+    const rootRef = useRef(null);
+    // Fx. dep. `scrollData` - State dispatcher
+    useEffect(() => {
+        stateHandlers?.scrollDataChanged?.(scrollData);
+    }, [scrollData]);
+    // Fx. no dep. - register / unregister to scroll listeners
+    useEffect(() => {
+        register({ id: privateId, rootRef, setData: setScrollData });
+        return () => { unregister(privateId); };
+    }, []);
+    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
         }
-      )
+        : {}).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;
     }
-  );
-};
-export {
-  ScrollListener
+    const c = clss(publicClassName, { cssModule });
+    const rootClss = mergeClassNames(c(), className);
+    return _jsx("div", { className: rootClss, ref: rootRef, style: { ...customProps }, children: _jsx(IntersectionObserverComponent, { onIntersected: handleIntersection, children: children }) });
 };