Contribuindo

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

Primeiros passos

O ciclo recomendado é: definir propósito e composição, gerar a base, implementar o comportamento, ajustar o exemplo, testar, documentar e validar os consumidores afetados. Use a anatomia do componente como roteiro. Quem só integra a biblioteca pode começar pela instalação no site, sem preparar o monorepo inteiro.

Requisitos

• Node.js e pnpm nas versões declaradas em package.json (engines e packageManager); mise install aplica as versões de mise.toml
• Git

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 a partir do lockfile
pnpm install --frozen-lockfile

# Confira versões, dependências, navegador e presença do bundle
pnpm preflight

# Instale os browsers necessários aos testes E2E (uma vez por ambiente)
pnpm browsers:install

# Inicie o site de documentação; antes, o Nx gera uma vez a documentação
# (`webcomponents:build:docs`) e o `www` (`webcomponents:build:www`) usados
# pelo Playground, sem subir o dev server dos web components
pnpm start:site

Para trabalhar só nos Web Components, sem o site, use pnpm start (ou pnpm start:webcomponents) em vez do comando acima. Ele inicia a bancada local em http://localhost:8001, com exemplos por componente e um inspetor de eventos nativos e customizados.

Jornadas e comandos do monorepo

pnpm test:component <nome> e pnpm test:watch <nome> usam www. Mantenha o watch ativo e aguarde a recompilação. pnpm tests usa dist; a seleção pode ser alterada explicitamente com WBC_TEST_BUNDLE=dist|www|coverage. Não há build automático nem fallback. pnpm test:changed inclui arquivos novos e alterações staged; mudanças compartilhadas selecionam a suíte completa, e falha do Git é um erro.

• Feedback rápido antes de revisão: use pnpm lint, pnpm typecheck e pnpm test:contract.
• Validação de empacotamento e wrappers: use pnpm build e pnpm pack.
• Comandos que alteram arquivos intencionalmente: use pnpm lint:fix e pnpm generate somente quando as alterações nos arquivos derivados forem desejadas.
• Consulte a matriz completa de comandos e arquitetura na documentação do repositório e os jobs de CI em .gitlab-ci.yml.

Criando um novo componente

Use o gerador Plop para criar a estrutura base:

pnpm plop

Informe nome em kebab-case, propósito e papel na composição. O gerador recusa colisões e caminhos externos antes de escrever arquivos. Tipos específicos só devem ser adicionados quando necessários; o SCSS importa o Core apenas quando há um arquivo correspondente.

O gerador cria automaticamente:

• <component>.tsx — Componente StencilJS
• <component>.figma.ts — Template Figma Code Connect com saída HTML
• <component>.scss — Estilos do componente
• _tests/<component>.e2e.tsx — Testes E2E
• sections/migrate.md — Guia de migração

Para componentes que já têm um equivalente visual no Design System, preencha o placeholder correspondente em figma.config.json com a URL oficial da instância Figma. Valide a cobertura sem publicar:

pnpm figma:validate:structure
pnpm figma:parse

O fluxo completo, incluindo token protegido, preview, labels de canal e o job pós-release independente, está no guia de Figma Code Connect.

Bundle usado nos testes

pnpm test:component button usa explicitamente a bancada (www). Aguarde a compilação de pnpm dev concluir antes de rodar o teste. Para testar a distribuição, execute o build deliberadamente e selecione a saída:

pnpm build:webcomponents
WBC_TEST_BUNDLE=dist pnpm test:component button

pnpm tests e o target de plataforma usam dist por padrão e não executam build automaticamente. Todos anunciam a saída utilizada e falham se ela não existir, sem tentar outra saída. A existência do bundle não comprova que ele acompanha alterações posteriores nas fontes.

pnpm clean executa git clean -fdx e remove todo arquivo não versionado pelo git, incluindo node_modules, .env, saídas de build e diretórios tasks. Simule antes com git clean -fdxn.

Executando testes

Loop rápido (recomendado no dia a dia)

Mantenha pnpm dev rodando num terminal — ele recompila a bancada a cada save e os testes reaproveitam esse bundle, sem passar pelo build do Nx:

# 1 componente por nome (rápido; ~2–3 s)
pnpm test:component button

# modo watch, re-roda a cada save
pnpm test:watch button

# só os componentes com diff (staged/unstaged/untracked)
pnpm test:changed

Sem um pnpm dev ativo, faça um pnpm build:webcomponents uma vez. Os atalhos acima chamam o Vitest direto em packages/webcomponents (ver scripts/dev/test-components.mjs).

No VS Code: task "Test: componente atual" (padrão de teste) e as configs de Run and Debug (.vscode/launch.json) para rodar o E2E do arquivo aberto com o navegador visível e breakpoints.

Suíte completa

# Todos os E2E (dispara o build do Nx antes)
pnpm tests

# Matriz Chromium/Firefox/WebKit
pnpm exec nx run webcomponents:test:platform

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

Os testes usam Vitest com @stencil/vitest, render(), userEvent e helpers de estabilidade. Para captura visual, viewport e consultas que atravessam múltiplos Shadow DOMs, use queryPiercing ou o fixture local já adotado pelo componente; não há um fixture compartilhado para essa composição.

Checklist de code review

Antes de submeter um MR, verifique:

• O teste direcionado do componente passa; build só é executado quando o tipo de mudança exigir ou quando estiver autorizado
• 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 packages/webcomponents/src/shared/utils/id.ts (ou a fachada compatível Helpers.generateUniqueId)
• 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
• Eventos nativos foram considerados antes dos customizados; eventos novos seguem br<ComponentName><Action> e eventos legados foram preservados
• Convenções de nomenclatura estão corretas (PascalCase para classes, camelCase para props)
• .github/review-checklists/component-api.md e, quando aplicável, state-events.md foram aplicados
• pnpm figma:validate:structure e pnpm figma:parse passam quando o componente possui representação visual e a mudança alcança Code Connect

Consulte também AI-CONTEXT.md, DECISIONS.md, as instruções em .github/instructions/ e os checklists em .github/review-checklists/ e .review-checklists/.

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

Referenciar discussões do Discord

Quando uma alteração responder a uma mensagem da comunidade, registre o link completo no corpo do commit ou na seção correspondente da descrição do MR:

fix(input): corrige foco ao clicar no label

Discord-Ref: https://discord.com/channels/111111/222222/333333

Use uma linha Discord-Ref por mensagem relacionada. O processo de release lê tanto os commits quanto a descrição do MR, portanto a referência é preservada mesmo quando o merge usa squash. Não inclua a referência no título do Conventional Commit.

O comando abaixo mostra as referências encontradas desde a última tag sem enviar mensagens ao Discord:

pnpm discord:refs -- --version <versão>

Recursos úteis

• Design System GovBR
• Documentação StencilJS
• Discord da comunidade