@design-edito/tools 0.5.0 → 0.5.2

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

@@ -2,20 +2,21 @@ 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 call from './call/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 deleteproperties from './deleteproperties/index.js'
 export * as getattribute from './getattribute/index.js'
 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 join from './join/index.js'
-export * as length from './length/index.js'
+export * as hjparse from './hjparse/index.js'
 export * as if from './if/index.js'
 export * as initialize from './initialize/index.js'
+export * as join from './join/index.js'
+export * as length from './length/index.js'
+export * as map from './map/index.js'
 export * as negate from './negate/index.js'
 export * as notrailing from './notrailing/index.js'
 export * as or from './or/index.js'
@@ -23,30 +24,29 @@ 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 map from './map/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 replace from './replace/index.js'
-export * as select from './select/index.js'
+export * as removeattribute from './removeattribute/index.js'
 export * as renameproperty from './renameproperty/index.js'
+export * as replace from './replace/index.js'
 export * as set from './set/index.js'
+export * as select from './select/index.js'
 export * as setattribute from './setattribute/index.js'
-export * as setproperty from './setproperty/index.js'
 export * as sorton from './sorton/index.js'
 export * as split from './split/index.js'
 export * as spread from './spread/index.js'
 export * as toarray from './toarray/index.js'
-export * as toboolean from './toboolean/index.js'
 export * as toelement from './toelement/index.js'
+export * as setproperty from './setproperty/index.js'
 export * as toggleclass from './toggleclass/index.js'
 export * as tonodelist from './tonodelist/index.js'
 export * as tonull from './tonull/index.js'
-export * as tonumber from './tonumber/index.js'
-export * as torecord from './torecord/index.js'
+export * as toboolean from './toboolean/index.js'
 export * as toref from './toref/index.js'
+export * as torecord from './torecord/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 tonumber from './tonumber/index.js'

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

@@ -2,20 +2,21 @@ 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 call from './call/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 deleteproperties from './deleteproperties/index.js'
 export * as getattribute from './getattribute/index.js'
 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 join from './join/index.js'
-export * as length from './length/index.js'
+export * as hjparse from './hjparse/index.js'
 export * as if from './if/index.js'
 export * as initialize from './initialize/index.js'
+export * as join from './join/index.js'
+export * as length from './length/index.js'
+export * as map from './map/index.js'
 export * as negate from './negate/index.js'
 export * as notrailing from './notrailing/index.js'
 export * as or from './or/index.js'
@@ -23,30 +24,29 @@ 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 map from './map/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 replace from './replace/index.js'
-export * as select from './select/index.js'
+export * as removeattribute from './removeattribute/index.js'
 export * as renameproperty from './renameproperty/index.js'
+export * as replace from './replace/index.js'
 export * as set from './set/index.js'
+export * as select from './select/index.js'
 export * as setattribute from './setattribute/index.js'
-export * as setproperty from './setproperty/index.js'
 export * as sorton from './sorton/index.js'
 export * as split from './split/index.js'
 export * as spread from './spread/index.js'
 export * as toarray from './toarray/index.js'
-export * as toboolean from './toboolean/index.js'
 export * as toelement from './toelement/index.js'
+export * as setproperty from './setproperty/index.js'
 export * as toggleclass from './toggleclass/index.js'
 export * as tonodelist from './tonodelist/index.js'
 export * as tonull from './tonull/index.js'
-export * as tonumber from './tonumber/index.js'
-export * as torecord from './torecord/index.js'
+export * as toboolean from './toboolean/index.js'
 export * as toref from './toref/index.js'
+export * as torecord from './torecord/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 tonumber from './tonumber/index.js'

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

@@ -1,13 +1,13 @@
 export * as any from './any/index.js'
-export * as array from './array/index.js'
 export * as boolean from './boolean/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 nodelist from './nodelist/index.js'
-export * as number from './number/index.js'
 export * as null from './null/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'
 export * as text from './text/index.js'
+export * as string from './string/index.js'
+export * as array from './array/index.js'

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

@@ -1,13 +1,13 @@
 export * as any from './any/index.js'
-export * as array from './array/index.js'
 export * as boolean from './boolean/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 nodelist from './nodelist/index.js'
-export * as number from './number/index.js'
 export * as null from './null/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'
 export * as text from './text/index.js'
+export * as string from './string/index.js'
+export * as array from './array/index.js'

package/agnostic/html/index.d.ts

@@ -1,10 +1,10 @@
 export * as deepSelect from './deep-select/index.js'
+export * as getNodeAncestors from './get-node-ancestors/index.js'
 export * as getPositionInsideParent from './get-position-inside-parent/index.js'
 export * as hyperJson from './hyper-json/index.js'
 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 getNodeAncestors from './get-node-ancestors/index.js'
 export * as watchSelection from './watch-selection/index.js'
+export * as stringToNodes from './string-to-nodes/index.js'

package/agnostic/html/index.js

