@leonardogarciahh/addon-template

v1.0.22

Published

5 months ago

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

0High
0Medium
0Low

leonardogarciah

Addon Template - Busca de Produtos

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

🚀 Desenvolvimento Local

Instalação

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:

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:

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:

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

// 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

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:

<head>
  <!-- ⚠️ OBRIGATÓRIO: CSS via CDN -->
  <link 
    rel="stylesheet" 
    href="https://cdn.jsdelivr.net/npm/@leonardogarciahh/[email protected]/dist/index.css"
  />
</head>
<body>
  <div id="root"></div>
  <script type="module">
    import TemplateAddon from 'https://cdn.jsdelivr.net/npm/@leonardogarciahh/[email protected]/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!

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

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

Resposta:

{
  "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