KIS UI Library

Set of functional, mostly stateless, presentational, reactive UI components for KIS React project. The storybook is hosted here: https://dialexa.github.io/kis-ui.

Getting Started

As you develop the kiosk / admin portals, you will likely have to make edits to this project and use them in tandem with those repos. Rather than republishing this over and over in the npm registry, you should link your local version of kis-ui into any and all dependent repos. Before continuing, install yalc:

yarn global add yalc

Developing

Setup and run storybook

To get the UI library up and running storybook, run the below command.

yarn install && yarn storybook

This will serve the documentation site at localhost:9001.

Developing alongside a dependent application

To make updates to this package and have them propagate to any dependent applications, run the following set of steps:

1. [Do this once] Publish your kis-ui repo to your local yalc repository (found at ~/.yalc)

yarn build
yalc publish

2. Link it to your dependent project. The project will then use your yalc published kis-ui. For example:

cd /path/to/kis-kiosk
yalc link @kistech/kis-ui

3. Make edits to this repo, and push those changes to all dependent repos (yalc automatically tracks this, so a single push will propagate changes to both the kiosk and admin portals, for example).

yarn push:local

To remove the link in dependent repo:

yalc remove @kistech/kis-ui
yarn # to reinstall the version found on the npm registry

When making a PR

Merges into the master branch will cause the Jenkins pipeline to deploy the UI-kit to the public @kistech/kis-ui NPM registry. As such, you need to increase the version in the package.json file before merging to master. Use semantic versioning when deciding what to set the version to:

• Major version: causes breaking changes, major implementation differences
• Minor version: new features / components, but otherwise backwards compatible
• Sub-minor version: Bug fixes, no breaking changes but may add new props to some components.

If you don't bump the version, then NPM will throw a deployment error because a UI-kit with that version already exists in the registry.

Integration after a feature is complete

Unlike the other repos that have a develop, qa, and master branch, this repo only contains a master branch. When you make PR's with new features or bug fixes, you will set the base branch to master. Once it is demoed, reviewed, and approved, then it is merged straight into master. The Jenkins pipeline will then build the UI-kit and publish it to the @kistech/kis-ui NPM Registry.

Once it is published (the build takes no more than a few minutes to build and deploy), then you can go to a dependent repo and update the dependency accordingly. For example, say you updated from version 1.0.0 to version 1.0.1.

cd /path/to/kis-kiosk
vim package.json
# In the dependency object, edit the version from 1.0.0 to 1.0.1. Save and exit
yarn # This will install the new version from NPM

Running a git diff will show two diffs: the update you made to the package.json file, and a corresponding update in the yarn.lock file that the yarn command made automatically. Make sure they are in sync, and then you can commit the changes in that repo.

Built With

The UI library is created with Create React App build. Other dependencies for the library and documentation site:

• Typescript for typescript.
• Storybook for documentation of each component that can render and be rendered as a react component.
• Husky and Lint Staged to lint and format staged files as a precommit hook.
• ESLint for linting using the Create React App config.
• Babel for writing modern JS using the Create React App presets.
• Prettier and ESLint Prettier to format code in the precommit hook.
• React Docgen Typescript Loader to be able to pass component source code to Storybook's Props.
• Marked for markdown compiling.
• Styled Components for ALL styling for components.
• Polished for style transforms like lighten() or darken().
• Testing-Library for creating tests.

Prerequisites

The only global dependencies necessary to develop locally with the UI library are Node and Yarn

Adding Components

You will add components by creating a new direction in src/lib. This directory should adhere to the following folder/file structure:

• lib/Component/index.ts to export your main components and any other components, along with types.ts.
• lib/Component/story is what gets rendered on the storybook documentation site. Start by adding a storiesOf function with the title as the first argumenta and module as the second. This should be chained with a .add with the first argument as the example title and second argument as the the withInfo containing the a short description, which invokes a callback that contains a jsx for examples to display. See existing story files for how these components are created.
• lib/Component/components is where your actual react components live.
• lib/Component/styled is where all your styled components live.
• lib/Component/tests for any tests related to the component.

From here you can head to src/lib/index, import the components index and export *.

Tests

Tests are written with Jest and Testing-Library using the default Create React App config. Tests should be placed in a tests directory inside of the component or store directory of which they are being written for. To run tests...

yarn test

Building

yarn build

This will clear out any existing build directory and build the components for distribution. This is what will be uploaded to the NPM registry

Deploying

Prerequisites: You must have push access to the @kistech/kis-ui repository. Ask a teammate for access. Prerequisites: Make sure you bump the version number in package.json before running the following commands.

npm login
npm deploy

Versioning

TODO

Licensing

TODO