Create syncstate-implementation.md

documentation/syncstate-implementation.md

@@ -0,0 +1,81 @@
+# SyncState Implementation in AppState
+
+This guide covers how to set up and configure SyncState in your application, including setting up iCloud capabilities and understanding potential limitations.
+
+## 1. Setting Up iCloud Capabilities
+
+To use SyncState in your application, you first need to enable iCloud in your project and configure Key-Value storage.
+
+### Steps to Enable iCloud and Key-Value Storage:
+
+1. Open your Xcode project and navigate to your project settings.
+2. Under the "Signing & Capabilities" tab, select your target (iOS or macOS).
+3. Click the "+ Capability" button and choose "iCloud" from the list.
+4. Enable the "Key-Value storage" option under iCloud settings. This allows your app to store and sync small amounts of data using iCloud.
+
+### Entitlements File Configuration:
+
+1. In your Xcode project, find or create the **entitlements file** for your app.
+2. Ensure that the iCloud Key-Value Store is correctly set up in the entitlements file with the correct iCloud container.
+
+Example in the entitlements file:
+
+```xml
+<key>com.apple.developer.ubiquity-kvstore-identifier</key>
+<string>$(TeamIdentifierPrefix)com.yourdomain.app</string>
+```
+
+Make sure that the string value matches the iCloud container associated with your project.
+
+## 2. Using SyncState in Your Application
+
+Once iCloud is enabled, you can use `SyncState` in your application to synchronize data across devices.
+
+### Example of SyncState in Use:
+
+```swift
+import AppState
+import SwiftUI
+
+extension Application {
+    var syncValue: SyncState<Int?> {
+        syncState(id: "syncValue")
+    }
+}
+
+struct ContentView: View {
+    @SyncState(\.syncValue) private var syncValue: Int?
+
+    var body: some View {
+        VStack {
+            if let syncValue = syncValue {
+                Text("SyncValue: \(syncValue)")
+            } else {
+                Text("No SyncValue")
+            }
+
+            Button("Update SyncValue") {
+                syncValue = Int.random(in: 0..<100)
+            }
+        }
+    }
+}
+```
+
+In this example, the sync state will be saved to iCloud and synchronized across devices logged into the same iCloud account.
+
+## 3. Limitations and Best Practices
+
+SyncState uses `NSUbiquitousKeyValueStore`, which has some limitations:
+
+- **Storage Limit**: SyncState is designed for small amounts of data. The total storage limit is 1 MB, and each key-value pair is limited to around 1 MB.
+- **Synchronization**: Changes made to the SyncState are not instantly synchronized across devices. There can be a slight delay in synchronization, and iCloud syncing may occasionally be affected by network conditions.
+
+### Best Practices:
+
+- **Use SyncState for Small Data**: Ensure that only small data like user preferences or settings are synchronized using SyncState.
+- **Handle SyncState Failures Gracefully**: Use default values or error handling mechanisms to account for potential sync delays or failures.
+
+## 4. Conclusion
+
+By properly configuring iCloud and understanding the limitations of SyncState, you can leverage its power to sync data across devices. Make sure you only use SyncState for small, critical pieces of data to avoid potential issues with iCloud storage limits.