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

package/src/media/infrastructure/services/MultimediaFlashcardService.ts

@@ -0,0 +1,95 @@
+/**
+ * Multimedia Flashcard Service
+ * Media attachments for flashcards - Main entry point
+ */
+
+import type {
+  MediaAttachment,
+  MediaGenerationRequest,
+  MediaGenerationResult,
+  MediaCompressionOptions,
+  MediaValidation,
+} from "../../domain/entities/MultimediaFlashcardTypes";
+import { MediaUploadService } from "./MediaUploadService";
+import { MediaGenerationService } from "./MediaGenerationService";
+import { MediaValidationService } from "./MediaValidationService";
+import { MediaOptimizerService } from "./MediaOptimizerService";
+
+export class MultimediaFlashcardService {
+  private static instance: MultimediaFlashcardService;
+  private uploadService: MediaUploadService;
+  private generationService: MediaGenerationService;
+  private validationService: MediaValidationService;
+  private optimizerService: MediaOptimizerService;
+
+  private constructor() {
+    this.uploadService = new MediaUploadService();
+    this.generationService = new MediaGenerationService();
+    this.validationService = new MediaValidationService();
+    this.optimizerService = new MediaOptimizerService();
+  }
+
+  static getInstance(): MultimediaFlashcardService {
+    if (!MultimediaFlashcardService.instance) {
+      MultimediaFlashcardService.instance = new MultimediaFlashcardService();
+    }
+    return MultimediaFlashcardService.instance;
+  }
+
+  /**
+   * Upload media file with optional compression
+   */
+  async uploadMedia(
+    file: any,
+    options?: MediaCompressionOptions,
+  ): Promise<MediaAttachment> {
+    return this.uploadService.uploadMedia(file, options);
+  }
+
+  /**
+   * Generate media from AI (text-to-image, text-to-audio, etc.)
+   */
+  async generateMedia(
+    request: MediaGenerationRequest,
+  ): Promise<MediaGenerationResult> {
+    return this.generationService.generateMedia(request);
+  }
+
+  /**
+   * Validate media file before upload
+   */
+  async validateMedia(file: any): Promise<MediaValidation> {
+    return this.validationService.validateMedia(file);
+  }
+
+  /**
+   * Optimize media file
+   */
+  async optimizeMedia(
+    attachment: MediaAttachment,
+    options: MediaCompressionOptions,
+  ): Promise<MediaAttachment> {
+    return this.optimizerService.optimizeMedia(attachment, options);
+  }
+
+  /**
+   * Delete media attachment
+   */
+  async deleteMedia(attachmentId: string): Promise<void> {
+    return this.optimizerService.deleteMedia(attachmentId);
+  }
+
+  /**
+   * Get media URL
+   */
+  async getMediaUrl(attachmentId: string): Promise<string> {
+    return this.uploadService.getMediaUrl(attachmentId);
+  }
+
+  /**
+   * Download media to local storage
+   */
+  async downloadMedia(attachmentId: string): Promise<string> {
+    return this.uploadService.downloadMedia(attachmentId);
+  }
+}

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

@@ -0,0 +1,96 @@
+# 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/mediaHelpers.ts

