misakey-ui v0.0.11

Introduction

This is the misakey-ui package repository.

It contains some component for frontend development at Misakey.

The present components are:

• UI component that we reuse in many frontend products
• Form elements with business logic that should be present in every project (for example form validation)

Table of content

• Introduction
• Folder Architecture
• Usage
• Develop
• Deploy
• Documentation
• Todo

Folder Architecture

Main folders:

• src: source code of the project.

Concerning the source code:

Here is the list of folders and a description:

• components: All the components. One folder (or sub-folder) contains a component (index.js file)
• utils: logic utils (like hashing method) used inside some components, and some tooling for the documentation

Usage

Installation

You can install the UI Kit as any npm package: yarn add misakey-ui

Component usage

From your ReactJS project file, you can import any component from the kit. For example: import { ColorizedAvatar } from 'misakey-ui

Form validation

The fom component in this UIKit are created to be used with Formik as form manager and Yup as form validation. So you'll need to install them in your project: yarn add formik yup

All the error managment (translating error code to error message, internationalization) is done in the component.

Example

import * as Yup from 'yup';
import { Formik, Form } from 'formik';
import {
  EmailInput, emailValidation, EMAIL_ERROR_TYPES,
  PasswordInput, passwordValidation, PASSWORD_ERROR_TYPES,
} from 'misakey-ui';

<Formik
  initialValues={{ email: 'initial@email.com', password: 'superstronginitialpassword' }}

  onSubmit={(values, { setSubmitting, setErrors }) => {
    // Do whatever you need to when submited.
    // You'll enter here when the form is valid

    customApiCall(values.email, values.password).then((response) => {
      setSubmitting(false);
      if (response.emailError) {
        setErrors({ email: EMAIL_ERROR_TYPES.emailError });
      } else {
        // Do what you need 
      }
    });
  }}
  validationSchema={Yup.object().shape({
    email: emailValidation,
    password: passwordValidation,
  })}
>
  {(props) => {
    const { isSubmitting } = props;
    return (
      <Form>
        <EmailInput
          {...props}
          language="fr" // You can pass it with the i18n object
        />
        <PasswordInput
          {...props}
          language="fr"
        />

        <button
          type="submit"
          disabled={isSubmitting}
        />
      </Form>
    );
  }}
</Formik>

Documentation

The documentation is generated by react-styleguidist. To run a local / live version of the documentation, run npx styleguidist server. To build a static version of the documentation, run npx styleguidist build. The build will be exported into a styleguide folder.

Develop

To create or enhance a component from the UI Kit, you can use react-styleguidist. You can run npx styleguidist server, and then go into your browser to see the component live in the documentation. Styleguidist has all features needed for developping (react embeded, live reload, con integrate Formik & Yup for forms elements).

Documentation

The generated documentation is based on two principles:

• JSDoc inside the component file (you should add a global description as comment of Component; you can describe the props by commenting the propTypes; you can document the methods by commenting them)
• A demonstration file, called index.md (aside the index.js file of the component). This is a Markdown file to show a usage of the component. It's written in Markdown, and supports JSX in code blocks.

Form elements

All form elements are build to work with Formik & Yup. Formik is a library to manage forms (validation, submitting, error managment, ...) Yup is a validation library

Using these tools add a lot of power in what we're doing, but add some constraints:

• We need to define the corresponding validation rules of a component in a validate.js file (aside the index.js file of the component)
• As we want to be as light as possible when integreting in a project, we need to make our elements able to receive all Formik props (that's why for a signle component we give the whole values, errors, touched, ... object).
  • Maybe a solution to that would be a value extractor function, but not sure it'll be a lot more performant)

If you need more informations about the Formik props that components are using (values, touched, errors, isSubmitting, handleChange, handleBlur), you can find it in the Formik documentation.

Deploy

Deploying the package

To deploy the package on npm, you need to:

• Change the package version with npm version
• Publish the package npm publish

Deploying the documentation

WIP documentation not hosted yet

Todo

• Improve package generation (to be able to import like import EmailInput from 'misakey-ui/EmailInput (material-ui style))
• Improve dependency managment (using peerdependencies ?)
• Auto add validation documentation in stylguide from the validate.js file