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

package/src/media/infrastructure/services/MediaValidationService.README.md

@@ -1,135 +0,0 @@
-# MediaValidationService
-
-## Purpose
-Validates media files before upload by checking file size, type, and other properties to ensure compatibility and performance.
-
-## File Location
-`/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-media/src/infrastructure/services/MediaValidationService`
-
-## Strategy
-
-### Core Purpose
-- Validate media files before upload
-- Check file size constraints
-- Verify supported file types
-- Provide actionable feedback (errors, warnings, recommendations)
-- Prevent upload of invalid or problematic files
-
-### Usage Scenarios
-- Pre-upload validation checks
-- Form submission workflows
-- File selection validation
-- User feedback on file issues
-- Quality control processes
-
-### Integration Points
-- Before upload operations
-- After file selection
-- In form validation workflows
-- User input feedback loops
-- File processing pipelines
-
-## Forbidden
-
-### MUST NOT
-- Allow uploads of files exceeding size limits
-- Accept unsupported file types
-- Ignore validation results
-- Proceed with upload when isValid is false
-- Assume all files are valid
-- Skip validation for performance
-
-### MUST NEVER
-- Upload files with errors
-- Modify files during validation
-- Cache validation results indefinitely
-- Assume synchronous validation
-- Ignore platform-specific constraints
-- Allow bypass of critical validation rules
-
-## Rules
-
-### Validation Rules
-- MUST check file size (max 50 MB)
-- MUST check file type against supported formats
-- MUST return validation result with isValid boolean
-- MUST provide errors for upload-blocking issues
-- MUST provide warnings for performance concerns
-- MUST provide recommendations for improvements
-
-### File Size Limits
-- MUST reject files over 50 MB (error)
-- MUST warn on files over 10 MB
-- MUST recommend compression for large files
-- MUST format file sizes for readability
-- MUST consider media type for limits
-
-### Supported File Types
-- Images: JPEG, PNG, WebP
-- Audio: MP3, WAV, M4A
-- Video: MP4, MOV
-- MUST validate MIME types
-- MUST reject unsupported types with clear error
-
-### Validation Results
-- MUST include isValid boolean
-- MUST include errors array (upload blockers)
-- MUST include warnings array (performance impacts)
-- MUST include recommendations array (improvements)
-- MUST be serializable for transport
-
-### Error Handling
-- MUST handle missing file metadata
-- MUST handle invalid file structures
-- MUST handle async validation operations
-- MUST provide specific error messages
-- MUST support batch validation
-
-### Feedback Levels
-- Errors: Critical issues that prevent upload
-- Warnings: Non-critical but impactful issues
-- Recommendations: Suggestions for optimization
-- MUST clearly distinguish between levels
-
-## AI Agent Guidelines
-
-### When Implementing Validation
-1. Always check file metadata completeness
-2. Validate size limits before processing
-3. Check MIME type against allowed list
-4. Provide specific, actionable error messages
-5. Return structured validation result
-
-### When Working with Validation Results
-- Check isValid flag before proceeding
-- Display errors to user (block upload)
-- Show warnings to user (allow upload)
-- Present recommendations as optional
-- Format messages for user understanding
-
-### When Adding Validation Rules
-- Add new size limits with clear thresholds
-- Add new file types with MIME validation
-- Add custom rules for specific use cases
-- Maintain backward compatibility
-- Document rule changes
-
-### When Refactoring
-- Keep validation API stable
-- Preserve error message format
-- Maintain validation logic flow
-- Don't change result structure
-- Add deprecation warnings for breaking changes
-
-### Common Patterns to Follow
-- Receive file -> Check metadata -> Validate rules -> Return result
-- Check isValid -> If false, show errors -> If true, proceed
-- Check size -> If large, warn and recommend compression
-- Check type -> If invalid, error with supported types
-- Always handle async validation properly
-
-## Dependencies
-
-- Domain types: MediaValidation from MultimediaFlashcardTypes
-- Internal utilities: mediaHelpers (formatFileSize)
-- No external library dependencies (uses native File API)

package/src/media/infrastructure/services/MultimediaFlashcardService.README.md

