@widergy/mobile-ui 2.0.2 → 3.4.1

package/lib/components/FileDownloadManager/README.md

@@ -0,0 +1,447 @@
+# FileDownloadManager
+
+Módulo unificado y abstracto para manejar la descarga, almacenamiento, notificación y apertura de archivos en React Native con Expo.
+
+## 🎯 Características
+
+- ✅ **Generación de archivos**: PDF, Excel (XLSX), JSON
+- ✅ **Almacenamiento seguro**: Storage Access Framework (Android) y documentDirectory (iOS)
+- ✅ **Notificaciones**: Notificación cuando el archivo está listo con tap-to-open
+- ✅ **Visualización nativa**: Soporte para PDF viewer nativo en la app
+- ✅ **Compartir**: Integración con Expo Sharing para archivos sin visor nativo
+- ✅ **Colisión de nombres**: Agrega timestamp automáticamente si el archivo ya existe
+- ✅ **Traducciones personalizables**: Sistema flexible de i18n por parámetros
+- ✅ **Multiplataforma**: iOS y Android
+
+## 📦 Estructura
+
+```
+src/services/FileDownloadManager/
+├── index.js       # Módulo core (listo para @widergy/mobile-ui)
+├── adapter.js     # Adapter específico del proyecto
+├── types.js       # Tipos y constantes
+└── README.md      # Esta documentación
+```
+
+## 🚀 Uso Básico
+
+### Excel (XLSX)
+
+```javascript
+import { downloadExcel } from 'services/FileDownloadManager/adapter';
+import * as snackbarActions from 'actions/snackbar';
+
+// En tu action o componente
+const exportData = async (data, dispatch) => {
+  await downloadExcel(
+    data,                    // Array de objetos
+    'Reporte_Facturas',     // Nombre base del archivo
+    dispatch,                // Redux dispatch (opcional)
+    snackbarActions,         // Snackbar actions del proyecto
+    {                        // Traducciones personalizadas (opcional)
+      successDownload: 'Excel descargado exitosamente',
+      errorDownload: 'Error al descargar Excel'
+    },
+    {                        // Opciones adicionales
+      successCallback: ({ fileUri, fileName }) => {
+        console.log(`Archivo guardado: ${fileName}`);
+      },
+      failureCallback: (error) => {
+        console.error('Error:', error);
+      },
+      preventAutoOpen: false,  // Auto-abrir después de guardar
+      hideNotification: false  // Mostrar notificación
+    }
+  );
+};
+```
+
+### PDF
+
+```javascript
+import { downloadPDF } from 'services/FileDownloadManager/adapter';
+import * as snackbarActions from 'actions/snackbar';
+
+const savePDF = async (base64Content, dispatch) => {
+  await downloadPDF(
+    base64Content,           // PDF en base64
+    'Factura_12345',        // Nombre base
+    dispatch,                // Redux dispatch
+    snackbarActions,         // Snackbar actions
+    {                        // Traducciones (opcional)
+      downloadReadyTitle: 'PDF listo',
+      downloadReadyBody: '{fileName} está listo para ver'
+    },
+    {                        // Opciones
+      preventAutoOpen: false // Se abrirá con visor nativo
+    }
+  );
+};
+```
+
+### JSON
+
+```javascript
+import { downloadJSON } from 'services/FileDownloadManager/adapter';
+import * as snackbarActions from 'actions/snackbar';
+
+const exportConfig = async (configData, dispatch) => {
+  await downloadJSON(
+    configData,             // Objeto o array
+    'configuracion',        // Nombre base
+    dispatch,               // Redux dispatch
+    snackbarActions,        // Snackbar actions
+    {}                      // Traducciones (usa defaults si está vacío)
+  );
+};
+```
+
+## 🔧 API del Módulo Core
+
+### `downloadFile(config)`
+
+Función principal que maneja todo el flujo de descarga.
+
+**Parámetros:**
+```typescript
+{
+  type: 'pdf' | 'xlsx' | 'json',    // Tipo de archivo
+  fileName: string,                   // Nombre base (sin extensión)
+  data: any,                          // Datos del archivo
+  dispatch?: Function,                // Redux dispatch (opcional)
+  translations?: {                    // Traducciones personalizadas (opcional)
+    downloadReadyTitle?: string,      // Título notificación
+    downloadReadyBody?: string,       // Cuerpo notificación (usa {fileName})
+    shareFileTitle?: string,          // Título diálogo compartir (usa {fileName})
+    shareError?: string,              // Error al compartir
+    successDownload?: string,         // Mensaje éxito
+    errorDownload?: string            // Mensaje error
+  },
+  options?: {
+    hideNotification?: boolean,       // Omitir notificación
+    preventAutoOpen?: boolean,        // No abrir automáticamente
+    successCallback?: Function,       // Callback de éxito
+    failureCallback?: Function,       // Callback de error
+    showSnackbar?: Function          // Función para mostrar snackbar
+  }
+}
+```
+
+**Retorna:**
+```typescript
+Promise<{
+  success: boolean,
+  fileUri: string,
+  fileName: string
+}>
+```
+
+### `openFile(fileUri, fileName, fileType, translations?)`
+
+Abre un archivo previamente guardado.
+
+```javascript
+import { openFile, FILE_TYPES } from 'services/FileDownloadManager/adapter';
+
+await openFile(
+  'file:///path/to/file.pdf',
+  'documento.pdf',
+  FILE_TYPES.PDF,
+  {  // Traducciones opcionales
+    shareFileTitle: 'Compartir {fileName}',
+    shareError: 'No se pudo compartir'
+  }
+);
+```
+
+## 🌐 Sistema de Traducciones
+
+El módulo utiliza un sistema flexible de traducciones que permite personalizar todos los mensajes sin depender de librerías externas como i18next.
+
+### Traducciones Disponibles
+
+```typescript
+{
+  // Título de notificación cuando el archivo está listo
+  // Usado en: Notificación del sistema
+  downloadReadyTitle: string;
+  
+  // Cuerpo de notificación con nombre del archivo
+  // Parámetros: {fileName} - se reemplaza automáticamente
+  // Usado en: Notificación del sistema
+  downloadReadyBody: string;
+  
+  // Título del diálogo de compartir
+  // Parámetros: {fileName} - se reemplaza automáticamente
+  // Usado en: Diálogo nativo de compartir (iOS/Android)
+  shareFileTitle: string;
+  
+  // Mensaje de error cuando falla compartir
+  // Usado en: Callback de error, snackbar
+  shareError: string;
+  
+  // Mensaje de éxito para snackbar/toast
+  // Usado en: Snackbar después de descarga exitosa
+  successDownload: string;
+  
+  // Mensaje de error para snackbar/toast
+  // Usado en: Snackbar cuando falla la descarga
+  errorDownload: string;
+}
+```
+
+### Valores por Defecto (Español)
+
+```javascript
+{
+  downloadReadyTitle: 'Archivo listo',
+  downloadReadyBody: '{fileName} está disponible',
+  shareFileTitle: 'Compartir {fileName}',
+  shareError: 'No se pudo compartir el archivo',
+  successDownload: 'Archivo descargado correctamente',
+  errorDownload: 'Error al descargar el archivo'
+}
+```
+
+### Ejemplo: Traducciones en Inglés
+
+```javascript
+import { downloadPDF } from 'services/FileDownloadManager/adapter';
+
+const translations = {
+  downloadReadyTitle: 'File ready',
+  downloadReadyBody: '{fileName} is available',
+  shareFileTitle: 'Share {fileName}',
+  shareError: 'Could not share file',
+  successDownload: 'File downloaded successfully',
+  errorDownload: 'Error downloading file'
+};
+
+await downloadPDF(
+  pdfBase64,
+  'Invoice_2024',
+  dispatch,
+  snackbarActions,
+  translations  // Pasa las traducciones personalizadas
+);
+```
+
+### Integración con i18next
+
+Si tu proyecto usa i18next, puedes crear un helper:
+
+```javascript
+// utils/fileManagerTranslations.js
+import i18next from 'i18next';
+
+export const getFileManagerTranslations = () => ({
+  downloadReadyTitle: i18next.t('fileManager.downloadReadyTitle'),
+  downloadReadyBody: i18next.t('fileManager.downloadReadyBody'),
+  shareFileTitle: i18next.t('fileManager.shareFileTitle'),
+  shareError: i18next.t('fileManager.shareError'),
+  successDownload: i18next.t('fileManager.successDownload'),
+  errorDownload: i18next.t('fileManager.errorDownload')
+});
+
+// Uso
+import { getFileManagerTranslations } from 'utils/fileManagerTranslations';
+
+await downloadExcel(
+  data,
+  fileName,
+  dispatch,
+  snackbarActions,
+  getFileManagerTranslations()
+);
+```
+
+### Traducciones Parciales
+
+No es necesario proveer todas las traducciones. Las que no se envíen usarán los valores por defecto:
+
+```javascript
+// Solo personalizar algunos mensajes
+await downloadJSON(
+  data,
+  'config',
+  dispatch,
+  snackbarActions,
+  {
+    successDownload: 'JSON exportado!',
+    errorDownload: 'Falló la exportación'
+    // Resto usa valores por defecto
+  }
+);
+```
+
+## 📱 Comportamiento por Tipo de Archivo
+
+### PDF
+- ✅ **Visor nativo**: Se abre dentro de la app
+- 📁 **Ubicación**: `documentDirectory` (iOS/Android)
+- 🔔 **Notificación**: Sí, con tap-to-open
+- 🔄 **Fallback**: Si falla visor nativo → Expo Sharing
+
+### XLSX (Excel)
+- ❌ **Visor nativo**: No soportado
+- 📁 **Ubicación**: `documentDirectory` (iOS/Android)
+- 🔔 **Notificación**: Sí, con tap-to-share
+- 🔄 **Comportamiento**: Siempre usa Expo Sharing para abrir
+
+### JSON
+- ❌ **Visor nativo**: No soportado
+- 📁 **Ubicación**: `documentDirectory` (iOS/Android)
+- 🔔 **Notificación**: Sí, con tap-to-share
+- 🔄 **Comportamiento**: Siempre usa Expo Sharing para abrir
+
+## 🔄 Migración desde Código Legacy
+
+### Antes (xlsDownload.js)
+```javascript
+import { generateExcel } from 'utils/xlsDownload';
+
+await generateExcel(data, 'Reporte', dispatch);
+```
+
+### Ahora (FileDownloadManager)
+```javascript
+import { downloadExcel } from 'services/FileDownloadManager/adapter';
+
+await downloadExcel(data, 'Reporte', dispatch);
+```
+
+### Antes (DownloadFileService.js para PDF)
+```javascript
+import { download, downloadBase64, openDocument } from 'services/DownloadFileService';
+
+const path = await download(base64Data, fileName, downloadBase64);
+await openDocument(path);
+```
+
+### Ahora (FileDownloadManager)
+```javascript
+import { downloadPDF } from 'services/FileDownloadManager/adapter';
+
+await downloadPDF(base64Data, fileName, dispatch);
+// Auto-abre con visor nativo
+```
+
+## 🛠️ Configuración Requerida
+
+### App.tsx
+
+```typescript
+import * as Notifications from 'expo-notifications';
+
+Notifications.setNotificationHandler({
+  handleNotification: async () => ({
+    shouldPlaySound: false,
+    shouldSetBadge: false,
+    shouldShowBanner: true,
+    shouldShowList: true
+  })
+});
+```
+
+### AndroidManifest.xml
+
+```xml
+<queries>
+  <!-- PDF -->
+  <intent>
+    <action android:name="android.intent.action.VIEW" />
+    <data android:mimeType="application/pdf" />
+  </intent>
+  
+  <!-- Excel -->
+  <intent>
+    <action android:name="android.intent.action.VIEW" />
+    <data android:mimeType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" />
+  </intent>
+  
+  <!-- JSON -->
+  <intent>
+    <action android:name="android.intent.action.VIEW" />
+    <data android:mimeType="application/json" />
+  </intent>
+</queries>
+
+<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+```
+
+## 📦 Dependencias
+
+```json
+{
+  "expo-file-system": "^19.0.17",
+  "expo-notifications": "^0.32.12",
+  "expo-sharing": "^14.0.7",
+  "react-native-file-viewer": "^2.1.5",
+  "xlsx": "^0.18.5",
+  "dayjs": "^1.11.x",
+  "base-64": "^1.0.0"
+}
+```
+
+## 🎨 Personalización para @widergy/mobile-ui
+
+El módulo core (`index.js`) está diseñado para ser portable. Para migrarlo a `@widergy/mobile-ui`:
+
+1. **Copiar `index.js` y `types.js`** al paquete
+2. **Exportar** desde el index principal
+3. **Documentar** que los consumidores deben pasar `showSnackbar` en options
+4. **Ejemplo de uso** en el README del paquete:
+
+```javascript
+import { downloadFile, FILE_TYPES } from '@widergy/mobile-ui';
+
+// El consumidor maneja sus propias notificaciones
+const showSnackbar = (dispatch, type, error) => {
+  if (type === 'success') {
+    dispatch(showSuccess('Archivo descargado'));
+  } else {
+    dispatch(showError(error.message));
+  }
+};
+
+await downloadFile({
+  type: FILE_TYPES.PDF,
+  fileName: 'documento',
+  data: base64Content,
+  dispatch,
+  options: {
+    showSnackbar  // Inyección de dependencia
+  }
+});
+```
+
+## 🐛 Troubleshooting
+
+### "Unable to open URL: file://..."
+- **Causa**: iOS no puede abrir archivos file:// directamente
+- **Solución**: El módulo automáticamente usa Expo Sharing como fallback
+
+### "Expo FileSystem legacy no disponible"
+- **Causa**: Falta dependencia o versión incorrecta
+- **Solución**: `yarn add expo-file-system@^19.0.17`
+
+### Notificación se muestra pero no abre archivo
+- **Causa**: Listener de notificaciones no registrado
+- **Solución**: Verificar que `App.tsx` tenga configurado el `NotificationHandler`
+
+### PDF no se abre nativamente en Android
+- **Causa**: Falta query en AndroidManifest
+- **Solución**: Agregar los `<queries>` indicados arriba
+
+## 📝 TODO / Roadmap
+
+- [ ] Soporte para más formatos (DOC, CSV, etc.)
+- [ ] Progress callbacks para archivos grandes
+- [ ] Compresión opcional
+- [ ] Cache de archivos descargados
+- [ ] Tests unitarios
+- [ ] Integración con analytics
+
+## 📄 Licencia
+
+Parte del proyecto UtilityGO - Widergy

