@umituz/react-native-design-system 2.8.8 → 2.8.9

package/src/media/presentation/hooks/useCardMultimediaFlashcard.ts

@@ -0,0 +1,104 @@
+/**
+ * Card Multimedia Flashcard Hooks
+ * Main hook and exports for card multimedia functionality
+ */
+
+import React from "react";
+import {
+  calculateTotalSize,
+  extractMediaTypes,
+} from "../../infrastructure/utils/mediaHelpers";
+import type { UseCardMultimediaFlashcardResult } from "./card-multimedia.types";
+import type {
+  CardMediaAttachment,
+  CardMultimediaFlashcard,
+} from "../../domain/entities/CardMultimedia.types";
+
+// Export individual hooks
+export { useCardMediaUpload } from "./useCardMediaUpload";
+export { useCardMediaGeneration } from "./useCardMediaGeneration";
+export { useCardMediaValidation } from "./useCardMediaValidation";
+
+// Export types
+export type {
+  UseCardMediaUploadResult,
+  UseCardMediaGenerationResult,
+  UseCardMediaValidationResult,
+  UseCardMultimediaFlashcardResult,
+} from "./card-multimedia.types";
+
+/**
+ * Main hook for card multimedia flashcard operations
+ */
+export const useCardMultimediaFlashcard =
+  (): UseCardMultimediaFlashcardResult => {
+    const [isProcessing, setIsProcessing] = React.useState(false);
+    const [error, setError] = React.useState<string | null>(null);
+
+    const createCardMultimedia = React.useCallback(
+      async (cardData: any): Promise<CardMultimediaFlashcard> => {
+        try {
+          setIsProcessing(true);
+          setError(null);
+
+          // Simulate card creation
+          await new Promise((resolve) => setTimeout(resolve, 1000));
+
+          const card: CardMultimediaFlashcard = {
+            id: `card_multimedia_${Date.now()}`,
+            front: cardData.front || "",
+            back: cardData.back || "",
+            difficulty: cardData.difficulty || "medium",
+            tags: cardData.tags || [],
+            media: cardData.media || [],
+            hasMedia: (cardData.media || []).length > 0,
+            mediaType: extractMediaTypes(cardData.media || []),
+            isDownloaded: (cardData.media || []).every(
+              (m: any) => m.isDownloaded,
+            ),
+            estimatedSize: calculateTotalSize(cardData.media || []),
+            createdAt: new Date().toISOString(),
+          };
+
+          return card;
+        } catch (err) {
+          const errorMessage =
+            err instanceof Error ? err.message : "Card creation failed";
+          setError(errorMessage);
+          setIsProcessing(false);
+          throw err;
+        } finally {
+          setIsProcessing(false);
+        }
+      },
+      [],
+    );
+
+    const updateCardMedia = React.useCallback(
+      async (
+        cardId: string,
+        media: CardMediaAttachment[],
+      ): Promise<CardMultimediaFlashcard> => {
+        // Mock implementation
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        return {} as CardMultimediaFlashcard;
+      },
+      [],
+    );
+
+    const deleteCardMedia = React.useCallback(
+      async (attachmentId: string): Promise<void> => {
+        // Mock implementation
+        await new Promise((resolve) => setTimeout(resolve, 500));
+      },
+      [],
+    );
+
+    return {
+      createCardMultimedia,
+      updateCardMedia,
+      deleteCardMedia,
+      isProcessing,
+      error,
+    };
+  };

package/src/media/presentation/hooks/useMedia.README.md

