Formless

class Initial v  where

A type class that provides initial values for form fields. While superficially similar to Haskell's Default type class, this class is only meant for the purposes of defining initial form values. If you need a default value for a field in your form, you are better off defining it as a Maybe field and providing a default as part of validation.

In general, if you find yourself reaching for this type class without defining your form as a row and generating your form spec from it, then you are probably not doing what you intend.

Members

• initial :: v

Instances

• Initial Unit
• Initial Boolean
• Initial Int
• Initial Number
• Initial String
• Initial Ordering
• Initial (Maybe a)
• Initial (Array a)
• Initial (List a)
• (Ord k) => Initial (Map k v)
• (Monoid b) => Initial (a -> b)
• (Initial a, Initial b) => Initial (Tuple a b)
• (RowToList row list, MonoidRecord list row row) => Initial (Record row)

eval :: forall ivfs ifs os vs us fxs fs ivs ixs is m form. RowToList is ixs => RowToList fs fxs => EqRecord ixs is => InputFieldsToFormFields ixs is fs => FormFieldsToInputFields fxs fs is => CountErrors fxs fs => AllTouched fxs fs => SetFormFieldsTouched fxs fs fs => ReplaceFormFieldInputs is fxs fs fs => ModifyAll ifs fxs fs fs => ValidateAll vs fxs fs fs m => FormFieldToMaybeOutput fxs fs os => Newtype (form Record InputField) (Record is) => Newtype (form Record InputFunction) (Record ifs) => Newtype (form Record FormField) (Record fs) => Newtype (form Record OutputField) (Record os) => Newtype (form Record (Validation form m)) (Record vs) => Newtype (form Variant InputField) (Variant ivs) => Newtype (form Variant InputFunction) (Variant ivfs) => Newtype (form Variant U) (Variant us) => Monad m => Query form -> State form m -> m (Either (State form m) (form Record OutputField))

data FormFieldResult error output

A data type which represents the possible output states of the field. Use the helpers in Retrieve to easily manipulate this type.

Constructors

• NotValidated
• Validating
• Error error
• Success output

Instances

• Generic (FormFieldResult e o) _
• (Eq e, Eq o) => Eq (FormFieldResult e o)
• Functor (FormFieldResult e)
• Apply (FormFieldResult e)
• Applicative (FormFieldResult e)
• Bind (FormFieldResult e)
• Monad (FormFieldResult e)
• (Show e, Show o) => Show (FormFieldResult e o)

toMaybe :: forall o e. FormFieldResult e o -> Maybe o

fromEither :: forall o e. Either e o -> FormFieldResult e o

_Success :: forall o e. Prism' (FormFieldResult e o) o

_Error :: forall o e. Prism' (FormFieldResult e o) e

validateAll :: forall form. Query form

Validate all fields in the form, collecting errors

validate :: forall o i e t0 sym us form. IsSymbol sym => Newtype (form Variant U) (Variant us) => Cons sym (U e i o) t0 us => SProxy sym -> Query form

A helper to create the correct Validate query for Formless, given a label

submit :: forall form. Query form

Submit the form, which will trigger a Submitted result if the form validates successfully.

