lion/packages/field/docs/modelValue.md

ModelValue

The modelValue or model can be considered as the ‘aorta’ of our form system. It is the single source of truth; not only for the current state of the form, also for all derived states: interaction, validation, visibility and other states are computed from a modelValue change.

Single source of truth

ModelValues are designed to provide the Application Developer a single way of programmatical interaction with the form for an Application Developer.

One single concept for Application Developers

Application Developers need to only care about interacting with the modelValue on a form control level, via:

• .modelValue
• @model-value-changed

Internal/private concepts like viewValue, formattedValue, serializedValue are therefore not recommended as a means of interaction.

One single concept for internals

Internally, all derived states are computed from model-value-changed events. Since the modelValue is computed 'realtime' and reflects all user interaction, visibility and validation states, we can guarantee a system that enables the best User Experience (see Interaction States).

Unparseable modelValues

A modelValue can demand a certain type (Date, Number, Iban etc.). A correct type will always be translatable into a String representation (the value presented to the end user) via the formatter. When the type is not valid (usually as a consequence of a user typing in an invalid or incomplete viewValue), the current truth is captured in the Unparseable type. For example: a viewValue can't be parsed (for instance 'foo' when the type should be Number).

The model(value) concept as implemented in lion-web is conceptually comparable to those found in popular frameworks like Angular and Vue.

The Unparseable type is an addition on top of this that mainly is added for the following two purposes:

• restoring user sessions
• realtime updated with all value changes

Restoring user sessions

As a modelValue is always a single source of truth

Realtime updated with all value changes

As an Application Developer, you will be notified when a user tries to write the correct type of a value. This might be handy for giving feedback to the user.

In order to check whether the input is correct, an Application Developer can do the following:

<lion-input @model-value-changed="${handleChange}"></lion-input>

function handleChange({ target: { modelValue, hasFeedbackFor } }) {
  if (!(modelValue instanceof Unparseable) && !(hasFeedbackFor.include('error))) {
    // do my thing
  }
}