@stonecrop/stonecrop 0.12.8 → 0.13.0

package/dist/composable.js

@@ -0,0 +1 @@
+export { useStonecrop } from './composables/stonecrop';

package/dist/composables/lazy-link.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 LazyLink with loading, loaded, error, reload, and data
+ * @public
+ */
+export function useLazyLink(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/operation-log.js

@@ -0,0 +1,224 @@
+import { useMagicKeys, whenever } from '@vueuse/core';
+import { storeToRefs } from 'pinia';
+import { getCurrentInstance, inject } from 'vue';
+import { useOperationLogStore } from '../stores/operation-log';
+/**
+ * Composable for operation log management
+ * Provides easy access to undo/redo functionality and operation history
+ *
+ * @param config - Optional configuration for the operation log
+ * @returns Operation log interface
+ *
+ * @example
+ * ```typescript
+ * const { undo, redo, canUndo, canRedo, operations, configure } = useOperationLog()
+ *
+ * // Configure the log
+ * configure({
+ *   maxOperations: 50,
+ *   enableCrossTabSync: true,
+ *   enablePersistence: true
+ * })
+ *
+ * // Undo/redo
+ * await undo(hstStore)
+ * await redo(hstStore)
+ * ```
+ *
+ * @public
+ */
+export function useOperationLog(config) {
+    // inject() is only valid inside a component setup() context. When this
+    // composable is called outside one (e.g. directly in test bodies or plain
+    // scripts) skip the injection entirely and fall back to the Pinia store.
+    const injectedStore = getCurrentInstance()
+        ? inject('$operationLogStore', undefined)
+        : undefined;
+    const store = injectedStore || useOperationLogStore();
+    // Apply configuration if provided
+    if (config) {
+        store.configure(config);
+    }
+    // Extract reactive state
+    const { operations, currentIndex, undoRedoState, canUndo, canRedo, undoCount, redoCount } = storeToRefs(store);
+    /**
+     * Undo the last operation
+     */
+    function undo(hstStore) {
+        return store.undo(hstStore);
+    }
+    /**
+     * Redo the next operation
+     */
+    function redo(hstStore) {
+        return store.redo(hstStore);
+    }
+    /**
+     * Start a batch operation
+     */
+    function startBatch() {
+        store.startBatch();
+    }
+    /**
+     * Commit the current batch
+     */
+    function commitBatch(description) {
+        return store.commitBatch(description);
+    }
+    /**
+     * Cancel the current batch
+     */
+    function cancelBatch() {
+        store.cancelBatch();
+    }
+    /**
+     * Clear all operations
+     */
+    function clear() {
+        store.clear();
+    }
+    /**
+     * Get operations for a specific doctype/record
+     */
+    function getOperationsFor(doctype, recordId) {
+        return store.getOperationsFor(doctype, recordId);
+    }
+    /**
+     * Get a snapshot of the operation log
+     */
+    function getSnapshot() {
+        return store.getSnapshot();
+    }
+    /**
+     * Mark an operation as irreversible
+     * @param operationId - The ID of the operation to mark
+     * @param reason - The reason why the operation is irreversible
+     */
+    function markIrreversible(operationId, reason) {
+        store.markIrreversible(operationId, reason);
+    }
+    /**
+     * Log an action execution (stateless actions like print, email, etc.)
+     * @param doctype - The doctype the action was executed on
+     * @param actionName - The name of the action that was executed
+     * @param recordIds - Optional array of record IDs the action was executed on
+     * @param result - The result of the action execution
+     * @param error - Optional error message if action failed
+     * @returns The operation ID
+     */
+    function logAction(doctype, actionName, recordIds, result = 'success', error) {
+        return store.logAction(doctype, actionName, recordIds, result, error);
+    }
+    /**
+     * Update configuration
+     * @param options - Configuration options to update
+     */
+    function configure(options) {
+        store.configure(options);
+    }
+    return {
+        // State
+        operations,
+        currentIndex,
+        undoRedoState,
+        canUndo,
+        canRedo,
+        undoCount,
+        redoCount,
+        // Methods
+        undo,
+        redo,
+        startBatch,
+        commitBatch,
+        cancelBatch,
+        clear,
+        getOperationsFor,
+        getSnapshot,
+        markIrreversible,
+        logAction,
+        configure,
+    };
+}
+/**
+ * Keyboard shortcut handler for undo/redo
+ * Automatically binds Ctrl+Z (undo) and Ctrl+Shift+Z/Ctrl+Y (redo) using VueUse
+ *
+ * @param hstStore - The HST store to operate on
+ * @param enabled - Whether shortcuts are enabled (default: true)
+ *
+ * @example
+ * ```typescript
+ * import { onMounted } from 'vue'
+ *
+ * const stonecrop = useStonecrop({ doctype, recordId })
+ * useUndoRedoShortcuts(stonecrop.hstStore)
+ * ```
+ *
+ * @public
+ */
+export function useUndoRedoShortcuts(hstStore, enabled = true) {
+    if (!enabled)
+        return;
+    const { undo, redo, canUndo, canRedo } = useOperationLog();
+    const keys = useMagicKeys();
+    // Undo shortcuts: Ctrl+Z or Cmd+Z (Mac)
+    whenever(keys['Ctrl+Z'], () => {
+        if (canUndo.value) {
+            undo(hstStore);
+        }
+    });
+    whenever(keys['Meta+Z'], () => {
+        if (canUndo.value) {
+            undo(hstStore);
+        }
+    });
+    // Redo shortcuts: Ctrl+Shift+Z, Cmd+Shift+Z (Mac), or Ctrl+Y
+    whenever(keys['Ctrl+Shift+Z'], () => {
+        if (canRedo.value) {
+            redo(hstStore);
+        }
+    });
+    whenever(keys['Meta+Shift+Z'], () => {
+        if (canRedo.value) {
+            redo(hstStore);
+        }
+    });
+    whenever(keys['Ctrl+Y'], () => {
+        if (canRedo.value) {
+            redo(hstStore);
+        }
+    });
+}
+/**
+ * Batch operation helper
+ * Wraps a function execution in a batch operation
+ *
+ * @param fn - The function to execute within a batch
+ * @param description - Optional description for the batch
+ * @returns The batch operation ID
+ *
+ * @example
+ * ```typescript
+ * const { withBatch } = useOperationLog()
+ *
+ * const batchId = await withBatch(() => {
+ *   hstStore.set('task.123.title', 'New Title')
+ *   hstStore.set('task.123.status', 'active')
+ *   hstStore.set('task.123.priority', 'high')
+ * }, 'Update task details')
+ * ```
+ *
+ * @public
+ */
+export async function withBatch(fn, description) {
+    const { startBatch, commitBatch, cancelBatch } = useOperationLog();
+    startBatch();
+    try {
+        await fn();
+        return commitBatch(description);
+    }
+    catch (error) {
+        cancelBatch();
+        throw error;
+    }
+}