@design-edito/tools 0.5.1 → 0.5.3

package/components/JsonEditor/utils.js

@@ -0,0 +1,23 @@
+import { clss } from '../../agnostic/css/clss/index.js';
+import { isNonNullObject } from '../../agnostic/objects/is-object/index.js';
+import { jsonEditor as publicClassName } from '../public-classnames.js';
+import cssModule from './styles.module.css';
+/**
+ * Shared by every editor in the tree — they all emit class names under the same
+ * public prefix, so a single instance is what keeps them consistent.
+ */
+export const c = clss(publicClassName, { cssModule });
+/** Which {@link ValueType} a value belongs to. */
+export function getValueType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    if (isNonNullObject(value))
+        return 'record';
+    if (typeof value === 'string')
+        return 'string';
+    if (typeof value === 'number')
+        return 'number';
+    return 'boolean';
+}

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

@@ -0,0 +1,78 @@
+import type { ReactNode } from 'react';
+import type { WithClassName } from '../utils/types.js';
+/**
+ * Props for the {@link ControlledListLoader} component.
+ *
+ * @template T - The item type carried by each page.
+ *
+ * @property pages - Page positions the consumer wants rendered. Entries outside
+ * `firstPagePos`–`lastPagePos` are ignored, as are entries absent from `itemsPages`.
+ * @property firstPagePos - Lowest page position that exists. No load button is
+ * ever rendered below it.
+ * @property lastPagePos - Highest page position that exists. No load button is
+ * ever rendered above it.
+ * @property itemsPages - Already-loaded items, keyed by page position. The
+ * component holds no data of its own and renders only what this map contains.
+ * @property filter - Decides whether an item is rendered. Applied before deduplication.
+ * @property display - Renders a single item.
+ * @property getIdentifier - Item identity, used as React key and to deduplicate.
+ * When two rendered items share an identifier, only the later one in page order
+ * survives. Returning `undefined` opts an item out of deduplication, and falls
+ * back to a positional key.
+ * @property loadingPages - Page positions currently being fetched. Exposed on the
+ * root element as `data-loading-pages`.
+ * @property onLoadPageClicked - Called with the page position a load button targets,
+ * either on click or on viewport entry when auto-loading is enabled.
+ * @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 className - Additional class name(s) applied to the root element.
+ */
+export type Props<T> = WithClassName<{
+    pages: number[];
+    firstPagePos: number;
+    lastPagePos: number;
+    itemsPages: Map<number, T[]>;
+    filter: (item: T) => boolean;
+    display: (item: T) => ReactNode;
+    getIdentifier?: (item: T) => string | undefined;
+    loadingPages?: number[];
+    onLoadPageClicked?: (pagePos: number) => void;
+    autoLoadPrevWhenVisible?: boolean;
+    autoLoadNextWhenVisible?: boolean;
+}>;
+/**
+ * Presentational layer of the paginated list. Renders already-loaded pages as a
+ * single flat item list, and interleaves load buttons wherever a page is missing.
+ *
+ * This component holds no state and performs no fetching. Loaded pages are sorted
+ * by position and flattened, so items appear in page order then in item order,
+ * with no per-page wrapper element.
+ *
+ * ### Load buttons
+ * One button is rendered per missing page position:
+ * - before the first loaded page, unless it is already `firstPagePos`,
+ * - in place of each page missing between two loaded pages,
+ * - after the last loaded page, unless it is already `lastPagePos`.
+ *
+ * ### CSS elements
+ * - `item` — wraps each rendered item. Carries `data-page`.
+ * - `load` — a load button. Rendered empty, so its label belongs in CSS.
+ *   Carries `data-page` and a `prev`, `next` or `gap` modifier.
+ * - `load-observer` — the intersection observer wrapping an auto-loading button.
+ *   Present only when `autoLoadPrevWhenVisible` or `autoLoadNextWhenVisible` is on.
+ *   Carries a `prev` or `next` modifier.
+ *
+ * ### Data attributes on the root element
+ * - `data-loading-pages` — comma-separated ascending list of the pages being
+ *   fetched, e.g. `"1,3,6"`. Absent entirely when nothing is loading.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @returns A flat list of items with load buttons in place of missing pages.
+ *
+ * @remarks
+ * 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;

package/components/ListLoader/index.controlled.js

@@ -0,0 +1,99 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { clss } from '../../agnostic/css/clss/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
+ * single flat item list, and interleaves load buttons wherever a page is missing.
+ *
+ * This component holds no state and performs no fetching. Loaded pages are sorted
+ * by position and flattened, so items appear in page order then in item order,
+ * with no per-page wrapper element.
+ *
+ * ### Load buttons
+ * One button is rendered per missing page position:
+ * - before the first loaded page, unless it is already `firstPagePos`,
+ * - in place of each page missing between two loaded pages,
+ * - after the last loaded page, unless it is already `lastPagePos`.
+ *
+ * ### CSS elements
+ * - `item` — wraps each rendered item. Carries `data-page`.
+ * - `load` — a load button. Rendered empty, so its label belongs in CSS.
+ *   Carries `data-page` and a `prev`, `next` or `gap` modifier.
+ * - `load-observer` — the intersection observer wrapping an auto-loading button.
+ *   Present only when `autoLoadPrevWhenVisible` or `autoLoadNextWhenVisible` is on.
+ *   Carries a `prev` or `next` modifier.
+ *
+ * ### Data attributes on the root element
+ * - `data-loading-pages` — comma-separated ascending list of the pages being
+ *   fetched, e.g. `"1,3,6"`. Absent entirely when nothing is loading.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @returns A flat list of items with load buttons in place of missing pages.
+ *
+ * @remarks
+ * 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 }) => {
+    const inBoundsPages = pages.filter(pagePos => pagePos >= firstPagePos && pagePos <= lastPagePos);
+    const filteredItems = Array.from(itemsPages)
+        .filter(([pagePos]) => inBoundsPages.includes(pagePos))
+        .sort(([pageA], [pageB]) => pageA - pageB)
+        .flatMap(([pagePos, items]) => items.map((item, itemPos) => ({ item, pagePos, itemPos })))
+        .filter(({ item }) => filter(item));
+    const identifiers = filteredItems.map(({ item }) => getIdentifier?.(item));
+    const displayedItems = filteredItems.filter((_, pos) => {
+        const identifier = identifiers[pos];
+        if (identifier === undefined)
+            return true;
+        return identifiers.lastIndexOf(identifier) === pos;
+    });
+    const loadedPages = Array.from(itemsPages.keys())
+        .filter(pagePos => inBoundsPages.includes(pagePos))
+        .sort((a, b) => a - b);
+    const firstLoadedPage = loadedPages[0];
+    const lastLoadedPage = loadedPages[loadedPages.length - 1];
+    const gapPages = loadedPages.flatMap((pagePos, pos) => {
+        const prevPage = loadedPages[pos - 1];
+        if (prevPage === undefined)
+            return [];
+        return rangeBetween(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 c = clss(publicClassName, { cssModule });
+    const rootClss = mergeClassNames(c(), 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 }) => {
+                if (ioEntry?.isIntersecting !== true)
+                    return;
+                onLoadPageClicked?.(pagePos);
+            }, children: button }, `load/${pagePos}`);
+    };
+    return _jsx("div", { className: rootClss, "data-loading-pages": sortedLoadingPages.length === 0 ? undefined : sortedLoadingPages.join(','), children: slots.map(({ pagePos, kind }) => kind === 'items'
+            ? displayedItems
+                .filter(entry => entry.pagePos === pagePos)
+                .map(({ item, itemPos }) => _jsx("div", { className: c('item'), "data-page": pagePos, children: display(item) }, getIdentifier?.(item) ?? `${pagePos}/${itemPos}`))
+            : renderLoadButton(pagePos, kind)) });
+};

package/components/ListLoader/index.d.ts

@@ -0,0 +1,69 @@
+import { type ReactNode } from 'react';
+import { type Props as ControlledProps } from './index.controlled.js';
+/**
+ * Props for the {@link ListLoader} component.
+ *
+ * Extends {@link ControlledProps} — minus the data it derives itself — with
+ * fetching, staleness and page-set management.
+ *
+ * @template T - The item type carried by each page.
+ *
+ * @property pages - Page positions to keep loaded. When provided, the component
+ * is fully controlled: load buttons only report clicks and never change the set
+ * themselves. When omitted, the set is managed internally.
+ * @property defaultPage - Page loaded first in uncontrolled mode. Clamped into
+ * `firstPagePos`–`lastPagePos`, and defaults to `firstPagePos`. Ignored when
+ * `pages` is provided.
+ * @property fillGaps - When `true` (the default), any page missing between the
+ * lowest and highest requested page is requested automatically, so the loaded
+ * range stays contiguous. Ignored when `pages` is provided.
+ * @property dropPagesFurtherThan - Maximum distance, in pages, kept around a page
+ * loaded through a load button. Pages further away are dropped from state and
+ * from the DOM. Applies to load-button activations only, never to retries or
+ * stale reloads. Ignored when `pages` is provided.
+ * @property fetch - Fetches one page's items. Rejections are reported through
+ * `onPageFetchFailed` and retried according to `fetchRetriesNb`.
+ * @property staleAfterMs - Delay after which a loaded page is refetched, counted
+ * from its own last successful load. When omitted, pages are never refreshed.
+ * @property onPageFetched - Called after a page's items have been stored. Not
+ * called for a page dropped while its request was in flight.
+ * @property onPageFetchFailed - Called on every failed attempt, not only once retries
+ * are exhausted. When omitted, failures are logged with `console.warn`.
+ * @property fetchRetriesNb - Number of retries after a failed fetch. Defaults to
+ * `Infinity`, so a page keeps retrying until it succeeds.
+ * @property fetchRetriesDelayMs - Delay between two attempts. Defaults to `1000`.
+ */
+export type Props<T> = Omit<ControlledProps<T>, 'itemsPages' | 'loadingPages' | 'pages'> & {
+    pages?: number[];
+    defaultPage?: number;
+    fillGaps?: boolean;
+    dropPagesFurtherThan?: number;
+    fetch: (page: number) => Promise<T[]>;
+    staleAfterMs?: number;
+    onPageFetched?: (pagePos: number, items: T[]) => void;
+    onPageFetchFailed?: (pagePos: number, error: Error) => void;
+    fetchRetriesNb?: number;
+    fetchRetriesDelayMs?: number;
+};
+/**
+ * Paginated list abstraction. Fetches the pages it is asked for, keeps them
+ * fresh, and drives a {@link ControlledListLoader} with the result.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @see {@link ControlledListLoader} for the rendered markup and CSS elements.
+ * @returns A {@link ControlledListLoader} fed with the loaded pages.
+ *
+ * @remarks
+ * - In controlled mode (`pages` defined), the page set is entirely driven by the
+ *   parent. `fillGaps` and `dropPagesFurtherThan` are inert, and load buttons only
+ *   report through `onLoadPageClicked`.
+ * - In uncontrolled mode, internal state is initialized from `defaultPage` and load
+ *   buttons extend the set themselves. `onLoadPageClicked` still fires, after the
+ *   internal state has been updated.
+ * - A page removed from the effective set is dropped from memory, and a request
+ *   still in flight for it is discarded on arrival rather than re-inserted.
+ * - 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;

package/components/ListLoader/index.js

@@ -0,0 +1,146 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from 'react';
+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.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @see {@link ControlledListLoader} for the rendered markup and CSS elements.
+ * @returns A {@link ControlledListLoader} fed with the loaded pages.
+ *
+ * @remarks
+ * - In controlled mode (`pages` defined), the page set is entirely driven by the
+ *   parent. `fillGaps` and `dropPagesFurtherThan` are inert, and load buttons only
+ *   report through `onLoadPageClicked`.
+ * - In uncontrolled mode, internal state is initialized from `defaultPage` and load
+ *   buttons extend the set themselves. `onLoadPageClicked` still fires, after the
+ *   internal state has been updated.
+ * - A page removed from the effective set is dropped from memory, and a request
+ *   still in flight for it is discarded on arrival rather than re-inserted.
+ * - 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 }) => {
+    const [itemsPages, setItemsPages] = useState(new Map());
+    const [loadingPages, setLoadingPages] = useState(new Set());
+    const [internalPages, setInternalPages] = useState([
+        clamp(defaultPage ?? firstPagePos, firstPagePos, lastPagePos)
+    ]);
+    const requestedPages = 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]);
+    const handleLoadClick = (pagePos) => {
+        if (pages === undefined) {
+            setInternalPages(curr => {
+                const next = curr.includes(pagePos) ? curr : [...curr, pagePos];
+                if (dropPagesFurtherThan === undefined)
+                    return next;
+                const kept = next.filter(page => Math.abs(page - pagePos) <= dropPagesFurtherThan);
+                return kept.length === next.length ? next : kept;
+            });
+        }
+        onLoadPageClicked?.(pagePos);
+    };
+    const storePage = (page, items) => setItemsPages(curr => {
+        const next = new Map(curr);
+        next.set(page, { loadedAt: new Date(), items });
+        return next;
+    });
+    const setPageLoading = (page, isLoading) => setLoadingPages(curr => {
+        const next = new Set(curr);
+        if (isLoading)
+            next.add(page);
+        else
+            next.delete(page);
+        return next;
+    });
+    const reportFetchError = (page, err) => {
+        const error = toError(err);
+        if (onPageFetchFailed !== undefined)
+            return onPageFetchFailed(page, error);
+        // eslint-disable-next-line no-console
+        console.warn(`ListLoader failed to fetch page ${page}`, error);
+    };
+    // Guards the whole load path at once: a page dropped meanwhile stops its
+    // pending retries and its stale reloads without any further bookkeeping.
+    const loadPage = (page, retriesLeft = fetchRetriesNb) => {
+        if (!requestedPages.current.has(page))
+            return;
+        setPageLoading(page, true);
+        void fetch(page)
+            .then(items => {
+            if (!requestedPages.current.has(page))
+                return;
+            storePage(page, items);
+            onPageFetched?.(page, items);
+            setPageLoading(page, false);
+        })
+            .catch((err) => {
+            reportFetchError(page, err);
+            if (retriesLeft <= 0)
+                return setPageLoading(page, false);
+            window.setTimeout(() => loadPage(page, retriesLeft - 1), fetchRetriesDelayMs);
+        });
+    };
+    // 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.
+    useEffect(() => {
+        Array.from(requestedPages.current)
+            .filter(page => !currentPages.includes(page))
+            .forEach(page => { requestedPages.current.delete(page); });
+        setItemsPages(curr => {
+            const next = new Map(Array.from(curr).filter(([page]) => currentPages.includes(page)));
+            return next.size === curr.size ? curr : next;
+        });
+        setLoadingPages(curr => {
+            const next = new Set(Array.from(curr).filter(page => currentPages.includes(page)));
+            return next.size === curr.size ? curr : next;
+        });
+    }, [currentPages]);
+    useEffect(() => {
+        if (pages !== undefined)
+            return;
+        if (!fillGaps)
+            return;
+        setInternalPages(curr => {
+            if (curr.length === 0)
+                return curr;
+            const missing = rangeBetween(Math.min(...curr), Math.max(...curr))
+                .filter(page => !curr.includes(page));
+            if (missing.length === 0)
+                return curr;
+            return [...curr, ...missing];
+        });
+    }, [currentPages, fillGaps, pages]);
+    useEffect(() => {
+        currentPages.forEach(page => {
+            if (requestedPages.current.has(page))
+                return;
+            requestedPages.current.add(page);
+            loadPage(page);
+        });
+    }, [currentPages, fetch]);
+    // Fx. dep. `itemsPages` - Reschedules one timeout per page on every store, each
+    // due from its own `loadedAt`. A refetch updates `loadedAt`, which re-runs this
+    // effect and keeps the cycle going.
+    useEffect(() => {
+        if (staleAfterMs === undefined)
+            return;
+        const timeouts = Array.from(itemsPages).map(([page, { loadedAt }]) => {
+            const dueInMs = Math.max(0, staleAfterMs - (Date.now() - loadedAt.getTime()));
+            return window.setTimeout(() => loadPage(page), dueInMs);
+        });
+        return () => timeouts.forEach(timeout => window.clearTimeout(timeout));
+    }, [itemsPages, staleAfterMs, fetch]);
+    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 });
+};

package/components/ListLoader/utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Lists every integer from `from` to `to`, both included.
+ *
+ * @param from - Lower bound.
+ * @param to - Upper bound. When lower than `from`, the range is empty.
+ * @returns The integers in ascending order.
+ */
+export declare function rangeBetween(from: number, to: number): number[];

