@ea-lab/reactive-json-docs 0.2.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ea-lab/reactive-json-docs",
-  "version": "0.2.1",
+  "version": "0.4.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": "^0.1.0",
+    "@ea-lab/reactive-json": "^0.3.1",
     "@ea-lab/reactive-json-chartjs": "^0.0.23",
     "@npmcli/fs": "^4.0.0",
     "@reduxjs/toolkit": "^2.6.1",

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

@@ -0,0 +1,76 @@
+# Data Mapping System
+
+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:
+
+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
+4. **Application State** → Updated with mapped data
+
+## Core Components
+
+### SimpleMapping (Core)
+
+Reactive-JSON includes **simpleMapping** as a core data mapper, providing string-based mappings for common data dispatch scenarios:
+
+- **Automatic Availability**: No additional configuration required
+- **String-based Configuration**: YAML-friendly destination → source mappings
+- **Error Handling**: Built-in fallback values and error recovery
+- **Template Integration**: Full support for `~~.` and `~.` template references
+
+**→ [View SimpleMapping Documentation & Examples](../core/dataMapping/simpleMapping)**
+
+## 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.
+
+### Creating Custom Mappers
+
+```javascript
+const customMapper = ({config, responseData, globalDataContext, templateContext}) => {
+  // Custom mapping logic
+  const {updateData} = globalDataContext;
+  
+  // Process config and apply transformations
+  updateData(transformedValue, "destination.path");
+};
+
+// Register in plugin system
+const customPlugins = {
+  dataMapping: {
+    customMapper
+  }
+};
+```
+
+### Integration with Core
+
+Custom mappers are automatically merged with core mappers, allowing you to extend the system while keeping access to `simpleMapping`.
+
+## Usage Context
+
+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
+- **Combined with Data Processors**: Sequential processing pipeline
+
+## Best Practices
+
+1. **Use simpleMapping first**: It handles most common data dispatch scenarios
+2. **Combine with Data Processors**: Let processors handle validation/transformation, mappers handle dispatch
+3. **Template References**: Leverage `~~.` and `~.` for dynamic mappings
+4. **Error Handling**: Always configure `onErrorMap` for critical data paths
+5. **Performance**: Use `required: false` with `defaultValue` for optional fields
+
+## Related Documentation
+
+- [SimpleMapping Examples & Configuration](../core/dataMapping/simpleMapping) - Complete guide to the core mapper
+- [Data Processors](data-processors) - Pre-mapping data transformation
+- [Plugin System](plugins/plugin-system) - Creating custom components
+- [FetchData Reaction](../core/reaction/fetchData) - HTTP request handling
+- [SubmitData Reaction](../core/reaction/submitData) - Form submission with data mapping 

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

