@productfy/react-ui NPM

Productfy React UI Library

React-ui is a collection of React hooks and UI components for use with 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.

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>.

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. 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}.

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).

// 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.

  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.

  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.

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.