@ea-lab/reactive-json-docs 0.1.2

package/public/rjbuild/component-doc/core/reaction/removeData.yaml

@@ -0,0 +1,56 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Reaction: removeData
+
+      The `removeData` reaction deletes data from a specific location in the global data context. It can operate in two modes: `path` mode or `target` mode.
+
+  - type: RjBuildDescriber
+    title: "1. Using `path` to remove a specific key"
+    description: "This example shows how to delete a specific user profile field by clicking a button."
+    toDescribe:
+      renderView:
+        - type: div
+          content: ["User email: ", ~.user.email]
+        - type: button
+          content: "Remove Email"
+          actions:
+            - what: removeData
+              on: click
+              path: ~.user.email
+      data:
+        user:
+          name: "John Doe"
+          email: "john.doe@example.com"
+
+  - type: RjBuildDescriber
+    title: "2. Using `target` to remove an item from a list"
+    description: |
+      This example shows a list of users where each user can be removed by clicking a "Remove" button next to their name.
+      The reaction uses `target: currentTemplateData` to identify which item to remove from the list.
+    toDescribe:
+      renderView:
+        - type: Switch
+          content: ~.users
+          singleOption:
+            load: user_item
+      templates:
+        user_item:
+          type: div
+          content:
+            - ~.name
+            - type: button
+              content: "Remove"
+              attributes:
+                style:
+                  marginLeft: 10px
+              actions:
+                - what: removeData
+                  on: click
+                  target: currentTemplateData
+                  parentLevel: 0
+      data:
+        users:
+          - name: "Alice"
+          - name: "Bob"
+          - name: "Charlie" 

package/public/rjbuild/component-doc/core/reaction/setClipboardData.md

@@ -0,0 +1,44 @@
+# Reaction: setClipboardData
+
+## Introduction
+
+The `setClipboardData` reaction copies a specified value to the user's clipboard. This is useful for creating "Copy to clipboard" buttons for sharing information like referral codes, URLs, or any text-based data.
+
+## Properties
+
+- `what` (string, required): The name of the reaction, which must be `setClipboardData`.
+- `on` (string, required): The name of the event that triggers the reaction (e.g., `click`).
+- `value` (any, required): The value to be copied to the clipboard. The value is evaluated, so it can be a literal string or a path to data.
+
+## Behavior
+
+- When triggered, the reaction evaluates the `value` property.
+- If the evaluated value is a string, it uses the `navigator.clipboard.writeText()` API to copy it to the clipboard.
+- If the evaluated value is not a string, the reaction does nothing.
+- An error is logged to the console if the clipboard operation fails (e.g., due to browser permissions).
+
+## Example
+
+### Copying text to the clipboard
+
+This example shows a button that, when clicked, copies the value of `~.shareable_code` to the clipboard.
+
+```yaml
+renderView:
+  - type: div
+    content: "Your code: ~.shareable_code"
+  - type: button
+    content: "Copy Code"
+    actions:
+      - what: setClipboardData
+        on: click
+        value: ~.shareable_code
+data:
+  shareable_code: "ABC-123-XYZ"
+```
+
+## Limitations
+
+- This reaction relies on the Clipboard API, which requires a secure context (HTTPS) to function in most modern browsers.
+- The user may be prompted for permission to access the clipboard, depending on browser settings.
+- The reaction only supports copying string values. Numbers and other types will be converted to strings, but objects and arrays will not be copied. 

package/public/rjbuild/component-doc/core/reaction/setClipboardData.yaml

@@ -0,0 +1,41 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Reaction: setClipboardData
+
+      The `setClipboardData` reaction copies a specified value to the user's clipboard.
+
+      ## Properties
+
+      - `what` (string, required): The name of the reaction, which must be `setClipboardData`.
+      - `on` (string, required): The name of the event that triggers the reaction (e.g., `click`).
+      - `value` (any, required): The value to be copied to the clipboard. The value is evaluated, so it can be a literal string or a path to data.
+
+      ## Behavior
+
+      - When triggered, the reaction evaluates the `value` property.
+      - If the evaluated value is a string, it uses the `navigator.clipboard.writeText()` API to copy it to the clipboard.
+      - If the evaluated value is not a string, the reaction does nothing.
+      - An error is logged to the console if the clipboard operation fails (e.g., due to browser permissions).
+
+      ## Limitations
+
+      - This reaction relies on the Clipboard API, which requires a secure context (HTTPS) to function in most modern browsers.
+      - The user may be prompted for permission to access the clipboard, depending on browser settings.
+      - The reaction only supports copying string values. Numbers and other types will be converted to strings, but objects and arrays will not be copied.
+
+  - type: RjBuildDescriber
+    title: "Copying text to the clipboard"
+    description: "This example shows a button that, when clicked, copies the value of `~.shareable_code` to the clipboard."
+    toDescribe:
+      renderView:
+        - type: div
+          content: ["Your code: ", ~.shareable_code]
+        - type: button
+          content: "Copy Code"
+          actions:
+            - what: setClipboardData
+              on: click
+              value: ~.shareable_code
+      data:
+        shareable_code: "ABC-123-XYZ" 

