shelving 1.236.0 → 1.236.2

package/ui/util/notice.d.ts

@@ -2,25 +2,113 @@ import type { ReactNode } from "react";
 import type { Arguments } from "../../util/function.js";
 import type { Status } from "../style/Status.js";
 /**
- * Notify the user with a message by dispatching a notice event.
+ * Notify the user with a message by dispatching a `notice` event.
+ *
  * - This is how e.g. `<Button>` and `<FormNotify>` components send notices to the `<Notices>` list of global notices.
+ * - The event bubbles, so any ancestor subscribed with `subscribeNotices()` will receive it.
+ *
+ * @param message The message to show, as a React node.
+ * @param status Optional status (`"success"`, `"error"`, etc.) controlling how the notice is styled.
+ * @param el Element to dispatch the event on (defaults to `window`).
+ * @example notify("Saved your changes", "success");
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/notify
  */
 export declare function notify(message: ReactNode, status?: Status | undefined, el?: EventTarget): void;
-/** Notify the user with a success message by dispatching a notice event. */
+/**
+ * Notify the user with a success message by dispatching a `notice` event with `"success"` status.
+ *
+ * @param message The success message to show, as a React node.
+ * @param el Element to dispatch the event on (defaults to `window`).
+ * @example notifySuccess("Profile updated");
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/notifySuccess
+ */
 export declare function notifySuccess(message: ReactNode, el?: EventTarget): void;
-/** Notify the user with a success message by dispatching a notice event. */
+/**
+ * Notify the user with an error message by dispatching a `notice` event with `"error"` status.
+ *
+ * @param message The error message to show, as a React node.
+ * @param el Element to dispatch the event on (defaults to `window`).
+ * @example notifyError("Could not save your changes");
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/notifyError
+ */
 export declare function notifyError(message: ReactNode, el?: EventTarget): void;
-/** Look at a thrown value, extract a viable message from it, and dispatch a notice event.. */
+/**
+ * Look at a thrown value, extract a viable message from it, and dispatch an error notice.
+ *
+ * - Uses `getMessage()` to pull a human-readable string from the thrown value.
+ * - Falls back to a generic `"Unknown error"` notice and `console.error()` when no message can be extracted.
+ *
+ * @param thrown The thrown value to report.
+ * @param el Element to dispatch the event on (defaults to `window`).
+ * @example try { await save(); } catch (thrown) { notifyThrown(thrown); }
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/notifyThrown
+ */
 export declare function notifyThrown(thrown: unknown, el?: EventTarget): void;
-/** Subscribe to notice events on the window and call a callback when they happen. */
+/**
+ * Subscribe to `notice` events on an element and call a callback when they happen.
+ *
+ * - Stops propagation so the notice is not handled again by a higher subscriber.
+ *
+ * @param callback Called with the message and status each time a notice event fires.
+ * @param el Element to subscribe on (defaults to `window`).
+ * @returns An unsubscribe function that removes the listener.
+ * @example const stop = subscribeNotices((message, status) => show(message, status));
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/subscribeNotices
+ */
 export declare function subscribeNotices(callback: (message: ReactNode, status?: Status | undefined) => void, el?: EventTarget): () => void;
-/** Callback that can return or throw a string, which will trigger a success or error notice accordingly. */
+/**
+ * Callback that can return or throw a value, triggering a success or error notice accordingly.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/NoticeCallback
+ */
 export type NoticeCallback<A extends Arguments> = (...args: A) => PromiseLike<ReactNode | undefined | void> | ReactNode | undefined | void;
