# 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>