reinhardt_forms/

lib.rs

#![warn(missing_docs)]

//! # Reinhardt Forms
//!
//! Form processing and validation for the Reinhardt framework.
//!
//! ## Overview
//!
//! This crate provides comprehensive form processing capabilities inspired by Django's
//! form system, focusing on data validation and multi-step form wizards.
//!
//! This crate is designed to be WASM-compatible, providing a pure form processing layer
//! without HTML generation or platform-specific features.
//!
//! ## Features
//!
//! - **[`Form`]**: Base form class with validation
//! - **[`ModelForm`]**: Auto-generated forms from model definitions
//! - **[`FormSet`]**: Handle multiple forms of the same type
//! - **[`FormWizard`]**: Multi-step form workflows
//! - **Field Types**: 20+ field types (CharField, IntegerField, EmailField, etc.)
//! - **WASM Support**: Compatible with WebAssembly targets via `wasm_compat` module
//!
//! ## Quick Start
//!
//! ### Basic Form
//!
//! ```rust,ignore
//! use reinhardt_forms::{Form, CharField, EmailField, IntegerField};
//!
//! // Build a form imperatively using add_field()
//! let mut form = Form::new();
//! form.add_field(Box::new(CharField::new("name")));
//! form.add_field(Box::new(EmailField::new("email")));
//! form.add_field(Box::new(IntegerField::new("age")));
//! form.add_field(Box::new(CharField::new("message")));
//!
//! // Validate form data
//! form.bind(&request_data);
//! if form.is_valid() {
//!     // Process the validated form...
//! } else {
//!     let errors = form.errors();
//! }
//! ```
//!
//! ### Prefixed Form Data
//!
//! A prefixed form expects submitted field names to use the prefix. The
//! validated values are exposed through canonical field names, while bound
//! fields continue to read the original submitted values for rerendering.
//!
//! ```rust
//! use reinhardt_forms::{CharField, Field, Form};
//! use serde_json::json;
//! use std::collections::HashMap;
//!
//! let mut form = Form::with_prefix("profile".to_string());
//! form.add_field(Box::new(CharField::new("name".to_string()).required()));
//! form.bind(HashMap::from([("profile-name".to_string(), json!("Ada"))]));
//!
//! assert!(form.is_valid());
//! assert_eq!(form.cleaned_data().get("name"), Some(&json!("Ada")));
//! assert_eq!(
//!     form.get_bound_field("name").unwrap().value(),
//!     Some(&json!("Ada"))
//! );
//! ```
//!
//! ### Model Form
//!
//! ```rust,ignore
//! use reinhardt_forms::{ModelForm, ModelFormBuilder};
//!
//! // Auto-generate form from User model
//! let form = ModelFormBuilder::<User>::new()
//!     .fields(vec!["username".to_string(), "email".to_string(), "bio".to_string()])
//!     .exclude(vec!["password".to_string()])
//!     .build();
//! ```
//!
//! ## Available Field Types
//!
//! | Field | Description |
//! |-------|-------------|
//! | [`CharField`] | Text input with max_length validation |
//! | [`IntegerField`] | Integer input with min/max validation |
//! | [`FloatField`] | Floating-point number input |
//! | [`DecimalField`] | Decimal number with precision control |
//! | [`BooleanField`] | Checkbox input |
//! | [`EmailField`] | Email address validation |
//! | [`URLField`] | URL validation |
//! | [`DateField`] | Date input with format parsing |
//! | [`DateTimeField`] | DateTime input |
//! | [`TimeField`] | Time input |
//! | [`DurationField`] | Duration input |
//! | [`FileField`] | File upload |
//! | [`ImageField`] | Image upload with dimension validation |
//! | [`ChoiceField`] | Select dropdown |
//! | [`MultipleChoiceField`] | Multi-select |
//! | [`ModelChoiceField`] | Foreign key selection |
//! | [`ModelMultipleChoiceField`] | Multiple model selection with normalized dirty-state comparison |
//! | [`JSONField`] | JSON data input |
//! | [`UUIDField`] | UUID input |
//! | [`SlugField`] | URL-safe slug input |
//! | [`RegexField`] | Custom regex validation |
//!
//! `ModelMultipleChoiceField` compares selected values without considering
//! order when [`Form::has_changed`] runs. Numeric IDs and strings with the same
//! textual representation are equivalent, while booleans, nulls, arrays, and
//! objects remain distinct JSON types.
//!
//! ## FormSets
//!
//! Handle multiple forms of the same type:
//!
//! ```rust,ignore
//! use reinhardt_forms::{FormSet, FormSetFactory};
//!
//! // Create a formset with 3 forms
//! let formset = FormSetFactory::<ItemForm>::new()
//!     .extra(3)
//!     .min_num(1)
//!     .max_num(10)
//!     .build();
//!
//! if formset.is_valid() {
//!     for form in formset.forms() {
//!         // Process each form
//!     }
//! }
//! ```
//!
//! ## Form Wizard
//!
//! Multi-step forms:
//!
//! ```rust,ignore
//! use reinhardt_forms::{FormWizard, WizardStep};
//!
//! let wizard = FormWizard::new()
//!     .add_step(WizardStep::new("account", AccountForm::new()))
//!     .add_step(WizardStep::new("profile", ProfileForm::new()))
//!     .add_step(WizardStep::new("confirmation", ConfirmForm::new()));
//!
//! // Process wizard step
//! let result = wizard.process_step(&request).await?;
//! ```

/// Bound field rendering with data and errors attached.
pub mod bound_field;
/// Core form field trait and error types.
pub mod field;
/// Built-in field types (text, email, integer, choice, etc.).
pub mod fields;
/// Form trait and validation logic.
pub mod form;
/// Formset for managing multiple form instances.
pub mod formset;
/// Built-in formset types (inline, base).
pub mod formsets;
/// Model-backed form with automatic field generation.
pub mod model_form;
/// Model-backed formset for bulk editing.
pub mod model_formset;
/// Field-level and form-level validators.
pub mod validators;
/// WASM compatibility layer for client-side forms.
pub mod wasm_compat;
/// Multi-step form wizard.
pub mod wizard;

pub use bound_field::BoundField;
pub use field::{
	ErrorType,
	FieldError,
	FieldResult,
	FormField as Field, // Alias for compatibility
	FormField,
	Widget,
	escape_attribute,
	html_escape,
};
pub use fields::{
	BooleanField, CharField, ChoiceField, ColorField, ComboField, DateField, DateTimeField,
	DecimalField, DurationField, EmailField, FileField, FloatField, GenericIPAddressField,
	IPProtocol, ImageField, IntegerField, JSONField, ModelChoiceField, ModelMultipleChoiceField,
	MultiValueField, MultipleChoiceField, PASSWORD_REDACTED, PasswordField, RegexField, SlugField,
	SplitDateTimeField, TimeField, URLField, UUIDField,
};
pub use form::{Form, FormError, FormResult};
pub use formset::FormSet;
pub use formsets::{
	FormSetFactory,
	InlineFormSet,
	ModelFormSet as AdvancedModelFormSet, // Renamed to avoid conflict
};
pub use model_form::{FieldType, FormModel, ModelForm, ModelFormBuilder, ModelFormConfig};
pub use model_formset::{ModelFormSet, ModelFormSetBuilder, ModelFormSetConfig};
pub use validators::{SlugValidator, UrlValidator};
pub use wizard::{FormWizard, WizardStep};