@solucx/react-native-solucx-widget 0.1.0

package/README.md

@@ -0,0 +1,260 @@
+# @solucx/react-native-solucx-widget
+
+[![npm version](https://badge.fury.io/js/@solucx%2Freact-native-solucx-widget.svg)](https://badge.fury.io/js/@solucx%2Freact-native-solucx-widget)
+[![React Native](https://img.shields.io/badge/React%20Native-0.70+-blue.svg)](https://reactnative.dev/)
+[![Expo](https://img.shields.io/badge/Expo-50+-lightgrey.svg)](https://expo.dev/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![iOS](https://img.shields.io/badge/iOS-11+-lightgrey.svg)](https://developer.apple.com/ios/)
+[![Android](https://img.shields.io/badge/Android-API%2021+-green.svg)](https://developer.android.com/)
+[![License](https://img.shields.io/badge/License-Proprietary-red.svg)](LICENSE)
+
+Um widget React Native modular para coleta de feedback e pesquisas de satisfação, desenvolvido pela SoluCX seguindo princípios de Clean Code e arquitetura escalável.
+
+## 🛠️ Tecnologias
+
+![React Native](https://img.shields.io/badge/React_Native-20232A?style=for-the-badge&logo=react&logoColor=61DAFB)
+![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)
+![WebView](https://img.shields.io/badge/WebView-4285F4?style=for-the-badge&logo=googlechrome&logoColor=white)
+![AsyncStorage](https://img.shields.io/badge/AsyncStorage-FF6B6B?style=for-the-badge&logo=react&logoColor=white)
+![Jest](https://img.shields.io/badge/Jest-C21325?style=for-the-badge&logo=jest&logoColor=white)
+
+## 📋 Visão Geral
+
+O SoluCX Widget permite integrar pesquisas de satisfação diretamente em aplicações React Native/Expo de forma simples e flexível. Desenvolvido para empresas que precisam coletar feedback em tempo real através de diferentes modalidades de apresentação.
+
+### 🎯 Principais Características
+
+- **4 Modos de Renderização**: Bottom, Top, Modal e Inline
+- **Persistência Automática**: Controle inteligente de frequência
+- **Comunicação WebView**: Integração transparente com plataforma SoluCX
+- **TypeScript**: Totalmente tipado para melhor experiência de desenvolvimento
+- **Performático**: Carregamento otimizado e cache local
+
+## 🚀 Instalação
+
+```bash
+npm install @solucx/react-native-solucx-widget
+```
+
+## 🎛️ Uso Básico
+
+```tsx
+import React from 'react';
+import { SoluCXWidget } from '@solucx/react-native-solucx-widget';
+
+export default function MyScreen() {
+  return (
+    <SoluCXWidget
+      soluCXKey="sua-chave-solucx"
+      type="bottom"
+      data={{
+        journey: "checkout_flow",
+        name: "João Silva",
+        email: "joao@email.com",
+        store_id: "loja_01",
+        amount: 150.00
+      }}
+      options={{ 
+        width: 380, 
+        height: 400 
+      }}
+    />
+  );
+}
+```
+
+## 📱 Modos de Renderização
+
+### Bottom (Padrão)
+Widget fixo na parte inferior da tela, ideal para feedback não intrusivo.
+
+```tsx
+<SoluCXWidget type="bottom" {...props} />
+```
+
+### Top
+Widget fixo no topo da tela, perfeito para notificações importantes.
+
+```tsx
+<SoluCXWidget type="top" {...props} />
+```
+
+### Modal
+Sobreposição centralizada que bloqueia interação com o fundo.
+
+```tsx
+<SoluCXWidget type="modal" {...props} />
+```
+
+### Inline
+Integrado ao fluxo normal do layout, respeitando a posição no código.
+
+```tsx
+<SoluCXWidget type="inline" {...props} />
+```
+
+## 🔧 API Completa
+
+### Props
+
+| Propriedade | Tipo | Obrigatório | Descrição |
+|------------|------|-------------|-----------|
+| `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 |
+
+### WidgetData
+
+```typescript
+interface WidgetData {
+  // Identificadores
+  transaction_id?: string;
+  customer_id?: string;
+  
+  // Dados do cliente
+  name?: string;
+  email?: string;
+  phone?: string;
+  birth_date?: string;     // Formato: YYYY-MM-DD
+  document?: string;
+  
+  // Contexto da transação
+  store_id?: string;
+  store_name?: string;
+  employee_id?: string;
+  employee_name?: string;
+  amount?: number;
+  score?: number;
+  journey?: string;        // Nome da jornada/fluxo
+  
+  // Parâmetros customizados (prefixo param_)
+  param_REGIAO?: string;
+  [key: string]: string | number | undefined;
+}
+```
+
+### WidgetOptions
+
+```typescript
+interface WidgetOptions {
+  width?: number;          // Largura (padrão: 380)
+  height?: number;         // Altura (padrão: 400)
+  retry?: {
+    attempts?: number;     // Tentativas (padrão: 3)
+    interval?: number;     // Intervalo em ms (padrão: 1000)
+  };
+  waitDelayAfterRating?: number; // Delay após avaliação
+}
+```
+
+### WidgetType
+
+```typescript
+type WidgetType = "bottom" | "top" | "inline" | "modal";
+```
+
+## 🔄 Sistema de Eventos
+
+O widget processa automaticamente os seguintes eventos da pesquisa:
+
+- `FORM_OPENED` - Widget foi aberto
+- `FORM_CLOSE` - Usuário fechou o widget
+- `FORM_COMPLETED` - Pesquisa concluída
+- `FORM_PARTIALCOMPLETED` - Completada parcialmente
+- `FORM_RESIZE` - Widget redimensionado
+- `FORM_ERROR` - Erro no carregamento
+
+## 💾 Persistência Inteligente
+
+O widget controla automaticamente:
+
+- **Histórico de tentativas**: Evita spam de widgets
+- **Última avaliação**: Data da última interação
+- **Controle de frequência**: Respeita configurações de exibição
+- **Armazenamento local**: Dados persistem entre sessões
+
+## ⚙️ Múltiplos Widgets
+
+```tsx
+const widgets = ['bottom', 'top'] as WidgetType[];
+
+return (
+  <>
+    {widgets.map((type) => (
+      <SoluCXWidget
+        key={type}
+        soluCXKey={key}
+        type={type}
+        data={data}
+        options={options}
+      />
+    ))}
+  </>
+);
+```
+
+## 🚨 Considerações Importantes
+
+### Posicionamento
+
+⚠️ **Comportamento Crítico**: A posição no JSX **não determina** onde widgets `top`, `bottom` e `modal` aparecem:
+
+```tsx
+// ❌ Widget "bottom" sempre aparece embaixo, independente da posição
+<Text>Conteúdo antes</Text>
+<SoluCXWidget type="bottom" {...props} />
+<Text>Conteúdo depois</Text>
+
+// ✅ Apenas "inline" respeita a posição no código
+<Text>Conteúdo antes</Text>
+<SoluCXWidget type="inline" {...props} />
+<Text>Conteúdo depois</Text>
+```
+
+## 🔍 Troubleshooting
+
+### Widget não aparece
+
+```typescript
+// Verificações essenciais:
+// ✅ Chave SoluCX válida?
+// ✅ Conectividade com internet?
+// ✅ Logs do WebView no console?
+// ✅ Dados obrigatórios preenchidos?
+```
+
+### Eventos não funcionam
+
+```typescript
+// Debug de comunicação:
+const handleMessage = (message: string) => {
+  console.log('Widget event:', message);
+};
+
+// Verificar se JavaScript foi injetado corretamente
+```
+
+### Layout quebrado
+
+```typescript
+// Ajustar dimensões para o dispositivo:
+const { width, height } = Dimensions.get('window');
+
+const options = {
+  width: width * 0.9,
+  height: Math.min(height * 0.6, 400)
+};
+```
+
+## 📚 Compatibilidade
+
+| Versão | React Native | Expo | iOS | Android |
+|--------|--------------|------|-----|---------|
+| 1.0.x | 0.70+ | 50+ | 11+ | API 21+ |
+
+## 📄 Licença
+
+Este pacote é proprietário da SoluCX. O uso é restrito a clientes licenciados da plataforma SoluCX.
+
+---

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@solucx/react-native-solucx-widget",
+  "version": "0.1.0",
+  "description": "The React Native SDK for Solucx Widget",
+  "main": "src/index",
+  "author": " <> ()",
+  "homepage": "#readme",
+  "files": [
+    "lib/",
+    "src/",
+    "README.md"
+  ]
+}

package/src/SoluCXWidget.tsx

@@ -0,0 +1,117 @@
+import React, { useEffect, useRef, useCallback } from 'react';
+import { Dimensions } from 'react-native';
+import { WebView } from 'react-native-webview';
+
+import { SoluCXKey, WidgetData, WidgetOptions, WidgetType } from './interfaces';
+import { useWidgetState } from './hooks/useWidgetState';
+import { WidgetEventService } from './services/widgetEventService';
+import { buildWidgetURL } from './utils/urlUtils';
+import { WEB_VIEW_MESSAGE_LISTENER } from './constants/webViewConstants';
+import { ModalWidget } from './components/ModalWidget';
+import { InlineWidget } from './components/InlineWidget';
+import { OverlayWidget } from './components/OverlayWidget';
+
+interface SoluCXWidgetProps {
+    soluCXKey: SoluCXKey;
+    type: WidgetType;
+    data: WidgetData;
+    options: WidgetOptions;
+}
+
+export const SoluCXWidget: React.FC<SoluCXWidgetProps> = ({
+    soluCXKey,
+    type,
+    data,
+    options
+}) => {
+    const webviewRef = useRef<WebView>(null);
+    const { width } = Dimensions.get('window');
+
+    const {
+        widgetHeight,
+        isWidgetVisible,
+        setIsWidgetVisible,
+        loadSavedData,
+        resize,
+        open,
+        close,
+        userId,
+    } = useWidgetState(data, type);
+
+    const eventService = new WidgetEventService(setIsWidgetVisible, resize, open, userId, options);
+
+    const uri = buildWidgetURL(soluCXKey, data);
+    const isForm = Boolean(data.form_id);
+    const height = options.height ? Number(options.height) : undefined;
+
+    useEffect(() => {
+        loadSavedData();
+    }, [loadSavedData]);
+
+    const handleWebViewMessage = useCallback(async (message: string) => {
+        if (message && message.length > 0) {
+            try {
+                await eventService.handleMessage(message, isForm);
+            } catch (error) {
+                console.error('Error handling widget message:', error);
+            }
+        }
+    }, [eventService, isForm]);
+
+    const handleWebViewLoad = useCallback(() => {
+        webviewRef.current?.injectJavaScript(WEB_VIEW_MESSAGE_LISTENER);
+    }, []);
+
+    const handleClose = useCallback(() => {
+        if (type === 'inline' || type === 'modal') {
+            close();
+        }
+        setIsWidgetVisible(false);
+    }, [setIsWidgetVisible]);
+
+
+    const webViewStyle = [
+        { height: widgetHeight },
+        { width }
+    ];
+
+    if (type === 'modal') {
+        return (
+            <ModalWidget visible={isWidgetVisible} onClose={handleClose}>
+                <WebView
+                    ref={webviewRef}
+                    style={webViewStyle}
+                    source={{ uri }}
+                    onLoadEnd={handleWebViewLoad}
+                    onMessage={(event) => handleWebViewMessage(event.nativeEvent.data)}
+                />
+            </ModalWidget>
+        );
+    }
+
+    if (type === 'inline') {
+        return (
+            <InlineWidget visible={isWidgetVisible} onClose={handleClose}>
+                <WebView
+                    ref={webviewRef}
+                    style={webViewStyle}
+                    source={{ uri }}
+                    onLoadEnd={handleWebViewLoad}
+                    onMessage={(event) => handleWebViewMessage(event.nativeEvent.data)}
+                />
+            </InlineWidget>
+        );
+    }
+
+    return (
+        <OverlayWidget visible={isWidgetVisible} width={width} height={widgetHeight} position={type} onClose={handleClose}>
+            <WebView
+                ref={webviewRef}
+                style={webViewStyle}
+                source={{ uri }}
+                onLoadEnd={handleWebViewLoad}
+                onMessage={(event) => handleWebViewMessage(event.nativeEvent.data)}
+            />
+        </OverlayWidget>
+    );
+};

package/src/__tests__/urlUtils.test.ts

@@ -0,0 +1,56 @@
+import { buildWidgetURL } from '../utils/urlUtils';
+
+describe('urlUtils', () => {
+    describe('buildWidgetURL', () => {
+        const mockKey = 'test-widget-key';
+
+        it('should build URL with transaction_id when provided', () => {
+            const data = {
+                customer_id: 'customer123',
+                form_id: 'form456',
+                transaction_id: 'trans789'
+            };
+
+            const result = buildWidgetURL(mockKey, data);
+
+            expect(result).toContain('https://survey-link.solucx.com.br/link/test-widget-key/?mode=widget');
+            expect(result).toContain('customer_id=customer123');
+            expect(result).toContain('form_id=form456');
+            expect(result).toContain('transaction_id=trans789');
+        });
+
+        it('should build URL with empty transaction_id when not provided', () => {
+            const data = {
+                customer_id: 'customer123',
+                form_id: 'form456'
+            };
+
+            const result = buildWidgetURL(mockKey, data);
+
+            expect(result).toContain('https://survey-link.solucx.com.br/link/test-widget-key/?mode=widget');
+            expect(result).toContain('transaction_id=&');
+            expect(result).toContain('customer_id=customer123');
+            expect(result).toContain('form_id=form456');
+        });
+
+        it('should handle empty data object', () => {
+            const data = {};
+
+            const result = buildWidgetURL(mockKey, data);
+
+            expect(result).toBe('https://survey-link.solucx.com.br/link/test-widget-key/?mode=widget&transaction_id=&');
+        });
+
+        it('should encode URL parameters correctly', () => {
+            const data = {
+                email: 'test@example.com',
+                name: 'John Doe'
+            };
+
+            const result = buildWidgetURL(mockKey, data);
+
+            expect(result).toContain('email=test%40example.com');
+            expect(result).toContain('name=John+Doe');
+        });
+    });
+});

package/src/__tests__/useWidgetState.test.ts

@@ -0,0 +1,190 @@
+import { WidgetEventService } from '../services/widgetEventService';
+import { WidgetOptions } from '../interfaces';
+
+const mockWidgetValidationService = {
+    shouldDisplayWidget: jest.fn().mockResolvedValue(true)
+};
+
+jest.mock('../services/widgetValidationService', () => ({
+    WidgetValidationService: jest.fn().mockImplementation(() => mockWidgetValidationService)
+}));
+
+describe('WidgetEventService', () => {
+    let mockSetIsWidgetVisible: jest.Mock;
+    let mockResize: jest.Mock;
+    let service: WidgetEventService;
+    let open: jest.Mock;
+    let mockUserId: string;
+    let mockWidgetOptions: WidgetOptions;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+
+        mockSetIsWidgetVisible = jest.fn();
+        mockResize = jest.fn();
+        open = jest.fn();
+        mockUserId = 'test-user-123';
+        mockWidgetOptions = {
+            width: 380,
+            height: 400,
+            retry: {
+                attempts: 5,
+                interval: 1
+            },
+            waitDelayAfterRating: 60
+        };
+
+        mockWidgetValidationService.shouldDisplayWidget.mockResolvedValue(true);
+
+        service = new WidgetEventService(
+            mockSetIsWidgetVisible,
+            mockResize,
+            open,
+            mockUserId,
+            mockWidgetOptions
+        );
+    });
+
+    afterEach(() => {
+        jest.clearAllMocks();
+        jest.restoreAllMocks();
+    });
+
+    it('should handle FORM_OPENED event correctly', async () => {
+        const result = await service.handleMessage('FORM_OPENED', true);
+
+        expect(mockWidgetValidationService.shouldDisplayWidget).toHaveBeenCalledWith(mockWidgetOptions);
+        expect(open).toHaveBeenCalled();
+        expect(mockSetIsWidgetVisible).toHaveBeenCalledWith(true);
+        expect(result).toEqual({ status: 'success' });
+    });
+
+    it('should prevent widget from opening when validation fails', async () => {
+        mockWidgetValidationService.shouldDisplayWidget.mockResolvedValueOnce(await Promise.resolve(false));
+
+        const result = await service.handleMessage('FORM_OPENED', true);
+
+        expect(mockWidgetValidationService.shouldDisplayWidget).toHaveBeenCalledWith(mockWidgetOptions);
+        expect(open).not.toHaveBeenCalled();
+        expect(mockSetIsWidgetVisible).not.toHaveBeenCalled();
+        expect(result).toEqual({ status: 'error', message: 'Widget not allowed' });
+    });
+
+    it('should handle FORM_CLOSE event correctly', async () => {
+        const result = await service.handleMessage('FORM_CLOSE', true);
+
+        expect(mockSetIsWidgetVisible).toHaveBeenCalledWith(false);
+        expect(result).toEqual({ status: 'success' });
+    });
+
+    it('should handle FORM_RESIZE event correctly', async () => {
+        const result = await service.handleMessage('FORM_RESIZE-350', true);
+
+        expect(mockSetIsWidgetVisible).toHaveBeenCalledWith(true);
+        expect(mockResize).toHaveBeenCalledWith('350');
+        expect(result).toEqual({ status: 'success' });
+    });
+
+    it('should handle FORM_ERROR event correctly', async () => {
+        const result = await service.handleMessage('FORM_ERROR-Something went wrong', true);
+
+        expect(mockSetIsWidgetVisible).toHaveBeenCalledWith(false);
+        expect(result).toEqual({ status: 'error', message: 'Something went wrong' });
+    });
+
+    it('should adapt survey keys to widget keys correctly for non-form widgets', async () => {
+        const result = await service.handleMessage('closeSoluCXWidget', false);
+
+        expect(mockSetIsWidgetVisible).toHaveBeenCalledWith(false);
+        expect(result).toEqual({ status: 'success' });
+    });
+
+    it('should return error for unknown events', async () => {
+        const result = await service.handleMessage('UNKNOWN_EVENT', true);
+
+        expect(result).toEqual({ status: 'error', message: 'Unknown event' });
+    });
+
+    it('should handle messages with no value correctly', async () => {
+        const result = await service.handleMessage('FORM_OPENED', true);
+
+        expect(mockWidgetValidationService.shouldDisplayWidget).toHaveBeenCalledWith(mockWidgetOptions);
+        expect(open).toHaveBeenCalled();
+        expect(mockSetIsWidgetVisible).toHaveBeenCalledWith(true);
+        expect(result).toEqual({ status: 'success' });
+    });
+
+    it('should handle FORM_PAGECHANGED event correctly', async () => {
+        const consoleSpy = jest.spyOn(console, 'log').mockImplementation(() => { });
+        const result = await service.handleMessage('FORM_PAGECHANGED-page2', true);
+
+        expect(consoleSpy).toHaveBeenCalledWith("Page changed:", "page2");
+        expect(result).toEqual({ status: 'success' });
+
+        consoleSpy.mockRestore();
+    });
+
+    it('should handle QUESTION_ANSWERED event correctly', async () => {
+        const consoleSpy = jest.spyOn(console, 'log').mockImplementation(() => { });
+        const result = await service.handleMessage('QUESTION_ANSWERED', true);
+        expect(consoleSpy).toHaveBeenCalledWith("Question answered");
+        expect(result).toEqual({ status: 'success' });
+
+        consoleSpy.mockRestore();
+    });
+
+    it('should handle FORM_COMPLETED event correctly', async () => {
+        const result = await service.handleMessage('FORM_COMPLETED', true);
+
+        expect(result).toEqual({ status: 'success' });
+    });
+
+    it('should handle FORM_PARTIALCOMPLETED event correctly', async () => {
+        const result = await service.handleMessage('FORM_PARTIALCOMPLETED', true);
+
+        expect(result).toEqual({ status: 'success' });
+    });
+
+    it('should adapt completeSoluCXWidget to FORM_COMPLETED', async () => {
+        const result = await service.handleMessage('completeSoluCXWidget', false);
+
+        expect(result).toEqual({ status: 'success' });
+    });
+
+    it('should adapt partialSoluCXWidget to FORM_PARTIALCOMPLETED', async () => {
+        const result = await service.handleMessage('partialSoluCXWidget', false);
+
+        expect(result).toEqual({ status: 'success' });
+    });
+
+    it('should adapt dismissSoluCXWidget to FORM_CLOSE', async () => {
+        const result = await service.handleMessage('dismissSoluCXWidget', false);
+
+        expect(mockSetIsWidgetVisible).toHaveBeenCalledWith(false);
+        expect(result).toEqual({ status: 'success' });
+    });
+
+    it('should adapt openSoluCXWidget to FORM_OPENED', async () => {
+        const result = await service.handleMessage('openSoluCXWidget', false);
+
+        expect(mockWidgetValidationService.shouldDisplayWidget).toHaveBeenCalledWith(mockWidgetOptions);
+        expect(open).toHaveBeenCalled();
+        expect(mockSetIsWidgetVisible).toHaveBeenCalledWith(true);
+        expect(result).toEqual({ status: 'success' });
+    });
+
+    it('should adapt errorSoluCXWidget to FORM_ERROR', async () => {
+        const result = await service.handleMessage('errorSoluCXWidget-Network error', false);
+
+        expect(mockSetIsWidgetVisible).toHaveBeenCalledWith(false);
+        expect(result).toEqual({ status: 'error', message: 'Network error' });
+    });
+
+    it('should adapt resizeSoluCXWidget to FORM_RESIZE', async () => {
+        const result = await service.handleMessage('resizeSoluCXWidget-400', false);
+
+        expect(mockSetIsWidgetVisible).toHaveBeenCalledWith(true);
+        expect(mockResize).toHaveBeenCalledWith('400');
+        expect(result).toEqual({ status: 'success' });
+    });
+});

package/src/components/CloseButton.tsx

@@ -0,0 +1,37 @@
+import React from 'react';
+import { TouchableOpacity, Text, StyleSheet } from 'react-native';
+
+interface CloseButtonProps {
+    onPress: () => void;
+    visible?: boolean;
+}
+
+export const CloseButton: React.FC<CloseButtonProps> = ({ onPress, visible = true }) => {
+    if (!visible) return null;
+
+    return (
+        <TouchableOpacity style={styles.closeButton} onPress={onPress}>
+            <Text style={styles.closeButtonText}>✕</Text>
+        </TouchableOpacity>
+    );
+};
+
+const styles = StyleSheet.create({
+    closeButton: {
+        position: 'absolute',
+        top: 10,
+        right: 10,
+        width: 30,
+        height: 30,
+        borderRadius: 15,
+        backgroundColor: 'rgba(0, 0, 0, 0.5)',
+        justifyContent: 'center',
+        alignItems: 'center',
+        zIndex: 10001,
+    },
+    closeButtonText: {
+        color: 'white',
+        fontSize: 16,
+        fontWeight: 'bold',
+    },
+});

package/src/components/InlineWidget.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+import { View } from 'react-native';
+import { styles, getWidgetVisibility } from '../styles/widgetStyles';
+import { CloseButton } from './CloseButton';
+
+interface InlineWidgetProps {
+    visible: boolean;
+    children?: React.ReactNode;
+    onClose?: () => void;
+}
+
+export const InlineWidget: React.FC<InlineWidgetProps> = ({ visible, children, onClose }) => {
+
+    return (
+        <View style={[styles.wrapper, getWidgetVisibility(visible)]}>
+            <View style={[styles.inline, getWidgetVisibility(visible)]}>
+                {children}
+                <CloseButton
+                    visible={visible}
+                    onPress={onClose || (() => { })}
+                />
+            </View>
+        </View>
+    );
+};