feat(combobox): add selectAll toggle property (#11721)

**Related Issue:** #2311

## Summary
Provides a `Select All` checkbox in the `calcite-combobox` by default
for `selection-mode="multiple"` as a convenient shortcut for users to
quickly select or deselect all items in the list. The `indeterminate`
state for this checkbox is a visual and programmatic state that
indicates a checkbox is neither fully checked nor unchecked. It
represents a "partial selection" in scenario where a checkbox is
associated with a group of child checkboxes, and some (but not all) of
the child checkboxes are selected.

---------

Co-authored-by: Matt Driscoll <[email protected]>

Author: Elijbet

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

@@ -3,10 +3,13 @@
  *
  * These properties can be overridden using the component's tag as selector.
  *
+ * @prop --calcite-combobox-item-border-color: Specifies the component's border color.
  * @prop --calcite-combobox-text-color: Specifies the component's text and `icon` color.
  * @prop --calcite-combobox-text-color-hover: Specifies the component's text and `icon` color when hovered.
  * @prop --calcite-combobox-item-background-color-active: Specifies the component's background color when active.
  * @prop --calcite-combobox-item-background-color-hover: Specifies the component's background color when hovered.
+ * @prop --calcite-combobox-item-shadow: Specifies the component's shadow.
+
  * @prop --calcite-combobox-selected-icon-color: Specifies the component's selected indicator icon color.
  * @prop --calcite-combobox-description-text-color: Specifies the component's `description` and `shortHeading` text color.
  * @prop --calcite-combobox-description-text-color-press: Specifies the component's `description` and `shortHeading` text color when hovered.
@@ -118,7 +121,8 @@ ul:focus {
   color: var(--calcite-color-border-input);
 }
 
-:host([selected]) .icon {
+:host([selected]) .icon,
+:host([indeterminate]) .icon {
   color: var(--calcite-combobox-selected-icon-color, var(--calcite-color-brand));
 }
 

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

@@ -14,7 +14,7 @@ import { getIconScale, warnIfMissingRequiredProp } from "../../utils/component";
 import { IconNameOrString } from "../icon/interfaces";
 import { slotChangeHasContent } from "../../utils/dom";
 import { highlightText } from "../../utils/text";
-import { CSS, SLOTS } from "./resources";
+import { CSS, ICONS, SLOTS } from "./resources";
 import { styles } from "./combobox-item.scss";
 
 declare global {
@@ -158,6 +158,13 @@ export class ComboboxItem extends LitElement implements InteractiveComponent {
    *  */
   @property({ reflect: true }) itemHidden = false;
 
+  /**
+   * When `selectionMode` is `"multiple"` or `"ancestors"` and one or more, but not all `calcite-combobox-item`s are selected, displays an indeterminate "select all" checkbox.
+   *
+   * @private
+   */
+  @property({ reflect: true }) indeterminate = false;
+
   //#endregion
 
   //#region Events
@@ -279,14 +286,16 @@ export class ComboboxItem extends LitElement implements InteractiveComponent {
       shortHeading,
     } = this;
     const isSingleSelect = isSingleLike(this.selectionMode);
-    const icon = disabled || isSingleSelect ? undefined : "check-square-f";
+    const icon = disabled || isSingleSelect ? undefined : ICONS.checked;
     const selectionIcon = isSingleSelect
       ? this.selected
-        ? "circle-inset-large"
-        : "circle"
-      : this.selected
-        ? "check-square-f"
-        : "square";
+        ? ICONS.selectedSingle
+        : ICONS.circle
+      : this.indeterminate
+        ? ICONS.indeterminate
+        : this.selected
+          ? ICONS.checked
+          : ICONS.unchecked;
     const headingText = heading || textLabel;
     const itemLabel = label || value;
 

packages/calcite-components/src/components/combobox-item/resources.ts

@@ -15,6 +15,14 @@ export const CSS = {
   heading: "heading",
 };
 
+export const ICONS = {
+  checked: "check-square-f",
+  circle: "circle",
+  indeterminate: "minus-square-f",
+  selectedSingle: "circle-inset-large",
+  unchecked: "square",
+};
+
 export const SLOTS = {
   contentEnd: "content-end",
   contentStart: "content-start",

packages/calcite-components/src/components/combobox/assets/t9n/messages.en.json

@@ -1,6 +1,7 @@
 {
   "all": "All",
   "allSelected": "All selected",
+  "selectAll": "Select All",
   "clear": "Clear value",
   "removeTag": "Remove tag",
   "selected": "selected"

packages/calcite-components/src/components/combobox/assets/t9n/messages.json

@@ -1,6 +1,7 @@
 {
   "all": "All",
   "allSelected": "All selected",
+  "selectAll": "Select All",
   "clear": "Clear value",
   "removeTag": "Remove tag",
   "selected": "selected"

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

@@ -752,7 +752,13 @@ describe("calcite-combobox", () => {
       </calcite-combobox>`,
     );
 
-    const item = await page.find("calcite-combobox-item");
+    await page.waitForChanges();
+
+    const combobox = await page.find("calcite-combobox");
+    await combobox.callMethod("componentOnReady");
+    expect(combobox).not.toBeNull();
+
+    const item = await page.find("calcite-combobox-item#item-0");
     let a11yItem = await page.find(`calcite-combobox >>> ul.${CSS.screenReadersOnly} li`);
 
     expect(a11yItem).not.toBeNull();
@@ -794,7 +800,7 @@ describe("calcite-combobox", () => {
     item.setProperty("disabled", true);
     await page.waitForChanges();
     await page.waitForTimeout(DEBOUNCE.nextTick);
-    a11yItem = await page.find(`calcite-combobox >>> ul.${CSS.screenReadersOnly} li`);
+    a11yItem = await page.find(`calcite-combobox >>> ul.${CSS.screenReadersOnly} li:nth-of-type(2)`);
 
     expect(a11yItem).toBeNull();
   });
@@ -2975,6 +2981,227 @@ describe("calcite-combobox", () => {
     expect((await combobox.getProperty("selectedItems")).length).toBe(1);
   });
 
+  describe("selectAllEnabled", async () => {
+    let page: E2EPage;
+
+    beforeEach(async () => {
+      page = await newE2EPage();
+      await page.setContent(
+        html`<calcite-combobox selection-mode="multiple" select-all-enabled>
+          <calcite-combobox-item value="Trees" text-label="Trees">
+            <calcite-combobox-item value="Pine" text-label="Pine">
+              <calcite-combobox-item value="Pine Nested" text-label="Pine Nested"></calcite-combobox-item>
+            </calcite-combobox-item>
+            <calcite-combobox-item value="Sequoia" text-label="Sequoia"></calcite-combobox-item>
+          </calcite-combobox-item>
+          <calcite-combobox-item value="Flowers" text-label="Flowers">
+            <calcite-combobox-item value="Daffodil" text-label="Daffodil"></calcite-combobox-item>
+            <calcite-combobox-item value="Nasturtium" text-label="Nasturtium"></calcite-combobox-item>
+          </calcite-combobox-item>
+        </calcite-combobox>`,
+      );
+      await page.waitForChanges();
+    });
+
+    async function testToggleAllItems(
+      page: E2EPage,
+      toggleAction: ([selectAll, combobox]: [E2EElement, E2EElement]) => Promise<void>,
+    ): Promise<void> {
+      const combobox = await page.find("calcite-combobox");
+      await combobox.click();
+      expect(await combobox.getProperty("open")).toBe(true);
+
+      const selectAll = await page.find(`calcite-combobox >>> .${CSS.selectAll}`);
+      await toggleAction([selectAll, combobox]);
+
+      let allComboboxItems = await findAll(page, "calcite-combobox-item");
+      for (const item of allComboboxItems) {
+        expect(await item.getProperty("selected")).toBe(true);
+      }
+      expect(await page.find(`calcite-combobox >>> calcite-chip.${CSS.allSelected}`)).toBeDefined();
+
+      await toggleAction([selectAll, combobox]);
+
+      allComboboxItems = await findAll(page, "calcite-combobox-item");
+      for (const item of allComboboxItems) {
+        expect(await item.getProperty("selected")).toBe(false);
+      }
+
+      const chip = await page.find(`calcite-combobox >>> calcite-chip.${CSS.allSelected}`);
+      expect(chip.classList.contains(`${CSS.chipInvisible}`)).toBe(true);
+    }
+
+    it("should toggle all items on and off with a click", async () => {
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      await testToggleAllItems(page, async ([selectAll, _combobox]) => {
+        await selectAll.click();
+      });
+    });
+
+    it("should toggle all items on and off with KeyDown press `enter`", async () => {
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      await testToggleAllItems(page, async ([_selectAll, combobox]) => {
+        await combobox.press("Enter");
+      });
+    });
+
+    it("indeterminate state", async () => {
+      const combobox = await page.find("calcite-combobox");
+      await combobox.click();
+      expect(await combobox.getProperty("open")).toBe(true);
+
+      await (await combobox.find("calcite-combobox-item[value=Sequoia]")).click();
+
+      const selectAll = await page.find(`calcite-combobox >>> calcite-combobox-item.${CSS.selectAll}`);
+      expect(await selectAll.getProperty("indeterminate")).toBe(true);
+      expect(await page.find(`calcite-combobox >>> calcite-chip[value=Sequoia]`)).toBeDefined();
+
+      await (await combobox.find("calcite-combobox-item[value=Flowers]")).click();
+
+      expect(await selectAll.getProperty("indeterminate")).toBe(true);
+      expect(await page.find(`calcite-combobox >>> calcite-chip[value=Flowers]`)).toBeDefined();
+
+      const chip = await page.find(`calcite-combobox >>> calcite-chip.${CSS.allSelected}`);
+      expect(chip.classList.contains(`${CSS.chipInvisible}`)).toBe(true);
+
+      await selectAll.click();
+      expect(await selectAll.getProperty("indeterminate")).toBe(false);
+      expect(await selectAll.getProperty("selected")).toBe(true);
+
+      expect(await page.find(`calcite-combobox >>> calcite-chip.${CSS.allSelected}`)).toBeDefined();
+      expect(await page.find(`calcite-combobox >>> calcite-chip[value=Sequoia]`)).toBeNull();
+      expect(await page.find(`calcite-combobox >>> calcite-chip[value=Flowers]`)).toBeNull();
+
+      const allComboboxItems = await findAll(page, "calcite-combobox-item");
+      for (const item of allComboboxItems) {
+        expect(await item.getProperty("selected")).toBe(true);
+      }
+    });
+
+    async function testToggleListItems(
+      page: E2EPage,
+      toggleAction: ([listItem, combobox]: [E2EElement, E2EElement]) => Promise<void>,
+    ): Promise<void> {
+      const messages = await import("./assets/t9n/messages.json");
+      const combobox = await page.find("calcite-combobox");
+      await combobox.click();
+      expect(await combobox.getProperty("open")).toBe(true);
+
+      const allComboboxItems = await findAll(page, "calcite-combobox-item");
+      for (const item of allComboboxItems) {
+        item.setProperty("selected", true);
+      }
+      await page.waitForChanges();
+      expect(await page.find(`calcite-combobox >>> calcite-chip[value="${messages.allSelected}"]`)).toBeDefined();
+
+      const listItem = await combobox.find("calcite-combobox-item[value=Sequoia]");
+      await toggleAction([listItem, combobox]);
+
+      const selectAll = await page.find(`calcite-combobox >>> calcite-combobox-item.${CSS.selectAll}`);
+      expect(await selectAll.getProperty("indeterminate")).toBe(true);
+      expect(await page.find(`calcite-combobox >>> calcite-chip[value=Sequoia]`)).toBeDefined();
+
+      await toggleAction([listItem, combobox]);
+
+      expect(await selectAll.getProperty("indeterminate")).toBe(false);
+      expect(await selectAll.getProperty("selected")).toBe(true);
+      expect(await page.find(`calcite-combobox >>> calcite-chip[value=Sequoia]`)).toBeNull();
+
+      await toggleAction([listItem, combobox]);
+
+      expect(await selectAll.getProperty("indeterminate")).toBe(true);
+      expect(await page.find(`calcite-combobox >>> calcite-chip[value=Sequoia]`)).toBeDefined();
+    }
+
+    it("should toggle indeterminate state to `All Selected` when list items are toggled with a click", async () => {
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      await testToggleListItems(page, async ([listItem, _combobox]) => {
+        await listItem.click();
+      });
+    });
+
+    it("should toggle indeterminate state to `All Selected` when list items are toggled with a keydown `Enter`", async () => {
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      await testToggleAllItems(page, async ([_listItem, combobox]) => {
+        await combobox.press("Enter");
+      });
+    });
+
+    it("should have indeterminate state when some items are initialized selected", async () => {
+      page = await newE2EPage();
+      await page.setContent(
+        html`<calcite-combobox selection-mode="multiple" select-all-enabled>
+          <calcite-combobox-item value="Trees" text-label="Trees" selected>
+            <calcite-combobox-item value="Pine" text-label="Pine" />
+          </calcite-combobox-item>
+        </calcite-combobox>`,
+      );
+      await page.waitForChanges();
+      const selectAll = await page.find(`calcite-combobox >>> calcite-combobox-item.${CSS.selectAll}`);
+      expect(await selectAll.getProperty("indeterminate")).toBe(true);
+    });
+
+    it("should have selectAll state true when all items are initialized selected", async () => {
+      page = await newE2EPage();
+      await page.setContent(
+        html`<calcite-combobox selection-mode="multiple" select-all-enabled>
+          <calcite-combobox-item value="Trees" text-label="Trees" selected>
+            <calcite-combobox-item value="Pine" text-label="Pine" selected />
+          </calcite-combobox-item>
+        </calcite-combobox>`,
+      );
+      await page.waitForChanges();
+      const selectAll = await page.find(`calcite-combobox >>> calcite-combobox-item.${CSS.selectAll}`);
+      expect(await selectAll.getProperty("selected")).toBe(true);
+    });
+
+    it("should bring back all the chips except `All Selected` when one item is deselected", async () => {
+      page = await newE2EPage();
+      await page.setContent(
+        html`<calcite-combobox selection-mode="multiple" select-all-enabled>
+          <calcite-combobox-item value="Trees" text-label="Trees" selected>
+            <calcite-combobox-item value="Pine" text-label="Maple" selected />
+            <calcite-combobox-item value="Pine" text-label="Pine" selected />
+          </calcite-combobox-item>
+        </calcite-combobox>`,
+      );
+      await page.waitForChanges();
+      const messages = await import("./assets/t9n/messages.json");
+
+      const combobox = await page.find("calcite-combobox");
+      await combobox.click();
+      await page.waitForChanges();
+
+      const listItem = await combobox.find("calcite-combobox-item[value=Pine]");
+      await listItem.click();
+
+      expect(await page.find(`calcite-combobox >>> calcite-chip[value="Trees"]`)).toBeDefined();
+      expect(await page.find(`calcite-combobox >>> calcite-chip[value="Maple"]`)).toBeDefined();
+      expect(await page.find(`calcite-combobox >>> calcite-chip[value="${messages.allSelected}"]`)).toBeNull();
+    });
+
+    it("should update aria-selected on items when toggling 'Select All'", async () => {
+      const combobox = await page.find("calcite-combobox");
+      await combobox.click();
+
+      const selectAll = await page.find(`calcite-combobox >>> calcite-combobox-item.${CSS.selectAll}`);
+      await selectAll.click();
+      await page.waitForChanges();
+
+      let a11yItem = await page.find(`calcite-combobox >>> ul.${CSS.screenReadersOnly} li:nth-of-type(2)`);
+      expect(await a11yItem.getProperty("ariaSelected")).toBe("true");
+
+      a11yItem = await page.find(`calcite-combobox >>> ul.${CSS.screenReadersOnly} li:nth-of-type(3)`);
+      expect(await a11yItem.getProperty("ariaSelected")).toBe("true");
+
+      await selectAll.click();
+      await page.waitForChanges();
+
+      a11yItem = await page.find(`calcite-combobox >>> ul.${CSS.screenReadersOnly} li:nth-of-type(2)`);
+      expect(await a11yItem.getProperty("ariaSelected")).toBe("false");
+    });
+  });
+
   describe("theme", () => {
     describe("default", () => {
       const comboboxHTML = html`<calcite-combobox label="test" max-items="6" open>

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

@@ -110,8 +110,8 @@
   gap: var(--calcite-internal-combobox-spacing-unit-s);
   margin-inline-end: var(--calcite-internal-combobox-spacing-unit-s);
 
-  &.selection-display-fit,
-  &.selection-display-single {
+  &.selection-display--fit,
+  &.selection-display--single {
     @apply flex-nowrap overflow-hidden;
   }
 }
@@ -236,6 +236,16 @@ calcite-chip {
   @apply block;
 }
 
+.select-all {
+  background-color: var(--calcite-combobox-item-background-color-active, var(--calcite-color-foreground-1));
+  border-block-end-color: var(--calcite-combobox-item-border-color, var(--calcite-color-border-3));
+  border-block-end-style: solid;
+  border-block-end-width: var(--calcite-border-width-sm);
+  inset-block-start: 0;
+  position: sticky;
+  z-index: var(--calcite-z-index-sticky);
+}
+
 @include disabled();
 @include x-button(
   $background-color: "var(--calcite-close-background-color, var(--calcite-color-foreground-2))",