Skip to main content

formars_ui/
lib.rs

1//! `formars-ui`: Leptos 0.8 companion crate for `formars-signals` — the
2//! `use_form` hook, the `<Form>` submit wrapper, and the `<TextField>` field
3//! binding.
4//!
5//! # Dependency note: effects availability (FU-DEP-3)
6//!
7//! Both `leptos` and `reactive_graph` are declared here with
8//! `default-features = false`. In `reactive_graph` 0.2.x the effect module
9//! (`reactive_graph::effect`) is UNCONDITIONAL — the optional `effects`
10//! feature gates only debug diagnostics, so no `effects` feature edge
11//! appears in `cargo tree -e features` at all. This is EXPECTED and
12//! harmless: `formars-signals` remains intact because its code paths never
13//! schedule effects (`FS-DEP-2` holds); only this crate's `<TextField>`
14//! display effect uses the always-present module.
15//!
16//! # SSR submit exclusion (FU-FM-6)
17//!
18//! `<Form>` markup may render server-side, but submit execution is
19//! client-path only in v0: [`leptos::task::spawn_local`] requires a
20//! local-task executor unavailable on server threads, and the composed
21//! submit future is deliberately NOT `Send`, so it can never be driven by
22//! `tokio::spawn`.
23//!
24//! # Context resolution behavior (FU-HK-2)
25//!
26//! [`use_form`] provisions the controller as Leptos context.
27//! [`use_form_controller()`] PANICS outside any `use_form` tree;
28//! [`try_form_controller()`] is the graceful `Option`-returning variant.
29//!
30//! # IME / caret caveat (FU-TF-2)
31//!
32//! `<TextField>` pushes signal content back to the DOM only when it differs
33//! from the current DOM value, which prevents caret jumps from same-value
34//! writes and avoids fighting mid-composition IME state. Residual
35//! composition edge cases vary by rendering engine; treat them as a known
36//! limitation and verify manually in a browser.
37//!
38//! # No-provider blur behavior (L-1)
39//!
40//! When no ancestor called [`use_form`], `<TextField>`'s blur seam resolves
41//! no controller and skips touch-marking: the component still renders and
42//! binds values correctly.
43//!
44//! # Double-submit race shield (L-2)
45//!
46//! `<Form>` guards each attempt against an in-flight submit and renders its
47//! built-in button reactively disabled while submitting. A pathological
48//! rapid double-click that slips two attempts past the guard before
49//! `is_submitting` flips cannot be fully excluded natively; the reactive
50//! disabled state is the primary shield and this residual race is a known
51//! v0 edge.
52
53mod form;
54mod text_field;
55mod use_form;
56
57pub use form::{Form, SubmitOutcome};
58pub use use_form::{UseForm, try_form_controller, use_form, use_form_controller};
59
60// One-import DX (FU-IN-1): everything a consumer needs from the base layer.
61pub use formars_signals::{
62    FieldHandle, FieldPath, FormController, FormSnapshot, FormaError, FormaIssue, IssueCode,
63    RegisterError, SubmitError, ValidateOn, Value,
64};
65
66pub use text_field::TextField;