Skip to main content

Crate formars_signals

Crate formars_signals 

Source
Expand description

formars-signals: headless reactive form controller built directly on reactive_graph.

FormController owns an insertion-ordered registry of fields — one ArcRwSignal<Value> plus touched/dirty cells per field — and derives every other quantity as a pure ArcMemo. The crate is UI-agnostic: no Leptos, no effects, no spawner configuration. All public reactive types are from the Arc family (Send + Sync), safe for headless tests and SSR.

§Disposed-owner hazard: accessors misreport

reactive_graph accessors MISREPORT rather than error on disposed owners: a get()/set() on a signal whose owner was dropped either panics with a misleading “already been disposed” message or silently treats a transient lock failure the same way. This crate treats any None from such an accessor as “not usable” and degrades defensively — see begin_attempt in formars-ui, which retries transiently (bounded) before treating persistent None as not-acquired. Guidance: NEVER rely on get() after owner disposal; drop the handle instead.

Async is confined to the composed future returned by FormController::on_submit; the consuming layer owns scheduling.

§End-to-end example

use formars_core::prelude::*;
use formars_signals::{FormController, SubmitError, ValidateOn};
use futures::executor::block_on;
use reactive_graph::traits::{Get, Set};

// Build a form with a controller-default timing mode.
let mut c = FormController::new(ValidateOn::Blur);
let email = c
    .register_with(
        FieldPath::key("email"),
        Box::new(string().min(8).email()),
        ValidateOn::Change,
    )
    .expect("fresh registration");

// Edits flow through the handle; derived memos track synchronously.
email.value().set(Value::from("user@example.com"));
assert!(email.errors().get().is_empty());
assert!(c.validate().is_ok());

// Submit is one composed future: sync gate, snapshot, is_submitting bracket.
let outcome = block_on(c.on_submit(|snapshot| async move {
    let payload = format!("{:?}", snapshot.get(&FieldPath::key("email")));
    Ok::<String, std::convert::Infallible>(payload)
}));
assert!(outcome.is_ok());

// Server errors merge back onto their addressed fields.
c.apply_server_errors(&FormaError {
    issues: vec![formars_core::error::FormaIssue {
        path: FieldPath::key("ghost"),
        code: IssueCode::Refine,
        message: "unknown field".into(),
        params: Vec::new(),
    }],
});
assert!(c.form_errors().get().iter().any(|i| i.path.to_string() == "ghost"));

Structs§

FieldHandle
Accessor view over one registered field’s reactive cells.
FieldPath
Address of the field a FormaIssue refers to.
FormController
Controller-owned registry of form fields.
FormSnapshot
Point-in-time copy of every field value, taken at the submit gate in registry declaration order. Plain owned data — later edits cannot mutate it.
FormaError
Every constraint violated during one parse call, in declaration order (ER-1).
FormaIssue
One violated constraint: where (FieldPath), what (IssueCode), human-readable message, and structured parameters.

Enums§

IssueCode
Stable, enumerable identifiers for every builtin constraint (ER-3), plus IssueCode::Custom for consumer-defined ones.
RegisterError
Error returned by FormController::register.
SubmitError
Why a composed submit future failed.
ValidateOn
When a field’s validation issues become visible to the consuming UI.
Value
Dependency-free dynamic value tree — the erased currency of the crate::schema::DynSchema view.