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

package/public/rjbuild/docs/core/dataMapping/index.md

@@ -0,0 +1,31 @@
+# Data Mapping Components
+
+Data mapping components process and transform HTTP response data to specific locations in your application state. These components work with `fetchData`, `submitData` reactions, and `additionalDataSources`.
+
+## Core Data Mappers
+
+### SimpleMapping
+The foundational data mapper that provides string-based mappings for selective data dispatch.
+
+- **Purpose**: Map HTTP response fields to application data paths
+- **Configuration**: YAML-based string mappings with destination templates
+- **Features**: Required fields, default values, error handling, update modes
+- **Use Cases**: User profiles, settings, API data transformation
+- **Documentation**: [SimpleMapping Guide](simpleMapping.md) | [Interactive Examples](simpleMapping)
+
+## Architecture
+
+Data mapping 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
+
+## Creating Custom Data Mappers
+
+For information about creating custom data mappers and the broader Data Mapping system architecture, see the [Data Mapping Documentation](../../advanced-concepts/data-mapping).
+
+## Related
+
+- [Data Mapping System](../../advanced-concepts/data-mapping) - System overview and custom mappers
+- [Plugin System](../../advanced-concepts/plugins/plugin-system) - Component architecture 

package/public/rjbuild/docs/core/dataMapping/index.yaml

@@ -0,0 +1,24 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Data Mapping Components
+
+      Data mapping components process and transform HTTP response data to specific locations in your application state. These components work with `fetchData`, `submitData` reactions, and `additionalDataSources`.
+
+      ## Core Data Mappers
+
+      ### [SimpleMapping](simpleMapping)
+      The foundational data mapper that provides string-based mappings for selective data dispatch.
+
+      - **Purpose**: Map HTTP response fields to application data paths
+      - **Configuration**: YAML-based string mappings with destination templates
+      - **Features**: Required fields, default values, error handling, update modes
+      - **Use Cases**: User profiles, settings, API data transformation
+
+      ## Creating Custom Data Mappers
+
+      For information about creating custom data mappers and the broader Data Mapping system architecture, see the **[Data Mapping Documentation](../../advanced-concepts/data-mapping)**.
+
+templates:
+
+data: 

package/public/rjbuild/docs/core/dataMapping/simpleMapping.md

@@ -0,0 +1,131 @@
+# SimpleMapping
+
+SimpleMapping is the core data mapping processor in Reactive-JSON that enables selective dispatch and transformation of HTTP response data to specific locations in your application state. It provides a straightforward, configuration-driven approach to map response fields to application data paths.
+
+## Properties
+
+### stringMap Configuration
+
+- `value` (string, required): Source path in the HTTP response (e.g., `user.firstName`)
+- `required` (boolean, optional, default: true): Whether the source value must exist
+- `defaultValue` (any, optional): Fallback value when source is missing and not required
+- `updateMode` (string, optional, default: "replace"): How to apply the value (`replace`, `add`, `move`, `remove`)
+
+### onErrorMap Configuration
+
+- `value` (string, required): Can be either static values (e.g., `Error occurred`) or template references (e.g., `~~.errorTimestamp`)
+
+## Configuration Structure
+
+The `onErrorMap` works like `stringMap`, but provides fallback values when main mappings fail. Same key-value structure as `stringMap` (destination → configuration). Applied only when corresponding `stringMap` entries fail and are marked as `required: true`.
+
+## Basic Example
+
+```yaml
+- what: fetchData
+  url: "/api/user-profile"
+  updateOnlyData: true
+  dataMapping:
+    simpleMapping:
+      stringMap:
+        "~~.currentUser.name":
+          value: "user.firstName"
+        "~~.currentUser.email":
+          value: "user.email"
+        "~~.settings.theme":
+          value: "user.preferences.theme"
+          required: false
+          defaultValue: "light"
+
+data:
+  currentUser: {}
+  settings: {}
+```
+
+## Error Handling Example
+
+```yaml
+- what: fetchData
+  url: "/api/incomplete-data"
+  updateOnlyData: true
+  dataMapping:
+    simpleMapping:
+      stringMap:
+        "~~.profile.name":
+          value: "user.name"
+          required: true
+        "~~.profile.email":
+          value: "user.email"
+          required: true
+      onErrorMap:
+        "~~.profile.status":
+          value: "Error loading profile"
+        "~~.profile.name":
+          value: "Unknown User"
+        "~~.profile.email":
+          value: "unknown@example.com"
+        "~~.profile.loadedAt":
+          value: "~~.currentTimestamp"
+
+data:
+  profile: {}
+  currentTimestamp: "2024-01-15T10:30:00Z"
+```
+
+## Advanced Configuration
+
+```yaml
+dataMapping:
+  simpleMapping:
+    stringMap:
+      "~~.order.id":
+        value: "order.id"
+      "~~.order.customerName":
+        value: "order.customer.name"
+      "~~.order.customerEmail":
+        value: "order.customer.contact.email"
+      "~~.order.total":
+        value: "order.billing.total"
+      "~~.order.currency":
+        value: "order.billing.currency"
+        required: false
+        defaultValue: "USD"
+```
+
+## Integration with additionalDataSources
+
+```yaml
+additionalDataSource:
+  - src: "/api/user-profile"
+    blocking: true
+    dataMapping:
+      simpleMapping:
+        stringMap:
+          "~~.profile.displayName":
+            value: "user.name"
+          "~~.profile.email":
+            value: "user.email"
+          "~~.settings.theme":
+            value: "user.preferences.theme"
+            required: false
+            defaultValue: "light"
+
+data:
+  profile: {}
+  settings: {}
+```
+
+## Usage Context
+
+SimpleMapping is automatically available as part of the core Reactive-JSON plugins and can be used in:
+
+- **fetchData reactions**: Process API responses selectively
+- **submitData reactions**: Handle server responses after form submissions
+- **additionalDataSources**: Map initial data loading responses
+
+## Related
+
+- [Data Mapping System Overview](../../advanced-concepts/data-mapping) - Complete system architecture and custom mappers
+- [FetchData Reaction](../reaction/fetchData) - HTTP request handling with data mapping
+- [SubmitData Reaction](../reaction/submitData) - Form submission with data mapping
+- [Plugin System](../../advanced-concepts/plugins/plugin-system) - Component architecture 

