@ea-lab/reactive-json-docs 0.1.2

package/README-npm.md

@@ -0,0 +1,49 @@
+# @ea-lab/reactive-json-docs
+
+Complete documentation for Reactive-JSON - LLM-Parsable Format
+
+## 📚 Content
+
+This package contains the complete Reactive-JSON documentation in YAML format, optimized for easy parsing by LLMs:
+
+- **Core Components**: HTML elements, actions & reactions, form elements, special components, etc.
+- **Integrations**: Chart.js components and others
+- **Examples**: Complete use cases and demos
+
+## 🚀 Installation
+
+```bash
+npm install @ea-lab/reactive-json-docs
+```
+
+## 📖 Usage
+
+### For LLM Users
+
+Tell your LLM about this package:
+
+> "I have the npm package `@ea-lab/reactive-json-docs` installed, which contains complete documentation for @ea-lab/reactive-json and plugins. The documentation is located in `node_modules/@ea-lab/reactive-json-docs/public/rjbuild/component-doc/`. Can you help me understand how to use Reactive-JSON components?"
+
+### Structure
+
+```
+component-doc/
+├── index.yaml              # Main index
+├── core/
+│   ├── action/            # Actions (Hide, Show, Redirect...)
+│   ├── element/           # UI Elements
+│   │   ├── form/         # Form fields
+│   │   ├── html/         # HTML elements
+│   │   └── special/      # Special components
+│   ├── example/          # Complete examples
+│   └── reaction/         # Reactivity system
+└── chartjs/              # Chart.js integration
+```
+
+## 🤖 LLM-Optimized
+
+- Standardized YAML format
+- Complete documentation with examples
+- Structured metadata
+- Detailed use cases
+- Cross-references

package/README.md

@@ -0,0 +1,86 @@
+# reactive-json-docs
+
+Documentation project for *[reactive-json](https://github.com/Ealab-collab/reactive-json)* (`@ea-lab/reactive-json`),
+a React-based library that transforms JSON (or YAML) into HTML markup.
+
+This project serves as the complete documentation hub for *reactive-json* and its ecosystem,
+providing structured YAML documentation files optimized for LLM parsing and developer reference.
+
+## The gist
+
+Two npm packages are available:
+
+**📚 Documentation Package** (this project):
+```bash
+npm install @ea-lab/reactive-json-docs
+```
+
+**⚛️ Main Library Package**:
+```bash
+npm install @ea-lab/reactive-json
+```
+
+The documentation package is optimized for LLMs and development tools, while the main library package is what you use in your React applications.
+
+The complete documentation repository can be found at: [reactive-json-docs](https://github.com/Ealab-collab/reactive-json-docs).
+
+You can also run the documentation website locally with `npm start` to browse the interactive documentation.
+
+## Project structure
+
+This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
+
+The usual commands can be found in the annex [README-CRA.md](README-CRA.md).
+
+> 💡 **Community contribution welcome**: We'd love to migrate this project to [Vite](https://vitejs.dev) for better performance and developer experience!
+
+The following is the specific documentation for the *reactive-json-docs* project.
+
+### Documentation directory `/public/rjbuild`
+
+This directory contains the structured documentation files for *reactive-json*.
+
+The `/public/rjbuild/component-doc` directory contains the main documentation in YAML format:
+- **Core components**: Actions, form elements, HTML elements, special components
+- **Integrations**: Chart.js and other plugin documentation  
+- **Examples**: Complete use cases and implementation demos
+- **Reactions**: Reactivity system and event handling
+
+These YAML files are the structured documentation that powers both the web interface
+and the npm package for LLM consumption.
+
+### Pages directory `/public/rjbuild/pages`
+
+Contains the website pages:
+- `home.yaml` - Website homepage
+- `docs.yaml` - Documentation browser index page
+- `home-docs/` - Styling guides for this documentation project only
+
+### Hull `/src/hull`
+
+Contains the code that powers the documentation website interface.
+
+This includes the React components that render the documentation browser,
+component demos, and interactive examples.
+
+The documentation website provides a user-friendly interface to browse
+all available reactive-json components and their usage examples.
+
+## Publishing Documentation
+
+This project can publish its documentation as an npm package. See [PUBLICATION-GUIDE.md](PUBLICATION-GUIDE.md) for details.
+
+## Development
+
+Run the documentation website locally:
+```bash
+npm start
+```
+
+Build the documentation website:
+```bash
+npm run build
+```
+
+The documentation files in `/public/rjbuild/component-doc` are the source of truth
+for all reactive-json component documentation.

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@ea-lab/reactive-json-docs",
+  "version": "0.1.2",
+  "description": "Complete documentation for Reactive-JSON - Components, examples and LLM-parsable guides",
+  "main": "public/rjbuild/component-doc/index.yaml",
+  "files": [
+    "public/rjbuild/component-doc/**/*",
+    "README-npm.md"
+  ],
+  "keywords": [
+    "reactive-json",
+    "documentation",
+    "components",
+    "yaml",
+    "llm-parsable",
+    "react",
+    "json-forms"
+  ],
+  "author": "EA-Lab",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-username/reactive-json-standalone.git"
+  },
+  "homepage": "https://github.com/your-username/reactive-json-standalone#readme",
+  "private": false,
+  "dependencies": {
+    "@craco/craco": "^7.1.0",
+    "@ea-lab/reactive-json": "^0.0.37",
+    "@ea-lab/reactive-json-chartjs": "^0.0.23",
+    "@npmcli/fs": "^4.0.0",
+    "@reduxjs/toolkit": "^2.6.1",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "bootstrap": "^5.3.5",
+    "lodash": "^4.17.21",
+    "react": "^19.1.0",
+    "react-bootstrap": "^2.10.2",
+    "react-dom": "^19.1.0",
+    "react-markdown": "^10.1.0",
+    "react-redux": "^9.2.0",
+    "react-router-dom": "^7.5.0",
+    "react-scripts": "^5.0.1",
+    "react-syntax-highlighter": "^15.6.1",
+    "redux": "^5.0.1",
+    "web-vitals": "^4.2.4"
+  },
+  "scripts": {
+    "start": "craco start",
+    "build": "craco build",
+    "test": "craco test",
+    "eject": "craco eject",
+    "publish-docs": "npm publish --access public"
+  },
+  "eslintConfig": {
+    "extends": [
+      "react-app",
+      "react-app/jest"
+    ]
+  },
+  "browser": {
+    "fs": false,
+    "path": false,
+    "os": false
+  },
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  }
+}

