fix: don't override existing validationMessage when displaying after …

…form submission (#8690)

**Related Issue:** #8000 

## Summary

- Only set `validationMessage` property during form submission if it
doesn't have an existing value. This allows users to set a custom
validation message, which will be displayed instead of the default
message provided by the browser.

- Move the form validation e2e tests to the formAssociated common test,
which was [requested as a follow up
item](#8574 (comment)).

packages/calcite-components/src/components/combobox/combobox.e2e.ts

@@ -1609,7 +1609,7 @@ describe("calcite-combobox", () => {
         <calcite-combobox-item id="two" icon="beaker" value="two" text-label="Two" selected></calcite-combobox-item>
         <calcite-combobox-item id="three" value="three" text-label="Three"></calcite-combobox-item>
       </calcite-combobox>`,
-      { testValue: "two", submitsOnEnter: true },
+      { testValue: "two", submitsOnEnter: true, validation: true, changeValueKeys: ["Space", "Enter"] },
     );
   });
 

packages/calcite-components/src/components/input-date-picker/input-date-picker.e2e.ts

@@ -715,7 +715,7 @@ describe("calcite-input-date-picker", () => {
 
   describe("is form-associated", () => {
     describe("supports single value", () => {
-      formAssociated("calcite-input-date-picker", { testValue: "1985-03-23", submitsOnEnter: true });
+      formAssociated("calcite-input-date-picker", { testValue: "1985-03-23", submitsOnEnter: true, validation: true });
     });
 
     describe("supports range", () => {

packages/calcite-components/src/components/input-number/input-number.e2e.ts

@@ -1746,9 +1746,10 @@ describe("calcite-input-number", () => {
 
   describe("is form-associated", () => {
     formAssociated("calcite-input-number", {
-      testValue: 5,
+      testValue: "5",
       submitsOnEnter: true,
       inputType: "number",
+      validation: true,
     });
 
     testPostValidationFocusing("calcite-input-number");

packages/calcite-components/src/components/input-text/input-text.e2e.ts

@@ -462,7 +462,7 @@ describe("calcite-input-text", () => {
   });
 
   describe("is form-associated", () => {
-    formAssociated("calcite-input-text", { testValue: "test", submitsOnEnter: true });
+    formAssociated("calcite-input-text", { testValue: "test", submitsOnEnter: true, validation: true });
 
     testPostValidationFocusing("calcite-input-text");
   });

packages/calcite-components/src/components/input-time-picker/input-time-picker.e2e.ts

@@ -593,7 +593,12 @@ describe("calcite-input-time-picker", () => {
   });
 
   describe("is form-associated", () => {
-    formAssociated("calcite-input-time-picker", { testValue: "03:23", submitsOnEnter: true });
+    formAssociated("calcite-input-time-picker", {
+      testValue: "03:23",
+      submitsOnEnter: true,
+      validation: true,
+      validUserInputTestValue: "03:23 AM",
+    });
   });
 
   it("updates value appropriately as step changes", async () => {

packages/calcite-components/src/components/input/input.e2e.ts

@@ -2053,6 +2053,7 @@ describe("calcite-input", () => {
         testValue: value,
         submitsOnEnter: true,
         inputType: type,
+        validation: true,
       });
     }
 

packages/calcite-components/src/components/select/select.e2e.ts

@@ -406,12 +406,13 @@ describe("calcite-select", () => {
     formAssociated(
       html`
         <calcite-select>
+          <calcite-option id="0"></calcite-option>
           <calcite-option id="1">uno</calcite-option>
           <calcite-option id="2">dos</calcite-option>
           <calcite-option id="3">tres</calcite-option>
         </calcite-select>
       `,
-      { testValue: "dos" },
+      { testValue: "dos", validation: true, changeValueKeys: ["ArrowDown"] },
     );
   });
 });

packages/calcite-components/src/components/text-area/text-area.e2e.ts

@@ -99,6 +99,7 @@ describe("calcite-text-area", () => {
       testValue: "zion national park",
       expectedSubmitValue: "zion national park",
       submitsOnEnter: false,
+      validation: true,
     });
   });
 

packages/calcite-components/src/tests/commonTests.ts

@@ -6,7 +6,7 @@ import { toHaveNoViolations } from "jest-axe";
 import { config } from "../../stencil.config";
 import { html } from "../../support/formatting";
 import type { JSX } from "../components";
-import { hiddenFormInputSlotName } from "../utils/form";
+import { getClearValidationEventName, hiddenFormInputSlotName, componentsWithInputEvent } from "../utils/form";
 import { MessageBundle } from "../utils/t9n";
 import {
   GlobalTestProps,
@@ -15,6 +15,7 @@ import {
   newProgrammaticE2EPage,
   skipAnimations,
 } from "./utils";
+import { KeyInput } from "puppeteer";
 
 expect.extend(toHaveNoViolations);
 
@@ -685,10 +686,29 @@ interface FormAssociatedOptions {
   testValue: any;
 
   /**
-   * Set this if the expected submit value **is different** from stringifying `testValue`. For example, a component may transform an object to a serializable string.
+   * Set this if the expected submit value **is different** from stringifying `testValue`.
+   * For example, a component may transform an object to a serializable string.
    */
   expectedSubmitValue?: any;
 
+  /*
+   * Set this if the value required to emit an input/change event is different from `testValue`.
+   * The value is passed to `page.keyboard.type()`. For example, input-time-picker requires
+   * appending AM or PM before the value commits and calciteInputTimePickerChange emits.
+   *
+   * This option is only relevant when the `validation` option is enabled.
+   */
+  validUserInputTestValue?: string;
+
+  /*
+   * Set this if emitting an input/change event requires key presses. Each array item will be passed
+   * to `page.keyboard.press()`. For example, the combobox value can be changed by pressing "Space"
+   * to open the component and "Enter" to select a value.
+   *
+   * This option is only relevant when the `validation` option is enabled.
+   */
+  changeValueKeys?: KeyInput[];
+
   /**
    * Specifies the input type that will be used to capture the value.
    */
@@ -703,6 +723,11 @@ interface FormAssociatedOptions {
    * Specifies if the component supports clearing its value (i.e., setting to null).
    */
   clearable?: boolean;
+
+  /**
+   * Specifies if the component supports preventing submission and displaying validation messages.
+   */
+  validation?: boolean;
 }
 
 /**
@@ -717,8 +742,14 @@ export function formAssociated(
   componentTagOrHtml: TagOrHTML | TagOrHTMLWithBeforeContent,
   options: FormAssociatedOptions,
 ): void {
-  it("supports association via ancestry", () => testAncestorFormAssociated());
-  it("supports association via form ID", () => testIdFormAssociated());
+  const inputTypeContext = options?.inputType ? ` (input type="${options.inputType}")` : "";
+
+  it(`supports association via ancestry${inputTypeContext}`, () => testAncestorFormAssociated());
+  it(`supports association via form ID${inputTypeContext}`, () => testIdFormAssociated());
+
+  if (options?.validation && !["color", "month", "time"].includes(options?.inputType)) {
+    it(`supports required property validation${inputTypeContext}`, () => testRequiredPropertyValidation());
+  }
 
   async function testAncestorFormAssociated(): Promise<void> {
     const { beforeContent, tagOrHTML } = getTagOrHTMLWithBeforeContent(componentTagOrHtml);
@@ -777,14 +808,52 @@ export function formAssociated(
     }
   }
 
-  function ensureForm(html: string, componentTag: string): string {
-    return html.includes("form=") ? html : html.replace(componentTag, `${componentTag} form="test-form" `);
+  async function testRequiredPropertyValidation(): Promise<void> {
+    const requiredValidationMessage = "Please fill out this field.";
+    const { beforeContent, tagOrHTML } = getTagOrHTMLWithBeforeContent(componentTagOrHtml);
+    const tag = getTag(tagOrHTML);
+    const componentHtml = ensureUnchecked(
+      ensureRequired(ensureName(isHTML(tagOrHTML) ? tagOrHTML : `<${tag}></${tag}>`, tag), tag),
+    );
+
+    const page = await newE2EPage();
+    await beforeContent?.(page);
+
+    const content = html`
+      <form>
+        ${componentHtml}
+        <calcite-button id="submitButton" type="submit">Submit</calcite-button>
+      </form>
+    `;
+
+    await page.setContent(content);
+    await page.waitForChanges();
+    const component = await page.find(tag);
+
+    const submitButton = await page.find("#submitButton");
+    const spyEvent = await page.spyOnEvent(getClearValidationEventName(tag));
+
+    await assertPreventsFormSubmission(page, component, submitButton, requiredValidationMessage);
+    await assertClearsValidationOnValueChange(page, component, options, spyEvent, tag);
+    await assertUserMessageNotOverridden(page, component, submitButton);
   }
 
   function ensureName(html: string, componentTag: string): string {
     return html.includes("name=") ? html : html.replace(componentTag, `${componentTag} name="testName" `);
   }
 
+  function ensureRequired(html: string, componentTag: string): string {
+    return html.includes("required") ? html : html.replace(componentTag, `${componentTag} required `);
+  }
+
+  function ensureUnchecked(html: string): string {
+    return html.replace(/(checked|selected)/, "");
+  }
+
+  function ensureForm(html: string, componentTag: string): string {
+    return html.includes("form=") ? html : html.replace(componentTag, `${componentTag} form="test-form" `);
+  }
+
   async function isCheckable(page: E2EPage, component: E2EElement, options: FormAssociatedOptions): Promise<boolean> {
     return (
       typeof options.testValue === "boolean" &&
@@ -983,6 +1052,74 @@ export function formAssociated(
 
     expect(called).toBe(true);
   }
+
+  async function assertPreventsFormSubmission(
+    page: E2EPage,
+    component: E2EElement,
+    submitButton: E2EElement,
+    message: string,
+  ) {
+    await submitButton.click();
+    await page.waitForChanges();
+
+    await expectValidationInvalid(component, message);
+  }
+
+  async function assertClearsValidationOnValueChange(
+    page: E2EPage,
+    component: E2EElement,
+    options: FormAssociatedOptions,
+    event: EventSpy,
+    tag: string,
+  ) {
+    if (options?.changeValueKeys) {
+      for (const key of options.changeValueKeys) {
+        await page.keyboard.press(key);
+      }
+    } else {
+      await page.keyboard.type(options?.validUserInputTestValue ?? options.testValue);
+      await page.keyboard.press("Tab");
+    }
+
+    await page.waitForChanges();
+
+    // components with an Input event will emit multiple times depending on the length of testValue
+    if (componentsWithInputEvent.includes(tag)) {
+      expect(event.length).toBeGreaterThanOrEqual(1);
+    } else {
+      expect(event).toHaveReceivedEventTimes(1);
+    }
+
+    await expectValidationIdle(component);
+  }
+
+  async function assertUserMessageNotOverridden(page: E2EPage, component: E2EElement, submitButton: E2EElement) {
+    const customValidationMessage = "This is a custom message.";
+    const customValidationIcon = "banana";
+
+    // don't override custom validation message and icon
+    component.setProperty("validationMessage", customValidationMessage);
+    component.setProperty("validationIcon", customValidationIcon);
+    component.setProperty("value", undefined);
+    await page.waitForChanges();
+
+    await submitButton.click();
+    await page.waitForChanges();
+
+    await expectValidationInvalid(component, customValidationMessage, customValidationIcon);
+  }
+
+  async function expectValidationIdle(element: E2EElement) {
+    expect(await element.getProperty("status")).toBe("idle");
+    expect(await element.getProperty("validationMessage")).toBe("");
+    expect(await element.getProperty("validationIcon")).toBe(false);
+  }
+
+  async function expectValidationInvalid(element: E2EElement, message: string, icon: string = "") {
+    expect(await element.getProperty("status")).toBe("invalid");
+    expect(await element.getProperty("validationMessage")).toBe(message);
+    expect(element.getAttribute("validation-icon")).toBe(icon);
+  }
 }
 
 interface TabAndClickTargets {