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

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,
+  };
+};

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

@@ -0,0 +1,108 @@
+# useMediaUpload
+
+## Purpose
+React hook for uploading media files to server with progress tracking and compression support.
+
+## File Location
+`src/presentation/hooks/useMediaUpload.ts`
+
+## Strategy
+- Provide unified media upload interface with progress tracking
+- Support compression options to optimize file sizes before upload
+- Track upload progress with percentage and status updates
+- Handle upload errors gracefully with proper error propagation
+- Maintain loading state to prevent duplicate uploads
+- Support various media types (image, video, audio)
+- Generate automatic thumbnails for media files
+
+## Forbidden
+- **DO NOT** start new upload while previous upload is in progress
+- **DO NOT** ignore compression options - always apply before upload
+- **DO NOT** upload files without validation (use useMediaValidation first)
+- **DO NOT** mock upload process in production without integration
+- **DO NOT** modify file during upload (compression happens before)
+- **DO NOT** assume upload will succeed - always handle errors
+- **DO NOT** use hardcoded API endpoints - must be configurable
+- **DO NOT** bypass progress tracking for async uploads
+- **DO NOT** store upload results permanently in hook state
+
+## Rules
+1. Always validate files before uploading (use useMediaValidation hook)
+2. Compression quality must be in 0-1 range
+3. Dimensions must be in pixels (maxWidth, maxHeight)
+4. Progress updates must be emitted every 10% or on status change
+5. Upload state must be cleared on error or completion
+6. Return complete MediaAttachment object on success
+7. Generate thumbnail URL automatically for visual media
+8. Calculate duration for audio/video files
+9. Update progress status: uploading -> completed or error
+10. Include unique fileId in progress tracking
+
+## AI Agent Guidelines
+
+When working with useMediaUpload hook:
+
+1. **Pre-upload Validation**: Always use useMediaValidation before calling uploadMedia
+2. **Progress Tracking**: Monitor uploadProgress state for real-time updates
+3. **Compression**: Apply appropriate compression based on use case
+4. **Error Recovery**: Handle upload errors and allow retry logic
+5. **File Size**: Consider file size when choosing compression settings
+
+### Upload Workflow
+
+1. Validate file with useMediaValidation hook
+2. Select compression options based on file type and size
+3. Call uploadMedia with file and options
+4. Monitor uploadProgress for status updates
+5. Handle completion (success or error)
+6. Process returned MediaAttachment object
+
+### Compression Guidelines
+
+**High Quality** (quality: 0.9, maxWidth: 4096)
+- Use for professional photos, detailed graphics
+- Larger file size, best quality
+
+**Medium Quality** (quality: 0.7, maxWidth: 1920) - RECOMMENDED
+- Balanced quality and size
+- Good for most use cases
+
+**Low Quality** (quality: 0.5, maxWidth: 1280)
+- Use for thumbnails, previews
+- Smallest file size, reduced quality
+
+### Upload Progress States
+
+- **uploading**: Upload in progress, progress 0-99%
+- **completed**: Upload finished successfully, progress 100%
+- **error**: Upload failed, error message available
+
+### MediaAttachment Structure
+
+Returned object includes:
+- id: Unique identifier
+- url: Uploaded file URL
+- type: MediaType (IMAGE, VIDEO, AUDIO)
+- position: MediaPosition (front, back, both)
+- filename: Original filename
+- fileSize: Size in bytes
+- mimeType: MIME type string
+- duration: Audio/video duration in seconds
+- thumbnailUrl: Thumbnail URL for visual media
+- caption: Optional caption text
+- isDownloaded: Download status flag
+- createdAt: ISO timestamp
+
+### Integration Requirements
+
+- Configure API endpoint for upload service
+- Implement actual upload logic in MediaUploadService
+- Handle authentication tokens for uploads
+- Support retry logic for failed uploads
+- Implement timeout handling for large files
+
+## Dependencies
+
+- MediaUploadService (infrastructure layer)
+- Domain types: MediaAttachment, MediaCompressionOptions, MediaUploadProgress
+- useMediaValidation (for pre-upload validation)

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

