@umituz/react-native-design-system 4.25.98 → 4.25.100

package/dist/utils/async/retryWithBackoff.d.ts

@@ -0,0 +1,74 @@
+/**
+ * retryWithBackoff
+ *
+ * Retry utility with exponential backoff for async operations.
+ * Useful for network requests, file operations, etc.
+ */
+export interface RetryOptions {
+    /**
+     * Maximum number of retry attempts
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Initial delay in milliseconds before first retry
+     * @default 1000
+     */
+    baseDelay?: number;
+    /**
+     * Maximum delay in milliseconds (caps exponential growth)
+     * @default 10000
+     */
+    maxDelay?: number;
+    /**
+     * Multiplier for exponential backoff
+     * @default 2
+     */
+    backoffMultiplier?: number;
+    /**
+     * Function to determine if error is retryable
+     * @default () => true (retry all errors)
+     */
+    shouldRetry?: (error: Error, attempt: number) => boolean;
+    /**
+     * Callback on each retry attempt
+     */
+    onRetry?: (error: Error, attempt: number, delay: number) => void;
+}
+/**
+ * Retry an async function with exponential backoff
+ *
+ * @example
+ * ```ts
+ * const result = await retryWithBackoff(
+ *   () => fetch('https://api.example.com'),
+ *   { maxRetries: 3, baseDelay: 1000 }
+ * );
+ * ```
+ */
+export declare function retryWithBackoff<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Retry with timeout
+ * Combines retry logic with a timeout
+ *
+ * @example
+ * ```ts
+ * const result = await retryWithTimeout(
+ *   () => fetch('https://api.example.com'),
+ *   { timeout: 5000, maxRetries: 3 }
+ * );
+ * ```
+ */
+export declare function retryWithTimeout<T>(fn: () => Promise<T>, options?: RetryOptions & {
+    timeout?: number;
+}): Promise<T>;
+/**
+ * Check if error is a network error
+ * Useful for shouldRetry callback
+ */
+export declare function isNetworkError(error: Error): boolean;
+/**
+ * Check if error is retryable HTTP status
+ * Useful for shouldRetry callback
+ */
+export declare function isRetryableHttpStatus(status: number): boolean;

package/dist/utils/errors/DesignSystemError.d.ts

