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

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

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

package/src/media/domain/utils/MediaUtils.README.md

@@ -0,0 +1,178 @@
+# MediaUtils
+
+## Purpose
+Utility class containing helper functions for media operations, validation, and calculations. Provides static methods for file type detection, dimension calculations, format conversions, and media validation.
+
+## File Location
+`src/domain/utils/MediaUtils.ts`
+
+## Strategy
+- Provide framework-agnostic utility functions for media operations
+- Enable consistent media type detection and validation
+- Support dimension calculations and scaling operations
+- Facilitate format conversions and MIME type mappings
+- Maintain aspect ratio preservation during transformations
+- Validate media constraints (dimensions, file types, sizes)
+- Provide helper functions for common media operations
+
+## Forbidden
+- **DO NOT** import external libraries (expo-image-picker, react-native) in utility functions
+- **DO NOT** include business logic or application-specific rules
+- **DO NOT** create instance methods - all methods must be static
+- **DO NOT** store state or maintain mutable properties
+- **DO NOT** make network calls or async operations in utility methods
+- **DO NOT** hardcode platform-specific behavior
+- **DO NOT** include UI-related logic or formatting for display
+- **DO NOT** modify input parameters - always return new objects/values
+- **DO NOT** throw exceptions for validation failures - return boolean results
+- **DO NOT** assume specific file systems or storage mechanisms
+
+## Rules
+1. All methods must be static and stateless
+2. All methods must be synchronous and pure functions
+3. Input validation must not throw exceptions
+4. Dimension calculations must preserve aspect ratios
+5. MIME type mappings must use standard MIME types
+6. Maximum dimension limit is 8192x8192 pixels
+7. Minimum dimension limit is 1x1 pixels
+8. File type detection must use extension checking
+9. Scale calculations must return integer values
+10. Aspect ratio must be calculated as width/height
+11. Unknown MIME types must map to MediaType.ALL
+12. Format validation must use supported format lists
+13. All methods must handle edge cases (zero, negative values)
+14. Return types must be consistent (boolean for validation, numbers for calculations)
+
+## AI Agent Guidelines
+
+When working with MediaUtils:
+
+1. **Static Usage**: Always call methods on the class, never create instances
+2. **Type Detection**: Use isImage() and isVideo() before processing files
+3. **Validation**: Always validate dimensions before scaling operations
+4. **Aspect Ratios**: Preserve aspect ratios when calculating scaled dimensions
+5. **MIME Types**: Use getImageMimeType() for format-to-MIME conversion
+6. **Media Type Parsing**: Use parseMediaType() to convert MIME to MediaType enum
+7. **Error Handling**: Check boolean return values for validation failures
+8. **Edge Cases**: Handle zero and negative dimensions appropriately
+9. **Performance**: Utility methods are lightweight and can be called frequently
+
+### Key Methods Reference
+
+- **isImage(uri: string)**: boolean - Check if file is an image by extension
+- **isVideo(uri: string)**: boolean - Check if file is a video by extension
+- **getImageMimeType(format: ImageFormat)**: string - Get MIME type for image format
+- **calculateAspectRatio(width, height)**: number - Calculate width/height ratio
+- **getScaledDimensions(width, height, maxWidth, maxHeight)**: object - Calculate scaled dimensions preserving aspect ratio
+- **isValidDimensions(width, height)**: boolean - Validate dimensions are within allowed range
+- **parseMediaType(mimeType: string)**: MediaType - Convert MIME type to MediaType enum
+
+### Method Usage Guidelines
+
+**File Type Detection:**
+1. Use isImage() to validate image files before processing
+2. Use isVideo() to validate video files before processing
+3. Both methods check file extensions (jpg, png, mp4, mov, etc.)
+4. Returns false for unknown or unsupported formats
+
+**Dimension Calculations:**
+1. Always validate dimensions with isValidDimensions() before processing
+2. Use calculateAspectRatio() to understand image proportions
+3. Use getScaledDimensions() to resize while preserving aspect ratio
+4. Scaled dimensions will never exceed maxWidth or maxHeight
+5. Aspect ratio is maintained even when only one dimension exceeds limits
+
+**Format Conversions:**
+1. Use getImageMimeType() to get standard MIME type from format enum
+2. Use parseMediaType() to convert MIME strings to MediaType enum
+3. Unknown MIME types return MediaType.ALL
+4. MIME type mappings are constant and cannot be modified
+
+### Validation Rules
+
+1. **isValidDimensions**:
+   - Width and height must be positive integers
+   - Maximum allowed dimension is 8192 pixels
+   - Minimum allowed dimension is 1 pixel
+   - Returns false for zero or negative values
+   - Returns false for values exceeding 8192
+
+2. **Aspect Ratio Calculations**:
+   - Must preserve original ratio in scaled dimensions
+   - Calculated as width divided by height
+   - Square images (1:1) return ratio of 1.0
+   - Widescreen (16:9) returns ratio of approximately 1.78
+   - Portrait (9:16) returns ratio of approximately 0.56
+
+3. **Scaling Operations**:
+   - Input dimensions can be any positive integers
+   - Output dimensions never exceed maxWidth or maxHeight
+   - Aspect ratio is always preserved
+   - Returns integer dimensions (not floating point)
+   - If both dimensions are within limits, returns original dimensions
+   - If only one dimension exceeds limit, scales proportionally
+
+### MIME Type Handling
+
+**Supported Image MIME Types:**
+- PNG: "image/png"
+- JPEG: "image/jpeg"
+- WEBP: "image/webp"
+
+**MediaType Mapping:**
+- "image/*" formats return MediaType.IMAGE
+- "video/*" formats return MediaType.VIDEO
+- Unknown formats return MediaType.ALL
+- Mapping is based on MIME type prefix
+
+### Constants Reference
+
+- **IMAGE_MIME_TYPES**: Readonly object mapping image formats to MIME types
+- Keys: "png", "jpeg", "webp"
+- Values: Standard MIME type strings
+- Used by getImageMimeType() method
+
+### Common Use Cases
+
+**Image Validation Pipeline:**
+1. Check file type with isImage()
+2. Validate dimensions with isValidDimensions()
+3. Calculate aspect ratio with calculateAspectRatio()
+4. Get MIME type with getImageMimeType()
+5. Scale if needed with getScaledDimensions()
+
+**Video Validation Pipeline:**
+1. Check file type with isVideo()
+2. Validate dimensions with isValidDimensions()
+3. Parse media type with parseMediaType()
+4. Scale if needed with getScaledDimensions()
+
+**Format Conversion:**
+1. Convert format enum to MIME type using getImageMimeType()
+2. Convert MIME type to MediaType using parseMediaType()
+3. Use MediaType for filtering and type checking
+
+### Edge Case Handling
+
+1. **Zero dimensions**: isValidDimensions() returns false
+2. **Negative dimensions**: isValidDimensions() returns false
+3. **Oversized dimensions**: isValidDimensions() returns false if > 8192
+4. **Unknown file extensions**: isImage() and isVideo() return false
+5. **Unknown MIME types**: parseMediaType() returns MediaType.ALL
+6. **Equal aspect ratios**: getScaledDimensions() returns original if within limits
+
+### Performance Considerations
+
+1. All methods are synchronous and execute in O(1) time
+2. No network calls or I/O operations
+3. No side effects or state mutations
+4. Safe to call frequently in loops or render cycles
+5. No memory allocation beyond return values
+
+## Dependencies
+
+- No external dependencies
+- References ImageFormat enum from domain types
+- References MediaType enum from domain types
+- Pure utility functions with no side effects
+- Can be used by any layer without additional dependencies

