@stonecrop/stonecrop 0.4.37 → 0.6.0

package/src/types/field-triggers.ts

@@ -0,0 +1,201 @@
+/**
+ * Field-level action trigger system types
+ * @public
+ */
+
+import { HSTNode } from '../stores/hst'
+
+/**
+ * Context provided to action functions when field changes occur
+ * @public
+ */
+export interface FieldChangeContext {
+	/** The HST path that was changed */
+	path: string
+	/** The field name (last segment of path) */
+	fieldname: string
+	/** Value before the change */
+	beforeValue: any
+	/** Value after the change */
+	afterValue: any
+	/** The operation type */
+	operation: 'set' | 'delete' | 'patch'
+	/** The doctype of the record being changed */
+	doctype: string
+	/** The record ID if applicable */
+	recordId?: string
+	/** Timestamp of the change */
+	timestamp: Date
+	/** Reference to the HST store for state access (optional) */
+	store?: HSTNode
+}
+
+/**
+ * Context provided to XState transition action functions
+ * Extends FieldChangeContext with FSM-specific data
+ * @public
+ */
+export interface TransitionChangeContext extends FieldChangeContext {
+	/** The XState transition name that triggered this action */
+	transition: string
+	/** Current workflow state before transition */
+	currentState?: string
+	/** Target workflow state after transition */
+	targetState?: string
+	/** Additional FSM context data */
+	fsmContext?: Record<string, any>
+}
+
+/**
+ * Action function that can be triggered by field changes
+ * @public
+ */
+export type FieldActionFunction = (context: FieldChangeContext) => void | Promise<void>
+
+/**
+ * Action function for XState transition triggers
+ * Receives enhanced context with FSM state information
+ * @public
+ */
+export type TransitionActionFunction = (context: TransitionChangeContext) => void | Promise<void>
+
+/**
+ * String reference to a globally registered action function or inline function
+ * @public
+ */
+export type FieldActionString = string
+
+/**
+ * Supported action types for field triggers
+ * @public
+ */
+export type FieldAction = FieldActionFunction | FieldActionString
+
+/**
+ * Supported action types for XState transitions
+ * Can be either a transition-specific function or a string reference
+ * @public
+ */
+export type TransitionAction = TransitionActionFunction | FieldActionString
+
+/**
+ * Configuration for a single field trigger
+ * @public
+ */
+export interface FieldTriggerConfig {
+	/** Array of actions to execute when this field changes */
+	actions: FieldAction[]
+	/** Optional condition function to determine if actions should run */
+	condition?: (context: FieldChangeContext) => boolean | Promise<boolean>
+	/** Whether to run actions before or after the value is set (default: 'after') */
+	timing?: 'before' | 'after'
+	/** Whether to stop execution on first error (default: true) */
+	stopOnError?: boolean
+	/** Maximum execution time in milliseconds before timeout */
+	timeout?: number
+	/** Whether to enable automatic rollback for this field trigger (overrides global setting) */
+	enableRollback?: boolean
+}
+
+/**
+ * Map of field paths to trigger configurations
+ * Supports wildcard patterns like 'emailAddress.*.is_primary'
+ * @public
+ */
+export type FieldTriggerMap = Record<string, FieldTriggerConfig | FieldAction[]>
+
+/**
+ * Registry for storing global action functions
+ * @public
+ */
+export interface ActionRegistry {
+	/** Register a global action function */
+	register(name: string, fn: FieldActionFunction): void
+	/** Get a registered action function */
+	get(name: string): FieldActionFunction | undefined
+	/** Check if an action is registered */
+	has(name: string): boolean
+	/** Unregister an action function */
+	unregister(name: string): void
+	/** Get all registered action names */
+	list(): string[]
+}
+
+/**
+ * Result of executing a field action
+ * @public
+ */
+export interface ActionExecutionResult {
+	/** Whether the action executed successfully */
+	success: boolean
+	/** Error if execution failed */
+	error?: Error
+	/** Execution time in milliseconds */
+	executionTime: number
+	/** The action that was executed */
+	action: FieldAction
+}
+
+/**
+ * Result of executing an XState transition action
+ * @public
+ */
+export interface TransitionExecutionResult {
+	/** Whether the action executed successfully */
+	success: boolean
+	/** Error if execution failed */
+	error?: Error
+	/** Execution time in milliseconds */
+	executionTime: number
+	/** The action that was executed */
+	action: TransitionAction
+	/** The transition name that was executed */
+	transition: string
+}
+
+/**
+ * Result of executing all actions for a field change
+ * @public
+ */
+export interface FieldTriggerExecutionResult {
+	/** The path that triggered the actions */
+	path: string
+	/** Results for each action that was executed */
+	actionResults: ActionExecutionResult[]
+	/** Total execution time for all actions */
+	totalExecutionTime: number
+	/** Whether all actions succeeded */
+	allSucceeded: boolean
+	/** Whether execution was stopped due to an error */
+	stoppedOnError: boolean
+	/** Whether a rollback was performed */
+	rolledBack: boolean
+	/** The snapshot that was captured before execution */
+	snapshot?: any
+}
+
+/**
+ * Options for the field trigger system
+ * @public
+ */
+export interface FieldTriggerOptions {
+	/** Default timeout for action execution in milliseconds */
+	defaultTimeout?: number
+	/** Whether to log trigger executions for debugging */
+	debug?: boolean
+	/** Custom error handler for action failures */
+	errorHandler?: (error: Error, context: FieldChangeContext, action: FieldAction) => void
+	/** Whether to enable automatic rollback on failure (default: true) */
+	enableRollback?: boolean
+}
+
+/**
+ * Pattern matching result for wildcard paths
+ * @internal
+ */
+export interface _PathMatchResult {
+	/** Whether the path matches the pattern */
+	matches: boolean
+	/** Captured wildcard values */
+	captures: Record<string, string>
+}

