@venizia/ardor-react 0.4.8-6 → 0.4.8-8

package/dist/hooks/use-intersection.d.ts

@@ -1,17 +1,26 @@
 import { type TElementTarget } from './element-target.js';
-/** The element `useIntersection` watches and when it delivers an entry. */
+/** The element or elements `useIntersection` watches, against which root, and when it delivers an entry. */
 export interface IUseIntersectionOptions {
-    /** Read after every render: an element, a ref to one, or `null`. */
-    target: TElementTarget;
+    /** Read after every render: an element, a ref to one, or `null`; or a list of them to watch several. */
+    target: TElementTarget | TElementTarget[];
+    /**
+     * The scrolling container the target is measured against. A ref is read after every render, and nothing is
+     * observed while its `current` is `null`. A literal `null`, or leaving it out, is the viewport.
+     */
+    root?: TElementTarget;
     /** @default '0px' */
     rootMargin?: string;
-    /** The ratio of the element in view at which an entry is delivered; a single number, not an array. @default 0 */
-    threshold?: number;
+    /** The ratio of the element in view at which an entry is delivered; a number or a list of them. @default 0 */
+    threshold?: number | number[];
 }
+type TEntry = IntersectionObserverEntry | undefined;
 /**
- * The latest `IntersectionObserverEntry` of the target, or `undefined` before the first one and
- * where there is no `IntersectionObserver`. The state changes only when `isIntersecting` or the
- * ratio changed. A new element, `rootMargin` or `threshold` starts again from `undefined`.
+ * The latest `IntersectionObserverEntry` of the target, or `undefined` before the first one and where there is
+ * no `IntersectionObserver`. The state changes only when `isIntersecting` or the ratio changed.
+ *
+ * With a list as `target` it returns an array in target order: the latest entry of each target, `undefined` for
+ * one with no element or not reported yet. A new element, `root`, `rootMargin` or `threshold` starts again from
+ * `undefined` for every target; the browser reports each target again at once.
  *
  * @example
  * ```tsx
@@ -25,5 +34,12 @@ export interface IUseIntersectionOptions {
  * }
  * ```
  */
-export declare const useIntersection: (opts: IUseIntersectionOptions) => IntersectionObserverEntry | undefined;
+export declare function useIntersection(opts: IUseIntersectionOptions & {
+    target: TElementTarget[];
+}): TEntry[];
+export declare function useIntersection(opts: IUseIntersectionOptions & {
+    target: TElementTarget;
+}): TEntry;
+export declare function useIntersection(opts: IUseIntersectionOptions): TEntry | TEntry[];
+export {};
 //# sourceMappingURL=use-intersection.d.ts.map

package/dist/hooks/use-intersection.js

@@ -1,50 +1,74 @@
 import React from 'react';
 import { ElementTargets } from './element-target.js';