package/public/rjbuild/component-doc/chartjs/components.yaml

@@ -0,0 +1,252 @@
+renderView:
+  - type: h1
+    content: ChartJS components
+
+  - type: RjBuildDescriber
+    title: Bar chart
+    toDescribe:
+      renderView:
+        - type: div
+          attributes:
+            class: chart-container
+            style:
+              position: relative
+              height: 60vh
+          content:
+            - type: BarChart
+              options:
+                plugins:
+                  legend:
+                    position: bottom
+              data: ~~.barChartData
+      templates:
+      data:
+        barChartData:
+          labels:
+            - Students
+            - Teachers
+            - Employees
+          datasets:
+            - label: Private school
+              data: [ 10, 20, 3 ]
+              backgroundColor:
+                - rgb(255, 99, 132)
+                - rgb(54, 162, 235)
+                - rgb(255, 206, 86)
+              borderColor:
+                - rgba(255, 99, 132, 0.7)
+                - rgba(54, 162, 235, 0.7)
+                - rgba(255, 206, 86, 0.7)
+              borderWidth: 1
+
+  - type: RjBuildDescriber
+    title: Doughnut chart
+    toDescribe:
+      renderView:
+        - type: div
+          attributes:
+            class: chart-container
+            style:
+              position: relative
+              height: 60vh
+          content:
+            - type: DoughnutChart
+              options:
+                plugins:
+                  legend:
+                    position: right
+              data: ~~.doughnutChartData
+      templates:
+      data:
+        doughnutChartData:
+          labels:
+            - Male
+            - Female
+          datasets:
+            - label: Gender distribution
+              data: [ 60, 40 ]
+              backgroundColor:
+                - rgb(75, 192, 192)
+                - rgb(255, 205, 86)
+              borderColor:
+                - rgba(75, 192, 192, 0.7)
+                - rgba(255, 205, 86, 0.7)
+              borderWidth: 1
+
+  - type: RjBuildDescriber
+    title: Polar area chart
+    toDescribe:
+      renderView:
+        - type: div
+          attributes:
+            class: chart-container
+            style:
+              position: relative
+              height: 60vh
+          content:
+            - type: PolarAreaChart
+              options:
+                plugins:
+                  legend:
+                    position: right
+              data: ~~.polarAreaChartData
+      templates:
+      data:
+        polarAreaChartData:
+          labels:
+            - Red
+            - Blue
+            - Yellow
+            - Green
+          datasets:
+            - label: Colors
+              data: [ 12, 19, 10, 7 ]
+              backgroundColor:
+                - rgba(255, 99, 132, 0.6)
+                - rgba(54, 162, 235, 0.6)
+                - rgba(255, 206, 86, 0.6)
+                - rgba(75, 192, 192, 0.6)
+              borderColor:
+                - rgba(255, 99, 132, 1)
+                - rgba(54, 162, 235, 1)
+                - rgba(255, 206, 86, 1)
+                - rgba(75, 192, 192, 1)
+              borderWidth: 1
+
+  - type: RjBuildDescriber
+    title: Line chart
+    toDescribe:
+      renderView:
+        - type: div
+          attributes:
+            class: chart-container
+            style:
+              position: relative
+              height: 60vh
+          content:
+            - type: LineChart
+              options:
+                plugins:
+                  legend:
+                    position: bottom
+              data: ~~.lineChartData
+      templates:
+      data:
+        lineChartData:
+          labels:
+            - January
+            - February
+            - March
+            - April
+            - May
+          datasets:
+            - label: Sales
+              data:
+                - 30
+                - 45
+                - 28
+                - 50
+                - 75
+              backgroundColor: rgba(54, 162, 235, 0.2)
+              borderColor: rgba(54, 162, 235, 1)
+              borderWidth: 2
+
+  - type: RjBuildDescriber
+    title: Embedded line charts
+    toDescribe:
+      renderView:
+        - type: div
+          attributes:
+            class: chart-container
+            style:
+              position: relative
+              height: 60vh
+          content:
+            - type: LineChart
+              options:
+                plugins:
+                  legend:
+                    position: bottom
+                  filler:
+                    propagate: true
+                elements:
+                  line:
+                    tension: 0.4
+                    borderWidth: 2
+                  point:
+                    radius: 0
+                scales:
+                  y:
+                    stacked: true
+              data: ~~.embeddedLineChartData
+      templates:
+      data:
+        embeddedLineChartData:
+          labels: [ Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday ]
+          datasets:
+            - label: "Presence"
+              data: [ 3, 7, 5, 12, 6, 2, 1 ]
+              fill: true
+              backgroundColor: rgba(0, 255, 0, 0.4)
+              borderColor: rgba(0, 255, 0, 1)
+              borderWidth: 2
+            - label: "Absence"
+              data: [ 2, 1, 3, 2, 4, 6, 7 ]
+              fill: true
+              backgroundColor: rgba(255, 0, 0, 0.4)
+              borderColor: rgba(255, 0, 0, 1)
+              borderWidth: 2
+
+  - type: RjBuildDescriber
+    title: Filled line chart
+    toDescribe:
+      renderView:
+        - type: div
+          attributes:
+            class: chart-container
+            style:
+              position: relative
+              height: 60vh
+          content:
+            - type: LineChart
+              options:
+                plugins:
+                  legend:
+                    position: bottom
+                  filler:
+                    propagate: true
+                elements:
+                  line:
+                    tension: 0.4
+                    borderWidth: 2
+                  point:
+                    radius: 0
+              data: ~~.filledLineChartData
+      templates:
+      data:
+        filledLineChartData:
+          labels:
+            - January
+            - February
+            - March
+            - April
+            - May
+            - June
+            - July
+          datasets:
+            - label: "Revenue"
+              data: [ 5000, 7000, 6500, 8500, 9000, 3000, 2000 ]
+              fill: true
+              backgroundColor: rgba(0, 128, 255, 0.4)
+              borderColor: rgba(0, 128, 255, 1)
+              borderWidth: 2
+            - label: "Expenses"
+              data: [ 3000, 4000, 4200, 5000, 4800, 6200, 5800 ]
+              fill: true
+              backgroundColor: rgba(255, 99, 132, 0.4)
+              borderColor: rgba(255, 99, 132, 1)
+              borderWidth: 2
+
+templates:
+
+data: { }