package/src/media/domain/utils/MediaUtils.ts

@@ -0,0 +1,82 @@
+/**
+ * Media Utilities
+ * Utility functions for media operations
+ */
+
+import { ImageFormat, MEDIA_CONSTANTS, MediaType } from "../entities/Media";
+
+/**
+ * Image MIME type mappings
+ */
+export const IMAGE_MIME_TYPES = {
+  [ImageFormat.PNG]: "image/png",
+  [ImageFormat.JPEG]: "image/jpeg",
+  [ImageFormat.WEBP]: "image/webp",
+} as const;
+
+/**
+ * Media utility class
+ */
+export class MediaUtils {
+  static isImage(uri: string): boolean {
+    const extension = uri.split(".").pop()?.toLowerCase();
+    return MEDIA_CONSTANTS.SUPPORTED_IMAGE_FORMATS.some(
+      (format) => format.replace(".", "") === extension
+    );
+  }
+
+  static isVideo(uri: string): boolean {
+    const extension = uri.split(".").pop()?.toLowerCase();
+    return MEDIA_CONSTANTS.SUPPORTED_VIDEO_FORMATS.some(
+      (format) => format.replace(".", "") === extension
+    );
+  }
+
+  static getImageMimeType(format: ImageFormat): string {
+    return IMAGE_MIME_TYPES[format];
+  }
+
+  static calculateAspectRatio(width: number, height: number): number {
+    return width / height;
+  }
+
+  static getScaledDimensions(
+    originalWidth: number,
+    originalHeight: number,
+    maxWidth: number,
+    maxHeight: number
+  ): { width: number; height: number } {
+    const aspectRatio = MediaUtils.calculateAspectRatio(
+      originalWidth,
+      originalHeight
+    );
+
+    let width = originalWidth;
+    let height = originalHeight;
+
+    if (width > maxWidth) {
+      width = maxWidth;
+      height = width / aspectRatio;
+    }
+
+    if (height > maxHeight) {
+      height = maxHeight;
+      width = height * aspectRatio;
+    }
+
+    return {
+      width: Math.round(width),
+      height: Math.round(height),
+    };
+  }
+
+  static isValidDimensions(width: number, height: number): boolean {
+    return width > 0 && height > 0 && width <= 8192 && height <= 8192;
+  }
+
+  static parseMediaType(mimeType: string): MediaType {
+    if (mimeType.startsWith("image/")) return MediaType.IMAGE;
+    if (mimeType.startsWith("video/")) return MediaType.VIDEO;
+    return MediaType.ALL;
+  }
+}

