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

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/media/presentation/hooks/useCardMediaValidation.ts

@@ -1,101 +0,0 @@
-/**
- * Card Media Validation Hook
- * Hook for validating card media files
- */
-
-import { useState, useCallback } from "react";
-import { formatFileSize } from "../../infrastructure/utils/media-collection-utils";
-import type { UseCardMediaValidationResult } from "./card-multimedia.types";
-import type { CardMediaValidation, CardMediaFile } from "../../domain/entities/CardMultimedia.types";
-
-export const useCardMediaValidation = (): UseCardMediaValidationResult => {
-  const [isValidating, setIsValidating] = useState(false);
-  const [validation, setValidation] =
-    useState<CardMediaValidation | null>(null);
-  const [error, setError] = useState<string | null>(null);
-
-  const validateMedia = useCallback(
-    async (file: CardMediaFile): Promise<CardMediaValidation> => {
-      try {
-        setIsValidating(true);
-        setError(null);
-
-        // Simulate validation
-        await new Promise((resolve) => setTimeout(resolve, 500));
-
-        const errors: string[] = [];
-        const warnings: string[] = [];
-        const recommendations: string[] = [];
-
-        // File size validation
-        const maxSize = 50 * 1024 * 1024; // 50MB
-        if (file.size > maxSize) {
-          errors.push(
-            `File size (${formatFileSize(file.size)}) exceeds maximum allowed size (${formatFileSize(maxSize)})`,
-          );
-        } else if (file.size > 10 * 1024 * 1024) {
-          // 10MB
-          warnings.push(`Large file size may impact performance`);
-          recommendations.push("Consider compressing file");
-        }
-
-        // File type validation
-        const supportedTypes = [
-          "image/jpeg",
-          "image/png",
-          "image/webp",
-          "audio/mp3",
-          "audio/wav",
-          "audio/m4a",
-          "video/mp4",
-          "video/mov",
-        ];
-
-        if (!supportedTypes.includes(file.type)) {
-          errors.push(`Unsupported file type: ${file.type}`);
-        }
-
-        // Media-specific validations
-        if (file.type.startsWith("image/")) {
-          if (file.size > 5 * 1024 * 1024) {
-            // 5MB for images
-            warnings.push("Very large image may cause performance issues");
-            recommendations.push("Consider resizing image to under 5MB");
-          }
-        }
-
-        const result: CardMediaValidation = {
-          isValid: errors.length === 0,
-          errors,
-          warnings,
-          recommendations,
-        };
-
-        setValidation(result);
-        return result;
-      } catch (err) {
-        const errorMessage =
-          err instanceof Error ? err.message : "Validation failed";
-        setError(errorMessage);
-        setIsValidating(false);
-
-        return {
-          isValid: false,
-          errors: [errorMessage],
-          warnings: [],
-          recommendations: [],
-        };
-      } finally {
-        setIsValidating(false);
-      }
-    },
-    [],
-  );
-
-  return {
-    validateMedia,
-    isValidating,
-    validation,
-    error,
-  };
-};

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