@@ -0,0 +1,86 @@
+/**
+ * Media Upload Hook
+ * Hook for uploading media files
+ */
+
+import React from "react";
+import {
+  generateThumbnail,
+  getMediaDuration,
+  getMediaType,
+} from "../../infrastructure/utils/mediaHelpers";
+import type { UseMediaUploadResult } from "./multimedia.types";
+import type {
+  MediaAttachment,
+  MediaCompressionOptions,
+  MediaUploadProgress,
+} from "../../domain/entities/MultimediaFlashcardTypes";
+
+export const useMediaUpload = (): UseMediaUploadResult => {
+  const [isUploading, setIsUploading] = React.useState(false);
+  const [uploadProgress, setUploadProgress] =
+    React.useState<MediaUploadProgress | null>(null);
+  const [error, setError] = React.useState<string | null>(null);
+
+  const uploadMedia = React.useCallback(
+    async (file: any, options?: MediaCompressionOptions) => {
+      try {
+        setIsUploading(true);
+        setError(null);
+
+        // Simulate upload progress
+        setUploadProgress({
+          fileId: `upload_${Date.now()}`,
+          progress: 0,
+          status: "uploading",
+        });
+
+        // Simulate progress updates
+        for (let i = 1; i <= 100; i += 10) {
+          await new Promise((resolve) => setTimeout(resolve, 100));
+          setUploadProgress((prev) => (prev ? { ...prev, progress: i } : null));
+        }
+
+        const attachment: MediaAttachment = {
+          id: `media_${Date.now()}`,
+          type: getMediaType(file.type),
+          position: "both",
+          url: `https://storage.example.com/media/${Date.now()}_${file.name}`,
+          filename: file.name,
+          fileSize: file.size || 100000,
+          mimeType: file.type,
+          duration: await getMediaDuration(file),
+          thumbnailUrl: generateThumbnail(file),
+          caption: "",
+          isDownloaded: true,
+          createdAt: new Date().toISOString(),
+        };
+
+        setUploadProgress({
+          fileId: `upload_${Date.now()}`,
+          progress: 100,
+          status: "completed",
+          url: attachment.url,
+        });
+
+        return attachment;
+      } catch (err) {
+        const errorMessage =
+          err instanceof Error ? err.message : "Upload failed";
+        setError(errorMessage);
+        setIsUploading(false);
+        throw err;
+      } finally {
+        setIsUploading(false);
+      }
+    },
+    [],
+  );
+
+  return {
+    uploadMedia,
+    isUploading,
+    uploadProgress,
+    error,
+  };
+};

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

@@ -0,0 +1,134 @@
+# useMediaValidation
+
+## Purpose
+React hook for validating media files before upload, checking file size, type, and providing improvement recommendations.
+
+## File Location
+`src/presentation/hooks/useMediaValidation.ts`
+
+## Strategy
+- Provide comprehensive media file validation before upload
+- Check file size limits with appropriate warnings
+- Validate MIME types against supported formats
+- Provide three-tier feedback: errors (blocking), warnings (performance), recommendations (improvements)
+- Support validation state management
+- Enable pre-upload validation workflow
+- Return actionable feedback for each validation issue
+
+## Forbidden
+- **DO NOT** upload files that fail validation (errors present)
+- **DO NOT** ignore warnings - they indicate performance issues
+- **DO NOT** bypass file type validation
+- **DO NOT** use mock validation in production
+- **DO NOT** allow files exceeding maximum size limits
+- **DO NOT** modify file during validation process
+- **DO NOT** store validation results permanently in hook state
+- **DO NOT** validate empty or missing files
+- **DO NOT** suppress validation errors for user convenience
+
+## Rules
+1. Always validate before upload operations
+2. Files over 50 MB must be rejected with error
+3. Files over 10 MB must trigger warning and recommendation
+4. Unsupported MIME types must be rejected
+5. Validation must check file size, type, and format
+6. Return errors array for blocking issues
+7. Return warnings array for performance concerns
+8. Return recommendations array for improvements
+9. Clear validation state on new validation requests
+10. Support synchronous and asynchronous validation
+
+## AI Agent Guidelines
+
+When working with useMediaValidation hook:
+
+1. **Pre-upload Check**: Always validate before useMediaUpload calls
+2. **Three-Tier Feedback**: Distinguish between errors, warnings, recommendations
+3. **User Decision**: Show warnings but allow user to proceed
+4. **File Size**: Be strict with maximum limits, flexible with warnings
+5. **Type Safety**: Validate MIME types against supported formats
+
+### Validation Levels
+
+**Errors** (Blocking - Must fix before upload):
+- File size exceeds 50 MB
+- Unsupported file type
+- Invalid file format
+- Missing required properties
+
+**Warnings** (Performance - Should fix but can proceed):
+- File size over 10 MB (performance impact)
+- Large dimensions (may need optimization)
+- Non-standard format (compatibility issues)
+
+**Recommendations** (Improvements - Optional suggestions):
+- Reduce file size for better performance
+- Use recommended format (JPEG for images, MP4 for video)
+- Optimize dimensions for target use case
+- Compress to balance quality and size
+
+### Supported File Types
+
+**Images:**
+- image/jpeg (JPEG photos)
+- image/png (PNG graphics with transparency)
+- image/webp (WebP format)
+
+**Audio:**
+- audio/mp3 (MP3 compressed audio)
+- audio/wav (WAV uncompressed audio)
+- audio/m4a (M4A audio format)
+
+**Video:**
+- video/mp4 (MP4 video)
+- video/mov (QuickTime video)
+
+### Validation Workflow
+
+1. Receive file object with name, type, size, uri
+2. Check file size against limits (50 MB max, 10 MB warning)
+3. Validate MIME type against supported formats
+4. Generate appropriate errors, warnings, recommendations
+5. Return MediaValidation object with results
+6. Display feedback to user for action
+
+### Validation State Management
+
+- isValid: Boolean (true if no errors)
+- errors: String array (blocking issues)
+- warnings: String array (performance concerns)
+- recommendations: String array (improvement suggestions)
+
+### Integration with Upload Flow
+
+Typical validation-upload workflow:
+1. Select file from picker or file system
+2. Call validateMedia(file)
+3. Check validation.isValid
+4. If errors: Show to user, block upload
+5. If warnings: Show to user, ask confirmation
+6. If recommendations: Show to user for reference
+7. Proceed to upload if no errors or user confirms warnings
+
+### File Size Guidelines
+
+**Images:**
+- Optimal: Under 2 MB
+- Warning: 2-10 MB
+- Error: Over 50 MB
+
+**Audio:**
+- Optimal: Under 5 MB
+- Warning: 5-10 MB
+- Error: Over 50 MB
+
+**Video:**
+- Optimal: Under 10 MB
+- Warning: 10-50 MB
+- Error: Over 50 MB
+
+## Dependencies
+
+- MediaValidationService (infrastructure layer)
+- Domain types: MediaValidation, file input interfaces
+- Media constants (size limits, supported types)

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

