@ea-lab/reactive-json-docs 0.1.2

package/public/rjbuild/component-doc/core/action/HashChangeListener.yaml

@@ -0,0 +1,124 @@
+renderView:
+  - type: Markdown
+    content: |
+      # HashChangeListener
+
+      **Description**: Listens to hash changes (URL fragment) in the window and executes a reaction function in response. This is an internal action component that is automatically used when you specify `on: "hashchange"` in your actions.
+
+      ## Usage
+
+      HashChangeListener is **not** used directly as an element type. Instead, it is automatically triggered when you use `on: "hashchange"` in any action. The system automatically adds this component to listen for hash changes globally.
+
+      ## Properties
+
+      When using `on: "hashchange"` in actions, you can specify:
+
+      - `what` (required): name of the reaction function to execute (e.g., `setData`, `fetchData`, `submitData`, etc.)
+      - `whenHashIs` (optional): hash value that should trigger the reaction (includes the '#' character)
+      - `whenHashWas` (optional): previous hash value that should trigger the reaction (includes the '#' character)
+      - All other properties are passed as arguments to the reaction function
+
+  - type: RjBuildDescriber
+    title: "HashChangeListener Example"
+    description:
+      - type: Markdown
+        content: |
+          This example demonstrates hash change listening. Try changing the URL hash manually or use the buttons below.
+          
+          **Note**: Hash changes are detected automatically when you use `on: "hashchange"` in actions.
+
+    toDescribe:
+      renderView:
+        - type: div
+          content:
+            - type: div
+              content: "Hash change detector is active. Try:"
+              
+            - type: button
+              content: "Set hash to #section1"
+              actions:
+                - what: redirectNow
+                  on: click
+                  to: "#section1"
+
+            - " "
+
+            - type: button
+              content: "Set hash to #section2"
+              actions:
+                - what: redirectNow
+                  on: click
+                  to: "#section2"
+
+            - " "
+
+            - type: button
+              content: "Clear hash"
+              actions:
+                - what: redirectNow
+                  on: click
+                  to: "#"
+
+            - type: div
+              content: "Current section from hash:"
+              actions:
+                - what: setData
+                  on: hashchange
+                  whenHashIs: "#section1"
+                  path: "currentSection"
+                  value: "Section 1"
+                - what: setData
+                  on: hashchange
+                  whenHashIs: "#section2"
+                  path: "currentSection"
+                  value: "Section 2"
+                - what: setData
+                  on: hashchange
+                  whenHashIs: "#"
+                  path: "currentSection"
+                  value: "Home"
+
+            - type: div
+              content: ["→ ", ~.currentSection]
+
+            - type: div
+              content: "Hash change history:"
+              actions:
+                - what: setData
+                  on: hashchange
+                  path: "hashChangeCount"
+                  value: 1
+                  when: ~.hashChangeCount
+                  isEmpty: true
+
+            - type: div
+              content: ["Changes detected: ", ~.hashChangeCount]
+
+      data:
+        currentSection: "Home"
+        hashChangeCount: 0
+
+  - type: Markdown
+    content: |
+      ## System Integration
+
+      - **EventDispatcherContext**: Uses the global event system to optimize performance
+      - **TemplateSystem**: The `whenHashIs` and `whenHashWas` values are evaluated through the template system
+      - **GlobalDataContext**: Provides context for reaction execution
+      - **Actions.jsx**: Automatically instantiated when `on: "hashchange"` is detected
+
+      ## Limitations
+
+      - Only works with `on: "hashchange"` in actions (not as a standalone element)
+      - Only works on hash changes (URL fragment)
+      - Depends on ReactiveJSON's global event system
+      - Hashes must include the '#' character (e.g., "#section1", not "section1")
+      - One reaction per action definition (use multiple actions for multiple reactions)
+
+      ## Technical Details
+
+      - Automatically instantiated by the Actions system when `on: "hashchange"` is used
+      - Uses `useEffect` to subscribe/unsubscribe to events
+      - Reaction functions are imported from `ReactOnEvent.jsx`
+      - Optimized to avoid too many real DOM listeners through the context system
+      - Automatically cleans up listeners when component unmounts 

package/public/rjbuild/component-doc/core/action/Hide.md

@@ -0,0 +1,22 @@
+# Hide
+
+**Description**: Completely hides the element and cancels any subsequent actions.
+
+## Properties
+- None
+
+## Behavior
+- The element and its children are not rendered in the DOM.
+- Subsequent actions are not executed.
+
+## Example
+```yaml
+renderView:
+  - type: div
+    content: "This text will be hidden."
+    actions:
+      - what: hide
+```
+
+## Limitation
+- The element no longer exists in the DOM, so no events can be attached to it. 

