@umituz/react-native-design-system 2.6.117 → 2.6.118

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@umituz/react-native-design-system",
-  "version": "2.6.117",
-  "description": "Universal design system for React Native apps - Consolidated package with atoms, molecules, organisms, theme, typography, responsive, safe area, exception, infinite scroll, UUID, image and timezone utilities",
+  "version": "2.6.118",
+  "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 and offline utilities",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
@@ -21,6 +21,7 @@
     "./device": "./src/device/index.ts",
     "./image": "./src/image/index.ts",
     "./timezone": "./src/timezone/index.ts",
+    "./offline": "./src/offline/index.ts",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -44,7 +45,8 @@
     "responsive",
     "safe-area",
     "image",
-    "timezone"
+    "timezone",
+    "offline"
   ],
   "author": "Ümit UZ <umit@umituz.com>",
   "license": "MIT",
@@ -69,6 +71,7 @@
     "expo-device": ">=5.0.0",
     "expo-font": ">=12.0.0",
     "expo-image": ">=3.0.0",
+    "expo-network": ">=8.0.0",
     "expo-sharing": ">=12.0.0",
     "react": ">=19.0.0",
     "react-native": ">=0.81.0",

package/src/exports/offline.ts

@@ -0,0 +1,7 @@
+/**
+ * Offline Exports
+ *
+ * Network connectivity state management for React Native apps
+ */
+
+export * from '../offline';

package/src/index.ts

@@ -77,6 +77,11 @@ export * from './exports/uuid';
 // =============================================================================
 export * from './exports/timezone';
 
+// =============================================================================
+// OFFLINE EXPORTS
+// =============================================================================
+export * from './exports/offline';
+
 // =============================================================================
 // VARIANT UTILITIES
 // =============================================================================

package/src/offline/index.ts

@@ -0,0 +1,35 @@
+/**
+ * @umituz/react-native-offline
+ * Network connectivity state management for React Native apps
+ */
+
+// Types
+export type {
+  NetworkState,
+  OfflineState,
+  OfflineStore,
+  OfflineConfig,
+  ConnectionQuality,
+} from './types';
+
+// Store
+export { useOfflineStore } from './infrastructure/storage/OfflineStore';
+
+// Hooks
+export { useOffline, configureOffline } from './presentation/hooks/useOffline';
+export { useOfflineState } from './presentation/hooks/useOfflineState';
+export { useOfflineWithMutations } from './presentation/hooks/useOfflineWithMutations';
+
+// Components
+export { OfflineBanner } from './presentation/components/OfflineBanner';
+export type { OfflineBannerProps } from './presentation/components/OfflineBanner';
+
+// Providers
+export { NetworkProvider } from './presentation/providers/NetworkProvider';
+
+// Events
+export { networkEvents } from './infrastructure/events/NetworkEvents';
+export type { NetworkEventListener, NetworkEvents } from './infrastructure/events/NetworkEvents';
+
+// Utils
+export { HealthCheck } from './infrastructure/utils/healthCheck';

package/src/offline/infrastructure/events/NetworkEvents.ts

