form-studio/dist/Form.d.ts

A tool that helps design, create and manage form / survey / questionnaire through simple JSON configurations.

import { Configs } from './Configs';
import { ExportedConfigs } from './ExportedConfigs';
import { RenderInstructions } from './RenderInstructions';
import { Answers, ConfigsValidationResult, Errors, FormUpdateListener, Validators } from './Types';
export interface UpdateAnswerOptions {
    /**
     * Validate the answer, default = `true`
     */
    validate?: boolean;
}
export interface FormOptions extends UpdateAnswerOptions {
    /**
     * Validators
     */
    validators?: Validators;
    /**
     * Function to be called when form is updated
     */
    onFormUpdate?: FormUpdateListener;
}
/**
 * @category Form
 */
export declare class Form<Custom = any> {
    #private;
    /**
     * Construct a form.
     *
     * @param configs configs
     * @param options options
     * @throws if configs is invalid
     */
    constructor(configs: Configs<Custom>, options?: FormOptions);
    setValidators(validators: Validators | undefined): void;
    setUpdateListener(onFormUpdate?: FormUpdateListener | undefined): void;
    /**
     * Get sanitized configs of this form.
     *
     * You can persist it and use it to reconstruct the form later.
     *
     * @returns configs
     */
    getConfigs(): ExportedConfigs<Custom>;
    /**
     * Get a set of instructions to be used for rendering frontend UI.
     *
     * @returns render instructions
     */
    getRenderInstructions(): RenderInstructions<Custom>;
    /**
     * Clear answers of the entire form.
     *
     * @param options options
     */
    clear(options?: UpdateAnswerOptions): void;
    /**
     * Clear answers of the entire group.
     *
     * @param groupId group id
     * @param options options
     */
    clearGroup(groupId: string, options?: UpdateAnswerOptions): void;
    /**
     * Clear answer of a question.
     *
     * @param questionId question id
     * @param options options
     */
    clearAnswer(questionId: string, options?: UpdateAnswerOptions): void;
    /**
     * Reset answers of the entire form to default answers.
     *
     * @param options options
     */
    reset(options?: UpdateAnswerOptions): void;
    /**
     * Reset answers of the entire group to default answers.
     *
     * @param groupId group id
     * @param options options
     */
    resetGroup(groupId: string, options?: UpdateAnswerOptions): void;
    /**
     * Reset answer of a question to default answer.
     *
     * @param questionId question id
     * @param options options
     */
    resetAnswer(questionId: string, options?: UpdateAnswerOptions): void;
    /**
     * Import answers to the form.
     *
     * @param answers answers
     * @param options options
     */
    importAnswers(answers: Answers, options?: UpdateAnswerOptions): void;
    /**
     * Set answer of a question.
     *
     * @param questionId question id
     * @param answer answer
     * @param options options
     */
    setAnswer(questionId: string, answer: any, options?: UpdateAnswerOptions): void;
    /**
     * Set answer of a question with `any` as [[type]].
     *
     * @param questionId question id
     * @param answer answer
     * @param options options
     */
    setAny(questionId: string, answer: any, options?: UpdateAnswerOptions): void;
    /**
     * Set answer of a question with `choice` as [[type]].
     *
     * @param questionId question id
     * @param value choice's value
     * @param options options
     */
    setChoice(questionId: string, value: any, options?: UpdateAnswerOptions): void;
    /**
     * Set answers of a question with `choices` as [[type]].
     *
     * @param questionId question id
     * @param values choices' values
     * @param options options
     */
    setChoices(questionId: string, values: any[], options?: UpdateAnswerOptions): void;
    /**
     * Select invididual choice.
     *
     * This method can be used by questions with `choice` or `choices` as [[type]] only.
     *
     * @param choiceId choice id
     * @param selected selected/unselected
     * @param options options
     */
    selectChoice(choiceId: string, selected: boolean, options?: UpdateAnswerOptions): void;
    /**
     * Get current answer of a question. The answer is unvalidated.
     *
     * @param questionId question id
     * @returns current answer
     */
    getCurrentAnswer(questionId: string): any;
    /**
     * Get current answers. The answers are unvalidated.
     *
     * You can persist it and use it with [[importAnswers]] method to restore the answers later.
     *
     * @returns current answers
     */
    getCurrentAnswers(): Answers;
    /**
     * Get validated answer of a question.
     *
     * If the question is disabled or it's answer is not valid, it's answer will be set to `undefined`.
     *
     * @param questionId question id
     * @returns validated answer
     */
    getValidatedAnswer(questionId: string): any;
    /**
     * Get validated answers.
     *
     * If a question is disabled or it's answer is not valid, it's answer will be set to `undefined`.
     *
     * You can persist it and use it with [[importAnswers]] method to restore the answers later.
     *
     * @returns validated answers
     */
    getValidatedAnswers(): Answers;
    /**
     * Get error of a question.
     *
     * If the question hasn't gone through validation, it will not have error, even if its answer is currently invalid.
     *
     * @param questionId question id
     * @returns error
     */
    getError(questionId: string): any;
    /**
     * Get errors.
     *
     * Questions which didn't go through validation will not have errors, even if their answers are currently invalid.
     *
     * You can use [[validate]] method to validate all answers in the form.
     *
     * @returns errors
     */
    getErrors(): Errors;
    /**
     * Check whether form is currently being validated.
     *
     * The result might be `true` if you have async validator and the validation is not completed yet.
     *
     * @returns whether form is current being validated
     */
    isValidating(): boolean;
    /**
     * Check whether form is clean.
     *
     * Form will always be clean if it didn't go through any validation, even if there are invalid answers in the form.
     *
     * You can use [[validate]] method to validate all answers in the form.
     *
     * @returns whether form is clean
     */
    isClean(): boolean;
    /**
     * Do a final round of validation and get the validated answers.
     *
     * This method will not update render instructions.
     * It is more for when you need to make sure that the form is really clean and get the final validated answers for further usage,
     * e.g. calling API, store into database, etc.
     *
     * @returns validated answer or `false` if form is not clean
     */
    asyncValidate(): Promise<Answers | false>;
    /**
     * Validate the entire form.
     *
     * @returns whether form is clean
     */
    validate(): void;
    /**
     * Validate configs.
     *
     * The following validations will be conducted:
     * - Form is not without any groups or questions
     * - No duplicated ids within the form
     * - No groups without questions
     * - No questions with `choice` or `choices` as type without choices
     * - No duplicated choice values within a question
     * - No circular choices' `onSelected` configs
     *
     * Put `strict` as `true` to validate the following:
     * - No unrecognized ids in choices' `onSelected` configs
     *
     * @param configs configs
     * @param strict strict
     * @returns validation result
     */
    static validateConfigs(configs: Configs, strict?: boolean): ConfigsValidationResult;
}