@ea-lab/reactive-json-docs/public/rjbuild/docs/core/action/ReactOnEvent.yaml

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

renderView:
  - type: Markdown
    content: |
      # ReactOnEvent

      ReactOnEvent is an internal action component that is automatically instantiated by the Actions system when reactions with event handlers (`on: "eventName"`) are detected.
      
      > **Important**: It should **not** be used directly as an element type. The Reactive-JSON engine will automatically instantiate it when needed.

      ## 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.

      ## Usage Pattern

      Instead of using ReactOnEvent directly, you define reactions in the `actions` array of any element:

      ```yaml
      renderView:
        - type: button
          content: "Click me"
          actions:
            - what: setData
              on: click           # This triggers ReactOnEvent internally
              path: "buttonClicked"
              value: true
      ```

      ## Supported Event Types

      ReactOnEvent supports any DOM event by prefixing with `on` and capitalizing the first letter:

      - `on: click` → `onClick`
      - `on: change` → `onChange`
      - `on: mouseover` → `onMouseOver`
      - `on: keydown` → `onKeyDown`
      - `on: submit` → `onSubmit`
      - etc.

      ## Special Event Handling

      Some events have special handling and **do not** use ReactOnEvent:

      - `on: "message"` → Uses the [MessageListener](MessageListener.md) component (listens on window)
      - `on: "hashchange"` → Uses the [HashChangeListener](HashChangeListener.md) component (listens on window)

      ## Event Propagation Control

      By default, ReactOnEvent stops event propagation. You can control this behavior:

      ```yaml
      actions:
        - what: setData
          on: click
          path: "clicked"
          value: true
          stopPropagation: false  # Allow event to continue propagating
      ```

      ## Event Placeholders

      ReactOnEvent supports special placeholders to access event data:

      - `<reactive-json:event-new-value>`: Returns the most relevant value from form events (checked for checkboxes, value for inputs)
      - `<reactive-json:event>.propertyPath`: Access any event property (e.g., `.data.message` for MessageEvent, `.key` for KeyboardEvent)

      ## Technical Implementation

      - **Event attachment**: Uses React's event system via `cloneElement`
      - **Multiple events**: Can handle multiple event types on the same element
      - **Reaction execution**: Executes reactions in the order they appear
      - **Context preservation**: Maintains access to global and template data contexts
      - **Early termination**: Supports `stopPropagation: true` to halt reaction chain execution

  - 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 Components
      
      - **[MessageListener](MessageListener.md)**: Handles `on: "message"` events
      - **[HashChangeListener](HashChangeListener.md)**: Handles `on: "hashchange"` events
      - **[Reactions System](../../getting-started/reactions.md)**: The actual reaction functions that ReactOnEvent executes