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

package/src/media/presentation/hooks/useCardMediaGeneration.README.md

@@ -1,164 +0,0 @@
-# useCardMediaGeneration
-
-## Purpose
-Card-specific React hook for AI-powered media generation (text-to-image, text-to-audio, image-search) for flashcards.
-
-## File Location
-`src/presentation/hooks/useCardMediaGeneration.ts`
-
-## Strategy
-- Provide card-specific interface for AI media generation
-- Support text-to-image, text-to-audio, and image-search operations
-- Return CardMediaAttachment with position property
-- Track generation status and metadata
-- Manage credit costs for card media generation
-- Handle generation errors with proper feedback
-- Support card-specific generation options
-
-## Forbidden
-- **DO NOT** start generation while previous is in progress
-- **DO NOT** ignore credit costs before generation
-- **DO NOT** mock generation in production without AI API
-- **DO NOT** assume generation will succeed - check result.success
-- **DO NOT** expose API keys or AI implementation details
-- **DO NOT** allow unlimited concurrent generations
-- **DO NOT** bypass timeout handling for long generations
-- **DO NOT** store large results permanently in hook state
-- **DO NOT** use empty or invalid prompts
-- **DO NOT** mix with MediaAttachment (must use CardMediaAttachment)
-
-## Rules
-1. Always validate prompt text before generation
-2. Check credit availability before operations
-3. Track processing time for each request
-4. Return CardMediaAttachment with position property
-5. Return unique requestId for tracking
-6. Include creditsUsed in result metadata
-7. Support maxResults for multiple outputs
-8. Clear generation state on new operations
-9. Handle both success and failure gracefully
-10. Support language, voice, speed options for audio
-
-## AI Agent Guidelines
-
-When working with useCardMediaGeneration hook:
-
-1. **Type Specificity**: Use CardMediaAttachment (not MediaAttachment)
-2. **Position Awareness**: Generated media has position property
-3. **Prompt Quality**: Use descriptive prompts for better results
-4. **Credit Tracking**: Monitor credit costs and balance
-5. **Error Handling**: Always check result.success field
-
-### Generation Types
-
-**Text-to-Image** (type: 'text_to_image')
-- Generates images from text descriptions
-- Credit cost: 5 per generation
-- Default maxResults: 1
-- Returns CardMediaAttachment with position: 'both'
-- Supports style customization
-
-**Text-to-Audio** (type: 'text_to_audio')
-- Generates audio from text (TTS)
-- Credit cost: 3 per generation
-- Default duration: 10 seconds
-- Returns CardMediaAttachment with position: 'back'
-- Supports voice, language, speed options
-
-**Image Search** (type: 'image_search')
-- Searches for existing images
-- Credit cost: 2 per search
-- Default maxResults: 5
-- Returns CardMediaAttachment with position: 'both'
-- Finds relevant images from database
-
-### Generation Workflow
-
-1. Validate prompt text quality
-2. Check credit balance
-3. Select generation type
-4. Configure options (maxResults, voice, language, etc.)
-5. Call generateMedia with request
-6. Monitor isGenerating state
-7. Process CardMediaGenerationResult
-8. Handle success or error
-
-### Result Structure
-
-CardMediaGenerationResult includes:
-- success: Boolean success/failure
-- attachments: Array of CardMediaAttachment (with position)
-- creditsUsed: Credits consumed
-- processingTime: Duration in milliseconds
-- requestId: Unique identifier
-- error: Error message if failed
-
-### CardMediaAttachment Features
-
-Generated attachments include:
-- id: Unique ID with card_media_ prefix
-- type: CardMediaType (IMAGE, VIDEO, AUDIO)
-- position: CardMediaPosition (front, back, or both)
-- url: Generated media URL
-- filename: Generated filename
-- fileSize: Size in bytes
-- mimeType: MIME type
-- duration: Audio/video duration
-- thumbnailUrl: Thumbnail for visual media
-- isDownloaded: Download status
-- createdAt: ISO timestamp
-
-### Generation Options
-
-**Image Options:**
-- maxResults: Number of images (default: 1)
-- style: Image style preset
-
-**Audio Options:**
-- voice: Voice type (male/female)
-- language: Language code ('tr-TR', 'en-US')
-- speed: Playback speed (default: 1.0)
-
-**Image Search Options:**
-- maxResults: Number of results (default: 5)
-
-### Integration with Card Creation
-
-Typical workflow:
-1. Generate media with useCardMediaGeneration
-2. Receive CardMediaAttachment objects
-3. Use in createCardMultimedia call
-4. Position is automatically assigned by generation type
-5. Complete card with generated media
-
-### Credit Costs
-
-| Operation | Credits |
-|-----------|---------|
-| Text-to-Image | 5 |
-| Text-to-Audio | 3 |
-| Image Search | 2 |
-
-### Error Scenarios
-
-- Insufficient credits: Check balance before generation
-- Invalid prompt: Validate text quality
-- API timeout: Implement retry logic
-- Content policy: Filter prompts appropriately
-- Service unavailable: Graceful error handling
-
-### Integration Requirements
-
-- Configure AI service endpoints
-- Implement authentication for AI APIs
-- Handle rate limiting and quotas
-- Implement retry logic for failures
-- Cache results when appropriate
-- Monitor credit usage
-
-## Dependencies
-
-- CardMediaGenerationService (infrastructure layer)
-- Domain types: CardMediaGenerationRequest, CardMediaGenerationResult, CardMediaAttachment
-- Credit tracking system
-- AI service APIs (text-to-image, TTS, image search)

