@ea-lab/reactive-json-docs 1.0.0-alpha.0 → 1.1.0

package/public/rjbuild/docs/advanced-concepts/forward-update.yaml

@@ -1,17 +1,11 @@
 renderView:
-  # Version badge reusable component
-  - type: span
-    attributes:
-      class: "badge bg-secondary px-2 py-1"
-    content: "reactive-json@0.0.43"
-
   - type: Markdown
     content: |
-      # Forward Update Pattern (Event Placeholders)
+      # Forward update
 
       > Use the special placeholder `<reactive-json:event>` to reference values coming directly from the DOM or custom event that triggered a reaction.
 
-      The **Forward Update** pattern lets you use the special placeholder `<reactive-json:event>` inside any reaction arguments. 
+      The **Forward update** pattern lets you use the special placeholder `<reactive-json:event>` inside any reaction arguments. 
       It is primarily useful with `setData`, but can be applied to any reaction.  
       Instead of reading a value *after* the global data has been updated, you can forward the fresh value carried by the event itself.
 
@@ -27,10 +21,31 @@ renderView:
 
   - type: Markdown
     content: |
-      `<reactive-json:event-new-value>` returns, in order of priority:
-      1. `event.target.checked` (checkboxes / toggle inputs)  
-      2. `event.target.value` (text inputs, selects, etc.)  
-      3. `undefined` if none of the above exists.
+      ## The `<reactive-json:event-new-value>` shortcut
+
+      `<reactive-json:event-new-value>` automatically detects and returns the most relevant value from different types of events. The extraction logic varies based on the event type and the target element.
+
+      ### Extraction Rules Reference
+
+      | Event Type | Target Element | Logic | Return Value | Example |
+      |------------|----------------|-------|--------------|---------|
+      | **CustomEvent** | Any | Returns `event.detail.value` | Any value from custom event payload | `<reactive-json:event-new-value>.preferences.theme` |
+      | **DOM Event** | `input[type="checkbox"]` | Returns `event.target.checked` | `true` or `false` | `<reactive-json:event-new-value>` → `true` |
+      | **DOM Event** | `input[type="radio"]` | Returns `event.target.value` if checked, otherwise `undefined` | String value or `undefined` | `<reactive-json:event-new-value>` → `"option1"` |
+      | **DOM Event** | `input[type="text"]`, `textarea`, `select` | Returns `event.target.value` | String value | `<reactive-json:event-new-value>` → `"user input"` |
+      | **DOM Event** | Element with `value` property | Returns `event.target.value` | Any value | `<reactive-json:event-new-value>` → `"42"` |
+      | **DOM Event** | Element with `checked` property (fallback) | Returns `event.target.checked` | `true` or `false` | `<reactive-json:event-new-value>` → `false` |
+      | **Any Event** | No applicable property | Returns `undefined` | `undefined` | `<reactive-json:event-new-value>` → `undefined` |
+
+      ### Processing Priority
+      For DOM events, the extraction follows this priority order:
+      1. **Checkbox**: `event.target.checked` (boolean)
+      2. **Radio button**: `event.target.value` only if checked, otherwise `undefined`
+      3. **General case**: `event.target.value` (if property exists)
+      4. **Fallback**: `event.target.checked` (if property exists)
+      5. **Default**: `undefined`
+
+      For CustomEvent objects (like `response` events from `fetchData`), it directly accesses `event.detail.value` and allows further property access with dot notation.
 
       **Good practice**
       - For standard form events (`change`, `input`, etc.), prefer the shortcut `<reactive-json:event-new-value>`.
@@ -43,10 +58,23 @@ renderView:
       
       You can access any nested property (`detail`, `key`, etc.).
 
+      ## Event Types
+
+      ### Standard DOM Events
+      The forward update system works with standard DOM events (`change`, `input`, `click`, etc.) from form elements and other HTML components.
+
+      ### Response Event
+      You can also use the special `response` event with reactions like `fetchData`. This event is triggered when an HTTP request completes successfully, allowing you to access the response data directly.
+
       Typical use-cases:
       - Real-time mirroring of form fields
       - "Select all" checkboxes
