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

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

@@ -0,0 +1,274 @@
+renderView:
+  - type: Markdown
+    content: |
+      # 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, 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"
+      ```
+
+      ### Syncable Object Fields
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: submission_url
+          after: " (string, required)"
+        details:
+          type: Markdown
+          content: "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."
+      - term:
+          code: item_url
+          after: " (string, optional)"
+        details:
+          type: Markdown
+          content: "URL to fetch the latest version of the item (GET). **Not used by `DataSync` itself** — provided as metadata for the backend or other components."
+      - term:
+          code: delete_url
+          after: " (string, optional)"
+        details:
+          type: Markdown
+          content: "URL to delete the item (DELETE). **Not used by `DataSync` itself** — provided as metadata for the backend or other components."
+      - term:
+          code: data
+          after: " (any, required)"
+        details:
+          type: Markdown
+          content: "The actual payload to synchronize. Its structure depends on the backend. **Only changes to this field trigger synchronization.**"
+      - term:
+          code: status
+          after: " (object, optional)"
+        details:
+          - type: Markdown
+            content: "Feedback message from the last operation. Contains:"
+          - type: DefinitionList
+            content:
+              - term:
+                  code: status.type
+                details:
+                  type: Markdown
+                  content: "One of: `success`, `error`, `info`, `warning`."
+              - term:
+                  code: status.message
+                details: "Human-readable message describing the result."
+
+  - type: Markdown
+    content: |
+      ### How `status` is managed
+
+      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 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.
+
+      ## Component Properties
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      - type: DataSync
+        path: ~~.mySyncableObject
+        mode: onIdle
+        idleDelay: 2000
+        trigger: ~~.saveNow
+        maxRetries: 0
+        retryDelay: 5000
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: path
+          after: " (string, required)"
+        details:
+          type: Markdown
+          content: "Path to the Syncable Object to watch. Supports template paths (`~~.`, `~.`, `~>`)."
+      - term:
+          code: mode
+          after: " (string, optional)"
+        details:
+          type: Markdown
+          content: "Synchronization mode. Default: `\"onIdle\"`. Options: `\"onIdle\"`, `\"immediate\"`, `\"manual\"`."
+      - term:
+          code: idleDelay
+          after: " (number, optional)"
+        details:
+          type: Markdown
+          content: "Milliseconds of inactivity before syncing. Only used in `onIdle` mode. Default: `1000`."
+      - term:
+          code: trigger
+          after: " (string, optional)"
+        details:
+          type: Markdown
+          content: "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."
+      - term:
+          code: maxRetries
+          after: " (number, optional)"
+        details:
+          type: Markdown
+          content: "Number of additional retry attempts after a failed sync. `0` means one attempt with no retry. Default: `0`."
+      - term:
+          code: retryDelay
+          after: " (number, optional)"
+        details:
+          type: Markdown
+          content: "Milliseconds between retry attempts. Default: `5000`."
+
+  - type: Markdown
+    content: |
+      ## 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
+
+      ### What triggers retries
+      - **Network outages** (browser is offline) — retried.
+      - **Server errors** (HTTP 5xx) — retried.
+      - **Client errors** (HTTP 4xx) — **not retried**.
+      - **CORS failures** — **not retried**.
+
+      When the user makes a new data change, the retry counter resets and a fresh sync cycle begins.
+
+      ### Configuration example
+      ```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 the status or when the server response updates the object.
+
+      ## 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 user feedback:
+
+      ```yaml
+      - type: div
+        content: ~~.userProfile.status.message
+        actions:
+          - what: hide
+            when: ~~.userProfile.status
+            is: undefined
+      ```
+
+      ## 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).

package/public/rjbuild/docs/core/example/DataFilter-example-direct-array.md

@@ -1,211 +0,0 @@
-# DataFilter Example: Filtering Direct Array Items
-
-This example demonstrates how to use `DataFilter` with arrays where each item is a direct object (not wrapped in a namespace property). This is useful when working with data from APIs that return arrays of objects directly.
-
-## Use Case
-
-When your data structure is a direct array of objects like:
-```yaml
-data:
-  rows:
-    - id: 1
-      label: "Operation 1"
-      done: "done"
-      operation: "create"
-    - id: 2
-      label: "Operation 2"
-      done: "pending"
-      operation: "update"
-```
-
-Instead of:
-```yaml
-data:
-  rows:
-    - item:
-        id: 1
-        label: "Operation 1"
-```
-
-## Solution
-
-Use an existing property that is present in all items (like `id`) as the `subjectsWithProperty` namespace. In `whenFilterableData`, reference properties directly without the namespace prefix.
-
-**Important**: When using string values for filtering (like status), use a special value like `"all"` to represent "no filter" instead of an empty string, as empty strings can cause issues with select elements.
-
-## Complete Example
-
-```yaml
-renderView:
-  - type: DataFilter
-    context: global
-    filters:
-      - subjectsWithProperty: id
-        andConditions:
-          # Filter by status (string)
-          - orConditions:
-              - when: ~~._filters.done
-                is: "all"
-              - whenFilterableData: done
-                is: ~~._filters.done
-          
-          # Filter by operation type (text search with contains)
-          - orConditions:
-              - when: ~~._filters.operation
-                is: ""
-              - andConditions:
-                  - whenFilterableData: operation
-                    isNotEmpty: true
-                  - when: ~~._filters.operation
-                    isNotEmpty: true
-                  - whenFilterableData: operation
-                    contains: ~~._filters.operation
-          
-          # Filter by label (text search with contains)
-          - orConditions:
-              - when: ~~._filters.label
-                is: ""
-              - andConditions:
-                  - whenFilterableData: label
-                    isNotEmpty: true
-                  - when: ~~._filters.label
-                    isNotEmpty: true
-                  - whenFilterableData: label
-                    contains: ~~._filters.label
-    content:
-      - type: Switch
-        content: ~~.rows
-        singleOption:
-          load: operationRow
-
-templates:
-  operationRow:
-    - type: tr
-      content:
-        - type: td
-          content: ~.id
-        - type: td
-          content: ~.label
-        - type: td
-          content: ~.done
-        - type: td
-          content: ~.operation
-
-data:
-  rows:
-    - id: 1
-      label: "Operation 1"
-      done: "done"
-      operation: "create"
-    - id: 2
-      label: "Operation 2"
-      done: "pending"
-      operation: "update"
-    - id: 3
-      label: "Operation 3"
-      done: "done"
-      operation: "create"
-  _filters:
-    done: "all"
-    label: ""
-    operation: ""
-```
-
-## Key Points
-
-1. **Namespace Selection**: Choose a property that exists in all items (e.g., `id`, `name`, `key`). This property acts as the identifier for DataFilter to recognize filterable items.
-
-2. **Direct Property Access**: In `whenFilterableData`, reference properties directly:
-   - ✅ `whenFilterableData: label` (correct)
-   - ❌ `whenFilterableData: id.label` (incorrect - don't use namespace prefix)
-
-3. **String-based Filtering**: When using select elements for filtering, use a special value like `"all"` to represent "no filter" instead of an empty string:
-   ```yaml
-   - orConditions:
-       - when: ~~._filters.done
-         is: "all"  # Shows all items
-       - whenFilterableData: done
-         is: ~~._filters.done  # Filters by exact match
-   ```
-   This avoids issues where select elements might not properly handle empty string values.
-
-4. **Text Search**: For text search with `contains`, ensure both the filter value and the data property are not empty:
-   ```yaml
-   - orConditions:
-       - when: ~~._filters.label
-         is: ""  # Shows all when empty
-       - andConditions:
-           - whenFilterableData: label
-             isNotEmpty: true
-           - when: ~~._filters.label
-             isNotEmpty: true
-           - whenFilterableData: label
-             contains: ~~._filters.label
-   ```
-   The `andConditions` wrapper ensures that both the data property and filter value are not empty before attempting the `contains` comparison.
-
-5. **Template Access**: In templates, access properties directly without namespace:
-   - ✅ `~.label`, `~.done`, `~.operation`
-   - ❌ `~.id.label` (incorrect)
-
-## Filter Types Demonstrated
-
-- **Select Filter with "All" option**: Using `is: "all"` to show all items when a special "all" value is selected
-- **Exact String Match**: Using `is` for exact string matching (e.g., status filtering)
-- **Text Search**: Using `contains` for substring matching (case-insensitive) with proper empty checks
-
-## Additional Template Techniques
-
-**Conditional Display in Templates**: The example uses `hide` actions to conditionally display badges based on data values. This is a common pattern for showing different UI elements based on data state:
-
-```yaml
-- type: span
-  content: "Done"
-  actions:
-    - what: hide
-      when: ~.done
-      isNot: "done"  # Hide if status is not "done"
-- type: span
-  content: "Pending"
-  actions:
-    - what: hide
-      when: ~.done
-      isNot: "pending"  # Hide if status is not "pending"
-```
-
-This technique is used in the example to display colored status badges, but it's not part of the DataFilter pattern itself - it's just a way to enhance the visual display of filtered data.
-
-## Filter Patterns
-
-### Pattern 1: Select Filter with "All" Option
-```yaml
-- orConditions:
-    - when: ~~._filters.status
-      is: "all"  # Special value for "show all"
-    - whenFilterableData: status
-      is: ~~._filters.status  # Exact match filter
-```
-
-### Pattern 2: Text Input Filter (Empty String Check)
-```yaml
-- orConditions:
-    - when: ~~._filters.search
-      is: ""  # Empty string means "show all"
-    - andConditions:
-        - whenFilterableData: searchField
-          isNotEmpty: true
-        - when: ~~._filters.search
-          isNotEmpty: true
-        - whenFilterableData: searchField
-          contains: ~~._filters.search
-```
-
-## Notes
-
-- The `subjectsWithProperty` value (`id` in this example) must exist in every item of the array
-- DataFilter filters the data before rendering, so no `hide` actions are needed in templates
-- All filter conditions use `orConditions` with an empty/"all" check first, allowing "show all" when filters are empty or set to "all"
-- For select elements, prefer using a special value like `"all"` instead of empty strings to avoid UI issues
-- For text inputs, empty strings (`""`) work fine for the "show all" condition
-- When using `contains` for text search, always wrap the condition in `andConditions` with `isNotEmpty` checks to avoid errors with empty values
-