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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. package/.turbo/turbo-build.log +11 -11
  2. package/CHANGELOG.md +221 -209
  3. package/README.md +407 -370
  4. package/dev/index.css +32 -32
  5. package/dev/main.tsx +460 -459
  6. package/dist/components/fields/date-picker.d.ts +1 -1
  7. package/dist/components/fields/file.d.ts +1 -1
  8. package/dist/components/fields/input.d.ts +1 -1
  9. package/dist/components/fields/textarea.d.ts +1 -1
  10. package/dist/components/provider.d.ts +1 -6
  11. package/dist/index.cjs +1 -1
  12. package/dist/index.d.ts +4 -3
  13. package/dist/index.js +152 -143
  14. package/dist/types/index.d.ts +16 -6
  15. package/dist/webcomponent.cjs +1 -1
  16. package/dist/webcomponent.d.ts +1 -1
  17. package/dist/webcomponent.js +3 -0
  18. package/lib/components/fields/date-picker.tsx +154 -154
  19. package/lib/components/fields/file.tsx +84 -83
  20. package/lib/components/fields/input.tsx +70 -70
  21. package/lib/components/fields/textarea.tsx +72 -68
  22. package/lib/components/provider.tsx +162 -163
  23. package/lib/index.tsx +45 -41
  24. package/lib/types/index.ts +102 -82
  25. package/lib/webcomponent.ts +2 -2
  26. package/package.json +1 -1
  27. package/vite.config.ts +2 -1
