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

package/README.md

@@ -15,15 +15,14 @@ which re-exports this package.
 | Area | Exports |
 |---|---|
 | Context | `ApplicationContext`, `useApplicationContext`, `useApplicationLogger` |
-| Injection | `useInjectable` - resolve a binding by key or by class |
+| Injection | `useInjectable` - resolve a binding by key or by class; the artifact hooks `useApplicationContainer`, `useService`, `useProvider`, `useComponent`, `useConfiguration`, `useRepository` |
 | Redux | `DispatchHooks.create`, `SelectorHooks.create` - factories that bind your `RootState` and `AppDispatch` (the old `createAppDispatch` and `createAppSelectors` are removed; `bun run ardor codemod namespace` moves your code) |
-| UI hooks | `useDebounce`, `useAutosave`, `useConfirm`, `useBeforeUnload`, `useCopyToClipboard`, `useSizer`, `useWindowDimensions` |
+| UI hooks | `useDebounce`, `useAutosave`, `useConfirm`, `useBeforeUnload`, `useCopyToClipboard`, `useWindowDimensions`, `useElementSize`, `useResizeEffect`, `useIntersection`, `useStoredState`, `useMediaQuery`, `useDocumentVisibility`, `useOnlineStatus` |
 | Types | `TUseInjectableKeys` |
 
 ## Typing your own binding keys
 
-`IUseInjectableKeysOverrides` is declared here, so augment this package - an interface merges only
-into the module that declares it, never through a re-export:
+`IUseInjectableKeysOverrides` is declared here, so augment this package when it is the one you depend on:
 
 ```typescript
 declare module '@venizia/ardor-react' {
@@ -33,6 +32,8 @@ declare module '@venizia/ardor-react' {
 }
 ```
 
+With `@venizia/ardor`, write `declare module '@venizia/ardor'` instead.
+
 ## License
 
 MIT - see [LICENSE.md](./LICENSE.md).

package/dist/contexts/application.d.ts

@@ -1,9 +1,13 @@
 import React from 'react';
 import type { Container } from '@venizia/ignis-inversion';
 import type { ILogger } from '@venizia/ignis-helpers/core';
+/** What `ApplicationContext` carries; both are `null` outside a provider. */
 export interface IApplicationContextValue {
+    /** The application's container. */
     container: Container | null;
+    /** The application's logger. */
     logger: ILogger | null;
 }
+/** Read through `useApplicationContext` and `useApplicationLogger`; the default value holds `null`s. */
 export declare const ApplicationContext: React.Context<IApplicationContextValue>;
 //# sourceMappingURL=application.d.ts.map

package/dist/contexts/application.js

@@ -1,4 +1,5 @@
 import React from 'react';
