@ea-lab/reactive-json-docs 0.4.0 → 0.5.0

package/package.json

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

package/public/rjbuild/docs/advanced-concepts/index.md

@@ -6,4 +6,5 @@ This section covers advanced features and concepts in Reactive-JSON that enable
 
 - **[Data Mapping](data-mapping.md)**: Learn how to selectively dispatch and transform response data using the Data Mapping system
 - **[Data Processors](data-processors.md)**: Learn how to intercept and modify data from HTTP requests using the DataProcessor system
+- **[Forward Update](forward-update.md)**: Implementation details about the retrieval of event values.
 - **[Plugins](plugins/index.md)**: Learn how to extend Reactive-JSON with custom components and plugins.

package/public/rjbuild/docs/advanced-concepts/index.yaml

@@ -9,6 +9,7 @@ renderView:
 
       - **[Data Mapping](data-mapping)**: Learn how to selectively dispatch and transform response data using the Data Mapping system.
       - **[Data Processors](data-processors)**: Learn how to intercept and modify data from HTTP requests using the DataProcessor system.
+      - **[Forward Update](forward-update)**: Implementation details about the retrieval of event values.
       - **[Plugins](plugins/index)**: Learn how to extend Reactive-JSON with custom components and plugins.
 
 data:

package/public/rjbuild/docs/advanced-concepts/plugins/component-development.md

@@ -19,7 +19,7 @@ All components have access to these React contexts:
 - **TemplateContext**: Contains current template data for evaluation
 
 Other specialized contexts are available.
-- **EventDispatcherContext**: Centralized event handling system, mostly used by the [reaction system](/docs/core/reaction/index).
+- **EventDispatcherContext**: Centralized event handling system, mostly used by the [reaction system](/docs/getting-started/reactions).
 - **PaginationContext**: Used by components that integrate pagination, such as [Switch](/docs/core/element/special/Switch).
 
 ## Basic Element Component

package/public/rjbuild/docs/advanced-concepts/plugins/component-development.yaml

@@ -22,7 +22,7 @@ renderView:
       - **TemplateContext**: Contains current template data for evaluation
 
       Other specialized contexts are available.
-      - **EventDispatcherContext**: Centralized event handling system, mostly used by the [reaction system](/docs/core/reaction/index).
+      - **EventDispatcherContext**: Centralized event handling system, mostly used by the [reaction system](/docs/getting-started/reactions).
       - **PaginationContext**: Used by components that integrate pagination, such as [Switch](/docs/core/element/special/Switch).
 
       ## Basic Element Component

package/public/rjbuild/docs/core/action/Hide.md

