@steveesamson/microform 0.0.10 → 1.0.0

package/README.md

@@ -25,18 +25,23 @@ Once you've added `microform` to your project, use it as shown below, in your vi
 ### In the view Script
 
 ```ts
-<script lang='ts'>
+<script>
 import uForm from "@steveesamson/microform";
 // default form data, probably passed as props
-export let defaultData:any = {};
+let defaultData:any = $props();
 
 // Instatiate microform
-const { form, values, errors, submit, valid } = uForm({
+const { form, values, errors, submit, sanity } = uForm({
     // Set default form data
     data:{...defaultData},
     // Set a global event for validation, can be overriden on a each field.
     // Possible values: blur, change, input, keyup
-    validateEvent:'blur'
+    options:{
+        // Default event that triggers validation
+        validateEvent:'blur',
+        // Configure validators here
+        validators:{}
+    }
 });
 
 // Submit handler
@@ -51,11 +56,11 @@ const onSubmit = (data:unknown) => {
 
 On the instantiation of `microform`, we have access to:
 
-- `values`, a `FormValues`, which is a `svelte store` for form data.
-- `errors`, a `FormErrors`, which is a `svelte store` for form errors.
+- `values`, a `FormValues`, which represents form data.
+- `errors`, a `FormErrors`, which represents form errors.
 - `form`, which is a `svelte action` that actually does the `microform` magic.
 - `submit`, which is another `svelte action` to handle form submission.
-- `valid`, a `FormSanity`, which is a `svelte store` that tells if a form is clean/without errors.
+- `sanity`, a `FormSanity`, which tells us if a form is clean/without errors by it's `ok` property.
 - `reset`, a function to reset form
 - `onsubmit`, a function to handle form submission.
 
@@ -63,91 +68,162 @@ On the instantiation of `microform`, we have access to:
 
 ```html
     <form use:submit={onSubmit}>
