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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-design-system",
-  "version": "2.8.8",
+  "version": "2.8.9",
   "description": "Universal design system for React Native apps - Consolidated package with atoms, molecules, organisms, theme, typography, responsive, safe area, exception, infinite scroll, UUID, image, timezone, offline, and onboarding utilities",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -25,6 +25,7 @@
     "./onboarding": "./src/onboarding/index.ts",
     "./storage": "./src/storage/index.ts",
     "./filesystem": "./src/filesystem/index.ts",
+    "./media": "./src/media/index.ts",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -75,6 +76,8 @@
     "expo-font": ">=12.0.0",
     "expo-image": ">=3.0.0",
     "expo-image-manipulator": ">=12.0.0",
+    "expo-image-picker": ">=14.0.0",
+    "expo-media-library": ">=15.0.0",
     "expo-network": ">=8.0.0",
     "expo-secure-store": ">=14.0.0",
     "expo-sharing": ">=12.0.0",
@@ -129,6 +132,8 @@
     "expo-video": "~3.0.0",
     "expo-haptics": "~14.0.0",
     "expo-image-manipulator": "~13.0.0",
+    "expo-image-picker": "~16.0.0",
+    "expo-media-library": "~17.0.0",
     "expo-image": "~3.0.11",
     "expo-localization": "~16.0.1",
     "expo-secure-store": "~14.0.0",

package/src/exports/media.ts

@@ -0,0 +1 @@
+export * from "../media";

package/src/index.ts

@@ -115,3 +115,8 @@ export * from './exports/onboarding';
 // FILESYSTEM EXPORTS
 // =============================================================================
 export * from './exports/filesystem';
+
+// =============================================================================
+// MEDIA EXPORTS
+// =============================================================================
+export * from './exports/media';

package/src/media/domain/entities/CardMultimedia.types.README.md

