relm.form — io.github.conjurernix/relm.form 0.1.0-alpha8

Declarative, robust form state management module for Relm applications.

Provides:

• Form state initialization (create) and pure state reducers (set-value, set-touched, reset-form, etc.)
• Built-in composable validators (required, email, min-num, max-num, min-length, max-length, pattern, one-of, compose)
• Whole-form and field-level validation engine (validate-form, validate-field)
• Granular view query functions for Hiccup rendering (value, error, touched?, dirty?, valid?, invalid?, submitting?)
• Declarative Relm update message handlers (::change, ::blur, ::submit, ::reset, ::set-field, ::set-values)
• Side effects for async validation and DOM input focus (::focus-field, ::focus-first-error, ::validate-async)

clear-errors cljs

(clear-errors form-state)

Clears all errors from form-state.

clear-state! cljs

(clear-state! form-or-key)

Clears all dynamically registered field configurations and validators for form-or-key.

compose cljs

(compose & validators)

Combines multiple validator functions in sequence. Returns the error message of the first failing validator, or nil if all pass.

create cljs

(create)

(create
  {:keys [id key form-key initial-values validators validate validate-on]
   :or {initial-values {} validators {} validate-on #{:submit :blur :change}}})

Creates a normalized form state map.

Options:

• :id (string, optional): Unique instance ID for the form (defaults to auto-generated UUID).
• :key / :form-key (keyword or vector, default :form): Key identifying form in component state.
• :initial-values (map, default {}): Map of initial field values (optional, can also be defined in register).
• :validators (map, default {}): Map of field paths to validator or vector of validators (optional, prefer defining in register).
• :validate (fn [values] -> error-map, optional): Form-level custom validation function.
• :validate-on (set of #{:change :blur :submit}, default #{:change :blur :submit}): When validation triggers.

dirty? cljs

(dirty? form-state)

(dirty? form-state path)

Returns true if the form (or a specific field path) has been modified from initial values.

email cljs

(email & [msg])

Validates that a field is a valid email address. Passes for nil or empty string (use required to mandate presence).

error cljs

(error form-state path)

(error form-state path only-if-touched?)

Retrieves the validation error for a field at path, or nil if valid. Optionally checks if the field is touched when only-if-touched? is true.

errors cljs

(errors form-state)

Returns the complete :errors map from form-state.

extract-event-value cljs

(extract-event-value event-or-val)

Extracts the value from a DOM event, event map, or DOM node. Handles checkboxes (checked boolean), radio buttons, select dropdowns, numbers, and standard text inputs. If passed a primitive value directly, returns it.

field cljs

Alias for register.

form-attrs cljs

(form-attrs form-or-key)

(form-attrs form-or-key attrs)

Generates standard form element attributes including unmount cleanup hook. Usage: [:form (form/form-attrs form {:on {:submit (form/on-submit form {:on-submit [::save]})}}) ...]

form-id cljs

(form-id form-or-key)

Returns the unique instance identifier of the form (or falls back to :key or :form).

form-key cljs

(form-key form-state)

Returns the key identifying the form in component state (defaulting to :form).

initial-values cljs

(initial-values form-state)

Returns the complete :initial-values map from form-state merged with registered field initial values.

invalid? cljs

(invalid? form-state)

Returns true if the form contains one or more validation errors.

key cljs

(key form-state)

Returns the key identifying the form in component state (defaulting to :form).

max-length cljs

(max-length max-len & [msg])

Validates that a string or collection has at most max-len items/characters. Passes for nil or empty values.

max-num cljs

(max-num max-val & [msg])

Validates that a numeric field is at most max-val. Passes for nil or empty string. Parses string numbers automatically.

min-length cljs

(min-length min-len & [msg])

Validates that a string or collection has at least min-len items/characters. Passes for nil or empty values.

min-num cljs

(min-num min-val & [msg])

Validates that a numeric field is at least min-val. Passes for nil or empty string. Parses string numbers automatically.

normalize-path cljs

(normalize-path path)

Ensures a field path is represented as a vector of keys/indexes. Accepts a keyword (e.g. :email), a symbol, or a vector (e.g. [:user :address :city]).

on-blur cljs

(on-blur form-or-key path)

Constructs a message vector for the :blur DOM event. Usage: (on-blur form :email) (on-blur :form :email) (on-blur form [:user :email])

on-change cljs

(on-change form-or-key path)

Constructs a message vector for the :input or :change DOM event. Usage: (on-change form :email) (on-change :form :email) (on-change form [:user :email])

on-clear cljs

(on-clear form-or-key)

Constructs a message vector for clearing form state upon unmounting from the DOM. Usage: (on-clear form) (on-clear :form)

on-reset cljs

(on-reset form-or-key)

Constructs a message vector for the ::form/reset event. Usage: (on-reset form) (on-reset :form)

on-submit cljs

(on-submit form-or-key opts)

Constructs a message vector for the :submit DOM event. Usage: (on-submit form {:on-submit [::save-user] :on-invalid [::show-toast]}) (on-submit :form {:on-submit [::save-user]})

one-of cljs

(one-of allowed-coll & [msg])

Validates that a value is contained in allowed-coll. Passes for nil or empty string.

pattern cljs

(pattern regex & [msg])

Validates that a string matches the provided regular expression regex (or regex string). Passes for nil or empty string.

pristine? cljs

(pristine? form-state)

(pristine? form-state path)

Returns true if the form (or a specific field path) is unmodified from initial values.

register cljs

(register form-state path)

(register form-state path-or-key opts-or-path)

(register form-state form-key path opts)

Generates standard Hiccup input attributes, event handlers, and registers validation rules and initial values for a form field.

Parameters:

• form-state: The current form state map (extracts :key automatically, default :form).
• path: The field key or vector path (e.g. :email or [:profile :age]).
• opts: (Optional) Map of options, initial values, validators, and HTML attributes:
  • :type - Input type ("text", "email", "password", "number", "checkbox", etc.)
  • :initial-value / :default / :value - Initial/default field value
  • :required - Boolean (true), custom error string, or {:value true :message "..."}
  • :email - Boolean (true), custom error string, or {:value true :message "..."}
  • :min - Numeric constraint (sets :min HTML attr & validates min-num)
  • :max - Numeric constraint (sets :max HTML attr & validates max-num)
  • :min-length / :minlength - Length constraint (sets :minlength HTML attr & validates min-length)
  • :max-length / :maxlength - Length constraint (sets :maxlength HTML attr & validates max-length)
  • :pattern - Regex or [regex "msg"] (sets :pattern HTML attr & validates regex match)
  • :one-of - Collection of allowed values or [coll "msg"]
  • :validate - Custom validator function (fn [val values]) or (fn [val])
  • :validators - Vector of validator functions
  • Any additional HTML attributes (e.g. :placeholder, :autocomplete, :disabled)

Usage: (register form :email {:type "email" :required "Email is required" :default "[e-mail]"}) (register form [:profile :age] {:type "number" :min [18 "Must be 18+"] :max 120}) (register form [:preferences :newsletter] {:type "checkbox" :default true}) (register form :confirm-password {:type "password" :required true :validate (fn [v values] ...)}) (register form :form :email {:type "email"}) ;; backwards compatibility

required cljs

(required & [msg])

Validates that a field has a non-empty value. Rejects nil, blank strings, empty collections, and boolean false.

reset-form cljs

(reset-form form-state)

(reset-form form-state new-initial-values)

Resets the form state back to initial state or with new-initial-values.

set-error cljs

(set-error form-state path error-msg)

Sets or clears an error message for a field at path.

set-errors cljs

(set-errors form-state errors-map)

Replaces the entire :errors map with errors-map, normalizing all keys into vector paths.

set-touched cljs

(set-touched form-state path)

(set-touched form-state path is-touched?)

Marks or unmarks a field at path as touched. If marked touched and :validate-on includes :blur, validates the form.

set-value cljs

(set-value form-state path value)

Updates the value of a field at path. If :validate-on includes :change, validates the form.

set-values cljs

(set-values form-state new-values)

Updates multiple form values. If :validate-on includes :change, re-validates the entire form.

submit-count cljs

(submit-count form-state)

Returns the number of times form submission has been attempted.

submit-end cljs

(submit-end form-state)

(submit-end form-state status)

Finishes form submission, setting :submitting? false and updating :status.

submit-start cljs

(submit-start form-state)

Marks the form as actively submitting and increments :submit-count.

submitting? cljs

(submitting? form-state)

Returns true if the form is currently in a submitting state.

touch-all cljs

(touch-all form-state)

Marks all fields (all configured validator paths and value paths) as touched.

touched cljs

(touched form-state)

Returns the set of touched paths from form-state.

touched? cljs

(touched? form-state path)

Returns true if the field at path has been touched/blurred.

valid? cljs

(valid? form-state)

Returns true if the form has no validation errors.

validate-field cljs

(validate-field form-state path)

Validates a single field at path against its configured validators and optional :validate-fn. Updates form-state with the field validation result.

validate-form cljs

(validate-form form-state)

Executes all configured field validators and optional form-level :validate-fn on form-state. Merges validators configured via form/create with dynamic validators defined via form/register. Returns updated form-state with :errors map populated.

value cljs

(value form-state path)

(value form-state path default-val)

Retrieves the current value of a field at path, returning registered initial value or default-val if not set.

values cljs

(values form-state)

Returns the complete :values map from form-state merged with registered field defaults.