@design-edito/tools 0.5.4 → 0.5.6

package/agnostic/colors/index.d.ts

@@ -4,9 +4,9 @@ export * as convert from './convert/index.js'
 export * as distance from './distance/index.js'
 export * as grayscale from './grayscale/index.js'
 export * as invert from './invert/index.js'
-export * as lerp from './lerp/index.js'
 export * as luminance from './luminance/index.js'
+export * as lerp from './lerp/index.js'
 export * as palette from './palette/index.js'
-export * as rotate from './rotate/index.js'
 export * as tidy from './tidy/index.js'
+export * as rotate from './rotate/index.js'
 export * as typechecks from './typechecks/index.js'

package/agnostic/colors/index.js

@@ -4,9 +4,9 @@ export * as convert from './convert/index.js'
 export * as distance from './distance/index.js'
 export * as grayscale from './grayscale/index.js'
 export * as invert from './invert/index.js'
-export * as lerp from './lerp/index.js'
 export * as luminance from './luminance/index.js'
+export * as lerp from './lerp/index.js'
 export * as palette from './palette/index.js'
-export * as rotate from './rotate/index.js'
 export * as tidy from './tidy/index.js'
+export * as rotate from './rotate/index.js'
 export * as typechecks from './typechecks/index.js'

package/agnostic/html/hyper-json/smart-tags/coalesced/index.d.ts

@@ -2,9 +2,9 @@ export * as add from './add/index.js'
 export * as addclass from './addclass/index.js'
 export * as and from './and/index.js'
 export * as append from './append/index.js'
+export * as clone from './clone/index.js'
 export * as at from './at/index.js'
 export * as call from './call/index.js'
-export * as clone from './clone/index.js'
 export * as deleteproperties from './deleteproperties/index.js'
 export * as equals from './equals/index.js'
 export * as getattribute from './getattribute/index.js'
@@ -12,22 +12,22 @@ export * as getproperties from './getproperties/index.js'
 export * as getproperty from './getproperty/index.js'
 export * as hjparse from './hjparse/index.js'
 export * as hjstringify from './hjstringify/index.js'
-export * as if from './if/index.js'
 export * as initialize from './initialize/index.js'
+export * as if from './if/index.js'
 export * as join from './join/index.js'
+export * as map from './map/index.js'
 export * as length from './length/index.js'
 export * as negate from './negate/index.js'
-export * as map from './map/index.js'
 export * as notrailing from './notrailing/index.js'
-export * as or from './or/index.js'
 export * as pickrandom from './pickrandom/index.js'
 export * as populate from './populate/index.js'
 export * as print from './print/index.js'
-export * as push from './push/index.js'
+export * as or from './or/index.js'
 export * as pusheach from './pusheach/index.js'
 export * as recordtoarray from './recordtoarray/index.js'
 export * as removeattribute from './removeattribute/index.js'
 export * as removeclass from './removeclass/index.js'
+export * as push from './push/index.js'
 export * as renameproperty from './renameproperty/index.js'
 export * as replace from './replace/index.js'
 export * as select from './select/index.js'
@@ -48,5 +48,5 @@ export * as torecord from './torecord/index.js'
 export * as toref from './toref/index.js'
 export * as tostring from './tostring/index.js'
 export * as totext from './totext/index.js'
-export * as transformselected from './transformselected/index.js'
 export * as trim from './trim/index.js'
+export * as transformselected from './transformselected/index.js'

package/agnostic/html/hyper-json/smart-tags/coalesced/index.js

@@ -2,9 +2,9 @@ export * as add from './add/index.js'
 export * as addclass from './addclass/index.js'
 export * as and from './and/index.js'
 export * as append from './append/index.js'
+export * as clone from './clone/index.js'
 export * as at from './at/index.js'
 export * as call from './call/index.js'
-export * as clone from './clone/index.js'
 export * as deleteproperties from './deleteproperties/index.js'
 export * as equals from './equals/index.js'
 export * as getattribute from './getattribute/index.js'
