@umituz/react-native-settings 4.20.58 → 4.20.60

package/src/domains/cloud-sync/README.md

@@ -1,444 +1,78 @@
 # Cloud Sync Domain
 
-The Cloud Sync domain provides components for displaying and managing cloud synchronization status in your React Native app.
-
-## Features
-
-- **Sync Status Display**: Show current sync status with visual indicators
-- **Last Synced Info**: Display relative time of last synchronization
-- **Sync Progress**: Show syncing state during active synchronization
-- **Interactive Sync**: Allow users to trigger manual sync
-- **Customizable Messages**: Custom sync status descriptions
-
-## Installation
-
-This domain is part of `@umituz/react-native-settings`. Install the package to use it:
-
-```bash
-npm install @umituz/react-native-settings
-```
-
-## Components
-
-### CloudSyncSetting
-
-Display cloud sync status and allow triggering manual sync.
-
-```tsx
-import { CloudSyncSetting } from '@umituz/react-native-settings';
-
-function MySettings() {
-  const [isSyncing, setIsSyncing] = useState(false);
-  const [lastSynced, setLastSynced] = useState(new Date());
-
-  const handleSync = async () => {
-    setIsSyncing(true);
-    await performSync();
-    setIsSyncing(false);
-    setLastSynced(new Date());
-  };
-
-  return (
-    <CloudSyncSetting
-      isSyncing={isSyncing}
-      lastSynced={lastSynced}
-      onPress={handleSync}
-    />
-  );
-}
-```
-
-#### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `title` | `string` | `'cloud_sync'` | Setting title |
-| `description` | `string` | `undefined` | Custom status description |
-| `isSyncing` | `boolean` | `false` | Syncing state |
-| `lastSynced` | `Date \| null` | `undefined` | Last sync timestamp |
-| `onPress` | `() => void` | `undefined` | Press handler |
-| `disabled` | `boolean` | `false` | Disable interaction |
-
-#### Relative Time Display
-
-The component automatically formats the `lastSynced` timestamp into relative time:
-- `"last_synced_just_now"` - Less than 1 minute ago
-- `"last_synced_5m_ago"` - 5 minutes ago
-- `"last_synced_2h_ago"` - 2 hours ago
-- `"last_synced_3d_ago"` - 3 days ago
-
-You can use these as translation keys or provide your own `description` prop.
-
-## Examples
-
-### Basic Cloud Sync
-
-```tsx
-import { CloudSyncSetting } from '@umituz/react-native-settings';
-import { useState } from 'react';
-
-function BasicCloudSync() {
-  const [isSyncing, setIsSyncing] = useState(false);
-  const [lastSynced, setLastSynced] = useState<Date | null>(null);
-
-  const handleSync = async () => {
-    setIsSyncing(true);
-    try {
-      await syncData();
-      setLastSynced(new Date());
-    } catch (error) {
-      console.error('Sync failed:', error);
-    } finally {
-      setIsSyncing(false);
-    }
-  };
-
-  return (
-    <CloudSyncSetting
-      isSyncing={isSyncing}
-      lastSynced={lastSynced}
-      onPress={handleSync}
-    />
-  );
-}
-```
-
-### With Custom Description
-
-```tsx
-function CloudSyncWithDescription() {
-  const syncStatus = 'Synced 5 minutes ago';
-
-  return (
-    <CloudSyncSetting
-      title="iCloud Sync"
-      description={syncStatus}
-      onPress={() => console.log('Sync pressed')}
-    />
-  );
-}
-```
-
-### Disabled State
-
-```tsx
-function DisabledCloudSync() {
-  return (
-    <CloudSyncSetting
-      title="Cloud Sync"
-      description="Sync disabled"
-      disabled={true}
-    />
-  );
-}
-```
-
-### With Translations
-
-```tsx
-import { useTranslation } from 'react-i18next';
-import { CloudSyncSetting } from '@umituz/react-native-settings';
-
-function LocalizedCloudSync() {
-  const { t } = useTranslation();
-  const [isSyncing, setIsSyncing] = useState(false);
-  const [lastSynced, setLastSynced] = useState<Date | null>(null);
-
-  // Get translation key based on state
-  const getDescription = () => {
-    if (isSyncing) return t('sync.syncing');
-    if (!lastSynced) return t('sync.never');
-    // Calculate relative time and return appropriate translation key
-    const timeAgo = calculateTimeAgo(lastSynced);
-    return t(`sync.${timeAgo}`);
-  };
-
-  return (
-    <CloudSyncSetting
-      title={t('sync.title')}
-      description={getDescription()}
-      isSyncing={isSyncing}
-      lastSynced={lastSynced}
-      onPress={handleSync}
-    />
-  );
-}
-```
-
-### Complete Integration
-
-```tsx
-import { CloudSyncSetting } from '@umituz/react-native-settings';
-import { SettingsSection } from '@umituz/react-native-settings';
-
-function CloudSyncSettings() {
-  const [syncState, setSyncState] = useState({
-    isSyncing: false,
-    lastSynced: null as Date | null,
-    error: null as string | null,
-  });
-
-  const handleSync = async () => {
-    setSyncState(prev => ({ ...prev, isSyncing: true, error: null }));
-
-    try {
-      await cloudSyncService.sync();
-      setSyncState({
-        isSyncing: false,
-        lastSynced: new Date(),
-        error: null,
-      });
-    } catch (error) {
-      setSyncState(prev => ({
-        ...prev,
-        isSyncing: false,
-        error: error.message,
-      }));
-    }
-  };
-
-  return (
-    <SettingsSection title="Sync">
-      <CloudSyncSetting
-        title="Cloud Backup"
-        isSyncing={syncState.isSyncing}
-        lastSynced={syncState.lastSynced}
-        description={syncState.error || undefined}
-        onPress={handleSync}
-        disabled={syncState.isSyncing}
-      />
-    </SettingsSection>
-  );
-}
-```
-
-### With Auto-Sync
-
-```tsx
-import { useEffect, useState } from 'react';
-import { CloudSyncSetting } from '@umituz/react-native-settings';
-
-function AutoSyncCloudSync() {
-  const [isSyncing, setIsSyncing] = useState(false);
-  const [lastSynced, setLastSynced] = useState<Date | null>(null);
-  const [autoSync, setAutoSync] = useState(true);
-
-  // Auto-sync every 5 minutes
-  useEffect(() => {
-    if (!autoSync) return;
-
-    const interval = setInterval(async () => {
-      await performSync();
-    }, 5 * 60 * 1000);
-
-    return () => clearInterval(interval);
-  }, [autoSync]);
-
-  const performSync = async () => {
-    setIsSyncing(true);
-    try {
-      await syncData();
-      setLastSynced(new Date());
-    } finally {
-      setIsSyncing(false);
-    }
-  };
-
-  return (
-    <SettingsSection title="Sync Settings">
-      <SettingsItemCard
-        title="Auto-Sync"
-        value={autoSync ? 'Enabled' : 'Disabled'}
-        onPress={() => setAutoSync(!autoSync)}
-      />
-      <CloudSyncSetting
-        isSyncing={isSyncing}
-        lastSynced={lastSynced}
-        onPress={performSync}
-      />
-    </SettingsSection>
-  );
-}
-```
-
-### Real-Time Sync Status
-
-```tsx
-import { useState, useEffect } from 'react';
-import { CloudSyncSetting } from '@umituz/react-native-settings';
-
-function RealTimeCloudSync() {
-  const [syncStatus, setSyncStatus] = useState({
-    isSyncing: false,
-    lastSynced: null as Date | null,
-    syncCount: 0,
-  });
-
-  useEffect(() => {
-    // Subscribe to sync events
-    const unsubscribe = cloudSyncService.onSyncChange((status) => {
-      setSyncStatus(status);
-    });
-
-    return unsubscribe;
-  }, []);
-
-  return (
-    <CloudSyncSetting
-      title="Real-time Sync"
-      isSyncing={syncStatus.isSyncing}
-      lastSynced={syncStatus.lastSynced}
-      onPress={() => cloudSyncService.triggerSync()}
-    />
-  );
-}
-```
-
-## Architecture
-
-```
-src/domains/cloud-sync/
-├── presentation/
-│   └── components/
-│       ├── CloudSyncSetting.tsx    # Main sync setting component
-│       └── __tests__/
-│           └── CloudSyncSetting.test.tsx
-└── index.ts                        # Public API exports
-```
-
-## Best Practices
-
-1. **Clear Status**: Always show current sync status clearly
-2. **Error Handling**: Display sync errors prominently
-3. **Manual Trigger**: Allow users to manually trigger sync
-4. **Prevent Duplicate Syncs**: Disable sync button while syncing
-5. **Auto-Sync**: Implement automatic sync intervals
-6. **Conflict Resolution**: Handle sync conflicts gracefully
-7. **Background Sync**: Use background sync for better UX
-8. **Progress Indicators**: Show progress for large syncs
-
-## Testing
-
-```tsx
-import { render, fireEvent, waitFor } from '@testing-library/react-native';
-import { CloudSyncSetting } from '@umituz/react-native-settings';
-
-describe('CloudSyncSetting', () => {
-  it('displays syncing state', () => {
-    const { getByText } = render(
-      <CloudSyncSetting
-        isSyncing={true}
-        onPress={() => {}}
-      />
-    );
-
-    expect(getByText(/syncing/i)).toBeTruthy();
-  });
-
-  it('displays last synced time', () => {
-    const lastSynced = new Date(Date.now() - 5 * 60 * 1000); // 5 minutes ago
-    const { getByText } = render(
-      <CloudSyncSetting
-        lastSynced={lastSynced}
-        onPress={() => {}}
-      />
-    );
-
-    expect(getByText(/5m_ago/i)).toBeTruthy();
-  });
-
-  it('calls onPress when pressed', () => {
-    const mockPress = jest.fn();
-    const { getByTestId } = render(
-      <CloudSyncSetting
-        onPress={mockPress}
-      />
-    );
-
-    fireEvent.press(getByTestId('settings-item-card'));
-    expect(mockPress).toHaveBeenCalled();
-  });
-
-  it('does not respond to press when syncing', () => {
-    const mockPress = jest.fn();
-    const { getByTestId } = render(
-      <CloudSyncSetting
-        isSyncing={true}
-        onPress={mockPress}
-      />
-    );
-
-    fireEvent.press(getByTestId('settings-item-card'));
-    expect(mockPress).not.toHaveBeenCalled();
-  });
-
-  it('shows custom description when provided', () => {
-    const { getByText } = render(
-      <CloudSyncSetting
-        description="Custom sync message"
-        onPress={() => {}}
-      />
-    );
-
-    expect(getByText('Custom sync message')).toBeTruthy();
-  });
-});
-```
-
-## Integration Examples
-
-### With Cloud Services
-
-```tsx
-// iCloud sync (iOS)
-import CloudSyncSetting from '@umituz/react-native-settings';
-
-function iCloudSync() {
-  const [isSyncing, setIsSyncing] = useState(false);
-  const [lastSynced, setLastSynced] = useState<Date | null>(null);
-
-  const syncWithiCloud = async () => {
-    setIsSyncing(true);
-    try {
-      await CKContainer.defaultContainer().sync();
-      setLastSynced(new Date());
-    } finally {
-      setIsSyncing(false);
-    }
-  };
-
-  return (
-    <CloudSyncSetting
-      title="iCloud"
-      isSyncing={isSyncing}
-      lastSynced={lastSynced}
-      onPress={syncWithiCloud}
-    />
-  );
-}
-
-// Firebase sync
-function FirebaseSync() {
-  const [isSyncing, setIsSyncing] = useState(false);
-
-  const syncWithFirebase = async () => {
-    setIsSyncing(true);
-    try {
-      await firebase.firestore().sync();
-    } finally {
-      setIsSyncing(false);
-    }
-  };
-
-  return (
-    <CloudSyncSetting
-      title="Firebase"
-      isSyncing={isSyncing}
-      onPress={syncWithFirebase}
-    />
-  );
-}
-```
+## Purpose
+
+Provides components for displaying and managing cloud synchronization status with relative time display and manual sync triggering.
+
+## File Paths
+
+**Components:**
+- `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/cloud-sync/presentation/components/CloudSyncSetting.tsx`
+
+**Tests:**
+- `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/cloud-sync/presentation/components/__tests__/CloudSyncSetting.test.tsx`
+
+**Index:**
+- `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/cloud-sync/index.ts`
+
+## Strategy
+
+1. **Relative Time Display**: Automatically format lastSynced timestamp into relative time strings (5m ago, 2h ago, etc.)
+2. **Sync State Management**: Display current sync status clearly with visual indicators
+3. **Manual Trigger**: Allow users to manually trigger sync with proper state management
+4. **Error Handling**: Display sync errors prominently with user-friendly messages
+5. **Prevent Duplicates**: Disable sync button while syncing is in progress
+
+## Restrictions (Forbidden)
+
+### DO NOT
+- ❌ DO NOT trigger sync while already syncing (check isSyncing prop)
+- ❌ DO NOT bypass the relative time formatting for lastSynced
+- ❌ DO NOT use CloudSyncSetting without handling onPress callback
+- ❌ DO NOT mix sync logic directly with UI components
+
+### NEVER
+- ❌ NEVER allow sync trigger when isSyncing is true
+- ❌ NEVER show sync status without proper error handling
+- ❌ NEVER use custom time formatting when relative time is provided
+- ❌ NEVER create custom sync components when CloudSyncSetting exists
+
+### AVOID
+- ❌ AVOID hardcoding sync status messages - use description prop or relative time
+- ❌ AVOID creating custom sync UI when CloudSyncSetting can be configured
+- ❌ AVOID mixing sync logic with business logic
+- ❌ AVOID triggering sync without proper state management
+
+## Rules
+
+### ALWAYS
+- ✅ ALWAYS provide onPress handler for manual sync triggering
+- ✅ ALWAYS check isSyncing before allowing sync operations
+- ✅ ALWAYS handle sync errors gracefully with user feedback
+- ✅ ALWAYS provide lastSynced timestamp for relative time display
+- ✅ ALWAYS disable interaction when sync is in progress
+
+### MUST
+- ✅ MUST use isSyncing prop to prevent duplicate sync operations
+- ✅ MUST provide lastSynced Date object for automatic relative time formatting
+- ✅ MUST handle sync errors and display them to users
+- ✅ MUST update lastSynced timestamp after successful sync
+- ✅ MUST disable CloudSyncSetting while syncing (disabled or isSyncing prop)
+
+### SHOULD
+- ✅ SHOULD show clear sync status to users
+- ✅ SHOULD implement automatic sync intervals
+- ✅ SHOULD handle sync conflicts gracefully
+- ✅ SHOULD use background sync for better UX
+- ✅ SHOULD show progress indicators for large syncs
+
+## AI Agent Guidelines
+
+1. **Component Usage**: Always use CloudSyncSetting for sync status display - never create custom sync components
+2. **State Management**: Always use isSyncing prop to prevent duplicate sync operations
+3. **Time Display**: Always use lastSynced Date object for automatic relative time formatting
+4. **Error Handling**: Always handle sync errors gracefully with user-friendly error messages
+5. **Prevention**: Always disable sync button while syncing is in progress
 
 ## Related