-      - Forward arbitrary values coming from events.
+      - Forward arbitrary values coming from events
+      - Process HTTP response data immediately after fetch operations
+
+  - type: Markdown
+    content: |
+      ## Examples
 
   # --- Interactive example: Synchronized CheckBoxes (use-case "Select all")
   - type: RjBuildDescriber
@@ -104,6 +132,48 @@ renderView:
         primary_text: ""
         secondary_text: ""
 
+  - type: Markdown
+    content: |
+      ### Response Event Processing
+
+      This example shows how to use the `response` event to process data returned by an HTTP request. When `fetchData` completes successfully, you can extract specific values from the response and store them in different locations using `<reactive-json:event-new-value>`.
+
+  - type: SyntaxHighlighter
+    language: yaml
+    title: "Response Event Processing"
+    content: |
+      renderView:
+        - type: button
+          content: "Load User Profile"
+          actions:
+            - what: fetchData
+              on: click
+              url: "/api/user-profile.json"
+              updateOnlyData: true
+              updateDataAtLocation: ~~.userProfile
+            - what: setData
+              on: response  # Triggered when fetchData completes
+              path: ~~.userTheme
+              value: <reactive-json:event-new-value>.preferences.theme
+            - what: setData
+              on: response
+              path: ~~.userName
+              value: <reactive-json:event-new-value>.name
+        - type: div
+          content:
+            - "User theme: "
+            - type: code
+              content: ~~.userTheme
+        - type: div
+          content:
+            - "User name: "
+            - type: strong
+              content: ~~.userName
+
+      data:
+        userTheme: "not-loaded"
+        userName: "not-loaded"
+
 templates:
 
 data: {} 

package/public/rjbuild/docs/advanced-concepts/index.md

@@ -4,6 +4,7 @@ This section covers advanced features and concepts in Reactive-JSON that enable
 
 ## Topics
 
+- **[Attribute Transformers](attribute-transformers.md)**: Details on how element attributes can be modified by the app state.
 - **[Data Mapping](data-mapping.md)**: Learn how to selectively dispatch and transform response data using the Data Mapping system
 - **[Data Processors](data-processors.md)**: Learn how to intercept and modify data from HTTP requests using the DataProcessor system
 - **[Forward Update](forward-update.md)**: Implementation details about the retrieval of event values.

package/public/rjbuild/docs/advanced-concepts/index.yaml

@@ -7,6 +7,7 @@ renderView:
 
       ## Topics
 
+      - **[Attribute Transformers](attribute-transformers)**: Details on how element attributes can be modified by the app state.
       - **[Data Mapping](data-mapping)**: Learn how to selectively dispatch and transform response data using the Data Mapping system.
       - **[Data Processors](data-processors)**: Learn how to intercept and modify data from HTTP requests using the DataProcessor system.
       - **[Forward Update](forward-update)**: Implementation details about the retrieval of event values.

package/public/rjbuild/docs/advanced-concepts/plugins/component-development.md

@@ -1,4 +1,4 @@
-# Component Development Guide
+# Component development guide
 
 ## Overview
 

package/public/rjbuild/docs/advanced-concepts/plugins/component-development.yaml

@@ -1,7 +1,7 @@
 renderView:
   - type: Markdown
     content: |
-      # Component Development Guide
+      # Component development guide
 
       ## Overview
 

package/public/rjbuild/docs/advanced-concepts/plugins/plugin-system.md

@@ -1,4 +1,4 @@
-# Plugin System Guide
+# Plugin system guide
 
 ## Overview
 

package/public/rjbuild/docs/advanced-concepts/plugins/plugin-system.yaml

@@ -1,7 +1,7 @@
 renderView:
   - type: Markdown
     content: |
-      # Plugin System Guide
+      # Plugin system guide
 
       ## Overview
 

package/public/rjbuild/docs/core/action/Attribute/SetAttributeValue.md

@@ -1,5 +1,7 @@
 # SetAttributeValue
 