@@ -12,22 +12,22 @@ export * as getproperties from './getproperties/index.js'
 export * as getproperty from './getproperty/index.js'
 export * as hjparse from './hjparse/index.js'
 export * as hjstringify from './hjstringify/index.js'
-export * as if from './if/index.js'
 export * as initialize from './initialize/index.js'
+export * as if from './if/index.js'
 export * as join from './join/index.js'
+export * as map from './map/index.js'
 export * as length from './length/index.js'
 export * as negate from './negate/index.js'
-export * as map from './map/index.js'
 export * as notrailing from './notrailing/index.js'
-export * as or from './or/index.js'
 export * as pickrandom from './pickrandom/index.js'
 export * as populate from './populate/index.js'
 export * as print from './print/index.js'
-export * as push from './push/index.js'
+export * as or from './or/index.js'
 export * as pusheach from './pusheach/index.js'
 export * as recordtoarray from './recordtoarray/index.js'
 export * as removeattribute from './removeattribute/index.js'
 export * as removeclass from './removeclass/index.js'
+export * as push from './push/index.js'
 export * as renameproperty from './renameproperty/index.js'
 export * as replace from './replace/index.js'
 export * as select from './select/index.js'
@@ -48,5 +48,5 @@ export * as torecord from './torecord/index.js'
 export * as toref from './toref/index.js'
 export * as tostring from './tostring/index.js'
 export * as totext from './totext/index.js'
-export * as transformselected from './transformselected/index.js'
 export * as trim from './trim/index.js'
+export * as transformselected from './transformselected/index.js'

package/agnostic/html/hyper-json/smart-tags/isolated/index.d.ts

@@ -1,12 +1,12 @@
 export * as any from './any/index.js'
-export * as array from './array/index.js'
 export * as boolean from './boolean/index.js'
+export * as array from './array/index.js'
 export * as element from './element/index.js'
 export * as get from './get/index.js'
 export * as guess from './guess/index.js'
 export * as null from './null/index.js'
-export * as number from './number/index.js'
 export * as nodelist from './nodelist/index.js'
+export * as number from './number/index.js'
 export * as record from './record/index.js'
 export * as ref from './ref/index.js'
 export * as string from './string/index.js'

package/agnostic/html/hyper-json/smart-tags/isolated/index.js

@@ -1,12 +1,12 @@
 export * as any from './any/index.js'
-export * as array from './array/index.js'
 export * as boolean from './boolean/index.js'
+export * as array from './array/index.js'
 export * as element from './element/index.js'
 export * as get from './get/index.js'
 export * as guess from './guess/index.js'
 export * as null from './null/index.js'
-export * as number from './number/index.js'
 export * as nodelist from './nodelist/index.js'
+export * as number from './number/index.js'
 export * as record from './record/index.js'
 export * as ref from './ref/index.js'
 export * as string from './string/index.js'

package/agnostic/html/index.d.ts

@@ -6,5 +6,5 @@ export * as insertNode from './insert-node/index.js'
 export * as placeholders from './placeholders/index.js'
 export * as replaceInElement from './replace-in-element/index.js'
 export * as selectorToElement from './selector-to-element/index.js'
-export * as stringToNodes from './string-to-nodes/index.js'
 export * as watchSelection from './watch-selection/index.js'
+export * as stringToNodes from './string-to-nodes/index.js'

package/agnostic/html/index.js

@@ -6,5 +6,5 @@ export * as insertNode from './insert-node/index.js'
 export * as placeholders from './placeholders/index.js'
 export * as replaceInElement from './replace-in-element/index.js'
 export * as selectorToElement from './selector-to-element/index.js'
-export * as stringToNodes from './string-to-nodes/index.js'
 export * as watchSelection from './watch-selection/index.js'
+export * as stringToNodes from './string-to-nodes/index.js'

package/agnostic/index.d.ts

@@ -1,6 +1,7 @@
 export * as arrays from './arrays/index.js'
 export * as booleans from './booleans/index.js'
 export * as colors from './colors/index.js'
