shelving 1.236.0 → 1.236.2

package/ui/util/state.d.ts

@@ -1,11 +1,25 @@
 /**
- * Set a state using a "debounce" delay — this ensures that the state is only updated after the specified delay has passed since the last update.
- * - Useful for input fields where you want to wait until the user has stopped typing before performing an action (e.g., API call).
+ * Hold a piece of state that only updates after a debounce delay since the last set.
+ *
+ * - The state changes only once `delay` milliseconds have elapsed with no further sets — useful for waiting until a user stops typing before reacting.
+ *
+ * @param initial The initial state value.
+ * @param delay The debounce delay in milliseconds (defaults to `500`).
+ * @returns A `[state, setState]` tuple, where `setState` defers the update by `delay`.
+ * @example const [query, setQuery] = useDebouncedState("");
+ * @see https://dhoulb.github.io/shelving/ui/util/state/useDebouncedState
  */
 export declare function useDebouncedState<T>(initial: T, delay?: number): [T, (v: T) => void];
 /**
- * Debounce a callback function — the callback will only be invoked after the specified delay has passed since the last call.
- * - Useful for triggering form submissions after the user has stopped typing.
- * - Automatically cleans up pending timeouts on unmount.
+ * Wrap a callback so it only runs after a debounce delay since the last invocation.
+ *
+ * - Each call resets the timer, so the callback fires once `delay` milliseconds have passed without another call — useful for auto-submitting a form after the user stops typing.
+ * - Pending timeouts are cleared automatically on unmount.
+ *
+ * @param callback The callback to debounce (may be `undefined` to no-op).
+ * @param delay The debounce delay in milliseconds (defaults to `500`).
+ * @returns A debounced function that schedules `callback` after `delay`.
+ * @example const submit = useDebouncedCallback(() => form.submit());
+ * @see https://dhoulb.github.io/shelving/ui/util/state/useDebouncedCallback
  */
 export declare function useDebouncedCallback(callback: (() => void) | undefined, delay?: number): () => void;

package/ui/util/state.js