@@ -0,0 +1,140 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Data Mapping System
+
+      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:
+
+      1. **HTTP Request** → Server responds with data
+      2. **Data Mapping** → Selectively dispatch response data to application state
+      3. **Application State** → Updated with mapped data
+
+      ## Core Components
+
+      ### SimpleMapping (Core)
+      
+      Reactive-JSON includes **simpleMapping** as a core data mapper, providing string-based mappings for common data dispatch scenarios.
+
+      - **Automatic Availability**: No additional configuration required
+      - **String-based Configuration**: YAML-friendly destination → source mappings
+      - **Error Handling**: Built-in fallback values and error recovery
+      - **Template Integration**: Full support for `~~.` and `~.` template references
+
+      **→ [View SimpleMapping Documentation & Examples](../core/dataMapping/simpleMapping)**
+
+      ## 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.
+
+      ### Creating Custom Mappers
+
+      ```javascript
+      const customMapper = ({config, responseData, globalDataContext, templateContext}) => {
+        // Custom mapping logic
+        const {updateData} = globalDataContext;
+        
+        // Process config and apply transformations
+        updateData(transformedValue, "destination.path");
+      };
+
+      // Register in plugin system
+      const customPlugins = {
+        dataMapping: {
+          customMapper
+        }
+      };
+      ```
+
+      ### Integration with Core
+
+      Custom mappers are automatically merged with core mappers, allowing you to extend the system while keeping access to `simpleMapping`:
+
+      ```yaml
+      dataMapping:
+        simpleMapping:
+          # Core mapper usage
+          stringMap:
+            "~~.profile.name": { value: "user.name" }
+        customMapper:
+          # Your custom mapper configuration
+          specialConfig: "value"
+      ```
+
+      ## Usage Context
+
+      Data Mapping can be used with all HTTP-based data operations in Reactive-JSON:
+
+  - type: Markdown
+    content: |
+      ### fetchData & submitData Reactions
+
+      ```yaml
+      - what: fetchData
+        url: "/api/user-profile"
+        updateOnlyData: true
+        dataMapping:
+          simpleMapping:
+            stringMap:
+              "~~.currentUser.name": { value: "user.name" }
+              "~~.currentUser.email": { value: "user.email" }
+      ```
+
+      ### additionalDataSources  
+
+      ```yaml
+      additionalDataSource:
+        - src: "/api/initial-config"
+          blocking: true
+          dataMapping:
+            simpleMapping:
+              stringMap:
+                "~~.appConfig.theme": { value: "config.theme" }
+                "~~.appConfig.features": { value: "config.enabled_features" }
+      ```
+
+      ## Plugin System Integration
+
+      The Data Mapping system integrates with Reactive-JSON's plugin architecture:
+
+      ```javascript
+      import { mergeComponentCollections, ReactiveJsonRoot } from "@ea-lab/reactive-json";
+
+      const customPlugins = {
+        dataMapping: {
+          // Custom mappers
+          advancedMapper: myAdvancedMapper,
+          xmlMapper: myXmlMapper
+        }
+      };
+
+      // Core plugins (including simpleMapping) are automatically merged
+      const plugins = mergeComponentCollections([customPlugins]);
+
+      export const MyApp = (props) => (
+        <ReactiveJsonRoot {...props} plugins={plugins} />
+      );
+      ```
+
+      ## Best Practices
+
+      1. **Use simpleMapping first**: It handles most common data dispatch scenarios
+      2. **Template References**: Leverage `~~.` and `~.` for dynamic mappings
+      3. **Error Handling**: Always configure `onErrorMap` for critical data paths
+      4. **Performance**: Use `required: false` with `defaultValue` for optional fields
+
+      ## Related Documentation
+
+      - **[SimpleMapping Examples & Configuration](../core/dataMapping/simpleMapping)** - Complete guide to the core mapper
+      - **[Plugin System](plugins/plugin-system)** - Creating custom components
+      - **[FetchData Reaction](../core/reaction/fetchData)** - HTTP request handling
+      - **[SubmitData Reaction](../core/reaction/submitData)** - Form submission with data mapping
+
+templates:
+
+data: 

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

