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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ea-lab/reactive-json-docs",
-  "version": "0.7.0",
+  "version": "1.0.0-alpha.0",
   "description": "Complete documentation for Reactive-JSON - Components, examples and LLM-parsable guides",
   "main": "public/rjbuild/docs/index.yaml",
   "files": [
@@ -26,17 +26,17 @@
   "private": false,
   "devDependencies": {
     "@craco/craco": "^7.1.0",
-    "@ea-lab/reactive-json": "^0.5.0",
-    "@ea-lab/reactive-json-chartjs": "^0.0.23",
+    "@ea-lab/reactive-json": "^1.0.0-alpha.6",
+    "@ea-lab/reactive-json-chartjs": "^1.0.0",
     "@npmcli/fs": "^4.0.0",
     "@reduxjs/toolkit": "^2.6.1",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",
-    "bootstrap": "^5.3.5",
+    "bootstrap": "^5.3.7",
     "lodash": "^4.17.21",
     "react": "^19.1.0",
-    "react-bootstrap": "^2.10.2",
+    "react-bootstrap": "^2.10.10",
     "react-dom": "^19.1.0",
     "react-markdown": "^10.1.0",
     "react-redux": "^9.2.0",
@@ -77,6 +77,8 @@
     ]
   },
   "dependencies": {
+    "@ea-lab/reactive-json-bootstrap": "^0.0.2",
+    "mermaid": "^11.10.1",
     "remark-gfm": "^4.0.1"
   }
 }

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

