@umituz/react-native-design-system 4.23.100 → 4.23.101

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

@@ -1,129 +0,0 @@
-# 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/presentation/hooks/card-multimedia.types.README.md

@@ -1,177 +0,0 @@
-# Card Multimedia Hook Types
-
-## Purpose
-TypeScript return type interfaces for card-specific multimedia hooks in the presentation layer.
-
-## File Location
-`src/presentation/hooks/card-multimedia.types.ts`
-
-## Strategy
-- Define contracts for card multimedia hook implementations
-- Ensure type safety across card media operations
-- Provide consistent return types for upload, generation, and validation
-- Support card-specific media operations (including image search)
-- Enable proper error handling and loading states
-- Maintain separation between card and general multimedia types
-
-## Forbidden
-- **DO NOT** import implementation details or hooks in type files
-- **DO NOT** mix CardMediaAttachment and MediaAttachment types
-- **DO NOT** add business logic to type definitions
-- **DO NOT** use `any` type for function parameters or returns
-- **DO NOT** create circular dependencies with domain types
-- **DO NOT** export implementation-specific types
-- **DO NOT** modify these types without updating all hook implementations
-
-## Rules
-1. All hook returns must include loading state, error state, and operation function
-2. Async operations must return Promise with appropriate type
-3. Error states must be string | null (not Error objects)
-4. Progress/results must be null when not active
-5. Boolean states must clearly indicate operation in progress
-6. All interfaces must be exported and public
-7. Type names must follow Use*Result pattern
-8. Functions must accept domain types, not external types
-9. Optional parameters must be clearly marked
-10. Return types must match hook implementations exactly
-
-## AI Agent Guidelines
-
-When working with card multimedia hook types:
-
-1. **Type Imports**: Always import types from this file for card multimedia hooks
-2. **Hook Implementation**: Implement hooks that return these exact interfaces
-3. **Card vs General**: Use Card* types for card-specific operations, Media* for general
-4. **Error Handling**: Always check error state before using results
-5. **Loading States**: Respect loading states to prevent race conditions
-6. **Progress Tracking**: Use progress objects for upload operations
-7. **Type Safety**: Use these types for all card multimedia hook return values
-8. **Testing**: Mock these interfaces when testing card media operations
-
-### Hook Return Type Structure
-
-All card multimedia hook returns follow this consistent pattern:
-
-**Core Components**:
-- **operationFunction**: An async function that accepts parameters and returns a Promise with the result type
-- **isOperationInProgress**: A boolean flag indicating whether the operation is currently running
-- **operationResult**: The result object or null when no operation is active
-- **error**: A string containing error messages or null when no error exists
-
-### UseCardMediaUploadResult
-
-**Purpose**: Card media upload operations with compression options
-
-**Key Features**:
-- Upload function accepts file and compression options
-- Tracks upload progress
-- Returns CardMediaAttachment
-- Handles upload errors
-
-**Usage Pattern**:
-1. Check `isUploading` before calling
-2. Call `uploadMedia()` with file and optional compression
-3. Monitor `uploadProgress` during upload
-4. Check `error` state on completion
-5. Use returned CardMediaAttachment on success
-
-### UseCardMediaGenerationResult
-
-**Purpose**: Card media generation (AI-based generation, image search)
-
-**Key Features**:
-- Generation function accepts request parameters
-- Tracks generation status
-- Returns CardMediaGenerationResult
-- Supports multiple generation methods
-
-**Usage Pattern**:
-1. Prepare CardMediaGenerationRequest
-2. Check `isGenerating` before calling
-3. Call `generateMedia()` with request
-4. Access `generationResult` when complete
-5. Handle `error` if generation fails
-
-### UseCardMediaValidationResult
-
-**Purpose**: Card media validation before upload or processing
-
-**Key Features**:
-- Validation function accepts file
-- Tracks validation status
-- Returns CardMediaValidation result
-- Provides detailed validation errors
-
-**Usage Pattern**:
-1. Check `isValidating` before calling
-2. Call `validateMedia()` with file
-3. Access `validation` result for validity check
-4. Use `validation.errors` array for error details
-5. Check `error` state for validation failures
-
-### UseCardMultimediaFlashcardResult
-
-**Purpose**: Card flashcard CRUD operations
-
-**Key Features**:
-- Create card with multimedia
-- Update card media
-- Delete specific media attachment
-- Tracks processing state
-- Returns CardMultimediaFlashcard
-
-**Usage Pattern**:
-1. Create: Call `createCardMultimedia()` with card data
-2. Update: Call `updateCardMedia()` with cardId and media array
-3. Delete: Call `deleteCardMedia()` with attachmentId
-4. Check `isProcessing` before operations
-5. Handle `error` state for failures
-
-### Card vs General Multimedia Types
-
-| Operation | Card Types | General Types | Key Difference |
-|-----------|-----------|---------------|----------------|
-| Upload | CardMediaAttachment | MediaAttachment | Card-specific metadata |
-| Generation | CardMediaGenerationRequest | MediaGenerationRequest | Cards include image search |
-| Validation | CardMediaValidation | MediaValidation | Card-specific rules |
-| Flashcard | CardMultimediaFlashcard | MultimediaFlashcard | Different entity types |
-
-### Type Guards and Validation
-
-1. **Upload Hook**: Check for `uploadMedia` function and `isUploading` boolean
-2. **Generation Hook**: Check for `generateMedia` function and `isGenerating` boolean
-3. **Validation Hook**: Check for `validateMedia` function and `isValidating` boolean
-4. **Flashcard Hook**: Check for all three CRUD functions and `isProcessing` boolean
-
-### Error Handling Patterns
-
-1. Always check if `error !== null` before using results
-2. Errors are strings, not Error objects
-3. Clear error before starting new operation
-4. Show user-friendly error messages
-5. Handle null states for progress/results
-
-### Async Operation Patterns
-
-1. **Before Call**: Check loading state to prevent concurrent calls
-2. **During Call**: Show loading indicator based on boolean state
-3. **After Call**: Check error state, then use result
-4. **Error Case**: Display error, reset loading state
-5. **Success Case**: Use result, clear error
-
-### Related Domain Types
-
-These interfaces use domain types:
-- CardMediaAttachment
-- CardMediaGenerationRequest
-- CardMediaGenerationResult
-- CardMediaCompressionOptions
-- CardMediaValidation
-- CardMediaUploadProgress
-- CardMultimediaFlashcard
-
-## Dependencies
-
-- Domain layer types (Card* entities)
-- Presentation layer hooks
-- No external dependencies

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

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

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

