@ea-lab/reactive-json-docs 0.1.3 → 0.1.4

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

@@ -0,0 +1,215 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Component Development Guide
+
+      ## Overview
+
+      Creating custom components for Reactive-JSON involves building React components that follow specific patterns and integrate with the library's context system. This guide covers the essential patterns, APIs, and best practices for component development.
+
+      ## Core Concepts
+
+      ### Component Architecture
+      Reactive-JSON components follow these key principles:
+      - **Context Integration**: Use React contexts for data access and manipulation
+      - **Template Evaluation**: Support dynamic values through template patterns
+      - **Action/reaction Support**: Enable the action system through proper wrapping
+      - **Consistent Props**: Follow standard property patterns for consistency
+
+      ### Essential Contexts
+      All components have access to these React contexts:
+      - **GlobalDataContext**: Contains root data and `updateData` callback
+      - **TemplateContext**: Contains current template data for evaluation
+
+      Other specialized contexts are available.
+      - **EventDispatcherContext**: Centralized event handling system, mostly used by the [reaction system](/docs/core/reaction/index).
+      - **PaginationContext**: Used by components that integrate pagination, such as [Switch](/docs/core/element/special/Switch).
+
+      ## Basic Element Component
+
+      This example shows the structure of a basic element component that displays content and supports the action system.
+
+  - type: SyntaxHighlighter
+    language: jsx
+    content: |
+      import { ActionDependant } from "@ea-lab/reactive-json/dist/engine";
+      import { GlobalDataContext } from "@ea-lab/reactive-json/dist/engine";
+      import { TemplateContext } from "@ea-lab/reactive-json/dist/engine";
+      import { evaluateTemplateValue } from "@ea-lab/reactive-json/dist/engine";
+      import { useContext } from "react";
+
+      export const MyComponent = ({ props }) => {
+          const globalDataContext = useContext(GlobalDataContext);
+          const templateContext = useContext(TemplateContext);
+
+          // Evaluate dynamic values
+          const evaluatedContent = evaluateTemplateValue({
+              valueToEvaluate: props.content,
+              globalDataContext,
+              templateContext
+          });
+
+          return (
+              <ActionDependant {...props}>
+                  <div className="my-component">
+                      {evaluatedContent}
+                  </div>
+              </ActionDependant>
+          );
+      };
+
+  - type: Markdown
+    content: |
+      ## Form Component Pattern
+
+      Form components handle user input and provide two-way data binding with the global data context.
+
+  - type: SyntaxHighlighter
+    language: jsx
+    content: |
+      import { useContext } from 'react';
+      import { GlobalDataContext } from "@ea-lab/reactive-json/dist/engine";
+      import { ActionDependant } from "@ea-lab/reactive-json/dist/engine";
+      import { TemplateContext } from "@ea-lab/reactive-json/dist/engine";
+      import { useEvaluatedAttributes } from "@ea-lab/reactive-json/dist/engine";
+      import { propsDataLocationToPathAndValue } from "@ea-lab/reactive-json/dist/engine";
+
+      export const MyFormField = ({ props, datafield, path }) => {
+          const globalDataContext = useContext(GlobalDataContext);
+          const templateContext = useContext(TemplateContext);
+
+          const attributes = useEvaluatedAttributes(props.attributes);
+          
+          const { formData, formDataPath } = propsDataLocationToPathAndValue({
+              currentPath: path,
+              datafield: datafield,
+              dataLocation: props.dataLocation,
+              defaultValue: props.defaultFieldValue,
+              globalDataContext,
+              templateContext,
+          });
+
+          const onChange = (e) => {
+              globalDataContext.updateData(e.currentTarget.value, formDataPath);
+          };
+
+          return (
+              <ActionDependant {...props}>
+                  <input
+                      type="text"
+                      value={formData || ''}
+                      onChange={onChange}
+                      {...attributes}
+                  />
+              </ActionDependant>
+          );
+      };
+
+  - type: Markdown
+    content: |
+
+      ## Component with Nested Content
+
+      Components that render nested RjBuild content use the View component to process child elements.
+
+  - type: SyntaxHighlighter
+    language: jsx
+    content: |
+      import { View } from "@ea-lab/reactive-json/dist/engine";
+      import { useEvaluatedAttributes } from "@ea-lab/reactive-json/dist/engine";
+      import { ActionDependant } from "@ea-lab/reactive-json/dist/engine";
+
+      export const MyWrapper = ({ props, path, currentData, datafield }) => {
+          const attributes = useEvaluatedAttributes(props.attributes);
+
+          return (
+              <ActionDependant {...props}>
+                  <div className="my-wrapper" {...attributes}>
+                      {props?.content && (
+                          <View
+                              props={props.content}
+                              path={path + ".content"}
+                              currentData={currentData?.["content"]}
+                              datafield={"content"}
+                          />
+                      )}
+                  </div>
+              </ActionDependant>
+          );
+      };
+
+  - type: Markdown
+    content: |
+
+      ## Key APIs and Utilities
+
+      ### Template Evaluation
+      - **evaluateTemplateValue()**: Evaluates template patterns like `~.value`, `~~.value`, `~>.value`
+      - **evaluateTemplateValueCollection()**: Evaluates collections and arrays with template patterns, supports multiple elements
+      - **useEvaluatedAttributes()**: Hook to evaluate dynamic attributes object
+
+      ### Data Management
+      - **propsDataLocationToPathAndValue()**: Handles form data location and path resolution
+      - **GlobalDataContext.updateData()**: Updates data at specified path
+
+      ### Component Integration
+      - **ActionDependant**: Wrapper that enables action system support
+      - **View**: Renders RjBuild content or any displayable value
+
+      ## Action Component Pattern
+
+      Action components perform side effects and don't render visible content. They wrap their children and react to events or data changes. The conditional system (`when`, `is`, etc.) is handled by Actions.jsx, not by the action component itself.
+
+  - type: SyntaxHighlighter
+    language: jsx
+    content: |
+      import { useContext, useEffect } from "react";
+      import { EventDispatcherContext } from "@ea-lab/reactive-json/dist/engine";
+      import { GlobalDataContext } from "@ea-lab/reactive-json/dist/engine";
+      import { TemplateContext } from "@ea-lab/reactive-json/dist/engine";
+      import { evaluateTemplateValue } from "@ea-lab/reactive-json/dist/engine";
+
+      export const MyAction = (props) => {
+          const eventDispatcherContext = useContext(EventDispatcherContext);
+          const globalDataContext = useContext(GlobalDataContext);
+          const templateContext = useContext(TemplateContext);
+
+          const actionProps = props?.actionProps ?? undefined;
+
+          useEffect(() => {
+              // Action logic - this runs when Actions.jsx determines conditions are met
+              // No need to check conditions here, Actions.jsx handles that
+              if (actionProps?.targetElement) {
+                  // Perform the action on the target element
+                  actionProps.targetElement.style.display = 'none';
+              }
+          }, [actionProps, eventDispatcherContext, globalDataContext, templateContext]);
+
+          return <>{props.children}</>;
+      };
+
+  - type: Markdown
+    content: |
+
+      ## Best Practices
+
+      ### Component Guidelines
+      1. **Always wrap content with ActionDependant** to enable action system
+      2. **Use provided contexts** for data access and manipulation
+      3. **Evaluate template values** using provided utilities
+      4. **Handle attributes properly** using useEvaluatedAttributes
+      5. **Follow naming conventions** for consistency
+
+      ### Performance Considerations
+      - Use React hooks efficiently to avoid unnecessary re-renders
+      - Memoize expensive computations when appropriate
+      - Leverage the EventDispatcherContext for optimal event handling
+
+      ### 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
+
+templates:
+
+data: {} 

