@ekisa-cdk/forms/dist/index.d.ts

🛠️ Easily build & integrate dynamic forms

declare type FormControlType = 'FieldSet' | 'TextBox' | 'TextArea' | 'NumberBox' | 'SelectBox' | 'CheckBox' | 'RadioGroup' | 'DatePicker' | 'TimePicker';

/**
 * @description
 * Defines the map of errors returned from failed validation checks.
 *
 * @publicApi
 */
declare type ValidationErrors = {
    [key: string]: any;
};
/**
 * @description
 * A function that receives a control and synchronously returns a map of
 * validation errors if present, otherwise null.
 *
 * @publicApi
 */
interface ValidatorFn {
    (control: AbstractControl): ValidationErrors | null;
}
/**
 * Validator that requires the control's value to match a regex pattern.
 */
/**
 * @description
 * Provides a set of built-in validators that can be used by form controls.
 *
 * A validator is a function that processes a `FormControl` or collection of
 * controls and returns an error map or null. A null map means that validation has passed.
 *
 *
 * @publicApi
 */
declare class Validators {
    static required: (control: AbstractControl) => ValidationErrors | null;
    static requiredTrue: (control: AbstractControl) => ValidationErrors | null;
    static email: (control: AbstractControl) => ValidationErrors | null;
    static min: (min: number) => ValidatorFn;
    static max: (max: number) => ValidatorFn;
    static minLength: (minLength: number) => ValidatorFn;
    static maxLength: (maxLength: number) => ValidatorFn;
}

declare abstract class AbstractControl {
    value: unknown | null;
    key: string;
    label: string | undefined;
    type: FormControlType | undefined;
    validators: ValidatorFn[];
    get errors(): ValidationErrors[] | null;
    constructor(value: unknown | null, options?: {
        key: string;
        label?: string;
        order?: number;
        type?: FormControlType;
        validators?: ValidatorFn[];
    });
    getElement<T extends HTMLElement>(): T | null;
    getParentElement(): HTMLDivElement | null;
    getValidationsElement(): HTMLElement | null;
    getValue(): any | null;
    setValue(value: any): void;
}

declare class CheckBox extends AbstractControl {
    type: FormControlType;
    key: string;
    value: boolean | null;
    label: string;
    validators: ValidatorFn[];
    constructor(value: boolean | null, options?: {
        key: string;
        label: string;
        validators?: ValidatorFn[];
    });
    getValue(): boolean;
    setValue(value: boolean): void;
}

declare class DatePicker extends AbstractControl {
    type: FormControlType;
    key: string;
    value: Date | null;
    label: string | undefined;
    validators: ValidatorFn[];
    constructor(value: Date | null, options?: {
        key: string;
        label?: string;
        validators?: ValidatorFn[];
    });
    getValue(): Date | null;
    setValue(value: Date): void;
}

declare type Columns = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;

declare type FormControl = FieldSet | TextBox | TextArea | NumberBox | SelectBox | CheckBox | RadioGroup | DatePicker | TimePicker;
declare type FormControls = Array<FormControl>;

declare class FieldSet {
    type: FormControlType;
    legend: string | undefined;
    cols: Columns | undefined;
    children: FormControls;
    constructor(options?: {
        legend?: string;
        cols?: Columns;
        children?: FormControls;
    });
}

declare class NumberBox extends AbstractControl {
    type: FormControlType;
    key: string;
    value: number | null;
    label: string | undefined;
    validators: ValidatorFn[];
    min: number | undefined;
    max: number | undefined;
    constructor(value: number | null, options?: {
        key: string;
        label?: string;
        validators?: ValidatorFn[];
        min?: number;
        max?: number;
    });
    getValue(): number | null;
    setValue(value: number): void;
}

declare type RadioGroupItem = {
    value: string;
    label: string;
};
declare class RadioGroup extends AbstractControl {
    type: FormControlType;
    key: string;
    value: string | null;
    validators: ValidatorFn[];
    text: string | undefined;
    items: RadioGroupItem[];
    constructor(value: string | null, options?: {
        key: string;
        text?: string;
        items: RadioGroupItem[];
        validators?: ValidatorFn[];
    });
    getValue(): string | null;
    setValue(value: string): void;
    reset(): void;
}

declare type SelectBoxOption = {
    value: string;
    text: string;
    meta?: string;
};
declare class SelectBox extends AbstractControl {
    type: FormControlType;
    key: string;
    value: string | null;
    label: string | undefined;
    validators: ValidatorFn[];
    options: SelectBoxOption[];
    constructor(value: string | null, options?: {
        key: string;
        label?: string;
        options?: SelectBoxOption[];
        validators?: ValidatorFn[];
    });
}

declare class TextArea extends AbstractControl {
    type: FormControlType;
    key: string;
    value: string | null;
    label: string | undefined;
    validators: ValidatorFn[];
    placeholder: string | undefined;
    cols: number | undefined;
    rows: number | undefined;
    constructor(value: string | null, options?: {
        key: string;
        label?: string;
        placeholder?: string;
        cols?: number;
        rows?: number;
        validators?: ValidatorFn[];
    });
}

declare class TextBox extends AbstractControl {
    type: FormControlType;
    key: string;
    value: string | null;
    label: string | undefined;
    validators: ValidatorFn[];
    placeholder: string | undefined;
    constructor(value: string | null, options?: {
        key: string;
        label?: string;
        placeholder?: string;
        validators?: ValidatorFn[];
    });
}

declare class TimePicker extends AbstractControl {
    type: FormControlType;
    key: string;
    value: Date | null;
    label: string | undefined;
    validators: ValidatorFn[];
    constructor(value: Date | null, options?: {
        key: string;
        label?: string;
        validators?: ValidatorFn[];
    });
    getValue(): Date | null;
    setValue(value: Date): void;
}