package/public/rjbuild/docs/core/dataMapping/simpleMapping.yaml

@@ -0,0 +1,376 @@
+renderView:
+  - type: Markdown
+    content: |
+      # SimpleMapping Data Mapper
+
+      SimpleMapping is the core data mapping processor in Reactive-JSON that enables selective dispatch and transformation of HTTP response data to specific locations in your application state.
+
+      ## Properties
+
+      ### stringMap Configuration
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: value
+          after: " (required)"
+        details:
+          type: Markdown
+          content: |
+            Source path in the HTTP response (e.g., `user.firstName`)
+      - term:
+          code: required
+          after: " (optional, default: true)"
+        details:
+          type: Markdown
+          content: |
+            Whether the source value must exist
+      - term:
+          code: defaultValue
+          after: " (optional)"
+        details:
+          type: Markdown
+          content: |
+            Fallback value when source is missing and not required
+      - term:
+          code: updateMode
+          after: " (optional, default: \"replace\")"
+        details:
+          type: Markdown
+          content: |
+            How to apply the value (`"replace"`, `"add"`, `"move"`, `"remove"`)
+
+  - type: Markdown
+    content: |
+      ### onErrorMap Configuration
+
+      The `onErrorMap` works like `stringMap`, but provides fallback values when main mappings fail.
+
+      Same key-value structure as `stringMap` (destination → configuration)
+      Applied only when corresponding `stringMap` entries fail and are marked as `required: true`.
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: value
+          after: " (required)"
+        details:
+          type: Markdown
+          content: |
+            Can be either static values (e.g., `Error occurred`) or template references (e.g., `~~.errorTimestamp`)
+
+  - type: Markdown
+    content: |
+      ## Basic Syntax
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      dataMapping:
+        simpleMapping:
+          stringMap:
+            "~~.app.data.path":
+              value: "response.data.path"
+              required: true
+              defaultValue: "fallback"
+              updateMode: "replace"
+          onErrorMap:
+            "~~.error.path":
+              value: "Error message or ~~.template.reference"
+
+  - type: Markdown
+    content: |
+      ## Live Example
+
+  - type: RjBuildDescriber
+    title: "Basic Data Mapping Example"
+    description:
+      - type: Markdown
+        content: |
+          This example demonstrates how to map API response fields to specific locations in your application state using the simpleMapping processor.
+    toDescribe:
+      renderView:
+        - type: div
+          attributes:
+            class: "mb-4"
+          content:
+            - type: Markdown
+              content: "**Simulated API Response:**"
+            - type: TabbedSerializer
+              yamlSerializedContent: |
+                user:
+                  firstName: "John"
+                  lastName: "Doe"
+                  email: "john@example.com"
+                  preferences:
+                    theme: "dark"
+                    language: "en"
+                    notifications: true
+                  profile:
+                    avatar: "/images/john-avatar.png"
+                    bio: "Software developer passionate about React and data processing"
+                metadata:
+                  requestId: "req_12345"
+                  timestamp: "2024-01-15T10:30:00Z"
+                  version: "v1.2.3"
+                status: "success"
+
+        - type: BsButton
+          content: "Simulate API Call with Data Mapping"
+          attributes:
+            class: "btn btn-primary mb-3"
+          actions:
+            - what: fetchData
+              on: click
+              url: "/mockup-api/fetchData/data-mapping-example.json"
+              updateOnlyData: true
+              dataMapping:
+                simpleMapping:
+                  stringMap:
+                    "~~.profile.displayName":
+                      value: "user.firstName"
+                    "~~.profile.email":
+                      value: "user.email"
+                    "~~.settings.theme":
+                      value: "user.preferences.theme"
+                      required: false
+                      defaultValue: "light"
+                    "~~.settings.language":
+                      value: "user.preferences.language"
+                      required: false
+                      defaultValue: "en"
+                    "~~.profile.fullName":
+                      value: "user.fullName"
+                      required: false
+                      defaultValue: "Anonymous User"
+
+        - type: Markdown
+          content: |
+            **Current Application State (after mapping):**
+
+        - type: div
+          attributes:
+            class: "card mb-3"
+          content:
+            - type: div
+              attributes:
+                class: "card-header"
+              content: "Profile Data"
+            - type: div
+              attributes:
+                class: "card-body"
+              content:
+                - type: p
+                  content:
+                    - "Display Name: "
+                    - type: strong
+                      content: ~~.profile.displayName
+                - type: p
+                  content:
+                    - "Email: "
+                    - type: strong
+                      content: ~~.profile.email
+                - type: p
+                  content:
+                    - "Full Name: "
+                    - type: strong
+                      content: ~~.profile.fullName
+
+        - type: div
+          attributes:
+            class: "card"
+          content:
+            - type: div
+              attributes:
+                class: "card-header"
+              content: "Settings Data"
+            - type: div
+              attributes:
+                class: "card-body"
+              content:
+                - type: p
+                  content:
+                    - "Theme: "
+                    - type: span
+                      attributes:
+                        class: "badge bg-primary"
+                      content: ~~.settings.theme
+                - type: p
+                  content:
+                    - "Language: "
+                    - type: span
+                      attributes:
+                        class: "badge bg-secondary"
+                      content: ~~.settings.language
+
+      data:
+        profile: {}
+        settings: {}
+
+  - type: RjBuildDescriber
+    title: "Error Handling with onErrorMap"
+    description:
+      - type: Markdown
+        content: |
+          This example shows how to provide fallback values when required data fields are missing from the API response, demonstrating graceful error handling.
+    toDescribe:
+      renderView:
+        - type: div
+          attributes:
+            class: "mb-3"
+          content:
+            - type: Markdown
+              content: |
+                **API Response (missing user data):**
+                ```json
+                {
+                  "status": "ok",
+                  "timestamp": "2024-06-01T12:00:00Z"
+                }
+                ```
+                
+                The mapping below tries to extract `user.name` and `user.email` which don't exist in this response, triggering the `onErrorMap` fallback values.
+
+        - type: BsButton
+          content: "Test Missing Data Handling"
+          attributes:
+            class: "btn btn-warning mb-3"
+          actions:
+            - what: fetchData
+              on: click
+              url: "/mockup-api/fetchData/status.json"
+              updateOnlyData: true
+              dataMapping:
+                simpleMapping:
+                  stringMap:
+                    "~~.profile.name":
+                      value: "user.name"
+                      required: true
+                    "~~.profile.email":
+                      value: "user.email"
+                      required: true
+                    "~~.profile.department":
+                      value: "user.department"
+                      required: false
+                      defaultValue: "No department"
+                  onErrorMap:
+                    "~~.profile.status":
+                      value: "Error loading profile"
+                    "~~.profile.name":
+                      value: "Unknown User"
+                    "~~.profile.email":
+                      value: "unknown@example.com"
+                    "~~.profile.loadedAt":
+                      value: "~~.currentTimestamp"
+
+        - type: Markdown
+          content: |
+            **Profile State (after error handling):**
+
+        - type: div
+          attributes:
+            class: "card"
+          content:
+            - type: div
+              attributes:
+                class: "card-header"
+              content: "Profile Data"
+            - type: div
+              attributes:
+                class: "card-body"
+              content:
+                - type: p
+                  content:
+                    - "Status: "
+                    - type: span
+                      attributes:
+                        class: "badge bg-warning"
+                      content: ~~.profile.status
+                - type: p
+                  content:
+                    - "Name: "
+                    - type: strong
+                      content: ~~.profile.name
+                - type: p
+                  content:
+                    - "Email: "
+                    - type: strong
+                      content: ~~.profile.email
+                - type: p
+                  content:
+                    - "Loaded At: "
+                    - type: em
+                      content: ~~.profile.loadedAt
+
+      data:
+        profile: {}
+        currentTimestamp: "2024-01-15T10:30:00Z"
+
+  - type: Markdown
+    content: |
+      ## Advanced Configuration Examples
+
+      ### Complex Data Structure Mapping
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      dataMapping:
+        simpleMapping:
+          stringMap:
+            "~~.currentOrder.id":
+              value: "order.id"
+            "~~.currentOrder.customerName":
+              value: "order.customer.name"
+            "~~.currentOrder.customerEmail":
+              value: "order.customer.contact.email"
+            "~~.currentOrder.total":
+              value: "order.billing.total"
+            "~~.currentOrder.currency":
+              value: "order.billing.currency"
+              required: false
+              defaultValue: "USD"
+
+  - type: Markdown
+    content: |
+      ### Integration with additionalDataSources
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      additionalDataSource:
+        - src: "/api/user-profile"
+          blocking: true
+          dataMapping:
+            simpleMapping:
+              stringMap:
+                "~~.profile.displayName": { value: "user.name" }
+                "~~.profile.email": { value: "user.email" }
+                "~~.settings.theme": 
+                  value: "user.preferences.theme"
+                  required: false
+                  defaultValue: "light"
+
+  - type: Markdown
+    content: |
+      ### Integration with Template Context
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      dataMapping:
+        simpleMapping:
+          stringMap:
+            "~~.pagination.currentPage":
+              value: "meta.page"
+              required: false
+              defaultValue: "~~.pagination.page"  # Use current page as default
+
+  - type: Markdown
+    content: |
+      ## About the Data Mapping System
+
+      For information about the broader Data Mapping system and how to create custom mappers, see the **[Data Mapping Overview](../../advanced-concepts/data-mapping)**.
+
+templates:
+
+data:
+  profile: {}
+  settings: {}
+  currentTimestamp: "2024-01-15T10:30:00Z" 

