@umituz/react-native-settings 5.4.18 → 5.4.20

package/dist/core/base/BaseService.d.ts

@@ -0,0 +1,86 @@
+/**
+ * BaseService
+ *
+ * Abstract base class for all domain services.
+ * Provides consistent error handling, logging, and result patterns.
+ *
+ * @example
+ * ```ts
+ * class MyService extends BaseService {
+ *   protected serviceName = 'MyService';
+ *
+ *   async doSomething(input: Input): Promise<Data> {
+ *     return this.execute('doSomething', async () => {
+ *       // Your logic here
+ *       return result;
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export type Result<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+};
+export type AsyncResult<T> = Promise<Result<T>>;
+/**
+ * Abstract base service with error handling and logging
+ */
+export declare abstract class BaseService {
+    /**
+     * Service name for logging (must be implemented by subclass)
+     */
+    protected abstract serviceName: string;
+    /**
+     * Execute an operation with automatic error handling and logging
+     *
+     * @param operation - Operation name for logging
+     * @param fn - Async function to execute
+     * @returns Result object with success flag
+     */
+    protected execute<T>(operation: string, fn: () => Promise<T>): AsyncResult<T>;
+    /**
+     * Execute without error handling (for critical operations that should crash)
+     *
+     * @param operation - Operation name for logging
+     * @param fn - Async function to execute
+     * @returns Direct result from function
+     */
+    protected executeUnsafe<T>(operation: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Execute a synchronous operation with error handling
+     *
+     * @param operation - Operation name for logging
+     * @param fn - Sync function to execute
+     * @returns Result object with success flag
+     */
+    protected executeSync<T>(operation: string, fn: () => T): Result<T>;
+    /**
+     * Log error in development mode
+     *
+     * @param operation - Operation name
+     * @param error - Error to log
+     */
+    protected logError(operation: string, error: unknown): void;
+    /**
+     * Log info in development mode
+     *
+     * @param operation - Operation name
+     * @param message - Message to log
+     */
+    protected logInfo(operation: string, message: string): void;
+    /**
+     * Log warning in development mode
+     *
+     * @param operation - Operation name
+     * @param message - Warning message
+     */
+    protected logWarning(operation: string, message: string): void;
+    /**
+     * Check if running in development mode
+     */
+    protected get isDev(): boolean;
+}

package/dist/core/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Core Layer - Public API
+ *
+ * Foundational utilities and base classes for the entire application.
+ *
+ * @example
+ * ```ts
+ * import { BaseService, logger, ModalPresets } from '@/core';
+ *
+ * class MyService extends BaseService {
+ *   protected serviceName = 'MyService';
+ * }
+ * ```
+ */
+export { BaseService } from './base/BaseService';
+export type { Result, AsyncResult } from './base/BaseService';
+export { logger, log, createLogger } from './utils/logger';
+export type { Logger, LogContext } from './utils/logger';
+export { validators, valid, invalid, validateAll } from './utils/validators';
+export type { ValidationResult } from './utils/validators';
+export { useModalState, useModalStateWithResult } from './patterns/Modal/useModalState';
+export type { ModalState, ModalConfig, ModalAction, ModalContent, ModalBehavior, ModalResult } from './patterns/Modal/ModalConfig';
+export { ModalPresets, confirmed, dismissed } from './patterns/Modal/ModalConfig';
+export { useScreenData, useSimpleScreenData } from './patterns/Screen/useScreenData';
+export type { UseScreenDataOptions } from './patterns/Screen/useScreenData';
+export type { ScreenData, ScreenDataState, ScreenDataActions, ScreenFetchFunction, ScreenConfig, ScreenHeader, ScreenLoading, ScreenError, ScreenEmpty, ScreenLayout, } from './patterns/Screen/ScreenConfig';
+export { ScreenPresets } from './patterns/Screen/ScreenConfig';

package/dist/core/patterns/Modal/ModalConfig.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Modal Configuration Types
+ *
+ * Standardized configuration for all modal components.
+ * Ensures consistency across the application.
+ *
+ * @example
+ * ```ts
+ * const config: ModalConfig = {
+ *   title: 'Rating',
+ *   content: 'Rate this app',
+ *   actions: [
+ *     { label: 'OK', onPress: () => {}, variant: 'primary' }
+ *   ]
+ * };
+ * ```
+ */
+import type { ReactNode } from 'react';
+/**
+ * Modal action button configuration
+ */
+export interface ModalAction {
+    /**
+     * Button label text
+     */
+    label: string;
+    /**
+     * Button press handler
+     */
+    onPress: () => void | Promise<void>;
+    /**
+     * Button variant
+     */
+    variant?: 'primary' | 'secondary' | 'outline' | 'text' | 'danger';
+    /**
+     * Disable button
+     */
+    disabled?: boolean;
+    /**
+     * Show loading indicator
+     */
+    loading?: boolean;
+    /**
+     * Test ID for E2E testing
+     */
+    testID?: string;
+}
+/**
+ * Modal content configuration
+ */
+export interface ModalContent {
+    /**
+     * Modal title
+     */
+    title?: string;
+    /**
+     * Modal subtitle or description
+     */
+    subtitle?: string;
+    /**
+     * Main content (can be string or React component)
+     */
+    message?: string | ReactNode;
+    /**
+     * Custom icon name
+     */
+    icon?: string;
+    /**
+     * Icon color
+     */
+    iconColor?: string;
+    /**
+     * Custom header component (overrides title/subtitle)
+     */
+    header?: ReactNode;
+    /**
+     * Custom body component (overrides message)
+     */
+    body?: ReactNode;
+    /**
+     * Custom footer component (overrides actions)
+     */
+    footer?: ReactNode;
+}
+/**
+ * Modal behavior configuration
+ */
+export interface ModalBehavior {
+    /**
+     * Close on backdrop press
+     */
+    closeOnBackdropPress?: boolean;
+    /**
+     * Close on back button press (Android)
+     */
+    closeOnBackPress?: boolean;
+    /**
+     * Animation type
+     */
+    animation?: 'none' | 'slide' | 'fade' | 'scale';
+    /**
+     * Dismissible flag
+     */
+    dismissible?: boolean;
+}
+/**
+ * Complete modal configuration
+ */
+export interface ModalConfig extends ModalContent, ModalBehavior {
+    /**
+     * Modal actions (buttons)
+     */
+    actions?: ModalAction[];
+    /**
+     * Maximum width (for responsive design)
+     */
+    maxWidth?: number;
+    /**
+     * Test ID for E2E testing
+     */
+    testID?: string;
+    /**
+     * Custom container style
+     */
+    containerStyle?: object;
+    /**
+     * Custom content style
+     */
+    contentStyle?: object;
+}
+/**
+ * Modal state for useModalState hook
+ */
+export interface ModalState {
+    /**
+     * Modal visibility
+     */
+    visible: boolean;
+    /**
+     * Current modal configuration
+     */
+    config: ModalConfig | null;
+    /**
+     * Show modal with configuration
+     */
+    show: (config: ModalConfig) => void;
+    /**
+     * Hide modal
+     */
+    hide: () => void;
+    /**
+     * Update modal configuration
+     */
+    update: (config: Partial<ModalConfig>) => void;
+}
+/**
+ * Modal result type for async operations
+ */
+export type ModalResult<T = void> = {
+    confirmed: true;
+    data: T;
+} | {
+    confirmed: false;
+};
+/**
+ * Create a confirmed modal result
+ */
+export declare function confirmed<T>(data?: T): ModalResult<T>;
+/**
+ * Create a dismissed modal result
+ */
+export declare function dismissed(): ModalResult<never>;
+/**
+ * Common preset configurations
+ */
+export declare const ModalPresets: {
+    /**
+     * Alert modal (single OK button)
+     */
+    alert: (title: string, message: string, okText?: string) => ModalConfig;
+    /**
+     * Confirm modal (OK and Cancel buttons)
+     */
+    confirm: (title: string, message: string, confirmText?: string, cancelText?: string) => ModalConfig;
+    /**
+     * Info modal (just message with icon)
+     */
+    info: (title: string, message: string, icon?: string) => ModalConfig;
+    /**
+     * Error modal (error styling)
+     */
+    error: (title: string, message: string) => ModalConfig;
+    /**
+     * Loading modal (spinner)
+     */
+    loading: (message: string) => ModalConfig;
+};

package/dist/core/patterns/Modal/useModalState.d.ts

@@ -0,0 +1,53 @@
+/**
+ * useModalState Hook
+ *
+ * Generic modal state management hook.
+ * Replaces modal-specific state logic across domains.
+ *
+ * @example
+ * ```ts
+ * const modal = useModalState();
+ *
+ * // Show modal
+ * modal.show({
+ *   title: 'Confirm',
+ *   message: 'Are you sure?',
+ *   actions: [...]
+ * });
+ *
+ * // Hide modal
+ * modal.hide();
+ * ```
+ */
+import type { ModalConfig, ModalState } from './ModalConfig';
+/**
+ * Generic modal state management hook
+ */
+export declare function useModalState(initialConfig?: ModalConfig | null): ModalState;
+/**
+ * Extended modal state with result handling
+ *
+ * @example
+ * ```ts
+ * const modal = useModalStateWithResult<string>();
+ *
+ * const result = await modal.showAsync({
+ *   title: 'Input',
+ *   actions: [
+ *     { label: 'OK', onPress: (resolve) => resolve('data') }
+ *   ]
+ * });
+ *
+ * if (result.confirmed) {
+ *   console.log(result.data);
+ * }
+ * ```
+ */
+export declare function useModalStateWithResult<T = void>(): {
+    visible: boolean;
+    config: ModalConfig;
+    showAsync: (newConfig: ModalConfig) => Promise<import("./ModalConfig").ModalResult<T>>;
+    hide: () => void;
+    confirm: (data?: T) => void;
+    update: (updates: Partial<ModalConfig>) => void;
+};

package/dist/core/patterns/Screen/ScreenConfig.d.ts

@@ -0,0 +1,273 @@
+/**
+ * Screen Configuration Types
+ *
+ * Standardized configuration for all screen components.
+ * Ensures consistency across the application.
+ *
+ * @example
+ * ```ts
+ * const config: ScreenConfig = {
+ *   title: 'Settings',
+ *   loadingMessage: 'Loading settings...',
+ *   errorMessage: 'Failed to load settings'
+ * };
+ * ```
+ */
+import type { ReactNode } from 'react';
+/**
+ * Screen header configuration
+ */
+export interface ScreenHeader {
+    /**
+     * Header title
+     */
+    title?: string;
+    /**
+     * Header subtitle
+     */
+    subtitle?: string;
+    /**
+     * Show back button
+     */
+    showBackButton?: boolean;
+    /**
+     * Custom back button handler
+     */
+    onBackPress?: () => void;
+    /**
+     * Custom header component
+     */
+    custom?: ReactNode;
+    /**
+     * Right action buttons
+     */
+    actions?: Array<{
+        icon: string;
+        onPress: () => void;
+        testID?: string;
+    }>;
+    /**
+     * Test ID for E2E testing
+     */
+    testID?: string;
+}
+/**
+ * Screen loading state configuration
+ */
+export interface ScreenLoading {
+    /**
+     * Loading spinner size
+     */
+    size?: 'sm' | 'md' | 'lg' | 'xl';
+    /**
+     * Loading message
+     */
+    message?: string;
+    /**
+     * Custom loading component
+     */
+    custom?: ReactNode;
+    /**
+     * Show full container spinner
+     */
+    fullContainer?: boolean;
+}
+/**
+ * Screen error state configuration
+ */
+export interface ScreenError {
+    /**
+     * Error message prefix
+     */
+    prefix?: string;
+    /**
+     * Default error message (when error details unknown)
+     */
+    message?: string;
+    /**
+     * Retry button text
+     */
+    retryText?: string;
+    /**
+     * Show retry button
+     */
+    showRetry?: boolean;
+    /**
+     * Retry handler
+     */
+    onRetry?: () => void;
+    /**
+     * Custom error component
+     */
+    custom?: ReactNode;
+    /**
+     * Error icon name
+     */
+    icon?: string;
+}
+/**
+ * Screen empty state configuration
+ */
+export interface ScreenEmpty {
+    /**
+     * Empty state message
+     */
+    message?: string;
+    /**
+     * Empty state description
+     */
+    description?: string;
+    /**
+     * Empty state icon
+     */
+    icon?: string;
+    /**
+     * Custom empty component
+     */
+    custom?: ReactNode;
+    /**
+     * Action button label
+     */
+    actionLabel?: string;
+    /**
+     * Action button handler
+     */
+    onAction?: () => void;
+}
+/**
+ * Screen layout configuration
+ */
+export interface ScreenLayout {
+    /**
+     * Safe area edges
+     */
+    edges?: Array<'top' | 'bottom' | 'left' | 'right'>;
+    /**
+     * Scrollable content
+     */
+    scrollable?: boolean;
+    /**
+     * Keyboard avoiding view
+     */
+    keyboardAvoiding?: boolean;
+    /**
+     * Hide scroll indicator
+     */
+    hideScrollIndicator?: boolean;
+    /**
+     * Content container style
+     */
+    contentContainerStyle?: object;
+    /**
+     * Test ID for E2E testing
+     */
+    testID?: string;
+}
+/**
+ * Complete screen configuration
+ */
+export interface ScreenConfig {
+    /**
+     * Screen header configuration
+     */
+    header?: ScreenHeader;
+    /**
+     * Loading state configuration
+     */
+    loading?: ScreenLoading;
+    /**
+     * Error state configuration
+     */
+    error?: ScreenError;
+    /**
+     * Empty state configuration
+     */
+    empty?: ScreenEmpty;
+    /**
+     * Layout configuration
+     */
+    layout?: ScreenLayout;
+    /**
+     * Custom container style
+     */
+    containerStyle?: object;
+    /**
+     * Screen test ID
+     */
+    testID?: string;
+}
+/**
+ * Screen data state (for useScreenData hook)
+ */
+export interface ScreenDataState<T> {
+    /**
+     * Loading state
+     */
+    loading: boolean;
+    /**
+     * Error message
+     */
+    error: string | null;
+    /**
+     * Data
+     */
+    data: T | null;
+    /**
+     * Is initialized
+     */
+    initialized: boolean;
+}
+/**
+ * Screen data actions (for useScreenData hook)
+ */
+export interface ScreenDataActions<T> {
+    /**
+     * Set loading state
+     */
+    setLoading: (loading: boolean) => void;
+    /**
+     * Set error state
+     */
+    setError: (error: string | null) => void;
+    /**
+     * Set data state
+     */
+    setData: (data: T | null) => void;
+    /**
+     * Reset state
+     */
+    reset: () => void;
+    /**
+     * Refresh data (calls fetch function)
+     */
+    refresh: () => Promise<void>;
+}
+/**
+ * Screen data hook return type
+ */
+export type ScreenData<T> = ScreenDataState<T> & ScreenDataActions<T>;
+/**
+ * Screen fetch function type
+ */
+export type ScreenFetchFunction<T> = () => Promise<T>;
+/**
+ * Common preset configurations
+ */
+export declare const ScreenPresets: {
+    /**
+     * Default screen configuration
+     */
+    default: ScreenConfig;
+    /**
+     * Modal screen configuration (no back button, full edges)
+     */
+    modal: ScreenConfig;
+    /**
+     * Loading screen configuration
+     */
+    loading: (message?: string) => ScreenConfig;
+    /**
+     * Error screen configuration
+     */
+    error: (message?: string) => ScreenConfig;
+};

package/dist/core/patterns/Screen/useScreenData.d.ts

@@ -0,0 +1,62 @@
+/**
+ * useScreenData Hook
+ *
+ * Generic screen data management hook.
+ * Handles loading, error, and data states for screens.
+ *
+ * @example
+ * ```ts
+ * const screenData = useScreenData({
+ *   fetch: async () => await api.getData(),
+ *   autoFetch: true
+ * });
+ *
+ * if (screenData.loading) return <LoadingSpinner />;
+ * if (screenData.error) return <ErrorMessage error={screenData.error} />;
+ * return <DataView data={screenData.data} />;
+ * ```
+ */
+import type { ScreenData, ScreenDataState, ScreenFetchFunction } from './ScreenConfig';
+export interface UseScreenDataOptions<T> {
+    /**
+     * Fetch function to load data
+     */
+    fetch: ScreenFetchFunction<T>;
+    /**
+     * Auto-fetch on mount
+     */
+    autoFetch?: boolean;
+    /**
+     * Initial data
+     */
+    initialData?: T | null;
+    /**
+     * Dependencies for re-fetching
+     */
+    deps?: unknown[];
+    /**
+     * Error handler
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Success handler
+     */
+    onSuccess?: (data: T) => void;
+}
+/**
+ * Generic screen data management hook
+ */
+export declare function useScreenData<T>(options: UseScreenDataOptions<T>): ScreenData<T>;
+/**
+ * Simple version for basic use cases
+ *
+ * @example
+ * ```ts
+ * const { loading, error, data, refresh } = useSimpleScreenData(
+ *   async () => await api.getData()
+ * );
+ * ```
+ */
+export declare function useSimpleScreenData<T>(fetch: ScreenFetchFunction<T>, autoFetch?: boolean): ScreenDataState<T> & {
+    refresh: () => Promise<void>;
+};