@stonecrop/stonecrop 0.10.11 → 0.10.13

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
+}

package/src/types/stonecrop.ts

@@ -0,0 +1,17 @@
+import type { DataClient } from '@stonecrop/schema'
+
+/**
+ * Options for constructing a Stonecrop instance directly.
+ * When using the Vue plugin, pass these via `InstallOptions` instead.
+ * @public
+ */
+export interface StonecropOptions {
+	/**
+	 * 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.
+	 */
+	client?: DataClient
+}