package/src/types/index.ts

@@ -4,15 +4,17 @@ import type { Component } from 'vue'
 import type { Router } from 'vue-router'
 import type { AnyStateNodeConfig, UnknownMachineConfig } from 'xstate'
 
-import DoctypeMeta from '../doctype'
+import type DoctypeMeta from '../doctype'
+import Registry from '../registry'
+import { Stonecrop } from '../stonecrop'
+import type { RouteContext } from './registry'
 
 /**
  * Immutable Doctype type for Stonecrop instances
  * @public
  */
 export type ImmutableDoctype = {
-	// TODO: allow schema to be a function
-	readonly schema?: List<SchemaTypes>
+	readonly schema?: List<SchemaTypes> // TODO: allow schema to be a function
 	readonly workflow?: UnknownMachineConfig | AnyStateNodeConfig
 	readonly actions?: Map<string, string[]>
 }
@@ -22,8 +24,8 @@ export type ImmutableDoctype = {
  * @public
  */
 export type MutableDoctype = {
-	// TODO: allow schema to be a function
-	schema?: SchemaTypes[]
+	doctype?: string
+	schema?: SchemaTypes[] // TODO: allow schema to be a function
 	workflow?: UnknownMachineConfig | AnyStateNodeConfig
 	actions?: Record<string, string[]>
 }
@@ -44,5 +46,14 @@ export type Schema = {
 export type InstallOptions = {
 	router?: Router
 	components?: Record<string, Component>
-	getMeta?: (doctype?: string) => DoctypeMeta | Promise<DoctypeMeta>
+	getMeta?: (routeContext: RouteContext) => DoctypeMeta | Promise<DoctypeMeta>
+	/** Automatically run initialization callback after app mounting (default: false) */
+	autoInitializeRouter?: boolean
+	/** Callback function called after plugin is ready and mounted */
+	onRouterInitialized?: (registry: Registry, stonecrop: Stonecrop) => void | Promise<void>
 }
+
+// Re-export types
+export * from './field-triggers'
+export * from './registry'
+export * from './operation-log'

package/src/types/operation-log.ts

@@ -0,0 +1,205 @@
+/**
+ * Type of HST operation
+ * @public
+ */
+export type HSTOperationType = 'set' | 'delete' | 'batch' | 'transition' | 'action'
+
+/**
+ * Operation source - where the change originated
+ * @public
+ */
+export type OperationSource = 'user' | 'system' | 'sync' | 'undo' | 'redo'
+
+/**
+ * Complete metadata for an HST mutation
+ * Enables time travel, synchronization, and audit trails
+ * @public
+ */
+export interface HSTOperation {
+	/** Unique operation identifier */
+	id: string
+
+	/** Type of operation performed */
+	type: HSTOperationType
+
+	/** Full HST path affected (e.g., "task.123.title") */
+	path: string
+
+	/** Field name extracted from path */
+	fieldname: string
+
+	/** Value before the operation */
+	beforeValue: any
+
+	/** Value after the operation */
+	afterValue: any
+
+	/** Doctype this operation affects */
+	doctype: string
+
+	/** Record ID if applicable */
+	recordId?: string
+
+	/** Timestamp of the operation */
+	timestamp: Date
+
+	/** Source of the operation (defaults to 'user' if not specified) */
+	source?: OperationSource
+
+	/** Whether this operation can be undone */
+	reversible: boolean
+
+	/** Reason if operation is irreversible */
+	irreversibleReason?: string
+
+	/** XState transition name if triggered by FSM */
+	transition?: string
+
+	/** XState current state before transition */
+	currentState?: string
+
+	/** XState target state after transition */
+	targetState?: string
+
+	/** Action name if operation is an action execution (type: 'action') */
+	actionName?: string
+
+	/** Record IDs that the action was executed on */
+	actionRecordIds?: string[]
+
+	/** Result or status of the action execution */
+	actionResult?: 'success' | 'failure' | 'pending'
+
+	/** Error message if action execution failed */
+	actionError?: string
+
+	/** User or session identifier */
+	userId?: string
+
+	/** Additional metadata for custom use cases */
+	metadata?: Record<string, any>
+
+	/** Parent operation ID for batch operations */
+	parentOperationId?: string
+
+	/** Child operation IDs for batch operations */
+	childOperationIds?: string[]
+}
+
+/**
+ * Input type for adding operations
+ * Excludes system-generated fields (id, timestamp)
+ * @public
+ */
+export type HSTOperationInput = Omit<HSTOperation, 'id' | 'timestamp' | 'source'> & {
+	source?: OperationSource
+}
+
+/**
+ * Batch operation wrapper
+ * @public
+ */
+export interface BatchOperation {
+	/** Unique batch identifier */
+	id: string
+	/** Operations included in this batch */
+	operations: HSTOperation[]
+	/** When the batch was created */
+	timestamp: Date
+	/** Optional description of what this batch represents */
+	description?: string
+	/** Whether the entire batch can be undone */
+	reversible: boolean
+}
+
+/**
+ * Operation log configuration
+ * @public
+ */
+export interface OperationLogConfig {
+	/** Maximum operations to store (default: 100) */
+	maxOperations?: number
+
+	/** Enable cross-tab synchronization (default: true) */
+	enableCrossTabSync?: boolean
+
+	/** Auto-sync interval in milliseconds (default: 30000) */
+	autoSyncInterval?: number
+
+	/** Enable operation persistence to localStorage (default: false) */
+	enablePersistence?: boolean
+
+	/** Persistence key prefix */
+	persistenceKeyPrefix?: string
+
+	/** User identifier for multi-user scenarios */
+	userId?: string
+
+	/** Custom operation filter */
+	operationFilter?: (operation: HSTOperation) => boolean
+}
+
+/**
+ * Undo/Redo state
+ * @public
+ */
+export interface UndoRedoState {
+	/** Can undo */
+	canUndo: boolean
+
+	/** Can redo */
+	canRedo: boolean
+
+	/** Number of operations available for undo */
+	undoCount: number
+
+	/** Number of operations available for redo */
+	redoCount: number
+
+	/** Current operation index */
+	currentIndex: number
+}
+
+/**
+ * Operation log snapshot for debugging
+ * @public
+ */
+export interface OperationLogSnapshot {
+	/** All operations in the log */
+	operations: HSTOperation[]
+	/** Current operation index in the history */
+	currentIndex: number
+	/** Total number of operations */
+	totalOperations: number
+	/** Number of operations that can be undone */
+	reversibleOperations: number
+	/** Number of operations that cannot be undone */
+	irreversibleOperations: number
+	/** Timestamp of the oldest operation */
+	oldestOperation?: Date
+	/** Timestamp of the newest operation */
+	newestOperation?: Date
+}
+
+/**
+ * Cross-tab message types
+ * @public
+ */
+export type CrossTabMessageType = 'operation' | 'undo' | 'redo' | 'sync-request' | 'sync-response'
+
+/**
+ * Cross-tab message payload
+ * @public
+ */
+export interface CrossTabMessage {
+	/** Type of cross-tab message */
+	type: CrossTabMessageType
+	/** Single operation for operation/undo/redo messages */
+	operation?: HSTOperation
+	/** Multiple operations for sync messages */
+	operations?: HSTOperation[]
+	/** Identifier of the client/tab sending the message */
+	clientId: string
+	/** When the message was sent */
+	timestamp: Date
+}

package/src/types/registry.ts

@@ -0,0 +1,10 @@
+/**
+ * Route context passed to getMeta function
+ * @public
+ */
+export interface RouteContext {
+	/** The full route path (e.g., "/todo/1" or "/todo") */
+	path: string
+	/** Path segments split by "/" (e.g., ["todo", "1"] or ["todo"]) */
+	segments: string[]
+}

package/dist/composable.js

@@ -1,50 +0,0 @@
-import { inject, onMounted, ref } from 'vue';
-import { Stonecrop } from './stonecrop';
-import { useDataStore } from './stores/data';
-/**
- * Stonecrop composable
- * @param registry - An existing Stonecrop Registry instance
- * @returns The Stonecrop instance and a boolean indicating if Stonecrop is setup and ready
- * @throws Error if the Stonecrop plugin is not enabled before using the composable
- * @public
- */
-export function useStonecrop(registry) {
-    const stonecrop = ref();
-    onMounted(async () => {
-        if (!registry) {
-            registry = inject('$registry');
-        }
-        if (!registry || !registry.router)
-            return;
-        let store;
-        try {
-            store = useDataStore();
-        }
-        catch {
-            throw new Error('Please enable the Stonecrop plugin before using the Stonecrop composable');
-        }
-        stonecrop.value = new Stonecrop(registry, store);
-        const route = registry.router.currentRoute.value;
-        const doctypeSlug = route.params.records?.toString().toLowerCase();
-        const recordId = route.params.record?.toString().toLowerCase(); // TODO: handle views other than list and form views?
-        if (!doctypeSlug && !recordId) {
-            return;
-        }
-        // setup doctype via registry
-        const doctype = await registry.getMeta?.(doctypeSlug);
-        if (doctype) {
-            registry.addDoctype(doctype);
-            stonecrop.value.setup(doctype);
-            if (doctypeSlug) {
-                if (recordId) {
-                    await stonecrop.value.getRecord(doctype, recordId);
-                }
-                else {
-                    await stonecrop.value.getRecords(doctype);
-                }
-            }
-            stonecrop.value.runAction(doctype, 'load', recordId ? [recordId] : undefined);
-        }
-    });
-    return { stonecrop };
-}

package/dist/index.js

@@ -1,6 +0,0 @@
-import { useStonecrop } from './composable';
-import DoctypeMeta from './doctype';
-import Registry from './registry';
-import Stonecrop from './plugins';
-import { Stonecrop as StonecropClass } from './stonecrop';
-export { DoctypeMeta, Registry, Stonecrop, StonecropClass, useStonecrop };

package/dist/plugins/index.js

@@ -1,49 +0,0 @@
-import Registry from '../registry';
-import { pinia } from '../stores';
-/**
- * Stonecrop Vue plugin
- * @param app - The Vue app instance
- * @param options - The plugin options
- * @example
- * ```ts
- *
- * import { createApp } from 'vue'
- * import Stonecrop from 'stonecrop'
- *
- * import App from './App.vue'
- *
- * const app = createApp(App)
- * app.use(Stonecrop, {
- *  router,
- *  components: {
- *   // register custom components
- *  },
- *  getMeta: async (doctype: string) => {
- *   // fetch doctype meta from API
- *  },
- * })
- *
- * app.mount('#app')
- * ```
- *
- * @public
- */
-const plugin = {
-    install: (app, options) => {
-        // check if the router is already installed via another plugin
-        const existingRouter = app.config.globalProperties.$router;
-        const appRouter = existingRouter || options?.router;
-        const registry = new Registry(appRouter, options?.getMeta);
-        if (!existingRouter && appRouter) {
-            app.use(appRouter);
-        }
-        app.use(pinia);
-        app.provide('$registry', registry);
-        if (options?.components) {
-            for (const [tag, component] of Object.entries(options.components)) {
-                app.component(tag, component);
-            }
-        }
-    },
-};
-export default plugin;

package/dist/src/stores/data.d.ts

@@ -1,11 +0,0 @@
-export declare const useDataStore: import("pinia").StoreDefinition<"data", Pick<{
-    records: import("vue").Ref<Record<string, any>[], Record<string, any>[]>;
-    record: import("vue").Ref<Record<string, any>, Record<string, any>>;
-}, "records" | "record">, Pick<{
-    records: import("vue").Ref<Record<string, any>[], Record<string, any>[]>;
-    record: import("vue").Ref<Record<string, any>, Record<string, any>>;
-}, never>, Pick<{
-    records: import("vue").Ref<Record<string, any>[], Record<string, any>[]>;
-    record: import("vue").Ref<Record<string, any>, Record<string, any>>;
-}, never>>;
-//# sourceMappingURL=data.d.ts.map

package/dist/src/stores/data.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"data.d.ts","sourceRoot":"","sources":["../../../src/stores/data.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,YAAY;;;;;;;;;UAIvB,CAAA"}

package/dist/stores/data.js

@@ -1,7 +0,0 @@
-import { defineStore } from 'pinia';
-import { ref } from 'vue';
-export const useDataStore = defineStore('data', () => {
-    const records = ref([]);
-    const record = ref({});
-    return { records, record };
-});

package/src/stores/data.ts

@@ -1,8 +0,0 @@
-import { defineStore } from 'pinia'
-import { ref } from 'vue'
-
-export const useDataStore = defineStore('data', () => {
-	const records = ref<Record<string, any>[]>([])
-	const record = ref<Record<string, any>>({})
-	return { records, record }
-})