package/src/media/index.ts

@@ -0,0 +1,70 @@
+/**
+ * @umituz/react-native-media - Enhanced Public API
+ *
+ * Media picking capabilities for React Native apps
+ * Includes multimedia flashcard support
+ *
+ * Usage:
+ *   import {
+ *     useMedia,
+ *     useMultimediaFlashcard,
+ *     MultimediaFlashcardService,
+ *     type MediaAttachment,
+ *     type MultimediaFlashcard,
+ *   } from '@umituz/react-native-media';
+ */
+
+// Domain Layer - Original Media Entities
+export {
+  MediaType,
+  ImageFormat as MediaImageFormat,
+  MediaQuality,
+  MediaLibraryPermission,
+  MEDIA_CONSTANTS,
+} from "./domain/entities/Media";
+
+export { IMAGE_MIME_TYPES as MEDIA_IMAGE_MIME_TYPES, MediaUtils } from "./domain/utils/MediaUtils";
+
+export type {
+  MediaAsset,
+  MediaPickerResult,
+  MediaPickerOptions,
+  CameraOptions,
+  ImageDimensions as MediaImageDimensions,
+  ImageManipulationActions,
+  ImageSaveOptions as MediaImageSaveOptions,
+} from "./domain/entities/Media";
+
+// Infrastructure Layer - Original Media Services
+export { MediaPickerService } from "./infrastructure/services/MediaPickerService";
+export { MediaSaveService } from "./infrastructure/services/MediaSaveService";
+export type { SaveResult, SaveOptions } from "./infrastructure/services/MediaSaveService";
+
+// Presentation Layer - Original Media Hooks
+export { useMedia } from "./presentation/hooks/useMedia";
+
+// Multimedia Flashcard Support
+export type {
+  CardMediaType,
+  CardMediaPosition,
+  CardMediaAttachment,
+  CardMultimediaFlashcard,
+  CardMediaGenerationRequest,
+  CardMediaGenerationResult,
+  CardMediaUploadProgress,
+  CardMediaCompressionOptions,
+  CardMediaValidation,
+} from "./domain/entities/CardMultimedia.types";
+
+export { CardMultimediaFlashcardService } from "./infrastructure/services/CardMultimediaService";
+
+export {
+  useCardMediaUpload,
+  useCardMediaGeneration,
+  useCardMediaValidation,
+  useCardMultimediaFlashcard,
+  type UseCardMediaUploadResult,
+  type UseCardMediaGenerationResult,
+  type UseCardMediaValidationResult,
+  type UseCardMultimediaFlashcardResult,
+} from "./presentation/hooks/useCardMultimediaFlashcard";

