@blueprint-ts/core 4.1.0-beta.3 → 4.1.0-beta.5

package/dist/vue/forms/BaseForm.js

@@ -1,8 +1,19 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 import { reactive, computed, toRaw, watch } from 'vue';
-import { camelCase, upperFirst, cloneDeep, isEqual } from 'lodash-es';
-import isEqualWith from 'lodash-es/isEqualWith';
+import { camelCase, upperFirst, cloneDeep, debounce, isEqual } from 'lodash-es';
 import { NonPersistentDriver } from '../../persistenceDrivers/NonPersistentDriver';
 import { PropertyAwareArray } from './PropertyAwareArray';
+import { PropertyAwareObject, PROPERTY_AWARE_OBJECT_MARKER } from './PropertyAwareObject';
+import { StrictPersistenceRestorePolicy } from './persistence/StrictPersistenceRestorePolicy';
+import { BaseRule } from './validation/rules/BaseRule';
 import { ValidationMode } from './validation';
 function isRecord(value) {
     return !!value && typeof value === 'object' && !Array.isArray(value);
@@ -11,11 +22,40 @@ function isErrorMessages(value) {
     return Array.isArray(value) && (value.length === 0 || typeof value[0] === 'string');
 }
 function isErrorArray(value) {
-    return Array.isArray(value) && value.length > 0 && isRecord(value[0]);
+    return Array.isArray(value) && value.some((item) => isRecord(item));
 }
 function isErrorObject(value) {
     return isRecord(value);
 }
+function isPropertyAwareObject(value) {
+    return value instanceof PropertyAwareObject;
+}
+function isSerializedPropertyAwareObject(value) {
+    return isRecord(value) && value[PROPERTY_AWARE_OBJECT_MARKER] === true;
+}
+function restoreSerializedPropertyAwareValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => restoreSerializedPropertyAwareValue(item));
+    }
+    if (isSerializedPropertyAwareObject(value)) {
+        const restored = {};
+        for (const [key, child] of Object.entries(value)) {
+            if (key === PROPERTY_AWARE_OBJECT_MARKER) {
+                continue;
+            }
+            restored[key] = restoreSerializedPropertyAwareValue(child);
+        }
+        return new PropertyAwareObject(restored);
+    }
+    if (isRecord(value)) {
+        const restored = {};
+        for (const [key, child] of Object.entries(value)) {
+            restored[key] = restoreSerializedPropertyAwareValue(child);
+        }
+        return restored;
+    }
+    return value;
+}
 export function propertyAwareToRaw(propertyAwareObject) {
     var _a;
     if (Array.isArray(propertyAwareObject)) {
@@ -65,40 +105,41 @@ function deepMergeArrays(target, source) {
         return s;
     });
 }
