@keysdown/form-wrapper 1.0.2 → 2.0.0

package/README.md

@@ -9,7 +9,11 @@
   <img src="https://img.shields.io/github/license/keysdown/form-wrapper.svg" alt="MIT"/>
 </p>
 
-> A package that allows you to easily manage forms, with Form Wrapper it is possible to perform validations with error messages, in addition to managing the state of the forms.
+> A zero-dependency, framework-agnostic form state management library with a plugin-based validation system. Manage form fields, validate with customizable error messages, and extend with built-in validation rules, only importing what you need.
+
+<p align="center">
+  <strong>Bundle size (minified + gzip):</strong> ~1.5 kB core / ~3 kB with all 33 rules
+</p>
 
 ## Installation
 
@@ -39,6 +43,211 @@ const form = ref(new FormWrapper({
 }))
 ```
 
+## Validation Plugins
+
+Validation rules are loaded via a plugin system, no rules are bundled in core. This keeps the base library minimal and lets you import only what you need.
+
+### Loading all rules
+
+Use the `formValidation` plugin to register all 33 validation rules at once:
+
+```js
+import FormWrapper from '@keysdown/form-wrapper'
+import formValidation from '@keysdown/form-wrapper/plugins/formValidation'
+
+FormWrapper.extend(formValidation)
+```
+
+### Default error messages with locales
+
+Validation rules have built-in default error messages. By default, messages are in **English**. You can change the language by loading a locale:
+
+```js
+import FormWrapper from '@keysdown/form-wrapper'
+import formValidation from '@keysdown/form-wrapper/plugins/formValidation'
+import pt from '@keysdown/form-wrapper/plugins/locales/pt'
+
+FormWrapper.extend(formValidation)
+FormWrapper.locale(pt) // switch to Portuguese
+```
+
+Available locales: `en` (English, default), `pt` (Portuguese), `es` (Spanish).
+
+Default messages support **interpolation**, placeholders like `:field`, `:min`, `:max`, `:size`, `:digits`, `:other`, `:values` are replaced with actual values:
+
+```
+The first name field is required.
+The password must be at least 6.
+```
+
+### Custom field display names with `attribute`
+
+By default, the `:field` placeholder uses the field name with underscores replaced by spaces (e.g., `first_name` → "first name"). You can customize this with the `attribute` property:
+
+```js
+const form = new FormWrapper({
+    email: {
+        value: null,
+        validation: {
+            rules: ['required', 'email']
+        },
+        attribute: 'contact email'
+    }
+})
+
+// Default error message would show:
+// "The contact email field is required."
+// instead of "The email field is required."
+```
+
+```js
+const form = new FormWrapper({
+    password: {
+        value: null,
+        validation: {
+            rules: ['required', 'min:8']
+        },
+        attribute: 'senha'
+    }
+})
+
+// With pt locale: "O campo senha deve ter no mínimo 8."
+```
+
+User-provided messages always **override** default messages:
+
+```js
+const form = new FormWrapper({
+    email: {
+        value: null,
+        validation: {
+            rules: ['required', 'email'],
+            messages: {
+                required: 'Email is required.' // overrides the default message
+                // email uses the default locale message
+            }
+        }
+    }
+})
+```
+
+### Tree-shaking individual rules
+
+Import only the rules you need and use them directly in the `rules` array for tree-shaking:
+
+```js
+import FormWrapper from '@keysdown/form-wrapper'
+import { required, email } from '@keysdown/form-wrapper/plugins/rules'
+
+const form = new FormWrapper({
+    email: {
+        value: null,
+        validation: {
+            rules: [required, email],
+            messages: {
+                required: 'The email field is required.',
+                email: 'The email must be a valid address.'
+            }
+        }
+    }
+})
+```
+
+You can also mix function rules with string rules (useful for parameterized rules like `min:6`):
+
+```js
+import { required, email } from '@keysdown/form-wrapper/plugins/rules'
+
+rules: [required, email, 'min:6']
+```
+
+### Custom rules
+
+Add inline validation rules directly in the `rules` array. A custom rule receives a destructured object `{value, fail, form, field}`:
+
+```js
+const form = createForm({
+    email: {
+        value: null,
+        validation: {
+            rules: [({value, fail}) => {
+                if (!value) fail('The email field is required.')
+            }]
+        }
+    }
+})
+```
+
+Access other form fields via the `form` parameter:
+
+```js
+const form = createForm({
+    password: { value: null, validation: {rules: []} },
+    password_confirmation: {
+        value: null,
+        validation: {
+            rules: [({value, fail, form}) => {
+                if (value !== form.password) fail('Passwords do not match.')
+            }]
+        }
+    }
+})
+```
+
+Custom rules support **async** validation (e.g., API calls):
+
+```js
+const form = createForm({
+    email: {
+        value: null,
+        validation: {
+            rules: [async ({value, fail}) => {
+                const response = await fetch(`/api/check-email?email=${encodeURIComponent(value)}`)
+                const { available } = await response.json()
+                if (!available) fail('This email is already taken.')
+            }]
+        }
+    }
+})
+```
+
+You can mix custom rules with built-in rules:
+
+```js
+import { required, email } from '@keysdown/form-wrapper/plugins/rules'
+
+const form = createForm({
+    email: {
+        value: null,
+        validation: {
+            rules: [
+                required,
+                email,
+                async ({value, fail}) => {
+                    const response = await fetch(`/api/check-email?email=${encodeURIComponent(value)}`)
+                    const { available } = await response.json()
+                    if (!available) fail('This email is already taken.')
+                }
+            ],
+            messages: {
+                required: 'The email field is required.',
+                email: 'The email must be a valid address.'
+            }
+        }
+    }
+})
+```
+
+### Static methods on FormWrapper
+
+| Method | Description |
+|---|---|
+| `FormWrapper.extend(plugin)` | Register a plugin (e.g., `formValidation`) |
+| `FormWrapper.addRule(name, handler)` | Register a single validation rule |
+| `FormWrapper.locale(locale)` | Set the default error messages locale |
+| `FormWrapper.rules` | Static rule registry |
+| `FormWrapper.defaultMessages` | Static default messages registry |
+
 ## Basic example
 
 Basic example using Vue.
@@ -99,29 +308,38 @@ Basic example with validation using Vue.
 <script setup lang="ts">
   import axios from 'axios'
   import {ref} from 'vue'
-  import {createForm} from '@keysdown/form-wrapper'
+  import FormWrapper from '@keysdown/form-wrapper'
+  import formValidation from '@keysdown/form-wrapper/plugins/formValidation'
 
-  const form = ref(createForm({
+  FormWrapper.extend(formValidation)
+
+  const form = ref(new FormWrapper({
     first_name: {
       value: null,
-      rules: ['required'],
-      messages: {
-        required: 'The first name field is required.'
+      validation: {
+        rules: ['required'],
+        messages: {
+          required: 'The first name field is required.'
+        }
       }
     },
     last_name: {
       value: null,
-      rules: ['required'],
-      messages: {
-        required: 'The last name field is required.'
+      validation: {
+        rules: ['required'],
+        messages: {
+          required: 'The last name field is required.'
+        }
       }
     },
     username: {
       value: null,
-      rules: ['required', 'min:6'],
-      messages: {
-        required: 'The username field is required.',
-        min: 'The username field must have at least 6 characters'
+      validation: {
+        rules: ['required', 'min:6'],
+        messages: {
+          required: 'The username field is required.',
+          min: 'The username field must have at least 6 characters'
+        }
       }
     }
   }))
@@ -150,7 +368,6 @@ Basic example with validation using Vue.
 </script>
 ```
 