package/lib/components/FileDownloadManager/adapter.js

@@ -0,0 +1,118 @@
+// FileDownloadManager - Project adapter
+// Adapts the generic FileDownloadManager to work with this project's specific Redux patterns
+
+import { FILE_TYPES } from './types';
+
+import { downloadFile as coreDownloadFile, openFile } from './index';
+
+/**
+ * Show snackbar helper factory
+ * @param {Object} snackbarActions - Snackbar actions from the project
+ * @param {Object} translations - Translations object
+ */
+const createShowSnackbar =
+  (snackbarActions, translations) =>
+  (dispatch, type, error = null) => {
+    if (type === 'success') {
+      dispatch(snackbarActions.displayInfo(translations.successDownload));
+    } else if (type === 'error') {
+      dispatch(snackbarActions.displayError(error?.message || translations.errorDownload));
+    }
+  };
+
+/**
+ * Download Excel file from data array
+ * @param {Array} data - Array of objects to export
+ * @param {string} fileName - Base file name
+ * @param {Function} dispatch - Redux dispatch
+ * @param {Object} snackbarActions - Snackbar actions from the project
+ * @param {Object} translations - Custom translations (optional)
+ * @param {Object} options - Additional options
+ */
+export const downloadExcel = async (
+  data,
+  fileName,
+  dispatch,
+  snackbarActions,
+  translations = {},
+  options = {}
+) =>
+  coreDownloadFile({
+    type: FILE_TYPES.XLS,
+    fileName,
+    data,
+    dispatch,
+    translations,
+    options: {
+      ...options,
+      showSnackbar: createShowSnackbar(snackbarActions, translations)
+    }
+  });
+
+/**
+ * Download PDF from base64
+ * @param {string} base64 - PDF content in base64
+ * @param {string} fileName - Base file name
+ * @param {Function} dispatch - Redux dispatch
+ * @param {Object} snackbarActions - Snackbar actions from the project
+ * @param {Object} translations - Custom translations (optional)
+ * @param {Object} options - Additional options
+ */
+export const downloadPDF = async (
+  base64,
+  fileName,
+  dispatch,
+  snackbarActions,
+  translations = {},
+  options = {}
+) =>
+  coreDownloadFile({
+    type: FILE_TYPES.PDF,
+    fileName,
+    data: base64,
+    dispatch,
+    translations,
+    options: {
+      ...options,
+      showSnackbar: createShowSnackbar(snackbarActions, translations)
+    }
+  });
+
+/**
+ * Download JSON file from object
+ * @param {Object|Array} data - JSON data to export
+ * @param {string} fileName - Base file name
+ * @param {Function} dispatch - Redux dispatch
+ * @param {Object} snackbarActions - Snackbar actions from the project
+ * @param {Object} translations - Custom translations (optional)
+ * @param {Object} options - Additional options
+ */
+export const downloadJSON = async (
+  data,
+  fileName,
+  dispatch,
+  snackbarActions,
+  translations = {},
+  options = {}
+) =>
+  coreDownloadFile({
+    type: FILE_TYPES.JSON,
+    fileName,
+    data,
+    dispatch,
+    translations,
+    options: {
+      ...options,
+      showSnackbar: createShowSnackbar(snackbarActions, translations)
+    }
+  });
+
+export { openFile, FILE_TYPES };
+
+export default {
+  downloadExcel,
+  downloadPDF,
+  downloadJSON,
+  openFile,
+  FILE_TYPES
+};