@@ -1,158 +0,0 @@
-# useCardMultimediaFlashcard
-
-## Purpose
-Card-specific hook for creating and managing flashcards with media attachments using CardMediaAttachment types.
-
-## File Location
-`src/presentation/hooks/useCardMultimediaFlashcard.ts`
-
-## Strategy
-- Provide card-specific interface for flashcard creation with media
-- Support CardMediaAttachment with position-aware media management
-- Enable card-specific media operations (create, update, delete)
-- Automatically analyze card media composition
-- Calculate storage requirements for card media
-- Track download status for offline card access
-- Maintain card-specific ID prefixes and naming conventions
-
-## Forbidden
-- **DO NOT** create cards without required front/back content
-- **DO NOT** add media without position assignment (front, back, both)
-- **DO NOT** mix MediaAttachment with CardMediaAttachment types
-- **DO NOT** use mock implementations in production
-- **DO NOT** assume card media is downloaded without checking
-- **DO NOT** modify card structure directly after creation
-- **DO NOT** exceed practical media limits per card
-- **DO NOT** bypass media size estimation
-- **DO NOT** use incorrect ID prefixes (must use card_multimedia_)
-
-## Rules
-1. Always use CardMediaAttachment type (not MediaAttachment)
-2. Always assign position (front, back, both) to each media
-3. Use card_multimedia_ prefix for card IDs
-4. Calculate estimatedSize from all card media
-5. Populate mediaType array with unique types
-6. Set hasMedia based on media array length
-7. Check isDownloaded from all media attachments
-8. Support empty media array for text-only cards
-9. Return complete CardMultimediaFlashcard object
-10. Clear processing state on completion
-
-## AI Agent Guidelines
-
-When working with useCardMultimediaFlashcard hook:
-
-1. **Type Correctness**: Always use CardMediaAttachment (not MediaAttachment)
-2. **Position Assignment**: Every media must have position (front, back, both)
-3. **Media Upload**: Use useCardMediaUpload for proper type handling
-4. **Card Analysis**: Leverage auto-generated hasMedia, mediaType, isDownloaded
-5. **ID Prefixes**: Ensure card IDs use card_multimedia_ prefix
-
-### Card Creation Workflow
-
-1. Prepare card content (front, back, difficulty, tags)
-2. Upload media using useCardMediaUpload (gets CardMediaAttachment)
-3. Assign position to each media attachment
-4. Call createCardMultimedia with data
-5. Receive CardMultimediaFlashcard object
-6. Store or display the completed card
-
-### CardMultimediaFlashcard Structure
-
-CardMultimediaFlashcard includes:
-- id: Unique card ID (card_multimedia_ prefix)
-- front: Front side content
-- back: Back side content
-- difficulty: easy/medium/hard
-- tags: Topic tags array
-- media: Array of CardMediaAttachment
-- hasMedia: Boolean flag
-- mediaType: Array of media types (image, audio, video)
-- isDownloaded: Boolean (all media downloaded)
-- estimatedSize: Total size in bytes
-- createdAt: ISO timestamp
-
-### CardMediaAttachment vs MediaAttachment
-
-Key differences:
-- CardMediaAttachment has position property (front, back, both)
-- CardMediaAttachment IDs use card_media_ prefix
-- CardMediaAttachment uses CardMediaPosition enum
-- CardMediaAttachment uses CardMediaType enum
-
-### Media Positioning Strategy
-
-**front**: Media for front side of card
-- Question images
-- Prompt audio
-- Instructional videos
-
-**back**: Media for back side of card
-- Answer images
-- Explanation audio
-- Solution videos
-
-**both**: Media for both sides
-- Background music
-- Contextual images
-- Reference materials
-
-### Card Management Functions
-
-**createCardMultimedia**: Create new card
-- Requires front and back content
-- Accepts CardMediaAttachment array
-- Assigns unique card_multimedia_ ID
-- Analyzes media composition
-- Calculates storage requirements
-
-**updateCardMedia**: Replace media on card
-- Takes cardId and new media array
-- Preserves card metadata
-- Re-analyzes composition
-- Updates size calculation
-
-**deleteCardMedia**: Remove specific media
-- Takes attachmentId (card_media_ prefix)
-- Updates media array
-- Recalculates size
-- Updates analysis
-
-### Integration with Card Hooks
-
-Use with card-specific hooks:
-- useCardMediaUpload: Upload with CardMediaAttachment type
-- useCardMediaValidation: Validate with card-specific rules
-- useCardMediaGeneration: Generate AI media for cards
-
-### Card Media Analysis
-
-**hasMedia**: True if media array length > 0
-**mediaType**: Unique array ['image', 'audio', 'video'] based on media
-**isDownloaded**: True if all media.isDownloaded are true
-**estimatedSize**: Sum of all media.fileSize values
-
-### Performance Guidelines
-
-- Limit to 5-10 media items per card
-- Warn if estimatedSize exceeds 25 MB
-- Use position to organize media effectively
-- Consider download status for offline usage
-- Balance media types across card sides
-
-### Best Practices
-
-1. Always assign meaningful positions to media
-2. Use tags for card organization and filtering
-3. Set appropriate difficulty levels
-4. Balance media between front and back
-5. Consider offline usage patterns
-6. Validate media before adding to cards
-
-## Dependencies
-
-- CardMultimediaFlashcardService (infrastructure layer)
-- Domain types: CardMultimediaFlashcard, CardMediaAttachment
-- useCardMediaUpload (for card-specific upload)
-- useCardMediaValidation (for card-specific validation)
-- useCardMediaGeneration (for card AI media)

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