@@ -0,0 +1,52 @@
+/**
+ * Network Events
+ * Event emitter for network state changes
+ * Allows subscribing to network events throughout the app
+ */
+
+import type { NetworkState } from '../../types';
+
+export type NetworkEventListener = (state: NetworkState) => void;
+
+export interface NetworkEvents {
+  on(event: 'online', listener: NetworkEventListener): void;
+  on(event: 'offline', listener: NetworkEventListener): void;
+  on(event: 'change', listener: NetworkEventListener): void;
+  off(event: 'online' | 'offline' | 'change', listener: NetworkEventListener): void;
+  emit(event: 'online' | 'offline' | 'change', state: NetworkState): void;
+  removeAllListeners(): void;
+}
+
+class NetworkEventEmitter implements NetworkEvents {
+  private listeners: Map<string, Set<NetworkEventListener>> = new Map();
+
+  on(event: 'online' | 'offline' | 'change', listener: NetworkEventListener): void {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, new Set());
+    }
+    this.listeners.get(event)?.add(listener);
+  }
+
+  off(event: 'online' | 'offline' | 'change', listener: NetworkEventListener): void {
+    this.listeners.get(event)?.delete(listener);
+  }
+
+  emit(event: 'online' | 'offline' | 'change', state: NetworkState): void {
+    this.listeners.get(event)?.forEach((listener) => {
+      try {
+        listener(state);
+      } catch (error) {
+        if (__DEV__) {
+          // eslint-disable-next-line no-console
+          console.error(`[NetworkEventEmitter] Error in ${event} listener:`, error);
+        }
+      }
+    });
+  }
+
+  removeAllListeners(): void {
+    this.listeners.clear();
+  }
+}
+
+export const networkEvents = new NetworkEventEmitter();

package/src/offline/infrastructure/storage/OfflineStore.ts

@@ -0,0 +1,79 @@
+/**
+ * Offline Store
+ * Manages network connectivity state across the application
+ * Uses expo-network for universal network detection
+ */
+
+import { createStore } from '@umituz/react-native-storage';
+import type { NetworkState, OfflineState, OfflineActions } from '../../types';
+
+const initialState: OfflineState = {
+  isOnline: true,
+  isOffline: false,
+  connectionType: null,
+  isInternetReachable: null,
+  lastOnlineAt: new Date(),
+  lastOfflineAt: null,
+  connectionQuality: {
+    latency: null,
+    effectiveType: null,
+    isSlow: false,
+  },
+};
+
+export const useOfflineStore = createStore<OfflineState, OfflineActions>({
+  name: 'offline-store',
+  initialState,
+  persist: false,
+  actions: (set, get) => ({
+    updateNetworkState: (state: NetworkState) => {
+      const isConnected = state.isConnected ?? false;
+      const isReachable = state.isInternetReachable ?? null;
+      const isOnline = isConnected && (isReachable !== false);
+      const currentState = get();
+
+      const hasChanged =
+        currentState.isOnline !== isOnline ||
+        currentState.connectionType !== state.type ||
+        currentState.isInternetReachable !== isReachable;
+
+      if (hasChanged) {
+        set({
+          isOnline,
+          isOffline: !isConnected || (isReachable === false),
+          connectionType: state.type,
+          isInternetReachable: isReachable,
+          lastOnlineAt: (isConnected && isReachable !== false) ? new Date() : currentState.lastOnlineAt,
+          lastOfflineAt: (!isConnected || isReachable === false) ? new Date() : currentState.lastOfflineAt,
+          connectionQuality: currentState.connectionQuality,
+        });
+      }
+    },
+
+    setOnline: () => {
+      const currentState = get();
+      if (!currentState.isOnline) {
+        set({
+          isOnline: true,
+          isOffline: false,
+          lastOnlineAt: new Date(),
+          connectionQuality: currentState.connectionQuality,
+        });
+      }
+    },
+
+    setOffline: () => {
+      const currentState = get();
+      if (currentState.isOnline) {
+        set({
+          isOnline: false,
+          isOffline: true,
+          lastOfflineAt: new Date(),
+          connectionQuality: currentState.connectionQuality,
+        });
+      }
+    },
+
+    reset: () => set(initialState),
+  }),
+});

package/src/offline/infrastructure/utils/healthCheck.ts