-/** Callback that publishes notices to the window if it returns or throws "string" */
+/**
+ * Run a callback and dispatch a success or error notice to the window based on its return or throw.
+ *
+ * - A returned truthy value becomes a `"success"` notice; a thrown value becomes an `"error"` notice via `notifyThrown()`.
+ * - Resolves asynchronously when the callback returns a promise.
+ *
+ * @param callback The callback to run, whose return/throw drives the notice.
+ * @param args Arguments forwarded to the callback.
+ * @returns `true` if the callback succeeded, `false` if it threw (a `Promise` of the same when async).
+ * @example callNotified(() => save()); // notifies "success" or "error"
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/callNotified
+ */
 export declare function callNotified<A extends Arguments>(callback: NoticeCallback<A>, ...args: A): boolean | Promise<boolean>;
-/** Await a value that publishes "success" or "error" notices to the window if it returns */
+/**
+ * Await a pending value and dispatch a success or error notice to the window based on its resolution.
+ *
+ * - A resolved truthy value becomes a `"success"` notice; a rejection becomes an `"error"` notice via `notifyThrown()`.
+ *
+ * @param pending The promise-like value to await.
+ * @returns `true` if the value resolved, `false` if it rejected.
+ * @example await awaitNotified(save());
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/awaitNotified
+ */
 export declare function awaitNotified(pending: PromiseLike<ReactNode | undefined | void>): Promise<boolean>;
-/** Callback that publishes notices to an element (defaults to the window) if it returns or throws "string" */
+/**
+ * Run a callback and dispatch a success or error notice to a specific element based on its return or throw.
+ *
+ * - A returned truthy value becomes a `"success"` notice; a thrown value becomes an `"error"` notice via `notifyThrown()`.
+ * - Resolves asynchronously when the callback returns a promise.
+ *
+ * @param el Element to dispatch the notice event on (defaults to `window` when `undefined`).
+ * @param callback The callback to run, whose return/throw drives the notice.
+ * @param args Arguments forwarded to the callback.
+ * @returns `true` if the callback succeeded, `false` if it threw (a `Promise` of the same when async).
+ * @example callNotifiedElement(formEl, () => save());
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/callNotifiedElement
+ */
 export declare function callNotifiedElement<A extends Arguments>(el: EventTarget | undefined, callback: NoticeCallback<A>, ...args: A): boolean | Promise<boolean>;
-/** Await a value that publishes "success" or "error" notices to an element (defaults to the window) if it returns */
+/**
+ * Await a pending value and dispatch a success or error notice to a specific element based on its resolution.
+ *
+ * - A resolved truthy value becomes a `"success"` notice; a rejection becomes an `"error"` notice via `notifyThrown()`.
+ *
+ * @param el Element to dispatch the notice event on (defaults to `window` when `undefined`).
+ * @param pending The promise-like value to await.
+ * @returns `true` if the value resolved, `false` if it rejected.
+ * @example await awaitNotifiedElement(formEl, save());
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/awaitNotifiedElement
+ */
 export declare function awaitNotifiedElement(el: EventTarget | undefined, pending: PromiseLike<ReactNode | undefined | void>): Promise<boolean>;

package/ui/util/notice.js

