npm package: @guilhermecs/stencil-components
Description: Web components agnósticos feitos com Stencil
Author: Seu Nome
Latest version: 0.0.1

# 🎨 Stencil Components

Web components agnósticos feitos com Stencil - funcionam em qualquer framework ou sem framework!

[![npm version](https://badge.fury.io/js/%40guilhermecs%2Fstencil-components.svg)](https://badge.fury.io/js/%40guilhermecs%2Fstencil-components)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 📦 Características

- ✅ **Agnósticos**: Funcionam com React, Vue, Angular, Svelte ou sem framework
- ✅ **Web Components**: Padrão W3C, suportados nativamente pelos navegadores modernos
- ✅ **TypeScript**: Totalmente tipados
- ✅ **Estilização**: CSS encapsulado com Shadow DOM
- ✅ **Testes**: Testes unitários inclusos
- ✅ **Documentação**: Docs auto-geradas
- ✅ **Sem dependências**: Leve e rápido

## 🚀 Instalação

```bash
# npm
npm install @guilhermecs/stencil-components

# yarn
yarn add @guilhermecs/stencil-components

# pnpm
pnpm add @guilhermecs/stencil-components
```

## 💡 Uso Básico

### HTML Puro

```html
<!DOCTYPE html>
<html>
  <head>
    <script
      type="module"
      src="https://unpkg.com/@guilhermecs/stencil-components@latest/dist/stencil-components/stencil-components.esm.js"
    ></script>
  </head>
  <body>
    <!-- Button -->
    <sc-button label="Clique aqui" variant="primary"></sc-button>

    <!-- Card -->
    <sc-card heading="Meu Card" subheading="Com Stencil">
      <p>Conteúdo aqui</p>
    </sc-card>

    <script>
      const button = document.querySelector("sc-button");
      button.addEventListener("btnClick", () => {
        console.log("Botão clicado!");
      });
    </script>
  </body>
</html>
```

### React

```jsx
import React from "react";
import { defineCustomElements } from "@guilhermecs/stencil-components/loader";

// Define os custom elements
defineCustomElements();

export default function App() {
  const handleButtonClick = () => {
    console.log("Botão clicado!");
  };

  return (
    <>
      <sc-button
        label="Clique aqui"
        variant="primary"
        onBtnClick={handleButtonClick}
      ></sc-button>

      <sc-card heading="Meu Card" subheading="Com React">
        <p>Conteúdo integrado com React</p>
      </sc-card>
    </>
  );
}
```

### Vue

```vue
<template>
  <div>
    <sc-button
      label="Clique aqui"
      variant="primary"
      @btnClick="handleClick"
    ></sc-button>

    <sc-card heading="Meu Card" subheading="Com Vue">
      <p>Conteúdo integrado com Vue</p>
    </sc-card>
  </div>
</template>

<script>
import { defineCustomElements } from "@guilhermecs/stencil-components/loader";

defineCustomElements();

export default {
  methods: {
    handleClick() {
      console.log("Botão clicado!");
    },
  },
};
</script>
```

### Angular

```typescript
import { Component, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
import { defineCustomElements } from "@guilhermecs/stencil-components/loader";

defineCustomElements();

@Component({
  selector: "app-root",
  template: `
    <sc-button
      label="Clique aqui"
      variant="primary"
      (btnClick)="handleClick()"
    ></sc-button>

    <sc-card heading="Meu Card" subheading="Com Angular">
      <p>Conteúdo integrado com Angular</p>
    </sc-card>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppComponent {
  handleClick() {
    console.log("Botão clicado!");
  }
}
```

## 📚 Componentes

### `<sc-button>`

Botão customizável e acessível.

#### Props

| Prop       | Type                                   | Default    | Descrição          |
| ---------- | -------------------------------------- | ---------- | ------------------ |
| `label`    | `string`                               | `Click me` | Texto do botão     |
| `variant`  | `'primary' \| 'secondary' \| 'danger'` | `primary`  | Estilo do botão    |
| `disabled` | `boolean`                              | `false`    | Desabilita o botão |
| `size`     | `'small' \| 'medium' \| 'large'`       | `medium`   | Tamanho do botão   |

#### Events

- `btnClick` - Emitido quando o botão é clicado

#### Exemplo

```html
<sc-button label="Enviar" variant="primary" size="large"></sc-button>
```

### `<sc-card>`

Card com header opcional e conteúdo.

#### Props

| Prop         | Type      | Default | Descrição             |
| ------------ | --------- | ------- | --------------------- |
| `heading`    | `string?` | -       | Título do card        |
| `subheading` | `string?` | -       | Subtítulo do card     |
| `elevated`   | `boolean` | `true`  | Mostra sombra no card |

#### Slots

- `default` - Conteúdo principal do card

#### Exemplo

```html
<sc-card heading="Título" subheading="Subtítulo" elevated>
  <p>Conteúdo aqui</p>
  <sc-button label="Ação"></sc-button>
</sc-card>
```

## 🛠️ Desenvolvimento

### Setup

```bash
# Instalar dependências
npm install

# Iniciar desenvolvimento com watch
npm run dev

# Build para produção
npm run build

# Rodar testes
npm test

# Watch mode para testes
npm run test.watch
```

### Criar novo componente

```bash
npm run generate
```

Será perguntado o nome do componente, então escolha um nome descritivo.

### Estrutura do Projeto

```
stencil-components/
├── src/
│   ├── components/
│   │   ├── button-component/
│   │   │   ├── button-component.tsx      # Component
│   │   │   ├── button-component.css      # Estilos
│   │   │   └── button-component.spec.ts  # Testes
│   │   └── card-component/
│   │       ├── card-component.tsx
│   │       ├── card-component.css
│   │       └── card-component.spec.ts
│   ├── index.ts                          # Exports
│   └── components.d.ts                   # Type definitions
├── dist/                                 # Build output
├── stencil.config.ts                     # Configuração do Stencil
├── tsconfig.json                         # TypeScript config
├── package.json                          # Dependencies & scripts
└── README.md                             # Este arquivo
```

## 📤 Publicar no NPM

### 1. Preparar o projeto

```bash
# Atualizar versão no package.json
npm version patch  # ou minor, major

# Build final
npm run build

# Verificar files no package.json
npm ls --depth=0
```

### 2. Criar conta NPM

Se você ainda não tem uma conta, crie em [npmjs.com](https://www.npmjs.com/signup)

### 3. Login no NPM

```bash
npm login
```

Será pedido seu username, password e email.

### 4. Publicar

```bash
npm publish --access public
```

Para pacotes com escopo (com @):

```bash
npm publish --access public
```

### 5. Verificar publicação

```bash
npm view @guilhermecs/stencil-components
```

## 🔄 Atualizar versão no NPM

```bash
# Para patch (0.0.X)
npm version patch
npm publish

# Para minor (0.X.0)
npm version minor
npm publish

# Para major (X.0.0)
npm version major
npm publish
```

## 📝 Boas práticas

- ✅ Sempre adicione testes unitários
- ✅ Use TypeScript para melhor type safety
- ✅ Documente seus komponentes
- ✅ Mantenha componentes pequenos e focados
- ✅ Use Shadow DOM para encapsulação
- ✅ Siga a semântica HTML5
- ✅ Teste em múltiplos navegadores

## 🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

1. Fork o repositório
2. Crie uma branch (`git checkout -b feature/amazing-feature`)
3. Commit suas mudanças (`git commit -m 'Add amazing feature'`)
4. Push para a branch (`git push origin feature/amazing-feature`)
5. Abra um Pull Request

## 📄 Licença

Este projeto é licenciado sob a Licença MIT - veja o arquivo LICENSE para mais detalhes.

## 🔗 Recursos úteis

- [Documentação Stencil](https://stenciljs.com)
- [Web Components MDN](https://developer.mozilla.org/en-US/docs/Web/Web_Components)
- [NPM Docs](https://docs.npmjs.com)
- [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM)

## 💬 Suporte

Para dúvidas ou problemas:

- 📮 Issues: [GitHub Issues](https://github.com/guilhermecs/stencil-components/issues)
- 💬 Discussões: [GitHub Discussions](https://github.com/guilhermecs/stencil-components/discussions)

---

**Feito com ❤️ usando Stencil**