npm package: @springernature/form-validation
Description: Javascript module for client-side form validation with custom validation.
Author: SpringerNature
Latest version: 0.1.6

This is a client-side form validation utility.

It combines custom error messaging with the validation logic provided in modern browsers by the [Constrain Validation API](https://developer.mozilla.org/en-US/docs/Web/HTML/Guides/Constraint_validation) and the associated form validation HTML attributes, It provides a custom error message using the [elements eds-c-error component](https://github.com/springernature/elements/tree/main/components/eds-c-error-message). 

It allows for and encourages custom validation messages for  to override browser default messaging which are inconsistent across browsers. It also allows for registration of custom validation functions and messaging  on initialisation of the library. 

Custom error messages for the required validation case are added using a data attribute, it is reccomendd to set this to avoid inconsistent messaging cross browser :

```html
<input type="text" value="" data-validation-custom-error="This field is definitely required" >

```

 In addition, custom validation functions should be specified per field using data attributes

 ```html
<input type="text" value="" data-validation-is-doi-starts-with-ten data-validation-is-valid-doi>
```

 
To set up validation import the library and set up a configuration object with custom values:

```js
import createValidatorLibrary from '@springernature/form-validation';


const validator = createValidatorLibrary({
    errorMessages: { required: 'This field is required.' },
    errorTemplateSelector: '#error-message-template'
});
```

To add client side validation to all forms on the page include the following on document ready:

```js

validator.trackAndValidateForms();

```

## Configuration values


**errorTemplateSelector:** Here you can define a selector for your error messages.

**errorMessages:** custom error messages for the following HTML validation types: required, minimumLength, maximumLength, badInput, typeMismatch. Here you can also add error messages for any custom validation functions you have added or the two custom validation functions included with the library:  'forbidTrailingWhitespace' and
'isEqualToField'.

**eventTrackingFunction:** This config value allows you to set GA4 event tracking function used to dispatch events on failed form submission and display of validation failure messages. This should make use of the function exposed on the globalThis object under the following namespace: globalThis.SN.libs.analytics.track. The function should accept an object with properties such as : track, trackValue, trackContext. 
Following the conventions found here:https://analytics-enablement.public.springernature.app/. For example: 
```js 
{
    track: "form_submit_error",
    value:  "failed_submission",
    context: "some content"
} 
``` 

**eventTrackingData:** With this object callers can extend or override any of the default tracking properties when creating the validator library. Be careful using this as it is used in multiple places across the library, but it can be useful if you want to set a custom event name for tracking form submission errors for example:

```js 
    eventTrackingData: {
        track: 'custom_event_name',
        additionalProperty: 'some_value'
    }
``` 

**customValidators:** This defines custom validation function, the name must match with a data attribute and a custom error message defined in 'errorMessages'.

For example: 

```js
const validator = createValidatorLibrary({
    errorTemplateSelector: '#error-message-template',
    errorMessages: {
        isDoiStartsWithTen: 'Your DOI must begin with 10',
        isValidDoi: 'Your DOI must follow the correct syntax'
        },
        customValidators: {
            isDoiStartsWithTen: (input) => {
                const doiPattern = /^10/;
                return doiPattern.test(input.value);
            },
            isValidDoi: (input) =>  {
                const doiPattern = /^10.\d{4,9}\/[-._;()/:A-Z0-9]+$/i;
                return doiPattern.test(input.value);
            }
        });
```    
For custom validation functions to work, they must be matched with a custom data attribute which must be added to any form input that you wish to validate against. For the example above: 

```html
<input type="text" value="" data-validation-is-doi-starts-with-ten data-validation-is-valid-doi>
```