-
 ## Form methods
 
 ### addField(field, value)
@@ -161,6 +378,7 @@ Method used to add a single field to the form.
 form.addField('username', null)
 
 form.addField('username', {
+    value: null,
     validation: {
         rules: ['required'],
         messages: {
@@ -182,6 +400,7 @@ form.addFields({
 
 form.addFields({
     full_name: {
+        value: null,
         validation: {
             rules: ['required'],
             messages: {
@@ -190,6 +409,7 @@ form.addFields({
         }
     },
     username: {
+        value: null,
         validation: {
             rules: ['required'],
             messages: {
@@ -268,6 +488,44 @@ form.reset()
 console.log(form.values()) // {username: null}
 ```
 
+### wasChanged(field)
+
+Method used to check if one or more fields have been changed from their original values. When an array is provided, returns `true` if **any** of the fields were changed.
+
+```js
+const form = createForm({
+    name: null,
+    username: null
+})
+
+console.log(form.wasChanged('username')) // false
+
+form.username = 'keysdown'
+
+console.log(form.wasChanged('username')) // true
+
+console.log(form.wasChanged(['name', 'username'])) // true (any changed)
+```
+
+### filled(field)
+
+Method used to check if one or more fields are filled (not `null`, not `undefined`, not empty string `''`). When an array is provided, returns `true` only if **all** fields are filled.
+
+```js
+const form = createForm({
+    name: null,
+    username: null
+})
+
+form.username = 'keysdown'
+
+console.log(form.filled('username')) // true
+
+console.log(form.filled('name')) // false
+
+console.log(form.filled(['name', 'username'])) // false (name is not filled)
+```
+
 ### setAwaiting(awaiting = true)
 
 Method used to change the form loading state.
@@ -296,9 +554,11 @@ Method used to validate the entire form or a specific field.
 const form = createForm({
     username: {
         value: null,
-        rules: ['required'],
-        messages: {
-            required: 'The username field is required.'
+        validation: {
+            rules: ['required'],
+            messages: {
+                required: 'The username field is required.'
+            }
         }
     }
 })
@@ -330,9 +590,11 @@ Method used to validate a specific field.
 const form = createForm({
     username: {
         value: null,
-        rules: ['required'],
-        messages: {
-            required: 'The username field is required.'
+        validation: {
+            rules: ['required'],
+            messages: {
+                required: 'The username field is required.'
+            }
         }
     }
 })
@@ -364,9 +626,11 @@ Method used to validate the entire form.
 const form = createForm({
     username: {
         value: null,
-        rules: ['required'],
-        messages: {
-            required: 'The username field is required.'
+        validation: {
+            rules: ['required'],
+            messages: {
+                required: 'The username field is required.'
+            }
         }
     }
 })
@@ -500,6 +764,16 @@ form.messages.first('username')
 form.rules.first('username')
 ```
 
+#### get(key)
+
+Returns the value for the given key, or `null` if not found.
+
+```js
+form.errors.get('username')
+form.messages.get('username')
+form.rules.get('username')
+```
+
 #### any()
 
 Returns true if the collection has any items and false if it is empty.
@@ -543,15 +817,16 @@ form.messages.push('username', {
     required: 'The username field is required.'
 })
 
-form.rules.push('username', 'required')
+form.rules.push('username', ['required'])
 ```
 
 #### has(key)
 
-Checking if the collection has an item with the key.
+Checking if the collection has an item with the key. Accepts a single key or an array of keys. When an array is provided, returns `true` if **any** of the keys exist.
 
 ```js
 form.errors.has('username')
+form.errors.has(['username', 'email'])
 form.messages.has('username')
 form.rules.has('username')
 ```
@@ -566,7 +841,7 @@ form.messages.unset('username')
 form.rules.unset('username')
 ```
 
-#### clear(key)
+#### clear()
 
 Clears the entire collection, making it empty.
 
@@ -578,8 +853,44 @@ form.rules.clear()
 
 ### Validation rules
 
-There are some predefined validation rules that you can use in the form:
-
-#### required
-
-Used when a field is required
+The `formValidation` plugin provides 33 validation rules. Rules are loaded via plugins, see [Validation Plugins](#validation-plugins) for setup instructions.
+
+| Rule | Parameters | Description |
+|---|---|---|
+| `required` | — | Field must be present and not empty |
+| `email` | — | Must be a valid email address |
+| `url` | — | Must be a valid URL |
+| `min` | `min:6` | Minimum length (string) or value (number) or count (array) |
+| `max` | `max:255` | Maximum length/value/count |
+| `between` | `between:1,10` | Between min and max |
+| `size` | `size:10` | Exact length/value/count |
+| `alpha` | — | Only alphabetic characters |
+| `alphaNumeric` | — | Only letters and numbers |
+| `string` | — | Must be a string |
+| `integer` | — | Must be an integer |
+| `numeric` | — | Must be numeric |
+| `array` | — | Must be an array |
+| `boolean` | — | Must be boolean (true, false, 0, 1, '0', '1') |
+| `date` | — | Must be a valid date |
+| `same` | `same:field` | Must match another field |
+| `different` | `different:field` | Must differ from another field |
+| `confirmed` | `confirmed:field` | Must match field_confirmation |
+| `in` | `in:admin,user` | Value must be in list |
+| `notIn` | `notIn:admin,user` | Value must not be in list |
+| `regex` | `regex:/pattern/` | Must match regex pattern |
+| `startsWith` | `startsWith:foo,bar` | Must start with one of the values |
+| `endsWith` | `endsWith:foo,bar` | Must end with one of the values |
+| `digits` | `digits:4` | Must have exactly N digits |
+| `digitsBetween` | `digitsBetween:3,6` | Must have between min and max digits |
+| `ip` | — | Must be a valid IP (v4 or v6) |
+| `json` | — | Must be a valid JSON string |
+| `uuid` | — | Must be a valid UUID |
+| `lessThan` | `lessThan:field` | Numeric value less than another field |
+| `greaterThan` | `greaterThan:field` | Numeric value greater than another field |
+| `lessThanOrEqual` | `lessThanOrEqual:field` | Less than or equal to another field |
+| `greaterThanOrEqual` | `greaterThanOrEqual:field` | Greater than or equal to another field |
+| `nullable` | — | Allows null/empty (always passes) |
+
+## License
+
+[MIT](LICENSE)

package/dist/form-wrapper.cjs

@@ -1 +1 @@
-Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});var e=e=>typeof e==`string`?e.split(`|`):e,t=t=>({validation:{rules:t.validation?.rules?e(t.validation.rules):[],messages:t.validation?.messages??{}},value:t.value??null}),n=class{collection={};all(){return this.collection}first(e){let t=this.get(e);if(t){let e=Array.isArray(t)?t[0]:t;if(e)return String(e)}return null}any(){return Object.keys(this.collection).length>0}fill(e){return this.collection=e,this}push(e,t){return this.collection={...this.collection,[e]:t},this}has(e){return this.collection.hasOwnProperty(e)}get(e,t=null){return this.has(e)?this.collection[e]:t}unset(e){return this.has(e)&&delete this.collection[e],this}clear(){return this.collection={},this}},r=class extends n{},i=class extends n{},a=class extends n{push(e,t){let n=this.get(e)||[];return this.collection={...this.collection,[e]:[...n,t]},this}get(e){return super.get(e,[])}},o=class{errors=new a;messages=new r;rules=new i},s={required:e=>new Promise((t,n)=>{if(e==null)return n();String(e).replace(/\s/g,``).length>0?t(e):n()})},c=e=>typeof e==`object`&&!!e&&!Array.isArray(e),l=(e,t,n=null)=>{let r=t||new FormData;return Object.keys(e).forEach(t=>{let i=e[t];if(t=n?`${n}[${t}]`:t,!([void 0,null].indexOf(i)>-1)){if(c(i)&&!(i instanceof File)||Array.isArray(i)){l(i,r,t);return}r.append(t,i)}}),r},u=class{awaiting=!1;originalValues={};validation=new o;constructor(e){this.addFields(e)}addField(e,n){if(typeof n==`object`&&n&&Object.prototype.toString.call(n)===`[object Object]`&&`value`in n){let r=t(n);this[e]=r.value,this.originalValues[e]=r.value,this.validation.messages.push(e,r.validation.messages),this.validation.rules.push(e,r.validation.rules)}else this[e]=n,this.originalValues[e]=n;return this}addFields(e){return Object.keys(e).forEach(t=>{this.addField(t,e[t])}),this}get errors(){return this.validation.errors}fill(e,t=!1){return Object.keys(e).forEach(n=>{let r=e[n];t&&(this.originalValues[n]=r),this[n]=r}),this}get messages(){return this.validation.messages}removeField(e){return delete this[e],delete this.originalValues[e],this.validation.errors.unset(e),this.validation.messages.unset(e),this.validation.rules.unset(e),this}removeFields(e){return e.forEach(e=>{this.removeField(e)}),this}reset(){return this.validation.errors.clear(),Object.keys(this.originalValues).forEach(e=>{this[e]=this.originalValues[e]}),this}get rules(){return this.validation.rules}setAwaiting(e=!0){return this.awaiting=e,this}validate(e=null){return e?this.validateField(e):this.validateForm()}validateField(e){this.validation.errors.unset(e);let t=this.validation.rules.get(e);if(t&&t.length>0){let n=t.map(t=>{let n=t.split(`:`),r=n[0],i=n.length===2?n[1].split(`,`):[];return r in s?s[r](this[e],i).catch(t=>{let n=this.validation.messages.get(e);return n&&r in n&&this.validation.errors.push(e,n[r]),Promise.reject(t)}):Promise.reject(Error(`There is no validation rule called "${r}"`))});return Promise.all(n).then(()=>{})}return Promise.resolve()}validateForm(){let e=Object.keys(this.originalValues).map(e=>this.validateField(e));return Promise.all(e).then(()=>Promise.resolve(this)).catch(()=>Promise.reject(this))}values(e){let t={};return Object.keys(this.originalValues).forEach(n=>{(!e||e.includes(n))&&(t[n]=this[n])}),t}valuesAsFormData(e){return l(this.values(e))}},d=e=>new u(e),f=u;exports.createForm=d,exports.default=f;
+Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});var e=e=>{if(typeof e==`string`){let t=[],n=e;for(;n.length>0;){let e=n.indexOf(`regex:`);if(e!==-1){let r=n.substring(0,e);r&&t.push(...r.split(`|`).filter(Boolean));let i=n.substring(e),a=i.indexOf(`:/`);if(a!==-1){let e=a+1,r=i.lastIndexOf(`/`);if(r>e){let e=i.substring(r+1),a=e.match(/^[gimsuy]*/)[0],o=i.substring(0,r+1+a.length);t.push(o),n=e.substring(a.length),n.startsWith(`|`)&&(n=n.substring(1));continue}}t.push(i);break}else{t.push(...n.split(`|`).filter(Boolean));break}}return t}return e},t=t=>({validation:{rules:t.validation?.rules?e(t.validation.rules):[],messages:t.validation?.messages??{}},value:t.value??null}),n=class{collection={};all(){return this.collection}first(e){let t=this.get(e);if(t!==null){let e=Array.isArray(t)?t[0]:t;if(e!=null)return String(e)}return null}any(){return Object.keys(this.collection).length>0}fill(e){return this.collection=e,this}push(e,t){return this.collection={...this.collection,[e]:t},this}has(e){return Array.isArray(e)?e.some(e=>this.collection.hasOwnProperty(e)):this.collection.hasOwnProperty(e)}get(e,t=null){return this.has(e)?this.collection[e]:t}unset(e){return this.has(e)&&delete this.collection[e],this}clear(){return this.collection={},this}},r=class extends n{},i=class extends n{},a=class extends n{push(e,t){let n=this.get(e)||[];return this.collection={...this.collection,[e]:[...n,t]},this}get(e){return super.get(e,[])}},o=class{errors=new a;messages=new r;rules=new i},s=e=>typeof e==`object`&&!!e&&!Array.isArray(e),c=(e,t,n=null)=>{let r=t||new FormData;return Object.keys(e).forEach(t=>{let i=e[t];if(t=n?`${n}[${t}]`:t,!([void 0,null].indexOf(i)>-1)){if(s(i)&&!(i instanceof File)||Array.isArray(i)){c(i,r,t);return}r.append(t,i)}}),r},l=class e{static rules={};static defaultMessages={};static interpolateMessage(e,t,n,r){let i=r[t]||t.replace(/_/g,` `);return e.replace(/:field/g,i).replace(/:min/g,n[0]||``).replace(/:max/g,n[1]||``).replace(/:size/g,n[0]||``).replace(/:digits/g,n[0]||``).replace(/:other/g,n[0]?r[n[0]]||n[0].replace(/_/g,` `):``).replace(/:values/g,n.join(`, `))}awaiting=!1;originalValues={};fieldAttributes={};validation=new o;constructor(e){this.addFields(e)}static extend(t){return t(e,e.rules),e}static addRule(t,n){return e.rules[t]=Object.assign(n,{ruleName:t}),e}static locale(t){return e.defaultMessages=t.messages,e}addField(e,n){if(typeof n==`object`&&n&&Object.prototype.toString.call(n)===`[object Object]`&&`value`in n){let r=t(n);this[e]=r.value,this.originalValues[e]=r.value,this.validation.messages.push(e,r.validation.messages),this.validation.rules.push(e,r.validation.rules),n.attribute&&(this.fieldAttributes[e]=n.attribute)}else this[e]=n,this.originalValues[e]=n;return this}addFields(e){return Object.keys(e).forEach(t=>{this.addField(t,e[t])}),this}get errors(){return this.validation.errors}fill(e,t=!1){return Object.keys(e).forEach(n=>{let r=e[n];t&&(this.originalValues[n]=r),this[n]=r,n in this.originalValues||(this.originalValues[n]=r)}),this}get messages(){return this.validation.messages}removeField(e){return delete this[e],delete this.originalValues[e],delete this.fieldAttributes[e],this.validation.errors.unset(e),this.validation.messages.unset(e),this.validation.rules.unset(e),this}removeFields(e){return e.forEach(e=>{this.removeField(e)}),this}reset(){return this.validation.errors.clear(),Object.keys(this.originalValues).forEach(e=>{this[e]=this.originalValues[e]}),this}wasChanged(e){return Array.isArray(e)?e.some(e=>this[e]!==this.originalValues[e]):this[e]!==this.originalValues[e]}filled(e){return Array.isArray(e)?e.every(e=>this[e]!==null&&this[e]!==void 0&&this[e]!==``):this[e]!==null&&this[e]!==void 0&&this[e]!==``}get rules(){return this.validation.rules}setAwaiting(e=!0){return this.awaiting=e,this}validate(e=null){return e?this.validateField(e):this.validateForm()}validateField(t){this.validation.errors.unset(t);let n=this.validation.rules.get(t);if(n&&n.length>0){let r=this.constructor.rules;return(async()=>{for(let i of n){let n=i;if(typeof n==`function`){if(`ruleName`in n){let r=n.ruleName;if(r===`nullable`&&(this[t]===null||this[t]===void 0||this[t]===``))return;try{await n(this[t],[],this,t)}catch(n){let i=this.validation.messages.get(t);throw r&&i&&r in i?this.validation.errors.push(t,i[r]):r in e.defaultMessages&&this.validation.errors.push(t,e.interpolateMessage(e.defaultMessages[r],t,[],this.fieldAttributes)),n}}else await new Promise((e,r)=>{let i=!1,a=e=>{i=!0,e&&this.validation.errors.push(t,e)};try{let o=n({value:this[t],fail:a,form:this,field:t});o instanceof Promise?o.then(()=>{i?r():e()}).catch(()=>{r()}):i?r():e()}catch{r()}});continue}let a=n.indexOf(`:`),o=a===-1?n:n.substring(0,a);if(o===`nullable`&&(this[t]===null||this[t]===void 0||this[t]===``))return;let s=a===-1?[]:n.substring(a+1).split(`,`);if(o in r)try{await r[o](this[t],s,this,t)}catch(n){let r=this.validation.messages.get(t);throw r&&o in r?this.validation.errors.push(t,r[o]):o in e.defaultMessages&&this.validation.errors.push(t,e.interpolateMessage(e.defaultMessages[o],t,s,this.fieldAttributes)),n}else throw Error(`There is no validation rule called "${o}"`)}})()}return Promise.resolve()}validateForm(){let e=Object.keys(this.originalValues).map(e=>this.validateField(e));return Promise.all(e).then(()=>Promise.resolve(this)).catch(()=>Promise.reject(this))}values(e){let t={};return Object.keys(this.originalValues).forEach(n=>{(!e||e.includes(n))&&(t[n]=this[n])}),t}valuesAsFormData(e){return c(this.values(e))}},u=e=>new l(e),d=l;exports.createForm=u,exports.default=d;