package/src/media/presentation/hooks/useCardMediaUpload.README.md

@@ -1,153 +0,0 @@
-# useCardMediaUpload
-
-## Purpose
-Card-specific React hook for uploading flashcard media files to server with progress tracking and compression support.
-
-## File Location
-`src/presentation/hooks/useCardMediaUpload.ts`
-
-## Strategy
-- Provide card-specific media upload interface
-- Support compression options for optimization
-- Track upload progress with percentage and status
-- Return CardMediaAttachment with position property
-- Handle upload errors gracefully
-- Generate thumbnails for visual media
-- Support various media types for cards
-
-## Forbidden
-- **DO NOT** start upload while previous is in progress
-- **DO NOT** ignore compression options
-- **DO NOT** upload without validation (use useCardMediaValidation)
-- **DO NOT** mock upload in production without backend integration
-- **DO NOT** modify file during upload (compress before)
-- **DO NOT** assume upload will succeed
-- **DO NOT** use hardcoded API endpoints
-- **DO NOT** bypass progress tracking
-- **DO NOT** store upload results permanently in state
-- **DO NOT** use incorrect ID prefixes (must use card_media_)
-
-## Rules
-1. Always validate before uploading (use useCardMediaValidation)
-2. Compression quality must be in 0-1 range
-3. Dimensions must be in pixels
-4. Progress updates every 10% or on status change
-5. Clear upload state on error or completion
-6. Return CardMediaAttachment with position property
-7. Generate thumbnail URL automatically
-8. Calculate duration for audio/video
-9. Update progress status: uploading -> completed/error
-10. Include unique fileId in progress tracking
-
-## AI Agent Guidelines
-
-When working with useCardMediaUpload hook:
-
-1. **Type Correctness**: Returns CardMediaAttachment (not MediaAttachment)
-2. **Position Property**: Uploaded media includes position field
-3. **Pre-upload Validation**: Always use useCardMediaValidation first
-4. **Progress Tracking**: Monitor uploadProgress for real-time updates
-5. **Compression**: Apply appropriate compression settings
-
-### Upload Workflow
-
-1. Validate file with useCardMediaValidation
-2. Select compression options based on type and size
-3. Call uploadMedia with file and options
-4. Monitor uploadProgress state
-5. Handle completion (success or error)
-6. Process returned CardMediaAttachment
-
-### CardMediaAttachment Structure
-
-Returned object includes:
-- id: Unique ID with card_media_ prefix
-- type: CardMediaType (IMAGE, VIDEO, AUDIO)
-- position: CardMediaPosition (defaults to 'both')
-- url: Uploaded file URL
-- filename: Original filename
-- fileSize: Size in bytes
-- mimeType: MIME type string
-- duration: Audio/video duration
-- thumbnailUrl: Thumbnail for visual media
-- caption: Optional caption text
-- isDownloaded: Download status
-- createdAt: ISO timestamp
-
-### Compression Guidelines
-
-**High Quality** (quality: 0.9, maxWidth: 4096)
-- Use for detailed card images
-- Larger file size, best quality
-
-**Medium Quality** (quality: 0.7, maxWidth: 1920) - RECOMMENDED
-- Balanced quality and size
-- Good for most card media
-
-**Low Quality** (quality: 0.5, maxWidth: 1280)
-- Use for card thumbnails
-- Smallest size, reduced quality
-
-### Upload Progress States
-
-- **uploading**: Upload in progress (0-99%)
-- **completed**: Upload finished successfully (100%)
-- **error**: Upload failed with error message
-
-### CardMediaUploadProgress
-
-Progress object includes:
-- fileId: Unique file identifier
-- progress: Percentage (0-100)
-- status: Current state (uploading/completed/error)
-- url: Final URL when completed
-
-### Integration with Card Creation
-
-Typical workflow:
-1. Select or generate media
-2. Validate with useCardMediaValidation
-3. Upload with useCardMediaUpload
-4. Receive CardMediaAttachment with position
-5. Add to card media array
-6. Create card with useCardMultimediaFlashcard
-
-### Position Assignment
-
-Uploaded media gets position property:
-- Default: 'both' (shown on both sides)
-- Can be overridden: 'front' or 'back'
-- Used to control media display on card sides
-
-### Multiple File Upload
-
-For multiple media files:
-1. Upload files sequentially or in parallel
-2. Collect CardMediaAttachment objects
-3. Assign positions appropriately
-4. Add to card media array
-5. Track individual upload progress
-
-### Integration Requirements
-
-- Configure API endpoint for card media upload
-- Implement authentication for uploads
-- Handle file size limits
-- Support retry logic for failures
-- Generate thumbnails automatically
-- Calculate media duration for audio/video
-
-### Error Handling
-
-Common error scenarios:
-- File too large: Validate before upload
-- Unsupported type: Check MIME type
-- Network timeout: Implement retry with backoff
-- Server error: Display user-friendly message
-- Authentication failure: Check token validity
-
-## Dependencies
-
-- CardMediaUploadService (infrastructure layer)
-- Domain types: CardMediaAttachment, CardMediaCompressionOptions, CardMediaUploadProgress
-- useCardMediaValidation (for pre-upload validation)

