@stonecrop/stonecrop 0.10.12 → 0.10.13

package/dist/stonecrop.d.ts

@@ -50,7 +50,16 @@ export declare interface ActionRegistry {
  * @public
  */
 export declare 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;
 };
 
@@ -71,6 +80,16 @@ export declare interface BatchOperation {
     reversible: boolean;
 }
 
+/**
+ * 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
+ */
+export declare function collectNestedData(resolvedSchema: SchemaTypes[], basePath: string, hstStore: HSTNode): Record<string, any>;
+
 /**
  * Factory function for HST creation
  * Creates a new HSTNode proxy for hierarchical state tree navigation.
@@ -585,9 +604,13 @@ export declare class HST {
  * @public
  */
 export declare 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;
 };
 
@@ -735,19 +758,77 @@ export declare type HSTOperationType = 'set' | 'delete' | 'batch' | 'transition'
  * @public
  */
 export declare 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>;
 };
 
@@ -816,8 +897,20 @@ export declare type MutableDoctype = {
  * @public
  */
 export declare 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;
@@ -825,20 +918,92 @@ export declare type OperationLogAPI = {
         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;
 };
 
@@ -1140,6 +1305,13 @@ export declare function setFieldRollback(doctype: string, fieldname: string, ena
  * @public
  */
 export declare class Stonecrop {
+    /**
+     * 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
+     */
+    static _root: Stonecrop;
     private hstStore;
     private _operationLogStore?;
     private _operationLogConfig?;
@@ -1147,7 +1319,7 @@ export declare class Stonecrop {
     /** The registry instance containing all doctype definitions */
     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)
@@ -1262,7 +1434,7 @@ export declare class Stonecrop {
     getSnapshot: () => OperationLogSnapshot;
     markIrreversible: (operationId: string, reason: string) => void;
     logAction: (doctype: string, actionName: string, recordIds?: string[], result?: "success" | "failure" | "pending", error?: string) => string;
-    }, "operations" | "currentIndex" | "config" | "clientId">, Pick<{
+    }, "operations" | "clientId" | "currentIndex" | "config">, Pick<{
     operations: Ref<    {
     id: string;
     type: HSTOperationType;
@@ -1551,6 +1723,23 @@ export declare class Stonecrop {
      * @public
      */
     getRecordState(doctype: string | Doctype, recordId: string): string;
+    /**
+     * 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>;
+    /**
+     * 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>;
 }
 
 /**
@@ -1835,7 +2024,7 @@ getOperationsFor: (doctype: string, recordId?: string) => HSTOperation[];
 getSnapshot: () => OperationLogSnapshot;
 markIrreversible: (operationId: string, reason: string) => void;
 logAction: (doctype: string, actionName: string, recordIds?: string[], result?: "success" | "failure" | "pending", error?: string) => string;
-}, "operations" | "currentIndex" | "config" | "clientId">, Pick<{
+}, "operations" | "clientId" | "currentIndex" | "config">, Pick<{
 operations: Ref<    {
 id: string;
 type: HSTOperationType;