@@ -0,0 +1,373 @@
+# 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.
+
+## 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:
+
+1. **Examines the request and response context** (URL, method, headers, status, etc.)
+2. **Receives the current data** being processed
+3. **Must return the data** - either transformed or unchanged
+4. **Chains with other processors** (processed data flows to the next processor)
+
+## Basic Structure
+
+A Data Processor is a function that receives context and data, then **must return** the processed data:
+
+```javascript
+const myDataProcessor = ({ requestContext, responseContext, dataToProcess, originalDataToProcess }) => {
+    // Check if we want to process this data
+    if (!requestContext.url.includes('/api/users')) {
+        return dataToProcess; // Return unchanged data
+    }
+    
+    // Check response status
+    if (responseContext.status >= 400) {
+        return dataToProcess; // Return unchanged data
+    }
+    
+    // Transform the data
+    const processedData = {
+        ...dataToProcess,
+        timestamp: new Date().toISOString(),
+        source: requestContext.url
+    };
+    
+    return processedData; // Return transformed data
+};
+```
+
+## Function Parameters
+
+### requestContext
+Information about the HTTP request:
+- `url`: The URL that was called
+- `method`: HTTP method (GET, POST, etc.)
+- `headers`: Request headers object
+- `body`: Request body (for POST, PUT, etc.)
+
+### responseContext
+Information about the HTTP response:
+- `headers`: Response headers object
+- `status`: HTTP status code (200, 404, etc.)
+- `data`: Raw response data
+
+### dataToProcess
+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:
+
+```javascript
+import { mergeComponentCollections } from "@ea-lab/reactive-json";
+
+const myPlugins = {
+    element: {
+        // Your custom components
+    },
+    dataProcessor: {
+        "timestamp-processor": { 
+            callback: timestampProcessor, 
+            order: 0 
+        },
+        "security-filter": { 
+            callback: securityProcessor, 
+            order: 10 
+        }
+    }
+};
+
+export const MyReactiveJsonRoot = (props) => {
+    const plugins = mergeComponentCollections([myPlugins]);
+    return <ReactiveJsonRoot {...props} plugins={plugins} />;
+};
+```
+
+### Plugin Structure
+- **Key**: Unique identifier for the processor
+- **callback**: The processor function
+- **order**: Execution order (lower numbers run first)
+
+## Common Use Cases
+
+### Adding Timestamps
+
+```javascript
+const timestampProcessor = ({ requestContext, responseContext, dataToProcess, originalDataToProcess }) => {
+    if (typeof dataToProcess !== 'object' || dataToProcess === null) {
+        return dataToProcess; // Return unchanged for non-objects
+    }
+    
+    return {
+        ...dataToProcess,
+        __metadata: {
+            processedAt: new Date().toISOString(),
+            sourceUrl: requestContext.url,
+            responseStatus: responseContext.status
+        }
+    };
+};
+```
+
+### Security Filtering
+
+```javascript
+const securityProcessor = ({ requestContext, responseContext, dataToProcess, originalDataToProcess }) => {
+    // Only filter external API responses
+    if (!requestContext.url.includes('external-api')) {
+        return dataToProcess; // Return unchanged
+    }
+    
+    if (typeof dataToProcess !== 'object' || dataToProcess === null) {
+        return dataToProcess; // Return unchanged for non-objects
+    }
+    
+    // Remove sensitive fields
+    const sensitiveFields = ['password', 'secret', 'apiKey', 'token'];
+    const cleanedData = { ...dataToProcess };
+    
+    sensitiveFields.forEach(field => {
+        if (cleanedData.hasOwnProperty(field)) {
+            delete cleanedData[field];
+            console.log(`🔒 Removed sensitive field: ${field}`);
+        }
+    });
+    
+    return cleanedData;
+};
+```
+
+### Data Format Transformation
+
+```javascript
+const dateFormatProcessor = ({ requestContext, responseContext, dataToProcess, originalDataToProcess }) => {
+    if (typeof dataToProcess !== 'object' || dataToProcess === null) {
+        return dataToProcess; // Return unchanged for non-objects
+    }
+    
+    const processedData = { ...dataToProcess };
+    
+    // Convert DD/MM/YYYY dates to YYYY-MM-DD
+    Object.keys(processedData).forEach(key => {
+        if (typeof processedData[key] === 'string' && /^\d{2}\/\d{2}\/\d{4}$/.test(processedData[key])) {
+            const [day, month, year] = processedData[key].split('/');
+            processedData[key] = `${year}-${month}-${day}`;
+        }
+    });
+    
+    return processedData;
+};
+```
+
+### 4. Conditional Processing
+
+```javascript
+const userDataProcessor = ({ requestContext, responseContext, dataToProcess, originalDataToProcess }) => {
+    // Only process successful user API responses
+    if (!requestContext.url.includes('/api/users') || responseContext.status !== 200) {
+        return dataToProcess; // Return unchanged
+    }
+    
+    if (typeof dataToProcess !== 'object' || dataToProcess === null) {
+        return dataToProcess; // Return unchanged for non-objects
+    }
+    
+    // Add user-specific processing
+    return {
+        ...dataToProcess,
+        fullName: `${dataToProcess.firstName} ${dataToProcess.lastName}`,
+        isActive: dataToProcess.status === 'active',
+        permissions: dataToProcess.role === 'admin' ? ['read', 'write', 'delete'] : ['read']
+    };
+};
+```
+
+## RjBuild vs Data Processing
+
+The system automatically detects whether the response is a complete RjBuild or just data:
+
+- **Complete RjBuild**: Processors only modify the `data` section
+- **Data only**: Processors modify the entire response
+
+This happens automatically based on the `updateOnlyData` parameter in `fetchData`/`submitData`.
+
+## Execution Context
+
+### With `fetchData`/`submitData`
+```yaml
+- type: button
+  content: "Load User Data"
+  actions:
+    - what: fetchData
+      on: click
+      url: "/api/users/123"
+      refreshAppOnResponse: true
+      updateOnlyData: false # The response is expected to be a complete RjBuild.
+      # When the response is a complete RjBuild, the processors will receive the data only.
+```
+
+### With `additionalDataSources`
+```yaml
+additionalDataSource:
+  - src: "/api/config"
+    path: "~~.config"
+    # Processors will automatically process this data
+```
+
+## Best Practices
+
+### Always Return Data
+Data Processors **must always return data**. To skip processing, return the original data:
+
+```javascript
+const myProcessor = ({ requestContext, responseContext, dataToProcess, originalDataToProcess }) => {
+    // Skip processing for certain conditions
+    if (!requestContext.url.includes('/api/')) {
+        return dataToProcess; // Return unchanged
+    }
+    if (responseContext.status >= 400) {
+        return dataToProcess; // Return unchanged
+    }
+    if (typeof dataToProcess !== 'object') {
+        return dataToProcess; // Return unchanged
+    }
+    
+    // Process and return transformed data
+    return { ...dataToProcess, processed: true };
+};
+```
+
+### Immutable Updates
+Always clone data before modifying:
+
+```javascript
+const processedData = { ...dataToProcess }; // Shallow clone
+// Or for deep cloning, use JSON.parse(JSON.stringify(...)):
+const processedData = JSON.parse(JSON.stringify(dataToProcess));
+// Or with lodash:
+const processedData = _.cloneDeep(dataToProcess);
+```
+
+### Error Handling
+The system automatically catches errors, but you can add your own:
+
+```javascript
+const safeProcessor = ({ requestContext, responseContext, dataToProcess, originalDataToProcess }) => {
+    try {
+        // Your processing logic
+        return processedData;
+    } catch (error) {
+        console.error('Processing failed:', error);
+        return dataToProcess; // Return original data on error
+    }
+};
+```
+
+### 4. Descriptive IDs and Ordering
+Use clear names and logical ordering:
+
+```javascript
+const plugins = {
+    dataProcessor: {
+        "01-timestamp": { callback: timestampProcessor, order: 0 },
+        "02-security": { callback: securityProcessor, order: 10 },
+        "03-formatting": { callback: formatProcessor, order: 20 }
+    }
+};
+```
+
+## Debugging
+
+### Logging
+Add console logs to understand the flow:
+
+```javascript
+const debugProcessor = ({ requestContext, responseContext, dataToProcess, originalDataToProcess }) => {
+    console.log('🔍 Processing:', requestContext.url);
+    console.log('📊 Status:', responseContext.status);
+    console.log('📥 Data keys:', Object.keys(dataToProcess));
+    
+    // Your processing logic
+    const processedData = { ...dataToProcess, debug: true };
+    
+    console.log('📤 Processed keys:', Object.keys(processedData));
+    return processedData;
+};
+```
+
+### Browser DevTools
+The system automatically logs processor errors to the console, making debugging straightforward.
+
+## Complete Example
+
+Here's a comprehensive example showing multiple processors working together:
+
+```javascript
+import { mergeComponentCollections } from "@ea-lab/reactive-json";
+
+// Utility processors
+const timestampProcessor = ({ requestContext, responseContext, dataToProcess, originalDataToProcess }) => {
+    if (typeof dataToProcess !== 'object' || dataToProcess === null) {
+        return dataToProcess;
+    }
+    
+    return {
+        ...dataToProcess,
+        __processed: {
+            timestamp: new Date().toISOString(),
+            url: requestContext.url,
+            status: responseContext.status
+        }
+    };
+};
+
+const securityProcessor = ({ requestContext, responseContext, dataToProcess, originalDataToProcess }) => {
+    if (!requestContext.url.includes('external')) {
+        return dataToProcess;
+    }
+    if (typeof dataToProcess !== 'object' || dataToProcess === null) {
+        return dataToProcess;
+    }
+    
+    const cleaned = { ...dataToProcess };
+    ['password', 'secret', 'token'].forEach(field => delete cleaned[field]);
+    return cleaned;
+};
+
+const userDataProcessor = ({ requestContext, responseContext, dataToProcess, originalDataToProcess }) => {
+    if (!requestContext.url.includes('/users')) {
+        return dataToProcess;
+    }
+    if (typeof dataToProcess !== 'object' || dataToProcess === null) {
+        return dataToProcess;
+    }
+    
+    return {
+        ...dataToProcess,
+        displayName: `${dataToProcess.firstName} ${dataToProcess.lastName}`,
+        isOnline: dataToProcess.lastSeen && 
+                 (Date.now() - new Date(dataToProcess.lastSeen).getTime()) < 300000 // 5 minutes
+    };
+};
+
+const myPlugins = {
+    element: {
+        // Your components
+    },
+    dataProcessor: {
+        "timestamp": { callback: timestampProcessor, order: 0 },
+        "security": { callback: securityProcessor, order: 5 },
+        "user-enhancement": { callback: userDataProcessor, order: 10 }
+    }
+};
+
+export const MyApp = (props) => {
+    const plugins = mergeComponentCollections([myPlugins]);
+    return <ReactiveJsonRoot {...props} plugins={plugins} />;
+};
+```