package/src/media/presentation/hooks/useCardMediaValidation.README.md

@@ -1,176 +0,0 @@
-# useCardMediaValidation
-
-## Purpose
-Card-specific React hook for validating flashcard media files before upload with enhanced controls for different media types.
-
-## File Location
-`src/presentation/hooks/useCardMediaValidation.ts`
-
-## Strategy
-- Provide comprehensive validation for card media files
-- Enhanced controls for images (5 MB warning threshold)
-- Support audio/video duration validation
-- Provide three-tier feedback: errors, warnings, recommendations
-- Card-specific validation rules compared to general media
-- Enable pre-upload validation workflow for cards
-- Return actionable feedback with media-type specific recommendations
-
-## Forbidden
-- **DO NOT** upload files that fail validation (have errors)
-- **DO NOT** ignore warnings - they indicate card performance issues
-- **DO NOT** bypass file type validation
-- **DO NOT** use mock validation in production
-- **DO NOT** allow files exceeding 50 MB limit
-- **DO NOT** modify files during validation
-- **DO NOT** store validation results permanently
-- **DO NOT** validate empty or missing files
-- **DO NOT** suppress errors for user convenience
-
-## Rules
-1. Always validate before card media upload
-2. Files over 50 MB must be rejected
-3. Files over 10 MB trigger warning
-4. Images over 5 MB trigger additional warning
-5. Unsupported MIME types must be rejected
-6. Validate file size, type, and format
-7. Return errors array for blocking issues
-8. Return warnings array for performance concerns
-9. Return recommendations array for improvements
-10. Clear validation state on new requests
-
-## AI Agent Guidelines
-
-When working with useCardMediaValidation hook:
-
-1. **Card-Specific Rules**: Use for card media (not general media)
-2. **Enhanced Image Control**: 5 MB threshold for images (stricter than general)
-3. **Three-Tier Feedback**: Distinguish errors, warnings, recommendations
-4. **Duration Control**: Check audio/video duration when available
-5. **Pre-upload Check**: Always validate before useCardMediaUpload
-
-### Validation Levels
-
-**Errors** (Blocking - Must fix):
-- File size exceeds 50 MB
-- Unsupported file type
-- Invalid file format
-- Missing required properties
-
-**Warnings** (Performance - Should fix):
-- File size over 10 MB (general warning)
-- Image size over 5 MB (card-specific warning)
-- Long duration audio/video
-- Large dimensions
-
-**Recommendations** (Improvements - Optional):
-- Reduce file size for card performance
-- Use recommended formats
-- Optimize dimensions
-- Compress for balance
-
-### Card-Specific vs General Validation
-
-| Feature | useMediaValidation | useCardMediaValidation |
-|---------|-------------------|------------------------|
-| Max file size | 50 MB | 50 MB |
-| General warning | 10 MB | 10 MB |
-| Image warning | None | 5 MB (extra) |
-| Duration check | No | Yes (5 min warning) |
-| Type support | Same | Same |
-
-### Supported File Types
-
-**Images:**
-- image/jpeg
-- image/png
-- image/webp
-
-**Audio:**
-- audio/mp3
-- audio/wav
-- audio/m4a
-
-**Video:**
-- video/mp4
-- video/mov
-
-### Validation Workflow
-
-1. Receive file object (name, type, size, uri)
-2. Check file size against limits
-3. Validate MIME type
-4. Apply card-specific rules (5 MB image warning)
-5. Check duration if available
-6. Generate errors, warnings, recommendations
-7. Return CardMediaValidation object
-
-### CardMediaValidation Structure
-
-Validation result includes:
-- isValid: Boolean (true if no errors)
-- errors: String array (blocking issues)
-- warnings: String array (performance concerns)
-- recommendations: String array (improvements)
-
-### File Size Guidelines
-
-**Images:**
-- Optimal: Under 2 MB
-- Card warning: 2-5 MB
-- Extra warning: 5-10 MB
-- Error: Over 50 MB
-
-**Audio:**
-- Optimal: Under 5 MB
-- Warning: 5-10 MB
-- Duration warning: Over 5 minutes
-- Error: Over 50 MB
-
-**Video:**
-- Optimal: Under 10 MB
-- Warning: 10-50 MB
-- Duration warning: Over 5 minutes
-- Error: Over 50 MB
-
-### Media Type Special Controls
-
-**Image Controls:**
-- Additional 5 MB warning threshold
-- Dimension recommendations
-- Format recommendations (JPEG for photos, PNG for graphics)
-
-**Audio Controls:**
-- Duration check (warn over 5 minutes)
-- Format recommendation (MP3 preferred)
-- Bitrate considerations
-
-**Video Controls:**
-- Duration check (warn over 5 minutes)
-- Format recommendation (MP4 preferred)
-- Resolution recommendations
-
-### Integration with Card Upload Flow
-
-Typical validation-upload workflow:
-1. Select file from picker
-2. Call validateMedia(file) from useCardMediaValidation
-3. Check validation.isValid
-4. If errors: Display and block upload
-5. If warnings: Display and get confirmation
-6. If recommendations: Display for reference
-7. Proceed to useCardMediaUpload if valid or confirmed
-
-### Best Practices
-
-1. Always validate before card media upload
-2. Show all three feedback levels to users
-3. Allow users to proceed with warnings
-4. Provide actionable recommendations
-5. Consider card performance implications
-6. Balance quality vs. file size
-
-## Dependencies
-
-- CardMediaValidationService (infrastructure layer)
-- Domain types: CardMediaValidation, file input interfaces
-- Media constants (card-specific size limits)

