@design-edito/tools 0.5.6 → 0.5.8

package/agnostic/subtitles/srt-timecode-to-ms/index.js

@@ -0,0 +1,36 @@
+/** Matches `hh:mm:ss,mmm`, with any number of digits in each field. */
+const timecodeRegexp = /^\s*(\d+):(\d+):(\d+),(\d+)\s*$/v;
+/**
+ * Reads the fractional field as a **number of digits**, not as a value.
+ *
+ * SRT writes milliseconds as a decimal fraction of a second: `,5` is half a second,
+ * where reading it as an integer would call it 5ms. Padding to three digits gives
+ * the fraction its place value back, and truncating past them drops precision the
+ * format doesn't carry.
+ */
+function fractionToMs(fraction) {
+    return parseInt(`${fraction}00`.slice(0, 3), 10);
+}
+/**
+ * Converts an SRT timecode to milliseconds.
+ *
+ * @param timecode - A timecode in `hh:mm:ss,mmm` form. Surrounding whitespace is
+ * tolerated; anything else is not a timecode.
+ * @returns The position in milliseconds, or `null` when `timecode` doesn't parse —
+ * a caller reading a subtitle file needs to tell a malformed line from one that
+ * legitimately sits at zero.
+ *
+ * @example
+ * srtTimecodeToMs('00:00:01,500') // 1500
+ * srtTimecodeToMs('00:00:01,5')   // 1500, not 1005
+ */
+export function srtTimecodeToMs(timecode) {
+    const match = timecode.match(timecodeRegexp);
+    if (match === null)
+        return null;
+    const [, hours = '0', minutes = '0', seconds = '0', fraction = '0'] = match;
+    return parseInt(hours, 10) * 60 * 60 * 1000
+        + parseInt(minutes, 10) * 60 * 1000
+        + parseInt(seconds, 10) * 1000
+        + fractionToMs(fraction);
+}

package/agnostic/subtitles/srt-timecode-to-ms/index.test.d.ts

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

package/agnostic/subtitles/srt-timecode-to-ms/index.test.js

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest';
+import { srtTimecodeToMs } from './index.js';
+describe('srtTimecodeToMs', () => {
+    it('adds up hours, minutes, seconds and milliseconds', () => {
+        expect(srtTimecodeToMs('01:02:03,004')).toBe(3723004);
+    });
+    it('sits at zero for the start of a file', () => {
+        expect(srtTimecodeToMs('00:00:00,000')).toBe(0);
+    });
+    describe('the fractional field', () => {
+        it('reads a single digit as tenths of a second', () => {
+            expect(srtTimecodeToMs('00:00:01,5')).toBe(1500);
+        });
+        it('reads two digits as hundredths', () => {
+            expect(srtTimecodeToMs('00:00:01,05')).toBe(1050);
+        });
+        it('reads three digits as milliseconds', () => {
+            expect(srtTimecodeToMs('00:00:01,005')).toBe(1005);
+        });
+        it('drops precision the format does not carry', () => {
+            expect(srtTimecodeToMs('00:00:01,5009')).toBe(1500);
+        });
+    });
+    it('tolerates surrounding whitespace, as found around an arrow', () => {
+        expect(srtTimecodeToMs(' 00:00:02,000 ')).toBe(2000);
+    });
+    it('accepts hour counts beyond two digits', () => {
+        expect(srtTimecodeToMs('100:00:00,000')).toBe(360000000);
+    });
+    describe('refusing what is not a timecode', () => {
+        it('returns null on a dot separator, which SRT does not use', () => {
+            expect(srtTimecodeToMs('00:00:01.500')).toBeNull();
+        });
+        it('returns null on a missing field', () => {
+            expect(srtTimecodeToMs('00:01,000')).toBeNull();
+        });
+        it('returns null on plain text', () => {
+            expect(srtTimecodeToMs('Bonjour')).toBeNull();
+        });
+        it('returns null rather than zero, so a caller can tell the two apart', () => {
+            expect(srtTimecodeToMs('')).toBeNull();
+        });
+    });
+});