@@ -6,8 +6,16 @@ const NOTICE_EVENT = "notice";
 class NoticeEvent extends CustomEvent {
 }
 /**
- * Notify the user with a message by dispatching a notice event.
+ * Notify the user with a message by dispatching a `notice` event.
+ *
  * - This is how e.g. `<Button>` and `<FormNotify>` components send notices to the `<Notices>` list of global notices.
+ * - The event bubbles, so any ancestor subscribed with `subscribeNotices()` will receive it.
+ *
+ * @param message The message to show, as a React node.
+ * @param status Optional status (`"success"`, `"error"`, etc.) controlling how the notice is styled.
+ * @param el Element to dispatch the event on (defaults to `window`).
+ * @example notify("Saved your changes", "success");
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/notify
  */
 export function notify(message, status, el = window) {
     el.dispatchEvent(new NoticeEvent(NOTICE_EVENT, {
@@ -15,15 +23,39 @@ export function notify(message, status, el = window) {
         bubbles: true,
     }));
 }
-/** Notify the user with a success message by dispatching a notice event. */
+/**
+ * Notify the user with a success message by dispatching a `notice` event with `"success"` status.
+ *
+ * @param message The success message to show, as a React node.
+ * @param el Element to dispatch the event on (defaults to `window`).
+ * @example notifySuccess("Profile updated");
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/notifySuccess
+ */
 export function notifySuccess(message, el) {
     notify(message, "success", el);
 }
-/** Notify the user with a success message by dispatching a notice event. */
+/**
+ * Notify the user with an error message by dispatching a `notice` event with `"error"` status.
+ *
+ * @param message The error message to show, as a React node.
+ * @param el Element to dispatch the event on (defaults to `window`).
+ * @example notifyError("Could not save your changes");
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/notifyError
+ */
 export function notifyError(message, el) {
     notify(message, "error", el);
 }
-/** Look at a thrown value, extract a viable message from it, and dispatch a notice event.. */
+/**
+ * Look at a thrown value, extract a viable message from it, and dispatch an error notice.
+ *
+ * - Uses `getMessage()` to pull a human-readable string from the thrown value.
+ * - Falls back to a generic `"Unknown error"` notice and `console.error()` when no message can be extracted.
+ *
+ * @param thrown The thrown value to report.
+ * @param el Element to dispatch the event on (defaults to `window`).
+ * @example try { await save(); } catch (thrown) { notifyThrown(thrown); }
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/notifyThrown
+ */
 export function notifyThrown(thrown, el) {
     const message = getMessage(thrown);
     if (message) {
@@ -34,7 +66,17 @@ export function notifyThrown(thrown, el) {
         console.error(thrown);
     }
 }
-/** Subscribe to notice events on the window and call a callback when they happen. */
+/**
+ * Subscribe to `notice` events on an element and call a callback when they happen.
+ *
+ * - Stops propagation so the notice is not handled again by a higher subscriber.
+ *
+ * @param callback Called with the message and status each time a notice event fires.
+ * @param el Element to subscribe on (defaults to `window`).
+ * @returns An unsubscribe function that removes the listener.
+ * @example const stop = subscribeNotices((message, status) => show(message, status));
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/subscribeNotices
+ */
 export function subscribeNotices(callback, el = window) {
     const listener = (e) => {
         e.stopPropagation(); // Prevent bubbling to a higher notice subscriber.
@@ -44,15 +86,47 @@ export function subscribeNotices(callback, el = window) {
     el.addEventListener(NOTICE_EVENT, listener);
     return () => el.removeEventListener(NOTICE_EVENT, listener);
 }
-/** Callback that publishes notices to the window if it returns or throws "string" */
+/**
+ * Run a callback and dispatch a success or error notice to the window based on its return or throw.
+ *
+ * - A returned truthy value becomes a `"success"` notice; a thrown value becomes an `"error"` notice via `notifyThrown()`.
+ * - Resolves asynchronously when the callback returns a promise.
+ *
+ * @param callback The callback to run, whose return/throw drives the notice.
+ * @param args Arguments forwarded to the callback.
+ * @returns `true` if the callback succeeded, `false` if it threw (a `Promise` of the same when async).
+ * @example callNotified(() => save()); // notifies "success" or "error"
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/callNotified
+ */
 export function callNotified(callback, ...args) {
     return callNotifiedElement(window, callback, ...args);
 }
-/** Await a value that publishes "success" or "error" notices to the window if it returns */
+/**
+ * Await a pending value and dispatch a success or error notice to the window based on its resolution.
+ *
+ * - A resolved truthy value becomes a `"success"` notice; a rejection becomes an `"error"` notice via `notifyThrown()`.
+ *
+ * @param pending The promise-like value to await.
+ * @returns `true` if the value resolved, `false` if it rejected.
+ * @example await awaitNotified(save());
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/awaitNotified
+ */
 export function awaitNotified(pending) {
     return awaitNotifiedElement(window, pending);
 }
-/** Callback that publishes notices to an element (defaults to the window) if it returns or throws "string" */
+/**
+ * Run a callback and dispatch a success or error notice to a specific element based on its return or throw.
+ *
+ * - A returned truthy value becomes a `"success"` notice; a thrown value becomes an `"error"` notice via `notifyThrown()`.
+ * - Resolves asynchronously when the callback returns a promise.
+ *
+ * @param el Element to dispatch the notice event on (defaults to `window` when `undefined`).
+ * @param callback The callback to run, whose return/throw drives the notice.
+ * @param args Arguments forwarded to the callback.
+ * @returns `true` if the callback succeeded, `false` if it threw (a `Promise` of the same when async).
+ * @example callNotifiedElement(formEl, () => save());
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/callNotifiedElement
+ */
 export function callNotifiedElement(el, callback, ...args) {
     try {
         const result = callback(...args);
@@ -67,7 +141,17 @@ export function callNotifiedElement(el, callback, ...args) {
         return false;
     }
 }
-/** Await a value that publishes "success" or "error" notices to an element (defaults to the window) if it returns */
+/**
+ * Await a pending value and dispatch a success or error notice to a specific element based on its resolution.
+ *
+ * - A resolved truthy value becomes a `"success"` notice; a rejection becomes an `"error"` notice via `notifyThrown()`.
+ *
+ * @param el Element to dispatch the notice event on (defaults to `window` when `undefined`).
+ * @param pending The promise-like value to await.
+ * @returns `true` if the value resolved, `false` if it rejected.
+ * @example await awaitNotifiedElement(formEl, save());
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/awaitNotifiedElement
+ */
 export async function awaitNotifiedElement(el, pending) {
     try {
         const result = await pending;

package/ui/util/notice.ts

@@ -11,8 +11,16 @@ const NOTICE_EVENT = "notice";
 class NoticeEvent extends CustomEvent<{ message: ReactNode; status: Status | undefined }> {}
 
 /**
- * Notify the user with a message by dispatching a notice event.
+ * Notify the user with a message by dispatching a `notice` event.
+ *
  * - This is how e.g. `<Button>` and `<FormNotify>` components send notices to the `<Notices>` list of global notices.
+ * - The event bubbles, so any ancestor subscribed with `subscribeNotices()` will receive it.
+ *
+ * @param message The message to show, as a React node.
+ * @param status Optional status (`"success"`, `"error"`, etc.) controlling how the notice is styled.
+ * @param el Element to dispatch the event on (defaults to `window`).
+ * @example notify("Saved your changes", "success");
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/notify
  */
 export function notify(message: ReactNode, status?: Status | undefined, el: EventTarget = window): void {
 	el.dispatchEvent(
@@ -23,17 +31,41 @@ export function notify(message: ReactNode, status?: Status | undefined, el: Even
 	);
 }
 
-/** Notify the user with a success message by dispatching a notice event. */
+/**
+ * Notify the user with a success message by dispatching a `notice` event with `"success"` status.
+ *
+ * @param message The success message to show, as a React node.
+ * @param el Element to dispatch the event on (defaults to `window`).
+ * @example notifySuccess("Profile updated");
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/notifySuccess
+ */
 export function notifySuccess(message: ReactNode, el?: EventTarget) {
 	notify(message, "success", el);
 }
 
-/** Notify the user with a success message by dispatching a notice event. */
+/**
+ * Notify the user with an error message by dispatching a `notice` event with `"error"` status.
+ *
+ * @param message The error message to show, as a React node.
+ * @param el Element to dispatch the event on (defaults to `window`).
+ * @example notifyError("Could not save your changes");
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/notifyError
+ */
 export function notifyError(message: ReactNode, el?: EventTarget) {
 	notify(message, "error", el);
 }
 
-/** Look at a thrown value, extract a viable message from it, and dispatch a notice event.. */
+/**
+ * Look at a thrown value, extract a viable message from it, and dispatch an error notice.
+ *
+ * - Uses `getMessage()` to pull a human-readable string from the thrown value.
+ * - Falls back to a generic `"Unknown error"` notice and `console.error()` when no message can be extracted.
+ *
+ * @param thrown The thrown value to report.
+ * @param el Element to dispatch the event on (defaults to `window`).
+ * @example try { await save(); } catch (thrown) { notifyThrown(thrown); }
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/notifyThrown
+ */
 export function notifyThrown(thrown: unknown, el?: EventTarget) {
 	const message = getMessage(thrown);
 	if (message) {
@@ -44,7 +76,17 @@ export function notifyThrown(thrown: unknown, el?: EventTarget) {
 	}
 }
 
-/** Subscribe to notice events on the window and call a callback when they happen. */
+/**
+ * Subscribe to `notice` events on an element and call a callback when they happen.
+ *
+ * - Stops propagation so the notice is not handled again by a higher subscriber.
+ *
+ * @param callback Called with the message and status each time a notice event fires.
+ * @param el Element to subscribe on (defaults to `window`).
+ * @returns An unsubscribe function that removes the listener.
+ * @example const stop = subscribeNotices((message, status) => show(message, status));
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/subscribeNotices
+ */
 export function subscribeNotices(
 	callback: (message: ReactNode, status?: Status | undefined) => void,
 	el: EventTarget = window,
@@ -57,20 +99,56 @@ export function subscribeNotices(
 	return () => el.removeEventListener(NOTICE_EVENT, listener);
 }
 
-/** Callback that can return or throw a string, which will trigger a success or error notice accordingly. */
+/**
+ * Callback that can return or throw a value, triggering a success or error notice accordingly.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/NoticeCallback
+ */
 export type NoticeCallback<A extends Arguments> = (...args: A) => PromiseLike<ReactNode | undefined | void> | ReactNode | undefined | void;
 
-/** Callback that publishes notices to the window if it returns or throws "string" */
+/**
+ * Run a callback and dispatch a success or error notice to the window based on its return or throw.
+ *
+ * - A returned truthy value becomes a `"success"` notice; a thrown value becomes an `"error"` notice via `notifyThrown()`.
+ * - Resolves asynchronously when the callback returns a promise.
+ *
+ * @param callback The callback to run, whose return/throw drives the notice.
+ * @param args Arguments forwarded to the callback.
+ * @returns `true` if the callback succeeded, `false` if it threw (a `Promise` of the same when async).
+ * @example callNotified(() => save()); // notifies "success" or "error"
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/callNotified
+ */
 export function callNotified<A extends Arguments>(callback: NoticeCallback<A>, ...args: A): boolean | Promise<boolean> {
 	return callNotifiedElement(window, callback, ...args);
 }
 
-/** Await a value that publishes "success" or "error" notices to the window if it returns */
+/**
+ * Await a pending value and dispatch a success or error notice to the window based on its resolution.
+ *
+ * - A resolved truthy value becomes a `"success"` notice; a rejection becomes an `"error"` notice via `notifyThrown()`.
+ *
+ * @param pending The promise-like value to await.
+ * @returns `true` if the value resolved, `false` if it rejected.
+ * @example await awaitNotified(save());
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/awaitNotified
+ */
 export function awaitNotified(pending: PromiseLike<ReactNode | undefined | void>): Promise<boolean> {
 	return awaitNotifiedElement(window, pending);
 }
 
-/** Callback that publishes notices to an element (defaults to the window) if it returns or throws "string" */
+/**
+ * Run a callback and dispatch a success or error notice to a specific element based on its return or throw.
+ *
+ * - A returned truthy value becomes a `"success"` notice; a thrown value becomes an `"error"` notice via `notifyThrown()`.
+ * - Resolves asynchronously when the callback returns a promise.
+ *
+ * @param el Element to dispatch the notice event on (defaults to `window` when `undefined`).
+ * @param callback The callback to run, whose return/throw drives the notice.
+ * @param args Arguments forwarded to the callback.
+ * @returns `true` if the callback succeeded, `false` if it threw (a `Promise` of the same when async).
+ * @example callNotifiedElement(formEl, () => save());
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/callNotifiedElement
+ */
 export function callNotifiedElement<A extends Arguments>(
 	el: EventTarget | undefined,
 	callback: NoticeCallback<A>,
@@ -87,7 +165,17 @@ export function callNotifiedElement<A extends Arguments>(
 	}
 }
 
-/** Await a value that publishes "success" or "error" notices to an element (defaults to the window) if it returns */
+/**
+ * Await a pending value and dispatch a success or error notice to a specific element based on its resolution.
+ *
+ * - A resolved truthy value becomes a `"success"` notice; a rejection becomes an `"error"` notice via `notifyThrown()`.
+ *
+ * @param el Element to dispatch the notice event on (defaults to `window` when `undefined`).
+ * @param pending The promise-like value to await.
+ * @returns `true` if the value resolved, `false` if it rejected.
+ * @example await awaitNotifiedElement(formEl, save());
+ * @see https://dhoulb.github.io/shelving/ui/util/notice/awaitNotifiedElement
+ */
 export async function awaitNotifiedElement(
 	el: EventTarget | undefined,
 	pending: PromiseLike<ReactNode | undefined | void>,

package/ui/util/props.d.ts

@@ -1,9 +1,17 @@
 import type { ReactNode } from "react";
-/** Props for a component that requires `children`. */
+/**
+ * Props for a component that requires `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/util/props/ChildProps
+ */
 export interface ChildProps {
     readonly children: ReactNode;
 }
-/** Props for a component that optionally accepts `children`. */
+/**
+ * Props for a component that optionally accepts `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/util/props/OptionalChildProps
+ */
 export interface OptionalChildProps {
     readonly children?: ReactNode | undefined;
 }

package/ui/util/props.ts

@@ -1,11 +1,19 @@
 import type { ReactNode } from "react";
 
-/** Props for a component that requires `children`. */
+/**
+ * Props for a component that requires `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/util/props/ChildProps
+ */
 export interface ChildProps {
 	readonly children: ReactNode;
 }
 
-/** Props for a component that optionally accepts `children`. */
+/**
+ * Props for a component that optionally accepts `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/util/props/OptionalChildProps
+ */
 export interface OptionalChildProps {
 	readonly children?: ReactNode | undefined;
 }

package/ui/util/refresh.d.ts

@@ -1,2 +1,11 @@
-/** Refresh a component automatically every X milliseconds. */
+/**
+ * Re-render a component automatically on a fixed interval.
+ *
+ * - Holds the current time in state and updates it every `interval` milliseconds, forcing a refresh.
+ * - Clears the timer on unmount or when `interval` changes.
+ *
+ * @param interval The refresh period in milliseconds.
+ * @example useRefresh(1000); // re-renders once per second, e.g. for a live clock
+ * @see https://dhoulb.github.io/shelving/ui/util/refresh/useRefresh
+ */
 export declare function useRefresh(interval: number): void;

package/ui/util/refresh.js

@@ -1,5 +1,14 @@
 import { useEffect, useState } from "react";
-/** Refresh a component automatically every X milliseconds. */
+/**
+ * Re-render a component automatically on a fixed interval.
+ *
+ * - Holds the current time in state and updates it every `interval` milliseconds, forcing a refresh.
+ * - Clears the timer on unmount or when `interval` changes.
+ *
+ * @param interval The refresh period in milliseconds.
+ * @example useRefresh(1000); // re-renders once per second, e.g. for a live clock
+ * @see https://dhoulb.github.io/shelving/ui/util/refresh/useRefresh
+ */
 export function useRefresh(interval) {
     const [_currentTime, setCurrentTime] = useState(() => Date.now());
     useEffect(() => {

package/ui/util/refresh.ts

@@ -1,6 +1,15 @@
 import { useEffect, useState } from "react";
 
-/** Refresh a component automatically every X milliseconds. */
+/**
+ * Re-render a component automatically on a fixed interval.
+ *
+ * - Holds the current time in state and updates it every `interval` milliseconds, forcing a refresh.
+ * - Clears the timer on unmount or when `interval` changes.
+ *
+ * @param interval The refresh period in milliseconds.
+ * @example useRefresh(1000); // re-renders once per second, e.g. for a live clock
+ * @see https://dhoulb.github.io/shelving/ui/util/refresh/useRefresh
+ */
 export function useRefresh(interval: number): void {
 	const [_currentTime, setCurrentTime] = useState<number>(() => Date.now());
 

package/ui/util/scroll.d.ts

@@ -2,10 +2,26 @@ import { type RefObject } from "react";
 import type { Callback } from "../../util/function.js";
 import type { Nullish } from "../../util/null.js";
 /**
- * Fires a callback when an element enters the visible scrolling area on the client.
- * - Checks that is the last element in its parent.
- * - Finds the closest parent above this that scrolls (e.g. `.page`, customisable with `selector` param), then fires the callbacks appropriately.
+ * Fire callbacks when a referenced element enters or leaves the visible scrolling area.
+ *
+ * - Returns a `ref` to attach to the element you want to observe — typically the last item in a scrolling list, for infinite-scroll loading.
+ * - Uses an `IntersectionObserver` with a full-visibility threshold and disconnects it on unmount or when callbacks change.
+ *
+ * @param onEnter Called when the element becomes fully visible.
+ * @param onLeave Called when the element stops being fully visible.
+ * @returns A React `ref` to attach to the element to observe.
+ * @example const ref = useScrollIntersect(loadMore); return <div ref={ref} />;
+ * @see https://dhoulb.github.io/shelving/ui/util/scroll/useScrollIntersect
  */
 export declare function useScrollIntersect<T extends HTMLElement>(onEnter?: Nullish<Callback>, onLeave?: Nullish<Callback>): RefObject<T | null>;
-/** Go through a list of `IntersectionObserverEntry` (from `IntersectionObserver`) and return the index of the one with the highest `intersectionRatio` */
+/**
+ * Find the most-visible entry in a list of `IntersectionObserverEntry` objects.
+ *
+ * - Returns the entry with the highest `intersectionRatio`, or `undefined` for an empty list.
+ *
+ * @param entries The observer entries to compare (e.g. from an `IntersectionObserver` callback).
+ * @returns The entry with the largest visible ratio, or `undefined` when `entries` is empty.
+ * @example getMostVisibleObserverEntry(entries)?.target;
+ * @see https://dhoulb.github.io/shelving/ui/util/scroll/getMostVisibleObserverEntry
+ */
 export declare function getMostVisibleObserverEntry(entries: IntersectionObserverEntry[]): IntersectionObserverEntry | undefined;

package/ui/util/scroll.js

@@ -1,8 +1,15 @@
 import { useEffect, useRef } from "react";
 /**
- * Fires a callback when an element enters the visible scrolling area on the client.
- * - Checks that is the last element in its parent.
- * - Finds the closest parent above this that scrolls (e.g. `.page`, customisable with `selector` param), then fires the callbacks appropriately.
+ * Fire callbacks when a referenced element enters or leaves the visible scrolling area.
+ *
+ * - Returns a `ref` to attach to the element you want to observe — typically the last item in a scrolling list, for infinite-scroll loading.
+ * - Uses an `IntersectionObserver` with a full-visibility threshold and disconnects it on unmount or when callbacks change.
+ *
+ * @param onEnter Called when the element becomes fully visible.
+ * @param onLeave Called when the element stops being fully visible.
+ * @returns A React `ref` to attach to the element to observe.
+ * @example const ref = useScrollIntersect(loadMore); return <div ref={ref} />;
+ * @see https://dhoulb.github.io/shelving/ui/util/scroll/useScrollIntersect
  */
 export function useScrollIntersect(onEnter, onLeave) {
     const ref = useRef(null);
@@ -23,7 +30,16 @@ export function useScrollIntersect(onEnter, onLeave) {
     }, [onEnter, onLeave]);
     return ref;
 }
-/** Go through a list of `IntersectionObserverEntry` (from `IntersectionObserver`) and return the index of the one with the highest `intersectionRatio` */
+/**
+ * Find the most-visible entry in a list of `IntersectionObserverEntry` objects.
+ *
+ * - Returns the entry with the highest `intersectionRatio`, or `undefined` for an empty list.
+ *
+ * @param entries The observer entries to compare (e.g. from an `IntersectionObserver` callback).
+ * @returns The entry with the largest visible ratio, or `undefined` when `entries` is empty.
+ * @example getMostVisibleObserverEntry(entries)?.target;
+ * @see https://dhoulb.github.io/shelving/ui/util/scroll/getMostVisibleObserverEntry
+ */
 export function getMostVisibleObserverEntry(entries) {
     return entries.reduce(_reduceMostVisibleObserverEntry, undefined);
 }

package/ui/util/scroll.ts

@@ -3,9 +3,16 @@ import type { Callback } from "../../util/function.js";
 import type { Nullish } from "../../util/null.js";
 
 /**
- * Fires a callback when an element enters the visible scrolling area on the client.
- * - Checks that is the last element in its parent.
- * - Finds the closest parent above this that scrolls (e.g. `.page`, customisable with `selector` param), then fires the callbacks appropriately.
+ * Fire callbacks when a referenced element enters or leaves the visible scrolling area.
+ *
+ * - Returns a `ref` to attach to the element you want to observe — typically the last item in a scrolling list, for infinite-scroll loading.
+ * - Uses an `IntersectionObserver` with a full-visibility threshold and disconnects it on unmount or when callbacks change.
+ *
+ * @param onEnter Called when the element becomes fully visible.
+ * @param onLeave Called when the element stops being fully visible.
+ * @returns A React `ref` to attach to the element to observe.
+ * @example const ref = useScrollIntersect(loadMore); return <div ref={ref} />;
+ * @see https://dhoulb.github.io/shelving/ui/util/scroll/useScrollIntersect
  */
 export function useScrollIntersect<T extends HTMLElement>(onEnter?: Nullish<Callback>, onLeave?: Nullish<Callback>): RefObject<T | null> {
 	const ref = useRef<T | null>(null);
@@ -28,7 +35,16 @@ export function useScrollIntersect<T extends HTMLElement>(onEnter?: Nullish<Call
 	return ref;
 }
 
-/** Go through a list of `IntersectionObserverEntry` (from `IntersectionObserver`) and return the index of the one with the highest `intersectionRatio` */
+/**
+ * Find the most-visible entry in a list of `IntersectionObserverEntry` objects.
+ *
+ * - Returns the entry with the highest `intersectionRatio`, or `undefined` for an empty list.
+ *
+ * @param entries The observer entries to compare (e.g. from an `IntersectionObserver` callback).
+ * @returns The entry with the largest visible ratio, or `undefined` when `entries` is empty.
+ * @example getMostVisibleObserverEntry(entries)?.target;
+ * @see https://dhoulb.github.io/shelving/ui/util/scroll/getMostVisibleObserverEntry
+ */
 export function getMostVisibleObserverEntry(entries: IntersectionObserverEntry[]): IntersectionObserverEntry | undefined {
 	return entries.reduce<IntersectionObserverEntry | undefined>(_reduceMostVisibleObserverEntry, undefined);
 }