@ea-lab/reactive-json-docs 0.1.11 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ea-lab/reactive-json-docs",
-  "version": "0.1.11",
+  "version": "0.2.1",
   "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": "^0.0.45",
+    "@ea-lab/reactive-json": "^0.1.0",
     "@ea-lab/reactive-json-chartjs": "^0.0.23",
     "@npmcli/fs": "^4.0.0",
     "@reduxjs/toolkit": "^2.6.1",

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

@@ -4,17 +4,133 @@
 
 The `ReactiveJsonSubroot` component allows you to render a new Reactive-JSON root inside an existing application. It is useful for embedding a sub-application, isolating a part of the data tree, or rendering a separate rjbuild with its own options.
 
+With the `sharedUpdates` feature, the component can also propagate data changes back to the parent, enabling seamless communication between parent and subroot when working with shared data references.
+
 ## Properties
-- `rjOptions` (object, required): Options to pass to the subroot (such as `rjBuildUrl`, `data`, `renderView`, etc.)
-- Other properties are passed to the underlying `ReactiveJsonRoot`
+- `rjOptions` (object, required): Options to pass to the subroot - accepts **all** `ReactiveJsonRoot` properties including:
+  - `rjBuildUrl`: URL to load the RjBuild from.
+  - `rjBuildFetchMethod`: HTTP method ("GET" or "POST").
+  - `headersForRjBuild`: Headers for the request.
+  - `dataOverride`: Override data for the loaded/defined RjBuild.
+  - `maybeRawAppRjBuild`: Inline RjBuild content (string or object) containing:
+    - `renderView`: View definition.
+    - `templates`: Template definitions.
+    - `data`: Initial data.
+  - `debugMode`: Enable debug mode and related wrapper components.
+- `sharedUpdates` (boolean, optional): Enable upstream data propagation to parent (default: false).
+- `dataOverrideEvaluationDepth` (number, optional): Special evaluation depth for dataOverride property.
+- `actions` (array, optional): Action components to apply (passed to `ActionDependant` wrapper).
+- Other standard component properties (e.g., `attributes`) are passed to the `ActionDependant` wrapper.
 
 ## Behavior
-- Renders a new `ReactiveJsonRoot` with the provided options
-- The subroot is isolated from the parent for data, templates, and rendering
-- Plugins from the parent are reused in the subroot
-- If `rjOptions` is not a valid object, nothing is rendered
+- Renders a new `ReactiveJsonRoot` with the provided options.
+- The subroot is typically isolated from the parent for data, templates, and rendering*.
+- Plugins from the parent are automatically reused in the subroot.
+- All properties in `rjOptions` are evaluated with template values using `evaluateTemplateValueCollection()`.
+- If `rjOptions` is not a valid object, nothing is rendered.
+
+*_Note: Data isolation is bypassed when `sharedUpdates: true` is enabled, allowing the subroot to propagate data changes back to the parent. Templates and rendering contexts remain isolated._
+
+## Shared Updates Feature
+
+When `sharedUpdates: true` is enabled, the component automatically detects template references in `dataOverride` and creates update callbacks to propagate changes back to the parent.
+
+**Data flow**: Parent data flows to subroot via `dataOverride` → Subroot changes flow back to parent via `sharedUpdates`
+
+### How it works
+1. **Automatic analysis**: The system analyzes `dataOverride` to detect references (`~~.`, `~.`, `~>`) to parent data
+2. **Callback creation**: For each detected reference, an update callback is created
+3. **Update interception**: When the subroot modifies data, the system checks if it corresponds to a parent reference
+4. **Propagation**: If so, the update is propagated to the parent instead of being applied locally
+
+**Important**: Only data changes are shared. Templates, rendering contexts, and component state remain isolated between parent and subroot.
+
+### Advantages
+1. **Automatic synchronization**: Data remains consistent between parent and subroot
+2. **Simplicity**: No need to manually manage update callbacks
+3. **Performance**: Avoids unnecessary re-renders by propagating directly to the right level
+4. **Flexibility**: Supports different referencing patterns (~~., ~., ~>) and arrays containing references
+
+### Supported reference types
+- `~~.parentData` - Global data references.
+- `~.localData` - Local template context references.
+- `~>key.data` - Hierarchical references.
+- Arrays and nested objects containing references.
+
+### Supported vs Unsupported Cases
+
+#### ✅ Supported cases
+
+##### 1. Direct reference
+```yaml
+dataOverride: ~~.user
+# Modifications in the subroot propagate to "user" in the parent
+```
+
+##### 2. Object mapping with references
+```yaml
+dataOverride:
+  userInfo: ~~.user
+  settings: ~~.config
+# Modifications to "userInfo" propagate to "user" in the parent
+# Modifications to "settings" propagate to "config" in the parent
+```
+
+##### 3. Local references
+```yaml
+dataOverride: ~.localData
+# Modifications propagate to the local template context
+```
+
+##### 4. Hierarchical references
+```yaml
+dataOverride: ~>key.someData
+# Modifications propagate up the template hierarchy
+```
+
+##### 5. Arrays in dataOverride
+```yaml
+dataOverride:
+  - ~~.firstItem
+  - ~~.secondItem
+# Array items with template references are properly handled
+```
+
+#### ❌ Unsupported cases
+
+##### Nested references in data
+```yaml
+dataOverride:
+  someProperty: ~~.user
+data:
+  someProperty: ~~.anotherProperty  # Not supported
+```
+
+### Configuration example
+```yaml
+- type: ReactiveJsonSubroot
+  sharedUpdates: true  # Enable propagation.
+  rjOptions:
+    # Option 1: Load from URL with data override.
+    rjBuildUrl: "/api/user-form.yaml"
+    dataOverride: ~~.user
+    headersForRjBuild:
+      Authorization: ~~.authToken
+    
+    # Option 2: Inline definition.
+    # dataOverride: ~~.user
+    # maybeRawAppRjBuild:
+    #   renderView:
+    #     form:
+    #       - type: TextField
+    #         dataLocation: ~.name
+```
+
+## Examples
+
+### Basic subroot from URL
+This example demonstrates the simplest use case: loading and rendering a separate RjBuild file as an isolated subroot. No data sharing occurs between parent and subroot.
 
