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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ea-lab/reactive-json-docs",
-  "version": "1.0.0-alpha.0",
+  "version": "1.1.0",
   "description": "Complete documentation for Reactive-JSON - Components, examples and LLM-parsable guides",
   "main": "public/rjbuild/docs/index.yaml",
   "files": [
@@ -26,7 +26,7 @@
   "private": false,
   "devDependencies": {
     "@craco/craco": "^7.1.0",
-    "@ea-lab/reactive-json": "^1.0.0-alpha.6",
+    "@ea-lab/reactive-json": "^1.1.0",
     "@ea-lab/reactive-json-chartjs": "^1.0.0",
     "@npmcli/fs": "^4.0.0",
     "@reduxjs/toolkit": "^2.6.1",

package/public/rjbuild/docs/advanced-concepts/attribute-transformers.md

@@ -0,0 +1,168 @@
+# Attribute Transformers
+
+> **Note**: Reactive-JSON provides two systems for attribute modification:
+> 
+> - **Attribute Transformers** (this section): Execute **before rendering**, modify attributes for child components
+> - **[Attribute Actions](../core/action/Attribute/index.md)**: Execute **after rendering**, modify DOM attributes directly
+> 
+> Choose transformers for pre-render attribute conditioning and actions for post-render DOM manipulation.
+
+Attribute Transformers in Reactive-JSON allow you to modify element attributes before rendering based on dynamic conditions. They are evaluated during the attribute evaluation phase and provide pre-render attribute manipulation capabilities.
+
+## Key Differences from Actions
+
+- **Timing**: Attribute transformers execute **before rendering**, while actions execute **after rendering**
+- **Impact**: Transformers affect attributes passed to child components, actions modify the DOM directly
+- **Use case**: Transformers are ideal for conditional attribute values that need to be available to child components
+
+## Available Transformers
+
+For a complete list of built-in attribute transformers, see **[Attribute Transformers Reference](../core/attributeTransformer/index.md)**.
+
+## Extensibility
+
+The Attribute Transformer system is fully extensible through the plugin system. You can create custom transformers to handle specific attribute manipulation needs in your application.
+
+### Creating Custom Attribute Transformers
+
+Attribute transformers are JavaScript functions that receive attributes and transformation properties, then return the modified attributes:
+
+```javascript
+// customTransformer.js
+export const myCustomTransformer = ({ attributes, globalDataContext, singleTransformProps, templateContext }) => {
+    const { name, customProperty } = singleTransformProps;
+    
+    // Your custom logic here
+    // Modify the attributes object
+    
+    return attributes;
+};
+```
+
+### Plugin Registration
+
+Include your custom transformers in a plugin and register them with ReactiveJsonRoot:
+
+```javascript
+// myPlugin.js
+import { myCustomTransformer } from "./transformers/customTransformer.js";
+
+export const myPlugin = {
+    attributeTransformer: {
+        myCustomTransformer,
+    }
+};
+```
+
+```javascript
+// App.js
+import { ReactiveJsonRoot, mergeComponentCollections } from "@ea-lab/reactive-json";
+import { myPlugin } from "./plugins/myPlugin.js";
+
+const App = () => {
+    return (
+        <ReactiveJsonRoot
+            plugins={mergeComponentCollections([myPlugin])}
+        />
+    );
+};
+```
+
+### Usage in RjBuild
+
+Once registered, your custom transformer can be used in any element:
+
+```yaml
+renderView:
+  - type: div
+    attributes:
+      class: "base-class"
+    attributeTransforms:
+      - what: myCustomTransformer
+        name: "data-custom"
+        customProperty: "value"
+        when: ~~.someCondition
+        is: true
+```
+
+For detailed component development guidance, see **[Plugin Development](./plugins/index.md)**.
+
+## Basic Usage
+
+Attribute transformers are defined in the `attributeTransforms` array on any element:
+
+```yaml
+renderView:
+  - type: div
+    attributes:
+      class: "base-class"
+      data-status: "default"
+    attributeTransforms:
+      # 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 transformers are applied in the order they appear in the `attributeTransforms` array:
+
+1. Base attributes are evaluated (template resolution)
+2. Each transformer is applied sequentially
+3. The final attributes are passed to the component/element
+
+## Conditional Execution
+
+All attribute transformers support the same conditional system as 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
+attributeTransforms:
+  - what: setAttributeValue
+    name: "class"
+    value: "error"
+    when: ~~.validation.hasErrors
+    is: true
+```
+
+### State-based Attributes
+```yaml
+attributeTransforms:
+  - what: toggleAttributeValue
+    name: "aria-expanded"
+    value: "true"
+    when: ~~.menu.isOpen
+    is: true
+```
+
+### Dynamic Data Attributes
+```yaml
+attributeTransforms:
+  - what: setAttributeValue
+    name: "data-user-role"
+    value: ~~.currentUser.role
+    mode: "replace"
+```

package/public/rjbuild/docs/advanced-concepts/attribute-transformers.yaml

@@ -0,0 +1,151 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Attribute Transformers
+
+      > **Note**: Reactive-JSON provides two systems for attribute modification:
+      > 
+      > - **Attribute Transformers** (this section): Execute **before rendering**, modify attributes for child components
+      > - **[Attribute Actions](../core/action/Attribute/index)**: Execute **after rendering**, modify DOM attributes directly
+      > 
+      > Choose transformers for pre-render attribute conditioning and actions for post-render DOM manipulation.
+
+      Attribute Transformers in Reactive-JSON allow you to modify element attributes before rendering based on dynamic conditions. They are evaluated during the attribute evaluation phase and provide pre-render attribute manipulation capabilities.
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      renderView:
+        - type: div
+          attributes:
+            class: "base-class"
+            data-status: "default"
+          attributeTransforms:
+            # 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 Actions
+
+      - **Timing**: Attribute transformers execute **before rendering**, while actions execute **after rendering**
+      - **Impact**: Transformers affect attributes passed to child components, actions modify the DOM directly
+      - **Use case**: Transformers are ideal for conditional attribute values that need to be available to child components
+
+      ## Available Transformers
+
+      For a complete list of built-in attribute transformers, see **[Attribute Transformers Reference](../core/attributeTransformer/index)**.
+
+      ## Extensibility
+
+      The Attribute Transformer system is fully extensible through the plugin system. You can create custom transformers to handle specific attribute manipulation needs in your application.
+
+      ### Creating Custom Attribute Transformers
+
+      Attribute transformers are JavaScript functions that receive attributes and transformation properties, then return the modified attributes:
+
+  - type: SyntaxHighlighter
+    language: javascript
+    content: |
+      // customTransformer.js
+      export const myCustomTransformer = ({ attributes, globalDataContext, singleTransformProps, templateContext }) => {
+          const { name, customProperty } = singleTransformProps;
+          
+          // Your custom logic here
+          // Modify the attributes object
+          
+          return attributes;
+      };
+
+  - type: Markdown
+    content: |
+      ### Plugin Registration
+
+      Include your custom transformers in a plugin and register them with ReactiveJsonRoot:
+
+  - type: SyntaxHighlighter
+    language: javascript
+    content: |
+      // myPlugin.js
+      import { myCustomTransformer } from "./transformers/customTransformer.js";
+
+      export const myPlugin = {
+          attributeTransformer: {
+              myCustomTransformer,
+          }
+      };
+
+  - type: SyntaxHighlighter
+    language: javascript
+    content: |
+      // App.js
+      import { ReactiveJsonRoot, mergeComponentCollections } from "@ea-lab/reactive-json";
+      import { myPlugin } from "./plugins/myPlugin.js";
+
+      const App = () => {
+          return (
+              <ReactiveJsonRoot
+                  plugins={mergeComponentCollections([myPlugin])}
+              />
+          );
+      };
+
+  - type: Markdown
+    content: |
+      ### Usage in RjBuild
+
+      Once registered, your custom transformer can be used in any element:
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      renderView:
+        - type: div
+          attributes:
+            class: "base-class"
+          attributeTransforms:
+            - what: myCustomTransformer
+              name: "data-custom"
+              customProperty: "value"
+              when: ~~.someCondition
+              is: true
+
+  - type: Markdown
+    content: |
+      For detailed component development guidance, see **[Plugin Development](./plugins/index)**.
+
+      ## Execution Order
+
+      Attribute transformers are applied in the order they appear in the `attributeTransforms` array:
+
+      1. Base attributes are evaluated (template resolution)
+      2. Each transformer is applied sequentially
+      3. The final attributes are passed to the component/element
+
+      ## Conditional Execution
+
+      All attribute transformers support the same conditional system as actions:
+
+      - **`when`**: Specifies the data value to evaluate
+      - **`is`**: Exact value comparison
+      - **`isEmpty`/`isNotEmpty`**: Empty/non-empty checks
+      - **Template evaluation**: Full support for `~.`, `~~.`, `~>`, `~~>` patterns
+
+data:
+  page_title: "Attribute Transformers - Reactive-JSON Documentation"
+

package/public/rjbuild/docs/advanced-concepts/data-mapping.md

@@ -1,14 +1,14 @@
-# Data Mapping System
+# Data mapping
 
-Data Mapping is a powerful, extensible system in Reactive-JSON that allows you to selectively dispatch and transform response data from HTTP requests to specific locations in your application state.
+Data mapping is a powerful, extensible system in Reactive-JSON that allows you to selectively dispatch and transform response data from HTTP requests to specific locations in your application state.
 
 ## System Architecture
 
-The Data Mapping system operates **after** Data Processors have processed the response, providing a clean separation of concerns:
+The Data mapping system operates **after** Data Processors have processed the response, providing a clean separation of concerns:
 
 1. **HTTP Request** → Server responds with raw data
 2. **Data Processors** → Transform/validate the raw response  
-3. **Data Mapping** → Selectively dispatch transformed data to application state
+3. **Data mapping** → Selectively dispatch transformed data to application state
 4. **Application State** → Updated with mapped data
 
 ## Core Components
@@ -26,7 +26,7 @@ Reactive-JSON includes **simpleMapping** as a core data mapper, providing string
 
 ## Custom Data Mappers
 
-The Data Mapping system is extensible through custom mapper plugins. You can create specialized mappers for complex transformation logic, integration with external libraries, or domain-specific processing needs.
+The Data mapping system is extensible through custom mapper plugins. You can create specialized mappers for complex transformation logic, integration with external libraries, or domain-specific processing needs.
 
 ### Creating Custom Mappers
 
@@ -53,7 +53,7 @@ Custom mappers are automatically merged with core mappers, allowing you to exten
 
 ## Usage Context
 
-Data Mapping can be used with all HTTP-based data operations in Reactive-JSON:
+Data mapping can be used with all HTTP-based data operations in Reactive-JSON:
 
 - **fetchData & submitData reactions**: Process API responses selectively
 - **additionalDataSources**: Map initial data loading responses

package/public/rjbuild/docs/advanced-concepts/data-mapping.yaml

@@ -1,18 +1,18 @@
 renderView:
   - type: Markdown
     content: |
-      # Data Mapping System
+      # Data mapping
 
-      Data Mapping is a powerful, extensible system in Reactive-JSON that allows you to selectively dispatch and transform response data from HTTP requests to specific locations in your application state. This system provides fine-grained control over how incoming data is processed and stored after HTTP operations.
+      Data mapping is a powerful, extensible system in Reactive-JSON that allows you to selectively dispatch and transform response data from HTTP requests to specific locations in your application state. This system provides fine-grained control over how incoming data is processed and stored after HTTP operations.
 
       Data mapping occurs after the [Data Processors](data-processors) have processed the response.
 
       ## System Architecture
 
-      The Data Mapping system processes HTTP response data to selectively dispatch it to application state:
+      The Data mapping system processes HTTP response data to selectively dispatch it to application state:
 
       1. **HTTP Request** → Server responds with data
-      2. **Data Mapping** → Selectively dispatch response data to application state
+      2. **Data mapping** → Selectively dispatch response data to application state
       3. **Application State** → Updated with mapped data
 
       ## Core Components
@@ -30,7 +30,7 @@ renderView:
 
       ## Custom Data Mappers
 
-      The Data Mapping system is extensible through custom mapper plugins. You can create specialized mappers for complex transformation logic, integration with external libraries, or domain-specific processing needs.
+      The Data mapping system is extensible through custom mapper plugins. You can create specialized mappers for complex transformation logic, integration with external libraries, or domain-specific processing needs.
 
       ### Creating Custom Mappers
 
@@ -68,7 +68,7 @@ renderView:
 
       ## Usage Context
 
-      Data Mapping can be used with all HTTP-based data operations in Reactive-JSON:
+      Data mapping can be used with all HTTP-based data operations in Reactive-JSON:
 
   - type: Markdown
     content: |
@@ -100,7 +100,7 @@ renderView:
 
       ## Plugin System Integration
 
-      The Data Mapping system integrates with Reactive-JSON's plugin architecture:
+      The Data mapping system integrates with Reactive-JSON's plugin architecture:
 
       ```javascript
       import { mergeComponentCollections, ReactiveJsonRoot } from "@ea-lab/reactive-json";

package/public/rjbuild/docs/advanced-concepts/data-processors.md

@@ -1,10 +1,10 @@
-# Data Processors
+# Data processors
 
-Data Processors are a powerful feature in Reactive-JSON that allow you to intercept and modify data received via `fetchData`, `submitData`, and `additionalDataSources`. This enables you to implement data transformation, validation, security filtering, and other data processing logic in a centralized and reusable way.
+Data processors are a powerful feature in Reactive-JSON that allow you to intercept and modify data received via `fetchData`, `submitData`, and `additionalDataSources`. This enables you to implement data transformation, validation, security filtering, and other data processing logic in a centralized and reusable way.
 
-## How Data Processors Work
+## How Data processors Work
 
-When Reactive-JSON receives data from HTTP requests, it automatically passes the data through all registered Data Processors in order. Each processor:
+When Reactive-JSON receives data from HTTP requests, it automatically passes the data through all registered Data processors in order. Each processor:
 
 1. **Examines the request and response context** (URL, method, headers, status, etc.)
 2. **Receives the current data** being processed
@@ -54,14 +54,14 @@ Information about the HTTP response:
 - `data`: Raw response data
 
 ### dataToProcess
-The data currently being processed. This may have been modified by previous Data Processors in the chain.
+The data currently being processed. This may have been modified by previous Data processors in the chain.
 
 ### originalDataToProcess
 The original data before any processing, useful for comparison or logging.
 
 ## Plugin Registration
 
-Data Processors are registered through the plugin system:
+Data processors are registered through the plugin system:
 
 ```javascript
 import { mergeComponentCollections } from "@ea-lab/reactive-json";
@@ -222,7 +222,7 @@ additionalDataSource:
 ## Best Practices
 
 ### Always Return Data
-Data Processors **must always return data**. To skip processing, return the original data:
+Data processors **must always return data**. To skip processing, return the original data:
 
 ```javascript
 const myProcessor = ({ requestContext, responseContext, dataToProcess, originalDataToProcess }) => {

package/public/rjbuild/docs/advanced-concepts/data-processors.yaml

@@ -1,13 +1,13 @@
 renderView:
   - type: Markdown
     content: |
-      # Data Processors
+      # Data processors
 
-      Data Processors are a powerful feature in Reactive-JSON that allow you to intercept and modify data received via `fetchData`, `submitData`, and `additionalDataSources`. This enables you to implement data transformation, validation, security filtering, and other data processing logic in a centralized and reusable way.
+      Data processors are a powerful feature in Reactive-JSON that allow you to intercept and modify data received via `fetchData`, `submitData`, and `additionalDataSources`. This enables you to implement data transformation, validation, security filtering, and other data processing logic in a centralized and reusable way.
 
-      ## How Data Processors Work
+      ## How Data processors Work
 
-      When Reactive-JSON receives data from HTTP requests, it automatically passes the data through all registered Data Processors in order. Each processor:
+      When Reactive-JSON receives data from HTTP requests, it automatically passes the data through all registered Data processors in order. Each processor:
 
       1. **Examines the request and response context** (URL, method, headers, status, etc.)
       2. **Receives the current data** being processed
@@ -73,7 +73,7 @@ renderView:
         details:
           type: Markdown
           content: |
-            The data currently being processed. This may have been modified by previous Data Processors in the chain.
+            The data currently being processed. This may have been modified by previous Data processors in the chain.
 
       - term: originalDataToProcess
         details:
@@ -85,7 +85,7 @@ renderView:
     content: |
       ## Plugin Registration
 
-      Data Processors are registered through the plugin system:
+      Data processors are registered through the plugin system:
 
   - type: SyntaxHighlighter
     language: javascript
@@ -213,7 +213,7 @@ renderView:
       ## Best Practices
 
       ### Always Return Data
-      Data Processors **must always return data**. To skip processing, return the original data:
+      Data processors **must always return data**. To skip processing, return the original data:
 
   - type: SyntaxHighlighter
     language: javascript

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

@@ -1,10 +1,8 @@
-# Forward Update Pattern (Event Placeholders)
-
-Added in **reactive-json@0.0.43**.
+# Forward update
 
 > Use the special placeholder `<reactive-json:event>` to reference values coming directly from the DOM or the custom event that triggered a reaction.
 
-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.
+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.
 
 ## Syntax
 
@@ -19,10 +17,29 @@ value: "<reactive-json:event>.target.checked" # For checkboxes
 
 ### The `<reactive-json:event-new-value>` shortcut
 
-`<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.
+`<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
 
@@ -36,11 +53,31 @@ If no property path is provided (`<reactive-json:event>` alone), nothing is forw
 
 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.
+
+```yaml
+actions:
+  - what: fetchData
+    url: "/api/user-profile.json"
+    on: click
+  - what: setData
+    on: response  # Triggered when fetchData completes
+    path: ~~.userTheme
+    value: <reactive-json:event-new-value>.preferences.theme
+```
+
 ## Typical Use-cases
 
 - Real-time mirroring of form fields
-- “Select all” checkboxes
+- "Select all" checkboxes
 - Forward arbitrary values coming from events
+- Process HTTP response data immediately after fetch operations
 
 ## Examples
 
@@ -90,4 +127,40 @@ renderView:
 data:
   primary_text: ""
   secondary_text: ""
+```
+
+### Response Event Processing
+
+```yaml
+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"
 ```