@stonecrop/stonecrop 0.10.16 → 0.11.0

package/src/composables/stonecrop.ts

@@ -5,7 +5,7 @@ import { inject, onMounted, Ref, ref, watch, provide, computed } from 'vue'
 import Doctype from '../doctype'
 import Registry from '../registry'
 import { Stonecrop } from '../stonecrop'
-import type { HSTNode } from '../stores/hst'
+import type { HSTNode } from '../types/hst'
 import type { BaseStonecropReturn, HSTStonecropReturn, HSTChangeData, OperationLogAPI } from '../types/composable'
 import type { HSTOperation, OperationLogConfig } from '../types/operation-log'
 import type { RouteContext } from '../types/registry'
@@ -19,7 +19,17 @@ import type { RouteContext } from '../types/registry'
  */
 export function useStonecrop(): BaseStonecropReturn | HSTStonecropReturn
 /**
- * Unified Stonecrop composable with HST integration for a specific doctype and record
+ * Unified Stonecrop composable with HST integration for a specific doctype and record.
+ *
+ * When a `Doctype` instance is passed, all synchronous initialisation (`hstStore`,
+ * `resolvedSchema`, `formData`, `handleHSTChange`, operation-log wiring) is performed
+ * during `setup()` — before the first render and without awaiting any lifecycle hook.
+ * Callers can read `hstStore.value`, `resolvedSchema.value`, and `formData.value`
+ * immediately after calling this composable; no `nextTick`, `flushPromises`, or
+ * `setTimeout` is required.
+ *
+ * The only remaining async work in `onMounted` is fetching an existing record from the
+ * server when `recordId` is not `'new'`, and lazy-loading a doctype by slug string.
  *
  * @param options - Configuration with doctype (string slug or Doctype instance) and optional recordId
  * @returns Stonecrop instance with full HST integration utilities
@@ -58,6 +68,23 @@ export function useStonecrop(options?: {
 	const error = ref<Error | null>(null)
 	const resolvedDoctype = ref<Doctype | undefined>()
 
+	// Workflow readiness computed properties
+	const isWorkflowReady = computed(() => {
+		if (!stonecrop.value || !resolvedDoctype.value || !options.recordId || options.recordId === 'new') {
+			return true
+		}
+		const status = stonecrop.value.isWorkflowReady(resolvedDoctype.value, options.recordId)
+		return status.ready
+	})
+
+	const blockedLinks = computed(() => {
+		if (!stonecrop.value || !resolvedDoctype.value || !options.recordId || options.recordId === 'new') {
+			return []
+		}
+		const status = stonecrop.value.isWorkflowReady(resolvedDoctype.value, options.recordId)
+		return status.blockedLinks ?? []
+	})
+
 	// Initialize stonecrop instance synchronously using singleton pattern
 	// Use injected instance if available, otherwise fall back to the singleton root
 	const stonecropInstance = providedStonecrop || Stonecrop._root
@@ -70,7 +97,7 @@ export function useStonecrop(options?: {
 		resolvedDoctype.value = options.doctype
 	}
 
-	// Operation log state and methods - will be populated after stonecrop instance is created
+	// Operation log state and methods
 	const operations = ref<HSTOperation[]>([])
 	const currentIndex = ref(-1)
 	const canUndo = computed(() => stonecrop.value?.getOperationLogStore().canUndo ?? false)
@@ -147,13 +174,9 @@ export function useStonecrop(options?: {
 		stonecrop.value?.getOperationLogStore().configure(config)
 	}
 
-	// Initialize Stonecrop instance
-	onMounted(async () => {
-		if (!registry || !stonecrop.value) {
-			return
-		}
-
-		// Set up reactive refs from operation log store - only if Pinia is available
+	// Wire operation log reactive state synchronously — no lifecycle hook needed.
+	// storeToRefs and watch are both safe to call in setup() body.
+	if (registry && stonecrop.value) {
 		try {
 			const opLogStore = stonecrop.value.getOperationLogStore()
 			const opLogRefs = storeToRefs(opLogStore)
@@ -174,8 +197,31 @@ export function useStonecrop(options?: {
 				}
 			)
 		} catch {
-			// Pinia not available (e.g., in tests) - operation log features will not be available
-			// Silently fail - operation log is optional
+			// Pinia not available — operation log is optional, silently skip
+		}
+	}
+
+	// Synchronous HST initialisation for an explicit Doctype instance.
+	// When the caller passes a Doctype object (not a slug string), every piece of
+	// setup that doesn't require network I/O runs here during setup() so that
+	// hstStore, resolvedSchema, and formData are populated before the first render
+	// and are immediately available to callers without any await.
+	if (options.doctype && typeof options.doctype !== 'string' && registry && stonecrop.value) {
+		hstStore.value = stonecrop.value.getStore()
+		resolvedSchema.value = registry.resolveSchema(options.doctype)
+		if (!options.recordId || options.recordId === 'new') {
+			formData.value = registry.initializeRecord(resolvedSchema.value)
+		}
+		if (hstStore.value) {
+			setupDeepReactivity(options.doctype, options.recordId || 'new', formData, hstStore.value)
+		}
+	}
+
+	// onMounted handles only work that is genuinely async: lazy-loading a doctype
+	// by slug, fetching an existing record from the server, and router-based setup.
+	onMounted(async () => {
+		if (!registry || !stonecrop.value) {
+			return
 		}
 
 		// Handle router-based setup if no specific doctype provided
@@ -207,12 +253,7 @@ export function useStonecrop(options?: {
 
 					// 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)
+						resolvedSchema.value = registry.resolveSchema(doctype)
 					}
 
 					if (recordId && recordId !== 'new') {
@@ -245,18 +286,16 @@ export function useStonecrop(options?: {
 
 		// Handle HST integration if doctype is provided explicitly
 		if (options.doctype) {
-			hstStore.value = stonecrop.value.getStore()
 			const recordId = options.recordId
 
-			// Resolve doctype - handle string (lazy-load) or Doctype instance
-			let doctype: Doctype | undefined
-
 			if (typeof options.doctype === 'string') {
-				// String doctype - check registry first, then lazy-load
+				// String doctype — resolve lazily, then do full sync-equivalent setup here.
 				const doctypeSlug = options.doctype
+				hstStore.value = stonecrop.value.getStore()
 				isLoading.value = true
 				error.value = null
 
+				let doctype: Doctype | undefined
 				try {
 					// Check if already in registry
 					doctype = registry.getDoctype(doctypeSlug)
@@ -281,48 +320,54 @@ export function useStonecrop(options?: {
 				} finally {
 					isLoading.value = false
 				}
-			} else {
-				// Doctype instance provided directly
-				doctype = options.doctype
-			}
 
-			// Set resolved doctype for consumers
-			resolvedDoctype.value = doctype
+				resolvedDoctype.value = doctype
+				if (!doctype) return
 
-			if (!doctype) {
-				// Error already set above, just return
-				return
-			}
+				resolvedSchema.value = registry.resolveSchema(doctype)
 
-			// Resolve schema for the doctype
-			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('') || {}
+				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 = registry.initializeRecord(resolvedSchema.value)
 						}
-					} catch {
-						formData.value = registry.initializeRecord(resolvedSchema.value)
 					}
+				} else {
+					formData.value = registry.initializeRecord(resolvedSchema.value)
 				}
-			} else {
-				formData.value = registry.initializeRecord(resolvedSchema.value)
-			}
 
-			if (hstStore.value) {
-				setupDeepReactivity(doctype, recordId || 'new', formData, hstStore.value)
+				if (hstStore.value) {
+					setupDeepReactivity(doctype, recordId || 'new', formData, hstStore.value)
+				}
+			} else {
+				// Doctype instance — sync init was done during setup().
+				// Only handle the async path: fetching an existing record from the server.
+				if (recordId && recordId !== 'new') {
+					const doctype = options.doctype
+					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 = registry.initializeRecord(resolvedSchema.value)
+						}
+					}
+				}
 			}
 		}
 	})
@@ -393,18 +438,36 @@ export function useStonecrop(options?: {
 	}
 
 	/**
-	 * Load nested doctype data from API or initialize empty structure
-	 * Delegates to Stonecrop.loadNestedData method
-	 * @param parentPath - The parent path (e.g., "customer.123.address")
-	 * @param childDoctype - The child doctype metadata
-	 * @param recordId - Optional record ID to load
-	 * @returns The loaded or initialized data
+	 * Scaffold empty descendant records from defaults for all descendant links.
+	 * Delegates to Stonecrop.initializeNestedData method.
+	 * @param path - The HST path where initialized data should be stored
+	 * @param doctype - The doctype to initialize
+	 */
+	const initializeNestedData = (path: string, doctype: Doctype): void => {
+		if (!stonecrop.value) {
+			throw new Error('Stonecrop instance not available')
+		}
+		return stonecrop.value.initializeNestedData(path, doctype)
+	}
+
+	/**
+	 * Fetch a record and its nested data from the server.
+	 * Delegates to Stonecrop.fetchNestedData method.
+	 * @param path - The HST path (e.g., "recipe.r1")
+	 * @param doctype - The doctype to fetch
+	 * @param recordId - Record ID to fetch
+	 * @param options - Query options (includeNested to control which links are fetched)
 	 */