package/public/rjbuild/component-doc/chartjs/overview.yaml

@@ -0,0 +1,51 @@
+renderView:
+  - type: h1
+    content: Chart.js integration overview
+
+  - type: Markdown
+    content: |
+      Reactive-JSON has Chart.js integration through the `@ea-lab/reactive-json-chartjs` plugin.
+      
+      The Chart.js integration adds components such as: `BarChart`, `LineChart`, `PolarAreaChart`.
+      
+      The Chart.js components use a config structure similar to the Chart.js library, so the official documentation
+      also applies here (as long the versions match).
+      
+      ## Install
+      
+      The demo website you currently look at has already this integration installed and ready.
+      
+      To enable the integration on your own project that uses Reactive-JSON, make sure
+      that the integration is installed and loaded.
+
+      Chart.js is available through the `@ea-lab/reactive-json-chartjs` plugin. To get it:
+
+      ```shell
+      npm i @ea-lab/reactive-json-chartjs
+      ```
+
+      Then make it available to ReactiveJsonRoot:
+
+      ```js
+      import {ReactiveJsonRoot} from "@ea-lab/reactive-json";
+      import {mergeComponentCollections} from "@ea-lab/reactive-json";
+      import {chartjsComponents} from "@ea-lab/reactive-json-chartjs";
+
+      export const YourComponent = () => {
+
+        const rjRootProps = {
+          // Set your own props to rjRootProps such as dataUrl.
+          // ...
+        };
+
+        // Set the plugins prop by merging the component collections.
+        // Here, we only have a single plugin, but you can add your own of course.
+        rjRootProps.plugins = mergeComponentCollections([chartjsComponents]);
+      
+        return <ReactiveJsonRoot {...rjRootProps} />;
+      }
+      ```
+
+templates:
+
+data: { }