package/src/media/index.ts.README.md

@@ -0,0 +1,191 @@
+# @umituz/react-native-media - Main Export
+
+## Purpose
+Main entry point for the library. Exports all services, hooks, types, and utilities for media management in React Native applications.
+
+## File Location
+`src/index.ts`
+
+## Strategy
+- Provide a single import point for all library functionality
+- Organize exports by category (services, hooks, types, utils)
+- Enable tree-shaking by using named exports
+- Maintain clear separation between general media and card-specific features
+- Support both individual imports and bulk imports
+
+## Forbidden
+- **DO NOT** add default exports - only named exports
+- **DO NOT** re-export external dependencies directly
+- **DO NOT** create circular import dependencies
+- **DO NOT** mix categories in export groups
+- **DO NOT** export internal implementation details
+- **DO NOT** use wildcard exports from sub-modules
+- **DO NOT** change export names once published
+
+## Rules
+1. All public exports must be re-exported from this file
+2. Exports must be organized by category (services, hooks, types, utils)
+3. Each category must be clearly commented
+4. General media features must be separate from card-specific features
+5. Type exports must use `export type` for tree-shaking
+6. Service exports must be singleton instances or static classes
+7. Hook exports must be named with `use` prefix
+8. All exports must have TypeScript types
+9. Breaking changes require major version bump
+10. All exports must be documented in their respective README files
+
+## AI Agent Guidelines
+
+### Import Strategy
+
+When working with this library:
+
+1. **Single Entry Point**: All imports should come from `@umituz/react-native-media`
+2. **Specific Imports**: Import only what you need for better tree-shaking
+3. **Type Imports**: Use `import type` for type-only imports
+4. **Category Awareness**: Understand the difference between general and card-specific features
+
+### Export Categories
+
+#### Services (Infrastructure Layer)
+All services follow singleton pattern:
+- `MediaPickerService` - Image/video selection from camera and gallery
+- `MediaSaveService` - Saving media to device gallery
+- `MediaUploadService` - Upload/download media and URL management
+- `MediaGenerationService` - AI-powered text-to-image and text-to-audio
+- `MediaValidationService` - File validation before upload
+- `MediaOptimizerService` - Compression and optimization
+- `CardMultimediaService` - Card-specific media operations
+- `CardMediaGenerationService` - Card AI generation with image search
+- `CardMediaUploadService` - Card upload with position support
+- `CardMediaValidationService` - Card validation with stricter rules
+- `CardMediaOptimizerService` - Card optimization
+- `MultimediaFlashcardService` - Main flashcard service
+- `CardMultimediaFlashcardService` - Main card flashcard service
+
+#### Hooks (Presentation Layer)
+All hooks are named with `use` prefix:
+
+**General Media Hooks:**
+- `useMedia` - Core media selection and camera
+- `useMediaUpload` - Upload with progress tracking
+- `useMediaGeneration` - AI generation
+- `useMediaValidation` - Pre-upload validation
+- `useMultimediaFlashcard` - Flashcard creation
+
+**Card-Specific Hooks:**
+- `useCardMultimediaFlashcard` - Card flashcard management
+- `useCardMediaGeneration` - Card AI generation
+- `useCardMediaUpload` - Card upload with position
+- `useCardMediaValidation` - Card validation
+
+#### Types (Domain Layer)
+Organized by functionality:
+
+**Basic Types:**
+- `MediaType` - Media type enum (IMAGE, VIDEO, ALL)
+- `ImageFormat` - Format enum (JPEG, PNG, WEBP)
+- `MediaQuality` - Quality enum (LOW, MEDIUM, HIGH)
+- `MediaLibraryPermission` - Permission states
+- `MediaAsset` - Media file properties
+- `MediaPickerResult` - Picker return type
+- `MediaPickerOptions` - Picker configuration
+- `CameraOptions` - Camera configuration
+
+**Card Types:**
+- `CardMediaType` - Card media types
+- `CardMediaPosition` - Position (FRONT, BACK, BOTH)
+- `CardMediaAttachment` - Card media with position
+- `CardMultimediaFlashcard` - Card entity
+- `CardMediaGenerationRequest` - Generation request
+- `CardMediaGenerationResult` - Generation result
+- `CardMediaUploadProgress` - Upload progress
+- `CardMediaCompressionOptions` - Compression options
+- `CardMediaValidation` - Validation result
+
+**Flashcard Types:**
+- `MediaAttachment` - General media attachment
+- `MultimediaFlashcard` - Flashcard entity
+- `MediaGenerationRequest` - Generation request
+- `MediaGenerationResult` - Generation result
+
+#### Utils (Domain & Infrastructure)
+Utility functions and helpers:
+
+**Domain Utils:**
+- `MediaUtils` - Core media utilities
+
+**Infrastructure Utils:**
+- Helper functions for media operations
+- Mapper functions for type conversions
+
+### Module Selection Guidelines
+
+#### Use General Media Features When:
+- Working with standard media operations
+- No card/flashcard requirements
+- Need basic upload/download/validation
+- Building general-purpose media features
+
+#### Use Card-Specific Features When:
+- Building flashcard applications
+- Need position-based media (front/back)
+- Working with card entities
+- Need card-specific validation rules
+- Using card generation or upload services
+
+### Dependency Rules
+
+1. **Services** can be used independently or through hooks
+2. **Hooks** wrap services and provide React state management
+3. **Types** are used by both services and hooks
+4. **Utils** provide helper functions used across layers
+
+### Common Import Patterns
+
+**Service-only usage:**
+- Import service classes directly
+- Use for non-React code or direct service access
+- Services follow singleton pattern
+
+**Hook usage (recommended for React components):**
+- Import hooks for React components
+- Hooks provide state management
+- Hooks wrap services with React integration
+
+**Type imports:**
+- Use `import type` for type-only imports
+- Enables tree-shaking
+- Better IDE support
+
+**Combined imports:**
+- Mix services, hooks, and types as needed
+- All imports from single entry point
+- Named exports only
+
+## File Structure Reference
+
+The library follows Clean Architecture with three main layers:
+
+**Domain Layer** (`src/domain/`)
+- `entities/` - Core type definitions and interfaces
+- `utils/` - Domain utility functions
+
+**Infrastructure Layer** (`src/infrastructure/`)
+- `services/` - Service implementations with external integrations
+- `utils/` - Helper functions and mappers
+
+**Presentation Layer** (`src/presentation/`)
+- `hooks/` - React hooks for UI integration
+
+**Main Export** (`src/index.ts`)
+- Single entry point for all exports
+- Organized by category
+- This file
+
+## Dependencies
+
+- Exports all domain entities and types
+- Exports all infrastructure services
+- Exports all presentation hooks
+- Re-exports utilities from domain and infrastructure layers