-/**
- * Helper: Given the defaults and a state object (or original),
- * for every key where the default is a PropertyAwareArray, rewrap the value if needed.
- */
-function restorePropertyAwareArrays(defaults, state) {
-    for (const key in defaults) {
-        const defVal = defaults[key];
-        if (defVal instanceof PropertyAwareArray) {
-            if (!(state[key] instanceof PropertyAwareArray)) {
-                const values = Array.isArray(state[key]) ? Array.from(state[key]) : [];
-                state[key] = new PropertyAwareArray(values);
+function restorePropertyAwareStructure(defaults, value) {
+    if (defaults instanceof PropertyAwareArray) {
+        const restored = value instanceof PropertyAwareArray ? value : new PropertyAwareArray(Array.isArray(value) ? Array.from(value) : []);
+        const defaultItemTemplate = defaults[0];
+        for (let index = 0; index < restored.length; index++) {
+            if (index < defaults.length) {
+                restored[index] = restorePropertyAwareStructure(defaults[index], restored[index]);
+            }
+            else if (defaultItemTemplate !== undefined) {
+                restored[index] = restorePropertyAwareStructure(defaultItemTemplate, restored[index]);
+            }
+            else {
+                restored[index] = restoreSerializedPropertyAwareValue(restored[index]);
             }
         }
+        return restored;
     }
-}
-/**
- * Compare values while treating PropertyAwareArray as its underlying array.
- * This avoids false negatives when comparing persisted state to defaults.
- */
-function propertyAwareDeepEqual(a, b) {
-    const getInner = (val) => {
-        if (val instanceof PropertyAwareArray) {
-            return val;
-        }
-        return val;
-    };
-    return isEqualWith(a, b, (aValue, bValue) => {
-        const normA = getInner(aValue);
-        const normB = getInner(bValue);
-        if (normA !== aValue || normB !== bValue) {
-            return isEqual(normA, normB);
-        }
-        return undefined; // use default comparison
-    });
+    if (defaults instanceof PropertyAwareObject) {
+        const restored = value instanceof PropertyAwareObject
+            ? value
+            : new PropertyAwareObject(isRecord(value) ? value : {});
+        const restoredRecord = restored;
+        const defaultRecord = defaults;
+        for (const key of Object.keys(defaults)) {
+            restoredRecord[key] = restorePropertyAwareStructure(defaultRecord[key], restoredRecord[key]);
+        }
+        return restored;
+    }
+    if (isRecord(defaults) && isRecord(value)) {
+        for (const key of Object.keys(defaults)) {
+            value[key] = restorePropertyAwareStructure(defaults[key], value[key]);
+        }
+        return value;
+    }
+    return restoreSerializedPropertyAwareValue(value);
 }
 /**
  * A generic base class for forms.
@@ -118,6 +159,20 @@ export class BaseForm {
     getPersistenceDriver(_suffix) {
         return new NonPersistentDriver();
     }
+    getPersistenceRestorePolicy() {
+        return new StrictPersistenceRestorePolicy();
+    }
+    shouldLogPersistenceDebug() {
+        return false;
+    }
+    logPersistenceDebug(event) {
+        if (!this.shouldLogPersistenceDebug()) {
+            return;
+        }
+        const suffixLabel = event.persistSuffix ? ` (${event.persistSuffix})` : '';
+        const details = event.details ? ` ${JSON.stringify(event.details)}` : '';
+        console.debug(`[BaseForm persistence] ${event.formName}${suffixLabel}: ${event.action} (${event.reason})${details}`);
+    }
     /**
      * Helper: recursively computes the dirty state for a value based on the original.
      * For plain arrays we compare the entire array (a single flag), not each element.
@@ -130,7 +185,7 @@ export class BaseForm {
             const dirty = {};
             for (const key in current) {
                 if (Object.prototype.hasOwnProperty.call(current, key)) {
-                    dirty[key] = !isEqual(current[key], original[key]);
+                    dirty[key] = this.computeDirtyState(current[key], original[key]);
                 }
             }
             return dirty;
@@ -251,44 +306,65 @@ export class BaseForm {
         }
     }
     constructor(defaults, options) {
+        var _a;
         this.options = options;
         this._errors = reactive({});
+        this._asyncErrors = reactive({});
         this.append = [];
         this.ignore = [];
         this.errorMap = {};
         this.rules = {};
+        this.validationGroups = {};
         this.fieldDependencies = new Map();
+        this.arrayWrapperCache = new Map();
+        this.arrayItemWrapperCache = new Map();
+        this.asyncValidationDebouncers = new Map();
+        this.pendingAsyncValidationContexts = new Map();
+        this.asyncValidationTokens = reactive({});
         const persist = (options === null || options === void 0 ? void 0 : options.persist) !== false;
         let initialData;
         const driver = this.getPersistenceDriver(options === null || options === void 0 ? void 0 : options.persistSuffix);
         if (persist) {
-            const persisted = driver.get(this.constructor.name);
-            if (persisted && propertyAwareDeepEqual(defaults, persisted.original)) {
-                initialData = persisted.state;
-                this.original = cloneDeep(persisted.original);
-                this.dirty = reactive(persisted.dirty);
-                this.touched = reactive(persisted.touched || {});
-                restorePropertyAwareArrays(defaults, initialData);
-                restorePropertyAwareArrays(defaults, this.original);
+            const persisted = (_a = driver.get(this.constructor.name)) !== null && _a !== void 0 ? _a : null;
+            const restoreDecision = this.getPersistenceRestorePolicy().resolve({
+                formName: this.constructor.name,
+                persistSuffix: options === null || options === void 0 ? void 0 : options.persistSuffix,
+                defaults,
+                persisted
+            });
+            this.logPersistenceDebug({
+                formName: this.constructor.name,
+                persistSuffix: options === null || options === void 0 ? void 0 : options.persistSuffix,
+                action: restoreDecision.action,
+                reason: restoreDecision.reason,
+                details: restoreDecision.details
+            });
+            if (restoreDecision.action === 'restore' && restoreDecision.persisted) {
+                initialData = restorePropertyAwareStructure(defaults, restoreDecision.persisted.state);
+                this.original = restorePropertyAwareStructure(defaults, cloneDeep(restoreDecision.persisted.original));
+                this.dirty = reactive(restoreDecision.persisted.dirty);
+                this.touched = reactive(restoreDecision.persisted.touched || {});
             }
             else {
-                console.log('Discarding persisted data for ' + this.constructor.name + " because it doesn't match the defaults.");
                 initialData = defaults;
-                this.original = cloneDeep(defaults);
+                this.original = restorePropertyAwareStructure(defaults, cloneDeep(defaults));
                 const init = this.initDirtyTouched(defaults);
                 this.dirty = init.dirty;
                 this.touched = init.touched;
-                driver.remove(this.constructor.name);
+                if (restoreDecision.action === 'discard') {
+                    driver.remove(this.constructor.name);
+                }
             }
         }
         else {
             initialData = defaults;
-            this.original = cloneDeep(defaults);
+            this.original = restorePropertyAwareStructure(defaults, cloneDeep(defaults));
             const init = this.initDirtyTouched(defaults);
             this.dirty = init.dirty;
             this.touched = init.touched;
         }
         this.rules = this.defineRules();
+        this.validationGroups = this.defineValidationGroups();
         this.buildFieldDependencies();
         this.state = reactive(initialData);
         this._model = {};
@@ -300,7 +376,7 @@ export class BaseForm {
                     set: (newVal) => {
                         const next = Array.isArray(newVal) ? Array.from(newVal) : [];
                         this.replacePropertyAwareArray(key, next);
-                        this.dirty[key] = next.map(() => false);
+                        this.dirty[key] = this.computeDirtyState(this.state[key], this.original[key]);
                         this.markFieldUpdated(key, driver);
                     }
                 });
@@ -323,29 +399,7 @@ export class BaseForm {
                 }, { deep: true });
             }
         }
-        this._hasErrors = computed(() => {
-            for (const field in this._errors) {
-                if (Object.prototype.hasOwnProperty.call(this._errors, field)) {
-                    const fieldErrors = this._errors[field];
-                    if (Array.isArray(fieldErrors) && fieldErrors.length > 0) {
-                        return true;
-                    }
-                    if (fieldErrors && typeof fieldErrors === 'object') {
-                        if (Array.isArray(fieldErrors)) {
-                            for (const item of fieldErrors) {
-                                if (item && typeof item === 'object' && Object.keys(item).length > 0) {
-                                    return true;
-                                }
-                            }
-                        }
-                        else if (Object.keys(fieldErrors).length > 0) {
-                            return true;
-                        }
-                    }
-                }
-            }
-            return false;
-        });
+        this._hasErrors = computed(() => Object.keys(this.flattenErrors()).length > 0);
         if (persist) {
             watch(() => this.state, () => this.persistState(driver), { deep: true, immediate: true });
         }
@@ -354,18 +408,275 @@ export class BaseForm {
     defineRules() {
         return {};
     }
+    defineValidationGroups() {
+        return {};
+    }
+    clearErrorBag(errorBag) {
+        for (const key in errorBag) {
+            delete errorBag[key];
+        }
+    }
+    clearSyncErrors() {
+        this.clearErrorBag(this._errors);
+    }
+    clearAsyncErrors() {
+        this.clearErrorBag(this._asyncErrors);
+    }
     clearErrors() {
-        for (const key in this._errors) {
-            delete this._errors[key];
+        this.cancelPendingAsyncValidations();
+        this.clearSyncErrors();
+        this.clearAsyncErrors();
+    }
+    hasAsyncRules(field) {
+        const fieldConfig = this.rules[field];
+        if (!(fieldConfig === null || fieldConfig === void 0 ? void 0 : fieldConfig.rules) || fieldConfig.rules.length === 0) {
+            return false;
+        }
+        return fieldConfig.rules.some((rule) => rule.validateAsync !== BaseRule.prototype.validateAsync);
+    }
+    bumpAsyncValidationToken(field) {
+        var _a;
+        const fieldKey = String(field);
+        const nextToken = ((_a = this.asyncValidationTokens[fieldKey]) !== null && _a !== void 0 ? _a : 0) + 1;
+        this.asyncValidationTokens[fieldKey] = nextToken;
+        return nextToken;
+    }
+    cancelPendingAsyncValidations() {
+        var _a;
+        for (const debouncer of this.asyncValidationDebouncers.values()) {
+            debouncer.cancel();
+        }
+        this.pendingAsyncValidationContexts.clear();
+        for (const fieldKey of Object.keys(this.asyncValidationTokens)) {
+            this.asyncValidationTokens[fieldKey] = ((_a = this.asyncValidationTokens[fieldKey]) !== null && _a !== void 0 ? _a : 0) + 1;
+        }
+    }
+    scheduleAsyncValidation(field, context) {
+        var _a, _b, _c;
+        if (!this.hasAsyncRules(field)) {
+            return;
+        }
+        const token = this.bumpAsyncValidationToken(field);
+        const debounceMs = (_c = (_b = (_a = this.rules[field]) === null || _a === void 0 ? void 0 : _a.options) === null || _b === void 0 ? void 0 : _b.asyncDebounceMs) !== null && _c !== void 0 ? _c : 0;
+        this.pendingAsyncValidationContexts.set(field, { token, context });
+        if (debounceMs <= 0) {
+            void this.executeScheduledAsyncValidation(field).catch(() => undefined);
+            return;
+        }
+        let debouncer = this.asyncValidationDebouncers.get(field);
+        if (debouncer === undefined) {
+            debouncer = debounce(() => {
+                void this.executeScheduledAsyncValidation(field).catch(() => undefined);
+            }, debounceMs);
+            this.asyncValidationDebouncers.set(field, debouncer);
         }
+        debouncer();
     }
-    getOrCreateErrorArray(key) {
-        const existing = this._errors[key];
+    executeScheduledAsyncValidation(field) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const pending = this.pendingAsyncValidationContexts.get(field);
+            if (pending === undefined) {
+                return;
+            }
+            yield this.runFieldAsyncValidation(field, Object.assign(Object.assign({}, pending.context), { skipSyncValidation: true, skipAsyncValidation: true }), pending.token);
+        });
+    }
+    flattenErrorValue(value, path, flattened) {
+        if (value === undefined) {
+            return;
+        }
+        if (isErrorMessages(value)) {
+            if (value.length > 0) {
+                flattened[path] = cloneDeep(value);
+            }
+            return;
+        }
+        if (isErrorArray(value)) {
+            value.forEach((item, index) => {
+                const itemPath = `${path}.${index}`;
+                if (isErrorMessages(item)) {
+                    if (item.length > 0) {
+                        flattened[itemPath] = cloneDeep(item);
+                    }
+                    return;
+                }
+                this.flattenErrorValue(item, itemPath, flattened);
+            });
+            return;
+        }
+        if (!isErrorObject(value)) {
+            return;
+        }
+        const rootErrors = value[''];
+        if (isErrorMessages(rootErrors) && rootErrors.length > 0) {
+            flattened[path] = cloneDeep(rootErrors);
+        }
+        for (const key of Object.keys(value)) {
+            if (key === '') {
+                continue;
+            }
+            const nestedPath = path.length > 0 ? `${path}.${key}` : key;
+            this.flattenErrorValue(value[key], nestedPath, flattened);
+        }
+    }
+    flattenErrorsFromBag(errorBag) {
+        const flattened = {};
+        for (const key of Object.keys(errorBag)) {
+            this.flattenErrorValue(errorBag[key], key, flattened);
+        }
+        return flattened;
+    }
+    mergeErrorMessages(...messageSets) {
+        const merged = [];
+        for (const messages of messageSets) {
+            for (const message of messages) {
+                if (!merged.includes(message)) {
+                    merged.push(message);
+                }
+            }
+        }
+        return merged;
+    }
+    flattenErrors() {
+        var _a;
+        const flattened = this.flattenErrorsFromBag(this._errors);
+        for (const [key, messages] of Object.entries(this.flattenErrorsFromBag(this._asyncErrors))) {
+            flattened[key] = this.mergeErrorMessages((_a = flattened[key]) !== null && _a !== void 0 ? _a : [], messages);
+        }
+        return flattened;
+    }
+    applyErrors(errorsData, useErrorMap, targetBag = this._errors) {
+        var _a, _b, _c;
+        for (const serverKey in errorsData) {
+            if (!Object.prototype.hasOwnProperty.call(errorsData, serverKey)) {
+                continue;
+            }
+            const errorMessage = errorsData[serverKey];
+            if (errorMessage === undefined) {
+                continue;
+            }
+            let targetKeys = [serverKey];
+            if (useErrorMap) {
+                const mapping = (_a = this.errorMap) === null || _a === void 0 ? void 0 : _a[serverKey];
+                if (mapping) {
+                    targetKeys = Array.isArray(mapping) ? mapping : [mapping];
+                }
+            }
+            for (const targetKey of targetKeys) {
+                const parts = targetKey.split('.');
+                if (parts.length > 1) {
+                    const topKey = (_b = parts[0]) !== null && _b !== void 0 ? _b : '';
+                    const indexPart = (_c = parts[1]) !== null && _c !== void 0 ? _c : '';
+                    const index = Number.parseInt(indexPart, 10);
+                    if (!topKey) {
+                        targetBag[targetKey] = errorMessage;
+                        continue;
+                    }
+                    if (!Number.isFinite(index)) {
+                        const current = isErrorObject(targetBag[topKey]) ? targetBag[topKey] : {};
+                        targetBag[topKey] = current;
+                        this.setNestedError(current, parts.slice(1), errorMessage);
+                        continue;
+                    }
+                    const errorSubKey = parts.slice(2).join('.');
+                    const errors = this.getOrCreateErrorArray(topKey, targetBag);
+                    const errorObject = this.getOrCreateErrorObject(errors, index);
+                    if (errorSubKey.length === 0) {
+                        errorObject[''] = errorMessage;
+                    }
+                    else {
+                        this.setNestedError(errorObject, errorSubKey.split('.'), errorMessage);
+                    }
+                }
+                else {
+                    targetBag[targetKey] = errorMessage;
+                }
+            }
+        }
+    }
+    getValidationGroupPaths(group) {
+        const paths = this.validationGroups[group];
+        if (!paths || paths.length === 0) {
+            return [];
+        }
+        return [...paths];
+    }
+    matchesValidationGroupPath(errorKey, groupPath) {
+        return errorKey === groupPath || errorKey.startsWith(`${groupPath}.`);
+    }
+    errorKeyBelongsToGroup(errorKey, group) {
+        return this.getValidationGroupPaths(group).some((groupPath) => this.matchesValidationGroupPath(errorKey, groupPath));
+    }
+    getValidationGroupFields(group) {
+        const fields = [];
+        for (const path of this.getValidationGroupPaths(group)) {
+            const [topLevelField] = path.split('.');
+            if (!topLevelField || !(topLevelField in this.state)) {
+                continue;
+            }
+            const typedField = topLevelField;
+            if (!fields.includes(typedField)) {
+                fields.push(typedField);
+            }
+        }
+        return fields;
+    }
+    clearGroupErrors(group) {
+        const groupPaths = this.getValidationGroupPaths(group);
+        if (groupPaths.length === 0) {
+            return;
+        }
+        const preservedErrors = {};
+        for (const [errorKey, errorValue] of Object.entries(this.flattenErrors())) {
+            if (!this.errorKeyBelongsToGroup(errorKey, group)) {
+                preservedErrors[errorKey] = cloneDeep(errorValue);
+            }
+        }
+        this.clearErrors();
+        this.applyErrors(preservedErrors, false);
+    }
+    collectSiblingNestedErrors(field, path) {
+        if (path.length === 0) {
+            return {};
+        }
+        const fieldKey = String(field);
+        const clearedPath = `${fieldKey}.${path.join('.')}`;
+        const preservedErrors = {};
+        for (const [errorKey, errorValue] of Object.entries(this.flattenErrors())) {
+            if (!this.matchesValidationGroupPath(errorKey, fieldKey)) {
+                continue;
+            }
+            if (errorKey === clearedPath || errorKey.startsWith(`${clearedPath}.`)) {
+                continue;
+            }
+            preservedErrors[errorKey] = cloneDeep(errorValue);
+        }
+        return preservedErrors;
+    }
+    validateFieldPreservingNestedErrors(field, path) {
+        const preservedErrors = this.collectSiblingNestedErrors(field, path);
+        this.validateField(field);
+        if (Object.keys(preservedErrors).length > 0) {
+            this.applyErrors(preservedErrors, false);
+        }
+    }
+    clearErrorBagPaths(errorBag, paths) {
+        const preservedErrors = {};
+        for (const [errorKey, errorValue] of Object.entries(this.flattenErrorsFromBag(errorBag))) {
+            if (!paths.some((path) => this.matchesValidationGroupPath(errorKey, path))) {
+                preservedErrors[errorKey] = cloneDeep(errorValue);
+            }
+        }
+        this.clearErrorBag(errorBag);
+        this.applyErrors(preservedErrors, false, errorBag);
+    }
+    getOrCreateErrorArray(key, errorBag = this._errors) {
+        const existing = errorBag[key];
         if (isErrorArray(existing)) {
             return existing;
         }
         const next = [];
-        this._errors[key] = next;
+        errorBag[key] = next;
         return next;
     }
     getOrCreateErrorObject(errors, index) {
@@ -378,8 +689,9 @@ export class BaseForm {
         return next;
     }
     getFieldErrors(field) {
-        const errors = this._errors[field];
-        return isErrorMessages(errors) ? errors : [];
+        const syncErrors = this._errors[field];
+        const asyncErrors = this._asyncErrors[field];
+        return this.mergeErrorMessages(isErrorMessages(syncErrors) ? syncErrors : [], isErrorMessages(asyncErrors) ? asyncErrors : []);
     }
     getOrCreateFieldErrors(field) {
         const existing = this._errors[field];
@@ -399,22 +711,24 @@ export class BaseForm {
         return isErrorObject(item) ? item : undefined;
     }
     getArrayItemFieldErrors(field, index, innerKey) {
-        const itemErrors = this.getArrayItemErrors(field, index);
-        if (!itemErrors) {
-            return [];
-        }
-        const fieldErrors = itemErrors[innerKey];
-        if (isErrorMessages(fieldErrors)) {
-            return fieldErrors;
-        }
-        if (isErrorObject(fieldErrors)) {
-            const nestedErrors = fieldErrors[''];
-            return isErrorMessages(nestedErrors) ? nestedErrors : [];
-        }
-        return [];
+        return this.mergeErrorMessages(this.getNestedErrorMessagesFromValue(this.getArrayItemErrors(field, index), innerKey.split('.')), this.getNestedErrorMessagesFromValue(this.getArrayItemErrorsFromBag(this._asyncErrors, field, index), innerKey.split('.')));
     }
     getArrayItemErrorMessages(field, index) {
-        const errors = this._errors[field];
+        return this.mergeErrorMessages(this.getArrayItemErrorMessagesFromBag(this._errors, field, index), this.getArrayItemErrorMessagesFromBag(this._asyncErrors, field, index));
+    }
+    getObjectFieldErrors(field, path) {
+        return this.mergeErrorMessages(this.getNestedErrorMessagesFromValue(this._errors[field], path), this.getNestedErrorMessagesFromValue(this._asyncErrors[field], path));
+    }
+    getArrayItemErrorsFromBag(errorBag, field, index) {
+        const errors = errorBag[field];
+        if (!isErrorArray(errors)) {
+            return undefined;
+        }
+        const item = errors[index];
+        return isErrorObject(item) ? item : undefined;
+    }
+    getArrayItemErrorMessagesFromBag(errorBag, field, index) {
+        const errors = errorBag[field];
         if (!Array.isArray(errors)) {
             return [];
         }
@@ -457,13 +771,7 @@ export class BaseForm {
             return false;
         }
         const entry = dirtyState[index];
-        if (typeof entry === 'boolean') {
-            return entry;
-        }
-        if (isRecord(entry)) {
-            return entry[innerKey] === true;
-        }
-        return false;
+        return this.getNestedDirtyValue(entry, innerKey.split('.'));
     }
     getArrayItemDirtyValue(field, index) {
         const dirtyState = this.dirty[field];
@@ -473,49 +781,229 @@ export class BaseForm {
         const entry = dirtyState[index];
         return typeof entry === 'boolean' ? entry : false;
     }
+    getNestedErrorMessagesFromValue(value, path) {
+        if (path.length === 0) {
+            if (isErrorMessages(value)) {
+                return value;
+            }
+            if (isErrorObject(value)) {
+                const nestedErrors = value[''];
+                return isErrorMessages(nestedErrors) ? nestedErrors : [];
+            }
+            return [];
+        }
+        if (!isErrorObject(value)) {
+            return [];
+        }
+        const [segment, ...rest] = path;
+        if (segment === undefined) {
+            return [];
+        }
+        return this.getNestedErrorMessagesFromValue(value[segment], rest);
+    }
+    setNestedError(target, path, errorMessage) {
+        if (path.length === 0) {
+            target[''] = errorMessage;
+            return;
+        }
+        const [segment, ...rest] = path;
+        if (segment === undefined) {
+            return;
+        }
+        if (rest.length === 0) {
+            target[segment] = errorMessage;
+            return;
+        }
+        const next = isErrorObject(target[segment]) ? target[segment] : {};
+        target[segment] = next;
+        this.setNestedError(next, rest, errorMessage);
+    }
+    getNestedDirtyValue(value, path) {
+        if (path.length === 0) {
+            if (typeof value === 'boolean') {
+                return value;
+            }
+            if (Array.isArray(value)) {
+                return value.some((entry) => this.getNestedDirtyValue(entry, []));
+            }
+            if (isRecord(value)) {
+                return Object.values(value).some((item) => this.getNestedDirtyValue(item, []));
+            }
+            return false;
+        }
+        if (!isRecord(value)) {
+            return false;
+        }
+        const [segment, ...rest] = path;
+        if (segment === undefined) {
+            return false;
+        }
+        return this.getNestedDirtyValue(value[segment], rest);
+    }
+    createFieldProperty(getValue, setValue, getErrors, getDirty, getTouched) {
+        const field = {
+            model: computed({
+                get: getValue,
+                set: setValue
+            })
+        };
+        Object.defineProperties(field, {
+            errors: {
+                enumerable: true,
+                get: getErrors
+            },
+            dirty: {
+                enumerable: true,
+                get: getDirty
+            },
+            touched: {
+                enumerable: true,
+                get: getTouched
+            }
+        });
+        return field;
+    }
+    resolveArrayItemIndex(field, item) {
+        const value = this.state[field];
+        if (!(value instanceof PropertyAwareArray)) {
+            return -1;
+        }
+        return value.indexOf(item);
+    }
+    getArrayItemValueByPath(field, item, path) {
+        const index = this.resolveArrayItemIndex(field, item);
+        if (index < 0) {
+            return undefined;
+        }
+        let current = this.state[field][index];
+        for (const segment of path) {
+            if (!isRecord(current)) {
+                return undefined;
+            }
+            current = current[segment];
+        }
+        return current;
+    }
+    setArrayItemValueByPath(field, item, path, value) {
+        const index = this.resolveArrayItemIndex(field, item);
+        if (index < 0) {
+            return;
+        }
+        if (path.length === 0) {
+            ;
+            this.state[field][index] = value;
+            const updatedElement = this.state[field][index];
+            const originalElement = this.original[field][index];
+            this.setArrayDirty(field, index, this.computeDirtyState(updatedElement, originalElement));
+            this.touched[field] = true;
+            this.validateField(field);
+            this.validateDependentFields(field);
+            return;
+        }
+        const currentItem = this.state[field][index];
+        if (!isRecord(currentItem)) {
+            return;
+        }
+        let current = currentItem;
+        const segments = [...path];
+        const last = segments.pop();
+        if (last === undefined) {
+            return;
+        }
+        for (const segment of segments) {
+            const next = current[segment];
+            if (!isRecord(next)) {
+                return;
+            }
+            current = next;
+        }
+        current[last] = value;
+        const updatedElement = this.state[field][index];
+        const originalElement = this.original[field][index];
+        this.setArrayDirty(field, index, this.computeDirtyState(updatedElement, originalElement));
+        this.touched[field] = true;
+        this.validateFieldPreservingNestedErrors(field, [String(index), ...path]);
+        this.validateDependentFields(field);
+    }
+    createObjectWrapperFromShape(field, shape, getValueByPath, setValueByPath, getErrorsByPath, getDirtyByPath, getTouched) {
+        const wrapper = {};
+        const shapeRecord = shape;
+        for (const innerKey of Object.keys(shape)) {
+            const child = shapeRecord[innerKey];
+            if (isPropertyAwareObject(child)) {
+                wrapper[innerKey] = this.createObjectWrapperFromShape(field, child, (path) => getValueByPath([innerKey, ...path]), (path, value) => setValueByPath([innerKey, ...path], value), (path) => getErrorsByPath([innerKey, ...path]), (path) => getDirtyByPath([innerKey, ...path]), getTouched);
+                continue;
+            }
+            wrapper[innerKey] = this.createFieldProperty(() => getValueByPath([innerKey]), (newValue) => setValueByPath([innerKey], newValue), () => getErrorsByPath([innerKey]), () => getDirtyByPath([innerKey]), getTouched);
+        }
+        return wrapper;
+    }
+    getOrCreateArrayItemWrapper(field, item) {
+        let fieldCache = this.arrayItemWrapperCache.get(field);
+        if (!fieldCache) {
+            fieldCache = new WeakMap();
+            this.arrayItemWrapperCache.set(field, fieldCache);
+        }
+        const existing = fieldCache.get(item);
+        if (existing) {
+            return existing;
+        }
+        const wrapper = {};
+        if (isRecord(item)) {
+            for (const innerKey of Object.keys(item)) {
+                const child = item[innerKey];
+                if (isPropertyAwareObject(child)) {
+                    wrapper[innerKey] = this.createObjectWrapperFromShape(field, child, (path) => this.getArrayItemValueByPath(field, item, [innerKey, ...path]), (path, value) => this.setArrayItemValueByPath(field, item, [innerKey, ...path], value), (path) => {
+                        const index = this.resolveArrayItemIndex(field, item);
+                        return index < 0 ? [] : this.getArrayItemFieldErrors(String(field), index, [innerKey, ...path].join('.'));
+                    }, (path) => {
+                        var _a;
+                        const index = this.resolveArrayItemIndex(field, item);
+                        return index < 0
+                            ? false
+                            : this.getNestedDirtyValue((_a = this.dirty[field]) === null || _a === void 0 ? void 0 : _a[index], [innerKey, ...path]);
+                    }, () => this.touched[field] || false);
+                    continue;
+                }
+                wrapper[innerKey] = this.createFieldProperty(() => this.getArrayItemValueByPath(field, item, [innerKey]), (newValue) => this.setArrayItemValueByPath(field, item, [innerKey], newValue), () => {
+                    const index = this.resolveArrayItemIndex(field, item);
+                    return index < 0 ? [] : this.getArrayItemFieldErrors(String(field), index, innerKey);
+                }, () => {
+                    const index = this.resolveArrayItemIndex(field, item);
+                    return index < 0 ? false : this.getArrayItemDirty(field, index, innerKey);
+                }, () => this.touched[field] || false);
+            }
+        }
+        else {
+            wrapper['value'] = this.createFieldProperty(() => this.getArrayItemValueByPath(field, item, []), (newValue) => this.setArrayItemValueByPath(field, item, [], newValue), () => {
+                const index = this.resolveArrayItemIndex(field, item);
+                return index < 0 ? [] : this.getArrayItemErrorMessages(String(field), index);
+            }, () => {
+                const index = this.resolveArrayItemIndex(field, item);
+                return index < 0 ? false : this.getArrayItemDirtyValue(field, index);
+            }, () => this.touched[field] || false);
+        }
+        fieldCache.set(item, wrapper);
+        return wrapper;
+    }
+    getOrCreateArrayWrappers(field, value) {
+        let wrappers = this.arrayWrapperCache.get(field);
+        if (!wrappers) {
+            wrappers = [];
+            this.arrayWrapperCache.set(field, wrappers);
+        }
+        wrappers.length = 0;
+        value.forEach((item) => {
+            wrappers.push(this.getOrCreateArrayItemWrapper(field, item));
+        });
+        return wrappers;
+    }
     /**
      * Map server-side errors (including dot-notation paths) into the form error bag.
      */
     fillErrors(errorsData) {
-        var _a, _b, _c;
         this.clearErrors();
-        for (const serverKey in errorsData) {
-            if (Object.prototype.hasOwnProperty.call(errorsData, serverKey)) {
-                const errorMessage = errorsData[serverKey];
-                if (errorMessage === undefined) {
-                    continue;
-                }
-                let targetKeys = [serverKey];
-                const mapping = (_a = this.errorMap) === null || _a === void 0 ? void 0 : _a[serverKey];
-                if (mapping) {
-                    targetKeys = Array.isArray(mapping) ? mapping : [mapping];
-                }
-                for (const targetKey of targetKeys) {
-                    const parts = targetKey.split('.');
-                    if (parts.length > 1) {
-                        const topKey = (_b = parts[0]) !== null && _b !== void 0 ? _b : '';
-                        const indexPart = (_c = parts[1]) !== null && _c !== void 0 ? _c : '';
-                        const index = Number.parseInt(indexPart, 10);
-                        if (!topKey || !Number.isFinite(index)) {
-                            this._errors[targetKey] = errorMessage;
-                            continue;
-                        }
-                        const errorSubKey = parts.slice(2).join('.');
-                        const errors = this.getOrCreateErrorArray(topKey);
-                        const errorObject = this.getOrCreateErrorObject(errors, index);
-                        if (errorSubKey.length === 0) {
-                            errorObject[''] = errorMessage;
-                        }
-                        else {
-                            errorObject[errorSubKey] = errorMessage;
-                        }
-                    }
-                    else {
-                        this._errors[targetKey] = errorMessage;
-                    }
-                }
-            }
-        }
+        this.applyErrors(errorsData, true);
     }
     /**
      * Mark a field as touched, which indicates user interaction
@@ -572,19 +1060,22 @@ export class BaseForm {
                     this.getOrCreateFieldErrors(errorKey).push(rule.getMessage());
                 }
             }
+            if (!context.skipAsyncValidation) {
+                this.scheduleAsyncValidation(field, context);
+            }
         }
     }
-    validate(isSubmitting = false) {
+    validate(isSubmitting = false, options = {}) {
+        var _a;
         let isValid = true;
-        for (const key in this._errors) {
-            delete this._errors[key];
-        }
+        this.clearSyncErrors();
         for (const field in this.rules) {
             if (Object.prototype.hasOwnProperty.call(this.rules, field)) {
                 this.validateField(field, {
                     isSubmitting,
                     isDependentChange: false,
-                    isTouched: this.isTouched(field)
+                    isTouched: this.isTouched(field),
+                    skipAsyncValidation: (_a = options.skipAsyncValidation) !== null && _a !== void 0 ? _a : false
                 });
                 const fieldErrors = this._errors[String(field)];
                 if (isErrorMessages(fieldErrors) && fieldErrors.length > 0) {
@@ -594,6 +1085,99 @@ export class BaseForm {
         }
         return isValid;
     }
+    validateGroup(group, isSubmitting = false, options = {}) {
+        var _a;
+        const fields = this.getValidationGroupFields(group);
+        if (fields.length === 0) {
+            return true;
+        }
+        this.clearGroupErrors(group);
+        for (const field of fields) {
+            this.validateField(field, {
+                isSubmitting,
+                isDependentChange: false,
+                isTouched: this.isTouched(field),
+                skipAsyncValidation: (_a = options.skipAsyncValidation) !== null && _a !== void 0 ? _a : false
+            });
+        }
+        return !this.hasErrorsInGroup(group);
+    }
+    runFieldAsyncValidation(field_1) {
+        return __awaiter(this, arguments, void 0, function* (field, context = {}, expectedToken) {
+            var _a;
+            if (!context.skipSyncValidation) {
+                this.validateField(field, Object.assign(Object.assign({}, context), { skipAsyncValidation: true }));
+            }
+            const fieldConfig = this.rules[field];
+            if (!(fieldConfig === null || fieldConfig === void 0 ? void 0 : fieldConfig.rules) || fieldConfig.rules.length === 0) {
+                return !Object.keys(this.flattenErrors()).some((errorKey) => this.matchesValidationGroupPath(errorKey, String(field)));
+            }
+            const asyncPaths = fieldConfig.rules.flatMap((rule) => rule.getAsyncValidationPaths(field, this.state));
+            const payload = this.buildPayload();
+            const nextAsyncErrors = {};
+            for (const rule of fieldConfig.rules) {
+                const errors = yield rule.validateAsync(this.state[field], this.state, {
+                    field: String(field),
+                    payload,
+                    isSubmitting: (_a = context.isSubmitting) !== null && _a !== void 0 ? _a : false
+                });
+                if (errors && Object.keys(errors).length > 0) {
+                    this.applyErrors(errors, false, nextAsyncErrors);
+                }
+            }
+            if (expectedToken !== undefined && this.asyncValidationTokens[String(field)] !== expectedToken) {
+                return !Object.keys(this.flattenErrors()).some((errorKey) => this.matchesValidationGroupPath(errorKey, String(field)));
+            }
+            this.clearErrorBagPaths(this._asyncErrors, asyncPaths);
+            for (const [key, messages] of Object.entries(this.flattenErrorsFromBag(nextAsyncErrors))) {
+                this.applyErrors({ [key]: messages }, false, this._asyncErrors);
+            }
+            return !Object.keys(this.flattenErrors()).some((errorKey) => this.matchesValidationGroupPath(errorKey, String(field)));
+        });
+    }
+    validateFieldAsync(field_1) {
+        return __awaiter(this, arguments, void 0, function* (field, context = {}) {
+            const token = this.bumpAsyncValidationToken(field);
+            return yield this.runFieldAsyncValidation(field, Object.assign(Object.assign({}, context), { skipAsyncValidation: true }), token);
+        });
+    }
+    validateAsync() {
+        return __awaiter(this, arguments, void 0, function* (isSubmitting = false) {
+            const isSyncValid = this.validate(isSubmitting, { skipAsyncValidation: true });
+            for (const field in this.rules) {
+                if (Object.prototype.hasOwnProperty.call(this.rules, field)) {
+                    yield this.validateFieldAsync(field, {
+                        isSubmitting,
+                        isTouched: this.isTouched(field),
+                        skipSyncValidation: true
+                    });
+                }
+            }
+            return isSyncValid && !this.hasErrors();
+        });
+    }
+    validateGroupAsync(group_1) {
+        return __awaiter(this, arguments, void 0, function* (group, isSubmitting = false) {
+            const fields = this.getValidationGroupFields(group);
+            if (fields.length === 0) {
+                return true;
+            }
+            const isSyncValid = this.validateGroup(group, isSubmitting, { skipAsyncValidation: true });
+            for (const field of fields) {
+                yield this.validateFieldAsync(field, {
+                    isSubmitting,
+                    isTouched: this.isTouched(field),
+                    skipSyncValidation: true
+                });
+            }
+            return isSyncValid && !this.hasErrorsInGroup(group);
+        });
+    }
+    touchGroup(group) {
+        for (const field of this.getValidationGroupFields(group)) {
+            this.touch(field);
+        }
+    }
     fillState(data) {
         var _a;
         const driver = this.getPersistenceDriver((_a = this.options) === null || _a === void 0 ? void 0 : _a.persistSuffix);
@@ -606,7 +1190,13 @@ export class BaseForm {
             if (currentVal instanceof PropertyAwareArray) {
                 const values = newVal instanceof PropertyAwareArray || Array.isArray(newVal) ? Array.from(newVal) : [];
                 this.replacePropertyAwareArray(key, values);
-                this.dirty[key] = values.map(() => false);
+                this.dirty[key] = this.computeDirtyState(this.state[key], this.original[key]);
+                this.touched[key] = true;
+                continue;
+            }
+            if (isPropertyAwareObject(currentVal)) {
+                this.state[key] = restorePropertyAwareStructure(currentVal, newVal);
+                this.dirty[key] = this.computeDirtyState(this.state[key], this.original[key]);
                 this.touched[key] = true;
                 continue;
             }
@@ -659,6 +1249,17 @@ export class BaseForm {
         if (value instanceof PropertyAwareArray) {
             return [...value].map((item) => this.transformValue(item, parentKey));
         }
+        if (isPropertyAwareObject(value)) {
+            const result = {};
+            const valueRecord = value;
+            for (const prop in valueRecord) {
+                const transformed = this.transformValue(valueRecord[prop], parentKey);
+                if (transformed !== undefined) {
+                    result[prop] = transformed;
+                }
+            }
+            return result;
+        }
         if (Array.isArray(value)) {
             return value.map((item) => this.transformValue(item, parentKey));
         }
@@ -742,6 +1343,11 @@ export class BaseForm {
                 this.dirty[typedKey] = values.map(() => false);
                 this.touched[typedKey] = false;
             }
+            else if (isPropertyAwareObject(this.state[key])) {
+                this.state[key] = restorePropertyAwareStructure(this.original[key], cloneDeep(this.original[key]));
+                this.dirty[key] = false;
+                this.touched[key] = false;
+            }
             else if (Array.isArray(this.original[key])) {
                 this.state[key] = cloneDeep(this.original[key]);
                 this.dirty[key] = this.computeDirtyState(this.state[key], this.original[key]);
@@ -753,9 +1359,7 @@ export class BaseForm {
                 this.touched[key] = false;
             }
         }
-        for (const key in this._errors) {
-            delete this._errors[key];
-        }
+        this.clearErrors();
         this.persistState(driver);
         this.validate();
     }
@@ -820,65 +1424,47 @@ export class BaseForm {
         for (const key of Object.keys(this.state)) {
             const value = this.state[key];
             if (value instanceof PropertyAwareArray) {
-                const arrayProps = [...value].map((item, index) => {
-                    if (isRecord(item)) {
-                        const elementProps = {};
-                        for (const innerKey of Object.keys(item)) {
-                            elementProps[innerKey] = {
-                                model: computed({
-                                    get: () => {
-                                        const current = value[index];
-                                        return isRecord(current) ? current[innerKey] : undefined;
-                                    },
-                                    set: (newVal) => {
-                                        const current = value[index];
-                                        if (isRecord(current)) {
-                                            current[innerKey] = newVal;
-                                        }
-                                        const updatedElement = value[index];
-                                        const originalElement = this.original[key][index];
-                                        this.setArrayDirty(key, index, this.computeDirtyState(updatedElement, originalElement));
-                                        this.touched[key] = true;
-                                        this.validateField(key);
-                                        this.validateDependentFields(key);
-                                    }
-                                }),
-                                errors: this.getArrayItemFieldErrors(key, index, innerKey),
-                                dirty: this.getArrayItemDirty(key, index, innerKey),
-                                touched: this.touched[key] || false
-                            };
+                props[key] = this.getOrCreateArrayWrappers(key, value);
+                continue;
+            }
+            if (isPropertyAwareObject(value)) {
+                props[key] = this.createObjectWrapperFromShape(key, value, (path) => {
+                    let current = this.state[key];
+                    for (const segment of path) {
+                        if (!isRecord(current)) {
+                            return undefined;
                         }
-                        return elementProps;
+                        current = current[segment];
+                    }
+                    return current;
+                }, (path, newValue) => {
+                    const current = this.state[key];
+                    if (!isRecord(current)) {
+                        return;
+                    }
+                    const segments = [...path];
+                    const last = segments.pop();
+                    if (last === undefined) {
+                        return;
                     }
-                    return {
-                        value: {
-                            model: computed({
-                                get: () => value[index],
-                                set: (newVal) => {
-                                    value[index] = newVal;
-                                    const updatedValue = value[index];
-                                    const originalValue = this.original[key][index];
-                                    this.setArrayDirty(key, index, this.computeDirtyState(updatedValue, originalValue));
-                                    this.touched[key] = true;
-                                    this.validateField(key);
-                                    this.validateDependentFields(key);
-                                }
-                            }),
-                            errors: this.getArrayItemErrorMessages(key, index),
-                            dirty: this.getArrayItemDirtyValue(key, index),
-                            touched: this.touched[key] || false
+                    let record = current;
+                    for (const segment of segments) {
+                        if (!isRecord(record[segment])) {
+                            return;
                         }
-                    };
-                });
-                props[key] = arrayProps;
+                        record = record[segment];
+                    }
+                    record[last] = newValue;
+                    this.dirty[key] = this.computeDirtyState(this.state[key], this.original[key]);
+                    this.touched[key] = true;
+                    this.validateFieldPreservingNestedErrors(key, path);
+                    this.validateDependentFields(key);
+                }, (path) => this.getObjectFieldErrors(String(key), path), (path) => this.getNestedDirtyValue(this.dirty[key], path), () => this.touched[key] || false);
                 continue;
             }
-            props[key] = {
-                model: this._model[key],
-                errors: this.getFieldErrors(key),
-                dirty: this.dirty[key] || false,
-                touched: this.touched[key] || false
-            };
+            props[key] = this.createFieldProperty(() => this._model[key].value, (newValue) => {
+                this._model[key].value = newValue;
+            }, () => this.getFieldErrors(key), () => this.dirty[key] || false, () => this.touched[key] || false);
         }
         return props;
     }
@@ -889,42 +1475,10 @@ export class BaseForm {
      */
     isDirty(field) {
         if (field !== undefined) {
-            const dirtyState = this.dirty[field];
-            if (typeof dirtyState === 'boolean') {
-                return dirtyState;
-            }
-            if (Array.isArray(dirtyState)) {
-                return dirtyState.some((item) => {
-                    if (typeof item === 'boolean') {
-                        return item;
-                    }
-                    if (item && typeof item === 'object') {
-                        return Object.values(item).some((v) => v === true);
-                    }
-                    return false;
-                });
-            }
-            if (dirtyState && typeof dirtyState === 'object') {
-                return Object.values(dirtyState).some((v) => v === true);
-            }
-            return false;
+            return this.getNestedDirtyValue(this.dirty[field], []);
         }
         for (const key in this.dirty) {
-            const dirtyState = this.dirty[key];
-            if (typeof dirtyState === 'boolean' && dirtyState) {
-                return true;
-            }
-            if (Array.isArray(dirtyState)) {
-                for (const item of dirtyState) {
-                    if (typeof item === 'boolean' && item) {
-                        return true;
-                    }
-                    if (item && typeof item === 'object' && Object.values(item).some((v) => v === true)) {
-                        return true;
-                    }
-                }
-            }
-            if (dirtyState && typeof dirtyState === 'object' && Object.values(dirtyState).some((v) => v === true)) {
+            if (this.getNestedDirtyValue(this.dirty[key], [])) {
                 return true;
             }
         }
@@ -937,6 +1491,21 @@ export class BaseForm {
     hasErrors() {
         return this._hasErrors.value;
     }
+    getErrors() {
+        return this.flattenErrors();
+    }
+    hasErrorsInGroup(group) {
+        return Object.keys(this.flattenErrors()).some((errorKey) => this.errorKeyBelongsToGroup(errorKey, group));
+    }
+    getErrorsInGroup(group) {
+        const groupErrors = {};
+        for (const [errorKey, errorMessages] of Object.entries(this.flattenErrors())) {
+            if (this.errorKeyBelongsToGroup(errorKey, group)) {
+                groupErrors[errorKey] = cloneDeep(errorMessages);
+            }
+        }
+        return groupErrors;
+    }
     /**
      * Updates both the state and original value for a given property,
      * keeping the field in a clean (not dirty) state.