-## Example
 ```yaml
 renderView:
   - type: ReactiveJsonSubroot
@@ -22,6 +138,185 @@ renderView:
       rjBuildUrl: "/rjs-build/home.yaml"
 ```
 
+### Inline definition with shared updates
+This example shows how to create an editable form where changes in the subroot automatically update the parent display. The key feature here is `sharedUpdates: true` which enables data synchronization between the form fields and the parent data display.
+
+```yaml
+data:
+  user:
+    name: "John"
+    email: "john@example.com"
+
+renderView:
+  userDisplay:
+    - type: p
+      content: ["Name: ", ~~.user.name]  # This displays the current user name.
+  
+  editForm:
+    - type: ReactiveJsonSubroot
+      sharedUpdates: true  # Required to update userDisplay when form changes.
+      rjOptions:
+        dataOverride: ~~.user
+        maybeRawAppRjBuild:
+          renderView:
+            form:
+                          - type: TextField
+              label: "Name" 
+              dataLocation: ~.name  # Changes propagate to ~~.user.name.
+            - type: TextField
+              label: "Email"
+              dataLocation: ~.email  # Changes propagate to ~~.user.email.
+```
+
+### Multi-section configuration
+This example demonstrates how to map different parts of the parent data to different sections within the subroot. The `dataOverride` object creates custom mappings (`userProfile` and `userSettings`) that allow the subroot to work with reorganized data while still propagating changes back to their original locations in the parent.
+
+```yaml
+data:
+  profile: { name: "John", age: 30 }
+  settings: { theme: "dark", lang: "en" }
+
+renderView:
+  editor:
+    - type: ReactiveJsonSubroot
+      sharedUpdates: true
+      rjOptions:
+        dataOverride:
+          userProfile: ~~.profile
+          userSettings: ~~.settings
+        maybeRawAppRjBuild:
+          renderView:
+            sections:
+              - type: TextField
+                label: "Name"
+                dataLocation: ~.userProfile.name
+              - type: TextField  
+                label: "Theme"
+                dataLocation: ~.userSettings.theme
+```
+
+### Loading from URL with authentication
+This example shows how to load an external RjBuild file while providing authentication headers and data overrides. The external form loaded from the URL will receive the user profile data and any changes made will be propagated back to the parent thanks to `sharedUpdates`. This pattern is useful for reusable form components that need to work with dynamic data and authentication.
+
+```yaml
+data:
+  user:
+    profile: { name: "John", role: "admin" }
+  authToken: "abc123"
+
+renderView:
+  profileEditor:
+    - type: ReactiveJsonSubroot
+      sharedUpdates: true
+      rjOptions:
+        rjBuildUrl: "/forms/user-profile-form.yaml"
+        dataOverride: ~~.user.profile
+        headersForRjBuild:
+          Authorization: ["Bearer ", ~~.authToken]
+```
+
+### Array with references
+This example demonstrates how to work with arrays in `dataOverride` where each array item is mapped to different parts of the parent data. The subroot can edit individual array items and changes will be propagated back to their respective locations in the parent array.
+
+```yaml
+data:
+  items: [
+    { title: "Item 1", active: true },
+    { title: "Item 2", active: false }
+  ]
+
+renderView:
+  listEditor:
+    - type: ReactiveJsonSubroot
+      sharedUpdates: true
+      rjOptions:
+        dataOverride:
+          - ~~.items.0
+          - ~~.items.1
+        maybeRawAppRjBuild:
+          renderView:
+            editors:
+              - type: TextField
+                label: "First item title"
+                dataLocation: ~.0.title
+              - type: TextField
+                label: "Second item title"
+                dataLocation: ~.1.title
+```
+
+## Technical Details
+
+- Uses `dataLocationToPath()` from the template system for consistent path resolution.
+- Supports all template reference types: `~~.`, `~.`, and `~>`.
+- Handles arrays and nested objects in `dataOverride` when analyzing references.
+- Falls back to local updates if upstream propagation fails.
+- All `rjOptions` properties are evaluated with `evaluateTemplateValueCollection()`.
+- Template evaluation respects the `dataOverrideEvaluationDepth` property for special cases.
+
+## Debugging
+
+For troubleshooting shared updates:
+
+1. **Browser console**: Propagation errors are logged with descriptive messages.
+2. **dataOverride structure**: Ensure template references are valid and exist in parent data.
+3. **Data context**: Verify that referenced data exists in the expected locations.
+4. **Data paths**: Confirm that `dataLocation` values in the subroot match the dataOverride structure.
+
+## Caveat: Data Loss Risk with sharedUpdates
+
+**⚠️ Important Warning**: When using `sharedUpdates`, there is a risk of data loss in specific scenarios.
+
+### The Problem
+If the subroot modifies data that is **not** covered by a template reference from the parent's `dataOverride`, and subsequently the parent re-renders the subroot, the local modifications will be **lost**.
+
+### When This Happens
+1. **Subroot modifies local data**: The subroot changes a value that doesn't correspond to any template reference in the parent's `dataOverride`.
+2. **Parent re-renders**: This can occur when:
+   - The parent updates itself for any reason.
+   - A subroot action triggers an upstream update that causes the parent to re-render.
+3. **Data loss**: The parent's `dataOverride` completely overwrites the subroot's data, erasing local modifications.
+
+### Example Scenario
+```yaml
+# Parent has this data structure
+data:
+  user: { name: "John", email: "john@example.com" }
+
+# Subroot configured like this
+- type: ReactiveJsonSubroot
+  sharedUpdates: true
+  rjOptions:
+    dataOverride: ~~.user  # Only user data is referenced
+    maybeRawAppRjBuild:
+      renderView:
+        - type: TextField
+          label: "Name"
+          dataLocation: ~.name          # ✅ Safe - covered by ~~.user
+        - type: TextField
+          label: "Temporary Note"
+          dataLocation: ~.tempNote      # ⚠️ Risk - NOT in parent data
+```
+
+In this example, if the user types in "Temporary Note" and then any parent update occurs, the `tempNote` value will be lost because it's not part of the original `~~.user` data.
+
+### Best Practices to Avoid Data Loss
+1. **Map all needed data**: Ensure all data fields the subroot might modify are included in the parent's data structure.
+2. **Use complete dataOverride**: Include all necessary data paths in your `dataOverride` mapping.
+3. **Avoid local-only modifications**: Design your data flow so that all user inputs correspond to parent data.
+4. **Consider alternatives**: For truly local data, consider using component state or separate data management instead of `sharedUpdates`.
+
 ## Limitations