package/public/rjbuild/component-doc/core/action/HashChangeListener.md

@@ -0,0 +1,90 @@
+# HashChangeListener
+
+**Description**: Listens to hash changes (URL fragment) in the window and executes a reaction function in response. This is an internal action component that is automatically used when you specify `on: "hashchange"` in your actions.
+
+## Usage
+
+HashChangeListener is **not** used directly as an element type. Instead, it is automatically triggered when you use `on: "hashchange"` in any action. The system automatically adds this component to listen for hash changes globally.
+
+## Properties
+
+When using `on: "hashchange"` in actions, you can specify:
+
+- `what` (required): name of the reaction function to execute (e.g., `setData`, `fetchData`, `submitData`, etc.)
+- `whenHashIs` (optional): hash value that should trigger the reaction (includes the '#' character)
+- `whenHashWas` (optional): previous hash value that should trigger the reaction (includes the '#' character)
+- All other properties are passed as arguments to the reaction function
+
+## Behavior
+
+When you use `on: "hashchange"` in an action:
+
+1. The system automatically adds a HashChangeListener component
+2. It listens to hash changes via the global event system (`EventDispatcherContext`)
+3. When a hash change occurs:
+   - If `whenHashIs` is defined, checks if the new hash matches
+   - If `whenHashWas` is defined, checks if the old hash matches
+   - If conditions are met, executes the reaction function specified in `what`
+
+## Examples
+
+### React to specific hash
+```yaml
+renderView:
+  - type: button
+    content: "Click me"
+    actions:
+      - what: setData
+        on: hashchange
+        whenHashIs: "#section2"
+        path: "currentSection"
+        value: "section2"
+```
+
+### React to previous hash change
+```yaml
+renderView:
+  - type: div
+    content: "Page content"
+    actions:
+      - what: fetchData
+        on: hashchange
+        whenHashWas: "#home"
+        url: "/api/section-data"
+        path: "sectionData"
+```
+
+### React to any hash change
+```yaml
+renderView:
+  - type: div
+    content: "Navigation"
+    actions:
+      - what: setData
+        on: hashchange
+        path: "hashChanged"
+        value: true
+```
+
+## System Integration
+
+- **EventDispatcherContext**: Uses the global event system to optimize performance
+- **TemplateSystem**: The `whenHashIs` and `whenHashWas` values are evaluated through the template system
+- **GlobalDataContext**: Provides context for reaction execution
+- **Actions.jsx**: Automatically instantiated when `on: "hashchange"` is detected
+
+## Limitations
+
+- Only works with `on: "hashchange"` in actions (not as a standalone element)
+- Only works on hash changes (URL fragment)
+- Depends on ReactiveJSON's global event system
+- Hashes must include the '#' character (e.g., "#section1", not "section1")
+- One reaction per action definition (use multiple actions for multiple reactions)
+
+## Technical Details
+
+- Automatically instantiated by the Actions system when `on: "hashchange"` is used
+- Uses `useEffect` to subscribe/unsubscribe to events
+- Reaction functions are imported from `ReactOnEvent.jsx`
+- Optimized to avoid too many real DOM listeners through the context system
+- Automatically cleans up listeners when component unmounts