setValidateAll :: forall is' is form. Newtype (form Record InputField) (Record is') => HMap WrapField (Record is) (Record is') => Record is -> Query form

Provide a record of inputs to overwrite all current inputs without resetting the form (as initialize does), and then validate the entire new set of fields. Similar to calling setValidate on every field in the form.

setValidate :: forall o i e t0 sym inputs form. IsSymbol sym => Newtype (form Variant InputFunction) (Variant inputs) => Cons sym (InputFunction e i o) t0 inputs => SProxy sym -> i -> Query form

Set the input value of a form field at the specified label, also triggering validation to run on the field.

setAll :: forall is' is form. Newtype (form Record InputField) (Record is') => HMap WrapField (Record is) (Record is') => Record is -> Query form

Provide a record of input fields to overwrite all current inputs. Unlike initialize, this does not otherwise reset the form as if it were new. Similar to calling set on every field in the form.

set :: forall o i e t0 sym inputs form. IsSymbol sym => Newtype (form Variant InputFunction) (Variant inputs) => Cons sym (InputFunction e i o) t0 inputs => SProxy sym -> i -> Query form

Set the input value of a form field at the specified label

resetAll :: forall form. Query form

Reset all fields to their initial values, and reset the form to its initial pristine state, no touched fields.

reset :: forall o i e t0 sym inputs form. IsSymbol sym => Initial i => Newtype (form Variant InputFunction) (Variant inputs) => Cons sym (InputFunction e i o) t0 inputs => SProxy sym -> Query form

Reset the value of the specified form field to its default value according to the Initial type class.

modifyValidateAll :: forall ifs' ifs form. Newtype (form Record InputFunction) (Record ifs') => HMap WrapField (Record ifs) (Record ifs') => Record ifs -> Query form

Provide a record of input functions to modify all current inputs, and then validate all fields. Similar to calling modifyValidate on every field in the form.

modifyValidate :: forall o i e t0 sym inputs form. IsSymbol sym => Newtype (form Variant InputFunction) (Variant inputs) => Cons sym (InputFunction e i o) t0 inputs => SProxy sym -> (i -> i) -> Query form

Modify the input value of a form field at the specified label, also triggering validation to run on the field, with the provided function.

modifyAll :: forall ifs' ifs form. Newtype (form Record InputFunction) (Record ifs') => HMap WrapField (Record ifs) (Record ifs') => Record ifs -> Query form

Provide a record of input functions to modify all current inputs. Similar to calling modify on every field in the form.

modify :: forall o i e t0 sym inputs form. IsSymbol sym => Newtype (form Variant InputFunction) (Variant inputs) => Cons sym (InputFunction e i o) t0 inputs => SProxy sym -> (i -> i) -> Query form

Modify the input value of a form field at the specified label with the provided function.

loadForm_ :: forall form. form Record InputField -> Query form

initialize as an action, so you don't need to specify a Unit result. Use to skip a use of Halogen.action.

loadForm :: forall form. form Record InputField -> Query form

Replace all form inputs with a new set of inputs, and re-initialize the form to a new state. Useful to set a new "initial state" for a form, especially when filling a form with data loaded asynchronously.

asyncSetValidate :: forall o i e t0 sym inputs form. IsSymbol sym => Newtype (form Variant InputFunction) (Variant inputs) => Cons sym (InputFunction e i o) t0 inputs => Milliseconds -> SProxy sym -> i -> Query form

Set the input value of a form field at the specified label, while debouncing validation so that it only runs after the specified amount of time has elapsed since the last modification. Useful when you need to avoid expensive validation but do not want to wait for a blur event to validate.

asyncModifyValidate :: forall o i e t0 sym inputs form. IsSymbol sym => Newtype (form Variant InputFunction) (Variant inputs) => Cons sym (InputFunction e i o) t0 inputs => Milliseconds -> SProxy sym -> (i -> i) -> Query form

Modify the input value of a form field at the specified label, while debouncing validation so that it only runs after the specified amount of time has elapsed since the last modification. Useful when you need to avoid expensive validation but do not want to wait for a blur event to validate.

andThen :: forall form. Query form -> Query form -> Query form

Perform two Formless actions in sequence. Can be chained arbitrarily. Useful when a field needs to modify itself on change and also trigger validation on one or more other fields, or when a modification on one field should also modify another field.

data GetTouchedField

Data constructor for the getTouchedField function

Constructors

• GetTouchedField

Instances

• Mapping GetTouchedField (FormField e i o) Boolean

  Heterogeneous type class for the getTouchedField function

data GetResultField

Data constructor for the getResultField function

Constructors

• GetResultField

Instances

• Mapping GetResultField (FormField e i o) (FormFieldResult e o)

  Heterogeneous type class for the getResultField function

data GetOutput

Data constructor for the getOutput function

Constructors

• GetOutput

Instances

• Mapping GetOutput (FormField e i o) (Maybe o)

  Heterogeneous type class for the getOutput function

data GetInputField

Data constructor for the getInputField function

Constructors

• GetInputField

Instances

• Mapping GetInputField (FormField e i o) i

  Heterogeneous type class for the getInputField function

data GetError

Data constructor for the getError function

Constructors

• GetError

Instances

• Mapping GetError (FormField e i o) (Maybe e)

  Heterogeneous type class for the getError function

type GetAll f = forall r1 r0 form. HMap f r0 r1 => Newtype (form Record FormField) r0 => form Record FormField -> r1

A type representing retrieving all of a particular field with the field's constructor name. For internal use.

type FormFieldLens e i o x = forall t0 fields form sym. IsSymbol sym => Newtype (form Record FormField) (Record fields) => Cons sym (FormField e i o) t0 fields => SProxy sym -> Lens' (form Record FormField) x

A type representing a lens onto part of a form field

type FormFieldGet e i o x = forall t0 fields form sym. IsSymbol sym => Newtype (form Record FormField) (Record fields) => Cons sym (FormField e i o) t0 fields => SProxy sym -> form Record FormField -> x

A type representing a function to produce a value from a record of form fields given a particular symbol. The result of view from Data.Lens applied with a particular lens to the form.

getTouchedAll :: GetAll GetTouchedField

Get the form as a record where all fields are only the touched value

getTouched :: forall o i e. FormFieldGet e i o Boolean

Given a form, get the touched field at the specified symbol

getResultAll :: GetAll GetResultField

Get the form as a record where all fields are only the result value

getResult :: forall o i e. FormFieldGet e i o (FormFieldResult e o)

Given a form, get the result at the specified symbol

getOutputAll :: GetAll GetOutput

Get the form as a record where all fields are only the output value

getOutput :: forall o i e. FormFieldGet e i o (Maybe o)

Given a form, get the output (if it exists) at the specified symbol

getInputAll :: GetAll GetInputField

Get the form as a record where all fields are only the input value

getInput :: forall o i e. FormFieldGet e i o i

Given a form, get the input at the specified symbol

getField :: forall o i e. FormFieldGet e i o (Record (FormFieldRow e i o))

Given a form, get the field at the specified symbol

getErrorAll :: GetAll GetError

Get the form as a record where all fields are only the error value

getError :: forall o i e. FormFieldGet e i o (Maybe e)

Given a form, get the error (if it exists) at the specified symbol

_FieldTouched :: forall o i e. FormFieldLens e i o Boolean

A lens to operate on the 'touched' field at a given symbol in your form

_FieldResult :: forall o i e. FormFieldLens e i o (FormFieldResult e o)

A lens to operate on the 'result' field at a given symbol in your form

_FieldOutput :: forall o i e t0 fields form sym. IsSymbol sym => Newtype (form Record FormField) (Record fields) => Cons sym (FormField e i o) t0 fields => SProxy sym -> Traversal' (form Record FormField) o

A traversal to operate on the possible output inside the 'result' field at a given symbol in your form

_FieldInput :: forall o i e. FormFieldLens e i o i

A lens to operate on the input at a given symbol in your form

_FieldError :: forall o i e t0 fields form sym. IsSymbol sym => Newtype (form Record FormField) (Record fields) => Cons sym (FormField e i o) t0 fields => SProxy sym -> Traversal' (form Record FormField) e

A traversal to operate on the possible error inside the 'result' field at a given symbol in your form

_Field :: forall o i e. FormFieldLens e i o (Record (FormFieldRow e i o))

A lens to operate on the field at a given symbol in your form

data WrapField

Wrap every field in a record with a particular newtype

Constructors

• WrapField

Instances

• (Newtype wrapper x) => Mapping WrapField x wrapper

data UnwrapField

Unwrap every newtype in a record filled with newtypes

Constructors

• UnwrapField

Instances

• (Newtype wrapper x) => Mapping UnwrapField wrapper x

wrapRecord :: forall r1 r0. HMap WrapField r0 r1 => r0 -> r1

wrapInputFunctions :: forall ifs' ifs form. Newtype (form Record InputFunction) (Record ifs') => HMap WrapField (Record ifs) (Record ifs') => Record ifs -> form Record InputFunction

Provided a record, where each field in the record contains a function from input -> input, wraps each function in the InputField type for compatibility with Formless

wrapInputFields :: forall is' is form. Newtype (form Record InputField) (Record is') => HMap WrapField (Record is) (Record is') => Record is -> form Record InputField

Provided a record, where each field in the record contains a value of type input, wraps each value in the InputField type for compatibility with Formless

unwrapRecord :: forall r1 r0. HMap UnwrapField r0 r1 => r0 -> r1

unwrapOutputFields :: forall os' os form. Newtype (form Record OutputField) (Record os) => HMap UnwrapField (Record os) (Record os') => form Record OutputField -> Record os'

