npm package: @govbr-ds-testing/webcomponents-vue
Description: Biblioteca de integração dos Web Components GovBR-DS com o Vue
Author: SERPRO
Latest version: 1.23.5

# Webcomponents Vue

Bibiloteca de componentes vue que encapsulam os [Web Components GovBR-DS](https://gov.br/ds/webcomponents).

## Instalação

Instale os pacotes abaixo:

```bash
npm install --save-dev @govbr-ds/core @govbr-ds-testing/webcomponents @govbr-ds-testing/webcomponents-vue
```

## Uso

<!-- ADD: adicionar "como" importar componentes separados -->

Inclua no `main.ts` (ou arquivo equivalente) da sua aplicação:

```typescript
import { ComponentLibrary } from '@govbr-ds-testing/webcomponents-vue'

import '@govbr-ds/core/dist/core.min.css'
```

O `core.min.css` é quem define os valores dos tokens de CSS usados.

## Estrutura de pastas e arquivos

```markdown
- vue
  - lib
    - stencil-generated
    - index.ts
    - plugin.ts
```

Ao gerar um build da biblioteca te Web Components os arquivos da pasta `lib/stencil-generated` são deletados e recriados. **Todas as alterações nesses arquivos vão ser perdidas ao gerar um novo build dos Web Components.**

O Arquivo `plugin.ts` registra os componentes como custom elements.

O Arquivo `index.ts` é o entry point da biblioteca e exporta os componentes.

## Build

Rode o comando `npm run build`.

## Configuração do Projeto Vue

Para utilizar a biblioteca em Stencil criada para o [GovBR-DS](https://www.gov.br/ds), é necessário que se tenha um novo projeto Vue previamente configurado. Se ainda não o tiver instalado, siga estes passos para criar um projeto Vue e configurá-lo para utilizar os componentes:

- **Criar um Projeto Vue**: Primeiramente, crie um novo projeto Vue utilizando o Vue CLI ou outro método de sua preferência. Por exemplo:

```terminal
vue create meu-projeto
```

- **Baixar Pacotes Necessários**: Após criar o projeto, instale os pacotes necessários, incluindo os componentes do Padrão Digital de Governo.

```terminal
npm install @govbr-ds-testing/webcomponents-vue @govbr-ds/core
```

- **Configurar o Arquivo main.js**: No arquivo main.js do seu projeto Vue, configure o uso dos componentes e do roteador, se necessário. Exemplo de arquivo main.js:

```terminal
import { ComponentLibrary } from '@govbr-ds-testing/webcomponents-vue';
import '@govbr-ds/core/dist/core.min.css';
import { createApp } from 'vue';
import App from './App.vue';
import router from './router';

const app = createApp(App);
app.use(router); // Se estiver utilizando roteador
app.use(ComponentLibrary);
app.mount('#app');
```

Com esses passos, seu projeto Vue estará configurado para utilizar os componentes do Padrão Digital de Governo.

É importante notar que as dependências estão sendo gerenciadas através do sistema de módulos do JavaScript. Se ainda estiver com dificuldade para aplicar os estilos, incluía no arquivo index.html algumas referências a bibliotecas externas e estilos adicionais, que incluem o GovBR-DS, o Google Fonts e o Font Awesome, verificando sempre se ocorre redundâncias e conflitos entre as importações no arquivo main.js e os scripts e folhas de estilo incluídos no index.html:

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <!-- Inclusão de estilos adicionais e bibliotecas externas -->
    <link rel="stylesheet" href="https://cdngovbr-ds.estaleiro.serpro.gov.br/design-system/fonts/rawline/css/rawline.css" />
    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Raleway:300,400,500,600,700,800,900&amp;display=swap" />
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/all.min.css" />
  </head>
  <body>
    <div id="app"></div>
    <!-- Importação do arquivo main.js -->
    <script type="module" src="/src/main.js"></script>
  </body>
</html>
```

## Geração de componente

Para gerar um componente no seu projeto Vue, vamos utilizar como exemplo o componente Input do GovBR-DS, seguindo o mesmo entendimento nos demais componentes.

### Passo 1: Tags do componente

Você pode usar as tags do componente diretamente no template. Por exemplo:

```html
<template>
  <div>
    <br-input></br-input>
  </div>
</template>
```

### Passo 2: Propriedades do componente

Cada componente possui várias propriedades que podem ser utilizadas para personalizar sua aparência e comportamento. A documentação de cada componente deve ser consultada para obtenção de maiores informações. É importante destacar que as propriedades padrão do HTML podem ser utilizadas da mesma forma que em um input HTML comum. Por exemplo, as propriedades id, name, value, disabled, required, entre outras, podem ser aplicadas diretamente à tag do componente `br-input`. Veja um exemplo:

```html
<template>
  <div>
    <br-input id="nome" name="nome" disabled required density="large" label="Nome"></br-input>
  </div>
</template>
```

Neste exemplo, além das propriedades HTML comum, foi definido as propriedades density (densidade do input, podendo ser "small" ou "large") e label(geração automática do label para o input).

### Passo 3: Bind de Dados

Utilizando `:` (sintaxe de bind), você pode passar dinamicamente o valor de uma variável para a propriedade do componente e uma variável no seu componente Vue. Por exemplo:

```html
<br-input name="name" :label="textLabel" placeholder="Digite algo"></br-input>
```

No componente Vue:

```javascript
data() {
  return {
    textLabel: "Texto do label"
  };
}
```

### Passo 4: Utilizar Eventos Customizados

Você pode ouvir eventos customizados emitidos pelo componente br-input usando a diretiva @, seguida pelo nome do evento. Por exemplo, você está ouvindo o evento input no exemplo fornecido:

```html
<br-input @input="handleInputChange" label="Label" placeholder="Digite algo"></br-input>
```

No componente Vue:

```javascript
methods: {
  handleInputChange(newValue) {
    this.inputValue = newValue.target.value;
  },
}
```

### Passo 5: Personalizar Estilos

É importante observar que os componentes utilizam Shadow DOM para encapsular seu estilo e comportamento. Isso significa que os estilos não podem ser facilmente modificados diretamente a partir do componente pai.

No entanto, você ainda pode personalizar alguns aspectos do estilo utilizando CSS personalizado dentro do escopo do componente pai. Isso pode ser feito definindo classes personalizadas ou utilizando estilos embutidos diretamente no componente pai.

## Reportar bugs/necessidades

Você pode usar as [issues](https://gitlab.com/govbr-ds/bibliotecas/wc/-/issues/new) para nos informar os problemas que tem enfrentado ao usar nossa biblioteca ou mesmo o que gostaria que fizesse parte do projeto. Por favor use o modelo que mais se encaixa na sua necessidade e preencha com o máximo de detalhes possível.

Nos comprometemos a responder a todas as issues.

## Commits

Nesse projeto usamos um padrão para branches e commits. Por favor observe a documentação na nossa [wiki](https://gov.br/ds/wiki/ 'Wiki') para aprender sobre os nossos padrões.

## Precisa de ajuda?

Por favor **não** crie issues para fazer perguntas.

Use nossos canais abaixo para obter 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)
- Usando nosso canal no discord [https://discord.gg/U5GwPfqhUP](https://discord.gg/U5GwPfqhUP)

## Créditos

Os Web Components do [GovBR-DS](https://gov.br/ds/ 'GovBR-DS') são criados pelo [SERPRO](https://www.serpro.gov.br/ 'SERPRO | Serviço Federal de Processamento de Dados') juntamente com a comunidade.

## Licença

Nesse projeto usamos a licença MIT.