@@ -0,0 +1,116 @@
+/**
+ * Connection Health Check
+ * Periodically checks real internet connectivity by pinging a reliable endpoint
+ */
+
+import type { OfflineConfig } from '../../types';
+
+const DEFAULT_HEALTH_CHECK_URL = 'https://www.google.com/favicon.ico';
+const DEFAULT_TIMEOUT = 5000;
+
+export class HealthCheck {
+  private intervalId: ReturnType<typeof setInterval> | null = null;
+  private isChecking = false;
+  private config: Required<OfflineConfig>;
+
+  constructor(config: OfflineConfig = {}) {
+    this.config = {
+      persist: config.persist ?? false,
+      debug: config.debug ?? false,
+      healthCheckInterval: config.healthCheckInterval ?? 0,
+      healthCheckTimeout: config.healthCheckTimeout ?? DEFAULT_TIMEOUT,
+      healthCheckUrl: config.healthCheckUrl ?? DEFAULT_HEALTH_CHECK_URL,
+    };
+  }
+
+  /**
+   * Perform a single health check
+   */
+  async check(): Promise<boolean> {
+    if (this.isChecking) {
+      return false;
+    }
+
+    this.isChecking = true;
+
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.config.healthCheckTimeout);
+
+      const response = await fetch(this.config.healthCheckUrl, {
+        method: 'HEAD',
+        signal: controller.signal,
+        cache: 'no-cache',
+      });
+
+      clearTimeout(timeoutId);
+
+      const isHealthy = response.ok;
+
+      if (this.config.debug) {
+        // eslint-disable-next-line no-console
+        console.log('[HealthCheck] Result:', isHealthy ? 'HEALTHY' : 'UNHEALTHY');
+      }
+
+      return isHealthy;
+    } catch (error) {
+      if (this.config.debug) {
+        // eslint-disable-next-line no-console
+        console.warn('[HealthCheck] Failed:', error);
+      }
+
+      return false;
+    } finally {
+      this.isChecking = false;
+    }
+  }
+
+  /**
+   * Start periodic health checks
+   */
+  start(callback: (isHealthy: boolean) => void): void {
+    if (this.config.healthCheckInterval === 0) {
+      if (this.config.debug) {
+        // eslint-disable-next-line no-console
+        console.log('[HealthCheck] Disabled (interval = 0)');
+      }
+      return;
+    }
+
+    if (this.intervalId) {
+      this.stop();
+    }
+
+    if (this.config.debug) {
+      // eslint-disable-next-line no-console
+      console.log('[HealthCheck] Starting (interval:', this.config.healthCheckInterval + 'ms)');
+    }
+
+    this.intervalId = setInterval(async () => {
+      const isHealthy = await this.check();
+      callback(isHealthy);
+    }, this.config.healthCheckInterval);
+  }
+
+  /**
+   * Stop health checks
+   */
+  stop(): void {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+
+      if (this.config.debug) {
+        // eslint-disable-next-line no-console
+        console.log('[HealthCheck] Stopped');
+      }
+    }
+  }
+
+  /**
+   * Clean up resources
+   */
+  destroy(): void {
+    this.stop();
+  }
+}

package/src/offline/presentation/components/OfflineBanner.tsx

