npm package: @productfy/react-ui
Description: ![Productfy](https://github.com/productfy/react-ui/raw/main/images/logo.png?raw=true)
Author: Phi Dong
Latest version: 1.6.2

![Productfy](https://github.com/productfy/react-ui/raw/main/images/logo.png?raw=true)

# Productfy React UI Library

React-ui is a collection of React hooks and UI components for use with [Productfy.io](https://productfy.io/).

## Usage

Productfy react-ui library is published to npm under @productfy/react-ui. Components are self-contained and published individually using lerna and can be imported and used directly.

The package is published on [npm](https://www.npmjs.com/package/@productfy/react-ui).

### Installing the package

Install the package using yarn or npm

```
yarn add @productfy/react-ui
```

```
npm install @productfy/react-ui
```

### Install any missing dependencies

Productfy react-ui uses `react` and `@stitches/react`. These have been added as peer dependencies so if your project is missing them make sure to also add those (e.g.)

```
yarn add @stitches/react
```

### Using components

Components are exported in individual folders to keep bundle sizes small for you. You can import the component from `@productfy/react-ui/packages/<component-name>`.

```javascript
import ProductfyFinancialTransactions from '@productfy/react-ui/financial-transactions';

const MyComponent = () => <ProductfyFinancialTransactions userID={userId} setupSources={['Y']} />;
```

Alternatively, files are packaged together in index files for both commonjs and es modules and can be imported like `import { ComponentName } from '@productfy/react-ui'`.

Productfy react-ui is typed using TypeScript and ships with scripts so you can get linting in your editor.

## Styling

Productfy React-ui is styled using [stitches](https://stitches.dev/). The default theme and styles are provided as `@productfy/react-ui/styles` and can be customized to match your application. To create a custom theme to match your application you can import `css` from `styles` and define a theme. This theme can then be added to any parent container that contains components from this repo using `classname={myTheme}`.

```javascript
import { css, theme } from '@productfy/react-ui/styles';

const myAppStyles = css.theme({
  // Start with base productfy theme
  ...theme,
  // Override/customize any settings to match your application
  colors: {
    ...theme.colors,
    $primary: 'green',
    $secondary: 'blue',
  },
  space: {
    $1: '6px',
    $2: '12px',
    $3: '18px',
    $4: '24px',
    $5: '30px',
    $6: '36px',
  },
});

const StyledProductfyContainer = ({ children }) => <div className={myAppStyles}>{children}</div>;

export default StyledProductfyContainer;
```

Use the style container to wrap any Productfy components (this does not need to be the immediate parent, you could wrap your whole app if you wanted).

```javascript
// my app
import StyledProductfyContainer from 'styled-productfy-container';

//...
// All components imported from react-ui will inherit the defined theme
<StyledProductfyContainer>
  <MyOwnComponent />
  <ProductfyComponent1 />
  <ProductfyComponent2 />
</StyledProductfyContainer>;
```

## Developing

Producty react-ui library uses storybook to test and view components. You can use this to view what components are available. Components are located in the `/packages` folder.

### Exporting your component

Currently only components exported in index files are packaged.  Because this library exports a single file as well as individual components make sure that there are both default exports as well as named component exports.

```javascript
  export const MyComponent = ...

  export default MyComponent;
```

If you need to export a sub-component independently you can export it as a named export e.g.

```javascript
  export { default as MySubComponent } from './mySubComponent';
```

### Adding and running tests

This library is tested using jest and react-testing-library. To run all the tests you can use

`yarn test` - run all specs `yarn test-watch` - run all the specs in watch mode

To add a test, create a file in the component directory `<component-name>.test.tsx`.

### Running storybook

`yarn start` - starts a server on port http://localhost:6006/

### Linking and testing locally in another app

You can test importing locally into your application using `yarn link` in this project folder then using `yarn link @productfy/react-ui` in your application folder.  After you `yarn` your project will use files from the `/dist` folder that are built using `yarn build`.

### Adding stories

- Add a file `<component-name.stories>.tsx` in your component folder in the `packages` folder. Component properties can be defined/documented using [Storybook controls](https://storybook.js.org/docs/react/essentials/controls).

```javascript
import React from 'react';
import { storiesOf } from '@storybook/react';
import ButtonComponent from '.';

// Defines the controls available for the story
export default {
  // Defines section for story
  title: 'Button',
  argTypes: {
    size: {
      control: {
        type: 'select',
        options: ['small', 'medium', 'large'],
      },
      description: 'The size of the button',
      defaultValue: 'small',
    },
    type: {
      control: { type: 'select', options: ['pill', 'rounded'] },
      description: 'Type sets the look of the button (pill or rounded)',
      defaultValue: 'rounded',
    },
    level: { control: { type: 'select', options: ['primary', 'secondary', 'link'] } },
    children: { control: 'text', description: 'Button label' },
    onClick: { action: 'clicked' },
  },
};

// This value is the component name
export const Button = (args: any) => <ButtonComponent {...args} />;

// default control values
Button.args = {
  children: 'hello',
};
```

### Commiting to the repo

This repo uses conventional commits convention to allow for automatic versioning. To make this easier you can use `git cz` or `yarn commit` to use commitizen.

You can use `git cz --retry` to redo your previous git cz in case something fails.

## Releases

Releases are done using `semantic-release` and `rollup.js`. Commits should be made in the conventional changelog method so that versioning can be automatically maintained.

- Releases include an index barrel file with the entire `@productfy/react-ui` lib as well as individual components in each folder as well as bundled types.

#### Breaking changes

When introducing a breaking change, include `BREAKING CHANGE` at the end of your commit message. You can include a message describing the breaking change. This will introduce a new major version of the library.

## Adding dependencies

Dependencies should be added as peer dependencies `yarn add -P react`.

## Filing an issue

If you find any problems feel free to file an [issue](https://github.com/productfy/react-ui/issues/new) or create a pull request.