@ea-lab/reactive-json-docs 0.1.2

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

@@ -0,0 +1,96 @@
+# addData
+
+## Introduction
+
+`addData` is a reaction that allows adding data at a specified path in the application's data context. It's particularly useful for appending new items to arrays or adding new properties to objects.
+
+## Properties
+- `path` (string, required): The location where the data should be added (using template path syntax with `~` or `~~`). If the path does not exist, it will be created automatically.
+- `value` (any, optional): The data to add. Can be any valid JSON value (string, number, object, array).
+
+## Behavior
+- If the path doesn't exist, it will be created automatically
+- For arrays, the value is appended to the end
+- For objects, the value must be an object with a single key
+- The operation is atomic and synchronous
+
+## Data Management
+The value is evaluated using the template system before being added.
+
+### Adding to Arrays
+If the target path is an array, the value is appended to the end of the array. The value can be a string, number, object, or array.
+
+### Adding to Objects
+If the target path is an object, the value must be an object with a single key. The key will be used as the new property name, and the value as its value.
+
+Example:
+```yaml
+actions:
+  - what: addData
+    on: click
+    path: ~.user
+    value:
+      role: "admin"  # Adds a new property 'role' to the user object
+```
+
+## Complete Examples
+
+### Adding to an Array
+```yaml
+renderView:
+  - type: button
+    content: Add Item
+    actions:
+      - what: addData
+        on: click
+        path: ~.items
+        value: "New Item"
+
+data:
+  items: ["Item 1", "Item 2"]
+```
+
+### Adding to an Object
+```yaml
+renderView:
+  - type: button
+    content: Add Property
+    actions:
+      - what: addData
+        on: click
+        path: ~.user
+        value:
+          role: "admin"
+
+data:
+  user:
+    name: "John"
+    email: "john@example.com"
+```
+
+### Adding with Dynamic Values
+```yaml
+renderView:
+  - type: TextField
+    label: "New Item"
+    dataLocation: ~.new_item
+  - type: button
+    content: Add
+    actions:
+      - what: addData
+        on: click
+        path: ~.items
+        value: ~.new_item
+        when: ~.new_item
+        isEmpty: not
+
+data:
+  items: []
+  new_item: ""
+```
+
+## Limitations
+- Cannot add data to non-object/non-array paths
+- The path must be valid according to the template system rules
+- The value must be serializable
+- For objects, the value must be an object with a single key 

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

@@ -0,0 +1,133 @@
+renderView:
+  - type: Markdown
+    content: |
+      # addData
+
+      `addData` is a reaction that allows adding data at a specified path in the application's data context. It's particularly useful for appending new items to arrays or adding new properties to objects.
+
+      ## Properties
+      - `path` (string, required): The location where the data should be added (using template path syntax with `~` or `~~`). If the path does not exist, it will be created automatically.
+      - `value` (any, optional): The data to add. Can be any valid JSON value (string, number, object, array).
+
+      ## Behavior
+      - If the path doesn't exist, it will be created automatically
+      - For arrays, the value is appended to the end
+      - For objects, the value must be an object with a single key
+      - The operation is atomic and synchronous
+
+      ## Data Management
+      The value is evaluated using the template system before being added.
+
+      ### Adding to Arrays
+      If the target path is an array, the value is appended to the end of the array. The value can be a string, number, object, or array.
+
+      ### Adding to Objects
+      If the target path is an object, the value must be an object with a single key. The key will be used as the new property name, and the value as its value.
+
+      Example:
+      ```yaml
+      actions:
+        - what: addData
+          on: click
+          path: ~.user
+          value:
+            role: "admin"  # Adds a new property 'role' to the user object
+      ```
+
+      ## Complete Examples
+
+      ### Adding to an Array
+      ```yaml
+      renderView:
+        - type: button
+          content: Add Item
+          actions:
+            - what: addData
+              on: click
+              path: ~.items
+              value: "New Item"
+
+      data:
+        items: ["Item 1", "Item 2"]
+      ```
+
+      ### Adding to an Object
+      ```yaml
+      renderView:
+        - type: button
+          content: Add Property
+          actions:
+            - what: addData
+              on: click
+              path: ~.user
+              value:
+                role: "admin"
+
+      data:
+        user:
+          name: "John"
+          email: "john@example.com"
+      ```
+
+      ### Adding with Dynamic Values
+      ```yaml
+      renderView:
+        - type: TextField
+          label: "New Item"
+          dataLocation: ~.new_item
+        - type: button
+          content: Add
+          actions:
+            - what: addData
+              on: click
+              path: ~.items
+              value: ~.new_item
+              when: ~.new_item
+              isEmpty: not
+
+      data:
+        items: []
+        new_item: ""
+      ```
+
+  - type: RjBuildDescriber
+    title: "Interactive Example: Add User to Array"
+    description:
+      - type: Markdown
+        content: |
+          The button below adds a new user (with empty name and email) to the `users` array. Each user is displayed with a form using the `Switch` component and the `user_form` template.
+    toDescribe:
+      renderView:
+        - type: button
+          content: Add user
+          actions:
+            - what: addData
+              on: click
+              path: ~.users
+              value:
+                name: ""
+                email: ""
+        - type: Switch
+          content: ~.users
+          singleOption:
+            load: user_form
+      templates:
+        user_form:
+          - type: TextField
+            label: Name
+            dataLocation: ~.name
+          - type: TextField
+            label: Email
+            dataLocation: ~.email
+      data:
+        users:
+          - name: "John"
+            email: "john@example.com"
+  - type: Markdown
+    content: |
+      ## Limitations
+
+      - Cannot add data to non-object/non-array paths
+      - The path must be valid according to the template system rules
+      - The value must be serializable
+      - For objects, the value must be an object with a single key 

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

