@ukhomeoffice/formio-gds-template 3.0.0-delta → 3.0.0-echo

package/lib/components/util/avoidCalculatedValueRedraw.d.ts

@@ -0,0 +1,28 @@
+interface ComponentInstance {
+    component: {
+        calculateValue?: string;
+        calculateValueVariable?: string;
+        redrawOn?: string | string[];
+        refreshOn?: string | string[];
+    };
+}
+interface ComponentPrototype {
+    __gdsCalculatedValueRedrawGuardInstalled?: boolean;
+    checkRefreshOn: (this: ComponentInstance, changes: unknown[], flags?: unknown) => void;
+}
+interface ComponentConstructor {
+    prototype: ComponentPrototype;
+}
+/**
+ * Avoid a Form.io v5 redraw loop for calculated display fields.
+ *
+ * Older forms commonly combine `calculateValue` with `redrawOn: "data"` so a
+ * disabled summary field reflects the latest calculation. In Form.io v5 every
+ * input event now refreshes and redraws those components before immediately
+ * calculating them. `calculateComponentValue` already calls `setValue` when
+ * the calculated result changes, so the full DOM redraw is redundant and can
+ * make a page visibly flicker while entering a multi-part value such as a date.
+ */
+export declare const installCalculatedValueRedrawGuard: (ComponentClass?: ComponentConstructor) => void;
+export {};
+//# sourceMappingURL=avoidCalculatedValueRedraw.d.ts.map

package/lib/components/util/avoidCalculatedValueRedraw.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"avoidCalculatedValueRedraw.d.ts","sourceRoot":"","sources":["../../../src/components/util/avoidCalculatedValueRedraw.ts"],"names":[],"mappings":"AAEA,UAAU,iBAAiB;IACvB,SAAS,EAAE;QACP,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,sBAAsB,CAAC,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;QAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;KACjC,CAAC;CACL;AAED,UAAU,kBAAkB;IACxB,wCAAwC,CAAC,EAAE,OAAO,CAAC;IACnD,cAAc,EAAE,CACZ,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,OAAO,EAAE,EAClB,KAAK,CAAC,EAAE,OAAO,KACd,IAAI,CAAC;CACb;AAED,UAAU,oBAAoB;IAC1B,SAAS,EAAE,kBAAkB,CAAC;CACjC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,iCAAiC,oBAC1B,oBAAoB,KACrC,IA2BF,CAAC"}

package/lib/components/util/avoidCalculatedValueRedraw.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installCalculatedValueRedrawGuard = void 0;
+const js_1 = require("@formio/js");
+/**
+ * Avoid a Form.io v5 redraw loop for calculated display fields.
+ *
+ * Older forms commonly combine `calculateValue` with `redrawOn: "data"` so a
+ * disabled summary field reflects the latest calculation. In Form.io v5 every
+ * input event now refreshes and redraws those components before immediately
+ * calculating them. `calculateComponentValue` already calls `setValue` when
+ * the calculated result changes, so the full DOM redraw is redundant and can
+ * make a page visibly flicker while entering a multi-part value such as a date.
+ */
+const installCalculatedValueRedrawGuard = (ComponentClass = js_1.Components.components.component) => {
+    const prototype = ComponentClass.prototype;
+    if (prototype.__gdsCalculatedValueRedrawGuardInstalled) {
+        return;
+    }
+    prototype.__gdsCalculatedValueRedrawGuardInstalled = true;
+    const originalCheckRefreshOn = prototype.checkRefreshOn;
+    prototype.checkRefreshOn = function (changes, flags) {
+        const component = this.component;
+        const hasCalculation = Boolean(component.calculateValue || component.calculateValueVariable);
+        const redrawsForAllData = component.redrawOn === 'data';
+        if (hasCalculation && redrawsForAllData && !component.refreshOn) {
+            return;
+        }
+        originalCheckRefreshOn.call(this, changes, flags);
+    };
+};
+exports.installCalculatedValueRedrawGuard = installCalculatedValueRedrawGuard;

package/lib/components/util/deferPristineErrors.d.ts

