npm package: @sula-tech/webcomponents
Description: A web component library built with Stencil
Latest version: 0.16.0

# Sula Webcomponents

## Como instalar

### NPM

Instale a dependência:

```bash
npm i @sula-tech/webcomponents
```

E importe o `webcomponents.esm.js`:

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

Para projetos legados, importe o `webcomponents.js`:

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

Para uso em frameworks, [consulte a documentação do Stencil](https://stenciljs.com/docs/overview).

### 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](https://bitbucket.org/sulamerica/sula-tailwind-css/src/develop/README.md)
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:

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

### Aplicações Angular

```bash
npm i @sula-tech/webcomponents
```

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

```ts
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:

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

defineCustomElements();
```

## **Instalação em Aplicações React**

### 1. Instalação do Pacote

```bash
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:

```js
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`:

```typescript
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`:

```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:

```jsx
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](CONTRIBUTING.md).