@@ -0,0 +1,60 @@
+# Reactive-JSON fetchData Documentation
+
+## Introduction
+`fetchData` is a reaction that allows making HTTP GET requests to a server. It operates in two distinct modes, depending on the value of `refreshAppOnResponse`.
+
+## Properties
+- `url` (string, required): The URL to call (must be a static string, dynamic URLs are not supported)
+- `refreshAppOnResponse` (boolean, optional): If true (default), the response must be a valid rjbuild and will replace the application state. If false, the response is ignored (webhook mode).
+
+## Behavior
+- Only GET requests are supported
+- Only one request can be active at a time
+- The URL is evaluated via the template system before sending, but must resolve to a static string
+- If `refreshAppOnResponse` is true, the response must be a valid rjbuild and will replace the application state
+- If `refreshAppOnResponse` is false, the response is ignored (webhook mode)
+- Errors are only logged to the console
+- The triggering element is visually disabled during the request
+
+## Examples
+
+### Data Loading (with Refresh)
+```yaml
+renderView:
+  - type: button
+    content: Load Data
+    actions:
+      - what: fetchData
+        on: click
+        url: "/api/users"
+        refreshAppOnResponse: true  # Response will replace the application state
+```
+
+### Simple Call (Webhook Style)
+```yaml
+renderView:
+  - type: button
+    content: Notify Server
+    actions:
+      - what: fetchData
+        on: click
+        url: "/api/notify"
+        refreshAppOnResponse: false  # Response is ignored, like a webhook
+```
+
+## Use Cases with refreshAppOnResponse: false
+1. Server notifications
+2. Webhooks
+3. API pinging
+4. Triggering server-side actions without waiting for response
+
+## Limitations
+- Only one request can be active at a time
+- Only GET requests are supported
+- Response must be a valid rjbuild **only** 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/fetchData.yaml

@@ -0,0 +1,156 @@
+renderView:
+  - type: Markdown
+    content: |
+      # fetchData
+
+      fetchData is a reaction that allows making HTTP GET requests to a server. It operates in two distinct modes:
+
+      The behavior depends on `refreshAppOnResponse`:
+      - If `true` (default): Response must be a valid rjbuild (with renderView/templates/data) as it will be used to re-render the application
+      - If `false`: Response is completely ignored - useful for webhook-like calls or server notifications
+
+      **Important**: Dynamic URLs are not supported. URLs must be static strings.
+
+      ## Properties
+      - `url` (string, required): The URL to call (must be a static string, dynamic URLs are not supported)
+      - `refreshAppOnResponse` (boolean, optional): If true (default), the response must be a valid rjbuild and will replace the application state. If false, the response is ignored (webhook mode).
+
+      ## Behavior
+      - Only GET requests are supported
+      - Only one request can be active at a time
+      - The URL is evaluated via the template system before sending, but must resolve to a static string
+      - If `refreshAppOnResponse` is true, the response must be a valid rjbuild and will replace the application state
+      - If `refreshAppOnResponse` is false, the response is ignored (webhook mode)
+      - Errors are only logged to the console
+      - The triggering element is visually disabled during the request
+
+  - type: RjBuildDescriber
+    title: Basic Structure
+    description:
+      - type: Markdown
+        content: |
+          The basic structure of a fetchData reaction requires a URL and can include the refreshAppOnResponse option.
+
+          The URL can be a template value that resolves to a static string.
+    toDescribe:
+      renderView:
+        - type: button
+          content: Basic Example
+          actions:
+            - what: fetchData
+              on: click
+              url: "/mockup-api/fetchData/example.json"
+              refreshAppOnResponse: true  # Response will replace the application state
+        - type: div
+          content:
+            - "URL: "
+            - "/mockup-api/fetchData/example.json"
+        - type: div
+          content:
+            - "Fetch status: "
+            - ~.fetch_status
+      data:
+        fetch_status: "Waiting for click"
+
+  - type: RjBuildDescriber
+    title: Webhook Mode
+    description:
+      - type: Markdown
+        content: |
+          With `refreshAppOnResponse: false`, fetchData behaves like a webhook:
+          - Response is completely ignored
+          - Only the HTTP call is made
+          - Useful for:
+            * Server notifications
+            * Triggering server-side actions
+            * API pinging
+            * Sending webhooks
+    toDescribe:
+      renderView:
+        - type: button
+          content: Notify Server
+          actions:
+            - what: fetchData
+              on: click
+              url: "/mockup-api/fetchData/status.json"
+              refreshAppOnResponse: false  # Response is ignored, like a webhook
+        - type: div
+          content:
+            - "Last call: "
+            - ~.last_status
+      data:
+        last_status: "Not made"
+
+  - type: RjBuildDescriber
+    title: Error Handling
+    description:
+      - type: Markdown
+        content: |
+          Errors are logged to the console but don't trigger a reload.
+
+          The triggering element is visually disabled during the request.
+
+          **Limitation**: No built-in error handling beyond console logging.
+    toDescribe:
+      renderView:
+        - type: button
+          content: Test Error
+          actions:
+            - what: fetchData
+              on: click
+              url: "/mockup-api/fetchData/error.json"
+        - type: div
+          content:
+            - "Status: "
+            - ~.error_state
+      data:
+        error_state: "Pending"
+
+  - type: Markdown
+    content: |
+      ## Limitations
+
+      - Only one request can be active at a time
+      - Only GET requests are supported
+      - Response must be a valid rjbuild **only** 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
+
+  - type: Markdown
+    content: |
+      ## Styling Fetching State (CSS)
+      You can visually disable form controls during a fetchData request using CSS. The system is the same as for submitData:
+
+      ### 1. Target only the fetching control (button, input, etc.)
+      The element that triggered the fetch 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 fetch
+      While a fetch 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. 

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

