Lumi.Components.Form

build :: forall result unvalidated props. FormBuilder { readonly :: Boolean | props } unvalidated result -> { forceTopLabels :: Boolean, formProps :: { readonly :: Boolean | props }, inlineTable :: Boolean, onChange :: (unvalidated -> unvalidated) -> Effect Unit, value :: unvalidated } -> JSX

Create a React component for a form from a FormBuilder.

Note: this function should be fully applied, to avoid remounting the component on each render.

build' :: forall result unvalidated formProps renderProps ui. (Record renderProps -> formProps -> ui -> JSX) -> FormBuilder' ui formProps unvalidated result -> { formProps :: formProps, onChange :: (unvalidated -> unvalidated) -> Effect Unit, value :: unvalidated | renderProps } -> JSX

Create a React component for a form from a FormBuilder' and a custom rendering function.

Note: this function should be fully applied, to avoid remounting the component on each render.

defaultRenderForm :: forall props. { forceTopLabels :: Boolean, inlineTable :: Boolean } -> { readonly :: Boolean | props } -> Forest -> JSX

The default Lumi implementation for rendering a forest of JSX form fields.

useForm :: forall result unvalidated props. FormBuilder { readonly :: Boolean | props } unvalidated result -> { forceTopLabels :: Boolean, formProps :: { readonly :: Boolean | props }, initialState :: unvalidated, inlineTable :: Boolean } -> Hook (UseState unvalidated) { form :: JSX, formData :: unvalidated, reset :: Effect Unit, setFormData :: (unvalidated -> unvalidated) -> Effect Unit, setModified :: Effect Unit, validated :: Maybe result }

Render a form with state managed automatically.

useForm' :: forall result unvalidated props ui. FormBuilder' ui props unvalidated result -> unvalidated -> props -> Hook (UseState unvalidated) { form :: ui, formData :: unvalidated, reset :: Effect Unit, setFormData :: (unvalidated -> unvalidated) -> Effect Unit, setModified :: Effect Unit, validated :: Maybe result }

Like useForm, but allows an alternative render implementation to be provided as an additional argument.

formState :: forall result unvalidated props. ReactComponent { forceTopLabels :: Boolean, form :: FormBuilder { readonly :: Boolean | props } unvalidated result, formProps :: { readonly :: Boolean | props }, initialState :: unvalidated, inlineTable :: Boolean, render :: { form :: JSX, formData :: unvalidated, reset :: Effect Unit, setFormData :: (unvalidated -> unvalidated) -> Effect Unit, setModified :: Effect Unit, validated :: Maybe result } -> JSX }

Consume useForm as a render-prop component. Useful when useForm would be preferred but you don't want to migrate an entire component to React's hooks API.

Note: this function should be fully applied, to avoid remounting the component on each render.

static :: forall value props. JSX -> FormBuilder props value Unit

Create an always-valid FormBuilder that renders the supplied JSX.

section :: forall value props. String -> FormBuilder props value Unit

A formatted section header used to visually separate the parts of a form

inputBox :: forall props. InputProps -> FormBuilder { readonly :: Boolean | props } String String

A configurable input box makes a FormBuilder for strings

textbox :: forall props. FormBuilder { readonly :: Boolean | props } String String

A simple text box makes a FormBuilder for strings

passwordBox :: forall props. FormBuilder { readonly :: Boolean | props } String String

A simple password box makes a FormBuilder for strings

textarea :: forall props. FormBuilder { readonly :: Boolean | props } String String

A simple text box makes a FormBuilder for strings

switch :: forall props. FormBuilder { readonly :: Boolean | props } Boolean Boolean

A switch is an editor for booleans which displays Yes or No.

radioGroup :: forall a props. Eq a => Orientation -> Array { label :: JSX, value :: a } -> FormBuilder { readonly :: Boolean | props } (Maybe a) (Maybe a)

A form that edits an optional structure represented by group of radio buttons, visually oriented in either horizontal or vertical fashion.

This is similar to select, but displays radio buttons instead.

file :: forall props. { backend :: UploadBackend, variant :: UploadVariant } -> FormBuilder { readonly :: Boolean | props } (Array FileId) (Array FileId)

A editor consisting of a file picker.

genericSelect :: forall rep a props. Generic a rep => GenericSelect rep => Array { label :: String, value :: a } -> FormBuilder { readonly :: Boolean | props } (Maybe a) (Maybe a)

given values which are composed from a sum-type, generate a select dropdown from its elements

data Yup = One | Two genericSelect [{label: "1st", value: One}, {label: "2nd", value: Two}] This would serialize to- and from select options automatically

class GenericSelect rep  where

Members

• fromString :: String -> Maybe rep
• toString :: rep -> String

Instances

• (GenericSelect a, GenericSelect b) => GenericSelect (Sum a b)
• (IsSymbol name) => GenericSelect (Constructor name NoArguments)

