React MVVM@2.2.0

[Andrei15193]

Hi,

I'm working on the next set of updates for this library and most will be around consolidating the hooks. Currently I am not following the naming guidelines and some of the hooks do not start with use but rather watch. This will be fixed in the next minor release along side a deprecation notice. The existing hooks will be using the correctly named ones.

On this note, I will be adding a unified useViewModel hook that will be handling all existing scenarios with an overload for each.

• Watching a view model for changes

• Creating a view model from a provided type, in addition to useViewModelType we will be able to pass constructor arguments as well, they will act as deps. Whenever the constructor arguments change we get a new instance of our view model.

  This is useful for ensuring clean initial states when reusing components, one of the constructor arguments can be the ID of an entity, thus when the ID changes a fresh view model will be created ensuring the same initial state.

• Creating a view model using a callback, in addition to useViewModelFactory we will be able to pass deps as well. This will accommodate all scenarios as sometimes we may not want the change in a constructor argument to result in a new instance.

Form changes

isFocused deprecation

The isFocused property will be deprecated. After long deliberation, I have come to the conclusion that this is a pure presentation concern and has very little to do with the view model or what the view model should handle.

View models exist outside of UI components and have no clue how their data is being presented to the user or even if some of these properties or composites are even being currently displayed.

For instance, think about a wizard form where you have multiple tabs or views where you configure sections of a form. Not all fields are interactable at the moment yet all of them are present in the view model form definition. What should setting isFocused to true do in this case? Switch the current tab in the wizard as a result? How and why does the view model even know about this?

The form may have invalid fields because they may be required, but if they are not visible in the current tab maybe they do not need to be displayed. Once again, this is a presentation issue, not a logic issue. Clearly we do not want to allow the form to be submitted if it has validation errors, this is a UI logic concern, not a UI presentation concern.

How the focus state of UI components change is a presentation concern, maintaining this state in the view model does not make general sense. There may be cases where this is necessary, I cannot think of one at the moment nor recall if I encountered this, however this will be covered in form extensibility.

isTouched deprecation

While this can be very useful for a number of reasons, it should not be made available with the base library. Form extensibility should cover this case and any application that wants this feature back will be able to easily add it back along side any other flags it needs.

Form extensibility

Currently, it is a bit difficult to extend FormFieldCollectionViewModel to have custom fields based on IFormFieldViewModel<>. I am working on making this a generic type which will allow a custom field type to be configured which defaults to FormFieldViewModel<> (the base class, not the interface). I'm not sure why I didn't do this from the start as it makes complete sense to be able to add flags and other properties for your own fields.

For instance, an isChanged feature can be useful to know if a form (re)submission is necessary or display a prompt when we want to leave the page and we have unsaved changed (to be fair, we can always display this prompt and not bother). Just to be clear, when I say prompt I do not mean the native browser prompt implicitly, it can be a custom modal that better fits the application theme, React Router has this option for its navigation.

As a sneak peak, I'm thinking of something like this.

abstract class FormFieldCollectionViewModel<TFormFieldViewModel extends IFormFieldViewModel<any> = FormFieldViewModel<any>> extends ViewModel implements IValidatable {
  // validatable properties

  protected registerField(field: TFormFieldViewModel): TFormFieldViewModel {
    // register logic
  }

  protected unregisterField(field: TFormFieldViewModel): void {
    // unregister logic
  }
}

Although still abstract, I'm thinking of adding a builder as well or a factory method since the base features might be enough for small applications or for when you want a quick proof of concept.

const form = FormFieldCollectionViewModel.create({
  myTextField: new FormFieldViewModel("myTextField", ""),
  myNumberField: new FormFieldViewModel("myNumberField", 0)
});

const myTextField = form.myTextField;
const { myNumberField } = form;

Ideally, with validator callbacks as well, I may add a config interface for that as it makes it easily extensible for custom fields and allows for an object initializer-like feature from C# (Object and Collection Initializers (C# Programming Guide)).

interface IFormFieldConfig<TValue> {
  readonly name: string;
  readonly initialValue: TValue;
  readonly validators?: readonly ValidatorCallback<FormFieldViewModel<TValue>>[];
  // can be extended with other props for custom fields while still using the base class
}

const form = FormFieldCollectionViewModel.create({
  myTextField: new FormFieldViewModel({
    name: "myTextField",
    initialValue: "",
    validators: [required]
  }),
  myNumberField: new FormFieldViewModel("myNumberField", 0) // Might deprecate this constructor, unsure
});

[Andrei15193]

After looking for improved way to check whether the passed value to useViewModel is a class or a function, I've reached the conclusion that this is not something that is doable in JavaScript due to its backward compatibility.

Unfortunately I won't be able to have the hook unification as I wanted to so it will only be done for instances and classes. Basically, if what you pass exposes a property "propertiesChanged" then it will be considered a view model instance; otherwise it is considered to be class or a function that can be called with the new operator.

Instead of the callback overload a new hook will be provided which is just a simplification for a sequence of calls, one of which is React's useMemo. Something like this:

function useViewModelMemo<TViewModel>(viewModelFactory: ViewModelFactory<TViewModel>, deps: React.DependencyList, watchedProperties?: readonly (keyof TViewModel)[]): TViewModel {
  const viewModel = useMemo(viewModelFactory, deps);
  useViewModel(viewModel, watchedProperties);
  return viewModel;
}

While it is easy for the above hook to be written by anyone using the library, it can be useful to have it available out of the box when the useViewModel hook does not solve the problem. I'm not sure there will be a case for using the callback approach, but you never know.

More info here: https://stackoverflow.com/questions/30758961/how-to-check-if-a-variable-is-an-es6-class-declaration

[Andrei15193]

A small update, while rc.3 is most likely going to be the next release, I'm working on a set of tutorials before pushing the release.

I want to replace the current ToDo List one and have them as GitHub discussions. I'm also thinking about having an announcement containing links to each as it can be difficult to know in which order to go through if you are getting started.

It may take a bit until the next release as this process usually takes some time, in the mean time, feel free to use 2.2.0-rc.3 as this is the latest and most likely the go-live version.

In addition, all tutorial code samples will be available on CodeSandbox so you can just run them and play around with the library, see if it is what you are looking for.

[Andrei15193]

Good news, I've published React MVVM 2.2.0 🥳

For any discussions about the release, go to #10