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

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

@@ -0,0 +1,158 @@
+# useCardMultimediaFlashcard
+
+## Purpose
+Card-specific hook for creating and managing flashcards with media attachments using CardMediaAttachment types.
+
+## File Location
+`src/presentation/hooks/useCardMultimediaFlashcard.ts`
+
+## Strategy
+- Provide card-specific interface for flashcard creation with media
+- Support CardMediaAttachment with position-aware media management
+- Enable card-specific media operations (create, update, delete)
+- Automatically analyze card media composition
+- Calculate storage requirements for card media
+- Track download status for offline card access
+- Maintain card-specific ID prefixes and naming conventions
+
+## Forbidden
+- **DO NOT** create cards without required front/back content
+- **DO NOT** add media without position assignment (front, back, both)
+- **DO NOT** mix MediaAttachment with CardMediaAttachment types
+- **DO NOT** use mock implementations in production
+- **DO NOT** assume card media is downloaded without checking
+- **DO NOT** modify card structure directly after creation
+- **DO NOT** exceed practical media limits per card
+- **DO NOT** bypass media size estimation
+- **DO NOT** use incorrect ID prefixes (must use card_multimedia_)
+
+## Rules
+1. Always use CardMediaAttachment type (not MediaAttachment)
+2. Always assign position (front, back, both) to each media
+3. Use card_multimedia_ prefix for card IDs
+4. Calculate estimatedSize from all card media
+5. Populate mediaType array with unique types
+6. Set hasMedia based on media array length
+7. Check isDownloaded from all media attachments
+8. Support empty media array for text-only cards
+9. Return complete CardMultimediaFlashcard object
+10. Clear processing state on completion
+
+## AI Agent Guidelines
+
+When working with useCardMultimediaFlashcard hook:
+
+1. **Type Correctness**: Always use CardMediaAttachment (not MediaAttachment)
+2. **Position Assignment**: Every media must have position (front, back, both)
+3. **Media Upload**: Use useCardMediaUpload for proper type handling
+4. **Card Analysis**: Leverage auto-generated hasMedia, mediaType, isDownloaded
+5. **ID Prefixes**: Ensure card IDs use card_multimedia_ prefix
+
+### Card Creation Workflow
+
+1. Prepare card content (front, back, difficulty, tags)
+2. Upload media using useCardMediaUpload (gets CardMediaAttachment)
+3. Assign position to each media attachment
+4. Call createCardMultimedia with data
+5. Receive CardMultimediaFlashcard object
+6. Store or display the completed card
+
+### CardMultimediaFlashcard Structure
+
+CardMultimediaFlashcard includes:
+- id: Unique card ID (card_multimedia_ prefix)
+- front: Front side content
+- back: Back side content
+- difficulty: easy/medium/hard
+- tags: Topic tags array
+- media: Array of CardMediaAttachment
+- hasMedia: Boolean flag
+- mediaType: Array of media types (image, audio, video)
+- isDownloaded: Boolean (all media downloaded)
+- estimatedSize: Total size in bytes
+- createdAt: ISO timestamp
+
+### CardMediaAttachment vs MediaAttachment
+
+Key differences:
+- CardMediaAttachment has position property (front, back, both)
+- CardMediaAttachment IDs use card_media_ prefix
+- CardMediaAttachment uses CardMediaPosition enum
+- CardMediaAttachment uses CardMediaType enum
+
+### Media Positioning Strategy
+
+**front**: Media for front side of card
+- Question images
+- Prompt audio
+- Instructional videos
+
+**back**: Media for back side of card
+- Answer images
+- Explanation audio
+- Solution videos
+
+**both**: Media for both sides
+- Background music
+- Contextual images
+- Reference materials
+
+### Card Management Functions
+
+**createCardMultimedia**: Create new card
+- Requires front and back content
+- Accepts CardMediaAttachment array
+- Assigns unique card_multimedia_ ID
+- Analyzes media composition
+- Calculates storage requirements
+
+**updateCardMedia**: Replace media on card
+- Takes cardId and new media array
+- Preserves card metadata
+- Re-analyzes composition
+- Updates size calculation
+
+**deleteCardMedia**: Remove specific media
+- Takes attachmentId (card_media_ prefix)
+- Updates media array
+- Recalculates size
+- Updates analysis
+
+### Integration with Card Hooks
+
+Use with card-specific hooks:
+- useCardMediaUpload: Upload with CardMediaAttachment type
+- useCardMediaValidation: Validate with card-specific rules
+- useCardMediaGeneration: Generate AI media for cards
+
+### Card Media Analysis
+
+**hasMedia**: True if media array length > 0
+**mediaType**: Unique array ['image', 'audio', 'video'] based on media
+**isDownloaded**: True if all media.isDownloaded are true
+**estimatedSize**: Sum of all media.fileSize values
+
+### Performance Guidelines
+
+- Limit to 5-10 media items per card
+- Warn if estimatedSize exceeds 25 MB
+- Use position to organize media effectively
+- Consider download status for offline usage
+- Balance media types across card sides
+
+### Best Practices
+
+1. Always assign meaningful positions to media
+2. Use tags for card organization and filtering
+3. Set appropriate difficulty levels
+4. Balance media between front and back
+5. Consider offline usage patterns
+6. Validate media before adding to cards
+
+## Dependencies
+
+- CardMultimediaFlashcardService (infrastructure layer)
+- Domain types: CardMultimediaFlashcard, CardMediaAttachment
+- useCardMediaUpload (for card-specific upload)
+- useCardMediaValidation (for card-specific validation)
+- useCardMediaGeneration (for card AI media)

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)