pub struct FormController { /* private fields */ }Expand description
Controller-owned registry of form fields.
Owns every value signal and state cell; callers only receive
FieldHandle accessors. Clones share the same underlying signals and
memos, so there is exactly one source of truth per field value. Memos
created owner-less (headless) are never disposed — acceptable because the
controller lives for the form’s lifetime.
v0 fields anchor their state to a Value snapshot taken at registration;
that snapshot anchors FieldHandle::dirty, FormController::reset,
and the server-baseline comparison. Default registration snapshots the
empty-string Value; FormController::register_initial and
FormController::register_initial_with snapshot a caller-supplied
value instead (for prefilled fields). The snapshot is immutable after
registration.
Implementations§
Source§impl FormController
impl FormController
Sourcepub fn new(default_validate_on: ValidateOn) -> FormController
pub fn new(default_validate_on: ValidateOn) -> FormController
Creates a controller with the given default validation timing.
§Panics
Only if the registry mutex is poisoned by a panic in another thread holding it (never in normal use).
Sourcepub fn register(
&mut self,
path: FieldPath,
schema: Box<dyn DynSchema>,
) -> Result<FieldHandle, RegisterError>
pub fn register( &mut self, path: FieldPath, schema: Box<dyn DynSchema>, ) -> Result<FieldHandle, RegisterError>
Registers a field using the controller-default timing mode, rejecting duplicate paths (fail-fast at the bug site: a double render or copy-paste build surfaces here instead of forking state invisibly).
§Errors
Returns RegisterError::Duplicate if path is already registered.
Sourcepub fn register_with(
&mut self,
path: FieldPath,
schema: Box<dyn DynSchema>,
validate_on: ValidateOn,
) -> Result<FieldHandle, RegisterError>
pub fn register_with( &mut self, path: FieldPath, schema: Box<dyn DynSchema>, validate_on: ValidateOn, ) -> Result<FieldHandle, RegisterError>
Registers a field with an explicit timing mode overriding the controller default.
§Errors
Returns RegisterError::Duplicate if path is already registered.
Sourcepub fn register_initial(
&mut self,
path: FieldPath,
schema: Box<dyn DynSchema>,
initial: Value,
) -> Result<FieldHandle, RegisterError>
pub fn register_initial( &mut self, path: FieldPath, schema: Box<dyn DynSchema>, initial: Value, ) -> Result<FieldHandle, RegisterError>
Registers a prefilled field using the controller-default timing mode,
with initial as the dirty/reset/server-baseline anchor instead of
the empty-string default. The snapshot is immutable after
registration — no re-anchoring API exists.
initial is NOT validated against the field’s schema at registration
time; if it violates constraints, the error memo reports those issues
immediately (identical to registering then setting the value).
§Errors
Returns RegisterError::Duplicate if path is already registered;
the existing field is left untouched.
Sourcepub fn register_initial_with(
&mut self,
path: FieldPath,
schema: Box<dyn DynSchema>,
validate_on: ValidateOn,
initial: Value,
) -> Result<FieldHandle, RegisterError>
pub fn register_initial_with( &mut self, path: FieldPath, schema: Box<dyn DynSchema>, validate_on: ValidateOn, initial: Value, ) -> Result<FieldHandle, RegisterError>
Same as FormController::register_initial plus an explicit timing
mode overriding the controller default, symmetric with
FormController::register_with.
initial is NOT validated against the field’s schema at registration
time; if it violates constraints, the error memo reports those issues
immediately (identical to registering then setting the value).
§Errors
Returns RegisterError::Duplicate if path is already registered;
the existing field is left untouched.
Sourcepub fn field(&self, path: &FieldPath) -> Option<FieldHandle>
pub fn field(&self, path: &FieldPath) -> Option<FieldHandle>
Looks up the handle for a registered path.
The returned handle is a cheap clone sharing the same underlying cells.
Sourcepub fn effective_validate_on(&self, path: &FieldPath) -> Option<ValidateOn>
pub fn effective_validate_on(&self, path: &FieldPath) -> Option<ValidateOn>
The resolved validation-timing mode for path, or None when the
path is not registered.
Sourcepub fn mark_touched(&self, path: &FieldPath)
pub fn mark_touched(&self, path: &FieldPath)
Marks the field touched — the blur seam driving visibility gates.
Sourcepub fn revalidate(&self, path: &FieldPath)
pub fn revalidate(&self, path: &FieldPath)
Eagerly evaluates the field’s error memos, synchronously — no await,
no scheduling (FSV-2). Because the memos are lazy, any consumer read
recomputes stale values on demand anyway; this only warms the memo
caches so a later .get() finds fresh values already computed.
Sourcepub fn submitted(&self) -> ArcRwSignal<bool>
pub fn submitted(&self) -> ArcRwSignal<bool>
The form-level submit-attempt flag feeding every display gate.
Sourcepub fn is_submitting(&self) -> ArcRwSignal<bool>
pub fn is_submitting(&self) -> ArcRwSignal<bool>
The in-flight submit flag: true between the snapshot gate and the handler future settling, across success and failure alike.
Sourcepub fn form_errors(&self) -> ArcMemo<Vec<FormaIssue>>
pub fn form_errors(&self) -> ArcMemo<Vec<FormaIssue>>
Reactive aggregate of every field’s display-gated issues plus form-level (unmatched) server issues.
Sourcepub fn apply_server_errors(&self, error: &FormaError)
pub fn apply_server_errors(&self, error: &FormaError)
Merges server-side issues into field state. Issues addressed to registered paths REPLACE that field’s server cells; unknown or ROOT paths land in the form-level unmatched collection. A subsequent edit to a field hides its stale server issues until the next apply.
The known-path list and every field’s current value are captured under ONE registry acquisition, so a concurrent edit can never anchor a baseline to a value torn against a stale grouping snapshot; all signal writes happen after the lock is released.
Sourcepub fn validate(&self) -> Result<(), FormaError>
pub fn validate(&self) -> Result<(), FormaError>
Validates the whole form synchronously against each field’s schema.
Independent of display gates — a hidden (untouched) violation still fails submission.
§Errors
Returns every violated field’s issues, in declaration order, when any registered field fails.
Sourcepub fn snapshot(&self) -> FormSnapshot
pub fn snapshot(&self) -> FormSnapshot
Takes a point-in-time copy of all field values in declaration order.
Sourcepub fn on_submit<T, E, F, Fut>(
&self,
handler: F,
) -> impl Future<Output = Result<T, SubmitError<E>>>
pub fn on_submit<T, E, F, Fut>( &self, handler: F, ) -> impl Future<Output = Result<T, SubmitError<E>>>
Composes the submit boundary as a plain future: whole-form sync
validation first (a failure resolves with SubmitError::Validation
and never constructs handler), then a FormSnapshot gate,
is_submitting bracketing the attempt via a drop guard — the flag
resets on success, handler error, validation failure, AND when the
composed future is dropped (cancelled) mid-flight. No spawner
required; the caller owns scheduling.
This never flips the FormController::submitted flag: the caller
owns that (formars-ui’s form glue flips it before awaiting), so headless
callers who skip the flip keep Submit-gated errors hidden.
Sourcepub fn reset(&self)
pub fn reset(&self)
Restores every field to its pristine registered state and clears all form-level (unmatched) server issues.
The FormController::submitted flag is deliberately NOT cleared:
the caller owns it, mirroring FormController::on_submit (which
never flips it).
Trait Implementations§
Source§impl Clone for FormController
impl Clone for FormController
Source§fn clone(&self) -> FormController
fn clone(&self) -> FormController
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read moreAuto Trait Implementations§
impl !RefUnwindSafe for FormController
impl !UnwindSafe for FormController
impl Freeze for FormController
impl Send for FormController
impl Sync for FormController
impl Unpin for FormController
impl UnsafeUnpin for FormController
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more