@ea-lab/reactive-json-docs 2.0.2 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ea-lab/reactive-json-docs",
-  "version": "2.0.2",
+  "version": "2.2.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

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

package/public/rjbuild/docs/getting-started/rjbuild-structure.md

@@ -266,12 +266,48 @@ additionalDataSource:
 ```
 
 ### Properties
-- **`src`** (required): URL of the data source
+- **`src`** (required): URL of the data source. Can be a **string** (used as-is) or an **array of segments** that are resolved and concatenated (see [Dynamic URLs](#dynamic-urls-with-src-as-array) below)
 - **`path`** (optional): Path where to place the data (template syntax)
 - **`method`** (optional): HTTP method (GET, POST, etc.)
 - **`dataMapping`** (optional): Configure selective data dispatch using mapping processors
 - **`blocking`** (optional): If `true`, waits for loading before displaying
 
+### Dynamic URLs with `src` as Array
+
+When `src` is an array, each segment is resolved individually and then concatenated into the final URL. Segments starting with `~~.` are treated as references to the store data and are replaced with their resolved values.
+
+This is particularly useful when an RjBuild is loaded inside a `ReactiveJsonSubroot` with `dataOverride`, where dynamic values (like entity IDs) are injected by the parent.
+
+```yaml
+# Parent RjBuild passes taskId via dataOverride
+- type: ReactiveJsonSubroot
+  rjOptions:
+    rjBuildUrl: "/components/TimeLogManager.yaml"
+    dataOverride:
+      taskId: ~.task.id
+```
+
+```yaml
+# TimeLogManager.yaml — uses taskId in additionalDataSource
+additionalDataSource:
+  - src:
+      - "/api/time-logs?filter[task]="
+      - ~~.taskId
+    path: ~~.timeLogs
+    blocking: true
+
+data:
+  taskId: ""       # Will be overridden by dataOverride
+  timeLogs: []
+```
+
+In this example, if `taskId` is `"42"`, the resolved URL will be `/api/time-logs?filter[task]=42`.
+
+**Rules:**
+- Only `~~.` (global/root data) references are supported in `src` segments — `~.` (local template context) is not available during initialization
+- If a `~~.` reference resolves to `null` or `undefined`, it is replaced with an empty string and a warning is logged
+- When `src` is a plain string, it behaves exactly as before (full backward compatibility)
+
 ### Loading Modes
 
 #### Blocking loading

package/public/rjbuild/docs/getting-started/rjbuild-structure.yaml

@@ -305,12 +305,55 @@ renderView:
     content: |
 
       ### Properties
-      - **`src`** (required): URL of the data source
+      - **`src`** (required): URL of the data source. Can be a **string** (used as-is) or an **array of segments** that are resolved and concatenated (see [Dynamic URLs](#dynamic-urls-with-src-as-array) below)
       - **`path`** (optional): Path where to place the data (template syntax)
       - **`method`** (optional): HTTP method (GET, POST, etc.)
       - **`dataMapping`** (optional): Configure selective data dispatch using mapping processors
       - **`blocking`** (optional): If `true`, waits for loading before displaying
 
+      ### Dynamic URLs with `src` as Array
+
+      When `src` is an array, each segment is resolved individually and then concatenated into the final URL. Segments starting with `~~.` are treated as references to the store data and are replaced with their resolved values.
+
+      This is particularly useful when an RjBuild is loaded inside a `ReactiveJsonSubroot` with `dataOverride`, where dynamic values (like entity IDs) are injected by the parent.
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      # Parent RjBuild passes taskId via dataOverride
+      renderView:
+        - type: ReactiveJsonSubroot
+          rjOptions:
+            rjBuildUrl: "/components/TimeLogManager.yaml"
+            dataOverride:
+              taskId: ~.task.id
+
+  - type: Markdown
+    content: |
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      # TimeLogManager.yaml — uses taskId in additionalDataSource
+      additionalDataSource:
+        - src:
+            - "/api/time-logs?filter[task]="
+            - ~~.taskId
+          path: ~~.timeLogs
+          blocking: true
+
+      data:
+        taskId: ""       # Will be overridden by dataOverride
+        timeLogs: []
+
+  - type: Markdown
+    content: |
+
+      In this example, if `taskId` is `"42"`, the resolved URL will be `/api/time-logs?filter[task]=42`.
+
+      **Rules:**
+      - Only `~~.` (global/root data) references are supported in `src` segments — `~.` (local template context) is not available during initialization
+      - If a `~~.` reference resolves to `null` or `undefined`, it is replaced with an empty string and a warning is logged
+      - When `src` is a plain string, it behaves exactly as before (full backward compatibility)
+
       ### Loading Modes
 
       #### Blocking loading