@super-formal/user-forms NPM

@super-formal/user-forms

Common user forms (log in, sign up, etc.) as react components to get your app going quick and well.

Index

The SignupForm Component

The ForgotPasswordForm Component

The ResetPasswordForm Component

Installation

Using npm:

npm i -g npm
npm i --save @super-formal/user-forms

Using yarn:

yarn add @super-formal/user-forms

Basic Usage

After installing the package you can use it in your React project as follows:

import {
  LoginForm,
  SignupForm,
  ForgotPasswordForm,
  ResetPasswordForm,
} from '@super-formal/user-forms';

const DEFAULT_BUILDERS = {
  'form': Form, // You have to define this component
  'text': TextField, // You have to define this component
  'button': Button, // You have to define this component
};

// inside your render() function
<div>
  <LoginForm
    builders={DEFAULT_BUILDERS}
    onSubmitClick={(username, password) => {
      // try to log the user in
    }}
  />

  <SignupForm
    builders={DEFAULT_BUILDERS}
    onSubmitClick={(username, email, password) => {
      // try to sign the user up
    }}
  />


  <ForgotPasswordForm
    builders={DEFAULT_BUILDERS}
    onSubmitClick={(username, email) => {
      // start the reset password procedure for this user
    }}
  />

  <ResetPasswordForm
    builders={DEFAULT_BUILDERS}
    onSubmitClick={(username, token, password) => {
      // reset the user's password
    }}
  />
</div>

Motivation

User forms are one of the first hurdles you encounter when trying to build an app. These components intend to make it easy to quickly set up the user forms and get going with the rest of the app.

The `LoginForm` Component

The LoginForm is a Form with the following structure:

[
  {type: "text", id: "userID"},
  {type: "text", id: "password"},
  {type: "button", id: "submit"}
]

It also has the implicit structural component {type: "form", id: "form"}.

`builders` prop

{Object<type: String, id: String>} - required - The builders (React components) to use when building each of the structural components of the form. You should at least provide the following builders:

{
  text: *your Text component*,
  button: *your Button component*
}

See the Form.builders prop's docs for more information.

`adapters` prop

{Object<String, Function>} - optional - The adapters that modify the state provided by the form to each of your components. By default an identity function is used as an adapter for each field in the form. This means the state and reactions are passed from the Form to the components as props without modifications. Here's a template you can use for the login form adapters:

adapters={{
  form: ({
    errorMessages: Array<String> - A list of error messages to display at the top of the form.
  }) => ({
    thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
    ...
  }),

  userID: ({
    hint: String - The label for the user field.
    value: String - The value typed into the user field.
    hasError: Boolean - `true` if this field has an error.
    errorMessage: String - The error message associated with this field.
    onChange: Function - The callback to be called when the value of the field changes.
  }) => ({
    thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
    ...
  }),

  password: ({
    hint: String - The label for the password field.
    value: String - The value typed into the password field.
    hasError: Boolean - `true` if this field has an error.
    errorMessage: String - The error message associated with this field.
    password: Boolean - `true`.
    onChange: Function - The callback to be called when the value of the field changes.
  }) => ({
    thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
    ...
  }),

  submit: ({
    label: String - The label to show in the button
    onClick: Function - The callback to be called when the submit button is clicked.
  }) => ({
    thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
    ...
  })
}}

See the Form.adapters prop's docs for more information.

`state` prop

{Object<String, Object<String, Any>>} - optional - Any additional state values to be passed as props to the fields in the form. Do not pass callbacks to the fields through the state prop. Use the reactions prop for that instead.

See the Form.state prop's docs for more information.

`reactions` prop

{Object<String, Object<String, Function | Array<Function> | ChainReaction>>} - optional - Any additional callback values to be passed as props to the fields in the form. Do not pass state props to the fields through the reactions prop. Use the state prop for that instead.

See the Form.reactions prop's docs for more information.

`onSubmitClick` prop

{Function} - optional - A callback to call when the submit button is clicked. It has the following signature:

(username, password) => {
  // log the user in
}

`userIDLabel` prop

{String} - optional - The label (hint) to show for the userID field. Defaults to "Email".

