@ea-lab/reactive-json-docs 0.7.0 → 1.0.0-alpha.0

package/public/rjbuild/docs/core/reaction/triggerEvent.yaml

@@ -7,15 +7,31 @@ renderView:
 
       ## Properties
 
-      - `what` (string, required): The name of the reaction, must be `triggerEvent`.
-      - `on` (string, required): The event that triggers this reaction.
-      - `eventName` (string, required): The name of the event to dispatch on the target element(s) (e.g., `click`, `focus`).
-      - `selector` (string, required): A CSS selector to identify the target element(s) that will receive the event.
-      - `selectorBase` (string, optional): Defines the starting point for the `selector` search.
-        - If omitted, the search starts from the `document` root.
-        - If set to `'currentEventTarget'`, the search starts from the element that triggered the reaction.
-        - If set to another CSS selector, the search starts from the closest ancestor matching that selector.
+  - type: DefinitionList
+    content:
+      - term:
+          code: eventName
+          after: "(string, required)"
+        details:
+          type: Markdown
+          content: "The name of the event to dispatch on the target element(s) (e.g., `click`, `focus`)"
+      - term:
+          code: selector
+          after: "(string, required)"
+        details: "A CSS selector to identify the target element(s) that will receive the event"
+      - term:
+          code: selectorBase
+          after: "(string, optional)"
+        details:
+          type: Markdown
+          content: |
+            Defines the starting point for the `selector` search.
+            - If omitted, the search starts from the `document` root.
+            - If set to `'currentEventTarget'`, the search starts from the element that triggered the reaction.
+            - If set to another CSS selector, the search starts from the closest ancestor matching that selector.
 
+  - type: Markdown
+    content: |
       ## Behavior
 
       - When triggered, the reaction searches for elements matching the `selector` within the scope defined by `selectorBase`.
@@ -32,9 +48,7 @@ renderView:
   - type: RjBuildDescriber
     title: "Triggering a click on another element"
     description: |
-      In this example, clicking the first button does not update the status directly. Instead, it dispatches a `click` event on the second button.
-      The second button has its own `click` reaction that updates the status.
-      Therefore, clicking either button will result in the same final action: the status text gets updated.
+      In this example, clicking the first button (`Trigger a click...`) does not update the status directly. Instead, it dispatches a `click` event on the second button (`Update the status`). The second button has its own `click` reaction that updates the status. Therefore, clicking either button will result in the same final action: the status text gets updated.
     toDescribe:
       renderView:
         - type: button

package/public/rjbuild/docs/docs-components/Mermaid.md

