@stonecrop/stonecrop 0.10.16 → 0.11.0

package/src/stores/operation-log.ts

@@ -1,16 +1,17 @@
 import { defineStore } from 'pinia'
 import { ref, computed, watch } from 'vue'
 import { useLocalStorage } from '@vueuse/core'
+
+import type { HSTNode } from './hst'
 import type {
+	CrossTabMessage,
 	HSTOperation,
 	HSTOperationInput,
 	OperationLogConfig,
-	UndoRedoState,
 	OperationLogSnapshot,
-	CrossTabMessage,
 	OperationSource,
+	UndoRedoState,
 } from '../types/operation-log'
-import type { HSTNode } from './hst'
 
 /**
  * Generate a UUID using crypto API or fallback
@@ -107,8 +108,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<HSTOperation[]>([])
-	const currentBatchId = ref<string | null>(null)
+	const batchStack = ref<{ id: string; operations: HSTOperation[] }[]>([])
 
 	// Computed
 	const canUndo = computed(() => {
@@ -183,9 +183,9 @@ export const useOperationLogStore = defineStore('hst-operation-log', () => {
 			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
 		}
 
@@ -218,25 +218,35 @@ 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?: string): string | null {
-		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 batchId = currentBatchId.value!
-		const allReversible = currentBatch.value.every(op => op.reversible)
+		const currentBatchData = batchStack.value.pop()!
+		const batchOperations = currentBatchData.operations
 
-		// Create parent batch operation
+		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 = currentBatchData.id
+		const allReversible = batchOperations.every(op => op.reversible)
+
+		// Create ancestor batch operation
 		const batchOperation: HSTOperation = {
 			id: batchId,
 			type: 'batch',
@@ -244,45 +254,49 @@ 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
+		// If no more batches on stack, exit batch mode
+		if (batchStack.value.length === 0) {
+			batchMode.value = false
+		}
 
-		return result
+		return batchId
 	}
 
 	/**
 	 * Cancel batch mode without committing
 	 */
 	function cancelBatch() {
+		batchStack.value = []
 		batchMode.value = false
-		currentBatch.value = []
-		currentBatchId.value = null
 	}
 
 	/**
@@ -304,13 +318,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)
 					}
 				}
 			} else {
@@ -346,12 +360,12 @@ export const useOperationLogStore = defineStore('hst-operation-log', () => {
 
 		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)
 					}
 				}
 			} else {
@@ -525,12 +539,12 @@ export const useOperationLogStore = defineStore('hst-operation-log', () => {
 		broadcastChannel.postMessage(serializeForBroadcast(message))
 	}
 
-	function broadcastBatch(childOps: HSTOperation[], batchOp: HSTOperation) {
+	function broadcastBatch(descendantOps: HSTOperation[], batchOp: HSTOperation) {
 		if (!broadcastChannel) return
 
 		const message: CrossTabMessage = {
 			type: 'operation',
-			operations: [...childOps, batchOp],
+			operations: [...descendantOps, batchOp],
 			clientId: clientId.value,
 			timestamp: new Date(),
 		}
@@ -567,7 +581,7 @@ export const useOperationLogStore = defineStore('hst-operation-log', () => {
 		currentIndex: number
 	}
 
-	const persistedData = useLocalStorage<PersistedData | null>('stonecrop-ops-operations', null, {
+	const persistedData = useLocalStorage<PersistedData | null>('stonecrop-operations', null, {
 		serializer: {
 			read: (v: string) => {
 				try {

package/src/types/composable.ts

@@ -1,8 +1,8 @@
-import { SchemaTypes } from '@stonecrop/aform'
+import type { SchemaTypes } from '@stonecrop/aform'
 import type { Ref, ComputedRef } from 'vue'
 
 import type Doctype from '../doctype'
-import type { HSTNode } from '../stores/hst'
+import type { HSTNode } from './hst'
 import type { HSTOperation, OperationLogConfig, OperationLogSnapshot } from './operation-log'
 
 /**
@@ -179,14 +179,28 @@ export type HSTStonecropReturn = BaseStonecropReturn & {
 	 */
 	resolvedSchema: Ref<SchemaTypes[]>
 	/**
-	 * Loads or initializes nested doctype data.
-	 * Use this when rendering a nested form component. Checks HST first, then initializes defaults.
-	 * @param parentPath - The HST path to check for existing data
-	 * @param childDoctype - The nested doctype metadata
-	 * @param recordId - Optional record ID (reserved for future API fetch)
-	 * @returns The loaded or initialized data object
+	 * Scaffold empty descendant records from defaults for all descendant links.
+	 * @param path - The HST path where initialized data should be stored
+	 * @param doctype - The doctype to initialize
 	 */
