@stonecrop/stonecrop 0.10.12 → 0.10.13

package/src/stonecrop.ts

@@ -1,3 +1,10 @@
+import {
+	type DoctypeManySchema,
+	type DoctypeOneSchema,
+	type DoctypeSchema,
+	type SchemaTypes,
+	isDoctypeMany,
+} from '@stonecrop/aform'
 import type { DataClient } from '@stonecrop/schema'
 import { reactive } from 'vue'
 
@@ -7,28 +14,21 @@ import { createHST, type HSTNode } from './stores/hst'
 import { useOperationLogStore } from './stores/operation-log'
 import type { OperationLogConfig } from './types/operation-log'
 import type { RouteContext } from './types/registry'
+import type { StonecropOptions } from './types/stonecrop'
 
 /**
- * Options for constructing a Stonecrop instance directly.
- * When using the Vue plugin, pass these via `InstallOptions` instead.
+ * Main Stonecrop class with HST integration and built-in Operation Log
  * @public
  */
-export interface StonecropOptions {
+export class Stonecrop {
 	/**
-	 * Data client for fetching doctype metadata and records.
-	 * Use \@stonecrop/graphql-client's StonecropClient for GraphQL backends,
-	 * or implement DataClient for custom data sources.
-	 *
-	 * Can be set later via `setClient()` for deferred configuration.
+	 * Singleton instance of Stonecrop. Only one Stonecrop instance can exist
+	 * per application, ensuring consistent HST state and registry access.
+	 * Subsequent constructor calls return this instance instead of creating new ones.
+	 * @internal
 	 */
-	client?: DataClient
-}
+	static _root: Stonecrop
 
-/**
- * Main Stonecrop class with HST integration and built-in Operation Log
- * @public
- */
-export class Stonecrop {
 	private hstStore: HSTNode
 	private _operationLogStore?: ReturnType<typeof useOperationLogStore>
 	private _operationLogConfig?: Partial<OperationLogConfig>
@@ -38,12 +38,17 @@ export class Stonecrop {
 	readonly registry: Registry
 
 	/**
-	 * Creates a new Stonecrop instance with HST integration
+	 * Creates a new Stonecrop instance with HST integration (singleton pattern)
 	 * @param registry - The Registry instance containing doctype definitions
 	 * @param operationLogConfig - Optional configuration for the operation log
 	 * @param options - Options including the data client (can be set later via setClient)
 	 */
 	constructor(registry: Registry, operationLogConfig?: Partial<OperationLogConfig>, options?: StonecropOptions) {
+		if (Stonecrop._root) {
+			return Stonecrop._root
+		}
+		Stonecrop._root = this
+
 		this.registry = registry
 
 		// Store config for lazy initialization
@@ -417,4 +422,130 @@ export class Stonecrop {
 
 		return status || initialState
 	}
+
+	/**
+	 * Collect a record payload with all nested doctype fields from HST
+	 * @param doctype - The doctype metadata
+	 * @param recordId - The record ID to collect
+	 * @returns The complete record payload ready for API submission
+	 * @public
+	 */
+	collectRecordPayload(doctype: Doctype, recordId: string): Record<string, any> {
+		const recordPath = `${doctype.slug}.${recordId}`
+		const recordData = this.hstStore.get(recordPath) || {}
+
+		const payload: Record<string, any> = { ...recordData }
+
+		const schemaArray = doctype.schema
+			? Array.isArray(doctype.schema)
+				? doctype.schema
+				: Array.from(doctype.schema)
+			: []
+		const resolved = this.registry.resolveSchema(schemaArray)
+
+		const doctypeFields = resolved.filter(
+			field =>
+				'fieldtype' in field &&
+				field.fieldtype === 'Doctype' &&
+				!isDoctypeMany(field as DoctypeSchema) &&
+				'schema' in field &&
+				Array.isArray(field.schema)
+		)
+
+		for (const field of doctypeFields) {
+			const doctypeField = field as DoctypeOneSchema
+			const fieldPath = `${recordPath}.${doctypeField.fieldname}`
+			const nestedData = collectNestedData(doctypeField.schema!, fieldPath, this.hstStore)
+			payload[doctypeField.fieldname] = nestedData
+		}
+
+		const doctypeManyFields = resolved.filter(
+			field => 'fieldtype' in field && field.fieldtype === 'Doctype' && isDoctypeMany(field as DoctypeSchema)
+		)
+
+		for (const field of doctypeManyFields) {
+			const doctypeField = field as DoctypeManySchema
+			const fieldPath = `${recordPath}.${doctypeField.fieldname}`
+			const arrayData = this.hstStore.get(fieldPath)
+			if (Array.isArray(arrayData)) {
+				payload[doctypeField.fieldname] = arrayData
+			}
+		}
+
+		return payload
+	}
+
+	/**
+	 * Load nested data from HST or initialize with defaults
+	 * @param parentPath - The HST path to check for existing data
+	 * @param childDoctype - The child doctype metadata
+	 * @param _recordId - Optional record ID to load
+	 * @returns The loaded or initialized data
+	 * @public
+	 */
+	loadNestedData(parentPath: string, childDoctype: Doctype, _recordId?: string): Record<string, any> {
+		// Check if data already exists in HST
+		const existingData = this.hstStore.get(parentPath)
+		if (existingData && typeof existingData === 'object') {
+			return existingData as Record<string, any>
+		}
+
+		// TODO: If recordId provided and no HST data, fetch from API using this._client
+		// For now, always fall through to initialize new record
+
+		// Resolve schema and initialize with defaults
+		const schemaArray = childDoctype.schema
+			? Array.isArray(childDoctype.schema)
+				? childDoctype.schema
+				: Array.from(childDoctype.schema)
+			: []
+		const resolvedSchema = this.registry.resolveSchema(schemaArray)
+		return this.registry.initializeRecord(resolvedSchema)
+	}
 }
+
+/**
+ * Recursively collect nested data from HST using pre-resolved schemas
+ * @param resolvedSchema - The already-resolved schema (with nested schemas embedded)
+ * @param basePath - The base path in HST (e.g., "customer.123.address")
+ * @param hstStore - The HST store instance
+ * @returns The collected data object
+ * @public
+ */
+function collectNestedData(resolvedSchema: SchemaTypes[], basePath: string, hstStore: HSTNode): Record<string, any> {
+	const data = hstStore.get(basePath) || {}
+	const payload: Record<string, any> = { ...data }
+
+	const doctypeFields = resolvedSchema.filter(
+		field =>
+			'fieldtype' in field &&
+			field.fieldtype === 'Doctype' &&
+			!isDoctypeMany(field as DoctypeSchema) &&
+			'schema' in field &&
+			Array.isArray(field.schema)
+	)
+
+	for (const field of doctypeFields) {
+		const doctypeField = field as DoctypeOneSchema
+		const fieldPath = `${basePath}.${doctypeField.fieldname}`
+		const nestedData = collectNestedData(doctypeField.schema!, fieldPath, hstStore)
+		payload[doctypeField.fieldname] = nestedData
+	}
+
+	const doctypeManyFields = resolvedSchema.filter(
+		field => 'fieldtype' in field && field.fieldtype === 'Doctype' && isDoctypeMany(field as DoctypeSchema)
+	)
+
+	for (const field of doctypeManyFields) {
+		const doctypeField = field as DoctypeManySchema
+		const fieldPath = `${basePath}.${doctypeField.fieldname}`
+		const arrayData = hstStore.get(fieldPath)
+		if (Array.isArray(arrayData)) {
+			payload[doctypeField.fieldname] = arrayData
+		}
+	}
+
+	return payload
+}
+
+export { collectNestedData }

package/src/types/composable.ts

@@ -0,0 +1,245 @@
+import { SchemaTypes } from '@stonecrop/aform'
+import type { Ref, ComputedRef } from 'vue'
+
+import type Doctype from '../doctype'
+import type { HSTNode } from '../stores/hst'
+import type { HSTOperation, OperationLogConfig, OperationLogSnapshot } from './operation-log'
+
+/**
+ * Operation Log API - nested object containing all operation log functionality
+ * @public
+ */
+export type OperationLogAPI = {
+	/**
+	 * List of all recorded operations in the log.
+	 * Each operation represents a state change that can be undone/redone.
+	 */
+	operations: Ref<HSTOperation[]>
+	/**
+	 * Current position in the operation log.
+	 * -1 means no operations, 0 means at first operation, etc.
+	 */
+	currentIndex: Ref<number>
+	/**
+	 * Computed snapshot of undo/redo state.
+	 * Use this for UI indicators (buttons, menu state).
+	 */
+	undoRedoState: ComputedRef<{
+		canUndo: boolean
+		canRedo: boolean
+		undoCount: number
+		redoCount: number
+		currentIndex: number
+	}>
+	/**
+	 * Whether undo is currently available.
+	 * True when there are operations that can be undone.
+	 */
+	canUndo: ComputedRef<boolean>
+	/**
+	 * Whether redo is currently available.
+	 * True when there are undone operations that can be redone.
+	 */
+	canRedo: ComputedRef<boolean>
+	/**
+	 * Number of operations available to undo.
+	 */
+	undoCount: ComputedRef<number>
+	/**
+	 * Number of operations available to redo.
+	 */
+	redoCount: ComputedRef<number>
+	/**
+	 * Undo the last operation.
+	 * @param hstStore - The HST node to apply the inverse operation to
+	 * @returns True if undo succeeded, false if nothing to undo
+	 */
+	undo: (hstStore: HSTNode) => boolean
+	/**
+	 * Redo the last undone operation.
+	 * @param hstStore - The HST node to apply the operation to
+	 * @returns True if redo succeeded, false if nothing to redo
+	 */
+	redo: (hstStore: HSTNode) => boolean
+	/**
+	 * Start batching multiple operations together.
+	 * Call before a series of changes that should be undone/redone as a unit.
+	 */
+	startBatch: () => void
+	/**
+	 * Commit the current batch of operations.
+	 * @param description - Optional description for the batch
+	 * @returns The batch operation ID, or null if no batch in progress
+	 */
+	commitBatch: (description?: string) => string | null
+	/**
+	 * Cancel the current batch without committing.
+	 * Discards all operations added since startBatch().
+	 */
+	cancelBatch: () => void
+	/**
+	 * Clear all operations from the log.
+	 * Resets the log to its initial empty state.
+	 */
+	clear: () => void
+	/**
+	 * Get all operations for a specific doctype.
+	 * @param doctype - The doctype name to filter by
+	 * @param recordId - Optional record ID to further filter
+	 * @returns Array of matching operations
+	 */
+	getOperationsFor: (doctype: string, recordId?: string) => HSTOperation[]
+	/**
+	 * Get a serializable snapshot of the operation log.
+	 * Use for debugging, logging, or state persistence.
+	 * @returns Snapshot containing operations and current index
+	 */
+	getSnapshot: () => OperationLogSnapshot
+	/**
+	 * Mark an operation as irreversible.
+	 * Irreversible operations cannot be undone.
+	 * @param operationId - The operation ID to mark
+	 * @param reason - Human-readable reason why it cannot be undone
+	 */
+	markIrreversible: (operationId: string, reason: string) => void
+	/**
+	 * Log a custom action (non-HST operation).
+	 * Use for tracking server calls, external side effects, etc.
+	 * @param doctype - The doctype this action relates to
+	 * @param actionName - Name of the action (e.g., 'save', 'submit')
+	 * @param recordIds - Optional array of affected record IDs
+	 * @param result - Optional result status
+	 * @param error - Optional error message if result is 'failure'
+	 * @returns The logged operation ID
+	 */
+	logAction: (
+		doctype: string,
+		actionName: string,
+		recordIds?: string[],
+		result?: 'success' | 'failure' | 'pending',
+		error?: string
+	) => string
+	/**
+	 * Configure operation log options.
+	 * @param options - Partial configuration to merge with existing settings
+	 */
+	configure: (options: Partial<OperationLogConfig>) => void
+}
+
+/**
+ * Base Stonecrop composable return type - includes operation log functionality
+ * @public
+ */
+export type BaseStonecropReturn = {
+	/**
+	 * Reactive reference to the Stonecrop singleton instance.
+	 * Use this to access class methods like `getRecord()`, `addRecord()`, `runAction()`.
+	 */
+	stonecrop: Ref<Stonecrop | undefined>
+	/**
+	 * Operation log API for undo/redo functionality.
+	 * Use `operationLog.undo()` and `operationLog.redo()` for user-triggered operations.
+	 * Use `operationLog.startBatch()` / `operationLog.commitBatch()` for grouping operations.
+	 */
+	operationLog: OperationLogAPI
+}
+
+/**
+ * HST-enabled Stonecrop composable return type
+ * @public
+ */
+export type HSTStonecropReturn = BaseStonecropReturn & {
+	/**
+	 * Generates a fully-qualified HST path for a field.
+	 * Use this in nested components to create paths like "customer.123.address".
+	 * @param fieldname - The field name to append to the path
+	 * @param recordId - Optional record ID (defaults to current record)
+	 * @returns The full HST path string
+	 */
+	provideHSTPath: (fieldname: string, recordId?: string) => string
+	/**
+	 * Handles a field value change and updates HST.
+	 * Call this from form input handlers to persist changes to the store.
+	 * @param changeData - Object containing path, value, fieldname, and optional recordId
+	 */
+	handleHSTChange: (changeData: HSTChangeData) => void
+	/**
+	 * Reactive reference to the HST node for this doctype/record.
+	 * Use this to read current form state or subscribe to changes.
+	 */
+	hstStore: Ref<HSTNode | undefined>
+	/**
+	 * Reactive form data bound to HST.
+	 * Use this as the v-model target for form inputs. Changes sync to hstStore.
+	 */
+	formData: Ref<Record<string, any>>
+	/**
+	 * Resolved schema with nested Doctype fields expanded.
+	 * Use this to iterate over fields for rendering, excluding nested doctypes handled separately.
+	 */
+	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
+	 */
+	loadNestedData: (parentPath: string, childDoctype: Doctype, recordId?: string) => Record<string, any>
+	/**
+	 * 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.
+	 * @param doctype - The doctype metadata
+	 * @param recordId - The record ID to collect
+	 * @returns The complete record payload ready for API submission
+	 */
+	collectRecordPayload: (doctype: Doctype, recordId: string) => Record<string, any>
+	/**
+	 * Creates a nested context for a child 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
+	 * @returns Scoped provideHSTPath and handleHSTChange functions
+	 */
+	createNestedContext: (
+		basePath: string,
+		childDoctype: Doctype
+	) => {
+		provideHSTPath: (fieldname: string) => string
+		handleHSTChange: (changeData: HSTChangeData) => void
+	}
+	/**
+	 * Loading state for async doctype resolution.
+	 * True while fetching doctype by slug string from registry.
+	 */
+	isLoading: Ref<boolean>
+	/**
+	 * Error state for doctype resolution failures.
+	 * Set when doctype slug lookup fails.
+	 */
+	error: Ref<Error | null>
+	/**
+	 * Resolved doctype instance.
+	 * Available immediately if Doctype instance passed, after async resolution if slug string passed.
+	 */
+	resolvedDoctype: Ref<Doctype | undefined>
+}
+
+// Import Stonecrop class for the BaseStonecropReturn type (circular reference handled via import)
+import type { Stonecrop } from '../stonecrop'
+
+/**
+ * HST Change data structure
+ * @public
+ */
+export type HSTChangeData = {
+	/** Full HST path to the changed field */
+	path: string
+	/** New value for the field */
+	value: any
+	/** Field name that changed */
+	fieldname: string
+	/** Optional record ID */
+	recordId?: string
+}

package/src/types/doctype.ts

@@ -0,0 +1,60 @@
+import type { SchemaTypes } from '@stonecrop/aform'
+import type { WorkflowMeta } from '@stonecrop/schema'
+import { List, Map } from 'immutable'
+import type { AnyStateNodeConfig, UnknownMachineConfig } from 'xstate'
+
+/**
+ * Immutable Doctype type for Stonecrop instances
+ * @public
+ */
+export type ImmutableDoctype = {
+	readonly schema?: List<SchemaTypes>
+	readonly workflow?: UnknownMachineConfig | AnyStateNodeConfig | WorkflowMeta
+	readonly actions?: Map<string, string[]>
+}
+
+/**
+ * Mutable Doctype type for Stonecrop instances
+ * @public
+ */
+export type MutableDoctype = {
+	doctype?: string
+	schema?: SchemaTypes[]
+	workflow?: UnknownMachineConfig | AnyStateNodeConfig | WorkflowMeta
+	actions?: Record<string, string[]>
+}
+
+/**
+ * Schema type for Stonecrop instances
+ * @public
+ */
+export type Schema = {
+	doctype: string
+	schema: List<SchemaTypes>
+}
+
+/**
+ * Plain object representation of doctype configuration for serialization/API responses.
+ * Compatible with the DoctypeMeta type from \@stonecrop/schema.
+ * @public
+ */
+export type DoctypeConfig = {
+	/** Display name of the doctype */
+	name: string
+	/** URL-friendly slug (kebab-case) */
+	slug?: string
+	/** Database table name */
+	tableName?: string
+	/** Field definitions */
+	fields?: SchemaTypes[]
+	/** Workflow configuration (XState format or simple WorkflowMeta) */
+	workflow?: UnknownMachineConfig | WorkflowMeta
+	/** Actions and their field triggers */
+	actions?: Record<string, string[]>
+	/** Parent doctype for inheritance */
+	inherits?: string
+	/** Doctype to use for list views */
+	listDoctype?: string
+	/** Parent doctype for child tables */
+	parentDoctype?: string
+}

package/src/types/index.ts

@@ -1,76 +1,9 @@
-import type { DataClient, WorkflowMeta } from '@stonecrop/schema'
-import type { SchemaTypes } from '@stonecrop/aform'
-import { List, Map } from 'immutable'
-import type { Component } from 'vue'
-import type { Router } from 'vue-router'
-import type { AnyStateNodeConfig, UnknownMachineConfig } from 'xstate'
-
-import type Doctype 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 = {
-	readonly schema?: List<SchemaTypes> // TODO: allow schema to be a function
-	readonly workflow?: UnknownMachineConfig | AnyStateNodeConfig | WorkflowMeta
-	readonly actions?: Map<string, string[]>
-}
-
-/**
- * Mutable Doctype type for Stonecrop instances
- * @public
- */
-export type MutableDoctype = {
-	doctype?: string
-	schema?: SchemaTypes[] // TODO: allow schema to be a function
-	workflow?: UnknownMachineConfig | AnyStateNodeConfig | WorkflowMeta
-	actions?: Record<string, string[]>
-}
-
-/**
- * Schema type for Stonecrop instances
- * @public
- */
-export type Schema = {
-	doctype: string
-	schema: List<SchemaTypes>
-}
-
-/**
- * Install options for Stonecrop Vue plugin
- * @public
- */
-export type InstallOptions = {
-	router?: Router
-	components?: Record<string, Component>
-	getMeta?: (routeContext: RouteContext) => Doctype | Promise<Doctype>
-	/**
-	 * Data client for fetching doctype metadata and records.
-	 * Use \@stonecrop/graphql-client's StonecropClient for GraphQL backends,
-	 * or implement DataClient for custom data sources.
-	 *
-	 * Can be set later via `useStonecropRegistry().setClient()` for deferred configuration.
-	 *
-	 * @example
-	 * ```ts
-	 * import { StonecropClient } from '@stonecrop/graphql-client'
-	 *
-	 * const client = new StonecropClient({ endpoint: '/graphql' })
-	 * app.use(StonecropPlugin, { client })
-	 * ```
-	 */
-	client?: DataClient
-	/** 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
+// Re-export all type files
+export * from './composable'
+export * from './doctype'
 export * from './field-triggers'
-export * from './registry'
 export * from './operation-log'
+export * from './plugin'
+export * from './registry'
+export * from './schema-validator'
+export * from './stonecrop'

package/src/types/plugin.ts

@@ -0,0 +1,38 @@
+import type { DataClient } from '@stonecrop/schema'
+import type { Component } from 'vue'
+import type { Router } from 'vue-router'
+
+import type Doctype from '../doctype'
+import type Registry from '../registry'
+import type { Stonecrop } from '../stonecrop'
+import type { RouteContext } from './registry'
+
+/**
+ * Install options for Stonecrop Vue plugin
+ * @public
+ */
+export type InstallOptions = {
+	router?: Router
+	components?: Record<string, Component>
+	getMeta?: (routeContext: RouteContext) => Doctype | Promise<Doctype>
+	/**
+	 * Data client for fetching doctype metadata and records.
+	 * Use \@stonecrop/graphql-client's StonecropClient for GraphQL backends,
+	 * or implement DataClient for custom data sources.
+	 *
+	 * Can be set later via `useStonecropRegistry().setClient()` for deferred configuration.
+	 *
+	 * @example
+	 * ```ts
+	 * import { StonecropClient } from '@stonecrop/graphql-client'
+	 *
+	 * const client = new StonecropClient({ endpoint: '/graphql' })
+	 * app.use(StonecropPlugin, { client })
+	 * ```
+	 */
+	client?: DataClient
+	/** 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>
+}

package/src/types/schema-validator.ts

@@ -0,0 +1,67 @@
+import type Registry from '../registry'
+
+/**
+ * Validation severity levels
+ * @public
+ */
+export enum ValidationSeverity {
+	/** Blocking error that prevents save */
+	ERROR = 'error',
+	/** Advisory warning that allows save */
+	WARNING = 'warning',
+	/** Informational message */
+	INFO = 'info',
+}
+
+/**
+ * Validation issue
+ * @public
+ */
+export interface ValidationIssue {
+	/** Severity level */
+	severity: ValidationSeverity
+	/** Validation rule that failed */
+	rule: string
+	/** Human-readable message */
+	message: string
+	/** Doctype name */
+	doctype?: string
+	/** Field name if applicable */
+	fieldname?: string
+	/** Additional context */
+	context?: Record<string, unknown>
+}
+
+/**
+ * Validation result
+ * @public
+ */
+export interface ValidationResult {
+	/** Whether validation passed (no blocking errors) */
+	valid: boolean
+	/** List of validation issues */
+	issues: ValidationIssue[]
+	/** Count of errors */
+	errorCount: number
+	/** Count of warnings */
+	warningCount: number
+	/** Count of info messages */
+	infoCount: number
+}
+
+/**
+ * Schema validator options
+ * @public
+ */
+export interface ValidatorOptions {
+	/** Registry instance for doctype lookups */
+	registry?: Registry
+	/** Whether to validate Link field targets */
+	validateLinkTargets?: boolean
+	/** Whether to validate workflow reachability */
+	validateWorkflows?: boolean
+	/** Whether to validate action registration */
+	validateActions?: boolean
+	/** Whether to validate required schema properties */
+	validateRequiredProperties?: boolean
+}