-	const loadNestedData = (parentPath: string, childDoctype: Doctype, recordId?: string): Record<string, any> => {
+	const fetchNestedData = async (
+		path: string,
+		doctype: Doctype,
+		recordId: string,
+		options?: { includeNested?: boolean | string[] }
+	): Promise<void> => {
 		if (!stonecrop.value) {
 			throw new Error('Stonecrop instance not available')
 		}
-		return stonecrop.value.loadNestedData(parentPath, childDoctype, recordId)
+		return stonecrop.value.fetchNestedData(path, doctype, recordId, options)
 	}
 
 	/**
@@ -422,12 +485,12 @@ export function useStonecrop(options?: {
 	}
 
 	/**
-	 * Create a nested context for child forms
+	 * Create a nested context for descendant 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)
+	 * @param _descendantDoctype - The descendant doctype metadata (unused but kept for API consistency)
 	 * @returns Object with scoped provideHSTPath and handleHSTChange
 	 */
-	const createNestedContext = (basePath: string, _childDoctype: Doctype) => {
+	const createNestedContext = (basePath: string, _descendantDoctype: Doctype) => {
 		const nestedProvideHSTPath = (fieldname: string): string => {
 			return `${basePath}.${fieldname}`
 		}
@@ -480,13 +543,16 @@ export function useStonecrop(options?: {
 			hstStore,
 			formData,
 			resolvedSchema,
-			loadNestedData,
+			initializeNestedData,
+			fetchNestedData,
 			collectRecordPayload,
 			createNestedContext,
 			isLoading,
 			error,
 			resolvedDoctype,
-		} as HSTStonecropReturn
+			isWorkflowReady,
+			blockedLinks,
+		} satisfies HSTStonecropReturn
 	} else if (!options.doctype && registry?.router) {
 		// Router-based - return HST (will be populated after mount)
 		return {
@@ -497,13 +563,16 @@ export function useStonecrop(options?: {
 			hstStore,
 			formData,
 			resolvedSchema,
-			loadNestedData,
+			initializeNestedData,
+			fetchNestedData,
 			collectRecordPayload,
 			createNestedContext,
 			isLoading,
 			error,
 			resolvedDoctype,
-		} as HSTStonecropReturn
+			isWorkflowReady,
+			blockedLinks,
+		} satisfies HSTStonecropReturn
 	}
 
 	// No doctype and no router - basic mode

package/src/doctype.ts

@@ -1,8 +1,7 @@
 import type { SchemaTypes } from '@stonecrop/aform'
-import type { WorkflowMeta } from '@stonecrop/schema'
+import type { LinkDeclaration, WorkflowMeta } from '@stonecrop/schema'
 import { List, Map } from 'immutable'
 import { Component } from 'vue'
-import type { UnknownMachineConfig } from 'xstate'
 
 import type { ImmutableDoctype } from './types'
 import type { DoctypeConfig } from './types/doctype'
@@ -56,6 +55,13 @@ export default class Doctype {
 	 */
 	readonly component?: Component
 
+	/**
+	 * Relationship links to other doctypes
+	 * @public
+	 * @readonly
+	 */
+	readonly links?: Record<string, LinkDeclaration>
+
 	/**
 	 * Creates a new Doctype instance
 	 * @param doctype - The doctype name
@@ -63,19 +69,22 @@ 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: string,
 		schema: ImmutableDoctype['schema'],
 		workflow: ImmutableDoctype['workflow'],
 		actions: ImmutableDoctype['actions'],
-		component?: Component
+		component?: Component,
+		links?: Record<string, LinkDeclaration>
 	) {
 		this.doctype = doctype
 		this.schema = schema
 		this.workflow = workflow
 		this.actions = actions
 		this.component = component
+		this.links = links
 	}
 
 	/**
@@ -120,7 +129,7 @@ export default class Doctype {
 		const schema = config.fields ? List(config.fields) : List<SchemaTypes>()
 		const actions = config.actions ? Map(config.actions) : Map<string, string[]>()
 
-		return new Doctype(config.name, schema, config.workflow, actions)
+		return new Doctype(config.name, schema, config.workflow, actions, undefined, config.links)
 	}
 
 	/**

package/src/field-triggers.ts

@@ -1,6 +1,7 @@
 import type { Map as ImmutableMap } from 'immutable'
 import { useOperationLogStore } from './stores/operation-log'
 import type {
+	FieldAction,
 	FieldActionFunction,
 	FieldChangeContext,
 	FieldTriggerExecutionResult,
@@ -22,7 +23,7 @@ export class FieldTriggerEngine {
 	 */
 	static _root: FieldTriggerEngine
 
-	private options: FieldTriggerOptions & { defaultTimeout: number; debug: boolean; enableRollback: boolean }
+	private options!: FieldTriggerOptions & { defaultTimeout: number; debug: boolean; enableRollback: boolean }
 	private doctypeActions = new Map<string, Map<string, string[]>>() // doctype -> action/field -> functions
 	private doctypeTransitions = new Map<string, Map<string, string[]>>() // doctype -> transition -> functions
 	private fieldRollbackConfig = new Map<string, Map<string, boolean>>() // doctype -> field -> rollback enabled
@@ -55,6 +56,15 @@ export class FieldTriggerEngine {
 		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: string): FieldActionFunction | undefined {
+		return this.globalActions.get(name)
+	}
+
 	/**
 	 * Register a global XState transition action function
 	 * @param name - The name of the transition action
@@ -227,11 +237,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
 					console.error('[FieldTriggers] Error in global error handler:', handlerError)
@@ -301,7 +313,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 as unknown as FieldAction)
+					}
 				} catch (handlerError) {
 					// eslint-disable-next-line no-console
 					console.error('[FieldTriggers] Error in global error handler:', handlerError)

package/src/index.ts

@@ -1,6 +1,7 @@
 export type * from '@stonecrop/aform/types'
 export type * from '@stonecrop/atable/types'
 
+import { useLazyLink } from './composables/lazy-link'
 import { useStonecrop } from './composables/stonecrop'
 import { useOperationLog, useUndoRedoShortcuts, withBatch } from './composables/operation-log'
 import Doctype from './doctype'
@@ -15,7 +16,7 @@ import {
 } from './field-triggers'
 import plugin from './plugins'
 import Registry from './registry'
-import { Stonecrop, collectNestedData } from './stonecrop'
+import { Stonecrop, getStonecrop } from './stonecrop'
 import { HST, createHST, type HSTNode } from './stores/hst'
 import { useOperationLogStore } from './stores/operation-log'
 import { SchemaValidator, createValidator, validateSchema } from './schema-validator'
@@ -31,6 +32,7 @@ export {
 	Doctype,
 	Registry,
 	Stonecrop,
+	useLazyLink,
 	useStonecrop,
 	// HST exports for advanced usage
 	HST,
@@ -54,7 +56,7 @@ export {
 	useUndoRedoShortcuts,
 	withBatch,
 	// Utility functions
-	collectNestedData,
+	getStonecrop,
 }
 
 // Default export is the Vue plugin