@design-edito/tools 0.5.2 → 0.5.4

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

package/components/ScrollListener/utils.d.ts

@@ -1,4 +1,4 @@
-import type { RefObject, Dispatch, SetStateAction } from 'react';
+import type { RefObject } from 'react';
 /**
  * Scroll-related measurements for the document and viewport.
  *
@@ -42,29 +42,50 @@ export type LocalScrollData = {
     height: number;
 };
 /**
- * Combined scroll state passed to each registered {@link ScrollListener}.
+ * Combined scroll state handed to each subscribed {@link ScrollListener}.
  *
- * @property global - Document-level scroll data.
- * @property local - Element-level position data.
+ * @property global - Document-level scroll data, measured once per frame and
+ * shared by every subscriber.
+ * @property local - Position and size of this subscriber's own element.
  */
 export type ScrollState = {
     global: GlobalScrollData;
     local: LocalScrollData;
 };
-export declare const globalDocumentScrollListener: () => GlobalScrollData;
-export declare const localElementScrollListener: (div: HTMLDivElement) => LocalScrollData;
 /**
- * An entry registered with the global scroll listener.
+ * A component subscribed to the shared scroll listener.
  *
- * @property id - Unique identifier for this registration.
- * @property rootRef - Ref to the tracked DOM element.
- * @property setData - State setter to update the component's scroll state.
+ * @property rootRef - Ref to the tracked element. A subscriber whose ref is not
+ * attached yet is skipped for that frame.
+ * @property onScrollStateChange - Receives the freshly measured state.
  */
-export type RegisterEntry = {
-    id: string;
+export type Subscriber = {
     rootRef: RefObject<HTMLDivElement | null>;
-    setData: Dispatch<SetStateAction<ScrollState | undefined>>;
+    onScrollStateChange: (scrollState: ScrollState) => void;
 };
-export declare const registeredIds: Map<string, RegisterEntry>;
-export declare const register: (props: RegisterEntry) => void;
-export declare const unregister: (id: string) => void;
+/**
+ * Starts tracking one element, attaching the shared listeners if this is the
+ * first subscriber. A measurement is scheduled right away, so a subscriber gets
+ * its initial state without waiting for a first scroll.
+ *
+ * @param id - Identifies the subscriber for {@link unsubscribe}.
+ * @param subscriber - The element to track and where to report.
+ */
+export declare function subscribe(id: string, subscriber: Subscriber): void;
+/**
+ * Stops tracking one element, detaching the shared listeners once no subscriber
+ * is left. Unsubscribing an unknown id is a no-op.
+ *
+ * @param id - The id passed to {@link subscribe}.
+ */
+export declare function unsubscribe(id: string): void;
+/**
+ * Builds the CSS custom properties exposed on a {@link ScrollListener} root.
+ *
+ * Measurements are lengths and come with a `-raw` twin carrying the plain number
+ * for `calc()`; ratios are unitless and have no twin.
+ *
+ * @param scrollState - The state to expose.
+ * @returns The custom properties, keyed by their full name.
+ */
+export declare function toScrollCssProps(scrollState: ScrollState): Record<string, string>;