formique 1.0.2 → 1.0.3

package/README.md

@@ -3,7 +3,17 @@
 <!-- <img src="https://github.com/thincmedia/anyGridJs/blob/main/images/anyGridJs_Example.png" alt="anyGridJs Example"> --> 
 
 
-Formique: A lightweight, declarative JavaScript library for generating forms. Suited for vanilla js needs and Semantq JS framework. Formique simplifies the process of creating and managing forms with a variety of input types, built-in validation, and customizable attributes. Open-source &amp; MIT licensed.
+Formique: A lightweight, declarative JavaScript syntax library for generating WCAG acceAccessibility compliant forms. Suited for vanilla js and Semantq JS framework. Formique simplifies the process of creating and managing forms with a variety of input types, built-in validation, and customizable attributes. Open-source &amp; MIT licensed.
+
+
+## Accessibility Compliance
+
+Formique is designed with a laser focus on usability and accessibility, ensuring that the generated form HTML markup meets the highest standards of web accessibility, such as the Web Content Accessibility Guidelines (WCAG) 2.1.
+
+With minimal declarative form input definitions, Formique takes care of the rest to ensure the final markup is comprehensive enough to meet [official](https://www.w3.org/WAI/tutorials/forms/) usability and accessibility standards. 
+
+For more information on the Web Content (Forms) Accessibility Guidelines (WCAG), you can visit the [W3C website](https://www.w3.org/WAI/tutorials/forms/).
+
 
 ## Key Features
 
@@ -17,10 +27,10 @@ Formique: A lightweight, declarative JavaScript library for generating forms. Su
 
 ## Why Choose Formique?
 
-   - Vanilla JS: No dependencies; works seamlessly with vanilla JS or any JS framework.
+   - Vanilla JS: No dependencies; works seamlessly with vanilla JS and Semantq JS framework.(More frameworks to be added)
    - Lightweight: Minimal footprint optimized for performance.
    - Customizable: Adapt the library to fit your project's unique needs.
-   - Declarative: Define forms with a straightforward schema for better readability and maintainability.
+   - Declarative: Write your forms in JavaScript and define forms with a concise schema for better readability and maintainability.
 
 
 ## Form Input Types Covered
@@ -53,12 +63,29 @@ Formique: A lightweight, declarative JavaScript library for generating forms. Su
 # How to Write Form Schema
 
 The form schema is an array of field definitions. Each field is defined by an array containing:
+- Input definition (required)
+- Input validation (optional)
+- Input attributes (optional)
+- Binding syntax (optional)
+- Options (applicable to single select, multiple select, radio and check box inputs)
 
 ## Input Definition
 - **Type**: The input type (e.g., 'text', 'email', 'radio').
-- **Name**: The name attribute for the input.
+- **Name**: The name attribute for the input. 
 - **Label**: The label for the input.
 
+You don't need to use the type, name and label keys to define these parameters.
+**Example Input Definition:**
+
+`{ 'text', 'firstname', 'First Name' }`
+
+In the example above:
+ - The first item (text) defines the type of the input - this will yield: `<input type="text"` 
+ - The second item (firstname) defines the name value of the input - this will yield: `<input name="firstname"`
+ - The third item (First Name) defines the Label value- this will yield:  `<label for="firstname">First Name</label>`
+
+
+
 ## Input Validation
 - **Validation**: Object specifying validation rules. This can include:
   - **Required**: Boolean to specify if the field is mandatory.
@@ -68,95 +95,179 @@ The form schema is an array of field definitions. Each field is defined by an ar
   - **MaxLength**: Specifies the maximum number of characters allowed.
     - Example: `maxlength: 50`
   - **Pattern**: A regex pattern the input must match.
-    - Example: `pattern: /^[A-Za-z0-9]+$/`
-  - **Custom**: Function for custom validation logic.
-    - Example: `custom: value => value.startsWith('A')`
+    - Example: `pattern: "/^[A-Za-z0-9]+$/"`
+
+**Formique will filter out any invalid validation defined and throw warnings on the browser console.E.g. you define min and max validations for a text field Formique will filter these out.**
+
 
 ## Input Attributes
 - **Attributes**: Object specifying additional attributes like `id`, `class`, `style`, etc.
-  - Example: `attributes: { id: 'username', class: 'form-control' }`
+  - Example: `{ id: 'username', class: 'form-input', style: 'font-size: 13px;' }`
 
 ## Binding
 - **Binding**: Optional binding syntax for dynamic data. It can use `bind:value` or `::inputName`.
-  - Example: `binding: 'bind:value'` or `binding: '::username'`
+  - Example: `'bind:value'` or `'::inputName'`  - inputName must be the value defined as the input name (second item) in the input definition object. 
 
 ## Options
-- **Options**: For select, radio, and checkbox inputs. This is an array of options, each with a `value` and `label`.
-  - Example: `options: [{ value: 'male', label: 'Male' }, { value: 'female', label: 'Female' }]`
+- **Options**: For singleSelect,, multipleSelect, radio, and checkbox inputs. This is an array of options, each with a `value` and `label`.
+  - Example: `[{ value: 'male', label: 'Male' }, { value: 'female', label: 'Female' }]`
 
+### Selected Options
+  For fields like singleSelect and multipleSelect you can also define default or pre selected options this way:  
 
+  `[{ value: 'red', label: 'Red' }, { value: 'blue', label: 'Blue', selected: true }]`
 
-## Usage Example
+  In the example given: the blue option will be selected by default.
 
 
-There are two ways to use install Formique in your project
+## Installation
 
-## Option A: Clone the GitHub repo:
+There are two ways to install and use Formique in your project:
 
-1. go to your terminal and run:
+## Option A: Use Formique as a Universal Module Definition (UMD) Module
 
-```bash
-git clone https://github.com/Gugulethu-Nyoni/formique.git
+1. Include the CSS and JavaScript in the head section of your HTML file:
 
-````
-2. now you can use anygridjs this way in your html file
+    ```html
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/formique-css@1.0.1/formique.min.css">
+    ```
 
-```html
+2. Insert the js script tag just before the closing tag ```html </body> ``` of your html file.
 
-<link rel="stylesheet" href="./formique/formique.css">
+    ```html
+    <script src="https://cdn.jsdelivr.net/npm/formique@1.0.1/formique.umd.js"></script>
+    ```
+## Usage Example
 
-```
+1. Define the form container somewhere in the html body: 
 
 ```html
-
-<script type="module">
-
-  import { Formique } from './formique/formique.js';
-
-</script>
-
+<div id="formique"></div>
 ```
 
 
-## Option B: Via npm
-
-### Installation 
-
-
-1. go to your terminal and run:
-
-```bash
-
-npm install formique
-
-````
-
-2. now you can use formique this way in your html file
+2. Define your form parameters (formParams), form schema (formSchema) and then initialize Formique in script which should go below this script tag: 
 
 ```html
-
-<link rel="stylesheet" href="./node_modules/formique/formique.css">
-
+    <script src="https://cdn.jsdelivr.net/npm/formique@1.0.1/formique.umd.js"></script>
 ```
 
-```html
-
-<script type="module">
 
-  import { Formique } from './node_modules/formique/formique.js';
-
-  // rest of js code (app.js) can come here e.g. data object, column definition etc ( see below)
-
-</script>
+    ```html
+    <script src="https://cdn.jsdelivr.net/npm/formique@1.0.1/formique.umd.js"></script>
+
+    <script>
+        const formParams = {
+            method: 'post',
+            action: 'submit.js',
+            id: 'myForm',
+            class: 'form',
+            semantq: true,
+            style: 'width: 100%; font-size: 14px;'
+        };
+
+        const formSchema = [
+            ['text', 'name', 'Name', { required: true }, {}, ''],
+            ['email', 'email', 'Email', { required: true }, {}, ''],
+            [
+                'singleSelect', 'diet', 'Dietary Requirements', {required: true}, {}, '', 
+                [
+                    {value: 'gluten-free', label: 'Gluten-free'},
+                    {value: 'dairy-free', label: 'Dairy-free'},
+                    {value: 'keto', label: 'Ketogenic'},
+                    {value: 'low-carb', label: 'Low-carb'},
+                    {value: 'pescatarian', label: 'Pescatarian'},
+                    {value: 'halal', label: 'Halal'},
+                    {value: 'kosher', label: 'Kosher'},
+                    {value: 'vegetarian', label: 'Vegetarian'},
+                    {value: 'lacto-ovo-vegetarian', label: 'Lacto-ovo-vegetarian'},
+                    {value: 'raw-food', label: 'Raw food'},
+                    {value: 'macrobiotic', label: 'Macrobiotic'},
+                    {value: 'flexitarian', label: 'Flexitarian'}
+                ]
+            ],
+            ['submit', 'submitButton', 'Submit', {}, {}, '']
+        ];
+
+
+       (function(formParams, formSchema) {
+        const form = new Formique(formParams, formSchema);
+        const formHTML = form.renderFormHTML();
+        })(formParams, formSchema);
+
+    </script>
+    // </body>
+    ```
+
+## Option B: Use Formique as an ESM Module
+
+1. Install Formique via npm:
+
+    ```bash
+    npm install formique
+    ```
+
+2. Include the CSS and import Formique in the head section of your HTML file:
+
+    ```html
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/formique-css@1.0.1/formique.min.css">
+    ```
+3. Define form container somewhere in the html body: 
 
+```html
+<div id="formique"></div>
 ```
 
-
-# Example Usage 
-
-## Form Schema
-
-Here's an example of a form schema that defines various input fields with validation, attributes, options, and binding syntax:
+4. Define your form parameters (formParams), form schema (formSchema) and then initialize Formique in script which should go before the ```html </body> ``` tag.
+ 
+    ```html
+    <script type="module">
+        import Formique  from 'formique';
+
+        const formParams = {
+            method: 'post',
+            action: 'submit.js',
+            id: 'myForm',
+            class: 'form',
+            semantq: true,
+            style: 'width: 100%; font-size: 14px;'
+        };
+
+        const formSchema = [
+            ['text', 'name', 'Name', { required: true }, {}, ''],
+            ['email', 'email', 'Email', { required: true }, {}, ''],
+            [
+                'singleSelect', 'diet', 'Dietary Requirements', {required: true}, {}, '', 
+                [
+                    {value: 'gluten-free', label: 'Gluten-free'},
+                    {value: 'dairy-free', label: 'Dairy-free'},
+                    {value: 'keto', label: 'Ketogenic'},
+                    {value: 'low-carb', label: 'Low-carb'},
+                    {value: 'pescatarian', label: 'Pescatarian'},
+                    {value: 'halal', label: 'Halal'},
+                    {value: 'kosher', label: 'Kosher'},
+                    {value: 'vegetarian', label: 'Vegetarian'},
+                    {value: 'lacto-ovo-vegetarian', label: 'Lacto-ovo-vegetarian'},
+                    {value: 'raw-food', label: 'Raw food'},
+                    {value: 'macrobiotic', label: 'Macrobiotic'},
+                    {value: 'flexitarian', label: 'Flexitarian'}
+                ]
+            ],
+            ['submit', 'submitButton', 'Submit', {}, {}, ''],
+        ];
+
+        const form = new Formique(formParams, formSchema);
+        const formHTML = form.renderFormHTML();
+
+    </script>
+    ```
+
+Formique can be used as either a UMD module with a simple `<script>` tag or as an ESM module via npm. 
+
+# Form Schema Example
+
+
+Here's an example of a form schema that defines various input fields with validation, attributes, binding syntax and options:
 
 ```javascript
 const formSchema = [
@@ -269,13 +380,9 @@ const formParams = {
   style: 'width: 100%; font-size: 14px;' // Inline CSS styling
 };
 
-const form = new Formique(formParams, formSchema);
-const formHTML = form.renderFormHTML();
-console.log(formHTML);
 ```
 
 
-
 # Full List of Possible Form Parameters
 
 ```javascript
@@ -299,7 +406,7 @@ const formParams = {
 - **action**: The URL where the form data will be submitted.
 - **id**: A unique identifier for the form.
 - **class**: CSS class names applied to the form for styling purposes.
-- **semantq**: Boolean value indicating whether to use semantic HTML elements (e.g., `<fieldset>`, `<legend>`).
+- **semantq**: Boolean value to add syntax sugar in the Semantq JS Framework use case. If set event handler attributes will be rendered in the format: @click={incrementer} 
 - **style**: Inline CSS styling applied directly to the form element.
 - **enctype**: Specifies how the form data should be encoded when submitted ('application/x-www-form-urlencoded', 'multipart/form-data', 'text/plain').
 - **target**: Specifies where to display the response after submitting the form ('_self', '_blank', '_parent', '_top').
@@ -310,15 +417,6 @@ By customizing these parameters, you can control various aspects of the form's b
 
 
 
-## HTML 
-
-In your html, place this markup as placegolder for where the form will be rendered.
-
-```html
-
-<div id="formique"></div>
-
-```
 
 ## Example HTML Output
 
@@ -495,24 +593,22 @@ In your html, place this markup as placegolder for where the form will be render
 
 Formique provides a set of CSS classes to facilitate the styling of various form elements. The default class names for different form components are as follows:
 
-- **Wrapper for Input Elements:** `input-block`
+- **Wrapper (div) for Input Elements:** `input-block`
 - **Input Fields:** `form-input`
 - **Radio Button Groups:** `radio-group`
 - **Checkbox Groups:** `checkbox-group`
 - **Select Dropdowns:** `form-select`
 
-These classes are predefined in the `formique.css` stylesheet. Developers can either use this stylesheet for consistent styling or create their own custom CSS based on these class names to suit their design preferences.
+These classes are predefined in the `formique.css` stylesheet. Developers can either use this stylesheet for consistent styling or create their own custom CSS based on these class names to suit their design preferences. Also, Formique implements these class names by default. The input class can be overidden by defining your preferred class names in the input attributes object e.g.
 
-### Customizing Styles
+```javascript
+{ class: 'form-control' }
+```
 
-1. **Using Default Styles:** Apply the `formique.css` stylesheet to leverage the default styling provided by Formique.
-2. **Custom CSS:** If you prefer custom styling, you can override the default styles by defining your own CSS rules for the above class names.
 
 ### Inline Styling
 
-In addition to external stylesheets, individual form elements can be styled directly via attributes specified in the form schema. This allows for precise control over the appearance of each element without needing additional CSS files.
-
-By utilizing these options, you can easily adapt the look and feel of your form to meet your project's design requirements.
+In addition to external stylesheets, individual form elements can be styled directly via attributes specified in the form schema. This allows for fine grained control over the appearance of each element. 
 
 
 ## Contribute
@@ -525,4 +621,4 @@ Formique is licensed under the MIT License.
 
 ## Keywords
 
-Javascript datatables.
+Javascript forms, declarative form syntax, js form library.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "formique",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Formique Declarative Form Syntax JavaScript Library",
   "main": "dist/formique.umd.js",
   "module": "dist/formique.esm.js",
@@ -11,4 +11,4 @@
   "keywords": [],
   "author": "",
   "license": "ISC"
-}
+}