@twintag/twintag-form 1.6.2-beta.1 → 1.7.0

package/README.md

@@ -1,407 +1,407 @@
-# **Twintag Form**
-
-## **Content**
-
-- [Introduction](#introduction)
-- [Framework Agnostic](#framework-agnostic)
-- [Parameters](#parameters)
-  - [Config](#config)
-  - [Options](#options)
-  - [Inputs](#inputs)
-    - [Options](#input-options)
-    - [Subtypes](#subtypes)
-- [Event Handling](#event-handling)
-- [CSS](#css)
-
-## **Introduction**
-
-Twintag Form provides a web component that allows you to create a form based on a JSON object, leaving the actions to the developer.
-
-## **Framework Agnostic**
-
-Twintag Form exposes a web component that can be used in any framework or vanilla JS.
-
-```html
-<twintag-form options="..." config="[...]"></twintag-form>
-```
-
-## **Parameters**
-
-The form component receives the following parameters:
-
-| Parameter | Type     | Description                             |
-| --------- | -------- | --------------------------------------- |
-| `config`  | `array`  | Array that contains the form structure. |
-| `options` | `object` | Options to customize the form           |
-
-### **Config**
-
-The `config` object contains the form structure. It is organized by the index of the items, where each item is an `Input` field represented by an object with the following properties:
-
-| Property  | Type     | Description                                                                      |
-| --------- | -------- | -------------------------------------------------------------------------------- |
-| `type`    | `string` | Component type. The subtype is optional as part of the string: `input:<subtype>` |
-| `subtype` | `string` | Component subtype                                                                |
-| `label`   | `string` | Field label.                                                                     |
-| `bind`    | `string` | Field name.                                                                      |
-
-```json
-[
-  {
-    "type": "input",
-    "props": {
-      "subtype": "simple",
-      "label": "Email",
-      "bind": "email"
-    }
-  },
-  {
-    "type": "input:textarea",
-    "props": {
-      "label": "Message",
-      "bind": "message"
-    }
-  },
-  {
-    "type": "input",
-    "props": {
-      "subtype": "submit",
-      "label": "Submit"
-    }
-  }
-]
-```
-
-### **Options**
-
-Twintag Form provides some options to customize the form:
-
-| Option           | Type                 | Description                                                                                                       |
-| ---------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `variant`        | `default  / outline` | Variant of the form.                                                                                              |
-| `size`           | `base     / sm`      | Default: `base` (font-size set to 16px).                                                                          |
-| `resetOnSubmit`  | `boolean`            | If `true`, the form will be reset after submitting. (`false` per default)                                         |
-| `defaultValues`  | `object`             | The properties are the same as the bind values in your config.                                                    |
-| `acceptFileType` | `string`             | Accept file type. ([ref](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/file#accept)) |
-
-### **Inputs**
-
-#### **Input options**
-
-Each input can be customized with the following optional options:
-
-| Option          | Type      | Description                                                                                                       |
-| --------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
-| `description`   | `string`  | Description of the input.                                                                                         |
-| `error`         | `string`  | Error message.                                                                                                    |
-| `placeholder`   | `string`  | Placeholder of the input.                                                                                         |
-| `optionalField` | `boolean` | If `true`, the field will be optional. (`false` per default)                                                      |
-| `accept`        | `string`  | Accept file type. ([ref](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/file#accept)) |
-
-```json
-{
-  "type": "input",
-  "props": {
-    "subtype": "simple",
-    "label": "Email",
-    "bind": "email",
-    "options": {
-      ...
-    }
-  }
-}
-```
-
-### **Subtypes**
-
-- Simple
-
-```json
-{
-  "type": "input",
-  "props": {
-    "subtype": "simple",
-    "label": "Email",
-    "bind": "email",
-    "options": {
-      "description": "Please enter you email",
-      "error": "The field is empty."
-      "placeholder": "Write here...",
-      "optionalField": false
-    }
-  }
-}
-```
-
-- Textarea
-
-```json
-{
-  "type": "input",
-  "props": {
-    "subtype": "textarea",
-    "label": "Message",
-    "bind": "message",
-    "options": {
-      "description": "Please enter you message",
-      "error": "The field is empty."
-      "placeholder": "Write here...",
-      "optionalField": false
-    }
-  }
-}
-```
-
-- File
-
-```json
-{
-  "type": "input",
-  "props": {
-    "subtype": "file",
-    "label": "File",
-    "bind": "file",
-    "options": {
-      "description": "Please upload an image",
-      "error": "The field is empty.",
-      "accept": "image/*",
-      "optionalField": true
-    }
-  }
-}
-```
-
-- Checkbox
-
-```json
-{
-  "type": "input",
-  "props": {
-    "subtype": "checkbox",
-    "label": "Checkbox",
-    "bind": "checkbox",
-    "options": {
-      "description": "Please enter you email",
-      "error": "The field is empty."
-      "optionalField": false
-    }
-  }
-}
-```
-
-- Toggle
-
-```json
-{
-  "type": "input",
-  "props": {
-    "subtype": "toggle",
-    "label": "Toggle",
-    "bind": "toggle",
-    "options": {
-      "description": "Please enter you email",
-      "error": "The field is empty."
-      "optionalField": false
-    }
-  }
-}
-```
-
-- Tri-Toggle
-
-```json
-{
-  "type": "input",
-  "props": {
-    "subtype": "tri-toggle",
-    "label": "Toggle with 3 states",
-    "bind": "tri-states",
-    "options": {
-      "description": "Please enter you email",
-      "error": "The field is empty."
-      "optionalField": false
-    }
-  }
-}
-```
-
-- Radiogroup
-
-```json
-{
-  "type": "input",
-  "props": {
-    "subtype": "radiogroup",
-    "label": "Radio Group",
-    "bind": "radiogroup",
-    "options": {
-      "description": "Please enter you email",
-      "error": "The field is empty."
-      "optionalField": false
-    }
-  },
-  "children": [
-    {
-      "type": "item",
-      "props": {
-        "label": "First item",
-        "bind": "first-item"
-      }
-    },
-    ...
-  ]
-}
-```
-
-- Submit
-
-```json
-{
-  "type": "input",
-  "props": {
-    "subtype": "submit",
-    "label": "Submit"
-  }
-}
-```
-
-- Date picker
-
-```json
-{
-  "type": "input",
-  "props": {
-    "subtype": "datepicker",
-    "label": "Pick a date"
-  }
-}
-```
-
-## **Containers**
-
-- Accordion
-
-```json
-{
-  "type": "accordion",
-  "props": {
-    "defaultValue": "first-item" // optional: default expanded item
-  },
-  "children": [
-    {
-      "type": "accordion",
-      "props": {
-        "subtype": "item",
-        "value": "first-item", // optional
-        "label": "Your label",
-        "icon": "archive-box-x-mark"
-      },
-      "children": [
-        {
-          "type": "input",
-          "props": {
-            "subtype": "simple",
-            "bind": "first-item"
-          }
-        },
-      ...
-      ]
-    },
-    ...
-  ]
-}
-```
-
-- Category
-
-```json
-{
-  "type": "category",
-  "props": {
-    "label": "Category"
-  },
-  "children": [
-    {
-      "type": "input",
-      "props": {
-        "subtype": "simple",
-        "label": "Your label"
-      }
-    },
-    ...
-  ]
-}
-```
-
-## **Event Handling**
-
-```html
-<twintag-form
-  id="yourform"
-  options='{"variant":"beta","resetOnSubmit":true}'
-  config='[{"type":"input:toggle","label":"Test","bind":"test","options":{"optionalField":true}},{"type":"input:submit","label":"Submit"}]'
-></twintag-form>
-
-<button id="submit-btn">Submit</button>
-<button id="get-values-btn">Submit</button>
-
-<script>
-  const form = document.getElementById('yourform');
-  const submit = document.getElementById('submit-btn');
-  const getValues = document.getElementById('get-values-btn');
-
-  // You can validate the form outside the component:
-  submit.addEventListener('click', () => {
-    const submitEvent = new Event('twintag-form-validate');
-    form.shadowRoot.querySelector('form').dispatchEvent(submitEvent);
-  });
-
-  // If there are no errors, the form will emit a custom event with the data on submit
-  form.addEventListener('twintag-form-valid', (e) => {
-    console.log(e.detail); // { test: true }
-  });
-
-  // If there are errors, the form will emit a custom event with the errors
-  form.addEventListener('twintag-form-invalid', (e) => {
-    console.log(e.detail); // { test: 'Test is required' }
-  });
-
-  // You can get the values of the form outside the component:
-  form.addEventListener('twintag-form-values', (e) => {
-    console.log(e.detail);
-  });
-  getValues.addEventListener('click', () => {
-    const getValuesEvent = new Event('twintag-form-get_values');
-    form.shadowRoot.querySelector('form').dispatchEvent(getValuesEvent);
-  });
-</script>
-```
-
-## **CSS**
-
-The form component exposes the following CSS variables:
-
-| Variable                | Description                                                                               |
-| ----------------------- | ----------------------------------------------------------------------------------------- |
-| --tf-label              | Color used for the inputs `label`.                                                        |
-| --tf-category           | Color used for the `category` labels.                                                     |
-|                         |                                                                                           |
-| --tf-background         | Background color for the input fields.                                                    |
-| --tf-foreground         | Text color for the input fields.                                                          |
-|                         |                                                                                           |
-| --tf-muted              | Used for `toggle` and `tri-toggle` background when value is false.                        |
-| --tf-muted-foreground   | Color used for `placeholder` text (inputs) and description text.                          |
-|                         |                                                                                           |
-| --tf-primary            | This color complements `primary-foreground`: `submit` button text                         |
-| --tf-primary-foreground | This color is used for, `submit` background, `label` text and input value.                |
-|                         |                                                                                           |
-| --tf-accent             | The accent color is used for `toggle`, `tri-toggle`, `checkbox` and `radiogroup` inputs.  |
-| --tf-accent-foreground  | This color complements `accent` to show contrast between elements: `checkbox` check icon. |
-|                         |                                                                                           |
-| --tf-destructive        | This color is used for `error` messages and the asterisk to mark a required input.        |
-| --tf-input              | This color is used by the input borders.                                                  |
-| --tf-ring               | This color highlights a focused input.                                                    |
-|                         |                                                                                           |
-| --tf-radius             | This value is used for input rounded corners.                                             |
-|                         |                                                                                           |
-| --tf-font               | Font family for all the form.                                                             |
+# **Twintag Form**
+
+## **Content**
+
+- [Introduction](#introduction)
+- [Framework Agnostic](#framework-agnostic)
+- [Parameters](#parameters)
+  - [Config](#config)
+  - [Options](#options)
+  - [Inputs](#inputs)
+    - [Options](#input-options)
+    - [Subtypes](#subtypes)
+- [Event Handling](#event-handling)
+- [CSS](#css)
+
+## **Introduction**
+
+Twintag Form provides a web component that allows you to create a form based on a JSON object, leaving the actions to the developer.
+
+## **Framework Agnostic**
+
+Twintag Form exposes a web component that can be used in any framework or vanilla JS.
+
+```html
+<twintag-form options="..." config="[...]"></twintag-form>
+```
+
+## **Parameters**
+
+The form component receives the following parameters:
+
+| Parameter | Type     | Description                             |
+| --------- | -------- | --------------------------------------- |
+| `config`  | `array`  | Array that contains the form structure. |
+| `options` | `object` | Options to customize the form           |
+
+### **Config**
+
+The `config` object contains the form structure. It is organized by the index of the items, where each item is an `Input` field represented by an object with the following properties:
+
+| Property  | Type     | Description                                                                      |
+| --------- | -------- | -------------------------------------------------------------------------------- |
+| `type`    | `string` | Component type. The subtype is optional as part of the string: `input:<subtype>` |
+| `subtype` | `string` | Component subtype                                                                |
+| `label`   | `string` | Field label.                                                                     |
+| `bind`    | `string` | Field name.                                                                      |
+
+```json
+[
+  {
+    "type": "input",
+    "props": {
+      "subtype": "simple",
+      "label": "Email",
+      "bind": "email"
+    }
+  },
+  {
+    "type": "input:textarea",
+    "props": {
+      "label": "Message",
+      "bind": "message"
+    }
+  },
+  {
+    "type": "input",
+    "props": {
+      "subtype": "submit",
+      "label": "Submit"
+    }
+  }
+]
+```
+
+### **Options**
+
+Twintag Form provides some options to customize the form:
+
+| Option           | Type                 | Description                                                                                                       |
+| ---------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `variant`        | `default  / outline` | Variant of the form.                                                                                              |
+| `size`           | `base     / sm`      | Default: `base` (font-size set to 16px).                                                                          |
+| `resetOnSubmit`  | `boolean`            | If `true`, the form will be reset after submitting. (`false` per default)                                         |
+| `defaultValues`  | `object`             | The properties are the same as the bind values in your config.                                                    |
+| `acceptFileType` | `string`             | Accept file type. ([ref](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/file#accept)) |
+
+### **Inputs**
+
+#### **Input options**
+
+Each input can be customized with the following optional options:
+
+| Option          | Type      | Description                                                                                                       |
+| --------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
+| `description`   | `string`  | Description of the input.                                                                                         |
+| `error`         | `string`  | Error message.                                                                                                    |
+| `placeholder`   | `string`  | Placeholder of the input.                                                                                         |
+| `optionalField` | `boolean` | If `true`, the field will be optional. (`false` per default)                                                      |
+| `accept`        | `string`  | Accept file type. ([ref](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/file#accept)) |
+
+```json
+{
+  "type": "input",
+  "props": {
+    "subtype": "simple",
+    "label": "Email",
+    "bind": "email",
+    "options": {
+      ...
+    }
+  }
+}
+```
+
+### **Subtypes**
+
+- Simple
+
+```json
+{
+  "type": "input",
+  "props": {
+    "subtype": "simple",
+    "label": "Email",
+    "bind": "email",
+    "options": {
+      "description": "Please enter you email",
+      "error": "The field is empty."
+      "placeholder": "Write here...",
+      "optionalField": false
+    }
+  }
+}
+```
+
+- Textarea
+
+```json
+{
+  "type": "input",
+  "props": {
+    "subtype": "textarea",
+    "label": "Message",
+    "bind": "message",
+    "options": {
+      "description": "Please enter you message",
+      "error": "The field is empty."
+      "placeholder": "Write here...",
+      "optionalField": false
+    }
+  }
+}
+```
+
+- File
+
+```json
+{
+  "type": "input",
+  "props": {
+    "subtype": "file",
+    "label": "File",
+    "bind": "file",
+    "options": {
+      "description": "Please upload an image",
+      "error": "The field is empty.",
+      "accept": "image/*",
+      "optionalField": true
+    }
+  }
+}
+```
+
+- Checkbox
+
+```json
+{
+  "type": "input",
+  "props": {
+    "subtype": "checkbox",
+    "label": "Checkbox",
+    "bind": "checkbox",
+    "options": {
+      "description": "Please enter you email",
+      "error": "The field is empty."
+      "optionalField": false
+    }
+  }
+}
+```
+
+- Toggle
+
+```json
+{
+  "type": "input",
+  "props": {
+    "subtype": "toggle",
+    "label": "Toggle",
+    "bind": "toggle",
+    "options": {
+      "description": "Please enter you email",
+      "error": "The field is empty."
+      "optionalField": false
+    }
+  }
+}
+```
+
+- Tri-Toggle
+
+```json
+{
+  "type": "input",
+  "props": {
+    "subtype": "tri-toggle",
+    "label": "Toggle with 3 states",
+    "bind": "tri-states",
+    "options": {
+      "description": "Please enter you email",
+      "error": "The field is empty."
+      "optionalField": false
+    }
+  }
+}
+```
+
+- Radiogroup
+
+```json
+{
+  "type": "input",
+  "props": {
+    "subtype": "radiogroup",
+    "label": "Radio Group",
+    "bind": "radiogroup",
+    "options": {
+      "description": "Please enter you email",
+      "error": "The field is empty."
+      "optionalField": false
+    }
+  },
+  "children": [
+    {
+      "type": "item",
+      "props": {
+        "label": "First item",
+        "bind": "first-item"
+      }
+    },
+    ...
+  ]
+}
+```
+
+- Submit
+
+```json
+{
+  "type": "input",
+  "props": {
+    "subtype": "submit",
+    "label": "Submit"
+  }
+}
+```
+
+- Date picker
+
+```json
+{
+  "type": "input",
+  "props": {
+    "subtype": "datepicker",
+    "label": "Pick a date"
+  }
+}
+```
+
+## **Containers**
+
+- Accordion
+
+```json
+{
+  "type": "accordion",
+  "props": {
+    "defaultValue": "first-item" // optional: default expanded item
+  },
+  "children": [
+    {
+      "type": "accordion",
+      "props": {
+        "subtype": "item",
+        "value": "first-item", // optional
+        "label": "Your label",
+        "icon": "archive-box-x-mark"
+      },
+      "children": [
+        {
+          "type": "input",
+          "props": {
+            "subtype": "simple",
+            "bind": "first-item"
+          }
+        },
+      ...
+      ]
+    },
+    ...
+  ]
+}
+```
+
+- Category
+
+```json
+{
+  "type": "category",
+  "props": {
+    "label": "Category"
+  },
+  "children": [
+    {
+      "type": "input",
+      "props": {
+        "subtype": "simple",
+        "label": "Your label"
+      }
+    },
+    ...
+  ]
+}
+```
+
+## **Event Handling**
+
+```html
+<twintag-form
+  id="yourform"
+  options='{"variant":"beta","resetOnSubmit":true}'
+  config='[{"type":"input:toggle","label":"Test","bind":"test","options":{"optionalField":true}},{"type":"input:submit","label":"Submit"}]'
+></twintag-form>
+
+<button id="submit-btn">Submit</button>
+<button id="get-values-btn">Submit</button>
+
+<script>
+  const form = document.getElementById('yourform');
+  const submit = document.getElementById('submit-btn');
+  const getValues = document.getElementById('get-values-btn');
+
+  // You can validate the form outside the component:
+  submit.addEventListener('click', () => {
+    const submitEvent = new Event('twintag-form-validate');
+    form.shadowRoot.querySelector('form').dispatchEvent(submitEvent);
+  });
+
+  // If there are no errors, the form will emit a custom event with the data on submit
+  form.addEventListener('twintag-form-valid', (e) => {
+    console.log(e.detail); // { test: true }
+  });
+
+  // If there are errors, the form will emit a custom event with the errors
+  form.addEventListener('twintag-form-invalid', (e) => {
+    console.log(e.detail); // { test: 'Test is required' }
+  });
+
+  // You can get the values of the form outside the component:
+  form.addEventListener('twintag-form-values', (e) => {
+    console.log(e.detail);
+  });
+  getValues.addEventListener('click', () => {
+    const getValuesEvent = new Event('twintag-form-get_values');
+    form.shadowRoot.querySelector('form').dispatchEvent(getValuesEvent);
+  });
+</script>
+```
+
+## **CSS**
+
+The form component exposes the following CSS variables:
+
+| Variable                | Description                                                                               |
+| ----------------------- | ----------------------------------------------------------------------------------------- |
+| --tf-label              | Color used for the inputs `label`.                                                        |
+| --tf-category           | Color used for the `category` labels.                                                     |
+|                         |                                                                                           |
+| --tf-background         | Background color for the input fields.                                                    |
+| --tf-foreground         | Text color for the input fields.                                                          |
+|                         |                                                                                           |
+| --tf-muted              | Used for `toggle` and `tri-toggle` background when value is false.                        |
+| --tf-muted-foreground   | Color used for `placeholder` text (inputs) and description text.                          |
+|                         |                                                                                           |
+| --tf-primary            | This color complements `primary-foreground`: `submit` button text                         |
+| --tf-primary-foreground | This color is used for, `submit` background, `label` text and input value.                |
+|                         |                                                                                           |
+| --tf-accent             | The accent color is used for `toggle`, `tri-toggle`, `checkbox` and `radiogroup` inputs.  |
+| --tf-accent-foreground  | This color complements `accent` to show contrast between elements: `checkbox` check icon. |
+|                         |                                                                                           |
+| --tf-destructive        | This color is used for `error` messages and the asterisk to mark a required input.        |
+| --tf-input              | This color is used by the input borders.                                                  |
+| --tf-ring               | This color highlights a focused input.                                                    |
+|                         |                                                                                           |
+| --tf-radius             | This value is used for input rounded corners.                                             |
+|                         |                                                                                           |
+| --tf-font               | Font family for all the form.                                                             |