@@ -1,142 +0,0 @@
-# MultimediaFlashcardService
-
-## Purpose
-Main service that manages all media operations for media-enabled flashcards from a single point, combining upload, generation, validation, and optimization capabilities through a singleton instance.
-
-## File Location
-`/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-media/src/infrastructure/services/MultimediaFlashcardService`
-
-## Strategy
-- Provide unified interface for all flashcard media operations
-- Coordinate upload, generation, validation, and optimization services
-- Maintain singleton pattern for resource efficiency
-- Simplify media management for flashcard applications
-- Support general flashcard media requirements
-- Enable batch operations for card sets
-- Provide consistent API across all media operations
-- Reduce complexity by exposing single service instance
-
-## Forbidden
-- **DO NOT** create multiple service instances (use singleton only)
-- **DO NOT** call media operations without validation
-- **DO NOT** assume AI generation is always available
-- **DO NOT** ignore optimization recommendations
-- **DO NOT** bypass singleton pattern with direct service instantiation
-- **DO NOT** proceed without error handling for any operation
-- **DO NOT** mix flashcard media with other media types
-- **DO NOT** assume all operations will succeed
-
-## Rules
-1. MUST use getInstance() to retrieve service instance
-2. MUST NOT create new instances with constructor
-3. MUST maintain single instance across application lifecycle
-4. MUST validate media before upload operations
-5. MUST handle all operation failures gracefully
-6. MUST support MediaAttachment and MediaPosition types
-7. MUST provide consistent interface through all methods
-8. MUST initialize all sub-services on first use
-9. MUST coordinate between sub-services for complex operations
-10. MUST handle asynchronous operations properly
-11. MUST return appropriate error messages for failures
-
-## AI Agent Guidelines
-
-When working with MultimediaFlashcardService:
-
-1. **Singleton Pattern**: Always use getInstance(), never constructor
-2. **Validation First**: Validate before upload or generation
-3. **Operation Flow**: Follow validate -> upload/generate -> optimize -> store
-4. **Error Handling**: Handle errors at each step appropriately
-5. **Resource Management**: Rely on singleton for efficient resource use
-6. **Type Safety**: Use MediaAttachment and MediaPosition types
-7. **Service Coordination**: Let service coordinate sub-operations
-
-### Flashcard Creation Workflow
-
-- **Step 1 - Get Instance**: `MultimediaFlashcardService.getInstance()`
-- **Step 2 - Select File**: Pick file from device or camera
-- **Step 3 - Validate**: Run validation, check results
-- **Step 4 - Upload**: Upload if validation passes
-- **Step 5 - Optimize** (Optional): Optimize if file is large
-- **Step 6 - Store**: Save attachment with flashcard data
-- **Step 7 - Handle Errors**: Provide feedback at each step
-
-### Media Upload Workflow
-
-- Use for user-selected media (images, audio, video)
-- Always validate before uploading
-- Consider compression for large files
-- Set appropriate position if applicable
-- Store returned attachment with flashcard
-- Handle upload failures with user feedback
-
-### AI Content Generation Workflow
-
-- Use for text-to-image or text-to-audio generation
-- Validate prompts before generation
-- Check credit/balance availability
-- Set appropriate options (language, voice, style)
-- Handle generation failures gracefully
-- Store successful attachments with flashcard
-
-### Media Optimization Workflow
-
-- Use when file size impacts performance
-- Choose quality level based on use case
-- Consider flashcard importance (front/back)
-- Calculate expected size reduction
-- Preserve attachments through optimization
-- Update flashcard with optimized media
-
-### Media Deletion Workflow
-
-- Verify media ownership before deletion
-- Check flashcard associations
-- Confirm deletion with user if needed
-- Delete from all storage locations
-- Update flashcard references
-- Handle missing files gracefully
-
-### Batch Operations
-
-- For multiple flashcards, use same service instance
-- Process uploads/generations in sequence
-- Collect results before saving
-- Handle partial failures appropriately
-- Consider parallel operations for independent media
-- Track progress for user feedback
-
-### Error Handling Patterns
-
-- **Validation Errors**: Show to user, block upload
-- **Upload Errors**: Retry or allow alternative file
-- **Generation Errors**: Check credits, try different prompt
-- **Optimization Errors**: Continue with original media
-- **Deletion Errors**: Log error, notify user
-- **Network Errors**: Show connection message, allow retry
-
-### Service Coordination
-
-The service automatically coordinates:
-- UploadService handles file uploads
-- GenerationService handles AI generation
-- ValidationService checks file validity
-- OptimizerService handles compression
-- All services work together seamlessly
-
-### Performance Considerations
-
-- Singleton reduces memory footprint
-- Single instance maintains state efficiently
-- Sub-services initialized once
-- All operations are asynchronous
-- Consider lazy loading for large card sets
-- Cache media URLs when possible
-
-## Dependencies
-- MediaUploadService for upload operations
-- MediaGenerationService for AI generation
-- MediaValidationService for validation
-- MediaOptimizerService for optimization
-- MediaAttachment type from domain layer
-- MediaPosition type for media placement

