guise/reactive/

form.rs

//! Form state: values, validators, and errors keyed by field name.
//!
//! Two layers:
//!
//! - [`FormState`] — the pure model (values + validators + errors), unit
//!   testable with no gpui. Hold it in a [`Signal`] via [`use_form`] when a
//!   plain map is all you need.
//! - [`Form`] — the reactive layer: **every field is its own
//!   `Signal<String>`**, so it plugs straight into any input's `bind`
//!   (`TextInput::bind(&input, form.signal("email"), cx)`). Rules can see
//!   the whole form (cross-field), errors live in a signal views can watch,
//!   and fields that failed validation re-validate live as they're edited.
//!
//! ```ignore
//! let form = Form::new(cx)
//!     .field(cx, "email", "")
//!     .rule("email", validators::required())
//!     .rule("email", validators::email())
//!     .field(cx, "confirm", "")
//!     .rule("confirm", validators::equals_field("email", "Emails must match"));
//!
//! TextInput::bind(&email_input, form.signal("email"), cx);
//! // in the submit handler:
//! if form.validate(cx) { save(form.value(cx, "email")); }
//! // in render:
//! Field::new().error_opt(form.error(cx, "email"))
//! ```

use std::cell::RefCell;
use std::collections::{HashMap, HashSet};
use std::rc::Rc;

use gpui::App;

use super::signal::Signal;

/// A validator: returns `Some(message)` when the value is invalid.
pub type Validator = Box<dyn Fn(&str) -> Option<String> + 'static>;

/// Form values + validators + the errors produced by the last validation.
#[derive(Default)]
pub struct FormState {
    values: HashMap<&'static str, String>,
    errors: HashMap<&'static str, String>,
    validators: HashMap<&'static str, Validator>,
}

impl FormState {
    pub fn new() -> Self {
        FormState::default()
    }

    /// Register a field with an initial value (builder form).
    pub fn field(mut self, name: &'static str, initial: impl Into<String>) -> Self {
        self.values.insert(name, initial.into());
        self
    }

    /// Attach a validator to a field (builder form).
    pub fn validator(mut self, name: &'static str, validator: Validator) -> Self {
        self.validators.insert(name, validator);
        self
    }

    /// The current value of a field (empty string if unset).
    pub fn value(&self, name: &str) -> &str {
        self.values.get(name).map(String::as_str).unwrap_or("")
    }

    /// Set a field's value and clear its error.
    pub fn set(&mut self, name: &'static str, value: impl Into<String>) {
        self.values.insert(name, value.into());
        self.errors.remove(name);
    }

    /// Validate one field, recording or clearing its error. Returns validity.
    pub fn validate_field(&mut self, name: &'static str) -> bool {
        if let Some(validator) = self.validators.get(name) {
            let value = self.values.get(name).map(String::as_str).unwrap_or("");
            match validator(value) {
                Some(message) => {
                    self.errors.insert(name, message);
                    return false;
                }
                None => {
                    self.errors.remove(name);
                }
            }
        }
        true
    }

    /// Validate every field with a validator. Returns whether all passed.
    pub fn validate(&mut self) -> bool {
        let names: Vec<&'static str> = self.validators.keys().copied().collect();
        let mut ok = true;
        for name in names {
            ok &= self.validate_field(name);
        }
        ok
    }

    /// The error message for a field, if the last validation produced one.
    pub fn error(&self, name: &str) -> Option<&str> {
        self.errors.get(name).map(String::as_str)
    }

    /// Whether there are no recorded errors.
    pub fn is_valid(&self) -> bool {
        self.errors.is_empty()
    }
}

/// A snapshot of every field's value, passed to [`Rule`]s so they can
/// cross-reference other fields.
pub type FormValues = HashMap<&'static str, String>;

/// A form-aware validator: sees the field's value and the whole form.
/// Plain [`Validator`]s lift into rules automatically via [`Form::rule`].
pub type Rule = Box<dyn Fn(&str, &FormValues) -> Option<String> + 'static>;

/// Built-in validators.
pub mod validators {
    use super::{FormValues, Rule, Validator};

    /// Fails when the trimmed value is empty.
    pub fn required() -> Validator {
        Box::new(|v: &str| {
            if v.trim().is_empty() {
                Some("Required".to_string())
            } else {
                None
            }
        })
    }

    /// Fails when the value is shorter than `n` characters.
    pub fn min_len(n: usize) -> Validator {
        Box::new(move |v: &str| {
            if v.chars().count() < n {
                Some(format!("Must be at least {n} characters"))
            } else {
                None
            }
        })
    }

    /// Fails when the value is longer than `n` characters.
    pub fn max_len(n: usize) -> Validator {
        Box::new(move |v: &str| {
            if v.chars().count() > n {
                Some(format!("Must be at most {n} characters"))
            } else {
                None
            }
        })
    }