package/public/rjbuild/component-doc/core/action/Hide.yaml

@@ -0,0 +1,60 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Hide
+
+      **Description**: Completely hides the element and cancels any subsequent actions.
+
+      ## Properties
+      - None
+
+      ## Behavior
+      - The element and its children are not rendered in the DOM.
+      - Subsequent actions are not executed.
+
+  - type: RjBuildDescriber
+    title: "Hide Action Example"
+    description:
+      - type: Markdown
+        content: |
+          This example shows how the `hide` action completely removes an element from the DOM based on a condition.
+          
+          Try toggling the visibility to see how the `hide` action works differently from just making something invisible.
+
+    toDescribe:
+      renderView:
+        - type: div
+          content:
+            - type: button
+              content: "Toggle visibility"
+              actions:
+                - what: setData
+                  on: click
+                  path: "shouldHide"
+                  value: ~.shouldHide
+                  is: false
+                - what: setData
+                  on: click
+                  path: "shouldHide"
+                  value: ~.shouldHide
+                  is: true
+                  when: ~.shouldHide
+                  is: false
+
+            - type: div
+              content: "This text will be hidden when shouldHide is true."
+              actions:
+                - what: hide
+                  when: ~.shouldHide
+                  is: true
+
+            - type: div
+              content: ["Current state: shouldHide = ", ~.shouldHide]
+
+      data:
+        shouldHide: false
+
+  - type: Markdown
+    content: |
+      ## Limitation
+      - The element no longer exists in the DOM, so no events can be attached to it. 

package/public/rjbuild/component-doc/core/action/MessageListener.md

@@ -0,0 +1,93 @@
+# MessageListener
+
+**Description**: Executes a reaction when receiving a message via `window.postMessage`. This is an internal action component that is automatically used when you specify `on: "message"` in your actions.
+
+## Usage
+
+MessageListener is **not** used directly as an element type. Instead, it is automatically triggered when you use `on: "message"` in any action. The system automatically adds this component to listen for messages globally on the window object.
+
+## Properties
+
+When using `on: "message"` in actions, you can specify:
+
+- `what` (required): name of the reaction function to execute (e.g., `setData`, `fetchData`, `submitData`, etc.)
+- `whenMessageIs` (optional): message value to react to (deep comparison with the received message data)
+- All other properties are passed as arguments to the reaction function
+
+## Behavior
+
+When you use `on: "message"` in an action:
+
+1. The system automatically adds a MessageListener component
+2. It listens to messages via the global event system (`EventDispatcherContext`)
+3. When a message is received:
+   - Checks if the message origin matches the current window's origin (security measure)
+   - If `whenMessageIs` is defined, performs a deep comparison with the message data
+   - If conditions are met, executes the reaction function specified in `what`
+
+## Examples
+
+### React to specific message
+```yaml
+renderView:
+  - type: button
+    content: "Click me"
+    actions:
+      - what: setData
+        on: message
+        whenMessageIs:
+          type: "userAction"
+          action: "update"
+        path: "lastMessage"
+        value: "Message received"
+```
+
+### React to any message
+```yaml
+renderView:
+  - type: div
+    content: "Waiting for messages..."
+    actions:
+      - what: setData
+        on: message
+        path: "messageReceived"
+        value: true
+```
+
+### Store message data
+```yaml
+renderView:
+  - type: div
+    content: "Message handler"
+    actions:
+      - what: setData
+        on: message
+        whenMessageIs:
+          actor: "parent"
+        path: "parentMessage"
+        value: ~.message
+```
+
+## System Integration
+
+- **EventDispatcherContext**: Uses the global event system to optimize performance
+- **TemplateSystem**: The `whenMessageIs` value is evaluated through the template system
+- **GlobalDataContext**: Provides context for reaction execution
+- **Actions.jsx**: Automatically instantiated when `on: "message"` is detected
+
+## Limitations
+
+- Only works with `on: "message"` in actions (not as a standalone element)
+- Only messages from the same `origin` are accepted (security measure)
+- Depends on ReactiveJSON's global event system
+- Uses deep comparison with lodash's `isEqual` for message matching
+- One reaction per action definition (use multiple actions for multiple reactions)
+
+## Technical Details
+
+- Automatically instantiated by the Actions system when `on: "message"` is used
+- Uses `useEffect` to subscribe/unsubscribe to events
+- Reaction functions are imported from `ReactOnEvent.jsx`
+- Optimized to avoid too many real DOM listeners through the context system
+- Automatically cleans up listeners when component unmounts
+- Security: Only accepts messages from the same origin as the current window 

