@ea-lab/reactive-json-docs 0.1.2

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

@@ -0,0 +1,254 @@
+renderView:
+  - type: Markdown
+    content: |
+      # 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.
+
+      Reactions enable you to create interactive interfaces that respond to user input, modify application state, communicate with servers, and control browser behavior - all through JSON configuration.
+
+  - type: RjBuildDescriber
+    title: "Basic Reaction Structure"
+    description:
+      - type: Markdown
+        content: |
+          This example demonstrates the fundamental structure of reactions in Reactive-JSON.
+          
+          Reactions are defined as part of the `actions` array on any element and consist of:
+          - `what`: The name of the reaction to execute
+          - `on`: The event that triggers the reaction
+          - **Reaction-specific properties**: Vary depending on the reaction type
+          - **Optional conditions**: Same conditional system as actions
+
+    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
+              isEmpty: "not"             # Condition value
+
+        - type: div
+          content: ["Saved text: ", ~.saved_text]
+          actions:
+            - what: hide                 # Action (no 'on' property)
+              when: ~.saved_text         # Condition
+              isEmpty: true
+
+      data:
+        user_input: ""
+        saved_text: ""
+
+  - type: Markdown
+    content: |
+      ## Reaction Types
+
+      Reactive-JSON provides several built-in reactions:
+
+      ### Data Management
+      - **[setData](setData)**: Sets data at the specified path
+      - **[addData](addData)**: Adds new data to the specified path
+      - **[removeData](removeData)**: Removes data from the specified path
+      - **[moveData](moveData)**: Moves data from one path to another
+
+      ### Network Operations
+      - **[fetchData](fetchData)**: Fetches data from a URL using GET requests
+      - **[submitData](submitData)**: Submits data to a server endpoint using POST/PUT/DELETE
+
+      ### Browser Operations
+      - **[setClipboardData](setClipboardData)**: Copies data to the clipboard
+      - **[redirectNow](redirectNow)**: Performs an immediate redirect
+      - **[triggerEvent](triggerEvent)**: Triggers a custom event
+      - **[postMessage](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 and Conditional Reactions"
+    description:
+      - type: Markdown
+        content: |
+          This example shows different event types and conditional reactions.
+          
+          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`/`keyup`: Keyboard events (works on focusable elements)
+
+    toDescribe:
+      renderView:
+        - type: button
+          content: "Toggle Mode (Click)"
+          actions:
+            - what: setData
+              on: click
+              path: ~.mode
+              value: "editing"
+              when: ~.mode
+              isNot: "editing"
+            - what: setData
+              on: click
+              path: ~.mode
+              value: "viewing"
+              when: ~.mode
+              is: "editing"
+
+        - type: TextField
+          label: "Text field (onChange):"
+          dataLocation: ~.text_value
+          actions:
+            - what: setData
+              on: change
+              path: ~.last_change
+              value: ~.text_value
+              when: ~.mode
+              is: "editing"
+
+        - type: div
+          content: ["Current mode: ", ~.mode]
+
+        - type: div
+          content: ["Last change: ", ~.last_change]
+          actions:
+            - what: hide
+              when: ~.last_change
+              isEmpty: true
+
+      data:
+        mode: "viewing"
+        text_value: ""
+        last_change: ""
+
+  - 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
+              isEmpty: "not"
+            - what: setData
+              on: click
+              path: ~.new_item
+              value: ""
+              when: ~.new_item
+              isEmpty: "not"
+
+        - 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 (see individual reaction documentation for CSS examples) 

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

@@ -0,0 +1,68 @@
+# Reaction: moveData
+
+## Introduction
+
+The `moveData` reaction changes the position of an element within an array in the global data context. This is particularly useful for reordering items in a list, for example, moving an item up or down. Like `removeData`, it can operate in `path` mode or `target` mode.
+
+## Properties
+
+- `what` (string, required): The name of the reaction, which must be `moveData`.
+- `on` (string, required): The name of the event that triggers the reaction.
+- `path` (string, optional): The path to the array element to move. Required if `target` is not used.
+- `target` (string, optional): If set to `currentTemplateData`, the reaction will target the data associated with the current template item.
+- `parentLevel` (number, optional): Used with `target: 'currentTemplateData'`. Specifies how many levels to go up from the current data path to find the element to move.
+- `increment` (integer, required): The number of positions to move the element. A positive integer moves it down (towards the end of the array), and a negative integer moves it up (towards the beginning).
+
+## Behavior
+
+- When triggered, `moveData` repositions an element within an array.
+- **Path Mode**: Identifies the element to move using its full `path`.
+- **Target Mode**: Identifies the element using `target: 'currentTemplateData'`, typically within a `Switch`.
+- The `increment` value determines the direction and magnitude of the move. For example, `increment: 1` moves the item one position down, and `increment: -1` moves it one position up.
+- The reaction has no effect if the target is not an array or if the move is out of bounds.
+
+## Example
+
+### Moving an item in a list
+
+This example demonstrates how to move items up and down in a to-do list. Each item has "Up" and "Down" buttons that trigger the `moveData` reaction.
+
+```yaml
+renderView:
+  - type: Switch
+    content: ~.todos
+    singleOption:
+      load: todo_item
+templates:
+  todo_item:
+    type: div
+    content:
+      - ~.text
+      - type: button
+        content: "Up"
+        attributes: { style: "margin-left: 10px;" }
+        actions:
+          - what: moveData
+            on: click
+            target: currentTemplateData
+            increment: -1
+      - type: button
+        content: "Down"
+        attributes: { style: "margin-left: 5px;" }
+        actions:
+          - what: moveData
+            on: click
+            target: currentTemplateData
+            increment: 1
+data:
+  todos:
+    - text: "Buy milk"
+    - text: "Learn Reactive-JSON"
+    - text: "Build an app"
+```
+
+## Limitations
+
+- The target data must be an element within an array. The reaction will not work on objects.
+- An `increment` must be provided.
+- Moving an element past the beginning or end of the array has no effect (e.g., moving the first item up). 

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

@@ -0,0 +1,71 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Reaction: moveData
+
+      The `moveData` reaction changes the position of an element within an array in the global data context.
+
+      ## Properties
+
+      - `what` (string, required): The name of the reaction, which must be `moveData`.
+      - `on` (string, required): The name of the event that triggers the reaction.
+      - `path` (string, optional): The path to the array element to move. Required if `target` is not used.
+      - `target` (string, optional): If set to `currentTemplateData`, the reaction will target the data associated with the current template item.
+      - `parentLevel` (number, optional): Used with `target: 'currentTemplateData'`. Specifies how many levels to go up from the current data path to find the element to move.
+      - `increment` (integer, required): The number of positions to move the element. A positive integer moves it down (towards the end of the array), and a negative integer moves it up (towards the beginning).
+
+      ## Behavior
+
+      - When triggered, `moveData` repositions an element within an array.
+      - **Path Mode**: Identifies the element to move using its full `path`.
+      - **Target Mode**: Identifies the element using `target: 'currentTemplateData'`, typically within a `Switch`.
+      - The `increment` value determines the direction and magnitude of the move. For example, `increment: 1` moves the item one position down, and `increment: -1` moves it one position up.
+      - The reaction has no effect if the target is not an array or if the move is out of bounds.
+
+      ## Limitations
+
+      - The target data must be an element within an array. The reaction will not work on objects.
+      - An `increment` must be provided.
+      - Moving an element past the beginning or end of the array has no effect (e.g., moving the first item up).
+
+  - type: RjBuildDescriber
+    title: "Moving an item in a list"
+    description: |
+      This example demonstrates how to move items up and down in a to-do list.
+      Each item has "Up" and "Down" buttons that trigger the `moveData` reaction with an `increment` of -1 or 1.
+    toDescribe:
+      renderView:
+        - type: Switch
+          content: ~.todos
+          singleOption:
+            load: todo_item
+      templates:
+        todo_item:
+          type: div
+          content:
+            - ~.text
+            - type: button
+              content: "Up"
+              attributes:
+                style:
+                  marginLeft: 10px
+              actions:
+                - what: moveData
+                  on: click
+                  target: currentTemplateData
+                  increment: -1
+            - type: button
+              content: "Down"
+              attributes:
+                style:
+                  marginLeft: 5px
+              actions:
+                - what: moveData
+                  on: click
+                  target: currentTemplateData
+                  increment: 1
+      data:
+        todos:
+          - text: "Buy milk"
+          - text: "Learn Reactive-JSON"
+          - text: "Build an app" 

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

@@ -0,0 +1,63 @@
+# Reaction: postMessage
+
+## Introduction
+
+The `postMessage` reaction sends a message to another window or frame using the standard `window.postMessage` Web API. This is useful for communication between your Reactive-JSON application and a parent window (if embedded in an iframe) or for other cross-origin communication scenarios.
+
+## Properties
+
+- `what` (string, required): The name of the reaction, must be `postMessage`.
+- `on` (string, required): The event that triggers the reaction (e.g., `click`, `change`).
+- `message` (any, required): The data to send as the message. This value is evaluated and can be any serializable type (string, number, object, array).
+- `messageTarget` (string, optional): The target window for the message. Can be `'parent'` (the default) or `'self'`.
+- `targetOrigin` (string, optional): Specifies the origin of the target window for security. Defaults to the current window's origin (`window.location.origin`). Use `"*"` for any origin, but be aware of the security implications.
+- `includeChangedValue` (boolean, optional): If the trigger event is `change` on an input element, setting this to `true` will add the input's new value to the message payload under the key `changedValue`. Currently, this is only supported for checkboxes.
+
+## Behavior
+
+- When triggered, the reaction evaluates the `message` content.
+- It identifies the target window based on `messageTarget` and the target origin from `targetOrigin`.
+- It sends the evaluated message to the target window using `postMessage`.
+- If `includeChangedValue` is true and the event is a `change` on a supported input, the input's value is added to the message.
+
+## Testing Messages
+
+To verify that messages are being sent correctly, you can add a message event listener in the browser's console:
+
+```javascript
+window.addEventListener("message", (evt) => {
+    console.log("Event data:", JSON.stringify(evt.data));
+});
+```
+
+This will log all received messages to the console, making it easy to debug and verify the message content.
+
+## Example
+
+### Sending a message to a parent window
+
+This example shows how to send a message to a parent frame when a button is clicked. A parent window would need to set up a `message` event listener to receive this data.
+
+```yaml
+renderView:
+  - type: button
+    content: "Send Data to Parent"
+    actions:
+      - what: postMessage
+        on: click
+        message:
+          type: "userAction"
+          payload:
+            user: ~.user.name
+            action: "confirm"
+        # targetOrigin: "https://parent.example.com" # Should be set for security
+data:
+  user:
+    name: "Alice"
+```
+
+## Limitations
+
+- The receiving window must implement an event listener for the `"message"` event to handle the incoming data.
+- For security, you should always specify a precise `targetOrigin` rather than using `*` when possible.
+- `includeChangedValue` currently only supports checkboxes. Other input types are not yet implemented. 

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

@@ -0,0 +1,68 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Reaction: postMessage
+
+      The `postMessage` reaction sends a message to another window or frame using the standard `window.postMessage` Web API.
+
+  - type: BsAlert
+    attributes:
+      variant: warning
+    content:
+      - type: Markdown
+        content: |
+          **Security warning:**
+          The `postMessage` API requires special attention to security. Always set a precise `targetOrigin` and validate the origin and content of received messages. See the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#security_concerns) for best practices.
+
+  - type: Markdown
+    content: |
+      ## Properties
+      - `what` (string, required): The name of the reaction, must be `postMessage`.
+      - `on` (string, required): The event that triggers the reaction (e.g., `click`, `change`).
+      - `message` (any, required): The data to send as the message. This value is evaluated and can be any serializable type (string, number, object, array).
+      - `messageTarget` (string, optional): The target window for the message. Can be `'parent'` (the default) or `'self'`.
+      - `targetOrigin` (string, optional): Specifies the origin of the target window for security. Defaults to the current window's origin (`window.location.origin`). Use `"*"` for any origin, but be aware of the security implications.
+      - `includeChangedValue` (boolean, optional): If the trigger event is `change` on an input element, setting this to `true` will add the input's new value to the message payload under the key `changedValue`. Currently, this is only supported for checkboxes.
+
+      ## Behavior
+      - When triggered, the reaction evaluates the `message` content.
+      - It identifies the target window based on `messageTarget` and the target origin from `targetOrigin`.
+      - It sends the evaluated message to the target window using `postMessage`.
+      - If `includeChangedValue` is true and the event is a `change` on a supported input, the input's value is added to the message.
+
+      ## Limitations
+      - The receiving window must implement an event listener for the `"message"` event to handle the incoming data.
+      - For security, you should always specify a precise `targetOrigin` rather than using `*` when possible.
+      - `includeChangedValue` currently only supports checkboxes. Other input types are not yet implemented.
+
+  - type: RjBuildDescriber
+    title: "Sending a message to the same window"
+    description:
+      - type: Markdown
+        content: |
+          This example shows how to send a message to the same window when a button is clicked.
+          The current window would need to set up a `message` event listener to receive this data.
+
+          To verify that messages are being sent correctly, you can open your browser's console and paste this code:
+          ```javascript
+          window.addEventListener("message", (evt) => {
+              console.log("Event data:", JSON.stringify(evt.data));
+          });
+          ```
+          Then try the example below and watch the console for messages.
+
+    toDescribe:
+      renderView:
+        - type: button
+          content: "Send Data"
+          actions:
+            - what: postMessage
+              on: click
+              message:
+                type: "userAction"
+                payload:
+                  user: "Alice"
+                  action: "confirm"
+              # targetOrigin: "https://parent.example.com" # Should be set for security
+              messageTarget: self # For demo purposes, we target self
+ 

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

@@ -0,0 +1,37 @@
+# Reaction: redirectNow
+
+## Introduction
+
+The `redirectNow` reaction performs an immediate browser redirection to a specified URL. It is useful for navigating to a new page after an action is completed, such as after submitting a form or clicking a link.
+
+## Properties
+
+- `what` (string, required): The name of the reaction, which must be `redirectNow`.
+- `on` (string, required): The name of the event that triggers the reaction (e.g., `click`).
+- `to` (string, required): The URL to redirect to. This value is evaluated, so it can be a static URL or dynamically constructed from data.
+
+## Behavior
+
+- When triggered, the reaction evaluates the `to` property to get the target URL.
+- It then sets `window.location.href` to the resulting URL, causing the browser to navigate to the new page.
+
+## Example
+
+### Redirecting to a URL
+
+This example shows a button that redirects the user to the Reactive-JSON GitHub page when clicked.
+
+```yaml
+renderView:
+  - type: button
+    content: "Visit GitHub"
+    actions:
+      - what: redirectNow
+        on: click
+        to: "https://github.com/reactive-json/reactive-json"
+```
+
+## Limitations
+
+- The `to` property must resolve to a valid URL string for the redirection to work.
+- This action causes a full page reload, which will reset the entire application state. 

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

@@ -0,0 +1,37 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Reaction: redirectNow
+
+      The `redirectNow` reaction performs an immediate browser redirection to a specified URL.
+
+      ## Properties
+
+      - `what` (string, required): The name of the reaction, which must be `redirectNow`.
+      - `on` (string, required): The name of the event that triggers the reaction (e.g., `click`).
+      - `to` (string, required): The URL to redirect to. This value is evaluated, so it can be a static URL or dynamically constructed from data.
+
+      ## Behavior
+
+      - When triggered, the reaction evaluates the `to` property to get the target URL.
+      - It then sets `window.location.href` to the resulting URL, causing the browser to navigate to the new page.
+
+      ## Limitations
+
+      - The `to` property must resolve to a valid URL string for the redirection to work.
+      - This action causes a full page reload, which will reset the entire application state.
+
+      **Note**: Since this example performs a real redirection, clicking the button will navigate you away from this page.
+
+  - type: RjBuildDescriber
+    title: "Redirecting to a URL"
+    description: "This example shows a button that redirects the user to the Reactive-JSON GitHub page when clicked."
+    toDescribe:
+      renderView:
+        - type: button
+          content: "Visit GitHub"
+          actions:
+            - what: redirectNow
+              on: click
+              to: "https://github.com/reactive-json/reactive-json"
+ 

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

@@ -0,0 +1,78 @@
+# Reaction: removeData
+
+## Introduction
+
+The `removeData` reaction deletes data from a specific location in the global data context. It is essential for dynamically managing lists, removing items, or clearing parts of the application state. It can operate in two modes: `path` mode (to target a specific data location) or `target` mode (to target the current template's data).
+
+## Properties
+
+- `what` (string, required): The name of the reaction, which must be `removeData`.
+- `on` (string, required): The name of the event that triggers the reaction (e.g., `click`).
+- `path` (string, optional): The target location in the data context to delete. Required if `target` is not used.
+- `target` (string, optional): If set to `currentTemplateData`, the reaction will remove the data associated with the current template item.
+- `parentLevel` (number, optional): Used with `target: 'currentTemplateData'`. Specifies how many levels to go up from the current data path before removing. `0` means the current level.
+
+## Behavior
+
+- When triggered, `removeData` deletes the data at the specified location.
+- **Path Mode**: If `path` is provided, the data at that exact location is removed.
+- **Target Mode**:
+    - If `target` is `'currentTemplateData'`, the reaction targets the data of the component triggering the action.
+    - `parentLevel` can be used to traverse up the data hierarchy. For example, in a list of items, `parentLevel: 0` would target the item itself, allowing for its deletion from the parent list/object.
+
+## Examples
+
+### 1. Using `path` to remove a specific key
+
+This example shows how to delete a specific user profile field by clicking a button.
+
+```yaml
+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"
+```
+
+### 2. Using `target` to remove an item from a list
+
+This example shows a list of users where each user can be removed by clicking a "Remove" button next to their name. The reaction targets the current item in the iteration.
+
+```yaml
+renderView:
+  - type: Switch
+    content: ~.users
+    singleOption:
+      load: user_item
+templates:
+  user_item:
+    type: div
+    content:
+      - ~.name
+      - type: button
+        content: "Remove"
+        attributes: { style: "margin-left: 10px;" }
+        actions:
+          - what: removeData
+            on: click
+            target: currentTemplateData
+            parentLevel: 0
+data:
+  users:
+    - name: "Alice"
+    - name: "Bob"
+    - name: "Charlie"
+```
+
+## Limitations
+
+- Either `path` or `target` must be provided for the reaction to work.
+- In `target` mode, if `parentLevel` goes beyond the root of the data, the reaction will do nothing.