@ea-lab/reactive-json-docs 1.4.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ea-lab/reactive-json-docs",
-  "version": "1.4.0",
+  "version": "2.0.0",
   "description": "Complete documentation for Reactive-JSON - Components, examples and LLM-parsable guides",
   "main": "public/rjbuild/docs/index.yaml",
   "files": [
@@ -26,7 +26,7 @@
   "private": false,
   "devDependencies": {
     "@craco/craco": "^7.1.0",
-    "@ea-lab/reactive-json": "^1.3.0",
+    "@ea-lab/reactive-json": "^1.2.0",
     "@ea-lab/reactive-json-chartjs": "^1.0.0",
     "@npmcli/fs": "^4.0.0",
     "@reduxjs/toolkit": "^2.6.1",

package/public/rjbuild/docs/core/attributeTransformer/setAttributeValue.md

@@ -8,73 +8,42 @@ Dynamically sets or modifies the value of an HTML attribute before rendering. Th
 
 ```yaml
 attributeTransforms:
-  # Add CSS class (string mode)
+  # Add CSS class
   - what: setAttributeValue
     name: "class"
     value: "active"
     
-  # Replace attribute value (string mode)
+  # Replace attribute value
   - what: setAttributeValue
     name: "data-status"
     mode: "replace"
     value: ~.currentStatus
-    
-  # Merge style object (object mode)
-  - what: setAttributeValue
-    name: "style"
-    value:
-      borderColor: "#3b82f6"
-      backgroundColor: "#ffffff"
 ```
 
 ## Properties
 
 - **name** *(string, required)*: The name of the attribute to modify.
 - **mode** *(string, optional)*: The modification mode. Default: `"append"`.
-  - `"append"`: Adds the value to the existing attribute value (space-separated for strings, merges properties for objects).
+  - `"append"`: Adds the value to the existing attribute value (space-separated).
   - `"replace"`: Completely replaces the existing attribute value.
-- **value** *(string | object, required)*: The value to set or append. Supports template evaluation (e.g., `~.dynamicValue`, `~~.globalValue`).
-  - **String mode**: When `value` is a string, operates in string mode for simple attributes like `class`, `data-*`, etc.
-  - **Object mode**: When `value` is an object, operates in object mode for complex attributes like `style`. In append mode, merges properties property by property.
-- **preventDuplicateValues** *(boolean, optional)*: When `true` (default), prevents duplicate values when using append mode (applies to string mode and string properties in object mode).
-- **separator** *(string, optional)*: The separator used between values in string mode. Default: `" "` (space).
+- **value** *(string, required)*: The value to set or append. Supports template evaluation (e.g., `~.dynamicValue`, `~~.globalValue`). Automatically converted to string if not already. Special characters are handled safely.
+- **preventDuplicateValues** *(boolean, optional)*: When `true` (default), prevents duplicate values when using append mode.
+- **separator** *(string, optional)*: The separator used between values. Default: `" "` (space).
 
 ## Behavior
 
-The transformer operates in two distinct modes based on the `value` type:
-
-### String Mode (when `value` is a string)
-
 - **Append mode**: Adds the new value to the existing attribute, separated by the specified separator.
 - **Replace mode**: Completely overwrites the existing attribute value.
 - **Duplicate prevention**: In append mode, prevents adding duplicate values when enabled.
 
-### Object Mode (when `value` is an object)
-
-- **Replace mode**: Completely replaces the entire object attribute.
-- **Append mode**: Merges properties property by property:
-  - Starts from the current object attribute
-  - For each property in `value`, applies the same logic as string mode:
-    - If both current and new values are strings: appends them (respecting `preventDuplicateValues`)
-    - Otherwise: replaces the property with the new value (new value has precedence)
-  - Handles nested objects recursively
-  - Works on a copy to avoid mutation issues
-
-### Undefined Values
-
-- **Append mode**: `undefined` values are ignored, keeping the current attribute unchanged.
-- **Replace mode**: `undefined` is assigned to the attribute.
-
 ## Common Use Cases
 
-- **Dynamic CSS classes**: Adding/removing CSS classes based on state (string mode).
-- **Data attributes**: Setting data-* attributes for JavaScript integration (string mode).
-- **ARIA attributes**: Dynamically updating accessibility attributes (string mode).
-- **Style attributes**: Modifying inline styles conditionally (object mode). Merge style properties without losing existing ones.
-
-## Examples
+- **Dynamic CSS classes**: Adding/removing CSS classes based on state.
+- **Data attributes**: Setting data-* attributes for JavaScript integration.
+- **ARIA attributes**: Dynamically updating accessibility attributes.
+- **Style attributes**: Modifying inline styles conditionally.
 
-### String Mode Example
+## Example
 
 ```yaml
 renderView:
@@ -122,73 +91,11 @@ data:
   input_data: ""
 ```
 
-### Object Mode Example (Style Merging)
-
-```yaml
-renderView:
-  - type: div
-    attributes:
-      style:
-        padding: "10px"
-        border: "2px solid #007bff"
-        borderRadius: "4px"
-    attributeTransforms:
-      # Merge additional style properties without losing existing ones
-      - what: setAttributeValue
-        name: "style"
-        value:
-          borderColor: "#3b82f6"
-          backgroundColor: "#f0f0f0"
-        when: ~.isHighlighted
-        is: true
-    # Result when isHighlighted is true:
-    # style: {
-    #   padding: "10px",
-    #   border: "2px solid #007bff",
-    #   borderRadius: "4px",
-    #   borderColor: "#3b82f6",
-    #   backgroundColor: "#f0f0f0"
-    # }
-
-data:
-  isHighlighted: false
-```
-
-### Object Mode Replace Example
-
-```yaml
-renderView:
-  - type: div
-    attributes:
-      style:
-        padding: "10px"
-        border: "2px solid #007bff"
-    attributeTransforms:
-      # Completely replace the style object
-      - what: setAttributeValue
-        name: "style"
-        mode: "replace"
-        value:
-          backgroundColor: "#ffffff"
-          color: "#000000"
-    # Result:
-    # style: {
-    #   backgroundColor: "#ffffff",
-    #   color: "#000000"
-    # }
-    # (original padding and border are lost)
-```
-
 ## Notes
 
 - **Pre-render execution**: This transformer modifies attributes before the component renders, ensuring child components receive the transformed attributes.
-- **Mode detection**: The transformer automatically detects whether to use string mode or object mode based on the `value` type after template evaluation.
-- **Append mode behavior**: 
-  - **String mode**: Respects existing attribute values, adding new values separated by the specified separator.
-  - **Object mode**: Merges properties property by property, applying string append logic where both values are strings, otherwise replacing with the new value.
-- **Replace mode**: Use when you need complete control over the attribute value. In object mode, completely replaces the entire object.
-- **Duplicate prevention**: Only applies to append mode, and works for string values in both string mode and object mode.
-- **Object merging**: In object mode append, nested objects are merged recursively. Properties that don't match the expected format for append are replaced (new value has precedence).
+- **Append mode behavior**: Respects existing attribute values when using append mode.
+- **Replace mode**: Use when you need complete control over the attribute value.
+- **Duplicate prevention**: Only applies to append mode.
 - **Template evaluation**: The value property supports full template evaluation including `~.localData`, `~~.globalData`, `~>nearestKey`, and `~~>globalKey` patterns.
 - **Conditional execution**: Supports the same condition system as actions (`when`, `is`, `isEmpty`, `isNotEmpty`, etc.).
-- **Undefined handling**: `undefined` values are ignored in append mode but assigned in replace mode.

package/public/rjbuild/docs/core/attributeTransformer/setAttributeValue.yaml

@@ -12,23 +12,16 @@ renderView:
   - type: TabbedSerializer
     yamlSerializedContent: |
       attributeTransforms:
-        # Add CSS class (string mode)
+        # Add CSS class
         - what: setAttributeValue
           name: "class"
           value: "active"
           
-        # Replace attribute value (string mode)
+        # Replace attribute value
         - what: setAttributeValue
           name: "data-status"
           mode: "replace"
           value: ~.currentStatus
-          
-        # Merge style object (object mode)
-        - what: setAttributeValue
-          name: "style"
-          value:
-            borderColor: "#3b82f6"
-            backgroundColor: "#ffffff"
 
   - type: Markdown
     content: |
@@ -51,14 +44,8 @@ renderView:
             - `"replace"`: Completely replaces the existing attribute value
       - term:
           code: value
-          after: "(string | object, required)"
-        details:
-          type: Markdown
-          content: |
-            The value to set or append. Supports template evaluation (e.g., `~.dynamicValue`, `~~.globalValue`).
-            
-            - **String mode**: When `value` is a string, operates in string mode for simple attributes like `class`, `data-*`, etc.
-            - **Object mode**: When `value` is an object, operates in object mode for complex attributes like `style`. In append mode, merges properties property by property.
+          after: "(string, required)"
+        details: The value to set or append. Supports template evaluation (e.g., `~.dynamicValue`, `~~.globalValue`). Automatically converted to string if not already. Special characters are handled safely.
       - term:
           code: preventDuplicateValues
           after: "(boolean, optional)"
@@ -78,36 +65,16 @@ renderView:
 
       ## Behavior
 
-      The transformer operates in two distinct modes based on the `value` type:
-
-      ### String Mode (when `value` is a string)
-
       - **Append mode**: Adds the new value to the existing attribute, separated by the specified separator.
       - **Replace mode**: Completely overwrites the existing attribute value.
       - **Duplicate prevention**: In append mode, prevents adding duplicate values when enabled.
 
-      ### Object Mode (when `value` is an object)
-
-      - **Replace mode**: Completely replaces the entire object attribute.
-      - **Append mode**: Merges properties property by property:
-        - Starts from the current object attribute
-        - For each property in `value`, applies the same logic as string mode:
-          - If both current and new values are strings: appends them (respecting `preventDuplicateValues`)
-          - Otherwise: replaces the property with the new value (new value has precedence)
-        - Handles nested objects recursively
-        - Works on a copy to avoid mutation issues
-
-      ### Undefined Values
-
-      - **Append mode**: `undefined` values are ignored, keeping the current attribute unchanged.
-      - **Replace mode**: `undefined` is assigned to the attribute.
-
       ## Common Use Cases
 
-      - **Dynamic CSS classes**: Adding/removing CSS classes based on state (string mode).
-      - **Data attributes**: Setting data-* attributes for JavaScript integration (string mode).
-      - **ARIA attributes**: Dynamically updating accessibility attributes (string mode).
-      - **Style attributes**: Modifying inline styles conditionally (object mode). Merge style properties without losing existing ones.
+      - **Dynamic CSS classes**: Adding/removing CSS classes based on state.
+      - **Data attributes**: Setting data-* attributes for JavaScript integration.
+      - **ARIA attributes**: Dynamically updating accessibility attributes.
+      - **Style attributes**: Modifying inline styles conditionally.
 
   - type: RjBuildDescriber
     title: "SetAttributeValue Action Examples"
@@ -167,90 +134,11 @@ renderView:
       data:
         input_data: ""
 
-  - type: RjBuildDescriber
-    title: "Object Mode Example - Style Merging"
-    description:
-      - type: Markdown
-        content: |
-          This example demonstrates how to use `setAttributeValue` in object mode to merge style properties without losing existing ones.
-          
-          **Expected behavior:**
-          - The div has initial styles (padding, border, borderRadius)
-          - When `isHighlighted` is true, additional style properties are merged
-          - The original styles are preserved, and new properties are added
-          - Try toggling the highlight to see the style merge in action
-
-    toDescribe:
-      renderView:
-        - type: div
-          attributes:
-            style:
-              padding: "10px"
-              border: "2px solid #007bff"
-              borderRadius: "4px"
-          attributeTransforms:
-            # Merge additional style properties without losing existing ones
-            - what: setAttributeValue
-              name: "style"
-              value:
-                borderColor: "#3b82f6"
-                backgroundColor: "#f0f0f0"
-              when: ~.isHighlighted
-              is: true
-          content: "Click to toggle highlight"
-
-        - type: button
-          content: "Toggle Highlight"
-          actions:
-            - what: setData
-              on: click
-              path: ~.isHighlighted
-              value: <reactive-json:not>~~.isHighlighted</reactive-json:not>
-
-      data:
-        isHighlighted: false
-
-  - type: RjBuildDescriber
-    title: "Object Mode Replace Example"
-    description:
-      - type: Markdown
-        content: |
-          This example demonstrates how to completely replace a style object using `mode: "replace"`.
-          
-          **Expected behavior:**
-          - The div has initial styles (padding, border)
-          - When replace mode is used, the entire style object is replaced
-          - Original styles are lost, only the new styles remain
-
-    toDescribe:
-      renderView:
-        - type: div
-          attributes:
-            style:
-              padding: "10px"
-              border: "2px solid #007bff"
-          attributeTransforms:
-            # Completely replace the style object
-            - what: setAttributeValue
-              name: "style"
-              mode: "replace"
-              value:
-                backgroundColor: "#ffffff"
-                color: "#000000"
-          content: "This div's style was completely replaced"
-
   - type: Markdown
     content: |
       ## Notes
 
-      - **Pre-render execution**: This transformer modifies attributes before the component renders, ensuring child components receive the transformed attributes.
-      - **Mode detection**: The transformer automatically detects whether to use string mode or object mode based on the `value` type after template evaluation.
-      - **Append mode behavior**: 
-        - **String mode**: Respects existing attribute values, adding new values separated by the specified separator.
-        - **Object mode**: Merges properties property by property, applying string append logic where both values are strings, otherwise replacing with the new value.
-      - **Replace mode**: Use when you need complete control over the attribute value. In object mode, completely replaces the entire object.
-      - **Duplicate prevention**: Only applies to append mode, and works for string values in both string mode and object mode.
-      - **Object merging**: In object mode append, nested objects are merged recursively. Properties that don't match the expected format for append are replaced (new value has precedence).
-      - **Template evaluation**: The value property supports full template evaluation including `~.localData`, `~~.globalData`, `~>nearestKey`, and `~~>globalKey` patterns.
-      - **Conditional execution**: Supports the same condition system as actions (`when`, `is`, `isEmpty`, `isNotEmpty`, etc.).
-      - **Undefined handling**: `undefined` values are ignored in append mode but assigned in replace mode.
+      - The action respects existing attribute values when using append mode.
+      - Use replace mode when you need complete control over the attribute value.
+      - Duplicate prevention only applies to append mode.
+      - The value property supports full template evaluation including `~.localData`, `~~.globalData`, `~>nearestKey`, and `~~>globalKey` patterns.

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

@@ -0,0 +1,252 @@
+# DataSync
+
+The `DataSync` component enables automatic synchronization between client-side data and a backend endpoint. It watches a **Syncable Object** in the data tree and pushes changes to a server when triggered, either automatically after a period of inactivity, immediately on change, or manually via an explicit trigger.
+
+This component does not render any visible UI. It acts as a background observer.
+
+## The Syncable Object
+
+`DataSync` watches a data object that follows a specific structure called a **Syncable Object**. This object contains both the data to synchronize and the configuration needed to reach the backend.
+
+### Structure
+
+```yaml
+mySyncableObject:
+  submission_url: "https://api.example.com/items/save"
+  item_url: "https://api.example.com/items/123"
+  delete_url: "https://api.example.com/items/123"
+  data:
+    entity_id: 123
+    name: "John Doe"
+    email: "john@example.com"
+  status:
+    type: "info"
+    message: "Ready"
+```
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `submission_url` | string | Yes | URL where the object is sent for create/update (POST). This is the only URL used by the `DataSync` component. If `entity_id` is absent from `data`, the backend should treat it as a creation. |
+| `item_url` | string | No | URL to fetch the latest version of the item (GET). **Not used by `DataSync` itself** — provided as metadata for the backend or other components. |
+| `delete_url` | string | No | URL to delete the item (DELETE). **Not used by `DataSync` itself** — provided as metadata for the backend or other components. |
+| `data` | any | Yes | The actual payload to synchronize. Its structure depends on the backend. Only changes to this field trigger synchronization. |
+| `status` | object | No | Feedback message from the last operation. Contains `type` and `message`. |
+
+### The `status` field
+
+The `status` field follows a standard structure with two properties:
+
+| Property | Type | Description |
+|---|---|---|
+| `type` | string | One of: `success`, `error`, `info`, `warning`. |
+| `message` | string | Human-readable message describing the result. |
+
+The `status` field is managed in three ways:
+1. **By the component**: Set to `{ type: "info", message: "Synchronisation en cours..." }` while a request is in flight.
+2. **By the backend**: The server response replaces the entire Syncable Object, including the `status` field. The backend can set it to `success`, `error`, or any type with a relevant message.
+3. **On HTTP failure**: If the request fails (network error, 5xx), the component generates `{ type: "error", message: "..." }` locally.
+
+### Backend contract
+
+When `DataSync` sends a request, it POSTs the **entire Syncable Object** (not just `data`) to `submission_url`. The backend must return the same Syncable Object structure in its response, potentially with:
+- Modified `data` (e.g., server-generated fields like `entity_id` or timestamps).
+- An updated `status` field reflecting the result of the operation.
+
+The response completely replaces the local Syncable Object.
+
+## Properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `path` | string | (required) | Path to the Syncable Object to watch. Supports template paths (`~~.`, `~.`, `~>`). |
+| `mode` | string | `"onIdle"` | Synchronization mode: `"onIdle"`, `"immediate"`, or `"manual"`. |
+| `idleDelay` | number | `1000` | Milliseconds of inactivity before syncing (only used in `onIdle` mode). |
+| `trigger` | string | - | Path to a boolean value. When set to `true`, triggers an immediate sync and resets to `false`. Works in any mode. In `onIdle` mode, it cancels the pending idle timer. |
+| `maxRetries` | number | `0` | Number of additional retry attempts after a failed sync. `0` means one attempt with no retry. |
+| `retryDelay` | number | `5000` | Milliseconds between retry attempts. |
+
+## Synchronization Modes
+
+### `onIdle` (default)
+Waits for the user to stop modifying data. Each change resets the idle timer. The sync fires only after `idleDelay` milliseconds of inactivity.
+
+```yaml
+- type: DataSync
+  path: ~~.userProfile
+  mode: onIdle
+  idleDelay: 2000
+```
+
+### `immediate`
+Syncs immediately on every data change. Use with caution -- this can generate a high volume of requests.
+
+```yaml
+- type: DataSync
+  path: ~~.settings
+  mode: immediate
+```
+
+### `manual`
+Does not sync on data changes. Waits for the `trigger` path to become `true`.
+
+```yaml
+- type: DataSync
+  path: ~~.formData
+  mode: manual
+  trigger: ~~.saveNow
+```
+
+## Manual Trigger
+
+The `trigger` property works in **any mode**, not just `manual`. When the trigger path is set to `true`:
+
+1. The trigger is immediately reset to `false`.
+2. Any pending idle timer is cancelled (in `onIdle` mode).
+3. A sync is performed immediately.
+
+This is useful for adding a "Save Now" button alongside auto-save:
+
+```yaml
+- type: button
+  content: "Save Now"
+  actions:
+    - what: setData
+      on: click
+      path: ~~.saveNow
+      value: true
+
+- type: DataSync
+  path: ~~.userProfile
+  mode: onIdle
+  idleDelay: 2000
+  trigger: ~~.saveNow
+```
+
+## Error Handling and Retries
+
+### Retry behavior
+- Only **network outages** (browser is offline) and **server errors** (HTTP 5xx) trigger retries.
+- Client errors (4xx) and CORS failures do **not** trigger retries.
+- When the user makes a new data change, the retry counter resets and a fresh sync cycle begins.
+
+### Configuration
+```yaml
+- type: DataSync
+  path: ~~.userProfile
+  mode: onIdle
+  idleDelay: 1000
+  maxRetries: 3
+  retryDelay: 10000
+```
+
+## Change Detection
+
+`DataSync` only triggers synchronization when the `data` field of the Syncable Object changes. Changes to `status`, `submission_url`, or other fields are ignored.
+
+This prevents feedback loops: when the component updates `status` to "syncing" or when the server response updates `status` to "success", these changes do not trigger a new sync cycle.
+
+## Using with Templates
+
+`DataSync` supports `TemplateContext`, so it can be used inside templates to sync individual items in a list:
+
+```yaml
+data:
+  items:
+    - submission_url: "/api/items/1"
+      data: { name: "Item 1" }
+    - submission_url: "/api/items/2"
+      data: { name: "Item 2" }
+
+templates:
+  itemRow:
+    type: div
+    content:
+      - type: TextField
+        dataLocation: ~.data.name
+      - type: DataSync
+        path: ~
+        mode: onIdle
+        idleDelay: 1500
+
+renderView:
+  - type: Switch
+    content: ~~.items
+    singleOption:
+      load: itemRow
+```
+
+## Displaying Status
+
+You can display the status message from the Syncable Object to provide feedback to the user:
+
+```yaml
+- type: div
+  content: ~~.userProfile.status.message
+  actions:
+    - what: hide
+      when: ~~.userProfile.status
+      is: undefined
+```
+
+## Complete Example
+
+```yaml
+data:
+  userProfile:
+    submission_url: "/api/user/save"
+    item_url: "/api/user/123"
+    delete_url: "/api/user/123"
+    data:
+      name: "John Doe"
+      email: "john@example.com"
+    status:
+      type: "info"
+      message: "Ready"
+  saveNow: false
+
+renderView:
+  - type: div
+    content:
+      # Status display
+      - type: div
+        content: ~~.userProfile.status.message
+        actions:
+          - what: hide
+            when: ~~.userProfile.status
+            is: undefined
+
+      # Form fields
+      - type: TextField
+        label: "Name"
+        dataLocation: ~~.userProfile.data.name
+
+      - type: TextField
+        label: "Email"
+        dataLocation: ~~.userProfile.data.email
+
+      # Manual save button
+      - type: button
+        content: "Save Now"
+        actions:
+          - what: setData
+            on: click
+            path: ~~.saveNow
+            value: true
+
+      # DataSync: auto-saves after 2s of idle, manual trigger available
+      - type: DataSync
+        path: ~~.userProfile
+        mode: onIdle
+        idleDelay: 2000
+        trigger: ~~.saveNow
+```
+
+## Limitations
+- Only one sync can be active at a time per `DataSync` instance. Concurrent changes while a sync is in flight are not queued.
+- The entire Syncable Object is sent in the POST body, not just the `data` field.
+- Only POST requests are supported for submission. Custom HTTP methods are not configurable.
+- `item_url` and `delete_url` are part of the Syncable Object structure but are not used by the component itself. They are available for the backend or for other components to use.
+- No built-in support for optimistic updates. The local data is replaced by the server response.
+- CORS errors are not retried (they are indistinguishable from network errors when the browser is online).