@@ -0,0 +1,94 @@
+# useMedia
+
+## Purpose
+Core React hook for media selection operations (image/video picking, camera access) in React Native applications.
+
+## File Location
+`src/presentation/hooks/useMedia.ts`
+
+## Strategy
+- Provide unified interface for media picker and camera operations
+- Abstract expo-image-picker complexity from components
+- Centralize permission management logic
+- Maintain consistent state management across media operations
+- Enable type-safe media operations with proper TypeScript interfaces
+- Support single and multiple media selection workflows
+- Handle loading states and error propagation
+
+## Forbidden
+- **DO NOT** expose expo-image-picker implementation details to consumers
+- **DO NOT** automatically request permissions without explicit user action
+- **DO NOT** mix camera and library picker logic in single operations
+- **DO NOT** assume permission states - always check before operations
+- **DO NOT** bypass error handling or loading states
+- **DO NOT** use mock implementations in production without clear warnings
+- **DO NOT** allow operations while previous operation is in progress
+- **DO NOT** modify media assets after selection
+- **DO NOT** store selected media permanently in hook state
+
+## Rules
+1. Always check permission status before camera/library operations
+2. All picker operations must return MediaPickerResult with canceled flag
+3. Loading state must be true during async operations
+4. Error state must be cleared on new operation attempts
+5. Permission requests must be explicit, not automatic
+6. Selected media must be validated against type definitions
+7. Quality parameters must be in 0-1 range
+8. Aspect ratio must be [width, height] tuple
+9. File size must be included when available from picker
+10. Support both single and multiple selection based on function used
+
+## AI Agent Guidelines
+
+When working with useMedia hook:
+
+1. **Permission First**: Always request/check permissions before calling picker or camera functions
+2. **State Management**: Use isLoading to prevent duplicate operations during active calls
+3. **Error Handling**: Always check error state and handle user cancellation (canceled: true)
+4. **Type Safety**: Use MediaPickerOptions and CameraOptions interfaces for configuration
+5. **Validation**: Validate returned assets before processing (check if assets array exists)
+
+### Key Functions
+
+- **pickImage**: Single image selection from library with optional editing
+- **pickMultipleImages**: Multiple image selection with selection limit
+- **pickVideo**: Video selection from library
+- **launchCamera**: Photo capture via device camera
+- **launchCameraForVideo**: Video recording via device camera
+- **requestCameraPermission**: Request camera access permission
+- **requestMediaLibraryPermission**: Request photo library access permission
+- **getCameraPermissionStatus**: Check current camera permission state
+- **getMediaLibraryPermissionStatus**: Check current library permission state
+
+### Media Selection Workflow
+
+1. Check permission status before operation
+2. Request permission if not granted
+3. Call appropriate picker/camera function with options
+4. Check canceled flag before processing assets
+5. Validate assets array exists and has items
+6. Process first asset (or all for multiple selection)
+
+### Quality Guidelines
+
+- HIGH (1.0): Original quality, largest file size
+- MEDIUM (0.7): Balanced quality and size (recommended)
+- LOW (0.3): Smallest file size, reduced quality
+
+### Platform Requirements
+
+- **iOS**: Add NSCameraUsageDescription and NSPhotoLibraryUsageDescription to Info.plist
+- **Android**: Add CAMERA and READ_EXTERNAL_STORAGE permissions to AndroidManifest.xml
+
+### State Management
+
+- **isLoading**: True during any async picker/camera operation
+- **error**: String error message or null, cleared on new operations
+- **MediaPickerResult.canceled**: True when user cancels operation
+- **MediaPickerResult.assets**: Array of selected media or undefined
+
+## Dependencies
+
+- MediaPickerService (infrastructure layer)
+- Domain types: MediaAsset, MediaPickerResult, MediaPickerOptions, CameraOptions
+- expo-image-picker (via service layer)

package/src/media/presentation/hooks/useMedia.ts

