@govbr-ds/webcomponents-react

Wrapper React para @govbr-ds/webcomponents

Este é um wrapper React que encapsula os Web Components GovBR-DS, permitindo seu uso como componentes nativos do React.

Por que usar este wrapper? 🤔

Utilizar o wrapper React para os Web Components GovBR-DS oferece várias vantagens:

• Bindings JSX: Gera wrappers de componentes funcionais React com bindings JSX para eventos e propriedades personalizadas, facilitando a integração e o uso dos componentes.

• Tipagens e Auto-completação: Proporciona tipagens e auto-completação para componentes React no seu IDE, melhorando a experiência de desenvolvimento e reduzindo erros.

• Manipulação de dados: O React passa todos os dados para os elementos personalizados na forma de atributos HTML. Para dados primitivos, isso funciona bem, mas o sistema apresenta dificuldades ao lidar com dados complexos, como objetos ou arrays. Nesses casos, os valores acabam sendo transformados em strings, como custom-attr="[object Object], tornando-os inutilizáveis.

• Manipulação de eventos: Como o React implementa seu próprio sistema de eventos sintéticos, ele não consegue escutar eventos DOM provenientes de elementos personalizados sem o uso de uma solução alternativa. Os desenvolvedores precisam referenciar seus elementos personalizados usando um ref e anexar manualmente os ouvintes de eventos com addEventListener, o que complica o trabalho com elementos personalizados.

Para mais detalhes, consulte a documentação oficial do Stencil.

React e custom elements enfrentam algumas limitações quando usados juntos. O Custom Elements Everywhere descreve bem essas dificuldades:

Voltar ao topo

Manipulação de dados

O React transfere dados para custom elements como atributos HTML. Isso funciona para valores primitivos, mas apresenta problemas para dados complexos, como objetos ou arrays. Esses valores acabam sendo convertidos para strings, como some-attr="[object Object], tornando-os inutilizáveis.

Voltar ao topo

Manipulação de eventos

Como o React utiliza seu próprio sistema de eventos sintéticos, ele não consegue capturar eventos DOM disparados por custom elements sem recorrer a soluções alternativas. Isso exige que os desenvolvedores utilizem referências (refs) para anexar ouvintes de eventos manualmente com addEventListener, complicando o uso de custom elements.

Este wrapper resolve essas questões, expondo um componente React que mapeia propriedades e eventos diretamente para o elemento personalizado correspondente.

Voltar ao topo

Uso 📚

Para utilizar o wrapper React dos Web Components GovBR-DS em uma aplicação React, siga os passos abaixo:

Instalação

Instale os pacotes necessários:

npm install --save-dev @govbr-ds/{core,webcomponents,webcomponents-react}

[!NOTE] Certifique-se de que o pacote @govbr-ds/webcomponents está instalado.

Voltar ao topo

Font Awesome e Fonte Rawline

Nossos componentes utilizam a Fonte Rawline juntamente com a 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 para mais detalhes sobre como importá-las de seus respectivos CDNs.

• 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: 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 para mais detalhes sobre como importá-los de seus respectivos CDNs.

Voltar ao topo

Passo-a-passo

Os estilos do govbr-ds/core devem ser importados no arquivo de estilo principal do seu aplicativo:

@import '~@govbr-ds/core/dist/core-tokens.min.css';

Importe os componente que for usar:

import React from 'react';
import { BrButton } from '@govbr-ds/webcomponents-react';

function App() {
  const handleButtonClick = (ev: CustomEvent) => {
    console.log(ev.detail);
  };

  return (
    <BrButton emphasis="primary" onBrClick={handleButtonClick}>
      Clique aqui
    </BrButton>
  );
}

export default App;

Voltar ao topo

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.

Voltar ao topo

Desenvolvimento 👨‍💻

Estrutura do projeto

├── 📁 src
      ├── 📁 stencil-generated
      ├── 📄 index.ts
├── 📁 ssr
      ├── 📁 stencil-generated
      ├── 📄 index.ts
├── ...

• src: Contém os arquivos da biblioteca React padrão.
  • stencil-generated: Arquivos gerados automaticamente durante o build dos Web Components.
  • index.ts: Entry point para a biblioteca.
• ssr: Contém os arquivos para aplicações com renderização no servidor (SSR).
  • stencil-generated: Arquivos gerados automaticamente durante o build dos Web Components.
  • index.ts: Entry point para a biblioteca em SSR.

[!WARNING] Todas as alterações nas pastas stencil-generated serão perdidas ao gerar um novo build dos Web Components.

Voltar ao topo

Build

Antes de compilar a biblioteca React, é necessário gerar o build dos webcomponents:

nx build webcomponents

Depois, para gerar o build da biblioteca React, execute:

nx build react

Voltar ao topo

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.

Voltar ao topo

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.
• Quer contribuir? Consulte o nosso guia como contribuir.

Voltar ao topo

Reportar Bugs/Problemas ou Sugestões 🐛

Para reportar problemas ou sugerir melhorias, abra uma issue. Utilize o modelo adequado e forneça o máximo de detalhes possível.

Nos comprometemos a responder a todas as issues.

Voltar ao topo

Commits 📝

Este projeto segue um padrão para branches e commits. Consulte a documentação na nossa wiki para aprender mais sobre esses padrões.

Voltar ao topo

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

Voltar ao topo

Créditos 🎉

Os Web Components do GovBR-DS foram desenvolvidos pelo SERPRO em colaboração com a comunidade.

Voltar ao topo