Working with Components
Last updated
Last updated
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.
To create a component, follow these steps:
Determine the purpose and functionality of the component.
Based on , 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 utility ComponentName.utils.ts file, and a ComponentName.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.
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.
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 or yarn 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.
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.
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:
Replace prop1 and prop2 with the actual names of your props, and provide the corresponding descriptions for each prop.
To follow the Sovryn development team's , adhere to the following style choices for code structure:
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: .
When creating a new component, it is recommended to use , 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.