@@ -19,4 +19,4 @@ renderView:
 ```
 
 ## Limitation
-- The element no longer exists in the DOM, so no events can be attached to it. 
+- When hidden, the element no longer exists in the DOM, so no events can be attached to it. 

package/public/rjbuild/docs/core/action/Hide.yaml

@@ -30,31 +30,31 @@ renderView:
               actions:
                 - what: setData
                   on: click
-                  path: "shouldHide"
-                  value: ~.shouldHide
-                  is: false
+                  path: ~.shouldHide
+                  value: "true"
+                  when: ~.shouldHide
+                  is: "false"
                 - what: setData
                   on: click
-                  path: "shouldHide"
-                  value: ~.shouldHide
-                  is: true
+                  path: ~.shouldHide
+                  value: "false"
                   when: ~.shouldHide
-                  is: false
+                  is: "true"
 
             - type: div
               content: "This text will be hidden when shouldHide is true."
               actions:
                 - what: hide
                   when: ~.shouldHide
-                  is: true
+                  is: "true"
 
             - type: div
               content: ["Current state: shouldHide = ", ~.shouldHide]
 
       data:
-        shouldHide: false
+        shouldHide: "false"
 
   - type: Markdown
     content: |
       ## Limitation
-      - The element no longer exists in the DOM, so no events can be attached to it. 
+      - When hidden, the element no longer exists in the DOM, so no events can be attached to it. 

package/public/rjbuild/docs/core/action/ReactOnEvent.md

@@ -1,8 +1,8 @@
 # ReactOnEvent
 
-**Type**: Internal Action Component
+ReactOnEvent is an internal action component that is automatically instantiated by the Actions system when reactions with event handlers (`on: "eventName"`) are detected. It should **not** be used directly as an element type.
 
-**Description**: ReactOnEvent is an internal action component that is automatically instantiated by the Actions system when reactions with event handlers (`on: "eventName"`) are detected. It should **not** be used directly as an element type.
+> **Important**: It should **not** be used directly as an element type. The Reactive-JSON engine will automatically instantiate it when needed.
 
 ## How it Works
 
@@ -43,8 +43,8 @@ ReactOnEvent supports any DOM event by prefixing with `on` and capitalizing the
 
 Some events have special handling and **do not** use ReactOnEvent:
 
-- `on: "message"` → Uses MessageListener component (listens on window)
-- `on: "hashchange"` → Uses HashChangeListener component (listens on window)
+- `on: "message"` → Uses the [MessageListener](MessageListener.md) component (listens on window)
+- `on: "hashchange"` → Uses the [HashChangeListener](HashChangeListener.md) component (listens on window)
 
 ## Event Propagation Control
 
@@ -67,15 +67,15 @@ actions:
 - **Context preservation**: Maintains access to global and template data contexts
 - **Early termination**: Supports `stopPropagation: true` to halt reaction chain execution
 
+## Important Notes
+
+- **Never use `type: ReactOnEvent`** in your renderView - it's an internal component
+- **Use `actions` with `on: "eventName"`** - this is the correct way to handle events
+- **ReactOnEvent is automatically instantiated** by the Actions system when needed
+- **Event propagation is stopped by default** - use `stopPropagation: false` to change this
+
 ## Related Components
 
 - **[MessageListener](MessageListener.md)**: Handles `on: "message"` events
 - **[HashChangeListener](HashChangeListener.md)**: Handles `on: "hashchange"` events
-- **[Reactions System](../reaction/index.md)**: The actual reaction functions that ReactOnEvent executes
-
-## Important Notes
-
-- **Not for direct use**: Never use `type: ReactOnEvent` in your renderView
-- **Automatic instantiation**: The Actions system creates this component automatically
-- **Internal implementation**: This is part of the framework's internal architecture
-- **Event binding**: Events are bound to the actual DOM elements, not wrapper components 
+- **[Reactions System](../../getting-started/reactions.md)**: The actual reaction functions that ReactOnEvent executes

package/public/rjbuild/docs/core/action/ReactOnEvent.yaml

@@ -3,9 +3,9 @@ renderView:
     content: |
       # ReactOnEvent
 
-      **Type**: Internal Action Component
-
-      **Description**: ReactOnEvent is an internal action component that is automatically instantiated by the Actions system when reactions with event handlers (`on: "eventName"`) are detected. It should **not** be used directly as an element type.
+      ReactOnEvent is an internal action component that is automatically instantiated by the Actions system when reactions with event handlers (`on: "eventName"`) are detected.
+      
+      > **Important**: It should **not** be used directly as an element type. The Reactive-JSON engine will automatically instantiate it when needed.
 
       ## How it Works
 
@@ -16,105 +16,66 @@ renderView:
       3. Creates a ReactOnEvent component that attaches the appropriate event listeners
       4. Wraps the target element with these event handlers
 
-  - type: RjBuildDescriber
-    title: "Correct Usage: Reactions with Events"
-    description:
-      - type: Markdown
-        content: |
-          This example shows the **correct** way to use event handling in Reactive-JSON. 
-          
-          ReactOnEvent is automatically created by the system when you use `on: "eventName"` in actions.
+      ## Usage Pattern
 
-    toDescribe:
-      renderView:
-        - type: div
-          content:
-            - type: button
-              content: "Click me"
-              actions:
-                - what: setData
-                  on: click              # ReactOnEvent handles this automatically
-                  path: "clicked"
-                  value: true
-                - what: setData
-                  on: click
-                  path: "clickCount"
-                  value: 1
-                  when: ~.clickCount
-                  isEmpty: true
-                - what: setData
-                  on: click
-                  path: "clickCount"
-                  value: "~.clickCount + 1"
-                  when: ~.clickCount
-                  isEmpty: "not"
-                  
-            - type: input
-              props:
-                type: "text"
-                placeholder: "Type something..."
-              actions:
-                - what: setData
-                  on: change           # ReactOnEvent handles this automatically
-                  path: "inputValue"
-                  value: "~event.target.value"
-                  
-            - type: div
-              content: "Mouse over this area"
-              props:
-                style:
-                  padding: "10px"
-                  border: "1px solid #ccc"
-                  backgroundColor: "~.hovered ? '#f0f0f0' : 'white'"
-              actions:
-                - what: setData
-                  on: mouseover       # ReactOnEvent handles this automatically
-                  path: "hovered"
-                  value: true
-                - what: setData
-                  on: mouseleave      # ReactOnEvent handles this automatically
-                  path: "hovered"
-                  value: false
-              
-        - type: div
-          content:
-            - type: div
-              content: ["Button clicked: ", ~.clicked]
-              
-            - type: div
-              content: ["Click count: ", ~.clickCount]
-              
-            - type: div
-              content: ["Input value: '", ~.inputValue, "'"]
-              
-            - type: div
-              content: ["Mouse hover state: ", ~.hovered]
+      Instead of using ReactOnEvent directly, you define reactions in the `actions` array of any element:
 
+      ```yaml
+      renderView:
         - type: button
