@ea-lab/reactive-json-docs 0.1.6 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ea-lab/reactive-json-docs",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Complete documentation for Reactive-JSON - Components, examples and LLM-parsable guides",
   "main": "public/rjbuild/docs/index.yaml",
   "files": [

package/public/rjbuild/docs/extend/component-development.md

@@ -190,4 +190,17 @@ export const MyAction = (props) => {
 ### Integration Requirements
 - Components must accept props in the standard format
 - Form components should implement proper data binding
-- Action components should not interfere with normal rendering 
+- Action components should not interfere with normal rendering
+
+## Making Your Components Available
+
+Now that you've learned how to create custom React components that integrate seamlessly with Reactive-JSON, the next step is understanding how to make them available in your applications.
+
+Your custom components need to be registered through the plugin system. For complete guidance on plugin registration, organization, and advanced management patterns, continue to the dedicated [Plugin System Guide](plugin-system).
+
+This guide will show you how to:
+- Register your components using the plugin system
+- Organize and structure your plugins effectively
+- Combine multiple plugin sources seamlessly
+- Create reusable plugin collections
+- Handle complex plugin dependencies and distribution patterns

package/public/rjbuild/docs/extend/component-development.yaml

@@ -210,6 +210,19 @@ renderView:
       - Form components should implement proper data binding
       - Action components should not interfere with normal rendering
 
+      ## Making Your Components Available
+
+      Now that you've learned how to create custom React components that integrate seamlessly with Reactive-JSON, the next step is understanding how to make them available in your applications.
+
+      Your custom components need to be registered through the plugin system. For complete guidance on plugin registration, organization, and advanced management patterns, continue to the dedicated [Plugin System Guide](plugin-system).
+
+      This guide will show you how to:
+      - Register your components using the plugin system
+      - Organize and structure your plugins effectively
+      - Combine multiple plugin sources seamlessly
+      - Create reusable plugin collections
+      - Handle complex plugin dependencies and distribution patterns
+
 templates:
 
 data: {} 

package/public/rjbuild/docs/extend/plugin-system.md

@@ -39,25 +39,23 @@ export const myPlugin = {
 Then, register the plugin with the ReactiveJsonRoot component:
 
 ```jsx
-import { ReactiveJsonRoot } from "@ea-lab/reactive-json";
+import { ReactiveJsonRoot, mergeComponentCollections } from "@ea-lab/reactive-json";
 import { myPlugin } from "./plugins/myPlugin.js";
 
 const App = () => {
     return (
         <ReactiveJsonRoot
-            plugins={[myPlugin]}
+            plugins={mergeComponentCollections([myPlugin])}
         />
     );
 };
 ```
 
-The plugin is now available throughout the application.
-
 You can now use the components in your RjBuild configuration:
 
 ```jsx
 import React from 'react';
-import { ReactiveJsonRoot } from "@ea-lab/reactive-json";
+import { ReactiveJsonRoot, mergeComponentCollections } from "@ea-lab/reactive-json";
 import { myPlugin } from "./plugins/myPlugin.js";
 
 const App = () => {
@@ -75,7 +73,7 @@ const App = () => {
     return (
         <ReactiveJsonRoot
             rjBuild={rjBuildConfig}
-            plugins={[myPlugin]}
+            plugins={mergeComponentCollections([myPlugin])}
         />
     );
 };
@@ -83,60 +81,93 @@ const App = () => {
 
 The plugin is now available throughout the application.
 
-## Multi-Plugin Application
+## Multi-Plugin Application & Plugin Merging
 
-Applications can use multiple plugins, allowing for modular component organization.
+When your application needs multiple plugins from different sources, you can combine them using `mergeComponentCollections`.
+
+### Multiple Plugin Usage
 
 ```jsx
-import { uiPlugin } from "./plugins/uiPlugin.js";
-import { formPlugin } from "./plugins/formPlugin.js";
-import { chartsPlugin } from "./plugins/chartsPlugin.js";
+import { ReactiveJsonRoot, mergeComponentCollections } from "@ea-lab/reactive-json";
+import { chartjsComponents } from "@ea-lab/reactive-json-chartjs";
+import { customPlugins } from "./plugins/customPlugins.js";
+import { thirdPartyPlugin } from "third-party-reactive-json-plugin";
 
 const App = () => {
     return (
         <ReactiveJsonRoot
             rjBuild={rjBuildConfig}
-            plugins={[
-                uiPlugin,
-                formPlugin,
-                chartsPlugin
-            ]}
+            plugins={mergeComponentCollections([
+                chartjsComponents,
+                customPlugins,
+                thirdPartyPlugin
+            ])}
         />
     );
 };
 ```
 
-## Plugin Development Patterns
+### Custom ReactiveJsonRoot Wrapper
 
-### Standalone Plugin
+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.
 
-For single-purpose plugins with a few related components:
+#### Benefits of Centralized Plugin Management
 
-```javascript
-export const simplePlugin = {
-    element: {
-        Alert: AlertComponent,
-        Badge: BadgeComponent,
-    }
+- **Consistency**: Ensures all parts of your application have access to the same set of components
+- **Maintainability**: Update plugin dependencies in one place
+- **Simplicity**: Other components only need to import your wrapper, not individual plugins
+- **Standardization**: Enforces a consistent plugin configuration across teams
+
+#### Implementation Example
+
+```jsx
+import { ReactiveJsonRoot, mergeComponentCollections } from "@ea-lab/reactive-json";
+import { chartjsComponents } from "@ea-lab/reactive-json-chartjs";
+import { customPlugins } from "./plugins/customPlugins.js";
+import { companyUIComponents } from "@company/reactive-json-ui";
+
+export const CustomReactiveJsonRoot = (props) => {
+    const additionalProps = {};
+
+    // Centralize all plugin dependencies for the entire application
+    additionalProps.plugins = mergeComponentCollections([
+        chartjsComponents,        // Third-party charting components
+        customPlugins,            // Application-specific components  
+        companyUIComponents       // Company-wide design system
+    ]);
+
+    const finalProps = { ...props, ...additionalProps };
+
+    return <ReactiveJsonRoot {...finalProps} />;
+};
+```
+
+#### Usage Across Your Application
+
+Once created, your wrapper simplifies usage throughout your application:
+
+```jsx
+import { CustomReactiveJsonRoot } from "./components/CustomReactiveJsonRoot";
+
+// Component A
+export const Dashboard = () => {
+    return (
+        <CustomReactiveJsonRoot rjBuild={dashboardConfig} />
+    );
+};
+
+// Component B  
+export const ReportPage = () => {
+    return (
+        <CustomReactiveJsonRoot rjBuild={reportConfig} />
+    );
 };
 ```
 
 ## Best Practices
 
-### Plugin Organization
 1. **Group related components** in the same plugin
 2. **Use descriptive names** for components and plugins
 3. **Document component props** and usage patterns
 4. **Provide examples** for complex components
-
-### Distribution
-1. **Package as npm modules** for easy distribution
-2. **Include TypeScript definitions** if using TypeScript
-3. **Provide clear documentation** and examples
-4. **Follow semantic versioning** for releases
-
-### Performance
-1. **Lazy load large plugins** when possible
-2. **Avoid global state** in plugin components
-3. **Use React best practices** for component implementation
-4. **Test plugin compatibility** with different Reactive-JSON versions 
+5. **Choose non-conflicting names** with existing components

package/public/rjbuild/docs/extend/plugin-system.yaml

@@ -22,7 +22,9 @@ renderView:
 
       First, regroup your components in a plugin object.
 
-      ```jsx
+  - type: SyntaxHighlighter
+    language: jsx
+    content: |
       // myPlugin.js
       import { MyButton } from "./components/MyButton.jsx";
       import { MyForm } from "./components/MyForm.jsx";
@@ -37,111 +39,158 @@ renderView:
               MyAction,
           }
       };
-      ```
 
+  - type: Markdown
+    content: |
       Then, register the plugin with the ReactiveJsonRoot component:
 
-      ```jsx
-      import { ReactiveJsonRoot } from "@ea-lab/reactive-json";
+  - type: SyntaxHighlighter
+    language: jsx
+    content: |
+      import { ReactiveJsonRoot, mergeComponentCollections } from "@ea-lab/reactive-json";
       import { myPlugin } from "./plugins/myPlugin.js";
 
       const App = () => {
           return (
               <ReactiveJsonRoot
-                  plugins={[myPlugin]}
+                  plugins={mergeComponentCollections([myPlugin])}
               />
           );
       };
-      ```
-
-      The plugin is now available throughout the application.
 
+  - type: Markdown
+    content: |
       You can now use the components in your RjBuild configuration:
 
-      ```jsx
-        import React from 'react';
-        import { ReactiveJsonRoot } from "@ea-lab/reactive-json";
-        import { myPlugin } from "./plugins/myPlugin.js";
-
-        const App = () => {
-            const rjBuildConfig = {
-                renderView: [
-                    {
-                        type: "MyButton",
-                        content: "Click me!",
-                        customProperty: "some value"
-                    }
-                ],
-                data: {}
-            };
-
-            return (
-                <ReactiveJsonRoot
-                    rjBuild={rjBuildConfig}
-                    plugins={[myPlugin]}
-                />
-            );
-        };
-        ```
+  - type: SyntaxHighlighter
+    language: jsx
+    content: |
+      import React from 'react';
+      import { ReactiveJsonRoot, mergeComponentCollections } from "@ea-lab/reactive-json";
+      import { myPlugin } from "./plugins/myPlugin.js";
+
+      const App = () => {
+          const rjBuildConfig = {
+              renderView: [
+                  {
+                      type: "MyButton",
+                      content: "Click me!",
+                      customProperty: "some value"
+                  }
+              ],
+              data: {}
+          };
+
+          return (
+              <ReactiveJsonRoot
+                  rjBuild={rjBuildConfig}
+                  plugins={mergeComponentCollections([myPlugin])}
+              />
+          );
+      };
 
+  - type: Markdown
+    content: |
       The plugin is now available throughout the application.
 
-      ## Multi-Plugin Application
-      
-      Applications can use multiple plugins, allowing for modular component organization.
+      ## Multi-Plugin Application & Plugin Merging
+
+      When your application needs multiple plugins from different sources, you can combine them using `mergeComponentCollections`.
+
+      ### Multiple Plugin Usage
 
-      ```jsx
-      import { uiPlugin } from "./plugins/uiPlugin.js";
-      import { formPlugin } from "./plugins/formPlugin.js";
-      import { chartsPlugin } from "./plugins/chartsPlugin.js";
+  - type: SyntaxHighlighter
+    language: jsx
+    content: |
+      import { ReactiveJsonRoot, mergeComponentCollections } from "@ea-lab/reactive-json";
+      import { chartjsComponents } from "@ea-lab/reactive-json-chartjs";
+      import { customPlugins } from "./plugins/customPlugins.js";
+      import { thirdPartyPlugin } from "third-party-reactive-json-plugin";
 
       const App = () => {
           return (
               <ReactiveJsonRoot
                   rjBuild={rjBuildConfig}
-                  plugins={[
-                      uiPlugin,
-                      formPlugin,
-                      chartsPlugin
-                  ]}
+                  plugins={mergeComponentCollections([
+                      chartjsComponents,
+                      customPlugins,
+                      thirdPartyPlugin
+                  ])}
               />
           );
       };
-      ```
 
-      ## Plugin Development Patterns
+  - type: Markdown
+    content: |
+      ### 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.
+
+      #### Benefits of Centralized Plugin Management
+
+      - **Consistency**: Ensures all parts of your application have access to the same set of components
+      - **Maintainability**: Update plugin dependencies in one place
+      - **Simplicity**: Other components only need to import your wrapper, not individual plugins
+      - **Standardization**: Enforces a consistent plugin configuration across teams
+
+      #### Implementation Example
+
+  - type: SyntaxHighlighter
+    language: jsx
+    content: |
+      import { ReactiveJsonRoot, mergeComponentCollections } from "@ea-lab/reactive-json";
+      import { chartjsComponents } from "@ea-lab/reactive-json-chartjs";
+      import { customPlugins } from "./plugins/customPlugins.js";
+      import { companyUIComponents } from "@company/reactive-json-ui";
+
+      export const CustomReactiveJsonRoot = (props) => {
+          const additionalProps = {};
+
+          // Centralize all plugin dependencies for the entire application
+          additionalProps.plugins = mergeComponentCollections([
+              chartjsComponents,        // Third-party charting components
+              customPlugins,            // Application-specific components  
+              companyUIComponents       // Company-wide design system
+          ]);
+
+          const finalProps = { ...props, ...additionalProps };
+
+          return <ReactiveJsonRoot {...finalProps} />;
+      };
+
+  - type: Markdown
+    content: |
+      #### Usage Across Your Application
+
+      Once created, your wrapper simplifies usage throughout your application:
 
-      ### Standalone Plugin
+  - type: SyntaxHighlighter
+    language: jsx
+    content: |
+      import { CustomReactiveJsonRoot } from "./components/CustomReactiveJsonRoot";
 
-      For single-purpose plugins with a few related components:
+      // Component A
+      export const Dashboard = () => {
+          return (
+              <CustomReactiveJsonRoot rjBuild={dashboardConfig} />
+          );
+      };
 
-      ```javascript
-      export const simplePlugin = {
-          element: {
-              Alert: AlertComponent,
-              Badge: BadgeComponent,
-          }
+      // Component B  
+      export const ReportPage = () => {
+          return (
+              <CustomReactiveJsonRoot rjBuild={reportConfig} />
+          );
       };
-      ```
 
+  - type: Markdown
+    content: |
       ## Best Practices
 
-      ### Plugin Organization
       1. **Group related components** in the same plugin
       2. **Use descriptive names** for components and plugins
       3. **Document component props** and usage patterns
       4. **Provide examples** for complex components
-
-      ### Distribution
-      1. **Package as npm modules** for easy distribution
-      2. **Include TypeScript definitions** if using TypeScript
-      3. **Provide clear documentation** and examples
-      4. **Follow semantic versioning** for releases
-
-      ### Performance
-      1. **Lazy load large plugins** when possible
-      2. **Avoid global state** in plugin components
-      3. **Use React best practices** for component implementation
-      4. **Test plugin compatibility** with different Reactive-JSON versions
+      5. **Choose non-conflicting names** with existing components
 
 templates:

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

@@ -0,0 +1,151 @@
+# Reactive-JSON Getting Started Guide
+
+## 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.
+
+## Installation
+
+```bash
+npm install @ea-lab/reactive-json
+```
+
+## Basic Structure
+
+Every Reactive-JSON configuration follows this structure:
+
+```yaml
+renderView:  # Defines what should be rendered
+  - type: div
+    content: "Hello World!"
+
+templates:   # Defines reusable templates (optional)
+  myTemplate:
+    type: div
+    content: "Template content"
+
+data:        # Defines the data to be used (optional)
+  message: "Hello!"
+```
+
+## Key Concepts
+
+### 1. Template System
+
+Reactive-JSON uses three main notations to access data:
+
+- `~.` : Local context (relative to current template)
+- `~~.` : Global context (access to global data)
+- `~>field` : Access to a specific parent context
+
+Example:
+```yaml
+templates:
+  userCard:
+    type: div
+    content:
+      - type: div
+        content: ["Name: ", ~.name]  # Local access to user data
+      - type: div
+        content: ["Admin: ", ~~.isAdmin]  # Global access to isAdmin
+```
+
+### 2. Basic Elements
+
+Reactive-JSON provides several types of elements:
+
+#### HTML Elements
+- Div, Button, Modal, Accordion, etc.
+- Example:
+```yaml
+renderView:
+  - type: button
+    content: "Click me"
+```
+
+#### Form Fields
+- TextField, SelectField, CheckBoxField, etc.
+- Example:
+```yaml
+renderView:
+  - type: TextField
+    label: "Username"
+    dataLocation: ~.username
+```
+
+#### Special Elements
+- DataFilter, Switch, Count, etc.
+- Example:
+```yaml
+renderView:
+  - type: Switch
+    content: ~.items
+    template:
+      type: div
+      content: ~.name
+```
+
+### 3. Actions and Reactions
+
+#### Actions
+Actions modify element behavior:
+```yaml
+renderView:
+  - type: div
+    content: "Hidden content"
+    actions:
+      - what: hide
+        when: ~.shouldHide
+        is: true
+```
+
+#### Reactions
+Reactions respond to user events:
+```yaml
+renderView:
+  - type: button
+    content: "Save"
+    actions:
+      - what: setData
+        on: click
+        path: ~.saved
+        value: true
+```
+
+## Complete Example
+
+Here's a simple example of an interactive form:
+
+```yaml
+renderView:
+  - type: div
+    content:
+      - type: TextField
+        label: "Name"
+        dataLocation: ~.form.name
+      - type: TextField
+        label: "Email"
+        dataLocation: ~.form.email
+      - type: button
+        content: "Submit"
+        actions:
+          - what: submitData
+            on: click
+            url: "/api/submit"
+            data: ~.form
+            when: ~.form.name
+            isEmpty: not
+
+data:
+  form:
+    name: ""
+    email: ""
+```
+
+## Next Steps
+
+1. Explore the [complete examples](/docs/core/example) to see Reactive-JSON in action
+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