diff --git a/translations/react-styleguide-pt-br.md b/translations/react-styleguide-pt-br.md new file mode 100644 index 0000000..0023d7c --- /dev/null +++ b/translations/react-styleguide-pt-br.md @@ -0,0 +1,406 @@ +# WIP - Projeto guia de formatação React + +**Este documento esta em construção (WIP) e pode ser modificado conforme necessário** + +Projetos [reactJS](https://reactjs.org/) podem escalar muito bem, mas também podem se tornar caóticos muito rapidamente. +Este guia tenta resolver problemas comuns em projetos React grandes. + +## Propósito + +Criar e documentar um guia [ReactJS](https://reactjs.org/) opinativo para projetos baseados em componentes. + +## Contibuindo + +Toda ajuda para melhorar esse documento é bem-vinda. + +Sugiro abrir uma [issue](https://github.com/andre-araujo/react-styleguide/issues/new), e marcar com as seguintes tags: + +- help wanted (perciso de ajuda) + > Qualquer conceito não compreendido, pergunta ou dúvida. +- opinion (opnião) + > Qualquer opnião sobre qualquer conceito. +- enhancement (aprimoramento) + > ideias para melhorar o documento. +- grammar (gramática) + > erros de gramática ou palavras com erros ortográficos. + +## Índice + +1. [Estrutura de pastas](#estrutura-de-pastas) +2. [Componentes](#componentes) + 1. [Elementos](#elementos) + 2. [Módulos](#modulos) + 3. [Features](#features) + 4. [Sub-componentes](#sub-componentes) + 5. [Componentes de terceiros](#componentes-de-terceiros) + 6. [Reusando a lógica de componentes](#reusando-a-lógica-de-componentes) + 7. [Estilização](#estilização) +3. [Commits](#commits) + +## Estrutura de pastas + +Este guia abrange apenas a pasta `/src`. + +``` +/src + /components + /elements + /NomeDoElemento + NomeDoElemento.js + NomeDoElemento.spec.js + NomeDoElemento.stories.js + NomeDoElemento.styles.js + index.js + /modules + /NomeDoModulo + NomeDoModulo.js + NomeDoModulo.spec.js + NomeDoModulo.stories.js + NomeDoModulo.styles.js + index.js + /features + /NomeDaFeature + NomeDaFeature.js + NomeDaFeature.spec.js + NomeDaFeature.stories.js + NomeDaFeature.styles.js + index.js + index.js + /pages + /minha-pagina + ... + /outra-pagina + ... + router.js + /lib + /stateManager + /actions + ... + /reduces + ... + index.js + /utils + ... + /static + /styles + reset.css + outro-estilo-estatico.css + /fonts + minha-fonte.woff + /images + minha-imagem.jpg + index.js +``` + +**[Voltar para o topo](#índice)** + +## Componentes + +[react-create-component](https://github.com/andre-araujo/react-create-component) pode ser usado para ajudar na criação de componentes. + +Cada componente tem a seguinte estrutura: +``` +NomeDoModulo.js +NomeDoModulo.spec.js +NomeDoModulo.stories.js +NomeDoModulo.styles.js +index.js +``` + +Onde: + +- `NomeDoComponente.js` + - é o próprio componente. +- `NomeDoComponente.spec.js` + - tem os casos de teste do componente. +- `NomeDoComponente.stories.js`: + - [Storybook](https://storybook.js.org/), ou qualquer outro tipo de documentação que substitua o ".stories", se necessário. +- `NomeDoComponente.styles.js`: + - estilo do componente, pode ser qualquer CSS ou solução de CSS em Javascript. +- `index.js`: + - índice do componente, qualquer High Order Componente deve ser aplicado aqui. + +### Elementos + +Nesse sistema, os elementos são o menor tipo de componente. Eles devem ser altamanente encapsuláveis, mas sem *state* prórpio, e não devem conter margem, espaçamentos ou qualquer outro estilo que possa interferir com o estilo geral da página. + +*Exemplos: botões, inputs, ...* + +#### Regras dos elementos: + +- Elementos não têm [sub-componentes](#sub-componentes). + > Por quê? Elementos devem ser pequenos e ter uma única responsabilidade. Se precisar de um sub-componente, então deveria ser um módulo. + +- **Elementos não podem ser quebrados**. + > Por quê? Se um elemento pode ser desmembrado, então não é o menor possível. + +- Todo elemento deve repassar props não usadas para o seu elemento raiz. + > Por quê? Isso aumenta a reusabilidade. Repassar props remanescentes para o componente raiz nos permite mudar atributos HTML, como *data-attributes*, *width*, *height*, ... + +- Elementos não devem ter margens. + > Por quê? Adicinar margem aos elementos os deixa mais difícil de alinhar e reutilizar. + +- Elementos devem ser *stateless*. + > Por quê? Controlar elemtentos *stateful* pode ser bem difícil, por isso elementos devem ser controlados por seus pais. + +#### Exemplo de elemento: + +```javascript +import React from 'react'; +import { string, node } from 'prop-types'; + +function MyElement({ + name, + ...props, +}) { + return ( +
+ Eu sou o elemento {name}! +
+ ); +} + +MyElement.defaultProps = { + name: 'default name', +}; + +MyElement.propTypes = { + name: string, +}; + +export default MyElement; +``` + +### Módulos + +Módulos usam elementos para criar componentes mais complexos. Eles devem ter um *state* e devem ser facilmente reutilizáveis. Eles organizam elementos ou outros módulos, adicionando margens e modificações aos elementos, mas não devem ter margens e espaçamentos próprios. + +Módulos podem ter [sub-componentes](#sub-componentes). + +*Exemplos: Menu, Dropdown, ...* + +#### Regras dos módulos: + + - Módulos podem ter [sub-componentes](#sub-componentes). + > Por quê? Tem alguns módulos que fazem sentido serem divididos em outros componentes conforme eles crescem, mas nem todos os componentes do módulo serão reutilizados em outros lugares, veja a sessão de [sub-componentes](#sub-componentes) para mais detalhes. + +- Módulos não devem ter margens. + > Por quê? Adicinar margem aos módulos os deixa mais difícil de alinhar e reutilizar. + +- Módulos devem usar elementos, se possível. + > Por quê? Elementos devem ser reutilizados o máximo possível para manter a consistência da aplicação, mas os módulos também podem mudar o estilo dos elementos para que se adaptem melhor. + +- Módulos podem ser *stateful* quando necessário. + > Por quê? Módulos devem ser fáceis de ser controlados pelos seus pais, mas, como são mais complexos, às vezes é necessário que tenham um *state*. + +- Módulos devem evitar *getDerivedStateFromProps* para manipular seu *state*. + > Por quê? Leia [este artigo](https://reactjs.org/blog/2018/06/07/you-probably-dont-need-derived-state.html) (em inglês). + +#### Exemplo de módulo: + +```javascript +import React from 'react'; +import { string, node } from 'prop-types'; + +import { MyElement } from '../..'; + +function MyModule({ + title, + children + ...props, +}) { + return ( +