@@ -0,0 +1,254 @@
+# Mermaid
+
+**Package**: @ea-lab/reactive-json-docs
+
+The `Mermaid` component enables the creation of beautiful diagrams and flowcharts using Mermaid syntax. It supports automatic dark mode adaptation and provides seamless integration with the reactive-json system.
+
+## Properties
+
+- `content` (string, required): The Mermaid diagram definition (supports template evaluation)
+- `attributes` (object, optional): HTML attributes for the wrapper div
+- `mermaidConfig` (object, optional): Custom Mermaid configuration to override defaults
+
+## Theme Support
+
+The component automatically adapts to dark/light mode:
+- **Light Mode**: Uses default Mermaid light theme with custom color variables
+- **Dark Mode**: Uses Mermaid dark theme with enhanced contrast and visibility
+- **Automatic Switching**: Theme changes dynamically based on the current mode
+
+## Supported Diagram Types
+
+The component supports all Mermaid diagram types, including:
+
+- **Flowcharts**: Decision trees, process flows, system diagrams
+- **Sequence Diagrams**: Interaction flows, API calls, communication patterns
+- **Class Diagrams**: Object-oriented design, database schemas
+- **State Diagrams**: State machines, workflow states
+- **Entity Relationship Diagrams**: Database relationships
+- **User Journey**: User experience flows
+- **Gantt Charts**: Project timelines, task scheduling
+- **Pie Charts**: Data visualization
+- **Git Graphs**: Version control workflows
+
+## Examples
+
+### Basic Flowchart
+
+Simple flowchart demonstrating decision logic:
+
+```yaml
+renderView:
+  - type: Mermaid
+    content: |
+      flowchart TD
+          A[Start] --> B{Is it working?}
+          B -->|Yes| C[Great!]
+          B -->|No| D[Fix it]
+          D --> B
+          C --> E[End]
+
+data: {}
+```
+
+### Sequence Diagram
+
+User authentication flow with multiple actors:
+
+```yaml
+renderView:
+  - type: Mermaid
+    content: |
+      sequenceDiagram
+          participant U as User
+          participant F as Frontend
+          participant A as Auth Service
+          participant D as Database
+          
+          U->>F: Login Request
+          F->>A: Validate Credentials
+          A->>D: Check User
+          D-->>A: User Data
+          A-->>F: JWT Token
+          F-->>U: Login Success
+
+data: {}
+```
+
+### State Diagram
+
+Application state transitions:
+
+```yaml
+renderView:
+  - type: Mermaid
+    content: |
+      stateDiagram-v2
+          [*] --> Loading
+          Loading --> Success : Data Loaded
+          Loading --> Error : Failed
+          Success --> Loading : Refresh
+          Error --> Loading : Retry
+          Success --> [*] : Complete
+          Error --> [*] : Give Up
+
+data: {}
+```
+
+### Class Diagram
+
+Object-oriented design example:
+
+```yaml
+renderView:
+  - type: Mermaid
+    content: |
+      classDiagram
+          class ReactiveJson {
+              +render()
+              +updateData()
+              +evaluateTemplate()
+          }
+          
+          class Component {
+              +props
+              +render()
+          }
+          
+          class ActionDependant {
+              +handleActions()
+              +processEvents()
+          }
+          
+          ReactiveJson --> Component
+          Component --> ActionDependant
+
+data: {}
+```
+
+## Dynamic Content
+
+The component supports template evaluation for dynamic diagrams:
+
+```yaml
+renderView:
+  - type: Mermaid
+    content: ~.diagramDefinition
+
+data:
+  diagramDefinition: |
+    flowchart LR
+        A[Input Data] --> B[Process]
+        B --> C[Output]
+```
+
+## Advanced Examples
+
+### User Journey
+
+Complete user experience flow:
+
+```yaml
+renderView:
+  - type: Mermaid
+    content: |
+      journey
+          title User Registration Journey
+          section Discovery
+            Visit Website: 3: User
+            Browse Features: 4: User
+            Read Documentation: 3: User
+          section Registration
+            Click Sign Up: 5: User
+            Fill Form: 2: User
+            Verify Email: 1: User
+          section Onboarding
+            Complete Profile: 4: User
+            First Login: 5: User
+            Explore Dashboard: 5: User
+```
+
+### Entity Relationship Diagram
+
+Database schema representation:
+
+```yaml
+renderView:
+  - type: Mermaid
+    content: |
+      erDiagram
+          USERS {
+              int id PK
+              string email UK
+              string password
+              datetime created_at
+          }
+          
+          PROFILES {
+              int id PK
+              int user_id FK
+              string first_name
+              string last_name
+              text bio
+          }
+          
+          POSTS {
+              int id PK
+              int author_id FK
+              string title
+              text content
+              datetime published_at
+          }
+          
+          USERS ||--|| PROFILES : has
+          USERS ||--o{ POSTS : creates
+```
+
+## Custom Configuration
+
+You can customize Mermaid behavior using the `mermaidConfig` property:
+
+```yaml
+renderView:
+  - type: Mermaid
+    mermaidConfig:
+      themeVariables:
+        primaryColor: "#ff6b6b"
+        primaryBorderColor: "#ff6b6b"
+        lineColor: "#333333"
+      flowchart:
+        nodeSpacing: 100
+        rankSpacing: 150
+        curve: "linear"
+    content: |
+      flowchart TD
+          A[Custom Colors] --> B{Decision}
+          B -->|Yes| C[Success]
+          B -->|No| D[Retry]
+```
+
+The `mermaidConfig` is deeply merged with default configuration, allowing you to override specific properties while keeping others.
+
+## Error Handling
+
+The component provides graceful error handling:
+- Syntax errors are logged to console with detailed information
+- Invalid diagram content doesn't display anything (silent failure)
+- Error messages are in English for consistency
+- Original content and error details are included in console logs for debugging
+
+## Best Practices
+
+1. **Syntax Validation**: Test diagram syntax before deployment
+2. **Content Length**: Keep diagrams readable by limiting complexity
+3. **Template Evaluation**: Use template patterns for dynamic diagram generation
+4. **Responsive Design**: Consider diagram size on different screen sizes
+5. **Performance**: Cache static diagrams when possible
+6. **Accessibility**: Provide text alternatives for complex diagrams
+
+## Integration Tips
+
+- Combine with other reactive-json components for interactive documentation
+- Use with `Switch` component for tabbed diagram views
+- Integrate with data fetching for dynamic diagram generation
+- Leverage template system for personalized diagrams based on user data