+> **Alternative**: For pre-render attribute modification, see the [setAttributeValue transformer](../../attributeTransformer/setAttributeValue.md).
+
 Dynamically sets or modifies the value of an HTML attribute on an element.
 
 ## Basic Syntax

package/public/rjbuild/docs/core/action/Attribute/SetAttributeValue.yaml

@@ -3,6 +3,8 @@ renderView:
     content: |
       # SetAttributeValue
 
+      > **Alternative**: For pre-render attribute modification, see the [setAttributeValue transformer](../../attributeTransformer/setAttributeValue).
+
       Dynamically sets or modifies the value of an HTML attribute on an element.
 
       ## Basic Syntax

package/public/rjbuild/docs/core/action/Attribute/ToggleAttributeValue.md

@@ -1,5 +1,7 @@
 # ToggleAttributeValue
 
+> **Alternative**: For pre-render attribute modification, see the [toggleAttributeValue transformer](../../attributeTransformer/toggleAttributeValue.md).
+
 Toggles the presence of a specific value in an HTML attribute. Supports both simple on-off toggles and cyclic toggling through multiple values.
 
 ## Important Notes

package/public/rjbuild/docs/core/action/Attribute/ToggleAttributeValue.yaml

@@ -3,6 +3,8 @@ renderView:
     content: |
       # ToggleAttributeValue
 
+      > **Alternative**: For pre-render attribute modification, see the [toggleAttributeValue transformer](../../attributeTransformer/toggleAttributeValue).
+
       Toggles the presence of a specific value in an HTML attribute. Supports both simple on-off toggles and cyclic toggling through multiple values.
 
       ## Important Notes

package/public/rjbuild/docs/core/action/Attribute/UnsetAttribute.md

@@ -1,5 +1,7 @@
 # UnsetAttribute
 
+> **Alternative**: For pre-render attribute modification, see the [unsetAttribute transformer](../../attributeTransformer/unsetAttribute.md).
+
 Completely removes an HTML attribute from an element.
 
 ## Basic Syntax

package/public/rjbuild/docs/core/action/Attribute/UnsetAttribute.yaml

@@ -3,6 +3,8 @@ renderView:
     content: |
       # UnsetAttribute
 
+      > **Alternative**: For pre-render attribute modification, see the [unsetAttribute transformer](../../attributeTransformer/unsetAttribute).
+
       Completely removes an HTML attribute from an element.
 
       ## Basic Syntax

package/public/rjbuild/docs/core/action/Attribute/UnsetAttributeValue.md

@@ -1,5 +1,7 @@
 # UnsetAttributeValue
 
+> **Alternative**: For pre-render attribute modification, see the [unsetAttributeValue transformer](../../attributeTransformer/unsetAttributeValue.md).
+
 Removes a specific value from an HTML attribute while preserving other values.
 
 ## Basic Syntax

package/public/rjbuild/docs/core/action/Attribute/UnsetAttributeValue.yaml

@@ -3,6 +3,8 @@ renderView:
     content: |
       # UnsetAttributeValue
 
+      > **Alternative**: For pre-render attribute modification, see the [unsetAttributeValue transformer](../../attributeTransformer/unsetAttributeValue).
+
       Removes a specific value from an HTML attribute while preserving other values.
 
       ## Basic Syntax

package/public/rjbuild/docs/core/action/Attribute/index.md