-- The subroot is isolated from the parent; data and state are not shared
-- No built-in communication between parent and subroot (except via plugins or explicit data passing) 
+- **Data loss risk**: Local modifications in subroot may be lost when parent re-renders (see Caveat section above).
+- **Nested references in data**: References within references are not supported (e.g., `dataOverride: { prop: "~~.user" }` where data contains `{ prop: "~~.other" }`).
+- **Circular references**: May cause infinite loops if data structures reference each other.
+- **Template isolation**: Templates and rendering contexts remain isolated even with `sharedUpdates`.
+- **Data isolation by default**: Without `sharedUpdates`, data changes in the subroot do not affect the parent.
+- **One-way shared updates**: `sharedUpdates` only propagates changes from subroot to parent, not vice versa.
+- **Backward compatibility**: `sharedUpdates` is disabled by default to maintain existing behavior. 
+
+## Changelog
+
+### reactive-json@0.1.0
+- **New**: `sharedUpdates` feature - enables automatic data synchronization between subroot and parent
+- **New**: `dataOverride` property - allows complete data replacement in subroot with support for template references
+- **New**: Automatic analysis of template references in `dataOverride` for shared updates propagation 

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

@@ -5,15 +5,88 @@ renderView:
 
       The `ReactiveJsonSubroot` component allows you to render a new Reactive-JSON root inside an existing application. It is useful for embedding a sub-application, isolating a part of the data tree, or rendering a separate rjbuild with its own options.
 
+      With the `sharedUpdates` feature, the component can also propagate data changes back to the parent, enabling seamless communication between parent and subroot when working with shared data references.
+
       ## Properties
-      - `rjOptions` (object, required): Options to pass to the subroot (such as `rjBuildUrl`, `data`, `renderView`, etc.)
-      - Other properties are passed to the underlying `ReactiveJsonRoot`
+      - `rjOptions` (object, required): Options to pass to the subroot - accepts **all** `ReactiveJsonRoot` properties.
+        - Direct properties: `rjBuildUrl`, `dataOverride`, `headersForRjBuild`, `debugMode`, etc.
+        - For inline content: use `maybeRawAppRjBuild` containing `renderView`, `templates`, `data`.
+      - `sharedUpdates` (boolean, optional): Enable upstream data propagation to parent (default: false).
+      - `dataOverrideEvaluationDepth` (number, optional): Special evaluation depth for dataOverride property.
+      - Other properties are passed to the underlying `ActionDependant` wrapper.
 
       ## Behavior
