@umituz/react-native-design-system 2.3.14 → 2.3.16

package/src/utilities/sharing/index.ts

@@ -0,0 +1,205 @@
+/**
+ * Sharing Domain - Barrel Export
+ *
+ * Provides system share sheet functionality using expo-sharing.
+ * Optional domain - disabled by default (opt-in).
+ *
+ * @domain sharing
+ * @enabled false (Apps that need file sharing - Opt-in)
+ *
+ * ARCHITECTURE:
+ * - Domain Layer: Entities (share types, MIME types, utilities)
+ * - Infrastructure Layer: Services (SharingService)
+ * - Presentation Layer: Hooks (useSharing)
+ *
+ * DEPENDENCIES:
+ * - expo-sharing (system share sheet)
+ *
+ * FEATURES:
+ * - Share files via system share sheet
+ * - Automatic MIME type detection
+ * - Platform-specific options (UTI for iOS, dialogTitle for Android)
+ * - Share availability check
+ * - Multiple file sharing (sequential)
+ *
+ * USAGE:
+ *
+ * Basic Sharing:
+ * ```typescript
+ * import { useSharing } from '@umituz/react-native-sharing';
+ *
+ * const { share, isAvailable, isSharing } = useSharing();
+ *
+ * if (!isAvailable) {
+ *   return <Text>Sharing not available</Text>;
+ * }
+ *
+ * const handleShare = async () => {
+ *   const success = await share('file:///path/to/file.jpg', {
+ *     dialogTitle: 'Share Photo',
+ *     mimeType: 'image/jpeg',
+ *   });
+ *
+ *   if (success) {
+ *     console.log('Shared successfully');
+ *   }
+ * };
+ *
+ * <AtomicButton onPress={handleShare} loading={isSharing}>
+ *   Share
+ * </AtomicButton>
+ * ```
+ *
+ * Auto-Detect MIME Type:
+ * ```typescript
+ * import { useSharing } from '@umituz/react-native-sharing';
+ *
+ * const { shareWithAutoType } = useSharing();
+ *
+ * // MIME type auto-detected from .pdf extension
+ * await shareWithAutoType(
+ *   'file:///path/to/document.pdf',
+ *   'document.pdf',
+ *   'Share Document'
+ * );
+ *
+ * // MIME type auto-detected from .jpg extension
+ * await shareWithAutoType(
+ *   'file:///path/to/photo.jpg',
+ *   'photo.jpg',
+ *   'Share Photo'
+ * );
+ * ```
+ *
+ * Share with media Integration:
+ * ```typescript
+ * import { useMedia } from '@umituz/react-native-media';
+ * import { useSharing } from '@umituz/react-native-sharing';
+ * import { FileSystemService } from '@umituz/react-native-filesystem';
+ *
+ * const { pickImage } = useMedia();
+ * const { shareWithAutoType } = useSharing();
+ *
+ * const handlePickAndShare = async () => {
+ *   // Pick image
+ *   const result = await pickImage();
+ *   if (result.canceled || !result.assets?.[0]?.uri) return;
+ *
+ *   // Save to filesystem
+ *   const savedPath = await FileSystemService.copyToDocuments(
+ *     result.assets[0].uri,
+ *     'shared_image.jpg'
+ *   );
+ *
+ *   if (!savedPath.success || !savedPath.uri) return;
+ *
+ *   // Share via system sheet
+ *   await shareWithAutoType(savedPath.uri, 'shared_image.jpg', 'Share Photo');
+ * };
+ * ```
+ *
+ * Share Multiple Files:
+ * ```typescript
+ * import { useSharing } from '@umituz/react-native-sharing';
+ *
+ * const { shareMultiple } = useSharing();
+ *
+ * const handleShareMultiple = async () => {
+ *   const uris = [
+ *     'file:///path/to/file1.jpg',
+ *     'file:///path/to/file2.jpg',
+ *     'file:///path/to/file3.jpg',
+ *   ];
+ *
+ *   await shareMultiple(uris, {
+ *     dialogTitle: 'Share Photos',
+ *     mimeType: 'image/jpeg',
+ *   });
+ * };
+ * ```
+ *
+ * MIME Type Utilities:
+ * ```typescript
+ * import { SharingUtils, MIME_TYPES } from '@umituz/react-native-sharing';
+ *
+ * // Get MIME type from extension
+ * const mimeType = SharingUtils.getMimeTypeFromExtension('document.pdf');
+ * // Returns: 'application/pdf'
+ *
+ * // Get UTI for iOS
+ * const uti = SharingUtils.getUTIFromExtension('photo.jpg');
+ * // Returns: 'public.jpeg'
+ *
+ * // Prepare full options
+ * const options = SharingUtils.prepareShareOptions('file.pdf', 'Share Document');
+ * // Returns: { dialogTitle, mimeType, UTI }
+ *
+ * // Use predefined MIME types
+ * await share(uri, { mimeType: MIME_TYPES.PDF });
+ * await share(uri, { mimeType: MIME_TYPES.IMAGE_JPEG });
+ * await share(uri, { mimeType: MIME_TYPES.VIDEO_MP4 });
+ * ```
+ *
+ * Direct Service Usage (Rare):
+ * ```typescript
+ * import { SharingService } from '@umituz/react-native-sharing';
+ *
+ * // Check availability
+ * const isAvailable = await SharingService.isAvailable();
+ *
+ * // Share file
+ * const result = await SharingService.shareFile(uri, options);
+ * if (result.success) {
+ *   console.log('Shared');
+ * } else {
+ *   console.error(result.error);
+ * }
+ * ```
+ *
+ * BENEFITS:
+ * - Native system share sheet (OS-provided UI)
+ * - Automatic MIME type detection from filename
+ * - Platform-specific options (iOS UTI, Android dialogTitle)
+ * - Share availability check before attempting
+ * - Type-safe share operations
+ * - Error handling with state management
+ * - Works with all file types
+ *
+ * USE CASES:
+ * - Share photos/videos from gallery
+ * - Export reports/documents
+ * - Share app-generated content
+ * - Social media sharing
+ * - File backup/export
+ * - Collaborative file sharing
+ *
+ * @see https://docs.expo.dev/versions/latest/sdk/sharing/
+ */
+
+// ============================================================================
+// DOMAIN LAYER - ENTITIES
+// ============================================================================
+
+export type {
+  ShareOptions,
+  ShareResult,
+} from './domain/entities/Share';
+
+export {
+  MIME_TYPES,
+  UTI_TYPES,
+  SHARING_CONSTANTS,
+  SharingUtils,
+} from './domain/entities/Share';
+
+// ============================================================================
+// INFRASTRUCTURE LAYER - SERVICES
+// ============================================================================
+
+export { SharingService } from './infrastructure/services/SharingService';
+
+// ============================================================================
+// PRESENTATION LAYER - HOOKS
+// ============================================================================
+
+export { useSharing } from './presentation/hooks/useSharing';

