@ea-lab/reactive-json-docs 0.1.2

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

@@ -0,0 +1,133 @@
+renderView:
+  - type: Markdown
+    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.
+
+      ## 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
+
+  - 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.
+
+    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]
+
+        - type: button
+          content: "Reset all"
+          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
+
+      data:
+        clicked: false
+        clickCount: 0
+        inputValue: ""
+        hovered: false
+
+  - type: Markdown
+    content: |
+      ## 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 Documentation
+      
+      - **[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 

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

@@ -0,0 +1,20 @@
+# Redirect
+
+**Description**: Redirects the user to a given URL if the condition is met.
+
+## Properties
+- `to`: destination URL
+
+## Example
+```yaml
+renderView:
+  - type: button
+    content: "Go to Google"
+    actions:
+      - what: redirect
+        to: "https://www.google.com"
+        on: click
+```
+
+## Limitation
+- The redirection is immediate and replaces the current page. 

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

@@ -0,0 +1,68 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Redirect
+
+      **Description**: Redirects the user to a given URL if the condition is met.
+
+      ## 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: div
+              content: ["Redirect allowed: ", ~.allowRedirect]
+
+      data:
+        allowRedirect: false
+
+  - type: Markdown
+    content: |
+      ## Limitation
+      - The redirection is immediate and replaces the current page. 

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

@@ -0,0 +1,22 @@
+# Tooltip
+
+**Description**: Displays a Bootstrap tooltip when hovering over the element.
+
+## Properties
+- `content`: tooltip content (text or component)
+- `placement` (optional): tooltip position (`top`, `bottom`, `left`, `right`)
+
+## Example
+```yaml
+renderView:
+  - type: button
+    content: "Hover me"
+    actions:
+      - what: tooltip
+        content: "This is a tooltip."
+        placement: top
+```
+
+## Limitation
+- Requires Bootstrap CSS.
+- The child component must be able to accept a React reference. 

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

@@ -0,0 +1,90 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Tooltip
+
+      **Description**: Displays a Bootstrap tooltip when hovering over the element.
+
+      ## Properties
+      - `content`: tooltip content (text or component)
+      - `placement` (optional): tooltip position (`top`, `bottom`, `left`, `right`)
+
+  - type: RjBuildDescriber
+    title: "Tooltip Action Example"
+    description:
+      - type: Markdown
+        content: |
+          This example shows different tooltip configurations. Hover over the buttons to see the tooltips in action.
+          
+          **Note**: Tooltips require Bootstrap CSS to display properly.
+
+    toDescribe:
+      renderView:
+        - type: div
+          content:
+            - type: button
+              content: "Hover me (top)"
+              actions:
+                - what: tooltip
+                  content: "This is a tooltip on top."
+                  placement: top
+
+            - " "
+
+            - type: button
+              content: "Hover me (bottom)"
+              actions:
+                - what: tooltip
+                  content: "This is a tooltip on bottom."
+                  placement: bottom
+
+            - " "
+
+            - type: button
+              content: "Hover me (left)"
+              actions:
+                - what: tooltip
+                  content: "This is a tooltip on left."
+                  placement: left
+
+            - " "
+
+            - type: button
+              content: "Hover me (right)"
+              actions:
+                - what: tooltip
+                  content: "This is a tooltip on right."
+                  placement: right
+
+            - type: br
+
+            - type: br
+
+            - type: button
+              content: "Dynamic tooltip"
+              actions:
+                - what: tooltip
+                  content: ["Current time: ", ~.currentTime]
+                  placement: top
+
+            - " "
+
+            - type: button
+              content: "Update time"
+              actions:
+                - what: setData
+                  on: click
+                  path: "currentTime"
+                  value: "Updated!"
+
+            - type: div
+              content: ["Tooltip content: ", ~.currentTime]
+
+      data:
+        currentTime: "Not set"
+
+  - 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/VisuallyHide.md

@@ -0,0 +1,21 @@
+# VisuallyHide
+
+**Description**: Visually hides the element but keeps it in the DOM (useful for accessibility or to keep the element reactive to events).
+
+## Properties
+- None
+
+## Behavior
+- The element is rendered in the DOM but with `display: none`.
+
+## Example
+```yaml
+renderView:
+  - type: div
+    content: "This text will be visually hidden."
+    actions:
+      - what: visuallyHide
+```
+
+## Limitation
+- The element remains in the DOM, which can impact accessibility or performance if overused. 

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

@@ -0,0 +1,62 @@
+renderView:
+  - type: Markdown
+    content: |
+      # VisuallyHide
+
+      **Description**: Visually hides the element but keeps it in the DOM (useful for accessibility or to keep the element reactive to events).
+
+      ## Properties
+      - None
+
+      ## Behavior
+      - The element is rendered in the DOM but with `display: none`.
+
+  - type: RjBuildDescriber
+    title: "VisuallyHide Action Example"
+    description:
+      - type: Markdown
+        content: |
+          This example shows how the `visuallyHide` action makes an element invisible while keeping it in the DOM.
+          
+          Compare with the `hide` action: visually hidden elements can still respond to events and maintain their place in the DOM structure.
+
+    toDescribe:
+      renderView:
+        - type: div
+          content:
+            - type: button
+              content: "Toggle visual hiding"
+              actions:
+                - what: setData
+                  on: click
+                  path: "shouldVisuallyHide"
+                  value: ~.shouldVisuallyHide
+                  is: false
+                - what: setData
+                  on: click
+                  path: "shouldVisuallyHide"
+                  value: ~.shouldVisuallyHide
+                  is: true
+                  when: ~.shouldVisuallyHide
+                  is: false
+
+            - type: div
+              content: "This text will be visually hidden but remains in the DOM."
+              actions:
+                - what: visuallyHide
+                  when: ~.shouldVisuallyHide
+                  is: true
+
+            - type: div
+              content: ["Current state: shouldVisuallyHide = ", ~.shouldVisuallyHide]
+
+            - type: div
+              content: "↑ Notice the space is preserved even when hidden"
+
+      data:
+        shouldVisuallyHide: false
+
+  - type: Markdown
+    content: |
+      ## Limitation
+      - The element remains in the DOM, which can impact accessibility or performance if overused. 

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

@@ -0,0 +1,214 @@
+# Reactive-JSON Actions System Documentation
+
+## Introduction
+
+The Reactive-JSON actions system allows you to modify element behavior and appearance based on dynamic conditions. Actions are applied to individual elements and can control visibility, display tooltips, redirect users, or trigger other behaviors based on the current data state.
+
+This system enables you to create interactive interfaces directly through JSON configuration, without requiring custom JavaScript code.
+
+### Basic Structure
+
+```yaml
+renderView:
+  - type: div
+    content: "My content"
+    actions:
+      - what: hide           # Action type
+        when: ~.my_condition # Condition to evaluate
+        is: true             # Expected value
+```
+
+## How Actions Work
+
+Actions are defined as an array on any element and are evaluated in the order they appear. Each action consists of:
+
+- `what`: The type of action to execute
+- **Action-specific properties**: Vary depending on the action type
+- **Conditional properties**: Define when the action should be executed (optional)
+
+### Action Types
+
+Reactive-JSON provides several built-in actions:
+
+- **[hide](Hide.md)**: Completely hides the element and its children
+- **[visuallyHide](VisuallyHide.md)**: Visually hides the element while keeping it accessible to screen readers
+- **[tooltip](Tooltip.md)**: Displays a tooltip on hover
+- **[popover](Popover.md)**: Shows a more complex popover on click
+- **[redirect](Redirect.md)**: Redirects to a specified URL
+
+For detailed documentation of each action, including properties and examples, see their respective documentation pages.
+
+## Conditional Execution
+
+Actions can be made conditional using various comparison operators. If no conditions are specified, the action will always execute.
+
+### Basic Comparisons
+- `is`: Value equals exactly
+- `isNot`: Value is different from
+
+```yaml
+actions:
+  - what: hide
+    when: ~.status
+    is: "inactive"
+```
+
+### Empty Value Tests
+- `isEmpty: true`: Value is empty (null, undefined, "", [], {})
+- `isEmpty: "not"`: Value is not empty
+
+```yaml
+actions:
+  - what: hide
+    when: ~.user.name
+    isEmpty: true
+```
+
+### Content Search
+- `contains`: Contains a substring or element
+- `containsNot`: Does not contain a substring or element
+- `containedBy`: Value is contained within another value
+- `containedByNot`: Value is not contained within another value
+
+```yaml
+actions:
+  - what: hide
+    when: ~.user.roles
+    contains: "admin"
+```
+
+### Numeric and Date Comparisons
+- `">"`: Greater than
+- `"<"`: Less than  
+- `">="`: Greater than or equal to
+- `"<="`: Less than or equal to
+- `compareAsDates: true`: Compare values as dates
+
+```yaml
+actions:
+  - what: hide
+    when: ~.user.age
+    "<": 18
+```
+
+### Complex Conditions
+- `andConditions`: All conditions must be true
+- `orConditions`: At least one condition must be true
+
+```yaml
+actions:
+  - what: hide
+    andConditions:
+      - when: ~.user.role
+        is: "user"
+      - when: ~.feature_enabled
+        is: false
+```
+
+## Data Integration
+
+Actions use Reactive-JSON's template system with the `~` operator to access data:
+
+- `~.property`: Access a property from the data context
+- `~.object.property`: Navigate through nested objects
+- `~.array[0]`: Access array elements
+
+The template system resolves these paths at runtime and provides the current values for condition evaluation.
+
+## Execution Order and Behavior
+
+1. **Sequential evaluation**: Actions are evaluated in the order they appear in the array
+2. **Condition precedence**: Conditions are evaluated before action execution
+3. **Early termination**: Some actions (like `hide`) prevent subsequent actions from executing
+4. **Synchronous execution**: All condition evaluations and actions are synchronous
+
+## Practical Examples
+
+### Conditional Element Visibility
+
+```yaml
+renderView:
+  - type: div
+    content: "Admin-only section"
+    actions:
+      - what: hide
+        when: ~.user.role
+        isNot: "admin"
+
+  - type: button
+    content: "Advanced feature"
+    actions:
+      - what: hide
+        when: ~.user.permissions
+        containsNot: "advanced_actions"
+
+data:
+  user:
+    role: "user"
+    permissions: ["read", "write"]
+```
+
+### Contextual Help Interface
+
+```yaml
+renderView:
+  - type: label
+    content: "Username"
+    actions:
+      - what: tooltip
+        content: "Use only letters and numbers"
+        placement: "right"
+  
+  - type: button
+    content: "More info"
+    actions:
+      - what: popover
+        title: "Detailed help"
+        content: "Complete instructions..."
+        placement: "top"
+```
+
+### Authentication Flow
+
+```yaml
+renderView:
+  - type: div
+    content: "Access denied"
+    actions:
+      - what: redirect
+        to: "/login"
+        when: ~.user.authenticated
+        is: false
+      
+      - what: hide
+        when: ~.user.authenticated
+        is: true
+
+data:
+  user:
+    authenticated: false
+```
+
+## Technical Limitations
+
+1. **Execution order**: Actions are evaluated in definition order and cannot be reordered dynamically
+2. **Hide behavior**: Once an element is hidden with the `hide` action, no subsequent actions execute
+3. **Synchronous evaluation**: All conditions and actions are evaluated synchronously
+4. **Data scope**: Actions can only access data from the current template context and global context
+5. **No side effects**: Actions cannot directly modify global state or trigger reactions
+6. **External dependencies**: Some actions (tooltip, popover) require React Bootstrap components
+
+## Best Practices
+
+1. **Keep conditions simple**: Avoid overly complex condition logic for better maintainability
+2. **Consider performance**: Minimize frequently-evaluated complex conditions
+3. **Use appropriate actions**: Choose `visuallyHide` over `hide` when content should remain accessible
+4. **Test thoroughly**: Verify action behavior with different data states
+5. **Document complex logic**: Add comments for non-obvious conditional logic
+6. **Order matters**: Place critical actions (like `hide`) early in the action array when appropriate
+
+## Related Documentation
+
+- **Individual Action Documentation**: See the dedicated pages for each action type
+- **[Reactions System](../reaction/index.md)**: Learn about handling user events and state changes
+- **[Template System](../../template-system.md)**: Understand data binding and template expressions