-      - Renders a new `ReactiveJsonRoot` with the provided options
-      - The subroot is isolated from the parent for data, templates, and rendering
-      - Plugins from the parent are reused in the subroot
-      - If `rjOptions` is not a valid object, nothing is rendered
+      - Renders a new `ReactiveJsonRoot` with the provided options.
+      - The subroot is typically isolated from the parent for data, templates, and rendering¹.
+      - Plugins from the parent are automatically reused in the subroot.
+      - All properties in `rjOptions` are evaluated with template values.
+      - If `rjOptions` is not a valid object, nothing is rendered.
+
+      ¹Note: Data isolation is bypassed when `sharedUpdates: true` is enabled, allowing the subroot to propagate data changes back to the parent. Templates and rendering contexts remain isolated.
+
+      ## Shared Updates Feature
+      When `sharedUpdates: true` is enabled, the component automatically detects template references in `dataOverride` and creates update callbacks to propagate changes back to the parent.
+
+      ### How it works
+      1. **Automatic analysis**: The system analyzes `dataOverride` to detect references (`~~.`, `~.`, `~>`) to parent data
+      2. **Callback creation**: For each detected reference, an update callback is created
+      3. **Update interception**: When the subroot modifies data, the system checks if it corresponds to a parent reference
+      4. **Propagation**: If so, the update is propagated to the parent instead of being applied locally
+
+      ### Advantages
+      1. **Automatic synchronization**: Data remains consistent between parent and subroot
+      2. **Simplicity**: No need to manually manage update callbacks
+      3. **Performance**: Avoids unnecessary re-renders by propagating directly to the right level
+             4. **Flexibility**: Supports different referencing patterns (~~., ~., ~>) and arrays containing references
+
+      ### Supported vs Unsupported Cases
+
+      #### ✅ Supported cases
+
+      ##### 1. Direct reference
+      ```yaml
+      dataOverride: ~~.user
+      # Modifications in the subroot propagate to "user" in the parent
+      ```
+
+      ##### 2. Object mapping with references
+      ```yaml
+      dataOverride:
+        userInfo: ~~.user
+        settings: ~~.config
+      # Modifications to "userInfo" propagate to "user" in the parent
+      # Modifications to "settings" propagate to "config" in the parent
+      ```
+
+      ##### 3. Local references
+      ```yaml
+      dataOverride: ~.localData
+      # Modifications propagate to the local template context
+      ```
+
+      ##### 4. Hierarchical references
+      ```yaml
+      dataOverride: ~>key.someData
+      # Modifications propagate up the template hierarchy
+      ```
+
+      ##### 5. Arrays in dataOverride
+      ```yaml
+      dataOverride:
+        - ~~.firstItem
+        - ~~.secondItem
+      # Array items with template references are properly handled
+      ```
+
+      #### ❌ Unsupported cases
+
+      ##### Nested references in data
+      ```yaml
+      dataOverride:
+        someProperty: ~~.user
+      data:
+        someProperty: ~~.anotherProperty  # Not supported
+      ```
 
   - type: RjBuildDescriber
     title: Example
@@ -44,8 +117,250 @@ renderView:
               - type: div
                 content: This second subroot is loaded from the "data" key of the main root.
 
+  - type: RjBuildDescriber
+    title: Example with Shared Updates
+    description: This example demonstrates the `sharedUpdates` feature where changes in the subroot automatically propagate back to the parent data. Notice how modifying the text field in the subroot will update the display in the parent above it.
+    toDescribe:
+      data:
+        user:
+          name: "John Doe"
+          email: "john@example.com"
+      renderView:
+        - type: div
+          attributes:
+            style:
+              padding: "1rem"
+              border: "2px solid #007bff"
+              borderRadius: "8px"
+              backgroundColor: "#f8f9fa"
+              marginBottom: "1rem"
+          content:
+            - type: h4
+              content: "Parent Data Display"
+            - type: p
+              content: ["Name: ", ~~.user.name]
+            - type: p
+              content: ["Email: ", ~~.user.email]
+        
+        - type: ReactiveJsonSubroot
+          sharedUpdates: true
+          rjOptions:
+            dataOverride: ~~.user
+            maybeRawAppRjBuild:
+              renderView:
+                - type: div
+                  attributes:
+                    style:
+                      padding: "1rem"
+                      border: "2px solid #28a745"
+                      borderRadius: "8px"
+                      backgroundColor: "#e8f5e9"
+                  content:
+                    - type: h4
+                      content: "Subroot Editor (with sharedUpdates)"
+                    - type: TextField
+                      label: "Name"
+                      dataLocation: ~.name
+                    - type: TextField
+                      label: "Email"
+                      dataLocation: ~.email
+                    - type: p
+                      attributes:
+                        style:
+                          fontSize: "0.9em"
+                          color: "#666"
+                          marginTop: "0.5rem"
+                      content: "Changes here automatically update the parent data above ↑"
+
+  - type: RjBuildDescriber
+    title: Example with Multi-Section Configuration
+    description: This example shows how `sharedUpdates` works with complex data mappings where different parts of the parent data are mapped to different sections in the subroot.
+    toDescribe:
+      data:
+        profile:
+          name: "Alice Smith"
+          age: 28
+        settings:
+          theme: "dark"
+          language: "en"
+      renderView:
+        - type: div
+          attributes:
+            style:
+              display: "grid"
+              gridTemplateColumns: "1fr 1fr"
+              gap: "1rem"
+              marginBottom: "1rem"
+          content:
+            - type: div
+              attributes:
+                style:
+                  padding: "1rem"
+                  border: "1px solid #ddd"
+                  borderRadius: "4px"
+                  backgroundColor: "#f5f5f5"
+              content:
+                - type: h5
+                  content: "Profile Data"
+                - type: p
+                  content: ["Name: ", ~~.profile.name]
+                - type: p
+                  content: ["Age: ", ~~.profile.age]
+            - type: div
+              attributes:
+                style:
+                  padding: "1rem"
+                  border: "1px solid #ddd"
+                  borderRadius: "4px"
+                  backgroundColor: "#f5f5f5"
+              content:
+                - type: h5
+                  content: "Settings Data"
+                - type: p
+                  content: ["Theme: ", ~~.settings.theme]
+                - type: p
+                  content: ["Language: ", ~~.settings.language]
+        
+        - type: ReactiveJsonSubroot
+          sharedUpdates: true
+          rjOptions:
+            dataOverride:
+              userProfile: ~~.profile
+              userSettings: ~~.settings
+            maybeRawAppRjBuild:
+              renderView:
+              - type: div
+                attributes:
+                  style:
+                    display: "grid"
+                    gridTemplateColumns: "1fr 1fr"
+                    gap: "1rem"
+                    padding: "1rem"
+                    border: "2px solid #17a2b8"
+                    borderRadius: "8px"
+                    backgroundColor: "#e3f2fd"
+                content:
+                  - type: div
+                    content:
+                      - type: h5
+                        content: "Edit Profile"
+                      - type: TextField
+                        label: "Name"
+                        dataLocation: ~.userProfile.name
+                      - type: NumberField
+                        label: "Age"
+                        dataLocation: ~.userProfile.age
+                  - type: div
+                    content:
+                      - type: h5
+                        content: "Edit Settings"
+                      - type: TextField
+                        label: "Theme"
+                        dataLocation: ~.userSettings.theme
+                      - type: TextField
+                        label: "Language"
+                        dataLocation: ~.userSettings.language
+
+  - type: RjBuildDescriber
+    title: Example with Array References
+    description: This example demonstrates how to work with arrays in `dataOverride` where each array item is mapped to different parts of the parent data. The subroot can edit individual array items and changes will be propagated back to their respective locations in the parent array.
+    toDescribe:
+      data:
+        items:
+          - title: "Task 1"
+            completed: false
+          - title: "Task 2"
+            completed: true
+      renderView:
+        - type: div
+          attributes:
+            style:
+              padding: "1rem"
+              border: "1px solid #ddd"
+              borderRadius: "4px"
+              backgroundColor: "#f9f9f9"
+              marginBottom: "1rem"
+          content:
+            - type: h4
+              content: "Parent Items Display"
+            - type: p
+              content: ["Item 1: ", ~~.items.0.title, " (", ~~.items.0.completed, ")"]
+            - type: p
+              content: ["Item 2: ", ~~.items.1.title, " (", ~~.items.1.completed, ")"]
+        
+        - type: ReactiveJsonSubroot
+          sharedUpdates: true
+          rjOptions:
+            dataOverride:
+              - ~~.items.0
+              - ~~.items.1
+            maybeRawAppRjBuild:
+              renderView:
+                - type: div
+                  attributes:
+                    style:
+                      padding: "1rem"
+                      border: "2px solid #ffc107"
+                      borderRadius: "8px"
+                      backgroundColor: "#fff3cd"
+                  content:
+                    - type: h4
+                      content: "Array Items Editor"
+                    - type: div
+                      content:
+                        - type: h5
+                          content: "First Item"
+                        - type: TextField
+                          label: "Title"
+                          dataLocation: ~.0.title
+                        - type: CheckBoxField
+                          label: "Completed"
+                          dataLocation: ~.0.completed
+                    - type: div
+                      content:
+                        - type: h5
+                          content: "Second Item"
+                        - type: TextField
+                          label: "Title"
+                          dataLocation: ~.1.title
+                        - type: CheckBoxField
+                          label: "Completed"
+                          dataLocation: ~.1.completed
+
   - type: Markdown
     content: |