@@ -0,0 +1,173 @@
+/**
+ * OfflineBanner Component
+ *
+ * Displays a banner when the device is offline.
+ * Fully customizable for use across 100+ apps.
+ *
+ * @example
+ * ```tsx
+ * import { OfflineBanner, useOffline } from '@umituz/react-native-offline';
+ *
+ * const App = () => {
+ *   const { isOffline } = useOffline();
+ *
+ *   return (
+ *     <>
+ *       <OfflineBanner
+ *         visible={isOffline}
+ *         message="No internet connection"
+ *         backgroundColor="#FF6B6B"
+ *       />
+ *       <YourContent />
+ *     </>
+ *   );
+ * };
+ * ```
+ */
+
+import React, { useEffect, useRef, memo } from 'react';
+import {
+  View,
+  Text,
+  Animated,
+  StyleSheet,
+  type ViewStyle,
+  type TextStyle,
+} from 'react-native';
+
+export interface OfflineBannerProps {
+  /** Whether the banner is visible */
+  visible: boolean;
+  /** Message to display */
+  message?: string;
+  /** Background color of the banner */
+  backgroundColor?: string;
+  /** Text color */
+  textColor?: string;
+  /** Icon to display (emoji or custom element) */
+  icon?: string | React.ReactNode;
+  /** Position of the banner */
+  position?: 'top' | 'bottom';
+  /** Custom container style */
+  style?: ViewStyle;
+  /** Custom text style */
+  textStyle?: TextStyle;
+  /** Animation duration in ms */
+  animationDuration?: number;
+  /** Height of the banner */
+  height?: number;
+}
+
+const DEFAULT_HEIGHT = 44;
+const DEFAULT_ANIMATION_DURATION = 300;
+
+export const OfflineBanner: React.FC<OfflineBannerProps> = memo(({
+  visible,
+  message = 'No internet connection',
+  backgroundColor = '#FF6B6B',
+  textColor = '#FFFFFF',
+  icon = '📡',
+  position = 'top',
+  style,
+  textStyle,
+  animationDuration = DEFAULT_ANIMATION_DURATION,
+  height = DEFAULT_HEIGHT,
+}) => {
+  const animatedValue = useRef(new Animated.Value(visible ? 1 : 0)).current;
+  const isFirstRender = useRef(true);
+
+  useEffect(() => {
+    if (isFirstRender.current) {
+      isFirstRender.current = false;
+      animatedValue.setValue(visible ? 1 : 0);
+      return;
+    }
+
+    Animated.timing(animatedValue, {
+      toValue: visible ? 1 : 0,
+      duration: animationDuration,
+      useNativeDriver: false,
+    }).start();
+  }, [visible, animatedValue, animationDuration]);
+
+  const translateY = animatedValue.interpolate({
+    inputRange: [0, 1],
+    outputRange: [position === 'top' ? -height : height, 0],
+  });
+
+  const animatedHeight = animatedValue.interpolate({
+    inputRange: [0, 1],
+    outputRange: [0, height],
+  });
+
+  const opacity = animatedValue.interpolate({
+    inputRange: [0, 0.5, 1],
+    outputRange: [0, 0.8, 1],
+  });
+
+  const positionStyle: ViewStyle = position === 'top'
+    ? { top: 0 }
+    : { bottom: 0 };
+
+  return (
+    <Animated.View
+      style={[
+        styles.container,
+        positionStyle,
+        {
+          backgroundColor,
+          height: animatedHeight,
+          transform: [{ translateY }],
+          opacity,
+        },
+        style,
+      ]}
+      pointerEvents={visible ? 'auto' : 'none'}
+    >
+      <View style={styles.content}>
+        {typeof icon === 'string' ? (
+          <Text style={styles.icon}>{icon}</Text>
+        ) : (
+          icon
+        )}
+        <Text
+          style={[
+            styles.message,
+            { color: textColor },
+            textStyle,
+          ]}
+          numberOfLines={1}
+        >
+          {message}
+        </Text>
+      </View>
+    </Animated.View>
+  );
+});
+
+OfflineBanner.displayName = 'OfflineBanner';
+
+const styles = StyleSheet.create({
+  container: {
+    position: 'absolute',
+    left: 0,
+    right: 0,
+    zIndex: 9999,
+    overflow: 'hidden',
+  },
+  content: {
+    flex: 1,
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingHorizontal: 16,
+    gap: 8,
+  },
+  icon: {
+    fontSize: 16,
+  },
+  message: {
+    fontSize: 14,
+    fontWeight: '500',
+  },
+});

package/src/offline/presentation/hooks/useOffline.ts

