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

package/public/rjbuild/docs/core/hook/useTransformedAttributes.md

@@ -0,0 +1,130 @@
+# useTransformedAttributes
+
+Applies attribute transformations based on configured transformers in plugins. This hook allows conditional modification of component attributes by applying a series of defined transformations.
+
+## Hook Signature
+
+```javascript
+const transformedAttributes = useTransformedAttributes(attrsToTransform, transformProps)
+```
+
+## Parameters
+
+- `attrsToTransform` (object): Raw attributes to transform
+- `transformProps` (array, optional): Array of transformation definitions to apply
+
+## Return Value
+
+- `transformedAttributes` (object): Final attributes after applying transformations (spread on target element/component)
+
+## How It Works
+
+The hook follows this logic:
+
+1. **Validation Check**: If `transformProps` is `undefined`, returns original attributes
+2. **Transformer Retrieval**: Accesses transformers via `globalDataContext.plugins.attributeTransformer`
+3. **Sequential Application**: Applies each transformation in defined order
+4. **Conditional Validation**: Each transformation is validated before application via `isValid()`
+5. **Accumulation**: Transformations are applied cumulatively
+
+## Supported Transformer Types
+
+The following transformers are available in the system:
+
+### setAttributeValue
+Sets an attribute value conditionally.
+
+### toggleAttributeValue
+Toggles between two values for an attribute.
+
+### unsetAttribute
+Completely removes an attribute.
+
+### unsetAttributeValue
+Removes an attribute value (sets to `undefined`).
+
+## Example Usage
+
+```jsx
+import { useTransformedAttributes } from '@ea-lab/reactive-json';
+
+const MyComponent = ({ props }) => {
+    const baseAttributes = {
+        className: "btn btn-primary",
+        disabled: false,
+        title: "Click me"
+    };
+
+    const transformedAttributes = useTransformedAttributes(
+        baseAttributes,
+        props.attributeTransforms
+    );
+
+    return <button {...transformedAttributes}>Submit</button>;
+};
+```
+
+## Transformation Configuration
+
+```yaml
+# Example configuration in RjBuild
+- type: MyComponent
+  attributeTransforms:
+    - what: setAttributeValue
+      when: ~~.form.isSubmitting
+      is: true
+      attributeName: disabled
+      value: true
+    
+    - what: toggleAttributeValue
+      when: ~~.theme
+      is: "dark"
+      attributeName: className
+      value1: "btn btn-primary"
+      value2: "btn btn-primary btn-dark"
+    
+    - what: unsetAttribute
+      when: ~~.user.role
+      is: "guest"
+      attributeName: title
+```
+
+## Context Integration
+
+The hook automatically uses:
+
+- **GlobalDataContext**: For accessing plugins and global data
+- **TemplateContext**: For condition evaluation in templates
+
+## Transformation Validation
+
+Each transformation is validated via the `isValid()` function which checks:
+
+- The `when` condition against the `is` value
+- Supported comparison operators
+- Data availability in contexts
+
+## Error Handling
+
+The hook is designed to be resilient:
+
+- **Missing Transformer**: Silently ignores the transformation
+- **Failed Validation**: Ignores invalid transformation
+- **Missing Plugins**: Returns original attributes
+- **Missing Data**: Ignores transformations that cannot be evaluated
+
+## Performance
+
+- **Sequential Application**: Transformations applied in order with accumulation
+- **Optimized Validation**: Invalid transformations ignored quickly
+- **Reusability**: Hook can be called multiple times without performance impact
+
+## Relationship with Transformers
+
+This hook is closely related to the attributeTransformer system:
+
+- Uses transformers registered in plugins
+- Respects transformer syntax (`what`, `when`, `is` properties)
+- Integrates with global validation system
+
+For details on individual transformers, see [attributeTransformer documentation](../attributeTransformer/index.md).

package/public/rjbuild/docs/core/hook/useTransformedAttributes.yaml

