@design-edito/tools 0.5.6 → 0.5.8

package/components/Scrllgngn/index.js

@@ -8,7 +8,7 @@ import { ResizeObserverComponent } from '../ResizeObserver/index.js';
 import { subscribe, unsubscribe } from '../ScrollListener/utils.js';
 import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
 import { scrllgngn as publicClassName } from '../public-classnames.js';
-import { blockDisplayZones, consolidateStickyBlocks, contextsAreEqual, lazyLoadedBlocks, measurePages, sameDiscretePart, scrollBlocksOf, scrollKey, stickyKey, toScreenCssProps, toTrackedBlockContext, toTrackedBlockCssProps, toTrackedBlockDataAttributes } from './utils.js';
+import { blockDisplayZones, consolidateStickyBlocks, contextsAreEqual, lazyLoadedBlocks, measurePages, sameDiscretePart, scrollBlocksOf, scrollKey, stickyKey, toPaginatorThresholdPercent, toScreenCssProps, toThresholdY, toTrackedBlockContext, toTrackedBlockCssProps, toTrackedBlockDataAttributes, toViewportOffsetCssProps, toVisibleZoneRect, toVisibleZoneRootMargin, visibleZonePollInterval, visibleZonesAreEqual } from './utils.js';
 import cssModule from './styles.module.css';
 /**
  * Scrollytelling engine component. Orchestrates layered sticky blocks (`back`
@@ -45,6 +45,16 @@ import cssModule from './styles.module.css';
  * `-width` and `-height` for the component's own stylesheet. They are internal:
  * do not read or override them.
  *
+ * ### Visible zone
+ * Set any of the `viewportOffset*` props and the component stops treating the whole
+ * screen as available: the fixed layers are inset by those edges, the top / content
+ * / bottom detection observes the reduced box, and `thresholdOffsetPercent` reads as
+ * a percentage of it. With none of them set, everything behaves exactly as before.
+ *
+ * The four edges are echoed as `--lm-scrllgngn-viewport-offset-top`, `-right`,
+ * `-bottom` and `-left`, carrying the length as authored — pixels for a number, the
+ * string untouched otherwise.
+ *
  * ### Sticky block elements
  * Each lazy-loaded sticky block receives:
  * - `--active` modifier when the block's page range includes the current page.
@@ -76,16 +86,24 @@ import cssModule from './styles.module.css';
  *
  * @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.
+ * @returns A div wrapping the full scrollytelling structure: visible zone probe,
+ * top-bound sentinel, back-blocks layer, front-blocks layer, paginated scrolling
+ * content, and bottom-bound sentinel.
  *
  * @remarks
+ * A `viewportOffset*` given as a CSS length is resolved by CSS, not parsed: a hidden
+ * probe is inset by the four of them and observed, so `var()`, `clamp()` and
+ * breakpoint-dependent values all work, and any restyling that changes them is
+ * picked up as a resize. A change that moves the zone without altering its size —
+ * a top offset traded for an equal bottom one — is caught instead by a re-read every
+ * 100ms, which runs only while the component is on screen and only reaches state
+ * when the zone really moved.
+ *
  * Tracking costs nothing until a block asks for it: with no `onScrolled` anywhere,
  * the component never joins the shared scroll listener. Once it does, each frame
  * measures only the pages the displayed tracked blocks span, not the whole sequence.
  */