package/public/rjbuild/component-doc/core/reaction/setData.md

@@ -0,0 +1,93 @@
+# Reaction: setData
+
+## Introduction
+
+The `setData` reaction updates the data at a specific location in the global data context. It is one of the most fundamental reactions for managing state and making applications interactive. It can be used to set simple values, objects, or the result of a template evaluation.
+
+## Properties
+
+- `what` (string, required): The name of the reaction, which must be `setData`.
+- `on` (string, required): The name of the event that triggers the reaction (e.g., `click`, `change`).
+- `path` (string, required): The target location in the data context where the value will be set. It supports `~.` notation for relative paths.
+- `value` (any, required): The value to set at the specified path. This value is evaluated, so it can be a literal, a path to other data, or a template string.
+- **Conditional properties** (optional): Like all reactions, `setData` supports conditional execution using `when`, `is`, `isNot`, `isEmpty`, `contains`, `>`, `<`, `>=`, `<=`, `andConditions`, `orConditions`.
+
+## Behavior
+
+- When triggered by the specified event (`on`), `setData` evaluates the `value` property within the current context.
+- It then updates the data at the location specified by `path`.
+- If the `value` is an object or an array, it is deep-cloned before being set to prevent shared-state mutations.
+- If the `path` does not exist, it will be created.
+
+## Example
+
+### Basic Usage
+
+This example demonstrates how to use `setData` to change a text value when a button is clicked.
+
+```yaml
+renderView:
+  - type: div
+    content: "Current value: ~.myValue"
+  - type: button
+    content: "Set value to 'Hello World'"
+    actions:
+      - what: setData
+        on: click
+        path: ~.myValue
+        value: "Hello World"
+  - type: button
+    content: "Set value to 'Another value'"
+    attributes:
+      style:
+        marginLeft: 5px
+    actions:
+      - what: setData
+        on: click
+        path: ~.myValue
+        value: "Another value"
+data:
+  myValue: "initial value"
+```
+
+### Conditional Usage
+
+This example shows how to use conditions with `setData` to only execute when certain criteria are met.
+
+```yaml
+renderView:
+  - type: TextField
+    dataLocation: ~.username
+    label: "Username:"
+    placeholder: "Enter username"
+  - type: button
+    content: "Set Welcome Message"
+    actions:
+      - what: setData
+        on: click
+        path: ~.message
+        value: ["Welcome, ", ~.username, "!"]
+        when: ~.username
+        isEmpty: "not"
+      - what: setData
+        on: click
+        path: ~.message
+        value: "Please enter a username first"
+        when: ~.username
+        isEmpty: true
+  - type: div
+    content: ~.message
+    actions:
+      - what: hide
+        when: ~.message
+        isEmpty: true
+
+data:
+  username: ""
+  message: ""
+```
+
+## Limitations
+
+- The `path` and `value` properties are mandatory for the reaction to have an effect.
+- When conditions are not met, the reaction is skipped entirely. 

package/public/rjbuild/component-doc/core/reaction/setData.yaml

