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

package/src/media/domain/entities/MultimediaFlashcardTypes.README.md

@@ -0,0 +1,144 @@
+# MultimediaFlashcard Types
+
+## Purpose
+Type definitions for general-purpose media operations in flashcard applications. These types define the contract for media attachment, generation, and management across various multimedia use cases.
+
+## File Location
+`src/domain/entities/MultimediaFlashcardTypes.ts`
+
+## Strategy
+- Define the contract for general multimedia operations in flashcards
+- Provide type-safe interfaces for media attachments and generation
+- Support AI-powered media generation for educational content
+- Enable comprehensive media validation and optimization
+- Maintain clear separation between general media and card-specific media types
+- Support upload progress tracking and compression
+- Facilitate media download management for offline learning
+
+## Forbidden
+- **DO NOT** use these types for card-specific operations with special requirements (use CardMultimedia types instead)
+- **DO NOT** include UI components or presentation logic in type definitions
+- **DO NOT** add business logic or implementation details to interfaces
+- **DO NOT** create circular dependencies with other domain types
+- **DO NOT** use `any` type or loose type definitions
+- **DO NOT** modify existing type properties - extend interfaces for new features
+- **DO NOT** assume specific storage backend or cloud provider
+- **DO NOT** hardcode validation limits in type definitions
+- **DO NOT** mix general multimedia types with card-specific types
+- **DO NOT** use image_search generation type (only available in CardMultimedia)
+
+## Rules
+1. All multimedia types must be exported from this file
+2. Type definitions must be framework-agnostic
+3. Media IDs must use "media_" prefix for uniqueness
+4. Position types must explicitly define front/back/both placement
+5. File size fields must use bytes as unit
+6. Duration fields must use seconds as unit
+7. Date fields must use ISO 8601 format
+8. All generation requests must include input validation
+9. Compression quality must be between 0.1 and 1.0
+10. Upload progress must be tracked from 0-100
+11. Validation results must separate errors, warnings, and recommendations
+12. Service interfaces must return Promises for all async operations
+13. Media type arrays must be automatically calculated, not manually set
+14. Download status must be tracked per attachment
+15. Estimated size must represent total of all attachments
+
+## AI Agent Guidelines
+
+When working with MultimediaFlashcard types:
+
+1. **Type Selection**: Use MediaAttachment for general-purpose media operations
+2. **Generation Requests**: Always specify input parameters and options explicitly
+3. **Validation**: Validate media files before upload and after generation
+4. **Progress Tracking**: Monitor upload progress for user feedback
+5. **Compression**: Apply compression options before upload to reduce bandwidth
+6. **Download Management**: Check isDownloaded status before displaying media
+7. **Position Logic**: Respect position field for front/back/both placement
+8. **Size Estimation**: Calculate total size for all media before batch operations
+9. **Error Handling**: Parse validation errors and warnings for user feedback
+10. **Cost Tracking**: Monitor creditsUsed for AI generation operations
+
+### Key Types Reference
+
+- **MediaType**: "image" | "audio" | "video" - Media type classification
+- **MediaPosition**: "front" | "back" | "both" - Display placement on card faces
+- **MediaAttachment**: Core interface for individual media items with metadata
+- **MultimediaFlashcard**: Card entity with computed media properties
+- **MediaGenerationRequest**: Input specification for AI media generation
+- **MediaGenerationResult**: Output with cost tracking and performance metrics
+- **MediaUploadProgress**: Real-time upload status tracking
+- **MediaCompressionOptions**: Quality and size optimization settings
+- **MediaValidation**: Comprehensive validation with recommendations
+- **MultimediaFlashcardService**: Service interface for media operations
+
+### Type Usage Patterns
+
+1. **MediaAttachment**: Individual media item with position, URL, and metadata
+2. **MultimediaFlashcard**: Card with computed properties (hasMedia, mediaType, isDownloaded)
+3. **MediaGenerationRequest**: Two generation types (text_to_image, text_to_audio) - no image_search
+4. **MediaValidation**: Separate errors (blocking) from warnings and recommendations
+
+### Validation Rules
+
+1. Validate file size against upload limits before processing
+2. Check MIME type matches MediaType
+3. Ensure dimensions are within supported ranges
+4. Verify URIs are properly formatted and accessible
+5. Validate duration for audio/video files
+6. Check compression quality is within 0.1-1.0 range
+7. Ensure generation prompts are non-empty strings
+8. Validate language codes for audio generation (e.g., "en-US", "es-ES")
+
+### Service Interface Guidelines
+
+When implementing MultimediaFlashcardService:
+
+1. **uploadMedia**: Accept file with optional compression, return attachment with URL
+2. **generateMedia**: Process AI generation request, track credits and timing
+3. **validateMedia**: Return comprehensive validation with errors, warnings, recommendations
+4. **optimizeMedia**: Apply compression to existing attachment, preserve metadata
+5. **deleteMedia**: Remove attachment and update card associations
+6. **getMediaUrl**: Return accessible URL for downloaded or remote media
+7. **downloadMedia**: Fetch remote media to local storage, update isDownloaded status
+
+### Generation Type Specifics
+
+1. **text_to_image**: Requires prompt, style (realistic/cartoon/artistic), quality, format
+2. **text_to_audio**: Requires text, language, voice (male/female/neutral), format
+3. **image_search**: NOT supported in general multimedia types (use CardMultimedia instead)
+
+### Position Logic
+
+1. **front**: Media displayed only on card front face
+2. **back**: Media displayed only on card back face
+3. **both**: Media displayed on both card faces (e.g., background image)
+
+### Download Management
+
+1. Check isDownloaded before displaying media offline
+2. Use localPath for offline access when available
+3. Fall back to URL when media not downloaded
+4. Track estimatedSize for storage management
+5. Implement downloadMedia for offline caching
+
+### CardMultimedia vs Multimedia Selection
+
+Use **CardMultimedia types** when:
+- Working with flashcard-specific features
+- Need image_search generation capability
+- Using card-specific ID prefixes (card_media_)
+- Integrating with card-specific services
+
+Use **Multimedia types** when:
+- Building general-purpose media features
+- Only need text_to_image and text_to_audio generation
+- Using general media ID prefixes (media_)
+- Building reusable media components
+
+## Dependencies
+
+- No external dependencies
+- References domain types from Media.ts for base media concepts
+- Must be usable by infrastructure and presentation layers without additional dependencies
+- Service interfaces require async operation support

package/src/media/domain/entities/MultimediaFlashcardTypes.ts

@@ -0,0 +1,105 @@
+/**
+ * Multimedia Flashcard Types
+ * Extended media types for flashcard support
+ */
+
+export type MediaType = "image" | "audio" | "video";
+export type MediaPosition = "front" | "back" | "both";
+
+export interface MediaAttachment {
+  id: string;
+  type: MediaType;
+  position: MediaPosition;
+  url: string;
+  localPath?: string;
+  filename: string;
+  fileSize: number;
+  mimeType: string;
+  duration?: number; // For audio/video in seconds
+  thumbnailUrl?: string; // For videos
+  caption?: string;
+  isDownloaded: boolean;
+  createdAt: string;
+}
+
+export interface MultimediaFlashcard {
+  id: string;
+  front: string;
+  back: string;
+  difficulty: "easy" | "medium" | "hard";
+  tags: string[];
+  createdAt?: string;
+  updatedAt?: string;
+  // Extended properties for multimedia support
+  media: MediaAttachment[];
+  hasMedia: boolean; // Computed property
+  mediaType: MediaType[]; // Array of media types present
+  isDownloaded: boolean; // All media downloaded?
+  estimatedSize: number; // Total size in bytes
+}
+
+export interface MediaGenerationRequest {
+  type: "text_to_image" | "text_to_audio" | "image_search";
+  input: {
+    text?: string;
+    prompt?: string;
+    language?: string;
+    voice?: "male" | "female" | "neutral";
+    style?: "realistic" | "cartoon" | "artistic";
+  };
+  options: {
+    maxResults?: number;
+    quality?: "low" | "medium" | "high";
+    format?: "jpeg" | "png" | "mp3" | "wav";
+  };
+}
+
+export interface MediaGenerationResult {
+  success: boolean;
+  attachments: MediaAttachment[];
+  creditsUsed: number;
+  processingTime: number;
+  error?: string;
+  requestId: string;
+}
+
+export interface MediaUploadProgress {
+  fileId: string;
+  progress: number; // 0-100
+  status: "uploading" | "processing" | "completed" | "error";
+  error?: string;
+  url?: string;
+}
+
+export interface MediaCompressionOptions {
+  quality: number; // 0.1 - 1.0
+  maxWidth?: number;
+  maxHeight?: number;
+  maxFileSize?: number; // bytes
+  format?: "jpeg" | "png" | "webp";
+}
+
+export interface MediaValidation {
+  isValid: boolean;
+  errors: string[];
+  warnings: string[];
+  recommendations: string[];
+}
+
+export interface MultimediaFlashcardService {
+  uploadMedia(
+    file: any,
+    options?: MediaCompressionOptions,
+  ): Promise<MediaAttachment>;
+  generateMedia(
+    request: MediaGenerationRequest,
+  ): Promise<MediaGenerationResult>;
+  validateMedia(file: any): Promise<MediaValidation>;
+  optimizeMedia(
+    attachment: MediaAttachment,
+    options: MediaCompressionOptions,
+  ): Promise<MediaAttachment>;
+  deleteMedia(attachmentId: string): Promise<void>;
+  getMediaUrl(attachmentId: string): Promise<string>;
+  downloadMedia(attachmentId: string): Promise<string>; // Returns local path
+}

package/src/media/domain/utils/MediaUtils.README.md

@@ -0,0 +1,178 @@
+# MediaUtils
+
+## Purpose
+Utility class containing helper functions for media operations, validation, and calculations. Provides static methods for file type detection, dimension calculations, format conversions, and media validation.
+
+## File Location
+`src/domain/utils/MediaUtils.ts`
+
+## Strategy
+- Provide framework-agnostic utility functions for media operations
+- Enable consistent media type detection and validation
+- Support dimension calculations and scaling operations
+- Facilitate format conversions and MIME type mappings
+- Maintain aspect ratio preservation during transformations
+- Validate media constraints (dimensions, file types, sizes)
+- Provide helper functions for common media operations
+
+## Forbidden
+- **DO NOT** import external libraries (expo-image-picker, react-native) in utility functions
+- **DO NOT** include business logic or application-specific rules
+- **DO NOT** create instance methods - all methods must be static
+- **DO NOT** store state or maintain mutable properties
+- **DO NOT** make network calls or async operations in utility methods
+- **DO NOT** hardcode platform-specific behavior
+- **DO NOT** include UI-related logic or formatting for display
+- **DO NOT** modify input parameters - always return new objects/values
+- **DO NOT** throw exceptions for validation failures - return boolean results
+- **DO NOT** assume specific file systems or storage mechanisms
+
+## Rules
+1. All methods must be static and stateless
+2. All methods must be synchronous and pure functions
+3. Input validation must not throw exceptions
+4. Dimension calculations must preserve aspect ratios
+5. MIME type mappings must use standard MIME types
+6. Maximum dimension limit is 8192x8192 pixels
+7. Minimum dimension limit is 1x1 pixels
+8. File type detection must use extension checking
+9. Scale calculations must return integer values
+10. Aspect ratio must be calculated as width/height
+11. Unknown MIME types must map to MediaType.ALL
+12. Format validation must use supported format lists
+13. All methods must handle edge cases (zero, negative values)
+14. Return types must be consistent (boolean for validation, numbers for calculations)
+
+## AI Agent Guidelines
+
+When working with MediaUtils:
+
+1. **Static Usage**: Always call methods on the class, never create instances
+2. **Type Detection**: Use isImage() and isVideo() before processing files
+3. **Validation**: Always validate dimensions before scaling operations
+4. **Aspect Ratios**: Preserve aspect ratios when calculating scaled dimensions
+5. **MIME Types**: Use getImageMimeType() for format-to-MIME conversion
+6. **Media Type Parsing**: Use parseMediaType() to convert MIME to MediaType enum
+7. **Error Handling**: Check boolean return values for validation failures
+8. **Edge Cases**: Handle zero and negative dimensions appropriately
+9. **Performance**: Utility methods are lightweight and can be called frequently
+
+### Key Methods Reference
+
+- **isImage(uri: string)**: boolean - Check if file is an image by extension
+- **isVideo(uri: string)**: boolean - Check if file is a video by extension
+- **getImageMimeType(format: ImageFormat)**: string - Get MIME type for image format
+- **calculateAspectRatio(width, height)**: number - Calculate width/height ratio
+- **getScaledDimensions(width, height, maxWidth, maxHeight)**: object - Calculate scaled dimensions preserving aspect ratio
+- **isValidDimensions(width, height)**: boolean - Validate dimensions are within allowed range
+- **parseMediaType(mimeType: string)**: MediaType - Convert MIME type to MediaType enum
+
+### Method Usage Guidelines
+
+**File Type Detection:**
+1. Use isImage() to validate image files before processing
+2. Use isVideo() to validate video files before processing
+3. Both methods check file extensions (jpg, png, mp4, mov, etc.)
+4. Returns false for unknown or unsupported formats
+
+**Dimension Calculations:**
+1. Always validate dimensions with isValidDimensions() before processing
+2. Use calculateAspectRatio() to understand image proportions
+3. Use getScaledDimensions() to resize while preserving aspect ratio
+4. Scaled dimensions will never exceed maxWidth or maxHeight
+5. Aspect ratio is maintained even when only one dimension exceeds limits
+
+**Format Conversions:**
+1. Use getImageMimeType() to get standard MIME type from format enum
+2. Use parseMediaType() to convert MIME strings to MediaType enum
+3. Unknown MIME types return MediaType.ALL
+4. MIME type mappings are constant and cannot be modified
+
+### Validation Rules
+
+1. **isValidDimensions**:
+   - Width and height must be positive integers
+   - Maximum allowed dimension is 8192 pixels
+   - Minimum allowed dimension is 1 pixel
+   - Returns false for zero or negative values
+   - Returns false for values exceeding 8192
+
+2. **Aspect Ratio Calculations**:
+   - Must preserve original ratio in scaled dimensions
+   - Calculated as width divided by height
+   - Square images (1:1) return ratio of 1.0
+   - Widescreen (16:9) returns ratio of approximately 1.78
+   - Portrait (9:16) returns ratio of approximately 0.56
+
+3. **Scaling Operations**:
+   - Input dimensions can be any positive integers
+   - Output dimensions never exceed maxWidth or maxHeight
+   - Aspect ratio is always preserved
+   - Returns integer dimensions (not floating point)
+   - If both dimensions are within limits, returns original dimensions
+   - If only one dimension exceeds limit, scales proportionally
+
+### MIME Type Handling
+
+**Supported Image MIME Types:**
+- PNG: "image/png"
+- JPEG: "image/jpeg"
+- WEBP: "image/webp"
+
+**MediaType Mapping:**
+- "image/*" formats return MediaType.IMAGE
+- "video/*" formats return MediaType.VIDEO
+- Unknown formats return MediaType.ALL
+- Mapping is based on MIME type prefix
+
+### Constants Reference
+
+- **IMAGE_MIME_TYPES**: Readonly object mapping image formats to MIME types
+- Keys: "png", "jpeg", "webp"
+- Values: Standard MIME type strings
+- Used by getImageMimeType() method
+
+### Common Use Cases
+
+**Image Validation Pipeline:**
+1. Check file type with isImage()
+2. Validate dimensions with isValidDimensions()
+3. Calculate aspect ratio with calculateAspectRatio()
+4. Get MIME type with getImageMimeType()
+5. Scale if needed with getScaledDimensions()
+
+**Video Validation Pipeline:**
+1. Check file type with isVideo()
+2. Validate dimensions with isValidDimensions()
+3. Parse media type with parseMediaType()
+4. Scale if needed with getScaledDimensions()
+
+**Format Conversion:**
+1. Convert format enum to MIME type using getImageMimeType()
+2. Convert MIME type to MediaType using parseMediaType()
+3. Use MediaType for filtering and type checking
+
+### Edge Case Handling
+
+1. **Zero dimensions**: isValidDimensions() returns false
+2. **Negative dimensions**: isValidDimensions() returns false
+3. **Oversized dimensions**: isValidDimensions() returns false if > 8192
+4. **Unknown file extensions**: isImage() and isVideo() return false
+5. **Unknown MIME types**: parseMediaType() returns MediaType.ALL
+6. **Equal aspect ratios**: getScaledDimensions() returns original if within limits
+
+### Performance Considerations
+
+1. All methods are synchronous and execute in O(1) time
+2. No network calls or I/O operations
+3. No side effects or state mutations
+4. Safe to call frequently in loops or render cycles
+5. No memory allocation beyond return values
+
+## Dependencies
+
+- No external dependencies
+- References ImageFormat enum from domain types
+- References MediaType enum from domain types
+- Pure utility functions with no side effects
+- Can be used by any layer without additional dependencies

package/src/media/domain/utils/MediaUtils.ts

@@ -0,0 +1,82 @@
+/**
+ * Media Utilities
+ * Utility functions for media operations
+ */
+
+import { ImageFormat, MEDIA_CONSTANTS, MediaType } from "../entities/Media";
+
+/**
+ * Image MIME type mappings
+ */
+export const IMAGE_MIME_TYPES = {
+  [ImageFormat.PNG]: "image/png",
+  [ImageFormat.JPEG]: "image/jpeg",
+  [ImageFormat.WEBP]: "image/webp",
+} as const;
+
+/**
+ * Media utility class
+ */
+export class MediaUtils {
+  static isImage(uri: string): boolean {
+    const extension = uri.split(".").pop()?.toLowerCase();
+    return MEDIA_CONSTANTS.SUPPORTED_IMAGE_FORMATS.some(
+      (format) => format.replace(".", "") === extension
+    );
+  }
+
+  static isVideo(uri: string): boolean {
+    const extension = uri.split(".").pop()?.toLowerCase();
+    return MEDIA_CONSTANTS.SUPPORTED_VIDEO_FORMATS.some(
+      (format) => format.replace(".", "") === extension
+    );
+  }
+
+  static getImageMimeType(format: ImageFormat): string {
+    return IMAGE_MIME_TYPES[format];
+  }
+
+  static calculateAspectRatio(width: number, height: number): number {
+    return width / height;
+  }
+
+  static getScaledDimensions(
+    originalWidth: number,
+    originalHeight: number,
+    maxWidth: number,
+    maxHeight: number
+  ): { width: number; height: number } {
+    const aspectRatio = MediaUtils.calculateAspectRatio(
+      originalWidth,
+      originalHeight
+    );
+
+    let width = originalWidth;
+    let height = originalHeight;
+
+    if (width > maxWidth) {
+      width = maxWidth;
+      height = width / aspectRatio;
+    }
+
+    if (height > maxHeight) {
+      height = maxHeight;
+      width = height * aspectRatio;
+    }
+
+    return {
+      width: Math.round(width),
+      height: Math.round(height),
+    };
+  }
+
+  static isValidDimensions(width: number, height: number): boolean {
+    return width > 0 && height > 0 && width <= 8192 && height <= 8192;
+  }
+
+  static parseMediaType(mimeType: string): MediaType {
+    if (mimeType.startsWith("image/")) return MediaType.IMAGE;
+    if (mimeType.startsWith("video/")) return MediaType.VIDEO;
+    return MediaType.ALL;
+  }
+}

