reactaform 1.8.3 → 1.8.4

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 (3) hide show
  1. package/README.full.md +432 -0
  2. package/README.md +63 -286
  3. package/package.json +2 -1
package/README.full.md ADDED
@@ -0,0 +1,432 @@
1
+ # ReactaForm
2
+
3
+ > **Build dynamic React forms visually — no JSX, no boilerplate.**
4
+
5
+ **ReactaForm is a dynamic, schema-driven form platform for React, built for visual workflows.**
6
+
7
+ Design forms using JSON schemas or a visual builder, render them instantly, and scale complex configurable UIs across multiple applications.
8
+
9
+ ✨ Visual Builder included
10
+ ✨ Schema-first, no JSX
11
+ ✨ Fully extendable (components, themes, validation, i18n)
12
+ ✨ TypeScript-first
13
+ ✨ Optimized for large, dynamic forms
14
+
15
+ 🌐 **Documentation & Demos**
16
+ - **Doc:** https://reactaform.vercel.app
17
+ - **Playground & Demos:** https://reactaform.vercel.app
18
+ - **Builder:** https://reactaform.vercel.app/builder
19
+
20
+ ---
21
+
22
+ ## Table of Contents
23
+
24
+ - [What is ReactaForm?](#what-is-reactaform)
25
+ - [Why ReactaForm?](#why-reactaform)
26
+ - [Extensibility](#extensibility)
27
+ - [ReactaForm Builder](#reactaform-builder)
28
+ - [Key Features](#key-features)
29
+ - [Installation](#installation)
30
+ - [Quick Start](#quick-start)
31
+ - [Conditional Logic](#conditional-logic)
32
+ - [Validation and Validators](#validation-and-validators)
33
+ - [Documentation](#documentation)
34
+ - [Who Is ReactaForm For?](#target-customer)
35
+ - [Roadmap](#roadmap)
36
+ - [Contributing](#contributing)
37
+ - [License](#license)
38
+
39
+
40
+ ## <a id="what-is-reactaform"></a> 🤔 What is-Reactaform?
41
+
42
+ ReactaForm is not a traditional React form library.
43
+
44
+ Instead of writing forms in JSX, ReactaForm treats forms as data:
45
+
46
+ - Defined using JSON schemas
47
+ - Stored in databases or CMSs
48
+ - Rendered dynamically at runtime
49
+ - Editable visually by non-developers
50
+
51
+ This makes ReactaForm ideal for applications where forms are configurable, shared, or owned by the backend.
52
+
53
+ ---
54
+
55
+ ## <a id="why-reactaform"></a> 🤔 Why ReactaForm?
56
+
57
+ ### Most React form libraries assume:
58
+
59
+ - The form structure is static
60
+ - Developers write every field in JSX
61
+ - Changes require code edits and redeploys
62
+
63
+ ### ReactaForm is built for cases where forms are:
64
+ - Generated from backend data
65
+ - Configurable at runtime
66
+ - Built visually (low-code / no-code)
67
+ - Shared across multiple apps
68
+ - Highly customizable and themeable
69
+
70
+ ### Comparison
71
+ ⚠️ Important context
72
+
73
+ Not all form libraries solve the same problem.
74
+
75
+ Libraries like React Hook Form, Formik, and Final Form are code-first form state managers.
76
+ They assume forms are authored in JSX at build time.
77
+
78
+ ReactaForm belongs to a different category:
79
+ 👉 schema-driven, runtime-configurable form engines.
80
+
81
+ ReactaForm vs Schema-Driven Form Libraries
82
+ | Feature | ReactaForm | RJSF | JSON Forms | Uniforms | Form.io |
83
+ |------|------|------|------|------|------|
84
+ | Form definition | Custom JSON schema | JSON Schema | JSON Schema + UI schema | Multiple schemas | Platform schema |
85
+ | JSX required | ❌ | ❌ | ❌ | ❌ | ❌ |
86
+ | Runtime-configurable | ✔ | ⚠️ | ⚠️ | ⚠️ | ✔ |
87
+ | Conditional logic | ✔ Native | ⚠️ | ⚠️ | ⚠️ | ✔ |
88
+ | Visual builder | ✔ | ❌ | ❌ | ❌ | ✔ |
89
+ | Backend-driven forms | ✔ First-class | ⚠️ | ⚠️ | ⚠️ | ✔ |
90
+ | Plugin architecture | ✔ | ⚠️ | ⚠️ | ✔ | ✔ |
91
+ | Built-in theming | ✔ | ⚠️ | ✔ | ⚠️ | ✔ |
92
+ | Low-code friendly | ✔ | ❌ | ❌ | ❌ | ✔ |
93
+
94
+ ---
95
+
96
+ ## <a id="extensibility"></a> 🏗 Extensibility
97
+
98
+ ReactaForm is designed as an extendable platform, not just a renderer.
99
+
100
+ | Area | Support |
101
+ | --------------------------- | ------------------------------------------ |
102
+ | Field components | ✔ Custom components |
103
+ | Layout & grouping | ✔ Groups, sections (more planned) |
104
+ | Validation logic | ✔ Field, form, and field-type validators |
105
+ | Submission workflows | ✔ Pluggable submission handlers |
106
+ | Themes | ✔ CSS-variable-based theme registry |
107
+ | Internationalization (i18n) | ✔ Custom dictionaries & per-form overrides |
108
+ | Schema model | ✔ Custom field types & metadata |
109
+
110
+ ---
111
+
112
+ ## <a id="reactaform-builder"></a> 🏗 ReactaForm Builder
113
+
114
+ ReactaForm includes a drag-and-drop visual builder:
115
+
116
+ - Build forms visually
117
+ - Configure validation & conditional logic
118
+ - Preview instantly
119
+ - Export production-ready JSON schemas
120
+
121
+ <img src="./docs/assets/images/builder_ui.jpg" alt="ReactaForm Builder Screenshot" width="900" style="max-width:80%;height:auto;display:block;margin:0.5rem auto;" />
122
+ 👉 https://reactaform.vercel.app/builder
123
+
124
+ ## <a id="key-features"></a> ✨ Key Features
125
+
126
+ ### 🔧 Core Concepts
127
+ | Concept | Description |
128
+ |------|------|
129
+ | Schema-driven | Forms are defined using JSON, not JSX |
130
+ | Runtime rendering | Forms can change without redeploying |
131
+ | Visual-first | Optional drag-and-drop builder |
132
+ | Extendable | Components, themes, validation, and i18n are pluggable |
133
+ | Backend-friendly | Schemas can live in APIs or databases |
134
+
135
+ ### 🎨 Theming
136
+ - CSS-variable-based themes
137
+ - Light & dark modes
138
+ - 20+ built-in themes
139
+
140
+ ### 🧠 Logic & Validation
141
+ - Conditional visibility
142
+ - Custom validators
143
+ - Custom submission handlers
144
+
145
+ ### 🔌 Extensibility
146
+ - Component registry
147
+ - Plugin system
148
+ - Custom fields and workflows
149
+
150
+ ### 🌍 i18n
151
+ - Built-in multi-language support
152
+ - Per-form/Per-app translation dictionaries
153
+ - Translation caching
154
+
155
+ ### ⚡ Performance & Accessibility
156
+ - Incremental (chunked) mounting.
157
+ - Efficient updates using requestAnimationFrame batching and targeted visibility recomputation.
158
+ - Reduced input overhead with debounced callbacks for expensive handlers.
159
+ - ARIA-compliant by default
160
+
161
+ ---
162
+
163
+ ## <a id="installation"></a> 📦 Installation
164
+
165
+ ```bash
166
+ npm install reactaform
167
+ ```
168
+
169
+ **Peer Dependencies**
170
+ - React ^18 || ^19
171
+ - React-DOM ^18 || ^19
172
+
173
+ ---
174
+
175
+ ## <a id="quick-start"></a> 🚀 Quick Start
176
+
177
+ ```tsx
178
+ import { ReactaForm } from 'reactaform';
179
+
180
+ const definition = {
181
+ name: "simpleForm",
182
+ displayName: "Simple Form",
183
+ properties: [
184
+ { name: "email", type: "email", required: true }
185
+ ]
186
+ };
187
+
188
+ export default function App() {
189
+ return <ReactaForm definitionData={definition} />;
190
+ }
191
+ ```
192
+
193
+ ## <a id="conditional-logic"></a> 🎭 Conditional Logic
194
+
195
+ Dynamically show or hide individual fields or groups based on parent–child rules or group conditions.
196
+
197
+ Parent–child example (schema fragment):
198
+ Parents are defined in the parents field by specifying the parent field name and the corresponding values.
199
+
200
+ ```json
201
+ {
202
+ "properties": [
203
+ {
204
+ "name": "country",
205
+ "displayName": "Country",
206
+ "type": "dropdown",
207
+ "options": [
208
+ { "label": "United States", "value": "US" },
209
+ { "label": "Canada", "value": "CA" }
210
+ ]
211
+ },
212
+ {
213
+ "name": "state",
214
+ "displayName": "State",
215
+ "type": "dropdown",
216
+ "parents": { "country": ["US"] }
217
+ },
218
+ {
219
+ "name": "province",
220
+ "displayName": "Province",
221
+ "type": "dropdown",
222
+ "parents": { "country": ["CA"] }
223
+ }
224
+ ]
225
+ }
226
+ ```
227
+
228
+ ### Group support
229
+
230
+ Groups let you treat multiple fields as a unit and control the group's visibility with group name defined in field. Consecutive fields with same group name will be grouped while non consecutive fields with same group name are treated as different groups.
231
+
232
+ Example — `Address` group contains `address1` and `address2`
233
+
234
+ ```json
235
+ {
236
+ {
237
+ "type": "text",
238
+ "name": "address1",
239
+ "displayName": "Address Line 1",
240
+ "defaultValue": "",
241
+ "group": "Address"
242
+ },
243
+ {
244
+ "type": "text",
245
+ "name": "address2",
246
+ "displayName": "Address Line 2",
247
+ "defaultValue": "",
248
+ "group": "Address"
249
+ }
250
+ }
251
+ ```
252
+
253
+ ---
254
+
255
+ ## <a id="validation-and-validators"></a> 🔒 Validation and Validators
256
+
257
+ ReactaForm supports both field-level and form-level validation.
258
+
259
+ - Field-level: validation for a single field; can happen in real-time (while editing) or on submission.
260
+ - Form-level: cross-field validation performed during submission.
261
+
262
+ ### Field validation modes
263
+
264
+ `FieldValidationMode`:
265
+ - `realTime`: Runs validation while the user edits a field.
266
+ - `onSubmission`: Runs validation only when the form is submitted.
267
+
268
+ ### Validators
269
+
270
+ - Field custom validator — register a handler for individual-field logic.
271
+ - Form custom validator — register a handler for cross-field logic (runs during submission).
272
+ - Field type validator — define validation for a custom field/component type.
273
+ ---
274
+
275
+ ## Submission Handler
276
+ Since ReactaForm is a dynamic form system, it provides a submission handler mechanism that allows you to define and plug in custom submission logic, such as validation, data processing, or API calls.
277
+
278
+ **How It Works**
279
+
280
+ Submission handling is configured in two steps:
281
+
282
+ 1. Define and Register a Submission Handler
283
+
284
+ ```ts
285
+ import { registerSubmissionHandler } from 'reactaform';
286
+
287
+ registerSubmissionHandler('api:saveForm', async (definition, instanceName, valuesMap, t) => {
288
+ // send valuesMap to your API
289
+ const res = await fetch('/api/save', { method: 'POST', body: JSON.stringify(valuesMap), headers: { 'Content-Type': 'application/json' } });
290
+ if (!res.ok) return [t('Server error while submitting form')];
291
+ return undefined; // returning undefined (or falsy) means success
292
+ });
293
+ ```
294
+
295
+ 2. Reference the Registered Handler in the Form Definition
296
+
297
+ Schema example (Reference a registered handler using the submitHandlerName property):
298
+
299
+ ```json
300
+ {
301
+ "name": "contactForm",
302
+ "version": "1.0",
303
+ "displayName": "Contact",
304
+ "submitHandlerName": "api:saveForm",
305
+ "properties": [ /* ... */ ]
306
+ }
307
+ ```
308
+
309
+ ## <a id="documentation"></a> 📚 Documentation
310
+
311
+ 👉 https://reactaform.vercel.app/docs
312
+
313
+ ---
314
+
315
+ ## 👥 <a id="target-customer"></a>Who Is ReactaForm For?
316
+
317
+ - SaaS settings pages
318
+ - Admin dashboards
319
+ - Product configurators
320
+ - CMS-driven forms
321
+ - Low-code tools
322
+ - Enterprise dynamic UIs
323
+
324
+ ---
325
+
326
+ ## <a id="roadmap"></a> 🗺️ Roadmap
327
+ Status Legend:
328
+ - 🟢 Current — available or actively shipping
329
+ - 🔵 Planned — designed and scheduled
330
+ - 🟡 Experimental — under research or prototyping
331
+
332
+ ### Core & Standards
333
+ - 🟡 Accessibility certification (WCAG 2.2 AA)
334
+ - 🔵 Performance & accessibility audit tooling
335
+ - 🔵 Schema versioning & migration tools
336
+ - 🔵 Backward-compatible schema evolution
337
+ - 🔵 Form definition linting & diagnostics
338
+ - 🔵 Runtime schema validation & error reporting
339
+
340
+ ### Conditional Logic
341
+ - 🟢 Parent–child conditional visibility
342
+ - 🟢 Field grouping
343
+ - 🔵 Logical operators (AND / OR / NOT)
344
+ - 🔵 Multi-field conditions
345
+ - 🔵 Expression-based rules
346
+ - 🔵 Nested condition groups
347
+ - 🔵 Cross-group conditional logic
348
+ - 🔵 Conditional validation rules
349
+ - 🔵 Conditional default values
350
+
351
+ ### Layout & Structure
352
+ - 🔵 Multi-step / wizard forms
353
+ - 🔵 Tabbed layouts
354
+ - 🔵 Navigation sections / anchors
355
+ - 🔵 Collapsible sections
356
+ - 🔵 Reusable layout templates
357
+ - 🔵 Responsive layout rules
358
+ - 🔵 Grid & column layouts
359
+ - 🟡 Layout-aware conditional logic
360
+
361
+ ### Visual Builders
362
+ - 🟢 Drag-and-drop form builder
363
+ - 🔵 Advanced conditional logic editor
364
+ - 🔵 Validation rule designer
365
+ - 🔵 Submission workflow editor
366
+ - 🔵 Layout editor (tabs, steps, groups)
367
+ - 🔵 Live schema diff & change preview
368
+ - 🔵 Schema version history & rollback
369
+ - 🔵 Import / export schema packs
370
+ - 🟡 Builder extensibility API
371
+
372
+ ### Theme System
373
+ - 🟢 CSS-variable-based theming
374
+ - 🟢 Light & dark mode support
375
+ - 🟢 Per-form theme customization
376
+ - 🔵 Visual theme builder
377
+ - 🔵 CSS variable editor
378
+ - 🔵 Light / dark theme generator
379
+ - 🔵 Live theme preview across field types
380
+ - 🔵 Exportable & versioned theme packages
381
+ - 🔵 Tailwind-compatible themes
382
+ - 🟡 Theme inheritance & overrides
383
+
384
+ ### Plugin System
385
+ - 🟢 Component registry
386
+ - 🟢 Submission handler registration
387
+ - 🟢 Validation handler registrytion
388
+ - 🔵 Plugin scaffolding CLI
389
+ - 🔵 Custom field plugin builder
390
+ - 🔵 Validator plugin builder
391
+ - 🔵 Submission handler plugins
392
+ - 🔵 Plugin metadata & versioning
393
+ - 🔵 Plugin dependency management
394
+ - 🟡 One-click plugin export
395
+ - 🟡 Plugin compatibility checks
396
+
397
+ Internationalization (i18n)
398
+
399
+ Current: built-in i18n with per-form dictionaries
400
+ - 🟢 Built-in i18n support
401
+ - 🟢 Per-form translation dictionaries
402
+ - 🔵 Visual translation editor
403
+ - 🔵 Translation key discovery
404
+ - 🔵 Missing translation detection
405
+ - 🔵 Locale fallback strategies
406
+ - 🟡 RTL layout support
407
+ - 🟡 Async translation loaders
408
+
409
+ ### Ecosystem & Marketplace
410
+ - 🟡 Definition templates (community-driven)
411
+ - 🟡 Plugin marketplace (community-driven)
412
+ - 🟡 Theme sharing & presets gallery
413
+ - 🟡 Official plugin & theme collections
414
+
415
+ ### Enterprise
416
+ - 🔵 Form analytics & submission insights
417
+ - 🔵 Role-based builder permissions
418
+ - 🔵 Hosted schema & asset management
419
+ - 🔵 Enterprise integrations
420
+
421
+ ---
422
+
423
+ ## <a id="contributing"></a> 🤝 Contributing
424
+
425
+ Contributions are welcome!
426
+ Open an issue or submit a pull request.
427
+
428
+ ---
429
+
430
+ ## <a id="license"></a> 📄 License
431
+
432
+ MIT
package/README.md CHANGED
@@ -1,146 +1,50 @@
1
1
  # ReactaForm
2
2
 
3
- > **Build dynamic React forms visually — no JSX, no boilerplate.**
3
+ Build dynamic React forms visually — no JSX, no boilerplate.
4
4
 
5
- **ReactaForm is a dynamic, schema-driven form platform for React, built for visual workflows.**
5
+ ReactaForm is a schema-driven, extendable form platform for React. Define forms as JSON (or visually), render them at runtime, and scale complex, configurable UIs without rewriting JSX.
6
6
 
7
- Design forms using the drag-and-drop builder or JSON schemas, render them instantly, and scale complex, configurable UIs without rewriting JSX.
7
+ - Visual Form Builder
8
+ - Forms as data (JSON, not JSX)
9
+ - Fully extendable (components, themes, validation, i18n)
10
+ - TypeScript-first
11
+ - Optimized for large, dynamic forms
8
12
 
9
- Visual Builder included
10
- ✨ TypeScript-first
11
- ✨ Themeable & extensible
12
- ✨ Designed for dynamic, backend-driven UIs
13
- ✨ Optimized performance dynamic forms — fast, predictable rendering.
13
+ ## Why ReactaForm?
14
14
 
15
- 🌐 **Documentation & Demos**
16
- - https://reactaform.vercel.app
17
- - **Builder:** https://reactaform.vercel.app/builder
15
+ Most React form libraries are code-first:
18
16
 
19
- ---
17
+ - Forms are written in JSX
18
+ - Changes require code edits and redeploys
20
19
 
21
- ## Table of Contents
20
+ ReactaForm is different:
22
21
 
23
- - [Why ReactaForm?](#why-reactaform)
24
- - [ReactaForm Builder](#reactaform-builder)
25
- - [Key Features](#key-features)
26
- - [Installation](#installation)
27
- - [Quick Start](#quick-start)
28
- - [Conditional Logic](#conditional-logic)
29
- - [Validation and Validators](#validation-and-validators)
30
- - [Documentation](#documentation)
31
- - [Roadmap](#roadmap)
32
- - [Contributing](#contributing)
33
- - [License](#license)
22
+ - Forms are schema-driven
23
+ - Stored in APIs, databases, or CMSs
24
+ - Editable visually (low-code / no-code)
25
+ - Rendered dynamically at runtime
34
26
 
27
+ If your forms change often or are backend-owned, ReactaForm fits naturally.
35
28
 
36
- ## <a id="why-reactaform"></a> 🤔 Why ReactaForm?
29
+ ## Use Cases
37
30
 
38
- Most React form libraries assume your form structure is **static JSX**.
39
-
40
- ReactaForm is built for cases where forms are:
41
- - Generated from backend data
42
- - Configurable at runtime
43
- - Built visually (low-code / no-code)
44
- - Shared across multiple apps
45
- - Highly customizable and themeable
46
-
47
- ### Comparison
48
-
49
- | Feature | React Hook Form | Formik | ReactaForm |
50
- |------|------|------|------|
51
- | JSX required | ✔ | ✔ | ❌ |
52
- | Schema-driven | ❌ | ❌ | ✔ |
53
- | Runtime dynamic forms | ⚠️ | ⚠️ | ✔ |
54
- | Visual form builder | ❌ | ❌ | ✔ |
55
- | Built-in theming | ❌ | ⚠️ | ✔ |
56
- | Plugin architecture | ❌ | ❌ | ✔ |
57
- | Backend-driven UI | ❌ | ❌ | ✔ |
58
-
59
- ---
60
-
61
- ## <a id="reactaform-builder"></a> 🏗 ReactaForm Builder
62
-
63
- Visual drag-and-drop builder for creating dynamic forms:
64
-
65
- <img src="./docs/assets/images/builder_ui.jpg" alt="ReactaForm Builder Screenshot" width="900" style="max-width:100%;height:auto;display:block;margin:0.5rem auto;" />
66
-
67
- ## <a id="key-features"></a> ✨ Key Features
68
-
69
- ### 🔧 Core
70
- - Schema-driven form rendering
71
- - 20+ built-in field types
72
- - Automatic state management
73
- - Full TypeScript support
74
-
75
- ### 🛠 Visual Form Builder
76
- - Drag-and-drop form creation
77
- - Live preview
78
- - Validation & conditional logic
79
- - Export production-ready JSON schemas
80
-
81
- 👉 https://reactaform.vercel.app/builder
82
-
83
- ### 🎨 Theming
84
- - CSS-variable-based themes
85
- - Light & dark modes
86
- - 20+ built-in themes
87
-
88
- ### 🧠 Logic & Validation
89
- - Conditional visibility
90
- - Custom validators
91
- - Custom submission handlers
92
-
93
- ### 🔌 Extensibility
94
- - Component registry
95
- - Plugin system
96
- - Custom fields and workflows
97
-
98
- ### 🌍 i18n
99
- - Built-in multi-language support
100
- - Translation caching
101
- - Support custom per-form translation dictionaries for user defined translation.
102
-
103
- ### ⚡ Performance & Accessibility
104
- - Fast initial load via incremental (chunked) mounting.
105
- - Efficient updates using requestAnimationFrame batching and targeted visibility recomputation.
106
- - Reduced input overhead with debounced callbacks for expensive handlers.
107
- - ARIA-compliant by default
108
-
109
- ---
110
-
111
- ## 👥 Who Is ReactaForm For?
112
-
113
- - SaaS settings pages
31
+ - SaaS settings & configuration pages
114
32
  - Admin dashboards
115
- - Product configurators
116
33
  - CMS-driven forms
117
- - Low-code tools
34
+ - Product configurators
35
+ - Low-code / no-code platforms
118
36
  - Enterprise dynamic UIs
119
37
 
120
- ---
121
-
122
- ## <a id="installation"></a> 📦 Installation
123
-
124
- ```bash
125
- npm install reactaform
126
- ```
127
-
128
- **Peer Dependencies**
129
- - React ^18 || ^19
130
- - React-DOM ^18 || ^19
131
-
132
- ---
133
-
134
- ## <a id="quick-start"></a> 🚀 Quick Start
38
+ ## Quick example
135
39
 
136
40
  ```tsx
137
41
  import { ReactaForm } from 'reactaform';
138
42
 
139
43
  const definition = {
140
- name: "simpleForm",
141
- displayName: "Simple Form",
44
+ name: 'contactForm',
45
+ displayName: 'Contact',
142
46
  properties: [
143
- { name: "email", type: "email", required: true }
47
+ { name: 'email', type: 'email', required: true }
144
48
  ]
145
49
  };
146
50
 
@@ -149,185 +53,58 @@ export default function App() {
149
53
  }
150
54
  ```
151
55
 
152
- ## <a id="conditional-logic"></a> 🎭 Conditional Logic
153
-
154
- Dynamically show or hide individual fields or groups based on parent–child rules or group conditions.
155
-
156
- Parent–child example (schema fragment):
157
- Parents are defined in the parents field by specifying the parent field name and the corresponding values.
158
-
159
- ```json
160
- {
161
- "properties": [
162
- {
163
- "name": "country",
164
- "displayName": "Country",
165
- "type": "dropdown",
166
- "options": [
167
- { "label": "United States", "value": "US" },
168
- { "label": "Canada", "value": "CA" }
169
- ]
170
- },
171
- {
172
- "name": "state",
173
- "displayName": "State",
174
- "type": "dropdown",
175
- "parents": { "country": ["US"] }
176
- },
177
- {
178
- "name": "province",
179
- "displayName": "Province",
180
- "type": "dropdown",
181
- "parents": { "country": ["CA"] }
182
- }
183
- ]
184
- }
185
- ```
56
+ No JSX fields. No wiring. Just render.
186
57
 
187
- ### Group support
188
-
189
- Groups let you treat multiple fields as a unit and control the group's visibility with group name defined in field. Consecutive fields with same group name will be grouped while non consecutive fields with same group name are treated as different groups.
190
-
191
- Example — `Address` group contains `address1` and `address2`
192
-
193
- ```json
194
- {
195
- {
196
- "type": "text",
197
- "name": "address1",
198
- "displayName": "Address Line 1",
199
- "defaultValue": "",
200
- "group": "Address"
201
- },
202
- {
203
- "type": "text",
204
- "name": "address2",
205
- "displayName": "Address Line 2",
206
- "defaultValue": "",
207
- "group": "Address"
208
- }
209
- }
210
- ```
211
-
212
- ---
213
-
214
- ## <a id="validation-and-validators"></a> 🔒 Validation and Validators
58
+ ## Key features
215
59
 
216
- ReactaForm supports both field-level and form-level validation.
60
+ - Schema-driven rendering (JSON, not JSX)
61
+ - Visual drag-and-drop form builder
62
+ - Runtime-configurable forms
63
+ - Conditional logic & grouping
64
+ - Pluggable validation & submission
65
+ - Themeable via CSS variables
66
+ - Built-in i18n
67
+ - High-performance rendering
68
+ - ARIA-compliant by default
217
69
 
218
- - Field-level: validation for a single field; can happen in real-time (while editing) or on submission.
219
- - Form-level: cross-field validation performed during submission.
70
+ ## Extensible by design
220
71
 
221
- ### Field validation modes
72
+ ReactaForm is a platform, not just a renderer. You can extend:
222
73
 
223
- `FieldValidationMode`:
224
- - `realTime`: Runs validation while the user edits a field.
225
- - `onSubmission`: Runs validation only when the form is submitted.
74
+ - Field components
75
+ - Validation logic (field, form, type)
76
+ - Submission workflows
77
+ - Themes & design systems
78
+ - Languages & translations
79
+ - Custom field types & metadata
226
80
 
227
- ### Validators
81
+ No forks. No hacks.
228
82
 
229
- - Field custom validator — register a handler for individual-field logic.
230
- - Form custom validator — register a handler for cross-field logic (runs during submission).
231
- - Field type validator — define validation for a custom field/component type.
232
- ---
83
+ ## How it compares
233
84
 
234
- ## Submission Handler
235
- Since ReactaForm is a dynamic form system, it provides a submission handler mechanism that allows you to define and plug in custom submission logic, such as validation, data processing, or API calls.
85
+ - Formik / React Hook Form → code-first, JSX-based
86
+ - ReactaForm schema-first, runtime-driven
236
87
 
237
- **How It Works**
88
+ ReactaForm doesn’t replace form state libraries — it replaces hand-coding forms when forms are dynamic.
238
89
 
239
- Submission handling is configured in two steps:
90
+ ## Installation
240
91
 
241
- 1. Define and Register a Submission Handler
92
+ ```bash
93
+ npm install reactaform
94
+ ```
242
95
 
243
- ```ts
244
- import { registerSubmissionHandler } from 'reactaform';
96
+ ### Peer dependencies
245
97
 
246
- registerSubmissionHandler('api:saveForm', async (definition, instanceName, valuesMap, t) => {
247
- // send valuesMap to your API
248
- const res = await fetch('/api/save', { method: 'POST', body: JSON.stringify(valuesMap), headers: { 'Content-Type': 'application/json' } });
249
- if (!res.ok) return [t('Server error while submitting form')];
250
- return undefined; // returning undefined (or falsy) means success
251
- });
252
- ```
98
+ - React ^18 || ^19
99
+ - React DOM ^18 || ^19
253
100
 
254
- 2. Reference the Registered Handler in the Form Definition
101
+ ## Learn more
255
102
 
256
- Schema example (Reference a registered handler using the submitHandlerName property):
103
+ - [Full README](README.full.md)
104
+ - [Documentation](https://reactaform.vercel.app/docs)
105
+ - [ReactaForm Website (Demos)](https://reactaform.vercel.app)
106
+ - [Visual Builder](https://reactaform.vercel.app/builder)
257
107
 
258
- ```json
259
- {
260
- "name": "contactForm",
261
- "version": "1.0",
262
- "displayName": "Contact",
263
- "submitHandlerName": "api:saveForm",
264
- "properties": [ /* ... */ ]
265
- }
266
- ```
108
+ ## License
267
109
 
268
- ## <a id="documentation"></a> 📚 Documentation
269
-
270
- 👉 https://reactaform.vercel.app/docs
271
-
272
- ---
273
-
274
- ## <a id="roadmap"></a> 🗺️ Roadmap
275
-
276
- ### Core & Standards
277
- - [ ] Accessibility certification (WCAG 2.2 AA)
278
- - [ ] Performance & accessibility audit tooling
279
- - [ ] Schema versioning & migration tools
280
-
281
- ### Conditional Logic
282
- - [x] Parent–child conditional visibility (current)
283
- - [x] Field grouping (current)
284
- - [ ] Advanced conditional logic engine
285
- - [ ] Logical operators (AND / OR / NOT)
286
- - [ ] Multi-field conditions
287
- - [ ] Expression-based rules
288
- - [ ] Nested condition groups
289
- - [ ] Layout enhancement
290
- - [ ] Tabbed forms (planned)
291
- - [ ] Navigation sections (planned)
292
- - [ ] Multi-step forms
293
-
294
- ### Visual Builders
295
- - [ ] Enhanced visual form builder
296
- - [ ]Advanced conditional logic editor
297
- - [ ]Validation rule designer
298
- - [ ] **Theme Builder (Visual)**
299
- - [ ]Visual CSS-variable editor
300
- - [ ]Live preview across field types
301
- - [ ]Light / dark theme generation
302
- - [ ]Exportable, versioned theme packages
303
- - [ ]Tailwind-compatible themes
304
- - [ ] **Plugin Builder**
305
- - [ ] Scaffold custom field components
306
- - [ ] Scaffold validators & submission handlers
307
- - [ ] Plugin metadata & versioning
308
- - [ ] One-click plugin export
309
-
310
- ### Ecosystem
311
- - [ ] Definition templates (community-driven)
312
- - [ ] Plugin marketplace (community-driven)
313
- - [ ] Theme sharing & presets gallery
314
- - [ ] Official plugin & theme collections
315
-
316
- ### Enterprise
317
- - [ ] Form analytics & submission insights
318
- - [ ] Role-based builder permissions
319
- - [ ] Hosted schema & asset management
320
- - [ ] Enterprise integrations
321
-
322
- ---
323
-
324
- ## <a id="contributing"></a> 🤝 Contributing
325
-
326
- Contributions are welcome!
327
- Open an issue or submit a pull request.
328
-
329
- ---
330
-
331
- ## <a id="license"></a> 📄 License
332
-
333
- MIT
110
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "reactaform",
3
- "version": "1.8.3",
3
+ "version": "1.8.4",
4
4
  "description": "A powerful, type-safe React form builder library with dynamic field rendering, conditional visibility, multi-language support, and extensible validation",
5
5
  "keywords": [
6
6
  "react",
@@ -40,6 +40,7 @@
40
40
  "files": [
41
41
  "dist",
42
42
  "README.md",
43
+ "README.full.md",
43
44
  "LICENSE"
44
45
  ],
45
46
  "sideEffects": [