@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.
Files changed (2) hide show
  1. package/README.md +137 -0
  2. 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.0",
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.0",
42
- "@fluixi/forms-framework": "0.2.0",
43
- "@fluixi/forms-zod": "0.2.0",
44
- "@fluixi/forms-valibot": "0.2.0",
45
- "@fluixi/forms-devtools": "0.2.0"
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/",