@@ -0,0 +1,164 @@
+renderView:
+  - type: Markdown
+    content: |
+      # useTransformedAttributes
+
+      Applies attribute transformations based on configured transformers in plugins. This hook allows conditional modification of component attributes by applying a series of defined transformations.
+
+      ## Hook Signature
+
+  - type: SyntaxHighlighter
+    language: "javascript"
+    content: |
+      const transformedAttributes = useTransformedAttributes(attrsToTransform, transformProps)
+
+  - type: Markdown
+    content: |
+      ## Parameters
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: attrsToTransform
+          after: "(object)"
+        details: "Raw attributes to transform"
+      - term:
+          code: transformProps
+          after: "(array, optional)"
+        details: "Array of transformation definitions to apply"
+
+  - type: Markdown
+    content: |
+      ## Return Value
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: transformedAttributes
+          after: "(object)"
+        details: "Final attributes after applying transformations (spread on target element/component)"
+
+  - type: Markdown
+    content: |
+      ## How It Works
+
+      The hook follows this logic:
+
+      1. **Validation Check**: If `transformProps` is `undefined`, returns original attributes
+      2. **Transformer Retrieval**: Accesses transformers via `globalDataContext.plugins.attributeTransformer`
+      3. **Sequential Application**: Applies each transformation in defined order
+      4. **Conditional Validation**: Each transformation is validated before application via `isValid()`
+      5. **Accumulation**: Transformations are applied cumulatively
+
+      ## Supported Transformer Types
+
+      The following transformers are available in the system:
+
+      ### setAttributeValue
+      Sets an attribute value conditionally.
+
+      ### toggleAttributeValue
+      Toggles between two values for an attribute.
+
+      ### unsetAttribute
+      Completely removes an attribute.
+
+      ### unsetAttributeValue
+      Removes an attribute value (sets to `undefined`).
+
+  - type: Markdown
+    content: |
+      ## Example Usage
+
+  - type: SyntaxHighlighter
+    language: "jsx"
+    content: |
+      import { useTransformedAttributes } from '@ea-lab/reactive-json';
+
+      const MyComponent = ({ props }) => {
+          const baseAttributes = {
+              className: "btn btn-primary",
+              disabled: false,
+              title: "Click me"
+          };
+
+          const transformedAttributes = useTransformedAttributes(
+              baseAttributes,
+              props.attributeTransforms
+          );
+
+          return <button {...transformedAttributes}>Submit</button>;
+      };
+
+  - type: Markdown
+    content: |
+      ## Transformation Configuration
+
+  - type: SyntaxHighlighter
+    language: "yaml"
+    content: |
+      # Example configuration in RjBuild
+      - type: MyComponent
+        attributeTransforms:
+          - what: setAttributeValue
+            when: ~~.form.isSubmitting
+            is: true
+            attributeName: disabled
+            value: true
+          
+          - what: toggleAttributeValue
+            when: ~~.theme
+            is: "dark"
+            attributeName: className
+            value1: "btn btn-primary"
+            value2: "btn btn-primary btn-dark"
+          
+          - what: unsetAttribute
+            when: ~~.user.role
+            is: "guest"
+            attributeName: title
+
+  - type: Markdown
+    content: |
+      ## Context Integration
+
+      The hook automatically uses:
+
+      - **GlobalDataContext**: For accessing plugins and global data
+      - **TemplateContext**: For condition evaluation in templates
+
+      ## Transformation Validation
+
+      Each transformation is validated via the `isValid()` function which checks:
+
+      - The `when` condition against the `is` value
+      - Supported comparison operators
+      - Data availability in contexts
+
+      ## Error Handling
+
+      The hook is designed to be resilient:
+
+      - **Missing Transformer**: Silently ignores the transformation
+      - **Failed Validation**: Ignores invalid transformation
+      - **Missing Plugins**: Returns original attributes
+      - **Missing Data**: Ignores transformations that cannot be evaluated
+
+      ## Performance
+
+      - **Sequential Application**: Transformations applied in order with accumulation
+      - **Optimized Validation**: Invalid transformations ignored quickly
+      - **Reusability**: Hook can be called multiple times without performance impact
+
+      ## Relationship with Transformers
+
+      This hook is closely related to the attributeTransformer system:
+
+      - Uses transformers registered in plugins
+      - Respects transformer syntax (`what`, `when`, `is` properties)
+      - Integrates with global validation system
+
+      For details on individual transformers, see [attributeTransformer documentation](../attributeTransformer/index).
+
+templates: {}
+data: {}

package/public/rjbuild/docs/core/reaction/fetchData.md

@@ -27,6 +27,31 @@
   - Without `updateDataAtLocation`: **completely replaces** the entire data object
   - With `updateDataAtLocation`: updates only the specified path in the data
 
+## Response Event
+
+`fetchData` triggers a special `response` event when the HTTP request completes successfully. This allows you to process the response data immediately using other reactions.
+
+You can use the `on: response` trigger with any reaction (like `setData`) to access the response data through the [forward update system](../../../advanced-concepts/forward-update.md):
+
+```yaml
+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: ~~.lastFetchTime
+    value: <reactive-json:event-new-value>.metadata.timestamp
+```
+
+The response event provides access to the complete server response through `<reactive-json:event-new-value>`, allowing you to extract specific values and store them in different data locations.
+
 > **⚠️ Important:** When using `updateOnlyData: true`, the server response must contain **data only**, not a complete RjBuild structure. The response should be the raw data object, not wrapped in `{data: {...}, renderView: [...], templates: {...}}`.
 
 ## Examples

package/public/rjbuild/docs/core/reaction/fetchData.yaml

@@ -56,6 +56,34 @@ renderView:
       - Errors are only logged to the console
       - The triggering element is visually disabled during the request
 