package/public/rjbuild/docs/extend/index.md

@@ -0,0 +1,20 @@
+# Extending Reactive-JSON
+
+## Overview
+
+Reactive-JSON is designed to be extensible through custom React components and plugins. This section provides comprehensive documentation on how to extend the library with your own components and integrate them using the plugin system.
+
+The extension system allows you to:
+- Create custom React components that integrate seamlessly with Reactive-JSON
+- Define plugins to organize and distribute your components
+- Use existing React libraries and wrap them for Reactive-JSON compatibility
+- Build reusable component libraries for your organization
+
+## Getting Started
+
+To start extending Reactive-JSON:
+
+1. **[Component Development](component-development)**: Learn how to create custom React components that integrate with Reactive-JSON
+2. **[Plugin System](plugin-system)**: Understand how to organize and distribute your components using the plugin system
+
+Each section provides detailed examples, best practices, and common patterns to help you build robust extensions. 

package/public/rjbuild/docs/extend/index.yaml

@@ -0,0 +1,29 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Extending Reactive-JSON
+
+      ## Overview
+
+      Reactive-JSON is designed to be extensible through custom React components and plugins. This section provides comprehensive documentation on how to extend the library with your own components and integrate them using the plugin system.
+
+      The extension system allows you to:
+      - Create custom React components that integrate seamlessly with Reactive-JSON
+      - Define plugins to organize and distribute your components
+      - Use existing React libraries and wrap them for Reactive-JSON compatibility
+      - Build reusable component libraries for your organization
+
+  - type: Markdown
+    content: |
+      ## Getting Started
+
+      To start extending Reactive-JSON:
+
+      1. **[Component Development](component-development)**: Learn how to create custom React components that integrate with Reactive-JSON
+      2. **[Plugin System](plugin-system)**: Understand how to organize and distribute your components using the plugin system
+
+      Each section provides detailed examples, best practices, and common patterns to help you build robust extensions.
+
+templates:
+
+data: {} 

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