-	loadNestedData: (parentPath: string, childDoctype: Doctype, recordId?: string) => Record<string, any>
+	initializeNestedData: (path: string, doctype: Doctype) => void
+
+	/**
+	 * Fetch a record and its nested data from the server.
+	 * Stores each field at its own HST path per the field-level convention.
+	 * @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)
+	 * @throws Error with code "CLIENT_REQUIRED" if no data client is configured
+	 * @throws Error with code "RECORD_NOT_FOUND" if the server returns null
+	 */
+	fetchNestedData: (
+		path: string,
+		doctype: Doctype,
+		recordId: string,
+		options?: { includeNested?: boolean | string[] }
+	) => Promise<void>
 	/**
 	 * Collects a complete record payload with all nested data from HST.
 	 * Use this before submitting to an API. Recursively includes 1:1 and 1:many nested records.
@@ -196,15 +210,15 @@ export type HSTStonecropReturn = BaseStonecropReturn & {
 	 */
 	collectRecordPayload: (doctype: Doctype, recordId: string) => Record<string, any>
 	/**
-	 * Creates a nested context for a child doctype component.
+	 * Creates a nested context for a descendant doctype component.
 	 * Use this in parent components to pass scoped handlers to child components.
 	 * @param basePath - The parent HST path prefix
-	 * @param childDoctype - The child doctype metadata
+	 * @param descendantDoctype - The descendant doctype metadata
 	 * @returns Scoped provideHSTPath and handleHSTChange functions
 	 */
 	createNestedContext: (
 		basePath: string,
-		childDoctype: Doctype
+		descendantDoctype: Doctype
 	) => {
 		provideHSTPath: (fieldname: string) => string
 		handleHSTChange: (changeData: HSTChangeData) => void
@@ -224,6 +238,17 @@ export type HSTStonecropReturn = BaseStonecropReturn & {
 	 * Available immediately if Doctype instance passed, after async resolution if slug string passed.
 	 */
 	resolvedDoctype: Ref<Doctype | undefined>
+	/**
+	 * Computed ref indicating whether workflow actions are ready to run.
+	 * True when all links with blockWorkflows are loaded in HST.
+	 * Use with v-bind:disabled="!isWorkflowReady" on action buttons.
+	 */
+	isWorkflowReady: ComputedRef<boolean>
+	/**
+	 * List of link fieldnames that are blocking workflow execution.
+	 * Empty array when isWorkflowReady is true.
+	 */
+	blockedLinks: ComputedRef<string[]>
 }
 
 // Import Stonecrop class for the BaseStonecropReturn type (circular reference handled via import)
@@ -243,3 +268,21 @@ export type HSTChangeData = {
 	/** Optional record ID */
 	recordId?: string
 }
+
+/**
+ * Lazy link state for a single link field.
+ * Provides reactive state and reload capability for lazy-loaded links.
+ * @public
+ */
+export type LazyLink = {
+	/** True while fetching data */
+	loading: Ref<boolean>
+	/** True after successful fetch (permanent until reload) */
+	loaded: Ref<boolean>
+	/** Error state, if any */
+	error: Ref<Error | null>
+	/** Explicitly trigger a fetch for this link */
+	reload: () => Promise<void>
+	/** The loaded data from HST, or undefined if not loaded */
+	data: ComputedRef<any>
+}

package/src/types/doctype.ts

@@ -1,5 +1,5 @@
 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 type { AnyStateNodeConfig, UnknownMachineConfig } from 'xstate'
 
@@ -11,6 +11,7 @@ export type ImmutableDoctype = {
 	readonly schema?: List<SchemaTypes>
 	readonly workflow?: UnknownMachineConfig | AnyStateNodeConfig | WorkflowMeta
 	readonly actions?: Map<string, string[]>
+	readonly links?: Record<string, LinkDeclaration>
 }
 
 /**
@@ -45,16 +46,14 @@ export type DoctypeConfig = {
 	slug?: string
 	/** Database table name */
 	tableName?: string
-	/** Field definitions */
+	/** Field definitions (including link fields with fieldtype: 'Link') */
 	fields?: SchemaTypes[]
+	/** Relationship links to other doctypes */
+	links?: Record<string, LinkDeclaration>
 	/** Workflow configuration (XState format or simple WorkflowMeta) */
 	workflow?: UnknownMachineConfig | WorkflowMeta
 	/** Actions and their field triggers */
 	actions?: Record<string, string[]>
-	/** Parent doctype for inheritance */
+	/** Ancestor doctype for inheritance */
 	inherits?: string
-	/** Doctype to use for list views */
-	listDoctype?: string
-	/** Parent doctype for child tables */
-	parentDoctype?: string
 }