package/src/media/infrastructure/utils/mediaHelpers.README.md

@@ -1,96 +0,0 @@
-# Media Helper Utilities
-
-## Purpose
-Core utility functions for media type detection, duration calculation, thumbnail generation, and file size operations.
-
-## File Location
-`src/infrastructure/utils/mediaHelpers.ts`
-
-## Strategy
-- Provide pure utility functions for common media operations
-- Enable media type classification from MIME types
-- Support file size calculations and formatting
-- Generate thumbnails for video files
-- Extract metadata from media collections
-- Maintain framework-agnostic approach where possible
-
-## Forbidden
-- **DO NOT** add business logic to utility functions
-- **DO NOT** make network calls or API requests
-- **DO NOT** modify input parameters (pure functions)
-- **DO NOT** store state or cache results globally
-- **DO NOT** depend on React or UI frameworks
-- **DO NOT** throw exceptions without clear error messages
-- **DO NOT** use locale-specific string formatting
-
-## Rules
-1. All functions must be pure (same input = same output)
-2. File size calculations must use bytes as the base unit
-3. Media type detection must use MIME type patterns
-4. Duration calculation must return seconds (or undefined for non-audio/video)
-5. Thumbnail generation must only return URLs for video files
-6. Type extraction must remove duplicates and preserve order
-7. Size formatting must use appropriate units (Bytes/KB/MB/GB)
-8. All functions must handle edge cases (empty arrays, null values)
-9. Must support both CardMediaAttachment and MediaAttachment types
-10. Must return fallback values for invalid inputs
-
-## AI Agent Guidelines
-
-When working with media helper utilities:
-
-1. **Type Detection**: Always use `getCardMediaType()` for consistent type classification from MIME types
-2. **Size Calculations**: Use `calculateTotalSize()` for aggregating file sizes, never sum manually
-3. **Duration Handling**: Check for undefined return value from `getMediaDuration()` for non-audio/video files
-4. **Thumbnail Generation**: Only videos return thumbnail URLs; images return undefined
-5. **Type Extraction**: Use `extractMediaTypes()` to get unique media types from collections
-6. **Size Formatting**: Always use `formatFileSize()` for user-facing size displays
-7. **Null Safety**: Always handle null/undefined returns appropriately
-8. **Collection Operations**: Use provided utilities instead of manual array operations
-
-### Media Type Classification
-
-- **Supported Types**: "image", "audio", "video"
-- **Detection Method**: MIME type pattern matching
-- **Default Behavior**: Unknown types default to "image"
-- **Common Patterns**:
-  - Images: image/jpeg, image/png, image/gif, image/webp
-  - Audio: audio/mp3, audio/wav, audio/mpeg, audio/aac
-  - Video: video/mp4, video/quicktime, video/x-msvideo
-
-### File Size Operations
-
-1. **Aggregation**: `calculateTotalSize()` - Sum all file sizes in bytes
-2. **Formatting**: `formatFileSize()` - Convert bytes to readable format
-3. **Unit Selection**: Automatically chooses appropriate unit (Bytes/KB/MB/GB)
-4. **Rounding**: Rounds to 2 decimal places for KB and above
-
-### Duration and Metadata
-
-1. **Duration**: Returns seconds for audio/video, undefined for images
-2. **Thumbnails**: Only generated for video files using external service
-3. **Type Extraction**: Returns unique types in order of appearance
-4. **Media Support**: Works with both CardMediaAttachment and MediaAttachment
-
-### Error Handling
-
-1. Handle undefined returns from `getMediaDuration()` for images
-2. Handle undefined returns from `generateThumbnail()` for non-videos
-3. Validate MIME type strings before type detection
-4. Handle empty arrays in collection operations
-5. Always check for null/undefined file objects
-
-### Usage Patterns
-
-1. **Media Analysis**: Combine multiple utilities for comprehensive file analysis
-2. **Validation**: Use type detection and size calculation for pre-upload validation
-3. **Statistics**: Aggregate collection data using type extraction and size calculation
-4. **Display**: Format sizes for user interfaces using formatFileSize
-5. **Filtering**: Use extracted types for conditional logic and filtering
-
-## Dependencies
-
-- Domain layer types (MediaAttachment, CardMediaAttachment)
-- No external libraries
-- No framework dependencies
-- Pure TypeScript/JavaScript utilities

