88 lines
5.3 KiB
Markdown
88 lines
5.3 KiB
Markdown
Bem-vindo à biblioteca `ui-components` do freeCodeCamp. Os componentes são construídos, em grande parte, do zero, com elementos HTML básicos e [Tailwind CSS](https://tailwindcss.com/).
|
|
|
|
# Como trabalhar na biblioteca de componentes
|
|
|
|
> [!NOTE]
|
|
>
|
|
> O freeCodeCamp tem usado componentes do Bootstrap na interface do usuário. No entanto, estamos nos afastando disso e construindo nossa própria biblioteca de componentes, o que ajuda a padronizar nossos padrões de UX/UI e melhorar a acessibilidade. O projeto é acompanhado [nesta issue do GitHub](https://github.com/freeCodeCamp/freeCodeCamp/issues/44668).
|
|
|
|
São recomendados os seguintes passos ao trabalhar em um novo componente:
|
|
|
|
- Pesquisar e planejar
|
|
- Implementar o componente
|
|
- Exibir os casos de uso no Storybook
|
|
- Escrever testes unitários
|
|
|
|
## Pesquisar e planejar
|
|
|
|
Antes de construir um componente, você precisa pesquisar e documentar como a versão existente se comporta e qual é sua aparência, para garantir que o novo tenha estilos correspondentes e suporte todos os usos atuais. Para atender aos requisitos de acessibilidade da web, você também deve prestar atenção ao aspecto de acessibilidade do componente, ver quais elementos HTML e atributos ARIA são usados por baixo dos panos.
|
|
|
|
Depois de coletar informações suficientes sobre o componente, você pode começar a pensar na interface de propriedades. Idealmente, a interface deveria ser o mais semelhante possível à versão atual, a fim de facilitar a adoção mais tarde. Como estamos usando componentes do Bootstrap, a abordagem mais simples é imitar a [implementação deles](https://github.com/react-bootstrap/react-bootstrap/tree/master/src).
|
|
|
|
Preferimos pull requests menores do que grandes, porque eles aceleram o tempo de revisão e reduzem a sobrecarga cognitiva para os revisores. Por essa razão, pense em como dividiria a implementação e apresentaria um plano de entrega.
|
|
|
|
Recomendamos abrir uma issue separada no GitHub para cada componente e incluir todas as observações na descrição da issue. Ela pode ser usada como um lugar para hospedar todas as suas notas de trabalho, assim como uma maneira de comunicar a abordagem aos revisores. Utilizaremos o tópico da issue para continuar a discussão, se necessário. [A issue sobre o componente Button](https://github.com/freeCodeCamp/freeCodeCamp/issues/45357) pode ser usada como uma referência.
|
|
|
|
## Implementar o componente
|
|
|
|
Um novo componente pode ser criado usando o seguinte comando a partir do diretório raiz:
|
|
|
|
```bash
|
|
cd tools/ui-components
|
|
|
|
npm run gen-component MyComponent
|
|
```
|
|
|
|
O comando gerará uma nova pasta dentro do diretório `ui-components`, com os seguintes arquivos:
|
|
|
|
| Nome do arquivo | Finalidade |
|
|
| -------------------------- | ----------------------------------------------------------------- |
|
|
| `index.ts` | É utilizado para exportar os componentes e os seus tipos. |
|
|
| `my-component.stories.tsx` | É utilizado para fazer a demonstração do componente no Storybook. |
|
|
| `my-component.test.tsx` | É um arquivo de teste. |
|
|
| `my-component.tsx` | É onde implementamos o componente. |
|
|
| `types.ts` | É onde localizamos a interface e os tipos do componente. |
|
|
|
|
Cada componente é diferente, mas, em geral, os componentes devem:
|
|
|
|
- Dar suporte à ref de encaminhamento
|
|
- Ser estilizados para temas claros e escuros
|
|
- Ser estilizados internamente com base em suas propriedades (os consumidores não devem precisar reestilizar o componente com a propriedade `className`)
|
|
- Usar o sistema de estilo integrado do Tailwind ao invés de ter estilos personalizados
|
|
|
|
### Links úteis
|
|
|
|
- [Configuração do Tailwind CSS](https://tailwindcss.com/docs/configuration)
|
|
- [Documentação do React Bootstrap v0.33](https://react-bootstrap-v3.netlify.app)
|
|
- [Folha de estilos do Bootstrap 3.3.7](https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.css)
|
|
- [Implementação atual do React Bootstrap](https://github.com/react-bootstrap/react-bootstrap/tree/master/src)
|
|
- [Testes atuais do React Bootstrap](https://github.com/react-bootstrap/react-bootstrap/tree/master/test)
|
|
|
|
## Exibir os casos de uso no Storybook
|
|
|
|
Os casos de uso do componente devem ser adicionados ao arquivo Storybook (`.stories.tsx`).
|
|
|
|
Para iniciar o Storybook, execute o seguinte comando a partir do diretório raiz:
|
|
|
|
```bash
|
|
npm run storybook
|
|
```
|
|
|
|
A página do Storybook está disponível em [http://localhost:6006](http://localhost:6006).
|
|
|
|
## Escrever testes unitários
|
|
|
|
Usamos a [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) (biblioteca de testes do React) para escrever testes unitários. Os testes devem investigar se os componentes se comportam como esperados e se estão acessíveis.
|
|
|
|
Para executar testes contra a biblioteca de componentes, execute o seguinte comando a partir do diretório raiz:
|
|
|
|
```bash
|
|
npm run test-ui-components
|
|
```
|
|
|
|
### Links úteis
|
|
|
|
- [Testes de acessibilidade](https://testing-library.com/docs/dom-testing-library/api-accessibility)
|
|
- [Ordem de prioridade das consultas da biblioteca de testes do React](https://testing-library.com/docs/queries/about/#priority)
|
|
- [Erros comuns com a biblioteca de testes do React](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library)
|