@solucx/react-native-solucx-widget 0.1.0

package/README.intern.md

@@ -0,0 +1,476 @@
+# SoluCX Widget
+
+Um widget React Native modular para coleta de feedback e pesquisas, desenvolvido seguindo princípios de Clean Code e arquitetura escalável.
+
+## 📋 Visão Geral
+
+O SoluCX Widget oferece quatro modos de renderização flexíveis para integração em aplicações React Native/Expo:
+
+- **Top**: Widget fixo no topo da tela
+- **Bottom**: Widget fixo na parte inferior
+- **Modal**: Widget em sobreposição centralizada
+- **Inline**: Widget integrado ao fluxo do layout
+
+## 🏗️ Arquitetura
+
+### Componentes Principais
+
+- [`SoluCXWidget.tsx`](src/SoluCXWidget.tsx) - Componente principal
+- [`useWidgetState.ts`](src/hooks/useWidgetState.ts) - Hook para gerenciamento de estado
+- [`WidgetEventService`](src/services/widgetEventService.ts) - Serviço de eventos
+- [`StorageService`](src/services/storage.ts) - Persistência local
+
+### Estrutura de Arquivos
+
+```
+src/
+├── SoluCXWidget.tsx           # Componente principal
+├── components/                # Componentes especializados
+│   ├── ModalWidget.tsx        # Widget modal
+│   ├── InlineWidget.tsx       # Widget inline
+│   └── OverlayWidget.tsx      # Widget overlay (top/bottom)
+├── hooks/                     # Hooks personalizados
+│   └── useWidgetState.ts      # Estado do widget
+├── services/                  # Serviços
+│   ├── widgetEventService.ts  # Gerenciamento de eventos
+│   └── storage.ts             # Persistência de dados
+├── interfaces/                # Tipos TypeScript
+│   ├── index.ts               # Exports centralizados
+│   ├── WidgetData.ts          # Dados do widget
+│   ├── WidgetOptions.ts       # Opções de configuração
+│   ├── WidgetResponse.ts      # Respostas e erros
+│   └── WidgetSamplerLog.ts    # Log de tentativas
+├── styles/                    # Estilos
+│   └── widgetStyles.ts        # Estilos por tipo
+├── utils/                     # Utilitários
+│   └── urlUtils.ts            # Construção de URLs
+├── constants/                 # Constantes
+│   └── webViewConstants.ts    # URLs e configurações
+└── __tests__/                 # Testes
+    ├── urlUtils.test.ts
+    └── useWidgetState.test.ts
+```
+
+## 🚀 Instalação e Uso
+
+### Instalação
+
+```bash
+# Como dependência local (monorepo)
+npm install solucx_widget@file:./modules/solucx_widget
+
+# Dependências peer necessárias
+npm install react-native-webview @react-native-async-storage/async-storage
+```
+
+### Uso Básico
+
+```tsx
+import React from 'react';
+import { SoluCXWidget } from 'solucx_widget';
+
+export default function MyComponent() {
+  return (
+    <SoluCXWidget
+      soluCXKey="sua-chave-solucx"
+      type="bottom" // 'top' | 'bottom' | 'modal' | 'inline'
+      data={{
+        journey: "nome_da_jornada",
+        name: "Nome do Cliente",
+        email: "cliente@email.com",
+        phone: "11999999999",
+        store_id: "1",
+        employee_id: "1",
+        amount: 100,
+        param_REGIAO: "SUDESTE"
+      }}
+      options={{ 
+        width: 380, 
+        height: 400 
+      }}
+    />
+  );
+}
+```
+
+## 🎛️ API do Componente
+
+### Props do SoluCXWidget
+
+```typescript
+interface SoluCXWidgetProps {
+  soluCXKey: string;           // Chave de autenticação SoluCX
+  type: WidgetType;            // Modo de renderização
+  data: WidgetData;            // Dados do cliente/transação
+  options: WidgetOptions;      // Configurações do widget
+}
+```
+
+### Tipos de Widget
+
+```typescript
+type WidgetType = "bottom" | "top" | "inline" | "modal";
+```
+
+### Dados do Widget
+
+```typescript
+interface WidgetData {
+  // Identificadores
+  transaction_id?: string;
+  customer_id?: string;
+  
+  // Dados do cliente
+  name?: string;
+  email?: string;
+  phone?: string;
+  birth_date?: string;
+  document?: string;
+  
+  // Dados da transação
+  store_id?: string;
+  store_name?: string;
+  employee_id?: string;
+  employee_name?: string;
+  amount?: number;
+  score?: number;
+  
+  // Parâmetros customizados
+  journey?: string;
+  [key: string]: string | number | undefined;
+}
+```
+
+### Opções de Configuração
+
+```typescript
+interface WidgetOptions {
+  width?: number;              // Largura do widget (padrão: 380)
+  height?: number;             // Altura do widget (padrão: 400)
+  retry?: {                    // Configuração de retry
+    attempts?: number;         // Número de tentativas
+    interval?: number;         // Intervalo entre tentativas
+  };
+  waitDelayAfterRating?: number; // Delay após avaliação
+}
+```
+
+## 🔄 Sistema de Eventos
+
+O widget comunica através de mensagens WebView bidirecionais:
+
+### Eventos Suportados
+
+```typescript
+type EventKey = 
+  | "FORM_OPENED"           // Widget foi aberto
+  | "FORM_CLOSE"            // Usuário fechou o widget  
+  | "FORM_ERROR"            // Erro no carregamento
+  | "FORM_RESIZE"           // Widget redimensionado
+  | "FORM_PAGECHANGED"      // Mudança de página
+  | "QUESTION_ANSWERED"     // Pergunta respondida
+  | "FORM_COMPLETED"        // Formulário concluído
+  | "FORM_PARTIALCOMPLETED" // Completado parcialmente
+```
+
+### Tratamento de Eventos
+
+Os eventos são processados automaticamente pelo [`WidgetEventService`](src/services/widgetEventService.ts):
+
+```typescript
+const eventService = new WidgetEventService(
+  setIsWidgetVisible,  // Função para controlar visibilidade
+  resize,              // Função para redimensionar
+  open                 // Função para abrir widget
+);
+```
+
+## 💾 Persistência de Dados
+
+O widget utiliza [`AsyncStorage`](@react-native-async-storage/async-storage) para persistir:
+
+- **Histórico de tentativas**: Controla quantas vezes o widget foi exibido
+- **Última avaliação**: Data da última interação
+- **Controle de frequência**: Evita spam de widgets
+
+### Estrutura dos Dados
+
+```typescript
+interface WidgetSamplerLog {
+  attempts: number;      // Número de tentativas
+  lastAttempt: number;   // Timestamp da última tentativa
+  lastRating: number;    // Timestamp da última avaliação
+  lastParcial: number;   // Timestamp do último parcial
+}
+```
+
+## 🎨 Customização de Estilos
+
+### Estilos por Tipo
+
+Cada tipo de widget possui estilos específicos definidos em [`widgetStyles.ts`](src/styles/widgetStyles.ts):
+
+```typescript
+export const getWidgetStyles = (type: WidgetType) => {
+  const styleMap = {
+    'bottom': { container: styles.wrapper, content: styles.bottom },
+    'top': { container: styles.wrapper, content: styles.top },
+    'inline': { container: styles.inlineWrapper, content: styles.inline },
+    'modal': { container: styles.wrapper, content: styles.inline }
+  };
+
+  return styleMap[type] || styleMap.bottom;
+};
+```
+
+### Características Visuais
+
+- **Bottom/Top**: Position absolute com z-index elevado
+- **Modal**: Overlay com background semitransparente
+- **Inline**: Integrado ao fluxo normal do layout
+
+## 🔧 Utilitários
+
+### Construção de URLs
+
+O [`urlUtils.ts`](src/utils/urlUtils.ts) gerencia a construção de URLs da pesquisa:
+
+```typescript
+export function buildWidgetURL(key: string, data: WidgetData): string {
+  const params = new URLSearchParams(data as Record<string, string>);
+  const baseURL = `${BASE_URL}/${key}/?mode=widget`;
+  
+  if (data.transaction_id) {
+    return `${baseURL}&${params.toString()}`;
+  }
+  
+  return `${baseURL}&transaction_id=&${params.toString()}`;
+}
+```
+
+## 🧪 Testes
+
+### Executando Testes
+
+```bash
+# Todos os testes
+npm test
+
+# Teste específico
+npm test -- urlUtils.test.ts
+npm test -- useWidgetState.test.ts
+```
+
+### Cobertura de Testes
+
+- ✅ Construção de URLs
+- ✅ Gerenciamento de eventos
+- ✅ Estados do widget
+- ✅ Persistência de dados
+
+## ⚙️ Configuração
+
+### Constantes
+
+Configurações centralizadas em [`webViewConstants.ts`](src/constants/webViewConstants.ts):
+
+```typescript
+export const BASE_URL = 'https://survey-link.solucx.com.br/link';
+export const STORAGE_KEY = '@solucxWidgetLog';
+export const DEFAULT_WIDTH = 380;
+export const MIN_HEIGHT = 200;
+export const FIXED_Z_INDEX = 9999;
+export const MODAL_Z_INDEX = 10000;
+```
+
+### JavaScript Injection
+
+Listener para comunicação WebView:
+
+```typescript
+export const WEB_VIEW_MESSAGE_LISTENER = `
+  window.addEventListener('message', function(event) {
+    window.ReactNativeWebView.postMessage(event.data);
+  });
+`;
+```
+
+## 🚨 Considerações Importantes
+
+### 1. **Comportamento de Posicionamento**
+
+⚠️ **Ponto Crítico**: A posição no JSX **não determina** onde widgets `top`, `bottom` e `modal` aparecem:
+
+```tsx
+// ❌ Isso NÃO faz o widget aparecer no meio
+<Text>Conteúdo antes</Text>
+<SoluCXWidget type="bottom" {...props} /> {/* Sempre aparece embaixo */}
+<Text>Conteúdo depois</Text>
+
+// ✅ Apenas o tipo "inline" respeita a posição no código
+<Text>Conteúdo antes</Text>
+<SoluCXWidget type="inline" {...props} /> {/* Aparece aqui */}
+<Text>Conteúdo depois</Text>
+```
+
+### 2. **Performance**
+
+- Widget usa WebView interna (overhead de performance)
+- Carregamento lazy das pesquisas
+- Cache automático via AsyncStorage
+- JavaScript injection para comunicação
+
+### 3. **Segurança**
+
+- **Chaves API**: Nunca hardcode em produção
+- **Dados sensíveis**: Não são logados automaticamente
+- **URLs**: Validadas antes do carregamento
+- **HTTPS**: Obrigatório para comunicação
+
+### 4. **Limitações Técnicas**
+
+- Requer conexão com internet
+- Dependente do WebView do sistema
+- Eventos assíncronos (não bloqueantes)
+- Storage limitado do dispositivo
+
+## 📝 Desenvolvimento
+
+### Adicionando Novos Tipos
+
+1. **Estenda o tipo WidgetType**:
+```typescript
+// modules/solucx_widget/src/interfaces/index.ts
+export type WidgetType = "bottom" | "top" | "inline" | "modal" | "novo_tipo";
+```
+
+2. **Adicione estilos correspondentes**:
+```typescript
+// modules/solucx_widget/src/styles/widgetStyles.ts
+const styleMap = {
+  // ... estilos existentes
+  'novo_tipo': { container: styles.novoWrapper, content: styles.novoContent }
+};
+```
+
+3. **Implemente lógica no componente principal**:
+```typescript
+// modules/solucx_widget/src/SoluCXWidget.tsx
+if (type === 'novo_tipo') {
+  return <NovoTipoWidget>{/* ... */}</NovoTipoWidget>;
+}
+```
+
+### Adicionando Novos Eventos
+
+1. **Estenda EventKey**:
+```typescript
+// modules/solucx_widget/src/interfaces/index.ts
+export type EventKey = 
+  | "FORM_OPENED"
+  | "NOVO_EVENTO"  // Novo evento
+```
+
+2. **Implemente handler**:
+```typescript
+// modules/solucx_widget/src/services/widgetEventService.ts
+private executeEvent(eventKey: EventKey, value: string): WidgetResponse {
+  const eventHandlers = {
+    // ... handlers existentes
+    NOVO_EVENTO: (value: string) => this.handleNovoEvento(value),
+  };
+}
+```
+
+3. **Adicione testes**:
+```typescript
+// modules/solucx_widget/src/__tests__/widgetEventService.test.ts
+it('should handle NOVO_EVENTO correctly', () => {
+  const result = service.handleMessage('NOVO_EVENTO-data', true);
+  expect(result).toEqual({ status: 'success' });
+});
+```
+
+## 🔍 Troubleshooting
+
+### Problemas Comuns
+
+#### 1. **Widget não aparece**
+```bash
+# Verificações:
+✅ Chave SoluCX válida?
+✅ Conectividade com internet?
+✅ Logs do WebView no console?
+✅ Evento FORM_OPENED sendo disparado?
+```
+
+#### 2. **Eventos não funcionam**
+```bash
+# Verificações:
+✅ JavaScript listener injetado?
+✅ Formato das mensagens correto?
+✅ WebView carregou completamente?
+✅ postMessage funcionando?
+```
+
+#### 3. **Layout quebrado**
+```bash
+# Verificações:
+✅ Dimensões adequadas para o dispositivo?
+✅ Estilos corretos para o tipo?
+✅ Z-index conflitando?
+✅ SafeArea configurada?
+```
+
+#### 4. **Storage não persiste**
+```bash
+# Verificações:
+✅ AsyncStorage instalado?
+✅ Permissões de storage?
+✅ Dados sendo serializados corretamente?
+✅ Chaves de storage únicas?
+```
+
+### Debug Avançado
+
+```typescript
+// Habilitar logs detalhados
+console.log("Widget event received:", processedKey, value);
+
+// Verificar dados persistidos
+const data = await storageService.read();
+console.log("Stored data:", data);
+
+// Verificar URL construída
+const url = buildWidgetURL(soluCXKey, data);
+console.log("Widget URL:", url);
+```
+
+## 📚 Dependências
+
+### Peer Dependencies
+
+```json
+{
+  "react-native-webview": "^13.0.0",
+  "@react-native-async-storage/async-storage": "^2.0.0",
+  "react": "^19.0.0",
+  "react-native": "^0.79.0"
+}
+```
+
+### Compatibilidade
+
+- **React Native**: 0.70+
+- **Expo**: 50+
+- **iOS**: 11+
+- **Android**: API 21+
+- **Web**: Suporte limitado (WebView)
+
+## 📄 Licença
+
+Este projeto é privado e proprietário da SoluCX.
+
+---
+
+**Desenvolvido com ❤️ pela equipe SoluCX**