@@ -0,0 +1,85 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Reaction: setData
+
+      The `setData` reaction updates the data at a specific location in the global data context. It is one of the most fundamental reactions for managing state and making applications interactive. It can be used to set simple values, objects, or the result of a template evaluation.
+
+      ### Properties
+      - `what` (string, required): The name of the reaction, which must be `setData`.
+      - `on` (string, required): The name of the event that triggers the reaction (e.g., `click`, `change`).
+      - `path` (string, required): The target location in the data context where the value will be set. It supports `~.` notation for relative paths.
+      - `value` (any, required): The value to set at the specified path. This value is evaluated, so it can be a literal, a path to other data, or a template string.
+      - **Conditional properties** (optional): Like all reactions, `setData` supports conditional execution using `when`, `is`, `isNot`, `isEmpty`, `contains`, `>`, `<`, `>=`, `<=`, `andConditions`, `orConditions`.
+
+      ### Behavior
+      - When triggered by the specified event (`on`), `setData` evaluates the `value` property within the current context.
+      - It then updates the data at the location specified by `path`.
+      - If the `value` is an object or an array, it is deep-cloned before being set to prevent shared-state mutations.
+      - If the `path` does not exist, it will be created.
+      - If conditions are specified, the reaction only executes when those conditions evaluate to true.
+
+      ### Limitations
+      - The `path` and `value` properties are mandatory for the reaction to have an effect.
+      - When conditions are not met, the reaction is skipped entirely.
+
+  - type: RjBuildDescriber
+    title: "Basic Usage"
+    description: "This example demonstrates how to use `setData` to change a text value when a button is clicked."
+    toDescribe:
+      renderView:
+        - type: div
+          content: ["Current value: ", ~.myValue]
+        - type: button
+          content: "Set value to 'Hello World'"
+          actions:
+            - what: setData
+              on: click
+              path: ~.myValue
+              value: "Hello World"
+        - type: button
+          content: "Set value to 'Another value'"
+          attributes:
+            style:
+              marginLeft: 5px
+          actions:
+            - what: setData
+              on: click
+              path: ~.myValue
+              value: "Another value"
+      data:
+        myValue: "initial value"
+
+  - type: RjBuildDescriber
+    title: "Conditional Usage"
+    description: "This example shows how to use conditions with `setData` to only execute when certain criteria are met."
+    toDescribe:
+      renderView:
+        - type: TextField
+          dataLocation: ~.username
+          label: "Username:"
+          placeholder: "Enter username"
+        - type: button
+          content: "Set Welcome Message"
+          actions:
+            - what: setData
+              on: click
+              path: ~.message
+              value: ["Welcome, ", ~.username, "!"]
+              when: ~.username
+              isEmpty: "not"
+            - what: setData
+              on: click
+              path: ~.message
+              value: "Please enter a username first"
+              when: ~.username
+              isEmpty: true
+        - type: div
+          content: ~.message
+          actions:
+            - what: hide
+              when: ~.message
+              isEmpty: true
+      data:
+        username: ""
+        message: "" 

package/public/rjbuild/component-doc/core/reaction/submitData.md

