From b7ea35006db8232458f0133dcba92b8153c04e52 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Valverd=C3=A9?= Date: Mon, 22 Jun 2026 01:38:06 +0200 Subject: [PATCH] Add forms doc --- packages/docs/docs/forms.md | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/packages/docs/docs/forms.md b/packages/docs/docs/forms.md index 37eca25..944234f 100644 --- a/packages/docs/docs/forms.md +++ b/packages/docs/docs/forms.md @@ -5,18 +5,33 @@ title: Forms # Forms -The `Form` module is the low-level field model used by Effect-FC forms. A form -field is built on the same state model as the rest of Effect-FC: +The form modules provide an Effect-first model for editable, schema-validated +state. They are not a visual component library. Instead, they give you +Lenses/Subscribables for form values, validation issues, and commit state, so +you can build the UI with whatever components your app already uses. -- `encodedValue`: a `Lens` containing the raw value used by the input. +The base `Form` type represents a field. A field tracks both the raw encoded +value used by inputs and the decoded value produced by an Effect `Schema`: + +- `encodedValue`: a `Lens` containing the raw input value. - `value`: a `Subscribable` containing the decoded value as an `Option`. - `issues`: a `Subscribable` containing schema validation issues for that field. - `canCommit`, `isValidating`, and `isCommitting`: `Subscribable` flags for UI state. -Most apps create a root form with `SubmittableForm` or `SynchronizedForm`, then -focus it into fields with `Form.focusObjectOn`, `Form.focusArrayAt`, or the -other focusing helpers. +There are two root form flavors: + +- `SubmittableForm`: owns local encoded form state, validates it, and submits a + decoded value through a mutation. +- `SynchronizedForm`: wraps an existing target `Lens` and writes valid changes + back to that target. + +Most apps create one of those root forms, then focus it into fields with +`Form.focusObjectOn`, `Form.focusArrayAt`, or the other focusing helpers. + +The core form model is Effect code and can technically be used outside +Effect-FC. Effect-FC adds the React-facing hooks, such as `Form.useInput`, that +make those forms convenient to bind to components. ## Field Inputs