@@ -1,10 +1,10 @@
 export * as deepSelect from './deep-select/index.js'
+export * as getNodeAncestors from './get-node-ancestors/index.js'
 export * as getPositionInsideParent from './get-position-inside-parent/index.js'
 export * as hyperJson from './hyper-json/index.js'
 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 getNodeAncestors from './get-node-ancestors/index.js'
 export * as watchSelection from './watch-selection/index.js'
+export * as stringToNodes from './string-to-nodes/index.js'

package/agnostic/misc/index.d.ts

@@ -1,12 +1,12 @@
 export * as assert from './assert/index.js'
-export * as cast from './cast/index.js'
 export * as connection from './connection/index.js'
+export * as cast from './cast/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 logs from './logs/index.js'
 export * as loremIpsum from './lorem-ipsum/index.js'
 export * as normalizeExtension from './normalize-extension/index.js'
 export * as outcome from './outcome/index.js'
+export * as dataSize from './data-size/index.js'
+export * as isConstructorFunction from './is-constructor-function/index.js'

package/agnostic/misc/index.js

@@ -1,12 +1,12 @@
 export * as assert from './assert/index.js'
-export * as cast from './cast/index.js'
 export * as connection from './connection/index.js'
+export * as cast from './cast/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 logs from './logs/index.js'
 export * as loremIpsum from './lorem-ipsum/index.js'
 export * as normalizeExtension from './normalize-extension/index.js'
 export * as outcome from './outcome/index.js'
+export * as dataSize from './data-size/index.js'
+export * as isConstructorFunction from './is-constructor-function/index.js'

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

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

package/agnostic/misc/logs/index.js

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

package/agnostic/numbers/index.d.ts

@@ -2,5 +2,5 @@ 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 geometricProgressions from './geometric-progressions/index.js'
-export * as interpolate from './interpolate/index.js'
 export * as round from './round/index.js'
+export * as interpolate from './interpolate/index.js'

package/agnostic/numbers/index.js

@@ -2,5 +2,5 @@ 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 geometricProgressions from './geometric-progressions/index.js'
-export * as interpolate from './interpolate/index.js'
 export * as round from './round/index.js'
+export * as interpolate from './interpolate/index.js'

package/agnostic/optim/index.d.ts

@@ -1,2 +1,2 @@
-export * as memoize from './memoize/index.js'
 export * as throttleDebounce from './throttle-debounce/index.js'
+export * as memoize from './memoize/index.js'

package/agnostic/optim/index.js

@@ -1,2 +1,2 @@
-export * as memoize from './memoize/index.js'
 export * as throttleDebounce from './throttle-debounce/index.js'
+export * as memoize from './memoize/index.js'

package/agnostic/strings/index.d.ts

@@ -3,6 +3,6 @@ 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 splitTrim from './split-trim/index.js'
 export * as trim from './trim/index.js'

package/agnostic/strings/index.js

@@ -3,6 +3,6 @@ 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 splitTrim from './split-trim/index.js'
 export * as trim from './trim/index.js'

package/agnostic/time/index.d.ts

@@ -1,5 +1,5 @@
 export * as dates from './dates/index.js'
-export * as duration from './duration/index.js'
 export * as timeout from './timeout/index.js'
+export * as duration from './duration/index.js'
 export * as transitions from './transitions/index.js'
 export * as wait from './wait/index.js'

package/agnostic/time/index.js

@@ -1,5 +1,5 @@
 export * as dates from './dates/index.js'
-export * as duration from './duration/index.js'
 export * as timeout from './timeout/index.js'
+export * as duration from './duration/index.js'
 export * as transitions from './transitions/index.js'
 export * as wait from './wait/index.js'

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