@@ -0,0 +1,47 @@
+type ValidationResult = unknown;
+interface ComponentInstance {
+    __gdsValidationAttempted?: boolean;
+    component?: {
+        clearOnHide?: boolean;
+    };
+    pristine: boolean;
+    root?: ValidationRoot;
+    setPristine?: (pristine: boolean) => void;
+    setCustomValidity: (messages: unknown) => ValidationResult;
+    visible?: boolean;
+}
+interface ValidationRoot {
+    __gdsValidationAttemptInProgress?: boolean;
+    submitting?: boolean;
+}
+interface ComponentPrototype {
+    __gdsDeferPristineErrorsInstalled?: boolean;
+    checkComponentConditions: (this: ComponentInstance, data?: unknown, flags?: unknown, row?: unknown) => boolean;
+    setComponentValidity: (this: ComponentInstance, errors: unknown[], dirty: boolean, silentCheck: boolean) => ValidationResult;
+}
+interface ComponentConstructor {
+    prototype: ComponentPrototype;
+}
+interface WizardPrototype extends ValidationRoot {
+    __gdsDeferPristineErrorsInstalled?: boolean;
+    nextPage: (...args: unknown[]) => unknown;
+}
+interface WizardConstructor {
+    prototype: WizardPrototype;
+}
+/**
+ * Restore Form.io v4's user-facing validation timing for Form.io v5.
+ *
+ * Form.io v5 validates the whole component tree after a value changes. Some
+ * pristine components have non-empty structural default values (objects,
+ * arrays, or conditionally-created container data), which makes the base
+ * implementation present their errors during an unrelated change.
+ *
+ * Validation still runs and remains available through component.errors. This
+ * patch only defers setCustomValidity, which renders the error, until the
+ * component has changed or Form.io explicitly validates it as dirty during
+ * wizard navigation or submission.
+ */
+export declare const installDeferredPristineErrors: (ComponentClass?: ComponentConstructor, WizardClass?: WizardConstructor) => void;
+export {};
+//# sourceMappingURL=deferPristineErrors.d.ts.map

package/lib/components/util/deferPristineErrors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferPristineErrors.d.ts","sourceRoot":"","sources":["../../../src/components/util/deferPristineErrors.ts"],"names":[],"mappings":"AAEA,KAAK,gBAAgB,GAAG,OAAO,CAAC;AAEhC,UAAU,iBAAiB;IACvB,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,SAAS,CAAC,EAAE;QACR,WAAW,CAAC,EAAE,OAAO,CAAC;KACzB,CAAC;IACF,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IAC1C,iBAAiB,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,gBAAgB,CAAC;IAC3D,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,UAAU,cAAc;IACpB,gCAAgC,CAAC,EAAE,OAAO,CAAC;IAC3C,UAAU,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,UAAU,kBAAkB;IACxB,iCAAiC,CAAC,EAAE,OAAO,CAAC;IAC5C,wBAAwB,EAAE,CACtB,IAAI,EAAE,iBAAiB,EACvB,IAAI,CAAC,EAAE,OAAO,EACd,KAAK,CAAC,EAAE,OAAO,EACf,GAAG,CAAC,EAAE,OAAO,KACZ,OAAO,CAAC;IACb,oBAAoB,EAAE,CAClB,IAAI,EAAE,iBAAiB,EACvB,MAAM,EAAE,OAAO,EAAE,EACjB,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,OAAO,KACnB,gBAAgB,CAAC;CACzB;AAED,UAAU,oBAAoB;IAC1B,SAAS,EAAE,kBAAkB,CAAC;CACjC;AAED,UAAU,eAAgB,SAAQ,cAAc;IAC5C,iCAAiC,CAAC,EAAE,OAAO,CAAC;IAC5C,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;CAC7C;AAED,UAAU,iBAAiB;IACvB,SAAS,EAAE,eAAe,CAAC;CAC9B;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,6BAA6B,oBACtB,oBAAoB,gBACvB,iBAAiB,KAC/B,IAkFF,CAAC"}