@@ -0,0 +1,142 @@
+# Plugin System Guide
+
+## Overview
+
+The Reactive-JSON plugin system provides a structured way to organize, distribute, and integrate custom components. Plugins allow you to package related components together and make them available to Reactive-JSON applications through a simple registration mechanism.
+
+## Plugin Structure
+
+A plugin is a JavaScript object that exports components organized by type. The standard plugin structure includes:
+
+- **element**: Display components, form fields, and interactive elements
+- **action**: Components that perform side effects or modify behavior
+- **reaction**: Event-driven components that respond to user interactions
+- **hook**: React hooks that provide additional functionality
+
+## Plugin Registration
+
+Plugins are registered with the ReactiveJsonRoot component to make components available throughout the application.
+
+First, regroup your components in a plugin object.
+
+```jsx
+// myPlugin.js
+import { MyButton } from "./components/MyButton.jsx";
+import { MyForm } from "./components/MyForm.jsx";
+import { MyAction } from "./components/MyAction.jsx";
+
+export const myPlugin = {
+    element: {
+        MyButton,
+        MyForm,
+    },
+    action: {
+        MyAction,
+    }
+};
+```
+
+Then, register the plugin with the ReactiveJsonRoot component:
+
+```jsx
+import { ReactiveJsonRoot } from "@ea-lab/reactive-json";
+import { myPlugin } from "./plugins/myPlugin.js";
+
+const App = () => {
+    return (
+        <ReactiveJsonRoot
+            plugins={[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 { 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]}
+        />
+    );
+};
+```
+
+The plugin is now available throughout the application.
+
+## Multi-Plugin Application
+
+Applications can use multiple plugins, allowing for modular component organization.
+
+```jsx
+import { uiPlugin } from "./plugins/uiPlugin.js";
+import { formPlugin } from "./plugins/formPlugin.js";
+import { chartsPlugin } from "./plugins/chartsPlugin.js";
+
+const App = () => {
+    return (
+        <ReactiveJsonRoot
+            rjBuild={rjBuildConfig}
+            plugins={[
+                uiPlugin,
+                formPlugin,
+                chartsPlugin
+            ]}
+        />
+    );
+};
+```
+
+## Plugin Development Patterns
+
+### Standalone Plugin
+
+For single-purpose plugins with a few related components:
+
+```javascript
+export const simplePlugin = {
+    element: {
+        Alert: AlertComponent,
+        Badge: BadgeComponent,
+    }
+};
+```
+
+## 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 

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

