@beetech/rroc

v1.4.6

Published

2 months ago

> Design System baseado em Material UI para projetos da Remessa Online

0High
0Medium
0Low

beetech

RROC - React Remessa Online Components

Design System baseado em Material UI para projetos da Remessa Online

📋 Índice

🎯 Sobre o Projeto

O RROC é um design system construído sobre o Material UI que padroniza e centraliza os componentes utilizados nos projetos da Remessa Online. Todos os componentes são customizáveis e mantêm a compatibilidade total com as props originais do Material UI.

Para desenvolver, usar e versão abaixo, devido a uso do Storybook

  "engines": {
    "node": ">=20.0.0"
  },

Projeto Visivel - StoryBook

🚀 Instalação

npm install @beetech/rroc

💡 Como Usar

import { Button, TextField, Alert } from '@beetech/rroc';

function App() {
  return (
    <div>
      <Button variant="contained" color="primary">
        Meu Botão
      </Button>
      <TextField label="Nome" variant="outlined" />
      <Alert severity="success">Operação realizada com sucesso!</Alert>
    </div>
  );
}

📦 Componentes Disponíveis

Formulários

Button - Botões com todas as variantes do Material UI
TextField - Campos de texto com suporte a validação
FormControl - Controle de formulários
InputLabel - Labels para inputs
Select - Seletor dropdown
Checkbox - Caixas de seleção
Autocomplete - Campo de autocompletar
Rating - Componente de avaliação

Exibição de Dados

Typography - Textos padronizados
Table - Tabelas com todos os componentes relacionados
Chip - Tags e labels
Badge - Badges de notificação
Avatar - Avatares de usuário
Alert - Alertas e notificações

Navegação e Layout

AppBar - Barra superior de navegação
Dialog - Modais e diálogos
Accordion - Painéis expansíveis

Feedback

CircularProgress - Indicador de carregamento

🛠 Desenvolvimento

Pré-requisitos

Node.js >= 20.0.0
npm ou yarn

Configuração Local

# Clone o repositório
git clone https://github.com/BeeTech-global/rroc.git

# Entre no diretório
cd rroc

# Instale as dependências
npm install

# Execute o Storybook para desenvolvimento
npm run storybook

🤝 Como Contribuir

1. Preparação do Ambiente

# Crie uma nova branch a partir da main
git checkout main
git pull origin main
git checkout -b feat/nome-do-componente

2. Padrões de Contribuição

Siga o padrão de nomenclatura: feat/, fix/, docs/
Todos os componentes devem ter TypeScript
Componentes importantes devem ter stories no Storybook
Execute os testes antes de fazer commit

3. Pull Request

Descreva claramente as mudanças
Inclua screenshots do Storybook se aplicável
Aguarde a revisão do código

📝 Criando Novos Componentes

Estrutura de Arquivos

src/components/
├── MeuComponente/
│   ├── MeuComponente.tsx      # Componente principal
│   ├── MeuComponente.stories.tsx  # Stories do Storybook
│   └── index.ts              # Exports

1. Criando o Componente

// src/components/MeuComponente/MeuComponente.tsx
import React from 'react';
import { 
  ComponenteOriginal as MuiComponenteOriginal, 
  ComponenteOriginalProps as MuiComponenteOriginalProps 
} from '@mui/material';

export interface MeuComponenteProps extends MuiComponenteOriginalProps {
  // Aqui você pode adicionar propriedades customizadas no futuro
}

export function MeuComponente({ children, ...props }: MeuComponenteProps) {
  return (
    <MuiComponenteOriginal {...props}>
      {children}
    </MuiComponenteOriginal>
  );
}

2. Criando o Arquivo de Export

// src/components/MeuComponente/index.ts
import { MeuComponente, MeuComponenteProps } from './MeuComponente';

export { MeuComponente, type MeuComponenteProps };

3. Atualizando o Index Principal

// src/components/index.ts
export * from './MeuComponente';
// ... outros exports

4. Criando Stories (Recomendado)

// src/components/MeuComponente/MeuComponente.stories.tsx
import React from 'react';
import type { Meta, StoryFn } from '@storybook/react';
import { MeuComponente } from './MeuComponente';

export default {
  title: 'Components/MeuComponente',
  component: MeuComponente,
  tags: ['autodocs'],
  parameters: {
    layout: 'centered',
    docs: {
      description: {
        component: `
Descrição do seu componente customizado baseado no Material UI.
        `,
      },
    },
  },
} as Meta<typeof MeuComponente>;

const Template: StoryFn<typeof MeuComponente> = (args) => <MeuComponente {...args} />;

export const Default = Template.bind({});
Default.args = {
  // Props padrão do componente
};

export const Variante = () => (
  <MeuComponente prop="valor">
    Exemplo de uso
  </MeuComponente>
);

5. Checklist de Criação

[ ] Componente TypeScript criado
[ ] Interface de props definida
[ ] Arquivo index.ts criado
[ ] Export adicionado ao index principal
[ ] Stories criadas (recomendado)
[ ] Teste no Storybook
[ ] Build do projeto executado sem erros

6. Validação

# Teste o build
npm run build

# Execute o Storybook
npm run storybook

# Verifique se não há erros de TypeScript
npm run build:types

📚 Storybook

O Storybook é nossa ferramenta de desenvolvimento e documentação. Para executá-lo:

npm run storybook

Acesse: http://localhost:6006

Criando Stories Efetivas

Default: Exemplo básico do componente
Variants: Diferentes variações visuais
States: Estados como erro, sucesso, disabled
Interactive: Exemplos com interações

🔧 Scripts Disponíveis