@@ -0,0 +1,121 @@
+# Attribute Actions
+
+> **Note**: Reactive-JSON provides two systems for attribute modification:
+> 
+> - **Attribute Actions** (this section): Execute **after rendering**, modify DOM attributes directly
+> - **[Attribute Transformers](../../attributeTransformer/index.md)**: Execute **before rendering**, modify attributes for child components
+> 
+> Choose actions for post-render DOM manipulation and transformers for pre-render attribute conditioning.
+
+Attribute Actions in Reactive-JSON allow you to modify element attributes after rendering based on dynamic conditions. They are evaluated continuously based on data state and provide direct DOM manipulation capabilities.
+
+## Key Differences from Transformers
+
+- **Timing**: Attribute actions execute **after rendering**, while transformers execute **before rendering**
+- **Impact**: Actions modify the DOM directly, transformers affect attributes passed to child components
+- **Use case**: Actions are ideal for imperative DOM updates that don't need to affect child component props
+
+## Available Attribute Actions
+
+### Value Management
+- **[SetAttributeValue](./SetAttributeValue.md)**: Sets or modifies HTML attribute values dynamically after rendering
+- **[UnsetAttributeValue](./UnsetAttributeValue.md)**: Removes specific values from HTML attributes while preserving others
+- **[ToggleAttributeValue](./ToggleAttributeValue.md)**: Toggles the presence of specific values in HTML attributes, supports cyclic toggling
+
+### Attribute Management
+- **[UnsetAttribute](./UnsetAttribute.md)**: Completely removes HTML attributes after rendering
+
+## Basic Usage
+
+Attribute actions are defined in the `actions` array on any element:
+
+```yaml
+renderView:
+  - type: div
+    attributes:
+      class: "base-class"
+      data-status: "default"
+    actions:
+      # Add class conditionally
+      - what: SetAttributeValue
+        name: "class"
+        value: "active"
+        when: ~~.isActive
+        is: true
+      
+      # Remove attribute entirely
+      - what: UnsetAttribute
+        name: "data-status"
+        when: ~~.hideStatus
+        is: true
+      
+      # Toggle between states
+      - what: ToggleAttributeValue
+        name: "class"
+        value: ["theme-light", "theme-dark"]
+        when: ~~.toggleTheme
+        isNotEmpty:
+```
+
+## Execution Order
+
+Attribute actions are applied based on data changes and re-evaluated when dependencies change:
+
+1. Component renders with base attributes
+2. Actions are evaluated based on current data state
+3. DOM attributes are modified directly
+4. Changes are applied to the live DOM element
+
+## Conditional Execution
+
+All attribute actions support the same conditional system as other actions:
+
+- **`when`**: Specifies the data value to evaluate
+- **`is`**: Exact value comparison
+- **`isEmpty`/`isNotEmpty`**: Empty/non-empty checks
+- **Template evaluation**: Full support for `~.`, `~~.`, `~>`, `~~>` patterns
+
+## Common Patterns
+
+### Conditional Styling
+```yaml
+actions:
+  - what: SetAttributeValue
+    name: "class"
+    value: "error"
+    when: ~~.validation.hasErrors
+    is: true
+```
+
+### State-based Attributes
+```yaml
+actions:
+  - what: ToggleAttributeValue
+    name: "aria-expanded"
+    value: "true"
+    when: ~~.menu.isOpen
+    is: true
+```
+
+### Dynamic Data Attributes
+```yaml
+actions:
+  - what: SetAttributeValue
+    name: "data-user-role"
+    value: ~~.currentUser.role
+    mode: "replace"
+```
+
+## When to Use Actions vs Transformers
+
+### Use Attribute Actions when:
+- You need to modify DOM attributes after the component has rendered
+- You're working with imperative DOM updates
+- You need to interact with external libraries that read DOM attributes
+- The attribute changes don't need to affect child component behavior
+
+### Use Attribute Transformers when:
+- You need attributes to be available to child components
+- You're doing conditional attribute setup before rendering
+- You want predictable attribute values during the render phase
+- You're building reusable components that depend on specific attributes

package/public/rjbuild/docs/core/action/Attribute/index.yaml

