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.
- package/README.full.md +432 -0
- package/README.md +63 -286
- 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
|
-
|
|
3
|
+
Build dynamic React forms visually — no JSX, no boilerplate.
|
|
4
4
|
|
|
5
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
20
|
+
ReactaForm is different:
|
|
22
21
|
|
|
23
|
-
-
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
-
|
|
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
|
-
##
|
|
29
|
+
## Use Cases
|
|
37
30
|
|
|
38
|
-
|
|
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
|
-
-
|
|
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:
|
|
141
|
-
displayName:
|
|
44
|
+
name: 'contactForm',
|
|
45
|
+
displayName: 'Contact',
|
|
142
46
|
properties: [
|
|
143
|
-
{ name:
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
219
|
-
- Form-level: cross-field validation performed during submission.
|
|
70
|
+
## Extensible by design
|
|
220
71
|
|
|
221
|
-
|
|
72
|
+
ReactaForm is a platform, not just a renderer. You can extend:
|
|
222
73
|
|
|
223
|
-
|
|
224
|
-
-
|
|
225
|
-
-
|
|
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
|
-
|
|
81
|
+
No forks. No hacks.
|
|
228
82
|
|
|
229
|
-
|
|
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
|
-
|
|
235
|
-
|
|
85
|
+
- Formik / React Hook Form → code-first, JSX-based
|
|
86
|
+
- ReactaForm → schema-first, runtime-driven
|
|
236
87
|
|
|
237
|
-
|
|
88
|
+
ReactaForm doesn’t replace form state libraries — it replaces hand-coding forms when forms are dynamic.
|
|
238
89
|
|
|
239
|
-
|
|
90
|
+
## Installation
|
|
240
91
|
|
|
241
|
-
|
|
92
|
+
```bash
|
|
93
|
+
npm install reactaform
|
|
94
|
+
```
|
|
242
95
|
|
|
243
|
-
|
|
244
|
-
import { registerSubmissionHandler } from 'reactaform';
|
|
96
|
+
### Peer dependencies
|
|
245
97
|
|
|
246
|
-
|
|
247
|
-
|
|
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
|
-
|
|
101
|
+
## Learn more
|
|
255
102
|
|
|
256
|
-
|
|
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
|
-
|
|
259
|
-
{
|
|
260
|
-
"name": "contactForm",
|
|
261
|
-
"version": "1.0",
|
|
262
|
-
"displayName": "Contact",
|
|
263
|
-
"submitHandlerName": "api:saveForm",
|
|
264
|
-
"properties": [ /* ... */ ]
|
|
265
|
-
}
|
|
266
|
-
```
|
|
108
|
+
## License
|
|
267
109
|
|
|
268
|
-
|
|
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
|
+
"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": [
|