npm package: @leonardogarciahh/addon-template
Description: Template de addon React + TypeScript + Vite para busca e exibição de produtos.
Latest version: 1.0.22

# Addon Template - Busca de Produtos

Template de addon React + TypeScript + Vite para busca e exibição de produtos.

## 🚀 Desenvolvimento Local

### Instalação

```bash
npm install
```

**Nota**: O projeto usa `sass` para desenvolvimento e `sass-embedded` para builds de produção. Ambos já estão configurados como dependências.

### Modo de Desenvolvimento

Para desenvolver e testar o componente localmente:

```bash
npm run dev
```

Isso irá:
- Iniciar o servidor de desenvolvimento na porta padrão (geralmente http://localhost:5173)
- Carregar o componente com dados mockados
- Ativar Hot Module Replacement (HMR) para atualizações instantâneas
- Simular a API de produtos com dados de teste

### Build para Produção

Para gerar a build da biblioteca:

```bash
npm run build
```

Isso irá:
- Compilar o TypeScript
- Gerar o bundle otimizado em `./dist/index.js`
- Preparar o pacote para publicação

### Preview da Build

Para testar a build de produção:

```bash
npm run preview
```

## 📦 Estrutura do Projeto

```
addon/
├── src/
│   ├── index.tsx                    # Componente principal (TemplateAddon)
│   ├── TemplateAddon.module.scss   # Estilos do componente principal
│   ├── main.tsx                     # Entry point para desenvolvimento
│   ├── main.module.scss             # Estilos da página de desenvolvimento
│   ├── index.scss                   # Estilos globais
│   └── vite-env.d.ts               # Declarações de tipos
├── dist/                            # Build de produção
├── vite.config.ts                   # Configuração do Vite
└── package.json                     # Dependências e scripts
```

## 🎨 Estilização com SCSS Modules

O projeto usa **SCSS Modules** para estilos com escopo local, evitando conflitos de nomes de classes.

### Como funciona

```tsx
// Import do módulo SCSS
import styles from "./TemplateAddon.module.scss";

// Uso das classes
<div className={styles.container}>
  <input className={styles.searchInput} />
</div>
```

### Vantagens

- ✅ **Escopo local**: Classes não vazam para outros componentes
- ✅ **TypeScript**: Autocomplete e type-safety nas classes CSS
- ✅ **SCSS**: Variáveis, nesting, mixins e outras features do Sass
- ✅ **Sem conflitos**: Nomes de classes são automaticamente únicos
- ✅ **Tree-shaking**: CSS não utilizado é removido na build

## 🔧 Configuração

### Props do Componente

```typescript
interface FictionAddonProps {
  cartId: string;                    // ID do carrinho (obrigatório)
  locationsAvailable?: {             // Locais disponíveis (opcional)
    locationId: number;
    locationName: string;
    status: 'ACTIVE' | 'INACTIVE';
  }[];
  apiBaseUrl?: string;               // URL base da API (padrão: "")
  sessionCookie?: string;            // Cookie de sessão (opcional)
}
```

### Exemplo de Uso

#### Via CDN (jsDelivr)

Se você está usando via CDN, **carregue o CSS também**:

```html
<head>
  <!-- ⚠️ OBRIGATÓRIO: CSS via CDN -->
  <link 
    rel="stylesheet" 
    href="https://cdn.jsdelivr.net/npm/@leonardogarciahh/addon-template@1.0.14/dist/index.css"
  />
</head>
<body>
  <div id="root"></div>
  <script type="module">
    import TemplateAddon from 'https://cdn.jsdelivr.net/npm/@leonardogarciahh/addon-template@1.0.14/dist/index.js';
    // ... usar o componente
  </script>
</body>
```

#### Via npm/import

**⚠️ IMPORTANTE**: Você **DEVE** importar o CSS gerado junto com o componente, caso contrário o componente aparecerá sem estilos!

```tsx
import TemplateAddon from '@leonardogarciahh/addon-template';
// ⚠️ OBRIGATÓRIO: Importe o CSS
import '@leonardogarciahh/addon-template/dist/index.css';

function App() {
  return (
    <TemplateAddon
      cartId="123"
      locationsAvailable={[
        {
          locationId: 1,
          locationName: "Loja Principal",
          status: "ACTIVE"
        }
      ]}
      // Opcional: configure a URL base da API se necessário
      apiBaseUrl="https://api.exemplo.com"
      // Opcional: configure o cookie de sessão
      sessionCookie="seu-cookie-aqui"
    />
  );
}
```

**Nota**: Os estilos são gerados como CSS Modules e vêm com classes com hash para evitar conflitos (ex: `._container_hqwt6_1`)

📖 **Veja mais detalhes em [USAGE.md](./USAGE.md)** para troubleshooting e exemplos completos.

## 🎨 Funcionalidades

- ✅ Busca de produtos em tempo real
- ✅ Debounce automático (600ms)
- ✅ Exibição de SKU, EAN e embalagens
- ✅ Indicador de status (Ativo/Inativo)
- ✅ Exibição de preços formatados
- ✅ Grid responsivo
- ✅ Estados de loading e erro

## 🔌 API Mock (Desenvolvimento)

Durante o desenvolvimento, o Vite intercepta as chamadas para `/api/product/price/search/*` e retorna dados mockados. Você pode modificar os dados em `vite.config.ts`.

### Endpoint Mockado

```
POST /api/product/price/search/{cartId}
```

**Body:**
```json
{
  "pageNumber": 1,
  "pageSize": 50,
  "sortOrders": [],
  "textSearch": "texto da busca",
  "filters": [{
    "field": "locationId",
    "value": [1, 2]
  }],
  "keyValues": false
}
```

**Resposta:**
```json
{
  "pageNumber": 1,
  "totalRecords": 1,
  "records": [
    {
      "id": 1,
      "productId": 1,
      "productName": "Produto Teste",
      "productSku": "SKU-001",
      "productEan": "7891234567890",
      "productPackages": [
        {
          "name": "UN",
          "multiplier": 1,
          "allowBuyDecimalQuantity": false
        }
      ],
      "status": "ACTIVE",
      "locationId": 1,
      "prices": [
        {
          "priceGroupId": 1,
          "priceGroupName": "Padrão",
          "priceGroupIsDefault": true,
          "price": 12.99,
          "priceEditAllowed": false
        }
      ],
      "updatedAt": "2025-11-11T11:47:23"
    }
  ]
}
```

## 🛠️ Tecnologias

- **React 19** - Biblioteca UI
- **TypeScript** - Type safety
- **Vite** - Build tool e dev server
- **SCSS Modules** - Estilos com escopo local e pré-processador CSS

## 📝 Licença

MIT