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

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

@@ -0,0 +1,300 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Reactions System
+
+      Reactions are a fundamental part of Reactive-JSON's interactivity system. They allow you to respond to user events and perform operations like data updates, network requests, and browser interactions - all through JSON configuration. In the RjBuild, reactions are defined under the `actions` key, just like regular actions, but are distinguished by the presence of the `on` property.
+
+      Reactions execute in response to user events (click, change, etc.) to modify application state and trigger behaviors. They differ from [actions](./actions), which continuously adapt the UI based on the current data state; reactions are event-driven while actions are state-driven.
+
+  - type: Markdown
+    content: |
+      ## Basic Syntax
+
+      Reactions are defined as part of the `actions` array on any element. Each reaction has the following core properties:
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: what
+        details: "The name of the reaction to execute."
+      - term:
+          code: on
+        details: "The event that triggers the reaction."
+      - term:
+          code: when
+          after: " (optional)"
+        details:
+          type: Markdown
+          content: "Reactions also support optional conditions to control when the reaction should execute. See the [Actions conditional operators documentation](./actions#conditional-operators) for detailed information about available condition types."
+
+  - type: Markdown
+    content: |
+      Beyond these core properties, reactions include reaction-specific properties that vary depending on the reaction type. For example, a `setData` reaction requires `path` and `value` properties, while a `fetchData` reaction needs a `url` property and optional `method` configuration.
+
+      Reactions also support optional conditions using the same conditional system as actions. This allows you to create sophisticated event-driven behavior that only executes when specific data conditions are met.
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      renderView:
+        - type: button
+          content: "Save Text"
+          actions:
+            - what: setData              # Reaction type
+              on: click                  # Triggering event
+              path: ~.saved_text         # Reaction-specific property
+              value: ~.user_input        # Reaction-specific property
+              when: ~.user_input         # Optional condition
+              isNotEmpty:                # Condition value
+
+  - type: RjBuildDescriber
+    title: "Basic Reaction Demonstration"
+    description:
+      - type: Markdown
+        content: |
+          This example demonstrates how to set data when a button is clicked.
+          
+          On the *Save Text* button, we define a `setData` reaction that will set the text field value
+          in the `saved_text` data location when the button is clicked, but only if the text field is not empty.
+
+    toDescribe:
+      renderView:
+        - type: TextField
+          label: "Enter some text:"
+          dataLocation: ~.user_input
+          placeholder: "Type something..."
+
+        - type: button
+          content: "Save Text"
+          actions:
+            - what: setData              # Reaction type
+              on: click                  # Triggering event
+              path: ~.saved_text         # Reaction-specific property
+              value: ~.user_input        # Reaction-specific property
+              when: ~.user_input         # Optional condition
+              isNotEmpty:             # Condition value
+
+        - type: div
+          content: ["Saved text: ", ~.saved_text]
+          actions:
+            - what: hide                 # Action (no 'on' property)
+              when: ~.saved_text         # Condition
+              isEmpty:
+
+      data:
+        user_input: ""
+        saved_text: ""
+
+  - type: Markdown
+    content: |
+      ## Reaction Types
+
+      Reactive-JSON provides several built-in reactions:
+
+      ### Data Management
+      - **[setData](../core/reaction/setData)**: Sets data at the specified path.
+      - **[addData](../core/reaction/addData)**: Adds new data to the specified path.
+      - **[removeData](../core/reaction/removeData)**: Removes data from the specified path.
+      - **[moveData](../core/reaction/moveData)**: Moves data from one path to another.
+
+      ### Network Operations
+      - **[fetchData](../core/reaction/fetchData)**: Fetches data from a URL using GET requests.
+      - **[submitData](../core/reaction/submitData)**: Submits data to a server endpoint using POST/PUT/DELETE.
+
+      ### Browser Operations
+      - **[setClipboardData](../core/reaction/setClipboardData)**: Copies data to the clipboard.
+      - **[redirectNow](../core/reaction/redirectNow)**: Performs an immediate redirect.
+      - **[triggerEvent](../core/reaction/triggerEvent)**: Triggers a custom event.
+      - **[postMessage](../core/reaction/postMessage)**: Sends a message to another window/frame.
+
+      For detailed documentation of each reaction, including properties and examples, see their respective documentation pages.
+
+  - type: RjBuildDescriber
+    title: "Event Types"
+    description:
+      - type: Markdown
+        content: |
+          This example demonstrates the different event types supported by reactions.
+          
+          Try interacting with the text field below to see which events are triggered:
+          - Type text to trigger `change` events
+          - Click on the field to trigger `click` events  
+          - Hover over the field to trigger `mouseOver` events
+
+    toDescribe:
+      renderView:
+        - type: div
+          content: ["Last event type: ", ~.last_event_type]
+          attributes:
+            style:
+              padding: "10px"
+              border: "1px solid var(--bs-border-color, #dee2e6)"
+              borderRadius: "4px"
+              marginBottom: "10px"
+              fontWeight: "bold"
+
+        - type: TextField
+          label: "Interactive text field:"
+          dataLocation: ~.user_input
+          placeholder: "Click, type, or hover..."
+          actions:
+            - what: setData
+              on: click
+              path: ~.last_event_type
+              value: "click"
+            - what: setData
+              on: change
+              path: ~.last_event_type
+              value: "change"
+            - what: setData
+              on: mouseOver
+              path: ~.last_event_type
+              value: "mouseOver"
+
+      data:
+        last_event_type: "none"
+        user_input: ""
+
+  - type: Markdown
+    content: |
+      Common event types:
+      - `click`: Mouse click (works on any element).
+      - `change`: Form input change (works on form elements only).
+      - `mouseOver`: Mouse hover (works on any element).
+      - `submit`: Form submission (works on form elements only).
+      - `keyDown`/`keyUp`: Keyboard events (works on focusable elements).
+
+      > **Note**: Event names must respect standard React/DOM event naming conventions (camelCase).
+
+  - type: RjBuildDescriber
+    title: "Data Management Example"
+    description:
+      - type: Markdown
+        content: |
+          This example demonstrates the core data management reactions: setData, addData, and removeData.
+
+    toDescribe:
+      renderView:
+        - type: TextField
+          label: "Add item:"
+          dataLocation: ~.new_item
+          placeholder: "Enter item name"
+
+        - type: button
+          content: "Add Item"
+          actions:
+            - what: addData
+              on: click
+              path: ~.items
+              value:
+                name: ~.new_item
+              when: ~.new_item
+              isNotEmpty:
+            - what: setData
+              on: click
+              path: ~.new_item
+              value: ""
+              when: ~.new_item
+              isNotEmpty:
+
+        - type: div
+          content: "Items:"
+          attributes:
+            style:
+              fontWeight: "bold"
+              margin: "10px 0 5px 0"
+
+        - type: Switch
+          content: ~.items
+          singleOption:
+            load: itemTemplate
+
+      templates:
+        itemTemplate:
+          type: div
+          content:
+            - "• "
+            - ~.name
+            - type: button
+              content: " [Remove]"
+              attributes:
+                style:
+                  marginLeft: "10px"
+                  background: "red"
+                  color: "white"
+                  border: "none"
+                  padding: "2px 8px"
+                  fontSize: "12px"
+              actions:
+                - what: removeData
+                  on: click
+                  target: currentTemplateData
+                  parentLevel: 0
+
+      data:
+        new_item: ""
+        items:
+          - name: "Sample item 1"
+          - name: "Sample item 2"
+
+  - type: Markdown
+    content: |
+      ## Advanced Features
+
+      ### Conditional Logic
+      Reactions support the same conditional operators as actions:
+      - `when` + `is`/`isNot`: Value equality checks.
+      - `when` + `isEmpty`: Empty value tests.
+      - `when` + `contains`/`containsNot`: Content search.
+      - `when` + `>`, `<`, `>=`, `<=`: Numeric/date comparisons.
+      - `andConditions`/`orConditions`: Complex condition logic.
+
+      ### Event Control
+      Use `stopPropagation: true` to:
+      1. Prevent event bubbling to parent elements.
+      2. Stop execution of subsequent actions for the same event.
+
+      ### Execution Order
+      - Multiple reactions on the same event execute in the order they are defined.
+      - Reactions with unmet conditions are skipped.
+      - Actions (without `on` property) are evaluated separately from reactions.
+
+  - type: Markdown
+    content: |
+      ## Technical Details
+
+      - Reactions are triggered by DOM events.
+      - Multiple reactions can be defined for the same event.
+      - Reactions are executed in the order they appear in the YAML.
+      - Reactions can be chained together by modifying data that other reactions depend on.
+      - Conditional reactions only execute when their conditions evaluate to true.
+      - The `stopPropagation` property affects both event bubbling and subsequent action execution.
+
+      ## Limitations
+
+      - Event availability depends on the HTML element type (e.g., `change` only works on form elements).
+      - Network operations require proper CORS configuration.
+      - Browser operations require appropriate permissions.
+      - No built-in error handling beyond console logging for network operations.
+      - Only one network request (fetch/submit) can be active at a time.
+      - URLs in network operations must be static strings (dynamic URLs not supported).
+
+      ## Best Practices
+
+      1. **Use descriptive conditions**: Make your conditional logic clear and readable.
+      2. **Handle empty states**: Always consider what happens when data is empty or undefined.
+      3. **Order matters**: Place more specific conditions before general ones.
+      4. **Use stopPropagation wisely**: Only use it when you specifically need to prevent event bubbling or stop action execution.
+      5. **Test network operations**: Ensure your API endpoints return the expected format.
+      6. **Provide user feedback**: Use visual indicators during loading states.
+
+      ## Next Steps
+
+      Congratulations! You've mastered the fundamentals of Reactive-JSON. You now understand how to structure RjBuilds, use templates, and create interactive applications with actions and reactions.
+
+      Ready to take your skills further? Explore the **[Advanced Concepts](../advanced-concepts/index)** to learn about data mapping, custom plugins, and performance optimization techniques.
+
+      ## Related Documentation
+
+      - **[Actions System](./actions)**: Review state-driven UI adaptation.
+      - **[Template System](./template-contexts-data-binding)**: Revisit data binding patterns.

