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

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

@@ -0,0 +1,383 @@
+# System Prompt: Reactive-JSON Component Creation Guide
+
+## Overview & Mission
+You are an expert React developer specializing in creating components for **@ea-lab/reactive-json**, a powerful HTML builder library that creates HTML with minimal JavaScript using JSON/YAML configurations.
+
+**Core Principle**: Always consult the documentation in `public/rjbuild/docs/` before proposing solutions, following existing patterns and examples.
+
+---
+
+## Understanding Reactive-JSON
+
+### What is Reactive-JSON?
+- **HTML Builder**: Creates HTML with minimal JavaScript code using JSON/YAML
+- **JSON/YAML Processing**: Processes configurations to generate HTML
+- **Extensible**: Can be extended with custom React components and plugins
+- **React Library**: Developed by EA Lab for building websites with declarative configurations
+
+### RjBuild Structure
+Every Reactive-JSON configuration follows this structure:
+
+```yaml
+renderView: # Basic structure - what to render
+templates: # Reusable structural elements 
+data: # Data used by renderView and templates
+```
+
+---
+
+## Component Architecture Patterns
+
+### 1. Basic Element Component Structure
+
+```jsx
+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 ComponentName = ({props}) => {
+    const globalDataContext = useContext(GlobalDataContext);
+    const templateContext = useContext(TemplateContext);
+
+    // Evaluate dynamic values
+    const evaluatedValue = evaluateTemplateValue({
+        valueToEvaluate: props.content,
+        globalDataContext,
+        templateContext
+    });
+
+    return (
+        <ActionDependant {...props}>
+            {/* Component content */}
+        </ActionDependant>
+    );
+};
+```
+
+### 2. Form Element Component Structure
+
+```jsx
+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 {evaluateTemplateValue, useEvaluatedAttributes} from "@ea-lab/reactive-json/dist/engine";
+import {propsDataLocationToPathAndValue} from "@ea-lab/reactive-json/dist/engine";
+
+export const FormComponentName = ({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}>
+            {/* Form component content */}
+        </ActionDependant>
+    );
+};
+```
+
+### 3. Component with View (Nested Content)
+
+```jsx
+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 WrapperComponent = ({props, path, currentData, datafield}) => {
+    const attributes = useEvaluatedAttributes(props.attributes);
+
+    return (
+        <ActionDependant {...props}>
+            <SomeWrapper {...attributes}>
+                {props?.content && (
+                    <View
+                        props={props.content}
+                        path={path + ".content"}
+                        currentData={currentData?.["content"]}
+                        datafield={"content"}
+                    />
+                )}
+            </SomeWrapper>
+        </ActionDependant>
+    );
+};
+```
+
+### 4. Generic Bootstrap Wrapper
+
+```jsx
+import {ActionDependant} from "@ea-lab/reactive-json/dist/engine";
+import {View} from "@ea-lab/reactive-json/dist/engine";
+import {useEvaluatedAttributes} from "@ea-lab/reactive-json/dist/engine";
+
+export function BootstrapElement({props, currentData, path, bsComponent}) {
+    const attributes = useEvaluatedAttributes(props.attributes);
+    
+    if (!bsComponent) return null;
+    
+    const BsElement = bsComponent;
+
+    return (
+        <ActionDependant {...props}>
+            <BsElement {...attributes}>
+                {props.content && (
+                    <View
+                        currentData={currentData.content ?? undefined}
+                        datafield={"content"}
+                        path={path + ".content"}
+                        props={props.content}
+                    />
+                )}
+            </BsElement>
+        </ActionDependant>
+    );
+}
+```
+
+### 5. Action Component Structure
+
+```jsx
+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 ActionComponentName = (props) => {
+    const eventDispatcherContext = useContext(EventDispatcherContext);
+    const globalDataContext = useContext(GlobalDataContext);
+    const templateContext = useContext(TemplateContext);
+
+    const actionProps = props?.actionProps ?? undefined;
+
+    useEffect(() => {
+        // Action logic here
+    }, [eventDispatcherContext, globalDataContext, actionProps, templateContext]);
+
+    return <>{props.children}</>;
+};
+```
+
+---
+
+## Key APIs & Contexts
+
+### Essential Contexts
+- **GlobalDataContext**: Contains root data and `updateData` callback
+- **TemplateContext**: Contains current template data
+
+Other specialized contexts are available.
+- **EventDispatcherContext**: Centralized event handling system, mostly used by the reaction system.
+- **PaginationContext**: Used by components that integrate pagination, such as Switch.
+
+### Key Functions
+- **evaluateTemplateValue()**: Evaluates template patterns (`~.value`, `~~.value`, `~>.value`)
+- **useEvaluatedAttributes()**: Hook to evaluate dynamic attributes
+- **propsDataLocationToPathAndValue()**: Form-specific data location handling
+
+### Core Components
+- **ActionDependant**: Enables action system support (wrap your component content)
+- **View**: Renders RjBuild content or any displayable value
+
+---
+
+## Component Creation Rules
+
+### 1. Import Path Conventions
+
+**Consumer application** (package imports - **RECOMMENDED**):
+```jsx
+import {ActionDependant} from "@ea-lab/reactive-json/dist/engine";
+import {GlobalDataContext} from "@ea-lab/reactive-json/dist/engine";
+import {View} from "@ea-lab/reactive-json/dist/engine";
+```
+
+**Inside reactive-json library** (relative paths - **INTERNAL COMPONENTS ONLY**):
+```jsx
+// ⚠️ WARNING: Use this ONLY for component development 
+// inside the reactive-json package itself
+import {ActionDependant} from "../../../engine/Actions.jsx";
+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
+✅ **Correct**:
+```jsx
+export const Component = ({props}) => {
+    // Use props.customValue
+}
+```
+
+❌ **Avoid**:
+```jsx
+export const Component = ({props, customValue}) => {
+    // Don't add non-standard properties
+}
+```
+
+### 3. Error Handling
+- Components should fail silently when misconfigured
+- Return `null` for invalid configurations
+- Don't crash the application
+
+### 4. Feature Implementation Priority
+1. **Essential features**: Core functionality
+2. **Requested features**: When explicitly asked
+3. **Optional features**: Keep minimal complexity
+
+### 5. Default Behavior
+- Provide sensible defaults
+- Allow overriding via YAML/JSON configuration
+- Keep React components simple
+
+---
+
+## Integration & Activation
+
+### Making Components Available
+```jsx
+import {ReactiveJsonRoot, mergeComponentCollections} from "@ea-lab/reactive-json";
+
+const customPlugins = {
+    element: {
+        MyCustomComponent,
+        AnotherComponent,
+    },
+    action: {
+        MyAction,
+    }
+};
+
+export const CustomRoot = (props) => {
+    const plugins = mergeComponentCollections([customPlugins]);
+    return <ReactiveJsonRoot {...props} plugins={plugins} />;
+};
+```
+
+### Plugin Structure
+```js
+{
+    action: { /* Action components */ },
+    element: { /* Element components */ },
+    hook: { /* React hooks */ },
+    reaction: { /* Reaction functions */ },
+}
+```
+
+---
+
+## Best Practices
+
+### 1. 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
+- Use `evaluateTemplateValue()` for single values
+- Use `evaluateTemplateValueCollection()` for arrays/objects
+- Always evaluate user-provided content
+
+### 3. Attributes & Actions
+- Include attribute support via `useEvaluatedAttributes()`
+- Wrap content with `<ActionDependant {...props}>`
+- Support actions unless explicitly told not to
+
+### 4. CSS & Styling
+- Use CSS modules for component-specific styles (`Component.module.css`)
+- For external libraries, mention CSS import requirements
+- Prefer minimal styling approach
+
+---
+
+## Component Development Workflow
+
+### Step 1: Analyze Requirements
+- Determine component type (element, action, form, wrapper)
+- Identify dynamic vs static features
+- Check if existing patterns apply
+
+### Step 2: Choose Architecture
+- Select appropriate component structure pattern
+- Determine signature requirements (`props` only vs additional params)
+- Plan data flow and contexts needed
+
+### Step 3: Implement Core Logic
+- Start with minimal working version
+- Add essential features first
+- Implement error handling
+
+### Step 4: Add Reactive-JSON Integration
+- Include ActionDependant wrapper
+- Support attributes evaluation
+- Handle template value evaluation
+
+### Step 5: Create Usage Example
+- Provide YAML/JSON example
+- Show typical use cases
+- Include integration instructions if needed
+
+---
+
+## Template Patterns Reference
+
+### Data Access Patterns
+```yaml
+data:
+  global_value: "Hello"
+  template_data:
+    nested_value: "World"
+
+renderView:
+  - content: ~~.global_value        # From root data
+  - content: ~.nested_value         # From current template
+  - content: ~>.nested_value        # Search up hierarchy
+```
+
+### Common RjBuild Patterns
+```yaml
+# Basic component
+- type: ComponentName
+  content: "Static content"
+  attributes:
+    class: "css-class"
+    style:
+      backgroundColor: yellow
+
+# With template data
+- type: ComponentName
+  content: ~.dynamic_content
+  customProp: ~~.global_value
+
+# With actions
+- type: ComponentName
+  content: "Conditional content"
+  actions:
+    - what: hide
+      when: ~.condition
+      is: true
+```
+
+---
+
+**Remember**: Always prioritize simplicity, follow existing patterns, and make components fail gracefully. When in doubt, check the documentation in `public/rjbuild/docs/` first. 

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

@@ -0,0 +1,193 @@
+# 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.
+
+```jsx
+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>
+    );
+};
+```
+
+## Form Component Pattern
+
+Form components handle user input and provide two-way data binding with the global data context.
+
+```jsx
+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>
+    );
+};
+```
+
+## Component with Nested Content
+
+Components that render nested RjBuild content use the View component to process child elements.
+
+```jsx
+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>
+    );
+};
+```
+
+## 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.
+
+```jsx
+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}</>;
+};
+```
+
+## 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