package/public/rjbuild/docs/core/element/form/DateField.md

@@ -101,7 +101,7 @@ renderView:
         path: ~.message
         value: "✓ Meeting date is set!"
         when: ~.meetingDate
-        isEmpty: "not"
+        isNotEmpty:
       - what: setData
         on: click
         path: ~.message

package/public/rjbuild/docs/core/element/form/DateField.yaml

@@ -124,13 +124,13 @@ renderView:
               actions:
                 - what: hide
                   when: ~.startDate
-                  isEmpty: "not"
+                  isNotEmpty:
                 - what: hide
                   when: ~.endDate
-                  isEmpty: "not"
+                  isNotEmpty:
                 - what: hide
                   when: ~.reminderDate
-                  isEmpty: "not"
+                  isNotEmpty:
       data:
         startDate: null
         endDate: null
@@ -176,7 +176,7 @@ renderView:
               path: ~.message
               value: "✓ Meeting date is set!"
               when: ~.meetingDate
-              isEmpty: "not"
+              isNotEmpty:
             - what: setData
               on: click
               path: ~.message

package/public/rjbuild/docs/core/element/form/SelectField.yaml

@@ -275,7 +275,7 @@ renderView:
                   actions:
                     - what: hide
                       when: ~.category
-                      isEmpty: "not"
+                      isNotEmpty:
                 - type: span
                   content: "✗ not empty"
                   attributes:
@@ -311,7 +311,7 @@ renderView:
                   actions:
                     - what: hide
                       when: ~.description
-                      isEmpty: "not"
+                      isNotEmpty:
                 - ")"
       data:
         category: ""

package/public/rjbuild/docs/core/element/special/ReactiveJsonSubroot.md

@@ -18,9 +18,10 @@ With the `sharedUpdates` feature, the component can also propagate data changes
     - `data`: Initial data.
   - `debugMode`: Enable debug mode and related wrapper components.
 - `sharedUpdates` (boolean, optional): Enable upstream data propagation to parent (default: false).
-- `dataOverrideEvaluationDepth` (number, optional): Special evaluation depth for dataOverride property.
-- `actions` (array, optional): Action components to apply (passed to `ActionDependant` wrapper).
-- Other standard component properties (e.g., `attributes`) are passed to the `ActionDependant` wrapper.
+- `dataOverrideEvaluationDepth` (number, optional): Special evaluation depth for dataOverride property (default: 10).
+
+### Standard properties
+- `actions` (array, optional): Actions to attach to the subroot.
 
 ## Behavior
 - Renders a new `ReactiveJsonRoot` with the provided options.