@ea-lab/reactive-json-docs 2.0.1 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ea-lab/reactive-json-docs",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Complete documentation for Reactive-JSON - Components, examples and LLM-parsable guides",
   "main": "public/rjbuild/docs/index.yaml",
   "files": [

package/public/rjbuild/docs/core/element/special/DataSync.md

@@ -124,6 +124,59 @@ This is useful for adding a "Save Now" button alongside auto-save:
   trigger: ~~.saveNow
 ```
 
+## Reacting to Sync Events
+
+`DataSync` dispatches two custom DOM events that can be caught using `on:` in its `actions` array:
+
+| Event | When it fires |
+|---|---|
+| `syncSuccess` | The server returned a 2xx response. |
+| `syncError` | The request failed (any 4xx, 5xx, or network error). |
+
+### Accessing event data
+
+Both events expose their payload through the standard event placeholder system:
+
+| Placeholder | Description |
+|---|---|
+| `<reactive-json:event-new-value>` | The response body (`event.detail.value`). On success, this is the full server response. On a structured error (see below), this is the error body returned by the server. |
+| `<reactive-json:event>.detail.responseContext.status` | The HTTP status code (number), or `undefined` for pure network errors. |
+
+### Example
+
+```yaml
+- type: DataSync
+  path: ~~.userProfile
+  mode: onIdle
+  idleDelay: 2000
+  actions:
+    - what: setData
+      on: syncSuccess
+      path: ~~.lastSync.httpStatus
+      value: "<reactive-json:event>.detail.responseContext.status"
+    - what: setData
+      on: syncSuccess
+      path: ~~.lastSync.response
+      value: "<reactive-json:event-new-value>"
+    - what: setData
+      on: syncError
+      path: ~~.lastSync.httpStatus
+      value: "<reactive-json:event>.detail.responseContext.status"
+    - what: setData
+      on: syncError
+      path: ~~.lastSync.errorBody
+      value: "<reactive-json:event-new-value>"
+```
+
+### Structured vs. unstructured errors
+
+When the server responds with a 4xx/5xx and the body contains a `status` field (matching the Syncable Object format), `DataSync` treats it as a **structured error**:
+- The body replaces the local Syncable Object.
+- `syncError` fires with `event.detail.value` set to that body.
+- The retry mechanism is **not** triggered — the server explicitly acknowledged the error.
+
+For raw server or network errors (5xx without a structured body, or the browser being offline), `syncError` fires with `event.detail.value` set to `undefined`. In this case the component generates a local `status` object with `{ type: "error", message: "..." }` and may trigger retries according to `maxRetries`.
+
 ## Error Handling and Retries
 
 ### Retry behavior
@@ -166,7 +219,7 @@ templates:
       - type: TextField
         dataLocation: ~.data.name
       - type: DataSync
-        path: ~
+        path: "~"
         mode: onIdle
         idleDelay: 1500
 

package/public/rjbuild/docs/core/element/special/DataSync.yaml

@@ -198,6 +198,52 @@ renderView:
         trigger: ~~.saveNow
       ```
 
+      ## Reacting to Sync Events
+
+      `DataSync` dispatches two custom DOM events that can be caught using `on:` in its `actions` array:
+
+      | Event | When it fires |
+      |---|---|
+      | `syncSuccess` | The server returned a 2xx response. |
+      | `syncError` | The request failed (any 4xx, 5xx, or network error). |
+
+      Both events expose their payload through the standard event placeholder system:
+
+      | Placeholder | Description |
+      |---|---|
+      | `<reactive-json:event-new-value>` | The response body (`event.detail.value`). On success, this is the full server response. On a structured error (see below), this is the error body returned by the server. |
+      | `<reactive-json:event>.detail.responseContext.status` | The HTTP status code (number), or `undefined` for pure network errors. |
+
+      ```yaml
+      - type: DataSync
+        path: ~~.userProfile
+        mode: onIdle
+        idleDelay: 2000
+        actions:
+          - what: setData
+            on: syncSuccess
+            path: ~~.lastSync.httpStatus
+            value: "<reactive-json:event>.detail.responseContext.status"
+          - what: setData
+            on: syncSuccess
+            path: ~~.lastSync.response
+            value: "<reactive-json:event-new-value>"
+          - what: setData
+            on: syncError
+            path: ~~.lastSync.httpStatus
+            value: "<reactive-json:event>.detail.responseContext.status"
+          - what: setData
+            on: syncError
+            path: ~~.lastSync.errorBody
+            value: "<reactive-json:event-new-value>"
+      ```
+
+      ### Structured vs. unstructured errors
+
+      When the server responds with a 4xx/5xx and the body contains a `status` field (matching the Syncable Object format), `DataSync` treats it as a **structured error**: the body replaces the local Syncable Object, `syncError` fires with `event.detail.value` set to that body, and the retry mechanism is not triggered.
+
+      For raw server or network errors (5xx without a structured body, or the browser being offline), `syncError` fires with `event.detail.value` set to `undefined`. In this case the component generates a local `status` object with `{ type: "error", message: "..." }` and may trigger retries according to `maxRetries`.
+
       ## Error Handling and Retries
 
       ### What triggers retries
@@ -241,7 +287,7 @@ renderView:
             - type: TextField
               dataLocation: ~.data.name
             - type: DataSync
-              path: ~
+              path: "~"
               mode: onIdle
               idleDelay: 1500