npm run build          # Compila o projeto
npm run build:types    # Gera apenas os tipos TypeScript
npm run clean          # Limpa a pasta dist
npm run dev            # Desenvolvimento com watch
npm run storybook      # Executa o Storybook
npm run build-storybook # Build estático do Storybook

🏗 Arquitetura do Projeto

rroc/
├── src/
│   ├── components/        # Componentes do design system
│   ├── theme.ts          # Configurações de tema
│   ├── ThemeProvider.tsx # Provider de tema
│   └── index.ts          # Export principal
├── dist/                 # Build compilado
├── .storybook/           # Configurações do Storybook
├── package.json
└── README.md

📄 Convenções de Código

Nomenclatura

Componentes: PascalCase (MeuComponente)
Props: PascalCase + Props (MeuComponenteProps)
Arquivos: PascalCase (MeuComponente.tsx)
Stories: PascalCase + .stories (MeuComponente.stories.tsx)

TypeScript

Sempre use interfaces para props
Exporte tipos quando necessário
Mantenha compatibilidade com props do Material UI

Organização

Um componente por arquivo
Index.ts para exports
Stories no mesmo diretório do componente

🎨 Customização

Todos os componentes podem ser customizados através:

Props nativas do Material UI
Sistema de temas do Material UI
Props customizadas (adicionadas à interface)

📖 Documentação Adicional

🚀 Publicação

# Build do projeto
npm run build

# Publish (apenas maintainers)
npm publish

GERAÇÃO DE PACOTE PARA DESENVOLVIMENTO LOCAL

Para facilitar o desenvolvimento e testes localmente, é possível gerar o pacote e fazer a instalação no projeto que irá utiliza-lo como dependência sem ter que baixar do npm. Basta seguir os seguintes passos:

# Build do projeto
npm run build

# Geração do tarball
npm pack

Após a geração do arquivo, basta adiciona-lo na raiz do projeto que irá consumi-lo e fazer a instalação com npm ou yarn:

yarn add file:./beetech-rroc-X.X.X.tgz

npm i file:./beetech-rroc-X.X.X.tgz

🎯 GERAÇÃO DE PACOTES NPM REGISTRY - PROCESSO COMPLETO

🚨 ATENÇÃO: Siga este processo para garantir que seus pacotes sejam construídos e publicados corretamente no NPM Registry

📋 Checklist Pré-Release

[ ] Node.js >= 20.0.0 ativado (nvm use 20)
[ ] Ambiente local funcionando (npm run build)
[ ] Branch main atualizada

🔄 Processo Step-by-Step

1️⃣ Preparação da Branch

# Certifique-se de estar na main e atualizada
git checkout main
git pull origin main

# Crie sua branch de feature
git checkout -b feat/seu-componente-ou-feature

2️⃣ Desenvolvimento

# 🛠 Faça suas modificações de código
# ✨ Crie seus componentes
# 📝 Atualize documentação
# 🧪 Teste no Storybook

# Validação local obrigatória
npm run build          # ✅ Build deve passar

3️⃣ Versionamento

🎯 OPÇÃO A - Automática (Recomendada):

# Para correções de bug
npm version patch      # 1.3.4 → 1.3.5

# Para novas features
npm version minor      # 1.3.4 → 1.4.0

# Para breaking changes
npm version major      # 1.3.4 → 2.0.0

🎯 OPÇÃO B - Manual (Não Recomendada):

# Criar tag manualmente
git tag -a v1.3.5 -m "Release v1.3.5"

# ⚠️ IMPORTANTE: Atualize package.json E package-lock.json manualmente
# Altere a versão nos dois arquivos para corresponder à tag

4️⃣ Commit e Push

# Commit suas alterações (inclua a mudança de versão se manual)
git add .
git commit -m "feat: adiciona novo componente XYZ

- Novo componente XYZ implementado
- Stories criadas para documentação  
- Versão atualizada para v1.3.5"

# Push da branch
git push origin feat/seu-componente-ou-feature

# Push da tag (CRÍTICO para trigger do Jenkins)
git push origin v1.3.5

Verifique sempre o PR no jenkins se esta buildando, ele ira garantir a build adequada da versão posterior Obrigatório: Validação PR - Jenkins Obrigatório: Validação TAG - Jenkins

⏰ Sincronização NPM Registry → Nexus

⚠️ IMPORTANTE: O NPM Registry e a disponibilidade no Nexus da empresa pode demorar alguns minutos. Se isso ocorrer, você pode forçar a sincronização:

🐳 Forçar Sincronização via Docker

⚠️ VPN PRECISA ESTAR LIGADA!!!

1️⃣ Inicie o Docker (deixe aberto em uma aba):

# Inicia container Node.js
docker run -it --rm node:iron-alpine ash

# Dentro do container:
mkdir app
cd app/
npm init

2️⃣ Em outra aba do terminal, force a instalação:

# Configure o registry para o Nexus da empresa
npm config set registry https://nexus.pesoreal.xyz/repository/npm-proxy/

# Instale o pacote (força a sincronização)
npm install @beetech/rroc

✅ Resultado esperado:

# Após a sincronização, o pacote estará disponível:
yarn add @beetech/[email protected]

🔍 Verificação no Nexus:

Interface Web: nexus.pesoreal.xyz
Busca: Procure por rroc para confirmar a disponibilidade
Tempo: Sincronização pode levar de 2-10 minutos

📞 Suporte

Para dúvidas ou problemas:

Abra uma Issue
Consulte a documentação do Material UI
Verifique os exemplos no Storybook

Feito com ❤️ pela equipe da Remessa Online