Merge remote-tracking branch 'origin/main' into benelan/8000-form-validation-ui

* origin/main:
  build: update browserslist db (#8565)
  fix(input, input-number, input-text): restore focus on input after browser validation error is displayed and user continues typing (#8563)
  docs(various components): consistent api description refs (#8550)

Author: benelan

package-lock.json

@@ -40,8 +40,13 @@ export class Accordion {
   @Prop({ reflect: true }) scale: Scale = "m";
 
   /**
-   * Specifies the selection mode - `"multiple"` (allow any number of open items), `"single"` (allow one open item),
-   * or `"single-persist"` (allow and require one open item).
+   * Specifies the selection mode of the component, where:
+   *
+   * `"multiple"` allows any number of selections,
+   *
+   * `"single"` allows only one selection, and
+   *
+   * `"single-persist"` allows one selection and prevents de-selection.
    */
   @Prop({ reflect: true }) selectionMode: Extract<
     "single" | "single-persist" | "multiple",

packages/calcite-components/src/components/accordion/accordion.tsx

@@ -50,10 +50,14 @@ export class ChipGroup implements InteractiveComponent {
   @Prop({ reflect: true }) scale: Scale = "m";
 
   /**
-   * Specifies the selection mode of the component:
+   * Specifies the selection mode of the component, where:
+   *
    * `"multiple"` allows any number of selections,
+   *
    * `"single"` allows only one selection,
-   * `"single-persist"` allow and require one selected item,
+   *
+   * `"single-persist"` allows one selection and prevents de-selection, and
+   *
    * `"none"` does not allow any selections.
    */
   @Prop({ reflect: true }) selectionMode: Extract<

packages/calcite-components/src/components/chip-group/chip-group.tsx

@@ -84,11 +84,15 @@ export class ComboboxItem implements ConditionalSlotComponent, InteractiveCompon
   @Prop({ reflect: true }) filterDisabled: boolean;
 
   /**
-   * Specifies the selection mode:
-   * - "multiple" allows any number of selected items (default),
-   * - "single" allows only one selection,
-   * - "single-persist" allow and require one open item,
-   * - "ancestors" is like multiple, but shows ancestors of selected items as selected, with only deepest children shown in chips.
+   * Specifies the selection mode of the component, where:
+   *
+   * `"multiple"` allows any number of selections,
+   *
+   * `"single"` allows only one selection,
+   *
+   * `"single-persist"` allows one selection and prevents de-selection, and
+   *
+   * `"ancestors"` allows multiple selections, but shows ancestors of selected items as selected, with only deepest children shown in chips.
    *
    * @internal
    */

packages/calcite-components/src/components/combobox-item/combobox-item.tsx

@@ -218,11 +218,15 @@ export class Combobox
   @Prop({ reflect: true }) required = false;
 
   /**
-   * Specifies the selection mode:
-   * `"multiple"` allows any number of selected items,
+   * Specifies the selection mode of the component, where:
+   *
+   * `"multiple"` allows any number of selections,
+   *
    * `"single"` allows only one selection,
-   * `"single-persist"` allow and require one open item,
-   * `"ancestors"` is like multiple, but shows ancestors of selected items as selected, with only deepest children shown in chips.
+   *
+   * `"single-persist"` allows one selection and prevents de-selection, and
+   *
+   * `"ancestors"` allows multiple selections, but shows ancestors of selected items as selected, with only deepest children shown in chips.
    */
   @Prop({ reflect: true }) selectionMode: Extract<
     "single" | "single-persist" | "ancestors" | "multiple",

packages/calcite-components/src/components/combobox/combobox.tsx

@@ -43,10 +43,13 @@ export class DropdownGroup {
   @Prop() scale: Scale = "m";
 
   /**
-   * Specifies the selection mode for `calcite-dropdown-item` children:
-   * `"multiple"` allows any number of selected items,
-   * `"single"` allows only one selection,
-   * `"none"` doesn't allow for any selection.
+   * Specifies the selection mode of the component, where:
+   *
+   * `"multiple"` allows any number of selections,
+   *
+   * `"single"` allows only one selection, and
+   *
+   * `"none"` does not allow any selections.
    */
   @Prop({ reflect: true }) selectionMode: Extract<"none" | "single" | "multiple", SelectionMode> =
     "single";

packages/calcite-components/src/components/dropdown-group/dropdown-group.tsx

@@ -152,7 +152,7 @@ export class InputDatePicker
     }
   }
 
-  /** Selected date as a string in ISO format (YYYY-MM-DD) */
+  /** Selected date as a string in ISO format (`"yyyy-mm-dd"`). */
   @Prop({ mutable: true }) value: string | string[] = "";
 
   @Watch("value")

packages/calcite-components/src/components/input-date-picker/input-date-picker.tsx

@@ -15,6 +15,7 @@ import {
 import { getElementRect, getElementXY, selectText } from "../../tests/utils";
 import { letterKeys, numberKeys } from "../../utils/key";
 import { locales, numberStringFormatter } from "../../utils/locale";
+import { testPostValidationFocusing } from "../input/common/tests";
 
 describe("calcite-input-number", () => {
   const delayFor2UpdatesInMs = 200;
@@ -1716,6 +1717,8 @@ describe("calcite-input-number", () => {
       submitsOnEnter: true,
       inputType: "number",
     });
+
+    testPostValidationFocusing("calcite-input-number");
   });
 
   describe("translation support", () => {

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

@@ -24,6 +24,7 @@ import {
   disconnectForm,
   FormComponent,
   HiddenFormInputSlot,
+  internalHiddenInputInputEvent,
   submitForm,
 } from "../../utils/form";
 import {
@@ -433,7 +434,7 @@ export class InputNumber
     });
     this.mutationObserver?.observe(this.el, { childList: true });
     this.setDisabledAction();
-    this.el.addEventListener("calciteInternalHiddenInputChange", this.hiddenInputChangeHandler);
+    this.el.addEventListener(internalHiddenInputInputEvent, this.onHiddenFormInputInput);
   }
 
   componentDidLoad(): void {
@@ -448,7 +449,7 @@ export class InputNumber
     disconnectMessages(this);
 
     this.mutationObserver?.disconnect();
-    this.el.removeEventListener("calciteInternalHiddenInputChange", this.hiddenInputChangeHandler);
+    this.el.removeEventListener(internalHiddenInputInputEvent, this.onHiddenFormInputInput);
   }
 
   async componentWillLoad(): Promise<void> {
@@ -785,13 +786,14 @@ export class InputNumber
     input.max = this.max?.toString(10) ?? "";
   }
 
-  hiddenInputChangeHandler = (event: Event): void => {
+  private onHiddenFormInputInput = (event: Event): void => {
     if ((event.target as HTMLInputElement).name === this.name) {
       this.setNumberValue({
         value: (event.target as HTMLInputElement).value,
         origin: "direct",
       });
     }
+    this.setFocus();
     event.stopPropagation();
   };
 

packages/calcite-components/src/components/input-number/input-number.tsx

@@ -12,6 +12,7 @@ import {
   t9n,
 } from "../../tests/commonTests";
 import { selectText } from "../../tests/utils";
+import { testPostValidationFocusing } from "../input/common/tests";
 
 describe("calcite-input-text", () => {
   describe("labelable", () => {
@@ -450,6 +451,8 @@ describe("calcite-input-text", () => {
 
   describe("is form-associated", () => {
     formAssociated("calcite-input-text", { testValue: "test", submitsOnEnter: true });
+
+    testPostValidationFocusing("calcite-input-text");
   });
 
   describe("translation support", () => {

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

@@ -17,6 +17,7 @@ import {
   disconnectForm,
   FormComponent,
   HiddenFormInputSlot,
+  internalHiddenInputInputEvent,
   submitForm,
 } from "../../utils/form";
 import {
@@ -335,7 +336,7 @@ export class InputText
     connectForm(this);
     this.mutationObserver?.observe(this.el, { childList: true });
     this.setDisabledAction();
-    this.el.addEventListener("calciteInternalHiddenInputChange", this.hiddenInputChangeHandler);
+    this.el.addEventListener(internalHiddenInputInputEvent, this.onHiddenFormInputInput);
   }
 
   disconnectedCallback(): void {
@@ -346,7 +347,7 @@ export class InputText
     disconnectMessages(this);
 
     this.mutationObserver?.disconnect();
-    this.el.removeEventListener("calciteInternalHiddenInputChange", this.hiddenInputChangeHandler);
+    this.el.removeEventListener(internalHiddenInputInputEvent, this.onHiddenFormInputInput);
   }
 
   async componentWillLoad(): Promise<void> {
@@ -516,13 +517,14 @@ export class InputText
     }
   }
 
-  hiddenInputChangeHandler = (event: Event): void => {
+  private onHiddenFormInputInput = (event: Event): void => {
     if ((event.target as HTMLInputElement).name === this.name) {
       this.setValue({
         value: (event.target as HTMLInputElement).value,
         origin: "direct",
       });
     }
+    this.setFocus();
     event.stopPropagation();
   };
 

packages/calcite-components/src/components/input-text/input-text.tsx

@@ -109,7 +109,9 @@ export class InputTimeZone
   /**
    * This specifies the type of `value` and the associated options presented to the user:
    *
-   * Using `"offset"` will provide options related
+   * Using `"offset"` will provide options that show timezone offsets.
+   *
+   * Using `"name"` will provide options that show the IANA time zone names.
    *
    * @default "offset"
    */

packages/calcite-components/src/components/input-time-zone/input-time-zone.tsx

@@ -0,0 +1,48 @@
+import { newE2EPage } from "@stencil/core/testing";
+import { isElementFocused } from "../../../tests/utils";
+import { hiddenFormInputSlotName } from "../../../utils/form";
+import { html } from "../../../../support/formatting";
+import { JSX } from "../../../components";
+
+export function testPostValidationFocusing(
+  inputTag: Extract<keyof JSX.IntrinsicElements, "calcite-input" | "calcite-input-text" | "calcite-input-number">,
+): void {
+  it("restores focus on invalid input if user continues typing", async () => {
+    const page = await newE2EPage();
+    const inputName = "test";
+
+    await page.setContent(html`
+        <form>
+          <${inputTag} type="text" required name="${inputName}"></${inputTag}>
+        </form>
+        <script>
+          const form = document.querySelector("form");
+          form.addEventListener("submit", (event) => {
+            event.preventDefault();
+          });
+        </script>
+      `);
+
+    const input = await page.find(inputTag);
+
+    await input.callMethod("setFocus");
+    await input.press("Enter");
+    await page.waitForChanges();
+
+    const hiddenInputSelector = `input[slot=${hiddenFormInputSlotName}]`;
+    const inputSelector = `${inputTag}[name=${inputName}]`;
+
+    expect(await isElementFocused(page, hiddenInputSelector)).toBe(true);
+    expect(await isElementFocused(page, inputSelector)).toBe(false);
+    expect(await input.getProperty("value")).toBe("");
+
+    const expectedValue = "12345"; // number works for both text and number types
+
+    await page.keyboard.type(expectedValue);
+    await page.waitForChanges();
+
+    expect(await isElementFocused(page, hiddenInputSelector)).toBe(false);
+    expect(await isElementFocused(page, inputSelector)).toBe(true);
+    expect(await input.getProperty("value")).toBe(expectedValue);
+  });
+}

packages/calcite-components/src/components/input/common/tests.ts

@@ -15,6 +15,7 @@ import { letterKeys, numberKeys } from "../../utils/key";
 import { locales, numberStringFormatter } from "../../utils/locale";
 import { getElementRect, getElementXY, selectText } from "../../tests/utils";
 import { KeyInput } from "puppeteer";
+import { testPostValidationFocusing } from "./common/tests";
 
 describe("calcite-input", () => {
   const delayFor2UpdatesInMs = 200;
@@ -2021,6 +2022,8 @@ describe("calcite-input", () => {
         inputType: type,
       });
     }
+
+    testPostValidationFocusing("calcite-input");
   });
 
   describe("translation support", () => {

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

@@ -24,6 +24,7 @@ import {
   disconnectForm,
   FormComponent,
   HiddenFormInputSlot,
+  internalHiddenInputInputEvent,
   submitForm,
 } from "../../utils/form";
 import {
@@ -499,7 +500,7 @@ export class Input
     this.mutationObserver?.observe(this.el, { childList: true });
 
     this.setDisabledAction();
-    this.el.addEventListener("calciteInternalHiddenInputChange", this.hiddenInputChangeHandler);
+    this.el.addEventListener(internalHiddenInputInputEvent, this.onHiddenFormInputInput);
   }
 
   disconnectedCallback(): void {
@@ -510,7 +511,7 @@ export class Input
     disconnectMessages(this);
 
     this.mutationObserver?.disconnect();
-    this.el.removeEventListener("calciteInternalHiddenInputChange", this.hiddenInputChangeHandler);
+    this.el.removeEventListener(internalHiddenInputInputEvent, this.onHiddenFormInputInput);
   }
 
   async componentWillLoad(): Promise<void> {
@@ -886,13 +887,14 @@ export class Input
     }
   }
 
-  hiddenInputChangeHandler = (event: Event): void => {
+  private onHiddenFormInputInput = (event: Event): void => {
     if ((event.target as HTMLInputElement).name === this.name) {
       this.setValue({
         value: (event.target as HTMLInputElement).value,
         origin: "direct",
       });
     }
+    this.setFocus();
     event.stopPropagation();
   };
 

packages/calcite-components/src/components/input/input.tsx

@@ -59,7 +59,7 @@ export class ListItemGroup implements InteractiveComponent {
   //--------------------------------------------------------------------------
 
   /**
-   * Emitted when the default slot has changes in order to notify parent lists.
+   * Fires when changes occur in the default slot, notifying parent lists of the changes.
    */
   @Event({ cancelable: false })
   calciteInternalListItemGroupDefaultSlotChange: EventEmitter<DragEvent>;

packages/calcite-components/src/components/list-item-group/list-item-group.tsx

@@ -236,7 +236,7 @@ export class ListItem
   //--------------------------------------------------------------------------
 
   /**
-   * Emits when the item's content is selected.
+   * Fires when the component is selected.
    */
   @Event({ cancelable: false }) calciteListItemSelect: EventEmitter<void>;