@@ -0,0 +1,89 @@
+/**
+ * useOffline Hook
+ * Primary hook for accessing offline state in components
+ * Automatically subscribes to network changes via expo-network
+ */
+
+import { useEffect, useCallback, useRef } from 'react';
+import * as Network from 'expo-network';
+import type { NetworkState as ExpoNetworkState } from 'expo-network';
+import type { NetworkState, OfflineConfig } from '../../types';
+import { useOfflineStore } from '../../infrastructure/storage/OfflineStore';
+import { networkEvents } from '../../infrastructure/events/NetworkEvents';
+
+/**
+ * Convert expo-network state to our internal format
+ */
+const toNetworkState = (state: ExpoNetworkState): NetworkState => ({
+  type: state.type?.toString() ?? 'unknown',
+  isConnected: state.isConnected ?? false,
+  isInternetReachable: state.isInternetReachable ?? null,
+  details: null,
+});
+
+let globalConfig: OfflineConfig = {};
+
+export const configureOffline = (config: OfflineConfig): void => {
+  globalConfig = config;
+};
+
+export const useOffline = (config?: OfflineConfig) => {
+  const store = useOfflineStore();
+  const isInitialized = useRef(false);
+  const previousStateRef = useRef<NetworkState | null>(null);
+  const mergedConfig = { ...globalConfig, ...config };
+
+  const handleNetworkStateChange = useCallback((state: ExpoNetworkState) => {
+    const networkState = toNetworkState(state);
+    const wasOnline = previousStateRef.current?.isConnected ?? false;
+    const isNowOnline = networkState.isConnected ?? false;
+
+    store.updateNetworkState(networkState);
+
+    if (wasOnline !== isNowOnline) {
+      if (isNowOnline) {
+        networkEvents.emit('online', networkState);
+      } else {
+        networkEvents.emit('offline', networkState);
+      }
+    }
+
+    networkEvents.emit('change', networkState);
+    previousStateRef.current = networkState;
+  }, [store]);
+
+  useEffect(() => {
+    if (isInitialized.current) return;
+
+    Network.getNetworkStateAsync()
+      .then((state: ExpoNetworkState) => {
+        handleNetworkStateChange(state);
+        isInitialized.current = true;
+      })
+      .catch((error: Error) => {
+        if (__DEV__ || mergedConfig.debug) {
+          // eslint-disable-next-line no-console
+          console.error('[react-native-offline] Failed to fetch network state:', error);
+        }
+      });
+
+    const subscription = Network.addNetworkStateListener(handleNetworkStateChange);
+
+    return () => {
+      subscription.remove();
+      isInitialized.current = false;
+    };
+  }, [handleNetworkStateChange, mergedConfig.debug]);
+
+  return {
+    isOnline: store.isOnline,
+    isOffline: store.isOffline,
+    connectionType: store.connectionType,
+    isInternetReachable: store.isInternetReachable,
+    lastOnlineAt: store.lastOnlineAt,
+    lastOfflineAt: store.lastOfflineAt,
+    connectionQuality: store.connectionQuality,
+    hasConnection: store.isOnline,
+    hasInternet: store.isOnline && store.isInternetReachable !== false,
+  };
+};

package/src/offline/presentation/hooks/useOfflineState.ts

@@ -0,0 +1,15 @@
+/**
+ * useOfflineState Hook
+ * Raw store access without NetInfo subscription
+ * Use this for selectors and performance optimization
+ */
+
+import type { OfflineStore } from '../../types';
+import { useOfflineStore } from '../../infrastructure/storage/OfflineStore';
+
+export const useOfflineState = <T = OfflineStore>(
+  selector?: (state: OfflineStore) => T
+): T => {
+  const store = useOfflineStore();
+  return selector ? selector(store) : (store as T);
+};

package/src/offline/presentation/hooks/useOfflineWithMutations.ts