-export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadDistance = 2, forceStickBlocks, onPageChanged, onContentVisibilityChanged, className }) => {
+export const Scrllgngn = ({ pages, thresholdOffsetPercent, viewportOffsetTop, viewportOffsetRight, viewportOffsetBottom, viewportOffsetLeft, stickyBlocksLazyLoadDistance = 2, forceStickBlocks, onPageChanged, onContentVisibilityChanged, className }) => {
     // State
     const [topVisible, setTopVis] = useState(false);
     const [contentVisible, setCntVis] = useState(false);
@@ -93,6 +111,7 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
     const [currentPagePos, setCurrentPagePos] = useState(0);
     const [stickyBlocks, setStickyBlocks] = useState(new Map());
     const [partialBoundingRect, setPartialBoundingRect] = useState();
+    const [visibleZone, setVisibleZone] = useState();
     // Scroll tracking. Everything the per-frame pass reads lives in a ref: it is
     // registered once with the shared scroll listener, and writes straight to the DOM
     // rather than through state, which would re-render the whole sequence per frame.
@@ -103,6 +122,8 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
     const trackedWrappersRef = useRef(new Map());
     const lastContextsRef = useRef(new Map());
     const currentPagePosRef = useRef(currentPagePos);
+    const visibleZoneRef = useRef(visibleZone);
+    const probeRef = useRef(null);
     // Sticky blocks calculations
     useEffect(() => {
         setStickyBlocks(consolidateStickyBlocks(pages));
@@ -139,7 +160,18 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
     useEffect(() => {
         trackedBlocksRef.current = trackedBlocks;
         currentPagePosRef.current = currentPagePos;
+        visibleZoneRef.current = visibleZone;
     });
+    // Re-reads the probe, and only disturbs the render if the zone actually moved.
+    const readVisibleZone = useCallback(() => {
+        const probe = probeRef.current;
+        if (probe === null)
+            return;
+        const zone = toVisibleZoneRect(probe.getBoundingClientRect());
+        if (visibleZonesAreEqual(zone, visibleZoneRef.current))
+            return;
+        setVisibleZone(zone);
+    }, []);
     // The per-frame pass: measure only the pages the displayed tracked blocks span,
     // then hand each block its context — once, and only when something moved.
     const handleScrolled = useCallback(() => {
@@ -172,7 +204,8 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
             for (const pagePos of block.displayZone)
                 pagesToMeasure.add(pagePos);
         }
-        const metrics = measurePages(pageElementsRef.current, pagesToMeasure, thresholdOffsetPercent);
+        const thresholdY = toThresholdY(visibleZoneRef.current, thresholdOffsetPercent);
+        const metrics = measurePages(pageElementsRef.current, pagesToMeasure, thresholdY);
         for (const [key, block, page] of pending) {
             const context = toTrackedBlockContext(block.displayZone, page, metrics);
             const lastContext = lastContexts.get(key);
@@ -209,6 +242,17 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
         });
         return () => unsubscribe(subscriptionId);
     }, [hasTrackedBlocks, handleScrolled]);
+    // Fx. dep. isOnScreen, readVisibleZone - Catch what the probe's ResizeObserver
+    // cannot: a restyle that moves the visible zone without resizing it, say a top
+    // offset traded for an equal bottom one. Only runs while the component is on
+    // screen, and only touches state when the zone actually moved.
+    const isOnScreen = topVisible || contentVisible || bottomVisible;
+    useEffect(() => {
+        if (!isOnScreen)
+            return;
+        const interval = window.setInterval(readVisibleZone, visibleZonePollInterval);
+        return () => window.clearInterval(interval);
+    }, [isOnScreen, readVisibleZone]);
     // Handlers
     useChangeDispatch(currentPagePos, pagePos => onPageChanged?.(pagePos, pages?.[pagePos]));
     useChangeDispatch(contentVisible, onContentVisibilityChanged);
@@ -232,6 +276,10 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
         else
             trackedWrappersRef.current.set(key, element);
     };
+    const handleProbeResized = ({ entry, boundingClientRect }) => {
+        probeRef.current = entry.target;
+        setVisibleZone(toVisibleZoneRect(boundingClientRect));
+    };
     const handleResize = ({ boundingClientRect }) => {
         if (partialBoundingRect === undefined
             || boundingClientRect.left !== partialBoundingRect.left
@@ -250,22 +298,31 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
         'force-stick-blocks-after': forceStickBlocks === 'after',
         'force-stick-blocks-both': forceStickBlocks === 'both'
     }), className);
