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

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

@@ -0,0 +1,403 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Actions System
+
+      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 enable the UI to adapt automatically based on the application's state. They differ from [reactions](./reactions), which execute in response to user events; actions are evaluated continuously based on data conditions.
+
+  - type: Markdown
+    content: |
+      ## Basic Syntax
+
+      Actions are defined as part of the `actions` array on any element. Each action has the following structure:
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: what
+        details: "The type of action to execute."
+      - term:
+          code: when
+          after: " (optional)"
+        details:
+          type: Markdown
+          content: "Data field reference to evaluate for the condition that determines when the action should execute. Supports various conditional operators: `is`, `isNot`, `isEmpty`, `contains`, `containsNot`, `containedBy`, `containedByNot`, numeric comparisons (`>`, `<`, `>=`, `<=`), and complex conditions (`andConditions`, `orConditions`). For detailed information about each condition type, see the [conditional operators reference](#conditional-operators) below."
+
+  - type: Markdown
+    content: |
+      In addition to these core properties, actions support action-specific properties that vary depending on the action type. For example, a `hide` action only requires the condition properties, while a `redirect` action needs a `to` property specifying the destination URL.
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      renderView:
+        - type: CheckBoxField
+          dataLocation: ~.show_advanced
+          options:
+            - value: true
+              label: "Show advanced settings"
+
+        - type: div
+          content: "Advanced Settings Panel"
+          actions:
+            - what: hide              # Action type
+              when: ~.show_advanced    # Condition to evaluate
+              isNot: true              # Expected value
+
+  - type: RjBuildDescriber
+    title: "Basic Action Demonstration"
+    description:
+      - type: Markdown
+        content: |
+          This example demonstrates how actions adapt the UI based on application state.
+          
+          When you check the checkbox, the "Advanced Settings Panel" becomes visible. The action continuously evaluates the condition and shows/hides content accordingly.
+
+    toDescribe:
+      renderView:
+        - type: CheckBoxField
+          dataLocation: ~.show_advanced
+          options:
+            - value: true
+              label: "Show advanced settings"
+
+        - type: div
+          content: "Basic Settings"
+          attributes:
+            style:
+              padding: "15px"
+              border: "2px solid var(--bs-border-color, #dee2e6)"
+              borderRadius: "8px"
+              margin: "10px 0"
+
+        - type: div
+          content: "Advanced Settings Panel"
+          attributes:
+            style:
+              padding: "15px"
+              border: "2px dashed var(--bs-border-color, #dee2e6)"
+              borderRadius: "8px"
+              margin: "10px 0"
+              fontStyle: "italic"
+          actions:
+            - what: hide              # Action type
+              when: ~.show_advanced    # Condition to evaluate
+              isNot: true              # Expected value
+
+      data:
+        show_advanced: false
+
+  - type: Markdown
+    content: |
+      ## Action Types
+
+      Reactive-JSON provides several built-in actions:
+
+      ### Visibility Control
+      - **[hide](../core/action/Hide)**: Completely hides the element and its children
+      - **[visuallyHide](../core/action/VisuallyHide)**: Visually hides the element while keeping it accessible to screen readers
+
+      ### User Interaction
+      - **[tooltip](../core/action/Tooltip)**: Displays a tooltip on hover
+      - **[popover](../core/action/Popover)**: Shows a more complex popover on click
+
+      ### Navigation
+      - **[redirect](../core/action/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: 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..."
+
+        - type: div
+          content:
+            - type: div
+              content: "This shows only when status is 'active'"
+              attributes:
+                style:
+                  padding: "10px"
+                  border: "1px solid var(--bs-border-color, #dee2e6)"
+                  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"
+                  border: "1px solid var(--bs-border-color, #dee2e6)"
+                  margin: "5px 0"
+              actions:
+                - what: hide
+                  when: ~.text_input
+                  isEmpty: true
+
+      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: "var(--bs-danger, #dc3545)"
+                  fontSize: "14px"
+              actions:
+                - what: hide
+                  andConditions:
+                    - when: ~.form.name
+                      isNotEmpty:
+                    - when: ~.form.email
+                      isNotEmpty:
+                  
+            - type: button
+              content: "Submit"
+              attributes:
+                style:
+                  border: "1px solid var(--bs-border-color, #dee2e6)"
+                  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: "var(--bs-success, #198754)"
+                  marginTop: "10px"
+                  fontWeight: "bold"
+              actions:
+                - what: hide
+                  when: ~.submitted
+                  isNot: true
+
+      data:
+        form:
+          name: ""
+          email: ""
+        submitted: false
+
+  - type: h2
+    content: "Conditional Operators"
+    attributes:
+      id: conditional-operators
+
+  - type: Markdown
+    content: |
+      Actions support the following conditional operators when using the `when` property:
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: is
+        details: "Value equals exactly the specified value."
+      - term:
+          code: isNot
+        details: "Value is different from the specified value."
+      - term:
+          code: isEmpty
+        details:
+          type: Markdown
+          content: "Value is empty (null, undefined, empty string, empty array, or empty object). The presence of the property is sufficient (value doesn't matter, can be `null` in JSON). Use `isEmpty:` to check if empty, or `isEmpty: \"not\"` to check if not empty (alternatively, use `isNotEmpty:`)."
+      - term:
+          code: isNotEmpty
+        details:
+          type: Markdown
+          content: "Value is not empty (shorthand for `isEmpty: \"not\"`). The presence of the property is sufficient - the value doesn't matter and can be `null` in JSON."
+      - term:
+          code: contains
+        details: "Value contains the specified substring or array element."
+      - term:
+          code: containsNot
+        details: "Value does not contain the specified substring or array element."
+      - term:
+          code: containedBy
+        details: "Value is contained within the specified array or string."
+      - term:
+          code: containedByNot
+        details: "Value is not contained within the specified array or string."
+      - term:
+          code: ">"
+        details: "Value is greater than the specified number or date."
+      - term:
+          code: "<"
+        details: "Value is less than the specified number or date."
+      - term:
+          code: ">="
+        details: "Value is greater than or equal to the specified number or date."
+      - term:
+          code: "<="
+        details: "Value is less than or equal to the specified number or date."
+      - term:
+          code: andConditions
+          after: " (array)"
+        details:
+          type: Markdown
+          content: |
+            All nested conditions must be true for the action to execute.
+            
+            ```yaml
+            # Example: Hide when both status is active AND user has admin role
+            andConditions:
+              - when: ~.status
+                is: "active"
+              - when: ~.user_role
+                is: "admin"
+            ```
+      - term:
+          code: orConditions
+          after: " (array)"
+        details: "At least one nested condition must be true for the action to execute."
+
+  - type: Markdown
+    content: |
+
+      ## Execution Order
+      - Actions are evaluated in the order they appear in the array.
+      - Conditions are evaluated before action execution.
+      - Some actions (like `hide`) prevent subsequent actions from executing.
+
+      ## State-Driven Behavior
+      - Actions continuously evaluate their conditions based on current data.
+      - No explicit triggers needed - they respond automatically to data changes.
+      - Perfect for creating adaptive interfaces that respond to application state.
+
+  - 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
+
+      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.
+
+      ## Next Steps
+
+      Now that you understand how actions work to adapt the UI based on application state, learn about **[Reactions](./reactions)** to handle user events and trigger behaviors in response to user interactions.
+
+      Actions and reactions work together to create fully interactive applications: actions provide state-driven UI adaptation, while reactions enable event-driven behavior.
+
+      ## Related Documentation
+
+      - **[Reactions System](./reactions)**: Learn about handling user events and state changes.
+      - **[Template System](../getting-started/template-contexts-data-binding)**: Understand data binding and template expressions.

package/public/rjbuild/docs/{getting-started.md → getting-started/index.md}

@@ -1,5 +1,29 @@
 # Reactive-JSON Getting Started Guide
 
+
+
+## Topics
+
+- **[RjBuild structure](rjbuild-structure.md)**:
+- **[Template system](template-contexts-data-binding.md)**:
+- **[Actions](actions.md)**: Make the UI reflect the state of the app.
+- **[Reactions](reactions.md)**: Bring interactivity to your app, such as performing HTTP requests, edit the app state on events…
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 ## Introduction
 
 Reactive-JSON is a powerful library that allows you to create interactive user interfaces using only JSON/YAML configurations. No need to write complex JavaScript code - simply define your interface and its behavior declaratively.
@@ -53,7 +77,7 @@ data:
   isAdmin: true
 ```
 
-> 💡 **Advanced navigation:** For complex hierarchical data access, see the [Template System documentation](/docs/template) which covers `~>key` and `~~>key` notations.
+> 💡 **Advanced navigation:** For complex hierarchical data access, see the [Template System documentation](/docs/getting-started/template-contexts-data-binding) which covers `~>key` and `~~>key` notations.
 
 ### Basic Elements
 
@@ -152,8 +176,8 @@ data:
 
 ## Next Steps
 
-1. Explore the [complete examples](/docs/core/example) to see Reactive-JSON in action
-2. Check out the [elements documentation](/docs/core/element) to discover all available components
-3. Learn how to use the [action system](/docs/core/action) to create interactive interfaces
-4. Discover the [reaction system](/docs/core/reaction) to handle user interactions
-5. If needed, learn how to [extend Reactive-JSON](/docs/extend) with your own components 
+Now that you have an overview of Reactive-JSON, continue with the getting started guide to master the fundamentals:
+
+**[RjBuild Structure](./rjbuild-structure)** - Learn about the core structure of Reactive-JSON configurations and how data, templates, and views work together.
+
+This systematic approach will give you a solid foundation for building interactive applications with Reactive-JSON. 

package/public/rjbuild/docs/{getting-started.yaml → getting-started/index.yaml}

@@ -3,6 +3,22 @@ renderView:
     content: |
       # Reactive-JSON Getting Started Guide
 
+      > Dev note: This page needs to be rewritten.
+
+      
+      ## Topics
+
+      - **[RjBuild structure](rjbuild-structure)**:
+      - **[Template, contexts, and data binding](template-contexts-data-binding)**:
+      - **[Actions](actions)**: Make the UI reflect the state of the app.
+      - **[Reactions](reactions)**: Bring interactivity to your app, such as performing HTTP requests, edit the app state on events…
+      
+
+
+
+
+
+      
       ## Introduction
 
       Reactive-JSON is a powerful library that allows you to create interactive user interfaces using only JSON/YAML configurations. No need to write complex JavaScript code - simply define your interface and its behavior declaratively.
@@ -39,7 +55,7 @@ renderView:
       - `~.` : Local context (relative to current template)
       - `~~.` : Global context (access to global data)
 
-      > 💡 **Advanced navigation:** For complex hierarchical data access, see the [Template System documentation](/docs/template) which covers `~>key` and `~~>key` notations.
+      > 💡 **Advanced navigation:** For complex hierarchical data access, see the [Template System documentation](/docs/getting-started/template-contexts-data-binding) which covers `~>key` and `~~>key` notations.
 
   - type: RjBuildDescriber
     title: "Template System Example"
@@ -217,8 +233,8 @@ renderView:
     content: |
       ## Next Steps
 
-      1. Explore the [complete examples](/docs/core/example) to see Reactive-JSON in action
-      2. Check out the [elements documentation](/docs/core/element) to discover all available components
-      3. Learn how to use the [action system](/docs/core/action) to create interactive interfaces
-      4. Discover the [reaction system](/docs/core/reaction) to handle user interactions
-      5. If needed, learn how to [extend Reactive-JSON](/docs/extend) with your own components 
+      Now that you have an overview of Reactive-JSON, continue with the getting started guide to master the fundamentals:
+
+      **[RjBuild Structure](./rjbuild-structure)** - Learn about the core structure of Reactive-JSON configurations and how data, templates, and views work together.
+
+      This systematic approach will give you a solid foundation for building interactive applications with Reactive-JSON.