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

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/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.

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

@@ -8,13 +8,121 @@ renderView:
       With the `sharedUpdates` feature, the component can also propagate data changes back to the parent, enabling seamless communication between parent and subroot when working with shared data references.
 
       ## Properties
-      - `rjOptions` (object, required): Options to pass to the subroot - accepts **all** `ReactiveJsonRoot` properties.
-        - Direct properties: `rjBuildUrl`, `dataOverride`, `headersForRjBuild`, `debugMode`, etc.
-        - For inline content: use `maybeRawAppRjBuild` containing `renderView`, `templates`, `data`.
-      - `sharedUpdates` (boolean, optional): Enable upstream data propagation to parent (default: false).
-      - `dataOverrideEvaluationDepth` (number, optional): Special evaluation depth for dataOverride property.
-      - Other properties are passed to the underlying `ActionDependant` wrapper.
 
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      # Complete rjOptions structure.
+      - type: ReactiveJsonSubroot
+        # Component-specific properties.
+        sharedUpdates: true
+        dataOverrideEvaluationDepth: 10
+        
+        # Subroot configuration.
+        rjOptions:
+          # Loading from URL.
+          rjBuildUrl: "/path/to/rjbuild.yaml"
+          rjBuildFetchMethod: "GET"  # or "POST".
+          headersForRjBuild:
+            Authorization: "Bearer token"
+            Content-Type: "application/json"
+          
+          # OR inline definition.
+          maybeRawAppRjBuild:
+            renderView:
+              - type: div
+                content: "Subroot content."
+            templates:
+              myTemplate:
+                type: span
+                content: ~.value
+            data:
+              initialValue: "Hello World"
+          
+          # Data replacement.
+          dataOverride: ~~.userData
+          
+          # Debug mode.
+          debugMode: true
+        
+        # Standard actions.
+        actions:
+          - what: hide
+            when: ~.condition
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: rjOptions
+          after: " (object, required)"
+        details:
+          - type: Markdown
+            content: "Options to pass to the subroot - accepts **all** `ReactiveJsonRoot` properties including:"
+          
+          - type: DefinitionList
+            content:
+              - term:
+                  code: rjOptions.rjBuildUrl
+                details: "URL to load the RjBuild from."
+              
+              - term:
+                  code: rjOptions.rjBuildFetchMethod
+                details: "HTTP method (\"GET\" or \"POST\")."
+              
+              - term:
+                  code: rjOptions.headersForRjBuild
+                details: "Headers for the request."
+              
+              - term:
+                  code: rjOptions.dataOverride
+                details: "Override data for the loaded/defined RjBuild."
+              
+              - term:
+                  code: rjOptions.maybeRawAppRjBuild
+                details:
+                  - type: Markdown
+                    content: "Inline RjBuild content (string or object) containing:"
+                  
+                  - type: DefinitionList
+                    content:
+                      - term:
+                          code: rjOptions.maybeRawAppRjBuild.renderView
+                        details: "View definition."
+                      
+                      - term:
+                          code: rjOptions.maybeRawAppRjBuild.templates
+                        details: "Template definitions."
+                      
+                      - term:
+                          code: rjOptions.maybeRawAppRjBuild.data
+                        details: "Initial data."
+              
+              - term:
+                  code: rjOptions.debugMode
+                details: "Enable debug mode and related wrapper components."
+      
+      - term:
+          code: sharedUpdates
+          after: " (boolean, optional)"
+        details: "Enable upstream data propagation to parent (default: false)."
+      
+      - term:
+          code: dataOverrideEvaluationDepth
+          after: " (number, optional)"
+        details: "Special evaluation depth for dataOverride property (default: 10)."
+
+  - type: Markdown
+    content: |
+      ### Standard properties
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: actions
+          after: " (array, optional)"
+        details: "Actions to attach to the subroot."
+
+  - type: Markdown
+    content: |
       ## Behavior
       - Renders a new `ReactiveJsonRoot` with the provided options.
       - The subroot is typically isolated from the parent for data, templates, and rendering¹.

package/public/rjbuild/docs/{getting-started.md → getting-started/index.md}

@@ -53,7 +53,7 @@ data:
   isAdmin: true
 ```
 
-> 💡 **Advanced navigation:** For complex hierarchical data access, see the [Template System documentation](/docs/template) which covers `~>key` and `~~>key` notations.
+> 💡 **Advanced navigation:** For complex hierarchical data access, see the [Template System documentation](/docs/getting-started/template) which covers `~>key` and `~~>key` notations.
 
 ### Basic Elements
 
@@ -156,4 +156,4 @@ data:
 2. Check out the [elements documentation](/docs/core/element) to discover all available components
 3. Learn how to use the [action system](/docs/core/action) to create interactive interfaces
 4. Discover the [reaction system](/docs/core/reaction) to handle user interactions
-5. If needed, learn how to [extend Reactive-JSON](/docs/extend) with your own components 
+5. If needed, learn how to [extend Reactive-JSON](/docs/advanced-concepts/plugins) with your own components 

package/public/rjbuild/docs/{getting-started.yaml → getting-started/index.yaml}

@@ -3,6 +3,8 @@ renderView:
     content: |
       # Reactive-JSON Getting Started Guide
 
+      > Dev note: This page needs to be rewritten.
+
       ## Introduction
 
       Reactive-JSON is a powerful library that allows you to create interactive user interfaces using only JSON/YAML configurations. No need to write complex JavaScript code - simply define your interface and its behavior declaratively.
@@ -39,7 +41,7 @@ renderView:
       - `~.` : Local context (relative to current template)
       - `~~.` : Global context (access to global data)
 
-      > 💡 **Advanced navigation:** For complex hierarchical data access, see the [Template System documentation](/docs/template) which covers `~>key` and `~~>key` notations.
+      > 💡 **Advanced navigation:** For complex hierarchical data access, see the [Template System documentation](/docs/getting-started/template) which covers `~>key` and `~~>key` notations.
 
   - type: RjBuildDescriber
     title: "Template System Example"
@@ -221,4 +223,4 @@ renderView:
       2. Check out the [elements documentation](/docs/core/element) to discover all available components
       3. Learn how to use the [action system](/docs/core/action) to create interactive interfaces
       4. Discover the [reaction system](/docs/core/reaction) to handle user interactions
-      5. If needed, learn how to [extend Reactive-JSON](/docs/extend) with your own components 
+      5. If needed, learn how to [extend Reactive-JSON](/docs/advanced-concepts/plugins) with your own components