-    const customCssProps = toScreenCssProps(partialBoundingRect);
-    return _jsx("div", { ref: rootRef, className: rootClss, "data-current-page-pos": currentPagePos, "data-current-page-id": pages?.[currentPagePos]?.id, style: { ...customCssProps }, children: _jsxs(ResizeObserverComponent, { onResized: handleResize, children: [_jsx("div", { className: c('top-bound'), children: _jsx(IntersectionObserverComponent, { onIntersected: handleTopBoundDetect }) }), _jsx("div", { className: c('back-blocks'), children: lazyLoadedBackBlocks.map(([blockId, block], blockPos) => {
-                        const isActive = block.displayOnPages.includes(currentPagePos);
-                        const blockClss = c('back-block', {
-                            active: isActive,
-                            'lazy-loaded': !isActive
-                        });
-                        return _jsx("div", { ref: registerWrapper(stickyKey(blockId)), className: blockClss, style: { zIndex: blockPos }, children: block.children }, blockId);
-                    }) }), _jsx("div", { className: c('front-blocks'), children: lazyLoadedFrontBlocks.map(([blockId, block], blockPos) => {
-                        const isActive = block.displayOnPages.includes(currentPagePos);
-                        const blockClss = c('front-block', {
-                            active: isActive,
-                            'lazy-loaded': !isActive
-                        });
-                        return _jsx("div", { ref: registerWrapper(stickyKey(blockId)), className: blockClss, style: { zIndex: blockPos }, children: block.children }, blockId);
-                    }) }), _jsx("div", { className: c('scrolling-content'), children: _jsx(IntersectionObserverComponent, { onIntersected: handleCntDetect, children: _jsx(Paginator, { thresholdOffsetPercent: thresholdOffsetPercent, onPagesChanged: handlePagesChanged, onPageElementsChanged: handlePageElementsChanged, children: pages?.map((page, pagePos) => {
-                                return _jsx(_Fragment, { children: scrollBlocksOf(page).map((block, blockPos) => _jsx("div", { ref: registerWrapper(scrollKey(pagePos, blockPos)), className: c('scroll-block'), children: block.children }, blockPos)) });
-                            }) }) }) }), _jsx("div", { className: c('bottom-bound'), children: _jsx(IntersectionObserverComponent, { onIntersected: handleBtmBoundDetect }) })] }) });
+    const customCssProps = {
+        ...toScreenCssProps(partialBoundingRect, visibleZone),
+        ...toViewportOffsetCssProps({
+            top: viewportOffsetTop,
+            right: viewportOffsetRight,
+            bottom: viewportOffsetBottom,
+            left: viewportOffsetLeft
+        })
+    };
+    const visibleZoneRootMargin = toVisibleZoneRootMargin(visibleZone);
+    return _jsxs("div", { ref: rootRef, className: rootClss, "data-current-page-pos": currentPagePos, "data-current-page-id": pages?.[currentPagePos]?.id, style: { ...customCssProps }, children: [_jsx(ResizeObserverComponent, { className: c('viewport-probe'), onResized: handleProbeResized }), _jsxs(ResizeObserverComponent, { onResized: handleResize, children: [_jsx("div", { className: c('top-bound'), children: _jsx(IntersectionObserverComponent, { rootMargin: visibleZoneRootMargin, onIntersected: handleTopBoundDetect }) }), _jsx("div", { className: c('back-blocks'), children: lazyLoadedBackBlocks.map(([blockId, block], blockPos) => {
+                            const isActive = block.displayOnPages.includes(currentPagePos);
+                            const blockClss = c('back-block', {
+                                active: isActive,
+                                'lazy-loaded': !isActive
+                            });
+                            return _jsx("div", { ref: registerWrapper(stickyKey(blockId)), className: blockClss, style: { zIndex: blockPos }, children: block.children }, blockId);
+                        }) }), _jsx("div", { className: c('front-blocks'), children: lazyLoadedFrontBlocks.map(([blockId, block], blockPos) => {
+                            const isActive = block.displayOnPages.includes(currentPagePos);
+                            const blockClss = c('front-block', {
+                                active: isActive,
+                                'lazy-loaded': !isActive
+                            });
+                            return _jsx("div", { ref: registerWrapper(stickyKey(blockId)), className: blockClss, style: { zIndex: blockPos }, children: block.children }, blockId);
+                        }) }), _jsx("div", { className: c('scrolling-content'), children: _jsx(IntersectionObserverComponent, { rootMargin: visibleZoneRootMargin, onIntersected: handleCntDetect, children: _jsx(Paginator, { thresholdOffsetPercent: toPaginatorThresholdPercent(visibleZone, thresholdOffsetPercent), onPagesChanged: handlePagesChanged, onPageElementsChanged: handlePageElementsChanged, children: pages?.map((page, pagePos) => {
+                                    return _jsx(_Fragment, { children: scrollBlocksOf(page).map((block, blockPos) => _jsx("div", { ref: registerWrapper(scrollKey(pagePos, blockPos)), className: c('scroll-block'), children: block.children }, blockPos)) });
+                                }) }) }) }), _jsx("div", { className: c('bottom-bound'), children: _jsx(IntersectionObserverComponent, { rootMargin: visibleZoneRootMargin, onIntersected: handleBtmBoundDetect }) })] })] });
 };

package/components/Scrllgngn/styles.module.css

