Angular – @govbr-ds/webcomponents-angular

Este é um wrapper Angular que encapsula os Web Components GovBR-DS, habilita NG_VALUE_ACCESSORS e permite a vinculação de eventos de entrada diretamente a um value accessor, proporcionando uma integração perfeita no fluxo de dados bidirecional do Angular.

Por que usar este wrapper? 🤔

• Desacoplamento da detecção de mudanças dos elementos Web.
• Conversão de eventos para observáveis RxJS, alinhado ao @Output().
• Control Value Accessors para integração com Reactive Forms e ngModel.

[!TIP] Para mais detalhes, consulte a documentação oficial do Stencil.

Instalação 📦

Instale os pacotes necessários como dependências de produção:

npm install @govbr-ds/core @govbr-ds/webcomponents @govbr-ds/webcomponents-angular
# ou
pnpm add @govbr-ds/core @govbr-ds/webcomponents @govbr-ds/webcomponents-angular
# ou
yarn add @govbr-ds/core @govbr-ds/webcomponents @govbr-ds/webcomponents-angular

[!NOTE] Certifique-se de incluir os estilos do @govbr-ds/core.

Nota importante: pnpm e tree-shaking

Se ao consumir estes pacotes você notar que o bundler não está removendo código não utilizado (tree‑shaking), pode haver uma incompatibilidade com o layout padrão do pnpm.

Solução rápida (opcional, somente se precisar): crie um arquivo .npmrc na raiz do seu projeto com:

node-linker=hoisted

Por que isso ajuda: por padrão, o pnpm organiza as dependências em pastas isoladas com symlinks. Alguns bundlers/otimizadores se baseiam na estrutura de node_modules e no campo sideEffects para decidir o que pode ser eliminado. O layout hoisted aproxima o formato “achatado” (similar ao npm/yarn), facilitando essa análise e, em muitos casos, restaurando o tree‑shaking.

Observações:

• Use apenas se o tree‑shaking realmente não estiver funcionando.
• Pode aumentar o uso de disco e alterar a resolução de dependências do seu projeto.

Uso 📚

Fontes e ícones

Inclua os estilos-base no Angular (via angular.json ou CSS global):

// angular.json (trecho)
{
  "projects": {
    "app": {
      "architect": {
        "build": {
          "options": {
            "styles": ["node_modules/@govbr-ds/core/dist/core-tokens.min.css"]
          }
        }
      }
    }
  }
}

Ou importe no seu stylesheet global:

@import '~@govbr-ds/core/dist/core-tokens.min.css';

Angular com módulos

// app.module.ts
import { NgModule } from '@angular/core'
import { BrowserModule } from '@angular/platform-browser'
import { FormsModule } from '@angular/forms'
import { WebcomponentsAngularModule } from '@govbr-ds/webcomponents-angular'
import { AppComponent } from './app.component'

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, FormsModule, WebcomponentsAngularModule.forRoot()],
  bootstrap: [AppComponent],
})
export class AppModule {}

Angular standalone

// app.component.ts
import { Component } from '@angular/core'
import { BrButton } from '@govbr-ds/webcomponents-angular/standalone'

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  standalone: true,
  imports: [BrButton],
})
export class AppComponent {}

<!-- app.component.html -->
<br-button emphasis="primary">Lorem ipsum</br-button>

Uso com NgModel e binding

Para habilitar ngModel e 2-way binding, adicione FormsModule e o atributo ngDefaultControl no componente de formulário.

[!CAUTION] Em algumas versões pode ser necessário desativar aot. Veja: issue #317

<br-checkbox
  name="userTermsConditions"
  [(ngModel)]="termsConditions"
  (checkedChange)="onTermsConditionsChange()"
  ngDefaultControl
>
  Concordo com os Termos e Condições
</br-checkbox>

// app.component.ts
import { Component } from '@angular/core'

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
  termsConditions = true
  onTermsConditionsChange() {
    console.log('O valor mudou!', this.termsConditions)
  }
}

Desenvolvimento 👨‍💻

Estrutura do projeto

├── 📁 src
│   ├── 📁 stencil-generated
│   ├── 📄 angular-webcomponents.module.ts
│   └── 📄 index.ts
├── 📁 standalone
│   └── 📁 src
│       ├── 📁 stencil-generated
│       └── 📄 index.ts
└── 📁 scripts

[!WARNING] Tudo dentro de stencil-generated é sobrescrito ao gerar o build de Web Components.

Scripts/Build

Gere os Web Components antes de compilar o wrapper:

nx build webcomponents
nx build angular

Documentações Complementares 📖

• Wiki: gov.br/ds/wiki/desenvolvimento/web-components
• MDN Web Components: developer.mozilla.org/Web_Components

Contribuindo 🤝

• Siga os padrões descritos na nossa wiki.
• Guia: como contribuir.

Reportar Bugs/Problemas 🐛

Abra uma issue: gitlab.com/.../issues/new

Commits 📝

Padrões de branches e commits: gov.br/ds/wiki

Precisa de ajuda? 🆘

• Site: gov.br/ds
• Web Components: gov.br/ds/webcomponents
• Discord: discord.gg/U5GwPfqhUP

Créditos 🎉

Desenvolvido pelo SERPRO com a comunidade.