@stonecrop/nuxt 0.6.0 → 0.6.2

package/README.md

@@ -3,57 +3,299 @@
 [![npm version][npm-version-src]][npm-version-href]
 [![npm downloads][npm-downloads-src]][npm-downloads-href]
 
-Nuxt module for Stonecrop.
+The official Nuxt module for Stonecrop - a schema-driven UI framework with event-driven workflows and hierarchical state management.
 
-## Features
+## What is Stonecrop?
 
-<!-- Highlight some of the features your module provide here -->
-- ⛰ &nbsp;Foo
-- 🚠 &nbsp;Bar
-- 🌲 &nbsp;Baz
+Stonecrop is a **schema-driven UI framework** that generates forms, tables, and workflows from JSON schemas. Instead of manually creating CRUD interfaces for every data model, you define your data structure once and Stonecrop handles the UI generation, state management, and validation automatically.
+
+**Key Benefits:**
+- **Schema-Driven**: Define data models in JSON, get full CRUD interfaces automatically
+- **HST State Management**: Hierarchical State Tree for complex, nested application state
+- **FSM Workflows**: XState-powered finite state machines for predictable business logic
+- **Nuxt Native**: First-class integration with Nuxt 4's architecture
+- **Live Validation**: Real-time form validation based on schema rules
+- **Excel-like Tables**: Rich table component with keyboard navigation and inline editing
+
+## Module Features
+
+- **Automatic Page Generation**: Creates routes from DocType schemas in your `/doctypes` folder
+- **Form & Table Components**: Pre-configured AForm and ATable components with HST integration
+- **Plugin System**: Auto-registers Stonecrop composables and utilities
+- **Theme Support**: Import and customize Stonecrop themes
+- **TypeScript First**: Full type safety and IntelliSense support
+- **Zero Config**: Works out of the box with sensible defaults
 
 ## Quick Setup
 
-Install the module to your Nuxt application with one command:
+Install the module to your Nuxt application:
 
 ```bash
 npx nuxi module add @stonecrop/nuxt
 ```
 
-That's it! You can now use Nuxt Stonecrop in your Nuxt app ✨
+That's it! You can now use Stonecrop in your Nuxt app.
 
+## Basic Usage
 
-## Contribution
+### Define a DocType Schema
+
+Create a JSON schema in `/doctypes/task.json`:
+
+```json
+{
+  "name": "task",
+  "label": "Task",
+  "schema": [
+    {
+      "fieldname": "title",
+      "label": "Title",
+      "fieldtype": "Data",
+      "required": true
+    },
+    {
+      "fieldname": "description",
+      "label": "Description",
+      "fieldtype": "Text"
+    },
+    {
+      "fieldname": "completed",
+      "label": "Completed",
+      "fieldtype": "Check"
+    }
+  ]
+}
+```
+
+The module automatically generates routes at `/task` for this DocType.
+
+### Use the Stonecrop Composable
+
+In your page or component:
+
+```vue
+<script setup lang="ts">
+import taskDoctype from '~/doctypes/task.json'
+
+// HST-reactive form setup
+const { stonecrop, provideHSTPath, handleHSTChange, formData } = useStonecrop({
+  doctype: taskDoctype,
+  recordId: 'task-123' // or undefined for new records
+})
+
+// Access the hierarchical state tree
+const taskTitle = stonecrop.getStore().get('task.task-123.title')
+</script>
+
+<template>
+  <AForm
+    :schema="formData.schema"
+    :data="formData"
+    @update="handleHSTChange"
+  />
+</template>
+```
+
+### Understanding Schema-Driven Development
+
+**Traditional Approach:**
+```vue
+<!-- Manual form creation -->
+<template>
+  <form>
+    <input v-model="task.title" required />
+    <textarea v-model="task.description" />
+    <input type="checkbox" v-model="task.completed" />
+    <button @click="validate">Save</button>
+  </form>
+</template>
+
+<script setup>
+// Manual validation logic
+const validate = () => {
+  if (!task.title) {
+    errors.title = 'Required'
+  }
+  // ... more validation
+}
+</script>
+```
+
+**Stonecrop Approach:**
+```vue
+<!-- Schema generates form automatically -->
+<template>
+  <AForm :schema="taskSchema" :data="formData" />
+</template>
+
+<script setup>
+// Validation is automatic from schema
+const { formData } = useStonecrop({
+  doctype: taskDoctype,
+  recordId: taskId
+})
+</script>
+```
+
+The schema defines:
+- Field types (text input, checkbox, select, etc.)
+- Validation rules (required, patterns, min/max)
+- Labels and help text
+- Relationships between data models
+
+## Configuration
+
+Add options to your `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ['@stonecrop/nuxt'],
+
+  stonecrop: {
+    // Enable DocBuilder for visual schema editing
+    docbuilder: true,
+
+    // Custom router configuration
+    router: {
+      // Router options
+    }
+  },
+
+  // Import Stonecrop theme
+  css: [
+    '@stonecrop/themes/default/default.css',
+    // or your custom theme
+  ]
+})
+```
 
-<details>
-  <summary>Local development</summary>
+## Module Behavior
 