@@ -0,0 +1,236 @@
+# Reactive-JSON Reactions System Documentation
+
+## Introduction
+
+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. In the RjBuild, reactions are defined under the `actions` key, just like regular actions, but are distinguished by the presence of the `on` property.
+
+### Basic Structure
+```yaml
+renderView:
+  - type: button
+    content: Click me
+    actions:
+      - what: setData    # Reaction type
+        on: click        # Event that triggers the reaction
+        path: ~.my_state # Where to store the data
+        value: "on"      # Value to set
+```
+
+## 1. Basic Reactions
+
+### 1.1 Data Management
+- `addData` : Adds new data to the specified path
+- `setData` : Sets data at the specified path
+- `removeData` : Removes data from the specified path
+- `moveData` : Moves data from one path to another
+
+### 1.2 Network Operations
+- `fetchData` : Fetches data from a URL
+- `submitData` : Submits data to a server endpoint
+
+### 1.3 Browser Operations
+- `setClipboardData` : Copies data to the clipboard
+- `redirectNow` : Performs an immediate redirect
+- `triggerEvent` : Triggers a custom event
+- `postMessage` : Sends a message to another window/frame
+
+## 2. Reaction Structure
+Each reaction is defined by:
+- `what` : The name of the reaction to execute
+- `on` : The event that triggers the reaction
+- Reaction-specific options (vary by reaction type)
+- **Optional conditions** : Reactions support the same conditional system as actions
+
+### 2.1 Conditional Reactions
+Just like actions, reactions can be made conditional using various comparison operators:
+
+- `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
+
+For example:
+```yaml
+actions:
+  - what: setData              # Reaction name
+    on: click                  # Triggering event
+    path: ~.user.profile       # Reaction-specific option
+    value: ~.form_data         # Reaction-specific option
+    when: ~.is_editing         # Condition - only execute if editing
+    is: true                   # Condition value
+  - what: submitData           # Reaction name
+    on: submit                 # Triggering event
+    url: "/api/endpoint"       # Reaction-specific option
+    method: "POST"             # Reaction-specific option
+    data: ~.form_data          # Reaction-specific option
+    when: ~.form_data          # Condition - only submit if form has data
+    isEmpty: "not"             # Condition check
+  - what: setData              # Multiple conditions example
+    on: click
+    path: ~.result
+    value: "success"
+    andConditions:             # All conditions must be true
+      - when: ~.user.role
+        is: "admin"
+      - when: ~.feature_enabled
+        is: true
+```
+
+## 3. Event Types
+The `on` property accepts standard browser events. These events are the same as those used in standard web development, and their availability depends on the HTML element type. For example, a `change` event will only work on form elements like `input`, `select`, or `textarea`, while a `click` event works on any element.
+
+Common event types:
+- `click` : Mouse click (works on any element)
+- `change` : Form input change (works on form elements only)
+- `submit` : Form submission (works on form elements only)
+- `keydown` : Keyboard key press (works on elements that can receive focus)
+- `keyup` : Keyboard key release (works on elements that can receive focus)
+
+## 4. Event Control
+The `stopPropagation` property can be used to control event bubbling and subsequent actions:
+```yaml
+actions:
+  - what: setData
+    on: click
+    path: ~.state
+    value: "on"
+    stopPropagation: true  # Prevents event bubbling AND stops execution of subsequent actions
+```
+
+When `stopPropagation` is set to `true`, it:
+1. Prevents the event from bubbling up to parent elements
+2. Stops the execution of any subsequent actions defined for the same event
+
+This is particularly useful when you want to ensure that only the first matching action is executed, even if multiple actions are defined for the same event.
+
+## 5. Technical Details
+- Reactions are triggered by events
+- Multiple reactions can be defined for the same event
+- Reactions are executed in order
+- Reactions can be chained together
+- **Reactions support all the same conditional operators as actions**: `when`, `is`, `isNot`, `isEmpty`, `contains`, `>`, `<`, `>=`, `<=`, `andConditions`, `orConditions`
+- Conditional reactions only execute when their conditions evaluate to true
+- The execution order of multiple reactions on the same event is guaranteed to match their order in the YAML
+- If a reaction's conditions are not met, it is skipped and the next reaction is evaluated
+
+## 6. Limitations
+- Reactions cannot modify external state
+- Network operations must be properly configured
+- Browser operations require appropriate permissions
+
+## 7. Complete Examples
+
+### 7.1 Data Input and Submission
+```yaml
+renderView:
+  - type: TextField
+    label: "Username"
+    placeholder: "Enter your username"
+    dataLocation: ~.form_data.username
+  - type: TextField
+    label: "Email"
+    placeholder: "Enter your email"
+    inputType: "email"
+    dataLocation: ~.form_data.email
+  - type: button
+    content: Submit
+    actions:
+      - what: submitData
+        on: click
+        url: "/api/submit"
+        data:
+          username: ~.form_data.username
+          email: ~.form_data.email
+        when: ~.form_data.username
+        isEmpty: not
+
+data:
+  form_data:
+    username: ""
+    email: ""
+```
+
+### 7.2 Conditional Reactions Example
+```yaml
+renderView:
+  - type: button
+    content: "Toggle State"
+    actions:
+      - what: setData
+        on: click
+        path: ~.button_state
+        value: "on"
+        when: ~.button_state
+        is: "off"
+        stopPropagation: true
+      - what: setData
+        on: click
+        path: ~.button_state
+        value: "off"
+        when: ~.button_state
+        is: "on"
+        stopPropagation: true
+  - type: div
+    content: ["Button state: ", ~.button_state]
+  - type: div
+    content: "Button has been clicked!"
+    actions:
+      - what: hide
+        when: ~.button_state
+        is: "off"
+
+data:
+  button_state: "off"
+```
+
+### 7.3 Complex Conditional Logic
+```yaml
+renderView:
+  - type: TextField
+    label: "Enter a number:"
+    dataLocation: ~.user_input
+    inputType: "number"
+  - type: button
+    content: "Process Number"
+    actions:
+      - what: setData
+        on: click
+        path: ~.result
+        value: "Number is valid and positive!"
+        andConditions:
+          - when: ~.user_input
+            isEmpty: "not"
+          - when: ~.user_input
+            ">": 0
+      - what: setData
+        on: click
+        path: ~.result
+        value: "Number must be positive!"
+        when: ~.user_input
+        "<=": 0
+      - what: setData
+        on: click
+        path: ~.result
+        value: "Please enter a number!"
+        when: ~.user_input
+        isEmpty: true
+  - type: div
+    content: ["Result: ", ~.result]
+    actions:
+      - what: hide
+        when: ~.result
+        isEmpty: true
+
+data:
+  user_input: null
+  result: null
+```
+
+## Conclusion
+
+You now have a good understanding of reactions in Reactive-JSON. We've seen how they allow you to respond to user events and perform various operations like data updates and network requests.
+
+To create complete interactive interfaces, you should combine reactions with actions. Actions handle the conditional behavior of elements, while reactions handle user interactions and data updates.
+
+For more information about actions and conditional behavior, check out the [Actions Documentation](../action/index.md).