+export * as css from './css/index.js'
 export * as errors from './errors/index.js'
 export * as html from './html/index.js'
 export * as misc from './misc/index.js'
@@ -9,8 +10,7 @@ export * as objects from './objects/index.js'
 export * as optim from './optim/index.js'
 export * as random from './random/index.js'
 export * as regexps from './regexps/index.js'
-export * as strings from './strings/index.js'
 export * as sanitization from './sanitization/index.js'
+export * as strings from './strings/index.js'
 export * as time from './time/index.js'
 export * as typescript from './typescript/index.js'
-export * as css from './css/index.js'

package/agnostic/index.js

@@ -1,6 +1,7 @@
 export * as arrays from './arrays/index.js'
 export * as booleans from './booleans/index.js'
 export * as colors from './colors/index.js'
+export * as css from './css/index.js'
 export * as errors from './errors/index.js'
 export * as html from './html/index.js'
 export * as misc from './misc/index.js'
@@ -9,8 +10,7 @@ export * as objects from './objects/index.js'
 export * as optim from './optim/index.js'
 export * as random from './random/index.js'
 export * as regexps from './regexps/index.js'
-export * as strings from './strings/index.js'
 export * as sanitization from './sanitization/index.js'
+export * as strings from './strings/index.js'
 export * as time from './time/index.js'
 export * as typescript from './typescript/index.js'
-export * as css from './css/index.js'

package/agnostic/misc/index.d.ts

@@ -1,11 +1,11 @@
 export * as assert from './assert/index.js'
-export * as cast from './cast/index.js'
 export * as connection from './connection/index.js'
 export * as crawler from './crawler/index.js'
 export * as crossenv from './crossenv/index.js'
 export * as dataSize from './data-size/index.js'
 export * as isConstructorFunction from './is-constructor-function/index.js'
 export * as isNullish from './is-nullish/index.js'
+export * as cast from './cast/index.js'
 export * as logs from './logs/index.js'
 export * as loremIpsum from './lorem-ipsum/index.js'
 export * as normalizeExtension from './normalize-extension/index.js'

package/agnostic/misc/index.js

@@ -1,11 +1,11 @@
 export * as assert from './assert/index.js'
-export * as cast from './cast/index.js'
 export * as connection from './connection/index.js'
 export * as crawler from './crawler/index.js'
 export * as crossenv from './crossenv/index.js'
 export * as dataSize from './data-size/index.js'
 export * as isConstructorFunction from './is-constructor-function/index.js'
 export * as isNullish from './is-nullish/index.js'
+export * as cast from './cast/index.js'
 export * as logs from './logs/index.js'
 export * as loremIpsum from './lorem-ipsum/index.js'
 export * as normalizeExtension from './normalize-extension/index.js'

package/agnostic/misc/logs/index.d.ts

@@ -1,3 +1,3 @@
+export * as logger from './logger/index.js'
 export * as makeTextBlock from './make-text-block/index.js'
 export * as styles from './styles/index.js'
-export * as logger from './logger/index.js'

package/agnostic/misc/logs/index.js

@@ -1,3 +1,3 @@
+export * as logger from './logger/index.js'
 export * as makeTextBlock from './make-text-block/index.js'
 export * as styles from './styles/index.js'
-export * as logger from './logger/index.js'

package/agnostic/numbers/index.d.ts

@@ -1,6 +1,6 @@
 export * as absoluteModulo from './absolute-modulo/index.js'
-export * as approximateRational from './approximate-rational/index.js'
 export * as clamp from './clamp/index.js'
-export * as interpolate from './interpolate/index.js'
+export * as approximateRational from './approximate-rational/index.js'
 export * as geometricProgressions from './geometric-progressions/index.js'
+export * as interpolate from './interpolate/index.js'
 export * as round from './round/index.js'

package/agnostic/numbers/index.js

@@ -1,6 +1,6 @@
 export * as absoluteModulo from './absolute-modulo/index.js'
-export * as approximateRational from './approximate-rational/index.js'
 export * as clamp from './clamp/index.js'