@@ -1,5 +1,30 @@
 .root {
   position: relative;
+
+  /*
+  The visible zone's height, derived from the offsets rather than measured: CSS
+  already knows them, and reading them back from JS would only add a frame of lag.
+  */
+  --PRIVATE-viewport-height: calc(
+    100vh
+    - var(--PRIVATE-viewport-offset-top)
+    - var(--PRIVATE-viewport-offset-bottom)
+  );
+}
+
+/*
+Measured, never seen: its box is the visible zone, and observing it is how a CSS
+length written by the consumer — a var, a clamp, a breakpoint — reaches JavaScript.
+*/
+.viewport-probe {
+  position: fixed;
+  top: var(--PRIVATE-viewport-offset-top);
+  right: var(--PRIVATE-viewport-offset-right);
+  bottom: var(--PRIVATE-viewport-offset-bottom);
+  left: var(--PRIVATE-viewport-offset-left);
+  visibility: hidden;
+  pointer-events: none;
+  z-index: -1;
 }
 
 /* MAIN LAYOUTS (back / front blocks, scrolling content) */
@@ -30,7 +55,7 @@
   top: 0;
   left: 0;
   right: 0;
-  height: 100vh;
+  height: var(--PRIVATE-viewport-height);
 }
 
 /*
@@ -51,20 +76,20 @@ Force stick blocks option
 .root.root--bottom-visible.root--content-visible.root--force-stick-blocks-both .back-blocks,
 .root.root--bottom-visible.root--content-visible.root--force-stick-blocks-both .front-blocks {
   position: fixed;
-  top: 0;
+  top: var(--PRIVATE-viewport-offset-top);
   left: var(--PRIVATE-left);
   width: var(--PRIVATE-width);
-  height: 100vh;
+  height: var(--PRIVATE-viewport-height);
 }
 
 /* Scrllgngn leaving the viewport, blocks not fixed but have offset */
 .root.root--bottom-visible.root--content-visible .back-blocks,
 .root.root--bottom-visible.root--content-visible .front-blocks {
   position: absolute;
-  top: calc(var(--PRIVATE-height) - 100vh);
+  top: calc(var(--PRIVATE-height) - var(--PRIVATE-viewport-height));
   left: 0;
   right: 0;
-  height: 100vh;
+  height: var(--PRIVATE-viewport-height);
 }
 
 /* INDIVIDUAL FIXED BLOCKS */

package/components/Scrllgngn/utils.d.ts