@@ -0,0 +1,77 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Attribute Actions
+
+      > **Note**: Reactive-JSON provides two systems for attribute modification:
+      > 
+      > - **Attribute Actions** (this section): Execute **after rendering**, modify DOM attributes directly
+      > - **[Attribute Transformers](../../attributeTransformer/index)**: Execute **before rendering**, modify attributes for child components
+      > 
+      > Choose actions for post-render DOM manipulation and transformers for pre-render attribute conditioning.
+
+      Attribute Actions in Reactive-JSON allow you to modify element attributes after rendering based on dynamic conditions. They are evaluated continuously based on data state and provide direct DOM manipulation capabilities.
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      renderView:
+        - type: div
+          attributes:
+            class: "base-class"
+            data-status: "default"
+          actions:
+            # Add class conditionally
+            - what: SetAttributeValue
+              name: "class"
+              value: "active"
+              when: ~~.isActive
+              is: true
+            
+            # Remove attribute entirely
+            - what: UnsetAttribute
+              name: "data-status"
+              when: ~~.hideStatus
+              is: true
+            
+            # Toggle between states
+            - what: ToggleAttributeValue
+              name: "class"
+              value: ["theme-light", "theme-dark"]
+              when: ~~.toggleTheme
+              isNotEmpty:
+
+  - type: Markdown
+    content: |
+      ## Key Differences from Transformers
+
+      - **Timing**: Attribute actions execute **after rendering**, while transformers execute **before rendering**
+      - **Impact**: Actions modify the DOM directly, transformers affect attributes passed to child components
+      - **Use case**: Actions are ideal for imperative DOM updates that don't need to affect child component props
+
+      ## Available Attribute Actions
+
+      ### Value Management
+      - **[SetAttributeValue](./SetAttributeValue)**: Sets or modifies HTML attribute values dynamically after rendering
+      - **[UnsetAttributeValue](./UnsetAttributeValue)**: Removes specific values from HTML attributes while preserving others
+      - **[ToggleAttributeValue](./ToggleAttributeValue)**: Toggles the presence of specific values in HTML attributes, supports cyclic toggling
+
+      ### Attribute Management
+      - **[UnsetAttribute](./UnsetAttribute)**: Completely removes HTML attributes after rendering
+
+      ## Execution Order
+
+      Attribute actions are applied based on data changes and re-evaluated when dependencies change:
+
+      1. Component renders with base attributes
+      2. Actions are evaluated based on current data state
+      3. DOM attributes are modified directly
+      4. Changes are applied to the live DOM element
+
+      ## Conditional Execution
+
+      All attribute actions support the same conditional system as other actions:
+
+      - **`when`**: Specifies the data value to evaluate
+      - **`is`**: Exact value comparison
+      - **`isEmpty`/`isNotEmpty`**: Empty/non-empty checks
+      - **Template evaluation**: Full support for `~.`, `~~.`, `~>`, `~~>` patterns

package/public/rjbuild/docs/core/action/CustomEventListener.md

