@repay/cactus-web

UI component library build for React, used by REPAY.

Usage

For usage, see the documentation for Cactus Web

Contributing

Running storybook for local development

yarn start

Testing the build

yarn test

Creating a new component

yarn new ComponentName

This will generate skeleton files for the component, tests, story, and documentation (.mdx) using the provided ComponentName.

Usage: node make-component.js [...options] ComponentName
- component name must be the last argument, contain no spaces,
  and should be pascal case.

  Options:
  --help, -h      display this information
  --force, -f     overwrite component if it exists

Building the repository

yarn build

Running the build in watch mode which will re-build on changes

yarn dev

Best Practices

Development

Components should have associated stories so that you as a developer can test the component in an active situation. The convention is to create an primary story called "Basic Usage" which allows the user to control the required properties. Then additional stories are created for optional properties.

Components are ideally exported as a styled component. This allows them to be styled directly by a parent component such as:

import styled from 'styled-components'
import { Button } from '@repay/cactus-web'

const Container = styled.div`
  padding: ${p => p.theme.space[0]};

  ${Button} {
    margin-left: ${p => p.theme.space[4]};
  }
`

If the component is not a static tag like styled.div, you can create a "base" component and style that:

import * as React from 'react'
import styled from 'styled-components'
import CloseIcon from '@repay/cactus-icons/i/actions-close'

interface ComponentProps & React.HTMLProps<HTMLDivElement> {
  showIcon: boolean
}

const ComponentBase = ({ showIcon, children, className, ...props }) => {
  return (
    <div className={className} {...props}>
      {showIcon && <CloseIcon />}
      {children}
    </div>
  )
}

export const Component = styled(ComponentBase)`
  padding: 8px;
`

export default Component

The requirement here, is that the className prop must be provided to the element that is being styled.

Styled System

We use Styled System to help ensure theme value adherence and decrease the difficulty of proper customizations. Most components should provide the margin properties.

Writing Documentation

Stories are both for development and documentation.

Documentation can be added directly to the mdx files alongside the components. You can also use the 'website-src' source alias which will point to the source root in the website directory.

The best practices section should include information related to accessibility or other critical information when using the component. However this section can be removed if there are none.

Basic usage section should have at least one example of usage as JSX. If usage in TypeScript is complex or interesting include that as well. Ideally any code written as basic usage can be copied and used directly.

A description can be added to a property via comment above the property definition. To force the inclusion of a property in the Properties section that is not showing up, add the prop to the definition with a comment above and type !important in the comment.

Testing

Components should be tested from the perspective of the end-user as possible; this means using the user-event library in combination with fireEvent() from react-testing-library. Additionally, when a label is rendered with text, it should be used to select the input element. This will best mimic the user's actions of reading the text to find the element and clicking or typing from there and enforces best practices for accessibility.

Example:

test('should trigger onChange event', () => {
  const onChange = jest.fn()
  const { getByLabelText } = render(
    <ThemeProvider theme={cactusTheme}>
      <CheckBoxField label="Katastro" name="katastro" onChange={onChange} />
    </ThemeProvider>
  )

  // Select the checkbox by label text, and fire the click event on it.
  fireEvent.click(getByLabelText('Katastro'))
  expect(onChange).toHaveBeenCalledWith('katastro', true)
})

Also, be sure to test the negative cases alongside the positive, such as when there is a diabled property:

test('should not trigger onChange event', () => {
  const onChange = jest.fn()
  const { getByLabelText } = render(
    <ThemeProvider theme={cactusTheme}>
      <CheckBoxField label="Flow" name="flow" onChange={onChange} disabled />
    </ThemeProvider>
  )

  userEvent.click(getByLabelText('Flow'))
  expect(onChange).not.toHaveBeenCalled()
})

Accessing Local Storybooks on iOS

Sometimes it may be necessary to view the storybooks on a mobile device to test/debug features like accessibility. To do this, you can follow these steps:

1. Plug an iPhone in to your Mac & make sure the phone is on the same network as the computer.
2. In the iPhone's settings, navigate to Safari > Advanced and make sure "Web Inspector" is turned on.
3. On your Mac, open Safari > Preferences > Advanced and make sure "Show develop menu in menu bar" is checked.
4. In the Safari search bar on the iPhone, type your computer's IP address followed by the port the storybooks are running on, which defaults to 9001. (Ex: 10.1.2.345:9001)
5. You can view the development console on Mac by clicking Develop > (your iPhone's name) > and selecting the browser window from the list of open windows on the iOS device.

Note: If you don't know your computer's IP address, you can get it by running ifconfig in your terminal. The IP address you'll want will be directly after inet in the last result returned from ifconfig.