# Guia de Contribuição

Obrigado por considerar contribuir com `@seniorsistemas/components-ai`! 🎉

## 📋 Índice

- [Código de Conduta](#código-de-conduta)
- [Como Contribuir](#como-contribuir)
- [Padrões de Código](#padrões-de-código)
- [Processo de Pull Request](#processo-de-pull-request)
- [Estrutura do Projeto](#estrutura-do-projeto)

---

## 📜 Código de Conduta

Este projeto adere a um código de conduta. Ao participar, você concorda em manter um ambiente respeitoso e colaborativo.

---

## 🤝 Como Contribuir

### Reportar Bugs

Se encontrar um bug, por favor abra uma issue com:

- Descrição clara do problema
- Passos para reproduzir
- Comportamento esperado vs atual
- Versão da biblioteca e Angular
- Screenshots (se aplicável)

### Sugerir Melhorias

Para sugerir novas funcionalidades:

- Descreva o caso de uso
- Explique por que seria útil
- Forneça exemplos de uso
- Considere alternativas

### Contribuir com Código

1. **Fork o repositório**
2. **Clone seu fork**
   ```bash
   git clone https://github.com/seu-usuario/components-ai.git
   ```
3. **Crie uma branch**
   ```bash
   git checkout -b feature/minha-feature
   ```
4. **Faça suas alterações**
5. **Commit suas mudanças**
   ```bash
   git commit -m "feat: adiciona nova funcionalidade"
   ```
6. **Push para o GitHub**
   ```bash
   git push origin feature/minha-feature
   ```
7. **Abra um Pull Request**

---

## 💻 Padrões de Código

### Convenções de Nomenclatura

- **Componentes**: PascalCase (ex: `DynamicFormComponent`)
- **Serviços**: PascalCase com sufixo Service (ex: `EntityService`)
- **Interfaces**: PascalCase (ex: `DynamicFormFieldConfig`)
- **Enums**: PascalCase (ex: `FieldType`)
- **Variáveis**: camelCase (ex: `formFields`)
- **Constantes**: UPPER_SNAKE_CASE (ex: `DEFAULT_PAGE_SIZE`)

### Estrutura de Arquivos

```
component-name/
├── component-name.component.ts
├── component-name.component.html
├── component-name.component.scss
├── component-name.component.spec.ts
└── README.md (opcional)
```

### TypeScript

- Use tipos explícitos sempre que possível
- Evite `any` (use `unknown` se necessário)
- Use interfaces para objetos complexos
- Documente funções públicas com JSDoc

```typescript
/**
 * Cria um novo registro
 * @param entity - Dados da entidade
 * @returns Observable com a entidade criada
 */
insert(entity: Partial<T>): Observable<T> {
  return this.http.post<T>(this.apiUrl, entity);
}
```

### HTML/Templates

- Use formatação consistente
- Prefira `*ngIf` e `*ngFor` ao invés de `ng-template`
- Use `trackBy` em `*ngFor` para performance
- Mantenha templates simples (lógica no component)

### SCSS

- Use variáveis para cores e espaçamentos
- Siga a metodologia BEM quando apropriado
- Evite seletores profundos
- Use mixins para código reutilizável

### Commits

Siga o padrão [Conventional Commits](https://www.conventionalcommits.org/):

```
<tipo>(<escopo>): <descrição>

[corpo opcional]

[rodapé opcional]
```

**Tipos:**
- `feat`: Nova funcionalidade
- `fix`: Correção de bug
- `docs`: Documentação
- `style`: Formatação (não afeta código)
- `refactor`: Refatoração
- `test`: Testes
- `chore`: Manutenção

**Exemplos:**
```
feat(dynamic-form): adiciona suporte a validação assíncrona
fix(export-dialog): corrige exportação de datas
docs(readme): atualiza exemplos de uso
refactor(entity-service): melhora tipagem genérica
test(breadcrumb): adiciona testes unitários
```

---

## 🔄 Processo de Pull Request

### Checklist

Antes de submeter um PR, verifique:

- [ ] Código segue os padrões do projeto
- [ ] Testes foram adicionados/atualizados
- [ ] Documentação foi atualizada
- [ ] Build passa sem erros
- [ ] Testes passam
- [ ] Commit messages seguem o padrão
- [ ] Branch está atualizada com main

### Revisão

- PRs serão revisados por mantenedores
- Feedback será fornecido via comentários
- Mudanças podem ser solicitadas
- Após aprovação, o PR será merged

### Após o Merge

- Sua contribuição será incluída no próximo release
- Você será creditado no CHANGELOG
- Obrigado pela contribuição! 🎉

---

## 📁 Estrutura do Projeto

```
components-ai/
├── projects/
│   └── seniorsistemas/
│       └── components-ai/
│           ├── src/
│           │   ├── lib/
│           │   │   ├── components/     # Componentes
│           │   │   ├── services/       # Serviços
│           │   │   ├── directives/     # Diretivas
│           │   │   ├── pipes/          # Pipes
│           │   │   ├── models/         # Interfaces/Types
│           │   │   ├── interceptors/   # Interceptors
│           │   │   ├── config/         # Configurações
│           │   │   └── styles/         # Estilos globais
│           │   └── public-api.ts       # API pública
│           ├── docs/                   # Documentação
│           ├── package.json
│           ├── README.md
│           ├── CHANGELOG.md
│           └── CONTRIBUTING.md
├── angular.json
├── package.json
└── tsconfig.json
```

---

## 🧪 Testes

### Executar Testes

```bash
npm run test
```

### Cobertura

```bash
npm run test:coverage
```

### Escrever Testes

- Teste comportamento, não implementação
- Use mocks para dependências
- Teste casos de sucesso e erro
- Mantenha testes simples e legíveis

```typescript
describe('DynamicFormComponent', () => {
  it('should create form with fields', () => {
    const fields: DynamicFormFieldConfig[] = [
      { name: 'name', label: 'Nome', type: FieldType.TEXT, cols: 12 }
    ];
    component.formFields = fields;
    component.ngOnInit();
    expect(component.getForm().get('name')).toBeDefined();
  });
});
```

---

## 📖 Documentação

### Atualizar Documentação

Ao adicionar/modificar funcionalidades:

1. Atualize `docs/COMPONENTS.md`
2. Adicione exemplos em `docs/EXAMPLES.md`
3. Atualize `docs/API.md` se necessário
4. Atualize `CHANGELOG.md`
5. Atualize `README.md` se relevante

### Escrever Documentação

- Use linguagem clara e objetiva
- Forneça exemplos práticos
- Inclua casos de uso comuns
- Documente parâmetros e retornos
- Adicione screenshots quando útil

---

## 🚀 Build e Publicação

### Build Local

```bash
npm run build
```

### Testar Localmente

```bash
# Na biblioteca
cd dist/seniorsistemas/components-ai
npm link

# No projeto de teste
npm link @seniorsistemas/components-ai
```

### Publicação

Apenas mantenedores podem publicar:

```bash
npm run build:prod
cd dist/seniorsistemas/components-ai
npm publish
```

---

## 💡 Dicas

- Comece com issues marcadas como `good first issue`
- Pergunte se tiver dúvidas
- Mantenha PRs focados e pequenos
- Seja paciente durante a revisão
- Aprenda com o feedback

---

## 📞 Contato

- Issues: [GitHub Issues](https://github.com/senior-sistemas/components-ai/issues)
- Discussões: [GitHub Discussions](https://github.com/senior-sistemas/components-ai/discussions)

---

Obrigado por contribuir! 🙏
