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

package/public/rjbuild/docs/getting-started/rjbuild-structure.yaml

@@ -0,0 +1,421 @@
+renderView:
+  - type: Markdown
+    content: |
+      # RjBuild File Structure
+
+      ## What is an RjBuild?
+
+      An **RjBuild** is the standard file format used by Reactive-JSON to build interactive web applications. It is a JSON or YAML structure that completely describes a user interface, its data, and behavior, without requiring traditional JavaScript code.
+
+      > By extension, we also call "RjBuild" any fragment of this structure, particularly a portion of `renderView` and `templates` that can be reused or included in other RjBuilds.
+
+      ### Supported Formats
+
+      An RjBuild can be written in two formats:
+
+      - **YAML** (recommended): More readable and easier to write for humans, ideal for creation and maintenance
+      - **JSON**: Standard supported format, useful for programmatic generation or integration with existing tools
+
+      **YAML is preferable** for most use cases as it offers better readability, allows comments, and is more tolerant of minor syntax errors.
+
+      ## Basic Structure of an RjBuild
+
+      Any RjBuild file can contain up to four main sections:
+
+      - `renderView`: User interface structure (required)
+      - `templates`: Reusable components (optional)
+      - `data`: Initial state and data (optional)
+      - `additionalDataSource`: External data sources (optional)
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      renderView:           # User interface structure (required)
+        - type: div
+          content: "Hello World"
+      
+      templates:            # Reusable components (optional)
+        myComponent:
+          type: div
+          content: "Template content"
+      
+      data:                 # Initial state and data (optional)
+        message: "Welcome!"
+        user:
+          name: "John"
+      
+      additionalDataSource: # External data sources (optional)
+        - src: "/api/data.json"
+          path: ~~.dynamicData
+
+  - type: Markdown
+    content: |
+
+      ## Section `renderView` (Required)
+
+      The `renderView` section defines the **user interface** that will be displayed. It is the only required section of an RjBuild.
+
+      ### Role
+      - Determines the visual structure of the application
+      - Defines the components to display and their organization
+      - Specifies interactions and behaviors
+
+      ### Structure
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      renderView:
+        - type: ComponentName    # Type of component to render
+          content: "Content"     # Component content
+          attributes:            # HTML attributes (optional)
+            class: "css-class"
+          actions:               # Interactive actions (optional)
+            - what: hide
+              on: click
+
+  - type: Markdown
+    content: |
+
+      ### Examples
+
+      #### Simple interface
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      renderView:
+        - type: div
+          content: 
+            - type: h1
+              content: "My Application"
+            - type: p
+              content: "Welcome!"
+
+  - type: Markdown
+    content: |
+
+      #### With dynamic data
+      
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      renderView:
+        - type: div
+          content: ["Hello ", ~~.user.name, "!"]
+      
+      data:
+        user:
+          name: "Marie"
+
+  - type: Markdown
+    content: |
+
+      ## Section `data` (Optional)
+
+      The `data` section contains the **initial state** of the application. This data can be read and modified by components.
+
+      ### Role
+      - Provides the initial state of the application
+      - Stores data modifiable by user interactions
+      - Enables data sharing between components
+
+      ### Structure
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      data:
+        # Simple data
+        title: "My Site"
+        isLoggedIn: false
+        
+        # Objects
+        user:
+          name: "John"
+          email: "john@example.com"
+          
+        # Arrays
+        items:
+          - name: "Item 1"
+            active: true
+          - name: "Item 2" 
+            active: false
+
+  - type: Markdown
+    content: |
+      ### Data Access
+
+      To use data in a component, you can use the following syntax:
+
+      - **`~~.`**: Global access to data from anywhere in the RjBuild
+      - **`~.`**: Local access to data from the current context (template)
+
+      ### Usage Examples
+
+      #### Forms with state
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      renderView:
+        - type: TextField
+          label: "Name"
+          dataLocation: ~~.user.name
+        - type: div
+          content: ["Entered name: ", ~~.user.name]
+
+      data:
+        user:
+          name: "Initial value"
+
+  - type: Markdown
+    content: |
+
+      #### Conditional display
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      renderView:
+        - type: div
+          content: "User is logged in!"
+          actions:
+            - what: hide
+              when: ~~.isLoggedIn
+              is: false
+
+      data:
+        isLoggedIn: true
+
+  - type: Markdown
+    content: |
+      > You can get more information about data access in the [template system documentation](/docs/getting-started/template-contexts-data-binding).
+
+      ## Section `templates` (Optional)
+
+      The `templates` section defines **reusable components** that can be used in `renderView` or other templates.
+
+      ### Role
+      - Avoids code duplication
+      - Enables reuse of complex structures
+      - Facilitates maintenance and modifications
+
+      ### Structure
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      templates:
+        templateName:         # Template name
+          type: ComponentName # Template structure
+          content: "Content"
+          
+        multipleComponents:   # Template with multiple components
+          - type: div
+            content: "Component 1"
+          - type: p
+            content: "Component 2"
+
+  - type: Markdown
+    content: |
+
+      ### Using templates
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      renderView:
+        - load: templateName  # Loads and displays the template
+
+      templates:
+        templateName:
+          type: div
+          content: "I am a reusable template!"
+
+  - type: Markdown
+    content: |
+
+      ### Data Context
+      Templates create their own **data context** when used with components like `Switch`:
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      renderView:
+        - type: Switch
+          content: ~~.users        # Iterates over each user
+          singleOption:
+            load: userCard        # Each user uses the template
+
+      templates:
+        userCard:
+          type: div
+          content:
+            - "Name: "
+            - ~.name              # Local access to current user's name
+            - " (Admin: "
+            - ~~.isAdmin          # Global access to settings
+
+      data:
+        isAdmin: true
+        users:
+          - name: "Alice"
+          - name: "Bob"
+
+  - type: Markdown
+    content: |
+
+      ## Section `additionalDataSource` (Optional)
+
+      The `additionalDataSource` section allows **loading data from external sources** during application initialization.
+
+      ### Role
+      - Integrates dynamic data from APIs
+      - Enables asynchronous data loading
+      - Separates static data from dynamic data
+
+      ### Structure
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      additionalDataSource:
+        - src: "/api/endpoint"    # Source URL (required)
+          path: ~~.targetPath     # Where to place the data (optional)
+          method: GET             # HTTP method (optional, default: GET)
+          blocking: true          # Block rendering (optional, default: false)
+
+  - type: Markdown
+    content: |
+
+      ### Properties
+      - **`src`** (required): URL of the data source
+      - **`path`** (optional): Path where to place the data (template syntax)
+      - **`method`** (optional): HTTP method (GET, POST, etc.)
+      - **`dataMapping`** (optional): Configure selective data dispatch using mapping processors
+      - **`blocking`** (optional): If `true`, waits for loading before displaying
+
+      ### Loading Modes
+
+      #### Blocking loading
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      additionalDataSource:
+        - src: "/api/user-profile.json"
+          path: ~~.currentUser
+          blocking: true          # Page waits for loading
+
+  - type: Markdown
+    content: |
+
+      #### Non-blocking loading
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      additionalDataSource:
+        - src: "/api/notifications.json"
+          path: ~~.notifications
+          blocking: false         # Page displays immediately
+
+  - type: Markdown
+    content: |
+
+      ### Data Placement
+
+      #### With specific path
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      additionalDataSource:
+        - src: "/api/user.json"
+          path: ~~.currentUser
+          
+      # Data will be placed in data.currentUser
+
+  - type: Markdown
+    content: |
+
+      #### Root-level merge
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      additionalDataSource:
+        - src: "/api/config.json"
+          # No path = direct merge into data
+
+  - type: Markdown
+    content: |
+
+      ### Data Mapping Integration
+
+      Data Mapping can be used with `additionalDataSource` to selectively dispatch response data to specific locations:
+
+  - 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: |
+
+      **Note**: When `dataMapping` is configured, it takes priority over the `path` property. For more details, see [Data Mapping Documentation](../advanced-concepts/data-mapping).
+
+      ### Complete Example
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      renderView:
+        - type: div
+          content:
+            - type: h1
+              content: ["Hello ", ~~.currentUser.name]
+            - type: p
+              content: ["Version: ", ~~.systemConfig.version]
+
+      data:
+        currentUser:
+          name: "Loading..."    # Temporary value
+        systemConfig:
+          version: "Loading..."
+
+      additionalDataSource:
+        # Critical user data (blocking)
+        - src: "/api/user-profile.json"
+          path: ~~.currentUser
+          blocking: true
+          
+        # System configuration (non-blocking)
+        - src: "/api/system-config.json"
+          path: ~~.systemConfig
+          blocking: false
+
+  - type: Markdown
+    content: |
+
+      ## Best Practices
+
+      ### Organization
+      1. **Logical structure**: Organize your data by functional domain
+      2. **Reusable templates**: Create templates to avoid duplication
+      3. **Default values**: Provide temporary values for external data
+
+      ### Performance
+      1. **Smart loading**: Use `blocking: true` only for critical data
+      2. **Minimal data**: Load only necessary data
+      3. **Optimized templates**: Avoid overly complex templates
+
+      ### Maintainability
+      1. **Consistent naming**: Use clear conventions for templates and data.
+      2. **Documentation**: Comment complex sections.
+      3. **Validation**: Verify the structure of your external data.
+
+      ## Next Steps
+
+      Now that you understand the structure of RjBuilds, learn about the **[Template System](./template-contexts-data-binding)** to master data binding and create reusable components.
+
+      The template system is crucial for building maintainable and dynamic applications with Reactive-JSON.
+
+templates:
+
+data: 