package/src/media/infrastructure/utils/mediaPickerMappers.README.md

@@ -1,129 +0,0 @@
-# Media Picker Mappers
-
-## Purpose
-Mapper functions to convert between expo-image-picker types and domain types, maintaining abstraction layer.
-
-## File Location
-`src/infrastructure/utils/mediaPickerMappers.ts`
-
-## Strategy
-- Isolate expo-image-picker dependency to infrastructure layer
-- Provide clean mapping between external and domain types
-- Handle permission status conversion
-- Convert media type enums to library-specific formats
-- Transform picker results to domain entities
-- Maintain compatibility with expo-image-picker API changes
-
-## Forbidden
-- **DO NOT** import expo-image-picker outside infrastructure layer
-- **DO NOT** add business logic to mapping functions
-- **DO NOT** modify input parameters during mapping
-- **DO NOT** throw exceptions for invalid inputs (use defaults)
-- **DO NOT** add side effects to mapping functions
-- **DO NOT** directly use mapped types in domain or presentation layers
-- **DO NOT** create circular dependencies with picker implementation
-
-## Rules
-1. All mapping functions must be pure transformations
-2. Permission status must map UNDETERMINED to DENIED
-3. MediaType must convert to array format for expo-image-picker
-4. Asset properties must use fallback values for undefined fields
-5. All mappers must handle null/undefined inputs gracefully
-6. Mapped types must match domain type contracts exactly
-7. Must preserve all original data during transformation
-8. Type conversion must be reversible where possible
-9. Must handle all enum values explicitly
-10. Default values must be documented
-
-## AI Agent Guidelines
-
-When working with media picker mappers:
-
-1. **Layer Isolation**: Only use mappers in infrastructure layer, never in domain/presentation
-2. **Type Conversion**: Always use provided mappers, never manually convert types
-3. **Permission Handling**: Check mapped permission status, not raw expo-image-picker values
-4. **Media Types**: Use domain MediaType enum, then map to expo format when calling picker
-5. **Result Processing**: Always map picker results before passing to other layers
-6. **Fallback Values**: Be aware that asset properties may have default values
-7. **Null Safety**: Handle undefined optional properties in mapped results
-8. **Version Compatibility**: Update mappers when upgrading expo-image-picker
-
-### Permission Status Mapping
-
-- **GRANTED** → GRANTED (full access)
-- **DENIED** → DENIED (no access)
-- **UNDETERMINED** → DENIED (treat as denied, request again)
-
-**Strategy**: Convert undetermined to denied to force explicit permission request
-
-### MediaType Mapping
-
-| Domain MediaType | expo-image-picker Format |
-|-----------------|------------------------|
-| IMAGE | ["images"] |
-| VIDEO | ["videos"] |
-| ALL | ["images", "videos"] |
-| undefined | ["images"] (default) |
-
-**Strategy**: Convert domain enum to array format required by library
-
-### Asset Transformation
-
-All asset fields are mapped with fallback values:
-- **uri**: Required, no fallback
-- **width**: Number, fallback 0
-- **height**: Number, fallback 0
-- **type**: MediaType enum (IMAGE or VIDEO)
-- **fileSize**: Number, fallback 0
-- **fileName**: String or undefined
-- **duration**: Number or undefined (video only)
-- **base64**: String or undefined (only when requested)
-- **mimeType**: String or undefined
-
-### Picker Result Structure
-
-**Input Structure (expo-image-picker)**:
-- A boolean `canceled` field indicating whether the user cancelled the operation
-- An optional `assets` array containing Asset objects from expo-image-picker
-
-**Output Structure (MediaPickerResult)**:
-- A boolean `canceled` field (same as input)
-- An optional `assets` array containing MediaAsset domain objects
-- All Asset fields are transformed to MediaAsset fields with appropriate fallback values
-
-### Integration Patterns
-
-1. **Before Picker**: Convert domain types to picker types
-2. **After Picker**: Convert picker results to domain types
-3. **Permission Check**: Map permission status before domain layer access
-4. **Error Handling**: Check canceled flag before processing assets
-5. **Type Safety**: Use domain types throughout application logic
-
-### Common Workflows
-
-1. **Permission Request**: Check status → Map → Request → Map result
-2. **Media Selection**: Map MediaType → Launch picker → Map result
-3. **Multiple Selection**: Handle array of assets in mapper
-4. **Camera vs Library**: Use same mappers for both picker types
-
-### Validation Rules
-
-1. Always check `canceled` flag before accessing assets
-2. Validate assets array exists and has length > 0
-3. Handle undefined optional properties gracefully
-4. Check permission status before launching picker
-5. Handle null asset properties with fallback values
-
-### Error Handling
-
-1. Cancelled operations return `{ canceled: true }`
-2. Missing assets return empty array or undefined
-3. Invalid types use default fallback values
-4. Permission denied operations should be handled at application level
-5. Never throw exceptions from mapping functions
-
-## Dependencies
-
-- expo-image-picker (external library)
-- Domain layer types (MediaAsset, MediaPickerResult, MediaType, MediaLibraryPermission)
-- Infrastructure layer only