    /// A permissive `a@b.c` email shape check.
    pub fn email() -> Validator {
        Box::new(|v: &str| {
            let ok = v
                .split_once('@')
                .map(|(user, domain)| {
                    !user.is_empty() && domain.contains('.') && !domain.starts_with('.')
                })
                .unwrap_or(false);
            if ok {
                None
            } else {
                Some("Enter a valid email".to_string())
            }
        })
    }

    /// Fails when the value doesn't parse as a number.
    pub fn numeric() -> Validator {
        Box::new(|v: &str| {
            if v.trim().parse::<f64>().is_ok() {
                None
            } else {
                Some("Enter a number".to_string())
            }
        })
    }

    /// Fails when the value parses below `min` (non-numbers fail too).
    pub fn min_value(min: f64) -> Validator {
        Box::new(move |v: &str| match v.trim().parse::<f64>() {
            Ok(n) if n >= min => None,
            _ => Some(format!("Must be at least {min}")),
        })
    }

    /// Fails when the value parses above `max` (non-numbers fail too).
    pub fn max_value(max: f64) -> Validator {
        Box::new(move |v: &str| match v.trim().parse::<f64>() {
            Ok(n) if n <= max => None,
            _ => Some(format!("Must be at most {max}")),
        })
    }

    /// Fails when the value isn't one of the allowed options.
    pub fn one_of(options: &'static [&'static str]) -> Validator {
        Box::new(move |v: &str| {
            if options.contains(&v) {
                None
            } else {
                Some("Not an allowed value".to_string())
            }
        })
    }

    /// Custom check: `pred` returns whether the value is valid.
    pub fn matches(pred: impl Fn(&str) -> bool + 'static, message: &'static str) -> Validator {
        Box::new(move |v: &str| {
            if pred(v) {
                None
            } else {
                Some(message.to_string())
            }
        })
    }

    /// Cross-field: fails unless this value equals the named field's
    /// ("confirm password"). A [`Rule`], for [`super::Form::rule_form`].
    pub fn equals_field(other: &'static str, message: &'static str) -> Rule {
        Box::new(move |v: &str, values: &FormValues| {
            if values.get(other).map(String::as_str) == Some(v) {
                None
            } else {
                Some(message.to_string())
            }
        })
    }
}

/// The reactive form. Cheap to clone (`Rc`-shared) and `'static`, so it can
/// be captured by handlers. Field order is registration order.
pub struct Form {
    inner: Rc<FormInner>,
}

struct FormInner {
    order: RefCell<Vec<&'static str>>,
    fields: RefCell<HashMap<&'static str, Signal<String>>>,
    rules: RefCell<HashMap<&'static str, Vec<Rule>>>,
    errors: Signal<HashMap<&'static str, String>>,
    touched: RefCell<HashSet<&'static str>>,
}

impl Clone for Form {
    fn clone(&self) -> Self {
        Form {
            inner: self.inner.clone(),
        }
    }
}

impl Form {
    pub fn new(cx: &mut App) -> Self {
        Form {
            inner: Rc::new(FormInner {
                order: RefCell::new(Vec::new()),
                fields: RefCell::new(HashMap::new()),
                rules: RefCell::new(HashMap::new()),
                errors: Signal::new(cx, HashMap::new()),
                touched: RefCell::new(HashSet::new()),
            }),
        }
    }

    /// Register a field with an initial value. Each field is a
    /// `Signal<String>`; edits mark it touched, and a field carrying an error
    /// re-validates live as it changes.
    pub fn field(self, cx: &mut App, name: &'static str, initial: impl Into<String>) -> Self {
        let signal = Signal::new(cx, initial.into());
        let form = self.clone();
        cx.observe(signal.entity(), move |_observed, cx| {
            form.inner.touched.borrow_mut().insert(name);
            if form.inner.errors.read(cx).contains_key(name) {
                form.validate_field(cx, name);
            }
        })
        .detach();
        self.inner.order.borrow_mut().push(name);
        self.inner.fields.borrow_mut().insert(name, signal);
        self
    }

    /// Attach a plain [`Validator`] to a field. Multiple rules run in order;
    /// the first failure wins.
    pub fn rule(self, name: &'static str, validator: Validator) -> Self {
        self.rule_form(name, Box::new(move |value, _values| validator(value)))
    }

    /// Attach a form-aware [`Rule`] (cross-field checks like
    /// [`validators::equals_field`]).
    pub fn rule_form(self, name: &'static str, rule: Rule) -> Self {
        self.inner
            .rules
            .borrow_mut()
            .entry(name)
            .or_default()
            .push(rule);
        self
    }

    /// The field's value signal — plug it into `TextInput::bind` and friends.
    /// Panics on an unregistered name (a typo you want loud).
    pub fn signal(&self, name: &str) -> Signal<String> {
        self.inner
            .fields
            .borrow()
            .get(name)
            .unwrap_or_else(|| panic!("guise: unknown form field {name:?}"))
            .clone()
    }

