Skip to main content

formars_signals/
lib.rs

1//! `formars-signals`: headless reactive form controller built directly on
2//! `reactive_graph`.
3//!
4//! [`FormController`] owns an insertion-ordered registry of fields — one
5//! `ArcRwSignal<Value>` plus touched/dirty cells per field — and derives every
6//! other quantity as a pure `ArcMemo`. The crate is UI-agnostic: no Leptos,
7//! no effects, no spawner configuration. All public reactive types are from
8//! the Arc family (`Send + Sync`), safe for headless tests and SSR.
9//!
10//! # Disposed-owner hazard: accessors misreport
11//!
12//! `reactive_graph` accessors MISREPORT rather than error on disposed owners:
13//! a `get()`/`set()` on a signal whose owner was dropped either panics with a
14//! misleading "already been disposed" message or silently treats a transient
15//! lock failure the same way. This crate treats any `None` from such an
16//! accessor as "not usable" and degrades defensively — see `begin_attempt`
17//! in `formars-ui`, which retries transiently (bounded) before treating
18//! persistent `None` as not-acquired.
19//! Guidance: NEVER rely on `get()` after owner disposal; drop the handle
20//! instead.
21//!
22//! Async is confined to the composed future returned by
23//! [`FormController::on_submit`]; the consuming layer owns scheduling.
24//!
25//! # End-to-end example
26//!
27//! ```
28//! use formars_core::prelude::*;
29//! use formars_signals::{FormController, SubmitError, ValidateOn};
30//! use futures::executor::block_on;
31//! use reactive_graph::traits::{Get, Set};
32//!
33//! // Build a form with a controller-default timing mode.
34//! let mut c = FormController::new(ValidateOn::Blur);
35//! let email = c
36//!     .register_with(
37//!         FieldPath::key("email"),
38//!         Box::new(string().min(8).email()),
39//!         ValidateOn::Change,
40//!     )
41//!     .expect("fresh registration");
42//!
43//! // Edits flow through the handle; derived memos track synchronously.
44//! email.value().set(Value::from("user@example.com"));
45//! assert!(email.errors().get().is_empty());
46//! assert!(c.validate().is_ok());
47//!
48//! // Submit is one composed future: sync gate, snapshot, is_submitting bracket.
49//! let outcome = block_on(c.on_submit(|snapshot| async move {
50//!     let payload = format!("{:?}", snapshot.get(&FieldPath::key("email")));
51//!     Ok::<String, std::convert::Infallible>(payload)
52//! }));
53//! assert!(outcome.is_ok());
54//!
55//! // Server errors merge back onto their addressed fields.
56//! c.apply_server_errors(&FormaError {
57//!     issues: vec![formars_core::error::FormaIssue {
58//!         path: FieldPath::key("ghost"),
59//!         code: IssueCode::Refine,
60//!         message: "unknown field".into(),
61//!         params: Vec::new(),
62//!     }],
63//! });
64//! assert!(c.form_errors().get().iter().any(|i| i.path.to_string() == "ghost"));
65//! ```
66
67mod controller;
68mod field;
69mod submit;
70mod validation;
71
72pub use controller::{FormController, RegisterError};
73pub use field::{FieldHandle, ValidateOn};
74pub use submit::{FormSnapshot, SubmitError};
75
76pub use formars_core::error::{FieldPath, FormaError, FormaIssue, IssueCode};
77pub use formars_core::value::Value;