Expand description
formars-ui: Leptos 0.8 companion crate for formars-signals — the
use_form hook, the <Form> submit wrapper, and the <TextField> field
binding.
§Dependency note: effects availability (FU-DEP-3)
Both leptos and reactive_graph are declared here with
default-features = false. In reactive_graph 0.2.x the effect module
(reactive_graph::effect) is UNCONDITIONAL — the optional effects
feature gates only debug diagnostics, so no effects feature edge
appears in cargo tree -e features at all. This is EXPECTED and
harmless: formars-signals remains intact because its code paths never
schedule effects (FS-DEP-2 holds); only this crate’s <TextField>
display effect uses the always-present module.
§SSR submit exclusion (FU-FM-6)
<Form> markup may render server-side, but submit execution is
client-path only in v0: leptos::task::spawn_local requires a
local-task executor unavailable on server threads, and the composed
submit future is deliberately NOT Send, so it can never be driven by
tokio::spawn.
§Context resolution behavior (FU-HK-2)
use_form provisions the controller as Leptos context.
use_form_controller() PANICS outside any use_form tree;
try_form_controller() is the graceful Option-returning variant.
§IME / caret caveat (FU-TF-2)
<TextField> pushes signal content back to the DOM only when it differs
from the current DOM value, which prevents caret jumps from same-value
writes and avoids fighting mid-composition IME state. Residual
composition edge cases vary by rendering engine; treat them as a known
limitation and verify manually in a browser.
§No-provider blur behavior (L-1)
When no ancestor called use_form, <TextField>’s blur seam resolves
no controller and skips touch-marking: the component still renders and
binds values correctly.
§Double-submit race shield (L-2)
<Form> guards each attempt against an in-flight submit and renders its
built-in button reactively disabled while submitting. A pathological
rapid double-click that slips two attempts past the guard before
is_submitting flips cannot be fully excluded natively; the reactive
disabled state is the primary shield and this residual race is a known
v0 edge.
Structs§
- Field
Handle - Accessor view over one registered field’s reactive cells.
- Field
Path - Address of the field a
FormaIssuerefers to. - Form
Controller - Controller-owned registry of form fields.
- Form
Snapshot - 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.
- Forma
Error - Every constraint violated during one parse call, in declaration order (ER-1).
- Forma
Issue - One violated constraint: where (
FieldPath), what (IssueCode), human-readable message, and structured parameters. - UseForm
- Returned by
use_form; the hook also provisions the controller as Leptos context so descendants can resolve it.
Enums§
- Issue
Code - Stable, enumerable identifiers for every builtin constraint (ER-3), plus
IssueCode::Customfor consumer-defined ones. - Register
Error - Error returned by
FormController::register. - Submit
Error - Why a composed submit future failed.
- Submit
Outcome - Mirrors
SubmitErrorarms plus success, delivered to the caller’son_outcomecallback. - Validate
On - 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::DynSchemaview.
Functions§
- Form
- Encapsulates async form submission over a
FormController. - Text
Field - One bound string field: bidirectional value bridge over the handle’s
get_str/set_strconvenience layer, touch-on-blur via the resolved controller, gated error rendering, and conditional pushback. - try_
form_ controller - Graceful variant of
use_form_controller:Nonewhen no ancestor calleduse_form. - use_
form - Constructs a controller with
default_validate_on, provides it as context (provide_context(controller.clone())), and returns it. - use_
form_ controller - Resolves the ancestor-provided form controller.