-          content: "Reset all"
+          content: "Click me"
           actions:
             - what: setData
-              on: click
-              path: "clicked"
-              value: false
-            - what: setData
-              on: click
-              path: "clickCount"
-              value: 0
-            - what: setData
-              on: click
-              path: "inputValue"
-              value: ""
-            - what: setData
-              on: click
-              path: "hovered"
-              value: false
+              on: click           # This triggers ReactOnEvent internally
+              path: "buttonClicked"
+              value: true
+      ```
+
+      ## Supported Event Types
+
+      ReactOnEvent supports any DOM event by prefixing with `on` and capitalizing the first letter:
+
+      - `on: click` → `onClick`
+      - `on: change` → `onChange`
+      - `on: mouseover` → `onMouseOver`
+      - `on: keydown` → `onKeyDown`
+      - `on: submit` → `onSubmit`
+      - etc.
+
+      ## Special Event Handling
+
+      Some events have special handling and **do not** use ReactOnEvent:
+
+      - `on: "message"` → Uses the [MessageListener](MessageListener.md) component (listens on window)
+      - `on: "hashchange"` → Uses the [HashChangeListener](HashChangeListener.md) component (listens on window)
+
+      ## Event Propagation Control
+
+      By default, ReactOnEvent stops event propagation. You can control this behavior:
+
+      ```yaml
+      actions:
+        - what: setData
+          on: click
+          path: "clicked"
+          value: true
+          stopPropagation: false  # Allow event to continue propagating
+      ```
+
+      ## Event Placeholders
+
+      ReactOnEvent supports special placeholders to access event data:
+
+      - `<reactive-json:event-new-value>`: Returns the most relevant value from form events (checked for checkboxes, value for inputs)
+      - `<reactive-json:event>.propertyPath`: Access any event property (e.g., `.data.message` for MessageEvent, `.key` for KeyboardEvent)
+
+      ## Technical Implementation
 
-      data:
-        clicked: false
-        clickCount: 0
-        inputValue: ""
-        hovered: false
+      - **Event attachment**: Uses React's event system via `cloneElement`
+      - **Multiple events**: Can handle multiple event types on the same element
+      - **Reaction execution**: Executes reactions in the order they appear
+      - **Context preservation**: Maintains access to global and template data contexts
+      - **Early termination**: Supports `stopPropagation: true` to halt reaction chain execution
 
   - type: Markdown
     content: |
@@ -125,9 +86,8 @@ renderView:
       - **ReactOnEvent is automatically instantiated** by the Actions system when needed
       - **Event propagation is stopped by default** - use `stopPropagation: false` to change this
       
-      ## Related Documentation
+      ## Related Components
       
-      - **[Actions System](index.md)**: Learn about the actions system that uses ReactOnEvent
-      - **[Reactions](../reaction/index.md)**: The reaction functions that ReactOnEvent executes
-      - **[MessageListener](MessageListener.md)**: For `on: "message"` events
-      - **[HashChangeListener](HashChangeListener.md)**: For `on: "hashchange"` events 
+      - **[MessageListener](MessageListener.md)**: Handles `on: "message"` events
+      - **[HashChangeListener](HashChangeListener.md)**: Handles `on: "hashchange"` events
+      - **[Reactions System](../../getting-started/reactions.md)**: The actual reaction functions that ReactOnEvent executes 

package/public/rjbuild/docs/core/action/Redirect.md

@@ -6,14 +6,22 @@
 - `to`: destination URL
 
 ## Example
+
+The following example will redirect the current page when the user clicks on the button.
+
 ```yaml
 renderView:
   - type: button