+      ## Caveat: Data Loss Risk with sharedUpdates
+
+      **⚠️ Important Warning**: When using `sharedUpdates`, there is a risk of data loss in specific scenarios.
+
+      ### The Problem
+      If the subroot modifies data that is **not** covered by a template reference from the parent's `dataOverride`, and subsequently the parent re-renders the subroot, the local modifications will be **lost**.
+
+      ### When This Happens
+      1. **Subroot modifies local data**: The subroot changes a value that doesn't correspond to any template reference in the parent's `dataOverride`.
+      2. **Parent re-renders**: This can occur when:
+         - The parent updates itself for any reason.
+         - A subroot action triggers an upstream update that causes the parent to re-render.
+      3. **Data loss**: The parent's `dataOverride` completely overwrites the subroot's data, erasing local modifications.
+
+      ### Best Practices to Avoid Data Loss
+      1. **Map all needed data**: Ensure all data fields the subroot might modify are included in the parent's data structure.
+      2. **Use complete dataOverride**: Include all necessary data paths in your `dataOverride` mapping.
+      3. **Avoid local-only modifications**: Design your data flow so that all user inputs correspond to parent data.
+      4. **Consider alternatives**: For truly local data, consider using component state or separate data management instead of `sharedUpdates`.
+
       ## Limitations
-      - The subroot is isolated from the parent; data and state are not shared
-      - No built-in communication between parent and subroot (except via plugins or explicit data passing) 
+      - **Data loss risk**: Local modifications in subroot may be lost when parent re-renders (see Caveat section above).
+      - **Nested references in data**: References within references are not supported.
+      - **Circular references**: May cause infinite loops if data structures reference each other.
+      - **Isolation by default**: Without `sharedUpdates`, the subroot is completely isolated from the parent.
+      - **Backward compatibility**: `sharedUpdates` is disabled by default to maintain existing behavior. 
+
+  - type: Markdown
+    content: |
+      ## Changelog
+
+      ### reactive-json@0.1.0
+      - **New**: `sharedUpdates` feature - enables automatic data synchronization between subroot and parent
+      - **New**: `dataOverride` property - allows complete data replacement in subroot with support for template references
+      - **New**: Automatic analysis of template references in `dataOverride` for shared updates propagation 

package/public/rjbuild/docs/extend/component-development-guide-llm.md

@@ -188,7 +188,7 @@ Other specialized contexts are available.
 - **PaginationContext**: Used by components that integrate pagination, such as Switch.
 
 ### Key Functions