@@ -48,10 +48,16 @@ export declare function lazyLoadedBlocks(blocks: Map<string, ConsolidatedStickyB
  * never inherit the same names from an ancestor component. `initial` leaves them
  * behaving exactly as an unset variable would, without opening the hole.
  *
+ * The public set describes the component's own box and nothing else. The private
+ * one is narrowed to what the fixed layers may actually occupy — the component's
+ * box **intersected** with the visible zone — so a viewport offset pushes them off
+ * whatever covers that edge without the stylesheet doing arithmetic.
+ *
  * @param rect - The measured bounding rect, absent until the first resize lands.
+ * @param zone - The measured visible zone, absent until the probe reports.
  * @returns The custom properties, keyed by their full name.
  */
-export declare function toScreenCssProps(rect?: ScreenRect): Record<string, string>;
+export declare function toScreenCssProps(rect?: ScreenRect, zone?: VisibleZoneRect): Record<string, string>;
 /**
  * Where one tracked block stands in the scroll, as handed to its `onScrolled`.
  *
@@ -119,11 +125,11 @@ export declare function contiguousRunContaining(zone: number[], page: number): n
  *
  * @param pageElements - Every page slot, indexed by position.
  * @param pagePositions - The positions worth measuring.
- * @param thresholdOffsetPercent - The same offset the internal `Paginator` uses,
- * as a percentage of the viewport height.
+ * @param thresholdY - The threshold line, in pixels from the viewport top. See
+ * {@link toThresholdY}.
  * @returns The metrics of each measurable page, keyed by position.
  */
-export declare function measurePages(pageElements: HTMLElement[], pagePositions: Iterable<number>, thresholdOffsetPercent?: number): Map<number, PageScrollMetrics>;
+export declare function measurePages(pageElements: HTMLElement[], pagePositions: Iterable<number>, thresholdY: number): Map<number, PageScrollMetrics>;
 /**
  * Assembles what one tracked block is told about the scroll.
  *
@@ -185,3 +191,80 @@ export declare function scrollKey(pagePos: number, blockPos: number): string;
  * @returns Its scroll blocks, in order. `depth` left out means `'scroll'`.
  */
 export declare function scrollBlocksOf(page: PropsPage): PropsBlock[];
+/** How much of each viewport edge is covered by something else, in pixels. */
+export type VisibleZoneRect = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+    width: number;
+    height: number;
+};
+/** A length as authored: a bare number means pixels, a string is CSS's problem. */
+export type ViewportOffset = number | string;
+/** The four edges, as authored on the component. */
+export type ViewportOffsets = {
+    top?: ViewportOffset;
+    right?: ViewportOffset;
+    bottom?: ViewportOffset;
+    left?: ViewportOffset;
+};
+/**
+ * Builds the custom properties carrying the visible zone's insets.
+ *
+ * They are emitted whatever the props hold, `0px` standing in for an edge left
+ * unset: the probe and the fixed layers position themselves against them, and an
+ * absent name would let an enclosing component's value inherit through.
+ *
+ * @param offsets - The edges as authored.
+ * @returns The custom properties, keyed by their full name.
+ */
+export declare function toViewportOffsetCssProps(offsets: ViewportOffsets): Record<string, string>;
+/**
+ * Reads the visible zone off the probe element.
+ *
+ * The probe is fixed and inset by the four offsets, so its rect *is* the zone —
+ * which is how a `var()`, a `clamp()` or a breakpoint-dependent length reaches
+ * JavaScript without anyone parsing a CSS length.
+ *
+ * @param probeRect - The probe's bounding rect.
+ * @returns The zone, as insets from each viewport edge plus its own size.
+ */
+export declare function toVisibleZoneRect(probeRect: DOMRect): VisibleZoneRect;
+/**
+ * Shrinks an {@link IntersectionObserver} root down to the visible zone.
+ *
+ * @param zone - The measured zone, absent until the probe reports.
+ * @returns A `rootMargin`, or `undefined` to leave the observer on the full
+ * viewport.
+ */
+export declare function toVisibleZoneRootMargin(zone?: VisibleZoneRect): string | undefined;
+/**
+ * Places the threshold line, in pixels from the viewport top.
+ *
+ * `thresholdOffsetPercent` reads as a percentage **of the visible zone**, not of
+ * the viewport: a threshold at 50% has to sit halfway down what the reader can
+ * actually see, or it lands under whatever covers the top of the screen.
+ *
+ * @param zone - The measured zone, absent until the probe reports.
+ * @param thresholdOffsetPercent - The offset as authored.
+ * @returns The line's distance from the viewport top.
+ */
+export declare function toThresholdY(zone?: VisibleZoneRect, thresholdOffsetPercent?: number): number;
+/**
+ * Restates the threshold as the percentage of the **viewport** an
+ * {@link IntersectionObserver} needs, since that is the only frame `rootMargin`
+ * knows.
+ *
+ * With no offsets set the zone spans the viewport and the number comes back
+ * unchanged, so nothing moves for a component that never asked for any of this.
+ *
+ * @param zone - The measured zone, absent until the probe reports.
+ * @param thresholdOffsetPercent - The offset as authored.
+ * @returns The equivalent viewport percentage, to hand to the internal `Paginator`.
+ */
+export declare function toPaginatorThresholdPercent(zone?: VisibleZoneRect, thresholdOffsetPercent?: number): number | undefined;
+/** How often the visible zone is re-read while the component is on screen, in ms. */
+export declare const visibleZonePollInterval = 100;
+/** Whether two zones hold the same six measurements. */
+export declare function visibleZonesAreEqual(a?: VisibleZoneRect, b?: VisibleZoneRect): boolean;

package/components/Scrllgngn/utils.js