@@ -0,0 +1,138 @@
+# Reactive-JSON submitData Documentation
+
+## Introduction
+`submitData` is a reaction that allows sending data to a server via HTTP requests (usually POST). It's especially useful for form submissions and API interactions.
+
+- The payload can be customized with the `data` property.
+- Only one submission can be active at a time (global lock).
+- The response can refresh the app (default) or be ignored.
+
+## Properties
+- `url` (string, required): The destination URL for the request
+- `httpMethod` (string, optional): The HTTP method to use (default: "post")
+- `data` (object, optional): The data to send. If not specified, data is sent in an object with the structure `{ data: globalDataContext.templateData }`. If `__state` exists in the context, it is automatically added.
+- `refreshAppOnResponse` (boolean, optional): If true (default), reloads the application with the server response. If false, the response is ignored and **no change is made to the application's state or display** (just like `fetchData`).
+- `submitSilently` (boolean, optional): If true, doesn't apply visual disabling styles during submission
+
+## Behavior
+- Only one submission can be active at a time (global lock)
+- The default HTTP method is POST, but can be customized
+- The payload is either the provided `data` object or the full data context
+- Only the first level of the `data` object is evaluated as templates
+- The server response must be a valid rjbuild if `refreshAppOnResponse` is true
+- If `refreshAppOnResponse` is false, the response is ignored (webhook mode)
+- In case of an error, the submission is cancelled and logged to the console
+- Interface elements are visually disabled during submission (unless `submitSilently` is enabled)
+
+## Submission States & Styling
+The system uses a global locking mechanism to handle submissions:
+- Only one submission can be active at a time for all application roots
+- New submissions are ignored while another is in progress
+- Interface elements are visually disabled (unless `submitSilently` is enabled)
+- The lock is released once the response is received
+
+This limitation is intentional to avoid data consistency issues but may be restrictive in some use cases.
+
+### Styling Submitting State (CSS)
+You can visually disable form controls during submission using CSS. There are two main approaches:
+
+#### 1. Target only the submitting control (button, input, etc.)
+The element that triggered the submission receives `data-is-submitting="true"` during the request:
+
+```css
+input[data-is-submitting="true"],
+button[data-is-submitting="true"],
+select[data-is-submitting="true"],
+textarea[data-is-submitting="true"] {
+  opacity: 0.5;
+  pointer-events: none;
+  cursor: not-allowed;
+}
+```
+
+#### 2. Target all controls globally during submission
+While a submission is in progress, the `<body>` receives `data-html-builder-is-submitting="true"`. You can use this to disable all form controls:
+
+```css
+body[data-html-builder-is-submitting="true"] input,
+body[data-html-builder-is-submitting="true"] button,
+body[data-html-builder-is-submitting="true"] select,
+body[data-html-builder-is-submitting="true"] textarea {
+  opacity: 0.5;
+  pointer-events: none;
+  cursor: not-allowed;
+}
+```
+
+Choose the approach that best fits your UX needs.
+
+## Example
+```yaml
+actions:
+  - what: submitData
+    on: click
+    url: "/mockup-api/submitData/example.json"
+    data:
+      username: ~.form_data.username
+    refreshAppOnResponse: true
+```
+
+## Data Management
+Only the first level of the `data` object is evaluated as templates. For nested objects, you must specify the full path explicitly.
+
+Example:
+```yaml
+data:
+  username: ~.form_data.username  # Evaluated
+  profile:
+    name: ~.user.name            # Not evaluated (static)
+    email: ~.user.email          # Not evaluated (static)
+```
+
+If `data` is not specified, the entire `data` context is sent as `{ data: ... }`.
+
+### __state Property
+`__state` is a special property that is automatically added to the payload when sending data if it exists in the global context. It allows transmitting the application state to the server.
+
+Example usage in a multi-screen form:
+```yaml
+# State sent to server
+data:
+  form_data:
+    username: "john"
+    email: "john@example.com"
+  __state:
+    current_screen: "step2"
+    previous_screen: "step1"
+    form_progress: 50
+
+# Server response
+data:
+  form_data:
+    username: "john"
+    email: "john@example.com"
+  __state:
+    current_screen: "step3"
+    previous_screen: "step2"
+    form_progress: 75
+    validation_status: "success"
+```
+
+This bidirectional state synchronization allows to:
+- Validate that the progression is consistent
+- Adapt the response based on the current screen
+- Manage navigation between screens
+- Save progression state
+- Maintain consistency between client and server
+
+## Limitations
+- Only one submission can be active at a time (global lock)
+- Only the first level of the `data` object is evaluated as templates
+- Only POST (or custom method) requests are supported
+- The server response must be a valid rjbuild if `refreshAppOnResponse` is true
+- No built-in error handling beyond console logging
+- No support for request cancellation
+- No support for timeouts
+- No support for dynamic URLs (URLs must be static strings)
+- No support for query parameters in URL templates
+- No support for complex URL routing or path generation 

package/public/rjbuild/component-doc/core/reaction/submitData.yaml

