1.3.3 • Published 3 years ago

sam-web-component-library v1.3.3

Weekly downloads
-
License
ISC
Repository
-
Last release
3 years ago

ECRS Vue Components

Live Storybook Demo

Overview

The goal of this library is to streamline the theme and interactions of the components used across ECRS applications. These components wrap the components provided by bootstrap-vue to abstract the component library away from ECRS applications, while at the same time taking advantage of these pre-existing elements. Ideally, if we ever choose to switch to a different 3rd party component library or write our own, all the work can be done in this project, and others will simply need to update to the latest version.

Setup

1 Setup NPM

This project is configured with an npmrc file. This file makes use of an environment variable called GITLAB_PERSONAL_ACCESS_TOKEN. This token will authenticate you to interact with the GitLab npm registry for this project.

Follow these directions to generate a personal access token.

Now, make your token a Windows environment variable: 1. Copy your personal access token 2. Press Windows key and start typing "Edit the system environment variables" 3. Press enter when you see the above option appear 4. Click "Environment Variables" 5. Click "New..." under "User variables for user" 6. Input GITLAB_PERSONAL_ACCESS_TOKEN in the box for "Variable name". The token name is important. 7. Paste your personal access token in the box for "Variable value" 8. Click "OK"

You should be left with something that looks like this:

Personal access token as an environment variable

2 Install Vue and Bootstrap via NPM

npm install vue bootstrap-vue bootstrap

3 Install the ECRS Vue Library

npm install

4 Import Bootstrap and ECRS Vue

Everything

// main.js

import Vue from 'vue';
import BootstrapVue from 'bootstrap-vue';
import ECRSVue from '@ecrs/vue';

// Load bootstrap styles and ECRS overrides
import 'bootstrap/dist/css/bootstrap.css';
import 'bootstrap-vue/dist/bootstrap-vue.css';
import '@ecrs/vue/dist/ecrs-vue.css';

Vue.use(BootstrapVue);
Vue.use(ECRSVue);

Optionally, styles can be loaded in a custom SCSS file. This will allow you to override variables with custom values:

// custom.scss

// Override variables here
// $primary: red;

// Import ecrs and bootstrap files last
@import '~@ecrs/vue/src/index.scss';
@import '~bootstrap/scss/bootstrap.scss';
@import '~bootstrap-vue/src/index.scss';
// main.js

import 'custom.scss';

Useful Tips

Icons

This library uses the vue-fontawesome component to allow using font awesome icons in Vue.

By default, ecrs-vue will only import the icons it needs to render its components. To easily hook into the icon loading, a list of icons can be passed in as options to the plugin:

import Vue from 'vue';
import BootstrapVue from 'bootstrap-vue';
import ECRSVue from '@ecrs/vue';
import { faPlusCircle } from '@fortawesome/free-solid-svg-icons';

Vue.use(BootstrapVue);
Vue.use(ECRSVue, {
    icons: [
        faPlusCircle
    ]
});

Note that the correct icon package will need to be installed for this to work

Project Development

Development in this project should be mandated by a mutual agreement that additional functionality should be added or bugs should be fixed.

Commands

  • Initialize project

    npm install
  • Push package to the ECRS NPM Repository

    npm publish
  • Compile and minify for production

    npm run build
  • Scaffold the files needed for a new component

    # Note that the -- is intentional
    npm run gen:component -- --name=<component-name>
  • Run lint tools to fix code formatting

    npm run lint
  • Compile Storybook as static pages for deployment

    npm run storybook:build
  • Run development mode with Storybook

    npm run storybook:serve
  • Run unit tests

    npm run test
  • Show npm dependency updates

    npm run update

Tools

Vue

Each component is written with the Vue component library. As well, the build command will use the vue-cli-service to compile the library.

Storybook

Storybook is a development environment for previewing and interacting with components.

Jest

Jest enables unit testing at the component level. These test are run when using the test command.

ESLint & Stylelint

ESLint allows enforcing arbitrary formatting and error prevention rules in Javascript.

Stylelint provides the same functionality as ESLint, but to CSS/SCSS content.

Both of these are run when using the lint or test command.

npm-check and npm-audit-ci

These are CLI tools for managing package updates and ensures the testing phase fails if there are known vulnerabilities.

Setting Up Development with Another Project

While it is recommended that you use Storybook for isolated component development, it can be useful to edit a component in tandem with a separate project.

To temporarily setup this up:

  1. Run this command in this project
    npm link
  2. Navigate to the other project that uses this one and run this command:
    npm link @ecrs/vue

Now you can simply make your changes to your components and run the build command. The other project will pick up the changes without having to re-install them from NPM. If you need to use the npm hosted package, you can unlink the local version by running:

npm unlink @ecrs/vue

Creating a New Component

To scaffold the files needed for a new component, run the following command:

# Note that the -- is intentional
npm run gen:component -- --name=[component-name]

Where component-name is the name of the component. The name should follow these guidelines:

  • These should not start with E (as you see all existing components do). This is added automatically
  • The name should be proper case

Once this is done, 4 new files are generated:

  • EComponent.vue - the actual component file
  • EComponent.stories.js - the story entries for Storybook
  • EComponent.spec.js - the Jes unit tests
  • index.js - an entry point to installing the component as a plugin

Read the next sections to learn what to do with these files.

Component Development

Icons

This library used FontAwesome for its icons. To facilitate their usage, all icons should be added to icons.js

Unit Tests

npm run test:unit

Each component is required to have a unit test or building the project will fail. Tests are written with Jest testing library. Each component created comes with a sample test:

test('can be created', () => {
    const wrapper = shallowMount(EInput, {});

    expect(wrapper.isVueInstance()).toBe(true);
});

This test simply ensures that the component is created and is a valid Vue component.

Furthermore, the tests much reach a certain coverage threshold or they will fail.

Each of these test coverage categories must be meet or exceed 70% coverage:

  • Statements - Has each statement in the program been executed?
  • Branches - Has each conditional branch path been executed? (ei. for if statements, have both the if and else statements been executed)
  • Functions - Has each function in the component been called?
  • Lines - Has each executable line in the component been executed?

Stories

Each component is required to have a set of Storybook stories. A single story describes a component in a specific state. For example, the EButton component contains this story to demonstrate a button with text:

.add('with text', () => ({
    components: { EButton },
    template: '<e-button variant="primary" @click="action">Buttion Text</e-button>',
    methods: { action: action('Clicked') }
}))

Stories should attempt to cover each state that a component can be in.

For complex components, knobs can be included to change the state of the UI rather than creating several stories. See the documentation on how to use the knobs addon.