@venizia/ardor-react 0.4.8-2 → 0.4.8-4

package/README.md

@@ -4,9 +4,11 @@ The React bindings of [ARDOR](https://github.com/VENIZIA-AI/ardor): the applicat
 hooks that resolve out of it, and the UI hooks. No react-admin.
 
 ```bash
-bun add @venizia/ardor-react @venizia/ardor-kernel @venizia/ignis-inversion @venizia/ignis-filter @venizia/ignis-kernel @venizia/ignis-helpers reflect-metadata
+bun add @venizia/ardor-react @venizia/ardor-kernel @venizia/ignis-inversion @venizia/ignis-filter @venizia/ignis-kernel @venizia/ignis-helpers reflect-metadata react react-redux
 ```
 
+`@reduxjs/toolkit` is an optional peer: only the types of `DispatchHooks` use it.
+
 Most applications install [`@venizia/ardor`](https://www.npmjs.com/package/@venizia/ardor) instead,
 which re-exports this package.
 

package/dist/hooks/redux/use-app-selector.d.ts

@@ -1,3 +1,4 @@
+/** Builds the typed selector hooks of a Redux store. */
 export declare class SelectorHooks {
     /** The three typed selector hooks of a store: bind your `RootState` once, and export what comes back. */
     static create<TState>(): {

package/dist/hooks/redux/use-app-selector.js

@@ -25,6 +25,7 @@ const deepEqual = (a, b) => {
             return Object.hasOwn(b, key) && deepEqual(Reflect.get(a, key), Reflect.get(b, key));
         }));
 };
+/** Builds the typed selector hooks of a Redux store. */
 export class SelectorHooks {
     /** The three typed selector hooks of a store: bind your `RootState` once, and export what comes back. */
     static create() {

package/dist/hooks/resize-observation.d.ts

@@ -4,7 +4,9 @@ export interface IResizeObservationOptions {
     box: TResizeBox;
     /** Also observe the direct children of each target, and again whenever they change. @default false */
     children?: boolean;
-    /** Called at most once per animation frame, with the latest entry of each element that resized. */
+    /** Call `onFrame` inside the `ResizeObserver` callback, after layout and before paint, instead of on the next animation frame. */
+    beforePaint?: boolean;
+    /** Called with the latest entry of each element that resized: at most once per animation frame, or once per observer callback with `beforePaint`. */
     onFrame: (entries: ResizeObserverEntry[]) => void;
 }
 export interface IResizeObservation {

package/dist/hooks/resize-observation.js

@@ -1,7 +1,7 @@
 export class ResizeObservation {
     /** Does nothing without `ResizeObserver`. */
     static observe(opts) {
-        const { box, children = false, onFrame } = opts;
+        const { box, children = false, beforePaint = false, onFrame } = opts;
         if (typeof ResizeObserver === 'undefined') {
             return { sync: () => { }, stop: () => { } };
         }
@@ -9,20 +9,27 @@ export class ResizeObservation {
         let watched = new Set();
         let current = [];
         let frame;
+        const flush = () => {
+            const batch = [...latest.values()];
+            latest.clear();
+            if (batch.length > 0) {
+                onFrame(batch);
+            }
+        };
         const observer = new ResizeObserver((entries) => {
             for (const entry of entries) {
                 latest.set(entry.target, entry);
             }
+            if (beforePaint) {
+                flush();
+                return;
+            }
             if (frame !== undefined) {
                 return;
             }
             frame = requestAnimationFrame(() => {
                 frame = undefined;
-                const batch = [...latest.values()];
-                latest.clear();
-                if (batch.length > 0) {
-                    onFrame(batch);
-                }
+                flush();
             });
         });
         const update = (targets) => {

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

@@ -1,3 +1,4 @@
+/** What `useAutosave` saves, through which callback, and when. */
 export interface IUseAutosaveOptions<TData, TReturn> {
     /** The value to save; a change starts the `interval` wait. */
     data: TData;

package/dist/hooks/use-before-unload.d.ts

@@ -1,3 +1,4 @@
+/** When `useBeforeUnload` asks, and the text it sets. */
 export interface IUseBeforeUnloadOptions {
     /** @default true */
     enabled?: boolean;

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

@@ -1,3 +1,4 @@
+/** The state of one confirmation prompt, and the handlers that settle it. */
 export interface IUseConfirmReturn {
     /** The pending prompt text; `undefined` when none is open. */
     message?: string;

package/dist/hooks/use-copy-to-clipboard.d.ts

@@ -1,7 +1,9 @@
+/** How long `useCopyToClipboard` keeps `isCopied` set. */
 export interface IUseCopyToClipboardOptions {
     /** Set `isCopied` back to `false` this many milliseconds after a copy; 0 or less never resets. @default 0 */
     resetMs?: number;
 }
+/** The copy function of `useCopyToClipboard` and the result of its last call. */
 export interface IUseCopyToClipboardReturn {
     /** Resolves `true` when the text is on the clipboard and `false` otherwise, and never throws. */
     copy: (opts: {

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

@@ -1,3 +1,4 @@
+/** The value `useDebounce` follows, how long it waits, and when it runs. */
 export interface IUseDebounceOptions<TValue> {
     /** The value to follow; the output changes once it has been still for `delay`. */
     value: TValue;
@@ -6,6 +7,7 @@ export interface IUseDebounceOptions<TValue> {
     /** @default true */
     enabled?: boolean;
 }
+/** The settled value of `useDebounce`. */
 export interface IUseDebounceReturn<TValue> {
     /** The last `value` that stayed unchanged for `delay`; the first `value` until then. */
     debouncedValue: TValue;

package/dist/hooks/use-element-size.d.ts

@@ -1,5 +1,6 @@
 import React from 'react';
 import { type TResizeBox } from './resize-observation.js';
+/** Which element `useElementSize` measures, which box it reads, and how it rounds. */
 export interface IUseElementSizeOptions {
     /** The element to measure. Leave it out to measure the element the returned `ref` is given to. */
     ref?: React.RefObject<Element | null>;
@@ -8,12 +9,14 @@ export interface IUseElementSizeOptions {
     /** Round width and height to whole pixels, so a fractional size does not render again. @default false */
     round?: boolean;
 }
+/** The size `useElementSize` read, in CSS pixels. */
 export interface IUseElementSizeReturn {
     width: number;
     height: number;
     /** `false` until the first size is read, so 0 by 0 can be told from a measured empty element. */
     measured: boolean;
 }
+/** The size of `useElementSize` called without a `ref` option, with the ref to give an element. */
 export interface IUseElementSizeRefReturn extends IUseElementSizeReturn {
     /** Give it to the element to measure. */
     ref: React.RefCallback<Element>;

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

@@ -1,4 +1,5 @@
 import { type TElementTarget } from './element-target.js';
+/** The element `useIntersection` watches and when it delivers an entry. */
 export interface IUseIntersectionOptions {
     /** Read after every render: an element, a ref to one, or `null`. */
     target: TElementTarget;

package/dist/hooks/use-resize-effect.d.ts

@@ -1,5 +1,6 @@
 import { type TElementTarget } from './element-target.js';
 import { type TResizeBox } from './resize-observation.js';
+/** What `useResizeEffect` watches and the callback it calls. */
 export interface IUseResizeEffectOptions {
     /** Read after every render: an element, a ref to one, or `null`, which is skipped. */
     targets: TElementTarget[];
@@ -9,11 +10,20 @@ export interface IUseResizeEffectOptions {
     box?: TResizeBox;
     /** Also observe the direct children of each target, and again whenever they change. @default false */
     children?: boolean;
+    /**
+     * Call `onResize` inside the `ResizeObserver` callback, after layout and before paint, instead of on
+     * the next animation frame, once per observer callback. What `onResize` draws or styles directly
+     * shows in the frame that resized; a state update renders later. Resizing an observed element from
+     * it can report "ResizeObserver loop completed with undelivered notifications".
+     * @default false
+     */
+    beforePaint?: boolean;
 }
 /**
- * Calls `onResize` at most once per animation frame when any of the targets resizes. A new
- * `onResize` is used without observing again, and the targets are read after every render, so an
- * element held in state, a ref whose element changed and a list that grows or shrinks are followed.
+ * Calls `onResize` at most once per animation frame when any of the targets resizes, or inside the
+ * observer callback with `beforePaint`. A new `onResize` is used without observing again, and the
+ * targets are read after every render, so an element held in state, a ref whose element changed and
+ * a list that grows or shrinks are followed.
  *
  * @example
  * ```tsx

package/dist/hooks/use-resize-effect.js

@@ -2,9 +2,10 @@ import React from 'react';
 import { ElementTargets } from './element-target.js';
 import { ResizeObservation } from './resize-observation.js';
 /**
- * Calls `onResize` at most once per animation frame when any of the targets resizes. A new
- * `onResize` is used without observing again, and the targets are read after every render, so an
- * element held in state, a ref whose element changed and a list that grows or shrinks are followed.
+ * Calls `onResize` at most once per animation frame when any of the targets resizes, or inside the
+ * observer callback with `beforePaint`. A new `onResize` is used without observing again, and the
+ * targets are read after every render, so an element held in state, a ref whose element changed and
+ * a list that grows or shrinks are followed.
  *
  * @example
  * ```tsx
@@ -19,7 +20,7 @@ import { ResizeObservation } from './resize-observation.js';
  * ```
  */
 export const useResizeEffect = (opts) => {
-    const { targets, onResize, box = 'content-box', children = false } = opts;
+    const { targets, onResize, box = 'content-box', children = false, beforePaint = false } = opts;
     const handleResize = React.useRef(onResize);
     const observation = React.useRef(undefined);
     React.useEffect(() => {
@@ -30,11 +31,12 @@ export const useResizeEffect = (opts) => {
         const created = ResizeObservation.observe({
             box,
             children,
+            beforePaint,
             onFrame: (entries) => handleResize.current(entries),
         });
         observation.current = created;
         return created.stop;
-    }, [box, children]);
+    }, [box, children, beforePaint]);
     React.useEffect(() => {
         observation.current?.sync(targets.flatMap((target) => ElementTargets.resolve({ target }) ?? []));
     });

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

@@ -1,4 +1,5 @@
 import { type IStorageCodec, type TStorageArea } from '@venizia/ardor-kernel';
+/** What `useStoredState` stores, where and how. */
 export interface IUseStoredStateOptions<TValue> {
     /** The storage key. */
     key: string;
@@ -11,6 +12,7 @@ export interface IUseStoredStateOptions<TValue> {
     /** Write storage once, this many milliseconds after the last `setValue`; `value` changes at once. Above 0, also pass a stable `codec`. @default 0 */
     writeDelayMs?: number;
 }
+/** The value `useStoredState` holds, and how to change or remove it. */
 export interface IUseStoredStateReturn<TValue> {
     /** The stored value, or `defaultValue` when the key holds nothing. */
     value: TValue;
@@ -19,6 +21,7 @@ export interface IUseStoredStateReturn<TValue> {
     /** Removes the key, so `value` is `defaultValue` again. */
     remove: () => void;
 }
+/** The call signatures of `useStoredState`. */
 export interface IUseStoredState {
     /** With a codec, the value type is the codec's: a literal `defaultValue` is checked against it, not widened past it. */
     <TValue>(opts: Omit<IUseStoredStateOptions<TValue>, 'defaultValue' | 'codec'> & {
@@ -39,7 +42,7 @@ export interface IUseStoredState {
  * import { useStoredState } from '@venizia/ardor';
  *
  * export function ThemeToggle() {
- *   const { value, setValue } = useStoredState({ key: 'theme', defaultValue: 'light' });
+ *   const { value, setValue } = useStoredState({ key: '@app/store/theme', defaultValue: 'light' });
  *   return <button onClick={() => setValue(value === 'light' ? 'dark' : 'light')}>{value}</button>;
  * }
  * ```

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

@@ -14,7 +14,7 @@ const isUpdater = (next) => typeof next === 'function';
  * import { useStoredState } from '@venizia/ardor';
  *
  * export function ThemeToggle() {
- *   const { value, setValue } = useStoredState({ key: 'theme', defaultValue: 'light' });
+ *   const { value, setValue } = useStoredState({ key: '@app/store/theme', defaultValue: 'light' });
  *   return <button onClick={() => setValue(value === 'light' ? 'dark' : 'light')}>{value}</button>;
  * }
  * ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/ardor-react",
-  "version": "0.4.8-2",
+  "version": "0.4.8-4",
   "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-2"
+    "@venizia/ardor-kernel": "0.4.8-4"
   },
   "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-1",
-    "@venizia/ignis-filter": "^0.4.7-1",
-    "@venizia/ignis-helpers": "^0.4.8-1",
-    "@venizia/ignis-inversion": "^0.4.7-1",
-    "@venizia/ignis-kernel": "^0.4.8-1",
+    "@venizia/dev-configs": "^0.4.8-2",
+    "@venizia/ignis-filter": "^0.4.7-2",
+    "@venizia/ignis-helpers": "^0.4.8-3",
+    "@venizia/ignis-inversion": "^0.4.7-2",
+    "@venizia/ignis-kernel": "^0.4.8-3",
     "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-1",
-    "@venizia/ignis-helpers": "^0.4.8-1",
-    "@venizia/ignis-inversion": "^0.4.7-1",
-    "@venizia/ignis-kernel": "^0.4.8-1",
+    "@venizia/ignis-filter": "^0.4.7-2",
+    "@venizia/ignis-helpers": "^0.4.8-3",
+    "@venizia/ignis-inversion": "^0.4.7-2",
+    "@venizia/ignis-kernel": "^0.4.8-3",
     "react": ">=19.3.1",
     "react-redux": ">=9.3.0",
     "reflect-metadata": ">=0.2.2"