package/components/BeforeAfter/index.controlled.d.ts

@@ -30,10 +30,11 @@ export type Props = PropsWithChildren<WithClassName<{
  * as a ratio between `0` and `1`. Handles both mouse and touch input, telling a
  * click apart from a drag.
  *
- * The active ratio is exposed as:
- * - CSS custom properties `--lm-before-after-ratio` and
- * `--lm-before-after-ratio-percent`,
- * - a `data-ratio` attribute on the root element.
+ * The divider's position is exposed on the root element as:
+ * - the unitless custom property `--lm-before-after-ratio`. No percentage twin —
+ * `calc(var(--lm-before-after-ratio) * 100%)` covers it.
+ * - a `data-ratio` attribute, for what a custom property cannot reach:
+ * `content: attr(data-ratio)` and attribute selectors.
  *
  * ### CSS modifiers
  * - `horizontal` — applied when `mode` is `'horizontal'`.

package/components/BeforeAfter/index.controlled.js

@@ -13,10 +13,11 @@ import cssModule from './styles.module.css';
  * as a ratio between `0` and `1`. Handles both mouse and touch input, telling a
  * click apart from a drag.
  *
- * The active ratio is exposed as:
- * - CSS custom properties `--lm-before-after-ratio` and
- * `--lm-before-after-ratio-percent`,
- * - a `data-ratio` attribute on the root element.
+ * The divider's position is exposed on the root element as:
+ * - the unitless custom property `--lm-before-after-ratio`. No percentage twin —
+ * `calc(var(--lm-before-after-ratio) * 100%)` covers it.
+ * - a `data-ratio` attribute, for what a custom property cannot reach:
+ * `content: attr(data-ratio)` and attribute selectors.
  *
  * ### CSS modifiers
  * - `horizontal` — applied when `mode` is `'horizontal'`.
@@ -105,8 +106,7 @@ export const ControlledBeforeAfter = ({ mode = 'horizontal', ratio = 0, before,
     }), className);
     const roundedRatio = round(clampedRatio, 4);
     const customProps = {
-        '--lm-before-after-ratio': `${roundedRatio}`,
-        '--lm-before-after-ratio-percent': `${round(clampedRatio * 100, 2)}%`
+        '--lm-before-after-ratio': `${roundedRatio}`
     };
     return _jsxs("div", { ref: rootRef, className: rootClss, onMouseDown: handlePointerDown, onMouseMove: handleMouseMove, onMouseUp: handleMouseUp, onTouchStart: handlePointerDown, onTouchMove: handleTouchMove, onTouchEnd: handleTouchEnd, style: { ...customProps }, "data-ratio": roundedRatio, children: [_jsx("div", { className: c('before'), children: before }), _jsx("div", { className: c('after'), children: after }), _jsx("div", { className: c('separator') }), children] });
 };

package/components/Drawer/index.d.ts