package/src/media/presentation/hooks/card-multimedia.types.README.md

@@ -1,177 +0,0 @@
-# Card Multimedia Hook Types
-
-## Purpose
-TypeScript return type interfaces for card-specific multimedia hooks in the presentation layer.
-
-## File Location
-`src/presentation/hooks/card-multimedia.types.ts`
-
-## Strategy
-- Define contracts for card multimedia hook implementations
-- Ensure type safety across card media operations
-- Provide consistent return types for upload, generation, and validation
-- Support card-specific media operations (including image search)
-- Enable proper error handling and loading states
-- Maintain separation between card and general multimedia types
-
-## Forbidden
-- **DO NOT** import implementation details or hooks in type files
-- **DO NOT** mix CardMediaAttachment and MediaAttachment types
-- **DO NOT** add business logic to type definitions
-- **DO NOT** use `any` type for function parameters or returns
-- **DO NOT** create circular dependencies with domain types
-- **DO NOT** export implementation-specific types
-- **DO NOT** modify these types without updating all hook implementations
-
-## Rules
-1. All hook returns must include loading state, error state, and operation function
-2. Async operations must return Promise with appropriate type
-3. Error states must be string | null (not Error objects)
-4. Progress/results must be null when not active
-5. Boolean states must clearly indicate operation in progress
-6. All interfaces must be exported and public
-7. Type names must follow Use*Result pattern
-8. Functions must accept domain types, not external types
-9. Optional parameters must be clearly marked
-10. Return types must match hook implementations exactly
-
-## AI Agent Guidelines
-
-When working with card multimedia hook types:
-
-1. **Type Imports**: Always import types from this file for card multimedia hooks
-2. **Hook Implementation**: Implement hooks that return these exact interfaces
-3. **Card vs General**: Use Card* types for card-specific operations, Media* for general
-4. **Error Handling**: Always check error state before using results
-5. **Loading States**: Respect loading states to prevent race conditions
-6. **Progress Tracking**: Use progress objects for upload operations
-7. **Type Safety**: Use these types for all card multimedia hook return values
-8. **Testing**: Mock these interfaces when testing card media operations
-
-### Hook Return Type Structure
-
-All card multimedia hook returns follow this consistent pattern:
-
-**Core Components**:
-- **operationFunction**: An async function that accepts parameters and returns a Promise with the result type
-- **isOperationInProgress**: A boolean flag indicating whether the operation is currently running
-- **operationResult**: The result object or null when no operation is active
-- **error**: A string containing error messages or null when no error exists
-
-### UseCardMediaUploadResult
-
-**Purpose**: Card media upload operations with compression options
-
-**Key Features**:
-- Upload function accepts file and compression options
-- Tracks upload progress
-- Returns CardMediaAttachment
-- Handles upload errors
-
-**Usage Pattern**:
-1. Check `isUploading` before calling
-2. Call `uploadMedia()` with file and optional compression
-3. Monitor `uploadProgress` during upload
-4. Check `error` state on completion
-5. Use returned CardMediaAttachment on success
-
-### UseCardMediaGenerationResult
-
-**Purpose**: Card media generation (AI-based generation, image search)
-
-**Key Features**:
-- Generation function accepts request parameters
-- Tracks generation status
-- Returns CardMediaGenerationResult
-- Supports multiple generation methods
-
-**Usage Pattern**:
-1. Prepare CardMediaGenerationRequest
-2. Check `isGenerating` before calling
-3. Call `generateMedia()` with request
-4. Access `generationResult` when complete
-5. Handle `error` if generation fails
-
-### UseCardMediaValidationResult
-
-**Purpose**: Card media validation before upload or processing
-
-**Key Features**:
-- Validation function accepts file
-- Tracks validation status
-- Returns CardMediaValidation result
-- Provides detailed validation errors
-
-**Usage Pattern**:
-1. Check `isValidating` before calling
-2. Call `validateMedia()` with file
-3. Access `validation` result for validity check
-4. Use `validation.errors` array for error details
-5. Check `error` state for validation failures
-
-### UseCardMultimediaFlashcardResult
-
-**Purpose**: Card flashcard CRUD operations
-
-**Key Features**:
-- Create card with multimedia
-- Update card media
-- Delete specific media attachment
-- Tracks processing state
-- Returns CardMultimediaFlashcard
-
-**Usage Pattern**:
-1. Create: Call `createCardMultimedia()` with card data
-2. Update: Call `updateCardMedia()` with cardId and media array
-3. Delete: Call `deleteCardMedia()` with attachmentId
-4. Check `isProcessing` before operations
-5. Handle `error` state for failures
-
-### Card vs General Multimedia Types
-
-| Operation | Card Types | General Types | Key Difference |
-|-----------|-----------|---------------|----------------|
-| Upload | CardMediaAttachment | MediaAttachment | Card-specific metadata |
-| Generation | CardMediaGenerationRequest | MediaGenerationRequest | Cards include image search |
-| Validation | CardMediaValidation | MediaValidation | Card-specific rules |
-| Flashcard | CardMultimediaFlashcard | MultimediaFlashcard | Different entity types |
-
-### Type Guards and Validation
-
-1. **Upload Hook**: Check for `uploadMedia` function and `isUploading` boolean
-2. **Generation Hook**: Check for `generateMedia` function and `isGenerating` boolean
-3. **Validation Hook**: Check for `validateMedia` function and `isValidating` boolean
-4. **Flashcard Hook**: Check for all three CRUD functions and `isProcessing` boolean
-
-### Error Handling Patterns
-
-1. Always check if `error !== null` before using results
-2. Errors are strings, not Error objects
-3. Clear error before starting new operation
-4. Show user-friendly error messages
-5. Handle null states for progress/results
-
-### Async Operation Patterns
-
-1. **Before Call**: Check loading state to prevent concurrent calls
-2. **During Call**: Show loading indicator based on boolean state
-3. **After Call**: Check error state, then use result
-4. **Error Case**: Display error, reset loading state
-5. **Success Case**: Use result, clear error
-
-### Related Domain Types
-
-These interfaces use domain types:
-- CardMediaAttachment
-- CardMediaGenerationRequest
-- CardMediaGenerationResult
-- CardMediaCompressionOptions
-- CardMediaValidation
-- CardMediaUploadProgress
-- CardMultimediaFlashcard
-
-## Dependencies
-
-- Domain layer types (Card* entities)
-- Presentation layer hooks
-- No external dependencies