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

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

@@ -1,120 +0,0 @@
-/**
- * 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 MediaFile {
-  name: string;
-  type: string;
-  size: number;
-  uri?: string;
-}
-
-export interface CreateMultimediaCardData {
-  front: string;
-  back: string;
-  difficulty?: "easy" | "medium" | "hard";
-  tags?: string[];
-  media?: MediaAttachment[];
-}
-
-export interface MediaValidation {
-  isValid: boolean;
-  errors: string[];
-  warnings: string[];
-  recommendations: string[];
-}
-
-export interface MultimediaFlashcardService {
-  uploadMedia(
-    file: MediaFile,
-    options?: MediaCompressionOptions,
-  ): Promise<MediaAttachment>;
-  generateMedia(
-    request: MediaGenerationRequest,
-  ): Promise<MediaGenerationResult>;
-  validateMedia(file: MediaFile): 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

@@ -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

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

@@ -1,176 +0,0 @@
-# CardMultimediaService
-
-## Purpose
-Central service for managing all media operations in card-based applications, combining upload, generation, validation, and optimization capabilities through a singleton instance with card-specific media support.
-
-## File Location
-`/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-media/src/infrastructure/services/CardMultimediaService`
-
-## Strategy
-- Provide unified interface for all card media operations
-- Coordinate upload, generation, validation, and optimization services
-- Maintain singleton pattern for resource efficiency
-- Support card-specific media requirements (front/back/both positions)
-- Simplify media management for card applications
-- Enable batch operations for card sets
-- Provide consistent API across all media operations
-- Handle card-specific metadata and associations
-
-## 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 card media with non-card media types
-- **DO NOT** assume all operations will succeed
-- **DO NOT** ignore card-specific position requirements
-
-## 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 support CardMediaAttachment and CardMediaPosition types
-6. MUST handle position attribute (front/back/both) correctly
-7. MUST handle all operation failures gracefully
-8. MUST provide consistent interface through all methods
-9. MUST initialize all sub-services on first use
-10. MUST coordinate between sub-services for complex operations
-11. MUST handle asynchronous operations properly
-12. MUST return appropriate error messages for failures
-13. MUST support card-specific media constraints
-
-## AI Agent Guidelines
-
-When working with CardMultimediaService:
-
-1. **Singleton Pattern**: Always use getInstance(), never constructor
-2. **Validation First**: Validate before upload or generation
-3. **Position Awareness**: Always consider card position (front/back/both)
-4. **Operation Flow**: Follow validate -> upload/generate -> optimize -> store
-5. **Error Handling**: Handle errors at each step appropriately
-6. **Resource Management**: Rely on singleton for efficient resource use
-7. **Type Safety**: Use CardMediaAttachment and CardMediaPosition types
-8. **Card Context**: Maintain card-specific context throughout operations
-
-### Card Creation Workflow
-
-- **Step 1 - Get Instance**: `CardMultimediaService.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 - Set Position**: Assign position (front/back/both)
-- **Step 6 - Optimize** (Optional): Optimize if file is large
-- **Step 7 - Store**: Save attachment with card data
-- **Step 8 - Handle Errors**: Provide feedback at each step
-
-### Media Upload with Position
-
-- Use for user-selected media on card sides
-- Always validate before uploading
-- Set position based on card side (front/back/both)
-- Consider compression for large files
-- Store returned attachment with card
-- Handle upload failures with user feedback
-
-### AI Content Generation for Cards
-
-- Use for text-to-image or text-to-audio generation
-- Validate prompts before generation
-- Check credit/balance availability
-- Set position based on use case (front for questions, back for answers)
-- Handle generation failures gracefully
-- Store successful attachments with card
-
-### Position Management
-
-- **Front**: Media displayed on card front side
-  - Typically contains questions or prompts
-  - Often uses text-to-image generation
-  - May require higher quality
-
-- **Back**: Media displayed on card back side
-  - Typically contains answers or explanations
-  - Often uses text-to-audio generation
-  - Can be more compressed
-
-- **Both**: Media used on both sides
-  - Shared content between sides
-  - Less common but supported
-  - Maintain consistency across sides
-
-### Media Optimization for Cards
-
-- Use when file size impacts performance
-- Choose quality level based on position (front = higher, back = lower)
-- Consider card importance and frequency of use
-- Calculate expected size reduction
-- Preserve position through optimization
-- Update card with optimized media
-
-### Media Deletion for Cards
-
-- Verify media ownership before deletion
-- Check card associations and dependencies
-- Confirm deletion with user if needed
-- Delete from all storage locations
-- Update card references
-- Handle missing files gracefully
-
-### Batch Operations for Card Sets
-
-- For multiple cards, 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
-- Maintain position consistency across cards
-
-### 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
-- **Position Errors**: Validate position before operations
-- **Network Errors**: Show connection message, allow retry
-
-### Card-Specific Considerations
-
-- **Front Media**: Often focal point, prioritize quality
-- **Back Media**: Secondary content, can be more compressed
-- **Both Position**: Ensure quality works for both sides
-- **Multiple Media**: Support multiple attachments per card
-- **Position Validation**: Validate media type compatibility with position
-- **Card Associations**: Maintain references between media and cards
-
-### Service Coordination
-
-The service automatically coordinates:
-- CardMediaUploadService handles file uploads
-- CardMediaGenerationService handles AI generation
-- CardMediaValidationService checks file validity
-- CardMediaOptimizerService handles compression
-- All services work together with card-specific requirements
-
-### 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
-- Optimize media based on card usage patterns
-
-## Dependencies
-- CardMediaUploadService for upload operations
-- CardMediaGenerationService for AI generation (including image-search)
-- CardMediaValidationService for validation
-- CardMediaOptimizerService for optimization
-- CardMediaAttachment type from domain layer
-- CardMediaPosition type for card-side placement