-        <label for='username'>
-            Username:
-            <input
-            type='text'
-            name='username'
-            id='username'
-            use:form
-            data-validations='required'>
-            {#if $errors.username}
-            <small>{$errors.username}</small>
-            {/if}
-        </label>
-         <label for='email_account'>
-            Email Account:
-            <input
-            type='text'
-            name='email_account'
-            id='email_account'
-            use:form={{
-                validations:'required|email'
-            }}/>
-            {#if $errors.email_account}
-            <small>{$errors.email_account}</small>
-            {/if}
-        </label>
-        <label for='gender'>
-            Gender:
-            <select
-            name='gender'
-            id='gender'
-            use:form={{
-                validations:'required',
-                validateEvent:'change'
-            }}>
-                <options value=''>Gender please</option>
-                <options value='F'>Female</option>
-                <options value='M'>Male</option>
-                </select>
-            {#if $errors.gender}
-            <small>{$errors.gender}</small>
-            {/if}
-        </label>
-        <label for='password'>
-            Password:
-            <input
-            type='text'
-            name='password'
-            id='password'
-            use:form
-            data-validations='required'>
-            {#if $errors.password}
-            <small>{$errors.password}</small>
-            {/if}
-        </label>
-         <label for='confirm_password'>
-            Confirm password:
-            <input
-            type='text'
-            name='confirm_password'
-            id='confirm_password'
-            use:form
-            data-validations='required|match:password'>
-            {#if $errors.confirm_password}
-            <small>{$errors.confirm_password}</small>
-            {/if}
-        </label>
-        <label for="story">
-        Story:
-            <div
-                contenteditable="true"
-                use:form={{
-                    validateEvent: 'input',
-                    validations: 'required',
-                    name: 'story',
-                    html: true
-                }}
-            />
-            {#if $errors.story}
-                <small>{$errors.story}</small>
-            {/if}
-        </label>
+        <label for="fullname">
+			Name:
+			<input 
+			type="text" 
+			name="fullname" 
+			id="fullname" 
+			use:form={{ validations: ['required'] }} 
+			/>
+			{#if errors.fullname}
+				<small>{errors.fullname}</small>
+			{/if}
+		</label>
+		<label for="dob">
+			DOB:
+			<input 
+			type="date" 
+			name="dob" 
+			id="dob" 
+			use:form={{ validations: ['required'] }} 
+			/>
+			{#if errors.dob}
+				<small>{errors.dob}</small>
+			{/if}
+		</label>
+		<label for="supper_time">
+			Supper time:
+			<input
+				type="time"
+				name="supper_time"
+				id="supper_time"
+				use:form={{ validations: ['required'] }}
+			/>
+			{#if errors.supper_time}
+				<small>{errors.supper_time}</small>
+			{/if}
+		</label>
+		<label for="password">
+			Password:
+			<input
+				type="password"
+				name="password"
+				id="password"
+				use:form={{ validations: ['required'] }}
+			/>
+			{#if errors.password}
+				<small>{errors.password}</small>
+			{/if}
+		</label>
+		<label for="gender">
+			Gender:
+			<select
+				name="gender"
+				id="gender"
+				use:form={{ validateEvent: 'change', validations: ['required'] }}
+			>
+				<option value="">Select gender</option>
+				<option value="M">Male</option>
+				<option value="F">Female</option>
+			</select>
+			{#if errors.gender}
+				<small>{errors.gender}</small>
+			{/if}
+		</label>
+		<label for="email">
+			Email:
+			<input
+				type="text"
+				name="email"
+				id="email"
+				use:form={{ validations: ['required', 'email'] }}
+			/>
+			{#if errors.email}
+				<small>{errors.email}</small>
+			{/if}
+		</label>
+        <label for="resume">
+			Resume:
+			<input
+				type="file"
+				name="resume"
+				id="resume"
+				use:form={{ 
+					validateEvent:'change', 
+					validations: ['required', 'file-size-mb:3'] 
+				}}
+			/>
+			{#if errors.resume}
+				<small>{errors.resume}</small>
+			{/if}
+		</label>
+		<label for="comment">
+			Comment:
+			<textarea 
+			name="comment" 
+			id="comment" 
+			use:form={{ validations: ['required'] }}
+			></textarea>
+			{#if errors.comment}
+				<small>{errors.comment}</small>
+			{/if}
+		</label>
+		<label for="beverage">
+			Beverage:
+			{#each items as item (item.value)}
+				<span>
+					<input
+						type="radio"
+						name="beverage"
+						value={item.value}
+						use:form={{ validateEvent: 'input', validations: ['required'] }}
+						bind:group={values.beverage}
+					/>
+					{item.label}
+				</span>
+			{/each}
+			{#if errors.beverage}
+				<small>{errors.beverage}</small>
+			{/if}
+		</label>
+		<label for="favfoods">
+			Fav Foods:
+			{#each foods as item (item.value)}
+				<span>
+					<input
+						type="checkbox"
+						name="favfoods"
+						value={item.value}
+						use:form={{ validateEvent: 'change', validations: ['required'] }}
+						bind:group={values['favfoods']}
+					/>
+					{item.label}
+				</span>
+			{/each}
+			{#if errors.favfoods}
+				<small>{errors.favfoods}</small>
+			{/if}
+		</label>
+		<label for="story">
+			Story:
+			<div
+				contenteditable="true"
+				use:form={{ 
+				 	validateEvent: 'input', 
+					validations: ['required'], 
+					name: 'story', 
+					html: true 
+				}}
+			></div>
+			{#if errors.story}
+				<small>{errors.story}</small>
+			{/if}
+		</label>
 
         <button
         type='submit'
-        disabled={!$valid}>
+        disabled={!sanity.ok}>
             Submit form
         </button>
     </form>
@@ -159,9 +235,16 @@ While the above example uses the `submit` action of `microform`, form could also
 <form>
 	<label for="password">
 		Password:
-		<input type="text" name="password" id="password" use:form data-validations="required" />
-		{#if $errors.password}
-		<small>{$errors.password}</small>
+		<input 
+            type="text" 
+            name="password" 
+            id="password" 
+            use:form={{
+				validations: ['required']
+            }}
+        />
+		{#if errors.password}
+		<small>{errors.password}</small>
 		{/if}
 	</label>
 	<label for="confirm_password">
@@ -170,15 +253,16 @@ While the above example uses the `submit` action of `microform`, form could also
 			type="text"
 			name="confirm_password"
 			id="confirm_password"
-			use:form
-			data-validations="required|match:password"
+			use:form={{
+				validations: ['required','match:password'], 
+            }}
 		/>
-		{#if $errors.confirm_password}
-		<small>{$errors.confirm_password}</small>
+		{#if errors.confirm_password}
+		<small>{errors.confirm_password}</small>
 		{/if}
 	</label>
 
-	<button type="button" disabled="{!$valid}" on:click="{onsubmit(onSubmit)}">Submit form</button>
+	<button type="button" disabled="{!sanity.ok}" onclick="{onsubmit(onSubmit)}">Submit form</button>
 </form>
 ```
 
@@ -186,12 +270,12 @@ While the above example uses the `submit` action of `microform`, form could also
 
 `microform` performs its magic by relying the `form` action. The `form` action can optionally accept the following:
 
-```javascript
+```ts
 <input
 	use:form={{
 		// an optional list of validations
 		// default is '' - no validations
-		validations: 'email|length:20',
+		validations: ['email', 'len:20'],
 		// an optional string of
 		// any of blur, change, input, keyup.
 		// default is blur
@@ -214,46 +298,36 @@ You need not bind the `values` to your fields except when there is a definite ne
 
 ```html
 <input
-	type="text"
-	name="email_account"
-	id="email_account"
-	value="{$values.email_account}"
-	data-validations="required|email"
-	use:form
+    ...
+	value="{values.email_account}"
 />
 ```
 
 ### 1. Validations
 
-Uses both inline `data-validations` on field and `validations` props on `form` action. For instance, the following are perfectly identical:
+`validations` is an array of validations to check field values against for correctnes. Uses `validations` props on `form` action. For instance, the following:
 
 ```html
-<input
-    type='text'
-    name='email_account'
-    id='email_account'
-    data-validations='required|email'
-    use:form/>
-
 <input
     type='text'
     name='email_account'
     id='email_account'
     use:form={{
-        validations:'required|email'
-    }}/>
+        validations:[ 'required', 'email' ]
+    }}
+/>
 ```
 
 ### 2. Validation Event
 
-Validation event can be changed/specified on a per-field basis. For instance, in our example, the global `validateEvent` was set to `blur` but we changed it on the select field to `change` like so:
+Validation event is to configure the event that should trigger validations. It can be changed/specified on a per-field basis. For instance, in our example, the global `validateEvent` was set to `blur` but we changed it on the select field to `change` like so:
 
 ```html
 <select
     name='gender'
     id='gender'
     use:form={{
-        validations:'required',
+        validations:['required'],
         validateEvent:'change'
     }}>
         <options value=''>Gender please</option>
@@ -274,13 +348,13 @@ Validation event can be changed/specified on a per-field basis. For instance, in
             contenteditable="true"
             use:form={{
                 validateEvent: 'input',
-                validations: 'required',
+                validations: ['required'],
                 name: 'story',
                 html: true
             }}
-        />
-        {#if $errors.story}
-            <small>{$errors.story}</small>
+        ></div>
+        {#if errors.story}
+            <small>{errors.story}</small>
         {/if}
     </label>
 </form>
@@ -290,35 +364,128 @@ Validation event can be changed/specified on a per-field basis. For instance, in
 
 `microform` provides a set of usable validations out-of-box. The following is a list of provided validations:
 
-- `required`: Usage, `validations='required'`
-- `email`: Usage, `validations='email'`
-- `url`: Usage, `validations='url'`
-- `ip`: Usage, `validations='ip'`
-- `length`: Usage, `validations='length:40'`
-- `number`: Usage, `validations='number'`
-- `integer`: Usage, `validations='integer'`
-- `alpha`: Usage, `validations='alpha'` - only alphabets
-- `alphanum`: Usage, `validations='alphanum'` - alphanumeric
-- `match`: Usage, `validations='match:<name-of-field-to-match>'`. For instance, this is examplified in our example with `password` and `confirm_password` fields
-- `min-length`: Usage, `validations='min-length:6'`
-- `max-length`: Usage, `validations='max-length:15'`
-- `max`: Usage, `validations='max:25'`
-- `max-file-size-mb`: Usage, `validations='max-file-size-mb:30'` - for file upload
+- `required`: Usage, `validations:['required']`
+- `email`: Usage, `validations:['email']`
+- `url`: Usage, `validations:['url']`
+- `ip`: Usage, `validations:['ip']`
+- `len:<number>`: Usage, `validations:['len:40']`
+- `number`: Usage, `validations:['number']`
+- `integer`: Usage, `validations:['integer']`
+- `alpha`: Usage, `validations:['alpha']` - only alphabets
+- `alphanum`: Usage, `validations:['alphanum']` - alphanumeric
+- `match:<input-id>`: Usage, `validations:['match:<id-of-field-to-match>']`. For instance, this is examplified in our example with `password` and `confirm_password` fields
+- `minlen:<number>`: Usage, `validations:['minlen:6']`
+- `maxlen:<number>`: Usage, `validations:['maxlen:15']`
+- `max:<number>`: Usage, `validations:['max:25']`
+- `file-size-mb:<number>`: Usage, `validations:['file-size-mb:30']` - for file upload
 
 Every validation listed above also comes with a very good default error message.
 
-Finally, the validations can be combined to form a complex graph of validations based on use cases by separating each validation rule with a `pipe`, `|`. For instance, a required field that also should be an email field could be validated thus:
+Finally, the validations can be combined to form a complex graph of validations based on use cases by combining them in a single array of validations. For instance, a required field that also should be an email field could be configured thus:
 
 ```html
 <input
 	type="text"
 	name="email_account"
 	id="email_account"
-	data-validations="required|email"
-	use:form
+    use:form={{
+        validations:['required','email']
+    }}
 />
 ```
 
-# TODO
+# Overriding validators
+Validators could be overriden to provide custom validation and/or messages besides the default ones. For instance, let us overide the `len` validation rule. Every non-empty string/message returned from a validator's call becomes the error to be displayed to the user; and it shows up in the `errors` keyed by the field name.
+
+### Approach 1
+```ts
+<script>
+import uForm, { type FieldProps } from "@steveesamson/microform";
+// default form data, probably passed as props
+export let defaultData:any = {};
+
+// Instatiate microform
+const { form, values, errors, submit, sanity } = uForm({
+    // Set default form data
+    data:{...defaultData},
+    // Set a global event for validation, can be overriden on a each field.
+    // Possible values: blur, change, input, keyup
+    options:{
+        // Default event that triggers validation
+        validateEvent:'blur',
+        // Configure validators here
+        validators:{
+            len:({name, label, parts}:FieldProps) =>{
+                if (!parts || parts.length < 2) {
+                    return `${label}: length validation requires length.`;
+                }
+                const extra = parts[1].trim();
+                return !!value && value.length !== parseInt(parts[1], 10) ?  `${label} must exactly be ${extra} characters long.` : "";
+            }
+        }
+    }
+});
+</script>
+```
+Instead of using the literal validation keys like `len`, `required` etc., while overriding validators, the exported key namee could be used. The key names are:
+- IS_REQUIRED = `required`
+- IS_EMAIL = `email`
+- IS_URL = `url`
+- IS_IP = `ip`
+- IS_INTEGER = `integer`
+- IS_NUMBER = `number`
+- IS_ALPHA = `alpha`
+- IS_ALPHANUM = `alphanum`
+- IS_MIN_LEN = `minlen`
+- IS_MAX_LEN = `maxlen`
+- IS_LEN = `len`
+- IS_MIN = `min`
+- IS_MAX = `max`
+- IT_MATCHES = `match`
+- IS_FILE_SIZE_MB = `file-size-mb`
+
+Therefore, the following is equivalent to the configuration in `Approach 1`:
+
+### Approach 2
+```ts
+<script>
+import uForm, { type FieldProps, IS_LEN } from "@steveesamson/microform";
+// default form data, probably passed as props
+export let defaultData:any = {};
+
+// Instatiate microform
+const { form, values, errors, submit, sanity } = uForm({
+    // Set default form data
+    data:{...defaultData},
+    // Set a global event for validation, can be overriden on a each field.
+    // Possible values: blur, change, input, keyup
+    options:{
+        // Default event that triggers validation
+        validateEvent:'blur',
+        // Configure validators here
+        validators:{
+            [IS_LEN]:({name, label, parts}:FieldProps) =>{
+                if (!parts || parts.length < 2) {
+                    return `${label}: length validation requires length.`;
+                }
+                const extra = parts[1].trim();
+                return !!value && value.length !== parseInt(parts[1], 10) ?  `${label} must exactly be ${extra} characters long.` : "";
+            }
+        }
+    }
+});
+</script>
+```
 
-I shall be working on how to allow users register their `validators` and `error messages` for the purpose of customisation.
+The validation will be used on the view as below:
+
+```html
+<input
+	type="text"
+	name="comment"
+	id="comment"
+    use:form={{
+        validations:['required','len:30']
+    }}
+/>
+```

package/dist/form-action.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="svelte" />
 import { type Writable } from "svelte/store";
-import type { FormErrors, FormOptions, FormValues, Params, FormAction } from "./types.js";
-export declare const formAction: (values: FormValues, errors: FormErrors, unfits: Writable<Params>, isdirty: Writable<boolean>, options: FormOptions, validationMap: Params) => FormAction;
+import type { FormOptions, FormAction } from "./types.js";
+import type { Params } from "./internal.js";
+export declare const formAction: (values: Writable<Params>, errors: Writable<Params>, unfits: Writable<Params>, isdirty: Writable<boolean>, options: FormOptions, validationMap: Params) => FormAction;

package/dist/form-action.js

@@ -7,22 +7,34 @@ const isField = (node) => {
         node instanceof HTMLTextAreaElement;
 };
 const isExcluded = (node) => {
-    return node instanceof HTMLInputElement && ['radio', 'checkbox', 'file'].includes(node.type.toLowerCase());
+    return node instanceof HTMLInputElement && ['radio', 'checkbox'].includes(node.type.toLowerCase());
 };
-const checkFormFitness = (values, unfits, validationMap) => {
-    const validate = useValidator(unfits, values);
+const isCheckbox = (node) => {
+    return node instanceof HTMLInputElement && ['checkbox'].includes(node.type.toLowerCase());
+};
+const isRadio = (node) => {
+    return node instanceof HTMLInputElement && ['radio'].includes(node.type.toLowerCase());
+};
+const checkFormFitness = (values, validationMap, validate) => {
     const _values = get(values);
     for (const [name, { validations }] of Object.entries(validationMap)) {
         validate({ name, value: _values[name], validations, });
     }
 };
 export const formAction = (values, errors, unfits, isdirty, options, validationMap) => {
-    const validate = useValidator(errors, values);
+    const { validators: customValidators } = options;
+    const { validate, validators } = useValidator(errors, values);
+    // override
+    if (customValidators) {
+        for (const [key, val] of Object.entries(customValidators)) {
+            validators[key] = val;
+        }
+    }
     return (node, eventProps) => {
         const nodeName = isField(node) ? node.name : '';
-        const { name: dsname = nodeName, validations: dsvalidations = '' } = node.dataset || {};
-        const { name = dsname, validations = dsvalidations, validateEvent = options.validateEvent, html = false } = eventProps || {};
-        validationMap[name] = { validations, html, nodeRef: isField(node) ? false : node };
+        const { name: dsname = nodeName } = node.dataset || {};
+        const { name = dsname, validations = [], validateEvent = options.validateEvent = 'blur', html = false } = eventProps || {};
+        validationMap[name] = { validations, html, nodeRef: node };
         const storedValue = get(values)[name] || '';
         let defValue = storedValue;
         if (isField(node) && !isExcluded(node)) {
@@ -55,7 +67,28 @@ export const formAction = (values, errors, unfits, isdirty, options, validationM
                     return { ...data, [name]: htm, [`${name}-text`]: text };
                 });
             }
-            checkFormFitness(values, unfits, validationMap);
+            else if (isCheckbox(node)) {
+                const { checked, value: val } = node;
+                const { [name]: fieldValue } = get(values);
+                let current = fieldValue;
+                if (checked) {
+                    current.push(val);
+                }
+                else {
+                    current = current.filter((next) => next !== val);
+                }
+                values.update((data) => {
+                    return { ...data, [name]: [...new Set(current)] };
+                });
+            }
+            else if (isRadio(node)) {
+                const { value: fvalue } = node;
+                values.update((data) => {
+                    return { ...data, [name]: fvalue };
+                });
+            }
+            const { validate: validateUnfit } = useValidator(unfits, values, validators);
+            checkFormFitness(values, validationMap, validateUnfit);
             isdirty.set(true);
         };
         node.addEventListener(validateEvent, updateNode);

package/dist/form-validators.d.ts

@@ -1,2 +1,23 @@
-import type { FormErrors, FormValues, ValidateArgs } from "./types.js";
-export declare const useValidator: (errors: FormErrors, values: FormValues) => ({ name, value, validations, node }: ValidateArgs) => Promise<void>;
+/// <reference types="svelte" />
+import { type Writable } from "svelte/store";
+import type { ValidateArgs, ValidatorType, ValidatorMap } from "./types.js";
+import type { Params } from "./internal.js";
+export declare const IS_REQUIRED = "required";
+export declare const IS_EMAIL = "email";
+export declare const IS_URL = "url";
+export declare const IS_IP = "ip";
+export declare const IS_INTEGER = "integer";
+export declare const IS_NUMBER = "number";
+export declare const IS_ALPHA = "alpha";
+export declare const IS_ALPHANUM = "alphanum";
+export declare const IS_MIN_LEN = "minlen";
+export declare const IS_MAX_LEN = "maxlen";
+export declare const IS_LEN = "len";
+export declare const IS_MIN = "min";
+export declare const IS_MAX = "max";
+export declare const IT_MATCHES = "match";
+export declare const IS_FILE_SIZE_MB = "file-size-mb";
+export declare const useValidator: (errors: Writable<Params>, values: Writable<Params>, validators?: ValidatorMap<ValidatorType>) => {
+    validate: ({ name, value, validations, node }: ValidateArgs) => Promise<void>;
+    validators: ValidatorMap<ValidatorType>;
+};