Cloudify UI Components

This repository contains React components reusable across Cloudify UI applications.

Table of Contents

• Installation
• Usage
• Documentation
• Development
• Testing
• Debugging
  • Internal
  • External
• Publishing
  • Useful links

Table of contents generated with markdown-toc

Installation

npm install cloudify-ui-components

Usage

To use the package in your environment just import the component you need. For example:

import { ApproveButton } from 'cloudify-ui-components';

export function MyButton() {
    return <ApproveButton icon='play' />; 
}

Documentation

Documentation of released versions can be found at https://docs.cloudify.co/ui-components/<version>.

You can get the same StoryBook documentation of the components locally by executing npm run build-storybook.

Development

Development environment is set up to enforce good practices in JS development (static code analysis, style formatting, code test coverage check, visual regression testing).

General guidelines for adding new components:

• add new code to src/components (or src/components/ids for components that are direct implementations of their IDS counterparts, see IDS README.md for specific guidelines about IDS components development)
• every exported component should be in separate folder
• remember to export new files using index.ts
• remember to export props interface along with the component
• first story in every component storybook is a default one and will be presented differently it will not have a presented name (even when .storyName is being set)
• build: npm run build (production build) or npm run storybook (run StoryBook with automatic rebuilding)
• test: npm test (static analysis, code style check, unit testing with Jest testing framework and coverage check)
• use prettier and eslint during development
• document your code by providing general description for component at the top of the component definition and description for all component props (StoryBook recognize react-docgen format)
• write StoryBook stories for every newly added component

DDS-core upgrade

To upgrade dds-core:

• delete contents of dds-core/src directory
• get new version of dds-core from https://gitlab.dell.com/dao/dell-digital-design/design-language-system/systems/dds-2.0-core - the repository can be cloned or its contents can be downloaded
• place the obtained source code in dds-core/src
• run npm run setup-dds-core
• remove package*.json from dds-core/src directory in order to silence warnings from Dependabot
• run all cloudify-ui-components tests to verify if there are any breaking changes that need to be addressed
• once completed, commit all the changes, including full content of dds-core/src directory

Testing

There are few different types of tests in this package:

1. Static analysis and code style checks - npm run lint)
2. Unit tests - npm run test:jest (checks components logic)
3. Visual regression tests - npm run test:loki (takes screenshots of every story and compares them to reference images)

NOTE: Visual regression tests depends on the environment - OS and browser used. Reliable results matching reference images can be gather only using Jenkins. In order to update screenshots:

• download and decompress current.tar.gz file taken from the Jenkins job artifacts
• replace relevant screenshots in .loki/reference directory

Debugging

Internal

You can debug components with use of StoryBook application (npm run storybook) or Jest unit tests (npm run test:jest).

External

If you want to develop/debug cloudify-ui-components from the package user side (eg. from cloudify-stage), then instead of using cloudify-ui-components package from NPM registry, you can:

1. Use npm link cloudify-ui-components <local-path-to-cloudify-ui-components> command in your package user project,
2. Build cloudify-ui-components project (see: Development section),
3. Run package user project and see changes applied locally in cloudify-ui-components.

Publishing

Cloudify UI Components library is published in NPM registry. See cloudify-ui-components@npm.

Cloudify UI Components uses the same mechanism as Cloudify UI Common repository for package publishing. Check Publishing section @ cloudify-ui-common for details.

Useful links

• cloudify-ui-components @ Jenkins
• cloudify-ui-components @ NPM
• cloudify-ui-components releases