@stonecrop/stonecrop 0.10.15 → 0.11.0

package/dist/composables/use-lazy-link-state.js

@@ -0,0 +1,125 @@
+import { computed, inject, ref } from 'vue';
+import { Stonecrop } from '../stonecrop';
+/**
+ * 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 LazyLinkState with loading, loaded, error, reload, and data
+ * @public
+ */
+export function useLazyLinkState(doctype, recordId, linkFieldname) {
+    const stonecropInstance = inject('$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(null);
+    const hstStore = stonecropInstance.getStore();
+    /**
+     * Build the HST path for a lazy link field
+     */
+    const getLinkPath = () => {
+        const slug = doctype.slug || doctype.doctype;
+        return `${slug}.${recordId}.${linkFieldname}`;
+    };
+    /**
+     * Get the link declaration from the doctype schema
+     */
+    const getLinkDeclaration = () => {
+        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) => {
+        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 () => {
+        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 () => {
+        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/dist/composables/use-stonecrop.js

@@ -0,0 +1,476 @@
+import { inject, onMounted, ref, watch, provide, computed } from 'vue';
+import { Stonecrop } from '../stonecrop';
+import { storeToRefs } from 'pinia';
+/**
+ * @public
+ */
+export function useStonecrop(options) {
+    if (!options)
+        options = {};
+    const registry = options.registry || inject('$registry');
+    const providedStonecrop = inject('$stonecrop');
+    const stonecrop = ref();
+    const hstStore = ref();
+    const formData = ref({});
+    // Use refs for router-loaded doctype to maintain reactivity
+    const routerDoctype = ref();
+    const routerRecordId = ref();
+    // Resolved schema with nested Doctype fields expanded
+    const resolvedSchema = ref([]);
+    // Auto-resolve schema when doctype is available
+    if (options.doctype && registry) {
+        const schemaArray = options.doctype.schema
+            ? Array.isArray(options.doctype.schema)
+                ? options.doctype.schema
+                : Array.from(options.doctype.schema)
+            : [];
+        resolvedSchema.value = registry.resolveSchema(schemaArray);
+    }
+    // Operation log state and methods - will be populated after stonecrop instance is created
+    const operations = ref([]);
+    const currentIndex = ref(-1);
+    const canUndo = computed(() => stonecrop.value?.getOperationLogStore().canUndo ?? false);
+    const canRedo = computed(() => stonecrop.value?.getOperationLogStore().canRedo ?? false);
+    const undoCount = computed(() => stonecrop.value?.getOperationLogStore().undoCount ?? 0);
+    const redoCount = computed(() => stonecrop.value?.getOperationLogStore().redoCount ?? 0);
+    const undoRedoState = computed(() => stonecrop.value?.getOperationLogStore().undoRedoState ?? {
+        canUndo: false,
+        canRedo: false,
+        undoCount: 0,
+        redoCount: 0,
+        currentIndex: -1,
+    });
+    // Operation log methods
+    const undo = (hstStore) => {
+        return stonecrop.value?.getOperationLogStore().undo(hstStore) ?? false;
+    };
+    const redo = (hstStore) => {
+        return stonecrop.value?.getOperationLogStore().redo(hstStore) ?? false;
+    };
+    const startBatch = () => {
+        stonecrop.value?.getOperationLogStore().startBatch();
+    };
+    const commitBatch = (description) => {
+        return stonecrop.value?.getOperationLogStore().commitBatch(description) ?? null;
+    };
+    const cancelBatch = () => {
+        stonecrop.value?.getOperationLogStore().cancelBatch();
+    };
+    const clear = () => {
+        stonecrop.value?.getOperationLogStore().clear();
+    };
+    const getOperationsFor = (doctype, recordId) => {
+        return stonecrop.value?.getOperationLogStore().getOperationsFor(doctype, recordId) ?? [];
+    };
+    const getSnapshot = () => {
+        return (stonecrop.value?.getOperationLogStore().getSnapshot() ?? {
+            operations: [],
+            currentIndex: -1,
+            totalOperations: 0,
+            reversibleOperations: 0,
+            irreversibleOperations: 0,
+        });
+    };
+    const markIrreversible = (operationId, reason) => {
+        stonecrop.value?.getOperationLogStore().markIrreversible(operationId, reason);
+    };
+    const logAction = (doctype, actionName, recordIds, result = 'success', error) => {
+        return stonecrop.value?.getOperationLogStore().logAction(doctype, actionName, recordIds, result, error) ?? '';
+    };
+    const configure = (config) => {
+        stonecrop.value?.getOperationLogStore().configure(config);
+    };
+    // Initialize Stonecrop instance
+    onMounted(async () => {
+        if (!registry) {
+            return;
+        }
+        stonecrop.value = providedStonecrop || new Stonecrop(registry);
+        // Set up reactive refs from operation log store - only if Pinia is available
+        try {
+            const opLogStore = stonecrop.value.getOperationLogStore();
+            const opLogRefs = storeToRefs(opLogStore);
+            operations.value = opLogRefs.operations.value;
+            currentIndex.value = opLogRefs.currentIndex.value;
+            // Watch for changes in operation log state
+            watch(() => opLogRefs.operations.value, newOps => {
+                operations.value = newOps;
+            });
+            watch(() => opLogRefs.currentIndex.value, newIndex => {
+                currentIndex.value = newIndex;
+            });
+        }
+        catch {
+            // Pinia not available (e.g., in tests) - operation log features will not be available
+            // Silently fail - operation log is optional
+        }
+        // Handle router-based setup if no specific doctype provided
+        if (!options.doctype && registry.router) {
+            const route = registry.router.currentRoute.value;
+            // Parse route path - let the application determine the doctype from the route
+            if (!route.path)
+                return; // Early return if no path available
+            const pathSegments = route.path.split('/').filter(segment => segment.length > 0);
+            const recordId = pathSegments[1]?.toLowerCase();
+            if (pathSegments.length > 0) {
+                // Create route context for getMeta function
+                const routeContext = {
+                    path: route.path,
+                    segments: pathSegments,
+                };
+                const doctype = await registry.getMeta?.(routeContext);
+                if (doctype) {
+                    registry.addDoctype(doctype);
+                    stonecrop.value.setup(doctype);
+                    // Set reactive refs for router-based doctype
+                    routerDoctype.value = doctype;
+                    routerRecordId.value = recordId;
+                    hstStore.value = stonecrop.value.getStore();
+                    // Resolve schema for router-loaded doctype
+                    if (registry) {
+                        const schemaArray = doctype.schema
+                            ? Array.isArray(doctype.schema)
+                                ? doctype.schema
+                                : Array.from(doctype.schema)
+                            : [];
+                        resolvedSchema.value = registry.resolveSchema(schemaArray);
+                    }
+                    if (recordId && recordId !== 'new') {
+                        const existingRecord = stonecrop.value.getRecordById(doctype, recordId);
+                        if (existingRecord) {
+                            formData.value = existingRecord.get('') || {};
+                        }
+                        else {
+                            try {
+                                await stonecrop.value.getRecord(doctype, recordId);
+                                const loadedRecord = stonecrop.value.getRecordById(doctype, recordId);
+                                if (loadedRecord) {
+                                    formData.value = loadedRecord.get('') || {};
+                                }
+                            }
+                            catch {
+                                formData.value = initializeNewRecord(doctype);
+                            }
+                        }
+                    }
+                    else {
+                        formData.value = initializeNewRecord(doctype);
+                    }
+                    if (hstStore.value) {
+                        setupDeepReactivity(doctype, recordId || 'new', formData, hstStore.value);
+                    }
+                    stonecrop.value.runAction(doctype, 'load', recordId ? [recordId] : undefined);
+                }
+            }
+        }
+        // Handle HST integration if doctype is provided explicitly
+        if (options.doctype) {
+            hstStore.value = stonecrop.value.getStore();
+            const doctype = options.doctype;
+            const recordId = options.recordId;
+            if (recordId && recordId !== 'new') {
+                const existingRecord = stonecrop.value.getRecordById(doctype, recordId);
+                if (existingRecord) {
+                    formData.value = existingRecord.get('') || {};
+                }
+                else {
+                    try {
+                        await stonecrop.value.getRecord(doctype, recordId);
+                        const loadedRecord = stonecrop.value.getRecordById(doctype, recordId);
+                        if (loadedRecord) {
+                            formData.value = loadedRecord.get('') || {};
+                        }
+                    }
+                    catch {
+                        formData.value = initializeNewRecord(doctype);
+                    }
+                }
+            }
+            else {
+                formData.value = initializeNewRecord(doctype);
+            }
+            if (hstStore.value) {
+                setupDeepReactivity(doctype, recordId || 'new', formData, hstStore.value);
+            }
+        }
+    });
+    // HST integration functions - always created but only populated when HST is available
+    const provideHSTPath = (fieldname, customRecordId) => {
+        const doctype = options.doctype || routerDoctype.value;
+        if (!doctype)
+            return '';
+        const actualRecordId = customRecordId || options.recordId || routerRecordId.value || 'new';
+        return `${doctype.slug}.${actualRecordId}.${fieldname}`;
+    };
+    const handleHSTChange = (changeData) => {
+        const doctype = options.doctype || routerDoctype.value;
+        if (!hstStore.value || !stonecrop.value || !doctype) {
+            return;
+        }
+        try {
+            const pathParts = changeData.path.split('.');
+            if (pathParts.length >= 2) {
+                const doctypeSlug = pathParts[0];
+                const recordId = pathParts[1];
+                if (!hstStore.value.has(`${doctypeSlug}.${recordId}`)) {
+                    stonecrop.value.addRecord(doctype, recordId, { ...formData.value });
+                }
+                if (pathParts.length > 3) {
+                    const recordPath = `${doctypeSlug}.${recordId}`;
+                    const nestedParts = pathParts.slice(2);
+                    let currentPath = recordPath;
+                    for (let i = 0; i < nestedParts.length - 1; i++) {
+                        currentPath += `.${nestedParts[i]}`;
+                        if (!hstStore.value.has(currentPath)) {
+                            const nextPart = nestedParts[i + 1];
+                            const isArray = !isNaN(Number(nextPart));
+                            hstStore.value.set(currentPath, isArray ? [] : {});
+                        }
+                    }
+                }
+            }
+            hstStore.value.set(changeData.path, changeData.value);
+            const fieldParts = changeData.fieldname.split('.');
+            const newFormData = { ...formData.value };
+            if (fieldParts.length === 1) {
+                newFormData[fieldParts[0]] = changeData.value;
+            }
+            else {
+                updateNestedObject(newFormData, fieldParts, changeData.value);
+            }
+            formData.value = newFormData;
+        }
+        catch {
+            // Silently handle errors
+        }
+    };
+    // Provide injection tokens if HST will be available
+    if (options.doctype || registry?.router) {
+        provide('hstPathProvider', provideHSTPath);
+        provide('hstChangeHandler', handleHSTChange);
+    }
+    /**
+     * Load nested doctype data from API or initialize empty structure
+     * @param parentPath - The parent path (e.g., "customer.123.address")
+     * @param childDoctype - The child doctype metadata
+     * @param recordId - Optional record ID to load
+     * @returns Promise resolving to the loaded or initialized data
+     */
+    const loadNestedData = (parentPath, childDoctype, recordId) => {
+        if (!stonecrop.value) {
+            return initializeNewRecord(childDoctype);
+        }
+        // If recordId provided, try to load existing data
+        if (recordId) {
+            try {
+                // Check if data already exists in HST
+                const existingData = hstStore.value?.get(parentPath);
+                if (existingData && typeof existingData === 'object') {
+                    return existingData;
+                }
+                // TODO: Add API fetch logic here if needed
+                // For now, initialize new record
+                return initializeNewRecord(childDoctype);
+            }
+            catch {
+                return initializeNewRecord(childDoctype);
+            }
+        }
+        // Initialize new record
+        return initializeNewRecord(childDoctype);
+    };
+    /**
+     * Recursively save a record with all nested doctype fields
+     * @param doctype - The doctype metadata
+     * @param recordId - The record ID to save
+     * @returns The complete save payload
+     */
+    const saveRecursive = (doctype, recordId) => {
+        if (!hstStore.value || !stonecrop.value) {
+            throw new Error('HST store not initialized');
+        }
+        const recordPath = `${doctype.slug}.${recordId}`;
+        const recordData = hstStore.value.get(recordPath) || {};
+        // Build the save payload using resolved schema
+        const payload = { ...recordData };
+        // Use resolveSchema to get the full resolved tree, then walk Doctype fields
+        const schemaArray = (doctype.schema ? (Array.isArray(doctype.schema) ? doctype.schema : Array.from(doctype.schema)) : []);
+        const resolved = registry ? registry.resolveSchema(schemaArray) : schemaArray;
+        const doctypeFields = resolved.filter(field => 'fieldtype' in field && field.fieldtype === 'Doctype' && 'schema' in field && Array.isArray(field.schema));
+        // Recursively collect nested data from HST using resolved schemas
+        for (const field of doctypeFields) {
+            const doctypeField = field;
+            const fieldPath = `${recordPath}.${doctypeField.fieldname}`;
+            const nestedData = collectNestedData(doctypeField.schema, fieldPath, hstStore.value);
+            payload[doctypeField.fieldname] = nestedData;
+        }
+        return payload;
+    };
+    /**
+     * Create a nested context for child forms
+     * @param basePath - The base path for the nested context (e.g., "customer.123.address")
+     * @param _childDoctype - The child doctype metadata (unused but kept for API consistency)
+     * @returns Object with scoped provideHSTPath and handleHSTChange
+     */
+    const createNestedContext = (basePath, _childDoctype) => {
+        const nestedProvideHSTPath = (fieldname) => {
+            return `${basePath}.${fieldname}`;
+        };
+        const nestedHandleHSTChange = (changeData) => {
+            // Update the path to be relative to the nested base path
+            const nestedPath = changeData.path.startsWith(basePath) ? changeData.path : `${basePath}.${changeData.fieldname}`;
+            handleHSTChange({
+                ...changeData,
+                path: nestedPath,
+            });
+        };
+        return {
+            provideHSTPath: nestedProvideHSTPath,
+            handleHSTChange: nestedHandleHSTChange,
+        };
+    };
+    // Create operation log API object
+    const operationLog = {
+        operations,
+        currentIndex,
+        undoRedoState,
+        canUndo,
+        canRedo,
+        undoCount,
+        redoCount,
+        undo,
+        redo,
+        startBatch,
+        commitBatch,
+        cancelBatch,
+        clear,
+        getOperationsFor,
+        getSnapshot,
+        markIrreversible,
+        logAction,
+        configure,
+    };
+    // Always return HST functions if doctype is provided or will be loaded from router
+    if (options.doctype) {
+        // Explicit doctype - return HST immediately
+        return {
+            stonecrop,
+            operationLog,
+            provideHSTPath,
+            handleHSTChange,
+            hstStore,
+            formData,
+            resolvedSchema,
+            loadNestedData,
+            saveRecursive,
+            createNestedContext,
+        };
+    }
+    else if (!options.doctype && registry?.router) {
+        // Router-based - return HST (will be populated after mount)
+        return {
+            stonecrop,
+            operationLog,
+            provideHSTPath,
+            handleHSTChange,
+            hstStore,
+            formData,
+            resolvedSchema,
+            loadNestedData,
+            saveRecursive,
+            createNestedContext,
+        };
+    }
+    // No doctype and no router - basic mode
+    return {
+        stonecrop,
+        operationLog,
+    };
+}
+/**
+ * Initialize new record structure based on doctype schema
+ */
+function initializeNewRecord(doctype) {
+    const initialData = {};
+    if (!doctype.schema) {
+        return initialData;
+    }
+    doctype.schema.forEach(field => {
+        const fieldtype = 'fieldtype' in field ? field.fieldtype : 'Data';
+        switch (fieldtype) {
+            case 'Data':
+            case 'Text':
+                initialData[field.fieldname] = '';
+                break;
+            case 'Check':
+                initialData[field.fieldname] = false;
+                break;
+            case 'Int':
+            case 'Float':
+                initialData[field.fieldname] = 0;
+                break;
+            case 'Table':
+                initialData[field.fieldname] = [];
+                break;
+            case 'JSON':
+                initialData[field.fieldname] = {};
+                break;
+            default:
+                initialData[field.fieldname] = null;
+        }
+    });
+    return initialData;
+}
+/**
+ * Setup deep reactivity between form data and HST store
+ */
+function setupDeepReactivity(doctype, recordId, formData, hstStore) {
+    watch(formData, newData => {
+        const recordPath = `${doctype.slug}.${recordId}`;
+        Object.keys(newData).forEach(fieldname => {
+            const path = `${recordPath}.${fieldname}`;
+            try {
+                hstStore.set(path, newData[fieldname]);
+            }
+            catch {
+                // Silently handle errors
+            }
+        });
+    }, { deep: true });
+}
+/**
+ * Update nested object with dot-notation path
+ */
+function updateNestedObject(obj, path, value) {
+    let current = obj;
+    for (let i = 0; i < path.length - 1; i++) {
+        const key = path[i];
+        if (!(key in current) || typeof current[key] !== 'object') {
+            current[key] = isNaN(Number(path[i + 1])) ? {} : [];
+        }
+        current = current[key];
+    }
+    const finalKey = path[path.length - 1];
+    current[finalKey] = value;
+}
+/**
+ * Recursively collect nested data from HST using pre-resolved schemas
+ * @param resolvedSchema - The already-resolved schema (with nested schemas embedded)
+ * @param basePath - The base path in HST (e.g., "customer.123.address")
+ * @param hstStore - The HST store instance
+ * @returns The collected data object
+ */
+function collectNestedData(resolvedSchema, basePath, hstStore) {
+    const data = hstStore.get(basePath) || {};
+    const payload = { ...data };
+    // Find Doctype fields that have resolved child schemas
+    const doctypeFields = resolvedSchema.filter(field => 'fieldtype' in field && field.fieldtype === 'Doctype' && 'schema' in field && Array.isArray(field.schema));
+    // Recursively collect nested data
+    for (const field of doctypeFields) {
+        const doctypeField = field;
+        const fieldPath = `${basePath}.${doctypeField.fieldname}`;
+        const nestedData = collectNestedData(doctypeField.schema, fieldPath, hstStore);
+        payload[doctypeField.fieldname] = nestedData;
+    }
+    return payload;
+}

package/dist/doctype.js

@@ -42,6 +42,12 @@ export default class Doctype {
      * @readonly
      */
     component;
+    /**
+     * Relationship links to other doctypes
+     * @public
+     * @readonly
+     */
+    links;
     /**
      * Creates a new Doctype instance
      * @param doctype - The doctype name
@@ -49,13 +55,15 @@ export default class Doctype {
      * @param workflow - The doctype workflow configuration (XState machine)
      * @param actions - The doctype actions and field triggers
      * @param component - Optional Vue component for rendering the doctype
+     * @param links - Optional relationship links to other doctypes
      */
-    constructor(doctype, schema, workflow, actions, component) {
+    constructor(doctype, schema, workflow, actions, component, links) {
         this.doctype = doctype;
         this.schema = schema;
         this.workflow = workflow;
         this.actions = actions;
         this.component = component;
+        this.links = links;
     }
     /**
      * Creates a Doctype instance from a plain configuration object.
@@ -98,7 +106,7 @@ export default class Doctype {
     static fromObject(config) {
         const schema = config.fields ? List(config.fields) : List();
         const actions = config.actions ? Map(config.actions) : Map();
-        return new Doctype(config.name, schema, config.workflow, actions);
+        return new Doctype(config.name, schema, config.workflow, actions, undefined, config.links);
     }
     /**
      * Returns the schema as a plain array for use with components that expect

package/dist/field-triggers.js

@@ -39,6 +39,14 @@ export class FieldTriggerEngine {
     registerAction(name, fn) {
         this.globalActions.set(name, fn);
     }
+    /**
+     * Look up a registered action function by name.
+     * Returns `undefined` if the action has not been registered.
+     * @param name - The action name
+     */
+    getAction(name) {
+        return this.globalActions.get(name);
+    }
     /**
      * Register a global XState transition action function
      * @param name - The name of the transition action
@@ -188,11 +196,13 @@ export class FieldTriggerEngine {
         }
         const totalExecutionTime = performance.now() - startTime;
         // Call global error handler if configured and errors occurred
-        const failedResults = actionResults.filter(r => !r.success);
+        const failedResults = actionResults.filter(r => !r.success && r.error != null);
         if (failedResults.length > 0 && this.options.errorHandler) {
             for (const failedResult of failedResults) {
                 try {
-                    this.options.errorHandler(failedResult.error, context, failedResult.action);
+                    if (failedResult.error) {
+                        this.options.errorHandler(failedResult.error, context, failedResult.action);
+                    }
                 }
                 catch (handlerError) {
                     // eslint-disable-next-line no-console
@@ -253,7 +263,9 @@ export class FieldTriggerEngine {
             for (const failedResult of failedResults) {
                 try {
                     // Call with FieldChangeContext (base context type)
-                    this.options.errorHandler(failedResult.error, context, failedResult.action);
+                    if (failedResult.error) {
+                        this.options.errorHandler(failedResult.error, context, failedResult.action);
+                    }
                 }
                 catch (handlerError) {
                     // eslint-disable-next-line no-console