@fluixi/forms 0.2.0 → 0.2.1-alpha.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.
- package/README.md +137 -0
- package/package.json +7 -6
package/README.md
ADDED
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# @fluixi/forms
|
|
2
|
+
|
|
3
|
+
Reactive forms for fine-grained signal frameworks — Angular Reactive Forms redesigned
|
|
4
|
+
natively for a Fluixi compiler-driven runtime. No RxJS, no central store, no
|
|
5
|
+
proxies. Every field is an independent reactive cell.
|
|
6
|
+
|
|
7
|
+
See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full design.
|
|
8
|
+
|
|
9
|
+
## Packages
|
|
10
|
+
|
|
11
|
+
| Package | What |
|
|
12
|
+
| --- | --- |
|
|
13
|
+
| [`@fluixi/forms-core`](packages/forms-core) | `createField` / `createGroup` / `createForm` / `createFormArray`, validators, async engine |
|
|
14
|
+
| [`@fluixi/forms-framework`](packages/forms-framework) | JSX bindings — `bindField`, `<Field>`, `use:model` |
|
|
15
|
+
| [`@fluixi/forms-zod`](packages/forms-zod) | Zod schema → validators (typed, error-by-path) |
|
|
16
|
+
| [`@fluixi/forms-valibot`](packages/forms-valibot) | Valibot schema → validators |
|
|
17
|
+
| [`@fluixi/forms-devtools`](packages/forms-devtools) | untracked tree inspector + `watch()` |
|
|
18
|
+
|
|
19
|
+
## Quick start
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
import { createForm, createField, required, email, minLength, sameAs } from '@fluixi/forms-core';
|
|
23
|
+
|
|
24
|
+
const form = createForm({
|
|
25
|
+
name: createField('', { validators: [required(), minLength(2)] }),
|
|
26
|
+
email: createField('', { validators: [required(), email()] }),
|
|
27
|
+
password: createField(''),
|
|
28
|
+
confirm: createField('', { validators: [sameAs('password', 'Passwords must match')] }),
|
|
29
|
+
});
|
|
30
|
+
|
|
31
|
+
// fine-grained reads — subscribe to exactly what you touch
|
|
32
|
+
form.get('email').value(); // ''
|
|
33
|
+
form.get('email').valid(); // false
|
|
34
|
+
form.get('email').error(); // { type: 'required', message: '…' }
|
|
35
|
+
form.valid(); // aggregate
|
|
36
|
+
|
|
37
|
+
form.get('email').setValue('ada@example.com');
|
|
38
|
+
|
|
39
|
+
await form.submit((values) => api.signup(values)); // validates (sync+async), returns boolean
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Async validation
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
const username = createField('', {
|
|
46
|
+
debounce: 300,
|
|
47
|
+
asyncValidators: [
|
|
48
|
+
async (v, _ctx, signal) =>
|
|
49
|
+
(await fetch(`/check?u=${v}`, { signal }).then(r => r.json())).available
|
|
50
|
+
? null : { type: 'taken', message: 'Already taken' },
|
|
51
|
+
],
|
|
52
|
+
});
|
|
53
|
+
username.pending(); // true while checking
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### Dynamic arrays
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
import { createFormArray, keyOf } from '@fluixi/forms-core';
|
|
60
|
+
|
|
61
|
+
const rows = createFormArray([createField('a'), createField('b')]);
|
|
62
|
+
rows.push(createField(''));
|
|
63
|
+
rows.move(0, 2);
|
|
64
|
+
rows.value(); // ['b', '', 'a']
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### Schema-driven (Zod)
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
import { z } from 'zod';
|
|
71
|
+
import { createForm, createField } from '@fluixi/forms-core';
|
|
72
|
+
import { zodValidator } from '@fluixi/forms-zod';
|
|
73
|
+
|
|
74
|
+
const Schema = z.object({ email: z.string().email(), age: z.number().min(18) });
|
|
75
|
+
const form = createForm(
|
|
76
|
+
{ email: createField(''), age: createField(0) },
|
|
77
|
+
{ validators: [zodValidator(Schema)] }, // group-level; errors routed by meta.path
|
|
78
|
+
);
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### JSX (Fluixi)
|
|
82
|
+
|
|
83
|
+
```tsx
|
|
84
|
+
import { Field, bindField } from '@fluixi/forms-framework';
|
|
85
|
+
|
|
86
|
+
<Field control={form.get('email')}>
|
|
87
|
+
{(b, f) => (
|
|
88
|
+
<label>
|
|
89
|
+
<input value={b.value()} onInput={b.onInput} onBlur={b.onBlur} aria-invalid={b['aria-invalid']()} />
|
|
90
|
+
<Show when={f.touched() && f.error()}>{e => <span class="err">{e().message}</span>}</Show>
|
|
91
|
+
</label>
|
|
92
|
+
)}
|
|
93
|
+
</Field>
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Implementation roadmap
|
|
97
|
+
|
|
98
|
+
1. **forms-core** — primitives + sync/async validation + array/group. ✅ (working, 7 tests)
|
|
99
|
+
2. **forms-framework** — `bindField`/`<Field>`/`use:model`. ✅ scaffolded
|
|
100
|
+
3. **forms-zod / forms-valibot** — schema → validators + typed inference. ✅ scaffolded
|
|
101
|
+
4. **forms-devtools** — snapshot/watch/flatten. ✅ scaffolded
|
|
102
|
+
5. Schema-to-form *generation* (`fromZod(schema)` → a typed `createForm`).
|
|
103
|
+
6. `@fluixi/forms-babel` compiler plugin (binding/validator/dependency optimizations).
|
|
104
|
+
7. Field-level error routing helper (map group `zodErrorsByPath` onto child fields).
|
|
105
|
+
8. Devtools UI panel + dependency/validation graph rendering.
|
|
106
|
+
|
|
107
|
+
## Testing strategy
|
|
108
|
+
|
|
109
|
+
- **Unit (vitest)** — each primitive: value/validity/touched/dirty, reset, cross-field,
|
|
110
|
+
async pending→resolve, array ops, submit gating. (`forms-core/src/forms.spec.ts`.)
|
|
111
|
+
- **Reactivity assertions** — count memo executions to prove a keystroke in field A does NOT
|
|
112
|
+
recompute field B (granularity guarantee).
|
|
113
|
+
- **Adapter conformance** — schema validators produce the same errors as the schema lib.
|
|
114
|
+
- **Integration (jsdom)** — `<Field>` wiring: input → value, blur → touched, no cross-field
|
|
115
|
+
re-render.
|
|
116
|
+
|
|
117
|
+
## Benchmark strategy
|
|
118
|
+
|
|
119
|
+
- **Throughput** — N independent fields; measure ms to mutate one (target: flat vs N).
|
|
120
|
+
- **Wide patch** — `patchValue` over k fields; assert one propagation pass (batch).
|
|
121
|
+
- **Array churn** — 1000-row array push/move/remove; measure DOM ops with keyed render.
|
|
122
|
+
- **Memory** — heap per field at N = 1k/10k. Compare with/without compiler hoisting.
|
|
123
|
+
- Baselines: Angular Reactive Forms, React Hook Form, Formik, SolidJS `createStore` forms.
|
|
124
|
+
|
|
125
|
+
## Comparison
|
|
126
|
+
|
|
127
|
+
| | Angular RF | React Hook Form | SolidJS (store) | **@fluixi/forms** |
|
|
128
|
+
| --- | --- | --- | --- | --- |
|
|
129
|
+
| Reactivity | RxJS Observables | re-render + refs | store proxy | **fine-grained signals** |
|
|
130
|
+
| Per-field updates | coarse (valueChanges) | uncontrolled/refs | proxy-path | **independent memos** |
|
|
131
|
+
| Re-render model | zone.js CD | minimize re-renders | granular | **no re-render — pull/lazy** |
|
|
132
|
+
| Async validation | AsyncValidator + RxJS | manual | manual | **debounced effect + AbortController** |
|
|
133
|
+
| Cross-field deps | manual subscribe | watch() | effect | **ctx.get path → precise subscription** |
|
|
134
|
+
| Schema | — | resolver (zod/yup) | — | **zod/valibot adapters, typed** |
|
|
135
|
+
| Type safety | partial | good | good | **GroupValue/PartialDeep/Path inference** |
|
|
136
|
+
| Big forms (10k) | heavy (CD) | good | good | **idle ≈ 0 (lazy memos)** |
|
|
137
|
+
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fluixi/forms",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.1-alpha.1",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"description": "Umbrella package — re-exports all @fluixi/forms-* packages (core, framework, zod, valibot, devtools).",
|
|
6
6
|
"type": "module",
|
|
@@ -34,15 +34,16 @@
|
|
|
34
34
|
}
|
|
35
35
|
},
|
|
36
36
|
"files": [
|
|
37
|
+
"README.md",
|
|
37
38
|
"dist",
|
|
38
39
|
"LICENSE"
|
|
39
40
|
],
|
|
40
41
|
"dependencies": {
|
|
41
|
-
"@fluixi/forms-core": "0.2.
|
|
42
|
-
"@fluixi/forms-framework": "0.2.
|
|
43
|
-
"@fluixi/forms-zod": "0.2.
|
|
44
|
-
"@fluixi/forms-valibot": "0.2.
|
|
45
|
-
"@fluixi/forms-devtools": "0.2.
|
|
42
|
+
"@fluixi/forms-core": "0.2.1-alpha.1",
|
|
43
|
+
"@fluixi/forms-framework": "0.2.1-alpha.1",
|
|
44
|
+
"@fluixi/forms-zod": "0.2.1-alpha.1",
|
|
45
|
+
"@fluixi/forms-valibot": "0.2.1-alpha.1",
|
|
46
|
+
"@fluixi/forms-devtools": "0.2.1-alpha.1"
|
|
46
47
|
},
|
|
47
48
|
"publishConfig": {
|
|
48
49
|
"registry": "https://registry.npmjs.org/",
|