@stonecrop/nuxt 0.10.2 → 0.10.3

package/README.md

@@ -7,10 +7,10 @@ The official Nuxt module for Stonecrop - a schema-driven UI framework with event
 
 ## What is Stonecrop?
 
-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.
+Stonecrop is a **schema-driven UI framework** that generates forms, tables, and workflows from JSON schemas. You define your data structure once and Stonecrop handles UI generation, state management, and validation.
 
 **Key Benefits:**
-- **Schema-Driven**: Define data models in JSON, get full CRUD interfaces automatically
+- **Schema-Driven**: Define data models in JSON; form and table rendering follows 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
@@ -100,6 +100,27 @@ Create a JSON schema in `/doctypes/task.json`:
 
 The module picks up this file and, if `pageComponent` is configured, registers a route at the doctype's `slug` value (or `task` if no slug is set), passing the parsed schema into `route.meta`.
 
+### Wire Up Your Data Client
+
+After installing the module, add a client-side plugin to connect your data transport. The `useStonecropRegistry()` composable gives you a stable API for this — no need to reach into `globalProperties` directly:
+
+```typescript
+// app/plugins/stonecrop.client.ts
+import { StonecropClient } from '@stonecrop/graphql-client'
+
+export default defineNuxtPlugin(() => {
+  const client = new StonecropClient({ endpoint: '/graphql' })
+  const { setMeta, setFetchRecord, setFetchRecords } = useStonecropRegistry()
+
+  // Map the route path/segments to a doctype name, then delegate to your client
+  setMeta(({ segments }) => client.getMeta({ doctype: segments[0] }))
+  setFetchRecord((doctype, id) => client.getRecord(doctype, id))
+  setFetchRecords((doctype) => client.getRecords(doctype))
+})
+```
+
+This wires `useStonecrop()`'s automatic record loading to your GraphQL (or any other) backend. Without this step, `useStonecrop({ doctype, recordId })` falls back to a REST fetch stub that may not exist in your app.
+
 ### Use the Stonecrop Composable
 
 In your page or component:
@@ -108,19 +129,20 @@ In your page or component:
 <script setup lang="ts">
 import taskDoctype from '~/doctypes/task.json'
 
-// HST-reactive form setup
+// HST-reactive form setup — pass doctype + recordId for full integration
 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')
+// Access the hierarchical state tree directly
+const store = stonecrop.value?.getStore()
+const taskTitle = store?.get('task.task-123.title')
 </script>
 
 <template>
   <AForm
-    :schema="formData.schema"
+    :schema="taskDoctype.fields"
     :data="formData"
     @update="handleHSTChange"
   />
