npm package: @govbr-ds-testing/webcomponents
Description: Projeto de Web Components baseado no GovBR-DS
Author: SERPRO
Latest version: 1.23.5

# Web Components GovBR-DS

Biblioteca de Web Components do [GovBR-DS](https://gov.br/ds).

Esse projeto é desenvolvido usando (entre outras tecnologias) o [Stencil](https://stenciljs.com/ 'Stencil').

## Demonstração

Acesse nossos sites e veja nossos componentes em ação:

- [Produção](https://gov.br/ds/webcomponents/)
- [Desenvolvimento](https://govbr-ds.gitlab.io/bibliotecas/wc/)

## Objetivo

Disponibilizar uma biblioteca de componentes baseada no [GovBR-DS](https://gov.br/ds 'GovBR-DS') que possa ser consumida independente de frameworks ou tecnologias utilizadas.

## Bibliotecas de integração/wrappers

A integração entre Web Components e frameworks pode não ser fácil em determinadas situações. Por isso nós criamos as bibliotecas de integração (wrappers). Basicamente eles encapsulam os Web Components em uma biblioteca de componentes na tecnologia nativa de alguns frameworks. Isso facilita a integração com funcionalidades nativas dos frameworks, como binding por exemplo.

Para mais detalhes sobre como o Stencil faz a integração consulte [a documentação do Stencil sobre integrações](https://stenciljs.com/docs/overview).

Note que determinadas situações pode não ser possível fazer essa integração. Isso depende muito da evolução da especificação de Web Components e do suporte dos frameworks.

## Font Awesome e Fonte Rawline

Nossos componentes usam 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.

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.

## Instalação

- Pacote NPM

```bash
npm install --save @govbr-ds/webcomponents
```

Depois de instalada, importe a biblioteca de dentro da pasta *node_modules*:

```javascript
@import "node_modules/@govbr-ds/webcomponents/dist/loader"
```

- CDN (não mantidos por nossa equipe)

```html
<script src="https://unpkg.com/@govbr-ds/webcomponents@<VERSÃO>/loader/index.js"></script>

ou

<script src="https://cdn.jsdelivr.net/npm/@govbr-ds/webcomponents@<VERSÃO>/loader/index.js"></script>

```

**Importante**: Dependendo do seu projeto pode ser necessário importar diretamente o arquivo `/dist/webcomponents/webcomponents.esm.js`. Observe as necessidades do seu projeto e importe os arquivos de acordo.

## VSCODE

Ao criar nossos Web Components fazemos uso de custom elements. O VSCODE não conhece os componentes e por isso não consegue fazer sugestões inteligentes para usar no autocomplete. Para auxiliar com isso nós geramos um arquivo `vscode-data.json` com as definições dos componentes e disponibilizamos junto com o nosso pacote npm.

Para importar no seu VSCODE, adicione o campo abaixo alterando o local onde o seu projeto armazena o `node_modules`.

```json
{
  "html.customData": [
    "./node_modules/@govbr-ds/webcomponents/vscode-data.json"
  ]
}
```

### Exemplos de uso

Disponibilizamos alguns exemplos de como usar esse projeto com algumas tecnologias. Consulte o [nosso grupo aqui no gitlab](https://gitlab.com/govbr-ds/bibliotecas/wc 'GovBR-DS/WC') e procure pelos projetos de 'Quickstart' para mais detalhes.

## Estrutura de pastas

Explicamos apenas as pastas/arquivos que são importantes para o entendimento do projeto e contribuição.

```markdown
/raiz
│───src
│ │───assets
│ │───components
│ │───pages
│ └───utils
│ └───components.d.ts
│ └───index.html
│ └───index.ts
└───scripts
```

- **src**
  - **assets**: pasta com arquivos estáticos
  - **components**: pasta com os componentes da biblioteca, seus testes e documentação gerada automaticamente.
  - **pages**: arquivos de exemplos usados no desenvolvimento local e no site.
  - **utils**: funções que são usados em vários componentes.
  - **components.d.ts**: arquivo gerado pelo stencil com os tipos dos parâmetros dos componentes.
  - **index.html**: arquivo inicial do ambiente de desenvolvimento.
  - **index.ts**: arquivo gerado pelo stencil que exporta todos os componentes.
- **scripts**: scripts usados durante alguma parte do fluxo do projeto

## Testar os componentes no localhost

De criar os componentes na pasta `src/components/`, crie as páginas de exemplos no `src/pages`. Essas páginas vão ser usadas também no site do docusaurus!

Depois de criar os exemplos inclua os arquivos e componentes criados no local correto no arquivo `src/index.html`.

Agora para rodar o projeto e testar os componentes, execute `npx nx run @govbr-ds/webcomponents:dev`. Isso vai iniciar o servidor de desenvolvimento exclusivo do projeto de Web Components.

## 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').

### Polyfill

Acesse os seguintes links para entender mais sobre o suporte dos browsers a [Custom Elements](https://caniuse.com/custom-elementsv1) e a [Shadow Dom](https://caniuse.com/shadowdomv1).

Caso os requisitos do seu projeto incluam navegadores que não suportam completamente os Web Components, adicione os [polyfills](https://www.webcomponents.org/polyfills) ao seu projeto.

Para aprender com instalar, consulte a [documentação oficial](https://github.com/webcomponents/polyfills/tree/master/packages/webcomponentsjs 'Polyfills')

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