@abgov/ui-components-common/lib/public-form-controller.d.ts

Government of Alberta - UI Web components

import { FieldsetItemState, FieldValidator } from './validators';
import { GoabFieldsetItemValue, GoabFormDispatchOn } from './common';
export type FormStatus = "not-started" | "incomplete" | "complete";
export type AppState<T> = {
    uuid: string;
    form: Record<string, Fieldset<T>>;
    history: string[];
    editting: string;
    lastModified?: Date;
    status: FormStatus;
    currentFieldset?: {
        id: T;
        dispatchType: GoabFormDispatchOn;
    };
};
export type Fieldset<T> = {
    heading: string;
    data: {
        type: "details";
        fieldsets: Record<string, FieldsetItemState>;
    } | {
        type: "list";
        items: AppState<T>[];
    };
};
export declare class PublicFormController<T> {
    #private;
    private type;
    state?: AppState<T> | AppState<T>[];
    _formData?: Record<string, string>;
    _formRef?: HTMLElement;
    private _isCompleting;
    constructor(type: "details" | "list");
    init(e: Event): void;
    initList(e: Event): void;
    initState(state?: string | AppState<T> | AppState<T>[], callback?: () => void): void;
    updateListState(e: Event): void;
    updateObjectState(e: Event): void;
    getStateList(): Record<string, string>[];
    getStateValue(group: string, key: string): string;
    continueTo(next: T | undefined): void;
    validate(e: Event, field: string, validators: FieldValidator[], options?: {
        grouped: boolean;
    }): [boolean, GoabFieldsetItemValue];
    /**
     * Validates a group of fields ensuring that at least `minPassCount` of the items within the group
     * passes. This is useful in the scenario when n number fields are required out of n+m number of fields.
     *
     * @param {string[]} fields - An array of field names to be validated.
     * @param {Event} e - The event object associated with the validation trigger.
     * @param {FieldValidator[]} validators - An array of validator functions to apply to the fields.
     * @return {[number, Record<string, boolean>]} - Returns back the number of fields that passed and a record of the fields and their pass status.
     */
    validateGroup(e: Event, fields: string[], validators: FieldValidator[]): [number, Record<string, boolean>];
    edit(index: number): void;
    remove(index: number): void;
    /**
     * Completes the form and triggers the onComplete callback.
     * This method should be used when you want to complete a form without navigating to a summary page.
     *
     * @important Developers must validate the form before calling this method.
     *
     * @example
     * // Validate first, then complete
     * const [isValid] = this.validate(e, "firstName", [
     *   requiredValidator("First name is required.")
     * ]);
     * if (isValid) {
     *   this.complete();
     * }
     * @returns void
     */
    complete(): void;
    /**
     * Completes a subform and returns control to the parent form.
     * This method should be used when working with subforms that need to complete without a summary page.
     *
     * @important Developers must validate the subform before calling this method.
     *
     * @example
     * // Validate first, then complete the subform
     * const [isValid] = this._childFormController.validate(e, "fullName", [
     *   requiredValidator("Please enter the dependent's full name.")
     * ]);
     * if (isValid) {
     *   this._childFormController.completeSubform();
     * }
     * @returns void
     */
    completeSubform(): void;
    clean(data: AppState<T>): Record<string, unknown>;
}