package/public/rjbuild/docs/getting-started/rjbuild-structure.md

@@ -157,7 +157,7 @@ data:
   isLoggedIn: true
 ```
 
-> You can get more information about data access in the [template system documentation](./template.md).
+ > You can get more information about data access in the [template system documentation](./template-contexts-data-binding.md).
 
 ## Section `templates` (Optional)
 
@@ -347,6 +347,12 @@ additionalDataSource:
 3. **Optimized templates**: Avoid overly complex templates
 
 ### Maintainability
-1. **Consistent naming**: Use clear conventions for templates and data
-2. **Documentation**: Comment complex sections
-3. **Validation**: Verify the structure of your external data 
+1. **Consistent naming**: Use clear conventions for templates and data.
+2. **Documentation**: Comment complex sections.
+3. **Validation**: Verify the structure of your external data.
+
+## Next Steps
+
+ Now that you understand the structure of RjBuilds, learn about the **[Template System](./template-contexts-data-binding.md)** to master data binding and create reusable components.
+
+The template system is crucial for building maintainable and dynamic applications with Reactive-JSON. 

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

@@ -183,7 +183,7 @@ renderView:
 
   - type: Markdown
     content: |
-      > You can get more information about data access in the [template system documentation](/docs/getting-started/template).
+      > You can get more information about data access in the [template system documentation](/docs/getting-started/template-contexts-data-binding).
 
       ## Section `templates` (Optional)
 
@@ -406,9 +406,15 @@ renderView:
       3. **Optimized templates**: Avoid overly complex templates
 
       ### Maintainability
-      1. **Consistent naming**: Use clear conventions for templates and data
-      2. **Documentation**: Comment complex sections
-      3. **Validation**: Verify the structure of your external data
+      1. **Consistent naming**: Use clear conventions for templates and data.
+      2. **Documentation**: Comment complex sections.
+      3. **Validation**: Verify the structure of your external data.
+
+      ## Next Steps
+
+      Now that you understand the structure of RjBuilds, learn about the **[Template System](./template-contexts-data-binding)** to master data binding and create reusable components.
+
+      The template system is crucial for building maintainable and dynamic applications with Reactive-JSON.
 
 templates:
 

package/public/rjbuild/docs/getting-started/{template.md → template-contexts-data-binding.md}

@@ -1,6 +1,4 @@
-# Template and Context System
-
-## Introduction
+# Template, Contexts, and Data Binding
 
 The template system in reactive-json efficiently manages data contexts and their access. Understanding how templates "containerize" data is essential for properly using components, actions, and reactions.
 
@@ -110,10 +108,10 @@ data:
       title: "User List"
       config:
         theme: "light"
-      level1:
-        items:
-          - name: "Item 1"
-          # userList template instances run here at: data.config.userSection.level1.items
+        level1:
+          items:
+            - name: "Item 1"
+            # userList template instances run here at: data.config.userSection.config.level1.items
 
 templates:
   userList:
@@ -130,7 +128,7 @@ templates:
 
 renderView:
   - type: Switch
-    content: ~~.config.userSection.level1.items
+    content: ~~.config.userSection.config.level1.items
     singleOption:
       load: userList
 ```
@@ -183,7 +181,13 @@ data:
 
 ## Best Practices
 
-1. **Context Coherence**: Ensure components that need to share data are in the same context
-2. **Global Access**: Use `~~.` for data that needs to be shared between different templates
-3. **Hierarchical Navigation**: Use `~>key` to find nearest occurrence or `~~>key` to find global setting
-4. **Local vs Global**: `~>` prioritizes local overrides, `~~>` prioritizes global settings 
+1. **Context Coherence**: Ensure components that need to share data are in the same context.
+2. **Global Access**: Use `~~.` for data that needs to be shared between different templates.
+3. **Hierarchical Navigation**: Use `~>key` to find nearest occurrence or `~~>key` to find global setting.
+4. **Local vs Global**: `~>` prioritizes local overrides, `~~>` prioritizes global settings.
+
+## Next Steps
+
+Now that you understand the template system and data binding, learn about **[Actions](./actions.md)** to make your interfaces interactive and responsive to data changes.
+
+Actions will allow you to hide, show, and manipulate elements based on the current application state. 

package/public/rjbuild/docs/getting-started/{template.yaml → template-contexts-data-binding.yaml}

@@ -1,14 +1,12 @@
 renderView:
   - type: Markdown
     content: |
-      # Template and Context System
-
-      ## Introduction
+      # Template, Contexts, and Data Binding
 
       The template system in reactive-json efficiently manages data contexts and their access. Understanding how templates "containerize" data is essential for properly using components, actions, and reactions.
 
-  - type: Markdown
-    content: |
+      ## Context Notations
+
       There are four main notations for accessing data:
       
       - `~.` : Local context (relative to current template)
@@ -19,7 +17,9 @@ renderView:
       Each notation is explained with examples below.
 
   - type: RjBuildDescriber
-    title: "Local Context (`~.`)"
+    title:
+      type: Markdown
+      content: "Local Context: `~.`"
     description:
       - type: Markdown
         content: |
@@ -34,7 +34,9 @@ renderView:
         username: "John"
 
   - type: RjBuildDescriber
-    title: "Global Context (`~~.`)"
+    title:
+      type: Markdown
+      content: "Global Context: `~~.`"
     description:
       - type: Markdown
         content: |
@@ -61,7 +63,9 @@ renderView:
         isAdmin: true
 
   - type: RjBuildDescriber
-    title: "Nearest Key (`~>key`)"
+    title:
+      type: Markdown
+      content: "Nearest Key: `~>key`"
     description:
       - type: Markdown
         content: |
@@ -89,7 +93,9 @@ renderView:
                 - name: "Item 1"  # themeDisplay template runs here
 
   - type: RjBuildDescriber
-    title: "Top-level Key (`~~>key`)"
+    title:
+      type: Markdown
+      content: "Top-level Key: `~~>key`"
     description:
       - type: Markdown
         content: |
@@ -193,10 +199,10 @@ renderView:
             title: "User List"
             config:
               theme: "light"
-            level1:
-              items:
-                - name: "Item 1"
-                # userList template instances run here at: data.config.userSection.level1.items
+              level1:
+                items:
+                  - name: "Item 1"
+                  # userList template instances run here at: data.config.userSection.config.level1.items
 
       templates:
         userList:
@@ -213,10 +219,18 @@ renderView:
 
       renderView:
         - type: Switch
-          content: ~~.config.userSection.level1.items
+          content: ~~.config.userSection.config.level1.items
           singleOption:
             load: userList
 
+  - type: Markdown
+    content: |
+      ## Next Steps
+
+      Now that you understand the template system and data binding, learn about **[Actions](./actions)** to make your interfaces interactive and responsive to data changes.
+
+      Actions will allow you to hide, show, and manipulate elements based on the current application state.
+
 templates:
 
 data: {}