Provided your form type containing a record of only valid outputs from the result of validation, unwraps the form and every value in the record to provide a record of only the output values.

type SProxies form = forall inputs row xs. RowToList inputs xs => Newtype (form Record InputField) (Record inputs) => MakeSProxies xs row => Record row

A type to collect constraints necessary to apply to prove that a record of SProxies is compatible with your form type.

class MakeInputFieldsFromRow (xs :: RowList) (row :: Row Type) (to :: Row Type) | xs -> to where

The class that provides the Builder implementation to efficiently transform a row into a proper InputFields by wrapping it in newtypes and supplying initial values

Members

• mkInputFieldsFromRowBuilder :: RLProxy xs -> RProxy row -> FromScratch to

Instances

• MakeInputFieldsFromRow Nil row ()
• (IsSymbol name, Initial i, Cons name (InputField e i o) trash row, MakeInputFieldsFromRow tail row from, Row1Cons name (InputField e i o) from to) => MakeInputFieldsFromRow (Cons name (InputField e i o) tail) row to

class MakeSProxies (xs :: RowList) (to :: Row Type) | xs -> to where

The class used to build up a new record of symbol proxies from an input row list.

Members

• makeSProxiesBuilder :: RLProxy xs -> FromScratch to

Instances

• MakeSProxies Nil ()
• (IsSymbol name, Row1Cons name (SProxy name) from to, MakeSProxies tail from) => MakeSProxies (Cons name x tail) to

