feat: implement offline synchronization with mutation queue and background sync

- Created useOfflineSync hook for connectivity detection and sync management
- Implemented localStorage-based mutation queue for offline operations
- Added background sync support in service worker
- Created OfflineIndicator component to show connection status
- Added offline-aware action wrappers for seamless offline/online transitions
- Implemented conflict handling with retry logic (up to 3 retries)
- Auto-sync when connection is restored
- Validates Requirements 4.5
This commit is contained in:
2025-12-01 20:34:21 +00:00
parent ef6a0bf5af
commit 9726f3a9e1
8 changed files with 716 additions and 1 deletions

View File

@@ -188,10 +188,73 @@ function MyComponent({ listId }) {
}
```
### `useOfflineSync`
Manages offline synchronization with automatic mutation queuing and background sync.
**Features:**
- Automatic online/offline detection
- Mutation queue for offline operations
- Background sync when connection restored
- Conflict handling
- Retry logic with exponential backoff
**Usage:**
```typescript
import { useOfflineSync } from '@/hooks'
function MyComponent() {
const {
isOnline,
isSyncing,
syncError,
queueLength,
queueMutation,
triggerSync,
clearQueue
} = useOfflineSync()
// Queue a mutation when offline
const handleCreateItem = async () => {
if (!isOnline) {
queueMutation({
type: 'create',
entity: 'item',
data: { listId: '123', title: 'New Item' }
})
} else {
await createItem('123', 'New Item')
}
}
return (
<div>
{!isOnline && <div>Offline - changes will sync when online</div>}
{isSyncing && <div>Syncing {queueLength} changes...</div>}
{syncError && <div>Sync error: {syncError.message}</div>}
</div>
)
}
```
**Offline-Aware Actions:**
For convenience, use the offline-aware action wrappers from `lib/offline-actions.ts`:
```typescript
import { createItemOffline, updateItemOffline, deleteItemOffline } from '@/lib/offline-actions'
// These automatically queue mutations when offline
await createItemOffline(listId, title, description, metadata)
await updateItemOffline(itemId, updates)
await deleteItemOffline(itemId)
```
## Requirements Validation
These hooks implement the following requirements from the specification:
- **Requirement 4.5**: Offline synchronization when connectivity restored
- **Requirement 6.4**: Filter state management and clearing
- **Requirement 7.3**: Visual feedback for user actions (optimistic updates)
- **Requirement 7.4**: Scroll position preservation