@stonecrop/stonecrop 0.10.16 → 0.11.1

package/dist/stores/hst.js

@@ -77,17 +77,15 @@ class HST {
 // Enhanced HST Proxy with tree navigation
 class HSTProxy {
     target;
-    parentPath;
+    ancestorPath;
     rootNode;
     doctype;
-    parentDoctype;
     hst;
-    constructor(target, doctype, parentPath = '', rootNode = null, parentDoctype) {
+    constructor(target, doctype, ancestorPath = '', rootNode = null) {
         this.target = target;
-        this.parentPath = parentPath;
+        this.ancestorPath = ancestorPath;
         this.rootNode = rootNode || this;
         this.doctype = doctype;
-        this.parentDoctype = parentDoctype;
         this.hst = HST.getInstance();
         return new Proxy(this, {
             get(hst, prop) {
@@ -121,14 +119,19 @@ class HSTProxy {
         }
         // Always wrap in HSTProxy for tree navigation
         if (typeof value === 'object' && value !== null && !this.isPrimitive(value)) {
-            return new HSTProxy(value, nodeDoctype, fullPath, this.rootNode, this.parentDoctype);
+            return new HSTProxy(value, nodeDoctype, fullPath, this.rootNode);
         }
         // For primitives, return a minimal wrapper that throws on tree operations
-        return new HSTProxy(value, nodeDoctype, fullPath, this.rootNode, this.parentDoctype);
+        return new HSTProxy(value, nodeDoctype, fullPath, this.rootNode);
     }
     set(path, value, source = 'user') {
         // Get current value for change context
         const fullPath = this.resolvePath(path);
+        if (fullPath === undefined) {
+            // eslint-disable-next-line no-console
+            console.warn('HST.set: resolved path is undefined, skipping operation');
+            return;
+        }
         const beforeValue = this.has(path) ? this.get(path) : undefined;
         // Log operation if not from undo/redo and store is available
         if (source !== 'undo' && source !== 'redo') {
@@ -194,28 +197,28 @@ class HSTProxy {
         }
     }
     // Tree navigation methods
-    getParent() {
-        if (!this.parentPath)
+    getAncestor() {
+        if (!this.ancestorPath)
             return null;
-        const parentSegments = this.parentPath.split('.').slice(0, -1);
-        const parentPath = parentSegments.join('.');
-        if (parentPath === '') {
+        const ancestorSegments = this.ancestorPath.split('.').slice(0, -1);
+        const ancestorPath = ancestorSegments.join('.');
+        if (ancestorPath === '') {
             return this.rootNode;
         }
         // Return a wrapped node, not raw data
-        return this.rootNode.getNode(parentPath);
+        return this.rootNode.getNode(ancestorPath);
     }
     getRoot() {
         return this.rootNode;
     }
     getPath() {
-        return this.parentPath;
+        return this.ancestorPath;
     }
     getDepth() {
-        return this.parentPath ? this.parentPath.split('.').length : 0;
+        return this.ancestorPath ? this.ancestorPath.split('.').length : 0;
     }
     getBreadcrumbs() {
-        return this.parentPath ? this.parentPath.split('.') : [];
+        return this.ancestorPath ? this.ancestorPath.split('.') : [];
     }
     /**
      * Trigger an XState transition with optional context data
@@ -223,7 +226,7 @@ class HSTProxy {
     async triggerTransition(transition, context) {
         const triggerEngine = getGlobalTriggerEngine();
         // Determine doctype and recordId from the current path
-        const pathSegments = this.parentPath.split('.');
+        const pathSegments = this.ancestorPath.split('.');
         let doctype = this.doctype;
         let recordId;
         // If we're at the root level and this is a StonecropStore, use the first path segment as the doctype
@@ -236,7 +239,7 @@ class HSTProxy {
         }
         // Build transition context
         const transitionContext = {
-            path: this.parentPath,
+            path: this.ancestorPath,
             fieldname: '', // No specific field for transitions
             beforeValue: undefined,
             afterValue: undefined,
@@ -255,7 +258,7 @@ class HSTProxy {
         if (logStore && typeof logStore.addOperation === 'function') {
             logStore.addOperation({
                 type: 'transition',
-                path: this.parentPath,
+                path: this.ancestorPath,
                 fieldname: transition,
                 beforeValue: context?.currentState,
                 afterValue: context?.targetState,
@@ -276,8 +279,8 @@ class HSTProxy {
     // Private helper methods
     resolvePath(path) {
         if (path === '')
-            return this.parentPath;
-        return this.parentPath ? `${this.parentPath}.${path}` : path;
+            return this.ancestorPath ?? '';
+        return this.ancestorPath ? `${this.ancestorPath}.${path}` : path;
     }
     resolveValue(path) {
         // Handle empty path - return the target object
@@ -302,7 +305,7 @@ class HSTProxy {
         const segments = this.parsePath(path);
         const lastSegment = segments.pop();
         let current = this.target;
-        // Navigate to parent object
+        // Navigate to ancestor object
         for (const segment of segments) {
             current = this.getProperty(current, segment);
             if (current === null || current === undefined) {
@@ -482,13 +485,12 @@ class HSTProxy {
  *
  * @param target - The target object to wrap with HST functionality
  * @param doctype - The document type identifier
- * @param parentDoctype - Optional parent document type identifier
  * @returns A new HSTNode proxy instance
  *
  * @public
  */
-function createHST(target, doctype, parentDoctype) {
-    return new HSTProxy(target, doctype, '', null, parentDoctype);
+function createHST(target, doctype) {
+    return new HSTProxy(target, doctype, '', null);
 }
 // Export everything
 export { HSTProxy, HST, createHST };

package/dist/stores/operation-log.js

@@ -75,8 +75,7 @@ export const useOperationLogStore = defineStore('hst-operation-log', () => {
     const currentIndex = ref(-1); // Points to the last applied operation
     const clientId = ref(generateId());
     const batchMode = ref(false);
-    const currentBatch = ref([]);
-    const currentBatchId = ref(null);
+    const batchStack = ref([]);
     // Computed
     const canUndo = computed(() => {
         // Can undo if there are operations and we're not at the beginning
@@ -141,9 +140,9 @@ export const useOperationLogStore = defineStore('hst-operation-log', () => {
         if (config.value.operationFilter && !config.value.operationFilter(fullOperation)) {
             return fullOperation.id;
         }
-        // If in batch mode, collect operations
-        if (batchMode.value) {
-            currentBatch.value.push(fullOperation);
+        // If in batch mode, collect operations in current batch
+        if (batchMode.value && batchStack.value.length > 0) {
+            batchStack.value[batchStack.value.length - 1].operations.push(fullOperation);
             return fullOperation.id;
         }
         // Remove any operations after current index (they become invalid after new operation)
@@ -170,22 +169,30 @@ export const useOperationLogStore = defineStore('hst-operation-log', () => {
      */
     function startBatch() {
         batchMode.value = true;
-        currentBatch.value = [];
-        currentBatchId.value = generateId();
+        batchStack.value.push({
+            id: generateId(),
+            operations: [],
+        });
     }
     /**
      * Commit batch - create a single batch operation
      */
     function commitBatch(description) {
-        if (!batchMode.value || currentBatch.value.length === 0) {
-            batchMode.value = false;
-            currentBatch.value = [];
-            currentBatchId.value = null;
+        if (!batchMode.value || batchStack.value.length === 0) {
+            return null;
+        }
+        const currentBatchData = batchStack.value.pop();
+        const batchOperations = currentBatchData.operations;
+        if (batchOperations.length === 0) {
+            // Empty batch - just pop and continue if there are outer batches
+            if (batchStack.value.length === 0) {
+                batchMode.value = false;
+            }
             return null;
         }
-        const batchId = currentBatchId.value;
-        const allReversible = currentBatch.value.every(op => op.reversible);
-        // Create parent batch operation
+        const batchId = currentBatchData.id;
+        const allReversible = batchOperations.every(op => op.reversible);
+        // Create ancestor batch operation
         const batchOperation = {
             id: batchId,
             type: 'batch',
@@ -193,39 +200,44 @@ export const useOperationLogStore = defineStore('hst-operation-log', () => {
             fieldname: '',
             beforeValue: null,
             afterValue: null,
-            doctype: currentBatch.value[0]?.doctype || '',
+            doctype: batchOperations[0]?.doctype || '',
             timestamp: new Date(),
             source: 'user',
             reversible: allReversible,
             irreversibleReason: allReversible ? undefined : 'Contains irreversible operations',
-            childOperationIds: currentBatch.value.map(op => op.id),
+            descendantOperationIds: batchOperations.map(op => op.id),
             metadata: { description },
         };
-        // Add parent operation ID to all children
-        currentBatch.value.forEach(op => {
-            op.parentOperationId = batchId;
+        // Add ancestor operation ID to all descendants
+        batchOperations.forEach(op => {
+            op.ancestorOperationId = batchId;
         });
-        // Add all operations to the log
-        operations.value.push(...currentBatch.value, batchOperation);
-        currentIndex.value = operations.value.length - 1;
+        // If we're inside a ancestor batch, add this batch as a descendant of the ancestor
+        if (batchStack.value.length > 0) {
+            // Nested batch - add the batch operation to the ancestor batch
+            batchStack.value[batchStack.value.length - 1].operations.push(batchOperation);
+        }
+        else {
+            // Top-level batch - add to the operations log
+            operations.value.push(...batchOperations, batchOperation);
+            currentIndex.value = operations.value.length - 1;
+        }
         // Broadcast batch
         if (config.value.enableCrossTabSync) {
-            broadcastBatch(currentBatch.value, batchOperation);
+            broadcastBatch(batchOperations, batchOperation);
         }
-        // Reset batch state
-        const result = batchId;
-        batchMode.value = false;
-        currentBatch.value = [];
-        currentBatchId.value = null;
-        return result;
+        // If no more batches on stack, exit batch mode
+        if (batchStack.value.length === 0) {
+            batchMode.value = false;
+        }
+        return batchId;
     }
     /**
      * Cancel batch mode without committing
      */
     function cancelBatch() {
+        batchStack.value = [];
         batchMode.value = false;
-        currentBatch.value = [];
-        currentBatchId.value = null;
     }
     /**
      * Undo the last operation
@@ -244,13 +256,13 @@ export const useOperationLogStore = defineStore('hst-operation-log', () => {
         }
         try {
             // Handle batch operations
-            if (operation.type === 'batch' && operation.childOperationIds) {
-                // Undo all child operations in reverse order
-                for (let i = operation.childOperationIds.length - 1; i >= 0; i--) {
-                    const childId = operation.childOperationIds[i];
-                    const childOp = operations.value.find(op => op.id === childId);
-                    if (childOp) {
-                        revertOperation(childOp, store);
+            if (operation.type === 'batch' && operation.descendantOperationIds) {
+                // Undo all descendant operations in reverse order
+                for (let i = operation.descendantOperationIds.length - 1; i >= 0; i--) {
+                    const descendantId = operation.descendantOperationIds[i];
+                    const descendantOp = operations.value.find(op => op.id === descendantId);
+                    if (descendantOp) {
+                        revertOperation(descendantOp, store);
                     }
                 }
             }
@@ -283,12 +295,12 @@ export const useOperationLogStore = defineStore('hst-operation-log', () => {
         const operation = operations.value[currentIndex.value + 1];
         try {
             // Handle batch operations
-            if (operation.type === 'batch' && operation.childOperationIds) {
-                // Redo all child operations in order
-                for (const childId of operation.childOperationIds) {
-                    const childOp = operations.value.find(op => op.id === childId);
-                    if (childOp) {
-                        applyOperation(childOp, store);
+            if (operation.type === 'batch' && operation.descendantOperationIds) {
+                // Redo all descendant operations in order
+                for (const descendantId of operation.descendantOperationIds) {
+                    const descendantOp = operations.value.find(op => op.id === descendantId);
+                    if (descendantOp) {
+                        applyOperation(descendantOp, store);
                     }
                 }
             }
@@ -440,12 +452,12 @@ export const useOperationLogStore = defineStore('hst-operation-log', () => {
         };
         broadcastChannel.postMessage(serializeForBroadcast(message));
     }
-    function broadcastBatch(childOps, batchOp) {
+    function broadcastBatch(descendantOps, batchOp) {
         if (!broadcastChannel)
             return;
         const message = {
             type: 'operation',
-            operations: [...childOps, batchOp],
+            operations: [...descendantOps, batchOp],
             clientId: clientId.value,
             timestamp: new Date(),
         };
@@ -473,7 +485,7 @@ export const useOperationLogStore = defineStore('hst-operation-log', () => {
         };
         broadcastChannel.postMessage(serializeForBroadcast(message));
     }
-    const persistedData = useLocalStorage('stonecrop-ops-operations', null, {
+    const persistedData = useLocalStorage('stonecrop-operations', null, {
         serializer: {
             read: (v) => {
                 try {

package/dist/types/index.js

@@ -2,6 +2,7 @@
 export * from './composable';
 export * from './doctype';
 export * from './field-triggers';
+export * from './hst';
 export * from './operation-log';
 export * from './plugin';
 export * from './registry';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonecrop/stonecrop",
-  "version": "0.10.16",
+  "version": "0.11.1",
   "license": "MIT",
   "type": "module",
   "author": {
@@ -34,7 +34,7 @@
     "pinia-shared-state": "^1.0.1",
     "pinia-xstate": "^3.0.0",
     "xstate": "^5.25.0",
-    "@stonecrop/schema": "0.10.16"
+    "@stonecrop/schema": "0.11.1"
   },
   "peerDependencies": {
     "pinia": "^3.0.4",
@@ -60,9 +60,9 @@
     "vue-router": "^5.0.2",
     "vite": "^7.3.1",
     "vitest": "^4.0.18",
-    "stonecrop-rig": "0.7.0",
-    "@stonecrop/atable": "0.10.16",
-    "@stonecrop/aform": "0.10.16"
+    "@stonecrop/aform": "0.11.1",
+    "@stonecrop/atable": "0.11.1",
+    "stonecrop-rig": "0.7.0"
   },
   "description": "Schema-driven framework with XState workflows and HST state management",
   "publishConfig": {

package/src/composables/lazy-link.ts

@@ -0,0 +1,146 @@
+import type { FetchStrategy, CustomFetch } from '@stonecrop/schema'
+import { computed, inject, ref } from 'vue'
+
+import Doctype from '../doctype'
+import { Stonecrop } from '../stonecrop'
+import type { LazyLink } from '../types/composable'
+
+/**
+ * Get the lazy link state for a specific link field on a doctype record.
+ *
+ * This composable provides reactive state for lazy-loaded links:
+ * - `loading`: true while fetching
+ * - `loaded`: true after successful fetch (permanent until reload)
+ * - `error`: error state if any
+ * - `reload()`: explicitly trigger a fetch
+ * - `data`: computed from HST, or undefined if not loaded
+ *
+ * The reload() function respects the link's fetch strategy:
+ * - `sync`: fetches via GraphQL query through fetchNestedData
+ * - `lazy`: fetches via GraphQL query through fetchNestedData
+ * - `custom`: invokes the serialized handler function directly
+ *
+ * @param doctype - The doctype instance
+ * @param recordId - The record ID
+ * @param linkFieldname - The link fieldname to load
+ * @returns LazyLink with loading, loaded, error, reload, and data
+ * @public
+ */
+export function useLazyLink(doctype: Doctype, recordId: string, linkFieldname: string): LazyLink {
+	const stonecropInstance = inject<Stonecrop>('$stonecrop') || Stonecrop._root
+
+	if (!stonecropInstance) {
+		throw new Error('Stonecrop instance not available. Ensure useStonecrop() has been called first.')
+	}
+
+	const loading = ref(false)
+	const loaded = ref(false)
+	const error = ref<Error | null>(null)
+
+	const hstStore = stonecropInstance.getStore()
+
+	/**
+	 * Build the HST path for a lazy link field
+	 */
+	const getLinkPath = (): string => {
+		const slug = doctype.slug || doctype.doctype
+		return `${slug}.${recordId}.${linkFieldname}`
+	}
+
+	/**
+	 * Get the link declaration from the doctype schema
+	 */
+	const getLinkDeclaration = (): FetchStrategy | undefined => {
+		return doctype.links?.[linkFieldname]?.fetch
+	}
+
+	/**
+	 * Invoke a custom fetch handler
+	 * The handler is a serialized function string that we execute via new Function()
+	 */
+	const invokeCustomHandler = async (handler: CustomFetch['handler']): Promise<any> => {
+		try {
+			// Create function from serialized string and invoke it
+			// The function receives the stonecrop instance and path as parameters
+			// eslint-disable-next-line @typescript-eslint/no-implied-eval
+			const fn = new Function(
+				'stonecrop',
+				'path',
+				'hst',
+				`
+				return (${handler})(stonecrop, path, hst)
+			`
+			)
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-call
+			return await fn(stonecropInstance, getLinkPath(), hstStore)
+		} catch (err) {
+			throw new Error(`Custom handler failed: ${err instanceof Error ? err.message : String(err)}`)
+		}
+	}
+
+	/**
+	 * Fetch the link data using the appropriate strategy
+	 */
+	const fetchLinkData = async (): Promise<void> => {
+		const linkFetch = getLinkDeclaration()
+		const ancestorPath = `${doctype.slug || doctype.doctype}.${recordId}`
+
+		if (linkFetch?.method === 'custom') {
+			// Ensure ancestor path exists before invoking custom handler
+			if (!hstStore.has(ancestorPath)) {
+				hstStore.set(ancestorPath, {}, 'system')
+			}
+
+			// Custom handler - invoke directly
+			const result = await invokeCustomHandler(linkFetch.handler)
+
+			// Store result in HST at the link path
+			hstStore.set(getLinkPath(), result, 'system')
+		} else {
+			// sync or lazy (both use fetchNestedData but with different includeNested)
+			// For lazy links, we still use fetchNestedData but only for this specific link
+			await stonecropInstance.fetchNestedData(ancestorPath, doctype, recordId, { includeNested: [linkFieldname] })
+		}
+	}
+
+	/**
+	 * Explicitly reload the lazy link data
+	 */
+	const reload = async (): Promise<void> => {
+		if (loading.value) return
+
+		loading.value = true
+		error.value = null
+
+		try {
+			await fetchLinkData()
+			loaded.value = true
+		} catch (err) {
+			error.value = err instanceof Error ? err : new Error(String(err))
+			throw err
+		} finally {
+			loading.value = false
+		}
+	}
+
+	/**
+	 * Computed property that returns the loaded data from HST
+	 */
+	const data = computed(() => {
+		if (!loaded.value) return undefined
+		return hstStore.get(getLinkPath())
+	})
+
+	return {
+		// State
+		loading,
+		loaded,
+		error,
+
+		// Computed
+		data,
+
+		// Actions
+		reload,
+	}
+}

package/src/composables/operation-log.ts

@@ -2,7 +2,7 @@ import { useMagicKeys, whenever } from '@vueuse/core'
 import { storeToRefs } from 'pinia'
 import { getCurrentInstance, inject } from 'vue'
 
-import type { HSTNode } from '../stores/hst'
+import type { HSTNode } from '../types/hst'
 import { useOperationLogStore } from '../stores/operation-log'
 import type { OperationLogConfig } from '../types/operation-log'