@@ -276,10 +298,10 @@ export default defineNuxtConfig({
 ### Plugin Registration
 
 The module auto-registers:
-- `useStonecrop()` - Main composable for HST integration
-- `useTableNavigation()` - Helper for table-to-detail navigation
+- `useStonecropRegistry()` - Composable for wiring data clients and `getMeta` after plugin install
+- `useStonecrop()` - Main composable for HST integration (from `@stonecrop/stonecrop`)
 - Pinia store configuration
-- Component auto-imports (AForm, ATable, etc.)
+- AForm and ATable component registration (from `@stonecrop/aform`)
 
 ## Why Schema-Driven?
 
@@ -299,6 +321,49 @@ The module auto-registers:
 - **Self-Documenting**: Schemas serve as data model documentation
 - **Easy Updates**: Change schema, UI updates automatically
 
+## `useStonecropRegistry()` — Configuring the Framework After Install
+
+The `@stonecrop/nuxt` runtime plugin installs `StonecropPlugin` with a router but no data transport, because data clients (GraphQL, tRPC, REST) are application-defined and cannot be serialised through `nuxt.config.ts` module options.
+
+`useStonecropRegistry()` is the documented extension point for wiring your data transport after plugin install. Call it in a client-side plugin:
+
+```typescript
+// app/plugins/stonecrop.client.ts
+export default defineNuxtPlugin(() => {
+  const { setMeta, setFetchRecord, setFetchRecords } = useStonecropRegistry()
+
+  // setMeta — resolves doctype metadata from the current route
+  // The context has { path, segments } from the router; adapt to your API.
+  setMeta(async ({ segments }) => {
+    // Example: segments[0] is the doctype slug, e.g. "task" from /task/123
+    const doctype = segments[0]
+    const meta = await $fetch(`/api/doctypes/${doctype}`)
+    return meta
+  })
+
+  // setFetchRecord — replaces the default REST stub in useStonecrop({ recordId })
+  setFetchRecord(async (doctype, id) => {
+    return await $fetch(`/api/${doctype.slug}/${id}`)
+  })
+
+  // setFetchRecords — replaces the default REST stub for list loading
+  setFetchRecords(async (doctype) => {
+    return await $fetch(`/api/${doctype.slug}`)
+  })
+})
+```
+
+**Why a composable and not module options?** Nuxt module options are serialised at build time — functions cannot be passed through `nuxt.config.ts`. `useStonecropRegistry()` is the composable equivalent of `usePinia()` or `useNuxtApp()`: a stable, typed API for configuring the framework singleton after it has been installed.
+
+### API
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `setMeta` | `(fn: (ctx) => DoctypeMeta \| Promise<DoctypeMeta>) => void` | Sets the `getMeta` function on the Registry. Called by `useStonecrop()` to lazy-load doctype metadata for the current route. `ctx` = `{ path, segments }`. |
+| `setFetchRecord` | `(fn: (doctype, id) => Promise<Record \| null>) => void` | Replaces the default REST fetch stub in `Stonecrop.getRecord()`. Enables GraphQL-backed or any other custom transport. |
+| `setFetchRecords` | `(fn: (doctype) => Promise<Record[]>) => void` | Replaces the default REST fetch stub in `Stonecrop.getRecords()`. |
+| `registry` | `Registry` | The raw Registry instance, for advanced use cases. |
+
 ## Advanced Features
 
 ### Hierarchical State Tree (HST)

package/dist/module.json

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

package/dist/module.mjs

@@ -1,7 +1,7 @@
 import { existsSync, realpathSync } from 'node:fs';
 import { readdir, readFile } from 'node:fs/promises';
 import { dirname, extname } from 'node:path';
-import { createResolver, defineNuxtModule, useLogger, addVitePlugin, addLayout, extendPages, addServerHandler, addPlugin } from '@nuxt/kit';
+import { createResolver, defineNuxtModule, useLogger, addVitePlugin, addLayout, extendPages, addServerHandler, addPlugin, addImportsDir } from '@nuxt/kit';
 
 function createSymlinkedPackagesPlugin(options) {
   const { rootDir, packages, logger } = options;
@@ -96,8 +96,7 @@ const module$1 = defineNuxtModule({
       });
       addVitePlugin(symlinkedPackagesPlugin);
     }
-    const layoutsDir = resolve("runtime/layouts");
-    const homepage = resolve(layoutsDir, "StonecropHome.vue");
+    const homepage = resolve("runtime/app/layouts/StonecropHome.vue");
     addLayout(homepage, "home");
     const appDir = nuxt.options.srcDir;
     const doctypesDir = resolve(appDir, options.doctypesDir ?? "doctypes");
@@ -186,9 +185,8 @@ const module$1 = defineNuxtModule({
     }
     if (options.docbuilder) {
       logger.log("DocBuilder enabled, adding routes and handlers");
-      const pagesDir = resolve("runtime/pages");
-      const docBuilderIndex = resolve(pagesDir, "DocBuilderIndex.vue");
-      const docBuilderDetail = resolve(pagesDir, "DocBuilderDetail.vue");
+      const docBuilderIndex = resolve("runtime/app/pages/DocBuilderIndex.vue");
+      const docBuilderDetail = resolve("runtime/app/pages/DocBuilderDetail.vue");
       extendPages((pages) => {
         pages.push({
           name: "docbuilder-index",
@@ -204,24 +202,24 @@ const module$1 = defineNuxtModule({
       });
       const handlersDir = resolve("runtime/server/api/docbuilder");
       addServerHandler({
-        route: "/api/docbuilder/doctypes",
+        route: "/api/_stonecrop/docbuilder/doctypes",
         handler: resolve(handlersDir, "doctypes.get")
       });
       addServerHandler({
-        route: "/api/docbuilder/:doctype",
+        route: "/api/_stonecrop/docbuilder/:doctype",
         handler: resolve(handlersDir, "[doctype].get")
       });
       addServerHandler({
-        route: "/api/docbuilder/validate",
+        route: "/api/_stonecrop/docbuilder/validate",
         method: "post",
         handler: resolve(handlersDir, "validate.post")
       });
       addServerHandler({
-        route: "/api/docbuilder/save",
+        route: "/api/_stonecrop/docbuilder/save",
         method: "post",
         handler: resolve(handlersDir, "save.post")
       });
-      logger.log("Added DocBuilder API handlers");
+      logger.log("Added DocBuilder API handlers at /api/_stonecrop/docbuilder/");
     }
     const pluginPath = resolve("./runtime/plugin");
     try {
@@ -230,6 +228,7 @@ const module$1 = defineNuxtModule({
       logger.error("Error adding plugin:", pluginError);
       throw new Error(`[@stonecrop/nuxt] Failed to add plugin at ${pluginPath}`);
     }
+    addImportsDir(resolve("runtime/app/composables"));
   }
 });
 

package/dist/runtime/app/composables/useStonecropRegistry.d.ts

@@ -0,0 +1,141 @@
+import type { DataClient, DoctypeMeta } from '@stonecrop/schema';
+import type { RouteContext } from '@stonecrop/stonecrop';
+/**
+ * Provides a stable, documented API for accessing and configuring the Stonecrop
+ * Registry instance after the `@stonecrop/nuxt` plugin has installed it.
+ *
+ * ## Why This Composable Exists
+ *
+ * Stonecrop's architecture separates concerns across packages:
+ * - **@stonecrop/schema**: Defines doctype schemas, `DoctypeContext`, and `DataClient` interface
+ * - **@stonecrop/stonecrop**: Core framework with `RouteContext` (path + segments) for routing
+ * - **@stonecrop/graphql-client**: Reference `DataClient` implementation using GraphQL
+ * - **@stonecrop/nuxt**: Nuxt integration that bootstraps the Registry and Stonecrop instances
+ *
+ * This composable bridges Nuxt's plugin lifecycle with Stonecrop's registry, allowing
+ * applications to inject their data client and configure metadata fetching after the
+ * framework is mounted.
+ *
+ * ## RouteContext vs DoctypeContext
+ *
+ * - **RouteContext** (`{ path, segments }`): Raw URL routing context. Used by the router
+ *   layer to identify "where we are" in the application (e.g., `/plan/123` → segments `['plan', '123']`).
+ *
+ * - **DoctypeContext** (`{ doctype, recordId? }`): Semantic doctype context. Used by the
+ *   data layer to identify "what we're working with" (e.g., `{ doctype: 'Plan', recordId: '123' }`).
+ *
+ * Your `setMeta` implementation bridges these: extract doctype/recordId from the route
+ * segments and pass `DoctypeContext` to your data client.
+ *
+ * ## Data Flow
+ *
+ * ```
+ * URL Route (/plan/123)
+ *     ↓
+ * RouteContext ({ path: '/plan/123', segments: ['plan', '123'] })
+ *     ↓
+ * getMeta (your implementation)
+ *     ↓
+ * DoctypeContext ({ doctype: 'Plan', recordId: '123' })
+ *     ↓
+ * DataClient.getMeta() → DoctypeMeta
+ * ```
+ *
+ * @example
+ * ```ts
+ * // app/plugins/stonecrop.client.ts
+ * import { StonecropClient } from '@stonecrop/graphql-client'
+ *
+ * export default defineNuxtPlugin(() => {
+ *   const client = new StonecropClient({ endpoint: '/graphql' })
+ *   const { setClient, setMeta } = useStonecropRegistry()
+ *
+ *   // Set the data client for record fetching
+ *   setClient(client)
+ *
+ *   // Bridge RouteContext → DoctypeContext for metadata fetching
+ *   setMeta(({ segments }) => {
+ *     const doctype = segments[0] // e.g. "plan" → doctype "Plan"
+ *     return client.getMeta({ doctype }) // client expects DoctypeContext
+ *   })
+ * })
+ * ```
+ *
+ * @public
+ */
+export declare function useStonecropRegistry(): {
+    /**
+     * The raw Registry instance, for advanced use cases.
+     * Prefer the typed setter methods below for normal configuration.
+     */
+    registry: {
+        getMeta?: (routeContext: RouteContext) => DoctypeMeta | Promise<DoctypeMeta>;
+    };
+    /**
+     * Set the data client on the Stonecrop instance.
+     * Required before fetching records or dispatching actions.
+     *
+     * @param client - DataClient implementation (e.g., StonecropClient from \@stonecrop/graphql-client)
+     *
+     * @throws Error if Stonecrop instance is not available
+     *
+     * @example
+     * ```ts
+     * const client = new StonecropClient({ endpoint: '/graphql' })
+     * setClient(client)
+     * ```
+     */
+    setClient(client: DataClient): void;
+    /**
+     * Get the currently configured data client.
+     * @returns The DataClient instance or undefined if not set
+     */
+    getClient(): DataClient | undefined;
+    /**
+     * Dispatch an action to the server via the configured data client.
+     * All state changes flow through this single mutation endpoint.
+     *
+     * @param doctype - Doctype reference (name and optional slug)
+     * @param action - Action name to execute (e.g., 'SUBMIT', 'APPROVE', 'save')
+     * @param args - Action arguments (typically record ID and/or form data)
+     * @returns Action result with success status, response data, and any error
+     *
+     * @example
+     * ```ts
+     * // Save a record
+     * const result = await dispatchAction(doctype, 'save', [{ id: recordId, data: formData }])
+     *
+     * // Submit for approval
+     * const result = await dispatchAction(doctype, 'SUBMIT', [recordId])
+     * ```
+     */
+    dispatchAction(doctype: {
+        name: string;
+        slug?: string;
+    }, action: string, args?: unknown[]): Promise<{
+        success: boolean;
+        data: unknown;
+        error: string | null;
+    }>;
+    /**
+     * Set the `getMeta` function on the Registry.
+     * Called by `useStonecrop()` to lazy-load doctype metadata for the current route.
+     *
+     * You must bridge `RouteContext` → `DoctypeContext`:
+     * - Extract doctype name from `segments` (e.g., `segments[0]`)
+     * - Extract record ID from `segments` if present (e.g., `segments[1]`)
+     * - Pass `DoctypeContext` to your data client
+     *
+     * @example
+     * ```ts
+     * // Map route to doctype
+     * setMeta(({ segments }) => {
+     *   const doctype = segments[0] // /plan/123 → 'plan'
+     *   return client.getMeta({ doctype }) // client expects DoctypeContext
+     * })
+     * ```
+     *
+     * @param fn - Function that receives RouteContext and returns DoctypeMeta.
+     */
+    setMeta(fn: (routeContext: RouteContext) => DoctypeMeta | Promise<DoctypeMeta>): void;
+};

package/dist/runtime/app/composables/useStonecropRegistry.js

@@ -0,0 +1,98 @@
+import { useNuxtApp } from "nuxt/app";
+export function useStonecropRegistry() {
+  const nuxtApp = useNuxtApp();
+  const registry = nuxtApp.$registry;
+  if (!registry) {
+    throw new Error(
+      "[useStonecropRegistry] The Stonecrop Registry is not available. Ensure @stonecrop/nuxt is installed and the plugin has run before calling this composable."
+    );
+  }
+  const stonecrop = nuxtApp.$stonecrop;
+  return {
+    /**
+     * The raw Registry instance, for advanced use cases.
+     * Prefer the typed setter methods below for normal configuration.
+     */
+    registry,
+    /**
+     * Set the data client on the Stonecrop instance.
+     * Required before fetching records or dispatching actions.
+     *
+     * @param client - DataClient implementation (e.g., StonecropClient from \@stonecrop/graphql-client)
+     *
+     * @throws Error if Stonecrop instance is not available
+     *
+     * @example
+     * ```ts
+     * const client = new StonecropClient({ endpoint: '/graphql' })
+     * setClient(client)
+     * ```
+     */
+    setClient(client) {
+      if (!stonecrop) {
+        throw new Error(
+          "[useStonecropRegistry] Stonecrop instance is not available. Ensure @stonecrop/nuxt is installed and the plugin has run."
+        );
+      }
+      stonecrop.setClient(client);
+    },
+    /**
+     * Get the currently configured data client.
+     * @returns The DataClient instance or undefined if not set
+     */
+    getClient() {
+      return stonecrop?.getClient();
+    },
+    /**
+     * Dispatch an action to the server via the configured data client.
+     * All state changes flow through this single mutation endpoint.
+     *
+     * @param doctype - Doctype reference (name and optional slug)
+     * @param action - Action name to execute (e.g., 'SUBMIT', 'APPROVE', 'save')
+     * @param args - Action arguments (typically record ID and/or form data)
+     * @returns Action result with success status, response data, and any error
+     *
+     * @example
+     * ```ts
+     * // Save a record
+     * const result = await dispatchAction(doctype, 'save', [{ id: recordId, data: formData }])
+     *
+     * // Submit for approval
+     * const result = await dispatchAction(doctype, 'SUBMIT', [recordId])
+     * ```
+     */
+    dispatchAction(doctype, action, args) {
+      if (!stonecrop) {
+        return Promise.reject(
+          new Error(
+            "[useStonecropRegistry] Stonecrop instance is not available. Ensure @stonecrop/nuxt is installed and the plugin has run."
+          )
+        );
+      }
+      return stonecrop.dispatchAction(doctype, action, args);
+    },
+    /**
+     * Set the `getMeta` function on the Registry.
+     * Called by `useStonecrop()` to lazy-load doctype metadata for the current route.
+     *
+     * You must bridge `RouteContext` → `DoctypeContext`:
+     * - Extract doctype name from `segments` (e.g., `segments[0]`)
+     * - Extract record ID from `segments` if present (e.g., `segments[1]`)
+     * - Pass `DoctypeContext` to your data client
+     *
+     * @example
+     * ```ts
+     * // Map route to doctype
+     * setMeta(({ segments }) => {
+     *   const doctype = segments[0] // /plan/123 → 'plan'
+     *   return client.getMeta({ doctype }) // client expects DoctypeContext
+     * })
+     * ```
+     *
+     * @param fn - Function that receives RouteContext and returns DoctypeMeta.
+     */
+    setMeta(fn) {
+      registry.getMeta = fn;
+    }
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonecrop/nuxt",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "description": "Nuxt module for Stonecrop",
   "license": "MIT",
   "type": "module",
@@ -44,14 +44,14 @@
     "jiti": "^2.4.2",
     "pathe": "^2.0.3",
     "prompts": "^2.4.2",
-    "@stonecrop/aform": "0.10.2",
-    "@stonecrop/casl-middleware": "0.10.2",
-    "@stonecrop/graphql-middleware": "0.10.2",
-    "@stonecrop/nuxt-grafserv": "0.10.2",
-    "@stonecrop/node-editor": "0.10.2",
-    "@stonecrop/stonecrop": "0.10.2",
-    "@stonecrop/schema": "0.10.2",
-    "@stonecrop/atable": "0.10.2"
+    "@stonecrop/aform": "0.10.3",
+    "@stonecrop/atable": "0.10.3",
+    "@stonecrop/casl-middleware": "0.10.3",
+    "@stonecrop/node-editor": "0.10.3",
+    "@stonecrop/graphql-middleware": "0.10.3",
+    "@stonecrop/nuxt-grafserv": "0.10.3",
+    "@stonecrop/schema": "0.10.3",
+    "@stonecrop/stonecrop": "0.10.3"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",