+/** Read through `useApplicationContext` and `useApplicationLogger`; the default value holds `null`s. */
 export const ApplicationContext = React.createContext({
     container: null,
     logger: null,

package/dist/hooks/element-target.d.ts

@@ -0,0 +1,9 @@
+import type React from 'react';
+/** An element, a ref to one, or `null` for none yet. */
+export type TElementTarget = React.RefObject<Element | null> | Element | null;
+export declare class ElementTargets {
+    static resolve(opts: {
+        target: TElementTarget;
+    }): Element | null;
+}
+//# sourceMappingURL=element-target.d.ts.map

package/dist/hooks/element-target.js

@@ -0,0 +1,7 @@
+export class ElementTargets {
+    static resolve(opts) {
+        const { target } = opts;
+        return target && 'current' in target ? target.current : target;
+    }
+}
+//# sourceMappingURL=element-target.js.map

package/dist/hooks/index.d.ts

@@ -1,3 +1,4 @@
+export type { TElementTarget } from './element-target.js';
 export * from './redux/index.js';
 export * from './use-application-context.js';
 export * from './use-artifact.js';
@@ -6,9 +7,13 @@ export * from './use-before-unload.js';
 export * from './use-confirm.js';
 export * from './use-copy-to-clipboard.js';
 export * from './use-debounce.js';
+export * from './use-document-visibility.js';
 export * from './use-element-size.js';
 export * from './use-injectable.js';
-export * from './use-sizer.js';
+export * from './use-intersection.js';
+export * from './use-media-query.js';
+export * from './use-online-status.js';
+export * from './use-resize-effect.js';
 export * from './use-stored-state.js';
 export * from './use-window-dimensions.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.js

@@ -6,9 +6,13 @@ export * from './use-before-unload.js';
 export * from './use-confirm.js';
 export * from './use-copy-to-clipboard.js';
 export * from './use-debounce.js';
+export * from './use-document-visibility.js';
 export * from './use-element-size.js';
 export * from './use-injectable.js';
-export * from './use-sizer.js';
+export * from './use-intersection.js';
+export * from './use-media-query.js';
+export * from './use-online-status.js';
+export * from './use-resize-effect.js';
 export * from './use-stored-state.js';
 export * from './use-window-dimensions.js';
 //# sourceMappingURL=index.js.map

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

@@ -1,6 +1,10 @@
 import type { Dispatch, UnknownAction } from '@reduxjs/toolkit';
+/** Builds the typed dispatch hooks of a store. */
 export declare class DispatchHooks {
-    /** The typed dispatch hooks of a store: bind your `AppDispatch` once, and export what comes back. */
+    /**
+     * The typed dispatch hooks of a store: bind your `AppDispatch` once, and export what comes back.
+     * `useMultipleAppDispatch` returns a function that dispatches each action in order and skips falsy ones.
+     */
     static create<TDispatch extends Dispatch<UnknownAction> = Dispatch<UnknownAction>>(): {
         useAppDispatch: import("react-redux").UseDispatch<TDispatch>;
         useMultipleAppDispatch: () => (...actions: Parameters<TDispatch>[0][]) => void;

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

@@ -1,7 +1,11 @@
 import React from 'react';
 import { useDispatch } from 'react-redux';
+/** Builds the typed dispatch hooks of a store. */
 export class DispatchHooks {
-    /** The typed dispatch hooks of a store: bind your `AppDispatch` once, and export what comes back. */
+    /**
+     * The typed dispatch hooks of a store: bind your `AppDispatch` once, and export what comes back.
+     * `useMultipleAppDispatch` returns a function that dispatches each action in order and skips falsy ones.
+     */
     static create() {
         const useAppDispatch = useDispatch.withTypes();
         const useMultipleAppDispatch = () => {

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

@@ -1,5 +1,30 @@
-import isEqual from 'lodash/isEqual.js';
 import { shallowEqual, useSelector } from 'react-redux';
+const isPlain = (value) => {
+    return (typeof value === 'object' &&
+        value !== null &&
+        (Array.isArray(value) || [Object.prototype, null].includes(Object.getPrototypeOf(value))));
+};
+/**
+ * Equality by value for what a selector returns: primitives, plain objects, arrays and dates, none
+ * of them cyclic; `0` equals `-0`, and `NaN` equals `NaN`. Any other object (a `Map`, a class
+ * instance) is equal only to itself.
+ */
+const deepEqual = (a, b) => {
+    if (a === b || Object.is(a, b)) {
+        return true;
+    }
+    if (a instanceof Date && b instanceof Date) {
+        return Object.is(a.getTime(), b.getTime());
+    }
+    if (!isPlain(a) || !isPlain(b) || Array.isArray(a) !== Array.isArray(b)) {
+        return false;
+    }
+    const keys = Object.keys(a);
+    return (keys.length === Object.keys(b).length &&
+        keys.every((key) => {
+            return Object.hasOwn(b, key) && deepEqual(Reflect.get(a, key), Reflect.get(b, key));
+        }));
+};
 export class SelectorHooks {
     /** The three typed selector hooks of a store: bind your `RootState` once, and export what comes back. */
     static create() {
@@ -8,7 +33,7 @@ export class SelectorHooks {
             return useAppSelector(selector, shallowEqual);
         };
         const useDeepEqualSelector = (selector) => {
-            return useAppSelector(selector, isEqual);
+            return useAppSelector(selector, deepEqual);
         };
         return {
             useAppSelector,

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

@@ -0,0 +1,19 @@
+/** The boxes `useElementSize` and `useResizeEffect` read. */
+export type TResizeBox = Exclude<ResizeObserverBoxOptions, 'device-pixel-content-box'>;
+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. */
+    onFrame: (entries: ResizeObserverEntry[]) => void;
+}
+export interface IResizeObservation {
+    /** Observes these elements and stops observing the ones no longer listed. */
+    sync: (targets: Element[]) => void;
+    stop: () => void;
+}
+export declare class ResizeObservation {
+    /** Does nothing without `ResizeObserver`. */
+    static observe(opts: IResizeObservationOptions): IResizeObservation;
+}
+//# sourceMappingURL=resize-observation.d.ts.map

package/dist/hooks/resize-observation.js

@@ -0,0 +1,67 @@
+export class ResizeObservation {
+    /** Does nothing without `ResizeObserver`. */
+    static observe(opts) {
+        const { box, children = false, onFrame } = opts;
+        if (typeof ResizeObserver === 'undefined') {
+            return { sync: () => { }, stop: () => { } };
+        }
+        const latest = new Map();
+        let watched = new Set();
+        let current = [];
+        let frame;
+        const observer = new ResizeObserver((entries) => {
+            for (const entry of entries) {
+                latest.set(entry.target, entry);
+            }
+            if (frame !== undefined) {
+                return;
+            }
+            frame = requestAnimationFrame(() => {
+                frame = undefined;
+                const batch = [...latest.values()];
+                latest.clear();
+                if (batch.length > 0) {
+                    onFrame(batch);
+                }
+            });
+        });
+        const update = (targets) => {
+            const wanted = new Set(children ? targets.flatMap((target) => [target, ...target.children]) : targets);
+            for (const element of watched) {
+                if (!wanted.has(element)) {
+                    observer.unobserve(element);
+                    latest.delete(element);
+                }
+            }
+            for (const element of wanted) {
+                if (!watched.has(element)) {
+                    observer.observe(element, { box });
+                }
+            }
+            watched = wanted;
+        };
+        const mutations = children ? new MutationObserver(() => update(current)) : undefined;
+        return {
+            sync: (targets) => {
+                if (targets.length === current.length &&
+                    targets.every((target, index) => target === current[index])) {
+                    return;
+                }
+                current = targets;
+                update(targets);
+                // A removed target stays registered on `mutations` until `stop`; its callback only updates the current targets.
+                for (const target of targets) {
+                    mutations?.observe(target, { childList: true });
+                }
+            },
+            stop: () => {
+                mutations?.disconnect();
+                observer.disconnect();
+                if (frame !== undefined) {
+                    cancelAnimationFrame(frame);
+                }
+            },
+        };
+    }
+}
+//# sourceMappingURL=resize-observation.js.map

package/dist/hooks/use-application-context.d.ts

@@ -1,3 +1,5 @@
+/** The application's `Container`. Throws when there is no `ApplicationContext` provider above. */
 export declare const useApplicationContext: () => import("@venizia/ignis-inversion").Container;
+/** The application's logger. Throws when there is no `ApplicationContext` provider above. */
 export declare const useApplicationLogger: () => import("@venizia/ignis-helpers/core").ILogger;
 //# sourceMappingURL=use-application-context.d.ts.map

package/dist/hooks/use-application-context.js

@@ -1,6 +1,7 @@
 import React from 'react';
 import { getError } from '@venizia/ignis-inversion';
 import { ApplicationContext } from '../contexts/application.js';
+/** The application's `Container`. Throws when there is no `ApplicationContext` provider above. */
 export const useApplicationContext = () => {
     const context = React.useContext(ApplicationContext);
     if (!context?.container) {
@@ -10,6 +11,7 @@ export const useApplicationContext = () => {
     }
     return context.container;
 };
+/** The application's logger. Throws when there is no `ApplicationContext` provider above. */
 export const useApplicationLogger = () => {
     const context = React.useContext(ApplicationContext);
     if (!context?.logger) {

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

@@ -2,19 +2,45 @@ import { type Container, type TClass } from '@venizia/ignis-inversion';
 import { type TUseInjectableKeys } from './use-injectable.js';
 /** By class: the return type is inferred from the target. */
 export interface IUseArtifactByTarget<TInstance> {
+    /** The container to resolve from. @default The application's container (`ApplicationContext`) */
     container?: Container;
+    /** The class to resolve; its recorded binding key is used. */
     target: TClass<TInstance>;
     key?: never;
 }
 /** By key: the caller supplies the type. */
 export interface IUseArtifactByKey {
+    /** The container to resolve from. @default The application's container (`ApplicationContext`) */
     container?: Container;
+    /** The binding key to resolve. */
     key: TUseInjectableKeys;
     target?: never;
 }
+/** Resolves the instance bound under the `service` namespace by `target` or `key`. A `target` bound under another namespace throws. */
 export declare const useService: <TInstance = unknown>(opts: IUseArtifactByTarget<TInstance> | IUseArtifactByKey) => TInstance;
+/** Resolves the instance bound under the `provider` namespace by `target` or `key`. A `target` bound under another namespace throws. */
 export declare const useProvider: <TInstance = unknown>(opts: IUseArtifactByTarget<TInstance> | IUseArtifactByKey) => TInstance;
+/** Resolves the instance bound under the `component` namespace by `target` or `key`. A `target` bound under another namespace throws. */
 export declare const useComponent: <TInstance = unknown>(opts: IUseArtifactByTarget<TInstance> | IUseArtifactByKey) => TInstance;
+/** Resolves the instance bound under the `configuration` namespace by `target` or `key`. A `target` bound under another namespace throws. */
 export declare const useConfiguration: <TInstance = unknown>(opts: IUseArtifactByTarget<TInstance> | IUseArtifactByKey) => TInstance;
+/**
+ * Resolves the instance bound under the `repository` namespace by `target` or `key`. A `target` bound under another namespace throws.
+ *
+ * @example
+ * ```tsx
+ * import { repository, useRepository } from '@venizia/ardor';
+ *
+ * @repository()
+ * class ProductRepository {
+ *   findStock(productId: string) { return productId ? 42 : 0; }
+ * }
+ *
+ * export function StockDisplay() {
+ *   const productRepository = useRepository({ target: ProductRepository });
+ *   return <span>Stock: {productRepository.findStock('p1')}</span>;
+ * }
+ * ```
+ */
 export declare const useRepository: <TInstance = unknown>(opts: IUseArtifactByTarget<TInstance> | IUseArtifactByKey) => TInstance;
 //# sourceMappingURL=use-artifact.d.ts.map

package/dist/hooks/use-artifact.js

@@ -1,6 +1,6 @@
 import { BindingNamespaces } from '@venizia/ardor-kernel';
 import { getError } from '@venizia/ignis-inversion';
-import { useInjectable, useInjectableContainer, } from './use-injectable.js';
+import { useInjectable, useApplicationContainer, } from './use-injectable.js';
 /**
  * `useService`, `useRepository`, `useProvider`, `useComponent`, `useConfiguration`. Unlike
  * `useInjectable`, a `{ target }` must be bound under the hook's namespace, or it throws.
@@ -8,7 +8,7 @@ import { useInjectable, useInjectableContainer, } from './use-injectable.js';
 const useArtifactInNamespace = (opts) => {
     const { options, namespace, hook } = opts;
     // Same inputs as `useInjectable`, so the check and the resolve read one container.
-    const container = useInjectableContainer({ container: options.container });
+    const container = useApplicationContainer({ container: options.container });
     // A `key` carries its namespace in the string; only a `target` is checked.
     if (options.target) {
         const key = container.getMetadataRegistry().getBindingKey({ target: options.target });
@@ -22,26 +22,48 @@ const useArtifactInNamespace = (opts) => {
     }
     return useInjectable(options);
 };
+/** Resolves the instance bound under the `service` namespace by `target` or `key`. A `target` bound under another namespace throws. */
 export const useService = (opts) => useArtifactInNamespace({
     options: opts,
     namespace: BindingNamespaces.SERVICE,
     hook: 'useService',
 });
+/** Resolves the instance bound under the `provider` namespace by `target` or `key`. A `target` bound under another namespace throws. */
 export const useProvider = (opts) => useArtifactInNamespace({
     options: opts,
     namespace: BindingNamespaces.PROVIDER,
     hook: 'useProvider',
 });
+/** Resolves the instance bound under the `component` namespace by `target` or `key`. A `target` bound under another namespace throws. */
 export const useComponent = (opts) => useArtifactInNamespace({
     options: opts,
     namespace: BindingNamespaces.COMPONENT,
     hook: 'useComponent',
 });
+/** Resolves the instance bound under the `configuration` namespace by `target` or `key`. A `target` bound under another namespace throws. */
 export const useConfiguration = (opts) => useArtifactInNamespace({
     options: opts,
     namespace: BindingNamespaces.CONFIGURATION,
     hook: 'useConfiguration',
 });
+/**
+ * Resolves the instance bound under the `repository` namespace by `target` or `key`. A `target` bound under another namespace throws.
+ *
+ * @example
+ * ```tsx
+ * import { repository, useRepository } from '@venizia/ardor';
+ *
+ * @repository()
+ * class ProductRepository {
+ *   findStock(productId: string) { return productId ? 42 : 0; }
+ * }
+ *
+ * export function StockDisplay() {
+ *   const productRepository = useRepository({ target: ProductRepository });
+ *   return <span>Stock: {productRepository.findStock('p1')}</span>;
+ * }
+ * ```
+ */
 export const useRepository = (opts) => useArtifactInNamespace({
     options: opts,
     namespace: BindingNamespaces.REPOSITORY,

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

@@ -1,11 +1,18 @@
 export interface IUseAutosaveOptions<TData, TReturn> {
+    /** The value to save; a change starts the `interval` wait. */
     data: TData;
+    /** Called with the latest `data` once it has been still for `interval`. A rejection is logged, not thrown. */
     onSave: (data: TData) => Promise<TReturn> | TReturn | void;
     /** @default 2000 */
     interval?: number;
+    /** Save the latest `data` on unmount. */
     enableSaveOnUnmount?: boolean;
     /** @default true */
     enabled?: boolean;
 }
+/**
+ * Calls `onSave` with `data` after it has stopped changing for `interval` milliseconds. The first
+ * render does not save. The latest `onSave` is always the one called.
+ */
 export declare const useAutosave: <TData, TReturn>(opts: IUseAutosaveOptions<TData, TReturn>) => void;
 //# sourceMappingURL=use-autosave.d.ts.map

package/dist/hooks/use-autosave.js

@@ -2,6 +2,10 @@ import React from 'react';
 import { LoggerFactory } from '@venizia/ignis-helpers/core';
 import { useDebounce } from './use-debounce.js';
 const logger = LoggerFactory.getLogger(['useAutosave']);
+/**
+ * Calls `onSave` with `data` after it has stopped changing for `interval` milliseconds. The first
+ * render does not save. The latest `onSave` is always the one called.
+ */
 export const useAutosave = (opts) => {
     const { data, onSave, interval = 2000, enableSaveOnUnmount, enabled = true } = opts;
     const valueOnCleanup = React.useRef(data);

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

@@ -1,7 +1,9 @@
 export interface IUseBeforeUnloadOptions {
     /** @default true */
     enabled?: boolean;
+    /** Set as the `returnValue` of the event; browsers may show their own text instead. */
     message?: string;
 }
+/** While `enabled`, asks the browser to confirm before the page is left or reloaded. */
 export declare const useBeforeUnload: (opts: IUseBeforeUnloadOptions) => void;
 //# sourceMappingURL=use-before-unload.d.ts.map

package/dist/hooks/use-before-unload.js

@@ -1,4 +1,5 @@
 import React from 'react';
+/** While `enabled`, asks the browser to confirm before the page is left or reloaded. */
 export const useBeforeUnload = (opts) => {
     const { enabled = true, message } = opts;
     const handleBeforeUnload = React.useCallback((event) => {

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

@@ -1,11 +1,17 @@
 export interface IUseConfirmReturn {
+    /** The pending prompt text; `undefined` when none is open. */
     message?: string;
+    /** Opens a prompt. Resolves `true` on `handleConfirm`, `false` on `handleAbort` or when another `confirm` replaces it. */
     confirm: (opts: {
         message: string;
     }) => Promise<boolean>;
+    /** Closes the prompt without settling it. */
     handleClose: () => void;
+    /** Resolves the pending `confirm` with `true` and closes. */
     handleConfirm: () => void;
+    /** Resolves the pending `confirm` with `false` and closes. */
     handleAbort: () => void;
 }
+/** State for a confirmation prompt: `confirm` returns a promise that the prompt's buttons settle. */
 export declare const useConfirm: () => IUseConfirmReturn;
 //# sourceMappingURL=use-confirm.d.ts.map

package/dist/hooks/use-confirm.js

@@ -1,4 +1,5 @@
 import React from 'react';
+/** State for a confirmation prompt: `confirm` returns a promise that the prompt's buttons settle. */
 export const useConfirm = () => {
     const settle = React.useRef(undefined);
     const [message, setMessage] = React.useState();

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

@@ -1,7 +1,27 @@
+export interface IUseCopyToClipboardOptions {
+    /** Set `isCopied` back to `false` this many milliseconds after a copy; 0 or less never resets. @default 0 */
+    resetMs?: number;
+}
 export interface IUseCopyToClipboardReturn {
+    /** Resolves `true` when the text is on the clipboard and `false` otherwise, and never throws. */
     copy: (opts: {
         value: string;
     }) => Promise<boolean>;
+    /** The result of the last copy, until `resetMs` has passed. */
+    isCopied: boolean;
 }
-export declare const useCopyToClipboard: () => IUseCopyToClipboardReturn;
+/**
+ * Copies text with `BrowserClipboard`; `isCopied` is the result of the last copy.
+ *
+ * @example
+ * ```tsx
+ * import { useCopyToClipboard } from '@venizia/ardor';
+ *
+ * export function CopyButton() {
+ *   const { copy, isCopied } = useCopyToClipboard({ resetMs: 2000 });
+ *   return <button onClick={() => copy({ value: 'hello' })}>{isCopied ? 'Copied' : 'Copy'}</button>;
+ * }
+ * ```
+ */
+export declare const useCopyToClipboard: (opts?: IUseCopyToClipboardOptions) => IUseCopyToClipboardReturn;
 //# sourceMappingURL=use-copy-to-clipboard.d.ts.map

package/dist/hooks/use-copy-to-clipboard.js

@@ -1,21 +1,45 @@
+import React from 'react';
 import { LoggerFactory } from '@venizia/ignis-helpers/core';
+import { BrowserClipboard } from '@venizia/ardor-kernel';
 const logger = LoggerFactory.getLogger(['useCopyToClipboard']);
-// A hook is never handed an async function, so the copy lives outside it; it holds no state, which is
-// why the hook returns the same function on every render, as `useCallback(..., [])` did.
+// A hook is never handed an async function, so the copy lives outside it.
 const copyToClipboard = async (opts) => {
-    if (!navigator?.clipboard) {
-        logger.warn('[copy] The clipboard is not supported');
-        return false;
-    }
-    const { value } = opts;
-    try {
-        await navigator.clipboard.writeText(value);
-        return true;
-    }
-    catch (error) {
-        logger.warn('[copy] Copy failed | error: %s', error);
-        return false;
+    const isCopied = await BrowserClipboard.writeText({ text: opts.value });
+    if (!isCopied) {
+        logger.warn('[copy] The clipboard did not take the text');
     }
+    return isCopied;
+};
+/**
+ * Copies text with `BrowserClipboard`; `isCopied` is the result of the last copy.
+ *
+ * @example
+ * ```tsx
+ * import { useCopyToClipboard } from '@venizia/ardor';
+ *
+ * export function CopyButton() {
+ *   const { copy, isCopied } = useCopyToClipboard({ resetMs: 2000 });
+ *   return <button onClick={() => copy({ value: 'hello' })}>{isCopied ? 'Copied' : 'Copy'}</button>;
+ * }
+ * ```
+ */
+export const useCopyToClipboard = (opts = {}) => {
+    const { resetMs = 0 } = opts;
+    const [isCopied, setCopied] = React.useState(false);
+    const timerRef = React.useRef(undefined);
+    React.useEffect(() => {
+        return () => clearTimeout(timerRef.current);
+    }, []);
+    const copy = React.useCallback((copyOpts) => {
+        return copyToClipboard(copyOpts).then((isDone) => {
+            clearTimeout(timerRef.current);
+            setCopied(isDone);
+            if (isDone && resetMs > 0) {
+                timerRef.current = setTimeout(() => setCopied(false), resetMs);
+            }
+            return isDone;
+        });
+    }, [resetMs]);
+    return { copy, isCopied };
 };
-export const useCopyToClipboard = () => ({ copy: copyToClipboard });
 //# sourceMappingURL=use-copy-to-clipboard.js.map

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

@@ -1,11 +1,15 @@
 export interface IUseDebounceOptions<TValue> {
+    /** The value to follow; the output changes once it has been still for `delay`. */
     value: TValue;
+    /** Milliseconds to wait after the last change. @default 500 */
     delay?: number;
     /** @default true */
     enabled?: boolean;
 }
 export interface IUseDebounceReturn<TValue> {
+    /** The last `value` that stayed unchanged for `delay`; the first `value` until then. */
     debouncedValue: TValue;
 }
+/** Follows `value` after it has stopped changing for `delay`. Outside a browser, or when not `enabled`, it never updates. */
 export declare const useDebounce: <TValue>(opts: IUseDebounceOptions<TValue>) => IUseDebounceReturn<TValue>;
 //# sourceMappingURL=use-debounce.d.ts.map

package/dist/hooks/use-debounce.js

@@ -1,5 +1,6 @@
 import React from 'react';
 import { App, BrowserUtility } from '@venizia/ardor-kernel';
+/** Follows `value` after it has stopped changing for `delay`. Outside a browser, or when not `enabled`, it never updates. */
 export const useDebounce = (opts) => {
     const { value, delay, enabled = true } = opts;
     const [debouncedValue, setDebouncedValue] = React.useState(value);

package/dist/hooks/use-document-visibility.d.ts

@@ -0,0 +1,3 @@
+/** `'visible'` or `'hidden'`, as the document says. `'visible'` in a server render. */
+export declare const useDocumentVisibility: () => DocumentVisibilityState;
+//# sourceMappingURL=use-document-visibility.d.ts.map

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,9 +1,10 @@
 import React from 'react';
+import { type TResizeBox } from './resize-observation.js';
 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;
 }
@@ -14,6 +15,7 @@ export interface IUseElementSizeReturn {
     measured: boolean;
 }
 export interface IUseElementSizeRefReturn extends IUseElementSizeReturn {
+    /** Give it to the element to measure. */
     ref: React.RefCallback<Element>;
 }
 /**
@@ -23,6 +25,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>;