+      ## Response Event
+
+      `fetchData` triggers a special `response` event when the HTTP request completes successfully. This allows you to process the response data immediately using other reactions.
+
+      You can use the `on: response` trigger with any reaction (like `setData`) to access the response data through the [forward update system](../../../advanced-concepts/forward-update):
+
+  - type: SyntaxHighlighter
+    language: yaml
+    content: |
+      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: ~~.lastFetchTime
+          value: <reactive-json:event-new-value>.metadata.timestamp
+
+  - type: Markdown
+    content: |
+      The response event provides access to the complete server response through `<reactive-json:event-new-value>`, allowing you to extract specific values and store them in different data locations.
+
   - type: RjBuildDescriber
     title: Basic Structure (GET - Default)
     description:
@@ -184,11 +212,11 @@ renderView:
     title:
       type: Markdown
       content: |
-        Data-Only Update Examples `@ea-lab/reactive-json@0.2.0`
+        Data-Only Update Examples
     description:
       - type: Markdown
         content: |
-          Properties `updateOnlyData` and `updateDataAtLocation` (added in @ea-lab/reactive-json@0.2.0) allow for more precise data management:
+          Properties `updateOnlyData` and `updateDataAtLocation` allow for more precise data management:
           
           - `updateOnlyData: true`: Only updates the data section, preserving templates and renderView
           - `updateDataAtLocation`: Specifies exactly where to place the response data

package/public/rjbuild/docs/core/reaction/submitData.md

@@ -29,6 +29,34 @@
   - Without `updateDataAtLocation`: **completely replaces** the entire data object
   - With `updateDataAtLocation`: updates only the specified path in the data
 
+## Response Event
+
+`submitData` triggers a special `response` event when the HTTP submission completes successfully. This allows you to process the response data immediately using other reactions.
+
+You can use the `on: response` trigger with any reaction (like `setData`) to access the response data through the [forward update system](../../../advanced-concepts/forward-update.md):
+
+```yaml
+actions:
+  - what: submitData
+    on: click
+    url: "/api/user/save"
+    data:
+      name: ~.form.name
+      email: ~.form.email
+    updateOnlyData: true
+    updateDataAtLocation: ~~.userProfile
+  - what: setData
+    on: response  # Triggered when submitData completes
+    path: ~~.lastSaveStatus
+    value: <reactive-json:event-new-value>.status
+  - what: setData
+    on: response
+    path: ~~.saveTimestamp
+    value: <reactive-json:event-new-value>.metadata.savedAt
+```
+
+The response event provides access to the complete server response through `<reactive-json:event-new-value>`, allowing you to extract specific values and store them in different data locations independently of the main data update process.
+
 > **⚠️ Important:** When using `updateOnlyData: true`, the server response must contain **data only**, not a complete RjBuild structure. The response should be the raw data object, not wrapped in `{data: {...}, renderView: [...], templates: {...}}`.
 
 ## Submission States & Styling

package/public/rjbuild/docs/core/reaction/submitData.yaml

@@ -64,6 +64,37 @@ renderView:
       - In case of an error, the submission is cancelled and logged to the console
       - Interface elements are visually disabled during submission (unless `submitSilently` is enabled)
 
+      ## Response Event
+
+      `submitData` triggers a special `response` event when the HTTP submission completes successfully. This allows you to process the response data immediately using other reactions.
+
+      You can use the `on: response` trigger with any reaction (like `setData`) to access the response data through the [forward update system](../../../advanced-concepts/forward-update):
+
+  - type: SyntaxHighlighter
+    language: yaml
+    content: |
+      actions:
+        - what: submitData
+          on: click
+          url: "/api/user/save"
+          data:
+            name: ~.form.name
+            email: ~.form.email
+          updateOnlyData: true
+          updateDataAtLocation: ~~.userProfile
+        - what: setData
+          on: response  # Triggered when submitData completes
+          path: ~~.lastSaveStatus
+          value: <reactive-json:event-new-value>.status
+        - what: setData
+          on: response
+          path: ~~.saveTimestamp
+          value: <reactive-json:event-new-value>.metadata.savedAt
+
+  - type: Markdown
+    content: |
+      The response event provides access to the complete server response through `<reactive-json:event-new-value>`, allowing you to extract specific values and store them in different data locations independently of the main data update process.
+
       ## Submission States & Styling
       The system uses a global locking mechanism to handle submissions:
       - Only one submission can be active at a time for all application roots
@@ -165,7 +196,7 @@ renderView:
       - Save progression state
       - Maintain consistency between client and server
 
-      ## Data-Only Update Examples (@ea-lab/reactive-json@0.2.0)
+      ## Data-Only Update Examples
       
       The properties `updateOnlyData` and `updateDataAtLocation` work identically for `submitData` and `fetchData`.