package/public/rjbuild/docs/{template.md → getting-started/template-contexts-data-binding.md}

@@ -1,6 +1,4 @@
-# Template and Context System
-
-## Introduction
+# Template, Contexts, and Data Binding
 
 The template system in reactive-json efficiently manages data contexts and their access. Understanding how templates "containerize" data is essential for properly using components, actions, and reactions.
 
@@ -110,10 +108,10 @@ data:
       title: "User List"
       config:
         theme: "light"
-      level1:
-        items:
-          - name: "Item 1"
-          # userList template instances run here at: data.config.userSection.level1.items
+        level1:
+          items:
+            - name: "Item 1"
+            # userList template instances run here at: data.config.userSection.config.level1.items
 
 templates:
   userList:
@@ -130,7 +128,7 @@ templates:
 
 renderView:
   - type: Switch
-    content: ~~.config.userSection.level1.items
+    content: ~~.config.userSection.config.level1.items
     singleOption:
       load: userList
 ```
@@ -183,7 +181,13 @@ data:
 
 ## Best Practices
 
-1. **Context Coherence**: Ensure components that need to share data are in the same context
-2. **Global Access**: Use `~~.` for data that needs to be shared between different templates
-3. **Hierarchical Navigation**: Use `~>key` to find nearest occurrence or `~~>key` to find global setting
-4. **Local vs Global**: `~>` prioritizes local overrides, `~~>` prioritizes global settings 
+1. **Context Coherence**: Ensure components that need to share data are in the same context.
+2. **Global Access**: Use `~~.` for data that needs to be shared between different templates.
+3. **Hierarchical Navigation**: Use `~>key` to find nearest occurrence or `~~>key` to find global setting.
+4. **Local vs Global**: `~>` prioritizes local overrides, `~~>` prioritizes global settings.
+
+## Next Steps
+
+Now that you understand the template system and data binding, learn about **[Actions](./actions.md)** to make your interfaces interactive and responsive to data changes.
+
+Actions will allow you to hide, show, and manipulate elements based on the current application state. 

package/public/rjbuild/docs/{template.yaml → getting-started/template-contexts-data-binding.yaml}

@@ -1,14 +1,12 @@
 renderView:
   - type: Markdown
     content: |
-      # Template and Context System
-
-      ## Introduction
+      # Template, Contexts, and Data Binding
 
       The template system in reactive-json efficiently manages data contexts and their access. Understanding how templates "containerize" data is essential for properly using components, actions, and reactions.
 
-  - type: Markdown
-    content: |
+      ## Context Notations
+
       There are four main notations for accessing data:
       
       - `~.` : Local context (relative to current template)
@@ -19,7 +17,9 @@ renderView:
       Each notation is explained with examples below.
 
   - type: RjBuildDescriber
-    title: "Local Context (`~.`)"
+    title:
+      type: Markdown
+      content: "Local Context: `~.`"
     description:
       - type: Markdown
         content: |
@@ -34,7 +34,9 @@ renderView:
         username: "John"
 
   - type: RjBuildDescriber
-    title: "Global Context (`~~.`)"
+    title:
+      type: Markdown
+      content: "Global Context: `~~.`"
     description:
       - type: Markdown
         content: |
@@ -61,7 +63,9 @@ renderView:
         isAdmin: true
 
   - type: RjBuildDescriber
-    title: "Nearest Key (`~>key`)"
+    title:
+      type: Markdown
+      content: "Nearest Key: `~>key`"
     description:
       - type: Markdown
         content: |
@@ -89,7 +93,9 @@ renderView:
                 - name: "Item 1"  # themeDisplay template runs here
 
   - type: RjBuildDescriber
-    title: "Top-level Key (`~~>key`)"
+    title:
+      type: Markdown
+      content: "Top-level Key: `~~>key`"
     description:
       - type: Markdown
         content: |
@@ -193,10 +199,10 @@ renderView:
             title: "User List"
             config:
               theme: "light"
-            level1:
-              items:
-                - name: "Item 1"
-                # userList template instances run here at: data.config.userSection.level1.items
+              level1:
+                items:
+                  - name: "Item 1"
+                  # userList template instances run here at: data.config.userSection.config.level1.items
 
       templates:
         userList:
@@ -213,10 +219,18 @@ renderView:
 
       renderView:
         - type: Switch
-          content: ~~.config.userSection.level1.items
+          content: ~~.config.userSection.config.level1.items
           singleOption:
             load: userList
 
+  - type: Markdown
+    content: |
+      ## Next Steps
+
+      Now that you understand the template system and data binding, learn about **[Actions](./actions)** to make your interfaces interactive and responsive to data changes.
+
+      Actions will allow you to hide, show, and manipulate elements based on the current application state.
+
 templates:
 
 data: {}