@ainelo/form-engine 1.0.3

package/dist/index.d.mts

@@ -0,0 +1,453 @@
+/**
+ * Represents a generic response value that can be of various types.
+ *
+ * @property responseValue - The value of the response, which can be a string, an array of strings,
+ * a number, an array of numbers, a boolean, a File, or an array of Files.
+ */
+interface ResponseInForm {
+    responseValue: string | string[] | number | number[] | boolean | File | File[] | null;
+}
+/**
+ * Représente une option sélectionnable dans un champ de formulaire de type sélection.
+ *
+ * @property value - La valeur unique associée à l’option (utilisée en interne).
+ * @property label - Le libellé affiché à l’utilisateur. Peut être une chaîne de caractères ou un objet de traductions par langue.
+ * @property points - (Optionnel) Nombre de points associés à cette option, utilisé pour des calculs ou des scores.
+ * @property icon - (Optionnel) Icône à afficher à côté de l’option dans l’interface utilisateur.
+ */
+interface SelectOption {
+    value: string;
+    label: string | {
+        [lang: string]: string;
+    };
+    points?: number;
+    icon?: string;
+}
+type ConditionalOperator = "==" | "!=" | ">" | "<" | "IN" | "NOT IN" | "CONTAINS" | "NOT CONTAINS";
+/**
+ * Méthodes d’agrégation de valeurs de plusieurs champs
+ */
+type TypeComputation = "SOMME" | "MULTIPLICATION";
+/**
+ * Une règle unique de condition d'affichage.
+ */
+interface ConditionalDisplayRule {
+    /**
+     * Clé(s) technique(s) des champs sur lesquels appliquer la règle.
+     * Peut être utilisé si formFieldId n’est pas renseigné.
+     */
+    fieldName?: string | string[];
+    /**
+     * ID(s) unique(s) des champs (UUID).
+     * Peut remplacer ou compléter fieldName.
+     */
+    formFieldId?: string | string[];
+    /**
+     * La valeur ou les valeurs attendues (cible de comparaison).
+     */
+    value?: string | number | boolean | string[] | number[];
+    /**
+     * L’opérateur de comparaison.
+     */
+    operator?: ConditionalOperator;
+    /**
+     * Comparaison à une valeur numérique (dans le cas d’une agrégation ou d’un champ nombre).
+     */
+    numeric_compare_to?: number;
+    /**
+     * Si plusieurs champs sont ciblés, méthode d’agrégation des valeurs.
+     * Exemple : SOMME, MULTIPLICATION
+     */
+    typeComputation?: TypeComputation;
+}
+/**
+ * Groupe de règles à combiner selon une logique AND ou OR
+ */
+interface ConditionalDisplayGroup {
+    rules: ConditionalDisplayRule | ConditionalDisplayRule[];
+    logic?: "AND" | "OR";
+}
+/**
+ * Represents the available validation types for form fields.
+ *
+ * - `"required"`: Ensures the field is not empty.
+ * - `"minLength"`: Validates that the field value meets a minimum length.
+ * - `"maxLength"`: Validates that the field value does not exceed a maximum length.
+ * - `"regex"`: Validates the field value against a regular expression pattern.
+ * - `"email"`: Ensures the field value is a valid email address.
+ * - `"number"`: Ensures the field value is a valid number.
+ * - `"fileSize"`: Validates the size of an uploaded file.
+ * - `"phone_number"`: Ensures the field value is a valid phone number.
+ * - `"textarea"`: Indicates the field is a textarea input.
+ * - `"fileType"`: Validates the type of an uploaded file.
+ */
+type ValidationType = "required" | "minLength" | "maxLength" | "regex" | "email" | "number" | "fileSize" | "phone_number" | "textarea" | "fileType";
+/**
+ * Represents a validation rule for a form field.
+ *
+ * @property validationType - The type of validation to apply (e.g., required, minLength, pattern).
+ * @property value - The value associated with the validation rule. This can be a number, a string, or an array of strings, depending on the validation type.
+ * @property errMsg - The error message to display if the validation fails.
+ */
+interface ValidationRule {
+    validationType?: ValidationType;
+    value?: number | string | string[];
+    errMsg: string;
+}
+/**
+ * Décrit la logique de répétition d’un groupe de champs selon une valeur numérique saisie dans un autre champ.
+ */
+interface RepeatRule {
+    /**
+     * Limite maximale du nombre de répétitions autorisées (optionnelle).
+     */
+    max?: number;
+    /**
+     * Limite minimale du nombre de répétitions requises (optionnelle).
+     */
+    min?: number;
+    /**
+     * Indique si on pré-remplit automatiquement un ensemble vide (utile pour le rendu initial).
+     */
+    prefillEmpty?: boolean;
+}
+interface FormRepeatGroup {
+    repeatGroupId: string;
+    fieldName: string;
+    label: string | {
+        [lang: string]: string;
+    };
+    minRepeats?: number;
+    maxRepeats?: number;
+    initialRepeats?: number;
+    formFields: FormField[];
+    position?: number;
+    conditionalDisplay?: ConditionalDisplayGroup;
+}
+declare enum SpecialField {
+    IMAGE = "IMAGE",
+    VIDEO = "VIDEO",
+    AUDIO = "AUDIO",
+    DOCUMENT = "DOCUMENT",
+    PDF = "PDF",
+    VOICE = "VOICE",
+    TIP_TAP_DOC_TEXT = "TIP_TAP_DOC_TEXT",
+    OTP = "OTP"
+}
+interface OTPFormFieldExecOptions {
+    serverDns: string;
+    /** Endpoint relatif, ex: /api/otp/send */
+    postApiEndPoint: string;
+    /** Payload à envoyer avec la requête OTP (sera fusionné avec les données du formulaire) */
+    payload?: Record<string, any> | Map<string, unknown>;
+    /** Headers additionnels à joindre à la requête */
+    extraHeaders?: Record<string, string>;
+    /** Token Bearer pour l'authentification */
+    bearer?: string;
+    /** Timeout en ms pour la requête */
+    timeoutMs?: number;
+    /** Nombre de cases OTP (défaut: 6) */
+    otpLength?: number;
+    /** Nom du champ Email qui doit déclencher l'envoi de l'OTP (dans une section précédente) */
+    linkedEmailFieldName?: string;
+    /** Configuration pour l'envoi initial de l'OTP (quand l'email est saisi). Si non défini, utilise la même config que la vérification */
+    sendOTPApiConfig?: {
+        serverDns: string;
+        postApiEndPoint: string;
+        payload?: Record<string, any> | Map<string, unknown>;
+        extraHeaders?: Record<string, string>;
+        bearer?: string;
+    };
+    /** Activer la validation automatique quand tous les chiffres sont saisis (défaut: false) */
+    autoValidate?: boolean;
+    /** Activer le bouton "Renvoyer le code" (défaut: true) */
+    enableResend?: boolean;
+    /** Délai minimum en secondes entre deux envois de code (défaut: 60) */
+    resendCooldownSeconds?: number;
+}
+interface EmailFormFieldExecOptions {
+    /** Si true, déclenche automatiquement l'envoi d'OTP quand l'email est validé */
+    triggerOTPSend?: boolean;
+    /** Nom du champ OTP lié (optionnel, pour validation) */
+    linkedOTPFieldName?: string;
+    /** Configuration API pour l'envoi d'OTP */
+    otpSendApiConfig?: {
+        serverDns: string;
+        postApiEndPoint: string;
+        payload?: Record<string, any> | Map<string, unknown>;
+        extraHeaders?: Record<string, string>;
+        bearer?: string;
+    };
+}
+interface OTPFormFieldLink {
+    fieldName: string;
+    fieldType: "email" | "favoris";
+}
+interface FileToBucketManage {
+    uploadOption: UploadOption;
+    deleteOption: DeleteOption;
+}
+/**
+ * Options pour l’upload d’un fichier vers le bucket.
+ * Correspond à POST /api/files/upload-file (ou /upload-files pour du multi).
+ */
+interface UploadOption {
+    /** Base URL du service, ex: https://bucket.urmaphalab.com */
+    serverDns: string;
+    /** Endpoint relatif, ex: /api/files/upload-file */
+    postApiEndPoint: string;
+    /**
+     * Payload non sérialisé : sera converti en multipart/form-data.
+     * Clés attendues par l’API :
+     * - file : File ou Blob (obligatoire)
+     * - secret_key : string (obligatoire)
+     * - folder_name : string (optionnel, défaut “general”)
+     * - filename : string (optionnel, sans extension)
+     * - files / filenames pour la variante multi-upload
+     */
+    payload?: Map<string, unknown> | Record<string, unknown>;
+    /** Optionnel : Authorization: Bearer ... si l’API évolue en nécessite */
+    bearer?: string;
+    /** Headers supplémentaires à joindre à la requête (hors Content-Type géré par FormData) */
+    extraHeaders?: Record<string, string>;
+    /** Timeout en ms, si l’on veut borner la requête */
+    timeoutMs?: number;
+    /** Optionnel : hook pour logger ou transformer la réponse brute */
+    onResponse?(response: Response): Promise<void>;
+}
+/**
+ * Options pour supprimer un fichier du bucket.
+ * Compatible avec:
+ *  - DELETE /api/files/delete-file
+ *  - DELETE /api/files/delete-file-by-url
+ */
+interface DeleteOption {
+    /** Base URL du service, ex: https://bucket.urmaphalab.com */
+    serverDns: string;
+    /** Endpoint relatif, ex: /api/files/delete-file */
+    deleteApiEndPoint: string;
+    /**
+     * Payload JSON envoyé en body (ou query string).
+     * Clés possibles suivant la route utilisée :
+     * - secret_key : string (obligatoire)
+     * - folder_name : string (optionnel, défaut “general”)
+     * - filename : string (obligatoire si delete-file)
+     * - file_url : string (obligatoire si delete-file-by-url)
+     */
+    payload?: Record<string, unknown> | Map<string, unknown>;
+    /** Optionnel : Authorization: Bearer ... */
+    bearer?: string;
+    /** Headers additionnels à envoyer */
+    extraHeaders?: Record<string, string>;
+    /** Timeout en ms pour cette requête */
+    timeoutMs?: number;
+    /** Optionnel : hook pour logger ou transformer la réponse brute */
+    onResponse?(response: Response): Promise<void>;
+}
+/**
+ * Represents a form field definition with metadata, validation, and display options.
+ *
+ * @property formFieldId - Unique identifier for the form field (UUID or generated).
+ * @property fieldName - Internal technical key for the field.
+ * @property slug - Optional, human-readable key for URLs or UI.
+ * @property dataLabel - Optional, label used for export or processing.
+ * @property fieldType - Type of the form field (e.g., text, dropdown, date, etc.).
+ * @property label - Field label, can be a string or a multilingual object.
+ * @property response - The response value or list of responses for the field.
+ * @property selectOptions - Optional, list of selectable options for select, radio, or checkbox fields.
+ * @property validations - Optional, array of validation rules for the field.
+ * @property position - Optional, display order of the field.
+ * @property placeholder - Optional, placeholder text, can be a string or multilingual object.
+ * @property tooltip - Optional, tooltip text, can be a string or multilingual object.
+ * @property helpText - Optional, help text, can be a string or multilingual object.
+ * @property example - Optional, example value, can be a string or multilingual object.
+ * @property conditionalDisplay - Optional, conditional display logic for the field.
+ */
+interface FormField {
+    formFieldId: string;
+    fieldName: string;
+    slug?: string;
+    fieldType: "text" | "textarea" | "dropdown" | "radio" | "checkbox" | "date" | "number" | "bool" | "file" | "password" | SpecialField;
+    label: string | {
+        [lang: string]: string;
+    };
+    repeatGroup?: FormRepeatGroup;
+    repeatRule?: RepeatRule;
+    response: ResponseInForm;
+    selectOptions?: SelectOption[];
+    validations?: ValidationRule[];
+    position?: number;
+    placeholder?: string | {
+        [lang: string]: string;
+    };
+    tooltip?: string | {
+        [lang: string]: string;
+    };
+    helpText?: string | {
+        [lang: string]: string;
+    };
+    example?: string | {
+        [lang: string]: string;
+    };
+    enableSearch?: boolean;
+    dynamicFilterRule?: DynamicFilterRule;
+    conditionalDisplay?: ConditionalDisplayGroup;
+    fileToBucketManage?: FileToBucketManage;
+    width?: "full" | "half";
+    otpFormFieldExecOptions?: OTPFormFieldExecOptions;
+    emailFormFieldExecOptions?: EmailFormFieldExecOptions;
+    flattenOnSubmit?: boolean;
+    detailInfos?: DetailInfosConfig;
+}
+/**
+ * Configuration pour générer automatiquement des champs de détails
+ * quand une option est sélectionnée dans un dropdown, radio ou checkbox.
+ *
+ * @property [optionValue] - Pour chaque valeur d'option, définir les champs de détails à générer
+ * @property formFields - Liste des champs à générer pour cette option
+ * @property label - Label optionnel pour le groupe de détails (peut être multilingue)
+ */
+interface DetailInfosConfig {
+    [optionValue: string]: {
+        formFields: FormField[];
+        label?: string | {
+            [lang: string]: string;
+        };
+    };
+}
+interface DynamicFilterRule {
+    dependentFieldName: string;
+    filterType: "exact" | "hierarchical";
+    dataSource: {
+        type: "static" | "external";
+        data: Record<string, DynamicFilteringDataSourceElement[]>;
+        endpoint?: string;
+    };
+    transform?: {
+        valueKey: string;
+        labelKey: string;
+    };
+}
+interface DynamicFilteringDataSourceElement {
+    value: string;
+    label: string | {
+        [lang: string]: string;
+    };
+}
+/**
+ * Sous-section regroupant des champs.
+ */
+/**
+ * Represents a subsection within a form structure.
+ *
+ * @property subSectionId - Unique identifier for the subsection.
+ * @property title - Optional title of the subsection. Can be a string, a localized object, or null.
+ * @property subTitle - Optional subtitle of the subsection. Can be a string, a localized object, or null.
+ * @property isSpacer - Optional visual spacer indicator (e.g., for visual separation).
+ * @property position - Optional display order of the subsection.
+ * @property formFields - Array of form fields contained in this subsection.
+ */
+interface Section {
+    sectionId: string;
+    title?: string | {
+        [lang: string]: string;
+    } | null;
+    subTitle?: string | {
+        [lang: string]: string;
+    } | null;
+    isSpacer?: string;
+    position?: number;
+    formFields: FormField[];
+    conditionalDisplay?: ConditionalDisplayGroup;
+}
+/**
+ * Structure complète d’un formulaire.
+ */
+/**
+ * Represents the structure of a form.
+ *
+ * @property name - The name of the form.
+ * @property provider - The author or provider of the form.
+ * @property description - A general description of the form.
+ * @property status - The activation status of the form. Can be "ACTIVE" or "INACTIVE".
+ * @property isDeclaration - Indicates if the form is an official declaration (1 = yes, 0 = no).
+ * @property isTest - Indicates if the form is a test form (1 = yes, 0 = no).
+ * @property version - (Optional) The version of the form.
+ * @property createdAt - (Optional) The ISO date when the form was created.
+ * @property updatedAt - (Optional) The ISO date when the form was last updated.
+ * @property sections - The sections that compose the form.
+ */
+interface FormTheme {
+    primaryColor?: string;
+}
+interface FormStructure {
+    name: string;
+    provider: string;
+    description: string;
+    status: "ACTIVE" | "INACTIVE";
+    isDeclaration: number;
+    isTest: number;
+    version?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    sections: Section[];
+    theme?: FormTheme;
+    layoutOptions?: FormEngineLayoutOptions;
+}
+interface FormEngineLayoutOptions {
+    paginationMode?: "byFields" | "bySection";
+    progressBarType?: ProgressBarType;
+    headerOptions?: HeaderOptions;
+    displayDeleteButton?: boolean;
+    containerStyles?: ContainerStylesOptions;
+}
+interface ProgressBarType {
+    type: "default_step" | "custom" | "pastel" | "linear" | "section_bubble" | "section_bubble_pastel";
+    colors?: {
+        background: string;
+        foreground: string;
+    };
+    visible?: boolean;
+}
+interface HeaderOptions {
+    visible?: boolean;
+    type: "default" | "custom";
+    customHeader?: React.ReactNode;
+}
+interface ContainerStyles {
+    borderColor?: string;
+    borderWidth?: string | number;
+    backgroundColor?: string;
+}
+interface ContainerStylesOptions {
+    mainContainer?: ContainerStyles;
+    sectionContainer?: ContainerStyles;
+}
+
+interface FormEngineProps {
+    form: FormStructure;
+    formId: string;
+    onSubmit: (data: Record<string, any>) => void;
+    currentLang?: string;
+    submitButtonText?: string;
+    paginationMode?: "byFields" | "bySection";
+}
+interface FieldValidationError {
+    fieldName: string;
+    fieldLabel: string;
+    errors: string[];
+}
+interface FormValidationResult {
+    isValid: boolean;
+    touched: boolean;
+    allRequiredFieldsFilled: boolean;
+    visibleFieldsCount: number;
+    requiredFieldsCount: number;
+    invalidFields?: FieldValidationError[];
+    untouchedRequiredFields?: FieldValidationError[];
+    emptyRequiredFields?: FieldValidationError[];
+}
+
+declare const FormEngine: React.FC<FormEngineProps>;
+
+export { type ConditionalDisplayGroup, type ConditionalDisplayRule, type ConditionalOperator, type ContainerStyles, type ContainerStylesOptions, type DeleteOption, type DetailInfosConfig, type DynamicFilterRule, type DynamicFilteringDataSourceElement, type EmailFormFieldExecOptions, type FieldValidationError, type FileToBucketManage, FormEngine, type FormEngineLayoutOptions, type FormEngineProps, type FormField, type FormRepeatGroup, type FormStructure, type FormTheme, type FormValidationResult, type HeaderOptions, type OTPFormFieldExecOptions, type OTPFormFieldLink, type ProgressBarType, type RepeatRule, type ResponseInForm, type Section, type SelectOption, SpecialField, type TypeComputation, type UploadOption, type ValidationRule, type ValidationType };