@kform/react/types/hooks/useFormatter.d.ts

React integration for KForm.

import { Path } from "@kform/core";
import { Controller, ControllerOptions, ExistingValueControllerState, NonexistentValueControllerState, UninitializedControllerState } from "./useController";
/**
 * Options available to the {@link useFormatter} hook.
 */
export interface FormatterOptions<T = unknown, TFormatted = T | undefined> extends ControllerOptions<T, FormatterControllerState<T, TFormatted>>, FormatterOwnOptions<T, TFormatted> {
}
/**
 * Own options available to the {@link useFormatter} hook.
 */
export interface FormatterOwnOptions<T = unknown, TFormatted = T | undefined> {
    /**
     * Function used to set the formatted value. A
     * [useState]{@link React.useState} dispatcher can be used to save the output
     * value within React state.
     *
     * The passed value results from calling {@link format} on the form manager
     * value. If {@link format} is not defined, then the form manager value is
     * passed directly.
     * @param formattedValue Formatted value to set.
     * @param controller Form value's controller.
     */
    setFormattedValue?: (formattedValue: TFormatted, state: FormatterControllerState<T, TFormatted>) => void | PromiseLike<void>;
    /**
     * Format function that transforms the form manager value into a value to be
     * output. The passed {@link value} is `undefined` when the form manager value
     * does not exist.
     * @param value Form manager value to transform.
     * @param controller Form value's controller.
     * @returns Transformed value.
     */
    format?: (value: T | undefined, state: FormatterControllerState<T, TFormatted>) => TFormatted | PromiseLike<TFormatted>;
}
/**
 * Controller which keeps track of a formatted value.
 */
export interface FormatterController<T = unknown, TFormatted = T | undefined> extends Controller<T, FormatterControllerState<T, TFormatted>>, FormatterOwnController<T, TFormatted> {
}
/**
 * Formatter's own controller.
 */
export interface FormatterOwnController<T = unknown, TFormatted = T | undefined> {
    readonly useFormattedValue: () => TFormatted | undefined;
}
/**
 * State of the formatter's controller.
 */
export type FormatterControllerState<T = unknown, TFormatted = T | undefined> = UninitializedFormatterControllerState<T, TFormatted> | InitializedFormatterControllerState<T, TFormatted>;
/**
 * Formatter controller's own base state.
 */
export interface FormatterControllerOwnBaseState<T = unknown, TFormatted = T | undefined> {
    /**
     * Formatted value.
     */
    formattedValue: TFormatted | undefined;
}
/**
 * Uninitialised formatter controller state.
 */
export interface UninitializedFormatterControllerState<T = unknown, TFormatted = T | undefined> extends FormatterControllerOwnBaseState<T, TFormatted>, UninitializedControllerState<T> {
    formattedValue: undefined;
}
/**
 * Initialised formatter controller state.
 */
export type InitializedFormatterControllerState<T = unknown, TFormatted = T | undefined> = NonexistentValueFormatterControllerState<T, TFormatted> | ExistingValueFormatterControllerState<T, TFormatted>;
/**
 * Formatter controller state of a nonexistent form value.
 */
export interface NonexistentValueFormatterControllerState<T = unknown, TFormatted = T | undefined> extends FormatterControllerOwnBaseState<T, TFormatted>, FormatterControllerOwnBaseState<T, TFormatted>, NonexistentValueControllerState<T> {
    formattedValue: TFormatted;
}
/**
 * Formatter controller state of an existing form value.
 */
export interface ExistingValueFormatterControllerState<T = unknown, TFormatted = T | undefined> extends FormatterControllerOwnBaseState<T, TFormatted>, ExistingValueControllerState<T> {
    formattedValue: TFormatted;
}
/**
 * Hook facilitating the formatting of a form value by providing a way of
 * formatting and setting said value (e.g. within React state).
 * @param path Path of the form value to access, relative to the current path.
 * @param options Available options.
 * @returns A controller used to read and control the form value.
 */
export declare function useFormatter<T = unknown, TFormatted = T | undefined>(path: Path | string | undefined, options: FormatterOptions<T, TFormatted>): FormatterController<T, TFormatted>;