@ea-lab/reactive-json 0.0.39 → 0.0.41

package/.cursorrules

@@ -0,0 +1,74 @@
+# Instructions for Cursor AI - Reactive-JSON
+
+## 🚀 Quick Start for AI Assistants
+**FIRST STEP**: Read `README_LLM.md` for comprehensive reactive-json development patterns, component architectures, and AI-optimized examples.
+
+## Reference Documentation
+- Installation: `npm install --save-dev @ea-lab/reactive-json-docs`
+- Main documentation entry point with demos: `node_modules/@ea-lab/reactive-json-docs/public/rjbuild/docs/index.yaml`
+- **Component Development** (React source code): `node_modules/@ea-lab/reactive-json-docs/public/rjbuild/docs/extend/`
+  - `component-development.md`: Complete guide for creating React components
+  - `plugin-system.md`: Plugin system and architecture
+- **Component Usage** (JSON/YAML configuration): `node_modules/@ea-lab/reactive-json-docs/public/rjbuild/docs/core/`
+  - `action/`: Action components usage (Hide, Tooltip, Popover, etc.)
+  - `element/`: Element components usage (form fields, HTML elements, etc.) 
+  - `reaction/`: Reaction components usage (data operations)
+  - `example/`: Complete examples and use cases
+- Chart.js integration overview: `node_modules/@ea-lab/reactive-json-docs/public/rjbuild/docs/chartjs/`
+
+## Main Instructions
+1. **ALWAYS consult the documentation in `@ea-lab/reactive-json-docs` package** before proposing solutions
+2. Start with `node_modules/@ea-lab/reactive-json-docs/public/rjbuild/docs/index.yaml` or relevant category documentation
+3. Follow the patterns and examples shown in the .yaml and .md files
+4. **Documentation Priority**: Prefer .md files when available (more digestible for LLM analysis), fallback to .yaml files if .md doesn't exist
+5. **Context-Aware Documentation**: 
+   - For React component development → `extend/component-development.md`
+   - For JSON/YAML usage → `core/[category]/`
+6. Refer to the comprehensive examples in `node_modules/@ea-lab/reactive-json-docs/public/rjbuild/docs/core/example/`
+
+**Context-Specific References**:
+- For **creating/developing** React components → use `extend/component-development.md`
+- For **using/configuring** components in JSON/YAML → use `core/[category]/`
+
+## Plugin System Requirements
+
+**⚠️ CRITICAL**: When using custom components as plugins, `mergeComponentCollections([...])` is **MANDATORY** - even for a single plugin collection. The reactive-json plugin system will NOT work without it.
+
+```js
+import {ReactiveJsonRoot, mergeComponentCollections} from "@ea-lab/reactive-json";
+
+const plugins = mergeComponentCollections([customPlugins]); // REQUIRED
+return <ReactiveJsonRoot {...props} plugins={plugins} />;
+```
+
+## Component Validation Rules
+
+1. For each component, STRICTLY verify:
+   - The structure of properties in the documentation
+   - The type of each property (array, object, string, etc.)
+   - The examples provided in .md and .yaml files
+
+2. For array-type properties:
+   - ✅ Allow multiple distinct elements
+   - ❌ Never duplicate properties within the same element
+   - ✅ Respect the unitary structure of each element
+
+3. Documentation conventions:
+   - If a property is an array, it accepts multiple DISTINCT elements
+   - Each array element must strictly follow the documented schema
+   - Multiple conditions must be distributed across separate elements
+
+4. When in doubt:
+   - Always refer to the documentation examples
+   - Do not extrapolate undocumented functionalities
+   - Prioritize simplicity and clarity
+
+## Language Rules
+- Respond in the language of the user's question or as specified by the user in the conversation
+- Always write documentation content in English, regardless of the conversation language
+
+## Response Process
+1. First consult the relevant documentation in `@ea-lab/reactive-json-docs` package
+2. Verify existing examples in the appropriate category
+3. Apply validation rules
+4. Propose a solution compliant with standards 

package/README.md

@@ -7,6 +7,8 @@ This lib lessens the need to write JS code for building frontend apps.
 With *reactive-json*, build your apps and forms frontend, embed them into your websites,
 and make them interactive with your backend.
 
