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

package/src/filesystem/infrastructure/services/file-manager.service.ts

@@ -0,0 +1,81 @@
+/**
+ * File Manager Service
+ * Single Responsibility: Manage file operations (delete, copy, move)
+ */
+
+import { File, Directory } from "expo-file-system";
+import type { FileOperationResult } from "../../domain/entities/File";
+
+/**
+ * Delete file or directory
+ */
+export async function deleteFile(uri: string): Promise<boolean> {
+  try {
+    // Try as file first
+    try {
+      const file = new File(uri);
+      if (file.exists) {
+        file.delete();
+        return true;
+      }
+    } catch {
+      // Not a file, try as directory
+    }
+
+    // Try as directory
+    try {
+      const dir = new Directory(uri);
+      if (dir.exists) {
+        dir.delete();
+        return true;
+      }
+    } catch {
+      // Not a directory either
+    }
+
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Copy file
+ */
+export async function copyFile(
+  sourceUri: string,
+  destinationUri: string,
+): Promise<FileOperationResult> {
+  try {
+    const sourceFile = new File(sourceUri);
+    const destination = new File(destinationUri);
+    sourceFile.copy(destination);
+    return { success: true, uri: destinationUri };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error",
+    };
+  }
+}
+
+/**
+ * Move file
+ */
+export async function moveFile(
+  sourceUri: string,
+  destinationUri: string,
+): Promise<FileOperationResult> {
+  try {
+    const sourceFile = new File(sourceUri);
+    const destination = new File(destinationUri);
+    sourceFile.move(destination);
+    return { success: true, uri: destinationUri };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error",
+    };
+  }
+}
+

package/src/filesystem/infrastructure/services/file-path.service.ts

@@ -0,0 +1,22 @@
+/**
+ * File Path Service
+ * Single Responsibility: Generate and manage file paths
+ */
+
+import type { DirectoryType } from "../../domain/entities/File";
+import { getDirectoryPath } from "./directory.service";
+import { FileUtils } from "../../domain/entities/File";
+
+/**
+ * Generate unique file path in specified directory
+ */
+export function generateFilePath(
+  filename: string,
+  directory: DirectoryType = "documentDirectory",
+): string {
+  const dirPath = getDirectoryPath(directory);
+  const uniqueFilename = FileUtils.generateUniqueFilename(filename);
+  return FileUtils.joinPaths(dirPath, uniqueFilename);
+}
+
+

package/src/filesystem/infrastructure/services/file-reader.service.ts

@@ -0,0 +1,52 @@
+/**
+ * File Reader Service
+ * Single Responsibility: Read files from device storage
+ */
+
+import { File } from "expo-file-system";
+import type { FileEncoding } from "../../domain/entities/File";
+import { blobToBase64 } from "../utils/blob.utils";
+
+/**
+ * Read file as string with encoding
+ */
+export async function readFile(
+  uri: string,
+  encoding: FileEncoding = "utf8",
+): Promise<string | null> {
+  try {
+    // For file:// URLs, try fetch first (works in React Native)
+    if (uri.startsWith("file://")) {
+      try {
+        const response = await fetch(uri);
+        if (response.ok) {
+          if (encoding === "base64") {
+            const blob = await response.blob();
+            return await blobToBase64(blob);
+          }
+          return await response.text();
+        }
+      } catch {
+        // Fall through to FileSystem API
+      }
+    }
+
+    // Use FileSystem API as fallback
+    const file = new File(uri);
+    if (encoding === "base64") {
+      const content = await file.base64();
+      return content;
+    }
+    const content = await file.text();
+    return content;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read file as base64 string
+ */
+export async function readFileAsBase64(uri: string): Promise<string | null> {
+  return readFile(uri, "base64");
+}

package/src/filesystem/infrastructure/services/file-writer.service.ts

@@ -0,0 +1,32 @@
+/**
+ * File Writer Service
+ * Single Responsibility: Write files to device storage
+ */
+
+import { File } from "expo-file-system";
+import type { FileEncoding, FileOperationResult } from "../../domain/entities/File";
+import { getEncodingType, type ExpoEncodingType } from "./encoding.service";
+
+/**
+ * Write string to file
+ */
+export async function writeFile(
+  uri: string,
+  content: string,
+  encoding: FileEncoding = "utf8",
+): Promise<FileOperationResult> {
+  try {
+    const encodingType = getEncodingType(encoding);
+    const file = new File(uri);
+    file.write(content, {
+      encoding: encodingType as ExpoEncodingType,
+    });
+    return { success: true, uri };
+  } catch (error) {
+    const writeError = error as Error;
+    return {
+      success: false,
+      error: writeError.message || "Unknown error",
+    };
+  }
+}

package/src/filesystem/infrastructure/utils/blob.utils.ts

@@ -0,0 +1,20 @@
+/**
+ * Blob Utils
+ * Blob utility functions for file operations
+ */
+
+/**
+ * Convert blob to base64 string
+ */
+export function blobToBase64(blob: Blob): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onloadend = () => {
+      const result = reader.result as string;
+      const base64 = result.includes(",") ? result.split(",")[1] ?? result : result;
+      resolve(base64);
+    };
+    reader.onerror = reject;
+    reader.readAsDataURL(blob);
+  });
+}

package/src/image/infrastructure/services/ImageStorageService.ts

@@ -4,7 +4,7 @@
  * Handles saving images to the device filesystem
  */
 
-import { FileSystemService } from '@umituz/react-native-filesystem';
+import { FileSystemService } from '@filesystem';
 import { ImageValidator } from '../utils/ImageValidator';
 import { ImageErrorHandler, IMAGE_ERROR_CODES } from '../utils/ImageErrorHandler';
 

package/src/index.ts

@@ -102,7 +102,21 @@ export * from './exports/variants';
 // =============================================================================
 export * from './exports/utilities';
 
+// =============================================================================
+// STORAGE EXPORTS
+// =============================================================================
+export * from './exports/storage';
+
 // =============================================================================
 // ONBOARDING EXPORTS
 // =============================================================================
 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;