@@ -0,0 +1,141 @@
+renderView:
+  - type: Markdown
+    content: |
+      # submitData
+
+      `submitData` is a reaction that allows sending data to a server via HTTP requests (usually POST). It's especially useful for form submissions and API interactions.
+
+      - The payload can be customized with the `data` property.
+      - Only one submission can be active at a time (global lock).
+      - The response can refresh the app (default) or be ignored.
+
+      ## Properties
+      - `url` (string, required): The destination URL for the request
+      - `httpMethod` (string, optional): The HTTP method to use (default: "post")
+      - `data` (object, optional): The data to send. If not specified, data is sent in an object with the structure `{ data: globalDataContext.templateData }`. If `__state` exists in the context, it is automatically added.
+      - `refreshAppOnResponse` (boolean, optional): If true (default), reloads the application with the server response. If false, the response is ignored and **no change is made to the application's state or display** (just like `fetchData`).
+      - `submitSilently` (boolean, optional): If true, doesn't apply visual disabling styles during submission
+
+      ## Behavior
+      - Only one submission can be active at a time (global lock)
+      - The default HTTP method is POST, but can be customized
+      - The payload is either the provided `data` object or the full data context
+      - Only the first level of the `data` object is evaluated as templates
+      - The server response must be a valid rjbuild if `refreshAppOnResponse` is true
+      - If `refreshAppOnResponse` is false, the response is ignored (webhook mode)
+      - In case of an error, the submission is cancelled and logged to the console
+      - Interface elements are visually disabled during submission (unless `submitSilently` is enabled)
+
+      ## Submission States & Styling
+      The system uses a global locking mechanism to handle submissions:
+      - Only one submission can be active at a time for all application roots
+      - New submissions are ignored while another is in progress
+      - Interface elements are visually disabled (unless `submitSilently` is enabled)
+      - The lock is released once the response is received
+
+      This limitation is intentional to avoid data consistency issues but may be restrictive in some use cases.
+
+      ### Styling Submitting State (CSS)
+      You can visually disable form controls during submission using CSS. There are two main approaches:
+
+      #### 1. Target only the submitting control (button, input, etc.)
+      The element that triggered the submission receives `data-is-submitting="true"` during the request:
+
+      ```css
+      input[data-is-submitting="true"],
+      button[data-is-submitting="true"],
+      select[data-is-submitting="true"],
+      textarea[data-is-submitting="true"] {
+        opacity: 0.5;
+        pointer-events: none;
+        cursor: not-allowed;
+      }
+      ```
+
+      #### 2. Target all controls globally during submission
+      While a submission is in progress, the `<body>` receives `data-html-builder-is-submitting="true"`. You can use this to disable all form controls:
+
+      ```css
+      body[data-html-builder-is-submitting="true"] input,
+      body[data-html-builder-is-submitting="true"] button,
+      body[data-html-builder-is-submitting="true"] select,
+      body[data-html-builder-is-submitting="true"] textarea {
+        opacity: 0.5;
+        pointer-events: none;
+        cursor: not-allowed;
+      }
+      ```
+
+      Choose the approach that best fits your UX needs.
+
+      ## Example
+      ```yaml
+      actions:
+        - what: submitData
+          on: click
+          url: "/mockup-api/submitData/example.json"
+          data:
+            username: ~.form_data.username
+          refreshAppOnResponse: true
+      ```
+
+      ## Data Management
+      Only the first level of the `data` object is evaluated as templates. For nested objects, you must specify the full path explicitly.
+
+      Example:
+      ```yaml
+      data:
+        username: ~.form_data.username  # Evaluated
+        profile:
+          name: ~.user.name            # Not evaluated (static)
+          email: ~.user.email          # Not evaluated (static)
+      ```
+
+      If `data` is not specified, the entire `data` context is sent as `{ data: ... }`.
+
+      ### __state Property
+      `__state` is a special property that is automatically added to the payload when sending data if it exists in the global context. It allows transmitting the application state to the server.
+
+      Example usage in a multi-screen form:
+      ```yaml
+      # State sent to server
+      data:
+        form_data:
+          username: "john"
+          email: "john@example.com"
+        __state:
+          current_screen: "step2"
+          previous_screen: "step1"
+          form_progress: 50
+
+      # Server response
+      data:
+        form_data:
+          username: "john"
+          email: "john@example.com"
+        __state:
+          current_screen: "step3"
+          previous_screen: "step2"
+          form_progress: 75
+          validation_status: "success"
+      ```
+
+      This bidirectional state synchronization allows to:
+      - Validate that the progression is consistent
+      - Adapt the response based on the current screen
+      - Manage navigation between screens
+      - Save progression state
+      - Maintain consistency between client and server
+
+      ## Limitations
+      - Only one submission can be active at a time (global lock)
+      - Only the first level of the `data` object is evaluated as templates
+      - Only POST (or custom method) requests are supported
+      - The server response must be a valid rjbuild if `refreshAppOnResponse` is true
+      - No built-in error handling beyond console logging
+      - No support for request cancellation
+      - No support for timeouts
+      - No support for dynamic URLs (URLs must be static strings)
+      - No support for query parameters in URL templates
+      - No support for complex URL routing or path generation
+ 

package/public/rjbuild/component-doc/core/reaction/triggerEvent.md

@@ -0,0 +1,59 @@
+# Reaction: triggerEvent
+
+## Introduction
+
+The `triggerEvent` reaction programmatically dispatches an event on one or more target elements found via a CSS selector. This allows for indirect interactions, such as one button triggering the `click` event of another element, or simulating user actions on specific components.
+
+## Properties
+
+- `what` (string, required): The name of the reaction, must be `triggerEvent`.
+- `on` (string, required): The event that triggers this reaction.
+- `eventName` (string, required): The name of the event to dispatch on the target element(s) (e.g., `click`, `focus`).
+- `selector` (string, required): A CSS selector to identify the target element(s) that will receive the event.
+- `selectorBase` (string, optional): 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.
+
+## 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.
+
+## Example
+
+### Triggering a click on another element
+
+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.
+
+```yaml
+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"
+```
+
+## 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`.