@ea-lab/reactive-json-docs 0.1.9 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ea-lab/reactive-json-docs",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Complete documentation for Reactive-JSON - Components, examples and LLM-parsable guides",
   "main": "public/rjbuild/docs/index.yaml",
   "files": [
@@ -26,7 +26,7 @@
   "private": false,
   "devDependencies": {
     "@craco/craco": "^7.1.0",
-    "@ea-lab/reactive-json": "^0.0.44",
+    "@ea-lab/reactive-json": "^0.0.45",
     "@ea-lab/reactive-json-chartjs": "^0.0.23",
     "@npmcli/fs": "^4.0.0",
     "@reduxjs/toolkit": "^2.6.1",

package/public/rjbuild/docs/chartjs/overview.yaml

@@ -34,7 +34,7 @@ renderView:
       export const YourComponent = () => {
 
         const rjRootProps = {
-          // Set your own props to rjRootProps such as dataUrl.
+          // Set your own props to rjRootProps such as rjBuildUrl.
           // ...
         };
 

package/public/rjbuild/docs/core/element/special/ReactiveJsonSubroot.md

@@ -5,7 +5,7 @@
 The `ReactiveJsonSubroot` component allows you to render a new Reactive-JSON root inside an existing application. It is useful for embedding a sub-application, isolating a part of the data tree, or rendering a separate rjbuild with its own options.
 
 ## Properties
-- `rjOptions` (object, required): Options to pass to the subroot (such as `dataUrl`, `data`, `renderView`, etc.)
+- `rjOptions` (object, required): Options to pass to the subroot (such as `rjBuildUrl`, `data`, `renderView`, etc.)
 - Other properties are passed to the underlying `ReactiveJsonRoot`
 
 ## Behavior
@@ -19,7 +19,7 @@ The `ReactiveJsonSubroot` component allows you to render a new Reactive-JSON roo
 renderView:
   - type: ReactiveJsonSubroot
     rjOptions:
-      dataUrl: "/rjs-build/home.yaml"
+      rjBuildUrl: "/rjs-build/home.yaml"
 ```
 
 ## Limitations

package/public/rjbuild/docs/core/element/special/ReactiveJsonSubroot.yaml

@@ -6,7 +6,7 @@ renderView:
       The `ReactiveJsonSubroot` component allows you to render a new Reactive-JSON root inside an existing application. It is useful for embedding a sub-application, isolating a part of the data tree, or rendering a separate rjbuild with its own options.
 
       ## Properties
-      - `rjOptions` (object, required): Options to pass to the subroot (such as `dataUrl`, `data`, `renderView`, etc.)
+      - `rjOptions` (object, required): Options to pass to the subroot (such as `rjBuildUrl`, `data`, `renderView`, etc.)
       - Other properties are passed to the underlying `ReactiveJsonRoot`
 
       ## Behavior
@@ -22,16 +22,16 @@ renderView:
       renderView:
         - type: ReactiveJsonSubroot
           rjOptions:
-            dataUrl: "/rjbuild/component/message.yaml"
+            rjBuildUrl: "/rjbuild/component/message.yaml"
 
   - type: RjBuildDescriber
     title: Example with inline JSON data
-    description: This example demonstrates two approaches for using ReactiveJsonSubroot with inline data. The first shows passing JSON data directly as a string via maybeRawAppData. The second shows loading subroot options dynamically from the main RjBuild's data using template interpolation. Both approaches are useful for embedding sub-applications without external files.
+    description: This example demonstrates two approaches for using ReactiveJsonSubroot with inline data. The first shows passing JSON data directly as a string via maybeRawAppRjBuild. The second shows loading subroot options dynamically from the main RjBuild's data using template interpolation. Both approaches are useful for embedding sub-applications without external files.
     toDescribe:
       renderView:
         - type: ReactiveJsonSubroot
           rjOptions:
-            maybeRawAppData: '{"data":{"userName":"Alice","messageCount":3},"renderView":[{"type":"div","attributes":{"style":{"padding":"1rem","border":"1px solid #ddd","borderRadius":"8px","backgroundColor":"#f9f9f9"}},"content":[{"type":"h3","content":"~~.userName"},{"type":"p","content":["You have ","~~.messageCount"," new messages."]},{"type":"button","content":"Mark as read","attributes":{"style":{"backgroundColor":"#007bff","color":"white","border":"none","padding":"0.5rem 1rem","borderRadius":"4px"}}}]}]}'
+            maybeRawAppRjBuild: '{"data":{"userName":"Alice","messageCount":3},"renderView":[{"type":"div","attributes":{"style":{"padding":"1rem","border":"1px solid #ddd","borderRadius":"8px","backgroundColor":"#f9f9f9"}},"content":[{"type":"h3","content":"~~.userName"},{"type":"p","content":["You have ","~~.messageCount"," new messages."]},{"type":"button","content":"Mark as read","attributes":{"style":{"backgroundColor":"#007bff","color":"white","border":"none","padding":"0.5rem 1rem","borderRadius":"4px"}}}]}]}'
 
         - type: hr
 
@@ -39,7 +39,7 @@ renderView:
           rjOptions: ~~.subrootToLoad
       data:
         subrootToLoad:
-          maybeRawAppData:
+          maybeRawAppRjBuild:
             renderView:
               - type: div
                 content: This second subroot is loaded from the "data" key of the main root.

package/public/rjbuild/docs/install.md

@@ -2,83 +2,166 @@
 
 > **Tip**: In the interactive version of this documentation, a button is available to automatically copy the initialization prompt. Copy it and paste it into Cursor to start the step-by-step assistant.
 
-## ⚠️ Important Rule
+## ⚠️ Important Rules
 
-**DO NOT SKIP STEPS** unless explicitly requested by the user. Each step is critical for the proper functioning of the project and must be executed in the defined order.
+**NEVER SKIP STEPS** unless explicitly requested by the user. Each step is critical for the proper functioning of the project and must be executed in the defined chronological order.
+
+When user feedback is required, wait for it and do not continue until this feedback is given.
+
+Adapt commands according to the execution environment (Windows, Ubuntu, Mac...).
 
 ## Table of Contents
 
-1. [Collecting User Information](#1-collecting-user-information)
-2. [Documentation Repositories Setup](#2-documentation-repositories-setup)
-3. [Cursor Workspace Configuration](#3-cursor-workspace-configuration)
-4. [Vite Project Initialization](#4-vite-project-initialization)
-5. [Dependencies Installation](#5-dependencies-installation)
-6. [Cursor Rules Creation](#6-cursor-rules-creation)
-7. [Generated Project Cleanup](#7-generated-project-cleanup)
-8. [Basic Configuration with ReactiveJsonRoot](#8-basic-configuration-with-reactivejsonroot)
-9. [Final Verification](#9-final-verification)
+1. [Project Directory Confirmation](#1-project-directory-confirmation)
+2. [Collecting User Information](#2-collecting-user-information)
+3. [Documentation Repositories Setup](#3-documentation-repositories-setup)
+4. [Cursor Workspace Configuration](#4-cursor-workspace-configuration)
+5. [Vite Project Initialization](#5-vite-project-initialization)
+6. [Project Structure Verification](#6-project-structure-verification)
+7. [Dependencies Installation](#7-dependencies-installation)
+8. [Cursor Project Rules Creation](#8-cursor-project-rules-creation)
+9. [Generated Project Cleanup](#9-generated-project-cleanup)
+10. [Basic Configuration with ReactiveJsonRoot](#10-basic-configuration-with-reactivejsonroot)
+11. [Routing Configuration (Optional)](#11-routing-configuration-optional)
+12. [Final Verification](#12-final-verification)
+
+## Chronological Steps
+
+### 1. Project Directory Confirmation
+
+**Action:** Show the user if the IDE is opened in the directory where the project will
+be initialized, then ask for confirmation:
+
+- Execute the command:
+  ```bash
+  pwd
+  ```
+- Show the user this info:
+  > **IMPORTANT: Directory Confirmation Required**
+  > 
+  > **Current directory:** `[Display the result of pwd command]`
+  > 
+  > **This directory will become your project root.** All project files will be created here.
+- Ask the user for confirmation:
+  > **Do you confirm that this is the correct location before continuing?** If the location is wrong,
+  > please open in your IDE the location where the project will be created and restart the
+  > installation procedure.
+- User feedback required.
+- When user confirms, note the project directory as `<project_dir>` and go to the next step.
 
 ---
 
-## 1. Collecting User Information
+### 2. Collecting User Information
 
-Ask the user for:
+**Action:** Ask the user for the following information:
 
-- **Project name**
-- **TypeScript?** (yes/no)
-- **Documentation repositories location** (absolute path)
+- **TypeScript**: Ask if the user wants to use TypeScript (yes/no)
+- **Documentation repositories location**: Absolute path where to clone reactive-json and reactive-json-docs repositories. When the user gives a relative path, convert it to absolute
+and ask for confirmation.
 
-Remember:
+**Important:** For documentation location, **NEVER** place them in the current project directory. Propose by default: `~/cursor-docs/` or let the user specify another location outside the current project.
 
-| Variable | Description |
-| -------- | ----------- |
-| `<project_name>` | Project name |
-| `<use_typescript>` | `true` or `false` |
-| `<docs_location>` | Absolute path for repositories |
+**Variables to remember:**
+- `<use_typescript>`: true/false based on the answer
+- `<docs_location>`: Absolute path for repositories (must be outside current directory)
+
+**Validation:** Verify that `<docs_location>` is not within the current project directory.
+When invalid, ask again the location with valid suggestions.
 
 ---
 
-## 2. Documentation Repositories Setup
+### 3. Documentation Repositories Setup
+
+**Action:** Clone the required documentation repositories
+
+**Commands to execute:**
 
 ```bash
+mkdir -p <docs_location>
 cd <docs_location>
 git clone https://github.com/Ealab-collab/reactive-json.git
 git clone https://github.com/Ealab-collab/reactive-json-docs.git
 ```
 
-> These repositories are used **only** for Cursor to index the documentation and will **not** be included in the final project.
+**Important:** Explain to the user that these repositories are **only** for Cursor to index the documentation and will **not** be included in the final project.
 
-If repositories are already cloned, proceed directly to step 3.
+**Note:** If the user indicates that the repositories are already cloned, proceed directly to step 4 (Cursor Workspace Configuration) as it is essential to add the folders to the workspace even if they already exist.
 
 ---
 
-## 3. Cursor Workspace Configuration
+### 4. Cursor Workspace Configuration
 
-**Manual action required!**
+**Action:** Ask the user to add repositories to the workspace
 
-1. Open `File > Add Folder to Workspace`
-2. Add `<docs_location>/reactive-json`
-3. Add `<docs_location>/reactive-json-docs`
+**Instructions to give to the user:**
 
-Make sure these folders appear in the explorer before continuing.
+> **IMPORTANT: Manual Action Required**
+> 
+> Before continuing, you must add the cloned repositories to your Cursor workspace:
+> 
+> 1. Go to `File > Add Folder to Workspace`
+> 2. Add the folder `<docs_location>/reactive-json`
+> 3. Add the folder `<docs_location>/reactive-json-docs`
+> 
+> **Confirm that this step is completed before continuing.**
 
 ---
 
-## 4. Vite Project Initialization
+### 5. Vite Project Initialization
+
+**Action:** Create the project with Vite in the current directory
+
+**Commands to execute:**
 
 ```bash
-# With TypeScript
-npm create vite@latest <project_name> -- --template react-ts
+# Return to project directory
+cd <project_dir>
+
+# If TypeScript
+npm create vite@latest . -- --template react-ts
 
-# With JavaScript
-npm create vite@latest <project_name> -- --template react
+# If JavaScript
+npm create vite@latest . -- --template react
+```
+
+---
+
+### 6. Project Structure Verification
 
-cd <project_name>
+**Action:** Verify the project structure is correct
+
+**Commands to execute:**
+
+```bash
+ls -la
 ```
 
+**Verification checklist:**
+
+1. **package.json** must be at the root of the current directory
+2. **src/** folder must be present
+3. **public/** folder must be present  
+4. **The reactive-json and reactive-json-docs repositories must NOT be in this directory** (they should only be in the workspace)
+
+**Instructions:**
+
+> **IMPORTANT: Project Structure Verification**
+> 
+> Please verify the following:
+> 
+> ✅ `package.json` is at the root of your current directory  
+> ✅ `src/` and `public/` folders are present  
+> ✅ `reactive-json/` and `reactive-json-docs/` folders are NOT in this directory  
+> 
+> If any of these conditions are not met, **STOP** and resolve the issues before continuing.
+
 ---
 
-## 5. Dependencies Installation
+### 7. Dependencies Installation
+
+**Action:** Install required packages
+
+**Commands to execute:**
 
 ```bash
 npm install
@@ -87,14 +170,21 @@ npm install @ea-lab/reactive-json bootstrap react-bootstrap axios clsx dnd-kit-s
 
 ---
 
-## 6. Cursor Rules Creation
+### 8. Cursor Project Rules Creation
+
+**Action:** Copy Cursor rules from documentation repositories
 
-Copy rules from documentation repositories **before** any code modification:
+**IMPORTANT:** This step must be done **immediately after installing dependencies** so that Cursor applies the rules during all subsequent code modifications.
 
+**Instructions:**
+
+1. Create the `.cursor/rules/` folder in your project:
 ```bash
-# Create rules directory
 mkdir -p .cursor/rules
+```
 
+2. Copy and merge rules from documentation repositories:
+```bash
 # Copy rules from reactive-json
 cp -r <docs_location>/reactive-json/.cursor/rules/* .cursor/rules/
 
@@ -110,21 +200,25 @@ These rules contain all the necessary directives to work effectively with reacti
 
 ---
 
-## 7. Generated Project Cleanup
+### 9. Generated Project Cleanup
 
-Remove unnecessary files:
+**Action:** Remove/clean files generated by Vite
 
+**Files to delete:**
 - `src/App.css`
 - `src/index.css` (keep only base styles)
 - `public/vite.svg`
 - `src/assets/react.svg`
 
-Modify `src/main.tsx` (or `src/main.jsx`):
+**Files to modify:**
+
+**`src/main.tsx` (or `src/main.jsx`):**
 
-```typescript
+```javascript
 import React from 'react'
 import ReactDOM from 'react-dom/client'
 import App from './App.tsx'
+// Import Bootstrap styles for reactive-json
 import 'bootstrap/dist/css/bootstrap.min.css'
 
 ReactDOM.createRoot(document.getElementById('root')!).render(
@@ -136,22 +230,26 @@ ReactDOM.createRoot(document.getElementById('root')!).render(
 
 ---
 
-## 8. Basic Configuration with ReactiveJsonRoot
+### 10. Basic Configuration with ReactiveJsonRoot
+
+**Action:** Configure the base component with an external YAML file
+
+**IMPORTANT:** Always use an external YAML file for configuration. Never pass configuration directly in props.
 
-`src/App.tsx`:
+**`src/App.tsx` (or `src/App.jsx`):**
 
-```typescript
+```javascript
 import { ReactiveJsonRoot } from '@ea-lab/reactive-json'
 import 'bootstrap/dist/css/bootstrap.min.css'
 
 function App() {
-  return <ReactiveJsonRoot dataUrl="/config.yaml" dataFetchMethod="GET" />
+  return <ReactiveJsonRoot rjBuildUrl="/config.yaml" rjBuildFetchMethod="GET" />
 }
 
 export default App
 ```
 
-`public/config.yaml`:
+**`public/config.yaml`:**
 
 ```yaml
 renderView:
@@ -161,10 +259,142 @@ renderView:
 
 ---
 
-## 9. Final Verification
+### 11. Routing Configuration (Optional)
+
+**Action:** Ask the user if they want to add routing for application organization
+
+**Question to ask:**
+
+> **Optional: React Router Setup**
+> 
+> Do you want to add React Router (react-router-dom) to organize your application with multiple pages/routes?
+> 
+> This is useful if you plan to create a multi-page application.
+> 
+> **Answer: Yes/No**
+
+**If YES, execute the following:**
+
+**Install react-router-dom:**
+```bash
+npm install react-router-dom
+# If TypeScript
+npm install --save-dev @types/react-router-dom
+```
+
+**Create routing structure:**
+
+**`src/components/Navigation.tsx` (or `.jsx`):**
+```javascript
+import { Link, useLocation } from 'react-router-dom'
+
+export default function Navigation() {
+  const location = useLocation()
+  
+  const navItems = [
+    { path: '/', label: 'Home' },
+    // Add or remove items here according to your needs
+  ]
+
+  return (
+    <nav className="navbar navbar-expand-lg navbar-light bg-light mb-4">
+      <div className="container">
+        <Link className="navbar-brand" to="/">
+          My App
+        </Link>
+        
+        <div className="navbar-nav">
+          {navItems.map((item) => (
+            <Link
+              key={item.path}
+              className={`nav-link ${location.pathname === item.path ? 'active' : ''}`}
+              to={item.path}
+            >
+              {item.label}
+            </Link>
+          ))}
+        </div>
+      </div>
+    </nav>
+  )
+}
+```
+
+**`src/config/routes.ts` (or `.js`):**
+```javascript
+export const routeMapping = [
+  { path: '/', rjbuild: '/pages/home.yaml' },
+  // Add or remove routes here according to your needs
+  // Example: { path: '/about', rjbuild: '/pages/about.yaml' }
+]
+```
+
+**Update `src/App.tsx` (or `.jsx`):**
+```javascript
+import { BrowserRouter as Router, Routes, Route } from 'react-router-dom'
+import { ReactiveJsonRoot } from '@ea-lab/reactive-json'
+import { routeMapping } from './config/routes'
+import Navigation from './components/Navigation'
+import 'bootstrap/dist/css/bootstrap.min.css'
+
+function App() {
+  return (
+    <Router>
+      <div>
+        <Navigation />
+        <div className="container">
+          <Routes>
+            {routeMapping.map((route) => (
+              <Route
+                key={route.path}
+                path={route.path}
+                element={
+                  <ReactiveJsonRoot
+                    rjBuildUrl={route.rjbuild}
+                    rjBuildFetchMethod="GET"
+                  />
+                }
+              />
+            ))}
+          </Routes>
+        </div>
+      </div>
+    </Router>
+  )
+}
+
+export default App
+```
+
+**Create page configuration:**
+```bash
+mkdir -p public/pages
+mkdir -p src/config
+```
+
+**`public/pages/home.yaml`:**
+```yaml
+renderView:
+  - type: h1
+    content: "Welcome to your React + Reactive-JSON app!"
+  - type: p
+    content: "Your routing is now configured with a navigation bar. You can add more pages in src/pages/ and routes in the App component."
+```
+
+**If NO, keep the simple configuration from step 10.**
+
+---
+
+### 12. Final Verification
+
+**Action:** Launch development server
 
 ```bash
 npm run dev
 ```
 
-If the "Ready to start!" message appears without errors, the installation is complete! You can start developing your application with Reactive-JSON. 
+If the server starts without errors and you see the expected message in your browser, the installation is successful. You can start developing your application with reactive-json.
+
+**Expected results:**
+- **Without routing:** "Ready to start!" message
+- **With routing:** "Welcome to your React + Reactive-JSON app!" message with a navigation bar at the top of the page allowing navigation between pages