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

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

@@ -0,0 +1,153 @@
+# useCardMediaUpload
+
+## Purpose
+Card-specific React hook for uploading flashcard media files to server with progress tracking and compression support.
+
+## File Location
+`src/presentation/hooks/useCardMediaUpload.ts`
+
+## Strategy
+- Provide card-specific media upload interface
+- Support compression options for optimization
+- Track upload progress with percentage and status
+- Return CardMediaAttachment with position property
+- Handle upload errors gracefully
+- Generate thumbnails for visual media
+- Support various media types for cards
+
+## Forbidden
+- **DO NOT** start upload while previous is in progress
+- **DO NOT** ignore compression options
+- **DO NOT** upload without validation (use useCardMediaValidation)
+- **DO NOT** mock upload in production without backend integration
+- **DO NOT** modify file during upload (compress before)
+- **DO NOT** assume upload will succeed
+- **DO NOT** use hardcoded API endpoints
+- **DO NOT** bypass progress tracking
+- **DO NOT** store upload results permanently in state
+- **DO NOT** use incorrect ID prefixes (must use card_media_)
+
+## Rules
+1. Always validate before uploading (use useCardMediaValidation)
+2. Compression quality must be in 0-1 range
+3. Dimensions must be in pixels
+4. Progress updates every 10% or on status change
+5. Clear upload state on error or completion
+6. Return CardMediaAttachment with position property
+7. Generate thumbnail URL automatically
+8. Calculate duration for audio/video
+9. Update progress status: uploading -> completed/error
+10. Include unique fileId in progress tracking
+
+## AI Agent Guidelines
+
+When working with useCardMediaUpload hook:
+
+1. **Type Correctness**: Returns CardMediaAttachment (not MediaAttachment)
+2. **Position Property**: Uploaded media includes position field
+3. **Pre-upload Validation**: Always use useCardMediaValidation first
+4. **Progress Tracking**: Monitor uploadProgress for real-time updates
+5. **Compression**: Apply appropriate compression settings
+
+### Upload Workflow
+
+1. Validate file with useCardMediaValidation
+2. Select compression options based on type and size
+3. Call uploadMedia with file and options
+4. Monitor uploadProgress state
+5. Handle completion (success or error)
+6. Process returned CardMediaAttachment
+
+### CardMediaAttachment Structure
+
+Returned object includes:
+- id: Unique ID with card_media_ prefix
+- type: CardMediaType (IMAGE, VIDEO, AUDIO)
+- position: CardMediaPosition (defaults to 'both')
+- url: Uploaded file URL
+- filename: Original filename
+- fileSize: Size in bytes
+- mimeType: MIME type string
+- duration: Audio/video duration
+- thumbnailUrl: Thumbnail for visual media
+- caption: Optional caption text
+- isDownloaded: Download status
+- createdAt: ISO timestamp
+
+### Compression Guidelines
+
+**High Quality** (quality: 0.9, maxWidth: 4096)
+- Use for detailed card images
+- Larger file size, best quality
+
+**Medium Quality** (quality: 0.7, maxWidth: 1920) - RECOMMENDED
+- Balanced quality and size
+- Good for most card media
+
+**Low Quality** (quality: 0.5, maxWidth: 1280)
+- Use for card thumbnails
+- Smallest size, reduced quality
+
+### Upload Progress States
+
+- **uploading**: Upload in progress (0-99%)
+- **completed**: Upload finished successfully (100%)
+- **error**: Upload failed with error message
+
+### CardMediaUploadProgress
+
+Progress object includes:
+- fileId: Unique file identifier
+- progress: Percentage (0-100)
+- status: Current state (uploading/completed/error)
+- url: Final URL when completed
+
+### Integration with Card Creation
+
+Typical workflow:
+1. Select or generate media
+2. Validate with useCardMediaValidation
+3. Upload with useCardMediaUpload
+4. Receive CardMediaAttachment with position
+5. Add to card media array
+6. Create card with useCardMultimediaFlashcard
+
+### Position Assignment
+
+Uploaded media gets position property:
+- Default: 'both' (shown on both sides)
+- Can be overridden: 'front' or 'back'
+- Used to control media display on card sides
+
+### Multiple File Upload
+
+For multiple media files:
+1. Upload files sequentially or in parallel
+2. Collect CardMediaAttachment objects
+3. Assign positions appropriately
+4. Add to card media array
+5. Track individual upload progress
+
+### Integration Requirements
+
+- Configure API endpoint for card media upload
+- Implement authentication for uploads
+- Handle file size limits
+- Support retry logic for failures
+- Generate thumbnails automatically
+- Calculate media duration for audio/video
+
+### Error Handling
+
+Common error scenarios:
+- File too large: Validate before upload
+- Unsupported type: Check MIME type
+- Network timeout: Implement retry with backoff
+- Server error: Display user-friendly message
+- Authentication failure: Check token validity
+
+## Dependencies
+
+- CardMediaUploadService (infrastructure layer)
+- Domain types: CardMediaAttachment, CardMediaCompressionOptions, CardMediaUploadProgress
+- useCardMediaValidation (for pre-upload validation)

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