@@ -0,0 +1,93 @@
+/**
+ * Media Validation Hook
+ * Hook for validating media files
+ */
+
+import React from "react";
+import { formatFileSize } from "../../infrastructure/utils/mediaHelpers";
+import type { UseMediaValidationResult } from "./multimedia.types";
+import type { MediaValidation } from "../../domain/entities/MultimediaFlashcardTypes";
+
+export const useMediaValidation = (): UseMediaValidationResult => {
+  const [isValidating, setIsValidating] = React.useState(false);
+  const [validation, setValidation] = React.useState<MediaValidation | null>(
+    null,
+  );
+  const [error, setError] = React.useState<string | null>(null);
+
+  const validateMedia = React.useCallback(
+    async (file: any): Promise<MediaValidation> => {
+      try {
+        setIsValidating(true);
+        setError(null);
+
+        // Simulate validation
+        await new Promise((resolve) => setTimeout(resolve, 500));
+
+        const errors: string[] = [];
+        const warnings: string[] = [];
+        const recommendations: string[] = [];
+
+        // File size validation
+        const maxSize = 50 * 1024 * 1024; // 50MB
+        if (file.size > maxSize) {
+          errors.push(
+            `File size (${formatFileSize(file.size)}) exceeds maximum allowed size (${formatFileSize(maxSize)})`,
+          );
+        } else if (file.size > 10 * 1024 * 1024) {
+          // 10MB
+          warnings.push(`Large file size may impact performance`);
+          recommendations.push("Consider compressing file");
+        }
+
+        // File type validation
+        const supportedTypes = [
+          "image/jpeg",
+          "image/png",
+          "image/webp",
+          "audio/mp3",
+          "audio/wav",
+          "audio/m4a",
+          "video/mp4",
+          "video/mov",
+        ];
+
+        if (!supportedTypes.includes(file.type)) {
+          errors.push(`Unsupported file type: ${file.type}`);
+        }
+
+        const result: MediaValidation = {
+          isValid: errors.length === 0,
+          errors,
+          warnings,
+          recommendations,
+        };
+
+        setValidation(result);
+        return result;
+      } catch (err) {
+        const errorMessage =
+          err instanceof Error ? err.message : "Validation failed";
+        setError(errorMessage);
+        setIsValidating(false);
+
+        return {
+          isValid: false,
+          errors: [errorMessage],
+          warnings: [],
+          recommendations: [],
+        };
+      } finally {
+        setIsValidating(false);
+      }
+    },
+    [],
+  );
+
+  return {
+    validateMedia,
+    isValidating,
+    validation,
+    error,
+  };
+};

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