    /// The errors signal (field -> message). `watch` it to re-render on
    /// validation changes.
    pub fn errors(&self) -> Signal<HashMap<&'static str, String>> {
        self.inner.errors.clone()
    }

    pub fn value(&self, cx: &App, name: &str) -> String {
        self.signal(name).get(cx)
    }

    pub fn set(&self, cx: &mut App, name: &str, value: impl Into<String>) {
        self.signal(name).set_if_changed(cx, value.into());
    }

    /// Every field's current value, keyed by name.
    pub fn values(&self, cx: &App) -> FormValues {
        let fields = self.inner.fields.borrow();
        fields
            .iter()
            .map(|(name, signal)| (*name, signal.get(cx)))
            .collect()
    }

    /// The current error for a field, if any.
    pub fn error(&self, cx: &App, name: &str) -> Option<String> {
        self.inner.errors.read(cx).get(name).cloned()
    }

    /// Whether the field has been edited since registration.
    pub fn touched(&self, name: &str) -> bool {
        self.inner.touched.borrow().contains(name)
    }

    /// Run one field's rules. Returns validity and updates the errors signal.
    pub fn validate_field(&self, cx: &mut App, name: &'static str) -> bool {
        let values = self.values(cx);
        let value = values.get(name).cloned().unwrap_or_default();
        let failure = {
            let rules = self.inner.rules.borrow();
            rules
                .get(name)
                .and_then(|list| list.iter().find_map(|rule| rule(&value, &values)))
        };
        let ok = failure.is_none();
        self.inner.errors.update(cx, |errors| match failure {
            Some(message) => {
                errors.insert(name, message);
            }
            None => {
                errors.remove(name);
            }
        });
        ok
    }

    /// Run every field's rules (in registration order). Returns whether all
    /// passed; the errors signal ends up reflecting exactly this pass.
    pub fn validate(&self, cx: &mut App) -> bool {
        let names: Vec<&'static str> = self.inner.order.borrow().clone();
        let mut ok = true;
        for name in names {
            ok &= self.validate_field(cx, name);
        }
        ok
    }

    /// Whether the last validation left no errors.
    pub fn is_valid(&self, cx: &App) -> bool {
        self.inner.errors.read(cx).is_empty()
    }

    /// Validate and hand back the values on success — the submit-handler
    /// one-liner.
    pub fn submit(&self, cx: &mut App) -> Option<FormValues> {
        if self.validate(cx) {
            Some(self.values(cx))
        } else {
            None
        }
    }
}

/// Create a reactive form: a [`Signal`] wrapping the given [`FormState`].
pub fn use_form(cx: &mut App, state: FormState) -> Signal<FormState> {
    Signal::new(cx, state)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn required_and_min_len() {
        let req = validators::required();
        assert!(req("").is_some());
        assert!(req("  ").is_some());
        assert!(req("x").is_none());

        let min = validators::min_len(3);
        assert!(min("ab").is_some());
        assert!(min("abc").is_none());
    }

    #[test]
    fn email_shape() {
        let email = validators::email();
        assert!(email("nope").is_some());
        assert!(email("a@b").is_some());
        assert!(email("a@b.com").is_none());
    }

    #[test]
    fn length_and_numeric_bounds() {
        let max = validators::max_len(3);
        assert!(max("abcd").is_some());
        assert!(max("abc").is_none());

        let num = validators::numeric();
        assert!(num("12.5").is_none());
        assert!(num(" 7 ").is_none());
        assert!(num("seven").is_some());

        let min = validators::min_value(18.0);
        assert!(min("17").is_some());
        assert!(min("18").is_none());
        assert!(min("x").is_some());

        let max = validators::max_value(100.0);
        assert!(max("101").is_some());
        assert!(max("99.9").is_none());
    }

    #[test]
    fn one_of_and_matches() {
        let choice = validators::one_of(&["red", "green", "blue"]);
        assert!(choice("green").is_none());
        assert!(choice("mauve").is_some());

        let upper = validators::matches(|v| v.chars().any(char::is_uppercase), "Need a capital");
        assert!(upper("hello").is_some());
        assert_eq!(upper("Hello"), None);
    }

    #[test]
    fn equals_field_reads_the_other_value() {
        let rule = validators::equals_field("password", "Must match");
        let mut values = FormValues::new();
        values.insert("password", "hunter2".into());
        assert!(rule("hunter2", &values).is_none());
        assert_eq!(rule("hunter3", &values), Some("Must match".to_string()));
        // Missing other field never matches.
        assert!(rule("", &FormValues::new()).is_some());
    }

    #[test]
    fn set_clears_error_then_validate_repopulates() {
        let mut form = FormState::new()
            .field("name", "")
            .validator("name", validators::required());
        assert!(!form.validate());
        assert_eq!(form.error("name"), Some("Required"));

        form.set("name", "Ada");
        // set clears the field's error eagerly.
        assert_eq!(form.error("name"), None);
        assert!(form.validate());
        assert!(form.is_valid());
    }
}