shelving/ui/form/Form.d.ts

Toolkit for using data in JavaScript.

import type { ReactElement, ReactNode, SubmitEvent } from "react";
import type { DataSchema } from "../../schema/DataSchema.js";
import type { Data, PartialData } from "../../util/data.js";
import type { ImmutableDictionary } from "../../util/dictionary.js";
import type { Arguments } from "../../util/function.js";
import { type NoticeCallback } from "../util/notice.js";
import type { OptionalChildProps } from "../util/props.js";
import { FormStore } from "./FormStore.js";
/**
 * Handler for a clickable `onClick` event.
 * - Returned value (if defined) is notified to the user using `notifySuccess()`
 * - Thrown value is notified to the user using `notifyError()`
 */
export type FormCallback<T extends Data> = (data: T, event: SubmitEvent<HTMLFormElement>) => ReactNode | void | PromiseLike<ReactNode | void>;
export interface FormProps<T extends Data> extends OptionalChildProps {
    /** Schema for the form. */
    schema: DataSchema<T>;
    /** Initial data for the form. */
    data?: PartialData<T> | undefined;
    /** Content of the submit button. */
    submit?: ReactNode | undefined;
    /** Optional function called when the form is submitted. Takes the current (validated) value of the form, processes it (possibly asynchronously) and returns any new values to set in the form. */
    onSubmit?: FormCallback<T> | undefined;
    /** Initial set of messages for the form as either a dictionary or a string with `fieldName:` style messages. */
    messages?: ImmutableDictionary<string> | string | undefined;
}
export declare function Form<T extends Data>(props: FormProps<T>): ReactElement;
/** Callback that publishes notices to an element (defaults to the window) if it returns or throws "string" */
export declare function callNotifiedForm<T extends Data, A extends Arguments>(value: T, store: FormStore<T>, form: HTMLFormElement, callback?: NoticeCallback<[T, ...A]>, ...args: A): boolean | Promise<boolean>;
/** Await a value that publishes "success" or "error" notices to a form */
export declare function awaitNotifiedForm<T extends Data>(store: FormStore<T>, form: HTMLFormElement, pending: PromiseLike<ReactNode | undefined | void>): Promise<boolean>;
/** Notify the user about a thrown value during a submit (if thrown value is a string then save it as messages instead. */
export declare function notifyThrownForm<T extends Data>(store: FormStore<T>, form: HTMLFormElement, thrown: unknown): false;