`submitLabel` prop

{String} - optional - The label to show on the submit button. Defaults to "Log In".

`showErrorMesssagesAtTop` prop

{Boolean} - optional - Defualts to false. true if you want to show all errors at the top of the form. Otherwise, each error will be displayed under its respective field.

`showMismatchingUserAndPasswordError` prop

{Boolean} - optional - Defualts to false. true if you want to show an error message indicating that the submitted userID and password values failed to log in. Set this to true after you send a log in request and your server fails to log in the user.

`dontValidateFieldsBeforeSending` prop

The `SignupForm` Component

The SignupForm is a Form with the following structure:

[
  {type: "text", id: "username"},
  {type: "text", id: "email"},
  {type: "text", id: "password"},
  {type: "text", id: "confirmPassword"},
  {type: "button", id: "submit"}
]

It also has the implicit structural component {type: "form", id: "form"}.

`builders` prop

{
  text: *your Text component*,
  button: *your Button component*
}

See the Form.builders prop's docs for more information.

`adapters` prop

adapters={{
  form: ({
    errorMessages: Array<String> - A list of error messages to display at the top of the form.
  }) => ({
    thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
    ...
  }),

  username: ({
    hint: String - The label for the username field.
    value: String - The value typed into the username field.
    hasError: Boolean - `true` if this field has an error.
    errorMessage: String - The error message associated with this field.
    onChange: Function - The callback to be called when the value of the field changes.
  }) => ({
    thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
    ...
  }),

  email: ({
    hint: String - The label for the user field.
    value: String - The value typed into the user field.
    hasError: Boolean - `true` if this field has an error.
    errorMessage: String - The error message associated with this field.
    onChange: Function - The callback to be called when the value of the field changes.
  }) => ({
    thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
    ...
  }),

  password: ({
    hint: String - The label for the password field.
    value: String - The value typed into the password field.
    hasError: Boolean - `true` if this field has an error.
    errorMessage: String - The error message associated with this field.
    password: Boolean - `true`.
    onChange: Function - The callback to be called when the value of the field changes.
  }) => ({
    thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
    ...
  }),

  confirmPassword: ({
    hint: String - The label for the confirm password field.
    value: String - The value typed into the confirm password field.
    hasError: Boolean - `true` if this field has an error.
    errorMessage: String - The error message associated with this field.
    password: Boolean - `true`.
    onChange: Function - The callback to be called when the value of the field changes.
  }) => ({
    thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
    ...
  }),

  submit: ({
    label: String - The label to show in the button
    onClick: Function - The callback to be called when the submit button is clicked.
  }) => ({
    thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
    ...
  })
}}

See the Form.adapters prop's docs for more information.

`state` prop

See the Form.state prop's docs for more information.

`reactions` prop

See the Form.reactions prop's docs for more information.

`onSubmitClick` prop

{Function} - optional - A callback to call when the submit button is clicked. It has the following signature:

(username, email, password) => {
  // sign the user up
}

Note that the username parameter will be removed from the signature if the hideUserIDField is set to true, and the email parameter will removed from the signature if the hideEmailField is set to true.

`userIDLabel` prop

{String} - optional - The label (hint) to show for the userID field. Defaults to "Username".

`submitLabel` prop

{String} - optional - The label to show on the submit button. Defaults to "Sign Up".

`showErrorMesssagesAtTop` prop

{Boolean} - optional - Defualts to false. true if you want to show all errors at the top of the form. Otherwise, each error will be displayed under its respective field.

`hideUserIDField` prop

{Boolean} - optional - Defaults to false. If true this removes the userID field from the structure of this Form. Use this if the user accounts in your app/service only require an email and a password for users to join.

`hideEmailField` prop

{Boolean} - optional - Defaults to false. If true this removes the email field from the structure of this Form. Use this if the user accounts in your app/service only require a username and a password for users to join.

`dontValidateFieldsBeforeSending` prop

{Boolean} - optional - Defualts to false. true if you don't want the form to validate the inputs before sending. They are validated by default. The validation simply verifies that the userID, email, password, and confirmPassword fields are not empty. It also verifies that the email value has a valid email format. It also verifies that the password and confirmPassword values are the same.

