Working with Components
Component Development Guide
This document provides instructions on how to work with components, including implementation, composition, and testing. It also covers guidelines for writing unit tests, minimum requirements for tests, code structure style choices, and following the development team's design principles. Please follow the instructions below.
Overview of Steps to Create a Component
To create a component, follow these steps:
Determine the purpose and functionality of the component.
Based on the atomic design methodology, classify the component into one of the atomic design categories: atoms, molecules, organisms, templates, or pages.
Create a new directory for the component -
ComponentName
, using the appropriate atomic design category as the directory name.Create necessary files for the component, such as the main component file, styling files (
ComponentName.module.css
), an optional utilityComponentName.utils.ts
file, and aComponentName.types.ts
file for TypeScript type definitions.Create an
index.ts
file within the component directory to export all relevant components, functions, and types from the component.Ensure the component adheres to the development team's design principles and style choices (refer to the "Style Choices for Code Structure" section below).
Test the component (refer to the "How to Write Unit Tests" section below).
In the "UI Library" section of GitBook, provide concise documentation for the component's usage, API, and key implementation details. This ensures users have a clear understanding of how to use the component effectively in their projects.
If the component is reusable and can be extended, consider creating documentation on how to extend it.
Create a Storybook story for the component (refer to the "Using Storybook" section below).
To display the red asterisk for required props, for instance,
children
and show the prop type in Storybook, you can update the component's prop definition by adding a description using the JSDoc syntax.
Style Choices for Code Structure
To follow the Sovryn development team's design principles and maintain code consistency, adhere to the following style choices for code structure:
Follow Coding Conventions: Familiarize yourself with established conventions for naming, file organization, and code formatting.
Use Meaningful Names: Opt for descriptive names for variables, functions, and components.
Break Down Complex Components: Divide complex components into reusable sub-components with clear responsibilities. Store these sub-components in a separate
components
folder within the main component's directory. This promotes a modular and organized structure, facilitating better understanding, reusability, and maintenance. Each sub-component should serve a specific purpose and encapsulate distinct functions within the overall component.Keep Code Concise: Avoid lengthy functions/components. Use smaller, focused units for better comprehension, testing, and maintenance.
Maintain Proper Formatting: Consistently apply indentation and formatting for improved readability.
Document Code: Use comments to explain the logic, provide context, and enhance collaboration.
Styling: For styling components, it is recommended to utilize separate
ComponentName.module.css
files to define component-specific styles. This practice ensures that only classes defined within the component are used, promoting encapsulation and preventing class name conflicts. However, developers can still incorporate Tailwind CSS styles by leveraging the@apply
directive. You can refer to the provided documentation link for further details: Styling Guidelines.
How to Write Unit Tests
Follow these guidelines when writing unit tests for components:
Create a separate test file for your component, typically named
ComponentName.test.tsx
.Write individual test cases within the test file to cover different aspects of your component's functionality.
Utilize Jest's testing APIs, such as
describe
,test
,expect
, and others, to structure and assert the desired behavior of your component.Run the tests using the Jest test runner with the command
npm test
oryarn test
.Review the test results in the terminal, and ensure that all tests pass successfully.
Tests should cover edge cases.
When testing components consisting of other components, you don't need to test the base functionality already covered in these child components.
By using Jest for unit testing, you can verify the correctness of your components, detect potential issues early on, and maintain a reliable codebase.
Minimum Requirements for Tests
To ensure code quality and minimize issues, adhere to the following minimum requirements for tests:
It is essential to ensure that every component has Jest tests in place.
Include tests for both positive and negative scenarios.
Cover the most critical and commonly used features of the component.
Update tests when modifying the component's behavior or functionality.
Regularly run the test suite during development and before committing changes.
Using Storybook
When creating a new component, it is recommended to use Storybook, an interactive UI component development environment. Storybook allows you to develop and test components in isolation, providing a visual representation of each component's variations and states.
To use Storybook for your component:
Create a new story file in your component's directory, typically named
ComponentName.stories.tsx
.Import and define the stories for your component using Storybook's API. Each story represents a different variation or state of the component.
Within the story definition, add a property called
argTypes
and assign it an object. Each key in this object should correspond to a prop name, and the value should be an object containing the description for that prop. For example:
argTypes: {
prop1: {
description: 'Description of prop1',
},
prop2: {
description: 'Description of prop2',
},
// Add more prop descriptions as needed
}
Replace prop1
and prop2
with the actual names of your props, and provide the corresponding descriptions for each prop.
Design Aids
Last updated