package/public/rjbuild/component-doc/core/action/MessageListener.yaml

@@ -0,0 +1,153 @@
+renderView:
+  - type: Markdown
+    content: |
+      # MessageListener
+
+      **Description**: Executes a reaction when receiving a message via `window.postMessage`. This is an internal action component that is automatically used when you specify `on: "message"` in your actions.
+
+      ## Usage
+
+      MessageListener is **not** used directly as an element type. Instead, it is automatically triggered when you use `on: "message"` in any action. The system automatically adds this component to listen for messages globally on the window object.
+
+      ## Properties
+
+      When using `on: "message"` in actions, you can specify:
+
+      - `what` (required): name of the reaction function to execute (e.g., `setData`, `fetchData`, `submitData`, etc.)
+      - `whenMessageIs` (optional): message value to react to (deep comparison with the received message data)
+      - All other properties are passed as arguments to the reaction function
+
+  - type: RjBuildDescriber
+    title: "MessageListener Example"
+    description:
+      - type: Markdown
+        content: |
+          This example demonstrates message listening. The buttons below will send messages to the same window to demonstrate the functionality.
+          
+          **Note**: In real usage, messages would typically come from parent windows, iframes, or other origins.
+
+    toDescribe:
+      renderView:
+        - type: div
+          content:
+            - type: div
+              content: "Message listener is active. Send messages:"
+
+            - type: button
+              content: "Send 'hello' message"
+              actions:
+                - what: postMessage
+                  on: click
+                  message:
+                    type: "greeting"
+                    text: "hello"
+                  messageTarget: self
+
+            - " "
+
+            - type: button
+              content: "Send 'update' message"
+              actions:
+                - what: postMessage
+                  on: click
+                  message:
+                    type: "action"
+                    command: "update"
+                  messageTarget: self
+
+            - " "
+
+            - type: button
+              content: "Send custom message"
+              actions:
+                - what: postMessage
+                  on: click
+                  message:
+                    type: "custom"
+                    data: ~.customData
+                  messageTarget: self
+
+            - type: div
+              content: "Message receiver:"
+              actions:
+                - what: setData
+                  on: message
+                  whenMessageIs:
+                    type: "greeting"
+                    text: "hello"
+                  path: "receivedMessage"
+                  value: "Received hello greeting!"
+                - what: setData
+                  on: message
+                  whenMessageIs:
+                    type: "action"
+                    command: "update"
+                  path: "receivedMessage"
+                  value: "Received update command!"
+                - what: setData
+                  on: message
+                  path: "lastMessage"
+                  value: "Any message received"
+
+            - type: div
+              content: ["Last received: ", ~.receivedMessage]
+
+            - type: div
+              content: ["Message indicator: ", ~.lastMessage]
+
+            - type: div
+              content: "Custom data for next message:"
+
+            - type: input
+              attributes:
+                type: text
+                value: ~.customData
+                placeholder: "Enter custom data"
+              actions:
+                - what: setData
+                  on: change
+                  path: "customData"
+                  value: ~.event.target.value
+
+            - type: button
+              content: "Clear messages"
+              actions:
+                - what: setData
+                  on: click
+                  path: "receivedMessage"
+                  value: ""
+                - what: setData
+                  on: click
+                  path: "lastMessage"
+                  value: ""
+
+      data:
+        receivedMessage: ""
+        lastMessage: ""
+        customData: "test data"
+
+  - type: Markdown
+    content: |
+      ## System Integration
+
+      - **EventDispatcherContext**: Uses the global event system to optimize performance
+      - **TemplateSystem**: The `whenMessageIs` value is evaluated through the template system
+      - **GlobalDataContext**: Provides context for reaction execution
+      - **Actions.jsx**: Automatically instantiated when `on: "message"` is detected
+
+      ## Limitations
+
+      - Only works with `on: "message"` in actions (not as a standalone element)
+      - Only messages from the same `origin` are accepted (security measure)
+      - Depends on ReactiveJSON's global event system
+      - Uses deep comparison with lodash's `isEqual` for message matching
+      - One reaction per action definition (use multiple actions for multiple reactions)
+
+      ## Technical Details
+
+      - Automatically instantiated by the Actions system when `on: "message"` is used
+      - Uses `useEffect` to subscribe/unsubscribe to events
+      - Reaction functions are imported from `ReactOnEvent.jsx`
+      - Optimized to avoid too many real DOM listeners through the context system
+      - Automatically cleans up listeners when component unmounts
+      - Security: Only accepts messages from the same origin as the current window 

