Web Components GovBR-DS

Biblioteca de Web Components do GovBR-DS.

Esse projeto é desenvolvido usando (entre outras tecnologias) o Stencil.

Demonstração

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

• Produção
• Desenvolvimento

Objetivo

Disponibilizar uma biblioteca de componentes baseada no 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.

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 juntamente com a Font Awesome padrão do DS.

Consulte a documentação no site do GovBR-DS para mais detalhes sobre como importá-los de seus respectivos CDNs.

Instalação

• Pacote NPM

npm install --save @govbr-ds/webcomponents

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

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

• CDN (não mantidos por nossa equipe)

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

{
  "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 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.

/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 para obter mais informações sobre esse projeto.

Para saber mais detalhes sobre a especificação Web Components sugerimos que consulte o MDN.

Polyfill

Acesse os seguintes links para entender mais sobre o suporte dos browsers a Custom Elements e a Shadow Dom.

Caso os requisitos do seu projeto incluam navegadores que não suportam completamente os Web Components, adicione os polyfills ao seu projeto.

Para aprender com instalar, consulte a documentação oficial

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
• Web Components https://gov.br/ds/webcomponents
• Usando nosso canal no discord https://discord.gg/U5GwPfqhUP

Créditos

Os Web Components do GovBR-DS são criados pelo SERPRO juntamente com a comunidade.

Licença

Nesse projeto usamos a licença MIT.