@@ -0,0 +1,186 @@
+/**
+ * Media Domain - useMedia Hook
+ *
+ * React hook for media picking operations (images, videos).
+ * Provides camera, gallery picking functionality.
+ */
+
+import { useState, useCallback } from "react";
+import { MediaPickerService } from "../../infrastructure/services/MediaPickerService";
+import type {
+  MediaPickerOptions,
+  MediaPickerResult,
+  CameraOptions,
+} from "../../domain/entities/Media";
+import { MediaLibraryPermission } from "../../domain/entities/Media";
+
+/**
+ * useMedia hook for complete media workflow
+ *
+ * USAGE:
+ * ```typescript
+ * const {
+ *   pickImage,
+ *   pickMultipleImages,
+ *   launchCamera,
+ *   isLoading,
+ *   error,
+ * } = useMedia();
+ *
+ * const handlePickImage = async () => {
+ *   const result = await pickImage({ allowsEditing: true });
+ *   if (!result.canceled && result.assets) {
+ *     console.log('Picked:', result.assets[0].uri);
+ *   }
+ * };
+ * ```
+ */
+export const useMedia = () => {
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const pickImage = useCallback(
+    async (options?: MediaPickerOptions): Promise<MediaPickerResult> => {
+      setIsLoading(true);
+      setError(null);
+      try {
+        const result = await MediaPickerService.pickSingleImage(options);
+        return result;
+      } catch (err) {
+        const errorMessage =
+          err instanceof Error ? err.message : "Failed to pick image";
+        setError(errorMessage);
+        return { canceled: true };
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    []
+  );
+
+  const pickMultipleImages = useCallback(
+    async (options?: MediaPickerOptions): Promise<MediaPickerResult> => {
+      setIsLoading(true);
+      setError(null);
+      try {
+        const result = await MediaPickerService.pickMultipleImages(options);
+        return result;
+      } catch (err) {
+        const errorMessage =
+          err instanceof Error ? err.message : "Failed to pick images";
+        setError(errorMessage);
+        return { canceled: true };
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    []
+  );
+
+  const pickVideo = useCallback(
+    async (options?: MediaPickerOptions): Promise<MediaPickerResult> => {
+      setIsLoading(true);
+      setError(null);
+      try {
+        const result = await MediaPickerService.pickVideo(options);
+        return result;
+      } catch (err) {
+        const errorMessage =
+          err instanceof Error ? err.message : "Failed to pick video";
+        setError(errorMessage);
+        return { canceled: true };
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    []
+  );
+
+  const launchCamera = useCallback(
+    async (options?: CameraOptions): Promise<MediaPickerResult> => {
+      setIsLoading(true);
+      setError(null);
+      try {
+        const result = await MediaPickerService.launchCamera(options);
+        return result;
+      } catch (err) {
+        const errorMessage =
+          err instanceof Error ? err.message : "Failed to launch camera";
+        setError(errorMessage);
+        return { canceled: true };
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    []
+  );
+
+  const launchCameraForVideo = useCallback(
+    async (options?: CameraOptions): Promise<MediaPickerResult> => {
+      setIsLoading(true);
+      setError(null);
+      try {
+        const result = await MediaPickerService.launchCameraForVideo(options);
+        return result;
+      } catch (err) {
+        const errorMessage =
+          err instanceof Error ? err.message : "Failed to record video";
+        setError(errorMessage);
+        return { canceled: true };
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    []
+  );
+
+  const requestCameraPermission =
+    useCallback(async (): Promise<MediaLibraryPermission> => {
+      try {
+        return await MediaPickerService.requestCameraPermission();
+      } catch {
+        return MediaLibraryPermission.DENIED;
+      }
+    }, []);
+
+  const requestMediaLibraryPermission =
+    useCallback(async (): Promise<MediaLibraryPermission> => {
+      try {
+        return await MediaPickerService.requestMediaLibraryPermission();
+      } catch {
+        return MediaLibraryPermission.DENIED;
+      }
+    }, []);
+
+  const getCameraPermissionStatus =
+    useCallback(async (): Promise<MediaLibraryPermission> => {
+      try {
+        return await MediaPickerService.getCameraPermissionStatus();
+      } catch {
+        return MediaLibraryPermission.DENIED;
+      }
+    }, []);
+
+  const getMediaLibraryPermissionStatus =
+    useCallback(async (): Promise<MediaLibraryPermission> => {
+      try {
+        return await MediaPickerService.getMediaLibraryPermissionStatus();
+      } catch {
+        return MediaLibraryPermission.DENIED;
+      }
+    }, []);
+
+  return {
+    pickImage,
+    pickMultipleImages,
+    pickVideo,
+    launchCamera,
+    launchCameraForVideo,
+    requestCameraPermission,
+    requestMediaLibraryPermission,
+    getCameraPermissionStatus,
+    getMediaLibraryPermissionStatus,
+    isLoading,
+    error,
+  };
+};

package/src/media/presentation/hooks/useMediaGeneration.README.md

@@ -0,0 +1,118 @@
+# useMediaGeneration
+
+## Purpose
+React hook for AI-powered media generation (text-to-image, text-to-audio) with result tracking.
+
+## File Location
+`src/presentation/hooks/useMediaGeneration.ts`
+
+## Strategy
+- Provide unified interface for AI media generation operations
+- Support multiple generation types (text-to-image, text-to-audio)
+- Track generation status and progress
+- Manage credit usage and balance tracking
+- Handle generation errors gracefully
+- Return structured results with metadata
+- Support customizable generation options
+
+## Forbidden
+- **DO NOT** start new generation while previous is in progress
+- **DO NOT** ignore credit costs before generation
+- **DO NOT** mock generation process in production without API integration
+- **DO NOT** assume generation will succeed - always check result.success
+- **DO NOT** expose API keys or AI service implementation details
+- **DO NOT** allow unlimited concurrent generations
+- **DO NOT** bypass generation timeout handling
+- **DO NOT** store large generation results permanently in hook state
+- **DO NOT** use empty or invalid prompts for generation
+
+## Rules
+1. Always validate prompt text before generation
+2. Check credit availability before generation operations
+3. Track processing time for each generation request
+4. Return unique requestId for each generation
+5. Support maxResults parameter for multiple outputs
+6. Generation state must be cleared on new operations
+7. Include creditsUsed in result metadata
+8. Handle both success and failure in result object
+9. Support language and voice options for audio generation
+10. Support style options for image generation
+
+## AI Agent Guidelines
+
+When working with useMediaGeneration hook:
+
+1. **Prompt Quality**: Use descriptive, specific prompts for better results
+2. **Credit Management**: Track credit costs and balance before operations
+3. **Error Handling**: Always check result.success field
+4. **Result Processing**: Validate attachments array before use
+5. **Options**: Use appropriate options for generation type
+
+### Generation Types
+
+**Text-to-Image** (type: 'text_to_image')
+- Generates images from text descriptions
+- Credit cost: 5 per generation
+- Default maxResults: 1
+- Supports style customization
+
+**Text-to-Audio** (type: 'text_to_audio')
+- Generates audio from text (text-to-speech)
+- Credit cost: 3 per generation
+- Default duration: 10 seconds
+- Supports voice, language, speed options
+
+### Generation Workflow
+
+1. Validate prompt text quality and length
+2. Check available credits
+3. Configure generation options
+4. Call generateMedia with request
+5. Monitor isGenerating state
+6. Process generationResult on completion
+7. Handle errors with user feedback
+
+### Result Structure
+
+GenerationResult includes:
+- success: Boolean indicating success/failure
+- attachments: Array of generated MediaAttachment
+- creditsUsed: Number of credits consumed
+- processingTime: Duration in milliseconds
+- requestId: Unique request identifier
+- error: Error message if failed
+
+### Generation Options
+
+**Image Options:**
+- maxResults: Number of images to generate (default: 1)
+- style: Image style preset
+
+**Audio Options:**
+- voice: Voice type (male/female)
+- language: Language code (e.g., 'tr-TR', 'en-US')
+- speed: Playback speed (default: 1.0)
+
+### Integration Requirements
+
+- Configure AI API endpoints
+- Implement authentication for AI services
+- Handle rate limiting and quotas
+- Implement retry logic for failed generations
+- Cache generation results when appropriate
+- Monitor credit balance and usage
+
+### Error Scenarios
+
+- Insufficient credits: Check balance before generation
+- Invalid prompt: Validate text quality and length
+- API timeout: Implement retry with exponential backoff
+- Content policy violations: Filter and validate prompts
+- Service unavailable: Graceful degradation with error message
+
+## Dependencies
+
+- MediaGenerationService (infrastructure layer)
+- Domain types: MediaGenerationRequest, MediaGenerationResult, MediaAttachment
+- Credit/balance tracking system
+- AI service APIs (text-to-image, text-to-speech)

package/src/media/presentation/hooks/useMediaGeneration.ts

@@ -0,0 +1,101 @@
+/**
+ * Media Generation Hook
+ * Hook for generating media with AI
+ */
+
+import React from "react";
+import type { UseMediaGenerationResult } from "./multimedia.types";
+import type {
+  MediaAttachment,
+  MediaGenerationRequest,
+  MediaGenerationResult,
+} from "../../domain/entities/MultimediaFlashcardTypes";
+
+export const useMediaGeneration = (): UseMediaGenerationResult => {
+  const [isGenerating, setIsGenerating] = React.useState(false);
+  const [generationResult, setGenerationResult] =
+    React.useState<MediaGenerationResult | null>(null);
+  const [error, setError] = React.useState<string | null>(null);
+
+  const generateMedia = React.useCallback(
+    async (request: MediaGenerationRequest): Promise<MediaGenerationResult> => {
+      try {
+        setIsGenerating(true);
+        setError(null);
+
+        // Simulate generation
+        await new Promise((resolve) => setTimeout(resolve, 3000));
+
+        const attachments: MediaAttachment[] = [];
+
+        switch (request.type) {
+          case "text_to_image":
+            for (let i = 0; i < (request.options.maxResults || 1); i++) {
+              attachments.push({
+                id: `ai_img_${Date.now()}_${i}`,
+                type: "image",
+                position: "both",
+                url: `https://picsum.photos/400/300?random=${Date.now() + i}`,
+                filename: `ai_generated_${i}.jpg`,
+                fileSize: 150000, // 150KB
+                mimeType: "image/jpeg",
+                isDownloaded: false,
+                createdAt: new Date().toISOString(),
+              });
+            }
+            break;
+
+          case "text_to_audio":
+            attachments.push({
+              id: `ai_audio_${Date.now()}`,
+              type: "audio",
+              position: "back",
+              url: `https://example.com/audio_${Date.now()}.mp3`,
+              filename: `ai_generated_${Date.now()}.mp3`,
+              fileSize: 80000, // 80KB
+              mimeType: "audio/mp3",
+              duration: 10, // 10 seconds
+              isDownloaded: false,
+              createdAt: new Date().toISOString(),
+            });
+            break;
+        }
+
+        const result: MediaGenerationResult = {
+          success: true,
+          attachments,
+          creditsUsed: request.type === "text_to_image" ? 5 : 3,
+          processingTime: 3000,
+          requestId: `req_${Date.now()}`,
+        };
+
+        setGenerationResult(result);
+        return result;
+      } catch (err) {
+        const errorMessage =
+          err instanceof Error ? err.message : "Generation failed";
+        setError(errorMessage);
+        setIsGenerating(false);
+
+        return {
+          success: false,
+          attachments: [],
+          creditsUsed: 0,
+          processingTime: 0,
+          error: errorMessage,
+          requestId: "",
+        };
+      } finally {
+        setIsGenerating(false);
+      }
+    },
+    [],
+  );
+
+  return {
+    generateMedia,
+    isGenerating,
+    generationResult,
+    error,
+  };
+};