package/lib/components/util/deferPristineErrors.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installDeferredPristineErrors = void 0;
+const js_1 = require("@formio/js");
+/**
+ * Restore Form.io v4's user-facing validation timing for Form.io v5.
+ *
+ * Form.io v5 validates the whole component tree after a value changes. Some
+ * pristine components have non-empty structural default values (objects,
+ * arrays, or conditionally-created container data), which makes the base
+ * implementation present their errors during an unrelated change.
+ *
+ * Validation still runs and remains available through component.errors. This
+ * patch only defers setCustomValidity, which renders the error, until the
+ * component has changed or Form.io explicitly validates it as dirty during
+ * wizard navigation or submission.
+ */
+const installDeferredPristineErrors = (ComponentClass = js_1.Components.components.component, WizardClass = js_1.Displays.getDisplay('wizard')) => {
+    const prototype = ComponentClass.prototype;
+    if (!prototype.__gdsDeferPristineErrorsInstalled) {
+        prototype.__gdsDeferPristineErrorsInstalled = true;
+        const originalSetComponentValidity = prototype.setComponentValidity;
+        const originalCheckComponentConditions = prototype.checkComponentConditions;
+        prototype.checkComponentConditions = function (data, flags, row) {
+            var _a;
+            const wasVisible = this.visible !== false;
+            const result = originalCheckComponentConditions.call(this, data, flags, row);
+            if (wasVisible &&
+                this.visible === false &&
+                ((_a = this.component) === null || _a === void 0 ? void 0 : _a.clearOnHide) !== false) {
+                delete this.__gdsValidationAttempted;
+                if (this.setPristine) {
+                    this.setPristine(true);
+                }
+                else {
+                    this.pristine = true;
+                }
+                this.setCustomValidity('');
+            }
+            return result;
+        };
+        prototype.setComponentValidity = function (errors, dirty, silentCheck) {
+            var _a, _b;
+            const validationAttemptInProgress = Boolean(((_a = this.root) === null || _a === void 0 ? void 0 : _a.submitting) || ((_b = this.root) === null || _b === void 0 ? void 0 : _b.__gdsValidationAttemptInProgress));
+            if (dirty && validationAttemptInProgress && this.visible !== false) {
+                this.__gdsValidationAttempted = true;
+            }
+            if (this.pristine && !this.__gdsValidationAttempted) {
+                return silentCheck ? [] : this.setCustomValidity('');
+            }
+            return originalSetComponentValidity.call(this, errors, dirty, silentCheck);
+        };
+    }
+    const wizardPrototype = WizardClass.prototype;
+    if (!wizardPrototype.__gdsDeferPristineErrorsInstalled) {
+        wizardPrototype.__gdsDeferPristineErrorsInstalled = true;
+        const originalNextPage = wizardPrototype.nextPage;
+        wizardPrototype.nextPage = function (...args) {
+            const previousState = this.__gdsValidationAttemptInProgress;
+            this.__gdsValidationAttemptInProgress = true;
+            try {
+                return originalNextPage.apply(this, args);
+            }
+            finally {
+                this.__gdsValidationAttemptInProgress = previousState;
+            }
+        };
+    }
+};
+exports.installDeferredPristineErrors = installDeferredPristineErrors;

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGA,wBAIE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAQA,wBAIE"}

package/lib/index.js

@@ -4,7 +4,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const components_1 = __importDefault(require("./components"));
+const avoidCalculatedValueRedraw_1 = require("./components/util/avoidCalculatedValueRedraw");
+const deferPristineErrors_1 = require("./components/util/deferPristineErrors");
 const templates_1 = __importDefault(require("./templates"));
