@jigx/core-sdk 1.0.0 → 1.2.0-rc

package/docs/pattern-sync-progress.md

@@ -0,0 +1,96 @@
+# Pattern: Sync Progress Bar
+
+Ideas for displaying sync progress to the user. Implement and mature as needed.
+
+## Basic approach
+
+Use a progress bar or value widget on the home screen, bound to the `SyncStatus` table. Show it only while syncing using a `when` rule.
+
+```typescript
+// Progress widget — visible only during sync
+screen.addWidget.value({ name: 'sync-progress' })
+  .title('=@ctx.datasources.data-select-sync-status.data.currentStep')
+  .value('=@ctx.datasources.data-select-sync-status.data.currentProgress')
+  .when('=@ctx.datasources.data-select-sync-status.data.status = "syncing"')
+```
+
+## Weight-based progress
+
+Assign a weight to each sync action based on expected duration or record count. As each action completes, add its weight to the running total and update `currentProgress` as a percentage.
+
+```yaml
+# Example weights
+Customers: 40    # large table, takes longest
+Contacts:  30
+Terms:     10
+ShipVia:   10
+Classes:   10
+# Total: 100
+
+# After Customers sync completes:
+currentProgress: 40
+totalSteps: 100
+currentStep: 'Syncing Contacts...'
+```
+
+The progress bar value is `currentProgress / totalSteps` as a fraction.
+
+## Step text
+
+Update `currentStep` in the `SyncStatus` record before each sync action:
+
+```typescript
+// Before syncing customers
+workflow.actions.executeEntity({ instanceId: 'progress-customers' })
+  .local('SyncStatus', 'save')
+  .data({ id: 'initialSync', status: 'syncing', currentStep: 'Syncing Customers...', currentProgress: '0', totalSteps: '100' })
+
+workflow.actions.executeAction({ action: 'act-customers-sync' })
+
+// Before syncing contacts
+workflow.actions.executeEntity({ instanceId: 'progress-contacts' })
+  .local('SyncStatus', 'save')
+  .data({ id: 'initialSync', status: 'syncing', currentStep: 'Syncing Contacts...', currentProgress: '40', totalSteps: '100' })
+
+workflow.actions.executeAction({ action: 'act-contacts-sync' })
+```
+
+## Show/hide with when rules
+
+- **Progress bar visible**: `when: '=@ctx.datasources.data-select-sync-status.data.status = "syncing"'`
+- **Main content visible**: `when: '=@ctx.datasources.data-select-sync-status.data.status = "complete"'` or no `when` (always visible, progress bar overlays)
+- **Error state**: Show a retry button when `status = "failed"`
+
+## Card-based progress display
+
+Instead of a simple value widget, use a card with a progress bar component and descriptive text:
+
+```typescript
+const syncCard = screen.addControl.card({ instanceId: 'sync-card' })
+  .when('=@ctx.datasources.data-select-sync-status.data.status = "syncing"')
+
+// Title shows current step
+syncCard.title('=@ctx.datasources.data-select-sync-status.data.currentStep')
+
+// Subtitle shows n of total
+syncCard.subtitle('="Step " & @ctx.datasources.data-select-sync-status.data.currentProgress & " of " & @ctx.datasources.data-select-sync-status.data.totalSteps')
+
+// Progress bar as fraction
+syncCard.progress('=@ctx.datasources.data-select-sync-status.data.currentProgress / @ctx.datasources.data-select-sync-status.data.totalSteps')
+```
+
+## Combining with sync scopes
+
+Use the `_syncScope` system table alongside `SyncStatus` for richer progress:
+
+- `_syncScope.synced` / total entities = overall entity-level progress
+- `_syncScope.details` JSON gives per-entity state for granular display
+- Show which entity is currently syncing by checking `state = "syncing"` in details
+
+## Ideas to consider
+
+- **Blocking UI during initial sync**: Overlay the progress card on the home screen and hide the main content until `status = "complete"`. Prevents users from interacting with empty data.
+- **Background sync indicator**: For subsequent diff syncs, show a subtle indicator (e.g., a small badge or icon) rather than a full progress bar — the user shouldn't be blocked.
+- **Offline indicator**: Combine with `@ctx.system.isOnline` to show "Waiting for connection..." when offline with pending sync.
+- **Retry on failure**: Add a retry button on the progress card that re-triggers `act-initial-sync` when `status = "failed"`.
+- **Per-entity progress**: For very large syncs, track continuation progress (records synced so far) in the `SyncStatus` table and display it: "Syncing Customers... (3,000 of ~10,000)".