@@ -0,0 +1,141 @@
+# useMultimediaFlashcard
+
+## Purpose
+Main hook for creating and managing flashcards with media attachments, providing all multimedia operations in one place.
+
+## File Location
+`src/presentation/hooks/useMultimediaFlashcard.ts`
+
+## Strategy
+- Provide unified interface for flashcard creation with media support
+- Support adding, updating, and deleting media on flashcards
+- Automatically analyze media composition (types, sizes, positions)
+- Calculate estimated storage requirements
+- Track download status for offline support
+- Enable rich multimedia flashcard experiences
+- Maintain separation between card data and media management
+
+## Forbidden
+- **DO NOT** create flashcards without required fields (front, back)
+- **DO NOT** add media without proper validation first
+- **DO NOT** allow duplicate media attachments with same ID
+- **DO NOT** mock card operations in production without backend integration
+- **DO NOT** assume all media is downloaded (check isDownloaded flag)
+- **DO NOT** modify card structure after creation (use update functions)
+- **DO NOT** exceed practical media limits per card (performance)
+- **DO NOT** store large media directly in card object (use references)
+- **DO NOT** bypass media analysis for size estimation
+
+## Rules
+1. Always validate media before adding to flashcard
+2. Calculate estimatedSize from all media attachments
+3. Generate unique ID for each flashcard
+4. Analyze media types and populate mediaType array
+5. Set hasMedia flag based on media array length
+6. Set isDownloaded based on all media download status
+7. Support front, back, and both positions for media
+8. Return complete MultimediaFlashcard object
+9. Clear processing state on completion or error
+10. Support empty media array for text-only cards
+
+## AI Agent Guidelines
+
+When working with useMultimediaFlashcard hook:
+
+1. **Media First**: Upload and validate media before creating card
+2. **Size Awareness**: Monitor estimatedSize for performance implications
+3. **Type Analysis**: Use mediaType array to determine card capabilities
+4. **Download Status**: Check isDownloaded before displaying media
+5. **Position Strategy**: Assign appropriate position (front, back, both)
+
+### Card Creation Workflow
+
+1. Prepare card content (front text, back text)
+2. Upload and validate media files separately
+3. Collect MediaAttachment objects
+4. Call createMultimediaCard with data
+5. Receive complete MultimediaFlashcard object
+6. Use returned card for display and storage
+
+### Flashcard Structure
+
+MultimediaFlashcard includes:
+- id: Unique card identifier
+- front: Front side content (question/prompt)
+- back: Back side content (answer/explanation)
+- difficulty: easy/medium/hard
+- tags: Array of topic tags
+- media: Array of MediaAttachment objects
+- hasMedia: Boolean flag for media presence
+- mediaType: Array of unique media types present
+- isDownloaded: Boolean (all media downloaded)
+- estimatedSize: Total size in bytes
+- createdAt: ISO timestamp
+
+### Media Analysis
+
+**hasMedia**: True if media array has items
+**mediaType**: Unique array of media types (image, audio, video)
+**isDownloaded**: True if all media.isDownloaded are true
+**estimatedSize**: Sum of all media.fileSize values
+
+### Media Positioning
+
+Media can be assigned to:
+- **front**: Displayed on front side of card
+- **back**: Displayed on back side of card
+- **both**: Displayed on both sides
+
+### Card Management Operations
+
+**createMultimediaCard**: Create new card with media
+- Validates required fields (front, back)
+- Processes media array
+- Generates unique ID
+- Analyzes media composition
+- Calculates estimated size
+
+**updateMedia**: Replace media on existing card
+- Updates media array
+- Re-analyzes composition
+- Recalculates size
+- Preserves card ID and metadata
+
+**deleteMedia**: Remove specific media attachment
+- Removes from media array by ID
+- Updates analysis
+- Recalculates size
+
+### Integration with Other Hooks
+
+Typical workflow combining multiple hooks:
+1. useMedia: Select images/videos
+2. useMediaUpload: Upload selected media
+3. useMediaValidation: Validate before upload
+4. useMediaGeneration: Generate AI media (optional)
+5. useMultimediaFlashcard: Create card with media
+
+### Performance Considerations
+
+- Limit media count per card (recommend 5-10 items)
+- Monitor estimatedSize (warn over 25 MB)
+- Use thumbnails for previews
+- Lazy load media when displaying cards
+- Cache cards with downloaded media
+
+### Best Practices
+
+1. Always validate media before adding to cards
+2. Use descriptive tags for card organization
+3. Set appropriate difficulty levels
+4. Balance media types (don't overload with videos)
+5. Consider offline usage (isDownloaded flag)
+6. Provide captions for accessibility
+
+## Dependencies
+
+- MultimediaFlashcardService (infrastructure layer)
+- Domain types: MultimediaFlashcard, MediaAttachment
+- useMediaUpload (for media upload)
+- useMediaValidation (for media validation)
+- useMediaGeneration (for AI media generation)