-  ```bash
-  # Install dependencies
-  npm install
+### Automatic Page Generation
 
-  # Generate type stubs
-  npm run dev:prepare
+The module scans your `/doctypes` folder and creates routes automatically:
 
-  # Develop with the playground
-  npm run dev
+```
+doctypes/
+  ├── task.json       → /task
+  ├── user.json       → /user
+  └── project.json    → /project
+```
+
+Each route uses the `StonecropPage.vue` layout that provides:
+- List view with ATable component
+- Detail view with AForm component
+- HST state management
+- Router integration for navigation
+
+### Plugin Registration
+
+The module auto-registers:
+- `useStonecrop()` - Main composable for HST integration
+- `useTableNavigation()` - Helper for table-to-detail navigation
+- Pinia store configuration
+- Component auto-imports (AForm, ATable, etc.)
+
+## Why Schema-Driven?
+
+**Problem:** Building CRUD applications is repetitive. Every data model needs:
+- Forms for creating/editing
+- Tables for listing
+- Validation logic
+- State management
+- API integration
+
+**Solution:** Define the structure once, generate everything automatically.
+
+**Benefits:**
+- **Faster Development**: Write less boilerplate code
+- **Consistency**: All forms/tables follow the same patterns
+- **Fewer Bugs**: Validation and state management are centralized
+- **Self-Documenting**: Schemas serve as data model documentation
+- **Easy Updates**: Change schema, UI updates automatically
+
+## Advanced Features
+
+### Hierarchical State Tree (HST)
+
+HST provides path-based state addressing:
+
+```typescript
+const store = stonecrop.getStore()
+
+// Set nested values with dot notation
+store.set('project.proj-1.tasks.task-1.completed', true)
+
+// Get values anywhere in the tree
+const completed = store.get('project.proj-1.tasks.task-1.completed')
 
-  # Build the playground
-  npm run dev:build
+// Navigate the tree hierarchy
+const taskNode = store.getNode('project.proj-1.tasks.task-1')
+const parent = taskNode.getParent() // Returns project node
+const breadcrumbs = taskNode.getBreadcrumbs()
+```
+
+### XState Integration
+
+Define workflows as finite state machines:
+
+```typescript
+import { createMachine } from 'xstate'
 
-  # Run ESLint
-  npm run lint
+const taskMachine = createMachine({
+  id: 'task',
+  initial: 'draft',
+  states: {
+    draft: {
+      on: { SUBMIT: 'pending' }
+    },
+    pending: {
+      on: {
+        APPROVE: 'completed',
+        REJECT: 'draft'
+      }
+    },
+    completed: {
+      type: 'final'
+    }
+  }
+})
 
-  # Run Vitest
-  npm run test
-  npm run test:watch
+// Stonecrop persists state machine data in HST
+```
+
+## Examples
 
-  # Release new version
-  npm run release
-  ```
+Check out the [playground](./playground) for an example featuring:
+- Permission management system (RBAC)
+- DocType builder with visual state machine editor
+- Complex nested forms with relationships
+- Table views with inline editing
+- HST state visualization
 
-</details>
 
+## Contribution
+
+```bash
+# Install dependencies
+npm install
+
+# Generate type stubs
+npm run dev:prepare
+
+# Develop with the playground
+npm run dev
+
+# Build the playground
+npm run dev:build
+
+# Run ESLint
+npm run lint
+
+# Run Vitest
+npm run test
+npm run test:watch
+```
 
 <!-- Badges -->
 [npm-version-src]: https://img.shields.io/npm/v/@stonecrop/nuxt/latest.svg?style=flat&colorA=020420&colorB=00DC82

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@stonecrop/nuxt",
   "configKey": "stonecrop",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "unknown"

package/dist/module.mjs

@@ -31,15 +31,16 @@ const module = defineNuxtModule({
         extendPages(async (pages) => {
           try {
             const pagePaths = pages.map((page) => page.path);
-            if (pagePaths.includes("/")) {
-              logger.error('Conflict found: existing root page "/" detected.');
-              throw new Error("[@stonecrop/nuxt] Conflict found with existing root page");
+            if (!pagePaths.includes("/")) {
+              pages.unshift({
+                name: "stonecrop-home",
+                path: "/",
+                file: homepage
+              });
+              logger.log("Added Stonecrop home page at /");
+            } else {
+              logger.log("Skipping Stonecrop home page: root page already exists");
             }
-            pages.unshift({
-              name: "stonecrop-home",
-              path: "/",
-              file: homepage
-            });
             for (const schema of schemas) {
               try {
                 const schemaName = schema.replace(".json", "");

package/dist/runtime/plugin.js

@@ -1,6 +1,7 @@
 import { install as AForm } from "@stonecrop/aform";
 import { install as ATable } from "@stonecrop/atable";
-import { Stonecrop } from "@stonecrop/stonecrop";
+import { install as NodeEditor } from "@stonecrop/node-editor";
+import StonecropPlugin from "@stonecrop/stonecrop";
 import { createPinia } from "pinia";
 import { defineNuxtPlugin, useRouter } from "nuxt/app";
 export default defineNuxtPlugin((nuxt) => {
@@ -10,5 +11,6 @@ export default defineNuxtPlugin((nuxt) => {
   app.use(pinia);
   app.use(AForm);
   app.use(ATable);
-  app.use(Stonecrop, { router });
+  app.use(NodeEditor);
+  app.use(StonecropPlugin, { router });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonecrop/nuxt",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Nuxt module for Stonecrop",
   "license": "MIT",
   "type": "module",
@@ -33,9 +33,10 @@
   "dependencies": {
     "@nuxt/kit": "^4.2.0",
     "pinia": "^3.0.3",
-    "@stonecrop/aform": "0.6.0",
-    "@stonecrop/atable": "0.6.0",
-    "@stonecrop/stonecrop": "0.6.0"
+    "@stonecrop/aform": "0.6.2",
+    "@stonecrop/node-editor": "0.6.2",
+    "@stonecrop/atable": "0.6.2",
+    "@stonecrop/stonecrop": "0.6.2"
   },
   "devDependencies": {
     "@eslint/js": "^9.38.0",