mkSProxies :: forall row inputs xs form. RowToList inputs xs => Newtype (form Record InputField) (Record inputs) => MakeSProxies xs row => FormProxy form -> Record row

A helper function to produce a record of SProxies given a form spec, to save you the boilerplate of writing them all out.

mkInputFields :: forall inputs form xs. RowToList inputs xs => Newtype (form Record InputField) (Record inputs) => MakeInputFieldsFromRow xs inputs inputs => FormProxy form -> form Record InputField

A function to transform a row of labels into a InputFields. This allows you to go directly from a custom form newtype to an inputs record without having to fill in any values. Requires that all members have an instance of the Initial type class (all monoidal values do by default, along with some other primitives).

data U e i o

Represents a unit value with the correct number of arguments; largely for internal use.

Constructors

• U

type OutputType error input output = output

A type synonym that lets you pick out just the output type from your form row.

newtype OutputField error input output

A wrapper to represent only the output type. Used to represent form results at the end of validation.

Constructors

• OutputField output

Instances

• Newtype (OutputField e i o) _
• (Eq o) => Eq (OutputField e i o)

type InputType error input output = input

A type synonym that lets you pick out just the input type from your form row.

newtype InputFunction error input output

Represents modifications to input fields

Constructors

• InputFunction (input -> input)

Instances

• Newtype (InputFunction e i o) _

newtype InputField error input output

A wrapper to represent only the input type. Requires that eq is defined for the input type in order to track dirty states.

Constructors

• InputField input

Instances

• Newtype (InputField e i o) _
• (Eq i) => Eq (InputField e i o)

data FormProxy (form :: (Row Type -> Type) -> (Type -> Type -> Type -> Type) -> Type)

Create a proxy for your form type, for use with functions that generate records from form proxies.

Constructors

• FormProxy

type FormFieldRow error input output = (input :: input, result :: FormFieldResult error output, touched :: Boolean)

The row used for the FormField newtype and in lens type signatures

newtype FormField e i o

The type that we need to record state across the form

Constructors

• FormField (Record (FormFieldRow e i o))

Instances

• Newtype (FormField e i o) _
• (Eq e, Eq i, Eq o) => Eq (FormField e i o)

type ErrorType error input output = error

A type synonym that lets you pick out just the error type from your form row.

data ValidStatus

A type to represent a running debouncer A type to represent validation status