-- **evaluateTemplateValue()**: Evaluates template patterns (`~.value`, `~~.value`, `~>.value`)
+- **evaluateTemplateValue()**: Evaluates template patterns (`~.value`, `~~.value`, `~>key` for nearest, `~~>key` for global)
 - **useEvaluatedAttributes()**: Hook to evaluate dynamic attributes
 - **propsDataLocationToPathAndValue()**: Form-specific data location handling
 
@@ -351,7 +351,8 @@ data:
 renderView:
   - content: ~~.global_value        # From root data
   - content: ~.nested_value         # From current template
-  - content: ~>.nested_value        # Search up hierarchy
+  - content: ~>parent_key.nested_value    # Get from nearest parent_key
+  - content: ~~>parent_key.nested_value   # Get from top-level parent_key
 ```
 
 ### Common RjBuild Patterns

package/public/rjbuild/docs/extend/component-development.md

@@ -130,7 +130,7 @@ export const MyWrapper = ({ props, path, currentData, datafield }) => {
 ## Key APIs and Utilities
 
 ### Template Evaluation
-- **evaluateTemplateValue()**: Evaluates template patterns like `~.value`, `~~.value`, `~>.value`
+- **evaluateTemplateValue()**: Evaluates template patterns like `~.value`, `~~.value`, `~>key` (nearest), `~~>key` (global)
 - **evaluateTemplateValueCollection()**: Evaluates collections and arrays with template patterns, supports multiple elements
 - **useEvaluatedAttributes()**: Hook to evaluate dynamic attributes object
 

package/public/rjbuild/docs/extend/component-development.yaml

@@ -144,7 +144,7 @@ renderView:
       ## Key APIs and Utilities
 
       ### Template Evaluation
-      - **evaluateTemplateValue()**: Evaluates template patterns like `~.value`, `~~.value`, `~>.value`
+      - **evaluateTemplateValue()**: Evaluates template patterns like `~.value`, `~~.value`, `~>key` (nearest), `~~>key` (global)
       - **evaluateTemplateValueCollection()**: Evaluates collections and arrays with template patterns, supports multiple elements
       - **useEvaluatedAttributes()**: Hook to evaluate dynamic attributes object
 

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

@@ -30,13 +30,12 @@ data:        # Defines the data to be used (optional)
 
 ## Key Concepts
 
-### 1. Template System
+### Template System
 
-Reactive-JSON uses three main notations to access data:
+In Reactive-JSON, you will often find those notations to access data:
 
-- `~.` : Local context (relative to current template)
+- `~.` : Local context (relative to current template)  
 - `~~.` : Global context (access to global data)
-- `~>field` : Access to a specific parent context
 
 Example:
 ```yaml
@@ -48,9 +47,15 @@ templates:
         content: ["Name: ", ~.name]  # Local access to user data
       - type: div
         content: ["Admin: ", ~~.isAdmin]  # Global access to isAdmin
+
+data:
+  name: "John"
+  isAdmin: true
 ```
 
-### 2. Basic Elements
+> 💡 **Advanced navigation:** For complex hierarchical data access, see the [Template System documentation](/docs/template) which covers `~>key` and `~~>key` notations.
+
+### Basic Elements
 
 Reactive-JSON provides several types of elements:
 
@@ -80,12 +85,15 @@ renderView:
 renderView:
   - type: Switch
     content: ~.items
-    template:
-      type: div
-      content: ~.name
+    singleOption:
+      load: itemTemplate
+templates:
+  itemTemplate:
+    type: div
+    content: ~.name
 ```
 
-### 3. Actions and Reactions
+### Actions and Reactions
 
 #### Actions
 Actions modify element behavior:

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

@@ -33,12 +33,13 @@ renderView:
     content: |
       ## Key Concepts
 
-      ### 1. Template System
+      ### Template System
 
-      Reactive-JSON uses three main notations to access data:
+      In Reactive-JSON, you will often find those notations to access data:
       - `~.` : Local context (relative to current template)
       - `~~.` : Global context (access to global data)
-      - `~>field` : Access to a specific parent context
+
+      > 💡 **Advanced navigation:** For complex hierarchical data access, see the [Template System documentation](/docs/template) which covers `~>key` and `~~>key` notations.
 
   - type: RjBuildDescriber
     title: "Template System Example"
@@ -62,7 +63,7 @@ renderView:
 
   - type: Markdown
     content: |
-      ### 2. Basic Elements
+      ### Basic Elements
 
       Reactive-JSON provides several types of elements:
 
@@ -114,9 +115,12 @@ renderView:
       renderView:
         - type: Switch
           content: ~.items
-          template:
-            type: div
-            content: ~.name
+          singleOption:
+            load: itemTemplate
+      templates:
+        itemTemplate:
+          type: div
+          content: ~.name
       data:
         items:
           - name: "Item 1"
@@ -124,7 +128,7 @@ renderView:
 
   - type: Markdown
     content: |
-      ### 3. Actions and Reactions
+      ### Actions and Reactions
 
       #### Actions
       Actions modify element behavior.

package/public/rjbuild/docs/install.yaml

@@ -873,7 +873,6 @@ renderView:
       **Need help?**
 
       - Check the [Troubleshooting Guide](/docs/troubleshooting/)