package/src/media/index.ts

@@ -0,0 +1,70 @@
+/**
+ * @umituz/react-native-media - Enhanced Public API
+ *
+ * Media picking capabilities for React Native apps
+ * Includes multimedia flashcard support
+ *
+ * Usage:
+ *   import {
+ *     useMedia,
+ *     useMultimediaFlashcard,
+ *     MultimediaFlashcardService,
+ *     type MediaAttachment,
+ *     type MultimediaFlashcard,
+ *   } from '@umituz/react-native-media';
+ */
+
+// Domain Layer - Original Media Entities
+export {
+  MediaType,
+  ImageFormat as MediaImageFormat,
+  MediaQuality,
+  MediaLibraryPermission,
+  MEDIA_CONSTANTS,
+} from "./domain/entities/Media";
+
+export { IMAGE_MIME_TYPES as MEDIA_IMAGE_MIME_TYPES, MediaUtils } from "./domain/utils/MediaUtils";
+
+export type {
+  MediaAsset,
+  MediaPickerResult,
+  MediaPickerOptions,
+  CameraOptions,
+  ImageDimensions as MediaImageDimensions,
+  ImageManipulationActions,
+  ImageSaveOptions as MediaImageSaveOptions,
+} from "./domain/entities/Media";
+
+// Infrastructure Layer - Original Media Services
+export { MediaPickerService } from "./infrastructure/services/MediaPickerService";
+export { MediaSaveService } from "./infrastructure/services/MediaSaveService";
+export type { SaveResult, SaveOptions } from "./infrastructure/services/MediaSaveService";
+
+// Presentation Layer - Original Media Hooks
+export { useMedia } from "./presentation/hooks/useMedia";
+
+// Multimedia Flashcard Support
+export type {
+  CardMediaType,
+  CardMediaPosition,
+  CardMediaAttachment,
+  CardMultimediaFlashcard,
+  CardMediaGenerationRequest,
+  CardMediaGenerationResult,
+  CardMediaUploadProgress,
+  CardMediaCompressionOptions,
+  CardMediaValidation,
+} from "./domain/entities/CardMultimedia.types";
+
+export { CardMultimediaFlashcardService } from "./infrastructure/services/CardMultimediaService";
+
+export {
+  useCardMediaUpload,
+  useCardMediaGeneration,
+  useCardMediaValidation,
+  useCardMultimediaFlashcard,
+  type UseCardMediaUploadResult,
+  type UseCardMediaGenerationResult,
+  type UseCardMediaValidationResult,
+  type UseCardMultimediaFlashcardResult,
+} from "./presentation/hooks/useCardMultimediaFlashcard";