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

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: |

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

@@ -1,214 +1,29 @@
-# Reactive-JSON Actions System Documentation
+# Actions
 
-## Introduction
+> For an introduction to the actions system and detailed examples, see [Getting Started: Actions](../../getting-started/actions.md).
 
-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.
+Actions in Reactive-JSON allow you to modify element behavior and appearance based on dynamic conditions. They are evaluated continuously based on data state and provide state-driven UI adaptation.
 
-This system enables you to create interactive interfaces directly through JSON configuration, without requiring custom JavaScript code.
+## Available Action Components
 
-### Basic Structure
+### Visibility Control
+- **[Hide](./Hide.md)**: Completely hides the element and its children
+- **[VisuallyHide](./VisuallyHide.md)**: Visually hides the element while keeping it accessible to screen readers
 
-```yaml
-renderView:
-  - type: div
-    content: "My content"
-    actions:
-      - what: hide           # Action type
-        when: ~.my_condition # Condition to evaluate
-        is: true             # Expected value
-```
+### User Interaction
+- **[Tooltip](./Tooltip.md)**: Displays a tooltip on hover
+- **[Popover](./Popover.md)**: Shows a more complex popover on click
 
-## How Actions Work
+### Navigation
+- **[Redirect](./Redirect.md)**: Redirects to a specified URL
 
-Actions are defined as an array on any element and are evaluated in the order they appear. Each action consists of:
+### Event Management
 