-/**
- * The latest `IntersectionObserverEntry` of the target, or `undefined` before the first one and
- * where there is no `IntersectionObserver`. The state changes only when `isIntersecting` or the
- * ratio changed. A new element, `rootMargin` or `threshold` starts again from `undefined`.
- *
- * @example
- * ```tsx
- * import React from 'react';
- * import { useIntersection } from '@venizia/ardor';
- *
- * export function Lazy() {
- *   const ref = React.useRef<HTMLDivElement>(null);
- *   const entry = useIntersection({ target: ref, threshold: 0.5 });
- *   return <div ref={ref}>{entry?.isIntersecting ? 'visible' : 'hidden'}</div>;
- * }
- * ```
- */
-export const useIntersection = (opts) => {
-    const { target, rootMargin, threshold } = opts;
-    const [element, setElement] = React.useState(null);
-    const [entry, setEntry] = React.useState();
-    // oxlint-disable-next-line react-hooks/exhaustive-deps -- the target is read after every render, and a state set to the same element renders nothing
+const EMPTY_SCOPE = { elements: [], root: null, isRootPending: false };
+const NO_ENTRIES = new Map();
+const resolveScope = (opts) => {
+    const { target, root } = opts;
+    const targets = Array.isArray(target) ? target : [target];
+    const rootElement = root === undefined ? null : ElementTargets.resolve({ target: root });
+    return {
+        elements: targets.map((item) => ElementTargets.resolve({ target: item })),
+        root: rootElement,
+        isRootPending: rootElement === null && root !== undefined && root !== null,
+    };
+};
+const sameScope = (a, b) => {
+    return (a.root === b.root &&
+        a.isRootPending === b.isRootPending &&
+        a.elements.length === b.elements.length &&
+        a.elements.every((element, index) => element === b.elements[index]));
+};
+export function useIntersection(opts) {
+    const { target, root, rootMargin, threshold } = opts;
+    const isList = Array.isArray(target);
+    const count = isList ? target.length : 1;
+    // A number list is compared by value, so a list made anew in each render observes nothing again.
+    const thresholdKey = threshold === undefined ? undefined : JSON.stringify(threshold);
+    const [scope, setScope] = React.useState(EMPTY_SCOPE);
+    const [entries, setEntries] = React.useState(NO_ENTRIES);
+    // oxlint-disable-next-line react-hooks/exhaustive-deps -- the target and root are read after every render, and a state set to an equal scope renders nothing
     React.useEffect(() => {
-        setElement(ElementTargets.resolve({ target }));
+        const next = resolveScope({ target, root });
+        setScope((current) => (sameScope(current, next) ? current : next));
     });
     React.useEffect(() => {
-        setEntry(undefined);
-        if (!element || typeof IntersectionObserver === 'undefined') {
+        setEntries((current) => (current.size === 0 ? current : NO_ENTRIES));
+        const watched = new Set(scope.elements.filter((element) => element !== null));
+        if (watched.size === 0 || scope.isRootPending || typeof IntersectionObserver === 'undefined') {
             return () => { };
         }
-        const observer = new IntersectionObserver((entries) => {
-            const latest = entries.at(-1);
-            if (!latest) {
-                return;
-            }
-            setEntry((current) => {
-                return current?.isIntersecting === latest.isIntersecting &&
-                    current.intersectionRatio === latest.intersectionRatio
-                    ? current
-                    : latest;
+        const observer = new IntersectionObserver((delivered) => {
+            setEntries((current) => {
+                let next = current;
+                for (const entry of delivered) {
+                    const known = next.get(entry.target);
+                    if (known?.isIntersecting === entry.isIntersecting &&
+                        known.intersectionRatio === entry.intersectionRatio) {
+                        continue;
+                    }
+                    if (next === current) {
+                        next = new Map(current);
+                    }
+                    next.set(entry.target, entry);
+                }
+                return next;
             });
-        }, { rootMargin, threshold });
-        observer.observe(element);
+        }, {
+            root: scope.root ?? undefined,
+            rootMargin,
+            threshold: thresholdKey === undefined ? undefined : JSON.parse(thresholdKey),
+        });
+        for (const element of watched) {
+            observer.observe(element);
+        }
         return () => observer.disconnect();
-    }, [element, rootMargin, threshold]);
-    return entry;
-};
+    }, [scope, rootMargin, thresholdKey]);
+    return React.useMemo(() => {
+        const read = Array.from({ length: count }, (_, index) => {
+            const element = scope.elements[index];
+            return element ? entries.get(element) : undefined;
+        });
+        return isList ? read : read[0];
+    }, [count, isList, scope, entries]);
+}
 //# sourceMappingURL=use-intersection.js.map

package/dist/hooks/use-stored-state.d.ts

@@ -1,8 +1,8 @@
 import { type IStorageCodec, type TStorageArea } from '@venizia/ardor-kernel';
 /** What `useStoredState` stores, where and how. */
 export interface IUseStoredStateOptions<TValue> {
-    /** The storage key. */
-    key: string;
+    /** The storage key. `null` turns the storage off: nothing is read, written or watched, `value` starts from `defaultValue` and `setValue` keeps it in memory only, as `useState` does. */
+    key: string | null;
     /** The value while the key holds nothing. */
     defaultValue: TValue;
     /** @default 'local' */

package/dist/hooks/use-stored-state.js

@@ -37,8 +37,9 @@ export const useStoredState = (opts) => {
     }, [keep]);
     const isDelayed = writeDelayMs > 0;
     const flush = React.useCallback(() => {
-        if (timerRef.current !== undefined && keptRef.current) {
-            write(keptRef.current);
+        const pending = keptRef.current;
+        if (timerRef.current !== undefined && pending?.key != null) {
+            write({ ...pending, key: pending.key });
         }
     }, [write]);
     // A new key or storage, an unmount, and a page that closes or hides write the pending value to the
@@ -49,6 +50,10 @@ export const useStoredState = (opts) => {
                 flush();
             }
         };
+        // The value kept in memory under a `null` key does not follow the hook to a real key, or back to a later `null`.
+        if (key !== null && keptRef.current?.key === null) {
+            keep(undefined);
+        }
         if (isDelayed) {
             window.addEventListener('pagehide', flush);
             document.addEventListener('visibilitychange', onHide);
@@ -58,8 +63,11 @@ export const useStoredState = (opts) => {
             document.removeEventListener('visibilitychange', onHide);
             flush();
         };
-    }, [key, storage, isDelayed, flush]);
+    }, [key, storage, isDelayed, flush, keep]);
     const subscribe = React.useCallback((listener) => {
+        if (key === null) {
+            return () => { };
+        }
         return BrowserStorage.subscribe({
             key,
             storage,
@@ -70,6 +78,9 @@ export const useStoredState = (opts) => {
         });
     }, [key, storage, keep]);
     const getSnapshot = React.useCallback(() => {
+        if (key === null) {
+            return defaultValue;
+        }
         const text = BrowserStorage.get({ key, storage, fallback: null, codec: RAW_TEXT });
         if (text === null) {
             return defaultValue;
@@ -87,7 +98,12 @@ export const useStoredState = (opts) => {
     const setValue = React.useCallback((next) => {
         const hit = keptRef.current;
         const current = hit?.key === key && hit.storage === storage ? hit.value : getSnapshot();
-        const entry = { key, storage, codec, value: isUpdater(next) ? next(current) : next };
+        const nextValue = isUpdater(next) ? next(current) : next;
+        if (key === null) {
+            keep({ key, storage, codec, value: nextValue });
+            return;
+        }
+        const entry = { key, storage, codec, value: nextValue };
         if (!(writeDelayMs > 0)) {
             write(entry);
             return;
@@ -96,6 +112,10 @@ export const useStoredState = (opts) => {
         timerRef.current = setTimeout(() => write(entry), writeDelayMs);
     }, [key, storage, codec, writeDelayMs, getSnapshot, keep, write]);
     const remove = React.useCallback(() => {
+        if (key === null) {
+            keep(undefined);
+            return;
+        }
         const isRemoved = BrowserStorage.remove({ key, storage });
         keep(isRemoved ? undefined : { key, storage, value: defaultValue });
     }, [key, storage, defaultValue, keep]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/ardor-react",
-  "version": "0.4.8-6",
+  "version": "0.4.8-8",
   "description": "ARDOR React bindings - the application context, the injectable and logger hooks that read it, typed Redux hook factories, and the framework-agnostic UI hooks (debounce, autosave, confirm, clipboard, element size, window dimensions). No react-admin.",
   "keywords": [
     "ardor",
@@ -59,7 +59,7 @@
     "prepublishOnly": "make rebuild"
   },
   "dependencies": {
-    "@venizia/ardor-kernel": "0.4.8-6"
+    "@venizia/ardor-kernel": "0.4.8-8"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^21.0.4",
@@ -69,11 +69,11 @@
     "@types/bun": "^1.4.3",
     "@types/react": "^19",
     "@types/react-dom": "^19",
-    "@venizia/dev-configs": "^0.4.8-2",
-    "@venizia/ignis-filter": "^0.4.7-3",
-    "@venizia/ignis-helpers": "^0.4.8-5",
-    "@venizia/ignis-inversion": "^0.4.7-2",
-    "@venizia/ignis-kernel": "^0.4.8-5",
+    "@venizia/dev-configs": "^0.4.8-4",
+    "@venizia/ignis-filter": "^0.4.7-4",
+    "@venizia/ignis-helpers": "^0.4.8-7",
+    "@venizia/ignis-inversion": "^0.4.7-3",
+    "@venizia/ignis-kernel": "^0.4.8-7",
     "eslint": "^10.13.0",
     "oxlint": "1.89.0",
     "oxlint-tsgolint": "7.0.2004",
@@ -87,10 +87,10 @@
   },
   "peerDependencies": {
     "@reduxjs/toolkit": ">=2.13.0",
-    "@venizia/ignis-filter": "^0.4.7-3",
-    "@venizia/ignis-helpers": "^0.4.8-5",
-    "@venizia/ignis-inversion": "^0.4.7-2",
-    "@venizia/ignis-kernel": "^0.4.8-5",
+    "@venizia/ignis-filter": "^0.4.7-4",
+    "@venizia/ignis-helpers": "^0.4.8-7",
+    "@venizia/ignis-inversion": "^0.4.7-3",
+    "@venizia/ignis-kernel": "^0.4.8-7",
     "react": ">=19.3.1",
     "react-redux": ">=9.3.0",
     "reflect-metadata": ">=0.2.2"
@@ -111,7 +111,7 @@
         "react",
         "react-redux"
       ],
-      "limit": "3540 B"
+      "limit": "3875 B"
     }
   ],
   "engines": {