@@ -1,201 +0,0 @@
-# Multimedia Hook Types
-
-## Purpose
-TypeScript return type interfaces for general multimedia hooks in the presentation layer.
-
-## File Location
-`src/presentation/hooks/multimedia.types.ts`
-
-## Strategy
-- Define contracts for general multimedia hook implementations
-- Ensure type safety across media operations
-- Provide consistent return types for upload, generation, and validation
-- Support general-purpose media operations
-- Enable proper error handling and loading states
-- Maintain separation from card-specific multimedia types
-
-## Forbidden
-- **DO NOT** import implementation details or hooks in type files
-- **DO NOT** mix MediaAttachment and CardMediaAttachment types
-- **DO NOT** add business logic to type definitions
-- **DO NOT** use `any` type for function parameters or returns
-- **DO NOT** create circular dependencies with domain types
-- **DO NOT** export implementation-specific types
-- **DO NOT** modify these types without updating all hook implementations
-
-## Rules
-1. All hook returns must include loading state, error state, and operation function
-2. Async operations must return Promise with appropriate type
-3. Error states must be string | null (not Error objects)
-4. Progress/results must be null when not active
-5. Boolean states must clearly indicate operation in progress
-6. All interfaces must be exported and public
-7. Type names must follow Use*Result pattern
-8. Functions must accept domain types, not external types
-9. Optional parameters must be clearly marked
-10. Return types must match hook implementations exactly
-
-## AI Agent Guidelines
-
-When working with multimedia hook types:
-
-1. **Type Imports**: Always import types from this file for general multimedia hooks
-2. **Hook Implementation**: Implement hooks that return these exact interfaces
-3. **General vs Card**: Use Media* types for general operations, Card* for card-specific
-4. **Error Handling**: Always check error state before using results
-5. **Loading States**: Respect loading states to prevent race conditions
-6. **Progress Tracking**: Use progress objects for upload operations
-7. **Type Safety**: Use these types for all general multimedia hook return values
-8. **Testing**: Mock these interfaces when testing media operations
-
-### Hook Return Type Structure
-
-All multimedia hook returns follow this consistent pattern:
-
-**Core Components**:
-- **operationFunction**: An async function that accepts parameters and returns a Promise with the result type
-- **isOperationInProgress**: A boolean flag indicating whether the operation is currently running
-- **operationResult**: The result object or null when no operation is active
-- **error**: A string containing error messages or null when no error exists
-
-### UseMediaUploadResult
-
-**Purpose**: General media upload operations with compression options
-
-**Key Features**:
-- Upload function accepts file and compression options
-- Tracks upload progress
-- Returns MediaAttachment
-- Handles upload errors
-
-**Usage Pattern**:
-1. Check `isUploading` before calling
-2. Call `uploadMedia()` with file and optional compression
-3. Monitor `uploadProgress` during upload
-4. Check `error` state on completion
-5. Use returned MediaAttachment on success
-
-### UseMediaGenerationResult
-
-**Purpose**: General media generation (AI-based generation without image search)
-
-**Key Features**:
-- Generation function accepts request parameters
-- Tracks generation status
-- Returns MediaGenerationResult
-- Supports core generation methods
-
-**Usage Pattern**:
-1. Prepare MediaGenerationRequest
-2. Check `isGenerating` before calling
-3. Call `generateMedia()` with request
-4. Access `generationResult` when complete
-5. Handle `error` if generation fails
-
-### UseMediaValidationResult
-
-**Purpose**: General media validation before upload or processing
-
-**Key Features**:
-- Validation function accepts file
-- Tracks validation status
-- Returns MediaValidation result
-- Provides detailed validation errors
-
-**Usage Pattern**:
-1. Check `isValidating` before calling
-2. Call `validateMedia()` with file
-3. Access `validation` result for validity check
-4. Use `validation.errors` array for error details
-5. Check `error` state for validation failures
-
-### UseMultimediaFlashcardResult
-
-**Purpose**: General flashcard CRUD operations
-
-**Key Features**:
-- Create flashcard with multimedia
-- Update flashcard media
-- Delete specific media attachment
-- Tracks processing state
-- Returns MultimediaFlashcard
-
-**Usage Pattern**:
-1. Create: Call `createMultimediaCard()` with card data
-2. Update: Call `updateMedia()` with cardId and media array
-3. Delete: Call `deleteMedia()` with attachmentId
-4. Check `isProcessing` before operations
-5. Handle `error` state for failures
-
-### General vs Card Multimedia Types
-
-| Operation | General Types | Card Types | Key Difference |
-|-----------|--------------|------------|----------------|
-| Upload | MediaAttachment | CardMediaAttachment | Different entity structures |
-| Generation | MediaGenerationRequest | CardMediaGenerationRequest | Cards include image search |
-| Validation | MediaValidation | CardMediaValidation | Different validation rules |
-| Flashcard | MultimediaFlashcard | CardMultimediaFlashcard | Different entity types |
-| Features | Core operations | Core + image search | Card has extended features |
-
-### When to Use Which Types
-
-**Use Media* Types (General)**:
-- Generic media handling
-- Non-card-specific operations
-- Reusable media components
-- General-purpose flashcards
-
-**Use Card* Types (Card-Specific)**:
-- Card-specific operations
-- Image search functionality
-- Card entity management
-- Card-specific validation rules
-
-### Type Guards and Validation
-
-1. **Upload Hook**: Check for `uploadMedia` function and `isUploading` boolean
-2. **Generation Hook**: Check for `generateMedia` function and `isGenerating` boolean
-3. **Validation Hook**: Check for `validateMedia` function and `isValidating` boolean
-4. **Flashcard Hook**: Check for all three CRUD functions and `isProcessing` boolean
-
-### Error Handling Patterns
-
-1. Always check if `error !== null` before using results
-2. Errors are strings, not Error objects
-3. Clear error before starting new operation
-4. Show user-friendly error messages
-5. Handle null states for progress/results
-
-### Async Operation Patterns
-
-1. **Before Call**: Check loading state to prevent concurrent calls
-2. **During Call**: Show loading indicator based on boolean state
-3. **After Call**: Check error state, then use result
-4. **Error Case**: Display error, reset loading state
-5. **Success Case**: Use result, clear error
-
-### Composable Hooks Pattern
-
-Combine multiple hook types for complex workflows:
-
-1. **Validate Then Upload**: Use validation result before calling upload
-2. **Generate Then Upload**: Chain generation and upload operations
-3. **Upload Then Create Card**: Use upload result to create flashcard
-4. **Parallel Operations**: Use multiple hooks independently
-
-### Related Domain Types
-
-These interfaces use domain types:
-- MediaAttachment
-- MediaGenerationRequest
-- MediaGenerationResult
-- MediaCompressionOptions
-- MediaValidation
-- MediaUploadProgress
-- MultimediaFlashcard
-
-## Dependencies
-
-- Domain layer types (Media* entities)
-- Presentation layer hooks
-- No external dependencies