package/public/rjbuild/docs/docs-components/Mermaid.yaml

@@ -0,0 +1,339 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Mermaid
+
+      **Package**: @ea-lab/reactive-json-docs
+
+      The `Mermaid` component enables the creation of beautiful diagrams and flowcharts using Mermaid syntax. It supports automatic dark mode adaptation and provides seamless integration with the reactive-json system.
+
+      ## Properties
+
+      - `content` (string, required): The Mermaid diagram definition (supports template evaluation)
+      - `attributes` (object, optional): HTML attributes for the wrapper div
+      - `mermaidConfig` (object, optional): Custom Mermaid configuration to override defaults
+
+      ## Theme Support
+
+      The component automatically adapts to dark/light mode:
+      - **Light Mode**: Uses default Mermaid light theme with custom color variables
+      - **Dark Mode**: Uses Mermaid dark theme with enhanced contrast and visibility
+      - **Automatic Switching**: Theme changes dynamically based on the current mode
+
+      ## Supported Diagram Types
+
+      The component supports all Mermaid diagram types, including:
+      - **Flowcharts**: Decision trees, process flows, system diagrams
+      - **Sequence Diagrams**: Interaction flows, API calls, communication patterns
+      - **Class Diagrams**: Object-oriented design, database schemas
+      - **State Diagrams**: State machines, workflow states
+      - **Entity Relationship Diagrams**: Database relationships
+      - **User Journey**: User experience flows
+      - **Gantt Charts**: Project timelines, task scheduling
+      - **Pie Charts**: Data visualization
+      - **Git Graphs**: Version control workflows
+
+  - type: RjBuildDescriber
+    title: "Basic Flowchart"
+    description:
+      - type: Markdown
+        content: |
+          Simple flowchart demonstrating decision logic with automatic theme adaptation.
+
+    toDescribe:
+      renderView:
+        - type: Mermaid
+          content: |
+            flowchart TD
+                A[Start] --> B{Is it working?}
+                B -->|Yes| C[Great!]
+                B -->|No| D[Fix it]
+                D --> B
+                C --> E[End]
+
+      data: {}
+
+  - type: RjBuildDescriber
+    title: "Sequence Diagram"
+    description:
+      - type: Markdown
+        content: |
+          User authentication flow with multiple actors demonstrating interaction patterns.
+
+    toDescribe:
+      renderView:
+        - type: Mermaid
+          content: |
+            sequenceDiagram
+                participant U as User
+                participant F as Frontend
+                participant A as Auth Service
+                participant D as Database
+                
+                U->>F: Login Request
+                F->>A: Validate Credentials
+                A->>D: Check User
+                D-->>A: User Data
+                A-->>F: JWT Token
+                F-->>U: Login Success
+
+      data: {}
+
+  - type: RjBuildDescriber
+    title: "State Diagram"
+    description:
+      - type: Markdown
+        content: |
+          Application state transitions showing different states and their relationships.
+
+    toDescribe:
+      renderView:
+        - type: Mermaid
+          content: |
+            stateDiagram-v2
+                [*] --> Loading
+                Loading --> Success : Data Loaded
+                Loading --> Error : Failed
+                Success --> Loading : Refresh
+                Error --> Loading : Retry
+                Success --> [*] : Complete
+                Error --> [*] : Give Up
+
+      data: {}
+
+  - type: RjBuildDescriber
+    title: "Class Diagram"
+    description:
+      - type: Markdown
+        content: |
+          Object-oriented design example showing reactive-json component relationships.
+
+    toDescribe:
+      renderView:
+        - type: Mermaid
+          content: |
+            classDiagram
+                class ReactiveJson {
+                    +render()
+                    +updateData()
+                    +evaluateTemplate()
+                }
+                
+                class Component {
+                    +props
+                    +render()
+                }
+                
+                class ActionDependant {
+                    +handleActions()
+                    +processEvents()
+                }
+                
+                ReactiveJson --> Component
+                Component --> ActionDependant
+
+      data: {}
+
+  - type: RjBuildDescriber
+    title: "Custom Configuration Example"
+    description:
+      - type: Markdown
+        content: |
+          Demonstration of custom Mermaid configuration using `mermaidConfig` property with custom colors and spacing.
+
+    toDescribe:
+      renderView:
+        - type: Mermaid
+          mermaidConfig:
+            themeVariables:
+              primaryColor: "#ff6b6b"
+              primaryBorderColor: "#ff6b6b"
+              lineColor: "#333333"
+              primaryTextColor: "#ffffff"
+            flowchart:
+              nodeSpacing: 80
+              rankSpacing: 120
+              curve: "linear"
+          content: |
+            flowchart TD
+                A[Custom Colors] --> B{Decision Node}
+                B -->|Yes Path| C[Success State]
+                B -->|No Path| D[Alternative]
+                D --> E[Retry Process]
+                E --> B
+                C --> F[Complete]
+
+      data: {}
+
+  - type: Markdown
+    content: |
+      ## Dynamic Content
+
+      The component supports template evaluation for dynamic diagrams:
+
+      ```yaml
+      renderView:
+        - type: Mermaid
+          content: ~.diagramDefinition
+
+      data:
+        diagramDefinition: |
+          flowchart LR
+              A[Input Data] --> B[Process]
+              B --> C[Output]
+      ```
+
+      ## Custom Configuration
+
+      You can customize Mermaid behavior using the `mermaidConfig` property:
+
+      ```yaml
+      renderView:
+        - type: Mermaid
+          mermaidConfig:
+            themeVariables:
+              primaryColor: "#ff6b6b"
+              primaryBorderColor: "#ff6b6b"
+              lineColor: "#333333"
+            flowchart:
+              nodeSpacing: 100
+              rankSpacing: 150
+              curve: "linear"
+          content: |
+            flowchart TD
+                A[Custom Colors] --> B{Decision}
+                B -->|Yes| C[Success]
+                B -->|No| D[Retry]
+      ```
+
+      The `mermaidConfig` is deeply merged with default configuration, allowing you to override specific properties while keeping others.
+
+      ### Default Configuration
+
+      The component provides sensible defaults that are automatically applied:
+
+      ```javascript
+      // Light mode defaults
+      {
+        startOnLoad: false,
+        theme: "default",
+        themeVariables: {
+          primaryColor: "#0066cc",
+          primaryTextColor: "#000000",
+          primaryBorderColor: "#0066cc",
+          lineColor: "#000000",
+          // ... more variables
+        },
+        flowchart: {
+          useMaxWidth: true,
+          htmlLabels: true,
+        },
+        sequence: {
+          useMaxWidth: true,
+        },
+        gantt: {
+          useMaxWidth: true,
+        }
+      }
+      ```
+
+      ### Configuration Merging
+
+      Your `mermaidConfig` is deeply merged with defaults:
+      - **Partial overrides**: Only specify properties you want to change
+      - **Theme variables**: Mix default and custom theme variables
+      - **Diagram-specific**: Override settings for specific diagram types
+      - **Dark mode**: Automatic adaptation while preserving your customizations
+
+      ## Advanced Examples
+
+      ### User Journey
+
+      Complete user experience flow:
+
+      ```yaml
+      renderView:
+        - type: Mermaid
+          content: |
+            journey
+                title User Registration Journey
+                section Discovery
+                  Visit Website: 3: User
+                  Browse Features: 4: User
+                  Read Documentation: 3: User
+                section Registration
+                  Click Sign Up: 5: User
+                  Fill Form: 2: User
+                  Verify Email: 1: User
+                section Onboarding
+                  Complete Profile: 4: User
+                  First Login: 5: User
+                  Explore Dashboard: 5: User
+      ```
+
+      ### Entity Relationship Diagram
+
+      Database schema representation:
+
+      ```yaml
+      renderView:
+        - type: Mermaid
+          content: |
+            erDiagram
+                USERS {
+                    int id PK
+                    string email UK
+                    string password
+                    datetime created_at
+                }
+                
+                PROFILES {
+                    int id PK
+                    int user_id FK
+                    string first_name
+                    string last_name
+                    text bio
+                }
+                
+                POSTS {
+                    int id PK
+                    int author_id FK
+                    string title
+                    text content
+                    datetime published_at
+                }
+                
+                USERS ||--|| PROFILES : has
+                USERS ||--o{ POSTS : creates
+      ```
+
+      ## Error Handling
+
+      The component provides graceful error handling:
+      - Syntax errors are logged to console with detailed information
+      - Invalid diagram content doesn't display anything (silent failure)
+      - Error messages are in English for consistency
+      - Original content and error details are included in console logs for debugging
+
+      ## Best Practices
+
+      1. **Syntax Validation**: Test diagram syntax before deployment
+      2. **Content Length**: Keep diagrams readable by limiting complexity
+      3. **Template Evaluation**: Use template patterns for dynamic diagram generation
+      4. **Responsive Design**: Consider diagram size on different screen sizes
+      5. **Performance**: Cache static diagrams when possible
+      6. **Accessibility**: Provide text alternatives for complex diagrams
+      7. **Configuration**: Use `mermaidConfig` sparingly - defaults are optimized
+      8. **Error Monitoring**: Check browser console for diagram rendering issues
+
+      ## Integration Tips
+
+      - Combine with other reactive-json components for interactive documentation
+      - Use with `Switch` component for tabbed diagram views
+      - Integrate with data fetching for dynamic diagram generation
+      - Leverage template system for personalized diagrams based on user data
+      - Override specific diagram types with custom `mermaidConfig` when needed
+
+templates:
+
+data: {}