package/src/utilities/sharing/infrastructure/services/SharingService.ts

@@ -0,0 +1,165 @@
+/**
+ * Sharing Domain - Sharing Service
+ *
+ * Service for sharing files using expo-sharing.
+ * Provides abstraction layer for system share sheet.
+ *
+ * @domain sharing
+ * @layer infrastructure/services
+ */
+
+import * as Sharing from 'expo-sharing';
+import * as FileSystem from 'expo-file-system/legacy';
+import type { ShareOptions, ShareResult } from '../../domain/entities/Share';
+import { SharingUtils } from '../../domain/entities/Share';
+
+/**
+ * Sharing service for sharing files via system share sheet
+ */
+export class SharingService {
+  /**
+   * Check if sharing is available on device
+   */
+  static async isAvailable(): Promise<boolean> {
+    try {
+      return await Sharing.isAvailableAsync();
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Share a file via system share sheet
+   *
+   * @param uri - File URI to share (can be local or remote http/https)
+   * @param options - Share options (dialog title, MIME type, UTI)
+   * @returns ShareResult with success status
+   *
+   * USAGE:
+   * ```typescript
+   * // Basic share (local)
+   * await SharingService.shareFile('file:///path/to/image.jpg');
+   *
+   * // Remote file (will be downloaded)
+   * await SharingService.shareFile('https://example.com/image.jpg');
+   * ```
+   */
+  static async shareFile(uri: string, options?: ShareOptions): Promise<ShareResult> {
+    try {
+      // Check availability
+      const available = await SharingService.isAvailable();
+      if (!available) {
+        return {
+          success: false,
+          error: 'Sharing is not available on this device',
+        };
+      }
+
+      let shareUri = uri;
+
+      // Handle remote URLs
+      if (uri.startsWith('http://') || uri.startsWith('https://')) {
+        try {
+          const filename = uri.split('/').pop()?.split('?')[0] || `share-${Date.now()}`;
+          // Ensure we have an extension if possible, or default to bin/jpg? 
+          // Better to rely on what we have, or let the caller specify mimeType to infer extension?
+          // For now, nice and simple:
+          const localUri = `${FileSystem.cacheDirectory}${filename}`;
+          const { uri: downloadedUri, status } = await FileSystem.downloadAsync(uri, localUri);
+
+          if (status !== 200) {
+            return { success: false, error: `Failed to download file: ${status}` };
+          }
+          shareUri = downloadedUri;
+        } catch (downloadError) {
+          return {
+            success: false,
+            error: downloadError instanceof Error ? downloadError.message : 'Failed to download file'
+          };
+        }
+      }
+
+      // Share file
+      await Sharing.shareAsync(shareUri, options);
+
+      return { success: true };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Failed to share file',
+      };
+    }
+  }
+
+  /**
+   * Share a file with automatic MIME type detection
+   *
+   * @param uri - File URI to share
+   * @param filename - Filename (used for MIME type detection)
+   * @param dialogTitle - Optional dialog title (Android)
+   * @returns ShareResult with success status
+   *
+   * USAGE:
+   * ```typescript
+   * // Auto-detect MIME type from filename
+   * await SharingService.shareWithAutoType(
+   *   'file:///path/to/file.jpg',
+   *   'photo.jpg',
+   *   'Share Photo'
+   * );
+   * ```
+   */
+  static async shareWithAutoType(
+    uri: string,
+    filename: string,
+    dialogTitle?: string
+  ): Promise<ShareResult> {
+    const options = SharingUtils.prepareShareOptions(filename, dialogTitle);
+    return await SharingService.shareFile(uri, options);
+  }
+
+  /**
+   * Share multiple files (if supported)
+   *
+   * NOTE: expo-sharing currently only supports sharing one file at a time.
+   * This method shares files sequentially.
+   *
+   * @param uris - Array of file URIs to share
+   * @param options - Share options
+   * @returns ShareResult with success status
+   */
+  static async shareMultipleFiles(
+    uris: string[],
+    options?: ShareOptions
+  ): Promise<ShareResult> {
+    try {
+      if (uris.length === 0) {
+        return {
+          success: false,
+          error: 'No files to share',
+        };
+      }
+
+      // Check availability
+      const available = await SharingService.isAvailable();
+      if (!available) {
+        return {
+          success: false,
+          error: 'Sharing is not available on this device',
+        };
+      }
+
+      // Share files sequentially
+      for (const uri of uris) {
+        await Sharing.shareAsync(uri, options);
+      }
+
+      return { success: true };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Failed to share files',
+      };
+    }
+  }
+}