-export * as interpolate from './interpolate/index.js'
+export * as approximateRational from './approximate-rational/index.js'
 export * as geometricProgressions from './geometric-progressions/index.js'
+export * as interpolate from './interpolate/index.js'
 export * as round from './round/index.js'

package/agnostic/objects/index.d.ts

@@ -1,8 +1,8 @@
 export * as deepGetProperty from './deep-get-property/index.js'
 export * as enums from './enums/index.js'
 export * as flattenGetters from './flatten-getters/index.js'
-export * as isObject from './is-object/index.js'
 export * as isRecord from './is-record/index.js'
+export * as isObject from './is-object/index.js'
 export * as recordFormat from './record-format/index.js'
 export * as recordMap from './record-map/index.js'
 export * as sortKeys from './sort-keys/index.js'

package/agnostic/objects/index.js

@@ -1,8 +1,8 @@
 export * as deepGetProperty from './deep-get-property/index.js'
 export * as enums from './enums/index.js'
 export * as flattenGetters from './flatten-getters/index.js'
-export * as isObject from './is-object/index.js'
 export * as isRecord from './is-record/index.js'
+export * as isObject from './is-object/index.js'
 export * as recordFormat from './record-format/index.js'
 export * as recordMap from './record-map/index.js'
 export * as sortKeys from './sort-keys/index.js'

package/agnostic/strings/index.d.ts

@@ -1,8 +1,8 @@
-export * as matches from './matches/index.js'
 export * as charCodes from './char-codes/index.js'
+export * as matches from './matches/index.js'
 export * as normalizeIndent from './normalize-indent/index.js'
 export * as parseTable from './parse-table/index.js'
-export * as replaceAll from './replace-all/index.js'
 export * as splitTrim from './split-trim/index.js'
 export * as toAlphanum from './to-alphanum/index.js'
 export * as trim from './trim/index.js'
+export * as replaceAll from './replace-all/index.js'

package/agnostic/strings/index.js

@@ -1,8 +1,8 @@
-export * as matches from './matches/index.js'
 export * as charCodes from './char-codes/index.js'
+export * as matches from './matches/index.js'
 export * as normalizeIndent from './normalize-indent/index.js'
 export * as parseTable from './parse-table/index.js'
-export * as replaceAll from './replace-all/index.js'
 export * as splitTrim from './split-trim/index.js'
 export * as toAlphanum from './to-alphanum/index.js'
 export * as trim from './trim/index.js'
+export * as replaceAll from './replace-all/index.js'

package/components/Clippable/index.d.ts

@@ -10,6 +10,8 @@ import type { WithClassName } from '../utils/types.js';
  * clipboard content is resolved, with the container's raw HTML.
  * @property onClipped - Called once content has been written to the clipboard.
  * Not called when the write fails.
+ * @property onCopyFailed - Called when the clipboard write throws, with the
+ * error. When set, the error is no longer logged to the console.
  * @property className - Additional class name(s) applied to the root element.
  * @property children - Content rendered inside the copyable container.
  */
@@ -17,6 +19,7 @@ export type Props = PropsWithChildren<WithClassName<{
     toClip?: string | ((curr: string | undefined) => string | undefined);
     onCopyClicked?: (e: MouseEvent<HTMLButtonElement, globalThis.MouseEvent>, rawContent: string | undefined) => void;
     onClipped?: (content: string) => void;
+    onCopyFailed?: (error: unknown) => void;
 }>>;
 /**
  * Clipboard-enabled container. Renders arbitrary content alongside a copy
@@ -34,7 +37,8 @@ export type Props = PropsWithChildren<WithClassName<{
  * @returns A copy-enabled content container.
  *
  * @remarks
- * A failed clipboard write is logged and leaves the component untouched:
- * neither `onClipped` nor the `clipped` modifier fires.
+ * A failed clipboard write fires `onCopyFailed` (or is logged when that prop is
+ * unset) and leaves the component untouched: neither `onClipped` nor the
+ * `clipped` modifier fires.
  */
 export declare const Clippable: FunctionComponent<Props>;

