@ea-lab/reactive-json-docs 0.3.0 → 0.5.0

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

@@ -0,0 +1,309 @@
+renderView:
+  - type: Markdown
+    content: |
+      # 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)
+
+  - type: Markdown
+    content: |
+      ## Basic Structure
+
+      A Data Processor is a function that receives context and data, then **must return** the processed data:
+
+  - type: SyntaxHighlighter
+    language: javascript
+    content: |
+      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
+      };
+
+  - type: Markdown
+    content: |
+      ## Function Parameters
+
+  - type: DefinitionList
+    content:
+      - term: requestContext
+        details:
+          type: Markdown
+          content: |
+            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.)
+
+      - term: responseContext
+        details:
+          type: Markdown
+          content: |
+            Information about the HTTP response:
+            - `headers`: Response headers object
+            - `status`: HTTP status code (200, 404, etc.)
+            - `data`: Raw response data
+
+      - term: dataToProcess
+        details:
+          type: Markdown
+          content: |
+            The data currently being processed. This may have been modified by previous Data Processors in the chain.
+
+      - term: originalDataToProcess
+        details:
+          type: Markdown
+          content: |
+            The original data before any processing, useful for comparison or logging.
+
+  - type: Markdown
+    content: |
+      ## Plugin Registration
+
+      Data Processors are registered through the plugin system:
+
+  - type: SyntaxHighlighter
+    language: javascript
+    content: |
+      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} />;
+      };
+
+  - type: Markdown
+    content: |
+      ### Plugin Structure
+
+  - type: DefinitionList
+    content:
+      - term: Key
+        details: Unique identifier for the processor.
+      - term: callback
+        details: The processor function.
+      - term:
+          code: order
+          after: "(number)"
+        details: Execution order (lower numbers run first).
+
+  - type: Markdown
+    content: |
+      ## Common Use Cases
+
+      ### Adding Timestamps
+
+  - type: SyntaxHighlighter
+    language: javascript
+    content: |
+      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
+              }
+          };
+      };
+
+  - type: Markdown
+    content: |
+      ### Security Filtering
+
+  - type: SyntaxHighlighter
+    language: javascript
+    content: |
+      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;
+      };
+
+  - type: Markdown
+    content: |
+      ### Data Format Transformation
+
+  - type: SyntaxHighlighter
+    language: javascript
+    content: |
+      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;
+      };
+
+  - type: Markdown
+    content: |
+      ## Best Practices
+
+      ### Always Return Data
+      Data Processors **must always return data**. To skip processing, return the original data:
+
+  - type: SyntaxHighlighter
+    language: javascript
+    content: |
+      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 };
+      };
+
+  - type: Markdown
+    content: |
+      ### Immutable Updates
+      Always clone data before modifying:
+
+  - type: SyntaxHighlighter
+    language: javascript
+    content: |
+      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);
+
+  - type: Markdown
+    content: |
+      ### Error Handling
+      The system automatically catches errors, but you can add your own:
+
+  - type: SyntaxHighlighter
+    language: javascript
+    content: |
+      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
+          }
+      };
+
+  - type: Markdown
+    content: |
+      ## 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`
+
+  - type: SyntaxHighlighter
+    language: yaml
+    content: |
+      - 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.
+
+  - type: Markdown
+    content: |
+      ### With `additionalDataSources`
+
+  - type: SyntaxHighlighter
+    language: yaml
+    content: |
+      additionalDataSource:
+        - src: "/api/config"
+          path: "~~.config"
+          # Processors will automatically process this data
+
+data:

package/public/rjbuild/docs/advanced-concepts/index.md

@@ -0,0 +1,10 @@
+# Advanced Concepts
+
+This section covers advanced features and concepts in Reactive-JSON that enable more sophisticated data processing and application behavior.
+
+## Topics
+
+- **[Data Mapping](data-mapping.md)**: Learn how to selectively dispatch and transform response data using the Data Mapping system
+- **[Data Processors](data-processors.md)**: Learn how to intercept and modify data from HTTP requests using the DataProcessor system
+- **[Forward Update](forward-update.md)**: Implementation details about the retrieval of event values.
+- **[Plugins](plugins/index.md)**: Learn how to extend Reactive-JSON with custom components and plugins.

package/public/rjbuild/docs/advanced-concepts/index.yaml

