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

React integration for KForm.

import { Path } from "@kform/core";
import * as React from "react";
import { DistributedOmit } from "../utils/typeUtils";
import { FormatterController, FormatterControllerState, FormatterOptions } from "./useFormatter";
/**
 * Options available to the {@link useInput} hook.
 */
export type InputOptions<T = unknown, TFormatted = T | undefined, TInput = unknown> = DistributedOmit<FormatterOptions<T, TFormatted>, "setFormattedValue" | "format"> & InputOwnOptions<T, TFormatted, TInput>;
/**
 * Own options available to the {@link useInput} hook.
 */
export interface InputOwnOptions<T = unknown, TFormatted = T | undefined, TInput = unknown> {
    /**
     * Function used to set the formatted value in the input element.
     *
     * 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 Controller of the form value.
     * @param input Input element.
     */
    setFormattedValue?: (formattedValue: TFormatted, state: FormatterControllerState<T, TFormatted>, input: TInput | null) => void;
    /**
     * Function that formats the form manager value into a value to be set in the
     * input element. The passed {@link value} is `undefined` when the form
     * manager value does not exist.
     * @param value Form manager value to transform.
     * @param controller Controller of the value to transform.
     * @param input Input element.
     * @returns Transformed value.
     */
    format?: (value: T | undefined, state: FormatterControllerState<T, TFormatted>, input: TInput | null) => TFormatted | PromiseLike<TFormatted>;
    /**
     * Function used to parse the input element value into a value to be set in
     * the form manager.
     * @param formattedValue Input element value to transform.
     * @param controller Controller of the value to transform.
     * @param input Input element.
     * @returns Transformed value.
     */
    parse?: (formattedValue: TFormatted, state: FormatterControllerState<T, TFormatted>, input: TInput | null) => T | PromiseLike<T>;
}
/**
 * Controller used to read and manipulate the form value associated with the
 * form input, exposing properties that should be set on the input itself.
 */
export type InputController<T = unknown, TFormatted = T | undefined, TInput = unknown> = FormatterController<T, TFormatted> & InputOwnController<TFormatted, TInput>;
/**
 * Input own controller.
 */
export interface InputOwnController<TFormatted = unknown, TInput = unknown> {
    /**
     * Properties to be passed to the input element.
     */
    inputProps: InputElementProps<TFormatted, TInput>;
}
/**
 * Properties to provide to an input element to integrate it with a form
 * manager.
 */
export interface InputElementProps<TFormatted = unknown, TInput = unknown> {
    /**
     * Name of the input element.
     */
    name: string;
    /**
     * Whether the input element should be read-only.
     *
     * This is `true` when the schema associated with this input is computed.
     */
    readOnly: boolean;
    /**
     * Reference to the input element.
     */
    ref: React.Ref<TInput>;
    /**
     * Function to run whenever the value of the input element changes. This
     * function can receive either a change event with a standard HTML input
     * ({@link HTMLInputElement <input>}, {@link HTMLSelectElement <select>},
     * {@link HTMLTextAreaElement <textarea>}) as target or a value directly.
     *
     * This function sets the new value in the form manager and marks the value as
     * dirty.
     * @param eventOrValue Either a "change event" or the new value.
     */
    onChange: (eventOrValue: React.ChangeEvent | TFormatted) => void;
    /**
     * Function to run whenever the input element is blurred. This function marks
     * the form value as "touched").
     */
    onBlur: () => void;
}
/**
 * Hook used to control the integration between a value of the form manager and
 * an input of the form. It provides access to the form value, as well as
 * properties for integration with an input element.
 * @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 associated with
 * the form input, exposing properties that should be set on the input itself.
 */
export declare function useInput<T = unknown, TInput = unknown>(path?: Path | string, options?: undefined): InputController<T, T | undefined, TInput>;
export declare function useInput<T = unknown, TFormatted = T | undefined, TInput = unknown>(path: Path | string | undefined, options: InputOptions<T, TFormatted, TInput>): InputController<T, TFormatted, TInput>;
/**
 * Default function used to set a formatted value within an input element.
 */
export declare function defaultSetFormattedValue(formattedValue: unknown, _state: any, input: unknown): void;