@@ -0,0 +1,86 @@
+/**
+ * Card Media Upload Hook
+ * Hook for uploading card media files
+ */
+
+import React from "react";
+import {
+  generateThumbnail,
+  getCardMediaType,
+  getMediaDuration,
+} from "../../infrastructure/utils/mediaHelpers";
+import type { UseCardMediaUploadResult } from "./card-multimedia.types";
+import type {
+  CardMediaAttachment,
+  CardMediaCompressionOptions,
+  CardMediaUploadProgress,
+} from "../../domain/entities/CardMultimedia.types";
+
+export const useCardMediaUpload = (): UseCardMediaUploadResult => {
+  const [isUploading, setIsUploading] = React.useState(false);
+  const [uploadProgress, setUploadProgress] =
+    React.useState<CardMediaUploadProgress | null>(null);
+  const [error, setError] = React.useState<string | null>(null);
+
+  const uploadMedia = React.useCallback(
+    async (file: any, options?: CardMediaCompressionOptions) => {
+      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, 50));
+          setUploadProgress((prev) => (prev ? { ...prev, progress: i } : null));
+        }
+
+        const attachment: CardMediaAttachment = {
+          id: `card_media_${Date.now()}`,
+          type: getCardMediaType(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/useCardMediaValidation.README.md

@@ -0,0 +1,176 @@
+# useCardMediaValidation
+
+## Purpose
+Card-specific React hook for validating flashcard media files before upload with enhanced controls for different media types.
+
+## File Location
+`src/presentation/hooks/useCardMediaValidation.ts`
+
+## Strategy
+- Provide comprehensive validation for card media files
+- Enhanced controls for images (5 MB warning threshold)
+- Support audio/video duration validation
+- Provide three-tier feedback: errors, warnings, recommendations
+- Card-specific validation rules compared to general media
+- Enable pre-upload validation workflow for cards
+- Return actionable feedback with media-type specific recommendations
+
+## Forbidden
+- **DO NOT** upload files that fail validation (have errors)
+- **DO NOT** ignore warnings - they indicate card performance issues
+- **DO NOT** bypass file type validation
+- **DO NOT** use mock validation in production
+- **DO NOT** allow files exceeding 50 MB limit
+- **DO NOT** modify files during validation
+- **DO NOT** store validation results permanently
+- **DO NOT** validate empty or missing files
+- **DO NOT** suppress errors for user convenience
+
+## Rules
+1. Always validate before card media upload
+2. Files over 50 MB must be rejected
+3. Files over 10 MB trigger warning
+4. Images over 5 MB trigger additional warning
+5. Unsupported MIME types must be rejected
+6. Validate file size, type, and format
+7. Return errors array for blocking issues
+8. Return warnings array for performance concerns
+9. Return recommendations array for improvements
+10. Clear validation state on new requests
+
+## AI Agent Guidelines
+
+When working with useCardMediaValidation hook:
+
+1. **Card-Specific Rules**: Use for card media (not general media)
+2. **Enhanced Image Control**: 5 MB threshold for images (stricter than general)
+3. **Three-Tier Feedback**: Distinguish errors, warnings, recommendations
+4. **Duration Control**: Check audio/video duration when available
+5. **Pre-upload Check**: Always validate before useCardMediaUpload
+
+### Validation Levels
+
+**Errors** (Blocking - Must fix):
+- File size exceeds 50 MB
+- Unsupported file type
+- Invalid file format
+- Missing required properties
+
+**Warnings** (Performance - Should fix):
+- File size over 10 MB (general warning)
+- Image size over 5 MB (card-specific warning)
+- Long duration audio/video
+- Large dimensions
+
+**Recommendations** (Improvements - Optional):
+- Reduce file size for card performance
+- Use recommended formats
+- Optimize dimensions
+- Compress for balance
+
+### Card-Specific vs General Validation
+
+| Feature | useMediaValidation | useCardMediaValidation |
+|---------|-------------------|------------------------|
+| Max file size | 50 MB | 50 MB |
+| General warning | 10 MB | 10 MB |
+| Image warning | None | 5 MB (extra) |
+| Duration check | No | Yes (5 min warning) |
+| Type support | Same | Same |
+
+### Supported File Types
+
+**Images:**
+- image/jpeg
+- image/png
+- image/webp
+
+**Audio:**
+- audio/mp3
+- audio/wav
+- audio/m4a
+
+**Video:**
+- video/mp4
+- video/mov
+
+### Validation Workflow
+
+1. Receive file object (name, type, size, uri)
+2. Check file size against limits
+3. Validate MIME type
+4. Apply card-specific rules (5 MB image warning)
+5. Check duration if available
+6. Generate errors, warnings, recommendations
+7. Return CardMediaValidation object
+
+### CardMediaValidation Structure
+
+Validation result includes:
+- isValid: Boolean (true if no errors)
+- errors: String array (blocking issues)
+- warnings: String array (performance concerns)
+- recommendations: String array (improvements)
+
+### File Size Guidelines
+
+**Images:**
+- Optimal: Under 2 MB
+- Card warning: 2-5 MB
+- Extra warning: 5-10 MB
+- Error: Over 50 MB
+
+**Audio:**
+- Optimal: Under 5 MB
+- Warning: 5-10 MB
+- Duration warning: Over 5 minutes
+- Error: Over 50 MB
+
+**Video:**
+- Optimal: Under 10 MB
+- Warning: 10-50 MB
+- Duration warning: Over 5 minutes
+- Error: Over 50 MB
+
+### Media Type Special Controls
+
+**Image Controls:**
+- Additional 5 MB warning threshold
+- Dimension recommendations
+- Format recommendations (JPEG for photos, PNG for graphics)
+
+**Audio Controls:**
+- Duration check (warn over 5 minutes)
+- Format recommendation (MP3 preferred)
+- Bitrate considerations
+
+**Video Controls:**
+- Duration check (warn over 5 minutes)
+- Format recommendation (MP4 preferred)
+- Resolution recommendations
+
+### Integration with Card Upload Flow
+
+Typical validation-upload workflow:
+1. Select file from picker
+2. Call validateMedia(file) from useCardMediaValidation
+3. Check validation.isValid
+4. If errors: Display and block upload
+5. If warnings: Display and get confirmation
+6. If recommendations: Display for reference
+7. Proceed to useCardMediaUpload if valid or confirmed
+
+### Best Practices
+
+1. Always validate before card media upload
+2. Show all three feedback levels to users
+3. Allow users to proceed with warnings
+4. Provide actionable recommendations
+5. Consider card performance implications
+6. Balance quality vs. file size
+
+## Dependencies
+
+- CardMediaValidationService (infrastructure layer)
+- Domain types: CardMediaValidation, file input interfaces
+- Media constants (card-specific size limits)

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

@@ -0,0 +1,101 @@
+/**
+ * Card Media Validation Hook
+ * Hook for validating card media files
+ */
+
+import React from "react";
+import { formatFileSize } from "../../infrastructure/utils/mediaHelpers";
+import type { UseCardMediaValidationResult } from "./card-multimedia.types";
+import type { CardMediaValidation } from "../../domain/entities/CardMultimedia.types";
+
+export const useCardMediaValidation = (): UseCardMediaValidationResult => {
+  const [isValidating, setIsValidating] = React.useState(false);
+  const [validation, setValidation] =
+    React.useState<CardMediaValidation | null>(null);
+  const [error, setError] = React.useState<string | null>(null);
+
+  const validateMedia = React.useCallback(
+    async (file: any): Promise<CardMediaValidation> => {
+      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}`);
+        }
+
+        // Media-specific validations
+        if (file.type.startsWith("image/")) {
+          if (file.size > 5 * 1024 * 1024) {
+            // 5MB for images
+            warnings.push("Very large image may cause performance issues");
+            recommendations.push("Consider resizing image to under 5MB");
+          }
+        }
+
+        const result: CardMediaValidation = {
+          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/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)