@@ -0,0 +1,129 @@
+# CardMultimedia Types
+
+## Purpose
+Type definitions for flashcard-specific media operations. These types define the contract for media attachment, generation, and management within the card-based learning system.
+
+## File Location
+`src/domain/entities/CardMultimedia.types.ts`
+
+## Strategy
+- Define the contract for card-specific media operations
+- Provide type-safe interfaces for flashcard media attachments
+- Support AI-powered media generation for educational content
+- Enable comprehensive media validation and optimization
+- Maintain clear separation between card media and general media types
+- Support upload progress tracking and compression
+- Facilitate media download management for offline learning
+
+## Forbidden
+- **DO NOT** use these types for general-purpose media operations (use Multimedia types instead)
+- **DO NOT** include UI components or presentation logic in type definitions
+- **DO NOT** add business logic or implementation details to interfaces
+- **DO NOT** create circular dependencies with other domain types
+- **DO NOT** use `any` type or loose type definitions
+- **DO NOT** modify existing type properties - extend interfaces for new features
+- **DO NOT** assume specific storage backend or cloud provider
+- **DO NOT** hardcode validation limits in type definitions
+- **DO NOT** mix card media types with general multimedia types
+
+## Rules
+1. All card media types must be exported from this file
+2. Type definitions must be framework-agnostic
+3. Card media IDs must use "card_media_" prefix for uniqueness
+4. Position types must explicitly define front/back/both placement
+5. File size fields must use bytes as unit
+6. Duration fields must use seconds as unit
+7. Date fields must use ISO 8601 format
+8. All generation requests must include input validation
+9. Compression quality must be between 0.1 and 1.0
+10. Upload progress must be tracked from 0-100
+11. Validation results must separate errors, warnings, and recommendations
+12. Service interfaces must return Promises for all async operations
+13. Media type arrays must be automatically calculated, not manually set
+14. Download status must be tracked per attachment
+15. Estimated size must represent total of all attachments
+
+## AI Agent Guidelines
+
+When working with CardMultimedia types:
+
+1. **Type Selection**: Use CardMediaAttachment for flashcard-specific media operations
+2. **Generation Requests**: Always specify input parameters and options explicitly
+3. **Validation**: Validate media files before upload and after generation
+4. **Progress Tracking**: Monitor upload progress for user feedback
+5. **Compression**: Apply compression options before upload to reduce bandwidth
+6. **Download Management**: Check isDownloaded status before displaying media
+7. **Position Logic**: Respect position field for front/back/both placement
+8. **Size Estimation**: Calculate total size for all media before batch operations
+9. **Error Handling**: Parse validation errors and warnings for user feedback
+10. **Cost Tracking**: Monitor creditsUsed for AI generation operations
+
+### Key Types Reference
+
+- **CardMediaType**: "image" | "audio" | "video" - Media type classification for cards
+- **CardMediaPosition**: "front" | "back" | "both" - Display placement on card faces
+- **CardMediaAttachment**: Core interface for individual media items with metadata
+- **CardMultimediaFlashcard**: Card entity with computed media properties
+- **CardMediaGenerationRequest**: Input specification for AI media generation
+- **CardMediaGenerationResult**: Output with cost tracking and performance metrics
+- **CardMediaUploadProgress**: Real-time upload status tracking
+- **CardMediaCompressionOptions**: Quality and size optimization settings
+- **CardMediaValidation**: Comprehensive validation with recommendations
+- **CardMultimediaFlashcardService**: Service interface for media operations
+
+### Type Usage Patterns
+
+1. **CardMediaAttachment**: Individual media item with position, URL, and metadata
+2. **CardMultimediaFlashcard**: Card with computed properties (hasMedia, mediaType, isDownloaded)
+3. **CardMediaGenerationRequest**: Three generation types (text_to_image, text_to_audio, image_search)
+4. **CardMediaValidation**: Separate errors (blocking) from warnings and recommendations
+
+### Validation Rules
+
+1. Validate file size against upload limits before processing
+2. Check MIME type matches CardMediaType
+3. Ensure dimensions are within supported ranges
+4. Verify URIs are properly formatted and accessible
+5. Validate duration for audio/video files
+6. Check compression quality is within 0.1-1.0 range
+7. Ensure generation prompts are non-empty strings
+8. Validate language codes for audio generation (e.g., "tr-TR", "en-US")
+
+### Service Interface Guidelines
+
+When implementing CardMultimediaFlashcardService:
+
+1. **uploadMedia**: Accept file with optional compression, return attachment with URL
+2. **generateMedia**: Process AI generation request, track credits and timing
+3. **validateMedia**: Return comprehensive validation with errors, warnings, recommendations
+4. **optimizeMedia**: Apply compression to existing attachment, preserve metadata
+5. **deleteMedia**: Remove attachment and update card associations
+6. **getMediaUrl**: Return accessible URL for downloaded or remote media
+7. **downloadMedia**: Fetch remote media to local storage, update isDownloaded status
+
+### Generation Type Specifics
+
+1. **text_to_image**: Requires prompt, style (realistic/cartoon/artistic), quality, format
+2. **text_to_audio**: Requires text, language, voice (male/female/neutral), format
+3. **image_search**: Requires prompt, maxResults (no quality/format options)
+
+### Position Logic
+
+1. **front**: Media displayed only on card front face
+2. **back**: Media displayed only on card back face
+3. **both**: Media displayed on both card faces (e.g., background image)
+
+### Download Management
+
+1. Check isDownloaded before displaying media offline
+2. Use localPath for offline access when available
+3. Fall back to URL when media not downloaded
+4. Track estimatedSize for storage management
+5. Implement downloadMedia for offline caching
+
+## Dependencies
+
+- No external dependencies
+- References domain types from Media.ts for base media concepts
+- Must be usable by infrastructure and presentation layers without additional dependencies
+- Service interfaces require async operation support

package/src/media/domain/entities/CardMultimedia.types.ts