select :: forall a props. (a -> String) -> (String -> Maybe a) -> Array { label :: String, value :: a } -> FormBuilder { readonly :: Boolean | props } (Maybe a) (Maybe a)

A editor consisting of a single-select dropdown.

multiSelect :: forall a props. (a -> String) -> Array { label :: String, value :: a } -> FormBuilder { readonly :: Boolean | props } (Array a) (Array a)

An editor consisting of a multi-select dropdown.

asyncSelect :: forall a props. (String -> Aff (Array a)) -> (a -> SelectOption) -> (a -> JSX) -> FormBuilder { readonly :: Boolean | props } (Maybe a) (Maybe a)

An editor which uses an API call to populate a single-select drop-down.

asyncSelectByKey :: forall a id props. (id -> Aff a) -> (String -> Aff (Array a)) -> (id -> String) -> (String -> id) -> (a -> SelectOption) -> (a -> JSX) -> FormBuilder { readonly :: Boolean | props } (Maybe id) (Maybe id)

Similar to asyncSelect but allows the current value to be specified using only its key.

number :: forall props. { max :: Maybe Number, min :: Maybe Number, step :: InputStep } -> FormBuilder { readonly :: Boolean | props } String String

A form which edits a number. The form produces a string as a result in order to allow more control over validation (e.g. to allow special handling of the empty string, or to distinguish 1, 1.0, and 1.00000 from each other).

See also validNumber from the Validation module.

array :: forall a u props. { addLabel :: String, defaultValue :: u, editor :: FormBuilder { readonly :: Boolean | props } u a, label :: String } -> FormBuilder { readonly :: Boolean | props } (Array u) (Array a)

Edit an Array of values.

This FormBuilder displays a removable section for each array element, along with an "Add..." button in the final row.

fixedSizeArray :: forall a u props. { editor :: FormBuilder { readonly :: Boolean | props } u a, label :: String } -> FormBuilder { readonly :: Boolean | props } (Array u) (Array a)

Edit an Array of values without letting the user add or remove entries.

arrayModal :: forall a componentProps props. Union componentProps (onChange :: a -> Effect Unit, value :: a) (onChange :: a -> Effect Unit, value :: a | componentProps) => Nub (onChange :: a -> Effect Unit, value :: a | componentProps) (onChange :: a -> Effect Unit, value :: a | componentProps) => { addLabel :: String, component :: { onChange :: a -> Effect Unit, value :: a | componentProps } -> JSX, componentProps :: Record componentProps, defaultValue :: a, label :: String, summary :: { readonly :: Boolean | props } -> a -> JSX } -> FormBuilder { readonly :: Boolean | props } (Array a) (Array a)

Edit an Array of values.

Unlike array, this FormBuilder uses a modal popup for adding and editing array elements.

Note: arrayModal does not support validation, in the sense that the component inside the modal popup cannot reject its form state when the use clicks the save button.

fetch :: forall a props. JSX -> String -> (String -> Aff a) -> FormBuilder props (Maybe a) (Maybe a)

Form that performs an asynchronous effect whenever id changes. The result is Nothing while the effect is not completed, and a Just after the value is available.

fetch_ :: forall a props. JSX -> Aff a -> FormBuilder props (Maybe a) (Maybe a)

Performs an asynchronous effect once and returns its result encapsulated in Just. The result is Nothing while the effect is not completed.

asyncEffect :: forall a props. String -> JSX -> Aff (a -> a) -> FormBuilder props a a

A dummy form that, whenever the specified key changes, performs an asynchronous effect. It displays the specified JSX while the effect is not complete, sets the form data to the result of the effect and returns it.

effect :: forall a props. String -> Effect (a -> a) -> FormBuilder props a a

A dummy form that, whenever the specified key changes, performs an effect. It sets the form data to the result of the effect and returns it.

initializer :: forall value props. Nub (initialized :: Boolean | value) (initialized :: Boolean | value) => JSX -> (props -> Record value -> Aff ({ initialized :: Boolean | value } -> { initialized :: Boolean | value })) -> SeqFormBuilder props { initialized :: Boolean | value } Unit

Sequential SeqFormBuilder used for asynchronously initializing some piece of form data, invalidating the form and preventing the rendering of subsequent fields while the supplied Aff is not completed.

For example:

myForm = parallel do
  initializer mempty \props value -> do
    foo <- fetchDefaultFoo
    pure $ value
      { foo = foo
      , bar = props.bar
      }

  sequential ado
    foo <- focus (SProxy :: SProxy "foo") textbox
    bar <- focus (SProxy :: SProxy "bar") switch
    in { foo, bar }

via :: forall result a s props ui. Iso' s a -> FormBuilder' ui props a result -> FormBuilder' ui props s result

Modify a FormBuilder using a (partial) Iso.