-- `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)
+Those actions have a special handling in Reactive-JSON. The engine transparently load them
+when the user requests a [reaction](../../getting-started/reactions.md) on a given element component.
 
-### Action Types
+As a user, you won't need to work with them directly.
 
-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
+- **[HashChangeListener](./HashChangeListener.md)**: Listens for URL hash changes
+- **[MessageListener](./MessageListener.md)**: Listens for window messages
+- **[ReactOnEvent](./ReactOnEvent.md)**: Reacts to custom events

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

@@ -1,278 +1,33 @@
 renderView:
   - type: Markdown
     content: |
-      # Reactive-JSON Actions System Documentation
+      # Actions
 
-      ## Introduction
+      > For an introduction to the actions system and detailed examples, see [Getting Started: Actions](../../getting-started/actions).
 
-      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.
+      Actions in Reactive-JSON allow you to modify element behavior and appearance based on dynamic conditions. They are evaluated continuously based on data state and provide state-driven UI adaptation.
 
-      This system enables you to create interactive interfaces directly through JSON configuration, without requiring custom JavaScript code.
+      ## Available Action Components
 
-  - type: RjBuildDescriber
-    title: "Basic Action Structure"
-    description:
-      - type: Markdown
-        content: |
-          This example demonstrates the fundamental structure of actions in Reactive-JSON.
-          
-          Actions are defined as an array on any element and consist 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)
+      ### Visibility Control
+      - **[Hide](./Hide)**: Completely hides the element and its children
+      - **[VisuallyHide](./VisuallyHide)**: Visually hides the element while keeping it accessible to screen readers
 
-    toDescribe:
-      renderView:
-        - type: button
-          content: "Toggle visibility"
-          actions:
-            - what: setData
-              on: click
-              path: ~.my_condition
-              value: false
-              when: ~.my_condition
-              is: true
-              stopPropagation: true
-            - what: setData
-              on: click
-              path: ~.my_condition
-              value: true
-              when: ~.my_condition
-              is: false
-              stopPropagation: true
+      ### User Interaction
+      - **[Tooltip](./Tooltip)**: Displays a tooltip on hover
+      - **[Popover](./Popover)**: Shows a more complex popover on click
 
-        - type: div
-          content: "This content can be hidden"
-          attributes:
-            style:
-              padding: "10px"
-              border: "1px solid #ccc"
-              margin: "5px 0"
-          actions:
-            - what: hide           # Action type
-              when: ~.my_condition # Condition to evaluate
-              is: true             # Expected value
+      ### Navigation
+      - **[Redirect](./Redirect)**: Redirects to a specified URL
 
-      data:
-        my_condition: false
+      ### Event Management
 
-  - type: Markdown
-    content: |
-      ## Action Types
-
-      Reactive-JSON provides several built-in actions:
-
-      - **[hide](Hide)**: Completely hides the element and its children
-      - **[visuallyHide](VisuallyHide)**: Visually hides the element while keeping it accessible to screen readers
-      - **[tooltip](Tooltip)**: Displays a tooltip on hover
-      - **[popover](Popover)**: Shows a more complex popover on click
-      - **[redirect](Redirect)**: Redirects to a specified URL
-
-      For detailed documentation of each action, including properties and examples, see their respective documentation pages.
-
-  - type: RjBuildDescriber
-    title: "Basic Conditional Actions"
-    description:
-      - type: Markdown
-        content: |
-          This example shows simple conditional actions using `is` and `isEmpty` conditions.
-
-    toDescribe:
-      renderView:
-        - type: div
-          content:
-            - type: div
-              content: "This shows only when status is 'active'"
-              attributes:
-                style:
-                  padding: "10px"
-                  backgroundColor: "#e8f5e8"
-                  margin: "5px 0"
-              actions:
-                - what: hide
-                  when: ~.status
-                  isNot: "active"
-                  
-            - type: div
-              content: "This shows only when text is not empty"
-              attributes:
-                style:
-                  padding: "10px"
-                  backgroundColor: "#f0f8ff"
-                  margin: "5px 0"
-              actions:
-                - what: hide
-                  when: ~.text_input
-                  isEmpty: true
-
-        - type: div
-          content:
-            - type: label
-              content: "Status: "
-            - type: SelectField
-              dataLocation: ~.status
-              options:
-                - value: "inactive"
-                  label: "Inactive"
-                - value: "active"
-                  label: "Active"
-                  
-            - type: br
-            
-            - type: label
-              content: "Text: "
-            - type: TextField
-              dataLocation: ~.text_input
-              placeholder: "Type something..."
-
-      data:
-        status: "inactive"
-        text_input: ""
-
-  - type: RjBuildDescriber
-    title: "Tooltip Action Example"
-    description:
-      - type: Markdown
-        content: |
-          This example demonstrates the tooltip action with conditional display.
-
-    toDescribe:
-      renderView:
-        - type: div
-          content:
-            - type: button
-              content: "Hover for help (when enabled)"
-              actions:
-                - what: tooltip
-                  content: "This is a helpful tooltip!"
-                  placement: "top"
-                  when: ~.show_tooltips
-                  is: true
-                  
-            - type: br
-            - type: br
-            
-            - type: label
-              content:
-                - type: CheckBoxField
-                  dataLocation: ~.show_tooltips
-                  options:
-                    - value: true
-                      label: ""
-                - " Enable tooltips"
-
-      data:
-        show_tooltips: true
-
-  - type: RjBuildDescriber
-    title: "Practical Form Example"
-    description:
-      - type: Markdown
-        content: |
-          This example shows a simple form with conditional submit button and validation messages.
-
-    toDescribe:
-      renderView:
-        - type: div
-          content:
-            - type: h4
-              content: "Simple Contact Form"
-              
-            - type: div
-              content:
-                - type: label
-                  content: "Name: "
-                - type: TextField
-                  dataLocation: ~.form.name
-                  placeholder: "Enter your name"
-                      
-            - type: br
-            
-            - type: div
-              content:
-                - type: label
-                  content: "Email: "
-                - type: TextField
-                  dataLocation: ~.form.email
-                  inputType: "email"
-                  placeholder: "Enter your email"
-                      
-            - type: br
-            
-            - type: div
-              content: "Please fill in both fields"
-              attributes:
-                style:
-                  color: "red"
-                  fontSize: "14px"
-              actions:
-                - what: hide
-                  andConditions:
-                    - when: ~.form.name
-                      isEmpty: not
-                    - when: ~.form.email
-                      isEmpty: not
-                  
-            - type: button
-              content: "Submit"
-              attributes:
-                style:
-                  backgroundColor: "#4caf50"
-                  color: "white"
-                  border: "none"
-                  padding: "8px 16px"
-              actions:
-                - what: hide
-                  when: ~.form.name
-                  isEmpty: true
-                - what: hide
-                  when: ~.form.email
-                  isEmpty: true
-                - what: setData
-                  on: click
-                  path: ~.submitted
-                  value: true
-                  
-            - type: div
-              content: "✅ Form submitted successfully!"
-              attributes:
-                style:
-                  color: "green"
-                  marginTop: "10px"
-                  fontWeight: "bold"
-              actions:
-                - what: hide
-                  when: ~.submitted
-                  isNot: true
-
-      data:
-        form:
-          name: ""
-          email: ""
-        submitted: false
-
-  - type: Markdown
-    content: |
-      ## 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
+      Those actions have a special handling in Reactive-JSON. The engine transparently load them
+      when the user requests a [reaction](../../getting-started/reactions) on a given element component.
 
-      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
+      As a user, you won't need to work with them directly.
 
-      ## Related Documentation
+      - **[HashChangeListener](./HashChangeListener)**: Listens for URL hash changes
+      - **[MessageListener](./MessageListener)**: Listens for window messages
+      - **[ReactOnEvent](./ReactOnEvent)**: Reacts to custom events
 
-      - **Individual Action Documentation**: See the dedicated pages for each action type
-      - **[Reactions System](../reaction/index)**: Learn about handling user events and state changes
-      - **[Template System](../../template-system)**: Understand data binding and template expressions