package/components/Clippable/index.js

@@ -22,10 +22,11 @@ const clippedModifierDurationMs = 3000;
  * @returns A copy-enabled content container.
  *
  * @remarks
- * A failed clipboard write is logged and leaves the component untouched:
- * neither `onClipped` nor the `clipped` modifier fires.
+ * A failed clipboard write fires `onCopyFailed` (or is logged when that prop is
+ * unset) and leaves the component untouched: neither `onClipped` nor the
+ * `clipped` modifier fires.
  */
-export const Clippable = ({ className, children, toClip, onCopyClicked, onClipped }) => {
+export const Clippable = ({ className, children, toClip, onCopyClicked, onClipped, onCopyFailed }) => {
     // State & refs
     const [hasBeenRecentlyClipped, setHasBeenRecentlyClipped] = useState(false);
     const contentRef = useRef(null);
@@ -50,8 +51,11 @@ export const Clippable = ({ className, children, toClip, onCopyClicked, onClippe
             ]);
         }
         catch (err) {
+            if (onCopyFailed !== undefined)
+                onCopyFailed(err);
             // eslint-disable-next-line no-console
-            console.error(err);
+            else
+                console.error(err);
             return;
         }
         onClipped?.(html);

package/components/Drawer/index.d.ts

@@ -15,6 +15,8 @@ import type { WithClassName } from '../utils/types.js';
  * drawer reacts, with the open state as it was.
  * @property onIsOpenedChanged - Called after the open state changed, with the
  * new value.
+ * @property onContentResized - Called after the measured content size changed,
+ * with the new width and height in pixels. Never on mount.
  * @property className - Additional class name(s) applied to the root element.
  * @property children - Drawer content.
  */
@@ -26,6 +28,10 @@ export type Props = PropsWithChildren<WithClassName<{
     onOpenerClicked?: (isOpened: boolean) => void;
     onCloserClicked?: (isOpened: boolean) => void;
     onIsOpenedChanged?: (isOpened: boolean) => void;
+    onContentResized?: (dimensions: {
+        width: number;
+        height: number;
+    }) => void;
 }>>;
 /**
  * Drawer component supporting controlled and uncontrolled usage.

package/components/Drawer/index.js

@@ -40,7 +40,7 @@ import cssModule from './styles.module.css';
  *   parent needs them to know a click happened at all.
  * - `onIsOpenedChanged` fires in both modes too, and never on mount.
  */
-export const Drawer = ({ openerContent, closerContent, defaultIsOpened = false, isOpened: isOpenedProp, onOpenerClicked, onCloserClicked, onIsOpenedChanged, className, children }) => {
+export const Drawer = ({ openerContent, closerContent, defaultIsOpened = false, isOpened: isOpenedProp, onOpenerClicked, onCloserClicked, onIsOpenedChanged, onContentResized, className, children }) => {
     // State
     const [internalIsOpened, setInternalIsOpened] = useState(defaultIsOpened);
     const [contentDimensions, setContentDimensions] = useState();
@@ -48,6 +48,8 @@ export const Drawer = ({ openerContent, closerContent, defaultIsOpened = false,
     const isOpened = isOpenedProp ?? internalIsOpened;
     // State dispatch
     useChangeDispatch(isOpened, onIsOpenedChanged);
+    useChangeDispatch(contentDimensions, dimensions => { if (dimensions !== undefined)
+        onContentResized?.(dimensions); }, (a, b) => a?.width === b?.width && a?.height === b?.height);
     // User action handlers
     const handleOpenerClick = () => {
         onOpenerClicked?.(isOpened);

package/components/Gallery/index.d.ts

@@ -31,6 +31,10 @@ import type { WithClassName } from '../utils/types.js';
  * before the gallery reacts, with the active index as it was and the target index.
  * @property onActiveSlotChanged - Called after the active slot changed, with
  * the new index.
+ * @property onCanGoLeftChanged - Called after the ability to scroll further left
+ * changed, with the new value. Never on mount.
+ * @property onCanGoRightChanged - Called after the ability to scroll further
+ * right changed, with the new value. Never on mount.
  * @property className - Optional additional class name(s) applied to the root element.
  * @property children - Elements rendered as gallery slots. Each child is wrapped in a slot container.
  */
@@ -48,6 +52,8 @@ export type Props = PropsWithChildren<WithClassName<{
     onNextClicked?: (activePos: number) => void;
     onPaginationClicked?: (activePos: number, targetPos: number) => void;
     onActiveSlotChanged?: (activePos: number) => void;
+    onCanGoLeftChanged?: (canGoLeft: boolean) => void;
+    onCanGoRightChanged?: (canGoRight: boolean) => void;
 }>>;
 /**
  * Horizontally scrollable gallery component with navigation controls and pagination.

package/components/Gallery/index.js

@@ -23,7 +23,7 @@ function resolvePadding(side, shorthand) {
  * - Previous/next navigation controls,
  * - Pagination controls allowing direct slot activation.
  */
-export const Gallery = ({ paddingLeft, paddingRight, padding, prevButtonContent, nextButtonContent, paginationContent, defaultActive, active, noSnap, onPrevClicked, onNextClicked, onPaginationClicked, onActiveSlotChanged, children, className }) => {
+export const Gallery = ({ paddingLeft, paddingRight, padding, prevButtonContent, nextButtonContent, paginationContent, defaultActive, active, noSnap, onPrevClicked, onNextClicked, onPaginationClicked, onActiveSlotChanged, onCanGoLeftChanged, onCanGoRightChanged, children, className }) => {
     // State & refs
     const scrollerRef = useRef(null);
     const [activeIndex, setActiveIndex] = useState(0);
@@ -33,6 +33,8 @@ export const Gallery = ({ paddingLeft, paddingRight, padding, prevButtonContent,
     const isControlled = active !== undefined;
     // State dispatch
     useChangeDispatch(activeIndex, onActiveSlotChanged);
+    useChangeDispatch(canGoLeft, onCanGoLeftChanged);
+    useChangeDispatch(canGoRight, onCanGoRightChanged);
     // User actions handlers
     const handlePrevClick = () => {
         onPrevClicked?.(activeIndex);

package/components/Paginator/index.d.ts

@@ -32,6 +32,10 @@ type DirectionState = 'forwards' | 'backwards' | null;
  * trigger it again.
  * @property onPagesChanged - Called after any page's {@link PageState} changed,
  * with a flat array of every page's state, ordered by position.
+ * @property onPageElementsChanged - Called with the page slot elements, in order,
+ * whenever the observed set changes. Unlike the other handlers it *does* fire on
+ * mount: the elements don't exist before it, so their appearance is the change.
+ * Lets a parent measure the pages without reaching into this component's DOM.
  * @property className - Optional additional class name(s) applied to the root element.
  * @property children - Each direct child is treated as an individual page slot.
  */
@@ -39,6 +43,7 @@ export type Props = PropsWithChildren<WithClassName<{
     thresholdOffsetPercent?: number;
     onDirectionChanged?: (direction: DirectionState) => void;
     onPagesChanged?: (pages: PageState[]) => void;
+    onPageElementsChanged?: (pageElements: HTMLElement[]) => void;
 }>>;
 /**
  * A scroll-driven pagination component that tracks which child page is currently

package/components/Paginator/index.js

@@ -27,7 +27,7 @@ import cssModule from './styles.module.css';
  * - `currCount` on each {@link PageState} increments each time a page transitions
  *   into the `'curr'` position, making it useful as a re-entry counter.
  */
-export const Paginator = ({ thresholdOffsetPercent, onDirectionChanged, onPagesChanged, className, children }) => {
+export const Paginator = ({ thresholdOffsetPercent, onDirectionChanged, onPagesChanged, onPageElementsChanged, className, children }) => {
     // State, refs, effects
     const [pagesState, setPagesState] = useState(new Map());
     const [directionState, setDirectionState] = useState(null);
@@ -67,6 +67,7 @@ export const Paginator = ({ thresholdOffsetPercent, onDirectionChanged, onPagesC
         if (pagesRef.current === null)
             return;
         const pages = Array.from(pagesRef.current.children);
+        onPageElementsChanged?.(pages.filter(page => page instanceof HTMLElement));
         const observerRootMargin = `-${thresholdOffsetPercent ?? 0}%`
             + ' 0px'
             + ` -${100 - (thresholdOffsetPercent ?? 0)}%`

package/components/Scrllgngn/index.d.ts

@@ -1,17 +1,20 @@
 import { type PropsWithChildren, type FunctionComponent } from 'react';
 import type { WithClassName } from '../utils/types.js';
+import { type TrackedBlockContext } from './utils.js';
 /**
  * Common properties shared by all block types.
  *
  * @property id - Optional stable identifier for the block. Used to consolidate
  * blocks with the same id across multiple pages into a single sticky block
  * displayed across those pages.
- * @property trackScroll - Whether scroll tracking is enabled for this block.
+ * @property onScrolled - Called with this block's {@link TrackedBlockContext} on
+ * every frame the scroll moved it, while it is displayed. Declaring it is what
+ * turns tracking on for the block — nothing is measured for a block without it.
  * @property children - Content rendered inside the block.
  */
 export type PropsCommonBlock = PropsWithChildren<{
     id?: string;
-    trackScroll?: boolean;
+    onScrolled?: (context: TrackedBlockContext) => void;
 }>;
 /**
  * A block that scrolls with the page content.
@@ -74,6 +77,8 @@ export type PropsPage = {
  * @property onPageChanged - Called once the current page has changed, never on
  * mount. Receives the zero-based index of the new current page and the
  * corresponding page definition, if available.
+ * @property onContentVisibilityChanged - Called after the scrolling content
+ * area entered or left the viewport, with the new value. Never on mount.
  * @property className - Optional additional class name(s) applied to the root
  * element.
  */
@@ -83,6 +88,7 @@ export type Props = WithClassName<{
     stickyBlocksLazyLoadDistance?: number;
     forceStickBlocks?: 'before' | 'after' | 'both' | 'none';
     onPageChanged?: (currentPagePos: number, pageData?: PropsPage) => void;
+    onContentVisibilityChanged?: (isVisible: boolean) => void;
 }>;
 /**
  * Scrollytelling engine component. Orchestrates layered sticky blocks (`back`
@@ -126,10 +132,37 @@ export type Props = WithClassName<{
  * - An inline `z-index` derived from the block's position in the sorted stack
  * (overridden by {@link PropsStickyBlock.zIndex} if provided).
  *
+ * ### Scroll block elements
+ * Each scroll block sits in its own wrapper, whatever it does — a block that isn't
+ * tracked still gets one, so the DOM keeps the same shape either way.
+ *
+ * ### Tracked block elements
+ * A block declaring {@link PropsCommonBlock.onScrolled} also carries its
+ * {@link TrackedBlockContext} on its wrapper, for scrollytelling driven in CSS
+ * alone. Written straight to the element on the frames they change, so they never
+ * re-render the sequence.
+ *
+ * Progressions, as unitless `0`–`1` ratios:
+ * - `--lm-scrllgngn-block-current-page-progression-ratio`
+ * - `--lm-scrllgngn-block-display-zone-progression-ratio`
+ * - `--lm-scrllgngn-block-contiguous-display-zone-progression-ratio`
+ *
+ * Position, which only moves with the page:
+ * - `data-current-page`
+ * - `data-display-zone` — comma-separated page positions.
+ * - `data-index-of-current-page-in-display-zone`
+ * - `data-contiguous-display-zone`
+ * - `data-index-of-current-page-in-contiguous-display-zone`
+ *
  * @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.
+ *
+ * @remarks
+ * 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 declare const Scrllgngn: FunctionComponent<Props>;