@reportportal/ui-kit

ReportPortal UI kit

This library is designed to reflect ReportPortal Design System components as React components.

alpha versions available

Installation

Install the package into your project using your favourite package manager:

Using npm

npm install @reportportal/ui-kit

or using yarn

yarn add @reportportal/ui-kit

or using pnpm

pnpm add @reportportal/ui-kit

Usage

• Import the library styles at the top-level of your application:

import '@reportportal/ui-kit/dist/style.css';

• To use the components in your project, import them from the package:

import { Button } from '@reportportal/ui-kit';

const MyComponent = () => (
    <Button>Button</Button>
);

Note: In the future we plan to calibrate the build process to prebuild styles individually for each component and enable tree-shaking.

Theming

All components are provided with the light theme by default. To use the dark theme, you need to wrap your application with the ThemeProvider component and pass the dark theme as a prop:

import { ThemeProvider, Button } from '@reportportal/ui-kit';

const MyComponent = () => (
    <ThemeProvider theme="dark">
        <Button>Dark theme button</Button>
    </ThemeProvider>
);

ThemeProvider can be nested to provide different themes for different parts of the application if needed.

import { ThemeProvider, Button } from '@reportportal/ui-kit';

const MyComponent = () => (
    <ThemeProvider theme="light">
        <Button>Light theme button</Button>
        <ThemeProvider theme="dark">
            <Button>Dark theme button override</Button>
        </ThemeProvider>
    </ThemeProvider>
);

Custom themes

The ThemeProvider component provides the ability to pass custom themes to the application.

To use a custom theme, you need to pass an object with the custom theme name as a key and the custom theme class name as a value to the customThemes prop of the ThemeProvider component:

import { ThemeProvider, Button } from '@reportportal/ui-kit';

const MyComponent = () => (
    <ThemeProvider customThemes={{ 'my-theme': 'my-custom-theme' }} theme="my-theme">
        <Button>Custom theme button</Button>
        <ThemeProvider theme="dark">
            <Button>Dark theme button override</Button>
        </ThemeProvider>
    </ThemeProvider>
);

Then just override the ui-kit CSS custom properties in your custom theme class:

.my-custom-theme {
  --rp-ui-base-font-family: OpenSans, Segoe UI, Tahoma, sans-serif;
  --rp-ui-color-primary: green;
  --rp-ui-color-primary-hover: #69e569;
  --rp-ui-color-primary-focused: var(--rp-ui-color-primary-hover);
  --rp-ui-color-primary-pressed: var(--rp-ui-color-primary-hover);
}

CSS custom properties and their default values can be found in the themes.

The number of custom themes is not limited and actual theme can be easily switched by changing the theme prop.

Components

To see a published showcase of the latest components released with its API and use cases, follow the link.

Icons

The library provides a set of SVG icons and the BaseIconButton component to apply basic styles for hover, disabled and other states to them.

The list of available icons can be found in the icons folder.

The icons exported as React components:

import { PlusIcon } from '@reportportal/ui-kit';

const MyComponent = () => (
    <PlusIcon />
);

To use the BaseIconButton component, you need to pass the icon component as a child:

import { BaseIconButton, PlusIcon } from '@reportportal/ui-kit';

const MyComponent = () => {
    const handleIconClick = () => {
        console.log('Icon clicked');
    };
    
    return (
        <BaseIconButton
            className={cx('my-icon')}
            disabled={false}
            onClick={handleIconClick}
        >
            <PlusIcon />
        </BaseIconButton>
    );
}

BaseIconButton supports all the props of the button HTML element.

Note: To support styling via BaseIconButton, it is recommended to use path-based, single-color SVG icons.

Development

The library is developed using React and TypeScript.

The Storybook used as a main development environment and a showcase for components.

To run it locally use

npm run start

To create a ready-to-deploy version of the Storybook, run

npm run build:storybook

Build process

We use vite as a build tool.

To build the library run

npm run build

Storybook showcase deploy

While the library is in alpha, the showcase hosted on GitHub Pages should be updated based on changes from the develop branch.

Deployment steps

• Navigate to the "Actions" page within the repository.
• Choose the "Deploy dev storybook showcase" action from list of available workflows.
• Click "Run workflow" button on the right and select the develop branch.
• Wait for the deployment process to complete. The progress can be tracked on the "Actions" page.
• Once the deployment is finished, verify that the changes have been deployed correctly, visiting GitHub Pages.

That's it! If you encounter any issues during the deployment process, please consult the documentation or reach out to the project maintainers for assistance.

Release

While the library is in alpha, the NPM package should be built and published from the develop branch with alpha tag.

Release steps

• Navigate to the "Actions" page within the repository.
• Choose the "Publish dev package version" action from list of available workflows.
• Click "Run workflow" button on the right and select the develop branch.
• Wait for the publishing process to complete. The progress can be tracked on the "Actions" page.
• Once the publishing is finished, verify that the changes have been published correctly, visiting NPM registry.

That's it! If you encounter any issues during the release process, please consult the documentation or reach out to the project maintainers for assistance.

Code style

We follow the Airbnb JavaScript Style Guide and use ESLint to enforce it.

CSS

We use SCSS as a CSS preprocessor.

Theming

The project uses CSS Custom Properties to provide colors/fonts/etc. values for different themes via theme-specific CSS classes. All components get the appropriate theme values at runtime based on the cascading nature of CSS.

This approach was chosen because it is easy to implement and maintain, and CSS Custom Properties are part of WEB standards and supported by all major browsers.

The CSS custom properties that come from DS are prefixed with rp-ui-base to avoid conflicts with other CSS properties and can be found in the base.scss.

External libs

• classnames - used for conditionally joining class names together.
• downshift - used to build simple, flexible, WAI-ARIA compliant React autocomplete/dropdown/select/combobox components.
• framer-motion - used for animations.
• rc-scrollbars - used for custom scrollbars.
• @floating-ui/react-dom - used for positioning menus, dropdown elements, autocompletes, etc.

Testing

Each new component/hook/utility must be covered by unit/component tests. All existing uncovered stuff will be tested gradually in the scope of tech-debt elimination activities.

Testing Tools

The project uses the following testing tools:

• Vitest: Fast testing framework, compatible with Vite
• React Testing Library: For testing React components with a focus on user interactions
• @testing-library/user-event: For simulating user events in tests
• JSDOM: For simulating a DOM environment in Node.js
• @vitest/coverage-v8: For code coverage reporting

Test Scripts

Available npm scripts for testing:

• npm run test - Run tests in watch mode
• npm run test:coverage - Run tests with coverage report
• npm run test:ci - Run tests once (for CI environments)
• npm run test:ui - Run tests with UI interface

Test Coverage

The project maintains a minimum of 80% test coverage threshold for:

• Statements
• Branches
• Functions
• Lines