@@ -0,0 +1,99 @@
+/**
+ * DesignSystemError
+ *
+ * Unified error class for the design system package.
+ * Provides consistent error handling with error codes and context.
+ */
+export declare class DesignSystemError extends Error {
+    /**
+     * Error code for categorization
+     */
+    readonly code: string;
+    /**
+     * Additional context about the error
+     */
+    readonly context?: Record<string, any>;
+    /**
+     * Timestamp when error was created
+     */
+    readonly timestamp: Date;
+    /**
+     * Error category for grouping
+     */
+    readonly category: ErrorCategory;
+    /**
+     * Operation that failed
+     */
+    readonly operation?: string;
+    /**
+     * Original error cause
+     */
+    readonly cause?: unknown;
+    /**
+     * Whether operation can be retried
+     */
+    readonly retryable: boolean;
+    constructor(message: string, code: string, context?: Record<string, any>, metadata?: ErrorMetadata);
+    /**
+     * Convert error to JSON for logging/debugging
+     */
+    toJSON(): Record<string, any>;
+    /**
+     * Get user-friendly error message
+     */
+    getUserMessage(): string;
+}
+/**
+ * Common error codes used across the design system
+ */
+export declare const ErrorCodes: {
+    readonly FILE_NOT_FOUND: "FILE_NOT_FOUND";
+    readonly FILE_READ_ERROR: "FILE_READ_ERROR";
+    readonly FILE_WRITE_ERROR: "FILE_WRITE_ERROR";
+    readonly FILE_DELETE_ERROR: "FILE_DELETE_ERROR";
+    readonly DIRECTORY_CREATE_ERROR: "DIRECTORY_CREATE_ERROR";
+    readonly PERMISSION_DENIED: "PERMISSION_DENIED";
+    readonly STORAGE_FULL: "STORAGE_FULL";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly TIMEOUT_ERROR: "TIMEOUT_ERROR";
+    readonly API_ERROR: "API_ERROR";
+    readonly MEDIA_PICKER_ERROR: "MEDIA_PICKER_ERROR";
+    readonly MEDIA_SAVE_ERROR: "MEDIA_SAVE_ERROR";
+    readonly IMAGE_LOAD_ERROR: "IMAGE_LOAD_ERROR";
+    readonly CACHE_ERROR: "CACHE_ERROR";
+    readonly STORAGE_ERROR: "STORAGE_ERROR";
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly THEME_LOAD_ERROR: "THEME_LOAD_ERROR";
+    readonly THEME_SAVE_ERROR: "THEME_SAVE_ERROR";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+    readonly INITIALIZATION_ERROR: "INITIALIZATION_ERROR";
+};
+export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
+/**
+ * Error Categories for grouping related errors
+ */
+export declare enum ErrorCategory {
+    FILESYSTEM = "FILESYSTEM",
+    NETWORK = "NETWORK",
+    MEDIA = "MEDIA",
+    STORAGE = "STORAGE",
+    CACHE = "CACHE",
+    IMAGE = "IMAGE",
+    VALIDATION = "VALIDATION",
+    THEME = "THEME",
+    PERMISSION = "PERMISSION",
+    INITIALIZATION = "INITIALIZATION",
+    UNKNOWN = "UNKNOWN"
+}
+/**
+ * Error metadata for rich context
+ */
+export interface ErrorMetadata {
+    category?: ErrorCategory;
+    operation?: string;
+    key?: string;
+    cause?: unknown;
+    retryable?: boolean;
+    userMessage?: string;
+}

package/dist/utils/errors/ErrorHandler.d.ts

@@ -0,0 +1,54 @@
+/**
+ * ErrorHandler
+ *
+ * Centralized error handling utility for the design system.
+ * Provides consistent error handling, logging, and reporting.
+ */
+import { DesignSystemError, type ErrorMetadata } from './DesignSystemError';
+import type { Result } from './types/Result';
+export declare class ErrorHandler {
+    /**
+     * Handle and normalize errors
+     * Converts any error type to DesignSystemError
+     */
+    static handle(error: unknown, context?: string, additionalContext?: Record<string, any>): DesignSystemError;
+    /**
+     * Log error to console (only in development)
+     */
+    static log(error: DesignSystemError | Error | unknown): void;
+    /**
+     * Handle error with logging
+     * Combines handle() and log() for convenience
+     */
+    static handleAndLog(error: unknown, context?: string, additionalContext?: Record<string, any>): DesignSystemError;
+    /**
+     * Create a new DesignSystemError with specific code
+     */
+    static create(message: string, code: string, context?: Record<string, any>): DesignSystemError;
+    /**
+     * Wrap async function with error handling
+     * Returns [error, result] tuple (similar to Go pattern)
+     */
+    static tryAsync<T>(fn: () => Promise<T>, context?: string): Promise<[DesignSystemError | null, T | null]>;
+    /**
+     * Wrap sync function with error handling
+     * Returns [error, result] tuple
+     */
+    static try<T>(fn: () => T, context?: string): [DesignSystemError | null, T | null];
+    /**
+     * Normalize any error to DesignSystemError with metadata
+     */
+    static normalize(error: unknown, code: string, metadata?: ErrorMetadata): DesignSystemError;
+    /**
+     * Wrap async function with timeout
+     */
+    static withTimeout<T>(promise: Promise<T>, timeoutMs: number, context?: string): Promise<T>;
+    /**
+     * Wrap async function returning Result type
+     */
+    static tryAsyncResult<T>(fn: () => Promise<T>, code: string, metadata?: ErrorMetadata): Promise<Result<T, DesignSystemError>>;
+    /**
+     * Wrap sync function returning Result type
+     */
+    static tryResult<T>(fn: () => T, code: string, metadata?: ErrorMetadata): Result<T, DesignSystemError>;
+}

package/dist/utils/errors/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Error Utilities
+ * Unified error handling for the design system
+ */
+export { DesignSystemError, ErrorCodes, ErrorCategory, type ErrorCode, type ErrorMetadata } from './DesignSystemError';
+export { ErrorHandler } from './ErrorHandler';
+export type { Result } from './types/Result';
+export { ok, err, unwrap, unwrapOr, map, mapError } from './types/Result';

package/dist/utils/errors/types/Result.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Result Type
+ *
+ * Rust/Go-inspired Result type for explicit error handling.
+ * Alternative to throwing errors or returning tuples.
+ */
+export type Result<T, E = Error> = {
+    success: true;
+    value: T;
+    error: null;
+} | {
+    success: false;
+    value: null;
+    error: E;
+};
+/**
+ * Create a successful result
+ */
+export declare function ok<T, E = Error>(value: T): Result<T, E>;
+/**
+ * Create an error result
+ */
+export declare function err<T, E = Error>(error: E): Result<T, E>;
+/**
+ * Unwrap result value or throw error
+ */
+export declare function unwrap<T, E = Error>(result: Result<T, E>): T;
+/**
+ * Unwrap result value or return default
+ */
+export declare function unwrapOr<T, E = Error>(result: Result<T, E>, defaultValue: T): T;
+/**
+ * Map result value if successful
+ */
+export declare function map<T, U, E = Error>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;
+/**
+ * Map result error if failed
+ */
+export declare function mapError<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F>;

package/dist/utils/formatters/stringFormatter.d.ts

@@ -0,0 +1,78 @@
+/**
+ * String Formatter Utility
+ * String, phone, file size, and duration formatting functions
+ */
+/**
+ * File size formatting options
+ */
+export interface FileSizeFormatOptions {
+    decimals?: number;
+    locale?: string;
+}
+/**
+ * Formats a file size in bytes to human-readable format
+ *
+ * @param bytes - File size in bytes
+ * @param options - Formatting options
+ * @returns Formatted file size string
+ */
+export declare function formatFileSize(bytes: number, options?: FileSizeFormatOptions): string;
+/**
+ * Duration formatting options
+ */
+export interface DurationFormatOptions {
+    format?: 'short' | 'long' | 'digital';
+}
+/**
+ * Formats a duration in seconds to human-readable format
+ *
+ * @param seconds - Duration in seconds
+ * @param options - Formatting options
+ * @returns Formatted duration string
+ */
+export declare function formatDuration(seconds: number, options?: DurationFormatOptions): string;
+/**
+ * Phone number formatting options
+ */
+export interface PhoneFormatOptions {
+    format?: 'national' | 'international' | 'e164';
+    countryCode?: string;
+}
+/**
+ * Formats a phone number
+ *
+ * @param phone - Phone number string (digits only)
+ * @param options - Formatting options
+ * @returns Formatted phone number string
+ */
+export declare function formatPhone(phone: string, options?: PhoneFormatOptions): string;
+/**
+ * Truncates text to a maximum length with ellipsis
+ *
+ * @param text - Text to truncate
+ * @param maxLength - Maximum length
+ * @param suffix - Suffix to add (default: '...')
+ * @returns Truncated text
+ */
+export declare function truncateText(text: string, maxLength: number, suffix?: string): string;
+/**
+ * Capitalizes the first letter of a string
+ *
+ * @param text - Text to capitalize
+ * @returns Capitalized text
+ */
+export declare function capitalize(text: string): string;
+/**
+ * Converts a string to title case
+ *
+ * @param text - Text to convert
+ * @returns Title case text
+ */
+export declare function toTitleCase(text: string): string;
+/**
+ * Converts a string to slug format
+ *
+ * @param text - Text to convert
+ * @returns Slug string
+ */
+export declare function toSlug(text: string): string;