@@ -1,7 +1,7 @@
 import { type FunctionComponent, type InputHTMLAttributes, type ReactNode } from 'react';
 import type { WithClassName } from '../utils/types.js';
 /**
- * Props for the {@link Input} component.
+ * Props for the {@link ControlledInput} component.
  *
  * Extends all native {@link InputHTMLAttributes} and {@link WithClassName}
  * with optional label and error content.

package/components/JsonEditor/index.js

@@ -60,11 +60,19 @@ export const JsonEditor = ({ defaultValue = null, onChange, onValidationError, s
     const rootClss = mergeClassNames(c(null, {}), className);
     return _jsxs("div", { className: rootClss, children: [_jsx(ValueEditor, { defaultValue: defaultValue, onChange: val => setValueAndDispatch(val), path: [] }), _jsx("pre", { children: JSON.stringify(value, null, 2) })] });
 };
-/* * * * * * * * * * * * * * * * *
- *
- * Value
- *
- * * * * * * * * * * * * * * * * */
+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';
+}
 export const ValueEditor = ({ defaultValue = {}, onChange, path = [] }) => {
     // State
     const [value, setValue] = useState(defaultValue);
@@ -94,16 +102,10 @@ export const ValueEditor = ({ defaultValue = {}, onChange, path = [] }) => {
     const handleRecordValueChange = e => setValueAndDispatch(e);
     const handleArrayValueChange = e => setValueAndDispatch(e);
     // Rendering
-    const valueEditorClss = c('value', {
-        string: typeof value === 'string',
-        number: typeof value === 'number',
-        boolean: typeof value === 'boolean',
-        null: value === null,
-        array: Array.isArray(value),
-        record: !Array.isArray(value) && isNonNullObject(value)
-    });
+    const valueType = getValueType(value);
+    const valueEditorClss = c('value', valueType);
     const pathStringDataAttr = path.map(e => e.toString()).join('.');
-    return _jsxs("span", { className: valueEditorClss, "data-path": pathStringDataAttr, children: [_jsxs(Select, { className: c('type'), onChange: handleTypeSelectChange, children: [_jsx("option", { value: 'string', selected: typeof value === 'string', children: "string" }), _jsx("option", { value: 'number', selected: typeof value === 'number', children: "number" }), _jsx("option", { value: 'boolean', selected: typeof value === 'boolean', children: "boolean" }), _jsx("option", { value: 'null', selected: value === null, children: "null" }), _jsx("option", { value: 'record', selected: isNonNullObject(value) && !Array.isArray(value), children: "record" }), _jsx("option", { value: 'array', selected: Array.isArray(value), children: "array" })] }), typeof value === 'string' && _jsx(StringEditor, { type: 'textarea', defaultValue: value, onChange: handleStringValueChange }), typeof value === 'number' && _jsx(NumberEditor, { defaultValue: value, onChange: handleNumberValueChange }), typeof value === 'boolean' && _jsx(BooleanEditor, { defaultValue: value, onChange: handleBooleanValueChange }), value === null && _jsx(NullEditor, { defaultValue: value }), isNonNullObject(value) && !Array.isArray(value) && _jsx(RecordEditor, { defaultValue: value, onChange: handleRecordValueChange, path: path }), Array.isArray(value) && _jsx(ArrayEditor, { defaultValue: value, onChange: handleArrayValueChange, path: path })] });
+    return _jsxs("span", { className: valueEditorClss, "data-path": pathStringDataAttr, children: [_jsxs(Select, { className: c('type'), value: valueType, onChange: handleTypeSelectChange, children: [_jsx("option", { value: 'string', children: "string" }), _jsx("option", { value: 'number', children: "number" }), _jsx("option", { value: 'boolean', children: "boolean" }), _jsx("option", { value: 'null', children: "null" }), _jsx("option", { value: 'record', children: "record" }), _jsx("option", { value: 'array', children: "array" })] }), typeof value === 'string' && _jsx(StringEditor, { type: 'textarea', defaultValue: value, onChange: handleStringValueChange }), typeof value === 'number' && _jsx(NumberEditor, { defaultValue: value, onChange: handleNumberValueChange }), typeof value === 'boolean' && _jsx(BooleanEditor, { defaultValue: value, onChange: handleBooleanValueChange }), value === null && _jsx(NullEditor, { defaultValue: value }), isNonNullObject(value) && !Array.isArray(value) && _jsx(RecordEditor, { defaultValue: value, onChange: handleRecordValueChange, path: path }), Array.isArray(value) && _jsx(ArrayEditor, { defaultValue: value, onChange: handleArrayValueChange, path: path })] });
 };
 /* * * * * * * * * * * * * * * * *
  *

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 ListLoaderControlled} 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 onLoadPageClick - 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 `onLoadPageClick` 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[];
+    onLoadPageClick?: (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 ListLoaderControlled: <T>({ className, pages, firstPagePos, lastPagePos, itemsPages, filter, display, getIdentifier, loadingPages, onLoadPageClick, 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 ListLoaderControlled = ({ className, pages, firstPagePos, lastPagePos, itemsPages, filter, display, getIdentifier, loadingPages, onLoadPageClick, 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(null), className);
+    const renderLoadButton = (pagePos, kind) => {
+        const button = _jsx("button", { className: c('load', kind), "data-page": pagePos, onClick: () => onLoadPageClick?.(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;
+                onLoadPageClick?.(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
+ * `onFetchError` 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 onFetchSuccess - Called after a page's items have been stored. Not
+ * called for a page dropped while its request was in flight.
+ * @property onFetchError - 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;
+    onFetchSuccess?: (pagePos: number, items: T[]) => void;
+    onFetchError?: (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 ListLoaderControlled} with the result.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @see {@link ListLoaderControlled} for the rendered markup and CSS elements.
+ * @returns A {@link ListLoaderControlled} 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 `onLoadPageClick`.
+ * - In uncontrolled mode, internal state is initialized from `defaultPage` and load
+ *   buttons extend the set themselves. `onLoadPageClick` 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, onLoadPageClick, staleAfterMs, onFetchSuccess, onFetchError, fetchRetriesNb, fetchRetriesDelayMs }: Props<T>) => ReactNode;