@kform/react
Version:
React integration for KForm.
115 lines (114 loc) • 4.02 kB
TypeScript
import { AbsolutePath, DisplayStatus, FormManager, Path, SealedValidationIssue } from "@kform/core";
/**
* Options available to the {@link useIssuesTracker} hook.
*/
export interface IssuesTrackerOptions {
/**
* Required if no form context is in scope.
*
* If a form context is in scope and this value is also provided, then the
* provided form manager will be used, in which case the current path of the
* form context is ignored.
*/
formManager?: FormManager;
/**
* Function which may be provided to specify the order of the resulting
* issues.
*
* It receives the paths of the issues being compared and should return a
* number in typical
* [Array.prototype.sort#compareFn](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#comparefn)
* fashion to determine the order of the issues.
*
* The default ordering is based on the order in which fields were declared
* within the form schema. If this function is provided, and `0` is returned,
* then the default schema-based ordering will be used for disambiguation.
*
* Note that this function should **not** change on every render, as any
* change to this function will cause the tracker to "restart".
* @param path1 First path being compared.
* @param path2 Second path being compared.
* @returns Positive number if `path1 > path2`, negative number if
* `path2 > path1`, `0` otherwise.
*/
issuesOrderCompareFn?: (path1: AbsolutePath, path2: AbsolutePath) => number;
/**
* Whether to enable validation issues tracking.
* @default true
*/
enabled?: boolean;
}
/**
* Result of the {@link useIssuesTracker} hook, containing the validation issues
* of the tracked values (when tracking and initialised).
*/
export type IssuesTrackerResult = UninitializedTrackedValidationIssues | InitializedTrackedValidationIssues;
/**
* Base representation of the result of the {@link useIssuesTracker}
* hook.
*/
export interface BaseIssuesTrackerResult {
/**
* Whether the tracking of validation issues has been initialised.
*/
initialized: boolean;
/**
* Validation information about the values with issues.
*/
info?: LocatedValidationInfo[];
/**
* Total number of errors.
*/
errors?: number;
/**
* Total number of warnings.
*/
warnings?: number;
}
/**
* Result of the {@link useIssuesTracker} hook while initialising the
* tracking of validation issues.
*/
export interface UninitializedTrackedValidationIssues extends BaseIssuesTrackerResult {
initialized: false;
info?: undefined;
errors?: undefined;
warnings?: undefined;
}
/**
* Result of the {@link useIssuesTracker} hook while tracking
* validation issues.
*/
export interface InitializedTrackedValidationIssues extends BaseIssuesTrackerResult {
initialized: true;
info: LocatedValidationInfo[];
errors: number;
warnings: number;
}
/**
* Information about the issues of a certain value.
*/
export interface LocatedValidationInfo {
/**
* Path of the value with issues.
*/
path: AbsolutePath;
/**
* Issues of the value (the array is guaranteed to not be empty).
*/
issues: SealedValidationIssue[];
/**
* Local display status of the value (ignores issues of descendants).
*/
localDisplayStatus: Exclude<DisplayStatus, "valid">;
}
/**
* Hook used to keep track of validation issues of values at paths matching
* {@link path}.
* @param path Path of values for which to keep track of validation issues.
* Defaults to `/**`.
* @param issuesTrackerOptions Available options.
* @returns Object containing information on issues of values at paths matching
* {@link path}.
*/
export declare function useIssuesTracker(path?: Path | string, { formManager: formManagerOption, issuesOrderCompareFn, enabled, }?: IssuesTrackerOptions): IssuesTrackerResult;