@@ -0,0 +1,16 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Advanced Concepts
+
+      This section covers advanced features and concepts in Reactive-JSON that enable more sophisticated data processing and application behavior.
+
+      ## Topics
+
+      - **[Data Mapping](data-mapping)**: Learn how to selectively dispatch and transform response data using the Data Mapping system.
+      - **[Data Processors](data-processors)**: Learn how to intercept and modify data from HTTP requests using the DataProcessor system.
+      - **[Forward Update](forward-update)**: Implementation details about the retrieval of event values.
+      - **[Plugins](plugins/index)**: Learn how to extend Reactive-JSON with custom components and plugins.
+
+data:
+  page_title: "Advanced Concepts - Reactive-JSON Documentation" 

package/public/rjbuild/docs/{extend → advanced-concepts/plugins}/component-development-guide-llm.md

@@ -277,6 +277,8 @@ export const CustomRoot = (props) => {
 ```js
 {
     action: { /* Action components */ },
+    dataMapping: { /* Data mapping processors */ },
+    dataProcessor: { /* Data processing functions */ },
     element: { /* Element components */ },
     hook: { /* React hooks */ },
     reaction: { /* Reaction functions */ },

package/public/rjbuild/docs/{extend → advanced-concepts/plugins}/component-development.md

@@ -19,7 +19,7 @@ All components have access to these React contexts:
 - **TemplateContext**: Contains current template data for evaluation
 
 Other specialized contexts are available.
-- **EventDispatcherContext**: Centralized event handling system, mostly used by the [reaction system](/docs/core/reaction/index).
+- **EventDispatcherContext**: Centralized event handling system, mostly used by the [reaction system](/docs/getting-started/reactions).
 - **PaginationContext**: Used by components that integrate pagination, such as [Switch](/docs/core/element/special/Switch).
 
 ## Basic Element Component

package/public/rjbuild/docs/{extend → advanced-concepts/plugins}/component-development.yaml

@@ -22,7 +22,7 @@ renderView:
       - **TemplateContext**: Contains current template data for evaluation
 
       Other specialized contexts are available.
-      - **EventDispatcherContext**: Centralized event handling system, mostly used by the [reaction system](/docs/core/reaction/index).
+      - **EventDispatcherContext**: Centralized event handling system, mostly used by the [reaction system](/docs/getting-started/reactions).
       - **PaginationContext**: Used by components that integrate pagination, such as [Switch](/docs/core/element/special/Switch).
 
       ## Basic Element Component

package/public/rjbuild/docs/{extend → advanced-concepts/plugins}/plugin-system.md

@@ -12,6 +12,8 @@ A plugin is a JavaScript object that exports components organized by type. The s
 - **action**: Components that perform side effects or modify behavior
 - **reaction**: Event-driven components that respond to user interactions
 - **hook**: React hooks that provide additional functionality
+- **dataProcessor**: Functions that intercept and modify HTTP response data
+- **dataMapping**: Processors that selectively dispatch response data to specific locations
 
 ## Plugin Registration
 

package/public/rjbuild/docs/{extend → advanced-concepts/plugins}/plugin-system.yaml

@@ -15,6 +15,8 @@ renderView:
       - **action**: Components that perform side effects or modify behavior
       - **reaction**: Event-driven components that respond to user interactions
       - **hook**: React hooks that provide additional functionality
+      - **dataProcessor**: Functions that intercept and modify HTTP response data
+      - **dataMapping**: Processors that selectively dispatch response data to specific locations
 
       ## Plugin Registration
 

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

@@ -19,4 +19,4 @@ renderView:
 ```
 
 ## Limitation
-- The element no longer exists in the DOM, so no events can be attached to it. 
+- When hidden, the element no longer exists in the DOM, so no events can be attached to it. 

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

@@ -30,31 +30,31 @@ renderView:
               actions:
                 - what: setData
                   on: click
-                  path: "shouldHide"
-                  value: ~.shouldHide
-                  is: false
+                  path: ~.shouldHide
+                  value: "true"
+                  when: ~.shouldHide
+                  is: "false"
                 - what: setData
                   on: click
-                  path: "shouldHide"
-                  value: ~.shouldHide
-                  is: true
+                  path: ~.shouldHide
+                  value: "false"
                   when: ~.shouldHide
-                  is: false
+                  is: "true"
 
             - type: div
               content: "This text will be hidden when shouldHide is true."
               actions:
                 - what: hide
                   when: ~.shouldHide
-                  is: true
+                  is: "true"
 
             - type: div
               content: ["Current state: shouldHide = ", ~.shouldHide]
 
       data:
-        shouldHide: false
+        shouldHide: "false"
 
   - type: Markdown
     content: |
       ## Limitation
-      - The element no longer exists in the DOM, so no events can be attached to it. 
+      - When hidden, the element no longer exists in the DOM, so no events can be attached to it. 

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

@@ -1,8 +1,8 @@
 # ReactOnEvent
 
-**Type**: Internal Action Component
+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.
 
-**Description**: 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.
+> **Important**: It should **not** be used directly as an element type. The Reactive-JSON engine will automatically instantiate it when needed.
 
 ## How it Works
 
@@ -43,8 +43,8 @@ ReactOnEvent supports any DOM event by prefixing with `on` and capitalizing the
 
 Some events have special handling and **do not** use ReactOnEvent:
 
-- `on: "message"` → Uses MessageListener component (listens on window)
-- `on: "hashchange"` → Uses HashChangeListener component (listens on window)
+- `on: "message"` → Uses the [MessageListener](MessageListener.md) component (listens on window)
+- `on: "hashchange"` → Uses the [HashChangeListener](HashChangeListener.md) component (listens on window)
 
 ## Event Propagation Control
 
@@ -67,15 +67,15 @@ actions:
 - **Context preservation**: Maintains access to global and template data contexts
 - **Early termination**: Supports `stopPropagation: true` to halt reaction chain execution
 
+## Important Notes
+
+- **Never use `type: ReactOnEvent`** in your renderView - 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
+- **Event propagation is stopped by default** - use `stopPropagation: false` to change this
+
 ## Related Components
 
 - **[MessageListener](MessageListener.md)**: Handles `on: "message"` events
 - **[HashChangeListener](HashChangeListener.md)**: Handles `on: "hashchange"` events
-- **[Reactions System](../reaction/index.md)**: The actual reaction functions that ReactOnEvent executes
-
-## Important Notes
-
-- **Not for direct use**: Never use `type: ReactOnEvent` in your renderView
-- **Automatic instantiation**: The Actions system creates this component automatically
-- **Internal implementation**: This is part of the framework's internal architecture
-- **Event binding**: Events are bound to the actual DOM elements, not wrapper components 
+- **[Reactions System](../../getting-started/reactions.md)**: The actual reaction functions that ReactOnEvent executes

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

@@ -3,9 +3,9 @@ renderView:
     content: |
       # ReactOnEvent
 
-      **Type**: Internal Action Component
-
-      **Description**: 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.
+      
+      > **Important**: It should **not** be used directly as an element type. The Reactive-JSON engine will automatically instantiate it when needed.
 
       ## How it Works
 
@@ -16,105 +16,66 @@ renderView:
       3. Creates a ReactOnEvent component that attaches the appropriate event listeners
       4. Wraps the target element with these event handlers
 
-  - type: RjBuildDescriber
-    title: "Correct Usage: Reactions with Events"
-    description:
-      - type: Markdown
-        content: |
-          This example shows the **correct** way to use event handling in Reactive-JSON. 
-          
-          ReactOnEvent is automatically created by the system when you use `on: "eventName"` in actions.
+      ## Usage Pattern
 
-    toDescribe:
-      renderView:
-        - type: div
-          content:
-            - type: button
-              content: "Click me"
-              actions:
-                - what: setData
-                  on: click              # ReactOnEvent handles this automatically
-                  path: "clicked"
-                  value: true
-                - what: setData
-                  on: click
-                  path: "clickCount"
-                  value: 1
-                  when: ~.clickCount
-                  isEmpty: true
-                - what: setData
-                  on: click
-                  path: "clickCount"
-                  value: "~.clickCount + 1"
-                  when: ~.clickCount
-                  isEmpty: "not"
-                  
-            - type: input
-              props:
-                type: "text"
-                placeholder: "Type something..."
-              actions:
-                - what: setData
-                  on: change           # ReactOnEvent handles this automatically
-                  path: "inputValue"
-                  value: "~event.target.value"
-                  
-            - type: div
-              content: "Mouse over this area"
-              props:
-                style:
-                  padding: "10px"
-                  border: "1px solid #ccc"
-                  backgroundColor: "~.hovered ? '#f0f0f0' : 'white'"
-              actions:
-                - what: setData
-                  on: mouseover       # ReactOnEvent handles this automatically
-                  path: "hovered"
-                  value: true
-                - what: setData
-                  on: mouseleave      # ReactOnEvent handles this automatically
-                  path: "hovered"
-                  value: false
-              
-        - type: div
-          content:
-            - type: div
-              content: ["Button clicked: ", ~.clicked]
-              
-            - type: div
-              content: ["Click count: ", ~.clickCount]
-              
-            - type: div
-              content: ["Input value: '", ~.inputValue, "'"]
-              
-            - type: div
-              content: ["Mouse hover state: ", ~.hovered]
+      Instead of using ReactOnEvent directly, you define reactions in the `actions` array of any element:
 
+      ```yaml
+      renderView:
         - type: button
-          content: "Reset all"
+          content: "Click me"
           actions:
             - what: setData
-              on: click
-              path: "clicked"
-              value: false
-            - what: setData
-              on: click
-              path: "clickCount"
-              value: 0
-            - what: setData
-              on: click
-              path: "inputValue"
-              value: ""
-            - what: setData
-              on: click
-              path: "hovered"
-              value: false
+              on: click           # This triggers ReactOnEvent internally
+              path: "buttonClicked"
+              value: true
+      ```
+
+      ## Supported Event Types
+
+      ReactOnEvent supports any DOM event by prefixing with `on` and capitalizing the first letter:
+
+      - `on: click` → `onClick`
+      - `on: change` → `onChange`
+      - `on: mouseover` → `onMouseOver`
+      - `on: keydown` → `onKeyDown`
+      - `on: submit` → `onSubmit`
+      - etc.
+
+      ## Special Event Handling
+
+      Some events have special handling and **do not** use ReactOnEvent:
+
+      - `on: "message"` → Uses the [MessageListener](MessageListener.md) component (listens on window)
+      - `on: "hashchange"` → Uses the [HashChangeListener](HashChangeListener.md) component (listens on window)
+
+      ## Event Propagation Control
+
+      By default, ReactOnEvent stops event propagation. You can control this behavior:
+
+      ```yaml
+      actions:
+        - what: setData
+          on: click
+          path: "clicked"
+          value: true
+          stopPropagation: false  # Allow event to continue propagating
+      ```
+
+      ## Event Placeholders
+
+      ReactOnEvent supports special placeholders to access event data:
+
+      - `<reactive-json:event-new-value>`: Returns the most relevant value from form events (checked for checkboxes, value for inputs)
+      - `<reactive-json:event>.propertyPath`: Access any event property (e.g., `.data.message` for MessageEvent, `.key` for KeyboardEvent)
+
+      ## Technical Implementation
 
-      data:
-        clicked: false
-        clickCount: 0
-        inputValue: ""
-        hovered: false
+      - **Event attachment**: Uses React's event system via `cloneElement`
+      - **Multiple events**: Can handle multiple event types on the same element
+      - **Reaction execution**: Executes reactions in the order they appear
+      - **Context preservation**: Maintains access to global and template data contexts
+      - **Early termination**: Supports `stopPropagation: true` to halt reaction chain execution
 
   - type: Markdown
     content: |
@@ -125,9 +86,8 @@ renderView:
       - **ReactOnEvent is automatically instantiated** by the Actions system when needed
       - **Event propagation is stopped by default** - use `stopPropagation: false` to change this
       
-      ## Related Documentation
+      ## Related Components
       
-      - **[Actions System](index.md)**: Learn about the actions system that uses ReactOnEvent
-      - **[Reactions](../reaction/index.md)**: The reaction functions that ReactOnEvent executes
-      - **[MessageListener](MessageListener.md)**: For `on: "message"` events
-      - **[HashChangeListener](HashChangeListener.md)**: For `on: "hashchange"` events 
+      - **[MessageListener](MessageListener.md)**: Handles `on: "message"` events
+      - **[HashChangeListener](HashChangeListener.md)**: Handles `on: "hashchange"` events
+      - **[Reactions System](../../getting-started/reactions.md)**: The actual reaction functions that ReactOnEvent executes