feat(combobox): make combobox clearable

src/assets/styles/includes.scss

@@ -74,3 +74,57 @@
     pointer-events: none;
   }
 }
+
+@mixin xButton() {
+  :host([scale="s"]) {
+    .x-button {
+      inline-size: theme("spacing.4");
+      block-size: theme("spacing.4");
+    }
+  }
+
+  :host([scale="m"]) {
+    .x-button {
+      inline-size: theme("spacing.6");
+      block-size: theme("spacing.6");
+    }
+  }
+
+  :host([scale="l"]) {
+    .x-button {
+      inline-size: theme("spacing.8");
+      block-size: theme("spacing.8");
+    }
+  }
+
+  .x-button {
+    @apply flex
+    self-center
+    focus-base
+    transition-default
+    text-color-1
+    m-0
+    cursor-pointer
+    items-center
+    border-none
+    bg-transparent;
+    -webkit-appearance: none;
+    display: flex;
+    border-radius: 50%;
+    align-content: center;
+    justify-content: center;
+    &:hover {
+      background-color: var(--calcite-button-transparent-hover);
+    }
+    &:focus {
+      background-color: var(--calcite-button-transparent-press);
+      @apply focus-inset;
+    }
+    &:active {
+      background-color: var(--calcite-button-transparent-press);
+    }
+    & calcite-icon {
+      color: inherit;
+    }
+  }
+}

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

@@ -127,11 +127,14 @@ export class ComboboxItem implements ConditionalSlotComponent, InteractiveCompon
   //
   // --------------------------------------------------------------------------
 
-  toggleSelected(coerce?: boolean): Promise<void> {
-    if (this.disabled) {
+  toggleSelected(): Promise<void> {
+    const isSingleSelect = getElementProp(this.el, "selection-mode", "multiple") === "single";
+
+    if (this.disabled || (isSingleSelect && this.selected)) {
       return;
     }
-    this.selected = typeof coerce === "boolean" ? coerce : !this.selected;
+
+    this.selected = !this.selected;
   }
 
   itemClickHandler = (event: MouseEvent): void => {

src/components/combobox/assets/combobox/t9n/messages.json

@@ -1,3 +1,4 @@
 {
+  "clear": "Clear value",
   "removeTag": "Remove tag"
 }

src/components/combobox/assets/combobox/t9n/messages_en.json

@@ -1,3 +1,4 @@
 {
+  "clear": "Clear value",
   "removeTag": "Remove tag"
 }

src/components/combobox/combobox.e2e.ts

@@ -13,6 +13,7 @@ import {
 
 import { html } from "../../../support/formatting";
 import { CSS } from "./resources";
+import { CSS as XButtonCSS } from "../functional/XButton";
 
 describe("calcite-combobox", () => {
   describe("renders", () => {
@@ -302,33 +303,86 @@ describe("calcite-combobox", () => {
   });
 
   describe("item selection", () => {
-    it("should add/remove item to the selected items when an item is clicked", async () => {
-      const page = await newE2EPage();
-      await page.setContent(
-        html`
-          <calcite-combobox>
-            <calcite-combobox-item value="one" text-label="one"></calcite-combobox-item>
-            <calcite-combobox-item value="two" text-label="two"></calcite-combobox-item>
-          </calcite-combobox>
-        `
-      );
-      const cbox = await page.find("calcite-combobox");
-      const openEvent = page.waitForEvent("calciteComboboxOpen");
-      await cbox.click();
-      await openEvent;
+    describe("toggling items", () => {
+      it("single-selection mode does not allow toggling selection once the selected item is clicked", async () => {
+        const page = await newE2EPage();
+        await page.setContent(
+          html`
+            <calcite-combobox>
+              <calcite-combobox-item value="one" text-label="one"></calcite-combobox-item>
+              <calcite-combobox-item value="two" text-label="two"></calcite-combobox-item>
+            </calcite-combobox>
+          `
+        );
+        const cbox = await page.find("calcite-combobox");
+        const openEvent = page.waitForEvent("calciteComboboxOpen");
+        await cbox.click();
+        await openEvent;
+
+        const item1 = await cbox.find("calcite-combobox-item[value=one]");
 
-      let item1 = await cbox.find("calcite-combobox-item[value=one]");
-      await item1.click();
+        await item1.click();
+        expect(await page.find("calcite-combobox >>> calcite-chip")).toBeDefined();
 
-      let chip = await page.find("calcite-combobox >>> calcite-chip");
-      expect(chip).toBeDefined();
+        await item1.click();
+        expect(await page.find("calcite-combobox >>> calcite-chip")).toBeDefined();
+      });
 
-      item1 = await cbox.find("calcite-combobox-item[value=one]");
-      await item1.click();
-      await page.waitForChanges();
+      it("multiple-selection mode allows toggling selection once the selected item is clicked", async () => {
+        const page = await newE2EPage();
+        await page.setContent(
+          html`
+            <calcite-combobox selection-mode="multiple">
+              <calcite-combobox-item value="one" text-label="one"></calcite-combobox-item>
+              <calcite-combobox-item value="two" text-label="two"></calcite-combobox-item>
+            </calcite-combobox>
+          `
+        );
+        const cbox = await page.find("calcite-combobox");
+        const openEvent = page.waitForEvent("calciteComboboxOpen");
+        await cbox.click();
+        await openEvent;
+
+        const item1 = await cbox.find("calcite-combobox-item[value=one]");
 
-      chip = await page.find("calcite-combobox >>> calcite-chip");
-      expect(chip).toBeNull();
+        await item1.click();
+        expect(await page.find("calcite-combobox >>> calcite-chip")).toBeDefined();
+
+        await item1.click();
+        expect(await page.find("calcite-combobox >>> calcite-chip")).toBeNull();
+
+        await item1.click();
+        expect(await page.find("calcite-combobox >>> calcite-chip")).toBeDefined();
+      });
+
+      it("ancestors-selection mode allows toggling selection once the selected item is clicked", async () => {
+        const page = await newE2EPage();
+        await page.setContent(
+          html`
+            <calcite-combobox selection-mode="ancestors">
+              <calcite-combobox-item value="one" text-label="parent">
+                <calcite-combobox-item value="two" text-label="child1"></calcite-combobox-item>
+                <calcite-combobox-item value="three" text-label="child2"></calcite-combobox-item>
+              </calcite-combobox-item>
+            </calcite-combobox>
+          `
+        );
+        const cbox = await page.find("calcite-combobox");
+        const openEvent = page.waitForEvent("calciteComboboxOpen");
+        await cbox.click();
+        await openEvent;
+
+        const item1 = await cbox.find("calcite-combobox-item[value=one]");
+
+        await item1.click();
+        expect(await page.find("calcite-combobox >>> calcite-chip")).toBeDefined();
+
+        await item1.click();
+        expect(await page.find("calcite-combobox >>> calcite-chip")).toBeNull();
+
+        await item1.click();
+        expect(await page.find("calcite-combobox >>> calcite-chip")).toBeDefined();
+      });
     });
 
     it("should select parent in ancestor selection mode", async () => {
@@ -539,6 +593,47 @@ describe("calcite-combobox", () => {
     });
   });
 
+  describe("clearable", () => {
+    async function assertClearable(html: string): Promise<void> {
+      const page = await newE2EPage();
+      await page.setContent(html);
+      const combobox = await page.find("calcite-combobox");
+      const xButton = await page.find(`calcite-combobox >>> .${XButtonCSS.button}`);
+
+      await xButton.click();
+
+      expect(await combobox.getProperty("value")).toBe("");
+    }
+
+    it("clears the value in single-selection mode", async () =>
+      assertClearable(html`
+        <calcite-combobox clearable selection-mode="single">
+          <calcite-combobox-item selected id="one" value="one" text-label="one"></calcite-combobox-item>
+          <calcite-combobox-item id="two" value="two" text-label="two"></calcite-combobox-item>
+          <calcite-combobox-item id="three" value="three" text-label="three"></calcite-combobox-item>
+        </calcite-combobox>
+      `));
+
+    it("clears the value in multiple-selection mode", async () =>
+      assertClearable(html`
+        <calcite-combobox clearable selection-mode="multiple">
+          <calcite-combobox-item selected id="one" value="one" text-label="one"></calcite-combobox-item>
+          <calcite-combobox-item selected id="two" value="two" text-label="two"></calcite-combobox-item>
+          <calcite-combobox-item selected id="three" value="three" text-label="three"></calcite-combobox-item>
+        </calcite-combobox>
+      `));
+
+    it("clears the value in ancestors-selection mode", async () =>
+      assertClearable(html`
+        <calcite-combobox clearable selection-mode="ancestors">
+          <calcite-combobox-item value="parent" text-label="parent">
+            <calcite-combobox-item value="child1" text-label="child1"></calcite-combobox-item>
+            <calcite-combobox-item selected value="child2" text-label="child2"></calcite-combobox-item>
+          </calcite-combobox-item>
+        </calcite-combobox>
+      `));
+  });
+
   describe("keyboard navigation", () => {
     let page: E2EPage;
     const scrollablePageSizeInPx = 2400;

src/components/combobox/combobox.scss

@@ -11,6 +11,7 @@
 }
 
 @include disabled();
+@include xButton();
 
 :host([scale="s"]) {
   @apply text-n2;

src/components/combobox/combobox.tsx

@@ -64,6 +64,7 @@ import { ComboboxMessages } from "./assets/combobox/t9n";
 import { ComboboxChildElement } from "./interfaces";
 import { ComboboxChildSelector, ComboboxItem, ComboboxItemGroup } from "./resources";
 import { getItemAncestors, getItemChildren, hasActiveChildren } from "./utils";
+import { XButton, CSS as XButtonCSS } from "../functional/XButton";
 
 interface ItemData {
   label: string;
@@ -111,6 +112,11 @@ export class Combobox
   //
   //--------------------------------------------------------------------------
 
+  /**
+   * When `true`, a clear button is displayed when the component has a value.
+   */
+  @Prop({ reflect: true }) clearable = false;
+
   /**When `true`, displays and positions the component. */
   @Prop({ reflect: true, mutable: true }) open = false;
 
@@ -506,6 +512,19 @@ export class Combobox
   //
   // --------------------------------------------------------------------------
 
+  private clearValue(): void {
+    this.ignoreSelectedEventsFlag = true;
+    this.items.forEach((el) => (el.selected = false));
+    this.ignoreSelectedEventsFlag = false;
+    this.selectedItems = [];
+    this.emitComboboxChange();
+    this.open = false;
+    this.updateActiveItemIndex(-1);
+    this.resetText();
+    this.filterItems("");
+    this.setFocus();
+  }
+
   setFilteredPlacements = (): void => {
     const { el, flipPlacements } = this;
 
@@ -688,11 +707,20 @@ export class Combobox
   };
 
   clickHandler = (event: MouseEvent): void => {
-    if (event.composedPath().some((node: HTMLElement) => node.tagName === "CALCITE-CHIP")) {
+    const composedPath = event.composedPath();
+
+    if (composedPath.some((node: HTMLElement) => node.tagName === "CALCITE-CHIP")) {
       this.open = false;
-      event.stopPropagation();
+      event.preventDefault();
       return;
     }
+
+    if (composedPath.some((node: HTMLElement) => node.classList?.contains(XButtonCSS.button))) {
+      this.clearValue();
+      event.preventDefault();
+      return;
+    }
+
     this.open = !this.open;
     this.updateActiveItemIndex(0);
     this.setFocus();
@@ -1242,6 +1270,7 @@ export class Combobox
   render(): VNode {
     const { guid, label, open } = this;
     const single = this.selectionMode === "single";
+    const isClearable = this.clearable && this.value.length > 0;
 
     return (
       <Host onClick={this.comboboxFocusHandler}>
@@ -1276,6 +1305,14 @@ export class Combobox
             </label>
             {this.renderInput()}
           </div>
+          {isClearable ? (
+            <XButton
+              disabled={this.disabled}
+              key="close-button"
+              label={this.messages.clear}
+              scale={this.scale}
+            />
+          ) : null}
           {this.renderIconEnd()}
         </div>
         <ul

src/components/functional/XButton.tsx

@@ -0,0 +1,39 @@
+import { FunctionalComponent, h } from "@stencil/core";
+import { JSXAttributes, JSXBase } from "@stencil/core/internal";
+import { Scale } from "../interfaces";
+
+export interface XButtonOptions extends JSXAttributes {
+  disabled: boolean;
+  label: string;
+  scale: Scale;
+  onClick?: JSXBase.DOMAttributes<HTMLElement>["onClick"];
+}
+
+export const CSS = {
+  button: "x-button"
+};
+
+export function XButton({
+  disabled,
+  key,
+  label,
+  onClick,
+  ref,
+  scale
+}: XButtonOptions): FunctionalComponent {
+  return (
+    <button
+      aria-label={label}
+      class={CSS.button}
+      disabled={disabled}
+      key={key}
+      onClick={onClick}
+      tabIndex={-1}
+      type="button"
+      // eslint-disable-next-line react/jsx-sort-props
+      ref={ref}
+    >
+      <calcite-icon icon="x" scale={scale === "l" ? "m" : "s"} />
+    </button>
+  );
+}