package/public/rjbuild/component-doc/core/action/Popover.md

@@ -0,0 +1,26 @@
+# Popover
+
+**Description**: Displays a Bootstrap popover on click or hover of the element.
+
+## Properties
+- `header` (optional): content of the popover header
+- `body`: content of the popover body
+- `placement` (optional): position (`top`, `bottom`, `left`, `right`)
+- `trigger` (optional): trigger event (`click`, `hover`, etc.)
+
+## Example
+```yaml
+renderView:
+  - type: button
+    content: "Click me"
+    actions:
+      - what: popover
+        header: "Popover Title"
+        body: "This is the popover content."
+        placement: right
+        trigger: click
+```
+
+## Limitation
+- Requires Bootstrap CSS.
+- The child component must be able to accept a React reference. 

package/public/rjbuild/component-doc/core/action/Popover.yaml

@@ -0,0 +1,100 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Popover
+
+      **Description**: Displays a Bootstrap popover on click or hover of the element.
+
+      ## Properties
+      - `header` (optional): content of the popover header
+      - `body`: content of the popover body
+      - `placement` (optional): position (`top`, `bottom`, `left`, `right`)
+      - `trigger` (optional): trigger event (`click`, `hover`, etc.)
+
+  - type: RjBuildDescriber
+    title: "Popover Action Example"
+    description:
+      - type: Markdown
+        content: |
+          This example shows different popover configurations with various triggers and placements.
+          
+          **Note**: Popovers require Bootstrap CSS to display properly.
+
+    toDescribe:
+      renderView:
+        - type: div
+          content:
+            - type: button
+              content: "Click me (popover right)"
+              actions:
+                - what: popover
+                  header: "Popover Title"
+                  body: "This is the popover content on the right."
+                  placement: right
+                  trigger: click
+
+            - " "
+
+            - type: button
+              content: "Hover me (popover top)"
+              actions:
+                - what: popover
+                  header: "Hover Popover"
+                  body: "This popover appears on hover."
+                  placement: top
+                  trigger: hover
+
+            - type: br
+
+            - type: br
+
+            - type: button
+              content: "Click me (popover bottom)"
+              actions:
+                - what: popover
+                  body: "This popover has no header and appears at the bottom."
+                  placement: bottom
+                  trigger: click
+
+            - " "
+
+            - type: button
+              content: "Dynamic popover content"
+              actions:
+                - what: popover
+                  header: "Dynamic Content"
+                  body: ["Counter value: ", ~.counter]
+                  placement: left
+                  trigger: click
+
+            - type: br
+
+            - type: br
+
+            - type: button
+              content: "Increment counter"
+              actions:
+                - what: setData
+                  on: click
+                  path: "counter"
+                  value: 1
+                  when: ~.counter
+                  isEmpty: true
+                - what: setData
+                  on: click
+                  path: "counter" 
+                  value: ~.counter
+                  isNot: ""
+                  # Note: This would need arithmetic operation, simplified for demo
+
+            - type: div
+              content: ["Current counter: ", ~.counter]
+
+      data:
+        counter: 0
+
+  - type: Markdown
+    content: |
+      ## Limitation
+      - Requires Bootstrap CSS.
+      - The child component must be able to accept a React reference. 

package/public/rjbuild/component-doc/core/action/ReactOnEvent.md

@@ -0,0 +1,81 @@
+# 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.
+
+## How it Works
+
+When you define actions with event handlers (like `on: "click"`), the Actions system automatically:
+
+1. Collects all reactions with event handlers for the element
+2. Groups them by event type (click, change, mouseover, etc.)
+3. Creates a ReactOnEvent component that attaches the appropriate event listeners
+4. Wraps the target element with these event handlers
+
+## Usage Pattern
+
+Instead of using ReactOnEvent directly, you define reactions in the `actions` array of any element:
+
+```yaml
+renderView:
+  - type: button
+    content: "Click me"
+    actions:
+      - what: setData
+        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 MessageListener component (listens on window)
+- `on: "hashchange"` → Uses HashChangeListener 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
+```
+
+## Technical Implementation
+
+- **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
+
+## 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