+(0, avoidCalculatedValueRedraw_1.installCalculatedValueRedrawGuard)();
+(0, deferPristineErrors_1.installDeferredPristineErrors)();
 exports.default = {
     framework: 'gds',
     templates: templates_1.default,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ukhomeoffice/formio-gds-template",
-  "version": "3.0.0-delta",
+  "version": "3.0.0-echo",
   "description": "Gov UK design system formio templates — upgraded to @formio/js@5.x",
   "publishConfig": {
     "access": "public"

package/src/components/util/avoidCalculatedValueRedraw.spec.ts

@@ -0,0 +1,64 @@
+import assert from 'assert';
+import sinon from 'sinon';
+import { installCalculatedValueRedrawGuard } from './avoidCalculatedValueRedraw';
+
+class TestComponent {
+    public component: {
+        calculateValue?: string;
+        calculateValueVariable?: string;
+        redrawOn?: string | string[];
+        refreshOn?: string | string[];
+    } = {};
+
+    public refreshed = sinon.stub();
+
+    public checkRefreshOn(changes: unknown[], flags?: unknown): void {
+        this.refreshed(changes, flags);
+    }
+}
+
+describe('installCalculatedValueRedrawGuard', () => {
+    before(() => {
+        installCalculatedValueRedrawGuard(TestComponent);
+    });
+
+    it('skips the redundant data redraw for a calculated field', () => {
+        const component = new TestComponent();
+        component.component.calculateValue = 'value = row.number';
+        component.component.redrawOn = 'data';
+
+        component.checkRefreshOn([{ value: 'new value' }], {});
+
+        assert.strictEqual(component.refreshed.notCalled, true);
+    });
+
+    it('preserves redrawOn data for a field without a calculation', () => {
+        const component = new TestComponent();
+        component.component.redrawOn = 'data';
+        const changes = [{ value: 'new value' }];
+        const flags = { changed: true };
+
+        component.checkRefreshOn(changes, flags);
+
+        assert.strictEqual(component.refreshed.calledOnceWithExactly(changes, flags), true);
+    });
+
+    it('preserves an explicit refreshOn dependency', () => {
+        const component = new TestComponent();
+        component.component.calculateValue = 'value = row.number';
+        component.component.redrawOn = 'data';
+        component.component.refreshOn = 'number';
+
+        component.checkRefreshOn([], {});
+
+        assert.strictEqual(component.refreshed.calledOnce, true);
+    });
+
+    it('installs only once', () => {
+        const installedMethod = TestComponent.prototype.checkRefreshOn;
+
+        installCalculatedValueRedrawGuard(TestComponent);
+
+        assert.strictEqual(TestComponent.prototype.checkRefreshOn, installedMethod);
+    });
+});

package/src/components/util/avoidCalculatedValueRedraw.ts

@@ -0,0 +1,64 @@
+import { Components } from '@formio/js';
+
+interface ComponentInstance {
+    component: {
+        calculateValue?: string;
+        calculateValueVariable?: string;
+        redrawOn?: string | string[];
+        refreshOn?: string | string[];
+    };
+}
+
+interface ComponentPrototype {
+    __gdsCalculatedValueRedrawGuardInstalled?: boolean;
+    checkRefreshOn: (
+        this: ComponentInstance,
+        changes: unknown[],
+        flags?: unknown,
+    ) => void;
+}
+
+interface ComponentConstructor {
+    prototype: ComponentPrototype;
+}
+
+/**
+ * Avoid a Form.io v5 redraw loop for calculated display fields.
+ *
+ * Older forms commonly combine `calculateValue` with `redrawOn: "data"` so a
+ * disabled summary field reflects the latest calculation. In Form.io v5 every
+ * input event now refreshes and redraws those components before immediately
+ * calculating them. `calculateComponentValue` already calls `setValue` when
+ * the calculated result changes, so the full DOM redraw is redundant and can
+ * make a page visibly flicker while entering a multi-part value such as a date.
+ */
+export const installCalculatedValueRedrawGuard = (
+    ComponentClass: ComponentConstructor = Components.components.component,
+): void => {
+    const prototype = ComponentClass.prototype;
+
+    if (prototype.__gdsCalculatedValueRedrawGuardInstalled) {
+        return;
+    }
+
+    prototype.__gdsCalculatedValueRedrawGuardInstalled = true;
+    const originalCheckRefreshOn = prototype.checkRefreshOn;
+
+    prototype.checkRefreshOn = function (
+        this: ComponentInstance,
+        changes: unknown[],
+        flags?: unknown,
+    ): void {
+        const component = this.component;
+        const hasCalculation = Boolean(
+            component.calculateValue || component.calculateValueVariable,
+        );
+        const redrawsForAllData = component.redrawOn === 'data';
+
+        if (hasCalculation && redrawsForAllData && !component.refreshOn) {
+            return;
+        }
+
+        originalCheckRefreshOn.call(this, changes, flags);
+    };
+};

package/src/components/util/deferPristineErrors.spec.ts

@@ -0,0 +1,201 @@
+import assert from 'assert';
+import sinon from 'sinon';
+import { installDeferredPristineErrors } from './deferPristineErrors';
+
+class TestComponent {
+    public __gdsValidationAttempted?: boolean;
+
+    public component: { clearOnHide?: boolean } = {};
+
+    public pristine = true;
+
+    public root?: TestWizard;
+
+    public setCustomValidity = sinon.stub().returns([]);
+
+    public visible = true;
+
+    public nextVisible?: boolean;
+
+    public checkComponentConditions(): boolean {
+        if (this.nextVisible !== undefined) {
+            this.visible = this.nextVisible;
+        }
+
+        return this.visible;
+    }
+
+    public setPristine(pristine: boolean): void {
+        this.pristine = pristine;
+    }
+
+    public setComponentValidity(
+        errors: unknown[],
+        dirty: boolean,
+        silentCheck: boolean,
+    ): unknown {
+        return { errors, dirty, silentCheck };
+    }
+}
+
+class TestWizard {
+    public __gdsValidationAttemptInProgress?: boolean;
+
+    public component?: TestComponent;
+
+    public submitting = false;
+
+    public nextPage(): unknown {
+        return this.component?.setComponentValidity(
+            [{ level: 'error', message: 'Required' }],
+            true,
+            false,
+        );
+    }
+}
+
+describe('installDeferredPristineErrors', () => {
+    before(() => {
+        installDeferredPristineErrors(TestComponent, TestWizard);
+    });
+
+    it('does not present errors for a pristine component during an unrelated change', () => {
+        const component = new TestComponent();
+
+        const result = component.setComponentValidity(
+            [{ level: 'error', message: 'Required' }],
+            false,
+            false,
+        );
+
+        assert.deepStrictEqual(result, []);
+        assert.strictEqual(component.setCustomValidity.calledOnceWithExactly(''), true);
+    });
+
+    it('delegates dirty validation used by Next', () => {
+        const component = new TestComponent();
+        const wizard = new TestWizard();
+        component.root = wizard;
+        wizard.component = component;
+        const errors = [{ level: 'error', message: 'Required' }];
+
+        const result = wizard.nextPage();
+
+        assert.deepStrictEqual(result, { errors, dirty: true, silentCheck: false });
+        assert.strictEqual(component.setCustomValidity.notCalled, true);
+        assert.strictEqual(component.__gdsValidationAttempted, true);
+    });
+
+    it('delegates dirty validation while a form is submitting', () => {
+        const component = new TestComponent();
+        const wizard = new TestWizard();
+        wizard.submitting = true;
+        component.root = wizard;
+        const errors = [{ level: 'error', message: 'Required' }];
+
+        const result = component.setComponentValidity(errors, true, false);
+
+        assert.deepStrictEqual(result, { errors, dirty: true, silentCheck: false });
+        assert.strictEqual(component.__gdsValidationAttempted, true);
+    });
+
+    it('does not apply an earlier submission attempt to a newly revealed component', () => {
+        const component = new TestComponent();
+        component.root = new TestWizard();
+
+        const result = component.setComponentValidity(
+            [{ level: 'error', message: 'Required' }],
+            true,
+            false,
+        );
+
+        assert.deepStrictEqual(result, []);
+        assert.strictEqual(component.setCustomValidity.calledOnceWithExactly(''), true);
+        assert.strictEqual(component.__gdsValidationAttempted, undefined);
+    });
+
+    it('does not mark a conditionally hidden field during Next before it is revealed', () => {
+        const component = new TestComponent();
+        const wizard = new TestWizard();
+        component.root = wizard;
+        component.visible = false;
+        wizard.component = component;
+
+        const hiddenResult = wizard.nextPage();
+
+        assert.deepStrictEqual(hiddenResult, []);
+        assert.strictEqual(component.__gdsValidationAttempted, undefined);
+
+        component.visible = true;
+        component.setCustomValidity.resetHistory();
+
+        const revealedResult = component.setComponentValidity(
+            [{ level: 'error', message: 'Mode of transport is required' }],
+            true,
+            false,
+        );
+
+        assert.deepStrictEqual(revealedResult, []);
+        assert.strictEqual(component.setCustomValidity.calledOnceWithExactly(''), true);
+        assert.strictEqual(component.__gdsValidationAttempted, undefined);
+    });
+
+    it('resets a clear-on-hide field when it is hidden and revealed again', () => {
+        const component = new TestComponent();
+        component.pristine = false;
+        component.__gdsValidationAttempted = true;
+        component.nextVisible = false;
+
+        const hiddenResult = component.checkComponentConditions();
+
+        assert.strictEqual(hiddenResult, false);
+        assert.strictEqual(component.pristine, true);
+        assert.strictEqual(component.__gdsValidationAttempted, undefined);
+        assert.strictEqual(component.setCustomValidity.calledOnceWithExactly(''), true);
+
+        component.visible = true;
+        component.setCustomValidity.resetHistory();
+
+        const revealedResult = component.setComponentValidity(
+            [{ level: 'error', message: 'Required' }],
+            false,
+            false,
+        );
+
+        assert.deepStrictEqual(revealedResult, []);
+        assert.strictEqual(component.setCustomValidity.calledOnceWithExactly(''), true);
+    });
+
+    it('preserves validation state when clearOnHide is disabled', () => {
+        const component = new TestComponent();
+        component.component.clearOnHide = false;
+        component.pristine = false;
+        component.__gdsValidationAttempted = true;
+        component.nextVisible = false;
+
+        component.checkComponentConditions();
+
+        assert.strictEqual(component.pristine, false);
+        assert.strictEqual(component.__gdsValidationAttempted, true);
+        assert.strictEqual(component.setCustomValidity.notCalled, true);
+    });
+
+    it('delegates validation after a component has changed', () => {
+        const component = new TestComponent();
+        component.pristine = false;
+        const errors = [{ level: 'error', message: 'Required' }];
+
+        const result = component.setComponentValidity(errors, false, false);
+
+        assert.deepStrictEqual(result, { errors, dirty: false, silentCheck: false });
+        assert.strictEqual(component.setCustomValidity.notCalled, true);
+    });
+
+    it('installs only once', () => {
+        const installedMethod = TestComponent.prototype.setComponentValidity;
+
+        installDeferredPristineErrors(TestComponent, TestWizard);
+
+        assert.strictEqual(TestComponent.prototype.setComponentValidity, installedMethod);
+    });
+});

package/src/components/util/deferPristineErrors.ts

@@ -0,0 +1,149 @@
+import { Components, Displays } from '@formio/js';
+
+type ValidationResult = unknown;
+
+interface ComponentInstance {
+    __gdsValidationAttempted?: boolean;
+    component?: {
+        clearOnHide?: boolean;
+    };
+    pristine: boolean;
+    root?: ValidationRoot;
+    setPristine?: (pristine: boolean) => void;
+    setCustomValidity: (messages: unknown) => ValidationResult;
+    visible?: boolean;
+}
+
+interface ValidationRoot {
+    __gdsValidationAttemptInProgress?: boolean;
+    submitting?: boolean;
+}
+
+interface ComponentPrototype {
+    __gdsDeferPristineErrorsInstalled?: boolean;
+    checkComponentConditions: (
+        this: ComponentInstance,
+        data?: unknown,
+        flags?: unknown,
+        row?: unknown,
+    ) => boolean;
+    setComponentValidity: (
+        this: ComponentInstance,
+        errors: unknown[],
+        dirty: boolean,
+        silentCheck: boolean,
+    ) => ValidationResult;
+}
+
+interface ComponentConstructor {
+    prototype: ComponentPrototype;
+}
+
+interface WizardPrototype extends ValidationRoot {
+    __gdsDeferPristineErrorsInstalled?: boolean;
+    nextPage: (...args: unknown[]) => unknown;
+}
+
+interface WizardConstructor {
+    prototype: WizardPrototype;
+}
+
+/**
+ * Restore Form.io v4's user-facing validation timing for Form.io v5.
+ *
+ * Form.io v5 validates the whole component tree after a value changes. Some
+ * pristine components have non-empty structural default values (objects,
+ * arrays, or conditionally-created container data), which makes the base
+ * implementation present their errors during an unrelated change.
+ *
+ * Validation still runs and remains available through component.errors. This
+ * patch only defers setCustomValidity, which renders the error, until the
+ * component has changed or Form.io explicitly validates it as dirty during
+ * wizard navigation or submission.
+ */
+export const installDeferredPristineErrors = (
+    ComponentClass: ComponentConstructor = Components.components.component,
+    WizardClass: WizardConstructor = Displays.getDisplay('wizard'),
+): void => {
+    const prototype = ComponentClass.prototype;
+
+    if (!prototype.__gdsDeferPristineErrorsInstalled) {
+        prototype.__gdsDeferPristineErrorsInstalled = true;
+
+        const originalSetComponentValidity = prototype.setComponentValidity;
+        const originalCheckComponentConditions = prototype.checkComponentConditions;
+
+        prototype.checkComponentConditions = function (
+            this: ComponentInstance,
+            data?: unknown,
+            flags?: unknown,
+            row?: unknown,
+        ): boolean {
+            const wasVisible = this.visible !== false;
+            const result = originalCheckComponentConditions.call(this, data, flags, row);
+
+            if (
+                wasVisible &&
+                this.visible === false &&
+                this.component?.clearOnHide !== false
+            ) {
+                delete this.__gdsValidationAttempted;
+
+                if (this.setPristine) {
+                    this.setPristine(true);
+                }
+                else {
+                    this.pristine = true;
+                }
+
+                this.setCustomValidity('');
+            }
+
+            return result;
+        };
+
+        prototype.setComponentValidity = function (
+            this: ComponentInstance,
+            errors: unknown[],
+            dirty: boolean,
+            silentCheck: boolean,
+        ): ValidationResult {
+            const validationAttemptInProgress = Boolean(
+                this.root?.submitting || this.root?.__gdsValidationAttemptInProgress,
+            );
+
+            if (dirty && validationAttemptInProgress && this.visible !== false) {
+                this.__gdsValidationAttempted = true;
+            }
+
+            if (this.pristine && !this.__gdsValidationAttempted) {
+                return silentCheck ? [] : this.setCustomValidity('');
+            }
+
+            return originalSetComponentValidity.call(this, errors, dirty, silentCheck);
+        };
+    }
+
+    const wizardPrototype = WizardClass.prototype;
+
+    if (!wizardPrototype.__gdsDeferPristineErrorsInstalled) {
+        wizardPrototype.__gdsDeferPristineErrorsInstalled = true;
+
+        const originalNextPage = wizardPrototype.nextPage;
+
+        wizardPrototype.nextPage = function (
+            this: WizardPrototype,
+            ...args: unknown[]
+        ): unknown {
+            const previousState = this.__gdsValidationAttemptInProgress;
+            this.__gdsValidationAttemptInProgress = true;
+
+            try {
+                return originalNextPage.apply(this, args);
+            }
+            finally {
+                this.__gdsValidationAttemptInProgress = previousState;
+            }
+        };
+    }
+};

package/src/index.ts

@@ -1,6 +1,11 @@
 import components from './components';
+import { installCalculatedValueRedrawGuard } from './components/util/avoidCalculatedValueRedraw';
+import { installDeferredPristineErrors } from './components/util/deferPristineErrors';
 import templates from './templates';
 
+installCalculatedValueRedrawGuard();
+installDeferredPristineErrors();
+
 export default {
   framework: 'gds',
   templates,