package/src/utilities/sharing/presentation/hooks/useSharing.ts

@@ -0,0 +1,154 @@
+/**
+ * Sharing Domain - useSharing Hook
+ *
+ * React hook for sharing files.
+ * Provides system share sheet functionality with state management.
+ *
+ * @domain sharing
+ * @layer presentation/hooks
+ */
+
+import { useState, useCallback, useEffect } from 'react';
+import { SharingService } from '../../infrastructure/services/SharingService';
+import type { ShareOptions } from '../../domain/entities/Share';
+
+/**
+ * useSharing hook for sharing files via system share sheet
+ *
+ * USAGE:
+ * ```typescript
+ * const { share, shareWithAutoType, isAvailable, isSharing } = useSharing();
+ *
+ * // Check availability
+ * if (!isAvailable) {
+ *   return <Text>Sharing not available</Text>;
+ * }
+ *
+ * // Basic share
+ * const handleShare = async () => {
+ *   await share('file:///path/to/file.jpg', {
+ *     dialogTitle: 'Share Photo',
+ *     mimeType: 'image/jpeg',
+ *   });
+ * };
+ *
+ * // Auto-detect MIME type
+ * const handleShareAuto = async () => {
+ *   await shareWithAutoType(
+ *     'file:///path/to/document.pdf',
+ *     'document.pdf',
+ *     'Share Document'
+ *   );
+ * };
+ * ```
+ */
+export const useSharing = () => {
+  const [isAvailable, setIsAvailable] = useState(false);
+  const [isSharing, setIsSharing] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  /**
+   * Check sharing availability on mount
+   */
+  useEffect(() => {
+    const checkAvailability = async () => {
+      const available = await SharingService.isAvailable();
+      setIsAvailable(available);
+    };
+
+    checkAvailability();
+  }, []);
+
+  /**
+   * Share a file via system share sheet
+   */
+  const share = useCallback(async (uri: string, options?: ShareOptions): Promise<boolean> => {
+    setIsSharing(true);
+    setError(null);
+
+    try {
+      const result = await SharingService.shareFile(uri, options);
+
+      if (!result.success) {
+        setError(result.error || 'Failed to share file');
+        return false;
+      }
+
+      return true;
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : 'Failed to share file';
+      setError(errorMessage);
+      return false;
+    } finally {
+      setIsSharing(false);
+    }
+  }, []);
+
+  /**
+   * Share file with automatic MIME type detection
+   */
+  const shareWithAutoType = useCallback(
+    async (uri: string, filename: string, dialogTitle?: string): Promise<boolean> => {
+      setIsSharing(true);
+      setError(null);
+
+      try {
+        const result = await SharingService.shareWithAutoType(uri, filename, dialogTitle);
+
+        if (!result.success) {
+          setError(result.error || 'Failed to share file');
+          return false;
+        }
+
+        return true;
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : 'Failed to share file';
+        setError(errorMessage);
+        return false;
+      } finally {
+        setIsSharing(false);
+      }
+    },
+    []
+  );
+
+  /**
+   * Share multiple files
+   */
+  const shareMultiple = useCallback(
+    async (uris: string[], options?: ShareOptions): Promise<boolean> => {
+      setIsSharing(true);
+      setError(null);
+
+      try {
+        const result = await SharingService.shareMultipleFiles(uris, options);
+
+        if (!result.success) {
+          setError(result.error || 'Failed to share files');
+          return false;
+        }
+
+        return true;
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : 'Failed to share files';
+        setError(errorMessage);
+        return false;
+      } finally {
+        setIsSharing(false);
+      }
+    },
+    []
+  );
+
+  return {
+    // Functions
+    share,
+    shareWithAutoType,
+    shareMultiple,
+
+    // State
+    isAvailable,
+    isSharing,
+    error,
+  };
+};