@@ -164,7 +164,7 @@ const dateFormatProcessor = ({ requestContext, responseContext, dataToProcess, o
 };
 ```
 
-### 4. Conditional Processing
+### Conditional Processing
 
 ```javascript
 const userDataProcessor = ({ requestContext, responseContext, dataToProcess, originalDataToProcess }) => {
@@ -268,7 +268,7 @@ const safeProcessor = ({ requestContext, responseContext, dataToProcess, origina
 };
 ```
 
-### 4. Descriptive IDs and Ordering
+### Descriptive IDs and Ordering
 Use clear names and logical ordering:
 
 ```javascript

package/public/rjbuild/docs/advanced-concepts/plugins/component-development-guide-llm.md

@@ -28,7 +28,7 @@ data: # Data used by renderView and templates
 
 ## Component Architecture Patterns
 
-### 1. Basic Element Component Structure
+### Basic Element Component Structure
 
 ```jsx
 import {ActionDependant} from "@ea-lab/reactive-json/dist/engine";
@@ -56,7 +56,7 @@ export const ComponentName = ({props}) => {
 };
 ```
 
-### 2. Form Element Component Structure
+### Form Element Component Structure
 
 ```jsx
 import {useContext} from 'react';
@@ -93,7 +93,7 @@ export const FormComponentName = ({props, datafield, path}) => {
 };
 ```
 
-### 3. Component with View (Nested Content)
+### Component with View (Nested Content)
 
 ```jsx
 import {View} from "@ea-lab/reactive-json/dist/engine";
@@ -120,7 +120,7 @@ export const WrapperComponent = ({props, path, currentData, datafield}) => {
 };
 ```
 
-### 4. Generic Bootstrap Wrapper
+### Generic Bootstrap Wrapper
 
 ```jsx
 import {ActionDependant} from "@ea-lab/reactive-json/dist/engine";
@@ -151,7 +151,7 @@ export function BootstrapElement({props, currentData, path, bsComponent}) {
 }
 ```
 
-### 5. Action Component Structure
+### Action Component Structure
 
 ```jsx
 import {useContext, useEffect} from "react";
@@ -200,7 +200,7 @@ Other specialized contexts are available.
 
 ## Component Creation Rules
 
-### 1. Import Path Conventions
+### Import Path Conventions
 
 **Consumer application** (package imports - **RECOMMENDED**):
 ```jsx
@@ -219,7 +219,7 @@ import {GlobalDataContext} from "../../../engine/GlobalDataContext.jsx";
 
 > **Important Note**: The relative path syntax (`../../../engine/`) is reserved for developing internal components within the reactive-json package. For all other use cases, use package imports with `@ea-lab/reactive-json/dist/engine`.
 
-### 2. Component Signature Standards
+### Component Signature Standards
 ✅ **Correct**:
 ```jsx
 export const Component = ({props}) => {
@@ -234,17 +234,17 @@ export const Component = ({props, customValue}) => {
 }
 ```
 
-### 3. Error Handling
+### Error Handling
 - Components should fail silently when misconfigured
 - Return `null` for invalid configurations
 - Don't crash the application
 
-### 4. Feature Implementation Priority
+### Feature Implementation Priority
 1. **Essential features**: Core functionality
 2. **Requested features**: When explicitly asked
 3. **Optional features**: Keep minimal complexity
 
-### 5. Default Behavior
+### Default Behavior
 - Provide sensible defaults
 - Allow overriding via YAML/JSON configuration
 - Keep React components simple
@@ -289,23 +289,23 @@ export const CustomRoot = (props) => {
 
 ## Best Practices
 
-### 1. Code Organization
+### Code Organization
 - Order imports alphabetically by path
 - Order object properties alphabetically
 - Use JSX for reactive-json library components
 - Export components via `index.js`: `export * from "./ComponentName.jsx";`
 
-### 2. Dynamic Values
+### Dynamic Values
 - Use `evaluateTemplateValue()` for single values
 - Use `evaluateTemplateValueCollection()` for arrays/objects
 - Always evaluate user-provided content
 
-### 3. Attributes & Actions
+### Attributes & Actions
 - Include attribute support via `useEvaluatedAttributes()`
 - Wrap content with `<ActionDependant {...props}>`
 - Support actions unless explicitly told not to
 
-### 4. CSS & Styling
+### CSS & Styling
 - Use CSS modules for component-specific styles (`Component.module.css`)
 - For external libraries, mention CSS import requirements
 - Prefer minimal styling approach

package/public/rjbuild/docs/advanced-concepts/plugins/plugin-system.md

@@ -109,6 +109,51 @@ const App = () => {
 };
 ```
 
+### Component Override Behavior
+
+When using `mergeComponentCollections` with multiple plugins, **the last component with a given name takes precedence**. This allows you to override default components with custom implementations.
+
+```jsx
+import { ReactiveJsonRoot, mergeComponentCollections } from "@ea-lab/reactive-json";
+import { defaultComponents } from "@ea-lab/reactive-json";
+import { customComponents } from "./plugins/customComponents.js";
+
+const plugins = mergeComponentCollections([
+    defaultComponents,    // Contains a "Button" component
+    customComponents      // Also contains a "Button" component - this one will be used
+]);
+```
+
+This override mechanism is particularly useful for:
+
+- **Customizing default components**: Replace built-in components with your own implementations
+- **Theme customization**: Override components to match your design system
+- **Feature enhancement**: Add functionality to existing components
+- **Third-party integration**: Replace components with versions from external libraries
+
+**Example: Overriding a Default Button**
+
+```jsx
+// Default plugin has a basic Button
+const defaultPlugin = {
+    element: {
+        Button: BasicButton  // Simple button implementation
+    }
+};
+
+// Your custom plugin overrides it
+const customPlugin = {
+    element: {
+        Button: EnhancedButton  // Button with animations and custom styling
+    }
+};
+
+// EnhancedButton will be used everywhere "Button" is referenced
+const plugins = mergeComponentCollections([defaultPlugin, customPlugin]);
+```
+
+**⚠️ Important**: Component names must match exactly (case-sensitive) for the override to work. The order in the `mergeComponentCollections` array determines precedence.
+
 ### Custom ReactiveJsonRoot Wrapper
 
 Creating a custom wrapper allows you to **centralize plugin inclusion** across your entire application. Instead of manually importing and merging plugins in every component that uses Reactive-JSON, you define them once in a wrapper component.
@@ -172,4 +217,5 @@ export const ReportPage = () => {
 2. **Use descriptive names** for components and plugins
 3. **Document component props** and usage patterns
 4. **Provide examples** for complex components
-5. **Choose non-conflicting names** with existing components
+5. **Be intentional with component names** - use unique names unless you specifically want to override existing components
+6. **Document overrides** when replacing default components to help other developers understand the customization

package/public/rjbuild/docs/advanced-concepts/plugins/plugin-system.yaml

@@ -124,6 +124,57 @@ renderView:
 
   - type: Markdown
     content: |
+      ### Component Override Behavior
+
+      When using `mergeComponentCollections` with multiple plugins, **the last component with a given name takes precedence**. This allows you to override default components with custom implementations.
+
+  - type: SyntaxHighlighter
+    language: jsx
+    content: |
+      import { ReactiveJsonRoot, mergeComponentCollections } from "@ea-lab/reactive-json";
+      import { defaultComponents } from "@ea-lab/reactive-json";
+      import { customComponents } from "./plugins/customComponents.js";
+
+      const plugins = mergeComponentCollections([
+          defaultComponents,    // Contains a "Button" component
+          customComponents      // Also contains a "Button" component - this one will be used
+      ]);
+
+  - type: Markdown
+    content: |
+      This override mechanism is particularly useful for:
+
+      - **Customizing default components**: Replace built-in components with your own implementations
+      - **Theme customization**: Override components to match your design system
+      - **Feature enhancement**: Add functionality to existing components
+      - **Third-party integration**: Replace components with versions from external libraries
+
+      **Example: Overriding a Default Button**
+
+  - type: SyntaxHighlighter
+    language: jsx
+    content: |
+      // Default plugin has a basic Button
+      const defaultPlugin = {
+          element: {
+              Button: BasicButton  // Simple button implementation
+          }
+      };
+
+      // Your custom plugin overrides it
+      const customPlugin = {
+          element: {
+              Button: EnhancedButton  // Button with animations and custom styling
+          }
+      };
+
+      // EnhancedButton will be used everywhere "Button" is referenced
+      const plugins = mergeComponentCollections([defaultPlugin, customPlugin]);
+
+  - type: Markdown
+    content: |
+      **⚠️ Important**: Component names must match exactly (case-sensitive) for the override to work. The order in the `mergeComponentCollections` array determines precedence.
+
       ### Custom ReactiveJsonRoot Wrapper
 
       Creating a custom wrapper allows you to **centralize plugin inclusion** across your entire application. Instead of manually importing and merging plugins in every component that uses Reactive-JSON, you define them once in a wrapper component.
@@ -193,6 +244,7 @@ renderView:
       2. **Use descriptive names** for components and plugins
       3. **Document component props** and usage patterns
       4. **Provide examples** for complex components
-      5. **Choose non-conflicting names** with existing components
+      5. **Be intentional with component names** - use unique names unless you specifically want to override existing components
+      6. **Document overrides** when replacing default components to help other developers understand the customization
 
 templates:

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

@@ -1,6 +1,6 @@
 # HashChangeListener
 
-**Description**: Listens to hash changes (URL fragment) in the window and executes a reaction function in response. This is an internal action component that is automatically used when you specify `on: "hashchange"` in your actions.
+Listens to hash changes (URL fragment) in the window and executes a reaction function in response. This is an internal action component that is automatically used when you specify `on: "hashchange"` in your actions.
 
 ## Usage
 

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

@@ -3,7 +3,7 @@ renderView:
     content: |
       # HashChangeListener
 
-      **Description**: Listens to hash changes (URL fragment) in the window and executes a reaction function in response. This is an internal action component that is automatically used when you specify `on: "hashchange"` in your actions.
+      Listens to hash changes (URL fragment) in the window and executes a reaction function in response. This is an internal action component that is automatically used when you specify `on: "hashchange"` in your actions.
 
       ## Usage
 
@@ -11,12 +11,30 @@ renderView:
 
       ## Properties
 
-      When using `on: "hashchange"` in actions, you can specify:
+  - type: DefinitionList
+    content:
+      - term:
+          code: what
+          after: "(string, required)"
+        details:
+          type: Markdown
+          content: "name of the reaction function to execute (e.g., `setData`, `fetchData`, `submitData`)"
+      - term:
+          code: whenHashIs
+          after: "(string, optional)"
+        details:
+          type: Markdown
+          content: "hash value that should trigger the reaction (includes the `#` character)"
+      - term:
+          code: whenHashWas
+          after: "(string, optional)"
+        details:
+          type: Markdown
+          content: "previous hash value that should trigger the reaction (includes the `#` character)"
 
-      - `what` (required): name of the reaction function to execute (e.g., `setData`, `fetchData`, `submitData`, etc.)
-      - `whenHashIs` (optional): hash value that should trigger the reaction (includes the '#' character)
-      - `whenHashWas` (optional): previous hash value that should trigger the reaction (includes the '#' character)
-      - All other properties are passed as arguments to the reaction function
+  - type: Markdown
+    content: |
+      All other properties are passed as arguments to the reaction function.
 
   - type: RjBuildDescriber
     title: "HashChangeListener Example"

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

@@ -1,9 +1,9 @@
 # Hide
 
-**Description**: Completely hides the element and cancels any subsequent actions.
+Completely hides the element and cancels any subsequent actions.
 
 ## Properties
-- None
+None.
 
 ## Behavior
 - The element and its children are not rendered in the DOM.

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

@@ -3,10 +3,11 @@ renderView:
     content: |
       # Hide
 
-      **Description**: Completely hides the element and cancels any subsequent actions.
+      Completely hides the element and cancels any subsequent actions.
 
       ## Properties
-      - None
+
+      None.
 
       ## Behavior
       - The element and its children are not rendered in the DOM.
@@ -18,7 +19,7 @@ renderView:
       - type: Markdown
         content: |
           This example shows how the `hide` action completely removes an element from the DOM based on a condition.
-          
+
           Try toggling the visibility to see how the `hide` action works differently from just making something invisible.
 
     toDescribe:

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

@@ -1,6 +1,6 @@
 # MessageListener
 
-**Description**: Executes a reaction when receiving a message via `window.postMessage`. This is an internal action component that is automatically used when you specify `on: "message"` in your actions.
+Executes a reaction when receiving a message via `window.postMessage`. This is an internal action component that is automatically used when you specify `on: "message"` in your actions.
 
 ## Usage
 
@@ -10,9 +10,9 @@ MessageListener is **not** used directly as an element type. Instead, it is auto
 
 When using `on: "message"` in actions, you can specify:
 
-- `what` (required): name of the reaction function to execute (e.g., `setData`, `fetchData`, `submitData`, etc.)
-- `whenMessageIs` (optional): message value to react to (deep comparison with the received message data)
-- All other properties are passed as arguments to the reaction function
+- `what` (required): Name of the reaction function to execute (e.g., `setData`, `fetchData`, `submitData`, etc.).
+- `whenMessageIs` (optional): Message value to react to (deep comparison with the received message data)
+- All other properties are passed as arguments to the reaction function.
 
 ## Behavior
 

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

@@ -3,7 +3,7 @@ renderView:
     content: |
       # MessageListener
 
-      **Description**: Executes a reaction when receiving a message via `window.postMessage`. This is an internal action component that is automatically used when you specify `on: "message"` in your actions.
+      Executes a reaction when receiving a message via `window.postMessage`. This is an internal action component that is automatically used when you specify `on: "message"` in your actions.
 
       ## Usage
 
@@ -11,11 +11,23 @@ renderView:
 
       ## Properties
 
-      When using `on: "message"` in actions, you can specify:
-
-      - `what` (required): name of the reaction function to execute (e.g., `setData`, `fetchData`, `submitData`, etc.)
-      - `whenMessageIs` (optional): message value to react to (deep comparison with the received message data)
-      - All other properties are passed as arguments to the reaction function
+  - type: DefinitionList
+    content:
+      - term:
+          code: what
+          after: "(string, required)"
+        details:
+          type: Markdown
+          content: "Name of the reaction function to execute (e.g., `setData`, `fetchData`, `submitData`)."
+      - term:
+          code: whenMessageIs
+          after: "(any, optional)"
+        details:
+          type: Markdown
+          content: "Message value to react to. Uses deep comparison with the received message data."
+      - type: Markdown
+        content: |
+          All other properties are passed as arguments to the reaction function.
 
   - type: RjBuildDescriber
     title: "MessageListener Example"

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

@@ -8,10 +8,10 @@ ReactOnEvent is an internal action component that is automatically instantiated
 
 When you define actions with event handlers (like `on: "click"`), the Actions system automatically:
 
-1. Collects all reactions with event handlers for the element
-2. Groups them by event type (click, change, mouseover, etc.)
-3. Creates a ReactOnEvent component that attaches the appropriate event listeners
-4. Wraps the target element with these event handlers
+1. Collects all reactions with event handlers for the element.
+2. Groups them by event type (click, change, mouseover, etc.).
+3. Creates a ReactOnEvent component that attaches the appropriate event listeners.
+4. Wraps the target element with these event handlers.
 
 ## Usage Pattern
 

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

@@ -11,10 +11,10 @@ renderView:
 
       When you define actions with event handlers (like `on: "click"`), the Actions system automatically:
 
-      1. Collects all reactions with event handlers for the element
-      2. Groups them by event type (click, change, mouseover, etc.)
-      3. Creates a ReactOnEvent component that attaches the appropriate event listeners
-      4. Wraps the target element with these event handlers
+      1. Collects all reactions with event handlers for the element.
+      2. Groups them by event type (click, change, mouseover, etc.).
+      3. Creates a ReactOnEvent component that attaches the appropriate event listeners.
+      4. Wraps the target element with these event handlers.
 
       ## Usage Pattern
 

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

@@ -1,9 +1,9 @@
 # Redirect
 
-**Description**: Redirects the user to a given URL if the condition is met.
+
 
 ## Properties
-- `to`: destination URL
+- `to`: Destination URL.
 
 ## Example
 

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

@@ -3,10 +3,16 @@ renderView:
     content: |
       # Redirect
 
-      **Description**: Redirects the user to a given URL if the condition is met.
+      Redirects the user to a given URL if the condition is met.
 
       ## Properties
-      - `to`: destination URL
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: to
+          after: "(string, required)"
+        details: "Destination URL."
 
   - type: Markdown
     content: |

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

@@ -1,9 +1,9 @@
 # VisuallyHide
 
-**Description**: Visually hides the element but keeps it in the DOM (useful for accessibility or to keep the element reactive to events).
+Visually hides the element but keeps it in the DOM (useful for accessibility or to keep the element reactive to events).
 
 ## Properties
-- None
+None.
 
 ## Behavior
 - The element is rendered in the DOM but with `display: none`.

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

@@ -3,10 +3,10 @@ renderView:
     content: |
       # VisuallyHide
 
-      **Description**: Visually hides the element but keeps it in the DOM (useful for accessibility or to keep the element reactive to events).
+      Visually hides the element but keeps it in the DOM (useful for accessibility or to keep the element reactive to events).
 
       ## Properties
-      - None
+      None.
 
       ## Behavior
       - The element is rendered in the DOM but with `display: none`.

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

@@ -6,14 +6,14 @@ SimpleMapping is the core data mapping processor in Reactive-JSON that enables s
 
 ### 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`)
+- `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`)
+- `value` (string, required): Can be either static values (e.g., `Error occurred`) or template references (e.g., `~~.errorTimestamp`).
 
 ## Configuration Structure