@@ -1,7 +1,14 @@
 import { useEffect, useRef, useState } from "react";
 /**
- * Set a state using a "debounce" delay — this ensures that the state is only updated after the specified delay has passed since the last update.
- * - Useful for input fields where you want to wait until the user has stopped typing before performing an action (e.g., API call).
+ * Hold a piece of state that only updates after a debounce delay since the last set.
+ *
+ * - The state changes only once `delay` milliseconds have elapsed with no further sets — useful for waiting until a user stops typing before reacting.
+ *
+ * @param initial The initial state value.
+ * @param delay The debounce delay in milliseconds (defaults to `500`).
+ * @returns A `[state, setState]` tuple, where `setState` defers the update by `delay`.
+ * @example const [query, setQuery] = useDebouncedState("");
+ * @see https://dhoulb.github.io/shelving/ui/util/state/useDebouncedState
  */
 export function useDebouncedState(initial, delay = 500) {
     const [state, setState] = useState(initial);
@@ -16,9 +23,16 @@ export function useDebouncedState(initial, delay = 500) {
     return [state, _internal.setDebouncedState];
 }
 /**
- * Debounce a callback function — the callback will only be invoked after the specified delay has passed since the last call.
- * - Useful for triggering form submissions after the user has stopped typing.
- * - Automatically cleans up pending timeouts on unmount.
+ * Wrap a callback so it only runs after a debounce delay since the last invocation.
+ *
+ * - Each call resets the timer, so the callback fires once `delay` milliseconds have passed without another call — useful for auto-submitting a form after the user stops typing.
+ * - Pending timeouts are cleared automatically on unmount.
+ *
+ * @param callback The callback to debounce (may be `undefined` to no-op).
+ * @param delay The debounce delay in milliseconds (defaults to `500`).
+ * @returns A debounced function that schedules `callback` after `delay`.
+ * @example const submit = useDebouncedCallback(() => form.submit());
+ * @see https://dhoulb.github.io/shelving/ui/util/state/useDebouncedCallback
  */
 export function useDebouncedCallback(callback, delay = 500) {
     const timeoutRef = useRef(null);

package/ui/util/state.ts

@@ -1,8 +1,15 @@
 import { useEffect, useRef, useState } from "react";
 
 /**
- * Set a state using a "debounce" delay — this ensures that the state is only updated after the specified delay has passed since the last update.
- * - Useful for input fields where you want to wait until the user has stopped typing before performing an action (e.g., API call).
+ * Hold a piece of state that only updates after a debounce delay since the last set.
+ *
+ * - The state changes only once `delay` milliseconds have elapsed with no further sets — useful for waiting until a user stops typing before reacting.
+ *
+ * @param initial The initial state value.
+ * @param delay The debounce delay in milliseconds (defaults to `500`).
+ * @returns A `[state, setState]` tuple, where `setState` defers the update by `delay`.
+ * @example const [query, setQuery] = useDebouncedState("");
+ * @see https://dhoulb.github.io/shelving/ui/util/state/useDebouncedState
  */
 export function useDebouncedState<T>(initial: T, delay = 500): [T, (v: T) => void] {
 	const [state, setState] = useState(initial);
@@ -17,9 +24,16 @@ export function useDebouncedState<T>(initial: T, delay = 500): [T, (v: T) => voi
 }
 
 /**
- * Debounce a callback function — the callback will only be invoked after the specified delay has passed since the last call.
- * - Useful for triggering form submissions after the user has stopped typing.
- * - Automatically cleans up pending timeouts on unmount.
+ * Wrap a callback so it only runs after a debounce delay since the last invocation.
+ *
+ * - Each call resets the timer, so the callback fires once `delay` milliseconds have passed without another call — useful for auto-submitting a form after the user stops typing.
+ * - Pending timeouts are cleared automatically on unmount.
+ *
+ * @param callback The callback to debounce (may be `undefined` to no-op).
+ * @param delay The debounce delay in milliseconds (defaults to `500`).
+ * @returns A debounced function that schedules `callback` after `delay`.
+ * @example const submit = useDebouncedCallback(() => form.submit());
+ * @see https://dhoulb.github.io/shelving/ui/util/state/useDebouncedCallback
  */
 export function useDebouncedCallback(callback: (() => void) | undefined, delay = 500): () => void {
 	const timeoutRef = useRef<NodeJS.Timeout | null>(null);

package/util/ansi.d.ts

@@ -1,37 +1,155 @@
 import type { ImmutableArray } from "./array.js";
+/**
+ * ANSI escape code that resets the foreground colour to the terminal default.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_DEFAULT
+ */
 export declare const ANSI_DEFAULT: "\u001B[39m";
+/**
+ * ANSI escape code that sets the foreground colour to black.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_BLACK
+ */
 export declare const ANSI_BLACK: "\u001B[30m";
+/**
+ * ANSI escape code that sets the foreground colour to red.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_RED
+ */
 export declare const ANSI_RED: "\u001B[31m";
+/**
+ * ANSI escape code that sets the foreground colour to green.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_GREEN
+ */
 export declare const ANSI_GREEN: "\u001B[32m";
+/**
+ * ANSI escape code that sets the foreground colour to yellow.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_YELLOW
+ */
 export declare const ANSI_YELLOW: "\u001B[33m";
+/**
+ * ANSI escape code that sets the foreground colour to blue.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_BLUE
+ */
 export declare const ANSI_BLUE: "\u001B[34m";
+/**
+ * ANSI escape code that sets the foreground colour to magenta.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_MAGENTA
+ */
 export declare const ANSI_MAGENTA: "\u001B[35m";
+/**
+ * ANSI escape code that sets the foreground colour to cyan.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_CYAN
+ */
 export declare const ANSI_CYAN: "\u001B[36m";
+/**
+ * ANSI escape code that sets the foreground colour to white.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_WHITE
+ */
 export declare const ANSI_WHITE: "\u001B[37m";
+/**
+ * ANSI escape code that enables bold text.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_BOLD
+ */
 export declare const ANSI_BOLD: "\u001B[1m";
+/**
+ * ANSI escape code that enables italic text.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_ITALIC
+ */
 export declare const ANSI_ITALIC: "\u001B[3m";
+/**
+ * ANSI escape code that enables underlined text.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_UNDERLINE
+ */
 export declare const ANSI_UNDERLINE: "\u001B[4m";
+/**
+ * ANSI escape code that enables strikethrough text.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_STRIKE
+ */
 export declare const ANSI_STRIKE: "\u001B[9m";
+/**
+ * ANSI escape code that enables inverse (swapped foreground/background) text.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_INVERSE
+ */
 export declare const ANSI_INVERSE: "\u001B[7m";
+/**
+ * ANSI escape code that resets all colour and style attributes.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_RESET
+ */
 export declare const ANSI_RESET = "\u001B[0m";
 /**
  * Wrap a string in the ANSI color/style codes (at the start), and `ANSI_RESET` at the end.
  *
  * - The `NO_COLOR` environment variable is read live on every call, so runtimes that populate `process.env` late (e.g. Cloudflare Workers, where `[vars]` bindings are only reliably available within the request scope) are honoured rather than baking in whatever `NO_COLOR` was at module-load time.
+ *
+ * @param input The string to wrap in ANSI codes.
+ * @param wrappers Any number of ANSI escape codes (e.g. `ANSI_RED`, `ANSI_BOLD`) to prepend before `input`.
+ * @returns The wrapped string, or `input` unchanged when the `NO_COLOR` environment variable is set.
+ * @example ansiWrap("hello", ANSI_RED, ANSI_BOLD) // "\x1b[31m\x1b[1mhello\x1b[0m"
+ * @see https://dhoulb.github.io/shelving/util/ansi/ansiWrap
  */
 export declare function ansiWrap(input: string, ...wrappers: ImmutableArray<string>): string;
 /**
  * A lazily-coloured icon that re-evaluates its ANSI colouring against the live `NO_COLOR` environment variable every time it is converted to a string.
  *
  * - Used directly inside template literals (`${ANSI_SUCCESS}`), where JavaScript invokes `toString()` automatically, so the icon is coloured at use-time, not at module-load time.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/AnsiIcon
  */
 export type AnsiIcon = {
     toString(): string;
 };
+/**
+ * Lazily blue-coloured waiting icon (`⋯`) for use in template literals.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_WAITING
+ */
 export declare const ANSI_WAITING: AnsiIcon;
+/**
+ * Lazily green-coloured success icon (`✓`) for use in template literals.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_SUCCESS
+ */
 export declare const ANSI_SUCCESS: AnsiIcon;
+/**
+ * Lazily red-coloured failure icon (`✗`) for use in template literals.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_FAILURE
+ */
 export declare const ANSI_FAILURE: AnsiIcon;
+/**
+ * Lazily blue-coloured up arrow icon (`↑`) for use in template literals.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_UP
+ */
 export declare const ANSI_UP: AnsiIcon;
+/**
+ * Lazily blue-coloured down arrow icon (`↓`) for use in template literals.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_DOWN
+ */
 export declare const ANSI_DOWN: AnsiIcon;
+/**
+ * Lazily blue-coloured right arrow icon (`→`) for use in template literals.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_RIGHT
+ */
 export declare const ANSI_RIGHT: AnsiIcon;
+/**
+ * Lazily blue-coloured left arrow icon (`←`) for use in template literals.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_LEFT
+ */
 export declare const ANSI_LEFT: AnsiIcon;

package/util/ansi.js

@@ -1,27 +1,108 @@
 import { DOWN, FAILURE, LEFT, RIGHT, SUCCESS, UP, WAITING } from "./constants.js";
 import { getEnvBoolean } from "./env.js";
 // Colors.
+/**
+ * ANSI escape code that resets the foreground colour to the terminal default.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_DEFAULT
+ */
 export const ANSI_DEFAULT = "\x1b[39m";
+/**
+ * ANSI escape code that sets the foreground colour to black.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_BLACK
+ */
 export const ANSI_BLACK = "\x1b[30m";
+/**
+ * ANSI escape code that sets the foreground colour to red.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_RED
+ */
 export const ANSI_RED = "\x1b[31m";
+/**
+ * ANSI escape code that sets the foreground colour to green.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_GREEN
+ */
 export const ANSI_GREEN = "\x1b[32m";
+/**
+ * ANSI escape code that sets the foreground colour to yellow.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_YELLOW
+ */
 export const ANSI_YELLOW = "\x1b[33m";
+/**
+ * ANSI escape code that sets the foreground colour to blue.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_BLUE
+ */
 export const ANSI_BLUE = "\x1b[34m";
+/**
+ * ANSI escape code that sets the foreground colour to magenta.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_MAGENTA
+ */
 export const ANSI_MAGENTA = "\x1b[35m";
+/**
+ * ANSI escape code that sets the foreground colour to cyan.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_CYAN
+ */
 export const ANSI_CYAN = "\x1b[36m";
+/**
+ * ANSI escape code that sets the foreground colour to white.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_WHITE
+ */
 export const ANSI_WHITE = "\x1b[37m";
 // Styles.
+/**
+ * ANSI escape code that enables bold text.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_BOLD
+ */
 export const ANSI_BOLD = "\x1b[1m";
+/**
+ * ANSI escape code that enables italic text.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_ITALIC
+ */
 export const ANSI_ITALIC = "\x1b[3m";
+/**
+ * ANSI escape code that enables underlined text.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_UNDERLINE
+ */
 export const ANSI_UNDERLINE = "\x1b[4m";
+/**
+ * ANSI escape code that enables strikethrough text.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_STRIKE
+ */
 export const ANSI_STRIKE = "\x1b[9m";
+/**
+ * ANSI escape code that enables inverse (swapped foreground/background) text.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_INVERSE
+ */
 export const ANSI_INVERSE = "\x1b[7m";
 // Reset.
+/**
+ * ANSI escape code that resets all colour and style attributes.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_RESET
+ */
 export const ANSI_RESET = "\x1b[0m";
 /**
  * Wrap a string in the ANSI color/style codes (at the start), and `ANSI_RESET` at the end.
  *
  * - The `NO_COLOR` environment variable is read live on every call, so runtimes that populate `process.env` late (e.g. Cloudflare Workers, where `[vars]` bindings are only reliably available within the request scope) are honoured rather than baking in whatever `NO_COLOR` was at module-load time.
+ *
+ * @param input The string to wrap in ANSI codes.
+ * @param wrappers Any number of ANSI escape codes (e.g. `ANSI_RED`, `ANSI_BOLD`) to prepend before `input`.
+ * @returns The wrapped string, or `input` unchanged when the `NO_COLOR` environment variable is set.
+ * @example ansiWrap("hello", ANSI_RED, ANSI_BOLD) // "\x1b[31m\x1b[1mhello\x1b[0m"
+ * @see https://dhoulb.github.io/shelving/util/ansi/ansiWrap
  */
 export function ansiWrap(input, ...wrappers) {
     if (getEnvBoolean("NO_COLOR"))
@@ -37,10 +118,45 @@ function _createAnsiIcon(icon, ...wrappers) {
     };
 }
 // Coloured icons.
+/**
+ * Lazily blue-coloured waiting icon (`⋯`) for use in template literals.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_WAITING
+ */
 export const ANSI_WAITING = _createAnsiIcon(WAITING, ANSI_BLUE);
+/**
+ * Lazily green-coloured success icon (`✓`) for use in template literals.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_SUCCESS
+ */
 export const ANSI_SUCCESS = _createAnsiIcon(SUCCESS, ANSI_GREEN);
+/**
+ * Lazily red-coloured failure icon (`✗`) for use in template literals.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_FAILURE
+ */
 export const ANSI_FAILURE = _createAnsiIcon(FAILURE, ANSI_RED);
+/**
+ * Lazily blue-coloured up arrow icon (`↑`) for use in template literals.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_UP
+ */
 export const ANSI_UP = _createAnsiIcon(UP, ANSI_BLUE);
+/**
+ * Lazily blue-coloured down arrow icon (`↓`) for use in template literals.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_DOWN
+ */
 export const ANSI_DOWN = _createAnsiIcon(DOWN, ANSI_BLUE);
+/**
+ * Lazily blue-coloured right arrow icon (`→`) for use in template literals.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_RIGHT
+ */
 export const ANSI_RIGHT = _createAnsiIcon(RIGHT, ANSI_BLUE);
+/**
+ * Lazily blue-coloured left arrow icon (`←`) for use in template literals.
+ *
+ * @see https://dhoulb.github.io/shelving/util/ansi/ANSI_LEFT
+ */
 export const ANSI_LEFT = _createAnsiIcon(LEFT, ANSI_BLUE);