@umituz/react-native-design-system 4.23.100 → 4.23.101

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

@@ -1,80 +0,0 @@
-# Media Types and Interfaces
-
-## Purpose
-Core type definitions and interfaces for media handling throughout the application.
-
-## File Location
-`src/domain/entities/Media.ts`
-
-## Strategy
-- Define the contract for media operations across all layers
-- Provide type-safe interfaces for media assets, picker options, and operations
-- Serve as the single source of truth for media-related types
-- Enable compile-time validation of media operations
-- Maintain separation between domain logic and implementation
-
-## Forbidden
-- **DO NOT** import external libraries (expo, react-native) in domain types
-- **DO NOT** include implementation details in type definitions
-- **DO NOT** add business logic to type definitions
-- **DO NOT** create circular dependencies between types
-- **DO NOT** export types that are not used by other layers
-- **DO NOT** use `any` type or loose type definitions
-- **DO NOT** modify existing types - extend them instead
-
-## Rules
-1. All media types must be exported from this file
-2. Type definitions must be framework-agnostic
-3. Enums must have explicit string values
-4. Interfaces must extend appropriate base types
-5. Optional fields must be clearly marked with `?`
-6. File size fields must use bytes as unit
-7. Dimensions must be in pixels
-8. MIME type validation must use standard MIME types
-9. All new properties must be added with backward compatibility in mind
-10. Type exports must be re-exported from main index
-
-## AI Agent Guidelines
-
-When working with Media types:
-
-1. **Type Import**: Always import types from `@umituz/react-native-media` domain layer
-2. **Type Safety**: Use provided types instead of `any` or loose types
-3. **Validation**: Validate media assets against these types before processing
-4. **Extensibility**: Extend interfaces when adding new properties, don't modify core types
-5. **Consistency**: Maintain naming conventions (PascalCase for types, camelCase for properties)
-
-### Key Enums Reference
-
-- `MediaType`: IMAGE, VIDEO, ALL - Use for media type filtering
-- `ImageFormat`: PNG, JPEG, WEBP - Use for format specification
-- `MediaQuality`: LOW (0.3), MEDIUM (0.7), HIGH (1.0) - Use for compression quality
-- `MediaLibraryPermission`: GRANTED, DENIED, LIMITED - Use for permission states
-
-### Type Usage Guidelines
-
-1. **MediaAsset**: Primary type for all media files with uri, dimensions, type, size
-2. **MediaPickerResult**: Return type for all picker operations with canceled flag
-3. **MediaPickerOptions**: Configuration for library picker with mediaTypes, quality, limits
-4. **CameraOptions**: Configuration for camera operations with quality, duration, editing
-
-### Validation Rules
-
-1. Check file size against `MediaAsset.fileSize` (in bytes)
-2. Validate dimensions using `width` and `height` properties (in pixels)
-3. Verify MIME type matches expected `MediaType`
-4. Ensure URIs are properly formatted strings
-5. Validate aspect ratio format as [width, height] tuple
-
-### Constants Reference
-
-Use `MEDIA_CONSTANTS` for:
-- Maximum file sizes (MAX_IMAGE_SIZE, MAX_VIDEO_SIZE)
-- Default values (DEFAULT_QUALITY, DEFAULT_FORMAT, DEFAULT_ASPECT_RATIO)
-- Supported format lists (SUPPORTED_IMAGE_FORMATS, SUPPORTED_VIDEO_FORMATS)
-
-## Dependencies
-
-- No external dependencies
-- May reference other domain types within the domain layer
-- Must be usable by infrastructure and presentation layers without additional dependencies

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

@@ -1,144 +0,0 @@
-# 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/utils/MediaUtils.README.md

@@ -1,178 +0,0 @@
-# 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/index.ts.README.md