@@ -1,94 +0,0 @@
-# useMedia
-
-## Purpose
-Core React hook for media selection operations (image/video picking, camera access) in React Native applications.
-
-## File Location
-`src/presentation/hooks/useMedia.ts`
-
-## Strategy
-- Provide unified interface for media picker and camera operations
-- Abstract expo-image-picker complexity from components
-- Centralize permission management logic
-- Maintain consistent state management across media operations
-- Enable type-safe media operations with proper TypeScript interfaces
-- Support single and multiple media selection workflows
-- Handle loading states and error propagation
-
-## Forbidden
-- **DO NOT** expose expo-image-picker implementation details to consumers
-- **DO NOT** automatically request permissions without explicit user action
-- **DO NOT** mix camera and library picker logic in single operations
-- **DO NOT** assume permission states - always check before operations
-- **DO NOT** bypass error handling or loading states
-- **DO NOT** use mock implementations in production without clear warnings
-- **DO NOT** allow operations while previous operation is in progress
-- **DO NOT** modify media assets after selection
-- **DO NOT** store selected media permanently in hook state
-
-## Rules
-1. Always check permission status before camera/library operations
-2. All picker operations must return MediaPickerResult with canceled flag
-3. Loading state must be true during async operations
-4. Error state must be cleared on new operation attempts
-5. Permission requests must be explicit, not automatic
-6. Selected media must be validated against type definitions
-7. Quality parameters must be in 0-1 range
-8. Aspect ratio must be [width, height] tuple
-9. File size must be included when available from picker
-10. Support both single and multiple selection based on function used
-
-## AI Agent Guidelines
-
-When working with useMedia hook:
-
-1. **Permission First**: Always request/check permissions before calling picker or camera functions
-2. **State Management**: Use isLoading to prevent duplicate operations during active calls
-3. **Error Handling**: Always check error state and handle user cancellation (canceled: true)
-4. **Type Safety**: Use MediaPickerOptions and CameraOptions interfaces for configuration
-5. **Validation**: Validate returned assets before processing (check if assets array exists)
-
-### Key Functions
-
-- **pickImage**: Single image selection from library with optional editing
-- **pickMultipleImages**: Multiple image selection with selection limit
-- **pickVideo**: Video selection from library
-- **launchCamera**: Photo capture via device camera
-- **launchCameraForVideo**: Video recording via device camera
-- **requestCameraPermission**: Request camera access permission
-- **requestMediaLibraryPermission**: Request photo library access permission
-- **getCameraPermissionStatus**: Check current camera permission state
-- **getMediaLibraryPermissionStatus**: Check current library permission state
-
-### Media Selection Workflow
-
-1. Check permission status before operation
-2. Request permission if not granted
-3. Call appropriate picker/camera function with options
-4. Check canceled flag before processing assets
-5. Validate assets array exists and has items
-6. Process first asset (or all for multiple selection)
-
-### Quality Guidelines
-
-- HIGH (1.0): Original quality, largest file size
-- MEDIUM (0.7): Balanced quality and size (recommended)
-- LOW (0.3): Smallest file size, reduced quality
-
-### Platform Requirements
-
-- **iOS**: Add NSCameraUsageDescription and NSPhotoLibraryUsageDescription to Info.plist
-- **Android**: Add CAMERA and READ_EXTERNAL_STORAGE permissions to AndroidManifest.xml
-
-### State Management
-
-- **isLoading**: True during any async picker/camera operation
-- **error**: String error message or null, cleared on new operations
-- **MediaPickerResult.canceled**: True when user cancels operation
-- **MediaPickerResult.assets**: Array of selected media or undefined
-
-## Dependencies
-
-- MediaPickerService (infrastructure layer)
-- Domain types: MediaAsset, MediaPickerResult, MediaPickerOptions, CameraOptions
-- expo-image-picker (via service layer)

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