package/README.md CHANGED
@@ -1,370 +1,407 @@
1
- # **Twintag Form**
2
-
3
- ## **Content**
4
-
5
- - [Introduction](#introduction)
6
- - [Framework Agnostic](#framework-agnostic)
7
- - [Parameters](#parameters)
8
- - [Config](#config)
9
- - [Options](#options)
10
- - [Inputs](#inputs)
11
- - [Options](#input-options)
12
- - [Subtypes](#subtypes)
13
- - [Event Handling](#event-handling)
14
- - [CSS](#css)
15
-
16
- ## **Introduction**
17
-
18
- Twintag Form provides a web component that allows you to create a form based on a JSON object, leaving the actions to the developer.
19
-
20
- ## **Framework Agnostic**
21
-
22
- Twintag Form exposes a web component that can be used in any framework or vanilla JS.
23
-
24
- ```html
25
- <twintag-form options="..." config="[...]"></twintag-form>
26
- ```
27
-
28
- ## **Parameters**
29
-
30
- The form component receives the following parameters:
31
-
32
- | Parameter | Type | Description |
33
- | --------- | -------- | --------------------------------------- |
34
- | `config` | `array` | Array that contains the form structure. |
35
- | `options` | `object` | Options to customize the form |
36
-
37
- ### **Config**
38
-
39
- 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:
40
-
41
- | Property | Type | Description |
42
- | --------- | -------- | -------------------------------------------------------------------------------- |
43
- | `type` | `string` | Component type. The subtype is optional as part of the string: `input:<subtype>` |
44
- | `subtype` | `string` | Component subtype |
45
- | `label` | `string` | Field label. |
46
- | `bind` | `string` | Field name. |
47
-
48
- ```json
49
- [
50
- {
51
- "type": "input",
52
- "props": {
53
- "subtype": "simple",
54
- "label": "Email",
55
- "bind": "email"
56
- }
57
- },
58
- {
59
- "type": "input:textarea",
60
- "props": {
61
- "label": "Message",
62
- "bind": "message"
63
- }
64
- },
65
- {
66
- "type": "input",
67
- "props": {
68
- "subtype": "submit",
69
- "label": "Submit"
70
- }
71
- }
72
- ]
73
- ```
74
-
75
- ### **Options**
76
-
77
- Twintag Form provides some options to customize the form:
78
-
79
- | Option | Type | Description |
80
- | --------------- | ----------------- | ------------------------------------------------------------------------- |
81
- | `variant` | `default / beta` | Variant of the form. |
82
- | `size` | `base / sm` | Default: `base` (font-size set to 16px). |
83
- | `resetOnSubmit` | `boolean` | If `true`, the form will be reset after submitting. (`false` per default) |
84
- | `defaultValues` | `object` | The properties are the same as the bind values in your config. |
85
-
86
- ### **Inputs**
87
-
88
- #### **Input options**
89
-
90
- Each input can be customized with the following optional options:
91
-
92
- | Option | Type | Description |
93
- | --------------- | --------- | ------------------------------------------------------------ |
94
- | `description` | `string` | Description of the input. |
95
- | `error` | `string` | Error message. |
96
- | `placeholder` | `string` | Placeholder of the input. |
97
- | `optionalField` | `boolean` | If `true`, the field will be optional. (`false` per default) |
98
-
99
- ```json
100
- {
101
- "type": "input",
102
- "props": {
103
- "subtype": "simple",
104
- "label": "Email",
105
- "bind": "email",
106
- "options": {
107
- "description": "Please enter you email",
108
- "error": "The field is empty."
109
- "placeholder": "Write here...",
110
- "optionalField": true
111
- }
112
- }
113
- }
114
- ```
115
-
116
- ### **Subtypes**
117
-
118
- - Simple
119
-
120
- ```json
121
- {
122
- "type": "input",
123
- "props": {
124
- "subtype": "simple",
125
- "label": "Email",
126
- "bind": "email"
127
- }
128
- }
129
- ```
130
-
131
- - Textarea
132
-
133
- ```json
134
- {
135
- "type": "input",
136
- "props": {
137
- "subtype": "textarea",
138
- "label": "Message",
139
- "bind": "message"
140
- }
141
- }
142
- ```
143
-
144
- - File
145
-
146
- ```json
147
- {
148
- "type": "input",
149
- "props": {
150
- "subtype": "file",
151
- "label": "File",
152
- "bind": "file"
153
- }
154
- }
155
- ```
156
-
157
- - Checkbox
158
-
159
- ```json
160
- {
161
- "type": "input",
162
- "props": {
163
- "subtype": "checkbox",
164
- "label": "Checkbox",
165
- "bind": "checkbox"
166
- }
167
- }
168
- ```
169
-
170
- - Toggle
171
-
172
- ```json
173
- {
174
- "type": "input",
175
- "props": {
176
- "subtype": "toggle",
177
- "label": "Toggle",
178
- "bind": "toggle"
179
- }
180
- }
181
- ```
182
-
183
- - Tri-Toggle
184
-
185
- ```json
186
- {
187
- "type": "input",
188
- "props": {
189
- "subtype": "tri-toggle",
190
- "label": "Toggle with 3 states",
191
- "bind": "tri-states"
192
- }
193
- }
194
- ```
195
-
196
- - Radiogroup
197
-
198
- ```json
199
- {
200
- "type": "input",
201
- "props": {
202
- "subtype": "radiogroup",
203
- "label": "Radio Group",
204
- "bind": "radiogroup",
205
- },
206
- "children": [
207
- {
208
- "type": "item",
209
- "props": {
210
- "label": "First item",
211
- "bind": "first-item"
212
- }
213
- },
214
- ...
215
- ]
216
- }
217
- ```
218
-
219
- - Submit
220
-
221
- ```json
222
- {
223
- "type": "input",
224
- "props": {
225
- "subtype": "submit",
226
- "label": "Submit"
227
- }
228
- }
229
- ```
230
-
231
- - Date picker
232
-
233
- ```json
234
- {
235
- "type": "input",
236
- "props": {
237
- "subtype": "datepicker",
238
- "label": "Pick a date"
239
- }
240
- }
241
- ```
242
-
243
- ## **Containers**
244
-
245
- - Accordion
246
-
247
- ```json
248
- {
249
- "type": "accordion",
250
- "props": {
251
- "defaultValue": "first-item" // optional: default expanded item
252
- },
253
- "children": [
254
- {
255
- "type": "accordion",
256
- "props": {
257
- "subtype": "item",
258
- "value": "first-item", // optional
259
- "label": "Your label",
260
- "icon": "archive-box-x-mark"
261
- },
262
- "children": [
263
- {
264
- "type": "input",
265
- "props": {
266
- "subtype": "simple",
267
- "bind": "first-item"
268
- }
269
- },
270
- ...
271
- ]
272
- },
273
- ...
274
- ]
275
- }
276
- ```
277
-
278
- - Category
279
-
280
- ```json
281
- {
282
- "type": "category",
283
- "props": {
284
- "label": "Category"
285
- },
286
- "children": [
287
- {
288
- "type": "input",
289
- "props": {
290
- "subtype": "simple",
291
- "label": "Your label"
292
- }
293
- },
294
- ...
295
- ]
296
- }
297
- ```
298
-
299
- ## **Event Handling**
300
-
301
- ```html
302
- <twintag-form
303
- id="yourform"
304
- options='{"variant":"beta","resetOnSubmit":true}'
305
- config='[{"type":"input:toggle","label":"Test","bind":"test","options":{"optionalField":true}},{"type":"input:submit","label":"Submit"}]'
306
- ></twintag-form>
307
-
308
- <button id="submit-btn">Submit</button>
309
- <button id="get-values-btn">Submit</button>
310
-
311
- <script>
312
- const form = document.getElementById('yourform');
313
- const submit = document.getElementById('submit-btn');
314
- const getValues = document.getElementById('get-values-btn');
315
-
316
- // You can validate the form outside the component:
317
- submit.addEventListener('click', () => {
318
- const submitEvent = new Event('twintag-form-validate');
319
- form.shadowRoot.querySelector('form').dispatchEvent(submitEvent);
320
- });
321
-
322
- // If there are no errors, the form will emit a custom event with the data on submit
323
- form.addEventListener('twintag-form-valid', (e) => {
324
- console.log(e.detail); // { test: true }
325
- });
326
-
327
- // If there are errors, the form will emit a custom event with the errors
328
- form.addEventListener('twintag-form-invalid', (e) => {
329
- console.log(e.detail); // { test: 'Test is required' }
330
- });
331
-
332
- // You can get the values of the form outside the component:
333
- form.addEventListener('twintag-form-values', (e) => {
334
- console.log(e.detail);
335
- });
336
- getValues.addEventListener('click', () => {
337
- const getValuesEvent = new Event('twintag-form-get_values');
338
- form.shadowRoot.querySelector('form').dispatchEvent(getValuesEvent);
339
- });
340
- </script>
341
- ```
342
-
343
- ## **CSS**
344
-
345
- The form component exposes the following CSS variables:
346
-
347
- | Variable | Description |
348
- | ----------------------- | ----------------------------------------------------------------------------------------- |
349
- | --tf-label | Color used for the inputs `label`. |
350
- | --tf-category | Color used for the `category` labels. |
351
- | | |
352
- | --tf-background | Background color for the input fields. |
353
- | --tf-foreground | Text color for the input fields. |
354
- | | |
355
- | --tf-muted | Used for `toggle` and `tri-toggle` background when value is false. |
356
- | --tf-muted-foreground | Color used for `placeholder` text (inputs) and description text. |
357
- | | |
358
- | --tf-primary | This color complements `primary-foreground`: `submit` button text |
359
- | --tf-primary-foreground | This color is used for, `submit` background, `label` text and input value. |
360
- | | |
361
- | --tf-accent | The accent color is used for `toggle`, `tri-toggle`, `checkbox` and `radiogroup` inputs. |
362
- | --tf-accent-foreground | This color complements `accent` to show contrast between elements: `checkbox` check icon. |
363
- | | |
364
- | --tf-destructive | This color is used for `error` messages and the asterisk to mark a required input. |
365
- | --tf-input | This color is used by the input borders. |
366
- | --tf-ring | This color highlights a focused input. |
367
- | | |
368
- | --tf-radius | This value is used for input rounded corners. |
369
- | | |
370
- | --tf-font | Font family for all the form. |
1
+ # **Twintag Form**
2
+
3
+ ## **Content**
4
+
5
+ - [Introduction](#introduction)
6
+ - [Framework Agnostic](#framework-agnostic)
7
+ - [Parameters](#parameters)
8
+ - [Config](#config)
9
+ - [Options](#options)
10
+ - [Inputs](#inputs)
11
+ - [Options](#input-options)
12
+ - [Subtypes](#subtypes)
13
+ - [Event Handling](#event-handling)
14
+ - [CSS](#css)
15
+
16
+ ## **Introduction**
17
+
18
+ Twintag Form provides a web component that allows you to create a form based on a JSON object, leaving the actions to the developer.
19
+
20
+ ## **Framework Agnostic**
21
+
22
+ Twintag Form exposes a web component that can be used in any framework or vanilla JS.
23
+
24
+ ```html
25
+ <twintag-form options="..." config="[...]"></twintag-form>
26
+ ```
27
+
28
+ ## **Parameters**
29
+
30
+ The form component receives the following parameters:
31
+
32
+ | Parameter | Type | Description |
33
+ | --------- | -------- | --------------------------------------- |
34
+ | `config` | `array` | Array that contains the form structure. |
35
+ | `options` | `object` | Options to customize the form |
36
+
37
+ ### **Config**
38
+
39
+ 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:
40
+
41
+ | Property | Type | Description |
42
+ | --------- | -------- | -------------------------------------------------------------------------------- |
43
+ | `type` | `string` | Component type. The subtype is optional as part of the string: `input:<subtype>` |
44
+ | `subtype` | `string` | Component subtype |
45
+ | `label` | `string` | Field label. |
46
+ | `bind` | `string` | Field name. |
47
+
48
+ ```json
49
+ [
50
+ {
51
+ "type": "input",
52
+ "props": {
53
+ "subtype": "simple",
54
+ "label": "Email",
55
+ "bind": "email"
56
+ }
57
+ },
58
+ {
59
+ "type": "input:textarea",
60
+ "props": {
61
+ "label": "Message",
62
+ "bind": "message"
63
+ }
64
+ },
65
+ {
66
+ "type": "input",
67
+ "props": {
68
+ "subtype": "submit",
69
+ "label": "Submit"
70
+ }
71
+ }
72
+ ]
73
+ ```
74
+
75
+ ### **Options**
76
+
77
+ Twintag Form provides some options to customize the form:
78
+
79
+ | Option | Type | Description |
80
+ | ---------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------- |
81
+ | `variant` | `default / outline` | Variant of the form. |
82
+ | `size` | `base / sm` | Default: `base` (font-size set to 16px). |
83
+ | `resetOnSubmit` | `boolean` | If `true`, the form will be reset after submitting. (`false` per default) |
84
+ | `defaultValues` | `object` | The properties are the same as the bind values in your config. |
85
+ | `acceptFileType` | `string` | Accept file type. ([ref](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/file#accept)) |
86
+
87
+ ### **Inputs**
88
+
89
+ #### **Input options**
90
+
91
+ Each input can be customized with the following optional options:
92
+
93
+ | Option | Type | Description |
94
+ | --------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
95
+ | `description` | `string` | Description of the input. |
96
+ | `error` | `string` | Error message. |
97
+ | `placeholder` | `string` | Placeholder of the input. |
98
+ | `optionalField` | `boolean` | If `true`, the field will be optional. (`false` per default) |
99
+ | `accept` | `string` | Accept file type. ([ref](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/file#accept)) |
100
+
101
+ ```json
102
+ {
103
+ "type": "input",
104
+ "props": {
105
+ "subtype": "simple",
106
+ "label": "Email",
107
+ "bind": "email",
108
+ "options": {
109
+ ...
110
+ }
111
+ }
112
+ }
113
+ ```
114
+
115
+ ### **Subtypes**
116
+
117
+ - Simple
118
+
119
+ ```json
120
+ {
121
+ "type": "input",
122
+ "props": {
123
+ "subtype": "simple",
124
+ "label": "Email",
125
+ "bind": "email",
126
+ "options": {
127
+ "description": "Please enter you email",
128
+ "error": "The field is empty."
129
+ "placeholder": "Write here...",
130
+ "optionalField": false
131
+ }
132
+ }
133
+ }
134
+ ```
135
+
136
+ - Textarea
137
+
138
+ ```json
139
+ {
140
+ "type": "input",
141
+ "props": {
142
+ "subtype": "textarea",
143
+ "label": "Message",
144
+ "bind": "message",
145
+ "options": {
146
+ "description": "Please enter you message",
147
+ "error": "The field is empty."
148
+ "placeholder": "Write here...",
149
+ "optionalField": false
150
+ }
151
+ }
152
+ }
153
+ ```
154
+
155
+ - File
156
+
157
+ ```json
158
+ {
159
+ "type": "input",
160
+ "props": {
161
+ "subtype": "file",
162
+ "label": "File",
163
+ "bind": "file",
164
+ "options": {
165
+ "description": "Please upload an image",
166
+ "error": "The field is empty.",
167
+ "accept": "image/*",
168
+ "optionalField": true
169
+ }
170
+ }
171
+ }
172
+ ```
173
+
174
+ - Checkbox
175
+
176
+ ```json
177
+ {
178
+ "type": "input",
179
+ "props": {
180
+ "subtype": "checkbox",
181
+ "label": "Checkbox",
182
+ "bind": "checkbox",
183
+ "options": {
184
+ "description": "Please enter you email",
185
+ "error": "The field is empty."
186
+ "optionalField": false
187
+ }
188
+ }
189
+ }
190
+ ```
191
+
192
+ - Toggle
193
+
194
+ ```json
195
+ {
196
+ "type": "input",
197
+ "props": {
198
+ "subtype": "toggle",
199
+ "label": "Toggle",
200
+ "bind": "toggle",
201
+ "options": {
202
+ "description": "Please enter you email",
203
+ "error": "The field is empty."
204
+ "optionalField": false
205
+ }
206
+ }
207
+ }
208
+ ```
209
+
210
+ - Tri-Toggle
211
+
212
+ ```json
213
+ {
214
+ "type": "input",
215
+ "props": {
216
+ "subtype": "tri-toggle",
217
+ "label": "Toggle with 3 states",
218
+ "bind": "tri-states",
219
+ "options": {
220
+ "description": "Please enter you email",
221
+ "error": "The field is empty."
222
+ "optionalField": false
223
+ }
224
+ }
225
+ }
226
+ ```
227
+
228
+ - Radiogroup
229
+
230
+ ```json
231
+ {
232
+ "type": "input",
233
+ "props": {
234
+ "subtype": "radiogroup",
235
+ "label": "Radio Group",
236
+ "bind": "radiogroup",
237
+ "options": {
238
+ "description": "Please enter you email",
239
+ "error": "The field is empty."
240
+ "optionalField": false
241
+ }
242
+ },
243
+ "children": [
244
+ {
245
+ "type": "item",
246
+ "props": {
247
+ "label": "First item",
248
+ "bind": "first-item"
249
+ }
250
+ },
251
+ ...
252
+ ]
253
+ }
254
+ ```
255
+
256
+ - Submit
257
+
258
+ ```json
259
+ {
260
+ "type": "input",
261
+ "props": {
262
+ "subtype": "submit",
263
+ "label": "Submit"
264
+ }
265
+ }
266
+ ```
267
+
268
+ - Date picker
269
+
270
+ ```json
271
+ {
272
+ "type": "input",
273
+ "props": {
274
+ "subtype": "datepicker",
275
+ "label": "Pick a date"
276
+ }
277
+ }
278
+ ```
279
+
280
+ ## **Containers**
281
+
282
+ - Accordion
283
+
284
+ ```json
285
+ {
286
+ "type": "accordion",
287
+ "props": {
288
+ "defaultValue": "first-item" // optional: default expanded item
289
+ },
290
+ "children": [
291
+ {
292
+ "type": "accordion",
293
+ "props": {
294
+ "subtype": "item",
295
+ "value": "first-item", // optional
296
+ "label": "Your label",
297
+ "icon": "archive-box-x-mark"
298
+ },
299
+ "children": [
300
+ {
301
+ "type": "input",
302
+ "props": {
303
+ "subtype": "simple",
304
+ "bind": "first-item"
305
+ }
306
+ },
307
+ ...
308
+ ]
309
+ },
310
+ ...
311
+ ]
312
+ }
313
+ ```
314
+
315
+ - Category
316
+
317
+ ```json
318
+ {
319
+ "type": "category",
320
+ "props": {
321
+ "label": "Category"
322
+ },
323
+ "children": [
324
+ {
325
+ "type": "input",
326
+ "props": {
327
+ "subtype": "simple",
328
+ "label": "Your label"
329
+ }
330
+ },
331
+ ...
332
+ ]
333
+ }
334
+ ```
335
+
336
+ ## **Event Handling**
337
+
338
+ ```html
339
+ <twintag-form
340
+ id="yourform"
341
+ options='{"variant":"beta","resetOnSubmit":true}'
342
+ config='[{"type":"input:toggle","label":"Test","bind":"test","options":{"optionalField":true}},{"type":"input:submit","label":"Submit"}]'
343
+ ></twintag-form>
344
+
345
+ <button id="submit-btn">Submit</button>
346
+ <button id="get-values-btn">Submit</button>
347
+
348
+ <script>
349
+ const form = document.getElementById('yourform');
350
+ const submit = document.getElementById('submit-btn');
351
+ const getValues = document.getElementById('get-values-btn');
352
+
353
+ // You can validate the form outside the component:
354
+ submit.addEventListener('click', () => {
355
+ const submitEvent = new Event('twintag-form-validate');
356
+ form.shadowRoot.querySelector('form').dispatchEvent(submitEvent);
357
+ });
358
+
359
+ // If there are no errors, the form will emit a custom event with the data on submit
360
+ form.addEventListener('twintag-form-valid', (e) => {
361
+ console.log(e.detail); // { test: true }
362
+ });
363
+
364
+ // If there are errors, the form will emit a custom event with the errors
365
+ form.addEventListener('twintag-form-invalid', (e) => {
366
+ console.log(e.detail); // { test: 'Test is required' }
367
+ });
368
+
369
+ // You can get the values of the form outside the component:
370
+ form.addEventListener('twintag-form-values', (e) => {
371
+ console.log(e.detail);
372
+ });
373
+ getValues.addEventListener('click', () => {
374
+ const getValuesEvent = new Event('twintag-form-get_values');
375
+ form.shadowRoot.querySelector('form').dispatchEvent(getValuesEvent);
376
+ });
377
+ </script>
378
+ ```
379
+
380
+ ## **CSS**
381
+
382
+ The form component exposes the following CSS variables:
383
+
384
+ | Variable | Description |
385
+ | ----------------------- | ----------------------------------------------------------------------------------------- |
386
+ | --tf-label | Color used for the inputs `label`. |
387
+ | --tf-category | Color used for the `category` labels. |
388
+ | | |
389
+ | --tf-background | Background color for the input fields. |
390
+ | --tf-foreground | Text color for the input fields. |
391
+ | | |
392
+ | --tf-muted | Used for `toggle` and `tri-toggle` background when value is false. |
393
+ | --tf-muted-foreground | Color used for `placeholder` text (inputs) and description text. |
394
+ | | |
395
+ | --tf-primary | This color complements `primary-foreground`: `submit` button text |
396
+ | --tf-primary-foreground | This color is used for, `submit` background, `label` text and input value. |
397
+ | | |
398
+ | --tf-accent | The accent color is used for `toggle`, `tri-toggle`, `checkbox` and `radiogroup` inputs. |
399
+ | --tf-accent-foreground | This color complements `accent` to show contrast between elements: `checkbox` check icon. |
400
+ | | |
401
+ | --tf-destructive | This color is used for `error` messages and the asterisk to mark a required input. |
402
+ | --tf-input | This color is used by the input borders. |
403
+ | --tf-ring | This color highlights a focused input. |
404
+ | | |
405
+ | --tf-radius | This value is used for input rounded corners. |
406
+ | | |
407
+ | --tf-font | Font family for all the form. |