Ir para o conteúdo principal

Contribuindo

Os guias sobre como contribuir para o GOVBR-DS podem ser encontrados na nossa Wiki.

Primeiros passos​

Requisitos​

  • Node.js 22.x
  • pnpm 11.3.0
  • Git 2.x

Configuração do ambiente​

# Clone o repositório
git clone https://gitlab.com/govbr-ds/bibliotecas/wbc/govbr-ds-wbc.git
cd govbr-ds-wbc

# Instale as dependências
pnpm install

# Inicie o dev server dos web components
pnpm exec nx run webcomponents:start

# Em outro terminal, inicie o site de documentação
pnpm exec nx run site:start

O comando curto pnpm dev inicia a bancada local dos Web Components em http://localhost:8001. Ela inclui exemplos por componente e um inspetor de eventos nativos e customizados.

Criando um novo componente​

Use o gerador Plop para criar a estrutura base:

pnpm plop

O gerador cria automaticamente:

  • <component>.tsx — Componente StencilJS
  • <component>.scss — Estilos do componente
  • _tests/<component>.e2e.ts — Testes E2E
  • sections/migrate.md — Guia de migração

Executando testes​

# Testes E2E
pnpm exec nx run webcomponents:tests

# Um componente ou arquivo específico
pnpm test:component src/components/button/_tests/button.e2e.tsx

# Lint com Biome
pnpm exec nx run webcomponents:lint:biome

Os testes usam render() e userEvent. Para captura visual, viewport e consultas que atravessam múltiplos Shadow DOMs, use createBrowserTestFixture(), a fachada tipada compartilhada.

Checklist de code review​

Antes de submeter um MR, verifique:

  • O componente compila sem erros (nx build webcomponents)
  • Os testes E2E passam
  • JSDoc está presente em todos os @Prop, @State, @Event e @Method
  • Slots estão documentados com @slot no cabeçalho JSDoc do componente
  • IDs únicos usam Helpers.generateUniqueId('br-<nome>')
  • Tipos compartilhados estão em global.types.ts
  • Tipos locais estão em <component>.types.ts
  • Acessibilidade: roles, aria-*, navegação por teclado e foco estão implementados
  • formAssociated: true só é usado em componentes de formulário
  • Nomes de eventos seguem o padrão com prefixo br (ex.: brChange, brDidOpen)
  • Convenções de nomenclatura estão corretas (PascalCase para classes, camelCase para props)

Consulte também os Padrões do projeto.

Estrutura de branches​

  • next — Branch principal de desenvolvimento
  • main — Branch de produção
  • feature/<nome> — Features novas
  • fix/<nome> — Correções de bugs
  • chore/<nome> — Tarefas de manutenção

Recursos úteis​