Field decorators

[kant01ne]

Field decorators

We want to allow to extend the default EmailPassword theme to add custom behaviour such as :

• Password strength meters
  • weak | good | excellent indicators
  • password time to crack
  • Password is in top 100/1k most used password
• Email suggestions: "We noticed that you are using a Gmail account, do you have a work email?"

We want to do this without having to:

• Implement a new theme that behaves exactly the same as the default except for that one small behaviour.
• Ask customers to disable default implementation to overwrite the default theme.

Solution

The idea is to add an optional property called decorators to formFields. This decorator consists of a React element that will be inserted below the input field and that will take its value as props.

Example:

SuperTokens.init({
  appInfo: {},
  recipeList: [
    EmailPassword.init({
      signInAndUpFeature: {
        onSuccessRedirectURL: '/dashboard',
        signUpForm: {
          formFields: [{
              id: "password",
              decorator: <PasswordStrengthMeterDecorator />
            }]
         }
       }
    })
   ] 
});

With PasswordStrengthMeterDecorator a React element that takes a value as props (the pasword which is updated on each changes), and displays a UI below the input.
We can provide few decorators as examples but the idea is that the developers can implement their own to extend the default theme easily if they like.

Implementation

Implementation is straightforward, we simply need to:

• Add decorator?: JSX.Element to FormFieldBaseConfig type.
• Prevent propagating SignUp decorators to SignIn
• Add onChange in input.tsx` to make sure that the state is updated each time the value is updated (as opposed to using React refs).
• Insert the decorator element, give it input value as props.

[rishabhpoddar]

This is a good idea. However, I think we should postpone this to post the MVP launch.

• If someone adds a decorator, will the formField error message still show in case of errors? If yes, how will the decorator be placed / behave in that case?
• Shouldn't the ability to add decorater go as a prop to the theme. I feel it's better there since having it in init forces all themes to take care of this, which may not be appropriate.

The above being said, I think the problem of wanting to change something very slightly resulting in having to build the whole theme yourself is deeper issue that may require a different solution.

Happy to discuss this after the MVP release.

[kant01ne]

If someone adds a decorator, will the formField error message still show in case of errors? If yes, how will the decorator be placed / behave in that case?

Decorators are interactive. They update every time their respective value changes. They are inserted before the error field.

Shouldn't the ability to add decorator go as a prop to the theme. I feel it's better there since having it in init forces all themes to take care of this, which may not be appropriate.

That's a fair point! That means using decorators implies that you have to disable the default implementation. That was the reason why we moved everything to the init in the first place.
Also, a theme who receives a decorator can simply ignore it.

The above being said, I think the problem of wanting to change something very slightly resulting in having to build the whole theme yourself is deeper issue that may require a different solution.

That's why we need to identify that strategic UI places where users might want to add custom UI to make sure that we provide enough flexibility so that they don't have to write the whole thing themselves.

[rishabhpoddar]

That's a fair point! That means using decorators implies that you have to disable the default implementation. That was the reason why we moved everything to the init in the first place.

If you are adding decorators, I don't think you would mind not using the default implementation. It doesn't add too much work.

That's why we need to identify that strategic UI places where users might want to add custom UI to make sure that we provide enough flexibility so that they don't have to write the whole thing themselves.

Agreed. Strategic places would change based on themes. This is another reason to not add this in the init and make it a theme specific "feature".

There are two ways to find out the strategic places:

• Analyse many sign up / in pages
• Get more user feedback / requests

[kant01ne]

Field decorators would allow to do things such as the above ^

In that case it even replaces the default behaviour of validators (at least we'd need tot have a way not to show the UI for validators in that case).

[rishabhpoddar]

Let's discuss this over a call.

[rishabhpoddar]

A better idea could be that the provided component is a wrapper to the actual text input and its label. This way, we can control not only what's below the text input, but above / next to etc.. as well..

[amitbadala]

TODOs

• Add props to enable initializing default value from formFields
• Investigate form fields for sign in
• Validation not working as expected for checkbox
• Make getDefaultValue work for all form fields, and not just the sign up one.
• This needs to work for thirdpartyemailpassword recipe as well.
• Fix the field not optional issue for checkbox component to show another type of message when sign up is called.

Tests for CustomFields

• Should contain CustomComponenets as defined in SuperTokens.init call
• Should show error messages for client side validation, check optional flag, error messages are displayed correctly
• Check if custom values are part of the signup payload
• Implement different types of fields, checkbox, dropdown.

Docs changes:

• How to make custom components for sign up form (example of selection and checkbox)
  • need to mention that it must be a string that is given to onChange
• Handling errors for custom components
  • validation errors
  • optional vs non optional
• Default values for components