@umituz/react-native-design-system 2.8.7 → 2.8.9

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

@@ -0,0 +1,177 @@
+# 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

package/src/media/presentation/hooks/card-multimedia.types.ts

@@ -0,0 +1,51 @@
+/**
+ * Card Multimedia Flashcard Hook Types
+ * Type definitions for card multimedia hooks
+ */
+
+import type {
+  CardMediaAttachment,
+  CardMediaGenerationRequest,
+  CardMediaGenerationResult,
+  CardMediaCompressionOptions,
+  CardMediaValidation,
+  CardMediaUploadProgress,
+  CardMultimediaFlashcard,
+} from "../../domain/entities/CardMultimedia.types";
+
+export interface UseCardMediaUploadResult {
+  uploadMedia: (
+    file: any,
+    options?: CardMediaCompressionOptions,
+  ) => Promise<CardMediaAttachment>;
+  isUploading: boolean;
+  uploadProgress: CardMediaUploadProgress | null;
+  error: string | null;
+}
+
+export interface UseCardMediaGenerationResult {
+  generateMedia: (
+    request: CardMediaGenerationRequest,
+  ) => Promise<CardMediaGenerationResult>;
+  isGenerating: boolean;
+  generationResult: CardMediaGenerationResult | null;
+  error: string | null;
+}
+
+export interface UseCardMediaValidationResult {
+  validateMedia: (file: any) => Promise<CardMediaValidation>;
+  isValidating: boolean;
+  validation: CardMediaValidation | null;
+  error: string | null;
+}
+
+export interface UseCardMultimediaFlashcardResult {
+  createCardMultimedia: (cardData: any) => Promise<CardMultimediaFlashcard>;
+  updateCardMedia: (
+    cardId: string,
+    media: CardMediaAttachment[],
+  ) => Promise<CardMultimediaFlashcard>;
+  deleteCardMedia: (attachmentId: string) => Promise<void>;
+  isProcessing: boolean;
+  error: string | null;
+}

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