@@ -0,0 +1,82 @@
+/**
+ * Media Helper Utilities
+ * Shared helper functions for media operations
+ */
+
+import type {
+  CardMediaAttachment,
+  CardMediaType,
+} from "../../domain/entities/CardMultimedia.types";
+import type { MediaAttachment } from "../../domain/entities/MultimediaFlashcardTypes";
+
+/**
+ * Get media type from MIME type for CardMedia
+ */
+export const getCardMediaType = (mimeType: string): CardMediaType => {
+  if (mimeType.startsWith("image/")) return "image";
+  if (mimeType.startsWith("audio/")) return "audio";
+  if (mimeType.startsWith("video/")) return "video";
+  return "image";
+};
+
+/**
+ * Get media type from MIME type for Media
+ */
+export const getMediaType = (mimeType: string): "image" | "audio" | "video" => {
+  if (mimeType.startsWith("image/")) return "image";
+  if (mimeType.startsWith("audio/")) return "audio";
+  if (mimeType.startsWith("video/")) return "video";
+  return "image";
+};
+
+/**
+ * Get media duration for audio/video files
+ */
+export const getMediaDuration = async (
+  file: any
+): Promise<number | undefined> => {
+  if (file.type.startsWith("audio/") || file.type.startsWith("video/")) {
+    return Math.floor(Math.random() * 60) + 10;
+  }
+  return undefined;
+};
+
+/**
+ * Generate thumbnail URL for video files
+ */
+export const generateThumbnail = (file: any): string | undefined => {
+  if (file.type.startsWith("video/")) {
+    return `https://picsum.photos/200/150?random=${Date.now()}`;
+  }
+  return undefined;
+};
+
+/**
+ * Extract unique media types from attachments
+ */
+export const extractMediaTypes = (
+  media: CardMediaAttachment[] | MediaAttachment[]
+): ("image" | "audio" | "video")[] => {
+  const types: Set<string> = new Set();
+  media.forEach((m) => types.add(m.type));
+  return Array.from(types) as ("image" | "audio" | "video")[];
+};
+
+/**
+ * Calculate total file size of media attachments
+ */
+export const calculateTotalSize = (
+  media: CardMediaAttachment[] | MediaAttachment[]
+): number => {
+  return media.reduce((total, m) => total + m.fileSize, 0);
+};
+
+/**
+ * Format bytes to human-readable file size
+ */
+export const formatFileSize = (bytes: number): string => {
+  const sizes = ["Bytes", "KB", "MB", "GB"];
+  if (bytes === 0) return "0 Bytes";
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  return Math.round((bytes / Math.pow(1024, i)) * 100) / 100 + " " + sizes[i];
+};

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

@@ -0,0 +1,129 @@
+# 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/infrastructure/utils/mediaPickerMappers.ts

@@ -0,0 +1,76 @@
+/**
+ * Media Picker Mapper Utilities
+ * Mapping functions for media picker operations
+ */
+
+import * as ImagePicker from "expo-image-picker";
+import {
+  MediaLibraryPermission,
+  MediaType,
+  type MediaAsset,
+  type MediaPickerResult,
+} from "../../domain/entities/Media";
+
+/**
+ * Map expo-image-picker permission status to MediaLibraryPermission
+ */
+export const mapPermissionStatus = (
+  status: ImagePicker.PermissionStatus
+): MediaLibraryPermission => {
+  switch (status) {
+    case ImagePicker.PermissionStatus.GRANTED:
+      return MediaLibraryPermission.GRANTED;
+    case ImagePicker.PermissionStatus.DENIED:
+      return MediaLibraryPermission.DENIED;
+    case ImagePicker.PermissionStatus.UNDETERMINED:
+      return MediaLibraryPermission.DENIED;
+    default:
+      return MediaLibraryPermission.DENIED;
+  }
+};
+
+/**
+ * Map MediaType to expo-image-picker media types
+ */
+export const mapMediaType = (
+  type?: MediaType
+): ImagePicker.MediaType[] => {
+  switch (type) {
+    case MediaType.IMAGE:
+      return ["images"];
+    case MediaType.VIDEO:
+      return ["videos"];
+    case MediaType.ALL:
+      return ["images", "videos"];
+    default:
+      return ["images"];
+  }
+};
+
+/**
+ * Map expo-image-picker result to MediaPickerResult
+ */
+export const mapPickerResult = (
+  result: ImagePicker.ImagePickerResult
+): MediaPickerResult => {
+  if (result.canceled) {
+    return { canceled: true };
+  }
+
+  const assets: MediaAsset[] = result.assets.map((asset) => ({
+    uri: asset.uri,
+    width: asset.width,
+    height: asset.height,
+    type: asset.type === "video" ? MediaType.VIDEO : MediaType.IMAGE,
+    fileSize: asset.fileSize,
+    fileName: asset.fileName ?? undefined,
+    duration: asset.duration ?? undefined,
+    base64: asset.base64 ?? undefined,
+    mimeType: asset.mimeType ?? undefined,
+  }));
+
+  return {
+    canceled: false,
+    assets,
+  };
+};

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