@stonecrop/stonecrop 0.10.6 → 0.10.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonecrop/stonecrop",
-  "version": "0.10.6",
+  "version": "0.10.8",
   "license": "MIT",
   "type": "module",
   "author": {
@@ -34,7 +34,7 @@
     "pinia-shared-state": "^1.0.1",
     "pinia-xstate": "^3.0.0",
     "xstate": "^5.25.0",
-    "@stonecrop/schema": "0.10.6"
+    "@stonecrop/schema": "0.10.8"
   },
   "peerDependencies": {
     "pinia": "^3.0.4",
@@ -60,8 +60,8 @@
     "vue-router": "^5.0.2",
     "vite": "^7.3.1",
     "vitest": "^4.0.18",
-    "@stonecrop/aform": "0.10.6",
-    "@stonecrop/atable": "0.10.6",
+    "@stonecrop/aform": "0.10.8",
+    "@stonecrop/atable": "0.10.8",
     "stonecrop-rig": "0.7.0"
   },
   "description": "Schema-driven framework with XState workflows and HST state management",

package/src/composables/stonecrop.ts

@@ -74,6 +74,9 @@ export type HSTStonecropReturn = BaseStonecropReturn & {
 		provideHSTPath: (fieldname: string) => string
 		handleHSTChange: (changeData: HSTChangeData) => void
 	}
+	isLoading: Ref<boolean>
+	error: Ref<Error | null>
+	resolvedDoctype: Ref<Doctype | undefined>
 }
 
 /**
@@ -98,17 +101,21 @@ export function useStonecrop(): BaseStonecropReturn | HSTStonecropReturn
 /**
  * Unified Stonecrop composable with HST integration for a specific doctype and record
  *
- * @param options - Configuration with doctype and optional recordId
+ * @param options - Configuration with doctype (string slug or Doctype instance) and optional recordId
  * @returns Stonecrop instance with full HST integration utilities
  * @public
  */