@@ -0,0 +1,201 @@
+# Multimedia Hook Types
+
+## Purpose
+TypeScript return type interfaces for general multimedia hooks in the presentation layer.
+
+## File Location
+`src/presentation/hooks/multimedia.types.ts`
+
+## Strategy
+- Define contracts for general multimedia hook implementations
+- Ensure type safety across media operations
+- Provide consistent return types for upload, generation, and validation
+- Support general-purpose media operations
+- Enable proper error handling and loading states
+- Maintain separation from card-specific multimedia types
+
+## Forbidden
+- **DO NOT** import implementation details or hooks in type files
+- **DO NOT** mix MediaAttachment and CardMediaAttachment 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 multimedia hook types:
+
+1. **Type Imports**: Always import types from this file for general multimedia hooks
+2. **Hook Implementation**: Implement hooks that return these exact interfaces
+3. **General vs Card**: Use Media* types for general operations, Card* for card-specific
+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 general multimedia hook return values
+8. **Testing**: Mock these interfaces when testing media operations
+
+### Hook Return Type Structure
+
+All 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
+
+### UseMediaUploadResult
+
+**Purpose**: General media upload operations with compression options
+
+**Key Features**:
+- Upload function accepts file and compression options
+- Tracks upload progress
+- Returns MediaAttachment
+- 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 MediaAttachment on success
+
+### UseMediaGenerationResult
+
+**Purpose**: General media generation (AI-based generation without image search)
+
+**Key Features**:
+- Generation function accepts request parameters
+- Tracks generation status
+- Returns MediaGenerationResult
+- Supports core generation methods
+
+**Usage Pattern**:
+1. Prepare MediaGenerationRequest
+2. Check `isGenerating` before calling
+3. Call `generateMedia()` with request
+4. Access `generationResult` when complete
+5. Handle `error` if generation fails
+
+### UseMediaValidationResult
+
+**Purpose**: General media validation before upload or processing
+
+**Key Features**:
+- Validation function accepts file
+- Tracks validation status
+- Returns MediaValidation 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
+
+### UseMultimediaFlashcardResult
+
+**Purpose**: General flashcard CRUD operations
+
+**Key Features**:
+- Create flashcard with multimedia
+- Update flashcard media
+- Delete specific media attachment
+- Tracks processing state
+- Returns MultimediaFlashcard
+
+**Usage Pattern**:
+1. Create: Call `createMultimediaCard()` with card data
+2. Update: Call `updateMedia()` with cardId and media array
+3. Delete: Call `deleteMedia()` with attachmentId
+4. Check `isProcessing` before operations
+5. Handle `error` state for failures
+
+### General vs Card Multimedia Types
+
+| Operation | General Types | Card Types | Key Difference |
+|-----------|--------------|------------|----------------|
+| Upload | MediaAttachment | CardMediaAttachment | Different entity structures |
+| Generation | MediaGenerationRequest | CardMediaGenerationRequest | Cards include image search |
+| Validation | MediaValidation | CardMediaValidation | Different validation rules |
+| Flashcard | MultimediaFlashcard | CardMultimediaFlashcard | Different entity types |
+| Features | Core operations | Core + image search | Card has extended features |
+
+### When to Use Which Types
+
+**Use Media* Types (General)**:
+- Generic media handling
+- Non-card-specific operations
+- Reusable media components
+- General-purpose flashcards
+
+**Use Card* Types (Card-Specific)**:
+- Card-specific operations
+- Image search functionality
+- Card entity management
+- Card-specific validation rules
+
+### 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
+
+### Composable Hooks Pattern
+
+Combine multiple hook types for complex workflows:
+
+1. **Validate Then Upload**: Use validation result before calling upload
+2. **Generate Then Upload**: Chain generation and upload operations
+3. **Upload Then Create Card**: Use upload result to create flashcard
+4. **Parallel Operations**: Use multiple hooks independently
+
+### Related Domain Types
+
+These interfaces use domain types:
+- MediaAttachment
+- MediaGenerationRequest
+- MediaGenerationResult
+- MediaCompressionOptions
+- MediaValidation
+- MediaUploadProgress
+- MultimediaFlashcard
+
+## Dependencies
+
+- Domain layer types (Media* entities)
+- Presentation layer hooks
+- No external dependencies

package/src/media/presentation/hooks/multimedia.types.ts

@@ -0,0 +1,51 @@
+/**
+ * Multimedia Flashcard Hook Types
+ * Type definitions for multimedia hooks
+ */
+
+import type {
+  MediaAttachment,
+  MediaGenerationRequest,
+  MediaGenerationResult,
+  MediaCompressionOptions,
+  MediaValidation,
+  MediaUploadProgress,
+  MultimediaFlashcard,
+} from "../../domain/entities/MultimediaFlashcardTypes";
+
+export interface UseMediaUploadResult {
+  uploadMedia: (
+    file: any,
+    options?: MediaCompressionOptions,
+  ) => Promise<MediaAttachment>;
+  isUploading: boolean;
+  uploadProgress: MediaUploadProgress | null;
+  error: string | null;
+}
+
+export interface UseMediaGenerationResult {
+  generateMedia: (
+    request: MediaGenerationRequest,
+  ) => Promise<MediaGenerationResult>;
+  isGenerating: boolean;
+  generationResult: MediaGenerationResult | null;
+  error: string | null;
+}
+
+export interface UseMediaValidationResult {
+  validateMedia: (file: any) => Promise<MediaValidation>;
+  isValidating: boolean;
+  validation: MediaValidation | null;
+  error: string | null;
+}
+
+export interface UseMultimediaFlashcardResult {
+  createMultimediaCard: (cardData: any) => Promise<MultimediaFlashcard>;
+  updateMedia: (
+    cardId: string,
+    media: MediaAttachment[],
+  ) => Promise<MultimediaFlashcard>;
+  deleteMedia: (attachmentId: string) => Promise<void>;
+  isProcessing: boolean;
+  error: string | null;
+}

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

@@ -0,0 +1,164 @@
+# 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)