@@ -0,0 +1,147 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Plugin System Guide
+
+      ## Overview
+
+      The Reactive-JSON plugin system provides a structured way to organize, distribute, and integrate custom components. Plugins allow you to package related components together and make them available to Reactive-JSON applications through a simple registration mechanism.
+
+      ## Plugin Structure
+
+      A plugin is a JavaScript object that exports components organized by type. The standard plugin structure includes:
+
+      - **element**: Display components, form fields, and interactive elements
+      - **action**: Components that perform side effects or modify behavior
+      - **reaction**: Event-driven components that respond to user interactions
+      - **hook**: React hooks that provide additional functionality
+
+      ## Plugin Registration
+
+      Plugins are registered with the ReactiveJsonRoot component to make components available throughout the application.
+
+      First, regroup your components in a plugin object.
+
+      ```jsx
+      // myPlugin.js
+      import { MyButton } from "./components/MyButton.jsx";
+      import { MyForm } from "./components/MyForm.jsx";
+      import { MyAction } from "./components/MyAction.jsx";
+
+      export const myPlugin = {
+          element: {
+              MyButton,
+              MyForm,
+          },
+          action: {
+              MyAction,
+          }
+      };
+      ```
+
+      Then, register the plugin with the ReactiveJsonRoot component:
+
+      ```jsx
+      import { ReactiveJsonRoot } from "@ea-lab/reactive-json";
+      import { myPlugin } from "./plugins/myPlugin.js";
+
+      const App = () => {
+          return (
+              <ReactiveJsonRoot
+                  plugins={[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 { 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]}
+                />
+            );
+        };
+        ```
+
+      The plugin is now available throughout the application.
+
+      ## Multi-Plugin Application
+      
+      Applications can use multiple plugins, allowing for modular component organization.
+
+      ```jsx
+      import { uiPlugin } from "./plugins/uiPlugin.js";
+      import { formPlugin } from "./plugins/formPlugin.js";
+      import { chartsPlugin } from "./plugins/chartsPlugin.js";
+
+      const App = () => {
+          return (
+              <ReactiveJsonRoot
+                  rjBuild={rjBuildConfig}
+                  plugins={[
+                      uiPlugin,
+                      formPlugin,
+                      chartsPlugin
+                  ]}
+              />
+          );
+      };
+      ```
+
+      ## Plugin Development Patterns
+
+      ### Standalone Plugin
+
+      For single-purpose plugins with a few related components:
+
+      ```javascript
+      export const simplePlugin = {
+          element: {
+              Alert: AlertComponent,
+              Badge: BadgeComponent,
+          }
+      };
+      ```
+
+      ## 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
+
+templates:

package/public/rjbuild/docs/index.yaml

@@ -1,12 +1,66 @@
 renderView:
-#  - type: div
-#    content: index de la doc
+  - type: Markdown
+    content: |
+      # Reactive-JSON Documentation
 
-  - type: h1
-    content: Demo pages
+      Welcome to the comprehensive documentation for **Reactive-JSON** - a powerful library that transforms JSON configurations into interactive React components.
 
-  - type: p
-    content: Please have a look on the sidebar to access our live examples.
+      ## What is Reactive-JSON?
+
+      Reactive-JSON is a declarative framework that allows you to build dynamic, interactive user interfaces using simple JSON or YAML configurations. No JavaScript boilerplate, no complex state management - just pure declarative power.
+
+  - type: Markdown
+    content: |
+      ## Key Features
+
+      - **🎯 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
+      - **🎨 Flexible**: Support for custom components and styling
+      - **📊 Data-Driven**: Built-in data operations and API integration
+
+      ## Documentation Sections
+
+      ### Core Components
+
+      - **Elements** - Form fields, HTML elements, and special components
+        - Form Fields - Input fields, selects, checkboxes, etc.
+        - HTML Elements - Divs, modals, accordions, syntax highlighting, etc.
+        - Special Elements - Advanced components like data filters, pagination, etc.
+
+      - **Actions** - Interactive behaviors and UI modifications
+        - Control element visibility, tooltips, redirects, and event handling
+
+      - **Reactions** - Data operations and side effects
+        - Fetch data, submit forms, manipulate state, and trigger events
+
+      ### Examples & Tutorials
+
+      - **Complete Examples** - Real-world use cases and patterns
+        - Interactive forms, dynamic content, website layouts, and more
+
+      ### Extensions
+
+      - **Component Development** - Create custom components
+      - **Plugin System** - Extend Reactive-JSON functionality
+
+      ### Integrations
+
+      - **Chart.js Integration** - Create interactive charts and visualizations
+
+  - type: Markdown
+    content: |
+      ## Getting Started
+
+      1. **Explore the Examples** - Check out the complete examples to see Reactive-JSON in action
+      2. **Learn the Basics** - Start with form elements and actions
+      3. **Try Interactive Features** - Experiment with reactions for data operations
+      4. **Build Something** - Use the documentation as your guide to create your first Reactive-JSON application
+
+      ---
+
+      **Ready to build something amazing?** Pick a section from the sidebar and start exploring!
 
 templates: