shelving/ui/util/notice.d.ts

Toolkit for using data in JavaScript.

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.
 * - This is how e.g. `<Button>` and `<FormNotify>` components send notices to the `<Notices>` list of global notices.
 */
export declare function notify(message: ReactNode, status?: Status | undefined, el?: EventTarget): void;
/** Notify the user with a success message by dispatching a notice event. */
export declare function notifySuccess(message: ReactNode, el?: EventTarget): void;
/** Notify the user with a success message by dispatching a notice event. */
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.. */
export declare function notifyThrown(thrown: unknown, el?: EventTarget): void;
/** Subscribe to notice events on the window and call a callback when they happen. */
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. */
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" */
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 */
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" */
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 */
export declare function awaitNotifiedElement(el: EventTarget | undefined, pending: PromiseLike<ReactNode | undefined | void>): Promise<boolean>;