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

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

@@ -0,0 +1,124 @@
+/**
+ * Card Media Generation Hook
+ * Hook for generating card media with AI
+ */
+
+import React from "react";
+import type { UseCardMediaGenerationResult } from "./card-multimedia.types";
+import type {
+  CardMediaAttachment,
+  CardMediaGenerationRequest,
+  CardMediaGenerationResult,
+} from "../../domain/entities/CardMultimedia.types";
+
+export const useCardMediaGeneration = (): UseCardMediaGenerationResult => {
+  const [isGenerating, setIsGenerating] = React.useState(false);
+  const [generationResult, setGenerationResult] =
+    React.useState<CardMediaGenerationResult | null>(null);
+  const [error, setError] = React.useState<string | null>(null);
+
+  const generateMedia = React.useCallback(
+    async (
+      request: CardMediaGenerationRequest,
+    ): Promise<CardMediaGenerationResult> => {
+      try {
+        setIsGenerating(true);
+        setError(null);
+
+        // Simulate generation
+        await new Promise((resolve) => setTimeout(resolve, 3000));
+
+        const attachments: CardMediaAttachment[] = [];
+
+        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;
+
+          case "image_search":
+            for (let i = 0; i < (request.options.maxResults || 5); i++) {
+              attachments.push({
+                id: `search_img_${Date.now()}_${i}`,
+                type: "image",
+                position: "both",
+                url: `https://picsum.photos/400/300?random=${Date.now() + i}`,
+                filename: `search_result_${i}.jpg`,
+                fileSize: 120000, // 120KB
+                mimeType: "image/jpeg",
+                isDownloaded: false,
+                createdAt: new Date().toISOString(),
+              });
+            }
+            break;
+        }
+
+        const result: CardMediaGenerationResult = {
+          success: true,
+          attachments,
+          creditsUsed:
+            request.type === "text_to_image"
+              ? 5
+              : request.type === "text_to_audio"
+                ? 3
+                : 2,
+          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/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,
+  };
+};