-      - Join our [Community Discord](https://discord.gg/reactive-json)
       - Open an issue on [GitHub](https://github.com/Ealab-collab/reactive-json/issues)
 
 templates:

package/public/rjbuild/docs/template.md

@@ -6,41 +6,134 @@ The template system in reactive-json efficiently manages data contexts and their
 
 ## Context Notations
 
-There are three main notations for accessing data:
+There are four main notations for accessing data:
 
 - `~.` : Local context (relative to current template)
 - `~~.` : Global context (access to global data)
-- `~>field` : Access to a specific parent context by climbing up to a given key
+- `~>key` : Finds the nearest "key" by going up the hierarchy (useful when multiple keys exist)
+- `~~>key` : Finds the top-level "key" from root (useful for global settings)
 
-### Context Usage Example
+Each notation is explained with examples below.
+
+#### Local Context (`~.`)
+
+```yaml
+renderView:
+  - type: div
+    content: ["Hello ", ~.username]  # Accesses username from current context
+
+data:
+  username: "John"
+```
+
+#### Global Context (`~~.`)
 
 ```yaml
 templates:
-  userList:
-    type: Switch
-    content: ~~.users
-    template:
-      type: div
+  userCard:
+    - type: div
       content:
-        - type: div
-          content: ["Name: ", ~.name]  # Local access to current user data
-        - type: div
-          content: ["Admin: ", ~~.isAdmin]  # Global access to isAdmin data
-        - type: div
-          content: ["Parent: ", ~>userList.title]  # Climbs up to 'userList' template to access title
+        - "Admin: "
+        - type: LabelFromValue
+          dataLocation: ~~.isAdmin  # Accesses isAdmin from global data
+          options:
+            - label: "Yes"
+              value: true
+            - label: "No"
+              value: false
+
+renderView:
+  - load: userCard
 
 data:
-  users:
-    - name: "John"
   isAdmin: true
-  userList:
-    title: "User List"
 ```
 
-In this example:
-- `~.name` accesses the `name` property from the local context (current user)
-- `~~.isAdmin` accesses the `isAdmin` property from the global context
-- `~>userList.title` climbs up to the "userList" template and accesses its `title` property
+#### Nearest Key (`~>key`)
+
+```yaml
+templates:
+  themeDisplay:
+    type: div
+    content: ["Theme: ", ~>config.theme]  # Gets theme from nearest config
+
+renderView:
+  - type: Switch
+    content: ~~.config.userSection.config.items
+    singleOption:
+      load: themeDisplay
+
+data:
+  config:
+    theme: "dark"
+    userSection:
+      config:
+        theme: "light"   # This will be found (nearest)
+        items:
+          - name: "Item 1"  # themeDisplay template runs here
+```
+
+#### Top-level Key (`~~>key`)
+
+```yaml
+templates:
+  themeDisplay:
+    type: div
+    content: ["Theme: ", ~~>config.theme]  # Gets theme from top-level config
+
+renderView:
+  - type: Switch
+    content: ~~.config.userSection.config.items
+    singleOption:
+      load: themeDisplay
+
+data:
+  config:
+    theme: "dark"      # This will be found (top-level)
+    userSection:
+      config:
+        theme: "light"
+        items:
+          - name: "Item 1"  # themeDisplay template runs here
+```
+
+### Complete Practical Example
+
+Here's a complete working example that demonstrates all four syntaxes in action:
+
+```yaml
+data:
+  global_value: "Hello"
+  config:
+    theme: "dark"
+    userSection:
+      title: "User List"
+      config:
+        theme: "light"
+      level1:
+        items:
+          - name: "Item 1"
+          # userList template instances run here at: data.config.userSection.level1.items
+
+templates:
+  userList:
+    type: div
+    content:
+      - type: div
+        content: ["Global: ", ~~.global_value]        # From root data
+      - type: div  
+        content: ["Local: ", ~.name]                  # From current template
+      - type: div
+        content: ["Theme (nearest): ", ~>config.theme]    # Get from nearest config → "light"
+      - type: div
+        content: ["Theme (global): ", ~~>config.theme]   # Get from top-level config → "dark"
+
+renderView:
+  - type: Switch
+    content: ~~.config.userSection.level1.items
+    singleOption:
+      load: userList
+```
 
 ## Containerization Principle
 
@@ -85,10 +178,12 @@ data:
 2. Actions and reactions respect the context where they are defined
 3. Containerization allows isolating modifications until validation
 4. `~~.` allows "escaping" the container to access global data
-5. `~>field` allows climbing up to a specific parent context using the template name as reference
+5. `~>key` finds the nearest "key" by going up step by step (useful for local overrides)
+6. `~~>key` finds the top-level "key" from root (useful for global settings)
 
 ## Best Practices
 
 1. **Context Coherence**: Ensure components that need to share data are in the same context
 2. **Global Access**: Use `~~.` for data that needs to be shared between different templates
-3. **Hierarchical Navigation**: Use `~>field` to access specific parent template data by explicitly naming it 
+3. **Hierarchical Navigation**: Use `~>key` to find nearest occurrence or `~~>key` to find global setting
+4. **Local vs Global**: `~>` prioritizes local overrides, `~~>` prioritizes global settings 

package/public/rjbuild/docs/template.yaml

@@ -7,46 +7,117 @@ renderView:
 
       The template system in reactive-json efficiently manages data contexts and their access. Understanding how templates "containerize" data is essential for properly using components, actions, and reactions.
 
+  - type: Markdown
+    content: |
+      There are four main notations for accessing data:
+      
+      - `~.` : Local context (relative to current template)
+      - `~~.` : Global context (access to global data)
+      - `~>key` : Finds the nearest "key" by going up the hierarchy (useful when multiple keys exist)
+      - `~~>key` : Finds the top-level "key" from root (useful for global settings)
+
+      Each notation is explained with examples below.
+
+  - type: RjBuildDescriber
+    title: "Local Context (`~.`)"
+    description:
+      - type: Markdown
+        content: |
+          Accesses data from the current template context.
+
+    toDescribe:
+      renderView:
+        - type: div
+          content: ["Hello ", ~.username]  # Accesses username from current context
+
+      data:
+        username: "John"
+
   - type: RjBuildDescriber
-    title: "Context Notations"
+    title: "Global Context (`~~.`)"
     description:
       - type: Markdown
         content: |
-          There are three main notations for accessing data:
-          
-          - `~.` : Local context (relative to current template)
-          - `~~.` : Global context (access to global data)
-          - `~>field` : Access to a specific parent context by climbing up to a given key
+          Accesses data from the global (root) data, regardless of current template context.
 
     toDescribe:
       templates:
-        userList:
-          type: Switch
-          content: ~~.users
-          template:
-            type: div
+        userCard:
+          - type: div
             content:
-              - type: div
-                content: ["Name: ", ~.name]  # Local access to current user data
-              - type: div
-                content: ["Admin: ", ~~.isAdmin]  # Global access to isAdmin data
-              - type: div
-                content: ["Parent: ", ~>userList.title]  # Climbs up to 'userList' template to access title
+              - "Admin: "
+              - type: LabelFromValue
+                dataLocation: ~~.isAdmin  # Accesses isAdmin from global data
+                options:
+                  - label: "Yes"
+                    value: true
+                  - label: "No"
+                    value: false
+
+      renderView:
+        - load: userCard
 
       data:
-        users:
-          - name: "John"
         isAdmin: true
-        userList:
-          title: "User List"
+
+  - type: RjBuildDescriber
+    title: "Nearest Key (`~>key`)"
+    description:
+      - type: Markdown
+        content: |
+          Searches for "key" by going up the hierarchy, finds the nearest occurrence.
+
+    toDescribe:
+      templates:
+        themeDisplay:
+          type: div
+          content: ["Theme: ", ~>config.theme]  # Gets theme from nearest config
+
+      renderView:
+        - type: Switch
+          content: ~~.config.userSection.config.items
+          singleOption:
+            load: themeDisplay
+
+      data:
+        config:
+          theme: "dark"
+          userSection:
+            config:
+              theme: "light"   # This will be found (nearest)
+              items:
+                - name: "Item 1"  # themeDisplay template runs here
+
+  - type: RjBuildDescriber
+    title: "Top-level Key (`~~>key`)"
+    description:
+      - type: Markdown
+        content: |
+          Searches for "key" starting from root, finds the top-level occurrence.
+
+    toDescribe:
+      templates:
+        themeDisplay:
+          type: div
+          content: ["Theme: ", ~~>config.theme]  # Gets theme from top-level config
+
+      renderView:
+        - type: Switch
+          content: ~~.config.userSection.config.items
+          singleOption:
+            load: themeDisplay
+
+      data:
+        config:
+          theme: "dark"      # This will be found (top-level)
+          userSection:
+            config:
+              theme: "light"
+              items:
+                - name: "Item 1"  # themeDisplay template runs here
 
   - type: Markdown
     content: |
-      In this example:
-      - `~.name` accesses the `name` property from the local context (current user)
-      - `~~.isAdmin` accesses the `isAdmin` property from the global context
-      - `~>userList.title` climbs up to the "userList" template and accesses its `title` property
-
       ## Containerization Principle
 
       Templates create context "containers". This means each template defines its own local data space.
@@ -96,13 +167,55 @@ renderView:
       2. Actions and reactions respect the context where they are defined
       3. Containerization allows isolating modifications until validation
       4. `~~.` allows "escaping" the container to access global data
-      5. `~>field` allows climbing up to a specific parent context using the template name as reference
+      5. `~>key` finds the nearest "key" by going up step by step (useful for local overrides)
+      6. `~~>key` finds the top-level "key" from root (useful for global settings)
 
       ## Best Practices
 
       1. **Context Coherence**: Ensure components that need to share data are in the same context
       2. **Global Access**: Use `~~.` for data that needs to be shared between different templates
-      3. **Hierarchical Navigation**: Use `~>field` to access specific parent template data by explicitly naming it
+      3. **Hierarchical Navigation**: Use `~>key` to find nearest occurrence or `~~>key` to find global setting
+      4. **Local vs Global**: `~>` prioritizes local overrides, `~~>` prioritizes global settings
+
+  - type: RjBuildDescriber
+    title: "Complete Practical Example"
+    description:
+      - type: Markdown
+        content: |
+          Here's a complete working example that demonstrates all four syntaxes in action with a functional renderView.
+
+    toDescribe:
+      data:
+        global_value: "Hello"
+        config:
+          theme: "dark"
+          userSection:
+            title: "User List"
+            config:
+              theme: "light"
+            level1:
+              items:
+                - name: "Item 1"
+                # userList template instances run here at: data.config.userSection.level1.items
+
+      templates:
+        userList:
+          type: div
+          content:
+            - type: div
+              content: ["Global: ", ~~.global_value]        # From root data
+            - type: div  
+              content: ["Local: ", ~.name]                  # From current template
+            - type: div
+              content: ["Theme (nearest): ", ~>config.theme]    # Get from nearest config → "light"
+            - type: div
+              content: ["Theme (global): ", ~~>config.theme]   # Get from top-level config → "dark"
+
+      renderView:
+        - type: Switch
+          content: ~~.config.userSection.level1.items
+          singleOption:
+            load: userList
 
 templates: