@ea-lab/reactive-json-docs 0.8.0 → 1.0.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/addData.md

@@ -69,9 +69,23 @@ data:
 ### Adding with Dynamic Values
 ```yaml
 renderView:
-  - type: TextField
-    label: "New Item"
-    dataLocation: ~.new_item
+  - type: label
+    content: "New Item:"
+  - type: input
+    attributes:
+      type: "text"
+      value: ~.new_item
+      style:
+        padding: "8px"
+        margin: "8px 0"
+        border: "1px solid #ccc"
+        borderRadius: "4px"
+        width: "200px"
+    actions:
+      - what: setData
+        on: input
+        path: ~.new_item
+        value: "<reactive-json:event-new-value>"
   - type: button
     content: Add
     actions:

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

@@ -87,9 +87,23 @@ renderView:
       ### Adding with Dynamic Values
       ```yaml
       renderView:
-        - type: TextField
-          label: "New Item"
-          dataLocation: ~.new_item
+        - type: label
+          content: "New Item:"
+        - type: input
+          attributes:
+            type: "text"
+            value: ~.new_item
+            style:
+              padding: "8px"
+              margin: "8px 0"
+              border: "1px solid #ccc"
+              borderRadius: "4px"
+              width: "200px"
+          actions:
+            - what: setData
+              on: input
+              path: ~.new_item
+              value: "<reactive-json:event-new-value>"
         - type: button
           content: Add
           actions:
@@ -128,12 +142,42 @@ renderView:
             load: user_form
       templates:
         user_form:
-          - type: TextField
-            label: Name
-            dataLocation: ~.name
-          - type: TextField
-            label: Email
-            dataLocation: ~.email
+          type: div
+          content:
+            - type: label
+              content: "Name:"
+            - type: input
+              attributes:
+                type: "text"
+                value: ~.name
+                style:
+                  padding: "8px"
+                  margin: "8px 0"
+                  border: "1px solid #ccc"
+                  borderRadius: "4px"
+                  width: "200px"
+              actions:
+                - what: setData
+                  on: input
+                  path: ~.name
+                  value: "<reactive-json:event-new-value>"
+            - type: label
+              content: "Email:"
+            - type: input
+              attributes:
+                type: "email"
+                value: ~.email
+                style:
+                  padding: "8px"
+                  margin: "8px 0"
+                  border: "1px solid #ccc"
+                  borderRadius: "4px"
+                  width: "200px"
+              actions:
+                - what: setData
+                  on: input
+                  path: ~.email
+                  value: "<reactive-json:event-new-value>"
       data:
         users:
           - name: "John"

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

@@ -205,12 +205,22 @@ renderView:
           content:
             - type: div
               attributes:
-                class: "col-md-6"
+                style:
+                  width: "48%"
+                  display: "inline-block"
+                  verticalAlign: "top"
+                  marginRight: "2%"
               content:
                 - type: BsButton
                   content: "Complete Data Replacement"
                   attributes:
-                    class: "btn btn-primary mb-2 w-100"
+                    style:
+                      padding: "8px 16px"
+                      margin: "8px 0"
+                      border: "1px solid #007bff"
+                      borderRadius: "4px"
+                      cursor: "pointer"
+                      width: "100%"
                   actions:
                     - what: fetchData
                       on: click
@@ -226,12 +236,22 @@ renderView:
             
             - type: div
               attributes:
-                class: "col-md-6"
+                style:
+                  width: "48%"
+                  display: "inline-block"
+                  verticalAlign: "top"
+                  marginRight: "2%"
               content:
                 - type: BsButton
                   content: "Targeted Data Update"
                   attributes:
-                    class: "btn btn-secondary mb-2 w-100"
+                    style:
+                      padding: "8px 16px"
+                      margin: "8px 0"
+                      border: "1px solid #6c757d"
+                      borderRadius: "4px"
+                      cursor: "pointer"
+                      width: "100%"
                   actions:
                     - what: fetchData
                       on: click
@@ -253,7 +273,11 @@ renderView:
             - type: BsButton
               content: "🔄 Reset to Initial Data"
               attributes:
-                class: "btn btn-secondary"
+                style:
+                  padding: "8px 16px"
+                  border: "1px solid #6c757d"
+                  borderRadius: "4px"
+                  cursor: "pointer"
               actions:
                 - what: fetchData
                   on: click
@@ -269,7 +293,11 @@ renderView:
           content:
             - type: div
               attributes:
-                class: "col-md-4"
+                style:
+                  width: "32%"
+                  display: "inline-block"
+                  verticalAlign: "top"
+                  marginRight: "1%"
               content:
                 - type: h6
                   content: "👤 User Profile"
@@ -295,7 +323,11 @@ renderView:
             
             - type: div
               attributes:
-                class: "col-md-4"
+                style:
+                  width: "32%"
+                  display: "inline-block"
+                  verticalAlign: "top"
+                  marginRight: "1%"
               content:
                 - type: h6
                   content: "⚙️ Settings"
@@ -321,7 +353,11 @@ renderView:
             
             - type: div
               attributes:
-                class: "col-md-4"
+                style:
+                  width: "32%"
+                  display: "inline-block"
+                  verticalAlign: "top"
+                  marginRight: "1%"
               content:
                 - type: h6
                   content: "📊 Status"

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

@@ -52,10 +52,24 @@ This example shows how to use conditions with `setData` to only execute when cer
 
 ```yaml
 renderView:
-  - type: TextField
-    dataLocation: ~.username
-    label: "Username:"
-    placeholder: "Enter username"
+  - type: label
+    content: "Username:"
+  - type: input
+    attributes:
+      type: "text"
+      value: ~.username
+      placeholder: "Enter username"
+      style:
+        padding: "8px"
+        margin: "8px 0"
+        border: "1px solid #ccc"
+        borderRadius: "4px"
+        width: "200px"
+    actions:
+      - what: setData
+        on: input
+        path: ~.username
+        value: "<reactive-json:event-new-value>"
   - type: button
     content: "Set Welcome Message"
     actions:

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

@@ -73,10 +73,24 @@ renderView:
     description: "This example shows how to use conditions with `setData` to only execute when certain criteria are met."
     toDescribe:
       renderView:
-        - type: TextField
-          dataLocation: ~.username
-          label: "Username:"
-          placeholder: "Enter username"
+        - type: label
+          content: "Username:"
+        - type: input
+          attributes:
+            type: "text"
+            value: ~.username
+            placeholder: "Enter username"
+            style:
+              padding: "8px"
+              margin: "8px 0"
+              border: "1px solid #ccc"
+              borderRadius: "4px"
+              width: "200px"
+          actions:
+            - what: setData
+              on: input
+              path: ~.username
+              value: "<reactive-json:event-new-value>"
         - type: button
           content: "Set Welcome Message"
           actions: