# `@nimbus-ds/components`
[](https://www.npmjs.com/package/@nimbus-ds/components)
Nimbus components is a component library built with [React](https://reactjs.org), designed to help our teams and ecosystem build better products for our merchants.
## ๐ Getting started
Install `@nimbus-ds/components` using any package manager.
```sh
$ yarn add @nimbus-ds/components
# or
$ npm install @nimbus-ds/components
```
## ๐ป Usage
```jsx
import { Button } from "@nimbus-ds/components";
const ComponentExample = () => ;
```
For more information about our components, check out our [Storybook](https://tiendanube.github.io/nimbus-design-system/).
### Folder & file structures ๐ ๐
- For best practices in structure files please read this [document](https://redux.js.org/style-guide/style-guide#structure-files-as-feature-folders-with-single-file-logic)
- When creating a new component, do so inside the **src/atomic** or **src/composite** directory
```
โโ ๐ src
โ โโ ๐ atomic/composite
```
- Every directory must contain a ๐ **CHANGELOG.md** which serves to document all changes and changes made to each component.
```
โโ ๐ src
โ โโ ๐ atomic/composite
โ โ โโ ๐ ComponentExample
โ โ โ โโ ๐ src
โ โ โ โโ CHANGELOG.md
```
- Every directory should contain a ๐ **README.md** which serves to document the installation steps and a brief summary of each component.
```
โโ ๐ src
โ โโ ๐ atomic/composite
โ โ โโ ๐ ComponentExample
โ โ โ โโ ๐ src
โ โ โ โโ CHANGELOG.md
โ โ โ โโ README.md
```
- The directory should have the same name as the component. The component file should have the name of the component in Pascal Case format and the extension `.tsx`
```
โโ ๐ src
โ โโ ๐ atomic/composite
โ โ โโ ๐ ComponentExample
โ โ โ โโ ๐ src
โ โ โ โ โโ ComponentExample.tsx
โ โ โ โโ CHANGELOG.md
โ โ โ โโ README.md
```
- Every directory should contain a ๐ **index.ts** which serves as an entry point for the module, component, utils and/or hooks.
```
โโ ๐ src
โ โโ ๐ atomic/composite
โ โ โโ ๐ ComponentExample
โ โ โ โโ ๐ src
โ โ โ โ โโ index.ts
โ โ โ โ โโ ComponentExample.tsx
โ โ โ โโ CHANGELOG.md
โ โ โ โโ README.md
```
- Every component, utils and/or hooks should come with a test. The test must have the same name as the file being tested and the extension must be `.spec.tsx`
```
โโ ๐ src
โ โโ ๐ atomic/composite
โ โ โโ ๐ ComponentExample
โ โ โ โโ ๐ src
โ โ โ โ โโ index.ts
โ โ โ โ โโ ComponentExample.tsx
โ โ โ โ โโ componentExample.spec.tsx
โ โ โ โโ CHANGELOG.md
โ โ โ โโ README.md
```
- Every component must come with documentation. The documentation must have the same name as the file being documented and the extension must be `.stories.tsx`.
```
โโ ๐ src
โ โโ ๐ atomic/composite
โ โ โโ ๐ ComponentExample
โ โ โ โโ ๐ src
โ โ โ โ โโ index.ts
โ โ โ โ โโ ComponentExample.tsx
โ โ โ โ โโ componentExample.spec.tsx
โ โ โ โ โโ componentExample.stories.tsx
โ โ โ โโ CHANGELOG.md
โ โ โ โโ README.md
```
- Every component must come with a typing. The type must have the same name as the file being documented and the extension must be `.types.tsx`.
```
โโ ๐ src
โ โโ ๐ atomic/composite
โ โ โโ ๐ ComponentExample
โ โ โ โโ ๐ src
โ โ โ โ โโ index.ts
โ โ โ โ โโ ComponentExample.tsx
โ โ โ โ โโ componentExample.spec.tsx
โ โ โ โ โโ componentExample.stories.tsx
โ โ โ โ โโ componentExample.types.ts
โ โ โ โโ CHANGELOG.md
โ โ โ โโ README.md
```
- If a component has one or more children components, a subdirectory **๐ components** must be created inside de main directory of the component.
```
โโ ๐ src
โ โโ ๐ atomic/composite
โ โ โโ ๐ ComponentExample
โ โ โ โโ ๐ src
โ โ โ โ โโ ๐ components
โ โ โ โ โ โโ ๐ ComponentChild
โ โ โ โ โ โ โโ index.ts
โ โ โ โ โ โ โโ ComponentChild.tsx
โ โ โ โ โ โ โโ componentChild.spec.tsx
โ โ โ โ โ โ โโ componentExample.types.ts
โ โ โ โ โ โโ index.ts
โ โ โ โ โโ index.ts
โ โ โ โ โโ ComponentExample.tsx
โ โ โ โ โโ componentExample.spec.tsx
โ โ โ โ โโ componentExample.stories.tsx
โ โ โ โ โโ componentExample.types.ts
โ โ โ โโ CHANGELOG.md
โ โ โ โโ README.md
```
### Component coding ๐ค โจ๏ธ
- The component should have the same name as the file using Pascal Case format. It should be declared in a Arrow Function, always typying the expected answer and making the default export at the end of the file.
```jsx
// ComponentExample.tsx
import React from "react";
const ComponentExample: React.FC = () =>
...
;
export { ComponentExample };
```
- If the component has props, they will be imported from the corresponding `.definitions.ts` file adding initial prefix corresponding to their type. Example interface ` ILogin`, type `TLogin`, enum `ELogin`.
```jsx
// ComponentExample.tsx
import React from "react";
import { ComponentExampleProps } from "./componentExampleProps.types";
const ComponentExample: React.FC = ({
title,
description,
}) => (
{title}
{description}
);
export { ComponentExample };
```
### Testing ๐งช๐ฌ
- For testing best practices, please read this [document](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library).
- To create a test is necessary to import from the testing library both the render and the screen.
```jsx
import { render, screen } from "@testing-library/react";
```
- The component to be tested should also be imported.
```jsx
import { render, screen } from "@testing-library/react";
import { ComponentExample } from "./ComponentExample";
```
- The heading of the tests must be written following the order Given-When-Then [Documentation](https://cucumber.io/docs/gherkin/reference/)
- **Given** represents a precondition
- **When** an action
- **Then** a result or consequence of the action (user acceptance criteria).
- **And** a result or consequence of other consequence (user acceptance criteria).
- **But** a result which should not be possibly observable
```jsx
import { render, screen } from "@testing-library/react";
import { ComponentExample } from "./ComponentExample";
describe("GIVEN ", () => {
describe("WHEN rendered", () => {
it("THEN should display the correct text", () => {
...
});
});
});
```
- In this first instance, we will verify the right rendering of the component by checking the text in each of the elements.
```jsx
import { render, screen } from "@testing-library/react";
import { ComponentExample } from "./ComponentExample";
describe("GIVEN ", () => {
describe("WHEN rendered", () => {
it("THEN should display the correct text", () => {
render();
expect(screen.getByText(/title/i)).toBeInTheDocument();
expect(screen.getByText(/description/i)).toBeInTheDocument();
});
});
});
```