@@ -75,10 +75,16 @@ export function lazyLoadedBlocks(blocks, depth, currentPagePos, lazyLoadDistance
  * never inherit the same names from an ancestor component. `initial` leaves them
  * behaving exactly as an unset variable would, without opening the hole.
  *
+ * The public set describes the component's own box and nothing else. The private
+ * one is narrowed to what the fixed layers may actually occupy — the component's
+ * box **intersected** with the visible zone — so a viewport offset pushes them off
+ * whatever covers that edge without the stylesheet doing arithmetic.
+ *
  * @param rect - The measured bounding rect, absent until the first resize lands.
+ * @param zone - The measured visible zone, absent until the probe reports.
  * @returns The custom properties, keyed by their full name.
  */
-export function toScreenCssProps(rect) {
+export function toScreenCssProps(rect, zone) {
     const publicProps = rect === undefined
         ? {}
         : {
@@ -91,14 +97,30 @@ export function toScreenCssProps(rect) {
             '--lm-scrllgngn-screen-height': `${rect.height}px`,
             '--lm-scrllgngn-screen-height-raw': `${rect.height}`
         };
+    const inZone = toZoneClampedRect(rect, zone);
     return {
         ...publicProps,
-        '--PRIVATE-left': toPrivateLength(rect?.left),
-        '--PRIVATE-right': toPrivateLength(rect?.right),
-        '--PRIVATE-width': toPrivateLength(rect?.width),
+        '--PRIVATE-left': toPrivateLength(inZone?.left),
+        '--PRIVATE-right': toPrivateLength(inZone?.right),
+        '--PRIVATE-width': toPrivateLength(inZone?.width),
         '--PRIVATE-height': toPrivateLength(rect?.height)
     };
 }
+/** The component's box, cut down to the horizontal span of the visible zone. */
+function toZoneClampedRect(rect, zone) {
+    if (rect === undefined)
+        return undefined;
+    if (zone === undefined)
+        return rect;
+    const left = Math.max(rect.left, zone.left);
+    const right = Math.min(rect.right, window.innerWidth - zone.right);
+    return {
+        left,
+        right,
+        width: Math.max(right - left, 0),
+        height: rect.height
+    };
+}
 function toPrivateLength(value) {
     return value === undefined ? 'initial' : `${value}px`;
 }
@@ -155,12 +177,11 @@ export function contiguousRunContaining(zone, page) {
  *
  * @param pageElements - Every page slot, indexed by position.
  * @param pagePositions - The positions worth measuring.
- * @param thresholdOffsetPercent - The same offset the internal `Paginator` uses,
- * as a percentage of the viewport height.
+ * @param thresholdY - The threshold line, in pixels from the viewport top. See
+ * {@link toThresholdY}.
  * @returns The metrics of each measurable page, keyed by position.
  */
-export function measurePages(pageElements, pagePositions, thresholdOffsetPercent) {
-    const thresholdY = window.innerHeight * (thresholdOffsetPercent ?? 0) / 100;
+export function measurePages(pageElements, pagePositions, thresholdY) {
     const measured = new Map();
     for (const pagePos of pagePositions) {
         const element = pageElements[pagePos];
@@ -293,3 +314,116 @@ export function scrollKey(pagePos, blockPos) {
 export function scrollBlocksOf(page) {
     return page.blocks?.filter(block => block.depth === 'scroll' || block.depth === undefined) ?? [];
 }
+function toCssLength(offset) {
+    if (offset === undefined)
+        return '0px';
+    return typeof offset === 'number' ? `${offset}px` : offset;
+}
+/**
+ * Builds the custom properties carrying the visible zone's insets.
+ *
+ * They are emitted whatever the props hold, `0px` standing in for an edge left
+ * unset: the probe and the fixed layers position themselves against them, and an
+ * absent name would let an enclosing component's value inherit through.
+ *
+ * @param offsets - The edges as authored.
+ * @returns The custom properties, keyed by their full name.
+ */
+export function toViewportOffsetCssProps(offsets) {
+    const top = toCssLength(offsets.top);
+    const right = toCssLength(offsets.right);
+    const bottom = toCssLength(offsets.bottom);
+    const left = toCssLength(offsets.left);
+    return {
+        '--lm-scrllgngn-viewport-offset-top': top,
+        '--lm-scrllgngn-viewport-offset-right': right,
+        '--lm-scrllgngn-viewport-offset-bottom': bottom,
+        '--lm-scrllgngn-viewport-offset-left': left,
+        '--PRIVATE-viewport-offset-top': top,
+        '--PRIVATE-viewport-offset-right': right,
+        '--PRIVATE-viewport-offset-bottom': bottom,
+        '--PRIVATE-viewport-offset-left': left
+    };
+}
+/**
+ * Reads the visible zone off the probe element.
+ *
+ * The probe is fixed and inset by the four offsets, so its rect *is* the zone —
+ * which is how a `var()`, a `clamp()` or a breakpoint-dependent length reaches
+ * JavaScript without anyone parsing a CSS length.
+ *
+ * @param probeRect - The probe's bounding rect.
+ * @returns The zone, as insets from each viewport edge plus its own size.
+ */
+export function toVisibleZoneRect(probeRect) {
+    return {
+        top: probeRect.top,
+        right: window.innerWidth - probeRect.right,
+        bottom: window.innerHeight - probeRect.bottom,
+        left: probeRect.left,
+        width: probeRect.width,
+        height: probeRect.height
+    };
+}
+/**
+ * Shrinks an {@link IntersectionObserver} root down to the visible zone.
+ *
+ * @param zone - The measured zone, absent until the probe reports.
+ * @returns A `rootMargin`, or `undefined` to leave the observer on the full
+ * viewport.
+ */
+export function toVisibleZoneRootMargin(zone) {
+    if (zone === undefined)
+        return undefined;
+    return `${-zone.top}px ${-zone.right}px ${-zone.bottom}px ${-zone.left}px`;
+}
+/**
+ * Places the threshold line, in pixels from the viewport top.
+ *
+ * `thresholdOffsetPercent` reads as a percentage **of the visible zone**, not of
+ * the viewport: a threshold at 50% has to sit halfway down what the reader can
+ * actually see, or it lands under whatever covers the top of the screen.
+ *
+ * @param zone - The measured zone, absent until the probe reports.
+ * @param thresholdOffsetPercent - The offset as authored.
+ * @returns The line's distance from the viewport top.
+ */
+export function toThresholdY(zone, thresholdOffsetPercent) {
+    const percent = thresholdOffsetPercent ?? 0;
+    if (zone === undefined)
+        return window.innerHeight * percent / 100;
+    return zone.top + zone.height * percent / 100;
+}
+/**
+ * Restates the threshold as the percentage of the **viewport** an
+ * {@link IntersectionObserver} needs, since that is the only frame `rootMargin`
+ * knows.
+ *
+ * With no offsets set the zone spans the viewport and the number comes back
+ * unchanged, so nothing moves for a component that never asked for any of this.
+ *
+ * @param zone - The measured zone, absent until the probe reports.
+ * @param thresholdOffsetPercent - The offset as authored.
+ * @returns The equivalent viewport percentage, to hand to the internal `Paginator`.
+ */
+export function toPaginatorThresholdPercent(zone, thresholdOffsetPercent) {
+    if (zone === undefined)
+        return thresholdOffsetPercent;
+    const viewportHeight = window.innerHeight;
+    if (viewportHeight === 0)
+        return thresholdOffsetPercent;
+    return toThresholdY(zone, thresholdOffsetPercent) / viewportHeight * 100;
+}
+/** How often the visible zone is re-read while the component is on screen, in ms. */
+export const visibleZonePollInterval = 100;
+/** Whether two zones hold the same six measurements. */
+export function visibleZonesAreEqual(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    return a.top === b.top
+        && a.right === b.right
+        && a.bottom === b.bottom
+        && a.left === b.left
+        && a.width === b.width
+        && a.height === b.height;
+}

package/components/ScrollListener/index.d.ts

@@ -1,5 +1,5 @@
 import { type FunctionComponent, type PropsWithChildren } from 'react';
-import type { WithClassName } from '../utils/types.js';
+import type { WithClassName, WithViewportObservation } from '../utils/types.js';
 import { type ScrollState } from './utils.js';
 /**
  * Props for the {@link ScrollListener} component.
@@ -17,22 +17,31 @@ import { type ScrollState } from './utils.js';
  * it has fully left it. Never on mount.
  * @property onScrollDirectionChanged - Called after the document scroll
  * direction changed, with `'up'` or `'down'`. Never on mount.
+ * @property threshold - How much of the component has to be in view before it
+ * counts as visible, forwarded to the internal {@link IntersectionObserver}.
+ * @property root - The observer's root. Defaults to the viewport.
+ * @property rootMargin - Grows or shrinks that root before measuring.
  * @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<{
+export type Props = PropsWithChildren<WithClassName<WithViewportObservation<{
     startOnVisible?: boolean;
     stopOnHidden?: boolean;
     onScrollStateChanged?: (scrollState?: ScrollState) => void;
     onVisibilityChanged?: (isVisible: boolean) => void;
     onScrollProgressChanged?: (progress: number) => void;
     onScrollDirectionChanged?: (direction: 'up' | 'down') => void;
-}>>;
+}>>>;
 /**
  * Exposes scroll metrics — both the document's and its own — as CSS custom
  * properties on its root element, so scroll-driven styling needs no JavaScript
  * of its own.
  *
+ * ### Root element modifiers
+ * - `--measured` — a first measurement landed, so the properties below are set.
+ * - `--scrolling-up` / `--scrolling-down` — the document's last known direction.
+ *   Neither is present before the first scroll.
+ *
  * ### 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:

package/components/ScrollListener/index.js

@@ -12,6 +12,11 @@ import cssModule from './styles.module.css';
  * properties on its root element, so scroll-driven styling needs no JavaScript
  * of its own.
  *
+ * ### Root element modifiers
+ * - `--measured` — a first measurement landed, so the properties below are set.
+ * - `--scrolling-up` / `--scrolling-down` — the document's last known direction.
+ *   Neither is present before the first scroll.
+ *
  * ### 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:
@@ -45,7 +50,7 @@ import cssModule from './styles.module.css';
  * for everyone, each element only for itself. The listeners exist only while at
  * least one instance is tracking.
  */
-export const ScrollListener = ({ startOnVisible, stopOnHidden, onScrollStateChanged, onVisibilityChanged, onScrollProgressChanged, onScrollDirectionChanged, className, children }) => {
+export const ScrollListener = ({ startOnVisible, stopOnHidden, threshold, root, rootMargin, onScrollStateChanged, onVisibilityChanged, onScrollProgressChanged, onScrollDirectionChanged, className, children }) => {
     // State & refs
     const [subscriberId] = useState(() => randomHash(6));
     const [scrollState, setScrollState] = useState();
@@ -92,9 +97,13 @@ export const ScrollListener = ({ startOnVisible, stopOnHidden, onScrollStateChan
     }, [startOnVisible, stopOnHidden, onVisibilityChanged]);
     // Rendering
     const c = clss(publicClassName, { cssModule });
-    const rootClss = mergeClassNames(c(), className);
+    const rootClss = mergeClassNames(c(null, {
+        measured: scrollState !== undefined,
+        'scrolling-up': scrollDirection === 'up',
+        'scrolling-down': scrollDirection === 'down'
+    }), className);
     const customProps = scrollState === undefined
         ? {}
         : toScrollCssProps(scrollState);
-    return _jsx("div", { className: rootClss, ref: rootRef, style: { ...customProps }, children: _jsx(IntersectionObserverComponent, { onIntersected: handleIntersection, children: children }) });
+    return _jsx("div", { className: rootClss, ref: rootRef, style: { ...customProps }, children: _jsx(IntersectionObserverComponent, { threshold: threshold, root: root, rootMargin: rootMargin, onIntersected: handleIntersection, children: children }) });
 };

package/components/Select/index.d.ts

@@ -24,6 +24,10 @@ export type Props = SelectHTMLAttributes<HTMLSelectElement> & PropsWithChildren<
  * A stable auto-generated `id` is created on mount and used to associate the
  * rendered label through the `htmlFor` attribute.
  *
+ * ### Root element modifiers
+ * - `--controlled` — the value comes from the parent, not from inside.
+ * - `--empty` / `--filled` — whether the current value is the empty string.
+ *
  * ### CSS elements
  * - `label`
  * - `error`

package/components/Select/index.js

@@ -15,6 +15,10 @@ import cssModule from './styles.module.css';
  * A stable auto-generated `id` is created on mount and used to associate the
  * rendered label through the `htmlFor` attribute.
  *
+ * ### Root element modifiers
+ * - `--controlled` — the value comes from the parent, not from inside.
+ * - `--empty` / `--filled` — whether the current value is the empty string.
+ *
  * ### CSS elements
  * - `label`
  * - `error`
@@ -44,6 +48,10 @@ export const Select = ({ label, error, value, defaultValue, onChange, className,
     };
     // Rendering
     const c = clss(publicClassName, { cssModule });
-    const rootClss = mergeClassNames(c(), className);
+    const rootClss = mergeClassNames(c(null, {
+        controlled: isControlled,
+        empty: currentValue === '',
+        filled: currentValue !== ''
+    }), className);
     return _jsxs(_Fragment, { children: [isNotFalsy(label) && _jsx("label", { className: c('label'), htmlFor: id, children: label }), _jsx("select", { ...rest, id: id, className: rootClss, value: currentValue, onChange: handleChange, children: children }), isNotFalsy(error) && _jsx("span", { className: c('error'), children: error })] });
 };