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

React integration for KForm.

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;