@@ -43,6 +43,8 @@ export type Props = PropsWithChildren<WithClassName<{
  * - `opened` — the drawer is open.
  * - `closed` — the drawer is closed.
  *
+ * - `--measured` — the content has been measured, so the properties below are set.
+ *
  * ### CSS elements
  * - `opener`
  * - `closer`
@@ -54,8 +56,8 @@ export type Props = PropsWithChildren<WithClassName<{
  * Absent until the first measurement lands.
  *
  * ### Data attributes on the root element
- * - `data-content-width`, `data-content-height` — the measured content size.
  * Absent until the first measurement lands.
+ * - `data-content-width`, `data-content-height` — the measured content size.
  *
  * @param props - Component properties.
  * @see {@link Props}

package/components/Drawer/index.js

@@ -15,6 +15,8 @@ import cssModule from './styles.module.css';
  * - `opened` — the drawer is open.
  * - `closed` — the drawer is closed.
  *
+ * - `--measured` — the content has been measured, so the properties below are set.
+ *
  * ### CSS elements
  * - `opener`
  * - `closer`
@@ -26,8 +28,8 @@ import cssModule from './styles.module.css';
  * Absent until the first measurement lands.
  *
  * ### Data attributes on the root element
- * - `data-content-width`, `data-content-height` — the measured content size.
  * Absent until the first measurement lands.
+ * - `data-content-width`, `data-content-height` — the measured content size.
  *
  * @param props - Component properties.
  * @see {@link Props}
@@ -71,7 +73,8 @@ export const Drawer = ({ openerContent, closerContent, defaultIsOpened = false,
     const c = clss(publicClassName, { cssModule });
     const rootClss = mergeClassNames(c(null, {
         'opened': isOpened,
-        'closed': !isOpened
+        'closed': !isOpened,
+        measured: contentDimensions !== undefined
     }), className);
     const openerClss = c('opener');
     const closerClss = c('closer');

package/components/Iframe/index.d.ts

@@ -24,6 +24,10 @@ export type Props = WithClassName<{
  * The parent component updates the iframe height via React state and `style`
  * prop (no direct DOM mutation).
  *
+ * ### Root element modifiers
+ * - `--auto-height` — the component is listening for a height from inside the frame.
+ * - `--measured` — one has arrived, and the frame is sized to it.
+ *
  * @param props - Component properties.
  * @see {@link Props}
  */

package/components/Iframe/index.js

@@ -33,6 +33,10 @@ const innerAutoHeightNotifier = (messageType) => `<script>
  * The parent component updates the iframe height via React state and `style`
  * prop (no direct DOM mutation).
  *
+ * ### Root element modifiers
+ * - `--auto-height` — the component is listening for a height from inside the frame.
+ * - `--measured` — one has arrived, and the frame is sized to it.
+ *
  * @param props - Component properties.
  * @see {@link Props}
  */
@@ -68,7 +72,10 @@ export const Iframe = ({ autoHeight = false, className, srcDoc, style, ...iframe
         return { ...base, height: `${height}px` };
     }, [style, autoHeight, height]);
     const c = clss(publicClassName, { cssModule });
-    const rootClss = mergeClassNames(c(), className);
+    const rootClss = mergeClassNames(c(null, {
+        'auto-height': autoHeight,
+        measured: height !== null
+    }), className);
     const html = useMemo(() => {
         const autoHeightScript = autoHeight
             ? innerAutoHeightNotifier(innerMessageType)

package/components/Input/index.d.ts

@@ -23,6 +23,10 @@ export type Props = InputHTMLAttributes<HTMLInputElement> & WithClassName<{
  * 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/Input/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 Input = ({ 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("input", { ...rest, id: id, className: rootClss, value: currentValue, onChange: handleChange }), isNotFalsy(error) && _jsx("span", { className: c('error'), children: error })] });
 };

package/components/ListLoader/index.controlled.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import type { WithClassName } from '../utils/types.js';
+import type { ViewportObserverOptions, WithClassName } from '../utils/types.js';
 /**
  * Props for the {@link ControlledListLoader} component.
  *
@@ -26,9 +26,14 @@ import type { WithClassName } from '../utils/types.js';
  * @property autoLoadPrevWhenVisible - Wraps the leading load button in an
  * {@link IntersectionObserverComponent} and fires `onLoadPageClicked` when it enters the viewport.
  * @property autoLoadNextWhenVisible - Same, for the trailing load button.
+ * @property threshold - How much of a load button has to be in view before it
+ * counts as visible, forwarded to each observer.
+ * @property root - Their root. Defaults to the viewport.
+ * @property rootMargin - Grows or shrinks that root before measuring — the way to
+ * start loading a page before its button actually shows.
  * @property className - Additional class name(s) applied to the root element.
  */
-export type Props<T> = WithClassName<{
+export type Props<T> = WithClassName<ViewportObserverOptions & {
     pages: number[];
     firstPagePos: number;
     lastPagePos: number;
@@ -55,6 +60,9 @@ export type Props<T> = WithClassName<{
  * - in place of each page missing between two loaded pages,
  * - after the last loaded page, unless it is already `lastPagePos`.
  *
+ * ### Root element modifiers
+ * - `--loading` — at least one page is being fetched.
+ *
  * ### CSS elements
  * - `item` — wraps each rendered item. Carries `data-page`.
  * - `load` — a load button. Rendered empty, so its label belongs in CSS.
@@ -75,4 +83,4 @@ export type Props<T> = WithClassName<{
  * Deduplication runs after `filter`, so an item hidden by `filter` never evicts
  * an earlier duplicate.
  */
-export declare const ControlledListLoader: <T>({ className, pages, firstPagePos, lastPagePos, itemsPages, filter, display, getIdentifier, loadingPages, onLoadPageClicked, autoLoadPrevWhenVisible, autoLoadNextWhenVisible }: Props<T>) => ReactNode;
+export declare const ControlledListLoader: <T>({ className, pages, firstPagePos, lastPagePos, itemsPages, filter, display, getIdentifier, loadingPages, onLoadPageClicked, autoLoadPrevWhenVisible, autoLoadNextWhenVisible, threshold, root, rootMargin }: Props<T>) => ReactNode;

package/components/ListLoader/index.controlled.js

@@ -19,6 +19,9 @@ import cssModule from './styles.module.css';
  * - in place of each page missing between two loaded pages,
  * - after the last loaded page, unless it is already `lastPagePos`.
  *
+ * ### Root element modifiers
+ * - `--loading` — at least one page is being fetched.
+ *
  * ### CSS elements
  * - `item` — wraps each rendered item. Carries `data-page`.
  * - `load` — a load button. Rendered empty, so its label belongs in CSS.
@@ -39,7 +42,7 @@ import cssModule from './styles.module.css';
  * Deduplication runs after `filter`, so an item hidden by `filter` never evicts
  * an earlier duplicate.
  */
-export const ControlledListLoader = ({ className, pages, firstPagePos, lastPagePos, itemsPages, filter, display, getIdentifier, loadingPages, onLoadPageClicked, autoLoadPrevWhenVisible, autoLoadNextWhenVisible }) => {
+export const ControlledListLoader = ({ className, pages, firstPagePos, lastPagePos, itemsPages, filter, display, getIdentifier, loadingPages, onLoadPageClicked, autoLoadPrevWhenVisible, autoLoadNextWhenVisible, threshold, root, rootMargin }) => {
     const inBoundsPages = pages.filter(pagePos => pagePos >= firstPagePos && pagePos <= lastPagePos);
     const filteredItems = Array.from(itemsPages)
         .filter(([pagePos]) => inBoundsPages.includes(pagePos))
@@ -78,14 +81,14 @@ export const ControlledListLoader = ({ className, pages, firstPagePos, lastPageP
         .filter(pagePos => inBoundsPages.includes(pagePos))
         .sort((a, b) => a - b);
     const c = clss(publicClassName, { cssModule });
-    const rootClss = mergeClassNames(c(), className);
+    const rootClss = mergeClassNames(c(null, { loading: sortedLoadingPages.length > 0 }), className);
     const renderLoadButton = (pagePos, kind) => {
         const button = _jsx("button", { className: c('load', kind), "data-page": pagePos, onClick: () => onLoadPageClicked?.(pagePos) }, `load/${pagePos}`);
         const autoLoads = (kind === 'prev' && autoLoadPrevWhenVisible === true)
             || (kind === 'next' && autoLoadNextWhenVisible === true);
         if (!autoLoads)
             return button;
-        return _jsx(IntersectionObserverComponent, { className: c('load-observer', kind), onIntersected: ({ ioEntry }) => {
+        return _jsx(IntersectionObserverComponent, { className: c('load-observer', kind), threshold: threshold, root: root, rootMargin: rootMargin, onIntersected: ({ ioEntry }) => {
                 if (ioEntry?.isIntersecting !== true)
                     return;
                 onLoadPageClicked?.(pagePos);

package/components/ListLoader/index.d.ts

@@ -66,4 +66,4 @@ export type Props<T> = Omit<ControlledProps<T>, 'itemsPages' | 'loadingPages' |
  * - No page outside `firstPagePos`–`lastPagePos` is ever fetched, whichever mode
  *   is in use.
  */
-export declare const ListLoader: <T>({ className, pages, defaultPage, fillGaps, dropPagesFurtherThan, autoLoadPrevWhenVisible, autoLoadNextWhenVisible, firstPagePos, lastPagePos, fetch, filter, display, getIdentifier, onLoadPageClicked, staleAfterMs, onPageFetched, onPageFetchFailed, fetchRetriesNb, fetchRetriesDelayMs }: Props<T>) => ReactNode;
+export declare const ListLoader: <T>({ className, pages, defaultPage, fillGaps, dropPagesFurtherThan, autoLoadPrevWhenVisible, autoLoadNextWhenVisible, threshold, root, rootMargin, firstPagePos, lastPagePos, fetch, filter, display, getIdentifier, onLoadPageClicked, staleAfterMs, onPageFetched, onPageFetchFailed, fetchRetriesNb, fetchRetriesDelayMs }: Props<T>) => ReactNode;

package/components/ListLoader/index.js

@@ -25,7 +25,7 @@ import { rangeBetween } from './utils.js';
  * - No page outside `firstPagePos`–`lastPagePos` is ever fetched, whichever mode
  *   is in use.
  */
-export const ListLoader = ({ className, pages, defaultPage, fillGaps = true, dropPagesFurtherThan, autoLoadPrevWhenVisible, autoLoadNextWhenVisible, firstPagePos, lastPagePos, fetch, filter, display, getIdentifier, onLoadPageClicked, staleAfterMs, onPageFetched, onPageFetchFailed, fetchRetriesNb = Infinity, fetchRetriesDelayMs = 1000 }) => {
+export const ListLoader = ({ className, pages, defaultPage, fillGaps = true, dropPagesFurtherThan, autoLoadPrevWhenVisible, autoLoadNextWhenVisible, threshold, root, rootMargin, firstPagePos, lastPagePos, fetch, filter, display, getIdentifier, onLoadPageClicked, staleAfterMs, onPageFetched, onPageFetchFailed, fetchRetriesNb = Infinity, fetchRetriesDelayMs = 1000 }) => {
     const [itemsPages, setItemsPages] = useState(new Map());
     const [loadingPages, setLoadingPages] = useState(new Set());
     const [internalPages, setInternalPages] = useState([
@@ -142,5 +142,5 @@ export const ListLoader = ({ className, pages, defaultPage, fillGaps = true, dro
     const controlledItemsPages = new Map(Array
         .from(itemsPages)
         .map(([page, { items }]) => [page, items]));
-    return _jsx(ControlledListLoader, { className: className, pages: currentPages, firstPagePos: firstPagePos, lastPagePos: lastPagePos, itemsPages: controlledItemsPages, filter: filter, display: display, getIdentifier: getIdentifier, loadingPages: Array.from(loadingPages), onLoadPageClicked: handleLoadClick, autoLoadPrevWhenVisible: autoLoadPrevWhenVisible, autoLoadNextWhenVisible: autoLoadNextWhenVisible });
+    return _jsx(ControlledListLoader, { className: className, pages: currentPages, firstPagePos: firstPagePos, lastPagePos: lastPagePos, itemsPages: controlledItemsPages, filter: filter, display: display, getIdentifier: getIdentifier, loadingPages: Array.from(loadingPages), onLoadPageClicked: handleLoadClick, autoLoadPrevWhenVisible: autoLoadPrevWhenVisible, autoLoadNextWhenVisible: autoLoadNextWhenVisible, threshold: threshold, root: root, rootMargin: rootMargin });
 };

package/components/ResizeObserver/index.d.ts

@@ -20,9 +20,14 @@ export type Props = PropsWithChildren<WithClassName<{
  * rect on its root element. Both sets stay absent until the first measurement
  * lands.
  *
+ * ### Root element modifiers
+ * - `--measured` — a first measurement landed, so the sets below are populated.
+ *
  * ### Data attributes
  * `data-x`, `data-y`, `data-top`, `data-left`, `data-bottom`, `data-right`,
- * `data-width` and `data-height` — the content rect, as plain numbers.
+ * `data-width` and `data-height` — the content rect, as plain numbers. They carry
+ * what a custom property cannot reach: `content: attr(data-width)`, and attribute
+ * selectors.
  *
  * ### CSS custom properties
  * The same eight measurements, each exposed twice: `--lm-resize-observer-width`

package/components/ResizeObserver/index.js

@@ -9,9 +9,14 @@ import cssModule from './styles.module.css';
  * rect on its root element. Both sets stay absent until the first measurement
  * lands.
  *
+ * ### Root element modifiers
+ * - `--measured` — a first measurement landed, so the sets below are populated.
+ *
  * ### Data attributes
  * `data-x`, `data-y`, `data-top`, `data-left`, `data-bottom`, `data-right`,
- * `data-width` and `data-height` — the content rect, as plain numbers.
+ * `data-width` and `data-height` — the content rect, as plain numbers. They carry
+ * what a custom property cannot reach: `content: attr(data-width)`, and attribute
+ * selectors.
  *
  * ### CSS custom properties
  * The same eight measurements, each exposed twice: `--lm-resize-observer-width`
@@ -89,6 +94,6 @@ export const ResizeObserverComponent = ({ className, onResized, children }) => {
         };
     }
     const c = clss(publicClassName, { cssModule });
-    const rootClss = mergeClassNames(c(), className);
+    const rootClss = mergeClassNames(c(null, { measured: contentRect !== undefined }), className);
     return _jsx("div", { ...dataAttributes, className: rootClss, ref: rootRef, style: { ...cssCustomProps }, children: children });
 };

package/components/Scrllgngn/index.d.ts

@@ -1,6 +1,6 @@
 import { type PropsWithChildren, type FunctionComponent } from 'react';
 import type { WithClassName } from '../utils/types.js';
-import { type TrackedBlockContext } from './utils.js';
+import { type TrackedBlockContext, type ViewportOffset } from './utils.js';
 /**
  * Common properties shared by all block types.
  *
@@ -62,9 +62,17 @@ export type PropsPage = {
  *
  * @property pages - Ordered list of pages that compose the scrollytelling
  * sequence. Each page may contain any mix of {@link PropsBlock} variants.
- * @property thresholdOffsetPercent - Forwarded to the internal
- * {@link Paginator}. Defines the viewport offset percentage used to determine
- * which page is considered current.
+ * @property thresholdOffsetPercent - Where the threshold line sits, as a
+ * percentage of the **visible zone** — not of the viewport, so a threshold stays
+ * put under a sticky nav. It decides which page counts as current, and anchors
+ * every progression handed to a tracked block.
+ * @property viewportOffsetTop - How much of the top of the screen is covered by
+ * something else — a sticky nav, say — and should be kept out of the visible zone.
+ * A number means pixels; a string is any CSS length, `var()` and `clamp()`
+ * included, so the value can follow a breakpoint without JavaScript.
+ * @property viewportOffsetRight - Same, on the right edge.
+ * @property viewportOffsetBottom - Same, on the bottom edge.
+ * @property viewportOffsetLeft - Same, on the left edge.
  * @property stickyBlocksLazyLoadDistance - Number of pages around the current
  * page within which sticky blocks are mounted. Blocks outside this window are
  * unmounted to save resources. Defaults to `2`.
@@ -85,6 +93,10 @@ export type PropsPage = {
 export type Props = WithClassName<{
     pages?: PropsPage[];
     thresholdOffsetPercent?: number;
+    viewportOffsetTop?: ViewportOffset;
+    viewportOffsetRight?: ViewportOffset;
+    viewportOffsetBottom?: ViewportOffset;
+    viewportOffsetLeft?: ViewportOffset;
     stickyBlocksLazyLoadDistance?: number;
     forceStickBlocks?: 'before' | 'after' | 'both' | 'none';
     onPageChanged?: (currentPagePos: number, pageData?: PropsPage) => void;
@@ -125,6 +137,16 @@ export type Props = WithClassName<{
  * `-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.
@@ -156,11 +178,19 @@ export type Props = WithClassName<{
  *
  * @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.