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

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

@@ -0,0 +1,158 @@
+renderView:
+  - type: Markdown
+    content: |
+      # 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:
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: what
+          after: "(required)"
+        details: "Name of the reaction function to execute (e.g., `setData`, `fetchData`, `submitData`, etc.)."
+      - term:
+          code: on
+          after: "(required)"
+        details: 'Name of the custom event to listen for (e.g., `"response"`, `"customUpdate"`, etc.).'
+      - term: "All other properties"
+        details:
+          type: Markdown
+          content: "Are passed as arguments to the reaction function and support [forward update placeholders](../../../advanced-concepts/forward-update)."
+
+  - type: Markdown
+    content: |
+      ## 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) 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`:
+
+  - type: SyntaxHighlighter
+    language: yaml
+    content: |
+      # 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
+
+  - type: Markdown
+    content: |
+      ## Event Data Access
+
+      CustomEventListener provides full access to the custom event data through the [forward update system](../../../advanced-concepts/forward-update):
+
+      - `<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
+
+  - type: RjBuildDescriber
+    title: "Process HTTP Response Data"
+    description:
+      type: Markdown
+      content: |
+        This example shows how CustomEventListener automatically handles the `response` event from `fetchData`. The response data can be extracted and stored in different locations using event placeholders.
+    toDescribe:
+      renderView:
+        - type: button
+          content: "Load User Profile"
+          actions:
+            - what: fetchData
+              on: click
+              url: "/mockup-api/fetchData/example.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
+        - type: div
+          content:
+            - "User Theme: "
+            - type: code
+              content: ~~.userTheme
+        - type: div
+          content:
+            - "Last Update: "
+            - type: code
+              content: ~~.lastUpdateTime
+      data:
+        userTheme: "not-loaded"
+        lastUpdateTime: "not-loaded"
+
+  - type: SyntaxHighlighter
+    language: yaml
+    title: "Custom Event Handling"
+    content: |
+      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>
+
+  - type: Markdown
+    content: |
+      ## 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
+
+      ## Related Components
+
+      - **[ReactOnEvent](ReactOnEvent)**: Handles standard DOM events (`click`, `change`, etc.)
+      - **[MessageListener](MessageListener)**: Handles `on: "message"` events
+      - **[Forward Update System](../../../advanced-concepts/forward-update)**: Event data access patterns
+      - **[Reactions System](../../getting-started/reactions)**: The actual reaction functions that CustomEventListener executes
+
+templates:
+
+data: {}

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

@@ -4,7 +4,7 @@ Listens to hash changes (URL fragment) in the window and executes a reaction fun
 
 ## Usage
 
-HashChangeListener is **not** used directly as an element type. Instead, it is automatically triggered when you use `on: "hashchange"` in any action. The system automatically adds this component to listen for hash changes globally.
+HashChangeListener should **not** be used directly in the RjBuild. The Reactive-JSON engine will use it automatically when you use `on: "hashchange"` in any action. The system automatically adds this component to listen for hash changes globally.
 
 ## Properties
 

package/public/rjbuild/docs/core/action/HashChangeListener.yaml

@@ -7,7 +7,7 @@ renderView:
 
       ## Usage
 
-      HashChangeListener is **not** used directly as an element type. Instead, it is automatically triggered when you use `on: "hashchange"` in any action. The system automatically adds this component to listen for hash changes globally.
+      HashChangeListener should **not** be used directly in the RjBuild. The Reactive-JSON engine will use it automatically when you use `on: "hashchange"` in any action. The system automatically adds this component to listen for hash changes globally.
 
       ## Properties
 

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

@@ -4,7 +4,7 @@ Executes a reaction when receiving a message via `window.postMessage`. This is a
 
 ## Usage
 
-MessageListener is **not** used directly as an element type. Instead, it is automatically triggered when you use `on: "message"` in any action. The system automatically adds this component to listen for messages globally on the window object.
+MessageListener should **not** be used directly in the RjBuild. The Reactive-JSON engine will use it automatically when you use `on: "message"` in any action. The system automatically adds this component to listen for messages globally on the window object.
 
 ## Properties
 

package/public/rjbuild/docs/core/action/MessageListener.yaml

@@ -7,7 +7,7 @@ renderView:
 
       ## Usage
 
-      MessageListener is **not** used directly as an element type. Instead, it is automatically triggered when you use `on: "message"` in any action. The system automatically adds this component to listen for messages globally on the window object.
+      MessageListener should **not** be used directly in the RjBuild. The Reactive-JSON engine will use it automatically when you use `on: "message"` in any action. The system automatically adds this component to listen for messages globally on the window object.
 
       ## Properties
 

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

@@ -1,6 +1,6 @@
 # ReactOnEvent
 
-ReactOnEvent is an internal action component that is automatically instantiated by the Actions system when reactions with event handlers (`on: "eventName"`) are detected. It should **not** be used directly as an element type.
+ReactOnEvent is an internal action component that is automatically instantiated by the Actions system when reactions with event handlers (`on: "eventName"`) are detected. It should **not** be used directly in the RjBuild.
 
 > **Important**: It should **not** be used directly as an element type. The Reactive-JSON engine will automatically instantiate it when needed.
 
@@ -69,9 +69,9 @@ actions:
 
 ## Important Notes
 
-- **Never use `type: ReactOnEvent`** in your renderView - it's an internal component
+- **Never use `type: ReactOnEvent`** in your RjBuild - it's an internal component
 - **Use `actions` with `on: "eventName"`** - this is the correct way to handle events
-- **ReactOnEvent is automatically instantiated** by the Actions system when needed
+- **The Reactive-JSON engine will use ReactOnEvent automatically** when needed
 - **Event propagation is stopped by default** - use `stopPropagation: false` to change this
 
 ## Related Components

package/public/rjbuild/docs/core/action/ReactOnEvent.yaml

@@ -5,7 +5,7 @@ renderView:
 
       ReactOnEvent is an internal action component that is automatically instantiated by the Actions system when reactions with event handlers (`on: "eventName"`) are detected.
       
-      > **Important**: It should **not** be used directly as an element type. The Reactive-JSON engine will automatically instantiate it when needed.
+      > **Important**: It should **not** be used directly in the RjBuild. The Reactive-JSON engine will automatically instantiate it when needed.
 
       ## How it Works
 
@@ -81,9 +81,9 @@ renderView:
     content: |
       ## Important Notes
       
-      - **Never use `type: ReactOnEvent`** in your renderView - it's an internal component
+      - **Never use `type: ReactOnEvent`** in your RjBuild - it's an internal component
       - **Use `actions` with `on: "eventName"`** - this is the correct way to handle events
-      - **ReactOnEvent is automatically instantiated** by the Actions system when needed
+      - **The Reactive-JSON engine will use ReactOnEvent automatically** when needed
       - **Event propagation is stopped by default** - use `stopPropagation: false` to change this
       
       ## Related Components

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

@@ -30,6 +30,7 @@ when the user requests a [reaction](../../getting-started/reactions.md) on a giv
 
 As a user, you won't need to work with them directly.
 
+- **[CustomEventListener](./CustomEventListener.md)**: Reacts to custom events
 - **[HashChangeListener](./HashChangeListener.md)**: Listens for URL hash changes
 - **[MessageListener](./MessageListener.md)**: Listens for window messages
-- **[ReactOnEvent](./ReactOnEvent.md)**: Reacts to custom events
+- **[ReactOnEvent](./ReactOnEvent.md)**: Reacts to DOM events

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

@@ -33,7 +33,8 @@ renderView:
 
       As a user, you won't need to work with them directly.
 
+      - **[CustomEventListener](./CustomEventListener)**: Reacts to custom events
       - **[HashChangeListener](./HashChangeListener)**: Listens for URL hash changes
       - **[MessageListener](./MessageListener)**: Listens for window messages
-      - **[ReactOnEvent](./ReactOnEvent)**: Reacts to custom events
+      - **[ReactOnEvent](./ReactOnEvent)**: Reacts to DOM events
 

package/public/rjbuild/docs/core/attributeTransformer/index.md

@@ -0,0 +1,17 @@
+# Attribute Transformers
+
+> **Note**: Don't confuse with [Attribute Actions](../action/Attribute/index.md). Attribute Transformers execute **before rendering** and modify attributes for child components, while Attribute Actions execute **after rendering** and modify the DOM directly.
+
+Attribute Transformers allow you to dynamically modify element attributes before rendering, based on conditions from the application state.
+
+> **For detailed usage, examples, and extensibility information**, see **[Attribute Transformers Advanced Guide](../../advanced-concepts/attribute-transformers.md)**.
+
+## Available Attribute Transformers
+
+### Value Management
+- **[setAttributeValue](./setAttributeValue.md)**: Sets or modifies HTML attribute values dynamically before 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 before rendering

package/public/rjbuild/docs/core/attributeTransformer/index.yaml

@@ -0,0 +1,24 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Attribute Transformers
+
+      > **Note**: Don't confuse with [Attribute Actions](../action/Attribute/index). Attribute Transformers execute **before rendering** and modify attributes for child components, while Attribute Actions execute **after rendering** and modify the DOM directly.
+
+      Attribute Transformers allow you to dynamically modify element attributes before rendering, based on conditions from the application state.
+
+      > **For detailed usage, examples, and extensibility information**, see **[Attribute Transformers Advanced Guide](../../advanced-concepts/attribute-transformers)**.
+
+      ## Available Attribute Transformers
+
+      ### Value Management
+      - **[setAttributeValue](./setAttributeValue)**: Sets or modifies HTML attribute values dynamically before 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 before rendering
+
+data:
+  page_title: "Attribute Transformers - Reactive-JSON Documentation"
+

package/public/rjbuild/docs/core/attributeTransformer/setAttributeValue.md

@@ -0,0 +1,101 @@
+# setAttributeValue
+
+> **Alternative**: For post-render DOM modification, see the [SetAttributeValue action](../action/Attribute/SetAttributeValue.md).
+
+Dynamically sets or modifies the value of an HTML attribute before rendering. This attribute transformer allows you to conditionally modify attributes based on data state during the evaluation phase.
+
+## Basic Syntax
+
+```yaml
+attributeTransforms:
+  # Add CSS class
+  - what: setAttributeValue
+    name: "class"
+    value: "active"
+    
+  # Replace attribute value
+  - what: setAttributeValue
+    name: "data-status"
+    mode: "replace"
+    value: ~.currentStatus
+```
+
+## Properties
+
+- **name** *(string, required)*: The name of the attribute to modify.
+- **mode** *(string, optional)*: The modification mode. Default: `"append"`.
+  - `"append"`: Adds the value to the existing attribute value (space-separated).
+  - `"replace"`: Completely replaces the existing attribute value.
+- **value** *(string, required)*: The value to set or append. Supports template evaluation (e.g., `~.dynamicValue`, `~~.globalValue`). Automatically converted to string if not already. Special characters are handled safely.
+- **preventDuplicateValues** *(boolean, optional)*: When `true` (default), prevents duplicate values when using append mode.
+- **separator** *(string, optional)*: The separator used between values. Default: `" "` (space).
+
+## Behavior
+
+- **Append mode**: Adds the new value to the existing attribute, separated by the specified separator.
+- **Replace mode**: Completely overwrites the existing attribute value.
+- **Duplicate prevention**: In append mode, prevents adding duplicate values when enabled.
+
+## Common Use Cases
+
+- **Dynamic CSS classes**: Adding/removing CSS classes based on state.
+- **Data attributes**: Setting data-* attributes for JavaScript integration.
+- **ARIA attributes**: Dynamically updating accessibility attributes.
+- **Style attributes**: Modifying inline styles conditionally.
+
+## Example
+
+```yaml
+renderView:
+  - type: input
+    attributes:
+      type: "text"
+      placeholder: "Type to see conditional styling..."
+      class: "base-input"
+      value: ~.input_data
+      style:
+        padding: "10px"
+        border: "2px solid #007bff"
+        borderRadius: "4px"
+        fontSize: "16px"
+        margin: "10px 0"
+        width: "300px"
+        display: "block"
+    attributeTransforms:
+      - what: setAttributeValue
+        name: "class"
+        value: "highlighted"
+        when: ~.input_data
+        isNotEmpty:
+    actions:
+      - what: setData
+        on: change
+        path: ~.input_data
+        value: <reactive-json:event-new-value>
+
+  - type: div
+    content: ["Current value: ", ~.input_data]
+
+  - type: style
+    content: |
+      .base-input {
+        transition: border-color 0.3s ease;
+      }
+      .highlighted {
+        border-color: #28a745 !important;
+        outline: 2px solid #28a745 !important;
+        outline-offset: 2px !important;
+      }
+
+data:
+  input_data: ""
+```
+
+## Notes
+
+- **Pre-render execution**: This transformer modifies attributes before the component renders, ensuring child components receive the transformed attributes.
+- **Append mode behavior**: Respects existing attribute values when using append mode.
+- **Replace mode**: Use when you need complete control over the attribute value.
+- **Duplicate prevention**: Only applies to append mode.
+- **Template evaluation**: The value property supports full template evaluation including `~.localData`, `~~.globalData`, `~>nearestKey`, and `~~>globalKey` patterns.
+- **Conditional execution**: Supports the same condition system as actions (`when`, `is`, `isEmpty`, `isNotEmpty`, etc.).

package/public/rjbuild/docs/core/attributeTransformer/setAttributeValue.yaml

@@ -0,0 +1,144 @@
+renderView:
+  - type: Markdown
+    content: |
+      # setAttributeValue
+
+      > **Alternative**: For post-render DOM modification, see the [SetAttributeValue action](../action/Attribute/SetAttributeValue).
+
+      Dynamically sets or modifies the value of an HTML attribute on an element.
+
+      ## Basic Syntax
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      attributeTransforms:
+        # Add CSS class
+        - what: setAttributeValue
+          name: "class"
+          value: "active"
+          
+        # Replace attribute value
+        - what: setAttributeValue
+          name: "data-status"
+          mode: "replace"
+          value: ~.currentStatus
+
+  - type: Markdown
+    content: |
+      ## Properties
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: name
+          after: "(string, required)"
+        details: The name of the attribute to modify.
+      - term:
+          code: mode
+          after: "(string, optional)"
+        details: 
+          type: Markdown
+          content: |
+            The modification mode. Default: `"append"`
+            - `"append"`: Adds the value to the existing attribute value (space-separated)
+            - `"replace"`: Completely replaces the existing attribute value
+      - term:
+          code: value
+          after: "(string, required)"
+        details: The value to set or append. Supports template evaluation (e.g., `~.dynamicValue`, `~~.globalValue`). Automatically converted to string if not already. Special characters are handled safely.
+      - term:
+          code: preventDuplicateValues
+          after: "(boolean, optional)"
+        details:
+          type: Markdown
+          content: When `true` (default), prevents duplicate values when using append mode.
+      - term:
+          code: separator
+          after: "(string, optional)"
+        details:
+          type: Markdown
+          content: |
+            The separator used between values. Default: `" "` (space).
+
+  - type: Markdown
+    content: |
+
+      ## Behavior
+
+      - **Append mode**: Adds the new value to the existing attribute, separated by the specified separator.
+      - **Replace mode**: Completely overwrites the existing attribute value.
+      - **Duplicate prevention**: In append mode, prevents adding duplicate values when enabled.
+
+      ## Common Use Cases
+
+      - **Dynamic CSS classes**: Adding/removing CSS classes based on state.
+      - **Data attributes**: Setting data-* attributes for JavaScript integration.
+      - **ARIA attributes**: Dynamically updating accessibility attributes.
+      - **Style attributes**: Modifying inline styles conditionally.
+
+  - type: RjBuildDescriber
+    title: "SetAttributeValue Action Examples"
+    description:
+      - type: Markdown
+        content: |
+          This example demonstrates how to use the `SetAttributeValue` action to dynamically add CSS classes based on input content.
+          
+          **Expected behavior:**
+          - Initially, the input field has normal appearance (base styling)
+          - Start typing in the input field
+          - When the field is not empty, the 'sav-highlighted' class is automatically added (visual highlighting)
+          - Clear the field to remove the highlighting
+          - The action uses append mode and responds to the `isNotEmpty` condition
+          
+          Try typing and clearing the input to see how the class attribute changes automatically.
+
+    toDescribe:
+      renderView:
+        - type: input
+          attributes:
+            type: "text"
+            placeholder: "Start typing to see the highlighting..."
+            class: "sav-demo-input"
+            value: ~.input_data
+            style:
+              padding: "10px"
+              border: "2px solid #007bff"
+              borderRadius: "4px"
+              fontSize: "16px"
+              margin: "10px 0"
+              width: "300px"
+              display: "block"
+          actions:
+            - what: setData
+              on: change
+              path: ~.input_data
+              value: <reactive-json:event-new-value>
+          attributeTransforms:
+            - what: setAttributeValue
+              name: "class"
+              value: "sav-highlighted"
+              when: ~.input_data
+              isNotEmpty:
+
+        - type: div
+          content: ~.input_data
+
+        - type: style
+          content: |
+            .sav-highlighted {
+              border-color: #28a745 !important;
+              outline: 2px solid #28a745 !important;
+              outline-offset: 2px !important;
+            }
+
+      data:
+        input_data: ""
+
+  - type: Markdown
+    content: |
+      ## Notes
+
+      - The action respects existing attribute values when using append mode.
+      - Use replace mode when you need complete control over the attribute value.
+      - Duplicate prevention only applies to append mode.
+      - The value property supports full template evaluation including `~.localData`, `~~.globalData`, `~>nearestKey`, and `~~>globalKey` patterns.