@ea-lab/reactive-json-docs/public/rjbuild/docs/getting-started/reactions.yaml

Complete documentation for Reactive-JSON - Components, examples and LLM-parsable guides

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.