@@ -0,0 +1,105 @@
+/**
+ * Card Multimedia Types
+ * Multimedia support for flashcard functionality
+ */
+
+export type CardMediaType = "image" | "audio" | "video";
+export type CardMediaPosition = "front" | "back" | "both";
+
+export interface CardMediaAttachment {
+  id: string;
+  type: CardMediaType;
+  position: CardMediaPosition;
+  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 CardMultimediaFlashcard {
+  id: string;
+  front: string;
+  back: string;
+  difficulty: "easy" | "medium" | "hard";
+  tags: string[];
+  createdAt?: string;
+  updatedAt?: string;
+  // Extended properties for multimedia support
+  media: CardMediaAttachment[];
+  hasMedia: boolean; // Computed property
+  mediaType: CardMediaType[]; // Array of media types present
+  isDownloaded: boolean; // All media downloaded?
+  estimatedSize: number; // Total size in bytes
+}
+
+export interface CardMediaGenerationRequest {
+  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 CardMediaGenerationResult {
+  success: boolean;
+  attachments: CardMediaAttachment[];
+  creditsUsed: number;
+  processingTime: number;
+  error?: string;
+  requestId: string;
+}
+
+export interface CardMediaUploadProgress {
+  fileId: string;
+  progress: number; // 0-100
+  status: "uploading" | "processing" | "completed" | "error";
+  error?: string;
+  url?: string;
+}
+
+export interface CardMediaCompressionOptions {
+  quality: number; // 0.1 - 1.0
+  maxWidth?: number;
+  maxHeight?: number;
+  maxFileSize?: number; // bytes
+  format?: "jpeg" | "png" | "webp";
+}
+
+export interface CardMediaValidation {
+  isValid: boolean;
+  errors: string[];
+  warnings: string[];
+  recommendations: string[];
+}
+
+export interface CardMultimediaFlashcardService {
+  uploadMedia(
+    file: any,
+    options?: CardMediaCompressionOptions,
+  ): Promise<CardMediaAttachment>;
+  generateMedia(
+    request: CardMediaGenerationRequest,
+  ): Promise<CardMediaGenerationResult>;
+  validateMedia(file: any): Promise<CardMediaValidation>;
+  optimizeMedia(
+    attachment: CardMediaAttachment,
+    options: CardMediaCompressionOptions,
+  ): Promise<CardMediaAttachment>;
+  deleteMedia(attachmentId: string): Promise<void>;
+  getMediaUrl(attachmentId: string): Promise<string>;
+  downloadMedia(attachmentId: string): Promise<string>; // Returns local path
+}

package/src/media/domain/entities/Media.README.md

@@ -0,0 +1,80 @@
+# Media Types and Interfaces
+
+## Purpose
+Core type definitions and interfaces for media handling throughout the application.
+
+## File Location
+`src/domain/entities/Media.ts`
+
+## Strategy
+- Define the contract for media operations across all layers
+- Provide type-safe interfaces for media assets, picker options, and operations
+- Serve as the single source of truth for media-related types
+- Enable compile-time validation of media operations
+- Maintain separation between domain logic and implementation
+
+## Forbidden
+- **DO NOT** import external libraries (expo, react-native) in domain types
+- **DO NOT** include implementation details in type definitions
+- **DO NOT** add business logic to type definitions
+- **DO NOT** create circular dependencies between types
+- **DO NOT** export types that are not used by other layers
+- **DO NOT** use `any` type or loose type definitions
+- **DO NOT** modify existing types - extend them instead
+
+## Rules
+1. All media types must be exported from this file
+2. Type definitions must be framework-agnostic
+3. Enums must have explicit string values
+4. Interfaces must extend appropriate base types
+5. Optional fields must be clearly marked with `?`
+6. File size fields must use bytes as unit
+7. Dimensions must be in pixels
+8. MIME type validation must use standard MIME types
+9. All new properties must be added with backward compatibility in mind
+10. Type exports must be re-exported from main index
+
+## AI Agent Guidelines
+
+When working with Media types:
+
+1. **Type Import**: Always import types from `@umituz/react-native-media` domain layer
+2. **Type Safety**: Use provided types instead of `any` or loose types
+3. **Validation**: Validate media assets against these types before processing
+4. **Extensibility**: Extend interfaces when adding new properties, don't modify core types
+5. **Consistency**: Maintain naming conventions (PascalCase for types, camelCase for properties)
+
+### Key Enums Reference
+
+- `MediaType`: IMAGE, VIDEO, ALL - Use for media type filtering
+- `ImageFormat`: PNG, JPEG, WEBP - Use for format specification
+- `MediaQuality`: LOW (0.3), MEDIUM (0.7), HIGH (1.0) - Use for compression quality
+- `MediaLibraryPermission`: GRANTED, DENIED, LIMITED - Use for permission states
+
+### Type Usage Guidelines
+
+1. **MediaAsset**: Primary type for all media files with uri, dimensions, type, size
+2. **MediaPickerResult**: Return type for all picker operations with canceled flag
+3. **MediaPickerOptions**: Configuration for library picker with mediaTypes, quality, limits
+4. **CameraOptions**: Configuration for camera operations with quality, duration, editing
+
+### Validation Rules
+
+1. Check file size against `MediaAsset.fileSize` (in bytes)
+2. Validate dimensions using `width` and `height` properties (in pixels)
+3. Verify MIME type matches expected `MediaType`
+4. Ensure URIs are properly formatted strings
+5. Validate aspect ratio format as [width, height] tuple
+
+### Constants Reference
+
+Use `MEDIA_CONSTANTS` for:
+- Maximum file sizes (MAX_IMAGE_SIZE, MAX_VIDEO_SIZE)
+- Default values (DEFAULT_QUALITY, DEFAULT_FORMAT, DEFAULT_ASPECT_RATIO)
+- Supported format lists (SUPPORTED_IMAGE_FORMATS, SUPPORTED_VIDEO_FORMATS)
+
+## Dependencies
+
+- No external dependencies
+- May reference other domain types within the domain layer
+- Must be usable by infrastructure and presentation layers without additional dependencies

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

@@ -0,0 +1,139 @@
+/**
+ * Media Domain - Core Entities
+ *
+ * Core types and interfaces for media operations.
+ * Handles images, videos, and media library interactions.
+ */
+
+
+/**
+ * Media type enumeration
+ */
+export enum MediaType {
+  IMAGE = "image",
+  VIDEO = "video",
+  ALL = "all",
+}
+
+/**
+ * Image format enumeration
+ */
+export enum ImageFormat {
+  PNG = "png",
+  JPEG = "jpeg",
+  WEBP = "webp",
+}
+
+/**
+ * Media quality enumeration
+ */
+export enum MediaQuality {
+  LOW = 0.3,
+  MEDIUM = 0.7,
+  HIGH = 1.0,
+}
+
+/**
+ * Media library permissions
+ */
+export enum MediaLibraryPermission {
+  GRANTED = "granted",
+  DENIED = "denied",
+  LIMITED = "limited",
+}
+
+/**
+ * Image dimensions interface
+ */
+export interface ImageDimensions {
+  width: number;
+  height: number;
+}
+
+/**
+ * Image manipulation actions
+ */
+export interface ImageManipulationActions {
+  resize?: ImageDimensions;
+  crop?: {
+    originX: number;
+    originY: number;
+    width: number;
+    height: number;
+  };
+  rotate?: number;
+  flip?: {
+    horizontal?: boolean;
+    vertical?: boolean;
+  };
+}
+
+/**
+ * Image save options
+ */
+export interface ImageSaveOptions {
+  quality?: MediaQuality;
+  format?: ImageFormat;
+  base64?: boolean;
+}
+
+/**
+ * Media picker options
+ */
+export interface MediaPickerOptions {
+  mediaTypes?: MediaType;
+  allowsEditing?: boolean;
+  allowsMultipleSelection?: boolean;
+  aspect?: [number, number];
+  quality?: MediaQuality;
+  selectionLimit?: number;
+  base64?: boolean;
+}
+
+/**
+ * Media asset interface
+ */
+export interface MediaAsset {
+  uri: string;
+  width: number;
+  height: number;
+  type: MediaType;
+  fileSize?: number;
+  fileName?: string;
+  duration?: number;
+  base64?: string;
+  mimeType?: string;
+}
+
+/**
+ * Media picker result
+ */
+export interface MediaPickerResult {
+  canceled: boolean;
+  assets?: MediaAsset[];
+}
+
+/**
+ * Camera options
+ */
+export interface CameraOptions {
+  quality?: MediaQuality;
+  allowsEditing?: boolean;
+  aspect?: [number, number];
+  base64?: boolean;
+  videoMaxDuration?: number;
+}
+
+/**
+ * Media constants
+ */
+export const MEDIA_CONSTANTS = {
+  MAX_IMAGE_SIZE: 10 * 1024 * 1024,
+  MAX_VIDEO_SIZE: 100 * 1024 * 1024,
+  DEFAULT_QUALITY: MediaQuality.HIGH,
+  DEFAULT_FORMAT: ImageFormat.JPEG,
+  DEFAULT_ASPECT_RATIO: [4, 3] as [number, number],
+  DEFAULT_SELECTION_LIMIT: 10,
+  SUPPORTED_IMAGE_FORMATS: [".jpg", ".jpeg", ".png", ".gif", ".webp"],
+  SUPPORTED_VIDEO_FORMATS: [".mp4", ".mov"],
+} as const;

package/src/media/domain/entities/MultimediaFlashcardTypes.README.md

@@ -0,0 +1,144 @@
+# MultimediaFlashcard Types
+
+## Purpose
+Type definitions for general-purpose media operations in flashcard applications. These types define the contract for media attachment, generation, and management across various multimedia use cases.
+
+## File Location
+`src/domain/entities/MultimediaFlashcardTypes.ts`
+
+## Strategy
+- Define the contract for general multimedia operations in flashcards
+- Provide type-safe interfaces for media attachments and generation
+- Support AI-powered media generation for educational content
+- Enable comprehensive media validation and optimization
+- Maintain clear separation between general media and card-specific media types
+- Support upload progress tracking and compression
+- Facilitate media download management for offline learning
+
+## Forbidden
+- **DO NOT** use these types for card-specific operations with special requirements (use CardMultimedia types instead)
+- **DO NOT** include UI components or presentation logic in type definitions
+- **DO NOT** add business logic or implementation details to interfaces
+- **DO NOT** create circular dependencies with other domain types
+- **DO NOT** use `any` type or loose type definitions
+- **DO NOT** modify existing type properties - extend interfaces for new features
+- **DO NOT** assume specific storage backend or cloud provider
+- **DO NOT** hardcode validation limits in type definitions
+- **DO NOT** mix general multimedia types with card-specific types
+- **DO NOT** use image_search generation type (only available in CardMultimedia)
+
+## Rules
+1. All multimedia types must be exported from this file
+2. Type definitions must be framework-agnostic
+3. Media IDs must use "media_" prefix for uniqueness
+4. Position types must explicitly define front/back/both placement
+5. File size fields must use bytes as unit
+6. Duration fields must use seconds as unit
+7. Date fields must use ISO 8601 format
+8. All generation requests must include input validation
+9. Compression quality must be between 0.1 and 1.0
+10. Upload progress must be tracked from 0-100
+11. Validation results must separate errors, warnings, and recommendations
+12. Service interfaces must return Promises for all async operations
+13. Media type arrays must be automatically calculated, not manually set
+14. Download status must be tracked per attachment
+15. Estimated size must represent total of all attachments
+
+## AI Agent Guidelines
+
+When working with MultimediaFlashcard types:
+
+1. **Type Selection**: Use MediaAttachment for general-purpose media operations
+2. **Generation Requests**: Always specify input parameters and options explicitly
+3. **Validation**: Validate media files before upload and after generation
+4. **Progress Tracking**: Monitor upload progress for user feedback
+5. **Compression**: Apply compression options before upload to reduce bandwidth
+6. **Download Management**: Check isDownloaded status before displaying media
+7. **Position Logic**: Respect position field for front/back/both placement
+8. **Size Estimation**: Calculate total size for all media before batch operations
+9. **Error Handling**: Parse validation errors and warnings for user feedback
+10. **Cost Tracking**: Monitor creditsUsed for AI generation operations
+
+### Key Types Reference
+
+- **MediaType**: "image" | "audio" | "video" - Media type classification
+- **MediaPosition**: "front" | "back" | "both" - Display placement on card faces
+- **MediaAttachment**: Core interface for individual media items with metadata
+- **MultimediaFlashcard**: Card entity with computed media properties
+- **MediaGenerationRequest**: Input specification for AI media generation
+- **MediaGenerationResult**: Output with cost tracking and performance metrics
+- **MediaUploadProgress**: Real-time upload status tracking
+- **MediaCompressionOptions**: Quality and size optimization settings
+- **MediaValidation**: Comprehensive validation with recommendations
+- **MultimediaFlashcardService**: Service interface for media operations
+
+### Type Usage Patterns
+
+1. **MediaAttachment**: Individual media item with position, URL, and metadata
+2. **MultimediaFlashcard**: Card with computed properties (hasMedia, mediaType, isDownloaded)
+3. **MediaGenerationRequest**: Two generation types (text_to_image, text_to_audio) - no image_search
+4. **MediaValidation**: Separate errors (blocking) from warnings and recommendations
+
+### Validation Rules
+
+1. Validate file size against upload limits before processing
+2. Check MIME type matches MediaType
+3. Ensure dimensions are within supported ranges
+4. Verify URIs are properly formatted and accessible
+5. Validate duration for audio/video files
+6. Check compression quality is within 0.1-1.0 range
+7. Ensure generation prompts are non-empty strings
+8. Validate language codes for audio generation (e.g., "en-US", "es-ES")
+
+### Service Interface Guidelines
+
+When implementing MultimediaFlashcardService:
+
+1. **uploadMedia**: Accept file with optional compression, return attachment with URL
+2. **generateMedia**: Process AI generation request, track credits and timing
+3. **validateMedia**: Return comprehensive validation with errors, warnings, recommendations
+4. **optimizeMedia**: Apply compression to existing attachment, preserve metadata
+5. **deleteMedia**: Remove attachment and update card associations
+6. **getMediaUrl**: Return accessible URL for downloaded or remote media
+7. **downloadMedia**: Fetch remote media to local storage, update isDownloaded status
+
+### Generation Type Specifics
+
+1. **text_to_image**: Requires prompt, style (realistic/cartoon/artistic), quality, format
+2. **text_to_audio**: Requires text, language, voice (male/female/neutral), format
+3. **image_search**: NOT supported in general multimedia types (use CardMultimedia instead)
+
+### Position Logic
+
+1. **front**: Media displayed only on card front face
+2. **back**: Media displayed only on card back face
+3. **both**: Media displayed on both card faces (e.g., background image)
+
+### Download Management
+
+1. Check isDownloaded before displaying media offline
+2. Use localPath for offline access when available
+3. Fall back to URL when media not downloaded
+4. Track estimatedSize for storage management
+5. Implement downloadMedia for offline caching
+
+### CardMultimedia vs Multimedia Selection
+
+Use **CardMultimedia types** when:
+- Working with flashcard-specific features
+- Need image_search generation capability
+- Using card-specific ID prefixes (card_media_)
+- Integrating with card-specific services
+
+Use **Multimedia types** when:
+- Building general-purpose media features
+- Only need text_to_image and text_to_audio generation
+- Using general media ID prefixes (media_)
+- Building reusable media components
+
+## Dependencies
+
+- No external dependencies
+- References domain types from Media.ts for base media concepts
+- Must be usable by infrastructure and presentation layers without additional dependencies
+- Service interfaces require async operation support