package/src/storage/domain/utils/__tests__/devUtils.test.ts

@@ -1,97 +0,0 @@
-/**
- * Development Utilities Tests
- */
-
-import { isDev, devWarn, devError, devLog } from '../devUtils';
-
-// Mock console methods
-const mockConsoleWarn = jest.fn();
-const mockConsoleError = jest.fn();
-const mockConsoleLog = jest.fn();
-
-describe('Development Utilities', () => {
-  beforeEach(() => {
-    jest.clearAllMocks();
-    
-    // Mock console methods
-    console.warn = mockConsoleWarn;
-    console.error = mockConsoleError;
-    console.log = mockConsoleLog;
-  });
-
-  describe('isDev', () => {
-    it('should return true when __DEV__ is true', () => {
-      (globalThis as any).__DEV__ = true;
-      expect(isDev()).toBe(true);
-    });
-
-    it('should return false when __DEV__ is false', () => {
-      (globalThis as any).__DEV__ = false;
-      expect(isDev()).toBe(false);
-    });
-
-    it('should return false when __DEV__ is undefined', () => {
-      delete (globalThis as any).__DEV__;
-      expect(isDev()).toBe(false);
-    });
-  });
-
-  describe('devWarn', () => {
-    it('should log warning when in development mode', () => {
-      (globalThis as any).__DEV__ = true;
-      
-      devWarn('Test warning', { data: 'test' });
-      
-      expect(mockConsoleWarn).toHaveBeenCalledWith('Test warning', { data: 'test' });
-    });
-
-    it('should not log warning when not in development mode', () => {
-      (globalThis as any).__DEV__ = false;
-      
-      devWarn('Test warning', { data: 'test' });
-      
-      expect(mockConsoleWarn).not.toHaveBeenCalled();
-    });
-  });
-
-  describe('devError', () => {
-    it('should log error when in development mode', () => {
-      (globalThis as any).__DEV__ = true;
-      
-      devError('Test error', new Error('test'));
-      
-      expect(mockConsoleError).toHaveBeenCalledWith('Test error', new Error('test'));
-    });
-
-    it('should not log error when not in development mode', () => {
-      (globalThis as any).__DEV__ = false;
-      
-      devError('Test error', new Error('test'));
-      
-      expect(mockConsoleError).not.toHaveBeenCalled();
-    });
-  });
-
-  describe('devLog', () => {
-    it('should log info when in development mode', () => {
-      (globalThis as any).__DEV__ = true;
-      
-      devLog('Test log', { info: 'test' });
-      
-      expect(mockConsoleLog).toHaveBeenCalledWith('Test log', { info: 'test' });
-    });
-
-    it('should not log info when not in development mode', () => {
-      (globalThis as any).__DEV__ = false;
-      
-      devLog('Test log', { info: 'test' });
-      
-      expect(mockConsoleLog).not.toHaveBeenCalled();
-    });
-  });
-
-  afterEach(() => {
-    // Clean up __DEV__ after each test
-    delete (globalThis as any).__DEV__;
-  });
-});