declare type ValidationOutput = Array<{
    control: AbstractControl;
    errors: ValidationErrors[];
}> | null;
declare abstract class AbstractForm {
    abstract getControl(key: string): AbstractControl | undefined;
    abstract render(parent: HTMLBodyElement | HTMLDivElement): void;
    abstract reset(): void;
    abstract validate(): ValidationOutput;
    abstract validateControl(controlKey: string): ValidationOutput;
    abstract toJSON<T>(): T;
}

declare type MappingSource = Array<Record<string, any>>;
declare type ControlPublicKeys = 'key' | 'value' | 'label' | 'placeholder' | 'validators';
declare type FieldsetPublicKeys = 'legend' | 'cols' | 'children';
declare type TextAreaPublicKeys = 'cols' | 'rows';
declare type NumberBoxPublicKeys = 'min' | 'max';
declare type SelectBoxPublicKeys = 'options' | keyof SelectBoxOption;
declare type RadioGroupPublicKeys = 'text' | 'items' | keyof RadioGroupItem;
declare type AutoMapperPluginConfig<ControlType> = {
    types: Record<FormControlType, ControlType>;
    keys: {
        controlTypePropertyName: string;
        fieldSet: Record<FieldsetPublicKeys, string>;
        control: Record<ControlPublicKeys, string>;
        textAreaOptions: Record<TextAreaPublicKeys, string>;
        numberBoxOptions: Record<NumberBoxPublicKeys, string>;
        selectBoxOptions: Record<SelectBoxPublicKeys, string>;
        radioGroupOptions: Record<RadioGroupPublicKeys, string>;
        validators: {
            propertyName: string;
            name: string;
            value?: string;
        };
    };
};
declare class AutoMapperPlugin<ControlType> implements FormPlugin<AutoMapperPluginConfig<ControlType>> {
    private _source;
    private _config;
    constructor(source: MappingSource, config: AutoMapperPluginConfig<ControlType>);
    run(): FormControls;
    private _mapFromSource;
    private _mapValidators;
}

declare type EventsPluginConfig = {
    targetKey: string;
    attachmentType: 'single' | 'multiple';
    on: keyof HTMLElementEventMap;
    runFn: (this: Element, ev: Event) => void;
};
declare class EventsPlugin implements FormPlugin<EventsPluginConfig> {
    run({ targetKey, attachmentType, on, runFn }: EventsPluginConfig): void;
}

declare type ValidationPluginConfig = {
    parentElement?: keyof HTMLElementTagNameMap;
    childElement?: keyof HTMLElementTagNameMap;
    messages?: {
        required?: string;
        requiredTrue?: string;
        email?: string;
        min?: string;
        max?: string;
        minLength?: string;
        maxLength?: string;
    };
};
declare class ValidationsPlugin implements FormPlugin<ValidationOutput> {
    private _parentElement;
    private _childElement;
    private _messages;
    constructor(config?: ValidationPluginConfig);
    run(input: ValidationOutput): void;
}

/**
 * @description
 * Defines a built-in plugins behavior
 *
 * A plugin is an encapsulated functionality that allows to extend form's functionallity
 */
interface FormPlugin<T = void, U = void> {
    /**
     * @description
     * Run process when the form needs it
     * @param input incoming data that provides the neccessary information to proccess inside the plugin
     */
    run(input: T): void | U;
}
/**
 * Single built-in plugin
 */
declare type BuiltInPlugin = ValidationsPlugin | EventsPlugin | AutoMapperPlugin<void>;
/**
 * Collection of built-in plugins that allow to extend form's functionallity
 */
declare type PluginsCollection = Array<BuiltInPlugin>;
declare type Constructor<T> = new () => T;
/**
 * Find plugin if it's configured & attached to dynamic form
 * @param plugins collection of configured form plugins
 * @returns class instance of plugin item
 */
declare function findPlugin<T extends BuiltInPlugin>(plugins: PluginsCollection, filterType: Constructor<T>): T;

declare class Form extends AbstractForm {
    dataSource: FormControls;
    /**
     * Collection of form plugins that extend its functionality
     */
    plugins: PluginsCollection;
    private _controls;
    get controls(): Array<AbstractControl>;
    constructor(args: {
        dataSource: FormControls;
        plugins?: PluginsCollection;
    });
    /**
     * Get form control
     * @param key control key identifier
     */
    getControl(key: string): AbstractControl | undefined;
    /**
     * Render dynamic form inside parent element
     * @param parent HTML element where the form will be rendered
     */
    render(parent: HTMLBodyElement | HTMLDivElement): void;
    /**
     * Reset form elements to defaults
     */
    reset(): void;
    /**
     * Check the validity of all the configured control validators
     * @returns ValidationOutput or null if no errors are found
     */
    validate(): ValidationOutput;
    /**
     * Check the validity of a single configured control validators
     * @returns ValidationOutput or null if no errors are found
     */
    validateControl(key: string): ValidationOutput;
    /**
     * Convert controls values to JSON format
     * @returns specified generic type
     */
    toJSON<T>(): T;
    /**
     * Return all form controls & all nested fieldset controls
     * @param controls
     * @returns flatten nested controls inside fieldsets
     */
    private _flattenControls;
}

export { AbstractControl, AutoMapperPlugin, AutoMapperPluginConfig, BuiltInPlugin, CheckBox, DatePicker, EventsPlugin, FieldSet, Form, FormControl, FormControlType, FormControls, FormPlugin, NumberBox, PluginsCollection, RadioGroup, RadioGroupItem, SelectBox, SelectBoxOption, TextArea, TextBox, TimePicker, ValidationsPlugin, ValidatorFn, Validators, findPlugin };