Sula Webcomponents

Como instalar

NPM

Instale a dependência:

npm i @sula-tech/webcomponents

E importe o webcomponents.esm.js:

<script src="@sula-tech/webcomponents/dist/webcomponents/webcomponents.esm.js" type="module"></script>

Para projetos legados, importe o webcomponents.js:

<script src="@sula-tech/webcomponents/dist/webcomponents/webcomponents.js" type="text/javascript"></script>

Para uso em frameworks, consulte a documentação do Stencil.

Configuração do TailwindCSS

Para que as cores do design system sejam aplicadas corretamente aos componentes, é obrigatório configurar o plugin do design system junto ao TailwindCSS.

Como configurar:

1. Instale e configure o plugin seguindo o guia de instalação completo
2. Certifique-se de que o plugin está devidamente integrado ao seu arquivo de configuração do Tailwind

⚠️ Importante: Sem essa configuração, as cores dos componentes não serão exibidas conforme o esperado.

Configuração de Ícones

Para que os ícones funcionem corretamente, adicione a seguinte linha no seu arquivo de estilos global:

@import '@sula-tech/webcomponents/dist/webcomponents/assets/icons/icons.css';

Aplicações Angular

npm i @sula-tech/webcomponents

É necessário declarar o CUSTOM_ELEMENTS_SCHEMA em cada módulo onde os webcomponents serão utilizados:

import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  declarations: [YourComponent],
  imports: [CommonModule, OtherModules],
  schemas: [CUSTOM_ELEMENTS_SCHEMA], // Necessário em cada módulo que utiliza webcomponents
})
export class YourModule {}

E no final do arquivo main.ts, adicione os seguintes imports:

import { applyPolyfills, defineCustomElements } from '@sula-tech/webcomponents/loader';

defineCustomElements();

Instalação em Aplicações React

1. Instalação do Pacote

npm install @sula-tech/webcomponents

2. Configuração Básica

No arquivo principal da sua aplicação (src/index.js ou src/index.tsx), adicione a configuração dos Web Components antes da renderização do React:

import { applyPolyfills, defineCustomElements } from '@sula-tech/webcomponents/loader';

// Inicializa os Web Components
defineCustomElements();

// Resto do seu código de inicialização do React...

💡 Dica: É importante importar e executar defineCustomElements() antes de renderizar qualquer componente React que utilize os Web Components.

3. Configuração para TypeScript

Se você estiver usando TypeScript, siga os passos adicionais abaixo:

3.1. Criação do arquivo de tipos

Crie o arquivo src/types/sula-components.d.ts:

import { HTMLAttributes } from 'react';

declare module 'react' {
  namespace JSX {
    interface IntrinsicElements {
      [K: `sula-${string}`]: HTMLAttributes<HTMLElement> & {
        className?: string;
        [prop: string]: unknown;
      };
    }
  }
}

3.2. Atualização do tsconfig.json

Adicione as seguintes configurações ao seu tsconfig.json:

{
  "compilerOptions": {
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": [
    "src/**/*",
    "src/types/**/*"
  ]
}

✅ Verificação da Instalação

Após seguir os passos acima, você pode testar se a instalação foi bem-sucedida utilizando qualquer componente da biblioteca:

function App() {
  return (
    <div>
      <sula-button
        text="Default Button"
        appearance="default"
        type="text"
        size="default"
        status="primary"
        loading="false"
        button-disabled="false"
      ></sula-button>
    </div>
  );
}

Quero contribuir

Veja o guia de contribuição.