Technically, we don't require to (from s) = s, but we do require from (to a) = a for the form to act sensibly. Since there's no PartialIso in profunctor-lenses, we use Iso here.

Caveat emptor, you get what you pay for if you pass in a dodgy Iso here.

focus :: forall result a s props ui. Lens' s a -> FormBuilder' ui props a result -> FormBuilder' ui props s result

Focus a FormBuilder on a smaller piece of state, using a Lens.

match :: forall a t s result props ui. Monoid ui => Prism s s a a -> Prism s t a result -> FormBuilder' ui props a result -> FormBuilder' ui props s t

Focus a FormBuilder on a possible type of state, using a Prism.

We need two Prisms in order to change the result type for validation purposes.

match_ :: forall a s props ui. Monoid ui => Prism' s a -> FormBuilder' ui props a a -> FormBuilder' ui props s s

Focus a FormBuilder on a possible type of state, using a Prism, ignoring validation.

withProps :: forall result unvalidated props ui. (props -> FormBuilder' ui props unvalidated result) -> FormBuilder' ui props unvalidated result

Make the props available. This allows for changing the structure of a form builder based on the current props.

withValue :: forall result unvalidated props ui. (unvalidated -> FormBuilder' ui props unvalidated result) -> FormBuilder' ui props unvalidated result

Make the value available. This allows for changing the structure of a form builder based on the current value.

mapProps :: forall a u q p ui. (q -> p) -> FormBuilder' ui p u a -> FormBuilder' ui q u a

Change the props type.

mapUI :: forall result value props ui' ui. (props -> value -> Maybe result -> ui -> ui') -> FormBuilder' ui props value result -> FormBuilder' ui' props value result

Change the UI type of a form based on the props, the current value and the validated result.

mapUI_ :: forall result value props ui' ui. (ui -> ui') -> FormBuilder' ui props value result -> FormBuilder' ui' props value result

Change the UI type of a form.

indent :: forall a u props. String -> RequiredField -> FormBuilder props u a -> FormBuilder props u a

Indent a Forest of editors by one level, providing a label.

wrap :: forall a u props. (Array JSX -> JSX) -> FormBuilder props u a -> FormBuilder props u a

filterWithProps :: forall a u props ui. Monoid ui => (props -> u -> Boolean) -> FormBuilder' ui props u a -> FormBuilder' ui props u a

Filter parts of the form based on the current value (and the props).

withKey :: forall a u props. String -> FormBuilder props u a -> FormBuilder props u a

TODO: document

styles :: JSS

formDefaults :: forall a. FormDefaults a => a

newtype SeqFormBuilder' ui props unvalidated result

A form builder where each field depends on the validity of the previous ones. That is, every field is only displayed if all the previous ones are valid. Forms can be turned into components using the build function.

Instances