@@ -0,0 +1,150 @@
+# CustomEventListener
+
+Executes a reaction when receiving custom events dispatched on DOM elements. This is an internal action component that is automatically used when you specify custom event names (like `on: "response"`) in your actions.
+
+## Usage
+
+CustomEventListener should **not** be used directly in the RjBuild. The Reactive-JSON engine will use it automatically when you specify custom event names (not standard DOM events) in any action. The system automatically adds this component to listen for custom events on the specific element that triggered the action.
+
+> **Technical requirement**: The element component must provide an `attributesHolderRef` for the listener to attach its event handler to the DOM element.
+
+## Properties
+
+When using custom event names in actions, you can specify:
+
+- `what` (required): Name of the reaction function to execute (e.g., `setData`, `fetchData`, `submitData`, etc.).
+- `on` (required): Name of the custom event to listen for (e.g., `"response"`, `"customUpdate"`, etc.).
+- All other properties are passed as arguments to the reaction function and support [forward update placeholders](../../../advanced-concepts/forward-update.md).
+
+## Behavior
+
+When you use a custom event name in an action (like `on: "response"`):
+
+1. The system automatically adds a CustomEventListener component
+2. It attaches an event listener directly on the element that triggered the action
+3. When the custom event is dispatched on that element:
+   - Receives the event object with its custom data
+   - Processes any [event placeholders](../../../advanced-concepts/forward-update.md) in the action properties
+   - Executes the reaction function specified in `what`
+
+## How Custom Events Are Triggered
+
+Custom events are typically triggered by reactions like `fetchData` or `submitData`:
+
+```yaml
+# fetchData automatically dispatches a "response" event when the request completes
+actions:
+  - what: fetchData
+    on: click
+    url: "/api/data.json"
+    # When this completes, it dispatches a "response" event on the same element
+```
+
+## Examples
+
+### Process HTTP response data
+```yaml
+renderView:
+  - type: button
+    content: "Load Data"
+    actions:
+      - what: fetchData
+        on: click
+        url: "/api/user-profile.json"
+        updateOnlyData: true
+        updateDataAtLocation: ~~.userProfile
+      - what: setData
+        on: response  # CustomEventListener handles this automatically
+        path: ~~.userTheme
+        value: <reactive-json:event-new-value>.preferences.theme
+      - what: setData
+        on: response
+        path: ~~.lastUpdateTime
+        value: <reactive-json:event-new-value>.metadata.timestamp
+```
+
+### React to submission completion
+```yaml
+renderView:
+  - type: button
+    content: "Save Profile"
+    actions:
+      - what: submitData
+        on: click
+        url: "/api/save-profile"
+        data:
+          name: ~~.form.name
+          email: ~~.form.email
+      - what: setData
+        on: response  # Triggered when submitData completes
+        path: ~~.saveStatus
+        value: <reactive-json:event-new-value>.status
+```
+
+### Custom event handling
+```yaml
+renderView:
+  - type: div
+    content: "Custom event handler"
+    actions:
+      - what: setData
+        on: customUpdate  # Any custom event name works
+        path: ~~.customData
+        value: <reactive-json:event-new-value>
+```
+
+## Event Data Access
+
+CustomEventListener provides full access to the custom event data through the [forward update system](../../../advanced-concepts/forward-update.md):
+
+- `<reactive-json:event-new-value>` - Accesses `event.detail.value` for CustomEvent objects
+- `<reactive-json:event>.detail.someProperty` - Direct access to event details
+- `<reactive-json:event>.data.someValue` - For events with data property
+
+## System Integration
+
+- **Forward Update System**: Supports all event placeholder patterns for accessing event data
+- **Reaction System**: Executes any available reaction function when events are received
+- **Element-Specific**: Listens on the exact element that triggered the original action
+- **Actions.jsx**: Automatically instantiated when custom event names are detected
+
+## Differences from Standard Events
+
+| Aspect | Standard DOM Events | Custom Events |
+|--------|-------------------|---------------|
+| **Handler** | ReactOnEvent | CustomEventListener |
+| **Event Names** | `click`, `change`, `submit`, etc. | `response`, `customUpdate`, etc. |
+| **Target** | Element (via React event system) | Element (via DOM addEventListener) |
+| **Event Data** | Standard DOM event properties | Custom data in `event.detail` |
+| **Triggering** | User interactions | Programmatic dispatch |
+
+## Built-in Custom Events
+
+Some reactions automatically dispatch custom events:
+
+- **`response`**: Dispatched by `fetchData` and `submitData` when HTTP requests complete successfully
+- **Custom events**: Can be triggered by `triggerEvent` reaction or external JavaScript
+
+## Limitations
+
+- Only works with custom event names in actions (not as a standalone element)
+- Requires the element component to provide an `attributesHolderRef` for DOM attachment
+- Listens only on the specific element that triggered the original action
+- Custom events must be dispatched on the correct element to be received
+- Event data structure depends on how the custom event was created
+- Automatic cleanup when the component unmounts
+
+## Technical Details
+
+- Automatically instantiated by the Actions system when custom event names are used
+- Uses `addEventListener` directly on DOM elements (not React's event system)
+- Supports the full [forward update system](../../../advanced-concepts/forward-update.md) for event data access
+- Properly cleans up event listeners when component unmounts
+- Integrates with the plugin system to execute available reaction functions
+
+## Related Components
+
+- **[ReactOnEvent](ReactOnEvent.md)**: Handles standard DOM events (`click`, `change`, etc.)
+- **[MessageListener](MessageListener.md)**: Handles `on: "message"` events
+- **[Forward Update System](../../../advanced-concepts/forward-update.md)**: Event data access patterns
+- **[Reactions System](../../getting-started/reactions.md)**: The actual reaction functions that CustomEventListener executes