package/public/rjbuild/docs/docs-components/index.yaml

@@ -26,6 +26,7 @@ renderView:
 
       ## Component List
 
+      - **[Mermaid](Mermaid)**: Create beautiful diagrams and flowcharts with automatic dark mode support
       - **[SyntaxHighlighter](SyntaxHighlighter)**: Advanced syntax highlighting with dark mode support
 
 templates:

package/public/rjbuild/docs/getting-started/actions.md

@@ -271,7 +271,7 @@ Actions support the following conditional operators when using the `when` proper
 3. **Synchronous evaluation**: All conditions and actions are evaluated synchronously.
 4. **Data scope**: Actions can only access data from the current template context and global context.
 5. **No side effects**: Actions cannot directly modify global state or trigger reactions.
-6. **External dependencies**: Some actions (tooltip, popover) require React Bootstrap components.
+6. **External dependencies**: Some actions may require specific plugin integrations (e.g., tooltips and popovers are available through the Bootstrap integration).
 
 ## Best Practices
 

package/public/rjbuild/docs/index.yaml

@@ -16,7 +16,7 @@ renderView:
       - **🎯 Declarative**: Define your UI structure and behavior in JSON/YAML
       - **⚡ Reactive**: Automatic state management and data binding
       - **🔧 Extensible**: Rich set of built-in components and actions
-      - **📱 Bootstrap Ready**: Seamlessly integrates with Bootstrap styling
+      - **🧩 Plugin System**: Modular architecture with specialized integrations
       - **🎨 Flexible**: Support for custom components and styling
       - **📊 Data-Driven**: Built-in data operations and API integration
 
@@ -52,6 +52,7 @@ renderView:
 
       ### Integrations
 
+      - **Bootstrap Integration** - Form fields, styled components, and UI elements
       - **Chart.js Integration** - Create interactive charts and visualizations
 
   - type: Markdown