Constructors

• Invalid
• Incomplete
• Valid

Instances

• Generic ValidStatus _
• Eq ValidStatus
• Ord ValidStatus
• Show ValidStatus

type StateRow form r = (dirty :: Boolean, errors :: Int, form :: form Record FormField, submitAttempts :: Int, submitting :: Boolean, validity :: ValidStatus | r)

The component's public state

type State form m = Record (StateRow form (internal :: InternalState form m))

The component local state

data Query form

The component query type. See Formless.Query for helpers related to constructing and using these queries.

Constructors

• Modify (form Variant InputFunction)
• Validate (form Variant U)
• ModifyValidate (Maybe Milliseconds) (form Variant InputFunction)
• Reset (form Variant InputFunction)
• SetAll (form Record InputField)
• ModifyAll (form Record InputFunction)
• ResetAll
• ValidateAll
• Submit
• LoadForm (form Record InputField)
• AndThen (Query form) (Query form)

type PublicState form = Record (StateRow form ())

The component's public state

newtype InternalState form m

A newtype to make easier type errors for end users to read by hiding internal fields

Constructors

• InternalState { allTouched :: Boolean, initialInputs :: form Record InputField, validators :: form Record (Validation form m) }

Instances

• Newtype (InternalState form m) _

newtype Validation form m error input output

A wrapper to represent the validation function on a form field, which can itself take the form state as its first argument. Inspired in some parts by the Validation type from purescript-polyform by @paluh.

Constructors

• Validation (form Record FormField -> input -> m (Either error output))

Instances

• Newtype (Validation form m e i o) _
• (Functor m) => Functor (Validation form m e i)
• (Monad m) => Apply (Validation form m e i)
• (Monad m) => Applicative (Validation form m e i)
• (Monad m) => Alt (Validation form m e i)
• (Semigroup (m (Either e o))) => Semigroup (Validation form m e i o)
• (Applicative m, Monoid (m (Either e o)), Semigroup (m (Either e o))) => Monoid (Validation form m e i o)
• (Monad m) => Semigroupoid (Validation form m e)
• (Monad m) => Category (Validation form m e)
• (Monad m) => Mapping EmptyValidators a (Validation form m e i i)

  The heterogeneous instance the noValidation function

data EmptyValidators

The data type used for the noValidation function's heterogenous instance

Constructors

• EmptyValidators

Instances

• (Monad m) => Mapping EmptyValidators a (Validation form m e i i)

  The heterogeneous instance the noValidation function

runValidation :: forall o i e m form. Monad m => Validation form m e i o -> form Record FormField -> i -> m (Either e o)

A more verbose but clearer function for running a validation function on its inputs

noValidation :: forall xs vs m fields form. Monad m => RowToList fields xs => Newtype (form Record (Validation form m)) (Record vs) => Newtype (form Record InputField) (Record fields) => MapRecordWithIndex xs (ConstMapping EmptyValidators) fields vs => form Record InputField -> form Record (Validation form m)

A function to create a record of validators that simply pass through all inputs for when no validation is needed. Provide this as your validators function.

hoistFn_ :: forall o i e m form. Monad m => (i -> o) -> Validation form m e i o

Turn a function from (i -> o) into a proper Validation

hoistFnME_ :: forall o i e m form. Monad m => (i -> m (Either e o)) -> Validation form m e i o

Turn a function from (i -> m (Either e o)) into a proper Validation

hoistFnME :: forall o i e m form. Monad m => (form Record FormField -> i -> m (Either e o)) -> Validation form m e i o

Turn a function from (form Record FormField -> i -> m (Either e o)) into a proper Validation

hoistFnE_ :: forall o i e m form. Monad m => (i -> Either e o) -> Validation form m e i o

Turn a function from (i -> Either e o) into a proper Validation

hoistFnE :: forall o i e m form. Monad m => (form Record FormField -> i -> Either e o) -> Validation form m e i o

Turn a function from (form Record FormField -> i -> Either e o) into a proper Validation

hoistFn :: forall o i e m form. Monad m => (form Record FormField -> i -> o) -> Validation form m e i o

Turn a function from (form Record FormField -> i -> o) into a proper Validation