+> **🤖 AI Guide**: If you're using an AI assistant (like Cursor, ChatGPT, Claude, etc.) to work with reactive-json, start by reading [`README_LLM.md`](./README_LLM.md) - it contains comprehensive patterns, examples, and best practices specifically designed for AI-assisted development.
+
 ## How to use *reactive-json*
 
 Reactive-json must be included as an npm dependency in your React project. There are two main ways to use it:
@@ -106,7 +108,7 @@ The `ReactiveJsonRoot` component accepts the following properties:
 - `dataUrl`: The URL of the document containing the build data (JSON or YAML)
 - `dataFetchMethod`: The fetch method for the data ("GET" or "POST", case-insensitive)
 - `headersForData`: Headers for the data request (e.g., authentication info)
-- `plugins`: Reactive-JSON plugins to extend functionality
+- `plugins`: Reactive-JSON plugins to extend functionality (**must** use `mergeComponentCollections`)
 - `debugMode`: Debug mode to show the data structure and debug info
 - `maybeRawAppData`: A RjBuild configuration to initialize directly (string or object)
 

package/README_LLM.md

@@ -0,0 +1,434 @@
+# System Prompt: Reactive-JSON User Guide
+
+<!-- 
+AI/LLM KEYWORDS: reactive-json, component development, react components, JSON to HTML, AI assistant guide, cursor ai, chatgpt, claude, component patterns, plugin system, template system
+PURPOSE: Comprehensive guide for AI assistants to work with reactive-json library
+AUDIENCE: AI assistants, LLM developers, Cursor AI users, ChatGPT users, Claude users
+-->
+
+## 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 `@ea-lab/reactive-json-docs` package before proposing solutions, following existing patterns and examples.
+
+## Reference Documentation
+- Installation: `npm install --save-dev @ea-lab/reactive-json-docs`
+- Main documentation entry point with demos: `node_modules/@ea-lab/reactive-json-docs/public/rjbuild/docs/index.yaml`
+- **Component Development** (React source code): `node_modules/@ea-lab/reactive-json-docs/public/rjbuild/docs/extend/`
+  - `component-development.md`: Complete guide for creating React components
+  - `plugin-system.md`: Plugin system and architecture
+- **Component Usage** (JSON/YAML configuration): `node_modules/@ea-lab/reactive-json-docs/public/rjbuild/docs/core/`
+  - `action/`: Action components usage (Hide, Tooltip, Popover, etc.)
+  - `element/`: Element components usage (form fields, HTML elements, etc.) 
+  - `reaction/`: Reaction components usage (data operations)
+  - `example/`: Complete examples and use cases
+- Chart.js integration overview: `node_modules/@ea-lab/reactive-json-docs/public/rjbuild/docs/chartjs/`
+
+**Documentation Priority**: Prefer .md files when available (more digestible for LLM analysis), fallback to .yaml files if .md doesn't exist.
+
+> 💡 **Quick Start**: Begin with `node_modules/@ea-lab/reactive-json-docs/public/rjbuild/docs/index.yaml` for an overview, then dive into specific component categories.
+
+---
+
+## 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,
+    evaluateTemplateValue,
+    GlobalDataContext,
+    TemplateContext
+} from "@ea-lab/reactive-json";
+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>
+    );
+};
+```
+
+> 📚 **More details**: See `node_modules/@ea-lab/reactive-json-docs/public/rjbuild/docs/extend/component-development.md` for detailed component development patterns.
+
+### 2. Form Element Component Structure
+
+```jsx
+import {useContext} from 'react';
+import {
+    ActionDependant,
+    evaluateTemplateValue,
+    GlobalDataContext,
+    propsDataLocationToPathAndValue,
+    TemplateContext,
+    useEvaluatedAttributes
+} from "@ea-lab/reactive-json";
+
+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>
+    );
+};
+```
+
+> 📚 **More details**: See `node_modules/@ea-lab/reactive-json-docs/public/rjbuild/docs/extend/component-development.md` for form component development patterns. For usage examples, see `core/element/form/`.
+
+### 3. Component with View (Nested Content)
+
+```jsx
+import {
+    ActionDependant,
+    useEvaluatedAttributes,
+    View
+} from "@ea-lab/reactive-json";
+
+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>
+    );
+};
+```
+
+> 📚 **More details**: See `node_modules/@ea-lab/reactive-json-docs/public/rjbuild/docs/extend/component-development.md` for wrapper component patterns. For usage examples, see `core/element/html/`.
+
+### 4. Generic Bootstrap Wrapper
+
+```jsx
+import {
+    ActionDependant,
+    useEvaluatedAttributes,
+    View
+} from "@ea-lab/reactive-json";
+
+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 {
+    evaluateTemplateValue,
+    EventDispatcherContext,
+    GlobalDataContext,
+    TemplateContext
+} from "@ea-lab/reactive-json";
+
+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}</>;
+};
+```
+
+> 📚 **More details**: See `node_modules/@ea-lab/reactive-json-docs/public/rjbuild/docs/extend/component-development.md` for action component development patterns. For usage examples, see `core/action/`.
+
+---
+
+## Key APIs & Contexts
+
+### Essential Contexts
+- **GlobalDataContext**: Contains root data and `updateData` callback
+- **TemplateContext**: Contains current template data
+- **EventDispatcherContext**: Centralized event handling for performance
+
+### Key Functions
+- **evaluateTemplateValue()**: Evaluates template patterns (`~.value`, `~~.value`, `~>.value`)
+- **useEvaluatedAttributes()**: Hook to evaluate dynamic attributes
+- **propsDataLocationToPathAndValue()**: Form-specific data location handling
+
+> 📚 **More details**: See `node_modules/@ea-lab/reactive-json-docs/public/rjbuild/docs/extend/component-development.md` for API usage patterns.
+
+### Core Components
+- **ActionDependant**: Enables action system support (wrap your component content)
+- **View**: Renders RjBuild content or any displayable value
+
+> 📚 **More details**: See `node_modules/@ea-lab/reactive-json-docs/public/rjbuild/docs/extend/component-development.md` for core component development patterns. For reaction function usage, see `core/reaction/`.
+
+---
+
+## Component Creation Rules
+
+### 1. Import Path Conventions
+**For consumer applications** (recommended):
+```jsx
+import {
+    ActionDependant,
+    evaluateTemplateValue,
+    GlobalDataContext,
+    TemplateContext
+} from "@ea-lab/reactive-json";
+```
+
+**Inside reactive-json library development** (internal use only):
+```jsx
+import {ActionDependant} from "../../../engine/Actions.jsx";
+```
+
+### 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 {
+    mergeComponentCollections,
+    ReactiveJsonRoot
+} 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} />;
+};
+```
+
+**⚠️ CRITICAL**: `mergeComponentCollections([...])` is **mandatory** even when you have only a single plugin collection. The reactive-json plugin system will not work without it.
+
+### Plugin Structure
+```js
+{
+    action: { /* Action components */ },
+    element: { /* Element components */ },
+    hook: { /* React hooks */ },
+    reaction: { /* Reaction functions */ },
+}
+```
+
+> 📚 **More details**: See `node_modules/@ea-lab/reactive-json-docs/public/rjbuild/docs/extend/plugin-system.md` for plugin development. For integration examples, see `core/example/`.
+
+---
+
+## 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
+
+> 📚 **More details**: See `node_modules/@ea-lab/reactive-json-docs/public/rjbuild/docs/extend/component-development.md` for complete development workflow guide.
+
+---
+
+## 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
+```
+
+> 📚 **More details**: See `node_modules/@ea-lab/reactive-json-docs/public/rjbuild/docs/core/` for usage examples.
+
+---
+
+**Remember**: Always prioritize simplicity, follow existing patterns, and make components fail gracefully. When in doubt, check the documentation in `@ea-lab/reactive-json-docs` package first. 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ea-lab/reactive-json",
   "private": false,
-  "version": "0.0.39",
+  "version": "0.0.41",
   "type": "module",
   "repository": {
     "type": "git",
@@ -16,7 +16,12 @@
     "json",
     "react",
     "structure",
-    "yaml"
+    "yaml",
+    "llm",
+    "ai-assistant",
+    "cursor",
+    "chatgpt",
+    "claude"
   ],
   "author": "Quang-Minh DANG <quang-minh@ea-lab.io> (https://ea-lab.io/)",
   "license": "ISC",
@@ -76,9 +81,16 @@
   "main": "dist/main.js",
   "types": "dist/main.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "README_LLM.md",
+    ".cursorrules"
   ],
   "sideEffects": [
     "**/*.css"
-  ]
+  ],
+  "llm": {
+    "entrypoint": "README_LLM.md",
+    "description": "AI/LLM guide for reactive-json development",
+    "purpose": "Component creation and reactive-json usage patterns for AI assistants"
+  }
 }