@ea-lab/reactive-json-docs/public/rjbuild/docs/core/reaction/triggerEvent.yaml

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

renderView:
  - type: Markdown
    content: |
      # Reaction: triggerEvent

      The `triggerEvent` reaction programmatically dispatches an event on one or more target elements found via a CSS selector.

      ## Properties

  - type: DefinitionList
    content:
      - term:
          code: eventName
          after: "(string, required)"
        details:
          type: Markdown
          content: "The name of the event to dispatch on the target element(s) (e.g., `click`, `focus`)"
      - term:
          code: selector
          after: "(string, required)"
        details: "A CSS selector to identify the target element(s) that will receive the event"
      - term:
          code: selectorBase
          after: "(string, optional)"
        details:
          type: Markdown
          content: |
            Defines the starting point for the `selector` search.
            - If omitted, the search starts from the `document` root.
            - If set to `'currentEventTarget'`, the search starts from the element that triggered the reaction.
            - If set to another CSS selector, the search starts from the closest ancestor matching that selector.

  - type: Markdown
    content: |
      ## Behavior

      - When triggered, the reaction searches for elements matching the `selector` within the scope defined by `selectorBase`.
      - It then dispatches a new DOM event of type `eventName` on each found element.
      - The event bubbles up the DOM (`bubbles: true`).
      - To ensure reliable event dispatch on multiple targets, especially for synchronous events like `click`, the reaction dispatches events sequentially using Promises.

      ## Limitations

      - The target elements must exist in the DOM when the reaction is triggered.
      - The behavior depends on the target element having an event listener for the dispatched `eventName`.
      - Complex events with custom data are not supported; it dispatches a standard `Event`.

  - type: RjBuildDescriber
    title: "Triggering a click on another element"
    description: |
      In this example, clicking the first button (`Trigger a click...`) does not update the status directly. Instead, it dispatches a `click` event on the second button (`Update the status`). The second button has its own `click` reaction that updates the status. Therefore, clicking either button will result in the same final action: the status text gets updated.
    toDescribe:
      renderView:
        - type: button
          content: "Trigger a click on the other button"
          actions:
            - what: triggerEvent
              on: click
              eventName: "click"
              selector: "#target-button"
        - type: button
          content: "Update the status"
          attributes:
            id: "target-button"
          actions:
            - what: setData
              on: click
              path: ~.status
              value: "Clicked!"
        - type: div
          content: ["Status: ", ~.status]
      data:
        status: "Not clicked"