@stonecrop/stonecrop 0.10.4 → 0.10.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonecrop/stonecrop",
-  "version": "0.10.4",
+  "version": "0.10.6",
   "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.4"
+    "@stonecrop/schema": "0.10.6"
   },
   "peerDependencies": {
     "pinia": "^3.0.4",
@@ -60,9 +60,9 @@
     "vue-router": "^5.0.2",
     "vite": "^7.3.1",
     "vitest": "^4.0.18",
-    "@stonecrop/aform": "0.10.4",
-    "stonecrop-rig": "0.7.0",
-    "@stonecrop/atable": "0.10.4"
+    "@stonecrop/aform": "0.10.6",
+    "@stonecrop/atable": "0.10.6",
+    "stonecrop-rig": "0.7.0"
   },
   "description": "Schema-driven framework with XState workflows and HST state management",
   "publishConfig": {

package/src/composables/stonecrop.ts

@@ -2,7 +2,7 @@ import { inject, onMounted, Ref, ref, watch, provide, computed, ComputedRef } fr
 
 import Registry from '../registry'
 import { Stonecrop } from '../stonecrop'
-import DoctypeMeta from '../doctype'
+import Doctype from '../doctype'
 import type { HSTNode } from '../stores/hst'
 import { RouteContext } from '../types/registry'
 import { storeToRefs } from 'pinia'
@@ -65,11 +65,11 @@ export type HSTStonecropReturn = BaseStonecropReturn & {
 	hstStore: Ref<HSTNode | undefined>
 	formData: Ref<Record<string, any>>
 	resolvedSchema: Ref<SchemaTypes[]>
-	loadNestedData: (parentPath: string, childDoctype: DoctypeMeta, recordId?: string) => Record<string, any>
-	saveRecursive: (doctype: DoctypeMeta, recordId: string) => Promise<Record<string, any>>
+	loadNestedData: (parentPath: string, childDoctype: Doctype, recordId?: string) => Record<string, any>
+	saveRecursive: (doctype: Doctype, recordId: string) => Promise<Record<string, any>>
 	createNestedContext: (
 		basePath: string,
-		childDoctype: DoctypeMeta
+		childDoctype: Doctype
 	) => {
 		provideHSTPath: (fieldname: string) => string
 		handleHSTChange: (changeData: HSTChangeData) => void
@@ -102,17 +102,13 @@ export function useStonecrop(): BaseStonecropReturn | HSTStonecropReturn
  * @returns Stonecrop instance with full HST integration utilities
  * @public
  */
-export function useStonecrop(options: {
-	registry?: Registry
-	doctype: DoctypeMeta
-	recordId?: string
-}): HSTStonecropReturn
+export function useStonecrop(options: { registry?: Registry; doctype: Doctype; recordId?: string }): HSTStonecropReturn
 /**
  * @public
  */
 export function useStonecrop(options?: {
 	registry?: Registry
-	doctype?: DoctypeMeta
+	doctype?: Doctype
 	recordId?: string
 }): BaseStonecropReturn | HSTStonecropReturn {
 	if (!options) options = {}
@@ -124,7 +120,7 @@ export function useStonecrop(options?: {
 	const formData = ref<Record<string, any>>({})
 
 	// Use refs for router-loaded doctype to maintain reactivity
-	const routerDoctype = ref<DoctypeMeta | undefined>()
+	const routerDoctype = ref<Doctype | undefined>()
 	const routerRecordId = ref<string | undefined>()
 
 	// Resolved schema with nested Doctype fields expanded
@@ -418,7 +414,7 @@ export function useStonecrop(options?: {
 	 * @param recordId - Optional record ID to load
 	 * @returns Promise resolving to the loaded or initialized data
 	 */
-	const loadNestedData = (parentPath: string, childDoctype: DoctypeMeta, recordId?: string): Record<string, any> => {
+	const loadNestedData = (parentPath: string, childDoctype: Doctype, recordId?: string): Record<string, any> => {
 		if (!stonecrop.value) {
 			return initializeNewRecord(childDoctype)
 		}
@@ -450,7 +446,7 @@ export function useStonecrop(options?: {
 	 * @param recordId - The record ID to save
 	 * @returns The complete save payload
 	 */
-	const saveRecursive = (doctype: DoctypeMeta, recordId: string): Record<string, any> => {
+	const saveRecursive = (doctype: Doctype, recordId: string): Record<string, any> => {
 		if (!hstStore.value || !stonecrop.value) {
 			throw new Error('HST store not initialized')
 		}
@@ -487,7 +483,7 @@ export function useStonecrop(options?: {
 	 * @param _childDoctype - The child doctype metadata (unused but kept for API consistency)
 	 * @returns Object with scoped provideHSTPath and handleHSTChange
 	 */
-	const createNestedContext = (basePath: string, _childDoctype: DoctypeMeta) => {
+	const createNestedContext = (basePath: string, _childDoctype: Doctype) => {
 		const nestedProvideHSTPath = (fieldname: string): string => {
 			return `${basePath}.${fieldname}`
 		}
@@ -570,7 +566,7 @@ export function useStonecrop(options?: {
 /**
  * Initialize new record structure based on doctype schema
  */
-function initializeNewRecord(doctype: DoctypeMeta): Record<string, any> {
+function initializeNewRecord(doctype: Doctype): Record<string, any> {
 	const initialData: Record<string, any> = {}
 
 	if (!doctype.schema) {
@@ -610,7 +606,7 @@ function initializeNewRecord(doctype: DoctypeMeta): Record<string, any> {
  * Setup deep reactivity between form data and HST store
  */
 function setupDeepReactivity(
-	doctype: DoctypeMeta,
+	doctype: Doctype,
 	recordId: string,
 	formData: Ref<Record<string, any>>,
 	hstStore: HSTNode

package/src/doctype.ts

@@ -1,12 +1,42 @@
+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'
 
 /**
- * Doctype Meta class
+ * 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 */
+	workflow?: UnknownMachineConfig
+	/** 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
+}
+
+/**
+ * Doctype runtime class with Immutable.js collections for HST change tracking.
  * @public
  */
-export default class DoctypeMeta {
+export default class Doctype {
 	/**
 	 * The doctype name
 	 * @public
@@ -52,7 +82,7 @@ export default class DoctypeMeta {
 	readonly component?: Component
 
 	/**
-	 * Creates a new DoctypeMeta instance
+	 * Creates a new Doctype instance
 	 * @param doctype - The doctype name
 	 * @param schema - The doctype schema definition
 	 * @param workflow - The doctype workflow configuration (XState machine)
@@ -73,6 +103,84 @@ export default class DoctypeMeta {
 		this.component = component
 	}
 
+	/**
+	 * Creates a Doctype instance from a plain configuration object.
+	 * Handles conversion of arrays to Immutable.js collections internally.
+	 *
+	 * This is the recommended way to create a Doctype from API responses
+	 * or configuration files, as it encapsulates the Immutable.js construction
+	 * that the framework uses internally.
+	 *
+	 * @param config - Plain object with doctype configuration (typically from API response)
+	 * @returns A new Doctype instance with Immutable.js collections
+	 *
+	 * @example
+	 * ```ts
+	 * // From an API response
+	 * const response = await client.getMeta({ doctype: 'plan' })
+	 * const doctype = Doctype.fromObject(response)
+	 * registry.addDoctype(doctype)
+	 * ```
+	 *
+	 * @example
+	 * ```ts
+	 * // From a configuration object
+	 * const planDoctype = Doctype.fromObject({
+	 *   name: 'Plan',
+	 *   fields: [
+	 *     { fieldname: 'title', label: 'Title', fieldtype: 'Data' },
+	 *     { fieldname: 'status', label: 'Status', fieldtype: 'Data' },
+	 *   ],
+	 *   workflow: {
+	 *     id: 'plan',
+	 *     initial: 'draft',
+	 *     states: { draft: {}, submitted: {} }
+	 *   }
+	 * })
+	 * ```
+	 *
+	 * @public
+	 */
+	static fromObject(config: DoctypeConfig): 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)
+	}
+
+	/**
+	 * Returns the schema as a plain array for use with components that expect
+	 * plain JavaScript arrays (e.g., AForm, ATable).
+	 *
+	 * @returns Array of schema fields
+	 *
+	 * @example
+	 * ```ts
+	 * const schemaArray = doctype.getSchemaArray()
+	 * // Use with AForm
+	 * <AForm :schema="schemaArray" v-model:data="formData" />
+	 * ```
+	 *
+	 * @public
+	 */
+	getSchemaArray(): SchemaTypes[] {
+		if (!this.schema) return []
+		return this.schema.toArray()
+	}
+
+	/**
+	 * Returns the actions as a plain object for use with components that expect
+	 * plain JavaScript objects.
+	 *
+	 * @returns Object mapping action names to field trigger arrays
+	 *
+	 * @public
+	 */
+	getActionsObject(): Record<string, string[]> {
+		if (!this.actions) return {}
+		return this.actions.toObject()
+	}
+
 	/**
 	 * Returns the transitions available from a given workflow state, derived from the
 	 * doctype's XState workflow configuration.
@@ -109,7 +217,7 @@ export default class DoctypeMeta {
 	 *
 	 * @example
 	 * ```ts
-	 * const doctype = new DoctypeMeta('TaskItem', schema, workflow, actions
+	 * const doctype = new Doctype('TaskItem', schema, workflow, actions)
 	 * console.log(doctype.slug) // 'task-item'
 	 * ```
 	 *

package/src/index.ts

@@ -3,7 +3,7 @@ export type * from '@stonecrop/atable/types'
 
 import { useStonecrop } from './composables/stonecrop'
 import { useOperationLog, useUndoRedoShortcuts, withBatch } from './composables/operation-log'
-import DoctypeMeta from './doctype'
+import Doctype, { type DoctypeConfig } from './doctype'
 import {
 	getGlobalTriggerEngine,
 	markOperationIrreversible,
@@ -36,7 +36,8 @@ export type { ValidationIssue, ValidationResult, ValidatorOptions } from './sche
 export { ValidationSeverity } from './schema-validator'
 
 export {
-	DoctypeMeta,
+	Doctype,
+	DoctypeConfig,
 	Registry,
 	Stonecrop,
 	StonecropOptions,

package/src/registry.ts

@@ -1,7 +1,7 @@
 import type { SchemaTypes } from '@stonecrop/aform'
 import { Router } from 'vue-router'
 
-import DoctypeMeta from './doctype'
+import Doctype from './doctype'
 import { getGlobalTriggerEngine } from './field-triggers'
 import { RouteContext } from './types/registry'
 
@@ -24,9 +24,9 @@ export default class Registry {
 
 	/**
 	 * The registry property contains a collection of doctypes
-	 * @see {@link DoctypeMeta}
+	 * @see {@link Doctype}
 	 */
-	readonly registry: Record<string, DoctypeMeta>
+	readonly registry: Record<string, Doctype>
 
 	/**
 	 * The Vue router instance
@@ -39,7 +39,7 @@ export default class Registry {
 	 * @param router - Optional Vue router instance for route management
 	 * @param getMeta - Optional function to fetch doctype metadata from an API
 	 */
-	constructor(router?: Router, getMeta?: (routeContext: RouteContext) => DoctypeMeta | Promise<DoctypeMeta>) {
+	constructor(router?: Router, getMeta?: (routeContext: RouteContext) => Doctype | Promise<Doctype>) {
 		if (Registry._root) {
 			return Registry._root
 		}
@@ -52,17 +52,17 @@ export default class Registry {
 
 	/**
 	 * The getMeta function fetches doctype metadata from an API based on route context
-	 * @see {@link DoctypeMeta}
+	 * @see {@link Doctype}
 	 */
-	getMeta?: (routeContext: RouteContext) => DoctypeMeta | Promise<DoctypeMeta>
+	getMeta?: (routeContext: RouteContext) => Doctype | Promise<Doctype>
 
 	/**
 	 * Get doctype metadata
 	 * @param doctype - The doctype to fetch metadata for
 	 * @returns The doctype metadata
-	 * @see {@link DoctypeMeta}
+	 * @see {@link Doctype}
 	 */
-	addDoctype(doctype: DoctypeMeta) {
+	addDoctype(doctype: Doctype) {
 		if (!(doctype.slug in this.registry)) {
 			this.registry[doctype.slug] = doctype
 		}
@@ -153,7 +153,7 @@ export default class Registry {
 				'options' in field &&
 				typeof field.options === 'string'
 			) {
-				const doctypeSlug = field.options as string
+				const doctypeSlug = field.options
 
 				// Circular reference protection
 				if (seen.has(doctypeSlug)) {
@@ -275,10 +275,10 @@ export default class Registry {
 	/**
 	 * Get a registered doctype by slug
 	 * @param slug - The doctype slug to look up
-	 * @returns The DoctypeMeta instance if found, or undefined
+	 * @returns The Doctype instance if found, or undefined
 	 * @public
 	 */
-	getDoctype(slug: string): DoctypeMeta | undefined {
+	getDoctype(slug: string): Doctype | undefined {
 		return this.registry[slug]
 	}
 

package/src/stonecrop.ts

@@ -1,7 +1,7 @@
 import type { DataClient } from '@stonecrop/schema'
 import { reactive } from 'vue'
 
-import DoctypeMeta from './doctype'
+import Doctype from './doctype'
 import Registry from './registry'
 import { createHST, type HSTNode } from './stores/hst'
 import { useOperationLogStore } from './stores/operation-log'
@@ -119,7 +119,7 @@ export class Stonecrop {
 		// Extend Registry.addDoctype to auto-create HST store sections
 		const originalAddDoctype = this.registry.addDoctype.bind(this.registry)
 
-		this.registry.addDoctype = (doctype: DoctypeMeta) => {
+		this.registry.addDoctype = (doctype: Doctype) => {
 			// Call original method
 			// eslint-disable-next-line @typescript-eslint/no-unsafe-call
 			originalAddDoctype(doctype)
@@ -136,7 +136,7 @@ export class Stonecrop {
 	 * @param doctype - The doctype to get records for
 	 * @returns HST node containing records hash
 	 */
-	records(doctype: string | DoctypeMeta): HSTNode {
+	records(doctype: string | Doctype): HSTNode {
 		const slug = typeof doctype === 'string' ? doctype : doctype.slug
 		this.ensureDoctypeExists(slug)
 		return this.hstStore.getNode(slug)
@@ -148,7 +148,7 @@ export class Stonecrop {
 	 * @param recordId - The record ID
 	 * @param recordData - The record data
 	 */
-	addRecord(doctype: string | DoctypeMeta, recordId: string, recordData: any): void {
+	addRecord(doctype: string | Doctype, recordId: string, recordData: any): void {
 		const slug = typeof doctype === 'string' ? doctype : doctype.slug
 
 		this.ensureDoctypeExists(slug)
@@ -163,7 +163,7 @@ export class Stonecrop {
 	 * @param recordId - The record ID
 	 * @returns HST node for the record or undefined
 	 */
-	getRecordById(doctype: string | DoctypeMeta, recordId: string): HSTNode | undefined {
+	getRecordById(doctype: string | Doctype, recordId: string): HSTNode | undefined {
 		const slug = typeof doctype === 'string' ? doctype : doctype.slug
 		this.ensureDoctypeExists(slug)
 
@@ -188,7 +188,7 @@ export class Stonecrop {
 	 * @param doctype - The doctype
 	 * @param recordId - The record ID
 	 */
-	removeRecord(doctype: string | DoctypeMeta, recordId: string): void {
+	removeRecord(doctype: string | Doctype, recordId: string): void {
 		const slug = typeof doctype === 'string' ? doctype : doctype.slug
 		this.ensureDoctypeExists(slug)
 
@@ -203,7 +203,7 @@ export class Stonecrop {
 	 * @param doctype - The doctype
 	 * @returns Array of record IDs
 	 */
-	getRecordIds(doctype: string | DoctypeMeta): string[] {
+	getRecordIds(doctype: string | Doctype): string[] {
 		const slug = typeof doctype === 'string' ? doctype : doctype.slug
 		this.ensureDoctypeExists(slug)
 
@@ -219,7 +219,7 @@ export class Stonecrop {
 	 * Clear all records for a doctype
 	 * @param doctype - The doctype
 	 */
-	clearRecords(doctype: string | DoctypeMeta): void {
+	clearRecords(doctype: string | Doctype): void {
 		const slug = typeof doctype === 'string' ? doctype : doctype.slug
 		this.ensureDoctypeExists(slug)
 
@@ -234,7 +234,7 @@ export class Stonecrop {
 	 * Setup method for doctype initialization
 	 * @param doctype - The doctype to setup
 	 */
-	setup(doctype: DoctypeMeta): void {
+	setup(doctype: Doctype): void {
 		// Ensure doctype exists in store
 		this.ensureDoctypeExists(doctype.slug)
 	}
@@ -246,7 +246,7 @@ export class Stonecrop {
 	 * @param action - The action to run
 	 * @param args - Action arguments (typically record IDs)
 	 */
-	runAction(doctype: DoctypeMeta, action: string, args?: any[]): void {
+	runAction(doctype: Doctype, action: string, args?: any[]): void {
 		const registry = this.registry.registry[doctype.slug]
 		const actions = registry?.actions?.get(action)
 		const recordIds = Array.isArray(args) ? args.filter((arg): arg is string => typeof arg === 'string') : undefined
@@ -285,7 +285,7 @@ export class Stonecrop {
 	 * @param doctype - The doctype
 	 * @throws Error if no data client has been configured
 	 */
-	async getRecords(doctype: DoctypeMeta): Promise<void> {
+	async getRecords(doctype: Doctype): Promise<void> {
 		if (!this._client) {
 			throw new Error(
 				'No data client configured. Call setClient() with a DataClient implementation ' +
@@ -309,7 +309,7 @@ export class Stonecrop {
 	 * @param recordId - The record ID
 	 * @throws Error if no data client has been configured
 	 */
-	async getRecord(doctype: DoctypeMeta, recordId: string): Promise<void> {
+	async getRecord(doctype: Doctype, recordId: string): Promise<void> {
 		if (!this._client) {
 			throw new Error(
 				'No data client configured. Call setClient() with a DataClient implementation ' +
@@ -335,7 +335,7 @@ export class Stonecrop {
 	 * @throws Error if no data client has been configured
 	 */
 	async dispatchAction(
-		doctype: DoctypeMeta,
+		doctype: Doctype,
 		action: string,
 		args?: unknown[]
 	): Promise<{ success: boolean; data: unknown; error: string | null }> {
@@ -386,13 +386,13 @@ export class Stonecrop {
 	 * empty the doctype's declared `workflow.initial` state is used as the fallback,
 	 * giving callers a reliable state name without having to duplicate that logic.
 	 *
-	 * @param doctype - The doctype slug or DoctypeMeta instance
+	 * @param doctype - The doctype slug or Doctype instance
 	 * @param recordId - The record identifier
 	 * @returns The current state name, or an empty string if the doctype has no workflow
 	 *
 	 * @public
 	 */
-	getRecordState(doctype: string | DoctypeMeta, recordId: string): string {
+	getRecordState(doctype: string | Doctype, recordId: string): string {
 		const slug = typeof doctype === 'string' ? doctype : doctype.slug
 		const meta = this.registry.getDoctype(slug)
 		if (!meta?.workflow) return ''

package/src/types/index.ts

@@ -5,7 +5,7 @@ import type { Component } from 'vue'
 import type { Router } from 'vue-router'
 import type { AnyStateNodeConfig, UnknownMachineConfig } from 'xstate'
 
-import type DoctypeMeta from '../doctype'
+import type Doctype from '../doctype'
 import Registry from '../registry'
 import { Stonecrop } from '../stonecrop'
 import type { RouteContext } from './registry'
@@ -47,7 +47,7 @@ export type Schema = {
 export type InstallOptions = {
 	router?: Router
 	components?: Record<string, Component>
-	getMeta?: (routeContext: RouteContext) => DoctypeMeta | Promise<DoctypeMeta>
+	getMeta?: (routeContext: RouteContext) => Doctype | Promise<Doctype>
 	/**
 	 * Data client for fetching doctype metadata and records.
 	 * Use \@stonecrop/graphql-client's StonecropClient for GraphQL backends,