@venizia/ardor-react 0.4.8-0 → 0.4.8-10

package/dist/hooks/use-document-visibility.js

@@ -0,0 +1,10 @@
+import React from 'react';
+const subscribe = (listener) => {
+    document.addEventListener('visibilitychange', listener);
+    return () => document.removeEventListener('visibilitychange', listener);
+};
+/** `'visible'` or `'hidden'`, as the document says. `'visible'` in a server render. */
+export const useDocumentVisibility = () => {
+    return React.useSyncExternalStore(subscribe, () => document.visibilityState, () => 'visible');
+};
+//# sourceMappingURL=use-document-visibility.js.map

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

@@ -1,19 +1,24 @@
 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>;
     /** @default 'content-box' */
-    box?: 'content-box' | 'border-box';
+    box?: TResizeBox;
     /** 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>;
 }
 /**
@@ -23,6 +28,16 @@ export interface IUseElementSizeRefReturn extends IUseElementSizeReturn {
  * is read when the effect runs, so it follows a new `ref`, `box` or `round`, not a `ref.current`
  * that is replaced later; pass a stable `ref`. A new element, `box` or `round` starts again from
  * 0 by 0 with `measured` false.
+ *
+ * @example
+ * ```tsx
+ * import { useElementSize } from '@venizia/ardor';
+ *
+ * export function Panel() {
+ *   const { ref, width, height, measured } = useElementSize();
+ *   return <div ref={ref}>{measured ? `${width} x ${height}` : '...'}</div>;
+ * }
+ * ```
  */
 export declare function useElementSize(opts: IUseElementSizeOptions & {
     ref: React.RefObject<Element | null>;

package/dist/hooks/use-element-size.js

@@ -1,4 +1,5 @@
 import React from 'react';
+import { ResizeObservation } from './resize-observation.js';
 const ZERO_SIZE = { width: 0, height: 0, measured: false };
 const readSize = (opts) => {
     const { entry, box, round } = opts;
@@ -16,36 +17,26 @@ export function useElementSize(opts = {}) {
     React.useEffect(() => {
         setSize((current) => (current.measured ? ZERO_SIZE : current));
         const target = ref ? ref.current : element;
-        if (!target || typeof ResizeObserver === 'undefined') {
+        if (!target) {
             return () => { };
         }
-        let frame;
-        let latest;
-        const observer = new ResizeObserver((entries) => {
-            latest = entries[entries.length - 1];
-            if (frame !== undefined) {
-                return;
-            }
-            frame = requestAnimationFrame(() => {
-                frame = undefined;
-                if (!latest) {
+        const observation = ResizeObservation.observe({
+            box,
+            onFrame: (entries) => {
+                const entry = entries.at(-1);
+                if (!entry) {
                     return;
                 }
-                const next = readSize({ entry: latest, box, round });
+                const next = readSize({ entry, box, round });
                 setSize((current) => {
                     return current.measured && current.width === next.width && current.height === next.height
                         ? current
                         : next;
                 });
-            });
+            },
         });
-        observer.observe(target, { box });
-        return () => {
-            observer.disconnect();
-            if (frame !== undefined) {
-                cancelAnimationFrame(frame);
-            }
-        };
+        observation.sync([target]);
+        return observation.stop;
     }, [ref, element, box, round]);
     return ref ? size : { ...size, ref: setElement };
 }

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

@@ -1,14 +1,31 @@
 import { type Container, type TClass } from '@venizia/ignis-inversion';
 import type { CoreBindings, ValueOf } from '@venizia/ardor-kernel';
+/** Declaration-merge string keys into this interface to make them valid `key` values of the injectable hooks. */
 export interface IUseInjectableKeysOverrides {
 }
+/** The binding keys the kernel defines (the string values of `CoreBindings`). */
 export type TUseInjectableKeysDefault = Extract<ValueOf<typeof CoreBindings>, string>;
+/** A key the injectable hooks accept: a kernel binding key or one added to `IUseInjectableKeysOverrides`. */
 export type TUseInjectableKeys = TUseInjectableKeysDefault | keyof IUseInjectableKeysOverrides;
+/**
+ * Resolve by `key` or by `target` class, never both.
+ *
+ * @example
+ * ```ts
+ * import { CoreBindings, type TUseInjectableOptions } from '@venizia/ardor';
+ *
+ * const byKey: TUseInjectableOptions = { key: CoreBindings.DEFAULT_REST_DATA_PROVIDER };
+ * class Greeter {}
+ * const byTarget: TUseInjectableOptions = { target: Greeter };
+ * ```
+ */
 export type TUseInjectableOptions = {
+    /** The container to resolve from. @default The application's container (`ApplicationContext`) */
     container?: Container;
     key: TUseInjectableKeys;
     target?: never;
 } | {
+    /** The container to resolve from. @default The application's container (`ApplicationContext`) */
     container?: Container;
     key?: never;
     target: TClass<unknown>;
@@ -16,9 +33,23 @@ export type TUseInjectableOptions = {
 /**
  * The container an injectable hook resolves from: the one passed in, else the application's. Shared,
  * so a hook never checks one container and resolves from another.
+ *
+ * @example
+ * ```tsx
+ * import { CoreBindings, useApplicationContainer } from '@venizia/ardor';
+ *
+ * export function BindingCheck() {
+ *   const container = useApplicationContainer();
+ *   return <span>{container.isBound({ key: CoreBindings.DEFAULT_REST_DATA_PROVIDER }) ? 'bound' : 'unbound'}</span>;
+ * }
+ * ```
  */
-export declare const useInjectableContainer: (opts?: {
+export declare const useApplicationContainer: (opts?: {
     container?: Container;
 }) => Container;
+/**
+ * Resolves an instance from the container by `key` or by `target` class. Throws when the key is not
+ * bound, when the class has no recorded binding key, or when neither `key` nor `target` is given.
+ */
 export declare const useInjectable: <TInstance>(opts: TUseInjectableOptions) => TInstance;
 //# sourceMappingURL=use-injectable.d.ts.map

package/dist/hooks/use-injectable.js

@@ -4,19 +4,33 @@ import { ApplicationContext } from '../contexts/application.js';
 /**
  * The container an injectable hook resolves from: the one passed in, else the application's. Shared,
  * so a hook never checks one container and resolves from another.
+ *
+ * @example
+ * ```tsx
+ * import { CoreBindings, useApplicationContainer } from '@venizia/ardor';
+ *
+ * export function BindingCheck() {
+ *   const container = useApplicationContainer();
+ *   return <span>{container.isBound({ key: CoreBindings.DEFAULT_REST_DATA_PROVIDER }) ? 'bound' : 'unbound'}</span>;
+ * }
+ * ```
  */
-export const useInjectableContainer = (opts) => {
+export const useApplicationContainer = (opts) => {
     const applicationContext = React.useContext(ApplicationContext);
     const container = opts?.container ?? applicationContext.container;
     if (!container) {
         throw getError({
-            message: '[useInjectable] Failed to determine injectable container!',
+            message: '[useApplicationContainer] Failed to determine the application container!',
         });
     }
     return container;
 };
+/**
+ * Resolves an instance from the container by `key` or by `target` class. Throws when the key is not
+ * bound, when the class has no recorded binding key, or when neither `key` nor `target` is given.
+ */
 export const useInjectable = (opts) => {
-    const container = useInjectableContainer({ container: opts?.container });
+    const container = useApplicationContainer({ container: opts?.container });
     const { key, target } = opts;
     if (key) {
         if (!container.isBound({ key })) {

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

@@ -0,0 +1,45 @@
+import { type TElementTarget } from './element-target.js';
+/** 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`; 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 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.
+ *
+ * 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
+ * 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 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

@@ -0,0 +1,74 @@
+import React from 'react';
+import { ElementTargets } from './element-target.js';
+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(() => {
+        const next = resolveScope({ target, root });
+        setScope((current) => (sameScope(current, next) ? current : next));
+    });
+    React.useEffect(() => {
+        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((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;
+            });
+        }, {
+            root: scope.root ?? undefined,
+            rootMargin,
+            threshold: thresholdKey === undefined ? undefined : JSON.parse(thresholdKey),
+        });
+        for (const element of watched) {
+            observer.observe(element);
+        }
+        return () => observer.disconnect();
+    }, [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-media-query.d.ts

@@ -0,0 +1,5 @@
+/** Whether the media query matches now, and again after each change. `false` in a server render. */
+export declare const useMediaQuery: (opts: {
+    query: string;
+}) => boolean;
+//# sourceMappingURL=use-media-query.d.ts.map

package/dist/hooks/use-media-query.js

@@ -0,0 +1,14 @@
+import React from 'react';
+/** Whether the media query matches now, and again after each change. `false` in a server render. */
+export const useMediaQuery = (opts) => {
+    const { query } = opts;
+    const subscribe = React.useMemo(() => {
+        return (listener) => {
+            const list = window.matchMedia(query);
+            list.addEventListener('change', listener);
+            return () => list.removeEventListener('change', listener);
+        };
+    }, [query]);
+    return React.useSyncExternalStore(subscribe, () => window.matchMedia(query).matches, () => false);
+};
+//# sourceMappingURL=use-media-query.js.map

package/dist/hooks/use-online-status.d.ts

@@ -0,0 +1,3 @@
+/** Whether the browser is online, kept by the `online` and `offline` events. `true` in a server render. */
+export declare const useOnlineStatus: () => boolean;
+//# sourceMappingURL=use-online-status.d.ts.map

package/dist/hooks/use-online-status.js

@@ -0,0 +1,14 @@
+import React from 'react';
+const subscribe = (listener) => {
+    window.addEventListener('online', listener);
+    window.addEventListener('offline', listener);
+    return () => {
+        window.removeEventListener('online', listener);
+        window.removeEventListener('offline', listener);
+    };
+};
+/** Whether the browser is online, kept by the `online` and `offline` events. `true` in a server render. */
+export const useOnlineStatus = () => {
+    return React.useSyncExternalStore(subscribe, () => navigator.onLine, () => true);
+};
+//# sourceMappingURL=use-online-status.js.map

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

@@ -0,0 +1,41 @@
+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[];
+    /** Receives the latest entry of each element that resized since the last call. */
+    onResize: (entries: ResizeObserverEntry[]) => void;
+    /** @default 'content-box' */
+    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, 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
+ * import React from 'react';
+ * import { useResizeEffect } from '@venizia/ardor';
+ *
+ * export function Panel() {
+ *   const ref = React.useRef<HTMLDivElement>(null);
+ *   useResizeEffect({ targets: [ref], onResize: (entries) => console.log(entries.length) });
+ *   return <div ref={ref} />;
+ * }
+ * ```
+ */
+export declare const useResizeEffect: (opts: IUseResizeEffectOptions) => void;
+//# sourceMappingURL=use-resize-effect.d.ts.map

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

@@ -0,0 +1,44 @@
+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, 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
+ * import React from 'react';
+ * import { useResizeEffect } from '@venizia/ardor';
+ *
+ * export function Panel() {
+ *   const ref = React.useRef<HTMLDivElement>(null);
+ *   useResizeEffect({ targets: [ref], onResize: (entries) => console.log(entries.length) });
+ *   return <div ref={ref} />;
+ * }
+ * ```
+ */
+export const useResizeEffect = (opts) => {
+    const { targets, onResize, box = 'content-box', children = false, beforePaint = false } = opts;
+    const handleResize = React.useRef(onResize);
+    const observation = React.useRef(undefined);
+    React.useEffect(() => {
+        handleResize.current = onResize;
+        return () => { };
+    }, [onResize]);
+    React.useEffect(() => {
+        const created = ResizeObservation.observe({
+            box,
+            children,
+            beforePaint,
+            onFrame: (entries) => handleResize.current(entries),
+        });
+        observation.current = created;
+        return created.stop;
+    }, [box, children, beforePaint]);
+    React.useEffect(() => {
+        observation.current?.sync(targets.flatMap((target) => ElementTargets.resolve({ target }) ?? []));
+    });
+};
+//# sourceMappingURL=use-resize-effect.js.map

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

@@ -1,21 +1,51 @@
 import { type IStorageCodec, type TStorageArea } from '@venizia/ardor-kernel';
+/** What `useStoredState` stores, where and how. */
 export interface IUseStoredStateOptions<TValue> {
-    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' */
     storage?: TStorageArea;
     /** @default JSON */
     codec?: IStorageCodec<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;
+    /** Stores a value, or the result of an updater called with the current one. */
     setValue: (next: TValue | ((current: TValue) => TValue)) => void;
+    /** 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'> & {
+        defaultValue: NoInfer<TValue>;
+        codec: IStorageCodec<TValue>;
+    }): IUseStoredStateReturn<TValue>;
+    <TValue>(opts: IUseStoredStateOptions<TValue>): IUseStoredStateReturn<TValue>;
+}
 /**
  * A value kept in `localStorage` or `sessionStorage`, in step with other hooks on the key, with code
  * that writes through `BrowserStorage`, and with other tabs. Pass a stable `codec` and `defaultValue`.
  * A write or a removal that the storage refuses is kept in this hook until the storage next changes.
+ * With `writeDelayMs` the value waits in the same place for the delay: a change of the storage from
+ * outside drops it, and an unmount, a new key or storage, a `pagehide` event or a hidden page writes it at once.
+ *
+ * @example
+ * ```tsx
+ * import { useStoredState } from '@venizia/ardor';
+ *
+ * export function ThemeToggle() {
+ *   const { value, setValue } = useStoredState({ key: '@app/prefs/theme', defaultValue: 'light' });
+ *   return <button onClick={() => setValue(value === 'light' ? 'dark' : 'light')}>{value}</button>;
+ * }
+ * ```
  */
-export declare const useStoredState: <TValue>(opts: IUseStoredStateOptions<TValue>) => IUseStoredStateReturn<TValue>;
+export declare const useStoredState: IUseStoredState;
 //# sourceMappingURL=use-stored-state.d.ts.map

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

@@ -1,26 +1,73 @@
 import React from 'react';
-import { BrowserStorage } from '@venizia/ardor-kernel';
-/** Reads the stored text as it is, `null` when there is none. */
-const RAW_TEXT = {
-    encode: (text) => text ?? '',
-    decode: (text) => text,
-};
+import { BrowserStorage, StorageCodecs, } from '@venizia/ardor-kernel';
+const RAW_TEXT = StorageCodecs.text();
 const isUpdater = (next) => typeof next === 'function';
 /**
  * A value kept in `localStorage` or `sessionStorage`, in step with other hooks on the key, with code
  * that writes through `BrowserStorage`, and with other tabs. Pass a stable `codec` and `defaultValue`.
  * A write or a removal that the storage refuses is kept in this hook until the storage next changes.
+ * With `writeDelayMs` the value waits in the same place for the delay: a change of the storage from
+ * outside drops it, and an unmount, a new key or storage, a `pagehide` event or a hidden page writes it at once.
+ *
+ * @example
+ * ```tsx
+ * import { useStoredState } from '@venizia/ardor';
+ *
+ * export function ThemeToggle() {
+ *   const { value, setValue } = useStoredState({ key: '@app/prefs/theme', defaultValue: 'light' });
+ *   return <button onClick={() => setValue(value === 'light' ? 'dark' : 'light')}>{value}</button>;
+ * }
+ * ```
  */
 export const useStoredState = (opts) => {
-    const { key, defaultValue, storage, codec } = opts;
+    const { key, defaultValue, storage, codec, writeDelayMs = 0 } = opts;
     const decoded = React.useRef(undefined);
     const keptRef = React.useRef(undefined);
+    const timerRef = React.useRef(undefined);
     const [kept, setKept] = React.useState();
+    // Every change of the kept value ends a pending write; only a delayed setValue starts one.
     const keep = React.useCallback((next) => {
+        clearTimeout(timerRef.current);
+        timerRef.current = undefined;
         keptRef.current = next;
         setKept(next);
     }, []);
+    const write = React.useCallback((entry) => {
+        keep(BrowserStorage.set(entry) ? undefined : entry);
+    }, [keep]);
+    const isDelayed = writeDelayMs > 0;
+    const flush = React.useCallback(() => {
+        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
+    // key it was set for: closing a tab does not unmount.
+    React.useEffect(() => {
+        const onHide = () => {
+            if (document.visibilityState === 'hidden') {
+                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);
+        }
+        return () => {
+            window.removeEventListener('pagehide', flush);
+            document.removeEventListener('visibilitychange', onHide);
+            flush();
+        };
+    }, [key, storage, isDelayed, flush, keep]);
     const subscribe = React.useCallback((listener) => {
+        if (key === null) {
+            return () => { };
+        }
         return BrowserStorage.subscribe({
             key,
             storage,
@@ -31,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;
@@ -48,11 +98,24 @@ 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 resolved = isUpdater(next) ? next(current) : next;
-        const isStored = BrowserStorage.set({ key, value: resolved, storage, codec });
-        keep(isStored ? undefined : { key, storage, value: resolved });
-    }, [key, storage, codec, getSnapshot, keep]);
+        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;
+        }
+        keep(entry);
+        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/dist/hooks/use-window-dimensions.d.ts

@@ -1,3 +1,4 @@
+/** The window's `innerWidth` and `innerHeight`, updated on resize; 0 x 0 where there is no window. */
 export declare const useWindowDimensions: () => {
     width: number;
     height: number;

package/dist/hooks/use-window-dimensions.js

@@ -6,6 +6,7 @@ const readWindowDimensions = () => {
         ? { width: window.innerWidth, height: window.innerHeight }
         : { width: 0, height: 0 };
 };
+/** The window's `innerWidth` and `innerHeight`, updated on resize; 0 x 0 where there is no window. */
 export const useWindowDimensions = () => {
     const [windowDimensions, setWindowDimensions] = React.useState(readWindowDimensions);
     React.useEffect(() => {