package/components/ListLoader/utils.js

@@ -0,0 +1,10 @@
+/**
+ * Lists every integer from `from` to `to`, both included.
+ *
+ * @param from - Lower bound.
+ * @param to - Upper bound. When lower than `from`, the range is empty.
+ * @returns The integers in ascending order.
+ */
+export function rangeBetween(from, to) {
+    return Array.from({ length: Math.max(0, to - from + 1) }, (_, pos) => from + pos);
+}

package/components/Overlayer/index.js

@@ -2,7 +2,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 { overlayer as publicClassname } from '../public-classnames.js';
+import { overlayer as publicClassName } from '../public-classnames.js';
 import cssModule from './styles.module.css';
 /**
  * Absolute positioning overlay component. Renders a base content layer and
@@ -27,10 +27,10 @@ import cssModule from './styles.module.css';
  * @returns A root `<div>` containing the base layer and all positioned overlay elements.
  */
 export const Overlayer = ({ overlays, children, className }) => {
-    const c = clss(publicClassname, { cssModule });
+    const c = clss(publicClassName, { cssModule });
     const rootClss = mergeClassNames(c(), className);
     const baseClss = c('base');
-    return _jsxs("div", { className: rootClss, children: [_jsx("div", { className: baseClss, children: children }), overlays?.map(({ content, xPercent = 0, yPercent = 0, justify }) => {
+    return _jsxs("div", { className: rootClss, children: [_jsx("div", { className: baseClss, children: children }), overlays?.map(({ content, xPercent = 0, yPercent = 0, justify }, overlayPos) => {
                 const overlayClss = c('overlay');
                 let computedTranslateX;
                 if (typeof justify === 'number') {
@@ -55,6 +55,6 @@ export const Overlayer = ({ overlays, children, className }) => {
                 };
                 if (isFalsy(content))
                     return null;
-                return _jsx("div", { className: overlayClss, style: overlayCustomProps, children: content });
+                return _jsx("div", { className: overlayClss, style: overlayCustomProps, children: content }, overlayPos);
             })] });
 };

package/components/Paginator/index.d.ts

@@ -27,23 +27,18 @@ type DirectionState = 'forwards' | 'backwards' | null;
  * the {@link IntersectionObserver} root margin. Determines how far into the viewport
  * a page must be before it is considered `'curr'`. Defaults to `0`.
  *
- * @property stateHandlers - Callbacks called after the internal state changed
- * @property stateHandlers.directionChanged - Callback invoked when the scroll direction changes.
- * Receives the new {@link DirectionState}. Only fires when the direction actually
- * changes — repeated scrolls in the same direction do not trigger it again.
- *
- * @property stateHandlers.pageChanged - Callback invoked whenever any page's {@link PageState}
- * changes. Receives a flat array of all pages' states, ordered by position.
- *
+ * @property onDirectionChanged - Called after the scroll direction changed, with
+ * the new {@link DirectionState}. Repeated scrolls in the same direction do not
+ * 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 className - Optional additional class name(s) applied to the root element.
  * @property children - Each direct child is treated as an individual page slot.
  */
 export type Props = PropsWithChildren<WithClassName<{
     thresholdOffsetPercent?: number;
-    stateHandlers?: {
-        directionChanged?: (direction: DirectionState) => void;
-        pageChanged?: (pages: PageState[]) => void;
-    };
+    onDirectionChanged?: (direction: DirectionState) => void;
+    onPagesChanged?: (pages: PageState[]) => void;
 }>>;
 /**
  * A scroll-driven pagination component that tracks which child page is currently

package/components/Paginator/index.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useRef, Children, useState } from 'react';
 import { clss } from '../../agnostic/css/clss/index.js';
-import { mergeClassNames } from '../utils/index.js';
+import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
 import { paginator as publicClassName } from '../public-classnames.js';
 import cssModule from './styles.module.css';
 /**
@@ -27,21 +27,17 @@ 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, stateHandlers, className, children }) => {
+export const Paginator = ({ thresholdOffsetPercent, onDirectionChanged, onPagesChanged, className, children }) => {
     // State, refs, effects
     const [pagesState, setPagesState] = useState(new Map());
     const [directionState, setDirectionState] = useState(null);
     const pagesRef = useRef(null);
     const directionRef = useRef(null);
-    // State change handlers
-    useEffect(() => {
-        stateHandlers?.pageChanged?.(Array
-            .from(pagesState)
-            .map(([, state]) => state));
-    }, [pagesState]);
-    useEffect(() => {
-        stateHandlers?.directionChanged?.(directionState);
-    }, [directionState]);
+    // State dispatch
+    useChangeDispatch(pagesState, pages => onPagesChanged?.(Array
+        .from(pages)
+        .map(([, pageState]) => pageState)));
+    useChangeDispatch(directionState, onDirectionChanged);
     // Catch scroll direction listening on scroll events
     useEffect(() => {
         let lastCall = 0;

package/components/ResizeObserver/index.d.ts

@@ -16,9 +16,20 @@ export type Props = PropsWithChildren<WithClassName<{
     onResized?: (entry: ROEntryWithBoundingRect) => void;
 }>>;
 /**
- * Component that observes its own size changes and exposes the dimensions.
- * Updates are exposed both via data attributes (e.g., `data-width`) and CSS custom properties
- * (e.g., `--<prefix>-width`, `--<prefix>-width-px`) for styling or scripting purposes.
+ * Component that observes its own size changes and exposes the measured content
+ * rect on its root element. Both sets stay absent until the first measurement
+ * lands.
+ *
+ * ### 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.
+ *
+ * ### CSS custom properties
+ * The same eight measurements, each exposed twice: `--lm-resize-observer-width`
+ * carries the ready-to-use `px` length, `--lm-resize-observer-width-raw` the
+ * plain number for `calc()`. Same pattern for `-x`, `-y`, `-top`, `-left`,
+ * `-bottom`, `-right` and `-height`.
+ *
  * @param props - Component properties
  * @see {@link Props}
  * @returns A div wrapping `children`, with resize observation applied.

package/components/ResizeObserver/index.js

@@ -3,11 +3,22 @@ import { useRef, useEffect, useState } from 'react';
 import { clss } from '../../agnostic/css/clss/index.js';
 import { mergeClassNames } from '../utils/index.js';
 import { resizeObserver as publicClassName } from '../public-classnames.js';
-import cssModule from './style.module.css';
+import cssModule from './styles.module.css';
 /**
- * Component that observes its own size changes and exposes the dimensions.
- * Updates are exposed both via data attributes (e.g., `data-width`) and CSS custom properties
- * (e.g., `--<prefix>-width`, `--<prefix>-width-px`) for styling or scripting purposes.
+ * Component that observes its own size changes and exposes the measured content
+ * rect on its root element. Both sets stay absent until the first measurement
+ * lands.
+ *
+ * ### 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.
+ *
+ * ### CSS custom properties
+ * The same eight measurements, each exposed twice: `--lm-resize-observer-width`
+ * carries the ready-to-use `px` length, `--lm-resize-observer-width-raw` the
+ * plain number for `calc()`. Same pattern for `-x`, `-y`, `-top`, `-left`,
+ * `-bottom`, `-right` and `-height`.
+ *
  * @param props - Component properties
  * @see {@link Props}
  * @returns A div wrapping `children`, with resize observation applied.
@@ -43,27 +54,41 @@ export const ResizeObserverComponent = ({ className, onResized, children }) => {
         return () => observerRef.current?.disconnect();
     }, [onResized]);
     // Data attributes, CSS custom props & Rendering
-    const { x, y, top, left, bottom, right, width, height } = roEntry?.entry.contentRect ?? {};
-    const contentRect = { x, y, top, left, bottom, right, width, height };
-    const dataAttributes = Object
-        .entries(contentRect)
-        .reduce((acc, [key, val]) => {
-        if (val === undefined)
-            return acc;
-        return { ...acc, [`data-${key}`]: val.toString() };
-    }, {});
-    const cssCustomProps = Object
-        .entries(contentRect)
-        .reduce((acc, [key, val]) => {
-        if (val === undefined)
-            return acc;
-        return {
-            ...acc,
-            [`--${publicClassName}-${key}`]: val.toString(),
-            [`--${publicClassName}-${key}-px`]: `${val.toString()}px`
+    const contentRect = roEntry?.entry.contentRect;
+    let dataAttributes = {};
+    let cssCustomProps = {};
+    if (contentRect !== undefined) {
+        const { x, y, top, left, bottom, right, width, height } = contentRect;
+        dataAttributes = {
+            'data-x': `${x}`,
+            'data-y': `${y}`,
+            'data-top': `${top}`,
+            'data-left': `${left}`,
+            'data-bottom': `${bottom}`,
+            'data-right': `${right}`,
+            'data-width': `${width}`,
+            'data-height': `${height}`
         };
-    }, {});
+        cssCustomProps = {
+            '--lm-resize-observer-x': `${x}px`,
+            '--lm-resize-observer-x-raw': `${x}`,
+            '--lm-resize-observer-y': `${y}px`,
+            '--lm-resize-observer-y-raw': `${y}`,
+            '--lm-resize-observer-top': `${top}px`,
+            '--lm-resize-observer-top-raw': `${top}`,
+            '--lm-resize-observer-left': `${left}px`,
+            '--lm-resize-observer-left-raw': `${left}`,
+            '--lm-resize-observer-bottom': `${bottom}px`,
+            '--lm-resize-observer-bottom-raw': `${bottom}`,
+            '--lm-resize-observer-right': `${right}px`,
+            '--lm-resize-observer-right-raw': `${right}`,
+            '--lm-resize-observer-width': `${width}px`,
+            '--lm-resize-observer-width-raw': `${width}`,
+            '--lm-resize-observer-height': `${height}px`,
+            '--lm-resize-observer-height-raw': `${height}`
+        };
+    }
     const c = clss(publicClassName, { cssModule });
-    const rootClss = mergeClassNames(c(null), className);
+    const rootClss = mergeClassNames(c(), className);
     return _jsx("div", { ...dataAttributes, className: rootClss, ref: rootRef, style: { ...cssCustomProps }, children: children });
 };