@govbr-ds/webcomponents-angular
Version:
Wrapper Angular para a biblioteca de Web Components do GovBR-DS.
322 lines (238 loc) • 10.8 kB
Markdown
# Wrapper Angular para @govbr-ds/webcomponents
<a id="readme-top"></a>
Este é um wrapper Angular que encapsula os [Web Components GovBR-DS](https://gov.br/ds/webcomponents), 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? 🤔
Utilizar o wrapper Angular para os Web Components GovBR-DS traz diversas vantagens:
- **Desacoplamento da Detecção de Mudanças**: Os wrappers de componentes Angular são independentes da detecção de mudanças, evitando repinturas desnecessárias dos seus componentes web.
- **Conversão de Eventos**: Os eventos dos componentes web são convertidos para observáveis RxJS, alinhando-se ao @Output() do Angular e não sendo emitidos através dos limites dos componentes.
- **Control Value Accessors**: Opcionalmente, os componentes web de controle de formulário podem ser utilizados como control value accessors com os formulários reativos do Angular ou `ngModel`.
> [!TIP]
> Para mais detalhes, consulte a [documentação oficial do Stencil](https://stenciljs.com/docs/angular).
<p align="right">
<a href="#readme-top">Voltar ao topo</a>
</p>
## Uso 📚
Para utilizar o wrapper Angular dos Web Components GovBR-DS em uma aplicação Angular, siga os passos abaixo:
### Instalação
Instale os pacotes a seguir:
```bash
npm install --save-dev @govbr-ds/{core,webcomponents,webcomponents-angular}
```
> [!NOTE]
> Certifique-se de que o pacote `@govbr-ds/webcomponents` está instalado.
<p align="right">
<a href="#readme-top">Voltar ao topo</a>
</p>
### Font Awesome e Fonte Rawline
Nossos componentes utilizam a [Fonte Rawline](https://www.cdnfonts.com/rawline.font/ 'Fonte Rawline') juntamente com a [Font Awesome](https://fontawesome.com/ 'Font Awesome') padrão do DS.
Ambas as fontes são essenciais para garantir a estética e a funcionalidade dos componentes. Consulte a documentação no site do [GovBR-DS](https://www.gov.br/ds/como-comecar/instalacao 'GovBR-DS') para mais detalhes sobre como importá-las de seus respectivos CDNs.
- **[Font Awesome](https://fontawesome.com/ 'Font Awesome')**: Uma biblioteca de ícones amplamente utilizada para adicionar ícones vetoriais e logotipos aos seus projetos. É fácil de integrar e personalizar.
- **[Fonte Rawline](https://www.cdnfonts.com/rawline.font/ 'Fonte Rawline')**: Uma fonte moderna e elegante usada para manter a identidade visual consistente com o Design System do GovBR-DS.
Consulte a documentação no site do [GovBR-DS](https://www.gov.br/ds/como-comecar/instalacao 'GovBR-DS') para mais detalhes sobre como importá-los de seus respectivos CDNs.
<p align="right">
<a href="#readme-top">Voltar ao topo</a>
</p>
### Passo-a-passo
```json
/** angular.json */
{
"$schema": "./node_modules/@angular/cli/lib/config/schema.json",
"version": 1,
"newProjectRoot": "projects",
"projects": {
"Angular-Project": {
...
"architect": {
"build": {
"builder": "@angular-devkit/build-angular:browser",
"options": {
...
"styles": [
...
"node_modules/@govbr-ds/core/dist/core-tokens.min.css"
],
...
}
}
}
}
}
```
Os estilos do `govbr-ds/core` também podem ser importados para o arquivo de estilo principal do seu aplicativo caso não deseje incluí-los no `angular.json`:
```css
@import '~@govbr-ds/core/dist/core-tokens.min.css';
```
<p align="right">
<a href="#readme-top">Voltar ao topo</a>
</p>
#### Angular com módulos
Adicione o `WebcomponentsAngularModule` exportado por `@govbr-ds/webcomponents-angular`:
```ts
/** app.module.ts */
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { WebcomponentsAngularModule } from '@govbr-ds/webcomponents-angular';
import { AppComponent } from './app.component';
...
@NgModule({
declarations: [AppComponent],
imports: [WebcomponentsAngularModule.forRoot(), BrowserModule, ...],
providers: [],
bootstrap: [AppComponent],
schemas: [],
...
})
export class AppModule {}
```
<p align="right">
<a href="#readme-top">Voltar ao topo</a>
</p>
#### Angular standalone
Você também pode usar nosso wrapper Angular no Angular standalone. Para isso, você precisará importar os componentes de `@govbr-ds/webcomponents-angular/standalone` e usá-los como usaria qualquer outro componente Angular.
```ts
/** Typescript do componente Angular */
import { Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { BrButton } from '@govbr-ds/webcomponents-angular/standalone';
...
@Component({
selector: 'app-component',
templateUrl: './app.component.html',
standalone: true,
imports: [BrButton],
})
export class AppComponent2 {}
```
```html
<!-- Template do componente Angular -->
<br-button emphasis="primary">Lorem ipsum</br-button>
```
<p align="right">
<a href="#readme-top">Voltar ao topo</a>
</p>
#### Uso com NgModel e binding
Para habilitar a vinculação bidirecional e o uso de `ngModel` dentro dos componentes de formulário, você precisará adicionar o `@angular/forms`. Também é necessário colocar o `ngDefaultControl` na tag dos componentes para ativar o `ngModel`.
> [!CAUTION]
> Pode ser necessário desativar `aot` para habilitar a vinculação bidirecional de dados. Mais informações: [https://github.com/ionic-team/stencil-ds-output-targets/issues/317](https://github.com/ionic-team/stencil-ds-output-targets/issues/317).
>
```ts
/** app.module.ts */
import { NgModule } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { BrowserModule } from '@angular/platform-browser';
import { WebcomponentsAngularModule } from '@govbr-ds/webcomponents-angular';
...
@NgModule({
declarations: [AppComponent],
imports: [WebcomponentsAngularModule.forRoot(), , BrowserModule, FormsModule, ...],
...
})
export class AppModule {}
```
```html
<!-- Template do componente Angular -->
<br-checkbox
name="userTermsConditions"
[(ngModel)]="termsConditions"
(checkedChange)="onTermsConditionsChange()"
ngDefaultControl
>
Concordo com os Termos e Condições
</br-checkbox>
```
```ts
/** Typescript do componente Angular */
import { Component } from '@angular/core'
@Component({
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: ['./app.component.scss'],
})
export class AppComponent {
termsConditions = true
onTermsConditionsChange() {
console.log('O valor dos termos e condições mudou!', this.termsConditions)
}
}
```
<p align="right">
<a href="#readme-top">Voltar ao topo</a>
</p>
## Desenvolvimento 👨💻
### Estrutura do projeto
```plaintext
├── 📁 src
├── 📁 stencil-generated
├── 📄 angular-webcomponents.module.ts
├── 📄 index.ts
├── 📁 standalone
├── 📁 src/
├── 📁 stencil-generated
├── 📄 index.ts
├── 📁 scripts
├── ...
```
- **src**: Contém os arquivos da biblioteca Angular com módulos.
- **stencil-generated**: Arquivos gerados automaticamente durante o build dos Web Components.
- **angular-webcomponents.module.ts**: Exporta os componentes, os registra como custom elements e exporta os Control Value Accessors.
- **index.ts**: Entry point para Angular com módulos.
- **standalone**: Contém os arquivos da biblioteca Angular standalone.
- **src/stencil-generated**: Arquivos gerados automaticamente durante o build dos Web Components.
- **src/index.ts**: Entry point para Angular standalone.
- **scripts**: Contém o script para corrigir um bug que ocorre algumas vezes ao gerar o build dos Web Components.
> [!WARNING]
> Todas as alterações nas pastas `stencil-generated` serão perdidas ao gerar um novo build dos Web Components.
<p align="right">
<a href="#readme-top">Voltar ao topo</a>
</p>
### Build
Antes de compilar a biblioteca Angular, é necessário gerar o build dos webcomponents:
```bash
nx build webcomponents
```
Em seguida, para gerar o build da biblioteca Angular, execute:
```bash
nx build angular
```
<p align="right">
<a href="#readme-top">Voltar ao topo</a>
</p>
## Documentações Complementares 📖
Consulte a seção sobre Web Componente na nossa [Wiki](https://gov.br/ds/wiki/desenvolvimento/web-components) para obter mais informações sobre esse projeto.
Para saber mais detalhes sobre a especificação Web Components sugerimos que consulte o [MDN](https://developer.mozilla.org/pt-BR/docs/Web/Web_Components 'Web Components | MDN').
<p align="right">
<a href="#readme-top">Voltar ao topo</a>
</p>
## Contribuindo 🤝
Antes de abrir um Merge Request, por favor, leve em consideração as seguintes informações:
- Este é um projeto open-source e contribuições são bem-vindas.
- Para facilitar a aprovação da sua contribuição, use um título claro e explicativo para o MR, e siga os padrões estabelecidos em nossa [wiki](https://gov.br/ds/wiki/ 'Wiki').
- Quer contribuir? Consulte o nosso guia [como contribuir](https://gov.br/ds/wiki/comunidade/contribuindo-com-o-ds/ 'Como contribuir?').
<p align="right">
<a href="#readme-top">Voltar ao topo</a>
</p>
## Reportar Bugs/Problemas ou Sugestões 🐛
Para reportar problemas ou sugerir melhorias, abra uma [issue](https://gitlab.com/govbr-ds/bibliotecas/wbc/govbr-ds-wbc/-/issues/new). Utilize o modelo adequado e forneça o máximo de detalhes possível.
Nos comprometemos a responder a todas as issues.
<p align="right">
<a href="#readme-top">Voltar ao topo</a>
</p>
## Commits 📝
Este projeto segue um padrão para branches e commits. Consulte a documentação na nossa [wiki](https://gov.br/ds/wiki/ 'Wiki') para aprender mais sobre esses padrões.
<p align="right">
<a href="#readme-top">Voltar ao topo</a>
</p>
## Precisa de ajuda? 🆘
Por favor, **não** crie issues para perguntas gerais.
Use os canais abaixo para tirar suas dúvidas:
- Site do GovBR-DS [http://gov.br/ds](http://gov.br/ds)
- Web Components [https://gov.br/ds/webcomponents](https://gov.br/ds/webcomponents)
- Canal no Discord [https://discord.gg/U5GwPfqhUP](https://discord.gg/U5GwPfqhUP)
<p align="right">
<a href="#readme-top">Voltar ao topo</a>
</p>
## Créditos 🎉
Os Web Components do [GovBR-DS](https://gov.br/ds/ 'GovBR-DS') foram desenvolvidos pelo [SERPRO](https://www.serpro.gov.br/ 'SERPRO | Serviço Federal de Processamento de Dados') em colaboração com a comunidade.
<p align="right">
<a href="#readme-top">Voltar ao topo</a>
</p>