package/src/media/presentation/hooks/useCardMediaGeneration.ts

@@ -1,20 +0,0 @@
-/**
- * Card Media Generation Hook
- * Hook for generating card media with AI
- * Now a thin wrapper around useGenericMediaGeneration
- *
- * Note: CardMedia types are aliases of Media types for backward compatibility
- */
-
-import { useGenericMediaGeneration } from "../../infrastructure/hooks/useGenericMediaGeneration";
-import type { UseCardMediaGenerationResult } from "./card-multimedia.types";
-import type {
-  MediaAttachment as CardMediaAttachment,
-  MediaGenerationRequest as CardMediaGenerationRequest,
-} from "../../domain/entities/MultimediaFlashcardTypes";
-
-export const useCardMediaGeneration = (): UseCardMediaGenerationResult => {
-  return useGenericMediaGeneration<CardMediaAttachment, CardMediaGenerationRequest>(
-    (baseAttachment) => baseAttachment as CardMediaAttachment
-  );
-};

package/src/media/presentation/hooks/useCardMediaUpload.ts

@@ -1,84 +0,0 @@
-/**
- * Card Media Upload Hook
- * Hook for uploading card media files
- */
-
-import { useState, useCallback } from "react";
-import { generateThumbnail, getMediaDuration } from "../../infrastructure/utils/file-media-utils";
-import { getMediaTypeFromMime } from "../../infrastructure/utils/mime-type-detector";
-import type { UseCardMediaUploadResult } from "./card-multimedia.types";
-import type {
-  MediaAttachment as CardMediaAttachment,
-  MediaCompressionOptions as CardMediaCompressionOptions,
-  MediaFile as CardMediaFile,
-  MediaUploadProgress as CardMediaUploadProgress,
-} from "../../domain/entities/MultimediaFlashcardTypes";
-
-export const useCardMediaUpload = (): UseCardMediaUploadResult => {
-  const [isUploading, setIsUploading] = useState(false);
-  const [uploadProgress, setUploadProgress] =
-    useState<CardMediaUploadProgress | null>(null);
-  const [error, setError] = useState<string | null>(null);
-
-  const uploadMedia = useCallback(
-    async (file: CardMediaFile, _options?: CardMediaCompressionOptions) => {
-      try {
-        setIsUploading(true);
-        setError(null);
-
-        // Simulate upload progress
-        setUploadProgress({
-          fileId: `upload_${Date.now()}`,
-          progress: 0,
-          status: "uploading",
-        });
-
-        // Simulate progress updates
-        for (let i = 1; i <= 100; i += 10) {
-          await new Promise((resolve) => setTimeout(resolve, 50));
-          setUploadProgress((prev) => (prev ? { ...prev, progress: i } : null));
-        }
-
-        const attachment: CardMediaAttachment = {
-          id: `card_media_${Date.now()}`,
-          type: getMediaTypeFromMime(file.type),
-          position: "both",
-          url: `https://storage.example.com/media/${Date.now()}_${file.name}`,
-          filename: file.name,
-          fileSize: file.size || 100000,
-          mimeType: file.type,
-          duration: await getMediaDuration(file),
-          thumbnailUrl: generateThumbnail(file),
-          caption: "",
-          isDownloaded: true,
-          createdAt: new Date().toISOString(),
-        };
-
-        setUploadProgress({
-          fileId: `upload_${Date.now()}`,
-          progress: 100,
-          status: "completed",
-          url: attachment.url,
-        });
-
-        return attachment;
-      } catch (err) {
-        const errorMessage =
-          err instanceof Error ? err.message : "Upload failed";
-        setError(errorMessage);
-        setIsUploading(false);
-        throw err;
-      } finally {
-        setIsUploading(false);
-      }
-    },
-    [],
-  );
-
-  return {
-    uploadMedia,
-    isUploading,
-    uploadProgress,
-    error,
-  };
-};