`validateUserIDAfterXSecondsOfTyping` prop

{Number} - optional - Defaults to undefined. Set to a positive integer to indicate how many seconds after the user changes the value for the username field (or the email field if hideUserIDField is set to true). If the user changes the value again before the specified number of seconds had passed then the validation will be delayed further. After the specified time passes without interruption then the callback in the onValidateUserID prop is called.

`onValidateUserID` prop

{Function} - optional - Defaults to undefined - Set to a callback function with the signature (userIDValue as String) => {// verify that user ID is valid / available}. This callback is called once the the username value changes (or the email value if hideUserIDField is set to true), see the description for the validateUserIDAfterXSecondsOfTyping prop. You are supposed to verify whether the userID is valid and available, and raise the showUserIdAlreadyInUseError flag otherwise.

`showUserIdAlreadyInUseError` prop

{Boolean} - optional - Defaults to false. If true then an error message will be passed to the form saying tha that the entered userID is not available.

The `ForgotPasswordForm` Component

The ForgotPasswordForm is a Form with the following structure:

[
  {type: "text", id: "username"},
  {type: "text", id: "email"},
  {type: "button", id: "submit"}
]

It also has the implicit structural component {type: "form", id: "form"}.

`builders` prop

{
  text: *your Text component*,
  button: *your Button component*
}

See the Form.builders prop's docs for more information.

`adapters` prop

adapters={{
  form: ({
    errorMessages: Array<String> - A list of error messages to display at the top of the form.
    successMessages: Array<String> - A list of success messages to display at the top of the form.
  }) => ({
    thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
    ...
  }),

  username: ({
    hint: String - The label for the username field.
    value: String - The value typed into the username field.
    hasError: Boolean - `true` if this field has an error.
    errorMessage: String - The error message associated with this field.
    onChange: Function - The callback to be called when the value of the field changes.
  }) => ({
    thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
    ...
  }),

  email: ({
    hint: String - The label for the email field.
    value: String - The value typed into the email field.
    hasError: Boolean - `true` if this field has an error.
    errorMessage: String - The error message associated with this field.
    onChange: Function - The callback to be called when the value of the field changes.
  }) => ({
    thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
    ...
  }),

  submit: ({
    label: String - The label to show in the button
    onClick: Function - The callback to be called when the submit button is clicked.
  }) => ({
    thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
    ...
  })
}}

See the Form.adapters prop's docs for more information.

`state` prop

See the Form.state prop's docs for more information.

`reactions` prop

See the Form.reactions prop's docs for more information.

`onSubmitClick` prop

{Function} - optional - A callback to call when the submit button is clicked. It has the following signature:

(username, email) => {// start the reset password procedure for this user}

Note that the username parameter will be removed from the signature if the hideUserIDField is set to true, and the email parameter will be removed from the signature if the hideEmailField is set to true.

`userIDLabel` prop

{String} - optional - The label (hint) to show for the username field. Defaults to "Username".

`submitLabel` prop

{String} - optional - The label to show on the submit button. Defaults to "Request Token".

`showErrorMesssagesAtTop` prop

{Boolean} - optional - Defualts to false. true if you want to show all errors at the top of the form. Otherwise, each error will be displayed under its respective field.

`dontValidateFieldsBeforeSending` prop

`showResetTokenHasBeenSentSuccess` prop

{Boolean} - optional - Defaults to false. true if you want to show a message at the top of the form informing the user that the reset token has been successfully sent to their email account.

`resetTokenHasBeenSentMessage` prop

{String} - optional - Defaults to "A reset token has been sent to your email account". You can set this value to a different message to show to the user. This mesasge is displayed at the top of the form when the showResetTokenHasBeenSentSuccess prop is set to true.

`hideUserIDField` prop

{Boolean} - optional - Defaults to false. If true then the userID field is removed from the structure of this Form. Use this if the user accounts in your app/service only require an email and a password for users to join.

`hideEmailField` prop

{Boolean} - optional - Defaults to false. If true then the email field is removed from the structure of this Form.

The `ResetPasswordForm` Component

The ResetPasswordForm is a Form with the following structure:

[
  {type: "text", id: "userID"},
  {type: "text", id: "token"},
  {type: "text", id: "password"},
  {type: "text", id: "confirmPassword"},
  {type: "button", id: "submit"},
]

It also has the implicit structural component {type: "form", id: "form"}.

`builders` prop

{
  text: *your Text component*,
  button: *your Button component*
}

See the Form.builders prop's docs for more information.

`adapters` prop

adapters={{
  form: ({
    errorMessages: Array<String> - A list of error messages to display at the top of the form.
  }) => ({
    thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
    ...
  }),

  userID: ({
    hint: String - The label for the userID field.
    value: String - The value typed into the userID field.
    hasError: Boolean - `true` if this field has an error.
    errorMessage: String - The error message associated with this field.
    onChange: Function - The callback to be called when the value of the field changes.
  }) => ({
    thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
    ...
  }),

  token: ({
    hint: String - The label for the token field.
    value: String - The value typed into the token field.
    hasError: Boolean - `true` if this field has an error.
    errorMessage: String - The error message associated with this field.
    onChange: Function - The callback to be called when the value of the field changes.
  }) => ({
    thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
    ...
  }),

  password: ({
    hint: String - The label for the password field.
    value: String - The value typed into the password field.
    hasError: Boolean - `true` if this field has an error.
    errorMessage: String - The error message associated with this field.
    password: Boolean - `true`.
    onChange: Function - The callback to be called when the value of the field changes.
  }) => ({
    thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
    ...
  }),

  confirmPassword: ({
    hint: String - The label for the confirm password field.
    value: String - The value typed into the confirm password field.
    hasError: Boolean - `true` if this field has an error.
    errorMessage: String - The error message associated with this field.
    password: Boolean - `true`.
    onChange: Function - The callback to be called when the value of the field changes.
  }) => ({
    thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
    ...
  }),

  submit: ({
    label: String - The label to show in the button
    onClick: Function - The callback to be called when the submit button is clicked.
  }) => ({
    thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
    ...
  })
}}

See the Form.adapters prop's docs for more information.

`state` prop

See the Form.state prop's docs for more information.

`reactions` prop

See the Form.reactions prop's docs for more information.

`onSubmitClick` prop

{Function} - optional - A callback to call when the submit button is clicked. It has the following signature:

(username, token, password) => {
  // reset the user's password
}

`userIDLabel` prop

{String} - optional - The label (hint) to show for the userID field. Defaults to "Username".

`submitLabel` prop

{String} - optional - The label to show on the submit button. Defaults to "Reset Password".

`showErrorMesssagesAtTop` prop

{Boolean} - optional - Defualts to false. true if you want to show all errors at the top of the form. Otherwise, each error will be displayed under its respective field.

`dontValidateFieldsBeforeSending` prop

{Boolean} - optional - Defualts to false. true if you don't want the form to validate the inputs before sending. They are validated by default. The validation verifies that the userID, token, password, and confirmPassword fields are not empty. Then it verifies that the values for the password and confirmPassword fields match.

`showPasswordHasBeenChangedSuccess` prop

{Boolean} - optional - Defaults to false. true if you want to show a message at the top of the form informing the user that the password to their account as been successfully reset.

`passwordHasBeenChangedMessage` prop

{String} - optional - Defaults to "Your password has been successfully updated.". You can set this value to a different message to show to the user. This mesasge is displayed at the top of the form when the showPasswordHasBeenChangedSuccess prop is set to true.

`showInvalidUsernameOrTokenError` prop

{Boolean} - optional - Defaults to false. true if you want to show an error message at the top of the form informing the user that the provided username or the token values are invalid. You should set this to true if the backend fails to validate the reset token for the user.

`invalidUsernameOrTokenMessage` prop

{String} - optional - Defaults to "The provided username and token are invalid. Password has not been reset.". You can set this value to a different message to show to the user. This mesasge is displayed at the top of the form when the showInvalidUsernameOrTokenError prop is set to true.

super-formal user form react component

@super-formal/chain-reaction @super-formal/form

@everything-registry/sub-chunk-882

0.1.0

4 years ago