@@ -0,0 +1,47 @@
+/**
+ * useOfflineWithMutations Hook
+ * Enhanced version that calls a callback when coming back online
+ * Useful for syncing data or resuming operations
+ */
+
+import { useEffect, useRef, useCallback } from 'react';
+import { useOffline } from './useOffline';
+
+export const useOfflineWithMutations = (onOnline: () => Promise<void>) => {
+  const offlineState = useOffline();
+  const previousOnlineRef = useRef(offlineState.isOnline);
+  const isProcessingRef = useRef(false);
+
+  const handleOnlineCallback = useCallback(async () => {
+    if (isProcessingRef.current) return;
+
+    isProcessingRef.current = true;
+    try {
+      if (__DEV__) {
+        // eslint-disable-next-line no-console
+        console.log('[react-native-offline] Executing online callback');
+      }
+      await onOnline();
+    } catch (error) {
+      if (__DEV__) {
+        // eslint-disable-next-line no-console
+        console.error('[react-native-offline] Online callback failed:', error);
+      }
+    } finally {
+      isProcessingRef.current = false;
+    }
+  }, [onOnline]);
+
+  useEffect(() => {
+    const wasOffline = !previousOnlineRef.current;
+    const isNowOnline = offlineState.isOnline;
+
+    if (wasOffline && isNowOnline && !isProcessingRef.current) {
+      handleOnlineCallback();
+    }
+
+    previousOnlineRef.current = offlineState.isOnline;
+  }, [offlineState.isOnline, handleOnlineCallback]);
+
+  return offlineState;
+};

package/src/offline/presentation/providers/NetworkProvider.tsx

@@ -0,0 +1,33 @@
+/**
+ * Network Provider
+ *
+ * Initializes network connectivity listener at app startup.
+ * Wrap your app with this provider to enable offline detection.
+ *
+ * @example
+ * ```tsx
+ * import { NetworkProvider } from '@umituz/react-native-offline';
+ *
+ * const App = () => (
+ *   <NetworkProvider>
+ *     <YourApp />
+ *   </NetworkProvider>
+ * );
+ * ```
+ */
+
+import React, { ReactNode, memo } from 'react';
+import { useOffline } from '../hooks/useOffline';
+
+interface NetworkProviderProps {
+  children: ReactNode;
+}
+
+export const NetworkProvider: React.FC<NetworkProviderProps> = memo(({ children }) => {
+  // Initialize NetInfo listener - updates Zustand store
+  useOffline();
+
+  return <>{children}</>;
+});
+
+NetworkProvider.displayName = 'NetworkProvider';

package/src/offline/types/index.ts

@@ -0,0 +1,67 @@
+/**
+ * Type Definitions
+ * Network connectivity state types for React Native apps
+ */
+
+/**
+ * Network state from expo-network
+ */
+export interface NetworkState {
+  readonly type: string;
+  readonly isConnected: boolean | null;
+  readonly isInternetReachable: boolean | null;
+  readonly details: unknown;
+}
+
+/**
+ * Configuration for offline behavior
+ */
+export interface OfflineConfig {
+  /** Enable persistent storage of network state */
+  persist?: boolean;
+  /** Enable debug logging */
+  debug?: boolean;
+  /** Health check interval in ms (0 = disabled) */
+  healthCheckInterval?: number;
+  /** Health check timeout in ms */
+  healthCheckTimeout?: number;
+  /** Health check URL to ping */
+  healthCheckUrl?: string;
+}
+
+/**
+ * Connection quality metrics
+ */
+export interface ConnectionQuality {
+  readonly latency: number | null;
+  readonly effectiveType: '2g' | '3g' | '4g' | '5g' | 'unknown' | null;
+  readonly isSlow: boolean;
+}
+
+/**
+ * Offline state representation
+ */
+export interface OfflineState {
+  readonly isOnline: boolean;
+  readonly isOffline: boolean;
+  readonly connectionType: string | null;
+  readonly isInternetReachable: boolean | null;
+  readonly lastOnlineAt: Date | null;
+  readonly lastOfflineAt: Date | null;
+  readonly connectionQuality: ConnectionQuality;
+}
+
+/**
+ * Offline store actions
+ */
+export interface OfflineActions {
+  readonly updateNetworkState: (state: NetworkState) => void;
+  readonly setOnline: () => void;
+  readonly setOffline: () => void;
+  readonly reset: () => void;
+}
+
+/**
+ * Offline store with state and actions
+ */
+export interface OfflineStore extends OfflineState, OfflineActions {}