package/dist/utils/hooks/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Shared Hooks Barrel Export
+ */
+export { useAsyncOperation } from './useAsyncOperation';
+export type { AsyncOperationOptions, AsyncOperationState, AsyncOperationActions, AsyncOperationReturn, ErrorHandler, } from './types/AsyncOperationTypes';

package/dist/utils/hooks/types/AsyncOperationTypes.d.ts

@@ -0,0 +1,52 @@
+/**
+ * AsyncOperation Types
+ * Type definitions for useAsyncOperation hook
+ */
+export type ErrorHandler<E = Error> = (error: unknown) => E;
+export interface AsyncOperationOptions<T, E = Error> {
+    /** Skip execution (useful for conditional operations) */
+    skip?: boolean;
+    /** Execute immediately on mount */
+    immediate?: boolean;
+    /** Initial data value */
+    initialData?: T | null;
+    /** Convert error to custom type */
+    errorHandler?: ErrorHandler<E>;
+    /** Callback on success */
+    onSuccess?: (data: T) => void;
+    /** Callback on error */
+    onError?: (error: E) => void;
+    /** Callback on finally (success or error) */
+    onFinally?: () => void;
+    /** Enable retry functionality */
+    enableRetry?: boolean;
+    /** Maximum retry attempts */
+    maxRetries?: number;
+}
+export interface AsyncOperationState<T, E = Error> {
+    /** Current data value */
+    data: T | null;
+    /** Loading state */
+    isLoading: boolean;
+    /** Error state */
+    error: E | null;
+    /** Is operation idle (not executed yet) */
+    isIdle: boolean;
+    /** Is operation successful */
+    isSuccess: boolean;
+    /** Is operation in error state */
+    isError: boolean;
+}
+export interface AsyncOperationActions<T, E = Error> {
+    /** Execute the async operation */
+    execute: (...args: any[]) => Promise<T | null>;
+    /** Retry the last operation */
+    retry: () => Promise<T | null>;
+    /** Reset to initial state */
+    reset: () => void;
+    /** Set data manually */
+    setData: (data: T | null) => void;
+    /** Set error manually */
+    setError: (error: E | null) => void;
+}
+export type AsyncOperationReturn<T, E = Error> = AsyncOperationState<T, E> & AsyncOperationActions<T, E>;

package/dist/utils/hooks/useAsyncOperation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * useAsyncOperation Hook
+ *
+ * Eliminates duplicate async error handling patterns across hooks.
+ * Handles isMountedRef + try-catch-finally + loading/error state management.
+ *
+ * Based on the useAsyncData pattern from useDeviceInfo.ts but generalized
+ * for broader use cases.
+ *
+ * @example
+ * ```typescript
+ * // Simple usage (like useAsyncData)
+ * const { data, isLoading, error, execute } = useAsyncOperation(
+ *   async () => await fetchData(),
+ *   { immediate: true }
+ * );
+ *
+ * // Manual execution (like useMedia)
+ * const { execute, isLoading, error } = useAsyncOperation(
+ *   async (uri: string) => await pickImage(uri),
+ *   { immediate: false }
+ * );
+ * const result = await execute('file://...');
+ *
+ * // With custom error handling
+ * const { data, error } = useAsyncOperation(
+ *   async () => await riskyOperation(),
+ *   {
+ *     errorHandler: (err) => err instanceof Error ? err.message : 'Failed',
+ *     onError: (err) => console.error('Operation failed:', err),
+ *   }
+ * );
+ * ```
+ */
+import type { AsyncOperationOptions, AsyncOperationReturn } from './types/AsyncOperationTypes';
+export declare function useAsyncOperation<T, E = Error>(operation: (...args: any[]) => Promise<T>, options?: AsyncOperationOptions<T, E>): AsyncOperationReturn<T, E>;

