@design-edito/tools 0.5.37 → 0.5.39

package/components/Lightbox/store.js

@@ -1,94 +1,72 @@
-/**
- * The registry of lightbox groups, shared by every {@link Lightbox} on the page.
- *
- * Deliberately outside React. lm-link renders each component in its **own React
- * root** — `renderInTarget` calls `createRoot` per component — so two `<lm-image>`
- * in the same article never share a tree, and a context could not reach from one to
- * the other. A module-level store can.
- *
- * Members are kept unordered here; the order that matters is the **document's**, and
- * it is read from the DOM when a group opens. React's mount order is not it.
- */
-const members = new Map();
-const listeners = new Set();
-let state = {
+const storeStateChangeCallbacks = new Set();
+let storeState = {
     openGroup: null,
-    openMemberId: null
+    openLightboxId: null,
+    lightboxesById: new Map()
 };
-function emit() {
-    for (const listener of listeners)
-        listener();
-}
-function setState(next) {
-    if (next.openGroup === state.openGroup
-        && next.openMemberId === state.openMemberId)
+export const getLightboxesStoreState = () => storeState;
+function setLightboxesStoreState(nextState) {
+    if (nextState.openGroup === storeState.openGroup
+        && nextState.openLightboxId === storeState.openLightboxId
+        && nextState.lightboxesById === storeState.lightboxesById)
         return;
-    state = next;
-    emit();
-}
-export function subscribe(listener) {
-    listeners.add(listener);
-    return () => { listeners.delete(listener); };
+    storeState = nextState;
+    for (const onStoreStateChange of storeStateChangeCallbacks)
+        onStoreStateChange();
 }
-export function getState() {
-    return state;
+export function watchLightboxesStoreState(onStoreStateChange) {
+    storeStateChangeCallbacks.add(onStoreStateChange);
+    const unwatchLightboxesStoreState = () => {
+        storeStateChangeCallbacks.delete(onStoreStateChange);
+    };
+    return unwatchLightboxesStoreState;
 }
-/** A member's own group, when it declared none: it is a group of one. */
-export function soloGroupOf(id) {
-    return `solo:${id}`;
-}
-export function register(member) {
-    members.set(member.id, member);
-    emit();
+export function registerLightbox(lightbox) {
+    setLightboxesStoreState({
+        ...storeState,
+        lightboxesById: new Map(storeState.lightboxesById).set(lightbox.id, lightbox)
+    });
 }
-export function unregister(id) {
-    members.delete(id);
-    // A member leaving while it is the one shown would strand the group on nothing.
-    if (state.openMemberId === id)
-        setState({ openGroup: null, openMemberId: null });
-    else
-        emit();
+export function unregisterLightbox(lightboxId) {
+    if (!storeState.lightboxesById.has(lightboxId))
+        return;
+    const lightboxesById = new Map(storeState.lightboxesById);
+    lightboxesById.delete(lightboxId);
+    const leavesNothingOpen = storeState.openLightboxId === lightboxId;
+    setLightboxesStoreState({
+        openGroup: leavesNothingOpen ? null : storeState.openGroup,
+        openLightboxId: leavesNothingOpen ? null : storeState.openLightboxId,
+        lightboxesById
+    });
 }
-/**
- * The members of a group, in **document order**.
- *
- * `compareDocumentPosition` rather than mount order: React mounts a tree in its own
- * order, and lm-link mounts each component in a root of its own, so nothing
- * guarantees the two match. Only runs when a group opens or navigates, over a
- * handful of members.
- */
-export function membersOf(group) {
-    const found = [...members.values()].filter(member => member.groups.includes(group));
+export function getGroupLightboxes(group) {
+    const found = [...storeState.lightboxesById.values()]
+        .filter(lightbox => lightbox.groups.includes(group));
     return found.sort((a, b) => {
         const aElt = a.getElement();
         const bElt = b.getElement();
         if (aElt === null || bElt === null)
             return 0;
         const position = aElt.compareDocumentPosition(bElt);
-        if ((position & Node.DOCUMENT_POSITION_FOLLOWING) !== 0)
-            return -1;
-        if ((position & Node.DOCUMENT_POSITION_PRECEDING) !== 0)
-            return 1;
-        return 0;
+        return (position & Node.DOCUMENT_POSITION_PRECEDING) !== 0 ? 1 : -1;
     });
 }
-export function open(group, memberId) {
-    setState({ openGroup: group, openMemberId: memberId });
+export function openLightbox(group, lightboxId) {
+    setLightboxesStoreState({ ...storeState, openGroup: group, openLightboxId: lightboxId });
 }
-export function close() {
-    setState({ openGroup: null, openMemberId: null });
+export function closeLightbox() {
+    setLightboxesStoreState({ ...storeState, openGroup: null, openLightboxId: null });
 }
-/** Moves to another member of the open group by `offset`, clamped at both ends. */
-export function step(offset) {
-    const { openGroup, openMemberId } = state;
-    if (openGroup === null || openMemberId === null)
+export function navigateOpenGroupBy(offset) {
+    const { openGroup, openLightboxId } = storeState;
+    if (openGroup === null || openLightboxId === null)
         return;
-    const ordered = membersOf(openGroup);
-    const current = ordered.findIndex(member => member.id === openMemberId);
+    const ordered = getGroupLightboxes(openGroup);
+    const current = ordered.findIndex(lightbox => lightbox.id === openLightboxId);
     if (current === -1)
         return;
-    const target = ordered[Math.min(ordered.length - 1, Math.max(0, current + offset))];
-    if (target === undefined)
-        return;
-    setState({ openGroup, openMemberId: target.id });
+    const index = Math.min(ordered.length - 1, Math.max(0, current + offset));
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const target = ordered[index];
+    setLightboxesStoreState({ ...storeState, openLightboxId: target.id });
 }

package/components/Lightbox/types.d.ts

@@ -0,0 +1,16 @@
+/** What a lightbox hands the store so its group can find and place it. */
+export type RegisteredLightbox = {
+    id: string;
+    groups: string[];
+    /** The lightbox's anchor in the page, for ordering. `null` before it mounts. */
+    getElement: () => HTMLElement | null;
+};
+/** Everything the store holds, and everything a lightbox watches. */
+export type LightboxesStoreState = {
+    /** The group currently open, `null` when nothing is. */
+    openGroup: string | null;
+    /** The lightbox currently shown. */
+    openLightboxId: string | null;
+    /** Every mounted lightbox of the page, unordered. */
+    lightboxesById: ReadonlyMap<string, RegisteredLightbox>;
+};

package/components/Lightbox/types.js

@@ -0,0 +1 @@
+export {};

package/components/ListLoader/index.controlled.js

@@ -1,9 +1,9 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { integersBetween } from '../../agnostic/arrays/integers-between/index.js';
 import { clss } from '../../agnostic/css/clss/index.js';
+import { mergeClassNames } from '../../agnostic/css/merge-class-names/index.js';
 import { IntersectionObserverComponent } from '../IntersectionObserver/index.js';
-import { mergeClassNames } from '../utils/index.js';
 import { listLoader as publicClassName } from '../public-classnames.js';
-import { rangeBetween } from './utils.js';
 import cssModule from './styles.module.css';
 /**
  * Presentational layer of the paginated list. Renders already-loaded pages as a
@@ -65,21 +65,27 @@ export const ControlledListLoader = ({ className, pages, firstPagePos, lastPageP
         const prevPage = loadedPages[pos - 1];
         if (prevPage === undefined)
             return [];
-        return rangeBetween(prevPage + 1, pagePos - 1);
+        return integersBetween(prevPage + 1, pagePos - 1);
     });
-    const slots = [
-        ...firstLoadedPage !== undefined && firstLoadedPage > firstPagePos
-            ? [{ pagePos: firstLoadedPage - 1, kind: 'prev' }]
-            : [],
-        ...loadedPages.map(pagePos => ({ pagePos, kind: 'items' })),
-        ...gapPages.map(pagePos => ({ pagePos, kind: 'gap' })),
-        ...lastLoadedPage !== undefined && lastLoadedPage < lastPagePos
-            ? [{ pagePos: lastLoadedPage + 1, kind: 'next' }]
-            : []
-    ].sort((a, b) => a.pagePos - b.pagePos);
     const sortedLoadingPages = [...loadingPages ?? []]
         .filter(pagePos => inBoundsPages.includes(pagePos))
         .sort((a, b) => a - b);
+    const hasNothing = loadedPages.length === 0 && sortedLoadingPages.length === 0;
+    const slots = hasNothing
+        ? [{
+                pagePos: [...inBoundsPages].sort((a, b) => a - b)[0] ?? firstPagePos,
+                kind: 'gap'
+            }]
+        : [
+            ...firstLoadedPage !== undefined && firstLoadedPage > firstPagePos
+                ? [{ pagePos: firstLoadedPage - 1, kind: 'prev' }]
+                : [],
+            ...loadedPages.map(pagePos => ({ pagePos, kind: 'items' })),
+            ...gapPages.map(pagePos => ({ pagePos, kind: 'gap' })),
+            ...lastLoadedPage !== undefined && lastLoadedPage < lastPagePos
+                ? [{ pagePos: lastLoadedPage + 1, kind: 'next' }]
+                : []
+        ].sort((a, b) => a.pagePos - b.pagePos);
     const c = clss(publicClassName, { cssModule });
     const rootClss = mergeClassNames(c(null, { loading: sortedLoadingPages.length > 0 }), className);
     const renderLoadButton = (pagePos, kind) => {

package/components/ListLoader/index.js

@@ -1,9 +1,9 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef, useState } from 'react';
+import { integersBetween } from '../../agnostic/arrays/integers-between/index.js';
 import { toError } from '../../agnostic/misc/cast/index.js';
 import { clamp } from '../../agnostic/numbers/clamp/index.js';
 import { ControlledListLoader } from './index.controlled.js';
-import { rangeBetween } from './utils.js';
 /**
  * Paginated list abstraction. Fetches the pages it is asked for, keeps them
  * fresh, and drives a {@link ControlledListLoader} with the result.
@@ -32,6 +32,7 @@ export const ListLoader = ({ className, pages, defaultPage, fillGaps = true, dro
         clamp(defaultPage ?? firstPagePos, firstPagePos, lastPagePos)
     ]);
     const requestedPages = useRef(new Set());
+    const retryTimeouts = useRef(new Set());
     // Single source of truth for what should be loaded. Memoized so the effects
     // below keep a stable dependency when the page set has not actually changed.
     const currentPages = useMemo(() => (pages ?? internalPages).filter(page => page >= firstPagePos && page <= lastPagePos), [pages, internalPages, firstPagePos, lastPagePos]);
@@ -45,6 +46,11 @@ export const ListLoader = ({ className, pages, defaultPage, fillGaps = true, dro
                 return kept.length === next.length ? next : kept;
             });
         }
+        const gaveUp = requestedPages.current.has(pagePos)
+            && !itemsPages.has(pagePos)
+            && !loadingPages.has(pagePos);
+        if (gaveUp)
+            loadPage(pagePos);
         onLoadPageClicked?.(pagePos);
     };
     const storePage = (page, items) => setItemsPages(curr => {
@@ -85,9 +91,19 @@ export const ListLoader = ({ className, pages, defaultPage, fillGaps = true, dro
             reportFetchError(page, err);
             if (retriesLeft <= 0)
                 return setPageLoading(page, false);
-            window.setTimeout(() => loadPage(page, retriesLeft - 1), fetchRetriesDelayMs);
+            const timeout = window.setTimeout(() => {
+                retryTimeouts.current.delete(timeout);
+                loadPage(page, retriesLeft - 1);
+            }, fetchRetriesDelayMs);
+            retryTimeouts.current.add(timeout);
         });
     };
+    // Fx. dep. none - Emptying `requestedPages` is what stops a fetch already in flight.
+    useEffect(() => () => {
+        retryTimeouts.current.forEach(timeout => { window.clearTimeout(timeout); });
+        retryTimeouts.current.clear();
+        requestedPages.current.clear();
+    }, []);
     // Fx. dep. `currentPages` - Drops everything held for pages no longer wanted.
     // The updaters return `curr` untouched when nothing was removed, so an unstable
     // `pages` prop cannot spin the render loop.
@@ -112,7 +128,7 @@ export const ListLoader = ({ className, pages, defaultPage, fillGaps = true, dro
         setInternalPages(curr => {
             if (curr.length === 0)
                 return curr;
-            const missing = rangeBetween(Math.min(...curr), Math.max(...curr))
+            const missing = integersBetween(Math.min(...curr), Math.max(...curr))
                 .filter(page => !curr.includes(page));
             if (missing.length === 0)
                 return curr;

package/components/Overlayer/index.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { clss } from '../../agnostic/css/clss/index.js';
 import { isFalsy } from '../../agnostic/booleans/is-falsy/index.js';
-import { mergeClassNames } from '../utils/index.js';
+import { mergeClassNames } from '../../agnostic/css/merge-class-names/index.js';
 import { overlayer as publicClassName } from '../public-classnames.js';
 import cssModule from './styles.module.css';
 /**

package/components/Paginator/index.js

@@ -1,7 +1,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useRef, Children, useState } from 'react';
+import { useStateChangeDispatch } from '../../agnostic/@react/effects/use-state-change-dispatch/index.js';
 import { clss } from '../../agnostic/css/clss/index.js';
-import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
+import { mergeClassNames } from '../../agnostic/css/merge-class-names/index.js';
 import { paginator as publicClassName } from '../public-classnames.js';
 import cssModule from './styles.module.css';
 /**
@@ -63,10 +64,10 @@ export const Paginator = ({ thresholdOffsetPercent, onDirectionChanged, onPagesC
         console.warn('Paginator: thresholdOffsetPercent must be a number between 0 and 100, received', thresholdOffsetPercent, `— clamped to ${thresholdPercent}.`);
     }, [thresholdOffsetPercent, thresholdPercent]);
     // State dispatch
-    useChangeDispatch(pagesState, pages => onPagesChanged?.(Array
+    useStateChangeDispatch(pagesState, pages => onPagesChanged?.(Array
         .from(pages)
         .map(([, pageState]) => pageState)));
-    useChangeDispatch(directionState, onDirectionChanged);
+    useStateChangeDispatch(directionState, onDirectionChanged);
     // Catch scroll direction listening on scroll events
     useEffect(() => {
         let lastCall = 0;

package/components/ResizeObserver/index.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useRef, useEffect, useState } from 'react';
 import { clss } from '../../agnostic/css/clss/index.js';
-import { mergeClassNames } from '../utils/index.js';
+import { mergeClassNames } from '../../agnostic/css/merge-class-names/index.js';
 import { resizeObserver as publicClassName } from '../public-classnames.js';
 import cssModule from './styles.module.css';
 /**

package/components/Scrllgngn/index.d.ts

@@ -1,6 +1,6 @@
-import { type PropsWithChildren, type FunctionComponent } from 'react';
+import { type FunctionComponent, type PropsWithChildren } from 'react';
 import type { WithClassName } from '../utils/types.js';
-import { type TrackedBlockContext, type ViewportOffset } from './utils.js';
+import type { ForceStickMode, StickyDepth, TrackedBlockContext, ViewportOffset } from './types.js';
 /**
  * Common properties shared by all block types.
  *
@@ -34,7 +34,7 @@ export type PropsScrollBlock = PropsCommonBlock & {
  * stacked in the order they appear across pages (ascending).
  */
 export type PropsStickyBlock = PropsCommonBlock & {
-    depth: 'back' | 'front';
+    depth: StickyDepth;
     zIndex?: number;
 };
 /**
@@ -98,7 +98,7 @@ export type Props = WithClassName<{
     viewportOffsetBottom?: ViewportOffset;
     viewportOffsetLeft?: ViewportOffset;
     stickyBlocksLazyLoadDistance?: number;
-    forceStickBlocks?: 'before' | 'after' | 'both' | 'none';
+    forceStickBlocks?: ForceStickMode;
     onPageChanged?: (payload: {
         currentPagePos: number;
         pageData?: PropsPage;

package/components/Scrllgngn/index.js

@@ -1,12 +1,13 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useRef, useState } from 'react';
+import { useStateChangeDispatch } from '../../agnostic/@react/effects/use-state-change-dispatch/index.js';
 import { clss } from '../../agnostic/css/clss/index.js';
 import { randomHash } from '../../agnostic/random/uuid/index.js';
+import { mergeClassNames } from '../../agnostic/css/merge-class-names/index.js';
 import { IntersectionObserverComponent } from '../IntersectionObserver/index.js';
 import { Paginator } from '../Paginator/index.js';
 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, toPaginatorThresholdPercent, toScreenCssProps, toThresholdY, toTrackedBlockContext, toTrackedBlockCssProps, toTrackedBlockDataAttributes, toViewportOffsetCssProps, toVisibleZoneRect, toVisibleZoneRootMargin, visibleZonePollInterval, visibleZonesAreEqual } from './utils.js';
 import cssModule from './styles.module.css';
@@ -254,11 +255,11 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, viewportOffsetTop, vi
         return () => window.clearInterval(interval);
     }, [isOnScreen, readVisibleZone]);
     // Handlers
-    useChangeDispatch(currentPagePos, pagePos => onPageChanged?.({
+    useStateChangeDispatch(currentPagePos, pagePos => onPageChanged?.({
         currentPagePos: pagePos,
         pageData: pages?.[pagePos]
     }));
-    useChangeDispatch(contentVisible, onContentVisibilityChanged);
+    useStateChangeDispatch(contentVisible, onContentVisibilityChanged);
     const handleTopBoundDetect = e => setTopVis(e.ioEntry?.isIntersecting ?? false);
     const handleCntDetect = e => setCntVis(e.ioEntry?.isIntersecting ?? false);
     const handleBtmBoundDetect = e => setBtmVis(e.ioEntry?.isIntersecting ?? false);

package/components/Scrllgngn/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The depths that lift a block out of the scroll flow.
+ *
+ * **Exported because a consumer has to validate what it is handed**, and a type gives a
+ * runtime validator nothing to compare against. A block declaring one of these is
+ * consolidated across the pages it appears on and rendered in that layer, not inline.
+ */
+export declare const SCRLLGNGN_STICKY_DEPTHS: readonly ["back", "front"];
+export type StickyDepth = typeof SCRLLGNGN_STICKY_DEPTHS[number];
+/**
+ * Which out-of-range sticky blocks are forced into a stuck state.
+ *
+ * Exported for the same reason as {@link SCRLLGNGN_STICKY_DEPTHS}: the list is what a
+ * validator needs, and the day a mode is added is the day a caller writing it would
+ * otherwise silently get nothing.
+ */
+export declare const SCRLLGNGN_FORCE_STICK_MODES: readonly ["before", "after", "both", "none"];
+export type ForceStickMode = typeof SCRLLGNGN_FORCE_STICK_MODES[number];
+/** A length as authored: a bare number means pixels, a string is CSS's problem. */
+export type ViewportOffset = number | string;
+/**
+ * Where one tracked block stands in the scroll, as handed to its `onScrolled`.
+ *
+ * Every progression is a `0`–`1` ratio measured against the threshold line, and
+ * weighted **by pixel height**: a zone of unequal pages is not the same as
+ * `(indexOfCurrentPage + currentPageProgression) / displayZone.length`.
+ *
+ * @property currentPage - Zero-based position of the page in view.
+ * @property currentPageProgression - `0` when the current page's top meets the
+ * threshold, `1` when its bottom does.
+ * @property displayZone - Every page the block's `id` appears on. A block without
+ * an `id` shows on one page, so its zone holds that page alone and its three
+ * progressions are equal.
+ * @property indexOfCurrentPageInDisplayZone - Where `currentPage` sits in
+ * `displayZone`.
+ * @property displayZoneProgression - Progression across the whole zone. On a zone
+ * like `[2, 3, 5]` it runs 0 → ~0.66 over pages 2–3, pauses while page 4 shows the
+ * block nowhere, then resumes to 1 on page 5.
+ * @property contiguousDisplayZone - The unbroken run of `displayZone` containing
+ * `currentPage` — `[2, 3]` for the zone above while on page 2 or 3.
+ * @property indexOfCurrentPageInContiguousDisplayZone - Where `currentPage` sits in
+ * `contiguousDisplayZone`.
+ * @property contiguousDisplayZoneProgression - Progression across that run alone,
+ * so it always spans a full 0 → 1.
+ */
+export type TrackedBlockContext = {
+    currentPage: number;
+    currentPageProgression: number;
+    displayZone: number[];
+    indexOfCurrentPageInDisplayZone: number;
+    displayZoneProgression: number;
+    contiguousDisplayZone: number[];
+    indexOfCurrentPageInContiguousDisplayZone: number;
+    contiguousDisplayZoneProgression: number;
+};

package/components/Scrllgngn/types.js

@@ -0,0 +1,24 @@
+/**
+ * The depths that lift a block out of the scroll flow.
+ *
+ * **Exported because a consumer has to validate what it is handed**, and a type gives a
+ * runtime validator nothing to compare against. A block declaring one of these is
+ * consolidated across the pages it appears on and rendered in that layer, not inline.
+ */
+export const SCRLLGNGN_STICKY_DEPTHS = [
+    'back',
+    'front'
+];
+/**
+ * Which out-of-range sticky blocks are forced into a stuck state.
+ *
+ * Exported for the same reason as {@link SCRLLGNGN_STICKY_DEPTHS}: the list is what a
+ * validator needs, and the day a mode is added is the day a caller writing it would
+ * otherwise silently get nothing.
+ */
+export const SCRLLGNGN_FORCE_STICK_MODES = [
+    'before',
+    'after',
+    'both',
+    'none'
+];

package/components/Scrllgngn/utils.d.ts

@@ -1,4 +1,5 @@
 import type { PropsBlock, PropsPage, PropsStickyBlock } from './index.js';
+import type { StickyDepth, TrackedBlockContext, ViewportOffset } from './types.js';
 /** The subset of a bounding rect a {@link Scrllgngn} tracks and exposes. */
 export type ScreenRect = {
     left: number;
@@ -37,7 +38,7 @@ export declare function consolidateStickyBlocks(pages?: PropsPage[]): Map<string
  * by ascending `zIndex`. The id comes along because it is what identifies the block
  * across renders — its own `id` is optional, a consolidation key never is.
  */
-export declare function lazyLoadedBlocks(blocks: Map<string, ConsolidatedStickyBlock>, depth: 'back' | 'front', currentPagePos: number, lazyLoadDistance: number): Array<[string, ConsolidatedStickyBlock]>;
+export declare function lazyLoadedBlocks(blocks: Map<string, ConsolidatedStickyBlock>, depth: StickyDepth, currentPagePos: number, lazyLoadDistance: number): Array<[string, ConsolidatedStickyBlock]>;
 /**
  * Builds the CSS custom properties exposed on a {@link Scrllgngn} root.
  *
@@ -58,41 +59,6 @@ export declare function lazyLoadedBlocks(blocks: Map<string, ConsolidatedStickyB
  * @returns The custom properties, keyed by their full name.
  */
 export declare function toScreenCssProps(rect?: ScreenRect, zone?: VisibleZoneRect): Record<string, string>;
-/**
- * Where one tracked block stands in the scroll, as handed to its `onScrolled`.
- *
- * Every progression is a `0`–`1` ratio measured against the threshold line, and
- * weighted **by pixel height**: a zone of unequal pages is not the same as
- * `(indexOfCurrentPage + currentPageProgression) / displayZone.length`.
- *
- * @property currentPage - Zero-based position of the page in view.
- * @property currentPageProgression - `0` when the current page's top meets the
- * threshold, `1` when its bottom does.
- * @property displayZone - Every page the block's `id` appears on. A block without
- * an `id` shows on one page, so its zone holds that page alone and its three
- * progressions are equal.
- * @property indexOfCurrentPageInDisplayZone - Where `currentPage` sits in
- * `displayZone`.
- * @property displayZoneProgression - Progression across the whole zone. On a zone
- * like `[2, 3, 5]` it runs 0 → ~0.66 over pages 2–3, pauses while page 4 shows the
- * block nowhere, then resumes to 1 on page 5.
- * @property contiguousDisplayZone - The unbroken run of `displayZone` containing
- * `currentPage` — `[2, 3]` for the zone above while on page 2 or 3.
- * @property indexOfCurrentPageInContiguousDisplayZone - Where `currentPage` sits in
- * `contiguousDisplayZone`.
- * @property contiguousDisplayZoneProgression - Progression across that run alone,
- * so it always spans a full 0 → 1.
- */
-export type TrackedBlockContext = {
-    currentPage: number;
-    currentPageProgression: number;
-    displayZone: number[];
-    indexOfCurrentPageInDisplayZone: number;
-    displayZoneProgression: number;
-    contiguousDisplayZone: number[];
-    indexOfCurrentPageInContiguousDisplayZone: number;
-    contiguousDisplayZoneProgression: number;
-};
 /** How far the threshold line has travelled through one page, in pixels. */
 export type PageScrollMetrics = {
     scrolled: number;
@@ -200,8 +166,6 @@ export type VisibleZoneRect = {
     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;

package/components/ScrollListener/index.d.ts

@@ -12,9 +12,6 @@ import type { ScrollListenerAction } from './types.js';
  * which is what this component has always done — a starting point and not a setting,
  * hence `default…`. `defaultTracking={false}` with `whenVisible='track'` is the old
  * `startOnVisible`, written in the shared grammar.
- * @property behavioursSuspended - Holds back the instructions that **start** something,
- * and lets through those that stop it. A gate reaches `'track'`: measuring a subtree
- * nobody is being shown is work done for no one.
  * @property onIsTrackingChanged - Called once the effective tracking state changed.
  * @property onScrollStateChanged - Called after the measured {@link ScrollState}
  * changed. Receives `undefined` until the first measurement lands.
@@ -42,9 +39,7 @@ export type Props = PropsWithChildren<WithClassName<{
     onScrollStateChanged?: (scrollState?: ScrollState) => void;
     onScrollProgressChanged?: (progress: number) => void;
     onScrollDirectionChanged?: (direction: 'up' | 'down') => void;
-}>> & ViewportBehaviours<ScrollListenerAction> & {
-    behavioursSuspended?: boolean;
-};
+}>> & ViewportBehaviours<ScrollListenerAction>;
 /**
  * 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

package/components/ScrollListener/index.js

@@ -1,8 +1,9 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from 'react';
+import { useStateChangeDispatch } from '../../agnostic/@react/effects/use-state-change-dispatch/index.js';
 import { clss } from '../../agnostic/css/clss/index.js';
 import { randomHash } from '../../agnostic/random/uuid/index.js';
-import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
+import { mergeClassNames } from '../../agnostic/css/merge-class-names/index.js';
 import { useViewportBehaviours } from '../utils/viewport-behaviours/index.js';
 import { scrollListener as publicClassName } from '../public-classnames.js';
 import { getScrollProgress, subscribe, toScrollCssProps, unsubscribe } from './utils.js';
@@ -64,7 +65,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 = ({ tracking, defaultTracking, behavioursSuspended, visibilityThreshold, visibilityRoot, visibilityRootMargin, visibilityOnAfterMs, visibilityOffAfterMs, whenVisible, whenHidden, onIsTrackingChanged, onScrollStateChanged, onVisibilityChanged, onScrollProgressChanged, onScrollDirectionChanged, className, children }) => {
+export const ScrollListener = ({ tracking, defaultTracking, visibilityThreshold, visibilityRoot, visibilityRootMargin, visibilityOnAfterMs, visibilityOffAfterMs, whenVisible, whenHidden, onIsTrackingChanged, onScrollStateChanged, onVisibilityChanged, onScrollProgressChanged, onScrollDirectionChanged, className, children }) => {
     // State & refs
     const [subscriberId] = useState(() => randomHash(6));
     const [internalTracking, setInternalTracking] = useState(defaultTracking ?? true);
@@ -82,8 +83,8 @@ export const ScrollListener = ({ tracking, defaultTracking, behavioursSuspended,
     // `tracking`: the effective state reads the prop first, so the internal one they write
     // is simply never consulted.
     const actions = {
-        track: { kind: 'start', domain: 'tracking', run: () => setInternalTracking(true) },
-        untrack: { kind: 'stop', domain: 'tracking', run: () => setInternalTracking(false) }
+        track: { domain: 'tracking', run: () => setInternalTracking(true) },
+        untrack: { domain: 'tracking', run: () => setInternalTracking(false) }
     };
     // The surrender half of the result is dropped: this component has no control a reader
     // could take over. The observer runs on the root itself — there is no inner box any
@@ -98,13 +99,13 @@ export const ScrollListener = ({ tracking, defaultTracking, behavioursSuspended,
         whenVisible,
         whenHidden,
         onVisibilityChanged
-    }, actions, behavioursSuspended === true);
+    }, actions);
     // State dispatch
-    useChangeDispatch(isTracking, onIsTrackingChanged);
-    useChangeDispatch(scrollState, onScrollStateChanged);
-    useChangeDispatch(scrollProgress, progress => { if (progress !== undefined)
+    useStateChangeDispatch(isTracking, onIsTrackingChanged);
+    useStateChangeDispatch(scrollState, onScrollStateChanged);
+    useStateChangeDispatch(scrollProgress, progress => { if (progress !== undefined)
         onScrollProgressChanged?.(progress); });
-    useChangeDispatch(scrollDirection, direction => { if (direction !== null)
+    useStateChangeDispatch(scrollDirection, direction => { if (direction !== null)
         onScrollDirectionChanged?.(direction); });
     // Fx. dep. `scrollState` - derive the document scroll direction
     useEffect(() => {

package/components/ScrollListener/types.d.ts

@@ -24,8 +24,5 @@ export type ScrollListenerAction = ScrollListenerVerb;
  * and nothing that ever surrenders. The field is part of `ActionSpec` and is declared
  * honestly rather than split into domains no hand could ever tell apart. The consequence
  * is that `':force'` has no trigger here.
- *
- * A gate is the other brake, and it does reach `track`: measuring a subtree nobody is
- * being shown is work done for no one.
  */
 export type ScrollListenerDomain = 'tracking';

package/components/Select/index.js

@@ -3,7 +3,7 @@ import { useState } from 'react';
 import { clss } from '../../agnostic/css/clss/index.js';
 import { isNotFalsy } from '../../agnostic/booleans/is-falsy/index.js';
 import { randomHash } from '../../agnostic/random/uuid/index.js';
-import { mergeClassNames } from '../utils/index.js';
+import { mergeClassNames } from '../../agnostic/css/merge-class-names/index.js';
 import { select as publicClassName } from '../public-classnames.js';
 import cssModule from './styles.module.css';
 /**