@stonecrop/stonecrop 0.10.4 → 0.10.6

package/dist/stonecrop.d.ts

@@ -116,10 +116,10 @@ export declare interface CrossTabMessage {
 export declare type CrossTabMessageType = 'operation' | 'undo' | 'redo' | 'sync-request' | 'sync-response';
 
 /**
- * Doctype Meta class
+ * Doctype runtime class with Immutable.js collections for HST change tracking.
  * @public
  */
-export declare class DoctypeMeta {
+export declare class Doctype {
     /**
      * The doctype name
      * @public
@@ -157,7 +157,7 @@ export declare 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)
@@ -165,6 +165,70 @@ export declare class DoctypeMeta {
      * @param component - Optional Vue component for rendering the doctype
      */
     constructor(doctype: string, schema: ImmutableDoctype['schema'], workflow: ImmutableDoctype['workflow'], actions: ImmutableDoctype['actions'], 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;
+    /**
+     * 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[];
+    /**
+     * 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[]>;
     /**
      * Returns the transitions available from a given workflow state, derived from the
      * doctype's XState workflow configuration.
@@ -194,7 +258,7 @@ export declare 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'
      * ```
      *
@@ -203,6 +267,32 @@ export declare class DoctypeMeta {
     get slug(): string;
 }
 
+/**
+ * Plain object representation of doctype configuration for serialization/API responses.
+ * Compatible with the DoctypeMeta type from \@stonecrop/schema.
+ * @public
+ */
+export declare 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;
+};
+
 /**
  * Supported action types for field triggers
  * @public
@@ -626,9 +716,9 @@ export declare 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>>;
-    createNestedContext: (basePath: string, childDoctype: DoctypeMeta) => {
+    loadNestedData: (parentPath: string, childDoctype: Doctype, recordId?: string) => Record<string, any>;
+    saveRecursive: (doctype: Doctype, recordId: string) => Promise<Record<string, any>>;
+    createNestedContext: (basePath: string, childDoctype: Doctype) => {
         provideHSTPath: (fieldname: string) => string;
         handleHSTChange: (changeData: HSTChangeData) => void;
     };
@@ -651,7 +741,7 @@ export declare type ImmutableDoctype = {
 export declare 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,
@@ -851,9 +941,9 @@ export declare class Registry {
     readonly name: string;
     /**
      * 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
      * @see {@link https://router.vuejs.org/}
@@ -864,19 +954,19 @@ export declare 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>);
     /**
      * 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): void;
+    addDoctype(doctype: Doctype): void;
     /**
      * Resolve nested Doctype and Table fields in a schema by embedding child schemas inline.
      *
@@ -938,10 +1028,10 @@ export declare 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;
 }
 
 /**
@@ -1328,43 +1418,43 @@ export declare 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;
     /**
      * Add a record to the store
      * @param doctype - The doctype
      * @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;
     /**
      * Get a specific record
      * @param doctype - The doctype
      * @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;
     /**
      * Remove a record from the store
      * @param doctype - The doctype
      * @param recordId - The record ID
      */
-    removeRecord(doctype: string | DoctypeMeta, recordId: string): void;
+    removeRecord(doctype: string | Doctype, recordId: string): void;
     /**
      * Get all record IDs for a doctype
      * @param doctype - The doctype
      * @returns Array of record IDs
      */
-    getRecordIds(doctype: string | DoctypeMeta): string[];
+    getRecordIds(doctype: string | Doctype): string[];
     /**
      * Clear all records for a doctype
      * @param doctype - The doctype
      */
-    clearRecords(doctype: string | DoctypeMeta): void;
+    clearRecords(doctype: string | Doctype): void;
     /**
      * Setup method for doctype initialization
      * @param doctype - The doctype to setup
      */
-    setup(doctype: DoctypeMeta): void;
+    setup(doctype: Doctype): void;
     /**
      * Run action on doctype
      * Executes the action and logs it to the operation log for audit tracking
@@ -1372,20 +1462,20 @@ export declare 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;
     /**
      * Get records from server using the configured data client.
      * @param doctype - The doctype
      * @throws Error if no data client has been configured
      */
-    getRecords(doctype: DoctypeMeta): Promise<void>;
+    getRecords(doctype: Doctype): Promise<void>;
     /**
      * Get single record from server using the configured data client.
      * @param doctype - The doctype
      * @param recordId - The record ID
      * @throws Error if no data client has been configured
      */
-    getRecord(doctype: DoctypeMeta, recordId: string): Promise<void>;
+    getRecord(doctype: Doctype, recordId: string): Promise<void>;
     /**
      * Dispatch an action to the server via the configured data client.
      * All state changes flow through this single mutation endpoint.
@@ -1396,7 +1486,7 @@ export declare class Stonecrop {
      * @returns Action result with success status, response data, and any error
      * @throws Error if no data client has been configured
      */
-    dispatchAction(doctype: DoctypeMeta, action: string, args?: unknown[]): Promise<{
+    dispatchAction(doctype: Doctype, action: string, args?: unknown[]): Promise<{
         success: boolean;
         data: unknown;
         error: string | null;
@@ -1424,13 +1514,13 @@ export declare 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;
 }
 
 /**
@@ -1907,7 +1997,7 @@ export declare function useStonecrop(): BaseStonecropReturn | HSTStonecropReturn
  */
 export declare function useStonecrop(options: {
     registry?: Registry;
-    doctype: DoctypeMeta;
+    doctype: Doctype;
     recordId?: string;
 }): HSTStonecropReturn;