-export function useStonecrop(options: { registry?: Registry; doctype: Doctype; recordId?: string }): HSTStonecropReturn
+export function useStonecrop(options: {
+	registry?: Registry
+	doctype: Doctype | string
+	recordId?: string
+}): HSTStonecropReturn
 /**
  * @public
  */
 export function useStonecrop(options?: {
 	registry?: Registry
-	doctype?: Doctype
+	doctype?: Doctype | string
 	recordId?: string
 }): BaseStonecropReturn | HSTStonecropReturn {
 	if (!options) options = {}
@@ -126,14 +133,14 @@ export function useStonecrop(options?: {
 	// Resolved schema with nested Doctype fields expanded
 	const resolvedSchema = ref<SchemaTypes[]>([])
 
-	// 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 as SchemaTypes[])
+	// Loading state for lazy-loaded doctypes
+	const isLoading = ref(false)
+	const error = ref<Error | null>(null)
+	const resolvedDoctype = ref<Doctype | undefined>()
+
+	// If doctype is a Doctype instance (not string), set resolved immediately
+	if (options?.doctype && typeof options.doctype !== 'string') {
+		resolvedDoctype.value = options.doctype
 	}
 
 	// Operation log state and methods - will be populated after stonecrop instance is created
@@ -280,7 +287,7 @@ export function useStonecrop(options?: {
 								? doctype.schema
 								: Array.from(doctype.schema)
 							: []
-						resolvedSchema.value = registry.resolveSchema(schemaArray as SchemaTypes[])
+						resolvedSchema.value = registry.resolveSchema(schemaArray)
 					}
 
 					if (recordId && recordId !== 'new') {
@@ -314,9 +321,62 @@ export function useStonecrop(options?: {
 		// Handle HST integration if doctype is provided explicitly
 		if (options.doctype) {
 			hstStore.value = stonecrop.value.getStore()
-			const doctype = options.doctype
 			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
+				const doctypeSlug = options.doctype
+				isLoading.value = true
+				error.value = null
+
+				try {
+					// Check if already in registry
+					doctype = registry.getDoctype(doctypeSlug)
+
+					if (!doctype && registry.getMeta) {
+						// Lazy-load via getMeta
+						const routeContext: RouteContext = {
+							path: `/${doctypeSlug}`,
+							segments: [doctypeSlug],
+						}
+						doctype = await registry.getMeta(routeContext)
+						if (doctype) {
+							registry.addDoctype(doctype)
+						}
+					}
+
+					if (!doctype) {
+						error.value = new Error(`Doctype '${doctypeSlug}' not found in registry and getMeta returned no result`)
+					}
+				} catch (e) {
+					error.value = e instanceof Error ? e : new Error(String(e))
+				} finally {
+					isLoading.value = false
+				}
+			} else {
+				// Doctype instance provided directly
+				doctype = options.doctype
+			}
+
+			// Set resolved doctype for consumers
+			resolvedDoctype.value = doctype
+
+			if (!doctype) {
+				// Error already set above, just return
+				return
+			}
+
+			// 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) {
@@ -344,7 +404,7 @@ export function useStonecrop(options?: {
 
 	// HST integration functions - always created but only populated when HST is available
 	const provideHSTPath = (fieldname: string, customRecordId?: string): string => {
-		const doctype = options.doctype || routerDoctype.value
+		const doctype = resolvedDoctype.value || routerDoctype.value
 		if (!doctype) return ''
 
 		const actualRecordId = customRecordId || options.recordId || routerRecordId.value || 'new'
@@ -352,7 +412,7 @@ export function useStonecrop(options?: {
 	}
 
 	const handleHSTChange = (changeData: HSTChangeData): void => {
-		const doctype = options.doctype || routerDoctype.value
+		const doctype = resolvedDoctype.value || routerDoctype.value
 		if (!hstStore.value || !stonecrop.value || !doctype) {
 			return
 		}
@@ -458,9 +518,11 @@ export function useStonecrop(options?: {
 		const payload: Record<string, any> = { ...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)) : []
-		) as SchemaTypes[]
+		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)
@@ -539,6 +601,9 @@ export function useStonecrop(options?: {
 			loadNestedData,
 			saveRecursive,
 			createNestedContext,
+			isLoading,
+			error,
+			resolvedDoctype,
 		} as HSTStonecropReturn
 	} else if (!options.doctype && registry?.router) {
 		// Router-based - return HST (will be populated after mount)
@@ -553,6 +618,9 @@ export function useStonecrop(options?: {
 			loadNestedData,
 			saveRecursive,
 			createNestedContext,
+			isLoading,
+			error,
+			resolvedDoctype,
 		} as HSTStonecropReturn
 	}
 

package/src/doctype.ts

@@ -1,7 +1,7 @@
+import type { SchemaTypes } from '@stonecrop/aform'
+import type { WorkflowMeta } from '@stonecrop/schema'
 import { List, Map } from 'immutable'
 import { Component } from 'vue'
-
-import type { SchemaTypes } from '@stonecrop/aform'
 import type { UnknownMachineConfig } from 'xstate'
 
 import type { ImmutableDoctype } from './types'
@@ -20,8 +20,8 @@ export type DoctypeConfig = {
 	tableName?: string
 	/** Field definitions */
 	fields?: SchemaTypes[]
-	/** Workflow configuration */
-	workflow?: UnknownMachineConfig
+	/** Workflow configuration (XState format or simple WorkflowMeta) */
+	workflow?: UnknownMachineConfig | WorkflowMeta
 	/** Actions and their field triggers */
 	actions?: Record<string, string[]>
 	/** Parent doctype for inheritance */
@@ -183,7 +183,7 @@ export default class Doctype {
 
 	/**
 	 * Returns the transitions available from a given workflow state, derived from the
-	 * doctype's XState workflow configuration.
+	 * doctype's workflow configuration. Supports both XState format and WorkflowMeta format.
 	 *
 	 * @param currentState - The state name to read transitions from
 	 * @returns Array of transition descriptors with `name` and `targetState`
@@ -197,7 +197,34 @@ export default class Doctype {
 	 * @public
 	 */
 	getAvailableTransitions(currentState: string): Array<{ name: string; targetState: string }> {
-		const states = this.workflow?.states
+		const workflow = this.workflow
+		if (!workflow) return []
+
+		// Check if this is WorkflowMeta format (states is an array) or XState format (states is an object)
+		if (Array.isArray(workflow.states)) {
+			// WorkflowMeta format: validate state exists and filter actions by allowedStates
+			const states = workflow.states
+			if (!states.includes(currentState)) return []
+
+			const actions = (workflow as WorkflowMeta).actions
+			if (!actions) return []
+
+			return Object.entries(actions)
+				.filter(([, actionDef]) => {
+					const allowedStates = actionDef.allowedStates
+					// If no allowedStates specified, action is available in all valid states
+					if (!allowedStates || allowedStates.length === 0) return true
+					return allowedStates.includes(currentState)
+				})
+				.map(([name]) => ({
+					name,
+					// WorkflowMeta doesn't define target states - transitions are handled server-side
+					targetState: currentState,
+				}))
+		}
+
+		// XState format: use the on property of the state
+		const states = workflow.states
 		if (!states) return []
 		const stateConfig = states[currentState]
 		if (!stateConfig?.on) return []
@@ -207,6 +234,40 @@ export default class Doctype {
 		}))
 	}
 
+	/**
+	 * Returns metadata for a specific action, if available.
+	 * Only works with WorkflowMeta format; returns undefined for XState format.
+	 *
+	 * @param actionName - The action name to get metadata for
+	 * @returns Action metadata or undefined
+	 *
+	 * @example
+	 * ```ts
+	 * const actionMeta = doctype.getActionMeta('submit')
+	 * // { label: 'Submit', handler: 'plan:submit', allowedStates: ['draft'] }
+	 * ```
+	 *
+	 * @public
+	 */
+	getActionMeta(
+		actionName: string
+	):
+		| {
+				label: string
+				handler: string
+				requiredFields?: string[]
+				allowedStates?: string[]
+				confirm?: boolean
+				args?: Record<string, unknown>
+		  }
+		| undefined {
+		const workflow = this.workflow
+		if (!workflow || !Array.isArray(workflow.states)) return undefined
+
+		const actions = (workflow as WorkflowMeta).actions
+		return actions?.[actionName]
+	}
+
 	/**
 	 * Converts the registered doctype string to a slug (kebab-case). The following conversions are made:
 	 * - It replaces camelCase and PascalCase with kebab-case strings

package/src/stonecrop.ts

@@ -1,4 +1,4 @@
-import type { DataClient } from '@stonecrop/schema'
+import type { DataClient, WorkflowMeta } from '@stonecrop/schema'
 import { reactive } from 'vue'
 
 import Doctype from './doctype'
@@ -400,10 +400,20 @@ export class Stonecrop {
 		const record = this.getRecordById(slug, recordId)
 		const status = record?.get('status') as string | undefined
 
-		const initialState =
-			typeof meta.workflow.initial === 'string'
-				? meta.workflow.initial
-				: Object.keys(meta.workflow.states ?? {})[0] ?? ''
+		// Handle both XState format and WorkflowMeta format
+		const workflow = meta.workflow
+		let initialState: string
+
+		if (Array.isArray(workflow.states)) {
+			// WorkflowMeta format: states is a string array
+			initialState = workflow.states[0] ?? ''
+		} else {
+			// XState format: states is an object, use initial or first key
+			initialState =
+				typeof (workflow as { initial?: unknown }).initial === 'string'
+					? (workflow as { initial: string }).initial
+					: Object.keys(workflow.states ?? {})[0] ?? ''
+		}
 
 		return status || initialState
 	}

package/src/types/index.ts

@@ -1,4 +1,4 @@
-import type { DataClient } from '@stonecrop/schema'
+import type { DataClient, WorkflowMeta } from '@stonecrop/schema'
 import type { SchemaTypes } from '@stonecrop/aform'
 import { List, Map } from 'immutable'
 import type { Component } from 'vue'
@@ -16,7 +16,7 @@ import type { RouteContext } from './registry'
  */
 export type ImmutableDoctype = {
 	readonly schema?: List<SchemaTypes> // TODO: allow schema to be a function
-	readonly workflow?: UnknownMachineConfig | AnyStateNodeConfig
+	readonly workflow?: UnknownMachineConfig | AnyStateNodeConfig | WorkflowMeta
 	readonly actions?: Map<string, string[]>
 }
 
@@ -27,7 +27,7 @@ export type ImmutableDoctype = {
 export type MutableDoctype = {
 	doctype?: string
 	schema?: SchemaTypes[] // TODO: allow schema to be a function
-	workflow?: UnknownMachineConfig | AnyStateNodeConfig
+	workflow?: UnknownMachineConfig | AnyStateNodeConfig | WorkflowMeta
 	actions?: Record<string, string[]>
 }