repaygithub
@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 startTesting the build
yarn testCreating a new component
yarn new ComponentNameThis 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 existsBuilding the repository
yarn buildRunning the build in watch mode which will re-build on changes
yarn devBest 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 ComponentThe 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:
- Plug an iPhone in to your Mac & make sure the phone is on the same network as the computer.
- In the iPhone's settings, navigate to Safari > Advanced and make sure "Web Inspector" is turned on.
- On your Mac, open Safari > Preferences > Advanced and make sure "Show develop menu in menu bar" is checked.
- 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)
- 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.