-    content: "Go to Google"
+    content: "Go to EA Lab"
     actions:
       - what: redirect
-        to: "https://www.google.com"
+        to: "https://ea-lab.io"
+        when: ~~.allowRedirect
+        is: "true"
+      - what: setData
         on: click
+        path: ~~.allowRedirect
+        value: "true"
 ```
 
 ## Limitation

package/public/rjbuild/docs/core/action/Redirect.yaml

@@ -8,59 +8,26 @@ renderView:
       ## Properties
       - `to`: destination URL
 
-  - type: RjBuildDescriber
-    title: "Redirect Action Example"
-    description:
-      - type: Markdown
-        content: |
-          This example demonstrates the `redirect` action. **Warning**: clicking the button below will actually redirect you!
-          
-          For demonstration purposes, this redirects to a safe page (the current page), but in real usage you would specify any URL.
-
-    toDescribe:
-      renderView:
-        - type: div
-          content:
-            - type: button
-              content: "Redirect to Current Page (Safe Demo)"
-              actions:
-                - what: redirect
-                  on: click
-                  to: "."
-
-            - type: div
-              content: "↑ Click the button above to see the redirect in action"
-
-            - type: button
-              content: "Conditional Redirect (Google)"
-              actions:
-                - what: redirect
-                  on: click
-                  to: "https://www.google.com"
-                  when: ~.allowRedirect
-                  is: true
-
-            - type: button
-              content: "Toggle Redirect Permission"
-              actions:
-                - what: setData
-                  on: click
-                  path: "allowRedirect"
-                  value: ~.allowRedirect
-                  is: false
-                - what: setData
-                  on: click
-                  path: "allowRedirect"
-                  value: ~.allowRedirect
-                  is: true
-                  when: ~.allowRedirect
-                  is: false
+  - type: Markdown
+    content: |
+      ## Example
 
-            - type: div
-              content: ["Redirect allowed: ", ~.allowRedirect]
+      The following example will redirect the current page when the user clicks on the button.
 
-      data:
-        allowRedirect: false
+      ```yaml
+      renderView:
+        - type: button
+          content: "Go to EA Lab"
+          actions:
+            - what: redirect
+              to: "https://ea-lab.io"
+              when: ~~.allowRedirect
+              is: "true"
+            - what: setData
+              on: click
+              path: ~~.allowRedirect
+              value: "true"
+      ```
 
   - type: Markdown
     content: |

package/public/rjbuild/docs/core/action/VisuallyHide.yaml

@@ -29,32 +29,30 @@ renderView:
               actions:
                 - what: setData
                   on: click
-                  path: "shouldVisuallyHide"
-                  value: ~.shouldVisuallyHide
-                  is: false
+                  path: ~.shouldVisuallyHide
+                  value: "false"
+                  when: ~.shouldVisuallyHide
+                  is: "true"
+                  stopPropagation: true
                 - what: setData
                   on: click
-                  path: "shouldVisuallyHide"
-                  value: ~.shouldVisuallyHide
-                  is: true
+                  path: ~.shouldVisuallyHide
+                  value: "true"
                   when: ~.shouldVisuallyHide
-                  is: false
+                  is: "false"
 
             - type: div
               content: "This text will be visually hidden but remains in the DOM."
               actions:
                 - what: visuallyHide
                   when: ~.shouldVisuallyHide
-                  is: true
+                  is: "true"
 
             - type: div
               content: ["Current state: shouldVisuallyHide = ", ~.shouldVisuallyHide]
 
-            - type: div
-              content: "↑ Notice the space is preserved even when hidden"
-
       data:
-        shouldVisuallyHide: false
+        shouldVisuallyHide: "false"
 
   - type: Markdown
     content: |