package/src/types/field-triggers.ts

@@ -3,7 +3,7 @@
  * @public
  */
 
-import { HSTNode } from '../stores/hst'
+import type { HSTNode } from './hst'
 
 /**
  * Context provided to action functions when field changes occur

package/src/types/hst.ts

@@ -0,0 +1,77 @@
+/**
+ * Core HST Interface - enhanced with tree navigation
+ * Provides a hierarchical state tree interface for navigating and manipulating nested data structures.
+ *
+ * @public
+ */
+export interface HSTNode {
+	/**
+	 * Gets a value at the specified path
+	 * @param path - The dot-separated path to the value
+	 * @returns The value at the specified path
+	 */
+	get(path: string): any
+
+	/**
+	 * Sets a value at the specified path
+	 * @param path - The dot-separated path where to set the value
+	 * @param value - The value to set
+	 * @param source - Optional source of the operation (user, system, sync, undo, redo)
+	 */
+	set(path: string, value: any, source?: 'user' | 'system' | 'sync' | 'undo' | 'redo'): void
+
+	/**
+	 * Checks if a value exists at the specified path
+	 * @param path - The dot-separated path to check
+	 * @returns True if the path exists, false otherwise
+	 */
+	has(path: string): boolean
+
+	/**
+	 * Gets the ancestor node in the tree hierarchy (immediate predecessor)
+	 * @returns The ancestor HSTNode or null if this is the root
+	 */
+	getAncestor(): HSTNode | null
+
+	/**
+	 * Gets the root node of the tree
+	 * @returns The root HSTNode
+	 */
+	getRoot(): HSTNode
+
+	/**
+	 * Gets the full path from root to this node
+	 * @returns The dot-separated path string
+	 */
+	getPath(): string
+
+	/**
+	 * Gets the depth level of this node in the tree
+	 * @returns The depth as a number (0 for root)
+	 */
+	getDepth(): number
+
+	/**
+	 * Gets an array of path segments from root to this node
+	 * @returns Array of path segments representing breadcrumbs
+	 */
+	getBreadcrumbs(): string[]
+
+	/**
+	 * Gets a child node at the specified relative path
+	 * @param path - The relative path to the child node
+	 * @returns The child HSTNode
+	 */
+	getNode(path: string): HSTNode
+
+	/**
+	 * Trigger an XState transition with optional context data
+	 * @param transition - The transition name (should be uppercase per convention)
+	 * @param context - Optional additional FSM context data
+	 * @returns Promise resolving to the transition execution results
+	 */
+	triggerTransition(
+		transition: string,
+		context?: { currentState?: string; targetState?: string; fsmContext?: Record<string, any> }
+	): Promise<any>
+}

package/src/types/index.ts

@@ -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/src/types/operation-log.ts

@@ -79,11 +79,11 @@ export interface HSTOperation {
 	/** Additional metadata for custom use cases */
 	metadata?: Record<string, any>
 
-	/** Parent operation ID for batch operations */
-	parentOperationId?: string
+	/** Ancestor operation ID for batch operations */
+	ancestorOperationId?: string
 
-	/** Child operation IDs for batch operations */
-	childOperationIds?: string[]
+	/** Descendant operation IDs for batch operations */
+	descendantOperationIds?: string[]
 }
 
 /**

package/src/types/schema-validator.ts

@@ -58,6 +58,8 @@ export interface ValidatorOptions {
 	registry?: Registry
 	/** Whether to validate Link field targets */
 	validateLinkTargets?: boolean
+	/** Whether to validate links object (target resolution, backlink consistency, Link field correspondence) */
+	validateLinks?: boolean
 	/** Whether to validate workflow reachability */
 	validateWorkflows?: boolean
 	/** Whether to validate action registration */