@@ -1,118 +0,0 @@
-# useMediaGeneration
-
-## Purpose
-React hook for AI-powered media generation (text-to-image, text-to-audio) with result tracking.
-
-## File Location
-`src/presentation/hooks/useMediaGeneration.ts`
-
-## Strategy
-- Provide unified interface for AI media generation operations
-- Support multiple generation types (text-to-image, text-to-audio)
-- Track generation status and progress
-- Manage credit usage and balance tracking
-- Handle generation errors gracefully
-- Return structured results with metadata
-- Support customizable generation options
-
-## Forbidden
-- **DO NOT** start new generation while previous is in progress
-- **DO NOT** ignore credit costs before generation
-- **DO NOT** mock generation process in production without API integration
-- **DO NOT** assume generation will succeed - always check result.success
-- **DO NOT** expose API keys or AI service implementation details
-- **DO NOT** allow unlimited concurrent generations
-- **DO NOT** bypass generation timeout handling
-- **DO NOT** store large generation results permanently in hook state
-- **DO NOT** use empty or invalid prompts for generation
-
-## Rules
-1. Always validate prompt text before generation
-2. Check credit availability before generation operations
-3. Track processing time for each generation request
-4. Return unique requestId for each generation
-5. Support maxResults parameter for multiple outputs
-6. Generation state must be cleared on new operations
-7. Include creditsUsed in result metadata
-8. Handle both success and failure in result object
-9. Support language and voice options for audio generation
-10. Support style options for image generation
-
-## AI Agent Guidelines
-
-When working with useMediaGeneration hook:
-
-1. **Prompt Quality**: Use descriptive, specific prompts for better results
-2. **Credit Management**: Track credit costs and balance before operations
-3. **Error Handling**: Always check result.success field
-4. **Result Processing**: Validate attachments array before use
-5. **Options**: Use appropriate options for generation type
-
-### Generation Types
-
-**Text-to-Image** (type: 'text_to_image')
-- Generates images from text descriptions
-- Credit cost: 5 per generation
-- Default maxResults: 1
-- Supports style customization
-
-**Text-to-Audio** (type: 'text_to_audio')
-- Generates audio from text (text-to-speech)
-- Credit cost: 3 per generation
-- Default duration: 10 seconds
-- Supports voice, language, speed options
-
-### Generation Workflow
-
-1. Validate prompt text quality and length
-2. Check available credits
-3. Configure generation options
-4. Call generateMedia with request
-5. Monitor isGenerating state
-6. Process generationResult on completion
-7. Handle errors with user feedback
-
-### Result Structure
-
-GenerationResult includes:
-- success: Boolean indicating success/failure
-- attachments: Array of generated MediaAttachment
-- creditsUsed: Number of credits consumed
-- processingTime: Duration in milliseconds
-- requestId: Unique request identifier
-- error: Error message if failed
-
-### Generation Options
-
-**Image Options:**
-- maxResults: Number of images to generate (default: 1)
-- style: Image style preset
-
-**Audio Options:**
-- voice: Voice type (male/female)
-- language: Language code (e.g., 'tr-TR', 'en-US')
-- speed: Playback speed (default: 1.0)
-
-### Integration Requirements
-
-- Configure AI API endpoints
-- Implement authentication for AI services
-- Handle rate limiting and quotas
-- Implement retry logic for failed generations
-- Cache generation results when appropriate
-- Monitor credit balance and usage
-
-### Error Scenarios
-
-- Insufficient credits: Check balance before generation
-- Invalid prompt: Validate text quality and length
-- API timeout: Implement retry with exponential backoff
-- Content policy violations: Filter and validate prompts
-- Service unavailable: Graceful degradation with error message
-
-## Dependencies
-
-- MediaGenerationService (infrastructure layer)
-- Domain types: MediaGenerationRequest, MediaGenerationResult, MediaAttachment
-- Credit/balance tracking system
-- AI service APIs (text-to-image, text-to-speech)