package/dist/utils/logger.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Logger Utility
+ * Production-safe logging that respects __DEV__ flag
+ * Logs are suppressed in production builds to reduce bundle size and improve performance
+ */
+interface LoggerConfig {
+    enableInProduction?: boolean;
+    errorTrackingService?: (error: unknown, context?: Record<string, unknown>) => void;
+}
+declare class Logger {
+    private isDev;
+    private config;
+    constructor(config?: LoggerConfig);
+    /**
+     * Debug logging - only in development
+     * Use for detailed debugging information
+     */
+    debug(...args: unknown[]): void;
+    /**
+     * Info logging - only in development
+     * Use for general information
+     */
+    info(...args: unknown[]): void;
+    /**
+     * Warning logging - always shown
+     * Use for recoverable issues
+     */
+    warn(...args: unknown[]): void;
+    /**
+     * Error logging - always shown
+     * Use for errors and exceptions
+     * In production, sends to error tracking service if configured
+     */
+    error(...args: unknown[]): void;
+    /**
+     * Group logging - only in development
+     * Use for grouping related logs
+     */
+    group(label: string): void;
+    /**
+     * End group logging - only in development
+     */
+    groupEnd(): void;
+    /**
+     * Table logging - only in development
+     * Use for displaying tabular data
+     */
+    table(data: unknown): void;
+    /**
+     * Time measurement - only in development
+     * Use for performance measurements
+     */
+    time(label: string): void;
+    /**
+     * End time measurement - only in development
+     */
+    timeEnd(label: string): void;
+    /**
+     * Assert logging - only in development
+     * Use for assertions
+     */
+    assert(condition: boolean, ...args: unknown[]): void;
+    /**
+     * Configure logger
+     */
+    configure(config: LoggerConfig): void;
+}
+export declare const logger: Logger;
+export { Logger };
+export type { LoggerConfig };

package/dist/uuid/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * React Native UUID
+ *
+ * Cross-platform UUID generation for React Native apps
+ */
+export { generateUUID, generateUUID as uuidv4, generateUUID as generateCreationId, isValidUUID, getUUIDVersion, } from "./infrastructure/utils/UUIDUtils";
+export type { UUID } from "./types/UUID";
+export { UUIDVersion, UUID_CONSTANTS } from "./types/UUID";

package/dist/uuid/infrastructure/utils/UUIDUtils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * UUID Generation Utility
+ *
+ * Provides cross-platform UUID generation.
+ * Uses expo-crypto when available, falls back to Math.random-based v4 UUID.
+ */
+import type { UUID } from '../../types/UUID';
+/**
+ * Generate a v4 UUID
+ * Uses expo-crypto's randomUUID() when available, otherwise Math.random fallback
+ */
+export declare const generateUUID: () => UUID;
+/**
+ * Validate UUID format
+ */
+export declare const isValidUUID: (value: string) => value is UUID;
+/**
+ * Get version from UUID string
+ */
+export declare const getUUIDVersion: (value: string) => number | null;

package/dist/uuid/types/UUID.d.ts

@@ -0,0 +1,34 @@
+/**
+ * UUID Type Definition
+ */
+/**
+ * UUID brand type for type safety
+ * Format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+ */
+export type UUID = string & {
+    readonly __brand: unique symbol;
+};
+/**
+ * UUID Version enum
+ */
+export declare enum UUIDVersion {
+    NIL = "nil",
+    V1 = "v1",
+    V2 = "v2",
+    V3 = "v3",
+    V4 = "v4",
+    V5 = "v5"
+}
+/**
+ * UUID constants
+ */
+export declare const UUID_CONSTANTS: {
+    /**
+     * NIL UUID (00000000-0000-0000-0000-000000000000)
+     */
+    readonly NIL: UUID;
+    /**
+     * UUID v4 regex pattern
+     */
+    readonly PATTERN: RegExp;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-design-system",
-  "version": "4.25.98",
+  "version": "4.25.100",
   "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, onboarding, and loading utilities",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",