• (Warn (Above (Text "The `Parallel` instance to `FormBuilder` is deprecated.") (Text "Prefer using `Form.parallel` and `Form.sequential` instead."))) => Parallel (FormBuilder' (Array Tree) props unvalidated) (SeqFormBuilder' (Array Tree) props unvalidated)
• Newtype (SeqFormBuilder' ui props unvalidated result) _
• Functor (SeqFormBuilder' ui props unvalidated)
• (Monoid ui) => Apply (SeqFormBuilder' ui props unvalidated)
• (Monoid ui) => Applicative (SeqFormBuilder' ui props unvalidated)
• (Monoid ui) => Bind (SeqFormBuilder' ui props unvalidated)
• (Monoid ui) => Monad (SeqFormBuilder' ui props unvalidated)
• (Monoid ui) => Alt (SeqFormBuilder' ui props unvalidated)
• (Monoid ui) => Plus (SeqFormBuilder' ui props unvalidated)
• (Monoid ui) => Alternative (SeqFormBuilder' ui props unvalidated)
• (Monoid ui) => MonadZero (SeqFormBuilder' ui props unvalidated)

type SeqFormBuilder props unvalidated result = SeqFormBuilder' Forest props unvalidated result

newtype FormBuilder' ui props unvalidated result

An applicative functor which can be used to build forms. Forms can be turned into components using the build function.

Instances

• Newtype (FormBuilder' ui props unvalidated result) _
• Functor (FormBuilder' ui props unvalidated)
• (Semigroup ui) => Apply (FormBuilder' ui props unvalidated)
• (Monoid ui) => Applicative (FormBuilder' ui props unvalidated)
• (Warn (Above (Text "The `Parallel` instance to `FormBuilder` is deprecated.") (Text "Prefer using `Form.parallel` and `Form.sequential` instead."))) => Parallel (FormBuilder' (Array Tree) props unvalidated) (SeqFormBuilder' (Array Tree) props unvalidated)

type FormBuilder props unvalidated result = FormBuilder' Forest props unvalidated result

type Forest = Array Tree

sequential :: forall value props. String -> (FormBuilder props value) ~> (SeqFormBuilder props value)

revalidate :: forall result unvalidated props ui. FormBuilder' ui props unvalidated result -> props -> unvalidated -> Maybe result

Revalidate the form, in order to display error messages or create a validated result.

parallel :: forall value props. String -> (SeqFormBuilder props value) ~> (FormBuilder props value)

listen :: forall result unvalidated props ui. (unvalidated -> Aff (unvalidated -> unvalidated)) -> FormBuilder' ui props unvalidated result -> FormBuilder' ui props unvalidated result

Listens for changes in a form's value and allows for performing asynchronous effects and additional value changes.

invalidate :: forall b a unvalidated props ui. FormBuilder' ui props unvalidated a -> FormBuilder' ui props unvalidated b

Invalidate a form, keeping its user interface but discarding the result and possibly changing its type.

formBuilder_ :: forall a props. (props -> a -> (a -> Effect Unit) -> JSX) -> FormBuilder props a a

The simplest way to create a FormBuilder. Create a FormBuilder provided a function that, given the current value and a change callback, renders a form element as JSX.

formBuilder :: forall a unvalidated props. (props -> unvalidated -> { edit :: ((unvalidated -> unvalidated) -> Effect Unit) -> JSX, validate :: Maybe a }) -> FormBuilder props unvalidated a

Create a FormBuilder from a function which produces a form element as JSX and a validated result.

type Validator result valid = result -> Either String valid

A Validator takes a possibly invalid form result and produces a valid result, or an error message.

data Validated a

The Validated type describes the state of a validated form field. This state may be used to modify the way this form field or its validation messages are displayed.

TODO: maybe convert this type to a record? Possible extensions to this type (as a record) could be a field valid :: Boolean to display an indicator that the field is valid, or a field validating :: Maybe (Canceler a) to control form fields with asynchronous validation.

Constructors

• Fresh a
• Modified a

Instances

• (Eq a) => Eq (Validated a)
• Eq1 Validated
• (Ord a) => Ord (Validated a)
• Ord1 Validated
• Functor Validated
• Apply Validated
• Applicative Validated
• (Mapping ModifyValidated a a) => Mapping ModifyValidated (Validated a) (Validated a)
• CanValidate (Validated a) a

fromValidated :: forall u v. CanValidate u v => Validated v -> u

warn :: forall result validated unvalidated props. CanValidate unvalidated validated => WarningValidator result -> FormBuilder { readonly :: Boolean | props } unvalidated result -> FormBuilder { readonly :: Boolean | props } (Validated validated) result

Attach a validation function to a FormBuilder p u a, producing a new FormBuilder that takes a Validated u as form state and displays a warning message if its form data triggers a warning, while still allowing the form to proceed.

validated :: forall result_ result validated unvalidated props. CanValidate unvalidated validated => Validator result_ result -> FormBuilder { readonly :: Boolean | props } unvalidated result_ -> FormBuilder { readonly :: Boolean | props } (Validated validated) result

Attach a validation function to a FormBuilder p u a, producing a new FormBuilder that takes a Validated u as form state and displays an error message if its form data is invalid.

This Validated data type describes a form field as either Fresh or Modified, so that validation messages are only displayed if the field is Modified.

validNumber :: String -> Validator String Number

A Validator which verifies that its input can be parsed as a number.

validInt :: String -> Validator String Int

A Validator which verifies that its input can be parsed as an integer.

validDate :: String -> Validator String Date

A Validator which verifies that its input can be parsed as a date. Dates are of the format "YYYY-MM-DD".

setModified :: forall value. Mapping ModifyValidated value value => value -> value

Sets all Validated fields in a record to Modified, showing all validation messages.

setFresh :: forall value. Mapping ModifyValidated value value => value -> value

Sets all Validated fields in a record to Fresh, hiding all validation messages.

optional :: forall a. Validator String a -> Validator String (Maybe a)

Modify a Validator to accept empty strings in addition to anything it already accepts. The empty string is mapped to Nothing, and any other valid input is mapped to Just the result of the original validator.

nonNull :: forall a. String -> Validator (Maybe a) a

A Validator which verifies that an optional field is specified.

nonEmptyArray :: forall a. String -> Validator (Array a) (NonEmptyArray a)

A Validator which verifies that an input array is non-empty.

nonEmpty :: String -> Validator String NonEmptyString

A Validator which verifies that an input string is non-empty.

mustEqual :: forall a. Eq a => a -> String -> Validator a a

A Validator which verifies that its input equals some value.

mustBe :: forall a. (a -> Boolean) -> String -> Validator a a

A Validator which verifies that its input fulfills a specified condition.

_Validated :: forall b a. Lens (Validated a) (Validated b) a b

Lens for viewing and modifying Validated values.