@@ -1,191 +0,0 @@
-# @umituz/react-native-media - Main Export
-
-## Purpose
-Main entry point for the library. Exports all services, hooks, types, and utilities for media management in React Native applications.
-
-## File Location
-`src/index.ts`
-
-## Strategy
-- Provide a single import point for all library functionality
-- Organize exports by category (services, hooks, types, utils)
-- Enable tree-shaking by using named exports
-- Maintain clear separation between general media and card-specific features
-- Support both individual imports and bulk imports
-
-## Forbidden
-- **DO NOT** add default exports - only named exports
-- **DO NOT** re-export external dependencies directly
-- **DO NOT** create circular import dependencies
-- **DO NOT** mix categories in export groups
-- **DO NOT** export internal implementation details
-- **DO NOT** use wildcard exports from sub-modules
-- **DO NOT** change export names once published
-
-## Rules
-1. All public exports must be re-exported from this file
-2. Exports must be organized by category (services, hooks, types, utils)
-3. Each category must be clearly commented
-4. General media features must be separate from card-specific features
-5. Type exports must use `export type` for tree-shaking
-6. Service exports must be singleton instances or static classes
-7. Hook exports must be named with `use` prefix
-8. All exports must have TypeScript types
-9. Breaking changes require major version bump
-10. All exports must be documented in their respective README files
-
-## AI Agent Guidelines
-
-### Import Strategy
-
-When working with this library:
-
-1. **Single Entry Point**: All imports should come from `@umituz/react-native-media`
-2. **Specific Imports**: Import only what you need for better tree-shaking
-3. **Type Imports**: Use `import type` for type-only imports
-4. **Category Awareness**: Understand the difference between general and card-specific features
-
-### Export Categories
-
-#### Services (Infrastructure Layer)
-All services follow singleton pattern:
-- `MediaPickerService` - Image/video selection from camera and gallery
-- `MediaSaveService` - Saving media to device gallery
-- `MediaUploadService` - Upload/download media and URL management
-- `MediaGenerationService` - AI-powered text-to-image and text-to-audio
-- `MediaValidationService` - File validation before upload
-- `MediaOptimizerService` - Compression and optimization
-- `CardMultimediaService` - Card-specific media operations
-- `CardMediaGenerationService` - Card AI generation with image search
-- `CardMediaUploadService` - Card upload with position support
-- `CardMediaValidationService` - Card validation with stricter rules
-- `CardMediaOptimizerService` - Card optimization
-- `MultimediaFlashcardService` - Main flashcard service
-- `CardMultimediaFlashcardService` - Main card flashcard service
-
-#### Hooks (Presentation Layer)
-All hooks are named with `use` prefix:
-
-**General Media Hooks:**
-- `useMedia` - Core media selection and camera
-- `useMediaUpload` - Upload with progress tracking
-- `useMediaGeneration` - AI generation
-- `useMediaValidation` - Pre-upload validation
-- `useMultimediaFlashcard` - Flashcard creation
-
-**Card-Specific Hooks:**
-- `useCardMultimediaFlashcard` - Card flashcard management
-- `useCardMediaGeneration` - Card AI generation
-- `useCardMediaUpload` - Card upload with position
-- `useCardMediaValidation` - Card validation
-
-#### Types (Domain Layer)
-Organized by functionality:
-
-**Basic Types:**
-- `MediaType` - Media type enum (IMAGE, VIDEO, ALL)
-- `ImageFormat` - Format enum (JPEG, PNG, WEBP)
-- `MediaQuality` - Quality enum (LOW, MEDIUM, HIGH)
-- `MediaLibraryPermission` - Permission states
-- `MediaAsset` - Media file properties
-- `MediaPickerResult` - Picker return type
-- `MediaPickerOptions` - Picker configuration
-- `CameraOptions` - Camera configuration
-
-**Card Types:**
-- `CardMediaType` - Card media types
-- `CardMediaPosition` - Position (FRONT, BACK, BOTH)
-- `CardMediaAttachment` - Card media with position
-- `CardMultimediaFlashcard` - Card entity
-- `CardMediaGenerationRequest` - Generation request
-- `CardMediaGenerationResult` - Generation result
-- `CardMediaUploadProgress` - Upload progress
-- `CardMediaCompressionOptions` - Compression options
-- `CardMediaValidation` - Validation result
-
-**Flashcard Types:**
-- `MediaAttachment` - General media attachment
-- `MultimediaFlashcard` - Flashcard entity
-- `MediaGenerationRequest` - Generation request
-- `MediaGenerationResult` - Generation result
-
-#### Utils (Domain & Infrastructure)
-Utility functions and helpers:
-
-**Domain Utils:**
-- `MediaUtils` - Core media utilities
-
-**Infrastructure Utils:**
-- Helper functions for media operations
-- Mapper functions for type conversions
-
-### Module Selection Guidelines
-
-#### Use General Media Features When:
-- Working with standard media operations
-- No card/flashcard requirements
-- Need basic upload/download/validation
-- Building general-purpose media features
-
-#### Use Card-Specific Features When:
-- Building flashcard applications
-- Need position-based media (front/back)
-- Working with card entities
-- Need card-specific validation rules
-- Using card generation or upload services
-
-### Dependency Rules
-
-1. **Services** can be used independently or through hooks
-2. **Hooks** wrap services and provide React state management
-3. **Types** are used by both services and hooks
-4. **Utils** provide helper functions used across layers
-
-### Common Import Patterns
-
-**Service-only usage:**
-- Import service classes directly
-- Use for non-React code or direct service access
-- Services follow singleton pattern
-
-**Hook usage (recommended for React components):**
-- Import hooks for React components
-- Hooks provide state management
-- Hooks wrap services with React integration
-
-**Type imports:**
-- Use `import type` for type-only imports
-- Enables tree-shaking
-- Better IDE support
-
-**Combined imports:**
-- Mix services, hooks, and types as needed
-- All imports from single entry point
-- Named exports only
-
-## File Structure Reference
-
-The library follows Clean Architecture with three main layers:
-
-**Domain Layer** (`src/domain/`)
-- `entities/` - Core type definitions and interfaces
-- `utils/` - Domain utility functions
-
-**Infrastructure Layer** (`src/infrastructure/`)
-- `services/` - Service implementations with external integrations
-- `utils/` - Helper functions and mappers
-
-**Presentation Layer** (`src/presentation/`)
-- `hooks/` - React hooks for UI integration
-
-**Main Export** (`src/index.ts`)
-- Single entry point for all exports
-- Organized by category
-- This file
-
-## Dependencies
-
-- Exports all domain entities and types
-- Exports all infrastructure services
-- Exports all presentation hooks
-- Re-exports utilities from domain and infrastructure layers