@tst-labs/basilar

BASILAR

A @tst-labs/basilar é uma proposta de biblioteca de componentes, inicialmente direcionada aos desenvolvedores do TST, contendo as bases necessárias para a construção de UIs em React e Material UI, que leva em consideração os elementos (design tokens) estabelecidos pelo Manual de Identidade Visual JT/TST.

Nesse primeiro momento, a @tst-labs/basilar está configurada para usar as versões v5.6.4 da MUI e v18.1.0 do React. Em um momento futuro (não muito distante) pretendemos torná-la compatível com as versões mais antigas em uso nos projetos de front end em produção no TST.

Começando a usar (Getting Started)

Instale a @tst-labs/basilar como dependência no seu projeto React

yarn add @tst-labs/basilar

Recomendamos o uso de yarn em seus projetos, mas não é uma exigência.

Em seguida é só escolher que funcionalidades exportadas pela @tst-labs/basilar deseja usar no seu projeto. Por exemplo, use o tema padrão do TST em seu projeto:

import React from 'react';
import ReactDOM from 'react-dom/client';
import CssBaseline from '@mui/material/CssBaseline';

import { ProvedorTemaTST } from '@tst-labs/basilar';

import App from './app/app';

import './index.css';

const root = ReactDOM.createRoot(document.getElementById('root'));

root.render(
  <React.StrictMode>
    <ProvedorTemaTST>
      <CssBaseline />
      <App />
    </ProvedorTemaTST>
  </React.StrictMode>
);

Pré-requisitos (ambiente de desenvolvimento e uso)

Usamos Node.js v16.x, mas já foi testada com v14.x e funciona bem. Recomendamos o uso do nvm para gerencia as versões do Node em sua máquina de trabalho.

Scripts do projeto

Usamos o yarn nesse projeto. No diretório do projeto você pode executar os seguintes de scripts:

yarn build

Empacota a biblioteca, usando o rollup, no diretório dist/.

yarn build-watch

Empacota a biblioteca, usando o rollup, no diretório dist/ e fica verificando alterações a serem reempacotadas.

yarn test

Inicia uma sessão interativa de testes executando react-scripts test.

yarn test:ci

Executa react-scripts test mas configurado para ser usado em pipelines de CI/CD.

Como adicionar novos componentes

Adotaremos um processo de trabalho manual para adicionar novos componentes à @tst-labs/basilar descrita nos passos a seguir.

1. Clone o repositório em seu host de trabalho:

# ### Pode usar https ou ssh, como preferir. Abaixo uso SSH.
git clone [e-mail]:tst-labs/basilar.git
# ### Mude para o diretório do projeto
cd basilar

2. Instale as dependências:

# ### IMPORTANTE: Usamos o yarn nesse projeto. Evite problemas!
yarn
# ### Ou
# yarn install

3. Insira novos componentes, seus testes e histórias (Storybook stories):

Os componentes deverão ser organizados abaixo do diretório src/componentes/ em diretórios próprios e exportados em arquivos index.js. O diretório raíz dos componentes (supracitado) tem o index.js que exporta tudo da biblioteca.

Explore o diretório de componentes para ter ideia de como organizar os novos componentes.

4. Exponha a biblioteca no seu host para uso em outros projetos:

# ### Ao usar o yarn link você instalará a biblioteca no repositório global do host.
# ### No diretório raíz do projeto execute o seguinte comando:
yarn link

5. Link a biblioteca ao seu projeto final:

# ### No diretório raíz do projeto que usará a biblioteca execute o seguinte comando:
yarn link @tst-labs/basilar

Agora é só incluir o novo componente e testar em sua aplicação.

6. Crie uma nova branch de trabalho para submeter o(s) novo(s) componente(s):

# ### No diretório raíz do projeto:
git checkout -b novo-componente-fantastico

# ### Envie a nova *branch* para o repositório principal no Github:
git push --set-upstream origin novo-componente-fantastico

E crie um novo Pull Request explicando o que está sendo proposto para inclusão na biblioteca. Marque o PR como WIP (Work In Progress) para evitar que seja incorporado à biblioteca acidentalmente.

Essa conversa pode demorar caso haja alguma discordância entre os mantenedores sobre o componente sendo proposto, por isso não é bom contar com uma atualização automática da biblioteca tão logo o código seja enviado ao repositório principal.

Etapas posteriores

Assim que os MRs abertos sejam aceitos a documentação em Storybook da biblioteca já será atualizada, mas a biblioteca em si ainda dependerá de uma release para que seja publicada em uma nova versão na registry do npmjs.com.

Como contribuir

TODO:

Licença

Usamos licença MIT para esse projeto.

Colaboradores

• @lemos.dev